SoundStash Documentation

Welcome to the SoundStash documentation! This guide will help you get started with your personal audio library manager.

🚀 Quick Start

SoundStash is a Docker-based application that runs on port 5100. Make sure Docker is installed on your system before proceeding.

iOS Companion App

SoundStash also has an iOS companion app for offline listening. Download tracks from your SoundStash server to your iPhone for playback anywhere, even without a network connection. Available on the App Store.

Installation

Prerequisites

Docker and Docker Compose
At least 10GB of free disk space for your music library
A modern web browser (Chrome, Firefox, Safari, Edge)

Step 1: Clone the Repository

git clone https://github.com/your-repo/soundstash.git
cd soundstash
                        

Step 2: Configure Environment

Copy the example environment file and configure your settings:

cp .env.example .env

Step 3: Set Music Storage Path

Edit the .env file to set your preferred music storage location:

MUSIC_PATH=/path/to/your/music
SECRET_KEY=your-secret-key-here
                        

Step 4: Start the Application

docker-compose up -d

Step 5: Access SoundStash

Open your web browser and navigate to http://localhost:5100

⚠️ Important

Make sure the MUSIC_PATH directory exists and is writable by the Docker container. The application will create the necessary subdirectories automatically.

Configuration

Environment Variables

MUSIC_PATH: Host path for audio storage (required)
SECRET_KEY: Flask secret key for session security (required)
DATABASE_PATH: SQLite database path (default: /data/soundstash.db)
CONCURRENT_DOWNLOADS: Maximum concurrent downloads (default: 3)
DEFAULT_FORMAT: Default audio format (default: mp3)
DEFAULT_QUALITY: Default audio quality (default: best)

Docker Compose Configuration

The default docker-compose.yml configuration:

version: '3.8'

services:
  soundstash:
    build: .
    container_name: soundstash
    restart: unless-stopped
    ports:
      - "5100:5100"
    volumes:
      - ${MUSIC_PATH:-./data}:/data
    environment:
      - SECRET_KEY=${SECRET_KEY:-change-me}
      - DATABASE_PATH=/data/soundstash.db
                        

Features

🎵 YouTube Downloads

Download high-quality audio from YouTube with automatic metadata extraction.

📁 Library Management

Organize your music with smart tagging, search, and filtering capabilities.

🎧 Audio Player

Built-in web player with playlist support and keyboard shortcuts.

📱 Plex Integration

Connect to your Plex server and import your existing music library.

🔄 Format Conversion

Convert between MP3, FLAC, WAV, AAC, OGG, and M4A formats.

📋 Playlists

Create custom playlists and export them as M3U files.

iOS Offline Playback

Download tracks to your iPhone for offline listening. Resume where you left off, adjust playback speed, and enjoy audio visualisations.

YouTube Downloads

SoundStash uses yt-dlp to download audio from YouTube:

Support for all YouTube video formats
Automatic metadata extraction
Thumbnail download as cover art
Real-time download progress
Download queue management

Plex Integration

Connect to your Plex Media Server:

Automatic library scanning
Metadata synchronization
Direct streaming from Plex
Multi-server support

Library Management

Powerful tools to organize your music:

Smart folder organization
Advanced search and filtering
Custom tags and metadata
Duplicate detection
Batch operations

Playlists

Create and manage playlists:

Custom playlist creation
Drag-and-drop reordering
M3U export functionality
Smart playlists with rules

API Reference

Authentication

Most API endpoints require session authentication. Log in through the web interface to establish a session.

Download Endpoints

GET /api/downloads - List all downloads
POST /api/downloads - Start new download
GET /api/downloads/{id} - Get download status
DELETE /api/downloads/{id} - Cancel download

Library Endpoints

GET /api/library/tracks - List tracks
GET /api/library/tracks/{id} - Get track details
PUT /api/library/tracks/{id} - Update metadata
GET /api/library/search - Search library

Player Endpoints

GET /api/player/stream/{id} - Stream audio
GET /api/player/cover/{id} - Get cover art

Troubleshooting

Common Issues

Container Won't Start

Check if Docker is running: docker --version
Verify port 5100 is not in use
Check logs: docker-compose logs soundstash

Downloads Fail

Verify YouTube URL is valid
Check internet connectivity
Ensure sufficient disk space
Check yt-dlp updates: docker-compose exec soundstash pip install --upgrade yt-dlp

Plex Connection Issues

Verify Plex server is accessible
Check authentication token
Ensure network connectivity between containers

Logs and Debugging

# View application logs docker-compose logs -f soundstash # Check container status docker-compose ps # Access container shell docker-compose exec soundstash bash

Frequently Asked Questions

General

Q: Is SoundStash free?
A: Yes, the self-hosted web application is completely free and open source.

Q: Can I run SoundStash without Docker?
A: Docker is the recommended installation method. Manual installation is possible but not officially supported.

Legal and Copyright

Q: Is downloading YouTube audio legal?
A: Downloading copyrighted content without permission may violate copyright laws. Users are responsible for ensuring compliance with applicable laws and terms of service.

Q: Does SoundStash store my files?
A: No, your audio files are stored locally on your system or designated storage. We only store minimal account and usage data.

iOS App

Q: Is there a mobile app?
A: Yes, SoundStash has an iOS companion app available on the App Store. It connects to your self-hosted SoundStash server and lets you download tracks for offline listening.

Q: Do I need to pay for the iOS app?
A: The iOS app is free to download with a limited number of offline downloads. SoundStash Unlimited (a one-time purchase of £0.99) removes the download limit permanently.

Technical

Q: What audio formats are supported?
A: MP3, FLAC, WAV, AAC, OGG, and M4A formats are supported for both input and output.

Q: Can I access SoundStash from outside my network?
A: Yes, but you'll need to configure port forwarding and SSL certificates. We recommend using a reverse proxy like nginx.

Q: How do I back up my library?
A: Back up your MUSIC_PATH directory and the soundstash.db file regularly.