macOS Local Voice

Fully local speech-to-text (STT) and text-to-speech (TTS) on macOS. No API keys, no network, no cloud. All processing happens on-device.

Requirements

• - macOS (Apple Silicon recommended, Intel works too)
• INLINECODE0 CLI in PATH — install via INLINECODE1
• INLINECODE2 in PATH (optional, needed for ogg/opus output) — INLINECODE3
• INLINECODE4 and osascript are macOS built-in

Speech-to-Text (STT)

Transcribe an audio file to text using Apple's on-device speech recognition.

CODEBLOCK0

• - audio_file: path to audio (ogg, m4a, mp3, wav, etc.)
• INLINECODE7: optional, e.g. zh_CN, en_US, ja_JP. If omitted, uses system default.
• Outputs transcribed text to stdout.

Supported STT locales

Use node {baseDir}/scripts/stt.mjs --locales to list all supported locales.

Key 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.

Language detection tips

• - If the user's recent messages are in Chinese → use INLINECODE26
• If in English → use INLINECODE27
• If mixed or unclear → try without locale (system default)

Text-to-Speech (TTS)

Convert text to an audio file using macOS native TTS.

CODEBLOCK1

• - text: the text to speak
• INLINECODE29: optional, e.g. Yue (Premium), Tingting, Ava (Premium). If omitted, auto-selects the best available voice based on text language.
• INLINECODE33: optional, defaults to a timestamped file in INLINECODE34
• Outputs the generated audio file path to stdout.
• If ffmpeg is available, output is ogg/opus (ideal for messaging platforms). Otherwise aiff.

Sending as voice note

After generating the audio file, send it using the message tool:

CODEBLOCK2

Voice Management

List available voices, check readiness, or find the best voice for a language:

CODEBLOCK3

Quality levels

• - 1 = compact (low quality, always available)
• 2 = enhanced (mid quality, may need download)
• 3 = premium (highest quality, needs download from System Settings)

If a voice is not available

Tell the user: "Voice X is not downloaded. Go to System Settings → Accessibility → Spoken Content → System Voice → Manage Voices to download it."

Notes

• - The say command silently falls back to a default voice if the requested voice is not available (exit code 0, no error). Always use voices.mjs check before calling tts.mjs with a specific voice name.
• Premium voices (e.g. Yue (Premium), Ava (Premium)) sound significantly better but must be manually downloaded by the user.
• Siri voices are not accessible via the speech synthesis API.