subtitle-scout

Subtitle Scout

A self-hosted system with an LLM agent at its core. It finds subtitles for your media library, judges whether each candidate belongs to the exact episode, and installs the one that fits.

以 LLM agent 为核心的自托管系统。替你的媒体库找字幕，逐条判定候选是否属于这一集，装上最适配的那条。

Live demo (read-only) · Website · English · 中文

What it does

For every episode or movie missing a subtitle in your target language, an agent runs a loop instead of a fixed pipeline:

• 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 also checks for embedded tracks that already cover the language.
• 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.
• Scans folders directly. No Plex, Jellyfin, Emby, Sonarr, or Radarr required. Credentials stay in the app's own SQLite on your machine.

Languages: Chinese has the deepest source coverage. English, Japanese, and Korean are fully supported. Spanish, French, German, Portuguese, Russian, and Italian work with basic coverage. Details in Target languages.

Quick start

git clone https://github.com/fancydirty/subtitle-scout && cd subtitle-scout
mkdir -p cache && cp .env.example .env
docker compose up -d

Open http://:8099 and finish the setup wizard. Or let your coding agent do it, see the next section.

Deploy with your AI agent

Subtitle Scout ships an Agent Skill at skills/subtitle-scout-wizard/SKILL.md that walks your coding agent through deployment, configuration, and troubleshooting, end to end.

Option 1 — paste this to your agent (Claude Code, Codex, Gemini CLI, Cursor, or any agent that can fetch URLs and run shell commands):

Fetch https://raw.githubusercontent.com/fancydirty/subtitle-scout/main/skills/subtitle-scout-wizard/SKILL.md and follow it to deploy and configure Subtitle Scout for me. If it references other files, fetch them from the same base path — or clone https://github.com/fancydirty/subtitle-scout and work from skills/subtitle-scout-wizard/.

Option 2 — clone first (offline-friendly; you need the repo to self-host anyway):

Clone https://github.com/fancydirty/subtitle-scout, read skills/subtitle-scout-wizard/SKILL.md, and follow it to deploy and configure Subtitle Scout for me.

Option 3 — install as a skill (harnesses supporting the Agent Skills standard):

npx skills add fancydirty/subtitle-scout

Then tell your agent: "Use the subtitle-scout-wizard skill to deploy Subtitle Scout."

The agent will ask before anything destructive. Review what it proposes — this skill has the same trust model as any install script you run from the internet.

Prefer doing it by hand? The manual path is below.

Quick Start (5 Minutes)

Get subtitle-scout running from zero to dashboard in under 5 minutes.

Prerequisites

• Docker and Docker Compose installed
• A media library directory (NAS, local disk, or any folder with video files)
• Internet connection for API access

Step 1: Get API Keys

Two credentials are required: TMDB (recognizes every file) and an LLM key set (judging and translation). The wizard is only complete once both are in place. Every subtitle source is optional.

Of the seven sources, five take keys and the wizard can skip them all — configure the ones for your language anyway (the wizard and Settings only show sources relevant to your target language). OpenSubtitles and SubDL are international catalogs useful for every target language — don't skip them. ASSRT is the professional Chinese catalog (finished Chinese sidecars); r3sub carries official Traditional Chinese tracks from Taiwan releases (email + password of your r3sub.com account). Jimaku feeds the translation agent with Japanese source subtitles. The remaining two, SubHD and Zimuku, need no keys — they are Chinese-focused sources you enable with a toggle in Settings (off by default; see SECURITY.md for the terms-of-service caveat).

LLM (OpenAI-compatible) is a separate wizard step and is not covered here. One expectation to set now: model tier matters more than any other setting. The agent does long multi-step tool-calling; models below roughly the deepseek-v4-flash / mini tier do not fail loudly — they confidently fabricate, which shows up as misidentified media rather than an error. If matching quality is poor, suspect the model tier before filing a bug. Good value starting points: deepseek-v4-flash (api.deepseek.com), Qwen qwen3.5-plus (Alibaba DashScope), or any current mini/flash-class frontier model. Check current prices on each provider's official pricing page.

Credentials: English · 中文

Required: TMDB API Key (Free)

TMDB powers media file recognition. Without it, subtitle-scout cannot identify your files.

1. Sign up at themoviedb.org
2. Go to Settings (top-right avatar menu) → API
3. Request a Developer key
4. Copy the API key (v3 32-char key or v4 Read Access Token both work)

→ TMDB · 中文

Mainland China note: api.themoviedb.org is blocked in mainland China. Subtitle Scout exposes TMDB_BASE_URL / TMDB_IMAGE_BASE_URL / TMDB_PROXY_URL so you can point it at the still-reachable official legacy domain (https://api.tmdb.org/3) or your own reverse proxy — a ready-to-paste Cloudflare Worker template ships in docs/tmdb-proxy-worker.js. Full walkthrough (Chinese): 大陆网络环境：TMDB 直连不通怎么办.

Strongly recommended: ASSRT Token (Free)

ASSRT is the primary Chinese subtitle source. The wizard lets you skip it; don't, if you want Chinese subs.

1. Register at assrt.net (the homepage does not show Sign up)
2. Log in, then open https://assrt.net/usercp.php (nav: 用户面板)
3. Copy the API token

→ ASSRT · 中文

OpenSubtitles and Jimaku (configure anyway)

OpenSubtitles is an international source for Chinese-speaking and non-Chinese-speaking users alike. Jimaku is not a professional Chinese catalog; it supplies Japanese source subtitles to the translation agent.

• OpenSubtitles: https://www.opensubtitles.com/en/consumers → API consumers → NEW CONSUMER. No VIP. Name: letters and digits only.
• Jimaku (Japanese): https://jimaku.cc/account

→ OpenSubtitles · Jimaku

Step 2: Clone and Configure

# Clone the repository
git clone https://github.com/fancydirty/subtitle-scout.git
cd subtitle-scout

# Create the cache directory (holds the SQLite DB and logs).
# Needed up front on Synology/DSM: its Docker daemon does not auto-create
# bind-mount host paths the way standard Linux Docker does.
mkdir -p cache

# Create environment file
cp .env.example .env

Edit .env — you only need to set the timezone:

TZ=Asia/Shanghai  # or your timezone

Important: API keys are NOT configured in .env. You'll enter them through the web dashboard in Step 4.

Step 3: Start the Container

docker compose up -d

Wait 10-20 seconds for the container to initialize.

If ghcr.io is slow or blocked on your network, pull through a mirror and retag — it serves the same image digest:

docker pull ghcr.1ms.run/fancydirty/subtitle-scout:latest
docker tag ghcr.1ms.run/fancydirty/subtitle-scout:latest ghcr.io/fancydirty/subtitle-scout:latest

Step 4: Complete Setup Wizard

1. Open http://localhost:8099 (or http://:8099 if running on a NAS/server)

2. Create Admin Account — the setup wizard will prompt you to:

   • Set a username and password (minimum 10 characters)
   • This generates an API key for automation (shown once)

3. Configure Credentials — in the Settings page, fill in:

   • TMDB card: paste your TMDB API key
   • ASSRT card: paste your ASSRT token
   • LLM card: enter Base URL, API Key, and Model name (all three from the same provider)

4. Add Media Directories:

   • Go to Settings → Media
   • Click Browse and navigate to your media folder
   • The default Docker setup mounts your host root at /hostroot, so:
     • Host path /mnt/media/Movies → select /hostroot/mnt/media/Movies
     • Host path /Users/yourname/Media → select /hostroot/Users/yourname/Media
   • Click Add to save

Same-filesystem rule for the archive dir: when subtitle-scout reorganizes a media folder (realign), it moves it with atomic rename and deliberately never falls back to copying — no half-moved libraries. If the archive directory (REALIGN_ARCHIVE_ROOT, default: parent of the library root) is on a different filesystem, the move is skipped (abandon) and logged. Synology note: every shared folder is its own btrfs subvolume, so cross-shared-folder moves always fail with EXDEV — keep the archive dir inside the same shared folder as the library it serves.

Step 5: Verify Setup

Run the health check:

docker compose exec subtitle-scout node dist/cli/index.js doctor

You should see green checkmarks (✓) for:

• TMDB API key valid
• ASSRT token valid
• LLM endpoint working (if configured)
• Media roots writable
• Database ready

Step 6: Start Watching

Subtitle-scout automatically scans your media library every 15 minutes. To trigger an immediate scan:

1. Go to the Library tab in the dashboard
2. Click Full Library Reconcile (or wait for the next auto-scan)
3. Watch the Activity page for real-time progress

That's it. Subtitle-scout is now monitoring your library and will fetch subtitles for any media missing them, in whichever target language you set (Chinese by default — see Target languages for what each language actually gets).

What's Next?

• Activity Page (http://localhost:8099/activity) — see what's being processed in real-time
• Notifications — review download history
• Advanced Settings — configure optional sources (OpenSubtitles, hardsub detection, etc.)

For detailed configuration, troubleshooting, and development setup, see the sections below.

让你的 AI agent 替你部署

本仓库自带 Agent Skill： skills/subtitle-scout-wizard/SKILL.md， 可引导你的编码 agent 全程完成部署、配置与排障。

方式一——把这段话粘贴给你的 agent（Claude Code / Codex / Gemini CLI / Cursor，或任何能抓取 URL 并执行命令的 agent）：

抓取 https://raw.githubusercontent.com/fancydirty/subtitle-scout/main/skills/subtitle-scout-wizard/SKILL.md 并按其中指引为我部署并配置 Subtitle Scout。若其中引用了其他文件， 从同一路径前缀抓取，或直接 clone https://github.com/fancydirty/subtitle-scout 后在 `skil