VideoCaptioner — 烧字幕

VideoCaptioner CLI

AI 驱动的视频字幕添加工具：语音转文字 → 优化字幕 → 翻译 → 以精美样式嵌入视频。

使用场景

• 用户想要为视频添加字幕
• 用户想要将音频/视频转录为文本
• 用户想要将字幕翻译成另一种语言
• 用户想要自定义字幕外观（颜色、字体、圆角背景）
• 用户想要下载并为在线视频添加字幕

开始之前

在运行命令前，务必先执行 videocaptioner <command> --help 查看最新选项和默认值。以下示例为常见用法，但 --help 才是权威参考。

• 安装：pip install videocaptioner
• 视频合成需要 FFmpeg（macOS 下执行 brew install ffmpeg）
• 免费（无需 API 密钥）： 语音识别（bijian/jianying）、翻译（Bing/Google）
• 需要 LLM API 密钥： 字幕优化、字幕重新分段、LLM 翻译。通过 OPENAI_API_KEY 环境变量或 --api-key 参数设置

常见场景

1. 为中文字幕视频添加英文翻译（一条命令，全免费）

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality high -o output.mp4

2. 将视频转录为 SRT 字幕（免费）

videocaptioner transcribe video.mp4 --asr bijian -o output.srt

# 以 JSON 格式输出到目录
videocaptioner transcribe video.mp4 --asr bijian --format json -o ./subtitles/

3. 翻译现有字幕

# 免费 Bing → 英文，双语输出，翻译在上
videocaptioner subtitle input.srt --translator bing --target-language en --layout target-above -o translated.srt

# 免费 Google → 日文，仅输出翻译（丢弃原文）
videocaptioner subtitle input.srt --translator google --target-language ja --no-optimize --layout target-only -o output_ja.srt

# 使用反思模式的高质量 LLM 翻译
videocaptioner subtitle input.srt --translator llm --target-language en --reflect \
  --api-key $OPENAI_API_KEY -o output_en.srt

4. 全流程带精美样式字幕

# 动漫风格字幕（暖色 + 橙色轮廓），高质量视频
videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja \
  --subtitle-mode hard --style anime --quality high -o output_ja.mp4

# 现代圆角背景字幕
videocaptioner process video.mp4 --asr bijian --translator google --target-language ko \
  --subtitle-mode hard --render-mode rounded -o output_ko.mp4

# 自定义颜色：白字红轮廓，超高质量
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality ultra \
  --style-override '{"outline_color": "#ff0000", "primary_color": "#ffffff"}' -o output_en.mp4

5. 仅输出字幕，ASS 格式（不合成视频）

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --format ass --no-synthesize -o ./output/

6. 分步执行（转录 → 翻译 → 合成分开）

# 第1步：转录
videocaptioner transcribe video.mp4 --asr bijian -o video.srt

# 第2步：翻译（双语，原文在上）
videocaptioner subtitle video.srt --translator bing --target-language en --layout source-above -o video_en.srt

# 第3步：以圆角背景、高质量嵌入视频
videocaptioner synthesize video.mp4 -s video_en.srt --subtitle-mode hard \
  --render-mode rounded --quality high -o video_with_subs.mp4

7. 处理音频文件（自动跳过视频合成）

videocaptioner process podcast.mp3 --asr bijian --translator bing --target-language en -o ./output/

8. 转录其他语言（whisper-api）

videocaptioner transcribe french_video.mp4 --asr whisper-api \
  --whisper-api-key $OPENAI_API_KEY --language fr -o french.srt

9. 仅用 LLM 优化字幕（修正语音识别错误，不翻译）

videocaptioner subtitle raw_subtitle.srt --no-translate --api-key $OPENAI_API_KEY -o optimized.srt

10. 自定义圆角背景样式与自定义字体

videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard \
  --style-override '{"text_color": "#ffffff", "bg_color": "#000000cc", "corner_radius": 10, "font_size": 36}' \
  --font-file ./NotoSansSC.ttf --quality high -o styled_video.mp4

命令参考

命令	用途
transcribe	语音 → 字幕。引擎：bijian(免费) jianying(免费) whisper-api whisper-cpp
subtitle	优化（LLM）和/或翻译（LLM/Bing/Google）字幕文件
synthesize	将字幕嵌入视频，支持自定义样式
process	全流程：转录 → 优化 → 翻译 → 合成
download	从 YouTube、Bilibili 等下载视频
config	管理设置（show set get path init）
style	列出所有字幕样式预设及其参数

执行 videocaptioner <command> --help 查看完整选项。

字幕样式

两种渲染模式，打造精美字幕：

ASS 模式（默认）— 轮廓/阴影样式：

• 预设：default（白字+黑轮廓）、anime（暖色+橙色轮廓）、vertical（竖屏视频）
• 可自定义字段：font_name、font_size、primary_color、outline_color、outline_width、bold、spacing、margin_bottom

圆角模式 — 现代圆角背景框：

• 预设：rounded（半透明背景上的深色文字）
• 可自定义字段：font_name、font_size、text_color、bg_color (#rrggbbaa)、corner_radius、padding_h、padding_v、margin_bottom

样式选项仅适用于 --subtitle-mode hard。

目标语言

BCP 47 代码：zh-Hans zh-Hant en ja ko fr de es ru pt it ar th vi id 等等，共 23 种以上。

环境变量

变量	用途
OPENAI_API_KEY	LLM API 密钥
OPENAI_BASE_URL	LLM API 基础 URL

退出码

0 成功 · 2 错误参数 · 3 文件未找到 · 4 缺少依赖 · 5 运行时错误

提示

• 在脚本中使用 -q（标准输出仅输出结果路径）
• Bing/Google 翻译免费，无需 API 密钥
• bijian/jianying 语音识别免费，但仅支持中文和英文
• 执行 videocaptioner style 查看所有样式预设