fork from MCP Video Extraction 
# MCP Video Extraction plus - 语音识别服务集成修改说明

## 概述

本次修改将项目的语音识别服务从仅支持 **Whisper（本地模型）** 扩展为支持三种方式：

1. **Whisper** - OpenAI 的本地语音识别模型（原有）
2. **JianYing (CapCut)** - 字节跳动简影/CapCut 的在线语音识别服务
3. **Bcut (B站剪辑)** - 哔哩哔哩剪辑的在线语音识别服务

## Overview

This update expands the project's speech recognition service from supporting only **Whisper (local model)** to supporting three methods:

1. **Whisper** – OpenAI's local speech recognition model (original)
2. **JianYing (CapCut)** – ByteDance's JianYing/CapCut online speech recognition service
3. **Bcut (Bilibili Cut)** – Bilibili's online speech recognition service
   
## 新增文件

### 核心 ASR 模块

| 文件                                             | 说明                                    |
| ------------------------------------------------ | --------------------------------------- |
| `src/mcp_video_service/services/asr_data.py`     | ASR 数据结构定义（ASRDataSeg、ASRData） |
| `src/mcp_video_service/services/status.py`       | ASR 任务状态枚举                        |
| `src/mcp_video_service/services/base_asr.py`     | 基础 ASR 抽象类，所有 ASR 实现的父类    |
| `src/mcp_video_service/services/jianying_asr.py` | 简影（CapCut）语音识别实现              |
| `src/mcp_video_service/services/bcut_asr.py`     | B站剪辑（Bcut）语音识别实现             |
| `src/mcp_video_service/services/__init__.py`     | Services 包初始化文件                   |

## 修改的文件

### 1. `src/mcp_video_service/services/video_service.py`

**主要改动：**

- 添加 ASR 提供者配置支持（`asr_provider`）
- 修改 `__init__` 方法，支持从配置文件读取 ASR 提供者选择
- 新增 `_create_asr_instance()` 方法，根据配置创建对应的 ASR 实例
- 修改 `extract_text()` 方法，支持多种 ASR 提供者
  - 如果选择 Whisper，使用本地模型
  - 如果选择 JianYing 或 Bcut，调用在线 API
- 添加导入语句，支持相对导入和绝对导入兼容

**配置参数：**

```python
self.config = {
    'asr': {
        'provider': 'whisper',  # 可选: whisper, jianying, bcut
        'use_cache': False,
        'need_word_time_stamp': False,
    },
    'jianying': {
        'start_time': 0,
        'end_time': 6000,
    },
    # ... 其他配置
}
```

### 2. `config.yaml`

**新增配置项：**

```yaml
# ASR（自动语音识别）提供者配置
asr:
  provider: "whisper"  # 可选: whisper, jianying, bcut
  use_cache: false
  need_word_time_stamp: false

# JianYing (CapCut) 语音识别配置
jianying:
  start_time: 0      # 音频开始时间（毫秒）
  end_time: 6000     # 音频结束时间（毫秒）

# Bcut (B站剪辑) 语音识别配置
# 暂无特殊配置，使用默认值
```

## 使用方式

### 1. 使用 Whisper（本地模型，默认）

```python
from mcp_video_service.services.video_service import VideoService

service = VideoService(config_path='config.yaml')
# config.yaml 中设置: asr.provider = "whisper"

text = await service.extract_text('audio.mp3')
```

### 2. 使用 JianYing（在线服务）

```python
# 修改 config.yaml
# asr:
#   provider: "jianying"
#   use_cache: false
#   need_word_time_stamp: false
# jianying:
#   start_time: 0
#   end_time: 6000

service = VideoService(config_path='config.yaml')
text = await service.extract_text('audio.mp3')
```

### 3. 使用 Bcut（在线服务）

```python
# 修改 config.yaml
# asr:
#   provider: "bcut"
#   use_cache: true
#   need_word_time_stamp: false

service = VideoService(config_path='config.yaml')
text = await service.extract_text('audio.mp3')
```

### 4. 通过环境变量配置

```bash
# 使用 JianYing
export ASR_PROVIDER=jianying
export ASR_USE_CACHE=false
export JIANYING_START_TIME=0
export JIANYING_END_TIME=6000

# 使用 Bcut
export ASR_PROVIDER=bcut
export ASR_USE_CACHE=true
```

## 架构设计

### 类继承关系

```
BaseASR (抽象基类)
├── JianYingASR
├── BcutASR
└── VideoService (使用 Whisper 时直接调用 whisper.load_model)
```

### BaseASR 的主要特性

- **统一接口**：所有 ASR 实现都继承自 `BaseASR`
- **缓存支持**：通过 CRC32 校验和生成缓存键
- **速率限制**：内置速率限制机制，防止 API 过载
- **进度回调**：支持异步进度回调函数
- **错误处理**：统一的错误处理和日志记录

## 数据结构

### ASRDataSeg（分段数据）

```python
@dataclass
class ASRDataSeg:
    text: str          # 分段文本
    start_time: float  # 开始时间（毫秒）
    end_time: float    # 结束时间（毫秒）
```

### ASRData（完整数据）

```python
@dataclass
class ASRData:
    text: str                    # 完整文本
    segments: List[ASRDataSeg]   # 分段列表
```

## 状态管理

ASR 任务的状态通过 `ASRStatus` 枚举管理：

| 状态            | 进度 | 说明       |
| --------------- | ---- | ---------- |
| UPLOADING       | 20   | 上传中     |
| SUBMITTING      | 40   | 提交中     |
| QUERYING_RESULT | 60   | 查询结果中 |
| CREATING_TASK   | 40   | 创建任务中 |
| TRANSCRIBING    | 60   | 转录中     |
| COMPLETED       | 100  | 已完成     |

## 导入兼容性

所有新增的 ASR 模块都支持**相对导入**和**绝对导入**的双重兼容：

```python
# 相对导入（在包内使用）
from .asr_data import ASRDataSeg
from .base_asr import BaseASR

# 绝对导入（直接加载模块时使用）
from asr_data import ASRDataSeg
from base_asr import BaseASR
```

这确保了模块在不同的导入场景下都能正常工作。

## 依赖项

### 新增依赖

- `requests` - 用于 HTTP 请求（JianYing 和 Bcut API）

### 现有依赖

- `yt-dlp` - 视频下载
- `whisper` - 本地语音识别（仅在使用 Whisper 时需要）
- `pyyaml` - 配置文件解析

## 环境变量支持

| 环境变量              | 说明                  | 默认值  |
| --------------------- | --------------------- | ------- |
| `ASR_PROVIDER`        | ASR 提供者            | whisper |
| `ASR_USE_CACHE`       | 是否使用缓存          | false   |
| `ASR_WORD_TIME_STAMP` | 是否需要词级时间戳    | false   |
| `JIANYING_START_TIME` | JianYing 音频开始时间 | 0       |
| `JIANYING_END_TIME`   | JianYing 音频结束时间 | 6000    |
| `WHISPER_MODEL`       | Whisper 模型大小      | base    |
| `WHISPER_LANGUAGE`    | Whisper 语言          | auto    |

## 向后兼容性

本次修改完全向后兼容：

- 默认 ASR 提供者为 `whisper`，保持原有行为
- 原有的 `extract_text()` 接口保持不变
- 所有新增功能都是可选的

## 测试验证

所有新增模块已通过以下验证：

- ✓ Python 语法检查
- ✓ 模块导入测试
- ✓ 类继承关系验证
- ✓ 配置文件解析测试

## 后续扩展

该架构支持轻松添加新的 ASR 提供者：

1. 创建新类继承 `BaseASR`
2. 实现 `_run()` 和 `_make_segments()` 方法
3. 在 `VideoService._create_asr_instance()` 中添加条件分支
4. 在 `config.yaml` 中添加相应配置项

## 许可证

保持原项目许可证不变。