transcribe.cpp快速开始Linux/macOS/Windows三平台构建完整教程【免费下载链接】transcribe.cppggml speech-to-text inference for 16 model families项目地址: https://gitcode.com/GitHub_Trending/tr/transcribe.cpptranscribe.cpp是一个基于 ggml 运行时的 C/C 语音识别speech-to-text推理库支持 16 个模型家族、60 多个变体覆盖 Parakeet、Whisper、Voxtral、Qwen3-ASR 等主流语音转写模型。本教程带你从零开始在 Linux、macOS、Windows 三个平台完成 transcribe.cpp 的构建并跑通第一次语音转文字。一、项目概览transcribe.cpp 能做什么transcribe.cpp 的核心特点多模型家族Parakeet、Whisper12 个变体、Canary、Moonshine、Voxtral、SenseVoice、Qwen3-ASR 等全部以 GGUF 格式加载多后端加速CPUtinyBLAS 加速、MetalApple 芯片自动启用、Vulkan、CUDA、ROCm流式与批处理既支持整段音频转写也支持流式streaming逐块识别多语言绑定官方提供 Python、TypeScript/JavaScript、Rust、Swift 绑定。每个模型在发布前都经过数值验证和 WER词错率测试结果可信。公开 C API 只有一个头文件 include/transcribe.h命令行示例位于 examples/cli/main.cpp。二、构建前准备克隆仓库三个平台的第一步都一样——克隆代码git clone https://gitcode.com/GitHub_Trending/tr/transcribe.cpp cd transcribe.cpp构建依赖一览平台必装依赖可选加速Linuxbuild-essential、cmake≥3.21libvulkan-dev、glslcVulkan、CUDA toolkitNVIDIA 显卡macOSXcode Command Line Tools、cmake无需额外安装Apple 芯片自动启用 MetalWindowsVisual Studio Build Tools 2022C、cmakeVulkan SDKGPU 后端 Linux 上推荐安装 OpenBLASlibopenblas-dev可将宿主机解码器加速约 10–15 倍不装会自动回退到标量路径不影响正确性。三、Linux 构建两条命令出成品3.1 CPU 后端默认最简单cmake -B build cmake --build build编译完成后CLI 工具位于build/bin/transcribe-cli。仓库自带多个 16 kHz 单声道 WAV 样例见 samples/ 目录可以直接开跑。3.2 Vulkan GPU 后端跨显卡通用# Ubuntu/Debian sudo apt install build-essential cmake libvulkan-dev glslc libopenblas-dev cmake -B build -DTRANSCRIBE_VULKANON cmake --build buildFedora 用户可改用sudo dnf install vulkan-headers openblas-devel glslc spirv-headers-devel。3.3 CUDA / ROCm 后端# NVIDIA 显卡需要 nvcc 在 PATH 上 cmake -B build -DTRANSCRIBE_CUDAON # AMD 显卡ROCm ≥ 6.1 cmake -B build -DTRANSCRIBE_HIPON -DAMDGPU_TARGETSgfx1201 cmake --build buildgfx1201需替换为你的 GPU 架构可用rocminfo | grep gfx查询。更多后端参数详见 CMakePresets.json 中的官方构建预设。四、macOS 构建Metal 自动就位macOS尤其是 Apple Silicon是体验最好的平台——Metal 后端会自动启用无需任何额外参数xcode-select --install brew install cmake # 或从官网下载 cmake -B build cmake --build buildX86 Mac 则走 CPU 或 Vulkan 路径与 Linux 的 Vulkan 流程一致。五、Windows 构建从零到 transcribe-cli.exeWindows 上有专门的完整指南 docs/build-windows.md核心流程如下以 PowerShell 为例5.1 一键安装工具链winget install --id Git.Git --accept-source-agreements --accept-package-agreements winget install --id Kitware.CMake --accept-source-agreements --accept-package-agreements winget install --id Microsoft.VisualStudio.2022.BuildTools --override --quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --includeRecommended⚠️ 安装完成后必须重开终端否则新安装的git、cmake不在 PATH 中。5.2 配置并编译cmake -B build cmake --build build --target transcribe-cli --config Release注意 VS 生成器是多配置的--config Release不能省略否则得到的是 Debug 版本。产物位于build\bin\Release\transcribe-cli.exe完全自包含无需额外 DLL。5.3 可选Vulkan GPU 加速winget install --id KhronosGroup.VulkanSDK --accept-source-agreements --accept-package-agreements cmake -B build -DTRANSCRIBE_VULKANON cmake --build build --target transcribe-cli --config Release运行后 CLI 会自动选择 GPU输出类似backend: Vulkan0。六、下载模型并运行第一次转写预构建的 GGUF 模型托管在 Hugging Face 的handy-computer组织下各模型的文档页位于 docs/models/提供每个量化版本的下载链接。以 Parakeet TDT 0.6B v3Q8_0约 705 MB为例mkdir models\parakeet-tdt-0.6b-v3 curl.exe -L --fail -o models\parakeet-tdt-0.6b-v3\parakeet-tdt-0.6b-v3-Q8_0.gguf https://huggingface.co/handy-computer/parakeet-tdt-0.6b-v3-gguf/resolve/main/parakeet-tdt-0.6b-v3-Q8_0.gguf6.1 运行 CLI 转写build/bin/transcribe-cli -m models/parakeet-tdt-0.6b-v3/parakeet-tdt-0.6b-v3-Q8_0.gguf samples/jfk.wav预期输出backend: CPU text: And so, my fellow Americans, ask not what your country can do for you, ask what you can do for your country. realtime: 6x (1703.9 ms for 11.0 s)realtime: 6x表示处理速度是实时语速的 6 倍。6.2 音频格式要求输入必须是16 kHz 单声道 WAVsamples/jfk.wav已满足条件。其他格式用 ffmpeg 转换ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav6.3 常用 CLI 选项选项说明-m model.gguf指定 GGUF 模型--backend auto\|cpu\|metal\|vulkan\|cuda\|rocm指定计算后端默认 auto 自动选择--batch file.list批量转写模式--list-devices列出可用设备完整选项可用transcribe-cli --help查看实现见 examples/cli/main.cpp。七、量化让模型更小更快仓库自带量化工具源码在 tools/transcribe-quantize/支持F16、Q8_0、Q6_K、Q5_K_M、Q4_K_M五种预设cmake -B build -DTRANSCRIBE_BUILD_TOOLSON cmake --build build 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八、多语言绑定把转写能力嵌入你的应用除了 C APItranscribe.cpp 提供四套官方绑定生成机制说明见 docs/bindings.md语言路径说明Pythonbindings/python/提供transcribe_cpp包支持流式转写TypeScript / JSbindings/typescript/面向 Node 应用Rustbindings/rust/transcribe-cpp/含-syscrateSwift / ObjCbindings/swift/可用 SPM 集成Python 用法示例16 kHz 单声道 float32 PCMimport transcribe_cpp with transcribe_cpp.Model(model.gguf) as model: with model.session() as session: result session.run(pcm_float32_16k_mono) print(result.text)流式模型还支持session.stream()增量转写示例见 bindings/python/examples/stream_wav.py。九、常见问题速查症状原因解决方法Windows 上git/cmake未找到终端 PATH 未刷新重开一个新终端Windows 构建产物很慢默认构建了 Debug 版加--config ReleaseWindows Vulkan 构建报MSB6003 link.exe could not be run构建目录路径过长超 MAX_PATH把构建目录放到短路径如cmake -B C:\bv -S .编译提示no BLAS found未安装 OpenBLAS可忽略仅影响宿主机解码速度Linux Vulkan 编译失败缺少glslc或 vulkan 头文件sudo apt install libvulkan-dev glslc十、下一步查看各模型家族的详细文档与量化下载链接docs/models/了解环境变量线程数、后端选择等docs/environment-variables.md从 0.1 版本升级docs/migrating-to-0.2.md运行测试套件cd build ctest至此你已经在 Linux / macOS / Windows 上完成了 transcribe.cpp 语音识别库的构建并成功转写了第一段音频。接下来可以挑选感兴趣的模型家族把语音转写能力集成进自己的项目里。【免费下载链接】transcribe.cppggml speech-to-text inference for 16 model families项目地址: https://gitcode.com/GitHub_Trending/tr/transcribe.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考