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.
Install
The lowest-friction way is uvx — it downloads, caches, and runs the latest published musickit in one step. No install step required:
uvx musickit --help
For daily / persistent use (PATH-installed, no per-run network check):
uv tool install musickit
musickit --help
You'll also need ffmpeg and ffprobe on $PATH for the convert pipeline:
brew install ffmpeg # macOS
sudo apt install ffmpeg # Debian / Ubuntu
Quickstart
uvx musickit convert ./input ./output # convert
uvx musickit library audit ./output # audit
uvx musickit tui ./output # TUI
uvx musickit serve ./output # Subsonic server
uvx musickit playlist gen ./output --seed <track> --minutes 60 # auto-generate a mix
Screenshots
The TUI — artist browser on the left, drilled into an album, 48-band visualizer at the top:
Fullscreen visualizer (f):
The bundled browser UI tracks the same visual language — bordered panels with floating titles, same palette and KeyBar:
Internet radio mode (Stations panel + ICY metadata in the title):
More screenshots in the TUI guide and serve guide.
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)
- Quickstart — end-to-end walkthrough including iPhone + Tailscale + Amperfy
- 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
- musickit playlist — auto-generated
.m3u8mixes anchored to a seed track - Desktop apps — Tauri + Electron generic Subsonic clients
- Mobile (Subsonic) — play:Sub / Amperfy / Symfonium / DSub / Tempo
- Edge cases — every weirdness encountered on real rips
- Roadmap — what's next
- Development — directory layout + test patterns + commit style
Status
v0.13.0 · browser UI tracks the TUI's visual language (bordered panels, palette, keybinds for repeat / shuffle / volume / seek, slide-in help, command palette via Cmd/Ctrl+P, internet radio via the existing radio.toml) — ruff + mypy + pyright clean, full pytest suite green. Six top-level commands — convert, library, inspect, tui, serve, playlist — with library carrying the read / mutate / manage subcommands (tree, audit, fix, cover, cover-pick, retag, lyrics, index) and playlist carrying gen / list / show. The TUI ships local-library playback, internet radio, Subsonic-client mode (with persistent token-auth credentials), AirPlay output (incl. pause + volume routing), mDNS discovery, ReplayGain normalisation, a diacritic-folded /-filter, in-place tag editing (e for track / album-wide), auto-generated Mixes (g to create, browseable view of saved .m3u8), a 48-band FFT visualiser with f / v toggles, synced lyrics via l (parsed [mm:ss.xx] markers, active line bolded as playback advances), 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), backs heart / star buttons with a persistent <root>/.musickit/stars.toml, returns sub-ms FTS5-ranked /search3 results, promotes LRC lyrics to synced: true, and is 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.
1 maintainer
Release files for musickit 0.23.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| musickit-0.23.15.tar.gz | 925.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| musickit-0.23.15-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / musickit-0.23.15.tar.gz
| Download URL | musickit-0.23.15.tar.gz |
|---|---|
| Size | 925.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ba03e728a3416927f8e97f41a57432e7f187042595b55b7550027a2b175b0dd
|
|
BLAKE2b-256 checksum How to use checksums |
74c506a29dd674dd5f6a71888634cf2fbcfb2b9863e899e2af51aa8c1ceffb1d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / musickit-0.23.15-py3-none-any.whl
| Download URL | musickit-0.23.15-py3-none-any.whl |
|---|---|
| Size | 987.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
120eb8f39af12e5033ec04c0c09921693ead1a109566c9cb7126c53e78fb068c
|
|
BLAKE2b-256 checksum How to use checksums |
2d77f1f1fc867b0344cd88a7f86ee20ad23308f95f3b7c406c0cf7c912f38ac7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
