macOS 本地语音

在 macOS 上完全离线运行的语音转文本（STT）与文本转语音（TTS）。无需 API 密钥、不依赖网络、不连接云端。所有处理均在设备本地完成。

系统要求

• macOS（推荐 Apple Silicon，Intel 处理器也可用）
• yap CLI 已加入 PATH — 可通过 brew install finnvoor/tools/yap 安装
• ffmpeg 已加入 PATH（可选，仅在生成 ogg/opus 格式输出时需要）— brew install ffmpeg
• say 和 osascript 为 macOS 系统内置命令

语音转文本（STT）

使用 Apple 设备端语音识别功能，将音频文件转录为文本。

node {baseDir}/scripts/stt.mjs  [locale]

• audio_file：音频文件路径（支持 ogg、m4a、mp3、wav 等格式）
• locale：可选参数，例如 zh_CN、en_US、ja_JP；若省略，则使用系统默认语言环境
• 将转录后的文本输出至 stdout

支持的 STT 语言环境

运行 node {baseDir}/scripts/stt.mjs --locales 可列出所有支持的语言环境。

常用语言环境：en_US、en_GB、zh_CN、zh_TW、zh_HK、ja_JP、ko_KR、fr_FR、de_DE、es_ES、pt_BR、ru_RU、vi_VN、th_TH。

语言检测建议

• 若用户近期消息主要为中文 → 使用 zh_CN
• 若为英文 → 使用 en_US
• 若混合使用或无法判断 → 可省略 locale 参数，交由系统默认语言环境处理

文本转语音（TTS）

利用 macOS 原生 TTS 功能，将文本转换为音频文件。

node {baseDir}/scripts/tts.mjs "" [voice_name] [output_path]

• text：待朗读的文本内容
• voice_name：可选参数，例如 Yue (Premium)、Tingting、Ava (Premium)；若省略，将根据文本语言自动选择最匹配的可用语音
• output_path：可选参数，若未指定，默认保存至 ~/.openclaw/media/outbound/ 下带时间戳的文件
• 将生成的音频文件路径输出至 stdout
• 若系统中已安装 ffmpeg，输出格式为 ogg/opus（适用于各类消息平台）；否则为 aiff 格式

作为语音消息发送

生成音频文件后，使用 message 工具发送：

message action=send media= asVoice=true

语音管理

列出可用语音、检查语音就绪状态，或为指定语言查找最优语音：

node {baseDir}/scripts/voices.mjs list [locale]     # 列出所有语音，可选按 locale 过滤
node {baseDir}/scripts/voices.mjs check ""     # 检查指定语音是否已下载并就绪
node {baseDir}/scripts/voices.mjs best        # 获取指定 locale 下质量最高的语音

语音质量等级

• 1 = compact（低质量，始终可用）
• 2 = enhanced（中等质量，可能需手动下载）
• 3 = premium（最高质量，需通过「系统设置 → 辅助功能 → 听觉 → 系统语音 → 管理语音」手动下载）

若语音不可用

提示用户：“语音 X 尚未下载。请前往 系统设置 → 辅助功能 → 听觉 → 系统语音 → 管理语音 下载该语音。”

注意事项

• say 命令在请求的语音不可用时会静默回退至默认语音（返回码为 0，无错误提示）。因此，在调用 tts.mjs 并指定 voice_name 前，务必先执行 voices.mjs check 进行校验。
• 高级语音（如 Yue (Premium)、Ava (Premium)）音质显著更优，但需用户手动下载。
• Siri 语音无法通过系统语音合成 API 访问。