apple-native-transcribe

name	apple-native-transcribe
description	Transcribe local audio files with Apple's native SpeechAnalyzer and SpeechTranscriber APIs using the installed apple-native-transcribe CLI. Use when a task needs on-device speech-to-text for local audio on macOS 26 or newer. Prefer installing with brew install mweinbach/max-skills/apple-native-transcribe. Do not use on Linux, Windows, or macOS versions earlier than 26.

Apple Native Transcribe

Use this skill only on macOS 26 or newer. Keep the contract simple: pass an input file, an output directory, and a format. Treat everything else as debug-only.

Ensure Installed

Before using the CLI, make sure apple-native-transcribe is available on PATH.

Preferred install path:

brew install mweinbach/max-skills/apple-native-transcribe

If you are working inside this repo checkout and want the skill to install the CLI for you, run:

bash ./apple-native-transcribe/scripts/ensure-installed.sh

ensure-installed.sh tries the Homebrew tap install first and only falls back to a repo-local build if Homebrew is unavailable or the tap install fails.

Do this as part of the skill flow. Do not ask the user to perform the install step manually unless the install fails.

Primary command

Use the installed command:

apple-native-transcribe --input "/abs/path/audio.mp3" --output-dir "/abs/path/out" --format json

Or use positional arguments:

apple-native-transcribe "/abs/path/audio.mp3" "/abs/path/out" json

Formats:

• json
• text
• srt

Output contract

The CLI writes:

• the requested transcript file into the output directory
• transcript.debug.json into the same directory

It also prints a JSON manifest to stdout with:

• transcriptFile
• debugFile
• format
• localeIdentifier
• segmentCount

Read the manifest first, then open the written files if you need the transcript contents.

Debug flags

Only use these when the default behavior is not enough:

• --debug-locale <locale-id>
• --debug-install-assets
• --debug-prewarm
• --debug-preset <transcription|alternatives|timeIndexed|progressive|timeIndexedProgressive>
• --debug-context <phrase>

Examples:

apple-native-transcribe \
  --input "/abs/path/audio.mp3" \
  --output-dir "/abs/path/out" \
  --format json \
  --debug-install-assets \
  --debug-locale en_US

apple-native-transcribe --list-locales

Packaging Notes

• The CLI only supports macOS 26 or newer and uses Apple's SpeechAnalyzer + SpeechTranscriber APIs from the macOS 26 Speech framework.
• Local install helper: bash ./apple-native-transcribe/scripts/install-system-wide.sh
• Homebrew/package prep script: bash ./apple-native-transcribe/scripts/prepare-homebrew-release.sh --version <version> --github-owner <owner> --github-repo <repo>
• Homebrew formula path: Formula/apple-native-transcribe.rb
• The first run for a locale may need on-device asset installation. Use --debug-install-assets if the CLI reports missing assets.
• Prefer json when another model or tool will consume the transcript.
• If you change the Swift package and want to refresh the installed command, re-run bash ./apple-native-transcribe/scripts/install-system-wide.sh.