FireRedASR2S GUI

FireRedASR2S GUI 是一个独立 Git 仓库管理的 Windows 桌面应用，使用 PySide6/Qt Widgets 提供模型管理、音视频转写、任务队列、历史记录和多格式导出。 推理运行在独立子进程中，模型加载后会持续复用，卸载模型或退出程序时由操作系统 完整回收 CPU 内存和 CUDA 显存。

本 GUI 不能只配合官方原版 FireRedASR2S 源码运行。它依赖 jyeric/FireRedASR2S 中的修改，包括：

• 有界长音频滑动缓存：600 秒核心窗，前后各 30 秒 VAD 上下文；
• 相邻窗口复用重叠 PCM，只读取和上传新的尾部；
• Torch/CUDA 原生 Kaldi-compatible FBank 和 CMVN；
• ASR、VAD、LID 复用 GPU 音频切片；
• BF16 时间戳对齐兼容、LID 半精度稳定性和 Punc FP16；
• LID 结果按 uttid 对齐，异常时不丢失 ASR 片段。

功能

• 支持 WAV、MP3、FLAC、M4A、AAC、OGG、WMA、MP4、MKV、MOV、AVI 和 WebM；
• 使用 FFmpeg 转换为 FireRedASR2S 所需的 16 kHz、16-bit、单声道 PCM WAV；
• 支持 FireRedASR2-AED、FireRedASR2-LLM、FireRedVAD、FireRedLID 和 FireRedPunc；
• 支持本地模型登记，以及从 ModelScope/Hugging Face 下载官方模型；
• 支持 FP32、FP16、BF16 和自动半精度；
• 支持任务取消且不卸载已经驻留的模型；
• 支持 TXT、SRT、ASS、JSON、JSONL 和 TextGrid 导出；
• 使用 SQLite 保存配置、模型记录、任务历史和转写结果。

仓库布局

两个仓库必须采用下面的父子目录布局：

fireredasr/
├─ fireredasr2s/                 # 修改版 FireRedASR2S Python 包
├─ assets/
├─ pretrained_models/
├─ requirements.txt
├─ .venv/
└─ GUI/                          # 本仓库
   ├─ src/fireredasr_gui/
   ├─ tests/
   ├─ packaging/
   ├─ run_gui.ps1
   └─ run_tests.ps1

GUI 的启动、测试和打包脚本会把父目录作为 FireRedASR2S 源码根目录，并默认使用 父目录中的 .venv。如果把两个仓库放在互不相关的目录，内置脚本将无法找到修改版 FireRedASR2S。

环境要求

当前经过验证的源码运行环境：

• Windows 10/11 x64；
• Python 3.10.11；
• NVIDIA GPU 和 CUDA 11.8 兼容驱动，或使用 CPU 模式；
• PyTorch 2.1.0+cu118；
• torchaudio 2.1.0+cu118；
• Transformers 4.51.3；
• PySide6 Essentials / Qt 6.11.1；
• FFmpeg，可通过 ffmpeg -version 在终端找到。

CPU 模式可以启动和推理，但大型 AED/LLM 模型会非常慢。使用 CUDA 前请先确认：

nvidia-smi
ffmpeg -version

从零搭建源码环境

1. 通过 SSH 检出两个仓库

git clone git@github.com:jyeric/FireRedASR2S.git fireredasr
git clone git@github.com:jyeric/FireRedASR2S-GUI.git fireredasr\GUI
Set-Location fireredasr

如果尚未配置 GitHub SSH 密钥，可先验证：

ssh -T git@github.com

2. 创建共享虚拟环境

py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel

如果 PowerShell 禁止执行激活脚本，可以不激活环境，后续直接使用 .\.venv\Scripts\python.exe。

3. 安装 FireRedASR2S 运行依赖

仓库根目录的 requirements.txt 是当前 GUI 验证过的 CUDA 11.8 组合：

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

CPU-only 环境应按照 PyTorch 官方说明先安装匹配的 CPU 版 torch/torchaudio， 然后安装 requirements.txt 中的其余依赖，避免再次覆盖 PyTorch。

4. 安装 GUI 和模型下载依赖

.\.venv\Scripts\python.exe -m pip install -e .\GUI
.\.venv\Scripts\python.exe -m pip install modelscope huggingface_hub

真实 LLM 模型还会使用 peft；它已包含在根目录 requirements.txt 中。

5. 验证关键导入

.\.venv\Scripts\python.exe -c "import torch, torchaudio, transformers, PySide6; import fireredasr2s; print(torch.__version__, torch.cuda.is_available())"

期望输出 PyTorch 版本，并在 CUDA 环境中显示 True。

模型准备

可以在 GUI 的“模型”页面从 ModelScope 或 Hugging Face 下载，也可以手工放置：

pretrained_models/
├─ FireRedASR2-AED/
│  ├─ cmvn.ark
│  ├─ model.pth.tar
│  ├─ dict.txt
│  └─ train_bpe1000.model
├─ FireRedVAD/
│  └─ VAD/
├─ FireRedLID/
└─ FireRedPunc/

LLM 模型除 AED 公共文件外，还需要 asr_encoder.pth.tar 和完整的 Qwen2-7B-Instruct 配置、分词器及权重。模型权重不会提交到 Git，也不会进入 PyInstaller/MSI 发布包。

启用 VAD、LID 或 Punc 后，加载流水线时必须选择对应模型。低于 12 GB 显存时：

• “自动”设备模式会把 LID/Punc 放到 CPU，仅让 ASR/VAD 使用 GPU；
• 明确选择 CUDA 且使用非 FP32 ASR 时，LID/Punc 会使用 FP16；
• 建议 ASR 批大小从 1 开始逐步测试。

从源码运行

在 FireRedASR2S 根目录执行：

.\GUI\run_gui.ps1

脚本执行以下操作：

1. 使用父目录 .venv；
2. 将 GUI/src 和 FireRedASR2S 根目录加入 PYTHONPATH；
3. 验证 PySide6；
4. 运行 python -m fireredasr_gui。

也可以手工启动：

$env:PYTHONPATH = "$PWD\GUI\src;$PWD"
.\.venv\Scripts\python.exe -m fireredasr_gui

用户数据默认写入：

%LOCALAPPDATA%\FireRedASR2S-GUI

可临时指定其他目录：

$env:FIREREDASR_GUI_DATA_DIR = "D:\FireRedASR2S-GUI-Data"
.\GUI\run_gui.ps1

长音频与 GPU 数据路径

输入首先由 FFmpeg 转换为临时 PCM WAV。启用 VAD 时，核心流水线维护：

• 600 秒核心窗口；
• 前后各 30 秒上下文；
• 最大约 660 秒的 int16 CPU/GPU 音频缓存；
• 相邻窗口复用约 60 秒重叠区；
• 后台预读取新的尾部。

跨越 600 秒边界的语音在相邻分析窗中都可见，但根据语音段中点只归属一个核心窗， 因此完整转写一次。ASR、VAD 和 LID 直接使用缓存张量的切片，GPU FBank/CMVN 不会为相同音频重复计算或往返上传。

测试

运行不加载真实大模型的完整测试：

.\GUI\run_tests.ps1

测试包含：

• 配置、任务状态、SQLite 和导出；
• Qt 离屏界面；
• 后端进程加载、取消和卸载；
• 滑动窗口边界与磁盘读取复用；
• CPU/GPU FBank 一致性和缓存生命周期；
• LID/beam-search 半精度稳定性；
• PyInstaller 运行时和 MSI 结构。

运行真实模型集成测试：

$env:FIREREDASR_RUN_INTEGRATION = "1"
.\GUI\run_tests.ps1
Remove-Item Env:FIREREDASR_RUN_INTEGRATION

真实测试会加载本地权重，并可能占用大量 RAM/显存。

构建 Windows onedir 发布包

安装构建工具并确认 FFmpeg 在 PATH：

.\.venv\Scripts\python.exe -m pip install "pyinstaller>=6,<7"
Set-Location GUI
.\build_binary.ps1 `
  -DistRoot D:\FireRedASR2S-GUI-Release `
  -WorkRoot D:\FireRedASR2S-GUI-build

构建脚本会：

• 生成 FireRedASR2S-GUI.exe 和 _internal；
• 收集修改版 FireRedASR2S、Torch、Transformers、Qt 和 FFmpeg；
• 排除模型权重；
• 禁止 Python 优化，避免 kaldiio 二进制矩阵读取失效；
• 执行 --runtime-check；
• 附带 GUI Unlicense、FireRedASR2S Apache-2.0 和第三方声明；
• 生成 SHA256 与构建信息。

构建 MSI

先生成 onedir，再执行：

.\build_installer.ps1 `
  -ReleaseRoot D:\FireRedASR2S-GUI-Release\FireRedASR2S-GUI `
  -OutputRoot D:\FireRedASR2S-GUI-Installer

MSI 和同目录下的 data*.cab 共同组成安装包，不能只分发 MSI。输出目录还包含 INSTALLER-SHA256.txt，用于校验所有分卷。

常见问题

ModuleNotFoundError: fireredasr2s

确认 GUI 位于修改版 FireRedASR2S 的 GUI/ 子目录，并从父目录执行 .\GUI\run_gui.ps1。

PySide6 is not installed

.\.venv\Scripts\python.exe -m pip install -e .\GUI

找不到 FFmpeg

把 ffmpeg.exe 所在目录加入 PATH，重新打开 PowerShell 后运行：

ffmpeg -version

CUDA 不可用

检查 NVIDIA 驱动、PyTorch CUDA 构建和驱动支持的 CUDA 版本：

nvidia-smi
.\.venv\Scripts\python.exe -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

8 GB GPU 显存不足

优先使用自动半精度、ASR 批大小 1，并让自动设备模式把 LID/Punc 放到 CPU。 四个模型全部以 FP32 常驻时，权重本身就可能超过 8 GB。

许可证

GUI 项目自身代码使用根目录 LICENSE 中的 The Unlicense。这不改变任何第三方组件的许可证。

修改版 FireRedASR2S 继续使用 Apache License 2.0。源码和二进制发布中的归属、 修改声明及第三方许可关系见 THIRD_PARTY_NOTICES.md。打包产物会同时包含：

LICENSE
THIRD_PARTY_NOTICES.md
licenses/FireRedASR2S-Apache-2.0.txt

其他打包依赖继续受其各自许可证约束。