realTimeVTT/docs/使用说明.md

# 实时语音转文字系统使用说明

## 项目简介

本项目是一个基于 sherpa-onnx 的实时语音转文字系统，支持中英双语识别，具有端点检测、断句处理和自动标点功能。系统采用流式识别技术，能够实时将语音转换为文字，并支持部分识别结果显示。

## 系统要求

- **操作系统**: macOS / Linux
- **Python版本**: >= 3.12.10
- **包管理工具**: uv
- **音频设备**: 支持录音的麦克风

## 安装步骤

### 1. 克隆项目

```bash
git clone <项目地址>
cd realTimeVTT
```

### 2. 安装依赖

使用 uv 安装项目依赖：

```bash
uv sync
```

### 3. 下载语音识别模型

首次使用需要下载语音识别模型：

```bash
uv run python main.py --download-model
```

系统会提供交互式界面，选择合适的模型进行下载。推荐使用默认的中英双语模型。

## 基本使用

### 启动实时语音识别

```bash
uv run python main.py
```

启动后，系统会：
1. 初始化音频设备
2. 加载语音识别模型
3. 开始实时录音和识别
4. 在控制台显示识别结果
5. 将结果保存到 `output/transcription.txt` 文件

### 查看可用音频设备

```bash
uv run python main.py --list-devices
```

### 启用调试模式

```bash
uv run python main.py --log-level DEBUG
```

## 命令行参数

| 参数 | 说明 |
|------|------|
| `--download-model` | 下载语音识别模型 |
| `--list-devices` | 列出可用的音频设备 |
| `--log-level` | 设置日志级别 (DEBUG/INFO/WARNING/ERROR) |
| `--no-save` | 不保存识别结果到文件 |
| `--no-partial` | 不显示部分识别结果 |

## 功能特性

### 1. 实时语音识别
- 支持中英双语识别
- 流式处理，低延迟
- 自动端点检测

### 2. 断句和标点处理
- 智能断句识别
- 自动添加标点符号
- 支持中英文混合文本

### 3. 结果输出
- 控制台实时显示
- 自动保存到文件
- 支持时间戳显示

### 4. 音频处理
- 自动音频设备检测
- 噪声抑制
- 音量自动调节

## 配置说明

### 模型配置 (src/config.py)

```python
class ModelConfig:
    # 模型文件路径
    model_dir = "models/"
    
    # 语音识别参数
    sample_rate = 16000      # 采样率
    feature_dim = 80         # 特征维度
    num_threads = 1          # 线程数
    
    # 端点检测参数
    enable_endpoint = True
    rule1_min_trailing_silence = 2.4  # 静音检测阈值1
    rule2_min_trailing_silence = 1.2  # 静音检测阈值2
    rule3_min_utterance_length = 300  # 最小语音长度
```

### 音频配置

```python
class AudioConfig:
    sample_rate = 16000      # 采样率
    chunk_size = 1024        # 音频块大小
    channels = 1             # 单声道
    samples_per_read = 1600  # 每次读取样本数
```

### 应用配置

```python
class AppConfig:
    show_partial_results = True   # 显示部分识别结果
    show_timestamps = True        # 显示时间戳
    save_to_file = True          # 保存到文件
    output_file = "output/transcription.txt"  # 输出文件路径
```

## 使用示例

### 基本使用流程

1. **启动系统**
   ```bash
   uv run python main.py
   ```

2. **开始说话**
   - 系统会自动检测语音输入
   - 实时显示识别结果
   - 自动进行断句和标点处理

3. **查看结果**
   - 控制台实时显示
   - 结果自动保存到 `output/transcription.txt`

4. **停止识别**
   - 按 `Ctrl+C` 停止程序

### 高级使用

**仅显示最终结果（不显示部分识别）**
```bash
uv run python main.py --no-partial
```

**不保存到文件**
```bash
uv run python main.py --no-save
```

**调试模式**
```bash
uv run python main.py --log-level DEBUG
```

## 输出格式

### 控制台输出
```
[14:30:25] 你好，这是一个测试。
[14:30:28] 语音识别效果很好。
[14:30:32] 支持中英文混合识别，Hello world!
```

### 文件输出
识别结果会保存到 `output/transcription.txt` 文件中，格式与控制台输出相同。

## 故障排除

### 常见问题

1. **模型文件缺失**
   ```
   错误: 缺少模型文件
   ```
   **解决方案**: 运行 `uv run python main.py --download-model` 下载模型

2. **音频设备初始化失败**
   ```
   错误: 无法初始化音频设备
   ```
   **解决方案**: 
   - 检查麦克风是否正常连接
   - 运行 `--list-devices` 查看可用设备
   - 确保系统音频权限已授予

3. **识别效果不佳**
   **解决方案**:
   - 确保环境安静
   - 调整麦克风音量
   - 保持适当的说话距离

4. **依赖安装失败**
   **解决方案**:
   - 确保使用 Python 3.12+
   - 在 macOS 上可能需要安装 portaudio: `brew install portaudio`
   - 使用 `uv sync --reinstall` 重新安装依赖

### 日志查看

启用调试日志查看详细信息：
```bash
uv run python main.py --log-level DEBUG
```

日志文件保存在 `logs/app.log`

## 性能优化

### 系统性能
- 建议在安静环境下使用
- 确保系统有足够的内存（建议 4GB+）
- 使用 SSD 存储以提高模型加载速度

### 识别精度
- 清晰发音，语速适中
- 避免背景噪音
- 保持麦克风距离适中（20-30cm）

## 开发说明

### 项目结构
```
.
├── main.py                 # 主程序入口
├── src/
│   ├── __init__.py
│   ├── config.py           # 配置管理
│   ├── audio_processor.py  # 音频处理
│   ├── speech_recognizer.py # 语音识别
│   ├── realtime_vtt.py     # 主应用逻辑
│   └── model_downloader.py # 模型下载
├── models/                 # 模型文件目录
├── output/                 # 输出文件目录
├── logs/                   # 日志文件目录
└── docs/                   # 文档目录
```

### 扩展开发

如需扩展功能，可以：
1. 修改 `src/config.py` 调整参数
2. 在 `src/speech_recognizer.py` 中添加新的识别逻辑
3. 在 `src/realtime_vtt.py` 中添加新的应用功能

## 许可证

本项目遵循开源许可证，具体请查看 LICENSE 文件。

## 技术支持

如遇到问题，请：
1. 查看本使用说明
2. 检查日志文件
3. 提交 Issue 到项目仓库

---

**注意**: 首次使用请务必先下载模型文件，否则无法正常运行。