企业官网建设流程全解析

OpenScreen 离线字幕怎么打包？Whisper 模型预置全流程

【免费下载链接】openscreenCreate stunning demos for free. Open-source, no subscriptions, no watermarks, and free for commercial use. An alternative to Screen Studio.项目地址: https://gitcode.com/GitHub_Trending/open/openscreen

要交付一个自动字幕断网也能用的 OpenScreen 安装包，前提是先把 Whisper 模型与 onnxruntime wasm 铺进resources/caption-assets/——打包后应用从file://协议加载页面，运行时既连不到 HuggingFace，也拉不到 CDN 上的 wasm。本文按"预置 → 校验 → 出包"三步把这条链路讲清。

原理链路：从协议判断到资源落位的一条单向流

离线转写读取的资产不是散落的，运行时按一条固定链路流动，每一步都可查证：

1. 渲染进程判断协议：src/lib/captioning/transcribe.ts 检测到window.location.protocol === "file:"（即打包后的状态）时置useLocalModels = true，并把window.electronAPI.assetBaseUrl一并传给 worker；dev 的 http 环境不走本地资产。
2. worker 配置环境变量：src/lib/captioning/transcribe.worker.ts 在useLocalModels时把env.localModelPath指到caption-assets/models/、env.backends.onnx.wasm.wasmPaths指到caption-assets/ort/，置env.allowRemoteModels = false，并固定numThreads = 1——file://下拿不到 SharedArrayBuffer，线程版 wasm 永远不会加载。
3. 主进程给出资源根：electron/windows.ts 在打包后取process.resourcesPath，以--asset-base-url=<file:// URL>传给 preload；electron/preload.ts 解析出assetBaseUrl暴露给渲染进程。
4. 打包资源落位：electron-builder.json5 的extraResources把caption-assets/整个拷入打包后的 resources，与运行时读取路径对齐。

也就是说，运行时只认resources/caption-assets/下的models/与ort/两个子目录，缺任何一个里的文件，离线转写都跑不起来。

🔧 动手前：环境与依赖核对表

脚本的失败来源只有两类：依赖缺失、网络不可达。先核对三项，再执行任何命令：

依赖未装好时先补齐：

npm ci

主线三步：预置、校验、出包

第一步·预置：跑 fetch-caption-model 写入资产

脚本幂等，手动先跑一遍能把网络错误暴露在打包之前，而不是卡进打包流程：

node scripts/fetch-caption-model.mjs

副作用边界：

• 写入全部落在仓库根的caption-assets/，该目录已被.gitignore忽略，不进 git。
• 从node_modules/@xenova/transformers/dist只拷两个非线程版 wasm（ort-wasm.wasm、ort-wasm-simd.wasm）到caption-assets/ort/；线程版不加载，省约 20MB。
• 从Xenova/whisper-tiny下载 13 个文件到caption-assets/models/Xenova/whisper-tiny/：11 个配置/分词元数据加 2 个量化 ONNX 权重。
• 已存在的非空文件直接跳过，重跑只补缺失部分。

关键输出（中间下载行截断）：

Fetching caption assets → caption-assets/ ONNX Runtime wasm: + copied ort/ort-wasm.wasm + copied ort/ort-wasm-simd.wasm Whisper model (Xenova/whisper-tiny): ↓ models/Xenova/whisper-tiny/onnx/encoder_model_quantized.onnx (7.4 MB) ... Caption assets ready.

可观察信号：日志以Caption assets ready.收尾即视为预置完成。

第二步·校验：重跑即校验

不需要单独的校验命令。再执行一次node scripts/fetch-caption-model.mjs：每个已就位且非空的文件打印✓ cached <相对路径>而不触发下载，结尾仍是Caption assets ready.，即代表ort/与models/Xenova/whisper-tiny/结构完整。若某行出现↓（新下载），说明该文件此前不完整，重跑直到全部变成cached即可。

第三步·出包：beforePack 钩子与 extraResources 映射

决定资产能否进安装包的是 electron-builder.json5 里两处配置：

• "beforePack": "scripts/before-pack.cjs"：scripts/before-pack.cjs 在每次打包（本地npm run build:*或 CI 的裸electron-builder）前同步执行预置脚本；资产已就位时这一步是 no-op。
• extraResources中{ "from": "caption-assets", "to": "caption-assets" }一条，负责把目录整体拷入 resources。

按平台选打包命令，输出统一落在release/${version}：

npm run build:mac # 先构建 ScreencaptureKit 录制助手，再 electron-builder --mac npm run build:win # 先构建 Windows WGC 原生助手，再 electron-builder --win npm run build:linux # tsc && vite build && electron-builder --linux AppImage deb pacman

build:mac与build:win把对应平台的原生录制助手构建编进了流程，出包时不要单独拆掉这几步。

报错速查：依赖缺失、限流与重试

边界：什么不生效、什么不能改

• 本地资产只在file://（打包后）环境生效；npm run dev的 http 环境走远程 CDN，caption-assets/不会被读取。
• 模型固定为Xenova/whisper-tiny，worker 中 pipeline 与模型 ID 写死为automatic-speech-recognition+Xenova/whisper-tiny；换模型需同步改脚本的MODEL_FILES与 worker 代码，不在本脚本参数范围内。
• 打包资产不含output_attentions修订版权重——该变体在某些环境会导致推理回退（空 chunk、抛错），worker 只使用默认 tiny 权重。
• caption-assets/不入 git，每台构建机（含 CI）首次构建都需要外网访问 HuggingFace，之后依赖幂等缓存。

验收清单：打包后逐条核对

1. 重跑node scripts/fetch-caption-model.mjs，所有文件显示✓ cached，以Caption assets ready.收尾。
2. release/${version}/下生成对应平台安装包（mac 为 dmg、win 为 nsis、linux 为 AppImage/deb/pacman）。
3. 安装包内resources/caption-assets/下同时存在非空的models/与ort/两个子目录。
4. 断网启动安装包，自动字幕仍能从本地加载模型与 wasm，产出带时间戳的字幕片段。

【免费下载链接】openscreenCreate stunning demos for free. Open-source, no subscriptions, no watermarks, and free for commercial use. An alternative to Screen Studio.项目地址: https://gitcode.com/GitHub_Trending/open/openscreen