Skip to content

Latest commit

 

History

History
262 lines (182 loc) · 16.9 KB

README_zh.md

File metadata and controls

262 lines (182 loc) · 16.9 KB

Utter

macOS 菜单栏 AI 语音输入


GitHub Stars GitHub Forks GitHub Issues

Platform Swift Apple Silicon License

WhisperKit MLX

官网 · English


项目简介

Utter 是一款 macOS 菜单栏 AI 语音输入与听写应用,支持完全本地推理和远程 LLM API 两种模式。按住快捷键开始录音,松开后自动转写,结果直接输入到当前激活的应用中。

三种输出模式:

  • 原文直出 — 语音识别原始结果,延迟最低
  • 智能整理 — LLM 根据上下文清理语气词、修正口误、结构化排版
  • 语音指令 — 说出指令,AI 结合屏幕内容生成回复

演示视频

功能一览 办公室里的一天 本地语音输入

可在官网观看,或直接下载 MP4:功能一览 (0:51) · 办公室里的一天 (0:58) · 本地语音输入 (0:28)。三支均为普通话配音;界面为真实应用的动画重建,示例文本仅作演示。

功能特性

功能 说明
多语音引擎 本地 Qwen3-ASR、Confucius4-R2T2、FireRedASR2、Mega-ASR、WhisperKit 或设备端 Apple 语音识别;豆包语音识别为远程选项
智能文字处理 本地 MLX 模型(Qwen3.5 / Qwen3 / Gemma)或远程 LLM 理解口述意图 — 上下文感知的语气词清理、“算了/删掉刚才”重说处理、自动纠正、口述标点、技术词、数字/范围/单位和列表格式化
LLM 负责口述格式 大小写、无空格、标识符、文件路径、快捷键、表情、Markdown 任务、日期时间、数量、单位、公式、分数和数字串都由智能整理/语音指令提示词交给 LLM 判断,不在本地写死替换规则
语音编辑口令 在语音指令模式下,由 LLM 分类安全结构化动作,支持上一段/选区替换、撤销、校对、跨语言回复起草、接受/拒绝/追问回复、会议纪要、关键要点/结论/问题/风险/截止时间/负责人/行动项提取、标题化、摘要、语气改写、扩写、表格化、列表化、删除与改写口令
直出与预览边界 原文直出、流式 HUD、集成 partial 和快速插入草稿尽量保留 ASR 原文,只做词库、空白、重复转写和非语音垃圾过滤
远程 LLM 支持 OpenAI、Claude(Anthropic 格式)、Gemini、OpenRouter、硅基流动、豆包、百炼、MiniMax(国内/海外)
全局快捷键 可配置按键(Fn/Ctrl/Shift/Option),支持长按、双击、单击三种触发模式
翻译听写 使用独立组合键,说一种语言,直接输入英语、中日韩、西班牙语、法语或德语译文
屏幕上下文 OCR 通过 ScreenCaptureKit + Vision 截取屏幕文字,辅助 LLM 纠正同音字
语音指令模式 屏幕感知的语音助手 — 总结、回复、翻译屏幕内容
输入记忆 近期输入历史作为 LLM 上下文,提升连续输入准确度
行业词库 可选医疗、法律、金融财会或软件技术词库,为 Apple Speech / Whisper 提供优先术语并辅助输出规范化;个人词条优先
编辑规则 自定义文本替换规则,每次输出自动应用
语言风格预设 口语 / 专业 / 自定义提示词
输入历史与统计 完整历史记录,原始文本与润色结果对比,字数统计,可配置保留时长
双语界面 中英文界面切换,独立于识别语言设置
音效反馈 录音开始/停止时播放提示音
引导式新手教程 分步设置:权限授予、模型下载、首次使用

系统要求

  • 系统:macOS 26 (Tahoe) 或更高版本
  • 芯片:Apple Silicon(M1 / M2 / M3 / M4)
  • 空间:最低约 0.7 GB(Apple 语音 + Qwen3.5 0.8B);默认配置(Apple 语音 + Qwen3.5 2B)约 1.8 GB;更大的识别和整理模型还需要数 GB

安装

下载安装

从 Releases 页面下载最新 .dmg,打开后将 Utter.app 拖入"应用程序"文件夹。

首次打开提示"无法验证开发者"? 由于应用未经 Apple 公证,首次运行前需在终端执行:

xattr -cr /Applications/Utter.app

或在"系统设置 → 隐私与安全性"中点击"仍然打开"。

从源码构建

# 构建 .app 包 + .dmg 安装器
bash scripts/build-app.sh

# 或开发模式
swift build
swift run OpenType

# 构建、签名并启动开发用 .app 包
bash scripts/build-and-run.sh --verify

# 或在 Xcode 中打开
open Package.swift

实质性改动遵循 docs/sdlc/README.md 中的 Artifact 驱动流程。 提交 Pull Request 前请运行:

bash scripts/sdlc-checks.sh
bash scripts/ci-basic-checks.sh
swift test

对外应用名为 Utter.app;Swift 包产物暂时保留 OpenType,以兼容现有源码集成和升级路径。

首次使用

  1. 启动 Utter — 菜单栏出现波形图标
  2. 新手引导自动启动,引导完成权限和模型配置
  3. 授予 麦克风 和 辅助功能 权限(必需)
  4. 等待默认整理模型(Qwen3.5 2B,约 1.7 GB)下载完成,仅首次
  5. 长按 Fn 键开始语音输入,松开后文字自动插入当前位置

权限说明

权限 用途 必需
麦克风 语音采集 是
辅助功能 全局快捷键、文本写入(剪贴板 + 模拟 ⌘V)、读取当前输入框内容作为上下文 是
语音识别 Apple 语音识别引擎 使用 Apple Speech 时需要
屏幕录制 OCR 屏幕文字辅助纠错 + 语音指令模式 可选
输入监控 仅在开启 设置 → 遥控器 → 重新分配遥控器按键 时需要:用来知道小米遥控器的哪个键被按下。Utter 只监听这支遥控器。打开该开关时才会申请,之前不会 可选
网络 下载模型;远程 LLM API 调用;每日检查更新 首次运行 / 远程 LLM 模式

自动更新

Utter 每天检查一次更新;也可以在 设置 → 关于 或菜单栏的「Check for Updates…」手动检查。自动检查默认开启,可在同一处关闭。

检查会通过 HTTPS 获取 GitHub 上的发布 feed,并可能跟随 GitHub CDN 重定向。GitHub 会收到你的 IP 地址,以及包含 app 和 Sparkle 版本的 User-Agent。检查不发送音频、文本、历史、系统画像或持久标识符。Sparkle 先验证 feed 的 Ed25519 签名,再显示更新。只有你在更新弹窗中选择 Install Update 后,它才会下载 DMG,并在解包和安装前验证更新包。

第一个带更新功能的版本需要手动安装一次;之后的版本会原地升级,权限、设置和历史都会保留。

小米遥控器语音键

小米遥控器的语音键还会发出 F5,macOS 把它当作系统听写键,并在输入框里打出多余的字(例如“I”)。设置 → 遥控器 → 语音键不再打开系统听写 开启时(默认开启),Utter 只在这支遥控器上关闭这一个键(小米 RC003,厂商 0x2717,产品 0x32B8)。其他按键和其他键盘不受影响,不需要额外权限;关闭此开关或退出 Utter 时按键会恢复。无需开启遥控器无线麦。

遇到问题时:

  • 关闭该开关,或执行 defaults write com.opentype.voiceinput remoteKeyRemapEnabled -bool false 后重新打开 Utter。
  • 如果 Utter 崩溃后语音键没有反应,在系统设置 → 蓝牙中重新连接遥控器,或手动清除:hidutil property --matching '{"VendorID":10007,"ProductID":12984}' --set '{"UserKeyMapping":[]}'。
  • 不使用 Utter 时,可用系统设置 → 键盘 → 听写关闭作为替代办法。

小米遥控器按键映射

开启 设置 → 遥控器 → 重新分配遥控器按键(默认关闭)后,小米 RC003 的十一个按键(上、下、左、右、确认、返回、主页、菜单、电视、音量加、音量减)都可以在单击、双击或长按时改做别的事:键盘快捷键、媒体键、显示桌面、切换应用,或打开某个应用。语音键不能重新分配。此功能需要上面的 语音键不再打开系统听写 保持开启。

  • 权限。 Utter 需要 输入监控 权限才能知道按下了哪个键。macOS 只会在你打开该开关时询问一次,在此之前不会申请。Utter 只匹配这支遥控器的设备,不会监听其他键盘,也不会把按键数据发出这台 Mac。允许后如果仍然不生效,请重启 Utter。
  • 安全规则。 只有在 Utter 能看到某个键的按下时,才会在设备层面关掉该键。没有权限或没有遥控器时,所有按键保持原有功能。
  • 限制。 被映射的按键每次按下只触发一次,按住不会重复。密码输入框获得键盘时,不会发送键盘快捷键和系统动作。“显示桌面”遵循你的 macOS 快捷键设置。Utter 处理音量键时,系统音量仍可能变化。

遇到问题时:

  • 关闭该开关,或执行 defaults write com.opentype.voiceinput remoteButtonMappingEnabled -bool false 后重新打开 Utter。
  • 如果 Utter 崩溃后遥控器按键没有反应,在系统设置 → 蓝牙中重新连接遥控器,或手动清除:hidutil property --matching '{"VendorID":10007,"ProductID":12984}' --set '{"UserKeyMapping":[]}'(这也会清掉语音键那一条,重新打开 Utter 会再次设置)。
  • 撤回权限:系统设置 → 隐私与安全性 → 输入监控 → 关闭 Utter,或执行 tccutil reset ListenEvent com.opentype.voiceinput。

常见问题

浏览器或 Electron 应用里听写的文字没有出现

在基于 Chromium 的应用里(如 Cursor 这类 Electron 应用,以及 Dia 这类 Chromium 浏览器),系统会接受对网页输入框的辅助功能直接写入并报告成功,但页面上什么都不会出现。对这类输入框,Utter 改用粘贴,所以必须开启 设置 → 通用 → 允许剪贴板粘贴;确认粘贴成功后,原来的剪贴板内容会被恢复。关闭该选项时,这类输入框不会被写入,Utter 提供显式的复制。

如果 Utter 无法确认粘贴是否生效,悬浮提示会说明无法确认写入,并提供复制文本。Utter 不会自行再写一次,请自己按 ⌘V 粘贴。

没有暴露 Chromium 辅助功能节点的输入框(例如 Safari 和 Firefox)不在此范围内,仍使用直接写入。

不重新安装就想回到之前的行为,可运行 defaults write com.opentype.voiceinput deliveryWebEditorPasteDisabled -bool true;恢复用 defaults delete com.opentype.voiceinput deliveryWebEditorPasteDisabled。对下一次听写生效;若没有生效,请重启 Utter。

更新后 Utter 打不开

如果更新过程中菜单栏图标消失,之后再点开 Utter 也没有反应,说明旧版本没有真正退出、还在后台运行,安装程序正在等它。强制退出一次即可:在活动监视器中选中 Utter 并选择强制退出,或在终端运行 pkill -9 -x Utter。随后更新会自动安装并重新打开 Utter;若没有打开,请再手动打开一次。

从 0.0.60 起,退出超过 5 秒仍未完成时会自行结束,并在系统日志(subsystem com.opentype.voiceinput,以 Shutdown exceeded 开头的消息)中写明是哪个部分拖住了退出。从更旧的版本更新时,仍可能需要上面这一次强制退出。

本地模型

以下模型都在你的 Mac 上运行。模型下载一次后,断网也能继续听写。

环节 模型 说明
语音识别 Qwen3-ASR 1.7B(推荐)、Confucius4-R2T2、FireRedASR2-AED、Mega-ASR、WhisperKit(large-v3-turbo … tiny)、Apple 语音识别(设备端) Qwen3-ASR 与 Confucius 通过原生 Swift + MLX 运行;FireRed、Mega-ASR 通过 MLX 运行;Apple 语音强制设备端识别
文字整理(LLM) Qwen3.5 0.8B / 2B(默认) / 9B / 35B-A3B、Qwen3 0.6B–30B-A3B、Qwen2.5、Gemma 4 E2B / E4B、Gemma 3 1B / 4B / 12B 基于 Apple Silicon 上的 MLX;实验性的 ANE-LM 运行时可运行本地 Qwen3 模型;也可以添加自己的 MLX 模型

远程选项需要手动开启:豆包(火山引擎)语音识别和下方的远程 LLM 服务商会把音频或文本发送给对应服务商。

远程 LLM 服务商

Utter 同时支持 OpenAI 兼容 和 Anthropic 两种 API 格式:

服务商 API 格式 接口地址
OpenAI OpenAI https://api.openai.com/v1
Anthropic Claude Anthropic https://api.anthropic.com/v1
Google Gemini OpenAI https://generativelanguage.googleapis.com/v1beta/openai
OpenRouter OpenAI https://openrouter.ai/api/v1
硅基流动 OpenAI https://api.siliconflow.cn/v1
火山引擎豆包 OpenAI https://ark.cn-beijing.volces.com/api/v3
阿里百炼 OpenAI https://dashscope.aliyuncs.com/compatible-mode/v1
MiniMax(国内) OpenAI https://api.minimax.chat/v1
MiniMax(海外) OpenAI https://api.minimaxi.chat/v1

本地语音识别服务商

服务商 本地运行方式 默认模型
Qwen3-ASR Apple Silicon 上的原生 Swift 与 MLX mlx-community/Qwen3-ASR-1.7B-bf16

Qwen3-ASR 不调用托管识别 API。应用将模型下载到共享模型存储目录, 通过原生 Swift 与 MLX 在本机运行。

项目结构

全部内置功能通过插件装配,可替换契约提供者并按配置组合。 参见插件组合和本地语音评测。

Sources/
├── App/                       # 应用启动与退出
├── UtterRuntime/              # 插件依赖图与生命周期
├── UtterContracts/            # 共享服务、值与本地化
├── UtterMediaContracts/       # 识别、处理与图像契约
├── UtterPresentationContracts/ # UI 投影与界面贡献
├── UtterData/                 # 设置、历史、词库与组合配置
├── UtterModels/               # 资产租约、下载与模型生命周期
├── UtterProcessing/           # 提示词、处理与保真检查
├── UtterSession/              # 共享会话与交付协调
├── UtterIngress/              # Fn、遥控麦克风、HTTP 与 XPC
├── UtterPresentation/         # 菜单、设置、引导、HUD 与界面资源
├── UtterBuiltins/             # 内置插件注册与应用装配
└── Utter*/                    # 音频、macOS、识别与推理提供者

构建与验证脚本统一放在 scripts/。build-app.sh 构建发布应用与安装包; evaluate-voice.sh 使用已安装模型运行生产处理路径,不向光标写入结果。

技术栈

  • WhisperKit — 离线 Whisper 语音识别
  • mlx-swift-lm — Apple Silicon 本地 LLM 推理(Qwen3.5 / Qwen3 / Gemma)
  • SwiftUI + AppKit — macOS 原生 UI
  • ScreenCaptureKit + Vision — 屏幕 OCR
  • AVAudioEngine — 低延迟麦克风采集
  • Apple Speech Framework — 系统语音识别
  • MLX 上的 Qwen3-ASR / FireRedASR2 / Mega-ASR — 本地语音识别

License

MIT


专为 Apple Silicon 打造