用 Electron 打造跨平台语音转文字桌面应用：从 Forge 脚手架、IPC 通信到 Whisper API 与 whisper.cpp 双模式识别与打包分发

用 Electron 打造跨平台语音转文字桌面应用从 Forge 脚手架、IPC 通信到 Whisper API 与 whisper.cpp 双模式识别与打包分发【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe本篇技术指南以仓库 docs/de-de/stage-3/cross-platform/electron-voice-to-text/index.md 的完整德语教程为主线结合 docs/zh-cn/stage-3/cross-platform/electron-voice-to-text/index.md 中文版工程实践系统讲解如何从零构建一款可安装到 Windows、macOS、Linux 的语音转文字Speech-to-Text桌面应用。读完本文你将掌握 Electron 的双进程架构与 IPC 通信、getUserMediaMediaRecorder录音链路、OpenAI Whisper API 云端识别与 whisper.cpp 本地离线识别两种模式的实现以及用 Electron Forge 完成跨平台打包分发和体积优化的完整方案。第 1 章什么是 Electron为什么要用桌面技术栈1.1 一句话理解 Electron你每天都在使用的VS Code、Slack、Discord 和 Notion有一个共同点它们都是基于Electron构建的桌面应用。Electron 是一个开源框架它允许你使用HTML CSS JavaScript与网页开发完全相同的技术栈来构建可以运行在Windows、macOS 和 Linux上的桌面应用。其原理非常简单把 Chromium 和 Node.js 打包在一起你的网页就变成了一款独立的桌面程序。一句话理解Electron 一个隐形的 Chrome 浏览器 Node.js 系统级能力。从仓库内中文版教程的工程视角看Electron 的价值在于如果一家公司已经拥有 Web 前端团队又希望把产品做成三大桌面系统都能安装的软件Electron 往往是最容易落地的方案——界面继续使用 HTML/CSS/JavaScriptElectron 再补上窗口、菜单、文件、托盘、通知和本地进程这些浏览器里没有的能力见 docs/zh-cn/stage-3/cross-platform/electron-voice-to-text/index.md。当然它并不是所有桌面软件的默认答案安装包通常不小需要携带 Chromium对内存、启动速度和安装体积极其敏感的小工具应比较 Tauri 或系统原生方案需要大量实时 3D、专业音视频处理或强依赖原生控件时也要先验证性能。1.2 Electron 核心架构两个进程与一座桥理解 Electron 的关键在于它由两种进程类型构成主进程Main Process应用的总经理每个应用只有一个主进程负责创建窗口、管理应用生命周期、访问文件系统等原生能力运行在 Node.js 环境中可以使用全部 Node.js 模块。渲染进程Renderer Process应用的门面本质上是一张 Chromium 网页负责 UI 渲染每个窗口对应一个渲染进程出于安全考虑渲染进程不能直接访问 Node.js API。预加载脚本Preload Script主进程与渲染进程之间的桥梁使用contextBridge将经过挑选的 API 安全地暴露给渲染进程。三者通过IPCInter-Process Communication进程间通信协作就像打电话渲染进程说我想开始录音主进程收到请求后调用系统麦克风。录音按钮在页面里保存临时文件和调用本地模型放在主进程里中间通过 Preload 传递有限的数据——这种边界设计是 Electron 应用安全性的基石。1.3 我们要构建什么语音转文字应用本文教程将构建一款语音转文字桌面应用功能清晰直接点击开始录音按钮应用开始监听麦克风说完后点击停止应用将音频发送给 AI 进行识别识别出的文本在 UI 中显示可一键复制。应用提供两种识别模式满足不同的使用场景对比维度云 API 模式本地模型模式代表方案OpenAI Whisper APIwhisper.cpp是否需要联网是否识别速度取决于网络取决于硬件Apple Silicon 上非常快中文识别质量优秀优秀large-v3 模型成本$0.006/分钟免费模型体积无需下载tiny 模型 75 MBlarge 模型 3 GB最适合场景快速上手、轻量使用注重隐私、离线使用、长期高频使用1.4 重要提醒Electron 中无法使用 Web Speech API如果你搜索过Electron 语音识别可能会看到推荐使用浏览器内置的Web Speech API。请注意这在 Electron 中不可用。Google 已停止对非 Chrome/Edge 浏览器壳的语音 API 支持。Electron 基于 Chromium但它本身不是 Chrome因此window.SpeechRecognition会直接失败。这就是为什么我们需要 OpenAI Whisper API 或 whisper.cpp 这类独立方案。1.5 教程路线图整个流程分为五步本文后续章节逐一展开创建 Electron 项目使用 Electron Forge 初始化项目并理解跨进程通信实现录音在渲染进程捕获麦克风输入并处理音频数据云端识别方案 A调用 OpenAI Whisper API 完成语音转文字本地识别方案 B使用 whisper.cpp 在无网络环境下完成识别打包分发将应用打包成可安装的桌面程序。第 2 章创建 Electron 项目2.1 环境准备开始前请确认满足以下条件一台电脑Windows 或 Mac推荐 Mac因为 Apple Silicon 上本地模型运行速度极快Node.js 环境18.0 或更高版本你的 AI 编程助手Cursor / Trae / Claude Code可选OpenAI API Key使用云模式时需要一个麦克风笔记本自带麦克风即可。2.2 用 AI 助手初始化项目打开你的 AI 编程助手输入以下 Prompt请帮我使用 Electron Forge 基于 Vite 模板创建一个新的 Electron 项目。 项目名称是 voice-to-text。 请执行npx create-electron-app voice-to-text --templatevite 创建完成后进入项目目录并安装依赖。Electron Forge 是 Electron 官方推荐的脚手架工具负责项目初始化、打包、分发等繁琐的配置工作。创建完成后项目结构大致如下voice-to-text/ ├── src/ │ ├── main.js # 主进程入口 │ ├── preload.js # 预加载脚本桥 │ ├── renderer.js # 渲染进程入口 │ └── index.html # 应用 HTML 页面 ├── forge.config.js # Electron Forge 配置 ├── vite.main.config.mjs # 主进程 Vite 配置 ├── vite.preload.config.mjs # 预加载脚本 Vite 配置 ├── vite.renderer.config.mjs # 渲染进程 Vite 配置 └── package.json2.3 启动与预览让 AI 助手启动开发服务器请帮我通过执行 npm start 启动 Electron 开发服务器几秒钟后会出现一个桌面窗口——这就是你的 Electron 应用。虽然目前只显示一个默认欢迎页但它已经是一个真正的桌面程序了。如果启动失败把报错完整贴给 AI 助手并让它只修复启动问题、不要增加业务功能。补充工程实践来自中文版教程依赖安装完成后运行项目看到 Electron 默认窗口且终端没有红色错误说明基础环境正常。如果界面太复杂可以要求 AI简化首页只保留录音、原始文字和结构化报告三个区域保持现有配色。2.4 理解 IPC进程间通信在实现语音功能之前必须先理解 Electron 最重要的概念IPC。由于渲染进程UI与主进程系统能力相互隔离它们必须通过 IPC打电话协作渲染进程UI 主进程系统 │ │ │── 我想开始录音 ──────────────→ │ │ │── 调用麦克风 │ │── 处理音频 │ ←──── 这是识别结果 ───────────│ │ │ │── 在 UI 中显示文本 │在代码层面这种通信通过preload.js桥接// preload.js - 将 API 安全地暴露给渲染进程 const { contextBridge, ipcRenderer } require(electron) contextBridge.exposeInMainWorld(electronAPI, { // 渲染进程 → 主进程 sendAudio: (audioData) ipcRenderer.invoke(transcribe-audio, audioData), // 主进程 → 渲染进程 onResult: (callback) ipcRenderer.on(transcription-result, callback) })// main.js - 主进程监听消息 const { ipcMain } require(electron) ipcMain.handle(transcribe-audio, async (event, audioData) { // 在这里调用 Whisper API 或 whisper.cpp const text await transcribe(audioData) return text })其中ipcRenderer.invoke/ipcMain.handle是请求-响应式 IPC 的推荐用法渲染进程发起调用并等待 Promise 结果主进程处理业务并返回值路径为 Renderer → Preload → Main。第 3 章实现录音功能3.1 在渲染进程捕获麦克风输入浏览器也就是 Electron 渲染进程通过navigator.mediaDevices.getUserMedia提供麦克风访问能力。把下面的需求交给 AI 助手请帮我按下述要求修改 src/index.html 和 src/renderer.js UI 1. 一个大圆形开始录音按钮点击后变成红色停止录音按钮 2. 录音期间显示简单的脉冲动画 3. 下方一个文本展示区用于显示识别结果 4. 底部两个按钮复制文本和清空 5. 右上角一个设置图标用于切换识别模式云/本地 录音逻辑在 renderer.js 中 1. 按钮点击时通过 navigator.mediaDevices.getUserMedia 请求麦克风 2. 使用 MediaRecorder 以 webm 格式录制音频 3. 停止后将音频 Blob 转换为 ArrayBuffer 4. 通过 window.electronAPI.sendAudio 发送给主进程 5. 等待主进程返回识别结果并展示核心录音代码// renderer.js let mediaRecorder null let audioChunks [] async function startRecording() { const stream await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, // 单声道 sampleRate: 16000, // 16kHz 采样率符合主流 ASR 输入要求 echoCancellation: true, // 回声消除 noiseSuppression: true // 噪声抑制 } }) mediaRecorder new MediaRecorder(stream, { mimeType: audio/webm;codecsopus }) audioChunks [] mediaRecorder.ondataavailable (e) audioChunks.push(e.data) mediaRecorder.onstop async () { const audioBlob new Blob(audioChunks, { type: audio/webm }) const arrayBuffer await audioBlob.arrayBuffer() // 发送给主进程进行转写 const result await window.electronAPI.sendAudio(arrayBuffer) document.getElementById(result).textContent result } mediaRecorder.start() }要点解析channelCount: 1与sampleRate: 16000是语音识别场景的通用配置16kHz 单声道是 Whisper 等模型的标准输入偏好echoCancellation与noiseSuppression能显著提升嘈杂环境下的识别准确率audio/webm;codecsopus是 Chromium 默认支持的录音容器格式无需额外编码器。3.2 处理麦克风权限Electron 默认会拦截权限请求必须在主进程中显式放行麦克风请帮我在 main.js 中添加麦克风权限处理 1. 使用 session.defaultSession.setPermissionRequestHandler 处理权限请求 2. 当请求类型为 media 时自动允许 3. 在 macOS 上确保在 package.json 或 entitlements 中声明麦克风使用描述// 添加到 main.js const { session } require(electron) session.defaultSession.setPermissionRequestHandler( (webContents, permission, callback) { if (permission media) { callback(true) } else { callback(false) } } )macOS 用户提示macOS 会弹出系统级的麦克风权限对话框这是正常现象点击允许即可。工程实践补充来自中文版教程第一次点击时系统会询问麦克风权限拒绝后应用应显示没有麦克风权限不能一直停在加载中。验证时应覆盖四种情况① 允许权限后可以开始和停止② 拒绝权限后能再次说明如何开启③ 连续点击不会同时创建两段录音④ 关闭窗口时释放麦克风。3.3 工程建议先跑通假识别再接入真模型真实模型会引入网络、格式和模型依赖。中文版教程给出的思路值得借鉴先让主进程收到音频后返回一段固定文本验证 IPC 链路、加载状态和结果页面成功后再替换为真实识别。停止录音后先显示处理中随后出现演示文字快速开始第二次录音时第一次的结果不能覆盖新任务。第 4 章方案 A——云端识别OpenAI Whisper API这是最简单的方式只需要一个 API Key 和几行代码。4.1 获取 OpenAI API Key访问 OpenAI Platform注册并登录进入 API Keys 页面点击Create new secret key复制生成的密钥以sk-开头并妥善保存。成本参考Whisper API 定价为$0.006/分钟即识别 1 小时音频仅需 $0.36非常便宜。4.2 在主进程中调用 Whisper API把需求交给 AI 助手请帮我在 main.js 中实现 OpenAI Whisper API 1. 安装 node-fetch如需要或使用 Node.js 内置的 fetch 2. 创建 transcribeWithWhisper 函数接收音频 ArrayBuffer 3. 将 ArrayBuffer 转换为 Blob/File 并构造 FormData 4. 调用 https://api.openai.com/v1/audio/transcriptions 5. 使用 whisper-1 模型language 设置为 zh中文 6. 返回识别出的文本 7. API Key 从环境变量或配置文件读取核心代码// main.js async function transcribeWithWhisper(audioBuffer, apiKey) { const blob new Blob([audioBuffer], { type: audio/webm }) const formData new FormData() formData.append(file, blob, audio.webm) formData.append(model, whisper-1) formData.append(language, zh) const response await fetch( https://api.openai.com/v1/audio/transcriptions, { method: POST, headers: { Authorization: Bearer ${apiKey} }, body: formData } ) const data await response.json() return data.text }4.3 添加设置 UI让 AI 助手在渲染进程添加一个简单的设置面板请帮我在 index.html 中添加设置面板 1. 右上角添加齿轮图标点击打开设置面板 2. 面板包含 - 识别模式切换云 API / 本地模型 - API Key 输入框仅云模式下可见 - 语言下拉框中文 / 英文 / 自动识别 3. 设置保存到 localStorage 4. 点击面板外部时关闭安全红线来自中文版教程不要把 API Key 放在 Renderer、localStorage、配置页或打包产物里。即使放在主进程桌面安装包仍然能被用户解包读取组织级共享密钥必须留在服务器端客户端只应持有短期登录凭证。第 5 章方案 B——本地识别whisper.cpp如果你不想依赖云端 API或者需要离线使用whisper.cpp 是最佳选择。它是 OpenAI Whisper 模型的 C 移植版完全在本地运行、无需联网。5.1 安装 whisper.cpp 的 Node.js 绑定请帮我在项目中安装 nodejs-whisper npm install nodejs-whisper 安装后请帮我下载 whisper tiny 模型体积小适合快速测试。 nodejs-whisper 会自动处理模型下载。模型选择指南tiny75 MB速度最快适合测试和轻量使用准确率中等base142 MB速度与准确率的平衡small466 MB中文识别质量明显提升large-v3-turbo1.5 GB推荐比 large 快 5–8 倍准确率仅低 1–2%large-v33 GB准确率最高但速度慢、对硬件要求更高。5.2 在主进程集成 whisper.cpp请帮我在 main.js 中添加 whisper.cpp 本地识别 1. 导入 nodejs-whisper 2. 创建 transcribeWithLocal 函数 3. 接收音频 ArrayBuffer先保存为临时 WAV 文件16kHz 单声道 4. 调用 nodejs-whisper 识别 5. 返回识别文本 6. 识别完成后删除临时文件核心代码// main.js const { nodewhisper } require(nodejs-whisper) const path require(path) const fs require(fs) const os require(os) async function transcribeWithLocal(audioBuffer) { // 保存为临时文件 const tempPath path.join(os.tmpdir(), recording-${Date.now()}.wav) fs.writeFileSync(tempPath, Buffer.from(audioBuffer)) try { const result await nodewhisper(tempPath, { modelName: base, autoDownloadModelName: base, whisperOptions: { language: zh, word_timestamps: true } }) return result.map(r r.speech).join() } finally { // 清理临时文件 fs.unlinkSync(tempPath) } }代码中try...finally保证了无论识别成功还是抛错临时 WAV 文件都会被删除避免在系统临时目录留下敏感音频残留。中文版教程的验收标准也印证了这一点验证时关闭网络录一段十秒中文应能生成文字、临时目录会清理、应用重启后没有残留录音。模型大小、速度与硬件加速会随绑定库版本变化不要把某个速度值写成固定承诺——先用小模型验证流程再根据电脑性能选择更大的模型。5.3 Apple Silicon 用户的利好消息如果你使用 M1/M2/M3/M4 芯片的 Macwhisper.cpp 可以自动利用Metal GPU 加速和Apple Neural Engine识别速度可以快于实时——即 1 分钟音频可能只需几秒处理。NVIDIA GPU 用户则可以享受CUDA 加速同样有出色表现。第 6 章打包与分发开发完成后需要把应用打包成可分发的安装程序。6.1 使用 Electron Forge 打包Electron Forge 已经包含在项目中打包非常简单请帮我执行 Electron Forge 打包命令 npx electron-forge make该命令会自动为当前操作系统生成安装程序macOS.dmg安装镜像和.zip归档Windows.exe安装程序Squirrel 格式Linux.debDebian/Ubuntu和.rpmFedora包。构建产物位于out/make/目录。重要工程认知来自中文版教程Forge 只会生成已配置且当前操作系统支持的格式一次命令不会自动在任意电脑上同时生成所有平台安装包。生成安装文件不等于可以公开发布——把产物拿到一台没有 Node.js、没有项目源码的干净电脑上测试能否安装启动、麦克风权限是否正常、模型或后端不可用时是否有提示、卸载后是否残留敏感临时文件。6.2 应用体积优化Electron 应用的痛点之一是包体积偏大因为内置了 Chromium。优化建议确保只有dependencies中的包被捆绑开发依赖留在devDependencies利用 Vite Tree-Shaking 减小 JavaScript 体积使用本地模型时考虑首次启动再下载模型而不是打进安装包。配置预估体积纯 Electron 应用不含模型~150–200 MB whisper tiny 模型~250 MB whisper large-v3-turbo 模型~1.7 GB6.3 跨平台注意要点macOS上架 App Store 或分发给他人需要代码签名Apple Developer ID$99/年还需要 Apple 的公证Notarization流程麦克风权限必须在Info.plist中声明NSMicrophoneUsageDescription建议构建 Universal Binary 以同时支持 Intel 与 Apple Silicon。Windows建议代码签名否则 Windows SmartScreen 会弹出安全警告未签名应用用户仍可选择仍然运行。Linux无需代码签名建议同时提供.deb和.AppImage两种格式。提示个人项目或小范围分发可以暂时跳过代码签名直接分享打包好的文件。第 7 章总结与进阶方向恭喜你已经从零构建了一款跨平台语音转文字桌面应用。回顾整个流程使用 Electron Forge 搭建了跨平台桌面应用脚手架理解了主进程、渲染进程与 IPC 通信实现了麦克风录音与音频采集集成了两种识别方案云端 Whisper API 与本地 whisper.cpp学会了如何打包和分发 Electron 应用。Electron 的强大之处在于你可以用 Web 技术栈构建 VS Code 或 Slack 级别的桌面应用。配合成熟的 AI 语音识别语音转文字这类过去需要一个专业团队的功能如今一个人就能完成。调试技巧来自中文版教程排查问题时关注三个位置——渲染进程错误打开窗口开发者工具主进程错误看启动 Electron 的终端IPC 问题给每次录音生成请求编号两边日志都记录编号。日志可以记录状态、耗时和错误码但不能记录完整音频、报告正文、Token 和联系方式。进阶方向实时字幕使用 AudioWorklet 做流式音频配合流式识别 API 实现实时转写会议助手录制完整会议自动生成带时间戳的转录稿并用 AI 总结要点多语言翻译转写语音后调用翻译 API实现实时语言转换语音笔记结合本地数据库如 SQLite构建可检索的语音笔记库。参考资料与仓库延伸阅读本文主文档docs/de-de/stage-3/cross-platform/electron-voice-to-text/index.md德语版完整教程中文版工程实践docs/zh-cn/stage-3/cross-platform/electron-voice-to-text/index.md含 Field Voice Log 案例、安全边界、完整验收清单英文版对应教程docs/en/stage-3/cross-platform/electron-voice-to-text/index.md仓库内的 Electron 示例项目examples/trae-3d-block-game/electron/main.js可对照阅读 Electron 主进程入口写法跨平台系列其他教程目录docs/zh-cn/stage-3/cross-platformPWA、Tauri 生态的 Flutter/React Native 等对照方案官方文档类主题可参考仓库中相关章节docs/zh-cn/stage-2/frontend 与 docs/zh-cn/appendix/7-infrastructure-and-operations【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考