- TypeScript 30.4%
- Kotlin 28.8%
- Python 26.2%
- Rust 9.2%
- HTML 2%
- Other 3.4%
| .claude | ||
| .forgejo/workflows | ||
| android | ||
| core | ||
| deploy | ||
| desktop | ||
| docs | ||
| icons | ||
| packages/api-client | ||
| scripts | ||
| spikes/gapless | ||
| tui | ||
| web | ||
| .dockerignore | ||
| .gitignore | ||
| CLAUDE.md | ||
| flake.lock | ||
| flake.nix | ||
| PLAN.md | ||
| README.md | ||
| ROADMAP.md | ||
Airtime
Placeholder name. Real name to be workshopped before launch. It is deliberately confined to four places so the rename stays mechanical:
deploy/docker-compose.*.yml(projectname:,container_name:, volumename:), the git remote, package names underpackages/, and doc headings. Nothing in code depends on it. See ROADMAP for the prior-art note on the name.
A full-featured self-hosted music player — web, desktop, Android — on top of an OpenSubsonic library server, with the DJ AI radio built in rather than bolted on.
- PLAN.md — architecture and the decisions behind it
- ROADMAP.md — phases, exit criteria, risk register
- docs/decisions/ — ADRs
Status
In daily use. Core runs on hermes behind a Cloudflare tunnel, and the web app,
the Android app, the terminal client and the desktop shell all talk to its
/api/v1. The DJ's backend lives inside Core (core/app/dj/) rather than
beside it. Accounts and per-user scoped API keys exist, so one library serves
more than one listener.
| Client | State |
|---|---|
Web (web/) |
The main client: library, search, queue, playlists, stations, stats, themes |
Android (android/) |
Daily driver on the phone, offline downloads included |
TUI (tui/) |
Every screen, keyboard-first |
Desktop (desktop/) |
Electron shell with Linux MPRIS; no tray, offline downloads or signed builds yet (ADR-0009) |
ROADMAP.md says what each phase delivered and what is left, and the ADRs in docs/decisions/ say why things are the way they are. Phase 0's questions are all answered there:
| Question | Answer |
|---|---|
| Does adding sonic similarity displace the working Last.fm one? | ADR-0001 · ADR-0005 — crowd data stays primary. AudioMuse was stopped in 2026-09 and is dormant |
| Does Navidrome expose library-change events to plugins? | ADR-0002 — no, and the native API is better anyway |
| Can clients stream directly from Navidrome? | ADR-0003 — not until 0.65, so Core resolves stream URLs |
| How gapless can a browser actually be? | ADR-0004 — Opus is 0 ms; MSE can't read Ogg, so Core remuxes to WebM with -c copy |
Layout
core/ FastAPI service — the player's backend and the DJ, one image
web/ React + TS + Vite player
desktop/ Electron shell around the web app
android/ Kotlin + Compose + Media3
tui/ Rust + ratatui terminal client — every screen, keyboard-first
packages/api-client/ Generated TS client from Core's OpenAPI spec
deploy/ Compose stacks: production (hermes) and the dev sandbox
scripts/ check.sh (everything CI runs) and the check_*.py behind it
docs/decisions/ ADRs
icons/ App icon sources and exported sizes
spikes/ Phase 0 experiments — throwaway, but keep the results
flake.nix Nix package and dev shell for the desktop shell only
Checks
sh scripts/check.sh # everything; or one of: web desktop core
# contract docs android tui
The same script is all CI runs. Android's JVM tests are local-only: CI has no Android toolchain, and the section says so rather than passing silently.
Development sandbox
The sandbox Navidrome is isolated from the live install and mounts your
music read-only. It exists so agent/plugin experiments can't break a setup
you actually use. It reads the same NFS share hermes serves (MUSIC_DIR,
default /mnt/content/Music), so comparisons against live are
apples-to-apples.
| Instance | Version | Port | Purpose |
|---|---|---|---|
navidrome-dev |
0.64.0 | 4533 | Main sandbox — experiments run here |
navidrome-parity |
0.64.2 | 4534 | Matches hermes. Profile-gated; start it only to run the upgrade contract test |
hermes runs 0.64.2 (as of 2026-11-06), pinned by nixpkgs. Before any Navidrome
upgrade reaches live, run deploy/parity-check.sh —
it diffs the extension set, the native /api/song field set, and pagination,
and fails on removals. ADR-0002 depends on an API upstream calls internal, so
this is the mitigation, not a nicety.
docker compose -f deploy/docker-compose.dev.yml up -d
No .env needed. The sandbox admin password is generated into Navidrome's
volume on first start; read it with
docker exec airtime-navidrome-dev cat /data/sandbox-admin-password and give
it to the setup screen of the web app (cd web && npm run dev, which proxies
to the dev Core on 8100). Optional settings
(Last.fm keys, the music path, an Anthropic key) are listed in
deploy/.env.example. Without the Last.fm keys the
sandbox's Last.fm agent returns nothing.
Ground rules
- Airtime never writes to your music files. Derived metadata — inferred genres, audio features, votes — lives in Core's database as an overlay.
- The sandbox is never the live install. If a command could touch the
live Navidrome or Core on hermes, it doesn't belong in this repo. Their
public hostnames are defined in
hermes/modules/cloudflare.nixin the NixOS config, not here. - Core serves
/api/v1and nothing else. This rule used to read "Don't break DJ —/api/*keeps working until nothing calls it", from when Core was planned as a strangler-fig around DJ's backend. DJ's backend now lives inside Core (core/app/dj/) and there is no/api/*compatibility layer; the standalone DJ project is slated for retirement (docs/README.md).