OpenWhispr开发指南贡献代码前你需要了解的核心组件【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/gh_mirrors/op/openwhisprOpenWhispr是一款开源的语音转文字听写应用支持本地和云端语音识别模型。如果你想要为这个项目贡献代码了解其核心架构和组件是至关重要的第一步。本文将为你详细解析OpenWhispr的架构设计、关键模块和开发流程帮助你快速上手。 项目概述与技术栈OpenWhispr采用现代化的桌面应用架构主要技术栈包括前端框架React 19 TypeScript Tailwind CSS v4桌面框架Electron 41支持跨平台语音处理whisper.cpp NVIDIA Parakeet本地模型 OpenAI API云端数据库better-sqlite3本地转录历史存储UI组件库shadcn/ui Radix UI 组件库️ 核心架构设计双窗口架构模式OpenWhispr采用独特的双窗口设计确保用户体验的流畅性主窗口轻量级悬浮窗口用于实时听写支持拖拽和置顶显示控制面板完整的设置界面包含所有配置选项和功能共享代码库两个窗口使用相同的React代码库通过URL路由进行区分进程隔离设计为了确保安全性和稳定性项目采用多层进程隔离主进程Electron主进程负责IPC处理、数据库操作和系统级功能渲染进程React应用运行环境支持上下文隔离预加载脚本安全的进程间通信桥梁ONNX工具进程专门处理语音识别和文本嵌入计算 关键组件解析语音处理引擎OpenWhispr的核心功能是语音转文字这一功能由多个组件协同完成whisper.js本地whisper.cpp集成管理器位于src/helpers/whisper.jsparakeet.jsNVIDIA Parakeet模型管理器支持高效CPU推理audioManager.js音频设备管理和录音流程控制语音处理流程如下MediaRecorder API收集音频数据音频数据通过IPC发送到主进程临时文件写入磁盘whisper.cpp或Parakeet进行转录结果返回并清理临时文件全局热键系统热键管理是OpenWhispr的关键特性支持多种操作系统和桌面环境hotkeyManager.js统一的热键注册和管理中心windowsKeyManager.jsWindows平台原生按键监听器gnomeShortcut.jsGNOME Wayland桌面环境集成hyprlandShortcut.jsHyprland Wayland桌面环境支持kdeShortcut.jsKDE桌面环境全局热键热键系统支持多种模式点击触发模式tap-to-talk按下保持模式push-to-talk语音助手专用热键voice agent hotkey会议检测引擎智能会议检测是OpenWhispr的亮点功能支持多种检测方式meetingDetectionEngine.js统一的检测协调器meetingProcessDetector.js进程检测器识别Zoom、Teams等应用audioActivityDetector.js麦克风使用检测器googleCalendarManager.jsGoogle日历集成检测策略包括事件驱动检测macOS CoreAudio、Windows WASAPI、Linux PulseAudio进程列表轮询30秒间隔日历事件集成本地语义搜索系统OpenWhispr内置了强大的离线语义搜索功能qdrantManager.jsQdrant向量数据库管理器localEmbeddings.js本地文本嵌入生成器vectorIndex.js向量索引管理搜索系统特点完全离线运行保护用户隐私混合搜索策略向量搜索 全文搜索自动模型下载和更新后台异步索引更新 项目文件结构了解项目文件结构有助于快速定位代码openwhispr/ ├── main.js # Electron主进程入口 ├── preload.js # 进程间通信桥接 ├── resources/ # 原生资源文件 │ ├── windows-key-listener.c # Windows按键监听器 │ ├── macos-mic-listener.swift # macOS麦克风监听器 │ └── bin/ # 编译后的原生二进制文件 ├── src/ │ ├── helpers/ # 核心功能模块 │ │ ├── whisper.js # 语音识别管理器 │ │ ├── hotkeyManager.js # 热键管理器 │ │ ├── audioManager.js # 音频管理器 │ │ └── database.js # 数据库操作 │ ├── components/ # React组件 │ │ ├── App.jsx # 主应用组件 │ │ ├── ControlPanel.tsx # 控制面板 │ │ └── ui/ # 可复用UI组件 │ ├── hooks/ # React Hooks │ │ ├── useAudioRecording.js # 录音Hook │ │ ├── useHotkey.js # 热键Hook │ │ └── useSettings.ts # 设置管理Hook │ └── stores/ # 状态管理 │ └── settingsStore.ts # 应用设置存储 └── scripts/ # 构建和工具脚本 ├── download-whisper-cpp.js # whisper.cpp下载脚本 ├── download-sherpa-onnx.js # Parakeet下载脚本 └── build-*.js # 各平台原生代码编译脚本 开发环境搭建前置要求Node.js 24项目严格使用Node.js 24版本查看.nvmrc文件npm包管理器建议使用npm 10平台特定工具macOSXcode命令行工具WindowsVisual Studio Build ToolsLinuxgcc、make等编译工具安装步骤# 克隆仓库 git clone https://gitcode.com/gh_mirrors/op/openwhispr # 进入项目目录 cd openwhispr # 使用Node.js 24通过nvm nvm use 24 # 安装依赖 npm install # 下载必要的二进制文件 npm run download:whisper-cpp npm run download:qdrant npm run download:embedding-model # 启动开发服务器 npm run dev编译原生组件不同平台需要编译不同的原生组件# 编译所有原生组件 npm run compile:native # 或单独编译特定组件 npm run build:windows-key-listener # Windows按键监听器 npm run build:macos-mic-listener # macOS麦克风监听器 npm run build:linux-fast-paste # Linux快速粘贴工具 开发工作流程添加新功能新增IPC通道在src/helpers/ipcHandlers.js中添加处理函数在preload.js中暴露给渲染进程新增设置项更新src/hooks/useSettings.ts中的设置类型定义在src/components/SettingsPage.tsx中添加UI控件新增UI组件遵循shadcn/ui设计模式放置在src/components/ui/目录中使用Tailwind CSS进行样式设计新增功能模块在src/helpers/目录中创建新的管理器类在main.js中初始化和注册确保资源正确清理国际化支持OpenWhispr支持9种语言所有用户界面文本必须使用国际化系统// 正确做法 import { useTranslation } from react-i18next; const { t } useTranslation(); return div{t(settings.audio.deviceLabel)}/div; // 错误做法 - 硬编码文本 return divAudio Device/div;翻译文件位于src/locales/目录需要为每个新增的文本键在所有语言文件中添加翻译。测试要点在提交代码前确保测试以下关键功能本地和云端语音识别模式全局热键功能剪贴板粘贴功能各平台不同音频输入设备whisper.cpp二进制文件检测所有语音识别模型AI助手命名功能自定义词典功能Windows按下保持模式GNOME/Hyprland Wayland热键会议检测功能本地语义搜索 常见问题与解决方案音频无法检测问题应用无法检测到麦克风输入解决方案检查FFmpeg路径解析查看调试日志验证麦克风权限设置检查音频设备配置查看调试日志中的音频级别分析转录失败问题语音转录功能无法正常工作解决方案确认whisper.cpp二进制文件存在检查模型文件是否已下载验证临时文件创建权限确认FFmpeg可执行权限剪贴板粘贴问题平台特定解决方案macOS检查辅助功能权限LinuxX11环境使用xdotoolWayland环境使用wtype或xdotoolXWayland应用GNOME Wayland仅支持XWayland应用Windows使用PowerShell SendKeys或nircmd.exe构建问题问题项目构建失败解决方案使用npm run pack进行未签名构建确保使用Node.js 24版本运行npm run download:whisper-cpp:all下载多平台二进制文件检查package-lock.json是否使用正确版本生成 贡献代码规范代码风格指南TypeScript优先新组件使用TypeScript编写遵循现有模式参考helpers/目录中的代码结构错误处理提供清晰的错误信息和用户友好的提示资源管理确保文件、监听器等资源正确清理边界情况处理所有可能的边缘情况提交要求功能完整性确保新功能完全实现测试覆盖添加必要的单元测试和集成测试文档更新更新相关文档和注释国际化为所有新文本添加翻译键性能考虑避免内存泄漏和性能问题安全注意事项API密钥管理使用Electron安全存储加密敏感信息上下文隔离保持渲染进程与主进程的隔离文件路径消毒防止路径遍历攻击IPC安全限制IPC通道的暴露范围 未来发展方向了解项目的发展方向有助于做出有价值的贡献流式转录支持实时语音转文字功能自定义唤醒词用户自定义的唤醒词检测批量转录功能支持批量处理音频文件导出格式扩展支持更多导出格式插件系统可扩展的插件架构云模型选择更多云端语音识别服务支持 开发建议调试技巧启用调试模式设置OPENWHISPR_LOG_LEVELdebug环境变量查看平台特定的日志文件位置使用Chrome DevTools调试渲染进程使用Node.js调试器调试主进程性能优化内存管理及时清理临时文件和缓冲区进程通信最小化IPC数据传递量懒加载按需加载大型模型和组件缓存策略合理使用缓存减少重复计算跨平台兼容性功能检测运行时检测平台特性优雅降级为不支持的功能提供替代方案渐进增强在支持的环境中提供增强功能用户反馈清晰告知用户平台限制 开始贡献现在你已经了解了OpenWhispr的核心架构和开发流程可以开始贡献代码了建议从以下方面入手修复现有问题查看GitHub Issues中的bug报告添加测试用例提高项目测试覆盖率改进文档完善使用文档和开发文档优化性能识别并修复性能瓶颈添加小功能实现用户请求的小功能记住OpenWhispr是一个注重隐私的开源项目所有贡献都应该遵循项目的核心价值观用户隐私保护、跨平台兼容性和优秀的用户体验。祝你编码愉快【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/gh_mirrors/op/openwhispr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考