老笔记本实现语音识别功能（macOS 12.7.6 修订版）

 Posted on October 19, 2026  |  4 minutes  |  686 words  |  Wang

本文是 2025-12 那篇笔记的修订版。系统从 macOS 10.15.7 升级到 12.7.6 后，原方案里有些结论已经过时，有些命令本来就有问题，这里重新审查并整理成目前最推荐的做法。

目标：在老 Intel 笔记本（16GB 内存）上，完全离线把中文音频转成逐字稿（txt）和字幕（srt）。

一、结论（太长不看）

项目推荐
引擎whisper.cpp（源码编译，仅 CPU）
可执行文件build/bin/whisper-cli（不是 main，也不是 whisper-cpp）
模型large-v3-turbo-q5_0（约 547 MiB）；如果效果或速度不满意，退回 medium-q5_0
编译选项-DGGML_METAL=OFF（Intel 机器继续关掉 Metal）
安装方式不要依赖 Homebrew，用 Xcode 命令行工具 + cmake 自己编译
质量参数加 --vad（静音检测）和 --prompt（简体中文+标点引导）

二、对原方案的审查

原方案内容现在的判断处理
OpenAI Whisper Python 版（pip + Python 3.8/3.9）在 Intel CPU 上最慢，依赖多；“不要 3.11"之类的限制是当年的环境约束不再推荐
brew install whisper-cpp、brew install ffmpegHomebrew 已把 macOS 12 和 Intel Mac 都降到 Tier 3：不再为新版本构建预编译包，容易变成本机从源码编译，慢且常失败改为源码编译 whisper.cpp；ffmpeg 用独立二进制
cd /usr/local/share/whisper-cpp && ./models/download-ggml-model.sh路径和脚本位置都是 AI 猜的，不可靠改为在克隆下来的仓库里下载模型
可执行文件叫 whisper-cpp 或 ./main新版是 whisper-cli，main 已被弃用统一用 whisper-cli
仓库 ggerganov/whisper.cpp已迁到 ggml-org/whisper.cpp用新地址
编译报 MTLGPUFamilyApple7 未声明，原因是 Catalina 的 SDK 太老原因判断没错。升到 12.7.6 后，配套的命令行工具 SDK 已包含这些定义，这个报错大概率不会再出现仍然建议关 Metal，见下
关闭 Metal，用 CPU方向正确。官方 README 把 Metal/Core ML 加速描述为面向 Apple Silicon；Intel 集显上收益很小，还多一层兼容风险保留：-DGGML_METAL=OFF
模型用 medium当年合理，现在有更好的选择：large-v3-turbo 的量化版体积更小、速度更快首选 large-v3-turbo-q5_0
输出文件名是 test1.txt实际会生成 test1.mp3.txt，除非用 -of 指定前缀用 -of 控制输出名
“1 小时音频 ≈ 1.2–1.5 小时 CPU”没有依据，AI 估的数字删除，改为自己用 time 实测
必须先把音频转 16kHz WAV对 mp3 / wav / flac / ogg 不再必要（你原来直接 -f xxx.mp3 就能跑）；m4a、mp4、mov 等仍需转换只在需要时转换
西语 iPhone 视频字幕那一段思路对，但用的是旧的 ./main并入第七节，改成 whisper-cli
Buzz v0.7.x、faster-whisper来自 AI 的建议，我没有核实它们在 Intel + Monterey 上的可用性，也没有必要再增加一条路线不再列入主方案

三、环境准备（macOS 12.7.6）

1. Xcode 命令行工具

xcode-select --install

如果提示找不到更新，到 Apple 开发者下载页（developer.apple.com/download/all）手动下载适配 Monterey 的 Command Line Tools。

确认：

clang --version
git --version
python3 --version

2. cmake

任选其一：

# 方式 A：用命令行工具自带的 python3 安装
python3 -m pip install --user cmake
# 然后确保 ~/Library/Python/3.9/bin 在 PATH 里（路径以实际 python 版本为准）

或者从 cmake.org 下载 macOS 的 dmg，装好后按它的提示把 cmake 加入 PATH。

确认：cmake --version

3. ffmpeg（只有处理 m4a / mp4 / mov 才需要）

mp3 / wav / flac / ogg 可以直接喂给 whisper-cli，可以先不装。需要时，下载 Intel 版的静态 ffmpeg 二进制（例如 evermeet.cx 提供的构建），放到 ~/bin 并加入 PATH，避免走 Homebrew 的源码编译。装好后：

ffmpeg -version

四、编译 whisper.cpp（仅 CPU）

mkdir -p ~/git && cd ~/git
git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp

# 可选：固定到某个发布版本（写这篇时最新是 v1.9.3；tag 不存在就保持默认分支）
# git checkout v1.9.3

cmake -B build -DGGML_METAL=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build -j --config Release

检查：

./build/bin/whisper-cli -h | head

说明：

  • 在 Intel 上，编译时默认会针对本机 CPU 优化（AVX/AVX2 等），所以在要运行的这台机器上编译即可，不要拷贝别的机器编出来的二进制。
  • 以后更新：git pull，然后重新执行最后两条 cmake 命令。

五、下载模型

cd ~/git/whisper.cpp
bash ./models/download-ggml-model.sh large-v3-turbo-q5_0

得到 models/ggml-large-v3-turbo-q5_0.bin（约 547 MiB，内存占用约 2GB 量级，16GB 绰绰有余）。

模型体积用途
large-v3-turbo-q5_0547 MiB首选
large-v3-turbo-q8_0约 834 MiB想要更高精度时
medium-q5_0约 514 MiBturbo 效果不满意或速度异常时的备选
large-v3-q5_0约 1.1 GiB追求最高准确率，速度会慢很多

重要：turbo 在中文上的表现我没有在你的音频上测过。建议拿一段 3–5 分钟的典型课程音频，分别用 large-v3-turbo-q5_0 和 medium-q5_0 各跑一遍，对比速度和错字，再决定默认用哪个。

可选：下载静音检测（VAD）模型

curl -L -o models/ggml-silero-v6.2.0.bin \
  https://huggingface.co/ggml-org/whisper-vad/resolve/main/ggml-silero-v6.2.0.bin

VAD 能在静音/背景音处跳过识别，减少幻觉和重复循环，长音频尤其有用。

六、基本使用（中文逐字稿）

cd ~/git/whisper.cpp

time ./build/bin/whisper-cli \
  -m models/ggml-large-v3-turbo-q5_0.bin \
  -f /path/to/lesson.mp3 \
  -l zh \
  -t "$(sysctl -n hw.physicalcpu)" \
  --vad -vm models/ggml-silero-v6.2.0.bin \
  --prompt "以下是普通话讲课内容，请使用简体中文，并加上逗号、句号等标点。" \
  -otxt -osrt \
  -of /path/to/lesson

输出：/path/to/lesson.txt 和 /path/to/lesson.srt。

参数说明：

参数作用
-l zh指定中文，比 auto 更稳
-t线程数，这里取物理核心数；默认值偏保守
--vad -vm …启用静音检测，需要上面下载的 VAD 模型
--prompt引导输出简体和标点（Whisper 中文输出常常没有标点，或者混入繁体）
-otxt / -osrt输出纯文本 / 字幕
-of输出文件前缀，不加的话文件名会是 lesson.mp3.txt

关于 --prompt 的两点提醒：

  1. 写成"说明性"的话即可，不要放太长。你原来的写法（带一句示例，如"你好，这是时寒冰微课堂。"）有效，但示例句偶尔会被模型原样吐进结果里。如果发现开头或段落间冒出示例句，就改成纯说明、不带示例。
  2. 如果结果仍夹杂繁体，可以用 OpenCC 做一次繁转简后处理。

出现重复循环、整段同一句话怎么办

按顺序试：确认已开启 --vad；再加 -mc 0（不带入上一段上下文）；仍不行就换 medium-q5_0。

七、批量处理脚本与字幕（含其他语种）

1. 批量脚本 asr.sh

#!/usr/bin/env bash
set -euo pipefail

W="$HOME/git/whisper.cpp"
CLI="$W/build/bin/whisper-cli"
MODEL="$W/models/ggml-large-v3-turbo-q5_0.bin"
VAD="$W/models/ggml-silero-v6.2.0.bin"
THREADS="$(sysctl -n hw.physicalcpu)"
PROMPT="以下是普通话讲课内容，请使用简体中文，并加上逗号、句号等标点。"

for f in "$@"; do
  base="${f%.*}"
  if [ -f "$base.txt" ]; then echo "跳过（已有结果）: $f"; continue; fi

  ext="$(echo "${f##*.}" | tr 'A-Z' 'a-z')"
  tmpdir=""
  case "$ext" in
    mp3|wav|flac|ogg) input="$f" ;;
    *) tmpdir="$(mktemp -d)"
       input="$tmpdir/in.wav"
       ffmpeg -y -loglevel error -i "$f" -ar 16000 -ac 1 -c:a pcm_s16le "$input" ;;
  esac

  "$CLI" -m "$MODEL" -f "$input" -l zh -t "$THREADS" \
    --vad -vm "$VAD" --prompt "$PROMPT" \
    -otxt -osrt -of "$base"

  [ -n "$tmpdir" ] && rm -rf "$tmpdir"
done

使用：

chmod +x asr.sh
./asr.sh ~/Downloads/课程/*.mp3

2. 其他语种的字幕（例如西语 iPhone 视频）

# 先提取音频（mov / mp4 不能直接读）
ffmpeg -i input.mov -ar 16000 -ac 1 -c:a pcm_s16le output.wav

~/git/whisper.cpp/build/bin/whisper-cli \
  -m ~/git/whisper.cpp/models/ggml-large-v3-turbo-q5_0.bin \
  -f output.wav -l es \
  -osrt -ml 40 -sow \
  -of output
  • -ml 40：每条字幕最多约 40 个字符；-sow：不在单词中间断开。
  • 需要网页用的 VTT 时，把 -osrt 换成 -ovtt。
  • 视频内容较短、对速度更在意时，可以换更小的模型（如 small-q5_1）。

整个流程（提取音频、识别、生成字幕）都在本地完成，不上传任何数据。

八、常见问题

现象处理
whisper-cli: command not found用完整路径 ./build/bin/whisper-cli，或在 ~/bin 里建软链接
编译时仍出现 MTLGPUFamily… 报错说明没有关掉 Metal：删除 build 目录，重新带 -DGGML_METAL=OFF 配置
cmake: command not foundPATH 没配好，见第三节
速度慢先确认用的是 Release 构建、-t 设了物理核心数；再试量化模型或更小模型；用 time 记录实测倍率
结果夹杂繁体保留 --prompt 的"简体中文"引导，必要时 OpenCC 后处理
开头或静音段出现莫名其妙的句子开启 --vad；去掉 prompt 里的示例句
输出文件名带 .mp3.txt加 -of 指定前缀
m4a / mp4 打不开先用 ffmpeg 转成 16kHz 单声道 wav

九、还没有核实、需要你自己验证的地方

  • 我没有在你的机器上运行过这套步骤；命令来自 whisper.cpp 官方仓库当前的文档和发布信息，以及对原笔记的审查。
  • large-v3-turbo-q5_0 在你的课程音频上的准确率和速度，需要实测对比。
  • 静态 ffmpeg 和 cmake 的具体安装方式取决于你选的来源和 PATH 设置，按各自页面的说明为准。
  • macOS 12.7.6 是 Monterey 的最后一个版本，不会再有新的系统更新；这套方案是离线工作的，风险主要来自工具链越来越难装，所以把依赖压到"命令行工具 + cmake + 一个模型文件"是刻意的。

参考

📚 所有文章