meaning/pmda repository overview

PMDA (pronounced "pimda")

⁠The self-hosted music library manager that actually knows your music.

You have 50,000 albums on a server. Ripped over decades, tagged by five different tools, duplicated across three "I'll sort this later" folders. PMDA is the thing that sorts it later.

Point it at your music. It identifies every release against MusicBrainz, Discogs, iTunes, Deezer and Bandcamp, pulls the real covers, the real biographies, the reviews, the aliases, the labels, the concert dates — and stores everything it ever finds in PostgreSQL. It never throws anything away. It's an aggregator with taste.

⁠Why it's different

🧠 It doesn't guess — it hoards evidence. Every bio, cover, and review PMDA finds is kept per source, and the best one wins automatically (a mediocre write-up can never overwrite a great one). Change your mind? Pin the version you prefer with one click. Your choice is final.

🤝 It never deletes your files. Duplicates are only flagged when the content is truly identical — same tracks, same lengths (and FLAC always beats MP3). Anything it moves goes to a reversible quarantine with a manifest. Different editions aren't "duplicates"; they become a version picker. Incomplete albums get detected, listed, and can even be reassembled from fragments — automatically.

🤖 Your AI agent is the brain — not ours. PMDA ships with zero built-in AI and needs zero API keys. Instead, it exposes 50+ MCP tools: download the plugin from the UI, hand the folder to Claude Code, Codex, OpenClaw or any MCP client, and it installs itself and starts proposing things to do — audit your dupes, hunt incomplete albums, request missing releases. Your model, your billing, your rules.

📥 It closes the loop. Missing release? Hit Request. PMDA drives Lidarr and Autobrr (bring your own indexers — PMDA never talks to trackers), and a webhook ingests finished downloads into the library within minutes. Spot an album you only have in MP3? Request FLAC upgrade. One artist, all lossy albums? One button.

🏠 A home that knows you. On repeat, rediscover what you dropped months ago, the albums you own but never played, new arrivals ranked by your taste, acclaimed records sitting unplayed in your own library — every card tells you why it's there.

⏱️ Two questions and you're in. Setup asks where your music lives and what PMDA may do with your files (look, build a clean copy, or tidy up). That's it. Everything else is smart defaults you can override later — including in the advanced panel, pre-filled and honest.

⁠Quick start

One container. PostgreSQL, Redis, the works — all inside.

docker run -d \
  --name pmda \
  --restart unless-stopped \
  -p 5005:5005 \
  -e PMDA_AUTH_ENABLED=1 \
  -e PMDA_MEDIA_CACHE_ROOT=/cache \
  -v /srv/pmda/config:/config \
  -v /srv/pmda/cache:/cache \
  -v /srv/music:/music:rw \
  -v /srv/pmda/review:/dupes:rw \
  -v /srv/pmda/musicbrainz-mirror:/musicbrainz-mirror \
  meaning/pmda:latest

The /musicbrainz-mirror mount is where the optional local MusicBrainz mirror stores its database and search index when you enable it (one click, later). Plan ~150 GB on fast storage. Include the mount from day one even if you are not sure yet: it costs nothing while empty, and it guarantees the mirror's data lands on a disk you chose — never inside Docker's own image file. The mirror is what makes PMDA's matching effectively rate-limit-free.

Open http://localhost:5005, create your admin account, answer the two questions, press GO. Your first scan starts immediately — matching, artwork, bios and reviews flow in from there.

Tags: latest (stable) · beta (fresh from the lab).

Beta testers: use meaning/pmda:beta. Fixes land on the beta line first — latest stays on the current stable release and only moves when a beta has been confirmed and promoted, so a tester sitting on latest is testing an older build. After switching the tag, recreate the container (Unraid: Force Update): a restart keeps the image already cached on the host.

⁠What you get

• A fast, beautiful library — artists, albums, genres, labels (with logos), full-text search with did-you-mean, box-set grouping, edition pickers, playback with history, likes, playlists and per-user stats.
• Artist pages that go deep — best-of biographies, "also performs as" and group chips that actually link to the right pages, release labels, concerts, similar artists, and the releases you're missing (requestable in one click).
• Album pages with receipts — reviews with critic scores (Wikipedia, CritiqueBrainz — no API keys needed), public ratings, provider links, match details, and admin curation pencils to swap a cover or a bio from real candidates, permanently.
• Maintenance you can trust — dedicated Duplicates and Incompletes pages, dry-run first, reversible always, honest reporting everywhere.
• Acquisition built in — Lidarr + Autobrr as first-class sources, request queues with real statuses, automatic retries, and instant ingestion of finished downloads.
• Agent-ready by design — the MCP plugin ships in the box, downloadable from the UI, self-installing, with a getting-started guide written for the agent itself.

⁠Good to know

• Files-first: your folders stay the source of truth. PMDA works for your files, not against them.
• Self-hosted, multi-user: admins manage; users browse, play, like, build playlists.
• Docker / Unraid friendly: single container, sane volumes, no external database to run.
• No AI required, no keys required: MusicBrainz, iTunes, Deezer, Spotify and Bandcamp work out of the box. Discogs and Last.fm keys are optional boosters, never requirements.

⁠Docs

• User Guide⁠ — everything, with pictures
• Configuration⁠ — every knob, for when defaults aren't enough
• Agent toolkit⁠ — the MCP plugin, install guide included

⁠Development

React + TypeScript + Vite + Tailwind frontend, Flask + PostgreSQL + Redis backend, one image. PRs welcome — the test suite is pytest, the frontend gate is tsc --noEmit, and the repo ships with an agent toolkit, because of course it does.