Music To Plex

Music to Plex

Acquire music and surface it in Plex/Plexamp. Three flows: album (one-shot via mtp-bot), DJ tracklist/crate, and YouTube playlist. Pick the flow, run it, verify, post notes.

Operating rules (non-negotiable)

• One command per album. For a single album/release, call mtp-bot handle once and post its output. Do not run mtp search/add/status yourself, do not pick a version (auto-pick is automatic), do not poll for download status (the notifier streams it).
• Serialize multi-album imports. mtp-bot keeps a state machine per chat; never dispatch album handler calls in parallel. Send one request, inspect its reply, and proceed only after it has accepted the release or returned to idle. If it opens a numbered picker, stop the batch and preserve that picker until its owner chooses or explicitly authorizes cancellation. Do not send a bare number, cancel, or a new request into an existing picker on behalf of a different request. Exception: when the user explicitly says to ignore or override an active download and names the replacement, treat that as direct cancellation authority: dispatch the resolved replacement once, without a redundant confirmation loop, and state that the earlier job may be abandoned.
• Route by shape. Album → mtp-bot handle. DJ tracklist/crate → the crate ingest reference. YouTube playlist or plain track list → the YouTube flow. Never pass a crate or multi-track prose to mtp-bot handle (album-shaped parser; it will reply ⏭️ Not a music album request — skipped.).
• Cover-art requests need resolution before dispatch. A bare mtp with an album image is an explicit album request, but mtp alone is not handler-ready. Transcribe/identify the cover, verify the canonical release and track count, then proceed through the resolved-image continuation. Never expect the album parser to infer a title from an image caption. When invoking mtp-bot, use the originating Telegram chat ID from the inbound route; a group ID, user ID, and configured home-chat ID are different things.
• Never claim done without verification. A "Downloading…" or a successful Plex refresh is a start signal, not proof. The album is done only when the files exist under the configured Plex library path and are visible in Plexamp. Read back playlist items before saying a playlist is updated.
• Show the user the checklist. For every album ingest, post/update this exact evidence-led checklist in order. Mark ✅ only after tool evidence; use ⏳ while active, ⚠️ for a verified blocker, and never silently omit a step:

  ⏳ Canonical release metadata / tracklist verified
  ⏳ Audio acquired and locally staged
  ⏳ Track count, tags, embedded art, and file integrity verified
  ⏳ NAS artist-path and write-permission preflight verified
  ⏳ Files copied to the final Plex-scanned NAS folder
  ⏳ NAS count/art/folder traversal verified; transfer sidecars cleaned
  ⏳ Plex refresh triggered and album + full track count read back from Plex
  ⏳ Obsidian note written: Artist note → Album note → DJ summary
  

  The final response must retain this checklist with concrete proof values (final path, counts, Plex result, and note path). If a fallback bypasses the normal handler, say so explicitly and still keep the checklist.
• Never fabricate facts. In DJ notes, if unsure of a musician/label/year, say less. Do not invent files, APIs, env vars, or NAS paths.
• Obsidian note voice and substance. Notes must use the full enrichment standard in references/music-note-blurb-order.md: original WFMU / LDBK / Radio Brussels / classic-underground-radio energy, vivid sensory language, and juicy source-backed facts that make listeners curious and emotionally engaged. Include verified recording/release context, label/year, collaborators/producers, samples or scene links, unusual backstory, cultural impact, and concrete listening cues when available. Never imitate a named presenter, write generic promo copy, or pad the note with unsourced trivia. Run the replaceability test before saving: if the note would mostly work after swapping the album name, rewrite it.
• Obsidian vault path. Write music notes to /Users/olegkoval/Documents/opus/Music/, the visible Music folder used by the existing notes (not Documents/opus/Obsidian/Hermes/Music/). Verify the exact note path by reading it back after writing.
• Secrets live in ~/.config/music-to-plex/.env (loaded automatically by Config.load), never in config.toml. If a check says "PLEX_TOKEN not set", fix the .env. See references/plex-token-source.md.
• Hand off repair. Album on disk but not visible, wrong folder/tags after the fact, bulk library cleanup, permission problems, or Plex scanner/DB crashes → this is plex-music-ingest's job, not this skill's.

One-shot album flow

The user posts once ("add ") and gets a status stream back. The mechanics (auto-pick best version, download, organize, Plex refresh, staged status messages) are handled by the tool chain. Your only creative job is the DJ blurb.

Step 1: run the handler once

mtp-bot handle "<exact user message>" --chat <chat_id>

<exact user message> = what the user said; <chat_id> = the Telegram chat ID. This auto-picks the highest-seed release, starts the download, and spawns a background notifier. It returns:

✅ Accepted: <Artist> — <Album>
⏳ Downloading [FORMAT] SIZE, N seeds — status updates to follow.

Post that result as-is.

Step 2: write the notes in strict order

Immediately after posting "Accepted", while the download runs in the background, write one enrichment package, in this order:

1. Artist note: a specific, substantial paragraph in the original WFMU / LDBK / Radio Brussels / classic-underground-radio lane: the artist's broader sound, history, scene, collaborators, and lane. Include at least one verified fact that gives the listener a reason to care.
2. Album note: a separate, juicy paragraph: year, label, recording/release context, key players, unusual backstory, samples or scene connections, cultural impact, and two or three concrete things to listen for. Use only facts verified from authoritative sources; turn them into a human invitation rather than a database dump.
3. Optional one-line DJ summary or recommendation: tactile, specific, curious, and emotionally inviting.

Keep artist note first and album note second, never merge them into one generic promo paragraph. Sound like a great late-night radio host with a crate-digger’s memory, not a press release or a Wikipedia entry. See references/music-note-blurb-order.md. Optional extras: 🎵 YouTube link, 🎶 You might also like: + 2 short recommendations.

Step 3: let the notifier stream the rest

The background notifier posts these on its own, so do not poll or re-run:

📥 Downloaded → 📂 Moving to library folder → 🔄 Rescanning Plex → ✅ Ready in Plexamp

After "Ready", mirror the notes into the canonical visible Music vault at /Users/olegkoval/Documents/opus/Music/ as a music note for that release (append if it exists), artist note above album note, followed by DJ summary and source links. Read the exact file back before reporting the note complete. If the user asked for album art, save the release image as cover.jpg in the artist/release folder and verify it exists. See references/cover-art-sourcing-session.md.

Step 4: follow-up replies (stuck downloads)

If a download stalls, the notifier posts a "stuck" message with 4 numbered options (wait 1h / wait N hours / next release / YouTube). When the user replies with a bare number 1-4, a count of hours, or "next" / "youtube", pass the reply verbatim to mtp-bot handle, exactly like an add request. Post whatever it returns.

YouTube handoff: if mtp-bot handle returns a line starting with __YOUTUBE_FALLBACK__, strip it and run the YouTube flow yourself (download highest-quality audio with yt-dlp, fix tags, move into the library, refresh Plex), then post the blurb. If rsync or scp is unsuitable for a release transfer, use the verified tar-over-SSH fallback, remove any macOS AppleDouble sidecars, and compare NAS/Plex track counts with canonical metadata. See references/manual-fallback-transfer-and-plex-verification.md, references/youtube-403-fallbacks.md, and references/youtube-full-album-fallback.md.

No-result continuation: if the bot returns an actual no-results outcome and the user asks to continue, do not stop at a blocker report. Resolve canonical MusicBrainz metadata, then run the fail-closed track-by-track YouTube fallback: match each track by normalized title and duration, reject videos/remixes/live versions unless canonical, tag and cover-embed every file, stage it, transfer, and verify in Plex. A file's existence is not evidence it completed: fully decode all staged files and compare each actual duration to canonical metadata before NAS transfer; re-tag the full set after any interrupted run. Prefer separately sourced tracks over slicing a continuous full-album upload; only split a full upload using validated cues and boundary checks. Clearly distinguish local staging, NAS transfer, and Plex visibility. See references/no-result-album-fallback.md and references/fallback-audio-validation-and-nas-preflight.md.

Manual-fallback NAS preflight

Resolve the canonical release first, then preflight the exact NAS destination in parallel with source selection and before substantial fallback downloading. Inspect the NAS layout and an existing album by the same artist. nas_music is a storage root, not proof that a new artist directory is inside the Plex-scanned library. Confirm the originating transfer account can write and traverse the exact final parent; if a new artist directory is required, confirm it can create that directory too. If the parent is root-owned or read-only, do not spend the whole fallback download hoping the copy will work and do not invent an alternate writable folder. Keep any already-staged release local and request an album-scoped permission repair from the NAS owner.

Durable access repair: when the user explicitly wants future managed imports to work, repair the Plex library root (for this setup, /volume1/music/library) rather than recursively changing ownership of the whole /volume1/music share. A safe target is managed-account ownership and library-root group write (for example beheerder:users, 775), then verify by creating and removing a uniquely named probe directory over SSH. New artist and album parents must still be Plex-traversable (755); an artist directory left at 770 can block scanner traversal even when the release directory and FLACs are readable. Never widen ownership/permissions above the Plex library root without explicit user approval. See references/nas-library-layout-and-write-preflight.md, references/fallback-audio-validation-and-nas-preflight.md, and references/nas-permissions-and-plex-traversal.md.

DJ tracklist / crate flow

A timestamped DJ set or a themed crate brief is not an album request. Parse the list, find lawful sources, acquire audio when allowed, fix metadata/artwork, store a separate DJ-friendly folder on NAS, and create/refresh a Plex playlist. Creation is incomplete until Plex shows a visible playlist and the crate has proper cover art. If the user says the set is for DJ practice, treat it as a practice crate: rebuild/trim for mixability, don't just append tracks. Full procedure: references/dj-tracklist-crate-ingest.md.

YouTube playlist flow

Use when the user wants a YouTube playlist (not a timestamped DJ set, not a single album) turned into a normal Plex listening playlist. Two inputs: a ready-made playlist URL, or a plain list of Artist - Title lines. Do not route through mtp-bot handle or the crate flow. Full download/tagging/placement/ verification steps: references/youtube-playlist-import.md.

Verification pitfalls (hard-won)

• File exists ≠ visible. After refresh, if Plexamp shows nothing, re-verify the album landed under the configured Plex-rooted library path (not a staging/ download dir or a bucket Plex doesn't scan). See references/plex-visibility-check.md.

• Permissions. Root-owned 700 directories are invisible to Plex traversal even if the audio is readable. Verify the final folder is traversable and fix to 755 before every refresh.

• Refresh verb. On this Plex install, /library/sections/{id}/refresh must be GET; PUT returns 404, and a targeted path= refresh may also 404 - fall back to a plain section refresh. Refresh only after files are in their final NAS path; refresh again after any later tag/rename change.

• Targeted refresh exists in the CLI. mtp refresh --path <final NAS path> is the preferred completion check when the release lands cleanly. Treat {"refreshed": true, "section_id": ...} as a real success signal.

• Target layout beats generic configuration. Before creating a genre bucket, inspect where Plex stores an existing album from the same artist and confirm the transfer account can write that parent. Do not redirect a release to an unrelated writable folder or unsorted solely to make the copy succeed; repair access to the canonical target instead. See references/nas-library-layout-and-write-preflight.md.

• Corrupt source ≠ Plex problem. If a chapter-based rip yields a zero-byte or corrupt final track, switch source first, then tag and move, don't just re-refresh. See references/malformed-flac-fallbacks.md.

• NAS codec tools may be unavailable. Some NAS images ship neither ffprobe nor an AAC decoder in ffmpeg. In that case, fully decode each staged source locally before transfer, then use NAS file count/art/sidecar/traversal checks plus Plex’s album-and-track read-back as the remote verification receipt. Do not describe a remote decode as passed when the NAS tool cannot decode it.

• Duplicate torrent. On Synology Duplicate torrent file, do not retry blindly: list_tasks first; repeated attempts stack failed tasks. Clean stale tasks, then re-search with plain artist/album text (no magnet URLs in replies). See references/duplicate-torrent-handling.md.

• Image/typo identification. If the user sends cover art or a misspelled/clip title (Single, Official clip, teaser), use it as a clue: confirm the real release name and track count on the store/release page before importing. See references/image-driven-identification-and-verification.md and references/bandcamp-album-identification.md.

• Lesson (scanner health): when an album repeatedly "won't ingest" after the files are correctly placed, stop re-moving files. The cause is usually scanner/ DB state, not placement: a direct scanner probe can crash with DB::Exception while a plain refresh succeeds. At that point the album is a plex-music-ingest case: check scanner health, DB state, and crash cause before touching tags again. (Real example: an album sat correctly at /volume1/music/Various Artists/… yet stayed invisible; extra nested library/pop layers never helped.)

References

• Notes & enrichment: music-note-blurb-order.md, cover-art-sourcing-session.md
• Album ID & verification: image-driven-identification-and-verification.md, gear-change-image-identification.md, bandcamp-album-identification.md, plex-visibility-check.md, verification-and-pitfalls.md
• DJ crates: dj-tracklist-crate-ingest.md, cover-art-repair-session.md, per-track-album-art-split.md, youtube-lineage-playlist-fallback.md
• YouTube: youtube-playlist-import.md, youtube-403-fallbacks.md, youtube-full-album-fallback.md, fallback-audio-validation-and-nas-preflight.md
• Playlists: plex-playlist-creation.md, plex-playlist-append-and-verify.md, zero-track-playlist-recovery.md
• Plex/NAS plumbing: plex-token-source.md, nas-routing-and-refresh.md, batch-import-staging.md, mtp-subprocess-wrapper.md, mtp-bot-bulk-state-safety.md, session-2026-06-17-synology-probe.md
• Repair/forensics (mostly owned by plex-music-ingest): library-repair-folders.md, canonical-artist-normalization.md, cover-art-and-plexamp.md

That is the skill. Pick the flow, run it, verify, post notes. Silence if no output.