音频 SRT 工作流

使用此技能完成端到端字幕处理任务。

本包为运行时入口点提供完整封装，包含以下脚本：

• scripts/align_to_srt.py
• scripts/gui_app.py
• scripts/srt_stats.py
• scripts/make_preview_mp4.py
• scripts/requirements.txt

适用范围

• 模式 A：音频 + 参考文本 → 对齐后的 SRT 字幕
• 模式 B：仅音频 → 自动语音识别生成的 SRT 字幕
• 使用 srt_stats.py 进行时间轴质量评估（QA）
• 使用 make_preview_mp4.py 生成带硬编码字幕的预览视频

需预先收集的输入项

1. 音频路径（支持 wav、mp3、m4a 等格式）
2. 是否存在参考文稿（transcript）
3. 输出 SRT 路径（或输出目录）
4. 语言提示（如 zh、en 等）
5. 首选执行方式：命令行（CLI）、图形界面（GUI）或 Python API

决策规则

• 若存在文稿，则运行模式 A（align_to_srt.py --text ...）。
• 若不存在文稿，则通过 GUI 或 Python API 运行模式 B（调用 run_auto_subtitle_pipeline）。

工作流

1. 校验运行环境与路径有效性。
2. 根据文稿是否可用，选择模式 A 或模式 B。
3. 调用封装好的脚本执行字幕生成。
4. 运行时间轴诊断工具（srt_stats.py）。
5. 如有需要，生成带硬编码字幕的预览 MP4 视频。

解析技能脚本路径

请设置一个本地变量，指向你已安装的技能目录。

Codex 默认路径：

SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/audio-srt-workflow"

OpenClaw / ClawHub 安装路径示例：

SKILL_DIR="/skills/audio-srt-workflow"

环境检查

执行前请运行以下检查命令：

python3 --version
ffmpeg -version
python3 -c "import faster_whisper; print('ok')"

若 faster-whisper 导入失败，请执行：

# 安装前先查看依赖列表：
cat "$SKILL_DIR/scripts/requirements.txt"
pip install -r "$SKILL_DIR/scripts/requirements.txt"

模式 A 命令模板（音频 + 文稿）

python3 "$SKILL_DIR/scripts/align_to_srt.py" 
  --audio "" 
  --text "" 
  --output "" 
  --model small 
  --language zh

模式 B 命令模板（仅音频）

图形界面（GUI）方式：

python3 "$SKILL_DIR/scripts/gui_app.py"

或在脚本中使用 Python API：

• 使用 build_alignment_config(...) 构建配置
• 调用 run_auto_subtitle_pipeline(...)

详细命令说明参见 references/command-templates.md。

质量评估与预览

时间轴统计信息：

python3 "$SKILL_DIR/scripts/srt_stats.py" --srt ""

生成预览视频：

python3 "$SKILL_DIR/scripts/make_preview_mp4.py" 
  --audio "" 
  --srt "" 
  --output "
"

输出规范

默认输出文件使用 .srt 扩展名。
批量运行时建议采用日期命名（例如 output_YYYYMMDD.srt）。
中间检查结果应存放于独立目录，与最终交付文件分离。

注意事项

中文（zh）输出时，该流水线仅移除逗号与句号，不进行其他标点处理。
若时间轴偏差明显，建议优先检查波形对齐（waveform snap）相关参数，再考虑调整模型尺寸。
本技能需显式调用（allow_implicit_invocation: false）。