feat(kb-whisper): 新增本地语音识别技能，基于 Whisper.cpp

2026-02-13 01:20:27 +08:00
parent 2adc3c1e8d
commit 9102a973cd
6 changed files with 993 additions and 0 deletions
@@ -0,0 +1,273 @@
+# 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"
+```