Subtitle Scout

Overview

GitHubGitHub

Subtitle Scout 是一个基于 TypeScript 编写的自托管字幕自动化系统，核心由 LLM agent 驱动。它用于解决本地媒体库中缺失目标语言字幕的问题，通过智能检索、结构校验和按需翻译来补全字幕。 ### 主要能力 - **多源检索**：支持 OpenSubtitles、SubDL、ASSRT、r3sub、Jimaku、SubHD、Zimuku 等多个字幕源，根据文件名、TMDB 元数据及历史搜索结果决定检索策略。 - **候选判定**：将候选字幕下载至沙盒中进行结构检查（如 cue 数量、时间轴跨度与运行时长是否匹配、编码格式），并由模型判断其是否属于当前具体集数。不会仅因发布组或分辨率不匹配而拒绝字幕。 - **精准安装**：遵循「错误字幕不如没有字幕」的原则，未匹配的剧集会保持可见的未匹配状态，按集展示已安装、待处理或不可用的情况。 - **自动翻译**：当目标语言无可用字幕源时，第二个 agent 会在术语表处理后逐句进行翻译。 - **独立扫描**：直接扫描本地文件夹，无需依赖 Plex、Jellyfin、Emby、Sonarr 或 Radarr。凭证存储在本地 SQLite 中。 ### 语言支持 中文拥有最深的源覆盖；英语、日语、韩语获得完整支持；西班牙语、法语、德语、葡萄牙语、俄语、意大利语提供基础覆盖。 ### 部署方式 项目采用 AGPL-3.0 协议开源，要求 Node.js 22 及以上版本，并提供 Docker 镜像。用户可通过 Docker Compose 快速启动，也可利用内置的 Agent Skill 让 AI 编程助手（如 Claude Code、Codex、Gemini CLI、Cursor）协助完成部署与配置。运行前需准备 TMDB API Key 以及兼容 OpenAI 接口的 LLM API Key。

Q&A

运行 Subtitle Scout 需要哪些 API Key？AI-generated

必须提供两个凭证：用于识别媒体文件的 TMDB API Key（免费申请），以及用于判定和翻译的兼容 OpenAI 接口的 LLM API Key。各个字幕源的 API Key 是可选的。

对 LLM 模型有什么要求？AI-generated

模型层级比其他设置更重要。agent 执行长链路的多步工具调用，低于 deepseek-v4-flash 或 mini 级别的模型可能不会报错而是自信地捏造结果，导致媒体识别错误。推荐使用 deepseek-v4-flash、qwen3.5-plus 或同级别的前沿模型。

需要配合 Plex 或 Jellyfin 使用吗？AI-generated

不需要。Subtitle Scout 直接扫描本地文件夹中的视频文件，无需依赖 Plex、Jellyfin、Emby、Sonarr 或 Radarr。

支持哪些语言的字幕？AI-generated

中文拥有最深的源覆盖；英语、日语、韩语获得完整支持；西班牙语、法语、德语、葡萄牙语、俄语、意大利语提供基础覆盖。

中国大陆网络环境可以使用吗？AI-generated

api.themoviedb.org 在中国大陆被屏蔽，但 Subtitle Scout 提供了 TMDB_BASE_URL、TMDB_IMAGE_BASE_URL 和 TMDB_PROXY_URL 环境变量，允许用户将其指向仍可访问的官方地址或代理。

如果找不到目标语言的字幕怎么办？AI-generated

系统会启动第二个 agent，在术语表处理后逐句将其他语言的现有字幕翻译成目标语言。