Command line (tx)

The tx command lets you transcribe audio and video files from Terminal, shell scripts and automation tools. It uses the same models and settings as the app and runs entirely on your Mac.

Set up tx

1. Open TranscribeX at least once, so its settings and models exist. The command line reads them.
2. Open Settings › Advanced and turn on Enable Command Line. This creates a link at ~/.local/bin/tx pointing to the tool inside the app.
3. Make sure ~/.local/bin is on your PATH. TranscribeX doesn’t change your shell settings. For zsh (the macOS default), run:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

   Then open a new Terminal window.
4. Check it works:

   tx models

The How to Use button next to the switch shows a short usage summary you can copy. To remove the command, turn off Enable Command Line.

Commands

tx models

Lists each available model with its id, name, type, volume (size), description and supported languages as [id, label] pairs. Use the id values with --model and --language.

{
  "models" : [
    {
      "description" : "Latest multilingual model. Slow but highest accuracy. Supports 100+ languages.",
      "id" : "large_v3",
      "languages" : [["auto", "Auto Detect"], ["af", "Afrikaans"], ...],
      "name" : "Large V3",
      "type" : "whisper",
      "volume" : "3.1 GB"
    }
  ]
}

tx transcribe

tx transcribe <path> [--flag value ...]

Put the file path first. Every flag is optional.

True values are true, yes, y and 1; anything else is false. A flag with no value counts as true, but only if the next word starts with -- or is the end of the line. Writing tx transcribe --should-diarize file.mp3 would read file.mp3 as the flag’s value, so put the path first or give an explicit value.

Accepted files

• Audio: mp3, wav, m4a, aac, flac, ogg, wma, aiff
• Video: mp4, mov, avi, mkv, flv, wmv, m4v, webm

Output

On success, tx transcribe prints a JSON object to standard output:

The transcript is always inside the JSON. Redirecting output with > file.srt gives you JSON, not an SRT file. Use --export-file to write the file itself.

Errors

On failure, tx prints {"error": "..."} to standard error and exits with code 1. Common messages:

• Unknown model: ...: the id or name doesn’t match any model. Check tx models.
• Model is not downloaded: ...: download it in the app first.
• Model is not available for the current license: ...: it’s a Pro model. Activate Pro in the app, or use a free model. See Free vs Pro.
• Language '...' is not supported by model '...': pick a language id from that model’s list.
• No available transcription model...: download a model in the app.
• Source file must be an audio or video file: the extension isn’t in the list above.
• PDF export requires --export-file.
• TranscribeX store does not exist: ...: open the app once first.

What the command line doesn’t do

To keep scripts predictable, tx skips the app’s automatic extras: AI title and description, automatic summaries, auto-export and notifications. Your app settings aren’t changed.

Examples

Transcribe with the app’s default model and print the text:

tx transcribe ~/Desktop/audio.mp3

Save a Markdown transcript:

tx transcribe ~/Desktop/audio.mp3 --export-format markdown --export-file ~/Desktop/transcript.md

Subtitles with speakers, using Whisper Large V3 in English (Pro):

tx transcribe ~/Desktop/meeting.m4a --model large_v3 --language en --should-diarize true --export-format srt --export-file ~/Desktop/meeting.srt

A segmented PDF with timestamps:

tx transcribe ~/Desktop/interview.mov --export-format pdf --display-mode segments --export-file ~/Desktop/interview.pdf

Keep the job so you can edit it in the app:

tx transcribe ~/Desktop/call.mp4 --should-persist-job true

Get only the text, using jq (install it separately, for example with Homebrew):

tx transcribe ~/Desktop/audio.mp3 | jq -r .content

Script: subtitles for a whole folder

This zsh script writes an .srt file next to every audio and video file in a folder, and skips files that already have one. Save it as transcribe-folder.zsh and run zsh transcribe-folder.zsh ~/Recordings.

#!/bin/zsh
setopt null_glob extended_glob

dir="${1:-.}"

for f in "$dir"/*.(#i)(mp3|wav|m4a|aac|flac|ogg|wma|aiff|mp4|mov|avi|mkv|flv|wmv|m4v|webm); do
  out="${f:r}.srt"
  if [[ -e "$out" ]]; then
    echo "Skipping $f (already has subtitles)"
    continue
  fi
  echo "Transcribing $f"
  if ! tx transcribe "$f" --export-format srt --export-file "$out" > /dev/null; then
    echo "Failed: $f" >&2
  fi
done

Files are transcribed one at a time. Errors are printed and the loop moves on to the next file. For watched folders inside the app, see bulk transcription.