| name | video-to-text |
| description | 视频/音频转文字稿。从视频文件中提取音频，用 whisperX 进行语音识别、时间戳对齐和说话人分离，输出带时间戳和说话人标签的文字稿。适用于：直播回放转写、会议录音转文字、播客转录、任何视频/音频转文稿的场景。 |
Video to Text — 视频/音频转文字稿
依赖
- ffmpeg: 从视频中提取音频（系统已安装）
- whisperX: 语音识别 + 对齐 + 说话人分离（
pip install whisperx）
- HF_TOKEN: 说话人分离需要 HuggingFace token（环境变量
HF_TOKEN）
快速执行
对于简单的转写任务，直接运行脚本：
nohup python3 {skillDir}/scripts/transcribe.py /path/to/video.mp4 \
--output-dir /path/to/output \
--output-name transcript \
--diarize \
> /tmp/transcribe.log 2>&1 &
必须用 nohup 后台执行——长音频（>30 min）转写时间可达数十分钟到数小时，exec session 会超时。
完整流程
Step 1: 预处理
- 确认输入文件存在，获取时长：
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 <file>
- 若文件名含 CJK 字符，创建 symlink 避免编码问题：
ln -sf "<原路径>" /tmp/input-video.mp4
- 脚本会自动判断：音频文件直接转写，视频文件先提取音频为 16kHz mono WAV
Step 2: 转写
运行 scripts/transcribe.py，关键参数：
| 参数 | 默认值 | 说明 |
|---|
--model | large-v3 | Whisper 模型，large-v3 最准但最慢 |
--language | zh | 语言代码 |
--diarize | off | 启用说话人分离（需 HF_TOKEN） |
--device | cpu | cpu 或 cuda |
--batch-size | 8 | 批次大小，内存不够可降低 |
Step 3: 监控进度
长音频转写用 cron watcher 监控：
cat > /tmp/watch-transcribe.sh << 'EOF'
if ! kill -0 <PID> 2>/dev/null; then
echo "done $(date)" > /tmp/transcribe-status.txt
fi
EOF
或通过 OpenClaw cron 每 5 分钟检查进程状态。
Step 4: 输出
脚本生成两个文件：
<name>.txt: 人类可读文稿，按说话人分段，带 [MM:SS] 时间戳<name>.json: 完整 whisperX 输出，含 word-level 时间戳
存档
转写完成后，将 .txt 文件复制到 workspace/transcripts/ 目录：
- 命名约定：
<原始文件名>.txt（如 直播回放-02月26日.txt）
性能参考
| 音频时长 | 模型 | 设备 | 预计耗时 |
|---|
| 30 min | large-v3 | CPU (M-series) | ~15 min |
| 1 hour | large-v3 | CPU (M-series) | ~30 min |
| 2 hours | large-v3 | CPU (M-series) | ~60 min |
注意事项
- CJK 文件名在 nohup/shell 中容易乱码，始终用 symlink 或英文路径
- CPU 转写时 CPU 占用 300-400%，避免同时跑其他重负载任务
- whisperX 的 diarization 依赖 pyannote，首次运行需要下载模型（~1GB）
- 如果本地有 Whisper HTTP server（端口 9876），该 skill 不使用它——直接调用 whisperX Python API 更灵活
