agentleFS
yfgeyfge/video-skills-suite/skills/video-to-text/SKILL.md

video-to-text

Skill1 starsChanged 9 months agoMITView on GitHub

视频/音频转文字稿。从视频文件中提取音频,用 whisperX 进行语音识别、时间戳对齐和说话人分离,输出带时间戳和说话人标签的文字稿。适用于:直播回放转写、会议录音转文字、播客转录、任何视频/音频转文稿的场景。

  • Installs packages

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

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,关键参数:

参数默认值说明
--modellarge-v3Whisper 模型,large-v3 最准但最慢
--languagezh语言代码
--diarizeoff启用说话人分离(需 HF_TOKEN)
--devicecpucpu 或 cuda
--batch-size8批次大小,内存不够可降低

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 minlarge-v3CPU (M-series)~15 min
1 hourlarge-v3CPU (M-series)~30 min
2 hourslarge-v3CPU (M-series)~60 min

注意事项

  • CJK 文件名在 nohup/shell 中容易乱码,始终用 symlink 或英文路径
  • CPU 转写时 CPU 占用 300-400%,避免同时跑其他重负载任务
  • whisperX 的 diarization 依赖 pyannote,首次运行需要下载模型(~1GB)
  • 如果本地有 Whisper HTTP server(端口 9876),该 skill 不使用它——直接调用 whisperX Python API 更灵活

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.