A local AI-powered service that identifies and renames unlabeled TV episodes from their subtitle files.
For each video/subtitle file:
- Extract the English subtitle track from MKV (via
mkvextract), or read an.srtdirectly - Summarize the subtitle text with a local LM Studio chat model
- Embed the summary and every TMDB episode overview for the season (local embedding model)
- Rank episodes by cosine similarity and take the top 6 candidates
- Clef (local decision model) picks the best match among the candidates, with a confidence score
- Jev (OpenRouter) arbitrates when clef is unsure; very unsure escalates to a full-season jev pick
Batch runs group files into per-season runs. Each file is only ever compared against episodes from its own season, which is what drives accuracy.
- Docker
- LM Studio running locally with three models loaded:
- a chat model for summaries (default
google/gemma-4-e4b) - an embedding model (default
text-embedding-nomic-embed-text-v1.5) - the clef decision model (default
cloudflare_clef-flash)
- a chat model for summaries (default
- TMDB Read Access Token (https://www.themoviedb.org/settings/api)
- OpenRouter API key (for jev arbitration)
-
Copy the environment file and fill in your keys:
cp .env.example .env
-
Build and start:
docker compose up -d
-
Health check:
curl http://localhost:8000/health
All interaction is over the REST API (e.g. with curl).
/detect requires an explicit season:
curl -X POST http://localhost:8000/detect \
-H "Content-Type: application/json" \
-d '{
"show_name": "The Office",
"season": 1,
"subtitle_path": "/data/The.Office.S01E01.mkv",
"rename": true
}'Omit season to auto-detect each file's season from the SxxEyy in its filename — files are grouped into per-season runs. Files with no recognizable season are skipped.
curl -X POST http://localhost:8000/batch \
-H "Content-Type: application/json" \
-d '{
"show_name": "The Office",
"folder_path": "/data/the-office",
"dry_run": true
}'Set "dry_run": false (and "rename": true, the default) to actually rename.
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Service + key configuration status |
GET |
/models |
List models loaded in LM Studio |
POST |
/detect |
Detect a single file (season required) |
POST |
/batch |
Process a folder, grouped per season |
Set in .env (loaded by docker compose):
| Variable | Default | Description |
|---|---|---|
TMDB_READ_ACCESS_TOKEN |
(required) | TMDB v3 read access token |
OPENROUTER_API_KEY |
(required) | OpenRouter key for jev arbitration |
LM_STUDIO_URL |
http://host.docker.internal:1234 |
LM Studio base URL |
SUMMARY_MODEL |
google/gemma-4-e4b |
LM Studio chat model for summaries |
EMBEDDING_MODEL |
text-embedding-nomic-embed-text-v1.5 |
LM Studio embedding model |
CLEF_MODEL |
cloudflare_clef-flash |
Local decision model |
JEV_MODEL |
typesafe/jev-router |
OpenRouter arbitration model |
CONFIDENCE_THRESHOLD |
0.85 |
Min clef confidence to auto-rename |
TMDB_CACHE_DIR |
/data/.tmdb_cache |
Episode metadata cache location |
DATA_DIR |
./data |
Media files volume mount (host side) |
OUTPUT_DIR |
./output |
Optional output folder for renamed files |
The matching thresholds (top-6 candidates, jev escalation below 0.85 confidence or <0.15 margin, full-season jev below 0.30) are constructor defaults in detector.py and not currently env-configurable.
Each detection returns the match plus pipeline diagnostics:
matched_episode/confidence— the match and clef's confidenceaction—auto_renamed,needs_confirmation,skipped,dry_run, or anerror:/no_english_subtitlereasonclef_choice— local model's pickescalated— whether jev was calledjev_choice/jev_reason— arbitration resultsummary— the generated plot summarynew_filename/renamed_path— when renaming occurred (or would, in dry-run)
| Condition | Outcome |
|---|---|
clef confidence ≥ CONFIDENCE_THRESHOLD (0.85) |
Clef's pick, auto-rename |
| clef confidence < 0.85, or top-2 margin < 0.15 | Jev arbitration among the top 6 |
| clef confidence < 0.30 | Jev picks from the full season |
jev returns NONE / unparseable |
Falls back to clef's pick |
| Final confidence below threshold | needs_confirmation (not renamed) |
| No English subtitle / no match | skipped |
docker compose down