a full featured navidrome client for web and android
  • TypeScript 30.4%
  • Kotlin 28.8%
  • Python 26.2%
  • Rust 9.2%
  • HTML 2%
  • Other 3.4%
Find a file
Matthew Weber 51b56e91a3
Some checks failed
checks / check (push) Has been cancelled
checks / tui (push) Has been cancelled
big fixes
2026-11-15 22:23:15 -05:00
.claude more 2026-09-16 21:41:30 -04:00
.forgejo/workflows big fixes 2026-11-15 22:23:15 -05:00
android big fixes 2026-11-15 22:23:15 -05:00
core big fixes 2026-11-15 22:23:15 -05:00
deploy big fixes 2026-11-15 22:23:15 -05:00
desktop big fixes 2026-11-15 22:23:15 -05:00
docs big fixes 2026-11-15 22:23:15 -05:00
icons icons 2026-09-30 03:31:01 -04:00
packages/api-client core: per-user scoped API keys, and station prompt/play routes 2026-11-07 16:49:50 -05:00
scripts big fixes 2026-11-15 22:23:15 -05:00
spikes/gapless big fixes 2026-11-15 22:23:15 -05:00
tui big fixes 2026-11-15 22:23:15 -05:00
web big fixes 2026-11-15 22:23:15 -05:00
.dockerignore deploy stage 1 2026-09-17 01:25:54 -04:00
.gitignore big fixes 2026-11-15 22:23:15 -05:00
CLAUDE.md big fixes 2026-11-15 22:23:15 -05:00
flake.lock desktop: lock the flake 2026-10-15 16:14:31 -04:00
flake.nix desktop: Electron shell with MPRIS, packaged for Nix 2026-10-15 16:14:25 -04:00
PLAN.md fix breaks and radio 2026-09-17 14:29:34 -04:00
README.md big fixes 2026-11-15 22:23:15 -05:00
ROADMAP.md big fixes 2026-11-15 22:23:15 -05:00

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 (project name:, container_name:, volume name:), the git remote, package names under packages/, 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.

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

  1. Airtime never writes to your music files. Derived metadata — inferred genres, audio features, votes — lives in Core's database as an overlay.
  2. 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.nix in the NixOS config, not here.
  3. Core serves /api/v1 and 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).