A personal, single-user, self-hosted music system:
- a server (FastAPI + PostgreSQL, Docker / Portainer) that holds your library,
- a terminal client in the spirit of Claude Code: paste a link, drop files, search, play, all from one prompt,
- a Subsonic-compatible API, so native iPhone apps (Amperfy, play:Sub, substreamer) stream your library with real background playback and lock-screen controls.
- Add music by pasting a YouTube / SoundCloud link (tracks, YouTube playlists, SoundCloud sets) or dropping audio files / folders into the terminal.
- iPhone-friendly audio: AAC/MP3/FLAC kept as-is, anything else converted once to AAC;
on-the-fly MP3 transcoding for mobile data (
maxBitRate). - Playlists shared by the terminal and the phone; playlist imports can create a playlist automatically.
- Terminal client: prompt, listening and browse modes; queue, shuffle, repeat (all / one), seeking, volume, Windows media keys; command completion; history and most played; themes, accent colours, key remapping, loudness normalisation, audio device, resume where you left off.
- Robust: duplicate detection, job queue with retries, auto-reconnect, mpv crash recovery, readable errors.
- Backups every 24 h (database dumps + incremental music mirror) with a tested restore.
terminal client ──┐ ┌── api FastAPI: REST /api, Subsonic /rest
(Textual + mpv) │ HTTPS (Cloudflare │
├── Tunnel) ─────────────► ├── worker yt-dlp imports (job queue in Postgres)
iPhone app ───────┘ ├── backup pg_dump + music mirror, every 24 h
(Amperfy, Subsonic) └── db PostgreSQL 16
One Docker image (server/) runs as api, worker and backup. Audio files live in a
volume as <track-id>.<ext>; everything else (titles, playlists, plays, jobs) is in
PostgreSQL. Imports are jobs in a Postgres table, claimed with SELECT … FOR UPDATE SKIP LOCKED; no Redis/Celery.
- Portainer → Stacks → Add stack → Repository: URL
https://github.com/Aitaneuh/soundable, referencerefs/heads/main(or a release tag such asrefs/tags/v1.0.0), compose pathdocker-compose.yml. - Environment variables (see Configuration): at least
POSTGRES_PASSWORD,ADMIN_PASSWORD,SECRET_KEY,SUBSONIC_PASSWORD, andPROXY_NETWORK(the Docker network cloudflared is attached to). - Deploy the stack. Portainer builds the image from the repo (first build: a few minutes).
- Cloudflare Zero Trust → Networks → Tunnels → your tunnel → Public hostname:
soundable.<your-domain>→ serviceHTTP→soundable-api:8000. - Check
https://soundable.<your-domain>/api/health→{"status":"ok","db":"ok"}. - Install the terminal client (below) and the iPhone app (docs/subsonic.md).
Updating: Stacks → soundable → Pull and redeploy. The app image is always rebuilt from
the repo (pull_policy: build), so that's all it takes. Database migrations run
automatically when the api container starts.
If Cloudflare's Bot Fight Mode / WAF is on, it may challenge the iPhone app's requests (non-browser traffic): add a WAF skip rule for this hostname if Amperfy can't log in.
Needs mpv (winget install shinchiro.mpv on Windows, brew install mpv
on macOS, apt install mpv on Linux) and uv.
uv tool install --managed-python "git+https://github.com/Aitaneuh/soundable@v1.0.0#subdirectory=client"
soundable doctor # checks mpv and the configuration
soundable # first run asks for the server URL and password(From a clone, uv tool install --managed-python --editable ./client keeps it in sync with
your checkout. On Windows prefer a uv-managed Python over the Microsoft Store one, which
silently redirects AppData writes into a sandbox folder.)
soundable logout revokes the token on the server and deletes it locally (it's stored in
the system keyring, or a 0600 file as a fallback).
| You type | What happens |
|---|---|
| a YouTube / SoundCloud link | imports it; for playlists, asks whether to create a playlist |
| file or folder path(s), drag & drop works | uploads them |
| anything else | searches the library (accent-insensitive) |
/ |
command menu with completion (Tab / Enter) |
Numbers refer to the last list shown: search, then /play 3, /queue add 1 4-6,
/playlist add road 2, /edit 3, /delete 3.
Modes
- prompt (default): type commands and searches.
- listening (
Esc): ←/→ previous/next, ↑/↓ volume, space pause,,/.seek,sshuffle,rrepeat. Typing anything returns to the prompt. - browse (
Ctrl+B): Library / Playlists / Queue tabs (Tab), Enter plays,aadds to the queue,padds to a playlist,eedits,ddeletes,/filters; in a playlist Shift+↑/↓ reorders.
Commands (all listed by /help and the / menu): /search, /recent, /history,
/top, /play, /queue [add|rm|clear], /next, /prev, /pause, /stop, /seek,
/vol, /shuffle, /repeat, /playlists, /playlist new|save|play|shuffle|show|add|rm| move|rename|delete, /add, /jobs [retry|cancel], /edit, /delete, /settings,
/login, /logout, /clear, /quit.
Shuffle & repeat: Ctrl+S toggles shuffle without interrupting the current song (off
restores the original order); Ctrl+R cycles repeat off → all → one. Both are remembered.
Settings (F2 or /settings): theme, accent colour, resume last queue on start,
loudness normalisation, audio output device, volume / seek steps, start mode, library order,
and remapping of every shortcut (with conflict checks).
History: a play counts after half a track (or 4 minutes), from the terminal and from
Subsonic apps. /history and /top show it; Amperfy's "recent"/"frequent" lists use it.
Logs: client.log in the client's state folder (soundable doctor prints the path).
See docs/subsonic.md: Amperfy setup step by step, how the library maps to artists/albums, transcoding for mobile data, the implemented endpoints and a curl cheat sheet.
- Tracks: YouTube videos, SoundCloud tracks (incl. private
s-…links andon.soundcloud.comshort links). - Playlists: YouTube playlists and SoundCloud sets (up to 500 tracks). The client shows
the title and size and asks whether to also create a soundable playlist. A video link
that carries a playlist (
watch?v=…&list=…) asks "just this video, or the whole playlist?". Tracks already in the library aren't downloaded again but are added to the playlist, which is filled in the original order once every track is done. YouTube Mix/radio lists (auto-generated, endless) are refused./jobs cancel <n>stops the rest. - Audio: YouTube's AAC stream is preferred (iPhones play it natively); anything iOS can't play (Opus/WebM…) is converted once to AAC 256 kbps.
- Duplicates are refused (same video / SoundCloud track, or identical file content).
- Failures: network problems, HTTP 5xx and rate limiting are retried 3 times with backoff; permanent ones (removed/private/DRM-protected, bot check…) fail with a readable message. Single links are handled before the remaining tracks of a big playlist import.
- Only YouTube and SoundCloud URLs are accepted, and yt-dlp is restricted to those extractors, so the server can't be used as a generic downloader.
YouTube changes often and yt-dlp follows. It's pinned in server/uv.lock; to update:
uv lock --directory server --upgrade-package yt-dlp --upgrade-package yt-dlp-ejs
git commit -am "Update yt-dlp" && git pushthen Pull and redeploy in Portainer. yt-dlp needs Deno for YouTube; its version is pinned
in server/Dockerfile (denoland/deno:bin-…): bump it there if yt-dlp asks for a newer one.
If YouTube starts asking for this, export cookies from a browser logged in to YouTube (a
throwaway account is safer) as a Netscape cookies.txt, put it on the server, uncomment the
cookie mount in docker-compose.yml and set YTDLP_COOKIES_FILE=/run/ytdlp/cookies.txt.
The file is mounted read-only; the worker uses a private copy.
The backup service runs every BACKUP_INTERVAL_HOURS (default 24 h, first run a minute
after start) and writes to BACKUP_DIR:
db/soundable-<date>.sql.gz: full database dump; the newestBACKUP_KEEP(14) are keptmusic/: mirror of the audio files, incremental (only new files are copied)last-backup.json: result of the last run (also in thebackupcontainer logs)
Put BACKUP_DIR on another disk (e.g. /mnt/backup/soundable, writable by uid 1000):
a backup on the same disk as Docker doesn't survive that disk dying. For an off-site copy,
sync that folder anywhere (rclone, Syncthing, a NAS job…).
Manual commands (Portainer → Containers → soundable-backup-1 → Console):
python -m app.backup run # back up now
python -m app.backup list # available dumps- Stop the
apiandworkercontainers (restore refuses to run while they're connected). - In the
backupcontainer:python -m app.backup restore latest(or a file name fromlist). The database is replaced by the dump and music files missing from the music volume are copied back from the mirror. - Start
apiandworkeragain.
On a brand-new server: deploy the stack with BACKUP_DIR pointing at the backup folder,
then do the same. (Both a partial-damage restore and a restore into an empty stack were
tested.)
All settings are environment variables (Portainer stack variables, or .env locally; see
.env.example).
| Variable | Default | |
|---|---|---|
POSTGRES_PASSWORD |
(required) | database password (internal network only) |
ADMIN_PASSWORD |
(required) | password for soundable login |
SECRET_KEY |
(required) | ≥ 32 random chars, signs stream links |
SUBSONIC_USER |
admin |
username in the iPhone app |
SUBSONIC_PASSWORD |
(required) | password in the iPhone app (separate on purpose) |
PROXY_NETWORK |
global |
Docker network shared with cloudflared |
MAX_UPLOAD_MB |
95 |
upload limit (Cloudflare caps requests at 100 MB) |
YTDLP_COOKIES_FILE |
(empty) | cookies for YouTube's bot check, if ever needed |
BACKUP_DIR |
backups volume |
where backups go (prefer another disk) |
BACKUP_INTERVAL_HOURS |
24 |
|
BACKUP_KEEP |
14 |
database dumps kept |
LOG_LEVEL |
INFO |
- Everything goes through HTTPS (Cloudflare Tunnel); the containers publish no ports and PostgreSQL is only on an internal network.
ADMIN_PASSWORDis only kept as an argon2 hash in memory; the client stores a revocable token (hashed in the database), never the password.SUBSONIC_PASSWORDmust be known in plaintext by the server (Subsonic token auth ismd5(password + salt)), which is why it's a separate password: don't reuse one you care about.- Failed logins (both APIs) are rate-limited per IP and logged.
- Uploads are size-limited, checked to be real audio, and stored under generated names.
cp .env.example .env && docker compose up -d --build # local stack on 127.0.0.1:8000
cd server && uv sync --managed-python && uv run pytest # needs Docker + ffmpeg (+ psql for backup tests)
cd client && uv sync --managed-python && uv run pytest
uv run ruff check . && uv run ruff format --check . # in either folderdocker-compose.override.yml is only used locally (publishes the API on 127.0.0.1:8000);
Portainer reads docker-compose.yml only. CI runs ruff and the tests of both packages and
builds the Docker image on every push.