[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-OpenWhispr--openwhispr":3,"tool-OpenWhispr--openwhispr":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",142651,2,"2026-04-06T23:34:12",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":72,"owner_avatar_url":73,"owner_bio":74,"owner_company":75,"owner_location":75,"owner_email":76,"owner_twitter":64,"owner_website":77,"owner_url":78,"languages":79,"stars":113,"forks":114,"last_commit_at":115,"license":116,"difficulty_score":117,"env_os":118,"env_gpu":119,"env_ram":120,"env_deps":121,"category_tags":133,"github_topics":135,"view_count":32,"oss_zip_url":75,"oss_zip_packed_at":75,"status":17,"created_at":151,"updated_at":152,"faqs":153,"releases":188},4810,"OpenWhispr\u002Fopenwhispr","openwhispr","Voice-to-text dictation app with local (Nvidia Parakeet\u002FWhisper) and cloud models (BYOK). Privacy-first and available cross-platform.","OpenWhispr 是一款注重隐私的跨平台语音转文字应用，旨在将用户的口述内容高效转化为文本，并集成智能 AI 助手以提升生产力。它解决了传统听写工具依赖云端导致的数据隐私顾虑，以及会议记录繁琐、AI 交互不够自然等痛点。\n\n无论是需要快速记录灵感的普通用户、追求数据安全的职场人士，还是希望本地部署大模型的技术爱好者，都能从中受益。其核心亮点在于“隐私优先”架构：支持利用 NVIDIA Parakeet 或 Whisper 模型在本地离线运行，确保语音数据不出设备；同时也兼容主流云端大模型（如 GPT-5、Claude 4.6 等），允许用户自带密钥（BYOK）灵活切换。\n\n功能上，OpenWhispr 不仅提供全局快捷键听写、自动粘贴和媒体暂停等便捷操作，还内置了智能词典自学习机制以优化专业术语识别。独特的\"AI 代理模式”允许用户通过自定义唤醒词与玻璃拟态界面的 AI 进行实时流式对话，甚至直接操作笔记。此外，它能自动检测并转录 Zoom、Teams 等平台的会议内容，无缝衔接日程管理，让语音交互真正成为日常工作的得力助手。","\u003Cp align=\"center\">\n  \u003Cimg src=\"src\u002Fassets\u002Flogo.svg\" alt=\"OpenWhispr\" width=\"120\" \u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">OpenWhispr\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002FOpenWhispr\u002Fopenwhispr?style=flat\" alt=\"License\" \u002F>\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey?style=flat\" alt=\"Platform\" \u002F>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Freleases\u002Flatest\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FOpenWhispr\u002Fopenwhispr?style=flat&sort=semver\" alt=\"GitHub release\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002FOpenWhispr\u002Fopenwhispr\u002Ftotal?style=flat&color=blue\" alt=\"Downloads\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FOpenWhispr\u002Fopenwhispr?style=flat\" alt=\"GitHub stars\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">Voice-to-text dictation and productivity app with AI agents, meeting transcription, notes, and local\u002Fcloud speech recognition.\u003Cbr\u002F>Privacy-first and available cross-platform.\u003C\u002Fp>\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FOpenWhispr_openwhispr_readme_66b78180373b.png)](https:\u002F\u002Fwww.star-history.com\u002F#OpenWhispr\u002Fopenwhispr&type=date&legend=top-left)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. This means you can freely use, modify, and distribute this software for personal or commercial purposes.\n\n## Features\n\n### Dictation & Transcription\n\n- 🎤 **Global Hotkey**: Customizable hotkey to start\u002Fstop dictation from anywhere (default: backtick `)\n- ⚡ **Automatic Pasting**: Transcribed text automatically pastes at your cursor location (with toggle to disable)\n- 🔒 **Privacy-First**: Local processing keeps your voice data completely private\n- ⚡ **NVIDIA Parakeet**: Fast local transcription via sherpa-onnx (multilingual, 25 languages)\n- 🔧 **Model Management**: Download and manage local Whisper models (tiny, base, small, medium, large, turbo)\n- 📖 **Custom Dictionary**: Add words, names, and technical terms to improve transcription accuracy, with auto-learn that detects your corrections and updates the dictionary automatically\n- 🗄️ **Transcription History**: SQLite database stores all your transcriptions locally with audio retention and retry\n- 🎵 **Auto-Pause Media**: Automatically pauses media playback (Spotify, Apple Music, etc.) during dictation and resumes afterward\n\n### AI Agent Mode\n\n- 🤖 **Agent Overlay**: Glassmorphism chat overlay with real-time AI streaming, resizable window, and conversation history\n- 🎯 **Agent Naming**: Personalize your AI assistant with a custom name — say \"Hey [AgentName]\" to give commands\n- 🧠 **Multi-Provider AI**:\n  - **OpenAI**: GPT-5, GPT-4.1, o-series reasoning models\n  - **Anthropic**: Claude Opus 4.6, Claude Sonnet 4.6\n  - **Google**: Gemini 3.1 Pro, Gemini 3 Flash, Gemini 2.5 Flash Lite\n  - **Groq**: Ultra-fast inference with Llama and Mixtral models\n  - **Local**: Qwen, LLaMA, Mistral, Gemma models via llama.cpp\n- 🛠️ **Agent Tool Calling**: Agentic tools for searching, creating, and updating notes — with RAG context injection for local models\n- 🤖 **AI Actions**: Apply AI-powered actions to notes with customizable processing templates\n\n### Meeting Transcription\n\n- 📅 **Google Calendar Integration**: Connect multiple Google accounts, view upcoming meetings in the sidebar, and receive auto-detection prompts\n- 🎙️ **Live Meeting Transcription**: Record and transcribe meetings in real-time via OpenAI Realtime API with automatic meeting detection (Zoom, Teams, FaceTime)\n- ⚡ **WebSocket Streaming for BYOK**: Real-time OpenAI Realtime API streaming for standard dictation mode, not just meetings — unified streaming path for all transcription\n- ⌨️ **Meeting Hotkey**: Dedicated hotkey to start\u002Fstop meeting transcription independently from dictation\n- 🔍 **Smart Detection**: Combines process monitoring, sustained audio detection, and calendar awareness to detect meetings automatically\n\n### Notes\n\n- 📝 **Notes System**: Create, edit, and organize notes with folders, audio upload, and real-time dictation\n- 🔎 **Full-Text Search**: FTS5-powered search across all note content with Cmd+K command palette\n- 🧠 **Local Semantic Search**: Always-on Qdrant vector DB with MiniLM embeddings for offline meaning-based search across notes\n- ☁️ **Cloud Sync**: Local-first storage with cloud backup and semantic search\n- 💬 **Embedded Chat**: Chat panel in the note editor with floating and sidebar modes\n- 📁 **Folder Organization**: Organize notes into custom folders with drag-and-drop\n- 💾 **Save Notes as Files**: Export notes to the local filesystem as Markdown files, mirroring your folder hierarchy\n\n### Cloud & Account\n\n- ☁️ **OpenWhispr Cloud**: Sign in and transcribe instantly — no API keys needed, with free and Pro plans\n- 🔐 **Account System**: Google OAuth and email\u002Fpassword sign-in with email verification\n- 💳 **Subscription Management**: Free tier (2,000 words\u002Fweek), Pro tier (unlimited), 7-day free trial\n- 🔗 **Referral Program**: Invite friends and earn free Pro months with shareable referral cards\n\n### Platform & UI\n\n- 🌐 **Cross-Platform**: Works on macOS, Windows, and Linux\n- 🎨 **Modern UI**: Built with React 19, TypeScript, and Tailwind CSS v4\n- 📱 **Responsive Settings**: Settings dialog adapts to narrow windows with collapsible icon-rail sidebar and stacked layouts\n- 🖱️ **Draggable Interface**: Move the dictation panel anywhere on your screen with configurable start position\n- 🌐 **Globe Key Toggle (macOS)**: Optional Fn\u002FGlobe key listener for a hardware-level dictation trigger — no Input Monitoring permission required\n- ⌨️ **Compound Hotkeys**: Support for multi-key combinations like `Cmd+Shift+K`\n- 🎙️ **Push-to-Talk (Windows)**: Native low-level keyboard hook for true push-to-talk with compound hotkey support\n- 🐧 **GNOME Wayland Support**: Native global shortcuts via D-Bus for GNOME Wayland users\n- 🐧 **KDE Wayland Support**: Native global shortcuts via D-Bus for KDE Plasma on Wayland\n- 🐧 **Hyprland Wayland Support**: Native global shortcuts via `hyprctl` keybindings + D-Bus for Hyprland users\n- 🖥️ **Multi-Monitor**: Floating dictation icon follows your cursor across monitors\n- 🧹 **Model Cleanup**: One-click removal of cached models with uninstall hooks to keep disks tidy\n\n## Prerequisites\n\n- **Node.js 22+** and npm (Download from [nodejs.org](https:\u002F\u002Fnodejs.org\u002F))\n- **macOS 12+**, **Windows 10+**, or **Linux**\n- On macOS, Globe key support requires the Xcode Command Line Tools (`xcode-select --install`) so the bundled Swift helper can run\n\n## Quick Start\n\n### For Personal Use (Recommended)\n\n1. **Clone the repository**:\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr.git\n   cd openwhispr\n   ```\n\n2. **Install dependencies**:\n\n   ```bash\n   npm install\n   ```\n\n3. **Optional: Set up API keys** (only needed for cloud processing):\n\n   **Method A - Environment file**:\n\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your API keys:\n   # OPENAI_API_KEY=your_openai_key\n   # ANTHROPIC_API_KEY=your_anthropic_key\n   # GEMINI_API_KEY=your_gemini_key\n   # GROQ_API_KEY=your_groq_key\n   # MISTRAL_API_KEY=your_mistral_key\n   ```\n\n   **Method B - In-app configuration**:\n   - Run the app and configure API keys through the Control Panel\n   - Keys are automatically saved and persist across app restarts\n\n4. **Build the application**:\n\n   ```bash\n   npm run build\n   ```\n\n5. **Run the application**:\n\n   ```bash\n   npm run dev  # Development mode with hot reload\n   # OR\n   npm start    # Production mode\n   ```\n\n6. **Optional: Local Whisper from source** (only needed if you want local processing):\n   ```bash\n   npm run download:whisper-cpp\n   ```\n   This downloads the whisper.cpp binary for your current platform into `resources\u002Fbin\u002F`.\n\n### Building for Personal Use (Optional)\n\nIf you want to build a standalone app for personal use:\n\n```bash\n# Build without code signing (no certificates required)\nnpm run pack\n\n# The unsigned app will be in: dist\u002Fmac-arm64\u002FOpenWhispr.app (macOS)\n# or dist\u002Fwin-unpacked\u002FOpenWhispr.exe (Windows)\n# or dist\u002Flinux-unpacked\u002Fopen-whispr (Linux)\n```\n\n**Note**: On macOS, you may see a security warning when first opening the unsigned app. Right-click and select \"Open\" to bypass this.\n\n#### Windows\n\n**Native Paste Binary (`windows-fast-paste`)**:\n\nOpenWhispr ships a native C binary for pasting text on Windows, using the Win32 `SendInput` API. This is the **primary** paste mechanism — `nircmd` and PowerShell are only used as fallbacks if the native binary fails.\n\nHow it works:\n\n- **Normal applications**: Simulates `Ctrl+V` via `SendInput` with virtual key codes (`VK_CONTROL` + `V`)\n- **Terminal emulators**: Detects the foreground window's class name and simulates `Ctrl+Shift+V` instead\n- **Terminal detection**: Recognizes Windows Terminal, cmd.exe, PowerShell, mintty (Git Bash), PuTTY, Alacritty, WezTerm, kitty, Hyper, MobaXterm, and ConEmu\u002FCmder\n- **Detect-only mode**: Supports `--detect-only` flag to report the foreground window class without sending keystrokes\n\nCompilation (handled automatically by the build system):\n\n```bash\n# MSVC\ncl \u002FO2 windows-fast-paste.c \u002FFe:windows-fast-paste.exe user32.lib\n\n# MinGW\ngcc -O2 windows-fast-paste.c -o windows-fast-paste.exe -luser32\n```\n\nThe build script (`scripts\u002Fbuild-windows-fast-paste.js`) first attempts to download a prebuilt binary from GitHub releases. If unavailable, it compiles from source using MSVC, MinGW-w64, or Clang. Falls back to `nircmd` or PowerShell `SendKeys` if neither option works.\n\n> ℹ️ **Note**: `CASCADIA_HOSTING_WINDOW_CLASS` covers all shells running inside Windows Terminal (PowerShell, CMD, WSL, etc.), so most modern Windows terminal usage is covered by a single class entry.\n\n#### Linux (Multiple Package Formats)\n\nOpenWhispr now supports multiple Linux package formats for maximum compatibility:\n\n**Available Formats**:\n\n- `.deb` - Debian, Ubuntu, Linux Mint, Pop!\\_OS\n- `.rpm` - Fedora, Red Hat, CentOS, openSUSE\n- `.tar.gz` - Universal archive (works on any distro)\n- `.flatpak` - Sandboxed cross-distro package\n- `AppImage` - Portable single-file executable\n\n**Building Linux Packages**:\n\n```bash\n# Build default Linux package formats (AppImage, deb, rpm, tar.gz)\nnpm run build:linux\n\n# Find packages in dist\u002F:\n# - OpenWhispr-x.x.x-linux-x64.AppImage\n# - OpenWhispr-x.x.x-linux-x64.deb\n# - OpenWhispr-x.x.x-linux-x64.rpm\n# - OpenWhispr-x.x.x-linux-x64.tar.gz\n```\n\n**Optional: Building Flatpak** (requires additional setup):\n\n```bash\n# Install Flatpak build tools\nsudo apt install flatpak flatpak-builder  # Debian\u002FUbuntu\n# OR\nsudo dnf install flatpak flatpak-builder  # Fedora\u002FRHEL\n\n# Add Flathub repository and install runtime\nflatpak remote-add --user --if-not-exists flathub https:\u002F\u002Fflathub.org\u002Frepo\u002Fflathub.flatpakrepo\nflatpak install --user -y flathub org.freedesktop.Platform\u002F\u002F24.08 org.freedesktop.Sdk\u002F\u002F24.08\n\n# Add \"flatpak\" to linux.target in electron-builder.json, then build\nnpm run build:linux\n```\n\n**Installation Examples**:\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install .\u002Fdist\u002FOpenWhispr-*-linux-x64.deb\n\n# Fedora\u002FRHEL\nsudo dnf install .\u002Fdist\u002FOpenWhispr-*-linux-x64.rpm\n\n# Universal tar.gz (no root required)\ntar -xzf dist\u002FOpenWhispr-*-linux-x64.tar.gz\ncd OpenWhispr-*\u002F\n.\u002Fopenwhispr\n\n# Flatpak\nflatpak install --user .\u002Fdist\u002FOpenWhispr-*-linux-x64.flatpak\n\n# AppImage (existing method)\nchmod +x dist\u002FOpenWhispr-*.AppImage\n.\u002Fdist\u002FOpenWhispr-*.AppImage\n```\n\n**Native Paste Binary (`linux-fast-paste`)**:\n\nOpenWhispr ships a native C binary for pasting text on Linux, compiled automatically at build time. This is the **primary** paste mechanism — external tools like `xdotool` and `wtype` are only used as fallbacks if the native binary fails.\n\nHow it works:\n\n- **X11**: Uses the XTest extension to synthesize `Ctrl+V` (or `Ctrl+Shift+V` in terminals) directly, with no external dependencies beyond X11 itself\n- **Wayland**: Uses the Linux `uinput` subsystem to create a virtual keyboard and inject keystrokes. Falls back to XTest via XWayland if uinput is unavailable\n- **Terminal detection**: Recognizes 20+ terminal emulators (kitty, alacritty, gnome-terminal, wezterm, ghostty, etc.) and automatically uses `Ctrl+Shift+V` instead of `Ctrl+V`\n- **Window targeting**: Can target a specific window ID via `--window` to ensure keystrokes reach the correct application\n\nBuild dependencies (for compiling from source):\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install gcc libx11-dev libxtst-dev\n\n# Fedora\u002FRHEL\nsudo dnf install gcc libX11-devel libXtst-devel\n\n# Arch\nsudo pacman -S gcc libx11 libxtst\n```\n\nThe build script (`scripts\u002Fbuild-linux-fast-paste.js`) runs during `npm run compile:linux-paste` and:\n\n1. Detects whether `linux\u002Fuinput.h` headers are available\n2. Compiles with `-DHAVE_UINPUT` if so (enables Wayland uinput support)\n3. Caches the binary and skips rebuilds unless the source or flags change\n4. Gracefully falls back to system tools if compilation fails\n\nIf the native binary isn't available, OpenWhispr falls back to external paste tools in this order:\n\n**Fallback Dependencies for Automatic Paste**:\n\nThe following tools are used as fallbacks when the native paste binary is unavailable or fails:\n\n**X11 (Traditional Linux Desktop)**:\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install xdotool\n\n# Fedora\u002FRHEL\nsudo dnf install xdotool\n\n# Arch\nsudo pacman -S xdotool\n```\n\n**Wayland (Modern Linux Desktop)**:\n\n**Recommended:** Install `wl-clipboard` for reliable clipboard sharing between Wayland apps:\n\n```bash\nsudo apt install wl-clipboard    # Debian\u002FUbuntu\nsudo dnf install wl-clipboard    # Fedora\u002FRHEL\nsudo pacman -S wl-clipboard      # Arch\n```\n\nChoose **one** of the following paste tools:\n\n**Option 1: wtype** (requires virtual keyboard protocol support)\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install wtype\n\n# Fedora\u002FRHEL\nsudo dnf install wtype\n\n# Arch\nsudo pacman -S wtype\n```\n\n**Option 2: ydotool** (works on more compositors, requires daemon)\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install ydotool\nsudo systemctl enable --now ydotoold\n\n# Fedora\u002FRHEL\nsudo dnf install ydotool\nsudo systemctl enable --now ydotoold\n\n# Arch\nsudo pacman -S ydotool\nsudo systemctl enable --now ydotoold\n```\n\n**Terminal Detection** (Optional - for KDE Wayland users):\n\n```bash\n# On KDE Wayland, kdotool enables automatic terminal detection\n# to paste with Ctrl+Shift+V instead of Ctrl+V\nsudo apt install kdotool  # Debian\u002FUbuntu\nsudo dnf install kdotool  # Fedora\u002FRHEL\nsudo pacman -S kdotool    # Arch\n```\n\n> ℹ️ **Note**: OpenWhispr automatically tries paste methods in this order: native `linux-fast-paste` binary (XTest or uinput) → `wtype` → `ydotool` → `xdotool` (for XWayland apps). If no paste method works, text will still be copied to the clipboard - you'll just need to paste manually with Ctrl+V.\n\n> ⚠️ **ydotool Requirements**: The `ydotoold` daemon must be running for ydotool to work. Start it manually with `sudo ydotoold &` or enable the systemd service as shown above.\n\n**GNOME Wayland Global Hotkeys**:\n\nOn GNOME Wayland, Electron's standard global shortcuts don't work due to Wayland's security model. OpenWhispr automatically uses native GNOME keyboard shortcuts via D-Bus and gsettings:\n\n- Hotkeys are registered as GNOME custom shortcuts (visible in Settings → Keyboard → Shortcuts)\n- Default hotkey is `Alt+R` (backtick not supported on GNOME Wayland)\n- **Push-to-talk mode is not available** on GNOME Wayland (only tap-to-talk)\n- Falls back to X11\u002FXWayland shortcuts if GNOME integration fails\n- No additional dependencies required - uses `dbus-next` npm package\n\n> ℹ️ **GNOME Wayland Limitation**: GNOME system shortcuts only fire a single toggle event (no key-up detection), so push-to-talk mode cannot work. The app automatically uses tap-to-talk mode on GNOME Wayland.\n\n> 🔒 **Flatpak Security**: The Flatpak package includes sandboxing with explicit permissions for microphone, clipboard, and file access. See [electron-builder.json](electron-builder.json) for the complete permission list.\n\n### Building for Distribution\n\nFor maintainers who need to distribute signed builds:\n\n```bash\n# Requires code signing certificates and notarization setup\nnpm run build:mac    # macOS (requires Apple Developer account)\nnpm run build:win    # Windows (requires code signing cert)\nnpm run build:linux  # Linux\n```\n\n### First Time Setup\n\n1. **Choose Processing Method**:\n   - **OpenWhispr Cloud**: Sign in for instant cloud transcription with free and Pro plans\n   - **Bring Your Own Key**: Use your own OpenAI\u002FGroq\u002FAssemblyAI API keys\n   - **Local Processing**: Download Whisper or Parakeet models for completely private transcription\n\n2. **Grant Permissions**:\n   - **Microphone Access**: Required for voice recording\n   - **Accessibility Permissions**: Required for automatic text pasting (macOS)\n   - **Screen Recording** (optional, macOS): Required for meeting audio capture — prompted during onboarding if you want meeting features\n\n3. **Name Your Agent**: Give your AI assistant a personal name (e.g., \"Assistant\", \"Jarvis\", \"Alex\")\n   - Makes interactions feel more natural and conversational\n   - Helps distinguish between giving commands and regular dictation\n   - Can be changed anytime in settings\n\n4. **Configure Global Hotkey**: Default is backtick (`) but can be customized\n\n## Usage\n\n### Basic Dictation\n\n1. **Start the app** - A small draggable panel appears on your screen\n2. **Press your hotkey** (default: backtick `) - Start dictating (panel shows recording animation)\n3. **Press your hotkey again** - Stop dictation and begin transcription (panel shows processing animation)\n4. **Text appears** - Transcribed text is automatically pasted at your cursor location\n5. **Drag the panel** - Click and drag to move the dictation panel anywhere on your screen\n\n### Control Panel\n\n- **Access**: Right-click the tray icon (macOS) or through the system menu\n- **Configure**: Choose between local and cloud processing\n- **History**: View, copy, and delete past transcriptions — with audio playback and retry for failed transcriptions\n- **Notes**: Create, edit, and organize notes with folders, AI actions, and full-text search\n- **Integrations**: Connect Google Calendar accounts for meeting detection and transcription\n- **Models**: Download and manage local Whisper and Parakeet models\n- **Storage Cleanup**: Remove downloaded models from cache to reclaim space\n- **Settings**: Configure API keys, customize hotkeys, manage permissions, and set up Agent Mode\n- **Cmd+K Search**: Quick search across notes and transcripts from anywhere in the app\n\n### Uninstall & Cache Cleanup\n\n- **In-App**: Use _Settings → General → Local Model Storage → Remove Downloaded Models_ to clear cached Whisper and Parakeet models from `~\u002F.cache\u002Fopenwhispr\u002F` (or `%USERPROFILE%\\.cache\\openwhispr\\` on Windows).\n- **Audio Files**: Retained audio files are stored in your app data directory and cleaned up automatically after 30 days. Clear manually via Settings if needed.\n- **Windows Uninstall**: The NSIS uninstaller automatically deletes the cache directory.\n- **Linux Packages**: `deb`\u002F`rpm` post-uninstall scripts also remove cached models.\n- **macOS**: If you uninstall manually, remove `~\u002FLibrary\u002FCaches` or `~\u002F.cache\u002Fopenwhispr\u002F` if desired.\n\n### Agent Naming & AI Processing\n\nOnce you've named your agent during setup, you can interact with it using multiple AI providers:\n\n**🎯 Agent Commands** (for AI assistance):\n\n- \"Hey [AgentName], make this more professional\"\n- \"Hey [AgentName], format this as a list\"\n- \"Hey [AgentName], write a thank you email\"\n- \"Hey [AgentName], convert this to bullet points\"\n\n**🤖 AI Provider Options**:\n\n- **OpenAI**: GPT-5, GPT-4.1, o-series reasoning models\n- **Anthropic**: Claude Opus 4.6, Sonnet 4.6, Haiku 4.5\n- **Google**: Gemini 3.1 Pro, Gemini 3 Flash, Gemini 2.5 Flash Lite\n- **Groq**: Ultra-fast Llama and Mixtral inference\n- **Local**: Qwen, LLaMA, Mistral, Gemma models via llama.cpp\n\n**📝 Regular Dictation** (for normal text):\n\n- \"This is just normal text I want transcribed\"\n- \"Meeting notes: John mentioned the quarterly report\"\n- \"Dear Sarah, thank you for your help\"\n\nThe AI automatically detects when you're giving it commands versus dictating regular text, and removes agent name references from the final output.\n\n### Custom Dictionary\n\nImprove transcription accuracy for specific words, names, or technical terms:\n\n1. **Access Settings**: Open Control Panel → Settings → Custom Dictionary\n2. **Add Words**: Enter words, names, or phrases that are frequently misrecognized\n3. **How It Works**: Words are provided as context hints to the speech recognition model\n\n**Examples of words to add**:\n\n- Uncommon names (e.g., \"Sergey\", \"Xanthe\")\n- Technical jargon (e.g., \"Kubernetes\", \"OAuth\")\n- Brand names (e.g., \"OpenWhispr\", \"whisper.cpp\")\n- Domain-specific terms (e.g., \"amortization\", \"polymerase\")\n\n### Agent Mode\n\nAgent Mode opens a resizable glassmorphism chat overlay for interactive AI conversations:\n\n1. **Enable**: Go to Settings → Agent Mode and toggle it on\n2. **Set a Hotkey**: Assign a dedicated hotkey to open the agent overlay\n3. **Chat**: Press the hotkey to open the overlay, dictate your message, and receive streaming AI responses\n4. **Customize**: Set a custom system prompt, choose your preferred AI provider and model\n5. **History**: All conversations are saved and can be resumed\n\n### Meeting Transcription\n\nAutomatically detect and transcribe meetings with Google Calendar integration:\n\n1. **Connect Calendar**: Go to Integrations → Google Calendar and sign in\n2. **Grant Screen Recording** (macOS): Required to capture meeting audio\n3. **Auto-Detection**: When a meeting starts (Zoom, Teams, FaceTime), a notification appears asking to record\n4. **Live Transcription**: Meeting audio is transcribed in real-time via OpenAI Realtime API\n5. **Review**: Meeting transcriptions are saved as notes for later review and AI enhancement\n\n### Processing Options\n\n- **OpenWhispr Cloud**:\n  - Sign in with Google or email — no API keys needed\n  - Free plan: 2,000 words\u002Fweek with 7-day Pro trial for new accounts\n  - Pro plan: unlimited transcriptions\n- **Bring Your Own Key (BYOK)**:\n  - Use your own API keys from OpenAI, Groq, Mistral, AssemblyAI, or custom endpoints\n  - Full control over provider and model selection\n- **Local Processing**:\n  - Install Whisper or NVIDIA Parakeet through the Control Panel\n  - Download models: tiny (fastest), base (recommended), small, medium, large (best quality)\n  - Complete privacy - audio never leaves your device\n\n## Project Structure\n\n```\nopen-whispr\u002F\n├── main.js              # Electron main process & IPC handlers\n├── preload.js           # Electron preload script & API bridge\n├── setup.js             # First-time setup script\n├── package.json         # Dependencies and scripts\n├── env.example          # Environment variables template\n├── CHANGELOG.md         # Project changelog\n├── src\u002F\n│   ├── App.jsx          # Main dictation interface\n│   ├── main.jsx         # React entry point\n│   ├── index.html       # Vite HTML template\n│   ├── index.css        # Tailwind CSS v4 configuration\n│   ├── vite.config.js   # Vite configuration\n│   ├── components\u002F\n│   │   ├── ControlPanel.tsx     # Settings and history UI\n│   │   ├── OnboardingFlow.tsx   # First-time setup wizard\n│   │   ├── SettingsPage.tsx     # Settings interface\n│   │   ├── AgentOverlay.tsx     # Agent mode chat overlay\n│   │   ├── CommandSearch.tsx    # Cmd+K command palette\n│   │   ├── IntegrationsView.tsx # Google Calendar & integrations\n│   │   ├── UpcomingMeetings.tsx # Sidebar meeting list\n│   │   ├── agent\u002F               # Agent mode components\n│   │   │   ├── AgentChat.tsx\n│   │   │   ├── AgentInput.tsx\n│   │   │   ├── AgentMessage.tsx\n│   │   │   └── AgentTitleBar.tsx\n│   │   ├── notes\u002F               # Notes system components\n│   │   │   ├── NoteEditor.tsx\n│   │   │   ├── ActionPicker.tsx\n│   │   │   ├── ActionManagerDialog.tsx\n│   │   │   └── ...\n│   │   ├── settings\u002F            # Settings sub-components\n│   │   │   └── AgentModeSettings.tsx\n│   │   ├── ui\u002F                  # shadcn\u002Fui components\n│   │   └── lib\u002F\n│   │       └── utils.ts         # Utility functions\n│   ├── config\u002F\n│   │   └── prompts.ts           # Centralized AI prompt definitions\n│   ├── services\u002F\n│   │   └── ReasoningService.ts  # Multi-provider AI processing with streaming\n│   ├── hooks\u002F\n│   │   ├── useMeetingTranscription.ts  # Meeting audio capture\n│   │   ├── useUpcomingEvents.ts        # Calendar event fetching\n│   │   ├── useScreenRecordingPermission.ts  # macOS permission\n│   │   └── ...\n│   ├── helpers\u002F\n│   │   ├── googleCalendarManager.js    # Calendar sync & events\n│   │   ├── googleCalendarOAuth.js      # OAuth 2.0 PKCE flow\n│   │   ├── meetingDetectionEngine.js   # Smart meeting detection\n│   │   ├── audioStorage.js             # Audio file retention\n│   │   ├── mediaPlayer.js             # Cross-platform media control\n│   │   └── ...\n│   ├── utils\u002F\n│   │   └── agentName.ts         # Agent name management utility\n│   └── components.json          # shadcn\u002Fui configuration\n├── resources\u002F\n│   └── bin\u002F                     # Native binaries (whisper-cpp, sherpa-onnx, etc.)\n└── assets\u002F                      # App icons and resources\n```\n\n## Technology Stack\n\n- **Frontend**: React 19, TypeScript, Tailwind CSS v4\n- **Build Tool**: Vite with optimized Tailwind plugin\n- **Desktop**: Electron 39 with context isolation\n- **UI Components**: shadcn\u002Fui with Radix primitives\n- **Database**: better-sqlite3 with FTS5 for local storage (transcriptions, notes, agents, calendar)\n- **Speech-to-Text**: OpenAI Whisper (whisper.cpp) + NVIDIA Parakeet (sherpa-onnx) for local, OpenAI API for cloud\n- **Live Transcription**: OpenAI Realtime API over WebSocket for meeting transcription\n- **AI Processing**: Multi-provider streaming (OpenAI, Anthropic, Gemini, Groq, local llama.cpp)\n- **Calendar**: Google Calendar API with OAuth 2.0 PKCE\n- **Icons**: Lucide React for consistent iconography\n\n## Development\n\n### Scripts\n\n- `npm run dev` - Start development with hot reload\n- `npm run start` - Start production build\n- `npm run setup` - First-time setup (creates .env file)\n- `npm run build:renderer` - Build the React app only\n- `npm run download:whisper-cpp` - Download whisper.cpp for the current platform\n- `npm run download:whisper-cpp:all` - Download whisper.cpp for all platforms\n- `npm run download:llama-server` - Download llama.cpp server for local LLM inference\n- `npm run download:llama-server:all` - Download llama.cpp server for all platforms\n- `npm run download:sherpa-onnx` - Download sherpa-onnx for Parakeet local transcription\n- `npm run download:sherpa-onnx:all` - Download sherpa-onnx for all platforms\n- `npm run compile:native` - Compile native helpers (Globe key listener and media remote for macOS, key listener and fast paste for Windows, fast paste for Linux, text monitor for auto-learn)\n- `npm run build` - Full build with signing (requires certificates)\n- `npm run build:mac` - macOS build with signing\n- `npm run build:win` - Windows build with signing\n- `npm run build:linux` - Linux build\n- `npm run pack` - Build without signing (for personal use)\n- `npm run dist` - Build and package with signing\n- `npm run lint` - Run ESLint\n- `npm run format` - Format code with Prettier\n- `npm run clean` - Clean build artifacts\n- `npm run preview` - Preview production build\n\n### Architecture\n\nThe app consists of two main windows:\n\n1. **Main Window**: Minimal overlay for dictation controls\n2. **Control Panel**: Full settings and history interface\n\nBoth use the same React codebase but render different components based on URL parameters.\n\n### Key Components\n\n- **main.js**: Electron main process, IPC handlers, database operations\n- **preload.js**: Secure bridge between main and renderer processes\n- **App.jsx**: Main dictation interface with recording controls\n- **ControlPanel.tsx**: Settings, history, notes, integrations, and model management\n- **AgentOverlay.tsx**: Agent mode chat overlay with streaming AI responses\n- **CommandSearch.tsx**: Cmd+K command palette for searching notes and transcripts\n- **IntegrationsView.tsx**: Google Calendar connection and meeting settings\n- **src\u002Fhelpers\u002Fwhisper.js**: whisper.cpp integration for local processing\n- **src\u002Fhelpers\u002FgoogleCalendarManager.js**: Calendar sync and event management\n- **src\u002Fhelpers\u002FmeetingDetectionEngine.js**: Smart meeting detection orchestrator\n- **src\u002Fhelpers\u002FaudioStorage.js**: Audio file retention and management\n- **src\u002Fhelpers\u002FmediaPlayer.js**: Cross-platform media pause\u002Fresume\n- **src\u002Fservices\u002FReasoningService.ts**: Multi-provider AI processing with streaming\n- **better-sqlite3**: Local database for transcriptions, notes, agents, and calendar data\n\n### Tailwind CSS v4 Setup\n\nThis project uses the latest Tailwind CSS v4 with:\n\n- CSS-first configuration using `@theme` directive\n- Vite plugin for optimal performance\n- Custom design tokens for consistent theming\n- Dark mode support with `@variant`\n\n## Building\n\nThe build process creates a single executable for your platform:\n\n```bash\n# Development build\nnpm run pack\n\n# Production builds\nnpm run dist           # Current platform\nnpm run build:mac      # macOS DMG + ZIP\nnpm run build:win      # Windows NSIS + Portable\nnpm run build:linux    # AppImage + DEB\n```\n\nNote: build\u002Fpack\u002Fdist scripts automatically download whisper.cpp, llama-server, and sherpa-onnx for the current platform. For multi-platform packaging from one host, run the `:all` variants first (`npm run download:whisper-cpp:all`, `npm run download:llama-server:all`, `npm run download:sherpa-onnx:all`).\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory (or use `npm run setup`):\n\n```env\n# OpenAI API Configuration (optional - only needed for cloud processing)\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Optional: Customize the Whisper model\nWHISPER_MODEL=whisper-1\n\n# Optional: Set language for better transcription accuracy\nLANGUAGE=\n\n# Optional: Anthropic API Configuration\nANTHROPIC_API_KEY=your_anthropic_api_key_here\n\n# Optional: Google Gemini API Configuration\nGEMINI_API_KEY=your_gemini_api_key_here\n\n# Optional: Groq API Configuration (ultra-fast inference)\nGROQ_API_KEY=your_groq_api_key_here\n\n# Optional: Mistral API Configuration (Voxtral transcription)\nMISTRAL_API_KEY=your_mistral_api_key_here\n\n# Optional: Debug mode\nDEBUG=false\n```\n\n### Local Whisper Setup\n\nFor local processing, OpenWhispr uses OpenAI's Whisper model via whisper.cpp - a high-performance C++ implementation:\n\n1. **Bundled Binary**: whisper.cpp is bundled with the app for all platforms\n2. **GGML Models**: Downloads optimized GGML models on first use to `~\u002F.cache\u002Fopenwhispr\u002Fwhisper-models\u002F`\n3. **No Dependencies**: No Python or other runtime required\n\n**System Fallback**: If the bundled binary fails, install via package manager:\n\n- macOS: `brew install whisper-cpp`\n- Linux: Build from source at https:\u002F\u002Fgithub.com\u002Fggml-org\u002Fwhisper.cpp\n\n**From Source**: When running locally (not a packaged build), download the binary with `npm run download:whisper-cpp` so `resources\u002Fbin\u002F` has your platform executable.\n\n**Requirements**:\n\n- Sufficient disk space for models (75MB - 3GB depending on model)\n\n**Upgrading from Python-based version**: If you previously used the Python-based Whisper, you'll need to re-download models in GGML format. You can safely delete the old Python environment (`~\u002F.openwhispr\u002Fpython\u002F`) and PyTorch models (`~\u002F.cache\u002Fwhisper\u002F`) to reclaim disk space.\n\n### Local Parakeet Setup (Alternative)\n\nOpenWhispr also supports NVIDIA Parakeet models via sherpa-onnx - a fast alternative to Whisper:\n\n1. **Bundled Binary**: sherpa-onnx is bundled with the app for all platforms\n2. **INT8 Quantized Models**: Efficient CPU inference\n3. **Models stored in**: `~\u002F.cache\u002Fopenwhispr\u002Fparakeet-models\u002F`\n\n**Available Models**:\n\n- `parakeet-tdt-0.6b-v3`: Multilingual (25 languages), ~680MB\n\n**When to use Parakeet vs Whisper**:\n\n- **Parakeet**: Best for speed-critical use cases or lower-end hardware\n- **Whisper**: Best for quality-critical use cases or when you need specific model sizes\n\n### Customization\n\n- **Hotkey**: Change in the Control Panel (default: backtick `) - fully customizable\n- **Panel Position**: Drag the dictation panel to any location on your screen`\n- **Processing Method**: Choose local or cloud in Control Panel\n- **Whisper Model**: Select quality vs speed in Control Panel\n- **UI Theme**: Edit CSS variables in `src\u002Findex.css`\n- **Window Size**: Adjust dimensions in `main.js`\n- **Database**: Transcriptions stored in user data directory\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature\u002Famazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature\u002Famazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Run `npm run lint` before committing\n- Follow the existing code style\n- Update documentation as needed\n- Test on your target platform before submitting\n\n## Security\n\nOpenWhispr is designed with privacy and security in mind:\n\n- **Local Processing Option**: Keep your voice data completely private\n- **No Analytics**: We don't collect any usage data or telemetry\n- **Open Source**: All code is available for review\n- **Secure Storage**: API keys are stored securely in your system's keychain\u002Fcredential manager\n- **Minimal Permissions**: Only requests necessary permissions (microphone, accessibility, screen recording for meetings)\n- **OAuth 2.0 PKCE**: Google Calendar uses secure PKCE flow — no client secrets stored\n- **Local-First Notes**: Notes are stored locally in SQLite; cloud sync is optional\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Microphone permissions**: Grant permissions in System Preferences\u002FSettings\n2. **Accessibility permissions (macOS)**: Required for automatic text pasting\n   - Go to System Settings → Privacy & Security → Accessibility\n   - Add OpenWhispr and enable the checkbox\n   - Use \"Fix Permission Issues\" in Control Panel if needed\n3. **API key errors** (cloud processing only): Ensure your OpenAI API key is valid and has credits\n   - Set key through Control Panel or .env file\n   - Check logs for \"OpenAI API Key present: Yes\u002FNo\"\n4. **Local Whisper issues**:\n   - whisper.cpp is bundled with the app\n   - If bundled binary fails, install via `brew install whisper-cpp` (macOS)\n   - Check available disk space for models\n5. **Global hotkey conflicts**: Change the hotkey in the Control Panel - any key can be used\n   - GNOME Wayland: Hotkeys are registered via gsettings; check Settings → Keyboard → Shortcuts for conflicts\n6. **Text not pasting**:\n   - macOS: Check accessibility permissions (System Settings → Privacy & Security → Accessibility)\n   - Linux X11: Install `xdotool`\n   - Linux Wayland: Install `wtype` or `ydotool` for paste simulation (ensure `ydotoold` daemon is running)\n   - All platforms: Text is always copied to clipboard - use Ctrl+V (Cmd+V on macOS) to paste manually\n7. **Panel position**: If the panel appears off-screen, restart the app to reset position\n8. **Meeting detection not working**:\n   - macOS: Grant screen recording permission in System Settings → Privacy & Security → Screen Recording\n   - Ensure Google Calendar is connected in Integrations\n   - Check that meeting detection is enabled in settings\n9. **Agent Mode issues**:\n   - Ensure Agent Mode is enabled in Settings → Agent Mode\n   - Verify you have a valid API key for your selected AI provider\n   - Check that the agent hotkey doesn't conflict with other shortcuts\n\n### Getting Help\n\n- Check the [Issues](https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues) page\n- Review the console logs for debugging information\n- For local processing: Ensure whisper.cpp is accessible and models are downloaded\n- For cloud processing: Verify your OpenAI API key and billing status\n- Check the Control Panel for system status and diagnostics\n\n### Performance Tips\n\n- **Local Processing**: Use \"base\" model for best balance of speed and accuracy\n- **Cloud Processing**: Generally faster but requires internet connection\n- **Model Selection**: tiny (fastest) → base (recommended) → small → medium → large (best quality)\n- **Permissions**: Ensure all required permissions are granted for smooth operation\n\n## FAQ\n\n**Q: Is OpenWhispr really free?**\nA: Yes! OpenWhispr is open source and free to use. The free plan includes 2,000 words\u002Fweek of cloud transcription, and local processing is completely free with no limits. Paid plans start from as little as $8\u002Fmonth.\n\n**Q: Which processing method should I use?**\nA: Use local processing for privacy and offline use. Use cloud processing for speed and convenience.\n\n**Q: Can I use this commercially?**\nA: Yes! The MIT license allows commercial use.\n\n**Q: How do I change the hotkey?**\nA: Open the Control Panel (right-click tray icon) and go to Settings. You can set any key as your hotkey.\n\n**Q: Is my data secure?**\nA: With local processing, your audio never leaves your device. With cloud processing, audio is sent to OpenAI's servers (see their privacy policy).\n\n**Q: What languages are supported?**\nA: OpenWhispr supports 58 languages including English, Spanish, French, German, Chinese, Japanese, and more. Set your preferred language in the .env file or use auto-detect.\n\n**Q: What is Agent Mode?**\nA: Agent Mode opens a chat overlay where you can have interactive AI conversations using voice. It supports streaming responses from all providers (OpenAI, Anthropic, Gemini, Groq, local) and saves conversation history.\n\n**Q: How does meeting transcription work?**\nA: Connect your Google Calendar in Integrations. When a meeting starts (Zoom, Teams, FaceTime), OpenWhispr detects it and offers to record. Audio is transcribed in real-time via OpenAI Realtime API. On macOS, screen recording permission is required to capture meeting audio.\n\n**Q: Where are my notes stored?**\nA: Notes are stored locally in SQLite with optional cloud sync. They support full-text search (FTS5), folder organization, and AI-powered enhancement actions.\n\n**Q: Does OpenWhispr require Input Monitoring on macOS?**\nA: No. As of v1.6.0, OpenWhispr uses NSEvent monitors instead of CGEvent taps, eliminating the Input Monitoring permission requirement. Only Microphone and Accessibility permissions are needed (plus Screen Recording for meeting features).\n\n## Project Status\n\nOpenWhispr is actively maintained and ready for production use. Current version: 1.6.7\n\n- ✅ Core dictation with local and cloud processing\n- ✅ Cross-platform support (macOS, Windows, Linux)\n- ✅ OpenWhispr Cloud with account system, usage tracking, and Stripe billing\n- ✅ Multi-provider AI (OpenAI, Anthropic, Gemini, Groq, Mistral, Local)\n- ✅ Agent Mode with streaming chat overlay and conversation history\n- ✅ Google Calendar integration with automatic meeting detection\n- ✅ Live meeting transcription via OpenAI Realtime API\n- ✅ Notes system with FTS5 search, cloud sync, folders, and AI actions\n- ✅ Audio retention with playback and retry for failed transcriptions\n- ✅ Cmd+K command search across notes and transcripts\n- ✅ Auto-pause media playback during dictation\n- ✅ Custom dictionary with auto-learn correction monitoring\n- ✅ NVIDIA Parakeet support via sherpa-onnx\n- ✅ Compound hotkeys and Windows Push-to-Talk\n- ✅ GNOME Wayland and Hyprland native global shortcuts\n- ✅ Referral program with shareable invite cards\n- ✅ Dedicated meeting mode hotkey\n- ✅ CodeQL static analysis and Dependabot dependency updates\n\n## Acknowledgments\n\n- **[OpenAI Whisper](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fwhisper)** - The speech recognition model that powers both local and cloud transcription\n- **[whisper.cpp](https:\u002F\u002Fgithub.com\u002Fggerganov\u002Fwhisper.cpp)** - High-performance C++ implementation of Whisper for local processing\n- **[NVIDIA Parakeet](https:\u002F\u002Fhuggingface.co\u002Fnvidia\u002Fparakeet-tdt-0.6b-v3)** - Fast ASR model for efficient local transcription\n- **[sherpa-onnx](https:\u002F\u002Fgithub.com\u002Fk2-fsa\u002Fsherpa-onnx)** - Cross-platform ONNX runtime for Parakeet model inference\n- **[Electron](https:\u002F\u002Fwww.electronjs.org\u002F)** - Cross-platform desktop application framework\n- **[React](https:\u002F\u002Freact.dev\u002F)** - UI component library\n- **[shadcn\u002Fui](https:\u002F\u002Fui.shadcn.com\u002F)** - Beautiful UI components built on Radix primitives\n- **[Hugging Face](https:\u002F\u002Fhuggingface.co\u002F)** - Model hosting platform for our local speech recognition and language models\n- **[llama.cpp](https:\u002F\u002Fgithub.com\u002Fggerganov\u002Fllama.cpp)** - Local LLM inference for AI-powered text processing\n","\u003Cp align=\"center\">\n  \u003Cimg src=\"src\u002Fassets\u002Flogo.svg\" alt=\"OpenWhispr\" width=\"120\" \u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">OpenWhispr\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002FOpenWhispr\u002Fopenwhispr?style=flat\" alt=\"许可证\" \u002F>\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F平台-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey?style=flat\" alt=\"平台\" \u002F>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Freleases\u002Flatest\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FOpenWhispr\u002Fopenwhispr?style=flat&sort=semver\" alt=\"GitHub 发布\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002FOpenWhispr\u002Fopenwhispr\u002Ftotal?style=flat&color=blue\" alt=\"下载量\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FOpenWhispr\u002Fopenwhispr?style=flat\" alt=\"GitHub 星标\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">一款结合AI智能体、会议转录、笔记记录以及本地\u002F云端语音识别功能的语音转文字听写与效率提升应用。\u003Cbr\u002F>以隐私为先，跨平台可用。\u003C\u002Fp>\n\n## 星标历史\n\n[![星标历史图](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FOpenWhispr_openwhispr_readme_66b78180373b.png)](https:\u002F\u002Fwww.star-history.com\u002F#OpenWhispr\u002Fopenwhispr?type=date&legend=top-left)\n\n## 许可证\n\n本项目采用 MIT 许可证授权——详情请参阅 [LICENSE](LICENSE) 文件。这意味着您可以自由地将此软件用于个人或商业用途，并对其进行修改和分发。\n\n## 功能特性\n\n### 听写与转录\n\n- 🎤 **全局热键**：可在任意位置通过自定义热键启动或停止听写（默认为反引号 `）\n- ⚡ **自动粘贴**：转录文本会自动粘贴到光标位置（可切换关闭）\n- 🔒 **隐私优先**：本地处理确保您的语音数据完全私密\n- ⚡ **NVIDIA Parakeet**：通过 sherpa-onnx 实现快速本地转录（多语言支持，涵盖25种语言）\n- 🔧 **模型管理**：下载并管理本地 Whisper 模型（tiny、base、small、medium、large、turbo）\n- 📖 **自定义词典**：添加词汇、人名和技术术语以提高转录准确度；具备自动学习功能，能检测您的修正并自动更新词典\n- 🗄️ **转录历史**：SQLite 数据库本地存储所有转录内容，支持音频保留与重试\n- 🎵 **媒体自动暂停**：听写时自动暂停媒体播放（如 Spotify、Apple Music 等），结束后恢复播放\n\n### AI 智能体模式\n\n- 🤖 **智能体悬浮窗**：玻璃质感聊天悬浮窗，支持实时 AI 流式交互、窗口大小调整及对话历史记录\n- 🎯 **自定义智能体名称**：为您的 AI 助手命名——只需说“Hey [AgentName]”即可下达指令\n- 🧠 **多提供商 AI 支持**：\n  - **OpenAI**：GPT-5、GPT-4.1、o-series 推理模型\n  - **Anthropic**：Claude Opus 4.6、Claude Sonnet 4.6\n  - **Google**：Gemini 3.1 Pro、Gemini 3 Flash、Gemini 2.5 Flash Lite\n  - **Groq**：使用 Llama 和 Mixtral 模型实现超高速推理\n  - **本地**：通过 llama.cpp 支持 Qwen、LLaMA、Mistral、Gemma 等模型\n- 🛠️ **智能体工具调用**：提供搜索、创建和更新笔记等代理工具——本地模型支持 RAG 上下文注入\n- 🤖 **AI 动作**：对笔记应用 AI 驱动的操作，支持自定义处理模板\n\n### 会议转录\n\n- 📅 **Google 日历集成**：连接多个 Google 账户，在侧边栏查看即将举行的会议，并接收自动检测提示\n- 🎙️ **实时会议转录**：通过 OpenAI Realtime API 实时录制并转录会议内容，支持自动检测会议场景（Zoom、Teams、FaceTime 等）\n- ⚡ **BYOK WebSocket 流式传输**：不仅适用于会议转录，标准听写模式也可使用实时 OpenAI Realtime API 流式传输——统一的转录流路径\n- ⌨️ **会议专用热键**：独立于常规听写模式，专为会议转录设计的热键\n- 🔍 **智能检测**：结合进程监控、持续音频检测和日历信息，自动识别会议场景\n\n### 笔记功能\n\n- 📝 **笔记系统**：创建、编辑和整理笔记，支持文件夹管理、音频上传及实时听写\n- 🔎 **全文搜索**：基于 FTS5 的搜索功能，可通过 Cmd+K 快捷键访问命令面板，实现全笔记内容搜索\n- 🧠 **本地语义搜索**：始终运行的 Qdrant 向量数据库，配合 MiniLM 嵌入技术，可在离线状态下进行基于语义的笔记搜索\n- ☁️ **云同步**：本地优先存储，同时支持云端备份与语义搜索\n- 💬 **嵌入式聊天**：笔记编辑器中内置聊天面板，支持浮动与侧边栏两种模式\n- 📁 **文件夹组织**：通过拖放方式将笔记归类到自定义文件夹中\n- 💾 **导出笔记为文件**：可将笔记以 Markdown 格式导出至本地文件系统，保持与文件夹结构一致\n\n### 云端与账户\n\n- ☁️ **OpenWhispr 云服务**：登录后即可立即开始转录，无需 API 密钥，提供免费版和专业版两种方案\n- 🔐 **账户体系**：支持 Google OAuth 以及邮箱\u002F密码登录，并需完成邮箱验证\n- 💳 **订阅管理**：免费版（每周2,000字）、专业版（无限制），提供7天免费试用\n- 🔗 **推荐计划**：邀请好友可获得免费的专业版使用月数，分享专属推荐卡片即可参与\n\n### 平台与界面\n\n- 🌐 **跨平台支持**：适用于 macOS、Windows 和 Linux\n- 🎨 **现代 UI**：基于 React 19、TypeScript 和 Tailwind CSS v4 构建\n- 📱 **响应式设置**：设置对话框可根据窗口宽度调整布局，提供可折叠图标侧边栏和堆叠式布局\n- 🖱️ **可拖动界面**：听写面板可在屏幕上任意位置移动，支持自定义起始位置\n- 🌐 **Globe 键切换（macOS）**：可选 Fn\u002FGlobe 键监听功能，作为硬件级别的听写触发机制——无需输入监控权限\n- ⌨️ **复合热键**：支持多键组合，例如 `Cmd+Shift+K`\n- 🎙️ **Windows 端推挽式通话**：原生低级键盘钩子实现真正的推挽式通话，同时支持复合热键\n- 🐧 **GNOME Wayland 支持**：通过 D-Bus 提供原生全局快捷键，适用于 GNOME Wayland 用户\n- 🐧 **KDE Wayland 支持**：通过 D-Bus 提供原生全局快捷键，适用于 KDE Plasma on Wayland\n- 🐧 **Hyprland Wayland 支持**：通过 `hyprctl` 键位绑定 + D-Bus 提供原生全局快捷键，适用于 Hyprland 用户\n- 🖥️ **多显示器支持**：浮动听写图标会跟随光标在不同显示器间移动\n- 🧹 **模型清理**：一键清除缓存模型，并配备卸载钩子以保持磁盘整洁\n\n## 系统要求\n\n- **Node.js 22+** 和 npm（从 [nodejs.org](https:\u002F\u002Fnodejs.org\u002F) 下载）\n- **macOS 12+**、**Windows 10+** 或 **Linux**\n- 在 macOS 上，若需 Globe 键支持，必须安装 Xcode 命令行工具（运行 `xcode-select --install`），以便捆绑的 Swift 辅助程序能够正常运行\n\n## 快速入门\n\n### 用于个人使用（推荐）\n\n1. **克隆仓库**：\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr.git\n   cd openwhispr\n   ```\n\n2. **安装依赖**：\n\n   ```bash\n   npm install\n   ```\n\n3. **可选：设置 API 密钥**（仅在使用云端处理时需要）：\n\n   **方法 A - 环境文件**：\n\n   ```bash\n   cp .env.example .env\n   # 编辑 .env 文件并添加您的 API 密钥：\n   # OPENAI_API_KEY=your_openai_key\n   # ANTHROPIC_API_KEY=your_anthropic_key\n   # GEMINI_API_KEY=your_gemini_key\n   # GROQ_API_KEY=your_groq_key\n   # MISTRAL_API_KEY=your_mistral_key\n   ```\n\n   **方法 B - 应用内配置**：\n   - 运行应用并通过控制面板配置 API 密钥。\n   - 密钥会自动保存，并在应用重启后仍然有效。\n\n4. **构建应用程序**：\n\n   ```bash\n   npm run build\n   ```\n\n5. **运行应用程序**：\n\n   ```bash\n   npm run dev  # 开发模式，支持热重载\n   # 或者\n   npm start    # 生产模式\n   ```\n\n6. **可选：从源代码本地下载 Whisper**（仅在需要本地处理时才需执行）：\n   ```bash\n   npm run download:whisper-cpp\n   ```\n   此命令会将适用于您当前操作系统的 whisper.cpp 二进制文件下载到 `resources\u002Fbin\u002F` 目录下。\n\n### 为个人使用构建（可选）\n\n如果您希望构建一个独立的应用程序供个人使用：\n\n```bash\n# 不进行代码签名的构建（无需证书）\nnpm run pack\n\n# 未签名的应用程序将位于：dist\u002Fmac-arm64\u002FOpenWhispr.app（macOS）\n# 或 dist\u002Fwin-unpacked\u002FOpenWhispr.exe（Windows）\n# 或 dist\u002Flinux-unpacked\u002Fopen-whispr（Linux）\n```\n\n**注意**：在 macOS 上，首次打开未签名的应用程序时可能会出现安全警告。请右键单击并选择“打开”以绕过该警告。\n\n#### Windows\n\n**原生粘贴二进制文件 (`windows-fast-paste`)**：\n\nOpenWhispr 在 Windows 上提供了一个原生 C 语言编写的二进制文件，用于通过 Win32 的 `SendInput` API 实现文本粘贴功能。这是主要的粘贴机制——`nircmd` 和 PowerShell 只是在原生二进制失败时作为备用方案。\n\n工作原理如下：\n\n- **普通应用程序**：通过 `SendInput` 模拟 `Ctrl+V`，使用虚拟键码组合（`VK_CONTROL` + `V`）。\n- **终端模拟器**：检测前台窗口的类名，并模拟 `Ctrl+Shift+V`。\n- **终端检测**：识别 Windows Terminal、cmd.exe、PowerShell、mintty（Git Bash）、PuTTY、Alacritty、WezTerm、kitty、Hyper、MobaXterm 以及 ConEmu\u002FCmder 等终端。\n- **仅检测模式**：支持 `--detect-only` 标志，用于报告前台窗口的类名而不发送按键。\n\n编译过程（由构建系统自动完成）：\n\n```bash\n# MSVC\ncl \u002FO2 windows-fast-paste.c \u002FFe:windows-fast-paste.exe user32.lib\n\n# MinGW\ngcc -O2 windows-fast-paste.c -o windows-fast-paste.exe -luser32\n```\n\n构建脚本（`scripts\u002Fbuild-windows-fast-paste.js`）首先尝试从 GitHub 发布页面下载预编译的二进制文件。如果无法获取，则使用 MSVC、MinGW-w64 或 Clang 从源代码编译。若以上两种方式均不可行，则回退到 `nircmd` 或 PowerShell 的 `SendKeys` 方法。\n\n> ℹ️ **注**：`CASCADIA_HOSTING_WINDOW_CLASS` 覆盖了所有在 Windows Terminal 内运行的 Shell（PowerShell、CMD、WSL 等），因此大多数现代 Windows 终端的使用场景都可通过这一单一的类名条目来覆盖。\n\n#### Linux（多种软件包格式）\n\nOpenWhispr 现在支持多种 Linux 软件包格式，以实现最大的兼容性：\n\n**可用格式**：\n\n- `.deb` - Debian、Ubuntu、Linux Mint、Pop!\\_OS\n- `.rpm` - Fedora、Red Hat、CentOS、openSUSE\n- `.tar.gz` - 通用归档文件（适用于任何发行版）\n- `.flatpak` - 沙盒化的跨发行版软件包\n- `AppImage` - 可移植的单文件可执行程序\n\n**构建 Linux 软件包**：\n\n```bash\n# 构建默认的 Linux 软件包格式（AppImage、deb、rpm、tar.gz）\nnpm run build:linux\n\n# 软件包位于 dist\u002F 目录下：\n# - OpenWhispr-x.x.x-linux-x64.AppImage\n# - OpenWhispr-x.x.x-linux-x64.deb\n# - OpenWhispr-x.x.x-linux-x64.rpm\n# - OpenWhispr-x.x.x-linux-x64.tar.gz\n```\n\n**可选：构建 Flatpak**（需要额外设置）：\n\n```bash\n# 安装 Flatpak 构建工具\nsudo apt install flatpak flatpak-builder  # Debian\u002FUbuntu\n# 或者\nsudo dnf install flatpak flatpak-builder  # Fedora\u002FRHEL\n\n# 添加 Flathub 仓库并安装运行时\nflatpak remote-add --user --if-not-exists flathub https:\u002F\u002Fflathub.org\u002Frepo\u002Fflathub.flatpakrepo\nflatpak install --user -y flathub org.freedesktop.Platform\u002F\u002F24.08 org.freedesktop.Sdk\u002F\u002F24.08\n\n# 将 \"flatpak\" 添加到 electron-builder.json 中的 linux.target，然后进行构建\nnpm run build:linux\n```\n\n**安装示例**：\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install .\u002Fdist\u002FOpenWhispr-*-linux-x64.deb\n\n# Fedora\u002FRHEL\nsudo dnf install .\u002Fdist\u002FOpenWhispr-*-linux-x64.rpm\n\n# 通用 tar.gz 包（无需 root 权限）\ntar -xzf dist\u002FOpenWhispr-*-linux-x64.tar.gz\ncd OpenWhispr-*\u002F\n.\u002Fopenwhispr\n\n# Flatpak\nflatpak install --user .\u002Fdist\u002FOpenWhispr-*-linux-x64.flatpak\n\n# AppImage（现有方法）\nchmod +x dist\u002FOpenWhispr-*.AppImage\n.\u002Fdist\u002FOpenWhispr-*.AppImage\n```\n\n**原生粘贴二进制文件 (`linux-fast-paste`)**：\n\nOpenWhispr 提供了一个原生 C 语言编写的二进制文件，用于在 Linux 上实现文本粘贴功能，该文件会在构建时自动编译。这是主要的粘贴机制——外部工具如 `xdotool` 和 `wtype` 仅在原生二进制失败时才会被用作备份。\n\n工作原理如下：\n\n- **X11**：使用 XTest 扩展直接合成 `Ctrl+V`（或在终端中合成 `Ctrl+Shift+V`），除了 X11 之外没有任何其他依赖。\n- **Wayland**：利用 Linux 的 `uinput` 子系统创建虚拟键盘并注入按键。如果 `uinput` 不可用，则会通过 XWayland 回退到 XTest。\n- **终端检测**：能够识别 20 多种终端模拟器（kitty、alacritty、gnome-terminal、wezterm、ghostty 等），并在终端中自动使用 `Ctrl+Shift+V` 而不是 `Ctrl+V`。\n- **窗口目标定位**：可以通过 `--window` 参数指定特定的窗口 ID，以确保按键输入到达正确的应用程序。\n\n编译所需的依赖项：\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install gcc libx11-dev libxtst-dev\n\n# Fedora\u002FRHEL\nsudo dnf install gcc libX11-devel libXtst-devel\n\n# Arch\nsudo pacman -S gcc libx11 libxtst\n```\n\n构建脚本（`scripts\u002Fbuild-linux-fast-paste.js`）会在执行 `npm run compile:linux-paste` 时运行，并完成以下步骤：\n\n1. 检测是否可以找到 `linux\u002Fuinput.h` 头文件；\n2. 如果可以，则编译时加入 `-DHAVE_UINPUT` 标志（启用 Wayland 的 uinput 支持）；\n3. 缓存生成的二进制文件，除非源代码或编译选项发生变化，否则不会重新编译；\n4. 如果编译失败，会优雅地回退到系统自带的工具。\n\n如果原生二进制文件不可用，OpenWhispr 会按照以下顺序回退到外部粘贴工具：\n\n**自动粘贴的备用依赖项**：\n\n当原生粘贴二进制文件不可用或失效时，将按以下顺序使用这些工具作为备用方案：\n\n**X11（传统 Linux 桌面环境）**：\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install xdotool\n\n# Fedora\u002FRHEL\nsudo dnf install xdotool\n\n# Arch\nsudo pacman -S xdotool\n```\n\n**Wayland（现代 Linux 桌面）**：\n\n**推荐**：安装 `wl-clipboard` 以实现 Wayland 应用程序之间可靠的剪贴板共享：\n\n```bash\nsudo apt install wl-clipboard    # Debian\u002FUbuntu\nsudo dnf install wl-clipboard    # Fedora\u002FRHEL\nsudo pacman -S wl-clipboard      # Arch\n```\n\n从以下粘贴工具中**选择一个**：\n\n**选项 1：wtype**（需要虚拟键盘协议支持）\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install wtype\n\n# Fedora\u002FRHEL\nsudo dnf install wtype\n\n# Arch\nsudo pacman -S wtype\n```\n\n**选项 2：ydotool**（适用于更多窗口管理器，需运行守护进程）\n\n```bash\n# Debian\u002FUbuntu\nsudo apt install ydotool\nsudo systemctl enable --now ydotoold\n\n# Fedora\u002FRHEL\nsudo dnf install ydotool\nsudo systemctl enable --now ydotoold\n\n# Arch\nsudo pacman -S ydotool\nsudo systemctl enable --now ydotoold\n```\n\n**终端检测**（可选——适用于 KDE Wayland 用户）：\n\n```bash\n# 在 KDE Wayland 上，kdotool 可启用自动终端检测，\n# 从而使用 Ctrl+Shift+V 而不是 Ctrl+V 进行粘贴。\nsudo apt install kdotool  # Debian\u002FUbuntu\nsudo dnf install kdotool  # Fedora\u002FRHEL\nsudo pacman -S kdotool    # Arch\n```\n\n> ℹ️ **注意**：OpenWhispr 会自动按以下顺序尝试粘贴方法：原生 `linux-fast-paste` 二进制文件（XTest 或 uinput）→ `wtype` → `ydotool` → `xdotool`（用于 XWayland 应用程序）。如果所有粘贴方法均无效，文本仍会被复制到剪贴板——您只需手动使用 Ctrl+V 进行粘贴。\n\n> ⚠️ **ydotool 要求**：`ydotoold` 守护进程必须运行才能使 ydotool 正常工作。您可以使用 `sudo ydotoold &` 手动启动，或按照上述说明启用 systemd 服务。\n\n**GNOME Wayland 全局快捷键**：\n\n在 GNOME Wayland 上，由于 Wayland 的安全模型限制，Electron 的标准全局快捷键无法正常工作。OpenWhispr 会自动通过 D-Bus 和 gsettings 使用 GNOME 原生键盘快捷键：\n\n- 快捷键将注册为 GNOME 自定义快捷键（可在“设置”→“键盘”→“快捷键”中查看）。\n- 默认快捷键为 `Alt+R`（GNOME Wayland 不支持反引号）。\n- **GNOME Wayland 上不支持按住说话模式**（仅支持点击说话）。\n- 如果 GNOME 集成失败，则回退到 X11\u002FXWayland 快捷键。\n- 无需额外依赖——使用 `dbus-next` npm 包。\n\n> ℹ️ **GNOME Wayland 局限性**：GNOME 系统快捷键仅触发一次切换事件（无法检测按键释放），因此按住说话模式无法实现。该应用会在 GNOME Wayland 上自动切换为点击说话模式。\n\n> 🔒 **Flatpak 安全性**：Flatpak 软件包包含沙盒机制，并明确授予了麦克风、剪贴板和文件访问权限。完整权限列表请参阅 [electron-builder.json](electron-builder.json)。\n\n### 分发版构建\n\n对于需要分发签名构建的维护者：\n\n```bash\n# 需要代码签名证书和公证设置\nnpm run build:mac    # macOS（需要 Apple 开发者账号）\nnpm run build:win    # Windows（需要代码签名证书）\nnpm run build:linux  # Linux\n```\n\n### 首次设置\n\n1. **选择处理方式**：\n   - **OpenWhispr 云**：登录即可享受即时云端转录服务，提供免费和 Pro 版本。\n   - **自备密钥**：使用您自己的 OpenAI\u002FGroq\u002FAssemblyAI API 密钥。\n   - **本地处理**：下载 Whisper 或 Parakeet 模型，实现完全私密的转录。\n\n2. **授予权限**：\n   - **麦克风访问权限**：录制语音所必需。\n   - **辅助功能权限**：自动粘贴文本所必需（macOS）。\n   - **屏幕录制权限**（可选，macOS）：录制会议音频所必需——如果您希望使用会议功能，将在引导过程中提示您。\n\n3. **命名您的代理**：为您的 AI 助手取一个个性化名称（例如，“助理”、“贾维斯”、“亚历克斯”）。\n   - 使交互更加自然和对话化。\n   - 有助于区分发出指令与普通听写。\n   - 您可以随时在设置中更改名称。\n\n4. **配置全局快捷键**：默认为反引号 (`)，但可自定义。\n\n## 使用方法\n\n### 基本听写\n\n1. **启动应用**——屏幕上会出现一个小巧可拖动的面板。\n2. **按下快捷键**（默认：反引号 `）——开始听写（面板显示录音动画）。\n3. **再次按下快捷键**——停止听写并开始转录（面板显示处理动画）。\n4. **文本出现**——转录后的文本会自动粘贴到光标位置。\n5. **拖动面板**——单击并拖动可将听写面板移动到屏幕上的任意位置。\n\n### 控制面板\n\n- **访问方式**：右键单击托盘图标（macOS）或通过系统菜单。\n- **配置**：选择本地处理或云端处理。\n- **历史记录**：查看、复制和删除过去的转录内容——支持音频播放及失败转录的重试。\n- **笔记**：创建、编辑和整理笔记，支持文件夹、AI 动作和全文搜索。\n- **集成**：连接 Google 日历账户，实现会议检测与转录。\n- **模型**：下载并管理本地的 Whisper 和 Parakeet 模型。\n- **存储清理**：移除缓存中的已下载模型以释放空间。\n- **设置**：配置 API 密钥、自定义快捷键、管理权限以及设置代理模式。\n- **Cmd+K 搜索**：可在应用内的任何位置快速搜索笔记和转录内容。\n\n### 卸载与缓存清理\n\n- **应用内操作**：使用“设置→常规→本地模型存储→移除已下载模型”来清除 `~\u002F.cache\u002Fopenwhispr\u002F`（或 Windows 上的 `%USERPROFILE%\\.cache\\openwhispr\\`）中的 Whisper 和 Parakeet 缓存模型。\n- **音频文件**：保留的音频文件存储在应用数据目录中，会在 30 天后自动清理。如有需要，可通过设置手动清理。\n- **Windows 卸载**：NSIS 卸载程序会自动删除缓存目录。\n- **Linux 软件包**：`deb`\u002F`rpm` 的卸载后脚本也会移除缓存模型。\n- **macOS**：如果您手动卸载，可根据需要删除 `~\u002FLibrary\u002FCaches` 或 `~\u002F.cache\u002Fopenwhispr\u002F`。\n\n### 代理命名与 AI 处理\n\n在设置阶段为您的代理命名后，您可以使用多种 AI 提供商与其互动：\n\n**🎯 代理指令**（用于 AI 辅助）：\n\n- “嘿[代理名]，把这个说得更专业点”\n- “嘿[代理名]，把它格式化成列表”\n- “嘿[代理名]，写一封感谢邮件”\n- “嘿[代理名]，把这个转换成要点”\n\n**🤖 AI 提供商选项**：\n\n- **OpenAI**：GPT-5、GPT-4.1、o 系列推理模型。\n- **Anthropic**：Claude Opus 4.6、Sonnet 4.6、Haiku 4.5。\n- **Google**：Gemini 3.1 Pro、Gemini 3 Flash、Gemini 2.5 Flash Lite。\n- **Groq**：超快速 Llama 和 Mixtral 推理。\n- **本地**：Qwen、LLaMA、Mistral、Gemma 模型，通过 llama.cpp 提供。\n\n**📝 普通听写**（用于常规文本）：\n\n- “这只是我想转录的普通文本”\n- “会议记录：约翰提到了季度报告”\n- “亲爱的莎拉，感谢你的帮助”\n\nAI 会自动检测您是在下达指令还是进行普通听写，并在最终输出中移除代理名称引用。\n\n### 自定义词典\n\n提升特定单词、姓名或技术术语的转录准确度：\n\n1. **访问设置**：打开控制面板 → 设置 → 自定义词典\n2. **添加词汇**：输入经常被误识别的单词、姓名或短语\n3. **工作原理**：这些词汇会作为上下文提示提供给语音识别模型\n\n**建议添加的词汇示例**：\n\n- 不常见的姓名（如“Sergey”、“Xanthe”）\n- 技术术语（如“Kubernetes”、“OAuth”）\n- 品牌名称（如“OpenWhispr”、“whisper.cpp”）\n- 领域特定术语（如“摊销”、“聚合酶”）\n\n### 代理模式\n\n代理模式会打开一个可调整大小的玻璃拟物风格聊天浮层，用于交互式AI对话：\n\n1. **启用**：前往设置 → 代理模式，并将其开启\n2. **设置快捷键**：分配一个专用快捷键以打开代理浮层\n3. **聊天**：按下快捷键打开浮层，口述你的消息，并接收流式AI回复\n4. **自定义**：设置自定义系统提示，选择你喜欢的AI提供商和模型\n5. **历史记录**：所有对话都会被保存，并可随时继续\n\n### 会议转录\n\n通过Google Calendar集成自动检测并转录会议内容：\n\n1. **连接日历**：前往集成 → Google Calendar并登录\n2. **授予屏幕录制权限**（macOS）：需要此权限才能捕获会议音频\n3. **自动检测**：当会议开始时（Zoom、Teams、FaceTime），会出现通知询问是否要录制\n4. **实时转录**：会议音频将通过OpenAI Realtime API进行实时转录\n5. **回顾**：会议转录内容会被保存为笔记，供日后查看和AI增强\n\n### 处理选项\n\n- **OpenWhispr云**：\n  - 使用Google或邮箱登录——无需API密钥\n  - 免费计划：每周2,000字，新账户可享受7天Pro试用期\n  - Pro计划：无限转录量\n- **自带密钥（BYOK）**：\n  - 使用你自己的来自OpenAI、Groq、Mistral、AssemblyAI的API密钥，或自定义端点\n  - 完全掌控提供商和模型的选择\n- **本地处理**：\n  - 通过控制面板安装Whisper或NVIDIA Parakeet\n  - 下载模型：tiny（最快）、base（推荐）、small、medium、large（最佳质量）\n  - 完全隐私——音频绝不会离开你的设备\n\n## 项目结构\n\n```\nopen-whispr\u002F\n├── main.js              # Electron主进程及IPC处理器\n├── preload.js           # Electron预加载脚本及API桥接\n├── setup.js             # 首次设置脚本\n├── package.json         # 依赖项和脚本\n├── env.example          # 环境变量模板\n├── CHANGELOG.md         # 项目变更日志\n├── src\u002F\n│   ├── App.jsx          # 主听写界面\n│   ├── main.jsx         # React入口文件\n│   ├── index.html       # Vite HTML模板\n│   ├── index.css        # Tailwind CSS v4配置\n│   ├── vite.config.js   # Vite配置\n│   ├── components\u002F\n│   │   ├── ControlPanel.tsx     # 设置与历史记录UI\n│   │   ├── OnboardingFlow.tsx   # 首次设置向导\n│   │   ├── SettingsPage.tsx     # 设置界面\n│   │   ├── AgentOverlay.tsx     # 代理模式聊天浮层\n│   │   ├── CommandSearch.tsx    # Cmd+K命令面板\n│   │   ├── IntegrationsView.tsx # Google Calendar及其他集成\n│   │   ├── UpcomingMeetings.tsx # 侧边栏会议列表\n│   │   ├── agent\u002F               # 代理模式组件\n│   │   │   ├── AgentChat.tsx\n│   │   │   ├── AgentInput.tsx\n│   │   │   ├── AgentMessage.tsx\n│   │   │   └── AgentTitleBar.tsx\n│   │   ├── notes\u002F               # 笔记系统组件\n│   │   │   ├── NoteEditor.tsx\n│   │   │   ├── ActionPicker.tsx\n│   │   │   ├── ActionManagerDialog.tsx\n│   │   │   └……\n│   │   ├── settings\u002F            # 设置子组件\n│   │   │   └── AgentModeSettings.tsx\n│   │   ├── ui\u002F                  # shadcn\u002Fui组件\n│   │   └── lib\u002F\n│   │       └── utils.ts         # 工具函数\n│   ├── config\u002F\n│   │   └── prompts.ts           # 中央化AI提示定义\n│   ├── services\u002F\n│   │   └── ReasoningService.ts  # 多提供商流式AI处理\n│   ├── hooks\u002F\n│   │   ├── useMeetingTranscription.ts  # 会议音频捕获\n│   │   ├── useUpcomingEvents.ts        # 日历事件获取\n│   │   ├── useScreenRecordingPermission.ts  # macOS权限\n│   │   └……\n│   ├── helpers\u002F\n│   │   ├── googleCalendarManager.js    # 日历同步及事件管理\n│   │   ├── googleCalendarOAuth.js      # OAuth 2.0 PKCE流程\n│   │   ├── meetingDetectionEngine.js   # 智能会议检测\n│   │   ├── audioStorage.js             # 音频文件存储\n│   │   ├── mediaPlayer.js             # 跨平台媒体控制\n│   │   └……\n│   ├── utils\u002F\n│   │   └── agentName.ts         # 代理名称管理工具\n│   └── components.json          # shadcn\u002Fui配置\n├── resources\u002F\n│   └── bin\u002F                     # 原生二进制文件（whisper-cpp、sherpa-onnx等）\n└── assets\u002F                      # 应用图标及资源\n```\n\n## 技术栈\n\n- **前端**：React 19、TypeScript、Tailwind CSS v4\n- **构建工具**：Vite搭配优化后的Tailwind插件\n- **桌面应用**：Electron 39，支持上下文隔离\n- **UI组件**：shadcn\u002Fui结合Radix原生组件\n- **数据库**：better-sqlite3配合FTS5用于本地存储（转录、笔记、代理、日历）\n- **语音转文字**：本地使用OpenAI Whisper（whisper.cpp）+ NVIDIA Parakeet（sherpa-onnx），云端则使用OpenAI API\n- **实时转录**：通过WebSocket的OpenAI Realtime API实现会议转录\n- **AI处理**：多提供商流式处理（OpenAI、Anthropic、Gemini、Groq、本地llama.cpp）\n- **日历集成**：Google Calendar API配合OAuth 2.0 PKCE\n- **图标**：Lucide React用于统一图标设计\n\n## 开发\n\n### 脚本\n\n- `npm run dev` - 启动开发模式，支持热重载\n- `npm run start` - 启动生产构建\n- `npm run setup` - 首次设置（创建 `.env` 文件）\n- `npm run build:renderer` - 仅构建 React 应用\n- `npm run download:whisper-cpp` - 下载适用于当前平台的 whisper.cpp\n- `npm run download:whisper-cpp:all` - 下载适用于所有平台的 whisper.cpp\n- `npm run download:llama-server` - 下载用于本地 LLM 推理的 llama.cpp 服务器\n- `npm run download:llama-server:all` - 下载适用于所有平台的 llama.cpp 服务器\n- `npm run download:sherpa-onnx` - 下载用于 Parakeet 本地转录的 sherpa-onnx\n- `npm run download:sherpa-onnx:all` - 下载适用于所有平台的 sherpa-onnx\n- `npm run compile:native` - 编译原生辅助工具（macOS 上的 Globe 键盘监听器和媒体遥控器，Windows 上的键盘监听器和快速粘贴功能，Linux 上的快速粘贴功能，以及用于自动学习的文本监控工具）\n- `npm run build` - 完整构建并签名（需要证书）\n- `npm run build:mac` - macOS 构建并签名\n- `npm run build:win` - Windows 构建并签名\n- `npm run build:linux` - Linux 构建\n- `npm run pack` - 不带签名的构建（供个人使用）\n- `npm run dist` - 构建并打包，同时签名\n- `npm run lint` - 运行 ESLint 检查\n- `npm run format` - 使用 Prettier 格式化代码\n- `npm run clean` - 清理构建产物\n- `npm run preview` - 预览生产构建\n\n### 架构\n\n该应用由两个主要窗口组成：\n\n1. **主窗口**：用于听写控制的极简叠加层\n2. **控制面板**：完整的设置与历史记录界面\n\n两者使用相同的 React 代码库，但会根据 URL 参数渲染不同的组件。\n\n### 关键组件\n\n- **main.js**：Electron 主进程、IPC 处理程序及数据库操作\n- **preload.js**：主进程与渲染进程之间的安全桥接\n- **App.jsx**：包含录音控制的主要听写界面\n- **ControlPanel.tsx**：用于设置、历史记录、笔记、集成及模型管理\n- **AgentOverlay.tsx**：代理模式下的聊天叠加层，支持流式 AI 回答\n- **CommandSearch.tsx**：Cmd+K 命令面板，用于搜索笔记和转录内容\n- **IntegrationsView.tsx**：Google 日历连接及会议设置\n- **src\u002Fhelpers\u002Fwhisper.js**：whisper.cpp 集成，用于本地处理\n- **src\u002Fhelpers\u002FgoogleCalendarManager.js**：日历同步与事件管理\n- **src\u002Fhelpers\u002FmeetingDetectionEngine.js**：智能会议检测引擎\n- **src\u002Fhelpers\u002FaudioStorage.js**：音频文件的存储与管理\n- **src\u002Fhelpers\u002FmediaPlayer.js**：跨平台的媒体暂停\u002F恢复功能\n- **src\u002Fservices\u002FReasoningService.ts**：多提供商的 AI 处理服务，支持流式处理\n- **better-sqlite3**：用于存储转录、笔记、代理数据及日历信息的本地数据库\n\n### Tailwind CSS v4 设置\n\n该项目使用最新的 Tailwind CSS v4，配置包括：\n\n- 基于 `@theme` 指令的 CSS 优先配置\n- Vite 插件以优化性能\n- 自定义设计令牌，实现一致的主题风格\n- 支持深色模式，通过 `@variant` 实现\n\n## 构建\n\n构建过程会为您的平台生成一个单独的可执行文件：\n\n```bash\n# 开发构建\nnpm run pack\n\n# 生产构建\nnpm run dist           # 当前平台\nnpm run build:mac      # macOS DMG + ZIP\nnpm run build:win      # Windows NSIS + 便携版\nnpm run build:linux    # AppImage + DEB\n```\n\n注意：`build\u002Fpack\u002Fdist` 脚本会自动下载适用于当前平台的 whisper.cpp、llama-server 和 sherpa-onnx。若需从同一台主机打包多个平台版本，请先运行 `:all` 变体脚本（`npm run download:whisper-cpp:all`、`npm run download:llama-server:all`、`npm run download:sherpa-onnx:all`）。\n\n## 配置\n\n### 环境变量\n\n在项目根目录下创建 `.env` 文件（或使用 `npm run setup`）：\n\n```env\n# OpenAI API 配置（可选，仅在使用云端处理时需要）\nOPENAI_API_KEY=your_openai_api_key_here\n\n# 可选：自定义 Whisper 模型\nWHISPER_MODEL=whisper-1\n\n# 可选：设置语言以提高转录准确度\nLANGUAGE=\n\n# 可选：Anthropic API 配置\nANTHROPIC_API_KEY=your_anthropic_api_key_here\n\n# 可选：Google Gemini API 配置\nGEMINI_API_KEY=your_gemini_api_key_here\n\n# 可选：Groq API 配置（超高速推理）\nGROQ_API_KEY=your_groq_api_key_here\n\n# 可选：Mistral API 配置（Voxtral 转录）\nMISTRAL_API_KEY=your_mistral_api_key_here\n\n# 可选：调试模式\nDEBUG=false\n```\n\n### 本地 Whisper 设置\n\n对于本地处理，OpenWhispr 使用 OpenAI 的 Whisper 模型，通过高性能 C++ 实现 whisper.cpp：\n\n1. **内置二进制文件**：whisper.cpp 已随应用打包，适用于所有平台\n2. **GGML 模型**：首次使用时会下载优化后的 GGML 模型，并存储到 `~\u002F.cache\u002Fopenwhispr\u002Fwhisper-models\u002F`\n3. **无依赖**：无需 Python 或其他运行时环境\n\n**系统回退**：若内置二进制文件无法正常工作，可通过包管理器安装：\n\n- macOS：`brew install whisper-cpp`\n- Linux：从 https:\u002F\u002Fgithub.com\u002Fggml-org\u002Fwhisper.cpp 源码编译\n\n**从源码安装**：在本地运行（而非打包构建）时，需使用 `npm run download:whisper-cpp` 下载二进制文件，确保 `resources\u002Fbin\u002F` 目录下有适用于您平台的可执行文件。\n\n**要求**：\n\n- 充足的磁盘空间以存储模型（75MB 至 3GB，视模型大小而定）\n\n**从基于 Python 的版本升级**：如果您之前使用的是基于 Python 的 Whisper，则需要重新下载 GGML 格式的模型。您可以安全地删除旧的 Python 环境（`~\u002F.openwhispr\u002Fpython\u002F`）以及 PyTorch 模型（`~\u002F.cache\u002Fwhisper\u002F`），以释放磁盘空间。\n\n### 本地 Parakeet 设置（替代方案）\n\nOpenWhispr 还支持通过 sherpa-onnx 使用 NVIDIA Parakeet 模型——这是 Whisper 的快速替代方案：\n\n1. **内置二进制文件**：sherpa-onnx 已随应用打包，适用于所有平台\n2. **INT8 量化模型**：高效 CPU 推理\n3. **模型存储位置**：`~\u002F.cache\u002Fopenwhispr\u002Fparakeet-models\u002F`\n\n**可用模型**：\n\n- `parakeet-tdt-0.6b-v3`：多语言支持（25 种语言），约 680MB\n\n**何时选择 Parakeet 或 Whisper**：\n\n- **Parakeet**：最适合对速度要求较高的场景或硬件配置较低的情况\n- **Whisper**：更适合对质量要求较高的场景，或需要特定模型尺寸时\n\n### 自定义选项\n\n- **快捷键**：可在控制面板中更改，默认为反引号 `，且完全可自定义\n- **面板位置**：可将听写面板拖动至屏幕上的任意位置\n- **处理方式**：在控制面板中选择本地或云端处理\n- **Whisper 模型**：在控制面板中根据需求选择质量或速度\n- **UI 主题**：可通过编辑 `src\u002Findex.css` 中的 CSS 变量进行调整\n- **窗口大小**：可在 `main.js` 中调整窗口尺寸\n- **数据库**：转录内容存储在用户数据目录中\n\n## 贡献\n\n我们欢迎各位贡献！请按照以下步骤操作：\n\n1. Fork 仓库\n2. 创建特性分支（`git checkout -b feature\u002Famazing-feature`）\n3. 提交更改（`git commit -m '添加精彩功能'`）\n4. 推送到分支（`git push origin feature\u002Famazing-feature`）\n5. 打开 Pull Request\n\n### 开发指南\n\n- 提交代码前运行 `npm run lint`\n- 遵循现有代码风格\n- 根据需要更新文档\n- 提交前在目标平台上进行测试\n\n## 安全性\n\nOpenWhispr 在设计时充分考虑了隐私与安全性：\n\n- **本地处理选项**：确保您的语音数据完全私密\n- **无数据分析**：我们不会收集任何使用数据或遥测信息\n- **开源**：所有代码均可供审查\n- **安全存储**：API 密钥会安全地存储在您系统的钥匙串\u002F凭据管理器中\n- **最小权限**：仅请求必要的权限（麦克风、辅助功能、会议录制）\n- **OAuth 2.0 PKCE**：Google 日历使用安全的 PKCE 流程——不存储客户端密钥\n- **本地优先笔记**：笔记本地存储在 SQLite 中；云同步为可选功能\n\n## 故障排除\n\n### 常见问题\n\n1. **麦克风权限**：请在系统偏好设置\u002F设置中授予相关权限\n2. **辅助功能权限（macOS）**：自动粘贴文本需要此权限\n   - 打开系统设置 → 隐私与安全性 → 辅助功能\n   - 添加 OpenWhispr 并启用复选框\n   - 如有需要，可在控制面板中使用“修复权限问题”功能\n3. **API 密钥错误**（仅限云端处理）：请确保您的 OpenAI API 密钥有效且账户余额充足\n   - 可通过控制面板或 .env 文件设置密钥\n   - 检查日志以确认“OpenAI API 密钥存在：是\u002F否”\n4. **本地 Whisper 问题**：\n   - whisper.cpp 已随应用打包\n   - 若打包的二进制文件无法运行，请通过 `brew install whisper-cpp` 进行安装（macOS）\n   - 请检查磁盘空间是否足以存放模型\n5. **全局热键冲突**：可在控制面板中更改热键——任意按键均可使用\n   - GNOME Wayland：热键通过 gsettings 注册；请检查设置 → 键盘 → 快捷键是否存在冲突\n6. **文本无法粘贴**：\n   - macOS：请检查辅助功能权限（系统设置 → 隐私与安全性 → 辅助功能）\n   - Linux X11：请安装 `xdotool`\n   - Linux Wayland：请安装 `wtype` 或 `ydotool` 来模拟粘贴操作（确保 `ydotoold` 守护进程正在运行）\n   - 所有平台：文本始终会被复制到剪贴板——请手动使用 Ctrl+V（macOS 为 Cmd+V）进行粘贴\n7. **面板位置**：若面板显示在屏幕外，请重启应用以重置位置\n8. **会议检测未生效**：\n   - macOS：请在系统设置 → 隐私与安全性 → 屏幕录制中授予屏幕录制权限\n   - 确保已在集成中连接 Google 日历\n   - 检查设置中是否已启用会议检测功能\n9. **代理模式问题**：\n   - 确保已在设置 → 代理模式中启用该功能\n   - 验证您是否拥有所选 AI 提供商的有效 API 密钥\n   - 检查代理模式热键是否与其他快捷键冲突\n\n### 获取帮助\n\n- 请查看 [Issues](https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues) 页面\n- 查看控制台日志以获取调试信息\n- 对于本地处理：请确保 whisper.cpp 可用且模型已下载\n- 对于云端处理：请验证您的 OpenAI API 密钥及账单状态\n- 检查控制面板中的系统状态和诊断信息\n\n### 性能提示\n\n- **本地处理**：建议使用 “base” 模型，以获得速度与准确性的最佳平衡\n- **云端处理**：通常速度更快，但需要互联网连接\n- **模型选择**：tiny（最快）→ base（推荐）→ small → medium → large（最佳质量）\n- **权限**：请确保所有必要权限均已授予，以保证流畅运行\n\n## 常见问题解答\n\n**问：OpenWhispr 真的是免费的吗？**\n答：是的！OpenWhispr 是开源且免费使用的。免费计划包含每周 2,000 字的云端转录服务，而本地处理则完全免费且无限制。付费计划低至每月 8 美元。\n\n**问：我应该使用哪种处理方式？**\n答：如果您注重隐私且需要离线使用，请选择本地处理；若您追求速度与便利，则可以选择云端处理。\n\n**问：我可以将它用于商业用途吗？**\n答：可以！MIT 许可证允许商业使用。\n\n**问：如何更改热键？**\n答：右键点击托盘图标打开控制面板，进入设置即可。您可以将任意按键设为热键。\n\n**问：我的数据安全吗？**\n答：使用本地处理时，您的音频绝不会离开设备。而使用云端处理时，音频会发送到 OpenAI 的服务器（请参阅其隐私政策）。\n\n**问：支持哪些语言？**\n答：OpenWhispr 支持 58 种语言，包括英语、西班牙语、法语、德语、中文、日语等。您可以在 .env 文件中设置首选语言，或使用自动检测功能。\n\n**问：什么是代理模式？**\n答：代理模式会打开一个聊天浮层，您可以通过语音与 AI 进行交互式对话。它支持来自所有提供商（OpenAI、Anthropic、Gemini、Groq、本地模型）的流式响应，并保存对话历史。\n\n**问：会议转录是如何工作的？**\n答：在集成中连接您的 Google 日历。当会议开始时（Zoom、Teams、FaceTime），OpenWhispr 会检测到并提供录音选项。音频将通过 OpenAI Realtime API 实时转录。在 macOS 上，需要屏幕录制权限才能捕获会议音频。\n\n**问：我的笔记存储在哪里？**\n答：笔记本地存储在 SQLite 中，支持可选的云同步。它们具备全文搜索（FTS5）、文件夹组织以及 AI 驱动的增强功能。\n\n**问：OpenWhispr 在 macOS 上是否需要输入监控权限？**\n答：不需要。自 v1.6.0 起，OpenWhispr 使用 NSEvent 监视器代替 CGEvent 拦截，从而不再需要输入监控权限。仅需麦克风和辅助功能权限（加上会议功能所需的屏幕录制权限）。\n\n## 项目状态\n\nOpenWhispr 目前处于积极维护状态，已准备好投入生产使用。当前版本：1.6.7\n\n- ✅ 核心听写功能，支持本地与云端处理\n- ✅ 跨平台支持（macOS、Windows、Linux）\n- ✅ OpenWhispr 云服务，配备账户系统、使用情况追踪及 Stripe 支付功能\n- ✅ 多家 AI 提供商支持（OpenAI、Anthropic、Gemini、Groq、Mistral、本地模型）\n- ✅ 代理模式，支持流式聊天浮层及对话历史记录\n- ✅ Google 日历集成，支持自动会议检测\n- ✅ 通过 OpenAI Realtime API 实现会议实时转录\n- ✅ 笔记系统，支持 FTS5 搜索、云同步、文件夹管理及 AI 动作\n- ✅ 音频保留功能，支持失败转录的回放与重试\n- ✅ Cmd+K 命令搜索，可跨笔记与转录内容查找\n- ✅ 听写过程中自动暂停媒体播放\n- ✅ 自定义词典，支持自动学习纠正功能\n- ✅ 通过 sherpa-onnx 支持 NVIDIA Parakeet\n- ✅ 复合热键及 Windows 按住说话功能\n- ✅ GNOME Wayland 和 Hyprland 原生全局快捷键\n- ✅ 推荐计划，支持分享邀请卡\n- ✅ 专用会议模式热键\n- ✅ CodeQL 静态分析及 Dependabot 依赖项更新\n\n## 致谢\n\n- **[OpenAI Whisper](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fwhisper)** - 为本地和云端转录提供支持的语音识别模型\n- **[whisper.cpp](https:\u002F\u002Fgithub.com\u002Fggerganov\u002Fwhisper.cpp)** - 高性能的 Whisper C++ 实现，用于本地处理\n- **[NVIDIA Parakeet](https:\u002F\u002Fhuggingface.co\u002Fnvidia\u002Fparakeet-tdt-0.6b-v3)** - 适用于高效本地转录的快速 ASR 模型\n- **[sherpa-onnx](https:\u002F\u002Fgithub.com\u002Fk2-fsa\u002Fsherpa-onnx)** - 用于 Parakeet 模型推理的跨平台 ONNX 运行时\n- **[Electron](https:\u002F\u002Fwww.electronjs.org\u002F)** - 跨平台桌面应用框架\n- **[React](https:\u002F\u002Freact.dev\u002F)** - UI 组件库\n- **[shadcn\u002Fui](https:\u002F\u002Fui.shadcn.com\u002F)** - 基于 Radix 原语构建的精美 UI 组件\n- **[Hugging Face](https:\u002F\u002Fhuggingface.co\u002F)** - 我们本地语音识别和语言模型的模型托管平台\n- **[llama.cpp](https:\u002F\u002Fgithub.com\u002Fggerganov\u002Fllama.cpp)** - 用于 AI 驱动文本处理的本地 LLM 推理","# OpenWhispr 快速上手指南\n\nOpenWhispr 是一款跨平台的语音转文字（Dictation）与 AI 助手应用，支持本地隐私优先的语音识别、会议转录、笔记管理及多模型 AI 代理。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**：\n    *   macOS 12+\n    *   Windows 10+\n    *   Linux (支持 GNOME\u002FKDE\u002FHyprland Wayland)\n*   **核心依赖**：\n    *   **Node.js 22+** 及 npm (推荐从 [nodejs.org](https:\u002F\u002Fnodejs.org\u002F) 下载，国内用户可使用淘宝镜像或 nvm 管理版本)\n*   **macOS 额外要求**：\n    *   若需使用 Globe 键（地球仪键）触发功能，需安装 Xcode 命令行工具：\n        ```bash\n        xcode-select --install\n        ```\n\n## 安装步骤\n\n### 1. 克隆项目\n将代码仓库克隆到本地并进入目录：\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr.git\ncd openwhispr\n```\n\n### 2. 安装依赖\n安装项目所需的 Node.js 依赖包：\n```bash\nnpm install\n```\n> **提示**：国内网络环境下，建议配置 npm 镜像源以加速下载：\n> ```bash\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> ```\n\n### 3. 配置 API 密钥（可选）\n如果您计划使用云端 AI 处理（如 OpenAI, Claude, Gemini 等），有两种配置方式：\n\n**方式 A：环境变量文件**\n复制示例文件并编辑：\n```bash\ncp .env.example .env\n```\n在 `.env` 文件中填入您的密钥：\n```text\nOPENAI_API_KEY=your_openai_key\nANTHROPIC_API_KEY=your_anthropic_key\nGEMINI_API_KEY=your_gemini_key\nGROQ_API_KEY=your_groq_key\nMISTRAL_API_KEY=your_mistral_key\n```\n\n**方式 B：应用内配置**\n跳过此步，启动应用后在控制面板（Control Panel）中直接输入密钥，系统将自动保存。\n\n### 4. 构建与运行\n\n**开发模式运行（支持热重载）：**\n```bash\nnpm run dev\n```\n\n**生产模式运行：**\n```bash\nnpm start\n```\n\n### 5. 启用本地语音识别（可选）\n若希望完全在本地进行语音转录（保护隐私，无需联网），需下载 `whisper.cpp` 二进制文件：\n```bash\nnpm run download:whisper-cpp\n```\n该命令会自动下载适合当前平台的二进制文件至 `resources\u002Fbin\u002F` 目录。\n\n## 基本使用\n\n启动应用后，您即可通过以下方式快速体验核心功能：\n\n1.  **开始听写 (Dictation)**\n    *   按下全局快捷键 **`` ` ``** (反引号键) 开始录音。\n    *   再次按下该键停止录音。\n    *   转录后的文本将自动粘贴到您当前的光标位置。\n    *   *注：可在设置中自定义快捷键或关闭自动粘贴功能。*\n\n2.  **使用 AI 助手 (Agent Mode)**\n    *   呼出玻璃拟态风格的 AI 悬浮窗。\n    *   说出 \"Hey [您的助手名称]\" 或直接输入指令。\n    *   支持实时流式对话、笔记创建及上下文检索（RAG）。\n\n3.  **会议转录**\n    *   使用独立的会议快捷键启动录制。\n    *   应用会自动检测 Zoom、Teams 等会议软件音频，或通过 Google 日历同步会议安排。\n\n4.  **管理笔记**\n    *   在应用内创建笔记文件夹，支持全文搜索和语义搜索（基于本地 Qdrant 向量库）。\n    *   笔记可导出为 Markdown 文件保存到本地文件系统。","资深数据科学家林工正在撰写一篇关于多模态模型的技术博客，同时需要整理上午与跨国团队的项目复盘会议记录。\n\n### 没有 openwhispr 时\n- **隐私与速度难两全**：使用云端语音输入担心代码逻辑和未公开数据泄露，而本地离线方案往往识别速度慢、延迟高，打断思考流。\n- **专业术语识别率低**：口述\"sherpa-onnx\"、\"RAG 上下文注入”等专有名词时频繁出错，需手动逐字修正，效率极低。\n- **会议记录割裂**：会议录音与文字稿分离，回顾时需反复拖拽进度条对照音频查找关键决策点，耗时费力。\n- **工作流中断**：语音输入时无法自动暂停背景音乐或播客，且转录内容需手动复制粘贴到编辑器，操作繁琐。\n\n### 使用 openwhispr 后\n- **私有化高速转录**：利用本地 NVIDIA Parakeet 模型实现零延迟、完全离线的语音转文字，敏感技术细节无需上传云端，安心又流畅。\n- **自定义词典自学习**：预先导入技术术语库，openwhispr 能精准识别生僻词，并自动记忆林工的口语修正，后续识别准确率持续提升。\n- **智能会议回溯**：通过 Google 日历联动自动捕捉 Zoom 会议，生成带时间戳的逐字稿，点击文字即可跳转对应音频片段，复盘效率倍增。\n- **无感沉浸式协作**：按下全局快捷键即可随时口述，openwhispr 自动暂停媒体播放并将文字直接“流式”插入光标处，真正实现手不离键盘的连贯创作。\n\nopenwhispr 通过本地优先的隐私架构与深度集成的 AI 代理能力，将碎片化的语音交互转化为高效、安全且连贯的生产力流。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FOpenWhispr_openwhispr_de2b6948.png","OpenWhispr","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FOpenWhispr_76d494d1.png","",null,"support@openwhispr.com","https:\u002F\u002Fopenwhispr.com","https:\u002F\u002Fgithub.com\u002FOpenWhispr",[80,84,88,92,96,100,104,107,111],{"name":81,"color":82,"percentage":83},"TypeScript","#3178c6",51.2,{"name":85,"color":86,"percentage":87},"JavaScript","#f1e05a",43.7,{"name":89,"color":90,"percentage":91},"C","#555555",2.5,{"name":93,"color":94,"percentage":95},"Swift","#F05138",1.2,{"name":97,"color":98,"percentage":99},"CSS","#663399",0.9,{"name":101,"color":102,"percentage":103},"Shell","#89e051",0.2,{"name":105,"color":106,"percentage":103},"Python","#3572A5",{"name":108,"color":109,"percentage":110},"HTML","#e34c26",0,{"name":112,"color":75,"percentage":110},"NSIS",2297,326,"2026-04-06T20:11:43","MIT",4,"macOS, Windows, Linux","非必需。支持本地运行 NVIDIA Parakeet (基于 sherpa-onnx)，未指定具体显卡型号或显存要求；也支持纯云端处理或使用 CPU 运行本地模型。","未说明",{"notes":122,"python":123,"dependencies":124},"1. 核心运行环境为 Node.js 22+ 而非 Python。\n2. macOS 用户若需使用 Globe 键功能，必须安装 Xcode Command Line Tools。\n3. Linux 用户在不同桌面环境（GNOME, KDE, Hyprland）下通过 D-Bus 或特定命令实现全局快捷键。\n4. Windows 和 Linux 包含原生 C 二进制文件用于快速粘贴文本，构建时会自动编译或下载。\n5. 支持多种本地 AI 模型 (Whisper, LLaMA, Qwen 等) 及云端 API，本地模型需手动下载管理。","未说明 (项目基于 Node.js，非 Python)",[125,126,127,81,128,129,130,131,132],"Node.js 22+","npm","React 19","Tailwind CSS v4","sherpa-onnx","llama.cpp","Qdrant","SQLite",[13,134,15,14],"音频",[136,137,138,139,140,141,142,143,144,145,146,147,148,149,150],"ai","open-source","whisper","anthropic","cross-platform","gemini","groq","linux","macos","openai","speech-to-text","transcribe","windows","nvidia","parakeet","2026-03-27T02:49:30.150509","2026-04-07T11:48:27.449870",[154,159,164,169,174,179,184],{"id":155,"question_zh":156,"answer_zh":157,"source_url":158},21855,"在 Linux (Ubuntu) 上使用本地 Whisper 转录时出现错误怎么办？","这是一个已知的兼容性问题，通常发生在特定版本中。维护者已在后续版本（如 v1.2.4 之后的更新）中修复了该问题，主要涉及参数顺序的调整。请确保将软件更新至最新发行版（latest release），如果问题仍然存在，可以尝试在终端中使用 `ELECTRON_DISABLE_SANDBOX=1 npm run dev` 运行开发版本进行测试，或者直接下载最新的安装包覆盖安装。","https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues\u002F104",{"id":160,"question_zh":161,"answer_zh":162,"source_url":163},21856,"升级到最新版本后快捷键（Hotkey）无法使用或无法识别怎么办？","如果在升级后（例如从 v1.4.1 升级到 v1.4.2 或更高）发现快捷键失效，或者按下快捷键无反应：\n1. 首先尝试重启应用程序或重新设置快捷键组合。\n2. 某些特殊按键（如 Mac 上的 Globe 键或 Fn 键）可能在特定版本中存在识别问题，建议先尝试使用标准的组合键（如 Ctrl+Space 或 Alt+Space）测试是否正常。\n3. 确保已升级到最新的稳定版（如 v1.4.8 或 v1.4.11+），维护者持续在修复快捷键回归问题。\n4. 如果问题依旧，可能是系统权限或冲突导致，建议加入官方 Discord 频道进行调试，或检查是否有其他软件占用了该快捷键。","https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues\u002F220",{"id":165,"question_zh":166,"answer_zh":167,"source_url":168},21857,"说西班牙语（或其他非英语语言）时，为什么会被自动翻译成英语？","这是因为语言检测设置未正确配置。解决方法如下：\n1. 进入软件的“设置” (Settings) > “偏好设置” (Preferences)。\n2. 找到语言选项，将其手动选择为您使用的语言（例如“Spanish”），或者选择“Auto”（自动）以让模型自动检测。\n3. 确保您使用的是较新的版本（推荐 v1.4.8 及以上），旧版本在多语言支持上存在缺陷。\n4. 如果您需要频繁切换多种语言，建议使用“Auto”模式，但需确保模型已正确下载并支持该语言。","https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues\u002F188",{"id":170,"question_zh":171,"answer_zh":172,"source_url":173},21858,"AI 模型下载显示成功，但切换页面后再回来显示“未下载”或无法使用怎么办？","这是一个界面状态刷新或数据持久化的 Bug。解决步骤：\n1. 尝试完全关闭应用程序（包括后台进程），然后重新启动，查看模型状态是否更新。\n2. 如果问题依旧，可能是缓存数据损坏。建议彻底卸载软件，并手动删除系统中的 OpenWhispr 数据文件夹（通常在用户目录下的 AppData 或 Application Support 中），然后重新安装最新版本。\n3. 维护者建议在测试新版本前彻底清理旧数据，以避免配置冲突。如果使用的是 v1.2.15 及以上版本出现无法启动的情况，请务必执行清理操作。","https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues\u002F68",{"id":175,"question_zh":176,"answer_zh":177,"source_url":178},21859,"如何开启快捷键按下和释放时的声音反馈功能？","该功能旨在帮助用户（特别是视障用户）确认录音状态。使用方法：\n1. 进入软件的“设置” (Settings) 菜单。\n2. 查找“音频反馈” (Audio Feedback) 或类似的开关选项并启用它。\n3. 启用后，按下快捷键开始录音时会播放一个短促的“开始”提示音（通常是高音），释放快捷键结束录音时会播放不同的“停止”提示音（通常是低音）。\n注意：如果设置中找不到该选项，请确保您的软件已更新到包含此功能的最新版本（v1.4.x 后期版本）。","https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues\u002F197",{"id":180,"question_zh":181,"answer_zh":182,"source_url":183},21860,"使用 'Hey [AgentName]' 语音命令时，为什么没有执行指令而是被当作文本录入？","这通常是因为代理（Agent）名称配置不匹配或唤醒词功能未正确激活。解决方法：\n1. 检查您的代理配置，确认您在设置中命名的 Agent 名称与您口述的名称完全一致（区分大小写）。\n2. 确保当前模式支持语音命令触发，某些模式下可能仅进行纯转录。\n3. 尝试简化名称，避免使用特殊字符。如果问题持续，可能是该版本的一个已知限制，建议检查是否有更新的补丁或暂时通过手动触发方式执行编辑指令。","https:\u002F\u002Fgithub.com\u002FOpenWhispr\u002Fopenwhispr\u002Fissues\u002F164",{"id":185,"question_zh":186,"answer_zh":187,"source_url":168},21861,"Mac 用户无法使用 Globe 键作为快捷键，且“按住说话”模式失效怎么办？","这是 macOS 特定版本中的回归问题。建议方案：\n1. 更新到最新版本（v1.4.8 或更高），维护者已针对 Globe 键和代理提示词（Agent Prompt）进行了修复。\n2. 如果更新后仍无效，尝试重置软件设置：删除旧的配置文件并重启应用。\n3. 临时替代方案：在设置中将快捷键更改为其他组合键（如 Command+Shift+Space），避开 Globe 键的识别问题。\n4. 确认 macOS 的辅助功能权限已授予 OpenWhispr，否则可能导致按键监听失败。",[189,194,199,204,209,214,219,224,229,234,239,244,249,253,258,263,268,273,278,283],{"id":190,"version":191,"summary_zh":192,"released_at":193},127844,"v1.6.7","**AI 聊天与语义搜索** — 使用全新的嵌入式聊天面板，轻松就笔记内容提问。对话会同步至云端，而本地语义搜索引擎则能根据内容含义而非单纯关键词来查找笔记。\n\n**会议功能优化** — 日历中的参会人员会自动添加到会议笔记中；浏览器会议支持自动检测功能；回声消除技术可有效净化麦克风输入音质。\n\n**将笔记保存为文件** — 可将笔记导出为本地 Markdown 文件，并保持与原有文件夹结构一致。\n\n**自适应设置界面** — 设置对话框能够流畅适配较小的窗口尺寸。\n\n**问题修复** — 修复了会议转录、文件夹切换、剪贴板粘贴以及参会者保存等方面的问题；同时提升了对 Linux Wayland 的支持，并完善了 Windows 版本的代码签名机制。\n\n特别感谢 @xAlcahest、@DamianPala 等多位贡献者，他们为平台的稳定性和功能改进做出了重要贡献！","2026-04-03T02:08:02",{"id":195,"version":196,"summary_zh":197,"released_at":198},127845,"v1.6.6","### 富文本笔记\n- 笔记现采用富文本编辑器，并支持 Obsidian 风格的实时预览——Markdown 语法会在您输入时自动隐藏，带来清爽的写作体验。\n\n### 会议转录升级\n- **双声道转录**——麦克风音频和系统音频将分别捕获，并以标注发言者的气泡形式显示，方便您清晰地了解是谁说了什么。\n- **带时间戳的片段**——会议转录现在按时间顺序包含时间戳。\n- **更智能的会议记录**——AI 生成的摘要现已区分发言人，使会议回顾更加准确。\n\n### 新增本地模型\n- Mistral Nemo 12B 和 Gemma 3 12B 现已可用于设备端 AI 处理。\n\n### macOS 音频改进\n- 通过 CoreAudio Tap 原生捕获系统音频——在 macOS 14.2 及更高版本上不再弹出“屏幕录制”权限提示。\n- macOS 15 及更高版本现会显示正确的系统音频授权对话框，而非旧版的屏幕录制权限对话框。\n\n### Linux\n- **KDE Wayland 支持**——原生全局快捷键现已通过 D-Bus 在 KDE Plasma 上生效，与 GNOME 和 Hyprland 的支持同步。\n- 修复了 KDE Plasma 的叠加窗口及热键行为问题。\n- 修复了 KDE Wayland 下剪贴板粘贴的可靠性问题。\n\n### 权限简化\n- 权限提示整合为一个“授予访问权限”按钮。\n- 每次打开设置时，系统都会重新检查权限状态，确保界面始终反映您的实际权限情况。\n\n### 错误修复\n- 修复了 Gemini 代理流式传输路由至错误端点的问题。\n- 修复了 Windows 设备在听写过程中麦克风音量被永久更改的问题。\n- 修复了 Linux 系统上单声道转录失败的问题。\n- 修复了会议期间蓝牙音频相关问题。\n- 修复了当您已处于会议中时，会议检测通知仍会触发的问题。\n- 修复了 Windows 系统下按住的修饰键在粘贴前未释放的问题。\n- 修复了听写过程中暂停的媒体被意外恢复播放的问题。\n- 修复了 Google OAuth 用户跳过入门引导流程的问题。\n- 修复了 AI 清理提示拒绝转录类似命令式语音的问题。\n- 修复了代理热键冲突时未显示警告的问题。","2026-03-23T22:55:18",{"id":200,"version":201,"summary_zh":202,"released_at":203},127846,"v1.6.5","- 会议检测优化","2026-03-17T17:26:04",{"id":205,"version":206,"summary_zh":207,"released_at":208},127847,"v1.6.4","### 会议模式\n- **会议模式快捷键** — 可分配一个专用快捷键，以便立即将面板切换至会议模式并开始新的会议笔记。\n- **更智能的会议检测** — 降低了误报率；诸如 FaceTime 等后台应用现在只有在检测到麦克风活动时才会触发通知。\n- **会议检测开关** — 可在设置中完全关闭会议检测功能。\n\n### 自动更新\n- **更新通知** — 当有新版本可用时，会弹出一条滑入式通知，并附带“立即更新”按钮。\n\n### 多显示器支持\n- **光标感知定位** — 浮动图标现在会显示在光标所在的任意一台显示器上。\n\n### 新模型\n- **GPT-5.4** — 新增为 OpenAI 的旗舰模型。\n- **通义千问 3.5** — 新增本地模型；移除了参数量低于 10 亿的模型。\n\n### 错误修复\n- 修复了在 Windows 系统中，当没有正在进行的播放会话时，暂停的媒体会意外恢复播放的问题。\n- 修复了在切换快捷键时，Windows 快捷键监听器状态损坏的问题。\n- 修复了静音检测误判有效语音（已降低阈值）。\n- 修复了在 Windows Terminal 中无法粘贴文本的问题（现已包含扫描码处理）。\n- 修复了保存在设置中的 API 密钥会被 Shell 环境变量覆盖的问题。\n- 修复了在 Windows 应用程序更新过程中，本地 LLM 模型被删除的问题。\n- 修复了 macOS 上多键组合快捷键提示框显示异常的问题。\n- 修复了 RPM 安装与 Linux 上其他 Electron 应用冲突的问题。\n- 为自托管部署新增了 Tailscale VPN（CGNAT 范围）支持。\n\n### 其他\n- 面板的初始位置现在会在每次重启应用后保持不变。\n- 跨窗口同步设置（快捷键更改会立即生效）。\n- 增加了账号删除流程，并同步清理云端数据。\n- 将“代理模式”窗口更名为“代理聊天”。","2026-03-16T15:09:04",{"id":210,"version":211,"summary_zh":212,"released_at":213},127848,"v1.6.3","### 权限提示更清晰\n\n- **“屏幕录制” → “系统音频”** — 所有权限请求现在都会明确说明我们捕获的是其他参与者的音频，而非您的屏幕内容。\n- **Electron 39** — 移除了紫色的“屏幕录制”指示器、“您的屏幕正在被监控”的锁屏提示，以及在 macOS 14.2 及更高版本上出现的误导性权限请求。\n\n### 更优秀的轻声语音识别\n\n- **自动增益控制**现已为听写功能启用，可自动增强低声语音。\n- **降低 VAD 检测灵敏度**，以避免遗漏轻声语音。\n- **减少语音起始处的削波现象**——增加了缓冲区长度，确保轻微的语音开头不会被截断。\n\n### Linux\n\n- **Hyprland Wayland 支持** — 原生全局快捷键，使用 `hyprctl` 键位绑定和 D-Bus 实现。\n\n### 错误修复\n\n- 修复了由于超时时间过短，导致 `wl-copy` 在 Wayland 上静默失败的问题。\n- 修复了在启用“听写时暂停媒体”选项的情况下，录制静音后媒体仍保持暂停状态的问题。","2026-03-14T15:16:27",{"id":215,"version":216,"summary_zh":217,"released_at":218},127849,"v1.6.2","### 系统音频采集\n在“备忘录”中，可同时录制系统音频和麦克风音频——轻松捕捉会议音频、讲座等内容。在获得屏幕录制权限后会自动启用（macOS）。\n\n### 更智能的会议检测\n会议检测现改用操作系统原生事件而非轮询方式，将后台 CPU 占用率降至接近零。\n\n### 错误修复\n- 修复了 Windows 11 上热键可靠性问题（仅含修饰键的快捷键）\n- 修复了 macOS 在全新安装时 Globe 键静默失效的问题——现会提示请求辅助功能权限\n- 修复了实时流式传输过程中初始音频被丢弃的问题\n- 修复了大型自定义词典中的错误\n- 修复了 Windows 10 上 Parakeet 模型提取失败的问题\n","2026-03-11T21:51:25",{"id":220,"version":221,"summary_zh":222,"released_at":223},127850,"v1.6.1","- 在 OpenWhispr Pro 上实现更快的转录，并支持 gpt4o 的 Websockets\r\n- 修复了若干 bug","2026-03-09T05:38:43",{"id":225,"version":226,"summary_zh":227,"released_at":228},127851,"v1.6.0","- 客服模式！新增独立快捷键用于快速开启聊天窗口，再也不用手动打开 Claude 或 ChatGPT 窗口了。可在设置中查看。\n- 绑定 Google 日历，无需使用机器人即可录制会议。\n- 搜索您的通话记录和笔记。\n- 恢复了清空所有通话记录的功能。\n- 自定义录音机的开始位置。\n- 可在启动时选择将仪表盘最小化。\n- 在进行语音转文字时，可选择暂停音乐等音频。\n- 以及其他多项错误修复和性能优化。\n\n特别感谢 @xAlcahest 为 Linux 系统稳定性及其他功能改进所做的重大贡献！","2026-03-07T02:39:10",{"id":230,"version":231,"summary_zh":232,"released_at":233},127852,"v1.5.5","- 新增 Google Gemma 本地大模型\n- 修复了若干 bug，并提升了性能","2026-03-02T05:11:34",{"id":235,"version":236,"summary_zh":237,"released_at":238},127853,"v1.5.4","- 词语编辑检测 + 自动添加到词典","2026-02-26T04:09:09",{"id":240,"version":241,"summary_zh":242,"released_at":243},127854,"windows-text-monitor-v1.0.0","Prebuilt Windows text monitor binary for auto-learn correction monitoring.\n\nThis binary uses Windows UI Automation to detect text field changes after paste.\n","2026-02-26T02:53:37",{"id":245,"version":246,"summary_zh":247,"released_at":248},127855,"v1.5.3","- Bug fixes and performance improvements","2026-02-25T01:36:35",{"id":250,"version":251,"summary_zh":247,"released_at":252},127856,"v1.5.2","2026-02-24T17:40:31",{"id":254,"version":255,"summary_zh":256,"released_at":257},127857,"v1.5.1","- CUDA support for whisper-server (local whisper models)\r\n- GPU support for llama.cpp (Local LLMs)\r\n- Other small bug fixes and performance improvements","2026-02-24T02:44:09",{"id":259,"version":260,"summary_zh":261,"released_at":262},127858,"v1.5.0","- Create and manage notes\r\n- Upload audio files and automatically transcribe them into notes\r\n- AI actions in notes\r\n- Referral scheme (give 1 month get 1 month)\r\n- Improved dark mode","2026-02-23T20:18:12",{"id":264,"version":265,"summary_zh":266,"released_at":267},127859,"v1.4.11","- Japanese as an interface language\r\n- Paste improvements on Windows","2026-02-13T18:52:48",{"id":269,"version":270,"summary_zh":271,"released_at":272},127860,"windows-fast-paste-v1.0.0","Prebuilt Windows fast-paste binary for clipboard paste operations.\n\nUses Win32 SendInput API with automatic terminal detection\n(Ctrl+V for normal apps, Ctrl+Shift+V for terminals).\n","2026-02-13T16:08:48",{"id":274,"version":275,"summary_zh":276,"released_at":277},127861,"v1.4.10","- Better support for Simplified vs Traditional Chinese on OpenWhispr Pro\r\n- Reliability improvements for OpenWhispr Pro","2026-02-13T06:09:08",{"id":279,"version":280,"summary_zh":281,"released_at":282},127862,"v1.4.9","- Better auto-paste support for Linux users\r\n- Better language support for OpenWhispr Pro","2026-02-13T03:52:49",{"id":284,"version":285,"summary_zh":286,"released_at":287},127863,"v1.4.8","- Internationlization ( EN, PT, IT, ZT, DE, ES, RU, ZH)\r\n- Bug fixes & performance improvements","2026-02-12T23:28:55"]