User Guide

Install required tools:

Media Curator User Guide

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Getting Started

Prerequisites

Install required tools:

# yt-dlp (video/audio downloader)
pip install yt-dlp

# ffmpeg (transcoding, extraction)
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# opustags (Opus metadata)
# Ubuntu/Debian
sudo apt install opustags

# macOS
brew install opustags

Deploy the Framework

Use AIWG to complete this documented outcome: Deploy the Framework
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Quick Start: Complete Collection

The simplest way to use Media Curator is the `/curate` command:

/curate "Twenty One Pilots" the output option ~/music/twenty-one-pilots

This runs the full pipeline: analyze → discover → acquire → tag → verify → report.

Step-by-Step Workflow

Step 1: Analyze the Artist

/analyze-artist "Twenty One Pilots" the depth option thorough

Output: structured era breakdown, catalog structure, special collections.

Step 2: Discover Sources

/find-sources "Twenty One Pilots" the scope option complete the output option sources.yaml

Output: ranked source list per track/album with quality scores.

Step 3: Acquire Content

/acquire the plan option sources.yaml the output option ~/music/twenty-one-pilots the parallel option 3

Downloads content with format selection, quality filtering, and progress tracking.

Step 4: Tag and Organize

/tag-collection ~/music/twenty-one-pilots the artist option "Twenty One Pilots"

Applies metadata tags, embeds artwork, enforces naming conventions.

Step 5: Verify Integrity

/verify-archive ~/music/twenty-one-pilots the generate option the provenance option

Generates CHECKSUMS.sha256, VERIFY.md, and PROVENANCE.jsonld.

Step 6: Check Completeness

/check-completeness "Twenty One Pilots" the collection option ~/music/twenty-one-pilots

Shows what you have, what's missing, and what to prioritize.

Targeted Workflows

Specific Era

/curate "Twenty One Pilots" the scope option era:trench the output option ~/music/top-trench

Specific Style

/curate "Twenty One Pilots" the scope option style:acoustic the output option ~/music/top-acoustic

Single Track/Album

/find-sources "Twenty One Pilots" the scope option track:"Car Radio"
/acquire the url option "https://youtube.com/watch?v=..." the format option audio the output option ~/music/

Assembly and Export

Create a Narrative Compilation

/assemble the type option narrative the name option "DEMA Saga" the collection option ~/music/twenty-one-pilots

Create a Playlist

/assemble the type option playlist the name option "Best of Vessel Era" the collection option ~/music/twenty-one-pilots

Export for Plex

/export the profile option plex ~/music/twenty-one-pilots ~/plex/music/twenty-one-pilots

Export for Mobile (Size-Budgeted)

/export the profile option mobile the max-size option 8 ~/music/twenty-one-pilots ~/phone/music/

Quality Control

Default Behavior

  • Quality threshold: 6.0/10
  • Phone recordings: rejected
  • Pro-shot content: accepted
  • Legendary content: accepted regardless of quality

Adjust Quality

# Accept everything
/curate "Artist" the quality option 3

# Only the best
/curate "Artist" the quality option 8

Archive Maintenance

Verify After Copy/Transfer

/verify-archive ~/music/twenty-one-pilots the verify option

Regenerate After Adding Files

/verify-archive ~/music/twenty-one-pilots the fix option

Periodic Bit Rot Check (cron)

# Add to crontab - weekly verification
0 3 * * 0 cd ~/music/twenty-one-pilots && tail -n +4 CHECKSUMS.sha256 | sha256sum -c the quiet option

Network Storage Rules

When working with archives on NAS/CIFS mounts:

1. Never do bulk operations directly on network mounts 2. Always pull to local storage first 3. Process locally (NVMe speed) 4. Push back when done

rsync -avh /nas/archive/ ~/local/working/
# ... all processing happens locally ...
rsync -avh the delete option ~/local/working/ /nas/archive/

Troubleshooting

yt-dlp 403 Errors

YouTube's SABR streaming causes HTTP 403 with specific format selectors on newer videos:

# FAILS on newer videos:
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]" URL

# WORKS: use generic selector
yt-dlp -f "best[ext=mp4]/best" URL

MusicBrainz Rate Limiting

MusicBrainz allows 1 request per second. The framework handles this automatically, but if you see 503 errors, add delays between lookups.

opustags Not Found

# Ubuntu/Debian
sudo apt install opustags

# If not in repos, build from source:
# https://github.com/fmang/opustags

Large Archive Performance

For archives with 1000+ files, use the parallel option flag for batch operations and avoid running verification on network mounts.