openclaw/skills/kb-whisper/SKILL.md

name, description

name	description
kb-whisper	本地语音识别 - 使用 Whisper.cpp 将音视频转文字

KB Whisper Skill

kb-whisper - 本地语音识别，使用 Whisper.cpp 将音视频文件转换为文本、字幕和 JSON 格式。

什么时候使用

• kb-workflow 步骤 4：视频无官方字幕时进行语音识别
• 需要将音视频转为文字

环境变量

变量名	必需	说明
WHISPER_CPP_PATH	是	whisper.cpp 安装路径

命令

# 基本用法
python3 whisper.py --input video.mp4

# 指定模型（推荐 base）
python3 whisper.py --input video.mp4 --model base

# 指定输出目录
python3 whisper.py --input video.mp4 --output ./output

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

参数说明

参数	说明	默认值
--input	输入音视频文件路径	必需
--model	Whisper 模型类型	tiny
--output	输出目录	文件所在目录
--background	后台异步执行	False

模型选项

模型	速度	精度	推荐场景
tiny	最快	较低	快速预览
base	快	良好	推荐
small	中等	高	精确识别
medium	慢	很高	专业场景
large	最慢	最高	最高精度

输出格式 Schema

必需字段

字段	类型	说明
success	boolean	是否识别成功
input_file	string	输入文件路径
model	string	使用的模型

可选字段

字段	类型	说明
output_files	object	输出文件路径
duration_seconds	number	音频时长
segments	array	识别分段
error	string	错误信息

成功示例

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

错误示例

模型未下载

{
  "success": false,
  "error": "模型文件不存在",
  "model": "base",
  "suggestion": "请运行: cd ~/whisper.cpp && ./models/download-ggml-model.sh base"
}

文件不存在

{
  "success": false,
  "error": "输入文件不存在",
  "input_file": "content/downloads/missing.mp4"
}

内存不足

{
  "success": false,
  "error": "内存不足，无法加载模型",
  "suggestion": "尝试使用更小的模型（tiny/base）"
}

安装

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

# 2. 编译
cd ~/whisper.cpp && make

# 3. 下载模型
./models/download-ggml-model.sh base

# 4. 设置环境变量
echo 'export WHISPER_CPP_PATH="$HOME/whisper.cpp"' >> ~/.kb_env
source ~/.kb_env

# 5. 复制技能
cp -r kb-whisper/ ~/.openclaw/skills/

在 kb-workflow 中的使用

# 步骤 4：语音识别（当 has_subtitle=false 时）
python3 ~/.openclaw/skills/kb-whisper/whisper.py \
    --input "content/downloads/bilibili_BV1xx411c7mD.mp4" \
    --model base \
    --output "content/"

# 输出：
# - bilibili_BV1xx411c7mD.json (完整结果)
# - bilibili_BV1xx411c7mD.txt (纯文本)
# - bilibili_BV1xx411c7mD.srt (字幕文件)

# 完成后进入步骤 5（深度分析）

注意事项

• 耗时操作：语音识别可能需要几分钟到几十分钟，取决于视频长度
• 异步执行：推荐使用 --background 参数
• 模型选择：base 模型平衡速度和精度，适合大多数场景
• 文件格式：支持 MP3、MP4、WAV、FLAC、OGG、M4A 等常见格式