openclaw/skills/kb-whisper/README.md

KB Whisper - 本地语音识别

基于 Whisper.cpp 的本地语音识别工具，支持将音视频文件转换为文本、字幕和 JSON 格式。

功能特性

• 🎯 本地执行 - 完全离线运行，保护隐私
• 🚀 多模型支持 - 从 tiny 到 large，根据需求选择速度/精度
• 📝 多格式输出 - JSON、SRT、TXT 三种格式
• ⚡ 异步执行 - 支持后台运行，不阻塞主代理
• 🎬 广泛兼容 - 支持常见音视频格式（MP3、MP4、WAV 等）

安装前提

1. 安装 whisper.cpp

# 克隆仓库
git clone https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp

# 编译
cd ~/whisper.cpp
make

# 下载模型（至少需要一个模型）
./models/download-ggml-model.sh tiny
./models/download-ggml-model.sh base  # 可选

2. 配置环境变量

在 ~/.clawdbot/clawdbot.json 中添加：

{
  skills: {
    entries: {
      "kb-whisper": {
        env: {
          WHISPER_CPP_PATH: "~/whisper.cpp"
        }
      }
    }
  }
}

或通过命令行配置：

clawdbot skills config kb-whisper WHISPER_CPP_PATH "~/whisper.cpp"

使用方法

基本用法

# 使用默认 tiny 模型处理
python whisper.py --input video.mp4

# 使用 base 模型（推荐，平衡速度和精度）
python whisper.py --input video.mp4 --model base

# 后台异步执行
python whisper.py --input video.mp4 --background

指定输出目录

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

处理音频文件

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

输出文件

对于输入 video.mp4，将生成以下文件：

output/
├── video.json   # 详细结果（含时间戳）
├── video.srt    # 字幕格式
└── video.txt    # 纯文本

JSON 格式

{
  "success": true,
  "input_file": "video.mp4",
  "model": "base",
  "output_files": {
    "json": "video.json",
    "srt": "video.srt",
    "txt": "video.txt"
  },
  "duration_seconds": 120.5,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 3.2,
      "text": "这是第一段字幕"
    },
    {
      "id": 1,
      "start": 3.2,
      "end": 6.8,
      "text": "这是第二段字幕"
    }
  ]
}

模型对比

模型	速度	精度	适用场景
tiny	⚡⚡⚡	⭐	快速预览、实时转录
base	⚡⚡	⭐⭐⭐	日常使用（推荐）
small	⚡	⭐⭐⭐⭐	高质量需求
medium	⭐	⭐⭐⭐⭐⭐	专业用途
large	🐢	⭐⭐⭐⭐⭐	最高精度要求

完整示例

示例 1: 转录播客

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

示例 2: 生成视频字幕

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

示例 3: 批量处理（配合脚本）

#!/bin/bash
for video in videos/*.mp4; do
  python whisper.py --input "$video" --model base
done

在 Workflow 中使用

在知识库处理流程中，如果视频没有字幕：

# 步骤4: 下载视频后，如果没有字幕
# 步骤5: 使用 Whisper 生成字幕
python whisper.py --input ${video_path} --model base --background

# 等待 Whisper 完成，然后继续后续步骤

技术细节

• 引擎: Whisper.cpp（C++ 实现，性能优异）
• 音频采样率: 自动转换为 16kHz
• 语言: 自动检测（支持 99 种语言）
• GPU 支持: whisper.cpp 支持 CUDA 加速（需编译时启用）

故障排查

问题: 找不到 whisper.cpp

# 检查环境变量
echo $WHISPER_CPP_PATH

# 手动测试
~/whisper.cpp/main --help

问题: 模型未下载

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

问题: 音频格式不支持

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

性能参考

在 CPU 环境下（Intel i7）：

• tiny 模型: ~1x 实时速度（1分钟音频 ~1分钟处理）
• base 模型: ~0.5x 实时速度（1分钟音频 ~2分钟处理）
• small 模型: ~0.25x 实时速度（1分钟音频 ~4分钟处理）

许可证

本技能使用 MIT 许可证，Whisper.cpp 使用 MIT 许可证。