# KB Whisper - 本地语音识别

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

## 功能特性

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

## 安装前提

### 1. 安装 whisper.cpp

```bash
# 克隆仓库
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` 中添加：

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

或通过命令行配置：

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

## 使用方法

### 基本用法

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

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

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

### 指定输出目录

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

### 处理音频文件

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

## 输出文件

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

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

### JSON 格式

```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: 转录播客

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

### 示例 2: 生成视频字幕

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

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

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

## 在 Workflow 中使用

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

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

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

## 技术细节

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

## 故障排查

### 问题: 找不到 whisper.cpp

```bash
# 检查环境变量
echo $WHISPER_CPP_PATH

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

### 问题: 模型未下载

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

### 问题: 音频格式不支持

```bash
# 转换音频格式
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 许可证。