OpenScreen 本地 Whisper 语音模型接入与 AI 大模型配置指南

一篇写给"网络环境不太理想"的人的实操记录：三个安装包到底差在哪、本地 Whisper 模型该放哪个目录、想换更大的模型行不行、以及 1.12.2 新加的 AI 大模型接入怎么用。

一、先说结论

如果你只想看答案：

我的实测环境（下文所有数据都出自这台机器）：

二、三个安装包到底有什么区别

2.1 先理清血统：这是一个项目的两个阶段

很多人（包括我）最初会以为这是同一个软件的不同版本号，其实不是：

• siddharthvaddem/openscreen —— 原始项目，作者 Sid。2026 年 6 月发布 v1.5.0 "Final Release"，作者在 release notes 里明确写了 "this project will be archived soon"（即将归档），并推荐大家去看后续分支。1.5.0 就是这个项目的终点。
• getopenscreen/openscreen —— 续作，作者 Etienne Lescot。版本号一路走到 1.12.x，目前仍在活跃开发（已有 1.13.0-rc）。本地 Whisper 转录、AI 代理这些新功能都是续作加的。

所以"1.5.0 没有 Whisper、1.12.2 有"这件事，本质是两个项目的功能代差，不是同一个软件的高低版本。

2.2 三个文件的真实元数据

我直接读了三个安装包的 PE 版本信息（顺带算了 SHA-256）：

第一个文件（815 KB 那个）不是 OpenScreen 本体，而是微软商店的安装引导器（StoreInstaller.exe），它会去商店拉取 MSIX 包安装。它的 CompanyName 是 Microsoft，OriginalFilename 是 StoreInstaller.exe —— 从这里就能一眼看出来。

注意一个反直觉的点：1.5.0 的安装包反而比 1.12.2 大 50 MB（270.8 MB vs 220.6 MB）。体积大 ≠ 功能多，原因见下一节。

2.3 拆包对比：差异到底在哪

我把两个安装包都拆开，对比了 resources/electron/native/bin/win32-x64/（原生可执行文件目录）：

1.5.0 的原生目录里只有两个 exe，没有任何语音推理运行时。

再把两个 app.asar 里的关键字拉出来数：

结论非常清楚：

• 1.5.0 的语音字幕走的是 transformers.js（@xenova/transformers）+ ONNX Whisper-tiny + ONNX Runtime WASM，模型和运行时全部打包在内（这就是它体积更大、asar 有 403 MB 的原因）。开箱即用、不需要下载任何东西 —— 代价是 tiny 模型精度一般。
• 1.12.2 把这条链路换掉了，改用 whisper.cpp 原生服务（whisper-stt-server.exe + ggml* 运行时），精度从 tiny 提到 small-q8_0，但模型不再随包分发，改成首次使用时下载。

附带发现：1.12.2 的 resources/caption-assets/ 目录下仍然躺着那套 39 MB 的 ONNX 模型和 19 MB 的 WASM 文件，但代码里已经没有任何地方引用 caption-assets 这个字符串了（1.5.0 里引用了一次）。也就是说这是打包时遗留的"僵尸资产"，约 58 MB 空间是白占的。这也从侧面印证了技术栈确实被替换掉了。

2.4 那我该用哪个？

• 要用本地 Whisper 转录 / AI 代理 → 只能选 1.12.2（或更新的续作版本），并按下文第四节补上模型。
• 要"装上就能用"、不在乎字幕精度 → 1.5.0 反而更省事，它什么模型都不用下载。
• 商店版 vs 安装包版 → 功能一致（都是 1.12.2），但用户数据目录是两套、互相隔离的（见第七节避坑第 4 条）。

三、安装

安装本身没什么可说的，双击即可。默认装到：

C:\Users\<用户名>\AppData\Local\Programs\Openscreen\

如果你走微软商店，包名是 EtienneLescot.OpenScreen_1.12.2.0_x64__hedpjctvqwhq0，装在 C:\Program Files\WindowsApps\ 下。

装完先别急着用语音功能 —— 先做下面这步。

四、接入本地 Whisper 语音模型（核心）

4.1 故障现象

点开编辑器右侧的「转录」面板，会一直卡在这里，转圈转到天荒地老：

转录使用本地 Whisper —— 在您的电脑上运行，数据不会离开本设备。

"本地运行""数据不外传"说得都对，但它没说还需要先下载一个 264 MB 的模型。

4.2 根因

查一下模型的缓存目录：

dir "$env:APPDATA\openscreen\stt-models\whisper-ggml\"

结果是目录存在，但是空的。模型从来没下载成功过。

我在 app.asar 的主进程代码里找到了这段下载配置：

// 摘自 dist-electron/main-*.js
const HF = "https://huggingface.co";
const REPO = "ggerganov/whisper.cpp";
const FILE = "ggml-small-q8_0.bin";
// ...url: `${HF}/${REPO}/resolve/<revision>/${FILE}`
//    expectedSha256: "49C8FB02B65E6049D5FA6C04F81F53B867B5EC9540406812C643F177317F779F"

再实测一下网络：

curl -o /dev/null -w "%{http_code}\n" --max-time 12 \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-small-q8_0.bin"
# 输出：000（超时，10 秒无响应）

000 就是连接根本建立不起来。根因确认：应用写死了从 huggingface.co 下载模型，而这个域名在当前网络下不可达，于是永远停在"正在启动语音模型"。

4.3 模型应该放在哪个目录（重点）

这是本文最需要记住的一条。1.12.2 期望的路径是：

%APPDATA%\openscreen\stt-models\whisper-ggml\ggml-small-q8_0.bin

展开成绝对路径就是：

C:\Users\<你的用户名>\AppData\Roaming\openscreen\stt-models\whisper-ggml\ggml-small-q8_0.bin

这个路径由代码里 path.join(app.getPath("userData"), "stt-models") 拼接而成，userData 就是 %APPDATA%\openscreen。

三个必须同时满足的条件：

1. 目录必须是 stt-models\whisper-ggml\
2. 文件名必须是 ggml-small-q8_0.bin（一个字符都不能改）
3. SHA-256 必须是 49C8FB02B65E6049D5FA6C04F81F53B867B5EC9540406812C643F177317F779F

为什么第 3 条也这么死？因为代码里有一段"缓存命中"短路逻辑：

if (fs.existsSync(modelPath)) {
  const st = await fs.stat(modelPath);
  if (st.isFile() && st.size > 0 && (!expected || sha256(modelPath) === expected))
    return;              // ← 文件存在 + 大小正常 + 哈希匹配 → 直接跳过下载
}
// 否则进入下载流程...

反过来说：只要我们手动把哈希正确的文件放到这个位置，应用就会直接跳过下载。这就是绕过被墙下载源的原理。

4.4 怎么拿到模型

既然官方源连不上，换国内镜像。hf-mirror.com 是 HuggingFace 的完整镜像，把域名换掉即可：

DEST="$APPDATA/openscreen/stt-models/whisper-ggml"

curl -L --retry 5 -C - \
  -H "user-agent: openscreen-stt" \
  -o "$DEST/ggml-small-q8_0.bin.partial" \
  "https://hf-mirror.com/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-small-q8_0.bin"

我这边实测 7.3 MB/s，36 秒下载完，共 264,464,607 字节。

下完必须校验哈希（这一步不能省，哈希不对等于白放）：

sha256sum "$DEST/ggml-small-q8_0.bin.partial"
# 49c8fb02b65e6049d5fa6c04f81f53b867b5ec9540406812c643f177317f779f ✅

校验通过再改名（先下 .partial 再改名，避免半截文件被误判为"已就绪"）：

mv "$DEST/ggml-small-q8_0.bin.partial" "$DEST/ggml-small-q8_0.bin"

最终目录长这样：

C:\Users\hek\AppData\Roaming\openscreen\stt-models\whisper-ggml\
└── ggml-small-q8_0.bin        264,464,607 字节

放好之后重开 OpenScreen，转录功能就直接可用了。

4.5 怎么确认真的生效了

不想只靠"界面上不转圈了"来判断的话，可以直接手动拉起应用自带的 whisper 服务来验证：

cd "C:\Users\<用户名>\AppData\Local\Programs\Openscreen\resources\electron\native\bin\win32-x64"

.\whisper-stt-server.exe ^
  --model "C:\Users\<用户名>\AppData\Roaming\openscreen\stt-models\whisper-ggml\ggml-small-q8_0.bin" ^
  --port 18777 --host 127.0.0.1 --threads 4

模型加载正常的话会打出：

whisper_model_load: type          = 3 (small)
whisper_model_load: ftype         = 7
whisper_model_load:      Vulkan0 total size =   263.87 MB
whisper_init_state: compute buffer (encode) =  132.63 MB
[whisper-stt] model loaded; backend=whispercpp-vulkan
[whisper-stt] listening on 127.0.0.1:18777

看到 backend=whispercpp-vulkan 说明走的是 GPU 而不是 CPU 兜底。然后另开一个终端丢个测试音频进去：

curl -s -X POST http://127.0.0.1:18777/inference \
  -F "file=@jfk.wav;type=audio/wav" \
  -F "response_format=verbose_json" \
  -F "language=auto"

我用的是 whisper.cpp 官方仓库里的经典测试音频 samples/jfk.wav，返回结果：

{
  "backend": "whispercpp-vulkan",
  "detected_language": "en",
  "segments": [{
    "start": 0.0, "end": 11.0,
    "text": " And so my fellow Americans, ask not what your country can do for you, ask what you can do for your country."
  }],
  "timing": { "audio_s": 11.0, "elapsed_s": 23.64, "rtf": 2.149 }
}

一字不差，而且带词级时间戳（DTW）。验证通过。

4.6 性能参考

同样是那 11 秒音频，在这台 i5-10500 + UHD 630 上：

RTF 2.15 意味着处理时间是音频时长的 2.15 倍。录 1 小时的素材，转录大概要跑 2 小时。日常录屏演示（几分钟）完全没问题，长视频要有心理准备。

五、想换成更大的模型行不行？

这是我在折腾过程中最关心的问题，答案有点遗憾：直接换文件不行。

5.1 为什么不行

我把 1.12.2 里所有能配置的入口都翻了一遍，模型这一块是完全硬编码的：

应用支持的全部环境变量里，只有 OPENSCREEN_WHISPER_SERVER_EXE 跟语音有关，没有任何环境变量能覆盖模型路径或文件名。

所以如果你把 ggml-large-v3-turbo-q8_0.bin 改名成 ggml-small-q8_0.bin 丢进去会发生什么？哈希校验失败 → 应用认为文件无效 → 发起下载 → 连不上 huggingface → 报错。界面依然用不了（你原来的文件还在，只是不被认可）。

5.2 那真要换怎么办

只能改代码。思路是：解包 app.asar → 替换掉文件名常量和 SHA-256 常量 → 重新打包。

# 1. 备份
cp "$LOCALAPPDATA/Programs/Openscreen/resources/app.asar" app.asar.bak

# 2. 解包
npx @electron/asar extract app.asar app_unpacked

# 3. 在 dist-electron/main-*.js 里改两处：
#    - "ggml-small-q8_0.bin"  → 你要的模型文件名
#    - "49C8FB02...317F779F"  → 新模型的 SHA-256（大写）

# 4. 重新打包
npx @electron/asar pack app_unpacked app.asar

# 5. 把新模型按新文件名放进 stt-models/whisper-ggml/

几点提醒：

• main-*.js 的文件名带哈希（我这里是 main-J1i5HN9P.js），每次升级都会变，得重新找。
• 改完 app.asar 就失去了自动更新能力，且 electron-updater 下次更新会直接覆盖你的修改。升级后要重做一遍。
• 首次解包会发现 app.asar 有 253 MB，其中绝大多数是依赖，真正要改的只有那一个 JS 文件。

说实话，除非你确实要用 large 级模型跑长语音，否则性价比不高。small-q8_0 在中文/英文口播场景下的准确率已经相当好（上面的 jfk 测试是逐字正确）。

5.3 各档模型体积参考（实测 Content-Length）

如果你决定动手，这里是 whisper.cpp 官方仓库各档 ggml 模型的真实体积：

按本机 RTF 2.15 外推，换 medium 后大致会到 RTF 6～7（1 小时音频跑 6 小时以上）。建议想省时间的话反向往小换（tiny/base），如果想更准再考虑 turbo。

六、1.12.2 的另一个新功能：接入其他 AI 大模型

这是续作相对 1.5.0 的另一块大改动 —— 内置了一个 AI 代理（Agent），可以直接用自然语言让它改视频，支持接入 8 家 LLM 提供商。

6.1 设置入口

打开「AI 设置」，能看到 8 个卡片：

我把代码里的厂家配置全部挖出来了，实际定义是这样的：

几个从源码里看出来的细节：

• Gemini 走的是 OpenAI 兼容层（/v1beta/openai），不是 Google 原生协议 —— 代码注释里专门解释了为什么（为了和 OpenAI/OpenRouter 复用同一条代码路径）。
• MiniMax 走 Anthropic 协议，baseUrl 是 https://api.minimax.io/anthropic，注意不能带 /v1（SDK 自己会拼 /v1/messages）。
• 代码里还留了一段注释，说明 1.8.0 移除了两个提供商：ChatGPT 的 openai-oauth 和 GitHub Copilot 的 copilot-proxy。理由是它们"借用了 GitHub 和 OpenAI 自家的客户端 ID 与编辑器 UA 去访问仅限第一方客户端的接口"，作者认为不合规，已经拿掉了。这点挺值得称赞的。
• 除了填 API Key，每个提供商还支持读环境变量（比如 ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、MISTRAL_API_KEY、MINIMAX_API_KEY、OPENAI_COMPATIBLE_API_KEY），适合喜欢用环境变量管理密钥的人。

6.2 密钥存在哪

界面上写的是"凭据存储在系统钥匙串（safeStorage）中"，代码也确实如此：

%APPDATA%\openscreen\llm-config.json      ← 明文：提供商 id、模型名、baseUrl
%APPDATA%\openscreen\llm-credentials.enc  ← 加密：API Key

llm-credentials.enc 通过 Electron 的 safeStorage 加密（Windows 上底层是 DPAPI，绑定当前用户账户）。也就是说 API Key 不是明文落盘的，换台机器或者换个用户账户就解不开。这一点做得比不少同类工具规范。

6.3 实战：用 OpenAI Compatible 接国内的 Qwen

因为它支持任意 OpenAI 兼容端点，国内用户最实用的选择是走国内的 MaaS 平台。我在「OpenAI Compatible」里填的是阿里云百炼的兼容模式：

保存后卡片会变成绿色的「✓ 已连接」，编辑器右下角也会显示当前模型：

这样配置的好处是：推理走国内节点，不需要科学上网，也不需要外币信用卡，而且 OpenAI Compatible 这一档是万能的 —— 任何提供 /v1/chat/completions 的服务（DeepSeek、智谱、月之暗面、硅基流动、Ollama 本地部署……）都能塞进去。

代码里对 openai-compatible 还做了动态模型列表支持：填好 Base URL 和 Key 之后，它会去请求 GET /v1/models 自动把可用模型拉成下拉列表，不用手敲模型名。

6.4 这个 AI 代理能做什么

它不是普通的聊天框，而是一个能直接操作时间线的 Agent。系统提示词里写得很直白：

You are an AI video editor working inside OpenScreen. Help them cut silences, tighten pacing, add captions, and rewrite titles.

它挂载的工具（我从不打包后的代码里扒出来的）：

设计上有个细节挺讲究：删除静音只允许用 addTrim，而不是 setClipRange 或重建时间线。注释里解释得很清楚 —— 重建时间线会把你手动排好的片段全丢掉，而 addTrim 只是在片段内部加剪切，用户已有的编辑全部保留。这种"宁可多绕一步也不破坏用户数据"的设计思路，在 AI 编辑器里其实是很难得的。

同样地，moveClip 的注释也特意强调"重新排序不会破坏任何东西"，因为"模型以前会去用那个会摧毁一切的替代工具"。看得出是踩过坑之后改的。

七、避坑清单

1. 哈希不校验就别改文件名。 先 .partial 下载 → 校验 SHA-256 → 再改名，顺序反了容易留下半截文件，反而让应用以为"文件已存在"。
2. 别指望应用自己重试成功。 它的重试逻辑只针对 408/425/429/5xx 这类 HTTP 状态码，域名根本连不上（curl 返回 000）走的是网络异常分支，重试几轮后照样失败。
3. OPENSCREEN_WHISPER_SERVER_EXE 是唯一能覆盖的路径。 它只换助手程序，不换模型。别指望用它指向自定义模型。
4. 商店版和安装包版的数据目录是分开的。 本地版用 %APPDATA%\openscreen\，商店版走 MSIX 沙箱 %LOCALAPPDATA%\Packages\EtienneLescot.OpenScreen_hedpjctvqwhq0\LocalCache\Roaming\openscreen\。给一份装了模型，另一份不会生效。两份都想用的话，可以给第二份建个硬链接（同盘、不额外占空间）： powershell New-Item -ItemType HardLink ` -Path "$env:LOCALAPPDATA\Packages\EtienneLescot.OpenScreen_hedpjctvqwhq0\LocalCache\Roaming\openscreen\stt-models\whisper-ggml\ggml-small-q8_0.bin" ` -Target "$env:APPDATA\openscreen\stt-models\whisper-ggml\ggml-small-q8_0.bin"
5. 重装 / 卸载会连模型一起清掉。 建议把 ggml-small-q8_0.bin 单独备份一份，重装后拷回去即可，不用再下一次。
6. 转录很吃时间。 本机 RTF 2.15，请对长视频有合理预期；同时它会常驻约 795 MB 内存。
7. 删静音请让 AI 用 addTrim。 如果你自己写提示词调用工具，别让它用 replaceTimeline，那条路会丢掉你手动排的片段。

八、附：本文实测环境

写在最后：OpenScreen 本身是个相当好用的开源录屏演示工具，本地 Whisper 的设计（数据不出设备）也很符合隐私预期。唯一的坑就是"默认下载源在国内不可达"，而它把这个失败处理得比较安静 —— 界面上只显示"正在启动语音模型"，不报错、不给原因，很容易让人以为是软件坏了。希望这篇记录能帮到后面遇到同样问题的人。