kb-skills/kb-whisper/SKILL.md

name, description

name	description
kb-whisper	本地语音识别，支持音视频转文字（基于 Whisper.cpp）

KB Whisper Skill

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

什么时候使用

当用户需要：

• 将视频/音频文件转换为文字
• 生成视频字幕（SRT 格式）
• 获取带时间戳的详细识别结果

环境变量

在使用之前，必须检查环境变量是否已经设置。

变量名	用途	示例
WHISPER_CPP_PATH	whisper.cpp 安装路径	~/whisper.cpp

使用方法

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

# 指定模型（默认 tiny）
python whisper.py --input video.mp4 --model base

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

# 异步执行（推荐）
python whisper.py --input video.mp4 --background

命令参数

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

模型选项

• tiny - 最小模型，速度快，精度较低（推荐快速识别）
• base - 基础模型，平衡速度和精度（推荐）
• small - 小型模型，精度更高，速度较慢
• medium - 中型模型，高精度
• large - 大型模型，最高精度，速度慢

输出文件

对于输入 video.mp4，将生成：

• video.json - 详细结果（包含时间戳、分段信息）
• video.srt - 字幕格式文件
• video.txt - 纯文本内容

输出格式示例

JSON 格式

{
  "success": true,
  "input_file": "video.mp4",
  "model": "tiny",
  "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": "这是第一段字幕"
    }
  ]
}

Workflow 中的使用

# 步骤4之后：如果已有音频但无字幕，可以使用 whisper
python whisper.py --input ${video_path} --model base --background

安装

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

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

# 3. 下载模型（tiny）
./models/download-ggml-model.sh tiny

# 4. 下载更多模型（可选）
# ./models/download-ggml-model.sh base
# ./models/download-ggml-model.sh small

# 5. 复制技能到 skills 目录
cp -r kb-whisper/ ~/skills/

注意事项

• 异步执行: 使用 --background 参数时，命令会在后台运行，不阻塞主代理
• 模型选择: tiny 模型适合快速识别，base 模型适合一般用途，large 模型适合高精度需求
• 文件格式: 支持 MP3、MP4、WAV、FLAC、OGG、M4A 等常见格式