打造带实时中间结果的听写应用:speech-swift 流式 ASR + VAD 句末检测实战指南

原创2026-10-13 22:45:171,461 阅读

打造带实时中间结果的听写应用: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/ 目录:

  1. 采集:StreamingRecorder.swift 用 AVAudioEngine 捕获麦克风,统一转成 16kHz 单声道 Float32 音频流;
  2. 后台处理:DictateViewModel.swift 中的 ASRProcessor 在独立队列上每 300ms 批量处理一次,主线程完全不被阻塞;
  3. 双信号判定:模型内部 EOU 防抖 + VAD 静音计时,谁先确认「句末」谁就触发定稿;
  4. 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 等用例。

十、关键文件导航

掌握这套「流式 ASR + VAD 句末检测」模式后,你可以把它直接迁移到会议记录、实时字幕、语音输入框等场景——替换 UI 层即可,音频处理管线基本不用动。

登录后查看全文
speech-swift