Dependencies
- ffmpeg: Extract audio from video (already installed on the system)
- whisperX: Speech recognition + alignment + speaker diarization (
pip install whisperx） - HF_TOKEN: Speaker diarization requires a HuggingFace token (environment variable
HF_TOKEN）
Quick execution
For simple transcription tasks, run the script directly:
nohup python3 {skillDir}/scripts/transcribe.py /path/to/video.mp4 \
--output-dir /path/to/output \
--output-name transcript \
--diarize \
> /tmp/transcribe.log 2>&1 &
Must use nohup to run in the background— Long audio (>30 min) transcription can take tens of minutes to several hours, and the exec session will time out.
Full workflow
Step 1: Preprocessing
- Confirm the input file exists and get its duration:
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 <file> - If the filename contains CJK characters, create a symlink to avoid encoding issues:
ln -sf "<原路径>" /tmp/input-video.mp4 - The script automatically determines: audio files are transcribed directly, video files first have their audio extracted to 16kHz mono WAV
Step 2: Transcription
Run scripts/transcribe.py, key parameters:
| Parameter | Default value | Description |
|---|---|---|
--model |
large-v3 | Whisper model; large-v3 is the most accurate but the slowest |
--language |
zh | Language code |
--diarize |
off | Enable speaker diarization (requires HF_TOKEN) |
--device |
cpu | cpu or cuda |
--batch-size |
8 | Batch size; can be lowered if memory is insufficient |
Step 3: Monitor progress
For long audio transcription, use a cron watcher to monitor:
# 创建 watcher 脚本
cat > /tmp/watch-transcribe.sh << 'EOF'
if ! kill -0 <PID> 2>/dev/null; then
echo "done $(date)" > /tmp/transcribe-status.txt
fi
EOF
Or use OpenClaw cron to check the process status every 5 minutes.
Step 4: Output
The script generates two files:
<name>.txt: Human-readable transcript, segmented by speaker, with[MM:SS]timestamps<name>.json: Full whisperX output, including word-level timestamps
Archiving
After transcription is complete, copy the .txt file to the workspace/transcripts/ directory:
- Naming convention:
<原始文件名>.txt(e.g.,直播回放-02月26日.txt）
Performance reference
| Audio duration | Model | Device | Estimated time |
|---|---|---|---|
| 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 |
Notes
- CJK filenames are prone to garbling in nohup/shell; always use a symlink or an English path
- During CPU transcription, CPU usage is 300-400%; avoid running other heavy-load tasks at the same time
- whisperX's diarization depends on pyannote, and the first run requires downloading models (~1GB)
- If there is a local Whisper HTTP server (port 9876), this skill does not use it—calling the whisperX Python API directly is more flexible