如何 10 分钟跑通 SimulStreaming:新手从音频文件到实时语音转文字的完整入门教程
如何 10 分钟跑通 SimulStreaming:新手从音频文件到实时语音转文字的完整入门教程
SimulStreaming 是一个开源的**实时语音转文字(流式 Speech-to-Text)**工具,它能让 Whisper 语音识别和 LLM 大模型以"边说边出字"的方式工作,支持 99 种源语言转写、35 种欧洲语言翻译,并且在 IWSLT 2025 同声传译任务中取得最佳成绩。本文将带你用 10 分钟完成从环境安装、音频文件转文字,到连接麦克风实时听写的完整流程。
一、SimulStreaming 能做什么?
一句话概括:把"离线大模型"变成"实时流式"工具。
| 能力 | 说明 |
|---|---|
| 📝 实时转写 | 基于 Whisper large-v3,音频边输入边输出文字,无需等待整段录音 |
| 🌐 多语言 | 支持 99 种 Whisper 源语言,--task translate 可直接翻译成英文 |
| 🔀 级联 LLM 翻译 | Whisper 转文字 + EuroLLM 翻译,覆盖 35 种目标语言 |
| ⚡ 低延迟 | 采用 AlignAtt 同声策略,比前作 WhisperStreaming 快约 5 倍 |
| 🎤 麦克风实时 | 自带 TCP 服务器模式,可直接接麦克风输入 |
下图展示了项目支持的多种语言方向(IWSLT 2025 使用的 4 个示例方向):
核心概念只有一个:simultaneous policy(同声策略)。Whisper 原本要听完整个 30 秒窗口才输出,SimulStreaming 通过 AlignAtt 注意力机制判断"现在解码到哪一帧是安全的",从而在音频流式到达时就逐句吐字,同时几乎不损失离线模型的质量。
二、安装步骤:3 分钟准备环境
1. 获取项目代码
git clone https://gitcode.com/gh_mirrors/si/SimulStreaming
cd SimulStreaming
2. 安装语音转文字组件依赖
pip install -r requirements_whisper.txt
依赖清单(requirements_whisper.txt)很精简:torch、torchaudio、librosa、tiktoken、tqdm、triton。
💡 轻量安装:如果你不用 Silero VAD 的语音活动检测(
--vac参数),可以删掉torchaudio,安装会更轻。
3. 硬件要求
- 推荐:至少 10G 显存的 GPU,用于跑 1.5B 参数的 Whisper large-v3 模型
- CPU 也可以运行,但速度无法满足实时场景,只适合功能验证
三、一键运行:从音频文件到实时转文字
准备好一个 16kHz、单声道 wav 音频文件(这是 Whisper 的标准输入格式),然后在项目根目录执行:
python3 simulstreaming_whisper.py audio.wav --language en --task transcribe --comp_unaware --vac
入口脚本是 simulstreaming_whisper.py,核心参数解读:
| 参数 | 作用 | 新手建议值 |
|---|---|---|
--language |
源语言代码,如 en、de、cs,auto 自动检测 |
en |
--task |
transcribe 转写 / translate 翻译成英文 |
transcribe |
--comp_unaware |
计算无感知模拟:计时器在模型计算时暂停,只体现模型本身延迟 | 新手推荐,延迟表现最"理想化" |
--vac |
启用语音活动控制器(VAC),自动跳过无声段落 | 推荐开启 |
--model_path |
Whisper 模型路径,默认 ./large-v3.pt,不存在会自动下载 |
用默认即可 |
--min-chunk-size |
每次处理的最小音频块(秒),越大质量越高但延迟越大 | 用默认即可 |
--out-txt |
输出人类可读的纯文本格式而非 JSONL | 调试时用 |
⏱️ 第一次运行会自动下载 large-v3 模型(约数 GB),请耐心等待下载完成后程序才开始逐行输出文字。
运行效果:命令会模拟实时流地播放你的音频文件,每处理一块就打印一行结果——就像真人听写员边听边写。
四、看懂实时输出:JSONL 逐行结果解析
默认输出是 JSONL(每行一个 JSON),每来一行就是一个增量更新:
{"start": 0.332, "end": 0.832, "text": " And so,", "words": [{"start": 0.332, "end": 0.332, "text": " And"}, ...], "is_final": false, "emission_time": 2.246}
关键字段速查:
| 字段 | 含义 |
|---|---|
start / end |
这段文字对应的源音频时间戳(秒) |
text |
本次更新新增的部分文字(增量,不是全文) |
words |
词级别时间戳,适合做字幕对齐 |
is_final |
开启 --vac 时,表示该有声段落已结束 |
emission_time |
输出产生时刻的模拟时间(秒),可用来计算延迟 |
拼接所有 text 字段,就是完整的实时转写文本。想要更直白的调试格式,加上 --out-txt:
2246.5429 332 832 And so,
3468.0274 1032 1712 my fellow Americans
每行前三列分别是输出时间、起止时间戳(毫秒),后面是文字。
五、进阶:连接麦克风,实现真正实时语音转文字
文件模拟跑通后,只需换一个入口脚本就能接真实麦克风。启动服务器:
python3 simulstreaming_whisper_server.py --language en --task transcribe --vac --port 43001
服务器入口 simulstreaming_whisper_server.py 相比文件版多了 --host / --port 和 --warmup-file(预热音频,避免第一块音频处理过慢)参数。
然后在另一个终端用 Linux 录音管道把麦克风音频推给服务器:
arecord -f S16_LE -c1 -r 16000 -t raw -D default | nc localhost 43001
arecord 负责以 16kHz 单声道采集声音,nc(netcat)把原始音频流转发到 43001 端口——此时你开口说话,服务器就开始实时转写。Windows / Mac 用户可以用 ffmpeg 替代 arecord 采集设备音频。
六、可选玩法:级联 LLM,语音直达目标语言
如果不止要转写,还要"同声传译"(例如英语 → 德语),安装翻译组件依赖 requirements_translate.txt 并准备 CTranslate2 格式的 LLM(官方示例是 EuroLLM-9B-Instruct),然后两步流水线:
# 第一步:音频 → 实时转写文本(jsonl)
python3 simulstreaming_whisper.py audio.wav --language en --task transcribe --comp_unaware --vac > output.jsonl
# 第二步:转写文本 → 实时翻译
python3 simulstreaming_translate.py --src-lang en --tgt-lan de --comp_unaware --input-jsonl output.jsonl
翻译入口 simulstreaming_translate.py 内部使用 LocalAgreement 策略:确认连续两次更新输出的最长公共前缀作为定稿文字,text 是已确认文本,unconfirmed_text 是可能仍会变化的暂定文本,前端展示时两者可分开渲染。
七、常见问题排查(FAQ)
| 问题 | 原因与解决 |
|---|---|
| 首次运行卡住不动 | 正在自动下载 large-v3.pt 模型,属正常现象,可提前手动放置到 --model_path 指定位置 |
| CPU 上跑不动 / 太慢 | 实时场景需要 GPU(≥10G 显存);CPU 只建议用于短音频功能验证 |
| 提示音频格式问题 | 输入必须是 16kHz 单声道 wav,可用 ffmpeg 转码:ffmpeg -i in.mp3 -ar 16000 -ac 1 out.wav |
| 想去掉 VAC 依赖 | 安装时移除 torchaudio 并去掉 --vac 参数 |
| 想回放已保存的 jsonl 调试 | 使用仓库自带工具 tools/replay-jsonl.py |
八、项目目录速览
| 路径 | 说明 |
|---|---|
| simulstreaming_whisper.py | 文件模拟实时转写的入口脚本 |
| simulstreaming_whisper_server.py | 麦克风 TCP 服务器入口 |
| simulstreaming_translate.py | LLM 实时翻译入口 |
| simulstreaming/whisper/ | Whisper 语音转文字核心(含 Simul-Whisper 与 WhisperStreaming 的融合实现) |
| simulstreaming/translate/ | LLM 翻译核心(LocalAgreement 策略、句子切分) |
| simulstreaming/utils/ | 两个组件共享的服务器与行包工具 |
| tools/ | jsonl 回放等调试工具 |
总结
按本文流程走一遍,你大约需要:克隆仓库 1 分钟、安装依赖 3 分钟、等待模型下载 3~5 分钟(视网络)、运行首条命令 1 分钟。跑通文件模拟后,再换一行命令就能接上麦克风做真正的实时语音转文字。SimulStreaming 的设计非常克制——服务器 + 文件模拟两种输入方式、JSONL 统一输出、组件可独立部署,这让它既适合新手快速上手,也适合作为生产级流式语音管道的一个模块来集成。
