transcribe.cpp

transcribe.cpp

C/C++ 语音转文字推理库。通过 GGUF 模型在 ggml 运行时上运行多种 STT 模型家族，支持 Metal、Vulkan 和 CUDA 后端以实现快速 GPU 推理，并包含通过 tinyBLAS 加速的 CPU 路径。

支持 16 个模型家族和 60 多个变体，支持流式与批量处理。我们在 handy-computer 下发布的每个模型均经过数值验证，并与参考实现进行了 WER（词错误率）测试

支持的模型：

模型家族	变体	文档
Parakeet	10 个变体：TDT、RNN-T、CTC、TDT+CTC（110M–1.1B）	docs/models/parakeet.md
Canary	canary-1b、canary-1b-v2、canary-1b-flash、canary-180m-flash	docs/models/canary.md
Canary-Qwen	canary-qwen-2.5b（FastConformer + Qwen3-1.7B SALM）	docs/models/canary-qwen-2.5b.md
Whisper	12 个变体（tiny 至 large-v3-turbo，外加 .en 系列）	docs/models/whisper.md
GigaAM	gigaam-v3-{e2e-rnnt,e2e-ctc,rnnt,ctc}	docs/models/gigaam.md
Moonshine	moonshine-tiny、moonshine-base	docs/models/moonshine.md
Moonshine 流式	moonshine-streaming-{tiny,small,medium}	docs/models/moonshine-streaming.md
Qwen3-ASR	qwen3-asr-0.6b、qwen3-asr-1.7b	docs/models/qwen3-asr.md
Cohere Transcribe	cohere-transcribe-03-2026	docs/models/cohere-transcribe-03-2026.md
SenseVoice	sensevoice-small	docs/models/sensevoice-small.md
FunASR Nano	fun-asr-nano-2512、fun-asr-mlt-nano-2512	docs/models/fun-asr-nano.md
Nemotron Speech Streaming	nemotron-speech-streaming-en-0.6b	docs/models/nemotron-speech-streaming-en-0.6b.md
Nemotron 3.5 ASR Streaming	nemotron-3.5-asr-streaming-0.6b（多语言，40 个地区）	docs/models/nemotron-3.5-asr-streaming-0.6b.md
Multitalker Parakeet Streaming	multitalker-parakeet-streaming-0.6b-v1（仅单说话人 ASR 路径）	docs/models/multitalker-parakeet-streaming-0.6b-v1.md
Granite Speech 4 / 4.1	granite-4.0-1b-speech、granite-speech-4.1-2b{,-plus,-nar}	docs/models/granite-speech.md
Voxtral	voxtral-mini-3b-2507、voxtral-small-24b-2507（音频-LLM，转录 + 翻译）	docs/models/voxtral.md
Voxtral Realtime	voxtral-mini-4b-realtime-2602（流式音频-LLM）	docs/models/voxtral-realtime.md
MedASR	medasr（Conformer + CTC，英文医学听写，受限访问）	docs/models/medasr.md
MOSS Transcribe-Diarize	moss-transcribe-diarize（音频-LLM，英文 + 中文 ASR，含内联说话人分离）	docs/models/moss-transcribe-diarize.md

每个变体的模型卡片位于 docs/models/ 目录下。

构建

cmake -B build
cmake --build build

在 Apple Silicon 上自动启用 Metal。对于 Vulkan（Linux/Windows）：

# Ubuntu/Debian
sudo apt install build-essential cmake libvulkan-dev glslc libopenblas-dev

cmake -B build -DTRANSCRIBE_VULKAN=ON
cmake --build build

在 Windows 上，请参阅 完整构建指南 了解 Vulkan SDK 设置、Visual Studio 命令以及针对过深检出目录的短构建根回退方案。

对于 CUDA（Linux + NVIDIA GPU）：

# 需要 CUDA 工具包（nvcc）在 PATH 中
cmake -B build -DTRANSCRIBE_CUDA=ON
cmake --build build

libopenblas-dev 是可选的，但推荐安装。它可以将主机端解码器加速约 10-15 倍。没有它，构建会自动回退到标量路径。

tinyBLAS（Justine Tunney 的 llamafile_sgemm 内核）默认启用。

要构建量化工具：

cmake -B build -DTRANSCRIBE_BUILD_TOOLS=ON
cmake --build build

模型

所有支持模型的预构建 GGUF 文件托管在 Hugging Face 的 handy-computer 下。上表中的每个模型文档都包含了每种量化版本的直接下载链接。只有在需要不同的数据类型或检查点没有预构建版本时，才需要从源码转换。

转换为 GGUF

转换器通过 ASRModel.from_pretrained 直接从 NVIDIA 的 NeMo 检查点加载。需要 uv；parakeet 环境会安装 NeMo 及其依赖项。

uv run --project scripts/envs/parakeet \
  scripts/convert-parakeet.py nvidia/parakeet-tdt-0.6b-v2

这会生成 models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf，遵循 llama.cpp 风格的 <slug>-<QUANT>.gguf 命名约定。对于离线转换，可以传入本地的 .nemo 路径或解压后的目录。

量化

transcribe-quantize 工具可以从参考 GGUF 生成更小的模型。可用的预设：F16、Q8_0、Q6_K、Q5_K_M、Q4_K_M。

build/bin/transcribe-quantize \
  models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \
  models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-Q4_K_M.gguf \
  --quant Q4_K_M

使用

build/bin/transcribe-cli -m models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf samples/jfk.wav

输入必须是 16 kHz 单声道 WAV 文件。使用 ffmpeg 或 sox 转换其他格式：

ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav

绑定

官方绑定为其他语言封装了 C API：

语言	路径
Python	bindings/python
TypeScript / JavaScript	bindings/typescript
Rust	bindings/rust/transcribe-cpp
Swift / ObjC	bindings/swift

请参阅 docs/bindings.md 了解绑定的生成方式以及如何与头文件保持同步。

测试

cd build && ctest

某些测试需要真实的模型文件。使用以下命令启用它们：

cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
cmake --build build
TRANSCRIBE_PARAKEET_GGUF=path/to/model.gguf ctest --test-dir build

关于新移植的模型家族所需的烟雾测试、数值验证和基准测试模式，请参阅 docs/model-family-testing.md。

赞助商与支持组织

Mozilla AI 与 BiR 计划

非常感谢 Mozilla AI 及其 BiR 计划。整个项目最初只是一个想法，甚至没有实现方向。它是一个研究项目，旨在尽可能轻松地跨所有平台加速转录模型。BiR 计划和 Davide 支持了这项研究，并最终促使我选择基于 ggml 实现推理引擎。同时，他们还尝试使用 agentic 编程工具进行自动模型移植的实验。

Hugging Face

Hugging Face 为项目提供了额外的存储空间，使我们能够托管所有支持的模型。我们希望为尽可能多的模型提供规范的参考，Hugging Face 的支持对此起到了关键作用。

Modal

M odal 提供了 GPU 积分，使项目能够测试和验证实现与 transformers 或 NeMo 参考源的一致性。这对于确保我们拥有尽可能接近生产级且能在任何地方运行的推理引擎至关重要。我们相信准确的转录至关重要，而确保这一点的唯一方法是通过长期的 WER 检查，Modal 帮助实现了这一点。在 handy-computer 上发布的每个模型都经过了 WER 检查，因此您可以信赖结果。如果出现任何性能回退，我们一定会修复。

Blacksmith

Blacksmith 提供了该项目的大部分 CI 运行器。这有助于保持 transcribe.cpp 的良好测试状态，并确保我们的发布尽可能顺畅。CI 速度快，并且可以无缝替代标准的 GitHub Actions 运行器。我很快遇到了限制，非常高兴地联系 Blacksmith 后，他们为项目提供了运行器。

项目结构

include/transcribe.h      公开 C API（单头文件）
src/                      库内部实现（C++17）
src/arch/parakeet/        Parakeet 家族实现
src/arch/cohere/          Cohere Transcribe 家族实现
examples/cli/             CLI 二进制源码
tools/transcribe-quantize/ 量化工具源码
bindings/                 Python、TypeScript、Rust 和 Swift 绑定
docs/                     移植与验证指南
scripts/                  Python 转换器 + 测试工具
ggml/                     内嵌 ggml（参见 ggml/UPSTREAM 获取固定 SHA）
src/third_party/miniz/    内嵌 miniz deflate 编解码器（参见其 UPSTREAM 文件）
samples/                  测试音频文件
tests/                    单元测试与烟雾测试

许可证

transcribe.cpp 使用 MIT 许可证。详情请参见 LICENSE。内嵌的第三方组件（ggml、miniz——均为 MIT）的归属信息见 THIRD-PARTY-LICENSES.md。