harmonia
A unified self-hosted media platform: one Rust server across 21 crates, replacing a stack of separate *arr-pattern services with one coherent media lifecycle manager.
RECORDING FORTHCOMING: harmonia serve boots → a health check answers → a library scan triggers → its import queue populates, against a small seeded sample-media directory
What it is
harmonia is a unified self-hosted media platform: a single Tokio/Axum/SQLite server spanning 21 workspace crates, aimed at replacing the pattern where you run five or six separate *arr-style applications (one for movies, one for TV, one for music, one for indexing, one for requests) and wire them together yourself. Instead it’s one coherent server covering the full media lifecycle: import and rename, library scanning, metadata enrichment, quality verification, torrent acquisition, download-queue orchestration, household request handling, HTTP streaming, and a native audio pipeline with bit-perfect decode and DSP.
Decisions and trade-offs
One server instead of five federated services
The *arr-stack pattern (a separate app per media type, each with its own database, its own auth, its own web UI, wired together by the user) is well-established and has a large plugin ecosystem behind it. harmonia rejects that shape on purpose: one server, one auth layer, one database, 21 crates organized by concern (core, auth, media ops, acquisition, serving, audio, UI) rather than by deployable unit. The cost is losing the *arr ecosystem’s existing plugin surface; the benefit is a media manager that doesn’t require reasoning about five services’ worth of drift between each other.
| Decision | Chose | Rejected | Cost accepted |
|---|---|---|---|
| Status reporting | A capability table naming shipped-and-wired vs. stubbed capabilities, down to the exact stub count | A blanket “it works” status claim | Harder to keep honest than a vague claim — the count has to stay current |
| Audio decode | Native bit-perfect decode and DSP (akouo-core), in-process | Piping through an external decoder tool | ALSA development headers required at build time on Linux, a real stated prerequisite |
What’s solid / what’s open
Solid, shipped and wired to live routes: auth, library scan/import, the feed scheduler, the torrent download engine, queue orchestration, the HTTP/OpenSubsonic streaming API, external integrations (Plex, Last.fm, Tidal), QUIC renderer transport, the native audio pipeline, and post-download import — a completed download lands directly in the library for music, movie, and book wants.
Open: two null placeholders remain at the HTTP layer, for metadata resolution and curation, on the live serve path — named directly, not folded into a vaguer “still improving” claim. Audiobook, comic, podcast, and TV-series wants have no library type yet and are deferred. A fallback/test path (AppState::with_stubs) defines nine additional Null* service implementations used for testing, separate from the two live-path placeholders above. The README documents the build and test commands but not yet how to run the server day to day: no quick-start section, no example config. Reaching a running instance from a fresh clone means reading the archon CLI’s own --help output rather than following a documented path; the recording above shows the same binary running, not a shortcut around that gap.
Numbers, and how they were measured
| Claim | Method | Where to check |
|---|---|---|
| 100,460 lines Rust (code-only), 117,575 including comments | tokei against a local clone, 2026-07-20 | reproducible: tokei on a fresh clone |
| 21 workspace crates | crate count in the workspace Cargo.toml | reproducible on a fresh clone |
| ~2,290 test-attribute occurrences | rg -c '#\[(tokio::)?test', 2026-07-20 | reproducible: same rg command on a fresh clone |
| 2 null placeholders remain at the live HTTP layer (metadata resolution, curation) | stated directly in the repo’s own capability-status table | README.md, Capability status section |
Where to look
- Repo: github.com/forkwright/harmonia
- The shipped-vs-stubbed capability table in full:
README.md - The CLI entry point (
serve,db,play,render,migrate, localmcp):crates/archon/src/cli.rs