教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载本指南基于 easy-vibe 仓库中docs/ar-sa/stage-3/cross-platform/electron-voice-to-text/index.md的完整教程脉络系统讲解如何从零构建一款支持「云端 API」与「本地模型」两种识别方式的跨平台语音转文字桌面应用。你将掌握 Electron 的主进程/渲染进程/Preload 三进程模型与 IPC 通信、基于getUserMediaMediaRecorder的录音实现、OpenAI Whisper API 与 whisper.cpp 两种转写方案的接入以及使用 Electron Forge 打包出 Windows/macOS/Linux 三平台安装包的全流程。文中同时结合仓库内 Electron 示例代码 与同主题中文教程 Field Voice Log 作为佐证让每一步都有可验证的落地依据。1. 认识 Electron 与桌面应用开发1.1 Electron 是什么日常使用的VS Code、Slack、Discord、Notion有一个共同点它们都是基于Electron构建的桌面应用。Electron 是一个开源框架允许你用 Web 开发中已经熟悉的HTML CSS JavaScript编写桌面软件并原生运行在Windows、macOS 和 Linux上。它的原理非常朴素把 Chromium 与 Node.js 打包在一起让网页应用变成一个独立的桌面程序。用一句话概括Electron 一个看不见的 Chrome 浏览器 Node.js 的系统能力。需要强调的是Electron 不是把网页随便套进一个窗口。一个能长期使用的 Electron 产品还要处理自动更新、离线状态、安装包、系统权限、进程隔离和本地数据安全。做好以后用户看到的就是普通桌面软件不需要先打开浏览器。1.2 三大组成部分主进程、渲染进程与 Preload一个 Electron 应用由两种类型的进程组成理解它们的边界是开发的关键主进程Main Process应用的总管家负责创建窗口、管理应用生命周期、访问文件系统等原生能力运行在 Node.js 环境中可以使用所有 Node.js 模块每个应用只有一个主进程。渲染进程Renderer Process应用的门面本质是一个 Chromium 网页负责渲染用户界面每个窗口对应一个渲染进程出于安全考虑渲染进程不能直接访问 Node.js API。预加载脚本Preload Script主进程与渲染进程之间的桥梁通过contextBridge把有限的、经过挑选的 API 安全地暴露给渲染进程。三者通过IPC进程间通信协作就像打电话渲染进程说我想开始录音主进程收到请求后去调用系统麦克风。关于安全边界仓库内的真实示例给出了标准做法。在 examples/trae-3d-block-game/electron/main.js 中BrowserWindow的webPreferences明确设置了webPreferences: { nodeIntegration: false, // 渲染进程不开放 Node.js contextIsolation: true, // 开启上下文隔离 sandbox: true // 启用沙箱 }这正是教程反复强调的原则不要让页面直接拿到 Node.jsPreload 只暴露必要的能力。1.3 我们要构建什么语音转文字应用本教程要构建一个语音转文字桌面应用功能非常直接点击 Start Recording 按钮应用开始监听麦克风说完后点击 Stop应用把音频交给 AI 识别识别出的文本显示在界面上可一键复制。应用提供两种识别模式对比如下对比维度云端 API 模式本地模型模式代表方案OpenAI Whisper APIwhisper.cpp是否需要联网是否识别速度取决于网络取决于硬件Apple Silicon 上非常快中文识别质量优秀优秀large-v3 模型成本约 $0.006/分钟以官方最新价格为准免费模型体积无需下载tiny 75 MBlarge 3 GB适合场景快速上手、轻量使用注重隐私、离线使用、高频长期使用1.4 重要提醒Web Speech API 在 Electron 中不可用如果你搜索过 Electron speech recognition可能会看到推荐使用浏览器内置的Web Speech API。请注意这在 Electron 中无法工作。Google 已经停止对非 Chrome/Edge 内核浏览器封装提供语音 API 支持。Electron 基于 Chromium但它不是 Chrome 本身因此window.SpeechRecognition会直接失败。这正是我们需要 Whisper API 或 whisper.cpp 这类独立方案的原因。1.5 教程路线图完整流程分为五步创建 Electron 项目使用 Electron Forge 搭建工程理解进程间通信实现录音在渲染进程采集麦克风输入、处理音频数据云端识别方案 A接入 OpenAI Whisper API本地识别方案 B使用 whisper.cpp 实现完全离线识别打包与分发把应用打成可安装的桌面安装包。2. 创建 Electron 项目2.1 用 AI 助手初始化项目打开你的 AI 编程助手Cursor / Trae / Claude Code 等输入以下 promptPlease help me create a new Electron project with Electron Forge using the Vite template. The project name is voice-to-text. Please run: npx create-electron-app voice-to-text --templatevite After creation, enter the project directory and install dependencies.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.json启动前请确认电脑已安装Node.js 18.0 或更高版本建议使用当前 LTS 版本。2.2 启动与预览让 AI 助手启动开发服务器Please help me start the Electron development server by running npm start几秒钟后桌面窗口出现这就是你的 Electron 应用。即使现在只显示默认欢迎页它已经是真正意义上的桌面软件了。如果启动失败可以把报错信息交给 AI 助手让它只修复启动问题不增加业务功能。2.3 理解 IPC进程间通信在实现语音功能之前必须先理解 Electron 最重要的概念IPC进程间通信。由于渲染进程UI与主进程系统能力相互隔离它们必须通过 IPC 这座电话线协作渲染进程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 })仓库中同主题的中文教程 docs/zh-cn/stage-3/cross-platform/electron-voice-to-text/index.md 给出了一个务实的开发建议先用固定文本模拟识别结果让主进程收到音频后返回一段固定文字先把 IPC、加载状态和结果展示链路跑通再接入真实模型。这样可以避免一开始就被网络、音频格式和模型依赖三个问题同时纠缠。3. 实现录音3.1 在渲染进程采集麦克风浏览器也就是 Electron 的渲染进程通过navigator.mediaDevices.getUserMedia访问麦克风。把下面的需求交给 AI 助手Please help me modify src/index.html and src/renderer.js to implement: UI: 1. 一个大圆形 Start Recording 按钮点击后变成红色 Stop Recording 按钮 2. 录音时显示一个简单的脉冲动画 3. 下方一个文本展示区用于显示识别结果 4. 底部两个按钮Copy Text 和 Clear 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适配语音识别 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 单声道在保证识别质量的同时显著降低数据量与传输成本MediaRecorder输出 webm/opus 格式停止后把 Blob 转成ArrayBuffer再走 IPC 发送避免大数据跨进程时的结构开销。3.2 麦克风权限处理Electron 默认拒绝权限请求需要在主进程中显式放行Please help me add microphone permission handling in main.js: 1. Use session.defaultSession.setPermissionRequestHandler to handle permission requests 2. Auto-allow when request type is media 3. For macOS, ensure microphone usage description is declared in package.json or entitlements// 添加到 main.js const { session } require(electron) session.defaultSession.setPermissionRequestHandler( (webContents, permission, callback) { if (permission media) { callback(true) } else { callback(false) } } )macOS 用户注意macOS 还会弹出一个系统级的麦克风授权对话框这是正常现象点击 Allow 即可。结合仓库中 Field Voice Log 教程的验收思路录音功能至少需要验证四种情况允许权限后可以正常开始和停止录音拒绝权限后应用能明确提示如何开启而不是一直卡在加载状态连续快速点击不会同时创建两段录音防止状态竞争关闭窗口时释放麦克风资源。4. 方案 A云端识别OpenAI Whisper API这是最简单的方案只需要一个 API Key 和几行代码。4.1 获取 OpenAI API Key前往 OpenAI 平台注册并登录进入 API Keys 页面点击Create new secret key复制生成的密钥以sk-开头并安全保存。成本参考教程给出的参考价约为$0.006/分钟即识别 1 小时音频约 $0.36。价格可能随官方调整请以官方最新定价为准。4.2 在主进程调用 Whisper API把以下需求交给 AI 助手实现Please help me implement OpenAI Whisper API in main.js: 1. Install node-fetch (if needed) or use built-in fetch in Node.js 2. Create transcribeWithWhisper function that accepts audio ArrayBuffer 3. Convert ArrayBuffer to Blob/File and build FormData 4. Call https://api.openai.com/v1/audio/transcriptions 5. Use model whisper-1 and set language to zh (Chinese) 6. Return the recognized text 7. Read API key from environment variables or config file核心代码// 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 }这里language: zh显式指定中文可以避免模型在语言之间摇摆、提升中文识别准确率与响应速度。4.3 添加设置面板在渲染进程中增加一个简单的设置面板让用户输入 API Key 并切换识别模式Please help me add a settings panel in index.html: 1. Add a gear icon in the top-right corner; click to expand settings panel 2. The panel includes: - Recognition mode switch (Cloud API / Local model) - API Key input (only visible in cloud mode) - Language dropdown (Chinese / English / Auto detect) 3. Save settings to localStorage 4. Close panel when clicking outside关键安全原则结合仓库中文教程的明确警告不要把 API Key 放在渲染进程、localStorage、配置页或打包产物里。即使 Key 放在主进程桌面安装包仍然能被用户解包读取。组织级的共享密钥必须留在受控的服务端桌面应用最多只持有短期登录凭证。设置页只保存语言、识别方式、下载目录这类非敏感选项。5. 方案 B本地识别whisper.cpp如果你不想依赖云端 API或者需要完全离线使用whisper.cpp 是最佳选择。它是 OpenAI Whisper 模型的 C 移植版完全本地运行、无需联网。5.1 安装 nodejs-whisperPlease help me install nodejs-whisper in the project: npm install nodejs-whisper After installation, please help me download the whisper tiny model (small size, fast for testing). nodejs-whisper will handle model download automatically.模型选择参考体积与速度关系如下实际表现会随绑定库与硬件变化不应视为固定承诺tiny75 MB最快适合测试和轻量使用精度中等base142 MB速度与精度的平衡点small466 MB中文识别质量明显更好large-v3-turbo1.5 GB推荐据教程描述比 large 快 5-8 倍精度仅低 1-2%large-v33 GB精度最高但更慢、对硬件要求更高。5.2 在主进程集成 whisper.cppPlease help me add whisper.cpp local recognition in main.js: 1. Import nodejs-whisper 2. Create transcribeWithLocal function 3. Accept audio ArrayBuffer and save it as a temporary WAV file first (16kHz mono) 4. Call nodejs-whisper for recognition 5. Return recognized text 6. Delete temporary file after recognition核心代码// 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) } }这段代码有两个容易被忽视的工程细节16kHz 单声道 WAV 是前提whisper.cpp 对输入格式有要求录音时应把渲染进程采集到的音频先转成 16kHz 单声道 PCM WAV 再交给模型这也是 Field Voice Log 教程 中明确要求的转换步骤finally保证清理无论识别成功还是抛出异常临时文件都会被删除避免在用户磁盘上残留敏感录音。验收本地模式时建议按仓库中文教程的做法关闭网络再录一段十秒中文能生成文字、临时目录被清理、应用重启后没有残留录音才算通过。5.3 Apple Silicon 与 NVIDIA 用户的加速说明如果你使用 M1/M2/M3/M4 芯片的 Macwhisper.cpp 可以自动利用Metal GPU 加速和Apple Neural Engine据教程描述识别速度可以快于实时——一分钟的音频可能只需几秒处理。对于 NVIDIA GPU 用户whisper.cpp 同样支持CUDA 加速。提醒教程中的加速描述基于特定绑定库与硬件环境实际速度取决于模型大小、硬件型号和编译选项请以自己机器上的实测为准。6. 打包与分发开发完成后需要把应用打包成可安装、可分发的桌面程序。6.1 使用 Electron Forge 打包Electron Forge 已经在项目中内置打包只需一条命令Please help me run the Electron Forge packaging command: npx electron-forge make该命令会自动为当前操作系统生成安装包macOS.dmg安装镜像和.zip归档Windows.exe安装程序Squirrel 格式Linux.debDebian/Ubuntu和.rpmFedora包。构建产物输出在out/make/目录。需要明确的是一次命令只会生成已经配置、且当前操作系统支持的格式不会自动在任意电脑上同时产出所有平台的安装包。打包前应先确认 Forge 配置forge.config.js里存在当前系统需要的 Maker。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 会弹出安全警告未签名的应用用户可以手动选择 Run anyway 继续运行。Linux不要求代码签名建议同时提供.deb和.AppImage两种格式。提示对于个人项目或小范围分发可以暂时跳过代码签名直接把打包产物分享给朋友测试。打包后的验收来自仓库中文教程的硬性标准把安装包拿到一台没有 Node.js、没有项目源码的干净电脑上测试——能否安装启动、麦克风权限是否正常、模型或后端不可用时是否有提示、卸载后是否残留敏感临时文件。开发窗口里录音成功只说明项目在你的电脑上能跑安装包能在另一台电脑正常打开才算真正做完。7. 收尾与进阶方向恭喜你已经从零构建了一个跨平台语音转文字应用。回顾整个流程使用 Electron Forge 搭建了跨平台桌面应用骨架理解了主进程、渲染进程与 IPC 通信实现了麦克风录音与音频采集集成了两条语音识别路线云端 Whisper API 与本地 whisper.cpp学会了打包与分发 Electron 应用。Electron 的强大之处在于你可以用 Web 技术构建 VS Code、Slack 级别的桌面软件。而随着 AI 语音识别日趋成熟像语音转文字这样的功能过去需要一个专职团队现在一个人就能完成。进阶方向实时转写使用AudioWorklet处理流式音频对接流式识别 API 实现边说边转会议助手录制整场会议自动生成逐字稿并让 AI 提炼关键结论多语言翻译语音转写后调用翻译 API实现实时跨语言转换语音笔记结合本地数据库如 SQLite构建可检索的语音笔记库。最后无论后续接入本地模型还是企业识别服务都要守住已经建立好的边界页面不能直接拿到 Node.jsPreload 只开放必要能力共享密钥留在后端用户永远可以修改机器整理出来的记录。延伸阅读本仓库中的相关资源本教程原文docs/ar-sa/stage-3/cross-platform/electron-voice-to-text/index.md同主题中文实战教程Field Voice Log含完整验收清单与安全实践docs/zh-cn/stage-3/cross-platform/electron-voice-to-text/index.md仓库内 Electron 真实示例含安全 WebPreferences 配置examples/trae-3d-block-game/electron/main.js跨平台开发专题目录docs/ar-sa/stage-3/cross-platform、docs/zh-cn/stage-3/cross-platform本教程配套架构图与截图docs/zh-cn/stage-3/cross-platform/electron-voice-to-text/images/目录下的 image1 至 image10赞分享教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载相关推荐用 Tauri v2 构建 sherpa-onnx 桌面应用hello_world 与离线语音识别文件/麦克风实战指南用 Tauri v2 构建 sherpa onnx 桌面应用hello_world 与离线语音识别文件/麦克风实战指南 导读 本文基于 sherpa on人工智能语音音频本地部署基于 Tauri v2 与 sherpa-onnx 构建的麦克风离线语音识别桌面应用实战基于 Tauri v2 与 sherpa onnx 构建的麦克风离线语音识别桌面应用实战 本篇技术指南围绕 tauri examples/non streami人工智能语音音频本地部署MoneyPrinterTurbo跨平台构建Electron桌面应用打包指南MoneyPrinterTurbo跨平台构建Electron桌面应用打包指南 你是否还在为视频创作流程繁琐而困扰MoneyPrinterTurbo作为一款全AI 应用媒体生成音视频视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考