🎬 Movie Librarian

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

Quick Start

$3

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

$3

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

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

$3

``bash
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:

`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