VoiceInk：开源 macOS 语音转文字应用全指南——核心功能、安装方式与源码构建

• 桌面应用
• 人工智能
• 语音
• 本地部署

VoiceInk 是一款面向 macOS 的原生语音转文字应用，致力于把语音"几乎即时"地转换为文本，并以 100% 离线处理为隐私底线，被官方定位为 Superwhisper 与 Wispr Flow 的开源替代方案。本文以仓库根目录的 README.md 为主线，完整梳理 VoiceInk 的功能特性、获取与安装方式、从源码构建的完整流程（含签名、Entitlements 与发布机制），并深入到 Makefile、BUILDING.md、scripts/release.sh 等仓库文件，帮助你在读完本文后既能快速上手使用，也能独立完成本地构建、甚至理解其发布与更新体系。

项目定位：macOS 上的开源语音转文字方案

VoiceInk 由开发者 Pax 在投入 5 个月开发后开源（GPL v3），定位是"面向 macOS 的最高效、隐私优先的语音转文字解决方案"。README 中明确的核心主张包括：99% 准确率的本地 AI 转写、100% 离线处理（数据不离开设备）、按应用/URL 自动切换预设配置的智能模式（Modes），以及内置 AI 助手与个人词典训练能力。

说明：README 中"99% 准确率"属于官方宣传口径，实际准确率会随环境音、口音与所选模型不同而波动，读者应结合自身场景验证。

从仓库目录结构看，这是一个规模不小的 Swift 工程，代码按App、Core、DesignSystem、Features、Infrastructure等模块组织，其中Features下分列了 Recording、Transcription、Modes、Dictionary、Enhancement、History、ModelLibrary、Onboarding、Licensing、Assistant、AudioImport、Dashboard、Settings 等子模块，基本与 README 的功能清单一一对应。

核心功能特性一览

README 列出了 8 项核心特性，下面逐一展开，并给出仓库中的对应实现入口，便于深入研读。

1. 精准转写（Accurate Transcription）

本地 AI 模型将语音转写为文本，宣称"几乎即时"完成。仓库中模型能力分布在 Features/ModelLibrary/State 与 Infrastructure/Providers/Transcription 两处：

• Whisper（基于 whisper.cpp）：WhisperTranscriptionService.swift、LibWhisper.swift；
• TranscribeCpp（本地 GGUF 转写模型）：OfflineTranscribeCppService.swift；
• FluidAudio（Parakeet 模型）：FluidAudioTranscriptionService.swift；
• 云端供应商（AssemblyAI、Deepgram、OpenAI 兼容接口等）：CloudTranscriptionService.swift。

此外，Resources/models 下已附带ggml-silero-v5.1.2.bin（VAD 语音活动检测模型），用于录音时的人声起止检测。

2. 隐私优先（Privacy First）

README 强调 100% 离线处理、数据不出设备。支撑这一承诺的本地推理链路包括 Whisper/TranscribeCpp 的本地执行，以及应用沙箱配置：VoiceInk.entitlements 与 VoiceInk.local.entitlements 均关闭了 App Sandbox（com.apple.security.app-sandbox = false），仅按需开放麦克风（audio-input）、屏幕录制（screen-capture）、Apple Events（apple-events）与网络客户端/服务端权限。网络权限的存在主要是为了云端转写与自动更新，纯本地场景下数据不会外发。

3. 智能模式（Modes）

"应用感知"是 VoiceInk 的特色：它会根据当前所在应用或浏览器 URL 自动套用预配置的转写设置。对应实现：

• 模式配置模型：ModeConfig.swift、ModeRuntimeConfiguration.swift；
• 触发词/触发应用检测：ModeTriggerWordDetectionService.swift、TriggerInstalledApps.swift；
• 前置模板库：StarterModeFactory.swift、TriggerTemplateCatalog.swift。

4. 上下文感知（Context Aware）

智能 AI 会理解屏幕内容并自适应上下文，例如结合当前网页 URL 或屏幕画面提高转写/增强质量。实现入口：ActiveWindowService.swift、BrowserURLService.swift、ScreenCaptureService.swift、SelectedTextService.swift。Info.plist 中的NSAppleEventsUsageDescription与NSScreenCaptureUsageDescription正是为这些能力申请的权限说明。

5. 全局快捷键（Global Shortcuts）

支持可配置的键盘/鼠标快捷键，实现快速录音与按讲（push-to-talk）。实现位于 Features/Shortcuts（ShortcutMonitor.swift、ShortcutStore.swift），依赖 sindresorhus 的KeyboardShortcuts库。

6. 个人词典（Personal Dictionary）

可训练 AI 理解你的专属术语、行业词汇，并支持智能文本替换。实现位于 Features/Dictionary：DictionaryService.swift、WordReplacementService.swift，以及 Auto Learn 自动学习体系（AutoLearnService.swift 等），后者还支持通过本地 CLI 进行审查。

7. 智能模式切换（Smart Modes）

针对不同写作风格与上下文，可即时切换由 AI 驱动的增强模式。相关实现见 Features/Enhancement：AIEnhancementService.swift、PromptTemplates.swift、FillerWordManager.swift。

8. AI 助手（AI Assistant）

内置类似 ChatGPT 的语音对话助手。实现见 Features/Assistant：AssistantChatService.swift、AssistantSession.swift。

系统要求

根据 README 与 BUILDING.md，使用与构建的最低要求均为macOS 15.0 或更高版本；源码构建还需要 Xcode（含 Command Line Tools）与 Git。

获取与安装

通过 Homebrew 安装

README 提供了 cask 安装方式：

brew install --cask voiceink

这是获取编译版最快的方式，安装后可自动获得后续更新。

从官网下载

官方下载渠道提供带免费试用的最新版本；购买许可（License）用于支持持续开发，并解锁自动更新、优先支持（Discord 与邮件）及后续新功能。仓库中的 appcast.xml 即为 Sparkle 更新源，目前最新条目为版本 2.21（sparkle:shortVersionString为2.21，sparkle:minimumSystemVersion为15.0），其更新说明涵盖 Parakeet Ultra、OpenRouter 转写模型、GPT-6 Luna/Sol 增强模型、自定义 AI 增强模型 ID、双击录音快捷键等新能力。

从源码构建

作为开源项目，你也可以自行构建，详见下文。

从源码构建：完整实战指南

README 将构建细节指向 BUILDING.md，而真正的执行逻辑在 Makefile 中。下面按 Makefile 目标逐一拆解。

前置检查：make check / make healthcheck

make check验证三个必备工具是否存在，缺一即退出：

• git
• xcodebuild（需要安装 Xcode）
• swift

准备 Whisper 框架：make whisper

make whisper会在~/VoiceInk-Dependencies下准备whisper.xcframework：

• 创建~/VoiceInk-Dependencies目录；
• 若whisper.cpp不存在则克隆并执行其build-xcframework.sh脚本构建通用框架；已存在则git pull更新；
• 产物路径为~/VoiceInk-Dependencies/whisper.cpp/build-apple/whisper.xcframework。

make setup只是whisper的别名封装，并在完成后提示 Xcode 工程需引用该框架路径。

一键本地构建：make local

这是 BUILDING.md 推荐的本地构建入口：

git clone <VoiceInk 仓库地址> cd VoiceInk make local open ~/Downloads/VoiceInk.app

make local的完整行为（对照 Makefile 的local目标）：

1. 先执行check与setup（即确认工具链并准备 whisper.xcframework）；
2. 清空本地 DerivedData 目录.local-build；
3. 签名身份自动检测：调用security find-identity -v -p codesigning查找Apple Development身份。若恰好找到 1 个，则使用该身份；若找到多个，则提示设置LOCAL_CODESIGN_IDENTITY并回退到 ad-hoc 签名；若没有找到，直接使用 ad-hoc 签名（CODE_SIGNING_REQUIRED=NO）；
4. 以Release 配置执行xcodebuild，关键参数：

xcodebuild -project VoiceInk.xcodeproj -scheme VoiceInk -configuration Release \ -derivedDataPath "$(CURDIR)/.local-build" \ -xcconfig LocalBuild.xcconfig \ CODE_SIGN_IDENTITY="$SIGNING_IDENTITY" \ CODE_SIGNING_REQUIRED="$SIGNING_REQUIRED" \ CODE_SIGNING_ALLOWED=YES \ DEVELOPMENT_TEAM="" \ CODE_SIGN_ENTITLEMENTS="$(CURDIR)/VoiceInk/VoiceInk.local.entitlements" \ SWIFT_ACTIVE_COMPILATION_CONDITIONS='$(inherited) LOCAL_BUILD'

5. 将产物VoiceInk.app复制到~/Downloads，并用xattr -cr清除扩展属性（去除 quarantine 标记）。

指定签名身份

本地构建默认使用唯一的 Apple Development 身份，也可显式指定：

# 使用指定身份（SHA 或名称） make local LOCAL_CODESIGN_IDENTITY="<SHA or name>" # 强制 ad-hoc 签名 make local LOCAL_CODESIGN_IDENTITY=-

本地构建的已知限制

BUILDING.md 与 Makefile 的local目标输出都明确提示：

• 无 iCloud 词典同步（正式版依赖VoiceInk.entitlements中的 CloudKit/iCloud 能力）；
• 无自动更新（需重新拉取代码并重建）；
• ad-hoc 签名在重建后可能需要重新授予 macOS 权限（麦克风、屏幕录制等）。

其他常用目标

用 Xcode 构建

make setup open VoiceInk.xcodeproj

选择VoiceInkscheme：Run 会构建VoiceInk Dev.app，Archive 使用 Release 配置。注意LOCAL_BUILD编译条件仅在make local下生效，正常 Xcode 构建不会引入。

本地构建的配置与 Entitlements

LocalBuild.xcconfig 专为本地构建设计，要点如下：

CODE_SIGN_IDENTITY = - CODE_SIGN_STYLE = Manual DEVELOPMENT_TEAM = PROVISIONING_PROFILE_SPECIFIER = SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) LOCAL_BUILD

• 默认 ad-hoc 签名，make local在检测到 Apple Development 身份时会覆盖；
• LOCAL_BUILD编译条件供 Swift 代码用#if LOCAL_BUILD分支处理本地构建差异。从源码看，该标志在 App/VoiceInk.swift、LicenseViewModel.swift、KeychainService.swift、OnboardingCoordinator.swift 等文件中均有使用，主要影响许可校验、Keychain 访问与 iCloud 初始化等行为。

本地与正式版的 Entitlements 差异非常明显：

• VoiceInk.local.entitlements：仅含麦克风、屏幕录制、Apple Events、网络客户端/服务端、关闭库校验等基础能力，不含iCloud/CloudKit；
• VoiceInk.entitlements：额外包含com.apple.developer.aps-environment（推送）、iCloud.com.prakashjoshipax.VoiceInkCloudKit 容器、keychain-access-groups（com.prakashjoshipax.VoiceInk的钥匙串访问组）以及两个mach-lookup临时例外（与 Sparkle 安装器服务相关）。

发布与自动更新流程（make release）

若你计划发布自己的版本，仓库提供了完整的自动化发布脚本 scripts/release.sh。其流水线为：

1. 归档：xcodebuild archive（Release 配置，产物VoiceInk.xcarchive）；
2. 导出：按 release/ExportOptions.plist 导出 Developer ID 签名的VoiceInk.app；
3. 一致性校验：核对 Bundle ID（com.prakashjoshipax.VoiceInk）、Sparkle 更新源 URL、最低系统版本（15.0）与数值型构建号；
4. 签名与公证：codesign --verify --deep --strict验证，notarytool submit提交并stapler staple公证；
5. 打包 DMG：基于 release/dmg/layout.conf（含背景图、窗口位置、图标布局参数）与 release/dmg/background.tiff、release/dmg/volume-icon.icns 生成 DMG，随后对 DMG 签名与公证，并通过hdiutil verify+ 挂载校验内容；
6. 生成 Appcast：使用 Sparkle 的generate_appcast生成 appcast.xml，用sign_update校验 EdDSA 签名，并用xmllint逐字段比对版本号、URL、长度与签名，最后输出 DMG 的 SHA-256。

脚本常用参数（scripts/release.sh --help可查看完整说明）：

make release # 全流程发布（默认 release-notes/<版本>.html） make release NOTES=release-notes/2.21.html scripts/release.sh --app /path/to/VoiceInk.app --notes /path/to/notes.html --skip-notarization --allow-dirty

关键环境变量（均有默认值）：VOICEINK_DEVELOPER_IDENTITY（Developer ID 身份名）、VOICEINK_NOTARY_PROFILE（公证 Keychain profile）、VOICEINK_RELEASE_BASE_URL（下载 URL 前缀）、VOICEINK_RELEASE_OUTPUT_ROOT（输出目录）、VOICEINK_WHISPER_FRAMEWORK（whisper.xcframework 路径）等。注意脚本默认要求 Git 工作区干净（可加--allow-dirty跳过），且不会自动提交、打 tag 或创建 GitHub release。

仓库源码结构导航

• App：应用入口（VoiceInk.swift）、菜单栏、窗口管理、快捷键/快捷指令（App Intents）、启动项、通知与更新；
• Core：转写引擎错误类型、录音状态、AI 增强输出过滤等核心类型；
• Features：上述全部业务功能（转写、模式、词典、增强、历史、模型库、引导、许可、助手等）；
• Infrastructure：底层支撑——录音与音频设备、供应商实现（转写/增强）、持久化与迁移、系统集成（剪贴板、光标粘贴、媒体控制、屏幕捕获）、隐私混淆、备份/导入导出；
• DesignSystem：主题、组件与布局（AppTheme、FlowLayout、Markdown 渲染等）；
• VoiceInkRefineXPC：本地增强推理的 XPC 服务（与 Shared/VoiceInkRefineXPCProtocol.swift 及客户端 VoiceInkRefineXPCClient.swift 配套）。

许可证、贡献与致谢

• 许可证：GNU GPL v3，详见 LICENSE；
• 贡献方式：项目当前不接受 Pull Request，但欢迎 fork 自用，或通过 issue 报告 bug、建议功能、改进文档，详见 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md；
• 核心转写技术：whisper.cpp（OpenAI Whisper 的高性能推理实现）、FluidAudio（用于 Parakeet 模型）、TranscribeCpp for Swift（本地 GGUF 转写模型）、SenseVoice Small（FunAudioLLM / 阿里的多语言模型）；
• 关键依赖：Sparkle（自动更新）、KeyboardShortcuts（可配置快捷键）、LaunchAtLogin（登录自启）、MediaRemoteAdapter（录音时控制媒体播放）、Zip（压缩解压）、SelectedTextKit（获取选中文本）、Swift Atomics（线程安全原子操作）。

小结

VoiceInk 的价值在于把"本地、隐私优先"的语音转文字体验做成了完整可用的 macOS 应用，并开源了从功能实现到发布流水线的全套代码。对普通用户，可经 Homebrew 一行安装体验；对开发者，则可通过make local快速本地构建，通过LOCAL_BUILD编译条件、两套 Entitlements 与make release发布脚本理解一个 macOS 商业级应用在签名、公证、自动更新上的工程化实践。若要在离线、隐私敏感场景下搭建自己的语音输入方案，VoiceInk 是一个可以直接上手、深度定制的开源起点。

• 桌面应用
• 人工智能
• 语音
• 本地部署