# 文件转录功能如何使用

文件转录功能可以将音视频文件直接转为字幕或文本，支持批量处理。

---

## 一、准备工作

需要安装 [ffmpeg](环境依赖安装说明.md) 并确保其在系统 PATH 中。客户端启动日志 `logs/client_latest.log` 中显示 `[INFO] ffmpeg found` 即表示就绪。

---

## 二、使用方式

将音视频文件**直接拖拽**到 `start_client.exe` 图标上，松开即可开始转录。

支持批处理：可以同时选中多个文件一起拖拽。

支持格式：几乎所有常见音视频格式（mp3, wav, mp4, mkv, flv, avi, mov 等）。

---

## 三、输出结果

转录结果文件会保存在**原文件同目录**，与原文件同名，仅后缀不同：

| 文件 | 内容 | 默认 |
|------|------|------|
| `.srt` | SRT 格式字幕，时间轴精确到句 | 生成 |
| `.txt` | 按标点分行的纯文本，方便阅读 | 生成 |
| `.json` | 字级时间戳 | 生成 |
| `.merge.txt` | 未切分的整段文本（长文） | 不生成 |

例如对 `lecture.mp4` 转录，会在同目录生成 `lecture.srt`、`lecture.txt`、`lecture.json`。


## 四、进阶：手动修正字幕时间轴

如果识别结果有错字，或想调整分行，可以这样操作：

1. 打开生成的 `.txt` 文件，修改错字、调整分行
2. 将修改后的 `.txt` 文件**重新拖拽**到客户端
3. 客户端会利用 `.json` 中的字级时间戳，与修改后的文本重新对齐，生成新的 `.srt` 文件

这样就实现了**在保留原时间轴的基础上修正字幕内容**。

---

## 五、配置项

在 [`config_client.py](../config_client.py) 中：

```python
file_seg_duration = 60    # 转录时分段长度（秒），越大服务端内存占用越高
file_seg_overlap = 4      # 转录时分段重叠（秒），避免切分点丢字
file_save_srt = True      # 是否生成 srt 字幕
file_save_txt = True      # 是否生成 txt 分行文本
file_save_json = True     # 是否生成 json 时间戳
file_save_merge = False   # 是否生成 merge.txt（未切分长文）
```

一般不需要改动。

---

## 六、工作流程

```
拖拽文件到客户端
    ↓
检查 ffmpeg 环境
    ↓
ffmpeg 提取音频（16kHz、单声道、f32le）
    ↓
按 60 秒一段发送给服务端
    ↓
服务端 ASR 识别 → 时间戳对齐 → 拼接
    ↓
客户端接收结果 → 保存 srt/txt/json
```

---

## 七、常见问题

**Q: 转录结果时间轴不准确？**

- Qwen3-ASR 引擎需要配合 ForceAligner 模型才能生成精确时间戳，确认已下载该模型
- Fun-ASR-Nano 和 SenseVoice 自带时间戳能力

**Q: 能转录多长时间的音频？**

理论上不限时长，服务端会逐段处理。不排除超大文件会触发没有考虑到的 Bug。