fancydirty / subtitle-scout
A self-hosted subtitle automation system with an LLM agent at its core — it identifies your media, judges whether each candidate belongs to the exact episode, installs the one that fits, and translates when no source has it.
Why this job: works in the areas we cover, but does not say which job it does
What it does
- Picks where to look. Chooses among multiple sources (OpenSubtitles, SubDL, ASSRT, r3sub, Jimaku, SubHD, Zimuku today) and what to search for, based on the filename, TMDB metadata, and what earlier searches returned.
- Reads the results. Right show, right episode, right cut — judged from the actual search output rather than the top hit. Release group and resolution are never a reason to reject a subtitle that otherwise fits.
- Judges what belongs. Each candidate is downloaded into a throwaway sandbox and checked structurally — cue count, whether its timeline span matches the runtime, encoding — and the model rules on whether it belongs to this exact episode. It a
- Installs the one that fits. A wrong subtitle is treated as worse than none, so unmatched episodes stay visibly unmatched. The per-episode grid shows what is installed, pending, or genuinely unavailable.
- Translates when there is no source. Want Chinese and only a Japanese sub exists? A second agent translates sentence by sentence after a glossary pass.
Get started
git clone https://github.com/fancydirty/subtitle-scout && cd subtitle-scout
mkdir -p cache && cp .env.example .env
docker compose up -d You need: Docker and Docker Compose installed; A media library directory (NAS, local disk, or any folder with video files); Internet connection for API access
- Maintenance
- Active
- Last commit 2 months ago
- Stars
- 148
- +1 this week
- Licence
- AGPL-3.0
- Share-alike, even hosted
- Downloads for
- None listed
- No release files
- Latest version
- v1.0.0
- Released 2 months ago
- Built with
- TypeScript
- 92% of the code
Is it looked after?
- Contributors
- 1
- Last 90 days
- Issues
- None
- No issues filed
- Pull requests
- 0 merged
- 0 waiting
- Releases
- 1
- 1 in the last year
- Contributing guide (opens in new tab)
- Security policy (opens in new tab)
- No code of conduct
More: languages, topics and project record
Languages
- TypeScript 92%
- HTML 6%
- CSS 2%
- Shell <1%
Topics
- ai-agent
- chinese-subtitles
- docker
- llm
- opensubtitles
- self-hosted
- subtitle-translation
- subtitles
- tmdb
- typescript
Project record
- JobOther AI tools
- StatusListed
- Commits1,496
- Forks5
- Watching1
- Stars in 28 days+23
- CreatedJul 9, 2026
- First seen by usNov 7, 2026
- CheckedNov 9, 2026