# Lyra

Self-hosted, multi-source music acquisition and library tool — a replacement for
Lidarr + NZBget. Lyra discovers, ranks, downloads, tags, and organizes music across
sources of differing quality: **Qobuz** (lossless/hi-res), **Soulseek** (P2P), and
**YouTube** (universal lossy fallback), with recommendation-driven discovery via
**ListenBrainz** (Spotify's recommendation/related-artists APIs were retired for new
apps, so discovery is MetaBrainz-native and MBID-clean — no Spotify).

## Status

Built in three slices:

1. **Acquisition engine** — ✅ **done**. Resolve a request against MusicBrainz,
   match/rank across Qobuz/Soulseek/YouTube, download the best source into an
   isolated staging dir, verify completeness, tag (mutagen), and atomically promote
   the clean album into `Artist/Album (Year)/## Title.ext`.
2. **Library manager** — ✅ **done**. Watched artists (live MB search + follow),
   per-release monitor toggles + auto-monitor-future, a wanted list with retry +
   quality-upgrade window, and a worker "monitor" that discovers new releases and
   auto-grabs through the acquisition pipeline. Plus a **library scan** that ingests
   existing on-disk albums as have + monitored + followed, and a per-artist
   studio-only / show-all release-type filter.
3. **Discovery** — ✅ **done**. Recommendation-driven finding of new music via
   **ListenBrainz** similar-artists (MBID-native), behind a pluggable
   `SimilaritySource` interface. A background sweep (and a "Discover now" button)
   aggregates artists similar to the ones you follow into a manual review feed of
   suggested **artists** and **albums** at `/discover`; **Follow** and **Want**
   reuse the slice-2 follow / wanted flows, **Dismiss** is permanent. Plus a
   web-side seed-search box. Every suggestion and seed-search result opens a
   read-only **artist preview** (`/discover/artist/[mbid]`) — discography,
   per-album tracklists, and "in library" / "monitored" badges — where you can
   Follow or Want before committing. No Spotify (its recommendation APIs are dead
   for new apps).

**Operational notes:** the monitor and the discovery sweep are both **off by
default** — set `monitor.enabled=true` (+ optional `monitor.*` tuning) in the
`Config` table to activate auto-grab/upgrade, and `discover.enabled=true` (or
Settings → Discovery, + optional `discover.*` tuning) to activate the scheduled
discovery sweep. The `/discover` "Discover now" button and seed-search work with the
sweep off. Credentials are entered in Settings and persist across
`docker compose up -d --build` rebuilds (don't use `down -v`). Tests run against a
separate `lyra_test` database (a guard blocks the live DB). Deferred hardening + the
full roadmap live in the implementation-plan "Notes" sections under
[`docs/superpowers/plans/`](docs/superpowers/plans/).

## Architecture

Three Docker containers on a home server:

- **Next.js app** — UI + API (search, request, queue, progress, settings).
- **Python worker** — all source integration (streamrip, yt-dlp, slskd client,
  mutagen; MusicBrainz + ListenBrainz for metadata and discovery), running the
  six-stage acquisition pipeline plus the background monitor and discovery sweeps.
- **slskd** — off-the-shelf headless Soulseek daemon.

**Postgres** is the shared source of truth; a shared `/music` volume is the library.

See [`docs/superpowers/specs/`](docs/superpowers/specs/) for the full design.