# KB FunASR - 本地语音识别

基于阿里 FunASR 的本地语音识别工具，支持将音视频文件转换为文本和 JSON 格式。

## 功能特性

- 🎯 **本地执行** - 完全离线运行，保护隐私
- 🚀 **多模型支持** - Paraformer、SenseVoice 等模型可选
- 📝 **多格式输出** - JSON、TXT 两种格式
- ⚡ **异步执行** - 支持后台运行，不阻塞主代理
- 🎬 **广泛兼容** - 支持常见音视频格式（MP3、MP4、WAV 等）
- 🇨🇳 **中文优化** - Paraformer 模型针对中文语音优化

## 安装前提

### 1. 安装依赖

```bash
pip install funasr modelscope
```

### 2. 配置环境变量（可选）

在 `~/.clawdbot/clawdbot.json` 中添加：

```json5
{
  skills: {
    entries: {
      "kb-funasr": {
        env: {
          FUNASR_CACHE_DIR: "~/.cache/modelscope/hub"
        }
      }
    }
  }
}
```

或通过命令行配置：

```bash
clawdbot skills config kb-funasr FUNASR_CACHE_DIR "~/.cache/modelscope/hub"
```

## 使用方法

### 基本用法

```bash
# 使用默认 Paraformer 中文模型处理
python funasr.py --input video.mp4

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

### 指定模型

```bash
# Paraformer 中文模型（推荐）
python funasr.py --input video.mp4 --model paraformer-zh

# Paraformer 多语言模型
python funasr.py --input video.mp4 --model paraformer

# SenseVoice 多语言模型
python funasr.py --input video.mp4 --model sensevoice
```

### 指定输出目录

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

## 输出文件

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

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

### JSON 格式

```json
{
  "success": true,
  "input_file": "video.mp4",
  "model": "paraformer-zh",
  "output_files": {
    "json": "video.json",
    "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": "这是第二段识别结果"
    }
  ]
}
```

## 模型对比

| 模型 | 速度 | 精度 | 适用场景 |
|------|------|------|----------|
| paraformer-zh | ⚡⚡⚡ | ⭐⭐⭐⭐ | 中文语音（推荐） |
| paraformer | ⚡⚡ | ⭐⭐⭐⭐ | 多语言识别 |
| sensevoice | ⚡ | ⭐⭐⭐⭐⭐ | 高精度多语言 |

## 完整示例

### 示例 1: 转录播客

```bash
python funasr.py --input podcast.mp3 --model paraformer-zh --background
```

### 示例 2: 生成视频识别结果

```bash
python funasr.py --input tutorial.mp4 --model paraformer
```

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

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

## 在 Workflow 中使用

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

```bash
# 步骤4: 下载视频后
# 步骤5: 使用 FunASR 生成识别结果
python funasr.py --input ${video_path} --model paraformer-zh --background

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

## 技术细节

- **引擎**: 阿里 FunASR
- **模型框架**: ModelScope
- **音频采样率**: 自动转换为 16kHz
- **语言**: 根据模型支持不同语言

## 故障排查

### 问题: 模型下载失败

```bash
# 首次运行会自动下载，确保网络稳定
python funasr.py --input test.mp4

# 手动检查缓存目录
ls ~/.cache/modelscope/hub/
```

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

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

### 问题: 依赖安装失败

```bash
# 使用清华镜像源
pip install funasr modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
```

## 性能参考

在 CPU 环境下（Intel i7）：

- **paraformer-zh 模型**: ~2x 实时速度（1分钟音频 ~30秒处理）
- **paraformer 模型**: ~1.5x 实时速度（1分钟音频 ~40秒处理）
- **sensevoice 模型**: ~1x 实时速度（1分钟音频 ~1分钟处理）

## 与 Whisper 对比

| 特性 | FunASR | Whisper |
|------|--------|---------|
| 中文识别 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 速度 | ⚡⚡⚡ | ⚡⚡ |
| 模型大小 | 较小 | 较大 |
| 多语言支持 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |

## 许可证

本技能使用 MIT 许可证，FunASR 使用 Apache 2.0 许可证。