v0.1.5

Unpack the source archive, then:

./scripts/install.sh
musicseed

Python 3.12+, uv, and Node/npm are required to install. Runtime is Python only.

Changes

• Merge remote-tracking branch 'origin/dev' (558e870)
• fix test (1e06aa9)
• improve docstrings and inline comments (a0be1d3)
• improved log (c856ae4)

v0.1.4

MusicSeed v0.1.4

An agent-first cut on top of v0.1.3. The headline: MusicSeed now ships an MCP server, so an AI agent — Claude Desktop, Codex, pi, opencode, anything that speaks MCP — can resolve your seeds, preview a playlist, and write it back to Plex through typed tools instead of you clicking. Behind that, the playlist write path became idempotent, so a retried agent (or a retried you) can't double-write or clobber a playlist.

What changed

• A new mcp/ app: musicseed-mcp. A stdio MCP server exposing playlist create and populate as typed agent tools. It's a thin adapter over core's services/ layer and depends on core only — no web server, no listening port, no HTTP. Read-only tools (get_status, list_presets, search_tracks, list_playlists, preview_playlist, preview_populate) let an agent inspect the library and score candidates; write tools (create_playlist, populate_playlist) are the only things that touch Plex.
• A safe agent workflow by construction. The intended flow is search → preview (read-only) → approve a subset → write with only the approved IDs. Writes never recompute recommendations and never silently write a subset: missing or stale IDs reject the whole write. A host-agnostic SKILL.md teaches the full workflow to hosts that support skills, and the server's instructions and tool descriptions carry the same guidance for hosts that don't.
• Idempotent playlist writes in core. create_playlist_from_tracks now reconciles by name — if a playlist with that name and exactly those tracks already exists, it reports success instead of erroring; if the name exists with different tracks, it raises a clear conflict. populate_playlist only adds tracks that aren't already present and reports added_count and already_present_count separately. Retrying after a lost response is now safe for agents and humans alike.
• One dev command for all three surfaces. scripts/dev.sh now starts the API, the web UI, and the MCP server together (stdio default, streamable-http/sse transports available for hosts that connect over a URL).
• Docs reflect the new surface. README, root guide, and the dependency diagram now describe mcp/ as a real app, with its own README and AGENTS.md.

Recommendation logic is unchanged — same six signals, weights, normalization, and formulas as v0.1.3. This release changes how playlists get written (idempotently) and adds a new surface for driving them; selections themselves don't move.

Install

Download the source zip or tar.gz below, unpack it, then:

./scripts/install.sh
musicseed

You need Python 3.12+ and Node/npm to install. After that, only Python is running. Open http://127.0.0.1:8789.

Prefer git? See Install from source in the README.

macOS and Linux. Windows is untested.

Notes for v0.1.4

Upgrading is safe: state is still the same single SQLite file, and there are no schema changes to migrate by hand.

The MCP server is opt-in. If you don't use agents, nothing changes. To let an agent drive playlists, register musicseed-mcp as a stdio server with your MCP host (see mcp/README.md); it reads the same config the CLI uses, and writes stay behind the same preview → approve → write discipline the web UI and CLI already enforce.

Recommendation output is unchanged from v0.1.3. Expect rough edges; file issues with what you tried and what Plex showed, not with tokens or library paths.

v0.1.3

MusicSeed v0.1.3

A remote-and-correctness cut on top of v0.1.2. The headline: MusicSeed no longer assumes Plex runs on the same machine. It can pull consistent snapshots of your Plex library and blobs databases over verified SSH, and it now imports Plex's sonic vectors into its own store — so sonic similarity keeps working even when Plex isn't reachable at query time. Behind the scenes, recommendation retrieval was rewritten to score every eligible track instead of a lossy shortlist.

What changed

• Remote Plex over SSH. Point at a Plex server on another machine (a NAS, another box) with an scp-style db_ssh_target, plus optional password/port auth. MusicSeed streams consistent SQLite backups over SSH using a bundled standard-library helper — never by copying your live database files. Host keys are verified, and the real SSH failure reason is surfaced in discovery instead of a generic error.
• Sonic vectors are imported, not re-read. Plex's analysis vectors are copied into MusicSeed's own track_vectors table (musicseed-cli import-plex-sonic, with a refresh flow and coverage in the web UI). The blobs database is only needed at import time; recommendations read the local store afterward. Pre-existing databases get the table created on demand.
• Retrieval rewritten to score every eligible track. The old bounded multi-source retriever could silently drop a perfect match (seeds exhausting a source budget, unordered tag limits). The new pipeline scores every eligible track in bounded-memory batches, applies year filters in SQL, and uses explicit tie-breakers. The old retriever survives only as an offline diagnostic reference.
• Offline recommendation evaluation. A reproducible harness scores synthetic fixtures through the production pipeline against an exhaustive oracle and a sonic+novelty baseline, and fails on safety-invariant violations (duplicates, seed/year/artist/threshold breaches). Rankings are reported honestly, not laundered into a passing score.
• Recommendation correctness. Year filters now apply before sonic nearest-neighbor selection, missing-signal confidence shows up in explanations, evidence and approved playlists survive, and services return JSON-safe DTOs.
• Jobs and import recovery are bound to stable contexts. Explicit context objects replace global singletons; job ownership, restart recovery, and import provenance are tracked so a dead process's claim can't strand your library, and deleting history can't make setup look incomplete again.
• The CLI can write playlists. recommend can create a Plex playlist or append to an existing one directly, and status now shows Plex-vs-local import coverage.
• Setup and settings polish. The wizard stays in the review step once Plex is connected, shows save confirmation and plain-language status, distinguishes local vs remote source, and drops the now-unneeded local database path field.

Recommendation scoring is unchanged — same six signals, weights, normalization, and formulas. What changed is retrieval: the old shortlist could drop a perfect match, and the new pipeline considers every eligible track, so selections can legitimately differ from v0.1.2. If a recommendation looks different, that's the fix working, not a change in taste.

Install

Download the source zip or tar.gz below, unpack it, then:

./scripts/install.sh
musicseed

You need Python 3.12+ and Node/npm to install. After that, only Python is running. Open http://127.0.0.1:8789.

Prefer git? See Install from source in the README.

macOS and Linux. Windows is untested.

Notes for v0.1.3

Upgrading is safe: state is still the same single SQLite file, and schema changes are additive — the new track_vectors table is created on demand for pre-existing databases, so there's nothing to migrate by hand.

Two things worth knowing:

• Sonic similarity now comes from MusicSeed's own store. Run musicseed-cli import-plex-sonic (or the equivalent in the web UI) once after upgrading to copy Plex's vectors in. Until then, sonic coverage will read low even though Plex analyzed your library long ago.
• Remote Plex is opt-in. If Plex runs on the same machine, nothing changes. To point at a NAS or another host, set plex.db_ssh_target in Settings; MusicSeed fetches snapshots over verified SSH and never needs a copy of your live database files.

Recommendations can change because retrieval is now complete. Expect rough edges; file issues with what you tried and what Plex showed, not with tokens or library paths.

v0.1.2

MusicSeed v0.1.2

A visual-identity cut on top of v0.1.1. The product UI now shares a vocabulary with the public site: one set of tokens, a branded shell, consistent page hierarchy and controls, and a warm amber accent instead of a generic dark theme.

What changed

• Shared design tokens. Canvas, type, radius, motion, and a warm amber accent live in one token file. The marketing site and the app are supposed to feel like the same MusicSeed, not two nearby projects.
• Branded app shell. Header, wordmark, and active/focus states match the site instead of a stock dashboard chrome.
• Consistent pages and controls. Product pages start with an eyebrow, title, and purpose. Buttons, panels, and surfaces share the same language and hit targets.
• Parity checks. A small script guards the shared token vocabulary and the shell/hierarchy/control patterns so the two surfaces cannot drift silently.

No recommendation logic changed; scores, signals, and playlist selection behave exactly as in v0.1.1.

Install

Download the source zip or tar.gz below, unpack it, then:

./scripts/install.sh
musicseed

You need Python 3.12+ and Node/npm to install. After that, only Python is running. Open http://127.0.0.1:8789.

Prefer git? See Install from source in the README.

macOS and Linux. Windows is untested.

Notes for v0.1.2

Upgrading is safe: state is still the same single SQLite file, and there are no schema changes to migrate by hand. This release is visual. Expect rough edges; file issues with what you tried and what Plex showed, not with tokens or library paths.

v0.1.1

MusicSeed v0.1.1

A fix-and-polish cut on top of v0.1.0. The headline: popularity enrichment via ListenBrainz — the preferred provider — is now done right, reachable from the web UI instead of CLI-only, and no longer shares the stage with a dead MusicBrainz client that implied support that was never there.

What changed

• ListenBrainz from the web UI. The API only exposed Spotify enrichment; ListenBrainz was CLI-only. There is now a POST /enrichment/listenbrainz route, so the dashboard can run the preferred provider too.
• Enrichment requires credentials. Bring a ListenBrainz user token (new listenbrainz.token config, env-expandable) or Spotify credentials. This gets you the authenticated rate-limit tier instead of anonymous throttling — a deliberate product decision, not an oversight.
• Dead code removed. The vestigial MusicBrainz enricher (a leftover MBID→Spotify cross-reference client from the original 4-tier design) is gone. Nothing called it; now nothing implies it.
• Simpler install. uv is no longer required for end users — the installer is plain python3 -m venv + pip. uv remains development-only tooling.
• Friendlier first run. The web wizard gained a configure intro screen.
• Docs grew up. The docs/ tree now renders as a MkDocs Material site, including a generated CLI reference page built from the same Typer docstrings that power --help. Public-seam docstring coverage went from 65% to 100% and is enforced by scoped ruff pydocstyle rules, so it cannot silently decay. mkdocs build --strict is part of verification, and CI now runs on dev.

No recommendation logic changed; scores, signals, and playlist selection behave exactly as in v0.1.0.

Install

Download the source zip or tar.gz below, unpack it, then:

./scripts/install.sh
musicseed

You need Python 3.12+ and Node/npm to install. After that, only Python is running. Open http://127.0.0.1:8789.

Prefer git? See Install from source in the README.

macOS and Linux. Windows is untested.

Notes for v0.1.1

If you enriched anonymously with v0.1.0, set a ListenBrainz token (or Spotify credentials) before your next enrichment run — unauthenticated runs are no longer accepted. Upgrading is safe: state is still the same single SQLite file, and there are no schema changes to migrate by hand. Expect rough edges; file issues with what you tried and what Plex showed, not with tokens or library paths.

v0.1.0

MusicSeed v0.1.0

MusicSeed is a local-first recommendation tool for people who already live in Plex: collectors with a large library, Plexamp daily drivers, and anyone who is tired of “similar tracks” that only chase one sonic slider.

This first public release is for technically comfortable music fans. You run it on your machine, against your Plex music section. No account, no cloud, no “upload your library.” If you can install Plex, you can install this.

What it is for

Plex is excellent at playback, metadata, and (if you let it) sonic analysis. It is weaker at discovery inside a collection you already paid for — the “I know this seed, now walk the stacks” problem. Radio-style mixes collapse into one dimension. Charts and streaming recs ignore the fact that the interesting copy is already on your disk.

MusicSeed ranks tracks that are already in your library. You pick one or more seeds; it builds a list you can preview, tune, and write back as a Plex playlist.

What you get

• A first-run wizard that finds Plex on the LAN (and via plex.tv when the server is on another subnet), then imports the library.
• Recommendations from six signals: sonic similarity (Plex’s own analysis, read at query time — MusicSeed does not fingerprint your files), popularity proximity (ListenBrainz first, Spotify optional), style, genre, era, and novelty from local play history.
• Weights and an average vs frequency strategy when you populate an existing playlist.
• Preview and confirm before anything is written to Plex.
• A dashboard for import/enrichment coverage, plus a CLI (musicseed-cli) if you would rather script than click.

State is one SQLite file. Backup is copy that file.

How this project is meant to be used

This is DIY software. MIT licensed, run from source, no installer dongle, no telemetry. The point is to sit next to Plex the way a good rip, a well-tagged folder, or a handmade playlist does: local, inspectable, and yours.

If you like opening the hood — logs, config, a dry-run before a write — you are the audience. If you wanted a hosted “smart radio” with a pricing page, this is the wrong repo.

Install

Download the source zip or tar.gz below, unpack it, then:

./scripts/install.sh
musicseed

You need Python 3.12+, uv, and Node/npm to install. After that, only Python is running. Open http://127.0.0.1:8789.

Prefer git? See Install from source in the README.

macOS and Linux. Windows is untested.

Notes for v0.1.0

This is the first tagged cut of a working local app, not a polished 1.0. Imports can be resumed if they stop early. Expect rough edges; file issues with what you tried and what Plex showed, not with tokens or library paths.