Mac command line · Product-demo narration

Rebuild a demo voiceover in your own voice.

Keep your script and timings in a CSV. Use a saved cloned voice to turn it into one audio track, then render it again whenever the demo changes.

SpeechTrack’s Mac app includes a CLI that runs locally without opening an app window. It fits repeatable product walkthroughs, slide narration, and training clips where you want to update the words without recording every line again.

Build your first voiceover Watch the presentation tutorial

Step 1 · Set up once

Install the Mac app and save a voice.

Install SpeechTrack on a supported Apple-silicon Mac. Open Voice Library → New Voice, record or import 5–15 seconds of clear English speech, give the voice a name, and save it. You can also use the independent voice saved in Voice Studio.

The CLI reads voices saved on this Mac. Voice creation and management happen in the app; there is no CLI enrollment command.

In Terminal, check the available commands. These examples assume the app is installed at /Applications/SpeechTrackMac.app; adjust the path if needed.

"/Applications/SpeechTrackMac.app/Contents/MacOS/SpeechTrackMac" --cli help

For the shorter commands below, add this alias to ~/.zshrc, then open a new Terminal window or run source ~/.zshrc:

alias speechtrack='"/Applications/SpeechTrackMac.app/Contents/MacOS/SpeechTrackMac" --cli'

Step 2 · Pick the speaker

List your voices and try a short line.

speechtrack voices
speechtrack voices --json

Each voice has a name and a scoped selector: library:UUID for Voice Library or studio:UUID for Voice Studio. JSON output contains selector, scope, and name fields.

Replace My Voice below with your voice’s unique display name. Keep names with spaces in quotes.

speechtrack say --acknowledge-voice-use --voice "My Voice" \
  "Welcome to the demo."

say generates and plays the phrase through your Mac. It still plays audio if you also request an output file. Press Ctrl-C to cancel generation or playback.

For scripts or duplicate names, use the exact scoped selector from your own voice listing in place of My Voice. Names and selectors are case-insensitive. Omit --voice only when exactly one voice exists across both stores; a Library voice copied to Studio can appear twice.

Step 3 · Write the walkthrough

Put three demo moments on a timeline.

Export a CSV from a SpeechTrack project, or save this example as a UTF-8 file named segments.csv in your working directory. These illustrative lines introduce a demo, show an action, and close with the result.

text_readable,start_time_readable,voice_id_internal,rate_readable,pitch_readable,volume_readable,header_gap_readable,footer_gap_readable
"Welcome to the demo.",00:00:00.000,,0.5,1,1,00:00:00.000,00:00:00.500
"Choose a project to begin.",00:00:05.000,,0.5,1,1,00:00:00.250,00:00:00.000
"Your audio is ready to share.",00:00:10.000,,0.5,1,1,00:00:00.000,00:00:01.000

The six columns from text_readable through volume_readable are required. Keep voice_id_internal even when its values are empty. The two gap columns are optional and default to zero; start times and gaps use HH:MM:SS.mmm.

Each row retains its speed, pitch, volume, and leading or trailing silence, including the final footer gap. The CLI’s selected cloned voice overrides the voice on every row, including Apple system voices and any voice_kind or voice_profile_id values in a project export.

Step 4 · Export and repeat

Render the narration without playback.

speechtrack render --acknowledge-voice-use --voice "My Voice" \
  --input - --output - --format m4a < segments.csv > demo.m4a

This writes one demo.m4a file in the current directory without playing it. Import it into your video or presentation editor. When the product changes, edit the CSV and rerun the command to replace the narration file.

By default, a segment that would overlap earlier audio or its gaps moves later. Listen and check the timing against your visuals. Shorten a line or adjust its timing if needed. --allow-overlaps keeps the requested start times, which can make spoken segments overlap.

Use the full path in scripts

Shell aliases are for interactive Terminal use. For a repeatable script, invoke the executable directly with --cli. Replace the illustrative selector below with your voice’s exact selector from voices --json:

"/Applications/SpeechTrackMac.app/Contents/MacOS/SpeechTrackMac" --cli render \
  --acknowledge-voice-use --voice "library:01234567-89ab-cdef-0123-456789abcdef" \
  --input - --output - --format wav < segments.csv > demo.wav

Commands and options at a glance

Run speechtrack help to check the commands supported by your installed app.

SpeechTrack Mac CLI commands
Command	Use it for
`help`	Read usage and the full voice-use declaration.
`voices [--json]`	List saved cloned voices, as text or a JSON array.
`say`	Generate and play a quoted text argument; optionally save audio too.
`render`	Export a timed CSV as one audio file without playback.

Options for the narration workflow
Option	Applies to	Behavior
`--acknowledge-voice-use`	`say`, `render`	Required each time; acknowledges the voice-use declaration.
`--voice NAME_OR_SELECTOR`	`say`, `render`	Choose a saved cloned voice. Required unless exactly one is available.
`--input PATH`	`render`	CSV input. `-` reads stdin and is the default when omitted.
`--output PATH`	`say`, `render`	Write audio to an accessible path, or `-` for stdout. `say` without output only plays audio.
`--format m4a\|wav\|aiff`	`say`, `render`	Required with `--output -`. With a path, infer from its extension; an explicit format must match. Without either an extension or explicit format, defaults are WAV for `say` and M4A for `render`. MP3 is unsupported.
`--allow-overlaps`	`render`	Retain requested start times instead of shifting overlapping segments later.

Free use and SpeechTrack Pro

Free say use shares Voice Studio’s 30 seconds of generated speech per day on this device. It checks the estimated phrase length against the remaining allowance and records the generated duration.

Free render use allows 30 seconds of estimated speech per output. Timeline silence does not count toward that limit. Free users can keep one cloned voice.

SpeechTrack Pro Lifetime removes both speech limits and the saved cloned-voice limit with a one-time purchase. Purchase or restore Pro in the Mac app using the Apple Account that owns it.

If the export doesn’t work

Executable or voice not found: Check the app path, save a voice on this Mac, and rerun speechtrack voices --json. For ambiguous names, use the exact scoped selector. Recreating a deleted voice changes its selector.
CSV validation or file access error: Check the reported rows, six required columns, numeric values, and time fields. Use shell redirection for file access and confirm the source exists and the destination directory is writable.
Free speech limit reached: For say, check the shared Studio daily allowance. For render, shorten the script’s speech or restore Pro in the app.

For automation, exit status 0 means success; 64 is a usage error, 65 invalid CSV, 66 a missing or ambiguous voice, 74 a file access error, 77 a free speech limit, and 130 cancellation. Other runtime failures return 70.

Help, errors, and terminal progress go to stderr. Voice listings and audio requested with --output - go to stdout. Only use an exported file after a successful command.

CLI examples checked October 19, 2026. For your installed build’s usage, run speechtrack help.