企业官网建设流程全解析

Buzz 偏好设置完全指南：GUI 配置项、导出文件模板与高级环境变量详解

【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAI's Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz

Buzz 是一款基于 OpenAI Whisper 的本地离线音频转写与翻译工具。本文以项目官方文档 docs/docs/preferences.md 为主体，结合仓库源码逐项解读 Preferences 窗口中的常规设置、模型管理与高级环境变量：你将掌握如何配置 OpenAI API、自定义导出文件名模板、开启实时转录导出、管理模型下载，以及如何通过一组BUZZ_*环境变量精细化调优线程数、显存占用、模型缓存目录与遥测开关等进阶能力。

打开 Preferences 窗口

在菜单栏中选择Preferences（偏好设置），或直接按快捷键Ctrl + ,（macOS 为Cmd + ,）即可打开设置窗口。

偏好设置项的持久化由 Qt 的QSettings完成，全部可持久化的键定义在 buzz/settings/settings.py 的Settings.Key枚举中（如DEFAULT_EXPORT_FILE_NAME、CUSTOM_OPENAI_BASE_URL、FORCE_CPU、REDUCE_GPU_MEMORY等），每次写入后都会立即sync()落盘，因此修改即时生效、无需额外保存操作。

常规偏好设置（General Preferences）

常规设置界面由 buzz/widgets/preferences_dialog/general_preferences_widget.py 实现，除文档重点介绍的内容外，该页面还包含界面语言（UI Language）与字体大小（Font Size）两项基础设置。

OpenAI API 相关设置

API Key：用于向 OpenAI API 发起请求时进行身份认证的密钥。密钥通过带掩码的密码输入框（OpenAIAPIKeyLineEdit）录入，并结合系统钥匙串/凭据管理器保存（参见 buzz/store/keyring_store.py）。界面提供Test按钮，点击后由ValidateOpenAIApiKeyJob向{base_url}/models发送带认证头的 GET 请求（超时 5 秒）来校验密钥有效性；若自定义 Base URL 末尾缺少/，校验时会自动补全，这一细节说明 Buzz 对第三方兼容接口的路径拼接做了容错处理。

Base URL：请求发送的接口地址。默认所有请求发往 OpenAI 官方提供的 API，地址为https://api.openai.com/v1/（也是输入框的占位提示文本）。OpenAI 兼容 API 由其他服务商广泛提供，也支持自建服务，可将 Base URL 指向任意兼容端点。该值保存在Settings.Key.CUSTOM_OPENAI_BASE_URL中，同时影响 Whisper API 转写与 AI 翻译两类请求。

OpenAI API model：界面中可指定调用的 API 模型，默认值为whisper-1（见Settings.Key.OPENAI_API_MODEL的默认值）。

Reduce GPU RAM（减少 GPU 显存）：勾选后会为 Hugging Face、Faster Whisper 与 Whisper.cpp 转写使用压缩版模型，以降低所需 GPU 显存。该选项与高级环境变量BUZZ_REDUCE_GPU_MEMORY等效——勾选后 buzz/widgets/application.py 会在应用启动时将环境变量BUZZ_REDUCE_GPU_MEMORY置为"true"。界面上的 tooltip 明确说明该选项作用于 Hugging Face 与 Faster Whisper 模型，可能略微降低转写质量，请按需权衡。底层实现中，buzz/model_loader.py 通过os.getenv("BUZZ_REDUCE_GPU_MEMORY", "false") != "false"判定是否启用 8-bit 量化。

默认导出文件名（Default export file name）

该设置用于指定文件转写导出时的默认文件名模板。例如，将值设为

{{ input_file_name }} ({{ task }}d on {{ date_time }})

时，TXT 导出文件的默认名称会形如Input Filename (transcribed on 19-Sep-2023 20-39-25).txt。模板支持以下变量：

在源码层面，模板默认值{{ input_file_name }} ({{ task }}d on {{ date_time }})由 buzz/settings/settings.py 的get_default_export_file_template()提供，写入时保存在Settings.Key.DEFAULT_EXPORT_FILE_NAME；实际的文件命名逻辑（含语言、任务、输出目录拼接）位于 buzz/transcriber/transcriber.py 的get_output_file_path()中。

实时转录导出（Live transcript exports）

实时（录音）转录导出可用于将 Buzz 与其他应用（如 OBS Studio）集成。启用后，实时生成的文本转写会随生成进度持续写入文本文件；若实时录音启用了 AI 翻译，翻译文本也会一并导出，且翻译结果文件名以.translated.txt结尾。

在界面中，该功能对应Enable live recording transcription export复选框与导出文件夹设置（默认导出到系统“文档”目录），相关实现位于 buzz/widgets/recording_transcriber_widget.py。此外，实时转录还可通过环境变量BUZZ_UPLOAD_URL上传到服务器展示（详见下文高级偏好设置）。

实时转录模式（Live transcription mode）

实时录音共有三种转写追加模式，定义在 buzz/settings/recording_transcriber_mode.py 的RecordingTranscriberMode枚举中，不同模式的差异化追加/修正逻辑见 buzz/widgets/recording_transcriber_widget.py：

• Append below（向下追加）：新句子追加到已有内容下方，句子之间保留一个空行，最后一句位于底部。
• Append above（向上追加）：新句子追加到已有内容上方，句子之间保留一个空行，最后一句位于顶部。
• Append and correct（追加并修正）：新句子追加到已有转写末尾且不插入额外空行，同时会尝试修正先前已转写句子的结尾错误。该模式需要更多处理能力与更强劲的硬件支持。

模型偏好设置（Model Preferences）

模型偏好页面用于下载新的转写模型、删除不再使用的模型，其交互逻辑由 buzz/widgets/preferences_dialog/models_preferences_widget.py 实现：模型列表区分“已下载 / 可用”两组，下载通过ModelDownloader在后台线程执行并配合进度对话框（ModelDownloadProgressDialog）展示进度，删除前会弹出二次确认。

针对 Whisper.cpp，还可以下载自定义模型：在模型大小列表中选择Custom，然后粘贴模型.bin文件的下载地址（使用 Hugging Face 页面上的 "download" 按钮生成的直链即可）。custom是 buzz/model_loader.py 中WhisperModelSize枚举的合法取值，对应逻辑会走独立的自定义仓库解析分支。

为提升转写速度并降低内存占用，可以选用部分较大模型的量化版本，例如q_5量化版本。Whisper.cpp 不同量化等级的基础模型可在 Hugging Face 的 ggerganov/whisper.cpp 仓库中找到；针对不同语言训练的自定义模型也有对应的社区讨论页可供参考。注意：量化模型通过减小权重精度换取更低的资源占用，实际效果以具体模型与硬件为准。

高级偏好设置（Advanced Preferences）

为了让新用户不被复杂的参数淹没，Buzz 将一部分进阶配置以操作系统环境变量的形式开放。你需要在启动 Buzz 之前设置好这些环境变量，或编写启动脚本统一设置。

macOS 与 Linux 下可创建run_buzz.sh启动脚本，内容如下：

#!/bin/bash export VARIABLE=value export SOME_OTHER_VARIABLE=some_other_value buzz

Windows 下可创建run_buzz.bat启动脚本，内容如下：

@echo off set VARIABLE=value set SOME_OTHER_VARIABLE=some_other_value "C:\Program Files (x86)\Buzz\Buzz.exe"

也可以直接在当前操作系统的环境变量设置中添加上述变量（macOS/Linux 可在 shell 配置文件中export，Windows 可通过系统设置中的环境变量面板配置）。

可用变量一览

以下变量均可在启动前设置，多数同时在源码中具有明确的读取位置与默认值：

BUZZ_WHISPERCPP_N_THREADS：设置 Whisper.cpp 模型使用的线程数。默认值为可用 CPU 核心数的一半。在 buzz/transcriber/whisper_cpp.py、buzz/transcriber/recording_transcriber.py 等处的实现中，默认值表达式为(os.cpu_count() or 8) // 2。文档给出的调优经验是：在一台 16 线程的笔记本上，设置BUZZ_WHISPERCPP_N_THREADS=8可使转写时间提升约 15%；继续增加线程数反而会拖慢速度，因为各并行线程的结果需要合并才能产出最终答案。

BUZZ_TRANSLATION_API_BASE_URL：用于翻译的 OpenAI 兼容 API 的基础地址。与常规设置中的 Base URL 相区别，此变量专门作用于 AI 翻译链路。

BUZZ_TRANSLATION_API_KEY：用于翻译的 OpenAI 兼容 API 的密钥。

BUZZ_MODEL_ROOT：模型文件的存储根目录。同时建议将HF_HOME指向同一目录，因为 Buzz 依赖的部分库会独立下载模型。默认值为platformdirs提供的用户缓存目录（user_cache_dir）。在源码中，buzz/buzz.py 会在设置该变量时自动由它推导出HF_HOME（取os.path.dirname(_model_root)），从而让 Hugging Face 适配器（例如 MMS 语言适配器）的下载也落入自定义路径；buzz/model_loader.py 同样读取该变量作为模型根目录。

BUZZ_FAVORITE_LANGUAGES：以逗号分隔的常用语言代码列表，这些语言会被置顶显示在语言下拉列表顶部。实现见 buzz/widgets/transcriber/languages_combo_box.py：列表按逗号拆分后，仅保留 Whisper 支持的合法语言代码，并以不可选的分隔线将“常用语言”与完整语言列表隔开。

BUZZ_DOWNLOAD_COOKIEFILE：cookie 文件路径，用于下载私有视频，或作为绕过反爬虫保护（anti-bot protection）的变通方案。该变量作用于 yt-dlp 下载环节，buzz/transcriber/file_transcriber.py 会将其透传给YoutubeDL的cookiefile选项，用于 URL 导入场景的音视频下载。

BUZZ_FORCE_CPU：强制 Buzz 使用 CPU 而非 GPU，适用于老显卡（GPU 反而更慢）或 GPU 存在问题的机器。示例用法BUZZ_FORCE_CPU=true，自版本1.2.1起可用。源码中，buzz/transcriber/whisper_cpp.py 在变量非"false"时会向 Whisper CLI 追加--no-gpu参数；buzz/transcriber/transformers_whisper.py 与录音链路同样读取该变量。此外，常规设置页面的 “Disable GPU” 复选框（Settings.Key.FORCE_CPU）会在启动时把它写入环境变量（见 buzz/widgets/application.py），二者完全等效。

BUZZ_REDUCE_GPU_MEMORY：对 Hugging Face、Faster Whisper 与 Whisper.cpp 转写启用 8-bit 量化以降低 GPU 显存占用。示例用法BUZZ_REDUCE_GPU_MEMORY=true，自版本1.4.0起可用。它与常规设置中的 “Reduce GPU RAM” 复选框等效（见上文），buzz/model_loader.py 中采用!= "false"的宽松判定，即任意非false值都会开启。

BUZZ_MERGE_REGROUP_RULE：在合并带词级时间戳的转写片段时使用的自定义 regroup 合并规则。可用选项参考 stable-ts 项目的 regrouping methods 文档。自版本1.3.0起可用。该变量被 buzz/plugins/transcript_resizer/plugin.py 读取，用于覆盖转录重排插件（transcript resizer）默认构建的合并规则字符串（如mg=0.2、sp=...、sl=...等参数组合）。

BUZZ_DISABLE_TELEMETRY：Buzz 会收集基本的操作系统名称与架构等使用统计信息，用于更好地聚焦开发方向；设置该变量可禁用统计收集。示例用法BUZZ_DISABLE_TELEMETRY=true，自版本1.3.0起可用。实现见 buzz/widgets/application.py：未禁用时，应用启动会通过 PostHog 上报app_launched事件。

BUZZ_DISABLE_UPDATE_CHECK：禁用启动时的更新检查。示例用法BUZZ_DISABLE_UPDATE_CHECK=true，自版本1.4.5起可用。buzz/widgets/main_window.py 在检测到该变量时会跳过启动更新检查并输出调试日志。

BUZZ_UPLOAD_URL：将实时录音的转写与翻译结果上传到指定服务器，以便在网页上展示。设置该变量为期望的上传地址即可（例如BUZZ_UPLOAD_URL=http://localhost:5000/upload），可配合 buzz-transcription-server 作为接收端。Buzz 会通过POST请求上传如下 JSON：{"kind": "transcript", "text": "Sample transcript"}或{"kind": "translation", "text": "Sample translation"}。自版本1.3.0起可用。相关上传逻辑位于 buzz/widgets/recording_transcriber_widget.py，仅在变量非空时执行。

HF_ENDPOINT：Hugging Face 下载端点，中国用户可设置为HF_ENDPOINT=https://hf-mirror.com以加速模型下载。

BUZZ_PARAGRAPH_SPLIT_TIME：以毫秒为单位的静音时长阈值。当转写片段之间的静音达到该值时，导出 TXT 文本会在片段之间插入两个换行符以切分段落。默认值为2000（2 秒），自版本1.3.0起可用。实现见 buzz/transcriber/file_transcriber.py 的write_output()：导出 TXT 时会比较相邻片段的时间间隔segment.start - previous_end_time是否达到阈值，从而决定是否追加\n\n。

关于遥测数据

遥测上报的内容示例（文档原文）如下：

Buzz: 1.3.0, locale: ('lv_LV', 'UTF-8'), system: Linux, release: 6.14.0-27-generic, machine: x86_64, version: #27~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue Jul 22 17:38:49 UTC 2,

从 buzz/widgets/application.py 的实现看，每次启动时上报的属性包括：应用版本（app）、区域设置（locale）、操作系统（system）、内核版本（release）、机器架构（machine）与系统版本（version）。匿名用户标识由Settings.get_user_identifier()生成的 UUID 承担。设置BUZZ_DISABLE_TELEMETRY=true即可完全关闭该类统计。

小结：GUI 与环境变量的配合使用

• 常规场景：打开 Preferences 窗口即可完成 OpenAI API 认证、默认导出文件名模板、实时转录导出与追加模式、显存优化等绝大多数日常配置，所有修改即时写入并持久化。
• 进阶与自动化场景：借助BUZZ_*环境变量可在不打开 GUI 的情况下统一配置线程数、翻译 API、模型缓存目录、常用语言、cookie、CPU/量化开关、重组规则、遥测与更新检查、实时上传地址与段落切分阈值；编写run_buzz.sh/run_buzz.bat启动脚本即可批量注入，适合团队统一分发与无人值守部署。
• 两者等价关系：注意 GUI 中的 “Reduce GPU RAM” 与BUZZ_REDUCE_GPU_MEMORY、“Disable GPU” 与BUZZ_FORCE_CPU是同一开关的两种表达形式，设置其一即可，避免困惑。

【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAI's Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz