Command reference

All commands print compact JSON lines by default. Use --json to ensure the final summary is printed (default for most commands).

maclisten locales

List the locales supported by the system’s SFSpeechRecognizer.

maclisten locales

Output fields

Example

{"count":63,"locales":["ar-SA","ca-ES","cs-CZ","da-DK","de-AT",...,"zh-CN","zh-HK","zh-TW"],"ok":true}

maclisten file <path>

Transcribe an audio file.

maclisten file ./recording.wav
maclisten file ./recording.m4a --locale zh-CN --on-device
maclisten file ./recording.m4a --cn --on-device
maclisten file ./recording.m4a --fr --on-device

# Multiple locales → run each, return the highest-confidence result
maclisten file ./clip.m4a --locale zh-CN --locale en-US
maclisten file ./clip.m4a --cn --en                 # shortcuts work too
maclisten file ./clip.m4a --cn --en --no-pick       # one JSON line per locale

Supported formats — any audio file Apple’s AVFoundation can decode: .wav, .m4a/.aac, .mp3, .caf, .aiff, and audio tracks from .mov/.mp4. PCM WAV and AAC/M4A are the most reliable.

Multi-locale (auto language pick)

Apple’s Speech framework is single-locale with no language-detection step. When a recording’s language is uncertain, pass a short candidate list (your guesses). file runs each and, by default, returns the highest-confidence result with a candidates scoreboard. The caller chooses the candidates — maclisten never iterates every supported locale.

# best-confidence winner (default)
maclisten file ./clip.m4a --locale zh-CN --locale en-US

# let an agent / jq judge instead
maclisten file ./clip.m4a --locale zh-CN --locale en-US --no-pick | jq -s 'max_by(.confidence)'

Confidence is a recognizer heuristic (mean of per-segment confidences), not a true language ID — wrong-locale recognition can still hallucinate, so keep candidates plausible.

Options

Output fields

maclisten mic

Record from the microphone and transcribe.

maclisten mic --timeout 5
maclisten mic --auto-stop --auto-stop-silence 3.0
maclisten mic --partial --output ./note.wav
maclisten mic --hk --partial
maclisten mic --de --partial

Options

Output fields

Partial output (--partial)

{"ok":true,"partial":true,"text":"hello"}
{"ok":true,"partial":true,"text":"hello world"}
{"ok":true,"locale":"en-US","onDevice":false,"timeout":10.0,"text":"hello world","recordedSeconds":2.1}

maclisten watch

Continuously listen for voice keywords or commands. Restarts recognition sessions automatically so it can run until you press Ctrl-C or Ctrl-D.

maclisten watch
maclisten watch --keyword "computer" --partial
maclisten watch --output ./stream.wav
maclisten watch --cn --keyword "电脑"
maclisten watch --fr --keyword "ordinateur"

Options

Output fields

Segment output

When a segment is captured, a JSON line is emitted immediately:

{"ok":true,"segment":"computer open safari"}

When stopped, a log line is emitted:

{"ok":true,"event":"stopped","reason":"Ctrl-C"}

maclisten auth

Open System Settings to the Speech Recognition and Microphone privacy panes.

maclisten auth

Output fields

Common error fields

When a command fails, the output contains:

Common causes:

• Speech Recognition permission not granted — run maclisten auth, grant access to your terminal, then retry.
• Microphone permission not granted — required for mic and watch.
• Running from a bare CLI process — TCC cannot grant access to processes without a terminal app bundle. Use Terminal.app / iTerm / Warp.
• Unsupported locale — run maclisten locales to see valid identifiers.