musickit 0.4.0

Self-hosted music toolkit: convert / audit / retag rips into a clean tagged library, browse + play via a Textual TUI (local / internet radio / Subsonic-client / AirPlay), and stream over Tailscale via a Subsonic-compatible HTTP server.

musickit

Python 3.13 CLI for converting audio rips into a clean tagged library, browsing and playing it via a Textual TUI, and streaming it over Tailscale via a Subsonic-compatible HTTP server.

Quickstart

uv sync
uv run musickit convert ./input ./output       # convert
uv run musickit library audit ./output         # audit
uv run musickit tui ./output                   # TUI
uv run musickit serve ./output                 # Subsonic server

Documentation

Full docs are at docs/ — built with MkDocs Material. Run them locally:

make docs-serve     # http://127.0.0.1:8000

Or jump straight to:

• Architecture — how all the pieces fit together (process model, data flow, audio subprocess, SQLite index, FFT visualizer)
• Tutorial: 0 to iPhone streaming — end-to-end walkthrough including Tailscale + Amperfy
• Quickstart — install + first convert
• musickit convert — codec / bitrate / enrichment matrix
• musickit library — audit rules + auto-fix + SQLite index
• musickit tui — TUI: local + radio + Subsonic-client + AirPlay
• musickit serve — Subsonic API + Tailscale + clients
• Edge cases — every weirdness encountered on real rips
• Roadmap — what's next
• Development — directory layout + test patterns + commit style

Status

v0.4.0 · ruff + mypy + pyright clean, full pytest suite green. Five top-level commands — convert, library, inspect, tui, serve — with library carrying the read / mutate / manage subcommands (tree, audit, fix, cover, cover-pick, retag, index). The TUI ships local-library playback, internet radio, Subsonic-client mode, AirPlay output (incl. pause + volume routing), mDNS discovery, ReplayGain normalisation, an incremental /-filter, in-place tag editing (e for track / album-wide), a 48-band FFT visualiser, and click-to-seek on the progress bar. Audio decoder + sounddevice callback run in a separate process so UI work in the main interpreter can't stall playback. The server is OpenSubsonic-compatible (multipleGenres, transcodeOffset, songLyrics extensions) and tested against Symfonium / Amperfy / play:Sub / Feishin clients on iOS / Android / desktop. A persistent SQLite library index at <root>/.musickit/index.db makes cold starts skip the filesystem walk + tag read; the filesystem watcher does per-album incremental rescans.

License

See LICENSE in the repo root.