SkillFoxx

oil-subtitle skill

A skill that transcribes video, lets you review captions in a browser and burns in Chinese and English captions.

  • 127 ★ on the repository
  • Last commit
Skill

Extended access

Why this level

  • Video audio is sent to the Bailian cloud service.
  • The API key is held in the system credential store and scripts can read it.
All reasons and checks

oil-oil/oil-subtitleAuthor:oil-oil

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/oil-subtitle

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • Video audio is sent to the Bailian cloud service.
  • The API key is held in the system credential store and scripts can read it.

This is third-party code. Review the repository files before installing.

What it does

oil-subtitle takes a local video and brings it to a clip with captions. FFmpeg extracts the audio, Python calls Bailian FunAudio ASR through the DashScope SDK, then term hints and a replacement glossary apply. The agent reads the whole text in context and fixes mistakes, the Qwen model splits it into lines and, for long videos, makes 2–6 chapters and a progress bar. Before burning, a local editor opens: preview on the left, editing, deletion and global replace on the right. The outputs are SRT and ASS files and a finished MP4. Chinese captions can be translated to English with the same timing, and when only an English file is requested the preview and burning are skipped.

Who it is for. Authors of Chinese-language videos who want accurate captions quickly and want to review them before burning.

Good fit when

  • A lecture or review in Chinese needs captions and chapters through the clip.
  • Captions must be checked by eye in an editor before burning into the MP4.
  • English captions with the same timing are needed alongside Chinese ones.
  • Terms in the video are often misrecognized and a replacement glossary is needed.

Not a fit when

  • You need work without a cloud recognition service.
  • The video is in Russian or other languages without Chinese.
  • Faces in frame must not be retouched under any circumstances.

Example request

Add Chinese captions to /path/to/demo.mp4, let me review them in the editor first, then burn them into the video.

Limitations

The scripts target macOS with Python 3 and Homebrew, and FFmpeg installs through `setup.sh`. A Bailian API key is required, and one account serves recognition, line splitting, chapters and hints. The key is saved in the system credential store, and the setup page opens locally and needs Node.js 22.18 or newer. Burning applies a light face retouch by default, which the `--no-beauty` flag turns off. The repository states no license and the last commit dates from September 2026.

How to disable. Delete the skill folder and the `~/.config/oil-subtitle` configuration, and remove the Bailian key from the system credential store.

FAQ

Which files will I get?

SRT and ASS caption files and an MP4 with burned text, plus a work folder with intermediate JSON so the result can be refined.

Where does the video audio go?

Recognition runs through the Alibaba Bailian cloud service, so audio goes to its servers.

How do I disable chapters?

Tell the agent to switch off the chapter bar for this run and it skips chapter generation.

Can I skip face retouching?

Yes, use the `--no-beauty` flag when burning.

Where is the key stored?

In the system credential store, and `~/.config/oil-subtitle/config.json` holds only a reference to it.

Discussion

No questions or reviews yet.

Skills

A Codex and Claude Code skill: subtitles and a summary from a Douyin, Xiaohongshu, Bilibili or YouTube link or a local file

SkillExtended access256

An agent edits short talking-head videos: transcript, subtitles, B-roll and export for Xiaohongshu, Douyin and WeChat Channels

SkillExtended access209

A Claude Code skill that downloads a YouTube video, splits it into semantic chapters, cuts chosen clips, translates subtitles and burns bilingual ones in

SkillExtended access2.3K

Skill that turns a video into tall subtitle collages: crops burned-in subtitles or draws reviewed lines onto real frames

SkillBroad access2.9K

VideoCaptioner transcribes speech, translates subtitles and burns them into video with a single command from Claude Code.

SkillExtended access16.5K

video-production-skill takes an agent from script to video: slides, speech-verified narration, subtitles and a cover.

SkillExtended access106

README in short

The description lists the output files, eight processing steps, a quick start and the Bailian key setup. The editor lets you check the result, and saved edits go into a review report.

README badge

Original SKILL.md

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

# Oil Subtitle

只负责已经导出的视频字幕，不修改 Screen Studio 工程。

脚本负责 ASR、术语表、分行、疑点检测、章节、排版、人脸区域检测和 FFmpeg 烧录。Agent 是字幕正文唯一的语义校对者，负责通读转录稿、结合音频和必要画面修正错词、组织用户预览并检查最终结果。百炼模型不得自动改写字幕正文。

## API Key 配置入口

需要外部服务凭据时先读[API Key 配置与业务读取](references/api-key-setup.md)：复用已有安全入口；本机缺少 Key 时使用随附固定页面，保存后通过业务包装入口读取。内置能力与纯本地流程不要求配置 Key。

## 默认行为

- 默认只生成中文字幕。用户明确要求英文字幕时，才从审校后的中文字幕逐条翻译；不把英文翻译混入默认转录和烧录流程。默认使用 DashScope Python SDK 调用百炼 FunAudio ASR；字幕断句和长视频章节由百炼 Qwen 完成，全部共用一个 API Key。旧本地 Whisper 仅用于明确比较或远程服务不可用时的降级。
- ASR 自动应用外部 hotwords 和 glossary；随后由 Agent 通读整份转录稿并补充高置信错误。`review_subtitles.py` 只复制原文和生成疑点清单，自动改词数必须为 0。
- 型号、版本号、命令、文件名和界面文字需要结合口播上下文核对。画面中的项目名、窗口标题或侧边栏背景文字只有与口播属于同一指代时才能作为证据；看不清或无法确认时保留原文，交给用户预览。
- 用户在预览页保存字幕时，脚本只比较修改前后内容并生成待 Agent 审阅的 `manual-edit-review.json`，不得调用模型或自动写入 glossary。Agent 只把稳定、可复用且上下文安全的 ASR 映射写入个人 glossary；润色、删句、标点和一次性改写一律忽略。
- 字幕默认不显示标点；人工审阅过的 SRT 通过 `--srt-input` 直烧时保持文本、换行和时间码不变。
- 清理标点必须保留数字之间的小数点，包括评测分数和模型版本号。交付前同时核对审校稿、准备后的字幕和最终 SRT 中的关键数字，不能只检查 ASR 校对副本。
- 正常中文字幕默认在中文与英文或数字的边界补一个半角空格，例如 `使用Claude Code做AI实战` 显示为 `使用 Claude Code 做 AI 实战`。该规则在准备阶段统一写入预览字幕，并在烧录阶段幂等复用；用户不需要手工逐条加空格，纯空格变化也不进入错题本。
- 章节进度功能默认开启。视频严格超过三分钟时，在视频画面底部用半透明渐变阴影承载宽粒度章节进度；不增加实色画布，也不把每个小点拆成章节。
- 用户只要用自然语言说“关闭章节进度条”或同义表达，本次任务就在准备和烧录命令中都传 `--no-progress`，不生成章节，也不显示进度条；用户说“开启章节进度条”时传 `--progress`。这是单次任务开关，不要求用户修改配置文件。
- 正常烧录会识别持续出现的人脸区域并执行固定轻度美颜；用户要求保持原画时传 `--no-beauty`。
- 不覆盖已有 MP4、SRT 或 ASS。目标存在时使用新文件名，除非用户明确同意覆盖。

## 初始化

```bash
SKILL_DIR="<oil-subtitle 的绝对目录>"
PYTHON="$SKILL_DIR/.venv/bin/python3"
CONFIG="${OIL_SUBTITLE_CONFIG:-$HOME/.config/oil-subtitle/config.json}"
```

首次使用时运行：

```bash
bash "$SKILL_DIR/setup.sh"

Report a problem