yfge/video-to-text

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: 预处理

1. 确认输入文件存在，获取时长：ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 <file>
2. 若文件名含 CJK 字符，创建 symlink 避免编码问题：ln -sf "<原路径>" /tmp/input-video.mp4
3. 脚本会自动判断：音频文件直接转写，视频文件先提取音频为 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 监控：

# 创建 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 更灵活