openclaw-skills/skills/kb-whisper/examples.md

KB Whisper 使用示例

快速开始

1. 基础使用

# 使用默认 tiny 模型转录视频
python whisper.py --input video.mp4

# 使用 base 模型（推荐）
python whisper.py --input video.mp4 --model base

2. 异步执行

# 后台处理，不阻塞主代理
python whisper.py --input video.mp4 --model base --background

3. 指定输出目录

python whisper.py --input video.mp4 --output ./transcripts

4. 指定语言

# 指定中文
python whisper.py --input video.mp4 --language zh

# 指定英文
python whisper.py --input video.mp4 --language en

# 指定日语
python whisper.py --input video.mp4 --language ja

实际应用场景

场景 1: 转录播客

python whisper.py --input podcast.mp3 --model base --background

输出:

• podcast.json - 带时间戳的详细结果
• podcast.srt - 字幕格式
• podcast.txt - 纯文本

场景 2: 生成视频字幕

python whisper.py --input tutorial.mp4 --model small

用途:

• 为教程视频生成字幕
• 导出 SRT 文件到视频编辑软件
• 生成多语言字幕版本

场景 3: 会议录音转文字

python whisper.py --input meeting.mp3 --model base --output ./meetings

输出示例:

meetings/
├── meeting.json   # 完整 JSON（含时间戳）
├── meeting.srt    # 字幕格式
└── meeting.txt    # 纯文本

场景 4: 批量处理

创建脚本 batch_transcribe.sh:

#!/bin/bash

OUTPUT_DIR="./transcripts"
mkdir -p "$OUTPUT_DIR"

for video in videos/*.mp4; do
    echo "处理: $video"
    python whisper.py --input "$video" --output "$OUTPUT_DIR" --model base
done

echo "批量处理完成!"

chmod +x batch_transcribe.sh
./batch_transcribe.sh

在 Workflow 中使用

知识库处理流程

在 kb-workflow 技能中，如果视频没有字幕：

# 步骤 4: 下载视频后
# 检查是否有字幕文件
if [ ! -f "${subtitle_file}" ]; then
    echo "无字幕文件，使用 Whisper 生成..."

    # 使用 Whisper 生成字幕（后台执行）
    python /path/to/whisper.py \
        --input "${video_path}" \
        --model base \
        --output "${content_dir}" \
        --background

    # 等待 Whisper 完成
    sleep 5  # 等待后台任务启动
    while ! [ -f "${content_dir}/$(basename ${video_path} .mp4).srt" ]; do
        sleep 2
    done

    echo "Whisper 处理完成"
fi

输出文件使用

JSON 格式

import json

# 读取 JSON 结果
with open('video.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# 访问分段
for segment in data['segments']:
    print(f"[{segment['start']:.2f}-{segment['end']:.2f}] {segment['text']}")

SRT 格式

# 直接在视频播放器中使用
mpv video.mp4 --sub-file=video.srt

# 或转换字幕格式
ffmpeg -i video.srt video.ass

TXT 格式

# 搜索关键词
grep "重要信息" video.txt

# 统计字数
wc -m video.txt

性能优化建议

1. 根据内容选择模型

# 快速预览（短视频、测试）
python whisper.py --input video.mp4 --model tiny

# 日常使用（播客、会议）
python whisper.py --input video.mp4 --model base

# 高质量需求（正式内容、多语言）
python whisper.py --input video.mp4 --model small

2. 使用后台执行

# 处理长文件时使用后台模式
python whisper.py --input long_video.mp4 --model base --background

3. 指定语言提升准确度

# 如果知道内容语言，指定后准确度更高
python whisper.py --input video.mp4 --language zh

故障排查

问题 1: whisper.cpp 未找到

# 检查环境变量
echo $WHISPER_CPP_PATH

# 或配置
clawdbot skills config kb-whisper WHISPER_CPP_PATH "~/whisper.cpp"

问题 2: 模型未下载

cd ~/whisper.cpp
./models/download-ggml-model.sh base

问题 3: 音频格式不支持

# 转换格式
ffmpeg -i input.avi -acodec libmp3lame output.mp3
python whisper.py --input output.mp3

问题 4: 后台任务未完成

# 查看日志
cat video_whisper.log

# 检查进程
ps aux | grep whisper

集成到其他工具

集成到 Python 脚本

import subprocess
import json

def transcribe_audio(audio_path, model='base'):
    """调用 whisper.py 转录音频"""
    cmd = [
        'python3', '/path/to/whisper.py',
        '--input', audio_path,
        '--model', model
    ]

    result = subprocess.run(cmd, capture_output=True, text=True)
    return json.loads(result.stdout)

# 使用
result = transcribe_audio('podcast.mp3', 'base')
print(f"识别到 {result['total_segments']} 个片段")

集成到 Shell 脚本

#!/bin/bash

transcribe() {
    local file=$1
    local model=${2:-base}

    echo "转录: $file"
    python3 whisper.py --input "$file" --model "$model" --background
}

# 批量处理
transcribe "video1.mp4"
transcribe "video2.mp4" "tiny"