Handy 0.9.0 升级指南：transcribe.cpp 引擎、流式实时转录与新一代离线语音模型-平芜编程栈

桌面应用
语音
音频
AI 应用
本地部署

【免费下载链接】Handy

A free, open source, and extensible speech-to-text application that works completely offline.

项目地址：https://gitcode.com/GitHub_Trending/handy11/Handy

导读

Handy 是一款完全离线运行、免费开源的语音转文字（Speech-to-Text）桌面应用。0.9.0 版本是自项目诞生以来最重要的一次架构级升级：transcribe.cpp 取代旧引擎成为全应用的主要转录引擎，并由此解锁了「边说边出字」的流式转录、新一代模型家族支持，以及配套的实时转录浮层（Overlay）。读完本文，你将了解 0.9.0 的核心变化、流式转录的底层工作方式、如何在新旧模型之间做选择，以及 Legacy 模型未来的弃用路径与升级方法。

transcribe.cpp：新的主要转录引擎

0.9.0 发布说明的核心声明是：transcribe.cpp 现在成为 Handy 全应用的主要转录引擎。这一替换带来了两个直接结果：

更快的转录速度——对绝大多数用户而言，转录耗时显著缩短；
新能力的基础——流式转录、模型能力自动探测等新特性都建立在这套引擎之上。

从源码可以印证这一架构事实。在 Cargo.toml 中，transcribe-cpp以版本0.2.4作为核心依赖（默认关闭所有 feature，按平台在目标表中分别开启），而transcribe-rs被明确注释为ONNX-only：

# Whisper-family models run through transcribe-cpp (GGUF/ggml, native backends); # transcribe-rs is now ONNX-only (Parakeet, Moonshine, SenseVoice, GigaAM, # Canary, Cohere). Per-platform backend features are added in the target tables. transcribe-rs = { version = "0.3.8", features = ["onnx"] } transcribe-cpp = { version = "0.2.4", default-features = false }

平台相关后端同样在 Cargo.toml 的目标表中声明：

macOS：features = ["metal"]，走 Metal 后端；
Linux：features = ["dynamic-backends", "vulkan"]，支持 Vulkan GPU 加速；
Windows x86_64：features = ["dynamic-backends", "vulkan"]；
Windows aarch64：静态链接纯 CPU 后端（不带任何额外 feature）。

在 model.rs 中，EngineType枚举的第一个变体即TranscribeCpp，其注释写明：任何通过 transcribe-cpp 加载的 GGML/GGUF 模型（Whisper、Parakeet、Voxtral、Qwen3-ASR、Nemotron 等）都归入这一个变体，模型架构在加载时从文件自动检测，因此一个变体即可覆盖整个 transcribe-cpp 家族。

流式转录：边说边出字

0.9.0 最重要的新功能是native streaming（原生流式）模型支持：在说话的同时就能看到转录文本实时生成，且使用流式模型时转录通常也会更快完成。

发布说明特别推荐了两款流式模型：

Parakeet Unified（英语）——面向英语使用者的流式模型；
Nemotron Streaming 3.5（多语言）——面向多语言使用者的流式模型。

流式转录的底层实现

从 transcription.rs 可以看到流式转录的完整设计。核心组件是StreamRouter：它持有音频录制器与流式工作线程之间的命令通道，录音的每一帧音频经feed()转发给流式工作线程；当没有流式会话时，feed()只是一个宽松原子读的廉价空操作，不会引入锁开销。

流式会话的生命周期围绕StreamCmd展开，三种命令通过同一通道传递，保证 FIFO 顺序——所有已送入的音频帧必然在 finalize 之前被处理完毕：

enum StreamCmd { Feed(Vec<f32>), Finalize(mpsc::Sender<Option<FinalizedStreamText>>), Cancel, }

工作线程在run_stream_worker中会先等待可能的模型加载完成，然后将引擎从互斥锁中取出独占（通过active_engine_lease租约标记），从结构上排除并发的批式转录。随后用session.stream(&run_options, &StreamOptions::default())建立流式会话，循环消费Feed帧并增量解码。

无闪烁的文本输出模型

流式文本通过StreamTextEvent推送给浮层，其设计要点是区分已提交文本与暂定文本：

pub struct StreamTextEvent { pub committed: String, // append-only、无闪烁的已定稿前缀 pub tentative: String, // 模型仍可能改写的易变后缀 }

在 RecordingOverlay.tsx 中，UI 将两者分开渲染：committed前缀固定展示，tentative后缀会随模型修订而更新，并配合一个闪烁光标提示仍在实时捕获。当进入收尾（finalize）阶段时，StreamPhaseEvent会把浮层切换到Working状态，显示"转写中 / 处理中"（StreamWorkKind::Transcribing或Polishing）的 spinner，同时保留已生成的文本不塌缩。

降级回退策略

流式并非总是可用：如果模型不支持流式、或流式启动失败、或模型在流式开始前被卸载，工作线程会清空通道并等待 finalize 握手，最终返回None，调用方自动回退到批式转录（finalize_stream的返回值语义是Ok(None)表示"没有可用流式会话，可回退批式"）。此外 finalize 设有 30 秒超时（STREAM_FINALIZE_REPLY_TIMEOUT），超时会返回错误而不是无限等待。这套设计保证了流式功能在旧模型上不会造成功能缺失。

流式转录浮层（Overlay）

配合流式转录，0.9.0 引入了一个全新的流式浮层，让你在说话的同时看到正在写入/转写的文本：

该浮层有几种形态（源码见 RecordingOverlay.tsx）：

Live 形态：一个小药丸（pill）在出现文本后平滑展开为面板，上方展示实时文本，底部保持「状态点 + 波形 + 计时器 + 取消按钮」的统一布局；文本区域在滚动到底部时自动跟随最新一行，用户上滑阅读历史时暂停跟随；
最小化（Minimal）形态：单行显示，录音时只显示波形，转写/处理时只显示 spinner 与标签。

0.9.0 的默认行为是：当使用兼容的流式模型时，自动启用这个流式浮层。如果不喜欢，可以在Advanced Settings（高级设置）中切换到 minimal 样式。在设置界面中，浮层开关对应ShowOverlay组件（见 AdvancedSettings.tsx 的SettingsGroup「App」分组），浮层的位置（顶部/底部）也支持通过设置项调整。

新模型支持：GGUF 头部能力探测

升级到 transcribe.cpp 之后，Handy 支持了大量新语音转文字模型。0.9.0 发布说明点名的模型家族包括：

IBM 的 Granite 家族（源码KNOWN_ARCHES中对应granite、granite_speech、granite_nar、granite_speech_nar）；
Mistral 的 Voxtral 家族（voxtral、voxtral_realtime）；
Google 的 MedASR（medasr）；
阿里巴巴的 Qwen3 ASR（qwen3_asr）。

能力探测：下载前就知道模型能干什么

在 model_capabilities.rs 中，KNOWN_ARCHES完整列出了 transcribe-cpp 能加载的架构字符串（与 transcribe-cpp 的src/arch/目录一一对应），除上述家族外还包括whisper、parakeet、cohere、canary、moonshine、sensevoice、gigaam、funasr_nano、moss、sortformer等。

Handy 通过GgufHeaderProber实现GGUF 头部能力探测：在模型下载之前，只读取本地 GGUF 文件的元数据头部（默认先读 64 KiB，头部异常庞大时几何增长至最多 16 MiB，绝不全量加载可能数 GB 的张量数据），解析出以下关键字段：

GGUF 元数据键	含义	对应 UI 能力
`general.architecture`	模型架构	兼容性判定（`Compatible`/`MaybeIncompatible`）
`general.name`	模型显示名	模型列表展示
`stt.variant`	变体	模型描述
`general.languages`	可转写语言代码	语言选择范围
`stt.capability.streaming`	原生流式支持	流式徽标
`stt.capability.translate`	翻译到英语	翻译能力徽标
`stt.capability.lang_detect`	自动语言检测	"Auto" 语言选项的门槛

一个重要的设计细节：探测结果未知时绝不猜测。例如 Parakeet 家族的流式能力由 transcribe-cpp 本地加载器从编码器 hparams 推断，而非平铺的布尔字段，因此当stt.capability.streaming键缺失时，探测结果保持None（未知），等模型真正加载后再由运行时校准（set_runtime_capabilities用加载后的真实能力覆盖注册表中的广告值），保证 UI 徽标反映的是运行时真相而非下载前的推测。相应的测试用例（见 model_capabilities.rs 的tests模块）验证了「已知架构 + 能力字段 → 正确标记」、「未知架构 → MaybeIncompatible」等行为。

模型管理层面（model.rs 的ModelInfo）为每个模型携带了supports_streaming、supports_translation、supports_language_detection、supported_languages、accuracy_score、speed_score等字段，并支持三种来源：直接 URL 下载、Hugging Face Hub 仓库（共享 HF 缓存）、以及本地已存在的自定义模型。升级后想尝鲜多种语音模型，可以直接前往Models 页面浏览这些新模型。

Legacy 模型弃用计划与升级路径

0.9.0 发布说明明确指出，这是一次大版本升级，"理论上一切开箱即用"，但大概率仍会存在个例问题，因此鼓励用户在出问题时向官方 Issues Tracker 反馈（仓库根目录 README.md 与 CONTRIBUTING.md 亦提供了项目背景与贡献方式）。

关于未来演进，发布说明给出了一条明确的弃用路线：

未来将弃用 "Legacy"（旧版）模型——即在旧引擎（transcribe-rs 的 ONNX 路径）下运行的模型家族（当前源码中仍保留的Parakeet、Moonshine、MoonshineStreaming、SenseVoice、GigaAM、Canary、Cohere引擎，见 model.rs）；
在移除支持之前会提供升级路径——对仍在使用这些模型的用户，升级动作很简单：把模型重新下载为 transcribe.cpp 支持的格式（GGUF/ggml）即可，无需其他操作。

从架构上看，这一弃用计划是引擎收敛的自然结果：transcribe-cpp 已成为主要引擎（流式转录也只在 transcribe-cpp 模型上可用，ONNX 引擎一律回退批式转录），将全部模型统一到 GGUF 格式后，能力探测、流式支持、加速后端选择（Metal / Vulkan / CPU）可以在同一套机制下工作。对普通用户而言，建议在升级到 0.9.0 后优先尝试流式模型与新的 GGUF 格式模型，提前体验更快、更实时的转录体验，并为将来的引擎统一做好准备。

小结

0.9.0 是 Handy 迈向新一代转录架构的里程碑：transcribe.cpp 接管主要转录、流式转录让「边说边出字」成为现实、GGUF 头部能力探测让模型选择更透明、四大新模型家族（Granite、Voxtral、MedASR、Qwen3 ASR）扩大了覆盖面。升级后，你只需要记住三件事：流式模型默认自动启用实时浮层（可在高级设置改为 minimal）、新模型可从 Models 页面下载、旧模型未来将统一迁移到 GGUF 格式。