Mac ASR + Translate

English | 中文 | Deutsch

A Codex Agent Skill and native macOS CLI for transcribing local audio or video with Apple Speech and translating the result with Apple Translation.

The tool keeps speech recognition on-device by default, supports timestamped JSON, SRT, VTT, and bilingual subtitle output, and does not require a cloud API key.

Requirements

• macOS 15 or newer for Apple Speech transcription
• macOS 26 or newer for direct Apple Translation
• Xcode Command Line Tools
• Installed Dictation language assets for on-device recognition
• Installed Apple Translation models for the requested language pair

Language support

• Speech recognition: Apple Speech exposes locales dynamically. On the test macOS 27 machine, locales reports 62 locales, including regional variants such as en-US, en-GB, zh-CN, zh-TW, ja-JP, and de-DE. The exact list depends on the macOS installation and downloaded Dictation assets.
• Translation: the common target set contains 19 languages: Simplified Chinese, Traditional Chinese, English, German, Japanese, Korean, French, Spanish, Italian, Portuguese, Russian, Turkish, Polish, Indonesian, Thai, Vietnamese, Arabic, Hindi, and Ukrainian.
• The CLI delegates translation to Apple Translation, so the actually usable source/target pairs depend on the macOS version and installed system language models. Check with doctor --source-lang <locale> --target-lang <language> before a long run.

List the Speech locales available on the current Mac:

bin/mac-asr-translate locales --format text

Quick start

Check the current environment:

bin/mac-asr-translate doctor \
  --source-lang en-US \
  --target-lang zh-Hans

Transcribe an audio or video file:

bin/mac-asr-translate transcribe recording.m4a \
  --source-lang en-US \
  --format json

Translate text with Apple Translation:

bin/mac-asr-translate translate "Good morning" \
  --source-lang en \
  --target-lang zh-Hans

Create bilingual subtitles:

bin/mac-asr-translate run talk.mp4 \
  --source-lang en-US \
  --target-lang zh-Hans \
  --format srt \
  --bilingual \
  --output talk.zh-Hans.srt

Run bin/mac-asr-translate --help for all options.

Use as a Codex Skill

Reference the included SKILL.md, or install/link this directory into your Codex skills directory. Then ask Codex to use $mac-asr-translate with a local media file.

Example prompt:

Use $mac-asr-translate to transcribe talk.mp4 locally and create bilingual Chinese subtitles.

Privacy

On-device Apple Speech is required by default. The CLI only permits server-backed Apple Speech when --allow-server is explicitly supplied. Apple Translation uses installed system models.

Review proper nouns, numbers, code-switching, and subtitle timing before delivering captions as final.

Documentation

• Skill instructions
• Setup and error recovery
• Output schema and subtitle formats