MacWhisper 命令行工具：安装 mw，在“终端”里转写，以及全部参数

作者 · 发布于

MacWhisper 自带一个命令行工具，叫 mw。它让你在“终端”里操作这款 App：转写文件和整个文件夹，识别说话人，输出字幕或 JSON，还能列出和切换模型。它通过本地套接字与正在运行的 MacWhisper 通信，所以会用到你已经设好的引擎、模型和设置，如果 App 没有打开，它会自动启动。

我做的 YapToText 是另一款 Mac 听写和文件转写 App，所以请在阅读我对 MacWhisper 的评述时把这一点考虑在内。这里关于 MacWhisper 的每一条事实，都来自它的帮助文章 MacWhisper Command-Line Tool，我在 2026年10月10日查阅。

在 Mac App Store 下载 YapToText免费下载。无需账号，没有锁定的功能。需要搭载 Apple 芯片的 Mac 和 macOS 14 或更高版本。 源代码在 GitHub 上。

用其他语言阅读： English, العربية, Čeština, Dansk, Deutsch, Ελληνικά, Español, Suomi, Français, עברית, हिन्दी, Magyar, Bahasa Indonesia, Italiano, 日本語, 한국어, Norsk, Nederlands, Polski, Português, Română, Русский, Slovenčina, Svenska, ไทย, Türkçe, Українська, Tiếng Việt, 繁體中文

安装 mw

  1. 打开 MacWhisper，进入 Settings（设置），再进入 Advanced（高级）。
  2. 在 Command-Line Tool（命令行工具）下，点击 Install（安装）。
  3. 如果 macOS 要求，输入你的 Mac 密码。写入 /usr/local/bin 需要它。
  4. 打开一个新的“终端”窗口，运行 mw version。

工具会安装到 /usr/local/bin/mw，完成后设置面板里会显示绿色对勾。如果 mw version 打印出版本号，就说明可以用了。想删除它，回到同一个面板，点击 Uninstall（卸载）。

转写一个文件

mw transcribe ~/Desktop/meeting.m4a
mw transcribe meeting.m4a > transcript.txt
mw transcribe meeting.m4a -o transcript.txt
mw transcribe meeting.m4a | pbcopy

结果：转写文字会输出到标准输出。进度信息输出到标准错误，所以重定向到文件时，文件里只有转写文字。

默认情况下，命令行转写不会被保存。它打印出来就丢弃，只有加上 --persist，才会出现在 MacWhisper 的历史记录里。按 Ctrl+C 可以停止运行。已经存在的输出文件不会被替换，除非加上 --overwrite。

全部命令

以下内容来自 MacWhisper 的帮助文章，2026年10月10日查阅。在任何命令后加上 --help，可以看到它的选项。

命令作用
mw显示状态概览：App 是否可连接、当前选中的模型、已下载的模型，以及示例命令
mw version打印 MacWhisper 的版本。可以用来检查连接是否正常
mw models list列出已安装的转写模型，每个模型都有一个 ID
mw models select更改当前使用的模型，命令行工具和 App 里都会改
mw transcribe转写音频或视频文件，或者整个文件夹，并打印文字

mw transcribe 的参数

来自同一篇文章。所选模型无法转写的语言会报错。

参数作用
--speakers, --no-speakers本次运行打开或关闭说话人识别。打开后，转写文字会按说话人分组
--format默认是 txt，也可以是 srt、vtt、json、csv、md、html 或 avid
--styletranscript、subtitles 或 segments，与 App 的导出面板里的样式相同
--model本次运行使用指定的模型，不改变 App 里的选择
--languageISO 语言代码，例如 en 或 de，也可以是 auto 或 multilingual
--output, -o把转写文字写入文件
--output-dir批量模式。每个输入文件生成一份转写，写入指定文件夹
--recursive传入文件夹时，包含其中的子文件夹
--stream每完成一段就打印出来。只适用于本地引擎
--persist把这次转写保存到 MacWhisper 的历史记录
--timestamps, --milliseconds, --group, --max-chars-per-line, --fps微调排版

各种格式，以及哪些需要 Pro

来自同一篇文章。MacWhisper 价格页介绍了 Pro 的价格。

格式得到什么许可
txt纯文本所有人
srtSubRip 字幕所有人
vttWebVTT 字幕所有人
csv每行包含开始时间、结束时间和转写文字，识别到说话人时还有说话人所有人
json毫秒级时间戳、每段的说话人，以及逐词时间Pro
mdMarkdown，带时间戳的文字块和说话人标题Pro
html独立的 HTML 文档Pro
avidAvid 字幕文本，带 SMPTE 时间码Pro

转写整个文件夹

mw transcribe ~/Recordings --recursive --output-dir ~/Transcripts
mw transcribe ~/Videos --output-dir ~/Subs --format srt
mw transcribe interview.m4a --speakers -o interview.txt

结果：每个输入文件都会生成一个以它命名的文件，文件夹结构也会原样保留。转写失败的文件会被报告并跳过，其余的继续运行。

说话人识别需要支持它的模型。说话人识别页面介绍了 App 的这一部分。

不能用的时候

  • mw: command not found。打开一个新的“终端”窗口，或者把 /usr/local/bin 加入 PATH。
  • 卡住不动。退出并重新打开 MacWhisper，然后再试 mw version。
  • 模型 ID 不被识别。运行 mw models list 查看准确的 ID，并先在 App 里下载这个模型。
  • 某个格式提示需要 Pro。json、md、html 和 avid 需要 Pro 许可。
  • 沙盒错误。沙盒里的程序，包括一些 AI 编程工具，可能无法连接 MacWhisper 的套接字。请直接在“终端”里运行 mw。

MacWhisper 故障排查页面介绍了 App 本身的问题。

在“终端”里用的免费办法

YapToText 没有命令行工具。它一次转写你拖进去的一个文件，输出纯文本，免费。如果你想用“终端”，又不想花钱买东西，whisper.cpp 是开源的，也是 YapToText 所基于的引擎。本地 Whisper 指南里有相关命令，开源转写软件页面比较了四款免费工具。

在 Mac App Store 下载 YapToText免费下载。无需账号，没有锁定的功能。需要搭载 Apple 芯片的 Mac 和 macOS 14 或更高版本。 源代码在 GitHub 上。

小结

  • 安装。Settings，Advanced，Command-Line Tool，Install。
  • 运行。mw transcribe，后面跟文件或文件夹。
  • 免费格式。txt、srt、vtt 和 csv。
  • Pro 格式。json、md、html 和 avid。
  • 历史记录。不加 --persist 就什么都不保存。

如果 MacWhisper 更改了这个工具，而这个页面没有跟上，请在 GitHub 上提交 issue（英文）。每一条我都会看。

在 Mac App Store 下载 YapToText免费下载。无需账号，没有锁定的功能。需要搭载 Apple 芯片的 Mac 和 macOS 14 或更高版本。 源代码在 GitHub 上。

关于作者。 Ryleigh Newman 从事软件开发，用手打字有困难，每天都用本站介绍的 YapToText 听写。本页译自英文。App 的界面和网站的其他页面是英文的。 进一步了解这个项目（英文）。

指南

更多指南（英文）

资料来源

常见问题

MacWhisper 有命令行工具吗？

有。它叫 mw，在 MacWhisper 的 Settings 里，Advanced 下的 Command-Line Tool 处安装。

怎么在“终端”里用 MacWhisper 转写文件？

运行 mw transcribe，后面加上文件路径。转写文字会输出到标准输出，加上 -o 则写入文件。

MacWhisper 命令行工具免费吗？

它的帮助文章说，txt、srt、vtt 和 csv 输出所有人都能用，json、md、html 和 avid 需要 Pro 许可。

MacWhisper 命令行能转写整个文件夹吗？

能。把文件夹传给 mw transcribe，加上 --recursive 包含子文件夹，再加上 --output-dir，每个文件生成一份转写。

用 mw 时 MacWhisper 必须是打开的吗？

它与正在运行的 App 通信，如果 MacWhisper 没有打开，会自动启动它。