Buzz：在个人电脑上离线转录与翻译音频的 Whisper 桌面应用实战指南

本指南围绕 Buzz 项目官方介绍页（docs/i18n/zh/docusaurus-plugin-content-docs/current/index.md）展开，系统梳理它的核心能力、支持的模型生态、文件导入与实时录制工作流、命令行界面与跨平台安装方式，并结合仓库源码补充底层实现依据，帮助读者快速评估、安装并使用这款由 OpenAI Whisper 驱动的本地转录与翻译工具。

项目概览：本地优先的 Whisper 转录翻译工具

Buzz 是一款运行在个人电脑上的开源桌面应用，其定位非常明确：在本地离线完成音频/视频的转录（Speech-to-Text）与翻译，核心引擎由 OpenAI 的 Whisper 系列模型提供支持。项目描述与介绍页第一句话即点明主题：

在您的个人电脑上离线转录和翻译音频。由 OpenAI 的 Whisper 提供支持。

“离线”是 Buzz 的核心卖点。除调用云端 OpenAI Whisper API 的场景外，模型权重默认下载到本地（模型下载与路径管理逻辑见 buzz/model_loader.py，包含 ModelDownloader 与本地路径解析），转录推理在用户自己的硬件上完成，音视频数据无需上传到第三方服务器，这对隐私敏感场景尤为重要。

从仓库结构看，Buzz 以 PyQt6 构建跨平台图形界面（buzz/widgets/main_window.py），核心转录能力由 buzz/transcriber 目录下的多个后端实现（Whisper、Whisper.cpp、Faster Whisper、OpenAI API 等），并辅以 CLI 入口（buzz/cli.py）和可选插件体系（buzz/plugins），形成了“GUI 为主、CLI 为辅、插件可扩展”的整体架构。

核心功能矩阵

官方介绍页列出的功能可归纳为五条主线，下面逐条展开并结合源码佐证。

1. 文件导入与多格式导出

Buzz 支持导入音频和视频文件，并将转录结果导出为 TXT、SRT、VTT 三种常见格式。

• 导入入口：菜单栏“文件”→“导入媒体文件”，或工具栏“+”图标，快捷键 Command/Ctrl + O（详细步骤见 文件导入指南）。
• 导出格式：源码中 OutputFormat 枚举定义了三种可选格式（见 buzz/transcriber/transcriber.py）：TXT（纯文本）、SRT（SubRip 字幕）、VTT（WebVTT 字幕）。
• 文件导入时的可配置字段包括：

字段	选项	默认值	描述
导出格式	"TXT"、"SRT"、"VTT"	"TXT"	导出文件的格式
单词级时间戳	关闭 / 开启	关闭	为音频中的每个单词生成单独的字幕行；仅当导出格式为 SRT 或 VTT 时可用
提取语音	关闭 / 开启	关闭	将语音提取到单独的音轨以提高转录准确性（自 1.3.0 起可用）

文件导入界面在 buzz/widgets/transcriber/file_transcriber_widget.py 中实现，任务表与状态管理见 buzz/widgets/transcription_tasks_table_widget.py。

2. 麦克风实时录制转录

Buzz 可以直接从电脑麦克风采集声音并实时转录/翻译为文本。官方文档特别提示：

使用默认的 Whisper 模型转录音频会占用大量系统资源。若想实现实时性能，可考虑使用 Whisper.cpp Tiny 模型。

实时录制界面（buzz/widgets/recording_transcriber_widget.py）提供四个关键配置字段：

字段	选项	默认值	描述
任务	"转录"、"翻译"	"转录"	转录将输入音频转换为所选语言的文本；翻译将其转换为英文文本
语言	完整的支持语言列表见 Whisper 文档	"自动检测语言"	自动检测基于音频前几秒；已知语言时建议手动指定以提高质量
质量	"极低"、"低"、"中"、"高"	"极低"	分别对应 tiny / base / small / medium 模型，模型越大质量越高、资源占用越大
麦克风	系统可用麦克风	系统默认麦克风	录制输入音频的设备

“质量”与模型大小的对应关系（tiny/base/small/medium）与源码中 WhisperModelSize 枚举一致（见 buzz/model_loader.py），该枚举还包含 tiny.en、base.en、small.en、medium.en 等英文专用变体以及 large、large-v2、large-v3、large-v3-turbo 等大模型。

此外，Buzz 还支持录制“电脑内部播放的音频”：macOS 可通过 Homebrew 安装 BlackHole 等虚拟音频设备并创建“多输出设备”；Windows 可借助 VB-CABLE 虚拟声卡将系统声音路由到 Buzz；Linux 则可在 PulseAudio 的 pavucontrol 录音选项卡中配置应用到 Buzz 的声音路由（详见 实时录制指南）。

3. 多后端模型支持

介绍页明确 Buzz 支持五类 Whisper 生态模型，这与源码中 ModelType 枚举一一对应（见 buzz/model_loader.py）：

命令行值	枚举名	后端说明
whisper	WHISPER	OpenAI 官方 Whisper 模型（Python 实现，见 buzz/transformers_whisper.py）
whispercpp	WHISPER_CPP	C++ 高性能实现（whisper.cpp/ 子模块，支持 Vulkan GPU 加速，见 buzz/transcriber/whisper_cpp.py）
huggingface	HUGGING_FACE	Whisper 兼容的 Hugging Face 模型（通过 --hfid 指定模型 ID，如 openai/whisper-tiny）
fasterwhisper	FASTER_WHISPER	CTranslate2 加速的 Faster Whisper 实现
openaiapi	OPEN_AI_WHISPER_API	调用 OpenAI Whisper 云端 API（buzz/transcriber/openai_whisper_api_file_transcriber.py）

从源码结构看，ModelType.supports_initial_prompt 属性（buzz/model_loader.py）显示上述全部五种后端均支持“初始提示词”（Initial Prompt）功能，可用于引导 Whisper 的转录风格或纠正特定词汇。

说明：当前中文介绍页列出的是五类模型；仓库英文文档（docs/docs/index.md）还额外提到 Parakeet、Qwen3-ASR、VibeVoice 等更新的 Hugging Face 模型类别，说明该生态仍在持续扩展。具体可用模型以当前版本为准。

4. 命令行界面（CLI）

Buzz 内置 CLI 入口，可从终端直接发起转录任务，适合批处理与自动化场景。源码中 CLI 解析基于 Qt 的 QCommandLineParser 实现（见 buzz/cli.py），核心命令为 buzz add。

命令用法：

Usage: buzz add [options] [file url file...]

核心参数：

参数	说明
-t, --task <task>	任务类型：translate 或 transcribe，默认 transcribe
-m, --model-type <model-type>	模型后端：whisper / whispercpp / huggingface / fasterwhisper / openaiapi，默认 whisper
-s, --model-size <model-size>	模型大小：tiny / base / small / medium / large，默认 tiny；仅用于 whisper、whispercpp、fasterwhisper
--hfid <id>	Hugging Face 模型 ID，仅用于 --model-type huggingface，例如 "openai/whisper-tiny"
-l, --language <code>	语言代码（如 fr、zh、en），留空则自动检测语言
-p, --prompt <prompt>	初始提示词
-w, --word-timestamps	生成单词级时间戳（自 1.2.0 起可用）
-e, --extract-speech	转录前先提取语音
--openai-token <token>	OpenAI 访问令牌，仅用于 --model-type openaiapi；缺省时回退到已保存的令牌（通过系统密钥环读取，见 buzz/store/keyring_store.py）
-d, --output-directory <directory>	输出目录
--srt / --vtt / --txt	分别输出 SRT / VTT / TXT 格式文件（可组合）
--hide-gui	隐藏主应用窗口（自 1.2.0 起可用）
-h, --help / --help-all / -v, --version	帮助与版本信息

典型示例：

# 使用 OpenAI Whisper API 将两个 MP3 文件从法语翻译为英语
buzz add --task translate --language fr --model-type openaiapi /path/to/1b3b03e4.mp3 /path/to/koaf9083k.mp3

# 使用 Whisper.cpp "small" 模型转录一个 MP4 文件，并立即导出为 SRT 和 VTT 文件
buzz add --task transcribe --model-type whispercpp --model-size small --prompt "My initial prompt" --srt --vtt /path/to/video.mp4

从源码看，buzz add 的完整执行链路为：_handle_add_command 解析参数 → _resolve_model 检查本地模型是否存在，不存在则通过 ModelDownloader 自动下载 → _add_transcription_tasks 为每个文件/URL 创建 FileTranscriptionTask 并加入应用任务队列，任务完成后自动退出（见 buzz/cli.py）。CLI 还支持直接传入 URL 作为输入（自 1.2.0 起），源码通过 urllib.parse 判断路径是否为 URL 并设置相应的任务来源（FILE_IMPORT / URL_IMPORT）。

语言代码支持范围极广（af 南非荷兰语、zh 中文、fr 法语、ja 日语等 90+ 种），完整列表可在运行 buzz add --help 时查看，其数据源是 buzz/transcriber/transcriber.py 中的 LANGUAGES 字典。

5. 跨平台支持

介绍页声明 Buzz 支持 Mac（Intel）、Windows 和 Linux。仓库中对应的打包与发布配置包括：

• Buzz.spec（PyInstaller 打包规范）、installer.iss（Windows Inno Setup 安装脚本）、entitlements.plist（macOS 签名权限）
• Linux 发行渠道：Snap（snap/snapcraft.yaml）、Flatpak（flatpak/run-buzz.sh）、AppImage（appimage/ 目录）
• 桌面集成文件：Buzz.desktop 与 share/metainfo/io.github.chidiwilliams.Buzz.metainfo.xml

安装方式详解

macOS（Intel，macOS 11.7 及以上）

brew install --cask buzz

或下载 Buzz-x.y.z.dmg 直接运行。Apple Silicon（M 系列）用户同样支持。

Windows（Windows 10 及以上）

下载并运行 Buzz-x.y.z.exe 安装程序即可。

Linux

推荐 Snap 安装：

sudo apt-get install libportaudio2 libcanberra-gtk-module libcanberra-gtk3-module
sudo snap install buzz
sudo snap connect buzz:password-manager-service

其中 libportaudio2 是音频采集（PortAudio）的运行时依赖，password-manager-service 连接用于密钥环（保存 OpenAI API Key 等凭据）。Ubuntu 20.04 及以上也可下载 Buzz-x.y.z-unix.tar.gz 解压运行（同样需要先安装 libportaudio2）。

PyPI（Python 包）

pip install buzz-captions
python -m buzz

通过 PyPI 安装后，python -m buzz 即启动 GUI（入口见 buzz/main.py），CLI 子命令同样可用。

进阶能力速览

介绍页之外，仓库的中文使用文档还覆盖了与核心功能配套的进阶能力，可作为上手后的下一步：

• 翻译功能：默认“翻译”任务借助 Whisper 将内容译为英文；从 1.0.0 起，Buzz 支持在“偏好设置”中配置 OpenAI API 密钥，使用兼容 OpenAI API 的本地模型（如 Ollama、LM Studio）将内容翻译为任意语言，并在转录查看器工具栏点击“翻译”按钮对已完成转录的文件执行翻译（详见 翻译功能指南）。
• 转录查看器：提供时间戳/纯文本/翻译三种视图模式，支持搜索（Ctrl+F）、播放控制（Ctrl+Alt+P）、跟随音频（Ctrl+G）、循环片段、0.5x–2.0x 变速播放与大量快捷键（详见 英文版转录查看器文档）。
• 编辑与调整：对已完成的转录可重新合并生成字幕，支持单词级时间戳时还能按标点拆分、并利用静音分析提高字幕精度（详见 编辑与调整指南）。
• 插件体系：仓库内置 AI 摘要、深度过滤、语言检测增强、DOCX 导出、跳过已转录文件、转录重排等插件（buzz/plugins），并支持自定义扩展（插件规范见 buzz/plugins/AGENTS.md 与 buzz/plugins/CLAUDE.md）。

总结

Buzz 将 OpenAI Whisper 的离线转录与翻译能力封装为易用的跨平台桌面应用：文件导入与多格式导出覆盖日常字幕生产，实时麦克风录制支持会议与现场场景，五种模型后端兼顾质量与性能的灵活取舍，CLI 让批处理与自动化成为可能，而完善的插件体系进一步延伸了它的能力边界。对于希望在本地完成语音转写、字幕生成或翻译任务的个人用户与开发者，Buzz 是一个开箱即用且可深入定制的选择。

延伸阅读（均为仓库内文档，可点击进入）：

• 安装指南
• CLI 使用说明
• 文件导入
• 实时录制
• 翻译功能
• 编辑与调整