# KB Whisper 使用示例

## 快速开始

### 1. 基础使用

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

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

### 2. 异步执行

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

### 3. 指定输出目录

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

### 4. 指定语言

```bash
# 指定中文
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: 转录播客

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

**输出**:
- `podcast.json` - 带时间戳的详细结果
- `podcast.srt` - 字幕格式
- `podcast.txt` - 纯文本

### 场景 2: 生成视频字幕

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

**用途**:
- 为教程视频生成字幕
- 导出 SRT 文件到视频编辑软件
- 生成多语言字幕版本

### 场景 3: 会议录音转文字

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

**输出示例**:
```
meetings/
├── meeting.json   # 完整 JSON（含时间戳）
├── meeting.srt    # 字幕格式
└── meeting.txt    # 纯文本
```

### 场景 4: 批量处理

创建脚本 `batch_transcribe.sh`:

```bash
#!/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 "批量处理完成!"
```

```bash
chmod +x batch_transcribe.sh
./batch_transcribe.sh
```

## 在 Workflow 中使用

### 知识库处理流程

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

```bash
# 步骤 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 格式

```python
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 格式

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

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

### TXT 格式

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

# 统计字数
wc -m video.txt
```

## 性能优化建议

### 1. 根据内容选择模型

```bash
# 快速预览（短视频、测试）
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. 使用后台执行

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

### 3. 指定语言提升准确度

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

## 故障排查

### 问题 1: whisper.cpp 未找到

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

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

### 问题 2: 模型未下载

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

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

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

### 问题 4: 后台任务未完成

```bash
# 查看日志
cat video_whisper.log

# 检查进程
ps aux | grep whisper
```

## 集成到其他工具

### 集成到 Python 脚本

```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 脚本

```bash
#!/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"
```