YouTube Playlist Manager

Analyze, search, filter, clean up, and export YouTube playlists from Google Takeout CSV exports.

Workflow

Working with a playlist involves these steps:

1. Enrich: Fetch video metadata from CSV of IDs (run fetch_metadata.py)
2. Analyze: Generate statistics and reports (run analyze_playlist.py)
3. Search/Filter/Export: Query and export subsets (run export_playlist.py)
4. Recommend: Use enriched data to suggest what to watch (use analysis + Claude reasoning)

Determine the user’s goal:

• “Analyze my playlist” -> Steps 1 + 2
• “Find videos about X” -> Step 1 (if not done) + 3 with --search
• “Clean up my playlist” -> Steps 1 + 2, focus on cleanup section
• “What should I watch?” -> Steps 1 + 2, then recommend based on patterns
• “Export my playlist” -> Step 1 (if not done) + 3

Step 1: Fetch Metadata

Convert a CSV of video IDs into enriched JSON with full metadata.

Input format

Google Takeout CSV (two columns: video ID, date added):

dQw4w9WgXcQ,2023-06-05T09:50:53+00:00

With YouTube API key (preferred, fast)

python scripts/fetch_metadata.py playlist.csv -o enriched.json --api-key YOUR_KEY

Or set YOUTUBE_API_KEY env variable. ~30 API calls for 1500 videos (well within 10k daily quota).

With yt-dlp (no key, slower)

python scripts/fetch_metadata.py playlist.csv -o enriched.json --use-ytdlp

Supports --resume to continue interrupted fetches and --limit N for testing.

For API setup details, see references/youtube-api.md.

Step 2: Analyze

Generate a full analysis report from enriched data:

python scripts/analyze_playlist.py enriched.json --format md -o report.md
python scripts/analyze_playlist.py enriched.json --format json -o report.json

Report includes:

• Summary: total videos, watch time, availability
• Channels: top channels by video count and views
• Duration: distribution buckets, longest/shortest videos
• Engagement: most viewed, most liked
• Timeline: additions by month, publications by year
• Tags: most common tags and YouTube categories
• Cleanup: unavailable videos, duplicates, old entries (>2 years)

Step 3: Search, Filter, Export

Use export_playlist.py to query and export subsets:

# Find videos about a topic
python scripts/export_playlist.py enriched.json --search "machine learning" --format md

# Videos from a specific channel
python scripts/export_playlist.py enriched.json --channel "3Blue1Brown" --format csv -o 3b1b.csv

# Short videos (under 10 min) sorted by views
python scripts/export_playlist.py enriched.json --max-duration 600 --sort views --format md

# Top 20 most viewed available videos
python scripts/export_playlist.py enriched.json --status available --sort views --top 20 --format md

# Export full available playlist as CSV
python scripts/export_playlist.py enriched.json --status available --format csv -o full.csv

Filter options: --status, --channel, --search, --tags, --min-duration, --max-duration Sort options: --sort (views, likes, duration, added, published, title, channel) + --asc Limit: --top N

Step 4: Recommendations

After enrichment and analysis, use the data to recommend videos. Strategies:

1. By interest clusters: Group by tags/channel, suggest unwatched from top clusters
2. Quick wins: Short videos (<15 min) from popular channels
3. Deep dives: Long-form content (>30 min) highly rated
4. Fresh content: Recently added, not yet watched
5. Channel exploration: Channels with only 1-2 videos (discover new creators)

Read the enriched JSON and analysis report, then apply these heuristics conversationally.

Cleanup Workflow

To clean up a bloated playlist:

1. Run analysis to identify cleanup candidates
2. Present unavailable/deleted videos (can be removed safely)
3. Show duplicates
4. Show very old entries (added >2 years ago) for review
5. Optionally export the “keep” list vs “remove” list

Notes

• All scripts use only Python stdlib (no pip install needed) except yt-dlp fallback
• Output JSON is UTF-8 encoded with full Unicode support
• Scripts print progress to stderr, data to stdout/file
• Large playlists (1000+) work fine with API; yt-dlp may take 10-30 minutes