Local Transcription

视频转文字本地引擎安装教程

这个功能使用你电脑上的免费本地 Whisper 引擎。插件不内置引擎和模型文件；安装完成后，转写在本机运行，不需要登录小红书，不消耗 OpenAI API 费用，也不会把视频上传到插件作者服务器。

1 先选电脑系统

Windows 看文件夹摆放；Mac 优先用 Docker。

2 准备模型文件

下载 ggml-small.bin 或 ggml-base.bin，不用解压。

3 复制对应命令

终端窗口保持打开，再回插件里点测试。

下载链接 Windows 教程 Mac 教程插件测试常见问题

Downloads

Windows / Mac 要准备的东西不同。

Windows 用户认准 whisper-bin-x64.zip、一个 .bin 模型文件和 ffmpeg.exe。Mac 用户不要照 Windows 下载这几个可执行文件，推荐安装 Docker Desktop，再下载同一个 .bin 模型文件。备用镜像不是 Multi Source Sync 作者维护，请按文件名确认下载内容。

whisper.cpp

真正负责转写的程序。Windows 用压缩包里的 whisper-server.exe；Mac 推荐让 Docker 帮你运行它。

Whisper 模型

识别语音用的文件。新手优先下载 ggml-small.bin；电脑比较慢就用 ggml-base.bin。

FFmpeg

负责让转写程序读懂 mp4、mov、webm 等视频。Windows 复制 ffmpeg.exe；Mac Docker 方案里已经包含。

工具推荐链接备用链接说明

whisper.cpp 引擎 GitHub 最新发布 whisper-bin-x64.zip SourceForge 镜像 SourceForge x64 包 Windows 普通电脑优先下载 whisper-bin-x64.zip。Mac 不要下载这个包。

Whisper 模型 模型列表 ggml-small.bin ggml-base.bin HF Mirror small 镜像 base 镜像 small 平衡准确率和速度；低配电脑先试 base。不要下载 .en 模型。

FFmpeg Windows essentials 官方入口 BtbN GitHub 让 whisper.cpp 识别 mp4、mov、webm 等视频。

Docker Desktop Docker Desktop 官方下载 Mac 安装说明 Mac 推荐方案使用。可以理解为给本地引擎准备一个单独运行环境。

Windows Setup

Windows 用户按这个顺序装。

最终样子

先看最终文件夹应该长什么样。

下面只是示例位置。你也可以放到别的固定文件夹，但后面的命令要在这个文件夹里执行。

D:\tools\whisper\

whisper-server.exe 转写程序
whisper.dll、ggml.dll、ggml-cpu-*.dll 等程序依赖文件，必须和 whisper-server.exe 同一层
ffmpeg.exe 放在同一层，负责读取视频
models\
- ggml-small.bin 模型文件，也可以换成 ggml-base.bin

ggml-small.bin 和 ggml-base.bin 都是模型文件，下载后不用解压。命令里写哪个，models 文件夹里就要有哪个。

1

建一个固定文件夹

例如新建 D:\tools\whisper。后面所有文件都放在这里，方便以后继续使用。

2

解压 whisper.cpp

把 whisper-bin-x64.zip 解压后，找到 whisper-server.exe 和解压包 Release 文件夹里的所有 .dll 文件，一起复制到 D:\tools\whisper。用鼠标拖过去也可以，但目标是复制一份到这个文件夹。

3

放入模型文件

在 D:\tools\whisper 里新建 models 文件夹，把 ggml-small.bin 或 ggml-base.bin 放进去。

4

复制 ffmpeg.exe

解压 ffmpeg-release-essentials.zip，进入里面的 bin 文件夹，把 ffmpeg.exe 复制到 D:\tools\whisper。

5

在这个文件夹打开终端

打开 D:\tools\whisper，在空白处右键，选择“在终端中打开”或“在 PowerShell 中打开”。

6

启动本地服务

先确认终端是在 D:\tools\whisper 里打开的，再复制下面整行命令并回车。这里说的“本地服务”，就是这个保持打开的黑窗口。

复制命令

把下面这一整行复制到终端里，然后按 Enter。

从 .\whisper-server.exe 开始，到最后的 --convert 结束，中间不要漏字。运行后看到窗口持续停在那里，就表示本地引擎正在等待插件调用。

.\whisper-server.exe -m .\models\ggml-small.bin -l zh --host 127.0.0.1 --port 8080 --convert

Windows PowerShell 在 D:\tools\whisper 文件夹中运行 whisper-server.exe 命令的示意图 — 示意图里的黑窗口需要保持打开。关闭窗口后，Obsidian 插件就连不上本地引擎。

模型名可以换

只建议改 -m 后面的模型路径，例如把 .\models\ggml-small.bin 换成 .\models\ggml-base.bin。前提是这个文件真的在 models 文件夹里。

这些可能需要换

如果你下载的是 ggml-base.bin，就必须改模型名；如果 8080 端口被其他软件占用，才需要改 --port 8080，并同步修改插件里的本地引擎地址。

普通用户不要动

.\whisper-server.exe、-l zh、--host 127.0.0.1 和 --convert 建议保持原样。中文小红书视频固定用 zh 更稳。

看到窗口持续运行后不要关闭它，直接回到 Obsidian 插件里测试。会配置系统环境变量的用户，也可以把 FFmpeg 的 bin 加入 Path，但新手按上面复制 ffmpeg.exe 更简单。

macOS Setup

Mac 用户优先用 Docker 启动。

先别下错

Mac 不照 Windows 的文件夹摆法。

Mac 用户不要下载 whisper-bin-x64.zip、ffmpeg.exe 或 xcframework.zip。推荐安装 Docker Desktop，让 Docker 直接运行 whisper-server；你只需要额外准备一个模型文件。

~/tools/whisper/

models/
- ggml-small.bin 模型文件，也可以换成 ggml-base.bin

这里的 ~ 表示你的 Mac 个人文件夹。模型 .bin 文件下载后不用解压；命令里写哪个文件名，models 文件夹里就要有哪个。

1

安装 Docker Desktop

从上面的官方链接安装 Docker Desktop。安装后先打开它，看到 Docker 已经在运行，再继续下面步骤。

2

新建模型文件夹

打开 Mac 的“终端”，复制下面命令并回车，用来创建 ~/tools/whisper/models 文件夹。

mkdir -p ~/tools/whisper/models

3

放入模型文件

把下载好的 ggml-small.bin 或 ggml-base.bin 放到 ~/tools/whisper/models 里。可以在 Finder 里按 Command + Shift + G，输入这个路径打开。

4

复制 Docker 命令

Docker Desktop 保持打开，在终端里复制下面整行命令并回车。第一次运行会下载本地引擎镜像，可能需要等几分钟。

Mac 推荐命令

把下面这一整行复制到 Mac 终端里，然后按 Return。

看到终端持续停在那里，就表示本地引擎已经启动。Docker Desktop 和这个终端窗口都不要关闭，关闭后插件就连不上。

docker run --rm -it -p 8080:8080 -v "$HOME/tools/whisper/models:/models" ghcr.io/ggml-org/whisper.cpp:main whisper-server -m /models/ggml-small.bin -l zh --host 0.0.0.0 --port 8080 --convert

模型名可以换

如果你下载的是 ggml-base.bin，把 /models/ggml-small.bin 改成 /models/ggml-base.bin。文件夹里也必须真的有这个文件。

端口通常不用换

-p 8080:8080 和 --port 8080 要保持一致。只有 8080 被占用时才改端口，并同步修改插件里的本地引擎地址。

Docker 里要用 0.0.0.0

Mac Docker 命令里的 --host 0.0.0.0 建议保持原样，这样 Obsidian 才能从 Docker 外面连到本地引擎。

备用方案

不想用 Docker 时，可以源码编译。

这条路适合会一点命令行的 Mac 用户。如果你不熟悉终端，优先用上面的 Docker 方案。

xcode-select --install
brew install git cmake ffmpeg
mkdir -p ~/tools
cd ~/tools
git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
cmake -B build -DWHISPER_BUILD_SERVER=ON
cmake --build build --config Release -j

编译完成后，把 ggml-small.bin 放到 ~/tools/whisper.cpp/models/，然后在 ~/tools/whisper.cpp 里运行：

./build/bin/whisper-server -m ./models/ggml-small.bin -l zh --host 127.0.0.1 --port 8080 --convert

Plugin Flow

回到插件里测试和转写。

在 Multi Source Sync 里开启视频本地化，并重新同步包含视频的小红书笔记。只有已经保存到本地的视频才能转写。
进入插件设置页的视频转文字区域。
确认本地引擎地址是 http://127.0.0.1:8080/inference。如果你照着 Windows 或 Mac 命令启动，通常不用改这里。
点击测试本地引擎。测试通过后，再点击转写当前笔记视频或转写未处理视频。
插件会把结果写回原笔记的视频转文字章节；已有转写默认跳过。

Requirements

电脑配置和网络要求。

8GB 内存

可以先用 base 或 small 模型。长视频会慢，建议先转写短视频测试。

16GB 以上

更适合使用 small 或更大的模型，中文口播准确率会更稳。

网络只影响首次下载

转写过程不需要联网。首次下载 GitHub、Hugging Face 文件，或 Mac 第一次拉取 Docker 镜像时，如果网络不稳定，可以换网络后重试。

只支持桌面端

本地引擎需要电脑运行，Obsidian 手机端暂不支持执行视频转文字。

FAQ

常见问题。

这个功能会产生按次费用吗？

不会。本地引擎和模型本身免费。永久版解锁的是插件里的一键调用、批量处理和写回 Obsidian 笔记能力。

提示找不到本地视频怎么办？

通常是笔记里还是远程视频链接。请先在“同步内容”里开启“视频本地化”，重新同步对应视频，确认视频已经保存到本地媒体目录后，再回来转写。

测试本地引擎失败怎么办？

先确认终端窗口还开着，启动命令里有 --port 8080 和 --convert。Windows 再检查 whisper-server.exe、ffmpeg.exe、whisper.dll、ggml.dll 和 ggml-cpu-*.dll 是否在同一层；Mac Docker 再检查 Docker Desktop 是否还在运行。

命令提示找不到模型文件怎么办？

检查 D:\tools\whisper\models\ 里是否真的有 ggml-small.bin。如果你下载的是 ggml-base.bin，就把命令里的 ggml-small.bin 改成 ggml-base.bin。

命令执行后马上回到 PS 提示符怎么办？

这通常表示本地服务没有成功启动。先不要放在 Obsidian 知识库、中文路径或很深的目录里，按教程改用 D:\tools\whisper 这种简单路径；再检查 whisper-server.exe、ffmpeg.exe、解压包 Release 里的所有 .dll 文件、models\ggml-base.bin 是否都在对应位置。重新运行后，窗口应该停住而不是马上回到下一行 PS ...>。

Mac 用 brew install whisper-cpp 为什么不够？

插件需要连接一个正在运行的 whisper-server。当前 Homebrew 安装方式主要适合单独转写文件，不是本教程要启动的本地服务；所以 Mac 新手优先用 Docker，进阶用户再按源码编译方式打开 WHISPER_BUILD_SERVER=ON。

Docker 提示连不上或下载很慢怎么办？

先确认 Docker Desktop 已经打开，并且状态不是正在启动。第一次运行会下载 ghcr.io/ggml-org/whisper.cpp:main，国内网络可能较慢；可以换网络后重新复制同一条命令。

Mac 看到服务启动后，插件地址还是填哪个？

还是填默认地址 http://127.0.0.1:8080/inference。Docker 命令里的 --host 0.0.0.0 是给 Docker 内部使用的，不需要填进插件设置。

为什么下载链接打不开？

GitHub 和 Hugging Face 在国内网络下可能慢或不稳定。可以换网络，或尝试表格里的 SourceForge、HF Mirror 备用链接。