打造带实时中间结果的听写应用:speech-swift 流式 ASR + VAD 句末检测实战指南
打造带实时中间结果的听写应用:speech-swift 流式 ASR + VAD 句末检测实战指南
用 speech-swift 打造真正的听写应用:说话时屏幕实时滚动出中间结果(partial transcript),说完一句自动定稿。本文以仓库自带的 DictateDemo 菜单栏听写 Demo 为蓝本,完整拆解「流式 ASR + VAD 句末检测」这套组合拳的工程实现,帮你在 Apple Silicon 上快速上手实时语音转写。
一、为什么听写应用要「流式 ASR + VAD」双管齐下?
传统批处理语音识别(Batch ASR)要等你说完整个文件才开始转写,延迟以秒计,完全不适合听写场景。一个合格的听写应用需要同时解决两个问题:
| 问题 | 解决手段 |
|---|---|
| ① 说话过程中如何立刻看到文字? | 流式 ASR(Streaming ASR)——按音频块增量解码,随时输出中间结果 |
| ② 用户什么时候「说完了」? | 句末检测(EOU, End-of-Utterance)——决定何时把中间结果变成定稿句子 |
speech-swift 的选择是:用 CoreML 加速的 Parakeet EOU 120M 流式模型(模型自带句末检测头),再叠加一个轻量的 Silero VAD 做外部兜底。两者互补,既不漏句也不重复句。
二、架构总览:麦克风到定稿文本的 4 步流水线
DictateDemo 的整体数据流非常清晰,核心代码都在 Examples/DictateDemo/ 目录:
- 采集:StreamingRecorder.swift 用 AVAudioEngine 捕获麦克风,统一转成 16kHz 单声道 Float32 音频流;
- 后台处理:DictateViewModel.swift 中的
ASRProcessor在独立队列上每 300ms 批量处理一次,主线程完全不被阻塞; - 双信号判定:模型内部 EOU 防抖 + VAD 静音计时,谁先确认「句末」谁就触发定稿;
- UI 更新:灰色显示中间结果,定稿句子以独立一行追加,支持一键粘贴到任意应用(
Cmd+Shift+V)。
三、第 1 步:16kHz 麦克风音频流
听写链路的一切约定都从采样率开始。ASR 模型和 VAD 模型都只认 16kHz,StreamingRecorder 内部用 AVAudioConverter 把麦克风硬件格式实时转换到目标格式,并通过回调把每个音频块交给处理器:
recorder.start { [proc] chunk in proc.appendAudio(chunk) }
它顺带计算 RMS 电平,驱动 HUD 上的音量指示器(见 DictateHUDView.swift)。
四、第 2 步:Parakeet EOU 流式会话
模型加载只需一行,首次运行会自动下载约 112MB 的 INT8 CoreML 权重(见 ParakeetStreamingASR.swift):
let model = try await ParakeetStreamingASRModel.fromPretrained()
let session = try model.createSession()
随后每个音频块喂给 pushAudio,返回一组 PartialTranscript:
| 字段 | 含义 |
|---|---|
text |
当前句到目前为止的转写文本 |
isFinal |
是否为定稿(检测到句末或流结束) |
confidence |
置信度 0.0–1.0 |
eouDetected |
是否由模型 EOU 头触发 |
有个对新手很友好的细节:你可以按任意大小推音频,StreamingSession.swift 内部会缓存样本,攒够一个编码块(640ms)才运行编码器,并自行处理帧重叠对齐——调用方完全不用管分块数学。
五、第 3 步:Silero VAD 的 512 样本分块
Silero VAD 是只有约 26 万参数的迷你模型(SileroVAD.swift),每次必须喂恰好 512 个样本(32ms @ 16kHz),且内部 LSTM 状态要跨块连续。麦克风音频块边界对不齐 512,所以要用「余量缓冲」模式:
// 每次调用:leftover + 新音频 → 按 512 切片喂给 VAD → 尾部不足 512 的留下次
let prob = vad.processChunk(Array(vadInput[offset..<offset+512]))
ASRProcessor 据此维护两个计数器:prob ≥ 0.5 判定为说话中(speechActive = true);连续 30 个静音块(约 960ms)才认为一句话真正结束了(DictateViewModel.swift#L35-L38)。
💡 这个 960ms 是刻意调过的:太短会截断句中停顿,太长则定稿显得迟钝。
六、第 4 步:双信号融合,不漏句也不重复句
句末判定有两条路,谁可靠用谁:
① 模型内部 EOU 头(带防抖) 联合网络的 EOU 分类有时会在说话含糊时「抢跑」,所以 StreamingSession.swift#L48 要求 EOU 信号持续 1280ms 且期间没有新 token 才确认定稿。缺点是:环境底噪、键盘声可能在「静音」间隙骗出 token,把防抖计时器反复清零,定稿延迟数秒。
② VAD 强制定稿(兜底)
当 VAD 确认人已经停了 960ms 而模型还没定稿时,直接调用 session.forceEndOfUtterance() 提交当前句子,同时保留编码器缓存和 LSTM 状态,下一句无缝继续流式解码。
防止两者打架的关键护栏(DictateViewModel.swift#L156-L158):
if partials.contains(where: { $0.isFinal }) {
hasPendingUtterance = false // 模型已定稿,跳过 VAD 强制定稿,避免重复句
}
完整的流式推理文档见 docs/inference/parakeet-streaming-asr-inference.md,VAD 细节见 docs/inference/silero-vad.md。
七、3 步跑通 DictateDemo
需要 macOS 15+ 与 Apple Silicon。仓库克隆地址:https://gitcode.com/gh_mirrors/sp/speech-swift
cd Examples/DictateDemo
swift build
.build/debug/DictateDemo
首次启动自动下载模型并预热;点击菜单栏麦克风图标或按 Cmd+Shift+D 开始听写,Cmd+Shift+V 粘贴结果。完整说明见 Examples/DictateDemo/README.md。
八、性能表现与调优参数速查
| 指标 | 数值 |
|---|---|
| 实时倍率 | 18× 实时(RTF ≈ 0.056) |
| 模型体积 | ~112MB(INT8 CoreML) |
| 中间结果延迟 | ~340ms(一个编码块) |
| 定稿延迟 | 停说后约 1s(VAD 路径) |
三个最值得调的参数:
eouDebounceMs(默认 1280ms):环境安静可调小,抢跑误断则调大;forceFinalizeSilentChunks(默认 30 块 ≈ 960ms):控制「停说多久算一句结束」;- 处理定时器周期(默认 300ms):每次 tick 触发 0–2 次编码调用,调小可进一步压低延迟。
九、新手避坑清单
- 菜单栏 UI 刷新陷阱:MenuBarExtra 弹出层会把主循环锁在 tracking 模式,
DispatchQueue.main派发会被饿死。Demo 用RunLoop.main.perform(inModes: <a href="https://link.gitcode.com/i/9b9d5bb0c5e5b21bd5ca98b7001a13a0" target="_blank">.common, .default, .eventTracking, .modalPanel])绕过([DictateViewModel.swift#L298-L299),做菜单栏语音应用时几乎必踩; - VAD 余量必须跨块携带:丢弃尾部不足 512 的样本会让 LSTM 状态断流,VAD 概率跳变;
- 开新一轮录音前调用
vad.resetState(),避免上一轮的 LSTM 状态泄漏; - 双路定稿务必加护栏,否则会出现同一句被提交两遍的经典 Bug。
这些坑都有回归测试覆盖,可参考 DictateDemoTests.swift 中的 testMultiUtteranceForceFinalize、testNoiseInSilenceDoesNotBlockFinalize 等用例。
十、关键文件导航
- 菜单栏听写应用:Examples/DictateDemo/
- 流式 ASR 模型与核心会话:Sources/ParakeetStreamingASR/
- Silero VAD 实现:Sources/SpeechVAD/SileroVAD.swift
- 音频采集/文件流工具:Sources/AudioCommon/AudioFileStream.swift
- 推理文档:docs/inference/parakeet-streaming-asr-inference.md、docs/inference/silero-vad.md
掌握这套「流式 ASR + VAD 句末检测」模式后,你可以把它直接迁移到会议记录、实时字幕、语音输入框等场景——替换 UI 层即可,音频处理管线基本不用动。