🎬 Movie Librarian

CLI tool to scan directories for video files, identify movies and TV shows via TMDb, and output a CSV catalog.

Quick Start

1. Install Node.js (if needed)

• Go to nodejs.org
• Download the LTS version
• Run the installer

2. Get a TMDb API Key (required)

1. Create a free account at themoviedb.org
2. Go to Settings → API
3. Request an API key (choose "Developer" option)
4. Copy your API key

3. Get an OpenAI API Key (optional)

Only needed if you want AI fallback for hard-to-identify files.

1. Go to platform.openai.com
2. Create an account and add billing
3. Go to API Keys and create a new key
4. Set a usage limit (e.g., $5/month) in Settings → Limits

4. Run the tool

npx movie-librarian

The tool will prompt you for your API keys on first run and save them to ~/.movie-librarian/config.json.

Usage

🎬 Welcome to Movie Librarian!

📁 Enter directories to scan (comma-separated):
> /Volumes/Movies, /Volumes/TV Shows

💾 Output filename [catalog.csv]:
> my-library.csv

🤖 Enable AI fallback for hard-to-identify files? (y/n):
> y

🔍 Scanning directories...
   Found 2000 video files

📽️  Processing files...
✓ [1/2000] The Ballad of Wallis Island (2025)
✓ [2/2000] Afternoons of Solitude (2024)
✗ [3/2000] random_file.mp4

✨ Complete!
   🎬 Movies: 1847
   📺 TV Shows: 142
   ❓ Unidentified: 11

💾 Saved to my-library.csv

How It Works

1. Pattern matching - regex extracts title, year, season/episode from filenames
2. TMDb lookup - verifies and enriches metadata
3. Progressive search - tries shorter title fragments if no match
4. AI fallback (optional) - uses GPT to parse difficult filenames

Supported File Extensions

.mkv, .mp4, .avi, .mov, .m4v, .wmv

CSV Output

| Column | Description | |--------|-------------| | title | Movie/show name | | type | movie or tv | | year | Release year | | director | Director name | | runtime | Minutes | | season | Season number (TV only) | | episode | Episode number (TV only) | | imdb_id | IMDB ID | | imdb_url | Link to IMDB page | | file_path | Full path to file | | duplicate_group | ID linking duplicate files | | status | verified, unverified, unidentified |

Configuration

Config is stored in ~/.movie-librarian/config.json:

{
  "tmdbApiKey": "your-tmdb-api-key",
  "openaiApiKey": "your-openai-api-key"
}

Attribution

This product uses the TMDb API but is not endorsed or certified by TMDb.

License

MIT