视频字幕器——动画字幕管线
使用 Whisper 转录语音,并通过 pycaps 将逐字动画字幕嵌入视频。不进行色彩校正——如需视觉增强,请先使用 video-enhancer 技能。
管线
输入视频 → Whisper 转录 → pycaps 字幕渲染 → 带字幕的输出视频
字幕样式
三种选项:
- 默认(无标志)——pycaps 内置极简风格:纯白文字,无特效。
- 未来主义(内置)——
--css scripts/futuristic.css——交替的金色/品红色字幕,带发光效果和等宽字体。适合科技、游戏或高能内容。 - 自定义——用户可以通过
--css /path/to/custom.css提供任意 CSS 文件路径。
如果用户未提及字幕样式,请询问他们想要默认外观、未来主义样式还是自定义 CSS 文件。
静态字幕
使用 --caption 在特定时间戳添加预定义文本,而非转录音频:
--caption "START-END: TEXT"
格式:
- 时间使用
M:SS或MM:SS格式(例如,0:05= 5 秒,1:30= 90 秒) - 多个字幕:多次使用
--caption - 如果同时提供静态字幕和转录,静态字幕优先
示例:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello world" \
--caption "0:10-0:20: This is a demo" \
--css scripts/futuristic.css
字幕样式设置
样式通过 JSON 配置文件 管理。使用静态字幕时,样式会自动应用。
默认样式
未指定 --style-config 时,使用 config.default.json:
- 背景: 白色 (
#FFFFFF) - 文字颜色: 蓝色 (
#0066FF) - 字体:
auto——首先使用brand-manager中标记为caption的可用的品牌字体,然后回退到 Courier New - 内边距:
10px 15px - 外边距:
0
使用样式配置
通过传递配置文件切换样式:
# 使用深色模式样式
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json
包含的配置:
config.default.json——白色背景、蓝色文字、Courier New(默认)config.dark-mode.json——深色背景、白色文字、较大字体
创建自定义样式配置
复制 config.default.json 并修改:
{
"caption_bg_color": "#000000",
"caption_color": "#FFFFFF",
"caption_font": "auto",
"caption_font_tag": "caption",
"caption_padding": "20px 30px",
"caption_margin": "10px",
"caption_font_size": 48
}
然后使用它:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Text" \
--style-config my-custom-style.json
使用 CLI 标志覆盖配置
CLI 标志优先级高于配置文件值:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json \
--caption-color "#00FF00" # 覆盖配置中的文字颜色
样式配置参考
| 键 | 类型 | 描述 |
|---|---|---|
caption_bg_color | string | 背景颜色(十六进制或 CSS 颜色名) |
caption_color | string | 文字颜色(十六进制或 CSS 颜色名) |
caption_font | string | auto、字体族或 .ttf、.otf、.woff、.woff2 文件路径 |
caption_font_tag | string 或 null | 从 brand-manager 首选的品牌字体标签(caption、body、heading 等) |
caption_padding | string | CSS 内边距(例如,"10px 15px") |
caption_margin | string | CSS 外边距(例如,"0") |
caption_font_size | integer 或 null | 字体大小(像素,null = 自动缩放) |
可用字体
系统字体可按名称指定:
DejaVu Sans/DejaVu Sans Bold/DejaVu SerifLiberation Sans/Liberation MonoCourier NewUbuntu Mono- 任意 TTF 文件路径:
/path/to/font.ttf
或者从 skills/brand-manager/brand-assets/asset-manifest.json 中选择品牌字体。
当 caption_font 为 auto 时,技能会读取品牌清单(或 CLAW_BRAND_ASSETS_DIR(如果已设置)),并使用第一个由 caption_font_tag 标记的可用字体;如果没有标记的字体,则尝试标记为 caption、body、heading 或 bold 的品牌字体,然后回退到 Courier New。如果解析出的品牌字体是文件路径,生成的 CSS 会包含一个 @font-face 规则,以便 pycaps 能渲染它。
如何运行
安装依赖项(仅首次运行):
cd "$SKILL_DIR" && uv sync
注意: 首次运行会很慢(可能耗时数分钟),因为 pycaps 会下载 Whisper 语音识别模型。在开始前警告用户。
然后处理视频:
cd "$SKILL_DIR" && uv run python scripts/caption_service.py \
--input <path/to/input> \
--output <path/to/output> \
[--css scripts/futuristic.css]
常用调用
# 默认极简字幕(Whisper 转录)
uv run python scripts/caption_service.py --input ./input --output ./output
# 未来主义样式
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css scripts/futuristic.css
# 自定义 CSS
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css /path/to/my.css
# 静态字幕,默认样式(白色背景、蓝色文字、Courier New)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Subscribe for more" \
--caption "0:10-0:15: Follow us on Instagram"
# 静态字幕,深色模式样式
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello world" \
--caption "0:10-0:20: This is a demo" \
--style-config config.dark-mode.json
# 静态字幕,自定义样式配置
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Custom text" \
--style-config my-custom-style.json
# 静态字幕,带 CLI 标志覆盖
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json \
--caption-color "#00FF00"
# 监视模式(每 10s 轮询新视频)
uv run python scripts/caption_service.py --input ./input --output ./output --watch
运行后
向用户报告:
- 成功处理了多少个视频,失败了多少个。
- 输出目录的完整路径。
- 如果有任何视频失败,明确列出它们。
边缘情况
- 如果未安装
ffmpeg:告诉用户安装它(Arch/CachyOS 上sudo pacman -S ffmpeg,macOS 上brew install ffmpeg,Ubuntu 上sudo apt install ffmpeg) - 如果未安装
uv:引导至 https://docs.astral.sh/uv/getting-started/installation/ - 如果输入目录为空:明确报告,而不是静默退出
- 首次运行会下载 Whisper 模型(
tiny约 140 MB,large约 1.5 GB)——仅一次
远程转录
此技能现在支持 可选的远程转录,同时保持 pycaps 渲染本地化。
- 默认行为仍然是完全本地化:pycaps 内部的 Whisper 转录 + 本地渲染
- 远程模式仅替换转录步骤
- 字幕渲染、模板和 CSS 处理仍然在本地
支持的提供商
huggingfacereplicate
配置 / CLI 键
| 键 | 默认值 | 说明 |
|---|---|---|
transcription_provider | null | null 保持本地 Whisper-in-pycaps 流程 |
remote_model | null | 可选的提供商特定转录模型覆盖 |
hf_token_env | HF_TOKEN | HuggingFace 授权环境变量名 |
replicate_api_key_env | REPLICATE_API_TOKEN | Replicate 授权环境变量名 |
remote_timeout_seconds | 300 | 远程调用超时 |
示例
# HuggingFace 远程转录 + 本地 pycaps 渲染
export HF_TOKEN=hf_your_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider huggingface
# Replicate 远程转录 + 本地 pycaps 渲染
export REPLICATE_API_TOKEN=r8_your_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider replicate --remote-model <replicate-model-slug>
说明
- 如果缺少远程授权/配置,不会静默回退到本地模式
- 现有的本地 CLI 用法仍然有效
- 如果不设置
--transcription-provider,pycaps 继续使用其内置的 Whisper 流程