Skip to content
Back to search

oil-subtitle

SkillWorks with Claude CodeGitHub

为本地 MP4、MOV 等视频转录、校对、预览并烧录准确的中文字幕, 或把审校后的中文字幕翻译成同时间轴的英文 SRT。 用户只要提供成片视频并要求加字幕、修字幕、生成 SRT/ASS、字幕进度条或英文字幕, 就使用本 Skill。不要用它修改 .screenstudio 工程时间线;工程剪辑使用 screen-studio-editor。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oil-oil--oil-subtitle/badge.svg)](/listings/oil-oil--oil-subtitle)

HTML

<a href="/listings/oil-oil--oil-subtitle"><img src="/api/listings/oil-oil--oil-subtitle/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 266 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: oil-subtitle
  3. description: >
  4. 为本地 MP4、MOV 等视频转录、校对、预览并烧录准确的中文字幕,
  5. 或把审校后的中文字幕翻译成同时间轴的英文 SRT。
  6. 用户只要提供成片视频并要求加字幕、修字幕、生成 SRT/ASS、字幕进度条或英文字幕,
  7. 就使用本 Skill。不要用它修改 .screenstudio 工程时间线;工程剪辑使用 screen-studio-editor。
  8. ---
  9. # Oil Subtitle
  10. 只负责已经导出的视频字幕,不修改 Screen Studio 工程。
  11. 脚本负责 ASR、术语表、分行、疑点检测、章节、排版、人脸区域检测和 FFmpeg 烧录。Agent 是字幕正文唯一的语义校对者,负责通读转录稿、结合音频和必要画面修正错词、组织用户预览并检查最终结果。百炼模型不得自动改写字幕正文。
  12. ## API Key 配置入口
  13. 需要外部服务凭据时先读[API Key 配置与业务读取](references/api-key-setup.md):复用已有安全入口;本机缺少 Key 时使用随附固定页面,保存后通过业务包装入口读取。内置能力与纯本地流程不要求配置 Key。
  14. ## 默认行为
  15. - 默认只生成中文字幕。用户明确要求英文字幕时,才从审校后的中文字幕逐条翻译;不把英文翻译混入默认转录和烧录流程。默认使用 DashScope Python SDK 调用百炼 FunAudio ASR;字幕断句和长视频章节由百炼 Qwen 完成,全部共用一个 API Key。旧本地 Whisper 仅用于明确比较或远程服务不可用时的降级。
  16. - ASR 自动应用外部 hotwords 和 glossary;随后由 Agent 通读整份转录稿并补充高置信错误。`review_subtitles.py` 只复制原文和生成疑点清单,自动改词数必须为 0。
  17. - 型号、版本号、命令、文件名和界面文字需要结合口播上下文核对。画面中的项目名、窗口标题或侧边栏背景文字只有与口播属于同一指代时才能作为证据;看不清或无法确认时保留原文,交给用户预览。
  18. - 用户在预览页保存字幕时,脚本只比较修改前后内容并生成待 Agent 审阅的 `manual-edit-review.json`,不得调用模型或自动写入 glossary。Agent 只把稳定、可复用且上下文安全的 ASR 映射写入个人 glossary;润色、删句、标点和一次性改写一律忽略。
  19. - 字幕默认不显示标点;人工审阅过的 SRT 通过 `--srt-input` 直烧时保持文本、换行和时间码不变。
  20. - 清理标点必须保留数字之间的小数点,包括评测分数和模型版本号。交付前同时核对审校稿、准备后的字幕和最终 SRT 中的关键数字,不能只检查 ASR 校对副本。
  21. - 正常中文字幕默认在中文与英文或数字的边界补一个半角空格,例如 `使用Claude Code做AI实战` 显示为 `使用 Claude Code 做 AI 实战`。该规则在准备阶段统一写入预览字幕,并在烧录阶段幂等复用;用户不需要手工逐条加空格,纯空格变化也不进入错题本。
  22. - 章节进度功能默认开启。视频严格超过三分钟时,在视频画面底部用半透明渐变阴影承载宽粒度章节进度;不增加实色画布,也不把每个小点拆成章节。
  23. - 用户只要用自然语言说“关闭章节进度条”或同义表达,本次任务就在准备和烧录命令中都传 `--no-progress`,不生成章节,也不显示进度条;用户说“开启章节进度条”时传 `--progress`。这是单次任务开关,不要求用户修改配置文件。
  24. - 正常烧录会识别持续出现的人脸区域并执行固定轻度美颜;用户要求保持原画时传 `--no-beauty`。
  25. - 不覆盖已有 MP4、SRT 或 ASS。目标存在时使用新文件名,除非用户明确同意覆盖。
  26. ## 初始化
  27. ```bash
  28. SKILL_DIR="<oil-subtitle 的绝对目录>"
  29. PYTHON="$SKILL_DIR/.venv/bin/python3"
  30. CONFIG="${OIL_SUBTITLE_CONFIG:-$HOME/.config/oil-subtitle/config.json}"
  31. ```
  32. 首次使用时运行:
  33. ```bash
  34. bash "$SKILL_DIR/setup.sh"
  35. node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" status default
  36. # 仅缺少凭据或用户要求更换时执行:
  37. node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" setup default
  38. ```
  39. API Key 优先读取运行时环境变量,然后读取系统凭据库;旧密钥文件和百炼配置只有设置 `OIL_SUBTITLE_ALLOW_LEGACY_PLAINTEXT=1` 时才兼容读取。默认使用随附本机配置页;页面保存后,云端转录、断句、章节和翻译程序经 run 入口读取,普通 JSON 只保存引用。`configure_api_key.py` 只负责启动或检查配置页,不接受密钥、不自动迁移。系统后端不可用则报告失败,不退回明文存储。首次执行 `setup.sh` 前说明它会安装 Python 和 Node 依赖,缺少 FFmpeg 时还会尝试通过 Homebrew 安装。
  40. 可选配置:
  41. ```json
  42. {
  43. "video_library_root": "/optional/path/to/video-library",
  44. "hotwords": "/optional/path/to/hotwords.json",
  45. "glossary": "/optional/custom/path/to/glossary.json",
  46. "vocabulary_cache": "/optional/path/to/vocabulary-cache.json",
  47. "subtitles": {
  48. "progress_enabled": true,
  49. "progress_min_duration_seconds": 180
  50. }
  51. }
  52. ```
  53. 新配置优先使用 `OIL_SUBTITLE_CONFIG`。为兼容迁移,脚本在新配置不存在时仍会读取 `SCREEN_STUDIO_EDITOR_CONFIG` 及旧环境变量。不要把用户配置、API Key、个人术语表或绝对路径提交进 Skill。
  54. 个人 glossary 默认位于 `~/.config/oil-subtitle/glossary.json`。只有需要换位置时才配置 `glossary`;转录、预览学习和烧录始终解析同一个路径。
  55. ## 工作流
  56. 先核对当前视频目录已有产物和本任务已经给出的确认。源视频及本阶段输入、选项未变时,从缺失阶段继续,不覆盖审校稿。同名文件不足以证明同一来源,应核对原任务记录的路径、大小、修改时间和可用指纹。
  57. 已有用户定稿时只修改需要修正的位置,沿用本次章节、美颜和输出规格;只需发布或改封面时,直接交接已验证的字幕成片。
  58. 只需要英文 SRT 时直接进入「英文 SRT 分支」;没有审校中文源时仅补齐转录、校对和 SRT 草稿,不执行章节准备。
  59. ### 1. 确定视频和工作目录
  60. 如果配置了 `video_library_root`,先把视频放到 `<video_library_root>/<视频标题>/`;否则保留在源视频旁边。不要覆盖同名文件。
  61. ```bash
  62. VIDEO="/path/to/video.mp4"
  63. VIDEO_DIR="$(dirname "$VIDEO")"
  64. VIDEO_NAME="$(basename "$VIDEO")"
  65. VIDEO_STEM="${VIDEO_NAME%.*}"
  66. WORK="$VIDEO_DIR/$VIDEO_STEM.subtitle-work"
  67. mkdir -p "$WORK"
  68. ```
  69. ### 2. 转录
  70. 只有没有可用转录,或源视频的内容/时间线已经改变时才转录。仅修错字、调整章节、修改封面或恢复发布,不重跑 ASR。
  71. 默认路径:
  72. ```bash
  73. node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" run default -- "$PYTHON" "$SKILL_DIR/scripts/bailian_transcribe.py" \
  74. "$VIDEO" \
  75. --output "$WORK/transcript.json" \
  76. --raw-output "$WORK/bailian_asr.json" \
  77. --language zh
  78. ```
  79. 脚本会保留原始 ASR、自动应用术语表并完成字幕级分行。只有剪辑分析才使用 `--split-mode raw`,不要把 raw 转录稿直接用于预览或烧录。
  80. 用户明确要求本地转录或百炼不可用时:
  81. ```bash
  82. ffmpeg -i "$VIDEO" -ar 16000 -ac 1 "$WORK/audio.wav" -y
  83. "$PYTHON" "$SKILL_DIR/scripts/local_transcribe.py" \
  84. --audio "$WORK/audio.wav" \
  85. --output "$WORK/transcript.json" \
  86. --language zh
  87. ```
  88. ### 3. Agent 校对转录稿
  89. 先生成不改词的校对副本和技术疑点清单:
  90. ```bash
  91. "$PYTHON" "$SKILL_DIR/scripts/review_subtitles.py" \
  92. --video "$VIDEO" \
  93. --transcript "$WORK/transcript.json" \
  94. --output "$WORK/reviewed-transcript.json" \
  95. --report "$WORK/subtitle-review.json" \
  96. --frames-dir "$WORK/review-frames"
  97. ```
  98. 脚本必须把 `transcript.json` 的字幕文字原样复制到 `reviewed-transcript.json`,并在 `subtitle-review.json` 中写入 `mode=agent-only` 和 `automatic_text_changes=0`。任何模型自动改词都属于流程失败。
  99. Agent 随后通读 `reviewed-transcript.json` 的全部 segment;`candidates` 只是技术词聚焦清单,不能代替全文检查。结合相邻字幕、音频和必要的视频帧确认后,只修改 segment 的 `text`:
  100. - 明确的产品名、专有名词和大小写错误;
  101. - 从上下文、音频或画面能够确认的 ASR 错误;
  102. - 新出现、尚未被 glossary 覆盖的重复误识别。
  103. 禁止修改 word 级 token;它们只用于时间定位,不得覆盖已经确认的 segment 文本。画面证据必须与口播属于同一指代,不能把背景项目名直接写进字幕。无法确认的项保留原文,交给用户预览。
  104. ### 4. 准备字幕和章节
  105. ```bash
  106. node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" run default -- "$PYTHON" "$SKILL_DIR/scripts/prepare_subtitles.py" \
  107. --transcript "$WORK/reviewed-transcript.json" \
  108. --video "$VIDEO" \
  109. --output "$WORK/subtitle-transcript.json" \
  110. --chapters-output "$WORK/subtitle-chapters.json" \
  111. --manifest-output "$WORK/subtitle-manifest.json" \
  112. --work-dir "$WORK/cache" \
  113. --resume
  114. ```
  115. 章节进度默认开启。用户要求本次关闭时,在以上命令追加 `--no-progress`;用户明确要求开启时追加 `--progress`。即使用户关闭进度条,也继续正常准备、预览和烧录中文字幕。
  116. 检查准备后的字幕和章节。三到五分钟的视频通常保留 2–4 个章节,更长视频通常保留 4–6 个,每个标题简短且对应主要内容阶段。章节长度与其时间占比对应的显示宽度一起检查,尤其是末尾短章节;全片烧录前先生成 ASS 并抽帧确认最长字幕和所有章节标签完整可见,超宽时缩短章节标题后再开始正式编码。
  117. ### 英文 SRT 分支
  118. 用户要求英文字幕,尤其说明“只需要字幕文件”时,优先使用已经审校完成的中文 SRT,不重新转录视频。没有中文 SRT 时,先完成转录和 Agent 校对,再生成中文 SRT 作为翻译源。
  119. - 只翻译每个字幕块的正文;编号、时间码、字幕块数量和顺序必须与中文源文件完全一致,不合并或拆分字幕块。
  120. - 按原文忠实翻译,不额外套用文风、营销表达或内容改写;保留第一人称、事实范围、产品名、缩写和语气强度。
  121. - 输出到视频旁的 `${VIDEO_STEM}_en.srt`。目标已存在时使用新文件名,除非用户明确同意覆盖。
  122. - 用户只要英文字幕文件时,到此停止;不生成 ASS、不烧录视频、不生成章节,也不启动预览服务。
  123. - 交付前逐块检查编号和时间码与中文源文件一致、英文正文非空,并确认没有未翻译的中文正文。专有名词确实需要保留中文时单独说明。
  124. ### 5. 用户预览
  125. 用户已经要求“直接烧录”“不用审核”,或上层工作流已明确获得本次免预览授权时,完成 Agent 全文校对和 SRT 检查后直接继续,不启动预览服务、不再次确认。否则按以下方式预览。
  126. 先检查当前任务已有预览服务,身份和内容匹配时复用。不要杀死占用端口的未知进程,改用空闲端口。使用宿主提供的持久进程运行器;macOS/Linux 也可用以下方式脱离命令会话启动,关闭标准输入并将日志写到工作目录:
  127. ```bash
  128. PREVIEW_EDITOR_PORT=8765 "$PYTHON" - "$SKILL_DIR" "$WORK" <<'PY'
  129. import pathlib, subprocess, sys
  130. skill, work = (pathlib.Path(p).resolve() for p in sys.argv[1:])
  131. with (work / "preview-editor.log").open("a") as log:
  132. process = subprocess.Popen(
  133. [sys.executable, str(skill / "scripts/preview_editor.py"),
  134. str(work / "subtitle-manifest.json")],
  135. stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True,
  136. )
  137. (work / "preview-editor.pid").write_text(str(process.pid), encoding="utf-8")
  138. print(process.pid)
  139. PY
  140. ```
  141. 启动返回后,用另一次调用检查进程和 HTTP;核对 `/manifest` 的视频、字幕路径,以及 `/api/transcript` 的首句和条目数量,才提供实际端口的地址。失败时检查日志,不重复发送未经验证的 URL。除非用户明确要求,不调用浏览器自动化。
  142. 告诉用户:
  143. > 已准备好字幕预览,请检查文字和时间是否准确。可以双击修改、取消勾选删除,确认后点击「保存并关闭」。保存会记录修改,随后由 Agent 判断哪些稳定错词适合加入个人错题本。
  144. 等用户明确确认,或取得当前预览会话成功保存的证据后继续;文件已存在不等于用户已保存。记录预览开始时的文件状态,结合保存响应/修改报告核对,不能把 Agent 准备文件的写入当成人工确认。
  145. ### 6. 审阅人工修改并维护 glossary
  146. 预览页保存中文源字幕时会自动执行 `scripts/learn_glossary.py`,但脚本只生成报告:
  147. 1. 比较 `subtitle-transcript.json.orig.json` 和保存后的字幕,记录每一处人工修改;
  148. 2. 本地规则先排除删句、纯新增、标点空格和整句大改;
  149. 3. 其余修改写入 `pending`,不调用模型,也不修改 glossary;
  150. 4. Agent 结合原句、修改后文本和上下文判断是否为稳定、可复用的 ASR 错词;
  151. 5. 只有安全映射才由 Agent 显式写入个人 glossary,冲突规则不得覆盖;
  152. 6. 润色、语气调整和一次性改写保持忽略。
  153. 保存后先检查 `manual-edit-review.json`,不要在审阅前重启编辑器,否则启动流程会覆盖修改前的副本。如果 `status=error` 或文件缺失,先用同一脚本重试:
  154. ```bash
  155. "$PYTHON" "$SKILL_DIR/scripts/learn_glossary.py" \
  156. --before "$WORK/subtitle-transcript.json.orig.json" \
  157. --after "$WORK/subtitle-transcript.json" \
  158. --report "$WORK/manual-edit-review.json"
  159. ```
  160. 不要把一次性改写、删除、语气调整或标点变化塞进 glossary。已有同一错词但正确词不同则记录冲突,不自动覆盖。
  161. ### 7. 草稿检查和烧录
  162. 先生成 SRT 草稿:
  163. ```bash
  164. "$PYTHON" "$SKILL_DIR/scripts/burn_subtitles.py" \
  165. --video "$VIDEO" \
  166. --transcript "$WORK/subtitle-transcript.json" \
  167. --chapters "$WORK/subtitle-chapters.json" \
  168. --draft-output "$VIDEO_DIR/${VIDEO_STEM}_subtitled.srt" \
  169. --draft-only
  170. ```
  171. 检查产品名、断句、落单语气词、可见标点和时间。确认输出 MP4 不存在后,一次完成 ASS 生成和烧录:
  172. ```bash
  173. "$PYTHON" "$SKILL_DIR/scripts/burn_subtitles.py" \
  174. --video "$VIDEO" \
  175. --transcript "$WORK/subtitle-transcript.json" \
  176. --chapters "$WORK/subtitle-chapters.json" \
  177. --output "$VIDEO_DIR/${VIDEO_STEM}_subtitled.mp4"
  178. ```
  179. 脚本默认拒绝覆盖已有 MP4、ASS 或草稿 SRT。只有用户明确同意覆盖时,才在确认目标路径后追加 `--overwrite`;不要把这个参数作为默认模板。
  180. 用户要求关闭章节进度条时,烧录命令也必须追加 `--no-progress`,避免已有章节文件被误用。
  181. 如果用户直接审阅了 SRT,按原样烧录:
  182. ```bash
  183. "$PYTHON" "$SKILL_DIR/scripts/burn_subtitles.py" \
  184. --video "$VIDEO" \
  185. --srt-input "/path/to/reviewed.srt" \
  186. --output "$VIDEO_DIR/${VIDEO_STEM}_subtitled.mp4"
  187. ```
  188. ### 8. 验证和交付
  189. 检查:
  190. - 输出文件可播放,时长与源视频一致;
  191. - 开头、中段、结尾字幕与声音同步;
  192. - 字幕没有遮挡持续出现的人脸区域;
  193. - 章节标题在各自时间段内保持稳定;
  194. - 是否启用美颜、输出路径与用户要求一致。
  195. 报告最终视频、SRT、ASS 和工作目录路径,并说明需要用户重点预览的位置。修订成片时,新版通过验证后再更新后续发布包的引用,不能让发布阶段继续使用旧视频。
README.md · README · 201 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # oil-subtitle
  2. <p align="center">
  3. <img src="./assets/readme/hero.svg" width="100%" alt="oil-subtitle 将本地视频转换为可校对并烧录的中文字幕">
  4. </p>
  5. 为本地视频转录、校对、预览并烧录中文字幕,支持章节进度和同时间轴英文字幕。
  6. 也可以将审校后的中文字幕翻译成英文 SRT,保留原有时间轴。明确只要英文字幕文件时,不启动预览、生成章节或烧录视频。
  7. [快速开始](#快速开始) · [工作流程](#工作流程) · [维护词库](#维护-hotwords-与-glossary) · [数据边界](#数据边界)
  8. ## 效果预览
  9. <p align="center">
  10. <img src="./assets/readme/subtitle-editor.png" width="100%" alt="oil-subtitle 本地字幕编辑器:左侧预览字幕与章节进度,右侧逐句校对">
  11. </p>
  12. 左侧实时预览字幕和章节进度,右侧逐句修改、删除或批量查找替换,确认后点击「保存并关闭」即可继续烧录。中文与英文或数字之间默认补一个半角空格,预览、SRT/ASS 和最终成片使用同一规则。
  13. 保存时会自动比较人工修改并生成待审报告,但不会调用模型或自动写入个人错题本。Agent 只把稳定、安全且不冲突的 ASR 映射写入词库;润色、删句和标点修改不会污染词库。
  14. ## 最终会得到什么
  15. 一次完整处理会保留可追溯的中间结果,并交付可继续修改的字幕文件和成片:
  16. ```text
  17. demo.subtitle-work/
  18. ├── bailian_asr.json # 原始 ASR 响应
  19. ├── transcript.json # ASR、术语校正并分行后的转录稿
  20. ├── reviewed-transcript.json # 等待 Agent 校对的转录稿副本
  21. ├── subtitle-review.json # 技术词聚焦清单与校对模式记录
  22. ├── review-frames/ # Agent 按需抽取的验证帧
  23. ├── subtitle-transcript.json # 人工预览后保存的字幕
  24. ├── manual-edit-review.json # 人工修改的待审与忽略记录
  25. ├── subtitle-chapters.json # 长视频章节
  26. └── subtitle-manifest.json # 本地预览入口
  27. demo_subtitled.srt
  28. demo_subtitled.ass
  29. demo_subtitled.mp4
  30. ```
  31. ## 工作流程
  32. 1. 用 FFmpeg 从本地视频提取单声道音频。
  33. 2. 通过 DashScope Python SDK 调用百炼 FunAudio ASR,保留原始识别结果和词级时间戳。
  34. 3. 在识别阶段应用 hotwords,再用 glossary 修正常见误识别。
  35. 4. 脚本原样复制转录稿并生成技术词聚焦清单;Agent 通读全部字幕,结合上下文、音频和必要画面修正错词。百炼模型不自动修改字幕正文。
  36. 5. 用 Qwen 完成字幕级断句;章节进度默认开启,视频严格超过 3 分钟时,同时根据字幕生成 2–6 个宽粒度章节,并在视频画面底部以半透明渐变阴影展示进度。
  37. 6. 启动本地字幕编辑器,由用户检查 Agent 校对结果,并按需修改或删除字幕。
  38. 7. 保存时自动提取人工修改并生成待审报告;Agent 判断是否需要显式加入个人 glossary,脚本不会自动写入。
  39. 8. 生成 SRT、ASS,并用 FFmpeg 一次烧录成片。
  40. 正常烧录还会检测持续出现的人脸区域并执行固定轻度美颜;需要保留原画时使用 `--no-beauty`。
  41. ## 快速开始
  42. 运行环境:macOS、Python 3、Homebrew。`setup.sh` 会准备独立虚拟环境,并在缺少 FFmpeg 时通过 Homebrew 安装。
  43. ```bash
  44. SKILL_DIR="/absolute/path/to/oil-subtitle"
  45. bash "$SKILL_DIR/setup.sh"
  46. node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" status default
  47. # 缺少凭据时,由用户在页面亲自填写:
  48. node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" setup default
  49. ```
  50. 配置完成后,把视频路径和目标告诉 Agent:
  51. ```text
  52. 给 /path/to/demo.mp4 加中文字幕,先让我校对,再烧录成片。
  53. ```
  54. Agent 的完整执行规范见 [SKILL.md](SKILL.md)。
  55. 不想显示章节进度条时,直接告诉 Agent“这次关闭章节进度条”即可;Agent 会跳过章节生成并在烧录时关闭进度条,不需要手动修改配置。需要重新开启时说“开启章节进度条”。
  56. ## API Key 只需配置一次
  57. FunAudio ASR、Qwen 字幕断句、章节生成和 hotwords 共用同一个百炼 API Key,全部通过 DashScope Python SDK 调用,业务程序不需要额外 CLI;本机配置页需要 Node.js 22.18+。
  58. 新凭据保存在系统凭据库,普通配置 `~/.config/oil-subtitle/config.json` 只保存引用。默认在本机配置页亲自填写,再按配置说明通过 run 入口运行业务;不要把密钥发到聊天。读取顺序为运行时 `DASHSCOPE_API_KEY`、系统凭据;旧密钥文件和旧百炼配置只有设置 `OIL_SUBTITLE_ALLOW_LEGACY_PLAINTEXT=1` 时才读取。
  59. 安装脚本不会自动迁移凭据,`configure_api_key.py` 也不会接受密钥或执行迁移。系统凭据库不可用时直接失败,不改用明文文件。
  60. ## 维护 hotwords 与 glossary
  61. 词库全部使用普通 JSON 文件,放在用户自己的配置目录,不必修改 Skill 代码,也不要把个人词库或 API Key 提交进仓库。个人 glossary 默认保存在 `~/.config/oil-subtitle/glossary.json`;只有希望换位置时才需要在配置中填写 `glossary`。
  62. `hotwords.json` 在 ASR 识别阶段提高产品名、英文缩写和人名的命中率:
  63. ```json
  64. [
  65. { "text": "Claude Code", "weight": 4, "lang": "en" },
  66. { "text": "百炼", "weight": 4, "lang": "zh" }
  67. ]
  68. ```
  69. `glossary.json` 在识别完成后执行确定性替换,适合修正已经反复出现的错字:
  70. ```json
  71. [
  72. { "wrong": "Claude Core", "correct": "Claude Code" },
  73. { "wrong": "白练", "correct": "百炼" }
  74. ]
  75. ```
  76. 在 `~/.config/oil-subtitle/config.json` 中指向这两个文件:
  77. ```json
  78. {
  79. "hotwords": "~/.config/oil-subtitle/hotwords.json",
  80. "glossary": "~/.config/oil-subtitle/glossary.json",
  81. "subtitles": {
  82. "progress_enabled": true,
  83. "progress_min_duration_seconds": 180
  84. }
  85. }
  86. ```
  87. 预览页保存后,脚本会固定比较修改前后的字幕,把可能复用的错词映射记录到 `manual-edit-review.json` 的 `pending`,但不会调用模型或自动追加 glossary。Agent 只在映射来自原句连续子串、保留必要上下文且不与已有规则冲突时显式写入;一次性改写、删句和标点调整保持忽略。hotwords 内容变化后,脚本会自动更新远程词表缓存。
  88. ## 手动运行
  89. 如果不通过 Agent,也可以直接执行各阶段脚本。下面是主流程中的核心命令:
  90. ```bash
  91. SKILL_DIR="/absolute/path/to/oil-subtitle"
  92. VIDEO="/path/to/demo.mp4"
  93. WORK="/path/to/demo.subtitle-work"
  94. mkdir -p "$WORK"
  95. RUN_CLOUD=(node "$SKILL_DIR/scripts/credential-ui/src/profile.ts" run default --)
  96. "${RUN_CLOUD[@]}" "$SKILL_DIR/.venv/bin/python3" "$SKILL_DIR/scripts/bailian_transcribe.py" \
  97. "$VIDEO" \
  98. --output "$WORK/transcript.json" \
  99. --raw-output "$WORK/bailian_asr.json" \
  100. --language zh
  101. "$SKILL_DIR/.venv/bin/python3" "$SKILL_DIR/scripts/review_subtitles.py" \
  102. --video "$VIDEO" \
  103. --transcript "$WORK/transcript.json" \
  104. --output "$WORK/reviewed-transcript.json" \
  105. --report "$WORK/subtitle-review.json" \
  106. --frames-dir "$WORK/review-frames"
  107. "${RUN_CLOUD[@]}" "$SKILL_DIR/.venv/bin/python3" "$SKILL_DIR/scripts/prepare_subtitles.py" \
  108. --transcript "$WORK/reviewed-transcript.json" \
  109. --video "$VIDEO" \
  110. --output "$WORK/subtitle-transcript.json" \
  111. --chapters-output "$WORK/subtitle-chapters.json" \
  112. --manifest-output "$WORK/subtitle-manifest.json" \
  113. --work-dir "$WORK/cache" \
  114. --resume
  115. ```
  116. 预览、草稿检查和最终烧录命令见 [SKILL.md](SKILL.md)。
  117. ## 适用边界
  118. - 只处理已经导出的本地视频,不修改 `.screenstudio` 工程时间线。
  119. - 默认远程转录;本地 Whisper 只作为明确指定的降级或对比路径。
  120. - 默认只生成中文字幕,不生成双语字幕。
  121. - 章节进度默认开启,但只在视频严格超过 3 分钟时显示;可直接让 Agent 为当前任务关闭。
  122. - 预览服务只在本机启动;端口默认是 `8765`。
  123. ## 数据边界
  124. - 远程转录会把从视频提取的音频上传到百炼临时存储。
  125. - 字幕断句和章节生成会把对应的字幕文本发送给百炼 Qwen。
  126. - 用户保存预览修改后,修改前后的相关字幕只在本机生成待审报告,不发送给百炼 Qwen。
  127. - API Key、个人配置和词库保存在用户目录,不应进入仓库。
  128. - 预览界面、人工编辑、判断报告、个人词库写入、SRT/ASS 生成和 FFmpeg 烧录都在本机完成。
  129. ## 脚本索引
  130. | 脚本 | 作用 |
  131. | --- | --- |
  132. | `scripts/credential-ui/src/profile.ts` | 默认配置页面、状态检查与业务凭据注入 |
  133. | `scripts/configure_api_key.py` | 启动或检查随附的系统凭据页 |
  134. | `scripts/bailian_transcribe.py` | FunAudio ASR、hotwords、glossary 和字幕分行 |
  135. | `scripts/review_subtitles.py` | 原样复制转录稿并生成 Agent 技术词聚焦清单,不自动改词 |
  136. | `scripts/local_transcribe.py` | 本地 Whisper 降级转录 |
  137. | `scripts/prepare_subtitles.py` | 准备中文字幕、章节和预览 manifest |
  138. | `scripts/preview_editor.py` | 启动本地字幕预览编辑器 |
  139. | `scripts/learn_glossary.py` | 从人工修改中生成待 Agent 审阅的错词报告,不自动写词库 |
  140. | `scripts/burn_subtitles.py` | 生成 SRT/ASS 并烧录 MP4;默认拒绝覆盖 |
  141. ## 测试
  142. ```bash
  143. ./.venv/bin/python3 -m unittest discover -s tests
  144. ```
  145. ## API Key 配置页面
  146. 首次使用外部服务时,可以在本机配置页亲自填写 Key;已有配置会复用,密钥存入系统凭据库。只为实际使用的外部服务配置;纯本地处理不需要 Key。页面需要 Node.js 22.18+ 与可用的系统凭据服务,业务运行仍使用原依赖。
  147. 安装、状态检查、打开页面和带凭据运行的完整入口见[配置说明](references/api-key-setup.md)。页面保存与业务读取已经接通;不把 Key 发进聊天,也不自动迁移旧文件。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.