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

Buzz 偏好设置完全指南GUI 配置项、导出文件模板与高级环境变量详解【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAIs Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzzBuzz 是一款基于 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导入文件的文件名不含扩展名audio例如导入路径为/path/to/audio.wav时task转写任务类型transcribe、translatelanguage语言代码en、fr、yo等model_type模型类型Whisper、Whisper.cpp、Faster Whisper等model_size模型大小tiny、base、small、medium、large等date_time导出时间格式%d-%b-%Y %H-%M-%S19-Sep-2023 20-39-25在源码层面模板默认值{{ 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.pyAppend 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 VARIABLEvalue export SOME_OTHER_VARIABLEsome_other_value buzzWindows 下可创建run_buzz.bat启动脚本内容如下echo off set VARIABLEvalue set SOME_OTHER_VARIABLEsome_other_value C:\Program Files (x86)\Buzz\Buzz.exe也可以直接在当前操作系统的环境变量设置中添加上述变量macOS/Linux 可在 shell 配置文件中exportWindows 可通过系统设置中的环境变量面板配置。可用变量一览以下变量均可在启动前设置多数同时在源码中具有明确的读取位置与默认值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_THREADS8可使转写时间提升约 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_COOKIEFILEcookie 文件路径用于下载私有视频或作为绕过反爬虫保护anti-bot protection的变通方案。该变量作用于 yt-dlp 下载环节buzz/transcriber/file_transcriber.py 会将其透传给YoutubeDL的cookiefile选项用于 URL 导入场景的音视频下载。BUZZ_FORCE_CPU强制 Buzz 使用 CPU 而非 GPU适用于老显卡GPU 反而更慢或 GPU 存在问题的机器。示例用法BUZZ_FORCE_CPUtrue自版本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_MEMORYtrue自版本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默认构建的合并规则字符串如mg0.2、sp...、sl...等参数组合。BUZZ_DISABLE_TELEMETRYBuzz 会收集基本的操作系统名称与架构等使用统计信息用于更好地聚焦开发方向设置该变量可禁用统计收集。示例用法BUZZ_DISABLE_TELEMETRYtrue自版本1.3.0起可用。实现见 buzz/widgets/application.py未禁用时应用启动会通过 PostHog 上报app_launched事件。BUZZ_DISABLE_UPDATE_CHECK禁用启动时的更新检查。示例用法BUZZ_DISABLE_UPDATE_CHECKtrue自版本1.4.5起可用。buzz/widgets/main_window.py 在检测到该变量时会跳过启动更新检查并输出调试日志。BUZZ_UPLOAD_URL将实时录音的转写与翻译结果上传到指定服务器以便在网页上展示。设置该变量为期望的上传地址即可例如BUZZ_UPLOAD_URLhttp://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_ENDPOINTHugging Face 下载端点中国用户可设置为HF_ENDPOINThttps://hf-mirror.com以加速模型下载。BUZZ_PARAGRAPH_SPLIT_TIME以毫秒为单位的静音时长阈值。当转写片段之间的静音达到该值时导出 TXT 文本会在片段之间插入两个换行符以切分段落。默认值为20002 秒自版本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_TELEMETRYtrue即可完全关闭该类统计。小结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 OpenAIs Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考