Buzz macOS 语音转文字安装排障手册

Buzz macOS 语音转文字安装排障手册【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAIs Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzzBuzz 是基于 OpenAI Whisper 的离线语音转文字工具PyQt6 桌面应用可本地转写音视频与麦克风实时录音。macOS 上最常见的两类故障Intel Mac 装新版起不来、Apple Silicon 装了却没吃到 GPU 加速。本文按先自检 → 再部署 → 后验证回退给出可复制命令。图1Buzz 主界面任务队列列出文件名、所选 Whisper 后端、任务类型与处理状态装前自检架构、系统与依赖三查诊断结论先给macOS 的部署成败90% 卡在处理器架构与 Python 版本两条硬门槛上。跑完下面三条命令对号入座再进方案比盲目重装省时。第一条看处理器架构决定装哪份包uname -m输出arm64Apple SiliconM 系列芯片走 Apple Silicon 通道输出x86_64Intel 芯片注意 1.4.6 起官方不再提供新版最后支持 Intel 的版本是 1.4.5第二条看系统版本CoreML 加速要求较新系统sw_vers第三条确认运行时依赖。Buzz 转写依赖 ffmpegPython 门槛以构建配置 pyproject.toml 的requires-python 3.13,3.14为准README 写的 3.12 已滞后ffmpeg -version python3 --versionffmpeg 缺失会报FileNotFoundError: ...ffmpeg先装 ffmpeg 再谈转写。三条部署路径从预编译到源码编译三条路径互斥按操作成本从低到高选选对一条即可不要混装。路径一按 uname -m 选对架构的 .dmg适用场景想开箱即用、不想碰命令行、机器是 Apple Silicon。从官方发布页下载标记为arm64的.dmg拖入 Applications。首次打开被 Gatekeeper 拦截时到 系统设置 隐私与安全性 点仍要打开。# 仅确认已安装的 App 是否为 Apple Silicon 架构 lipo -archs /Applications/Buzz.app/Contents/MacOS/Buzz预期输出arm64。失败特征若输出x86_64说明你拿了 Intel 版arm64 机器上会走 Rosetta 2 翻译GPU 模块调用失败、转写明显变慢。路径二Python 3.13 环境安装 buzz-captions适用场景已有 Python 环境、想要可脚本调用的 CLI或预编译包反复异常时改用安装器通道。在 Python 3.13 虚拟环境里安装并启动python3 -m venv buzz-venv source buzz-venv/bin/activate pip install buzz-captions python -m buzz预期窗口弹出或终端打印版本后进入交互。失败特征ERROR: Package buzz-captions requires a different Python即版本不符退回python3 --version确认是否 3.13。Apple Silicon 下 torch 走标准 PyPI 包无需额外 CUDA 参数CUDA 仅 Nvidia 需要。路径三源码编译 whisper.cpp 并开启 CoreML 加速适用场景要最新特性、或需要手动控制 GPU 加速开关的进阶用户。arm64 编译时 Makefile 自动带上-DWHISPER_COREML1这就是 Mac 的 GPU 加速开关。git clone https://gitcode.com/GitHub_Trending/buz/buzz cd buzz uv venv source .venv/bin/activate uv sync make buzz/whisper_cpp # arm64 自动启用 CoreML python -m buzz预期make结束时在buzz/whisper_cpp/生成whisper-cli、whisper-server与libwhisper.dylib随后python -m buzz正常起界面。失败特征cmake 阶段报-DWHISPER_COREML相关编译错误多为 Xcode 命令行工具不全先xcode-select --install再重跑。装好怎么验跑一条 CLI 转写并看关键参数跑通的标准不是界面能开而是能转出一条带时间戳的文本。用 CLI 对短音频做端到端验证比反复点界面更快定位问题。python -m buzz add testdata/whisper-french.mp3 --model-type whispercpp --model-size base --language fr --word-timestamps --srt预期工作目录生成同名.srt打开能看到逐句时间轴与法语文本无报错。关键参数两个改前先记默认值与副作用--model-size默认tinycli.py 里WhisperModelSize.TINY为缺省。tiny最快但法语等非英语语种误差大验证用base/medium更稳副作用是耗时随模型档位近似翻倍。--model-type默认whisperOpenAI 原始实现慢且吃内存。macOS 上推荐显式指定whispercpp——它是 C 优化实现能跑集成显卡甚至纯 CPU官方 FAQ 明确Mac 上最佳选项。图2偏好设置 - Models 页按 Whisper.cpp 分组管理可下载与已下载的模型回退清单按报错原文对号入座跑不通时不要重装先抄报错原文比对下面四条。报错原文Unanticipated host error[PaErrorCode-9999]→ 定位系统拦了麦克风权限 → 处置系统设置 隐私与安全性 麦克风为 Buzz 打勾后重启应用FAQ 第 6 条。报错特征转写中进程崩溃或输出为空 → 定位模型文件下载不完整/损坏 → 处置Help - Preferences - Models删除该模型重新下载缓存目录为~/Library/Caches/Buzz可手动清掉残缺文件FAQ 第 8 条。报错特征启动即闪退、日志见非法指令类崩溃 → 定位CPU 不支持 AVX2老硬件官方不支持 → 处置换支持 AVX2 的机器或 Intel Mac 回退到 1.4.5README 标注的 Intel 末版。报错特征Intel Mac 装 1.4.6 无法运行、或发布页找不到 Intel 包 → 定位1.4.6 起仅支持 Apple Silicon发布通道与主仓库不同步、商店版滞后 → 处置确认芯片类型Intel 机器改用 1.4.5arm64 机器改走路径一。Buzz 按版本节奏持续发布稳定版1.4.6为当前主线。安装、GPU 与麦克风类问题优先查 安装文档 与 FAQ仍未解决再到项目 issue 区反馈并附上Help - About Buzz里Show logs导出的日志。【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAIs Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考