Typecast CLI

The Typecast CLI (cast) lets you convert text to speech right from your terminal. Play audio instantly, save to files, browse voices interactively, and control emotions — all without leaving the command line. Requires a Typecast API key.

Installation

Install

Homebrew
Go

brew install neosapience/tap/cast

go install github.com/neosapience/cast@latest

cast login

You’ll be prompted to enter your API key. Get yours at Typecast API Console.You can also pass it directly:

cast login <api_key>

Verify

cast "Hello, world!"

If you hear audio playback, you’re all set!

For API details, see Typecast API Console.

Quick Start

# Play immediately
cast "Hello, world!"

# Use a specific voice
cast "Hello, world!" --voice-id tc_xxx

# Save to WAV file
cast "Hello, world!" --out hello.wav

# Save to MP3 file
cast "Hello, world!" --out hello.mp3 --format mp3

By default, cast plays audio immediately. Use the --out flag to save to a WAV or MP3 file instead.

Features

Options

Flag	Description	Default
`--voice-id`	Voice ID	`tc_60e5426de8b95f1d3000d7b5`
`--model`	Model (`ssfm-v30`, `ssfm-v21`)	`ssfm-v30`
`--language`	Language code (ISO 639-3)	auto-detected
`--emotion`	Emotion type: `smart`, `preset`
`--emotion-preset`	Preset emotion (requires `--emotion preset`)
`--emotion-intensity`	Emotion intensity 0.0–2.0 (requires `--emotion preset`)	`1.0`
`--prev-text`	Previous sentence for context (`--emotion smart` only)
`--next-text`	Next sentence for context (`--emotion smart` only)
`--volume`	Volume (0–200)	`100`
`--pitch`	Pitch in semitones (-12 to +12)	`0`
`--tempo`	Tempo multiplier (0.5–2.0)	`1.0`
`--format`	Output format (`wav`, `mp3`)	`wav`
`--seed`	Unsigned integer seed for reproducible output (≥ 0)
`--out`	Save to file instead of playing

Models

Model	Languages	Emotions	Latency
`ssfm-v30`	37	7 presets + smart emotion	Standard
`ssfm-v21`	27	4 presets (normal, happy, sad, angry)	Low

# Use ssfm-v21 for lower latency
cast "Hello, world!" --model ssfm-v21

Emotions

Smart Emotion
Preset Emotion

AI automatically infers the appropriate emotion from the text. Only available with ssfm-v30.

cast "I just got promoted!" --emotion smart

Optionally provide surrounding sentences for better context:

cast "I just got promoted!" --emotion smart \
  --prev-text "I have been working so hard this year." \
  --next-text "Let's celebrate tonight!"

Choose a specific emotion with --emotion-preset, and control its strength with --emotion-intensity (0.0–2.0, default 1.0).

Model	Available Presets
`ssfm-v30`	`normal`, `happy`, `sad`, `angry`, `whisper`, `toneup`, `tonedown`
`ssfm-v21`	`normal`, `happy`, `sad`, `angry`

# Happy with default intensity
cast "Hello, world!" --emotion preset --emotion-preset happy

# Happy with maximum intensity
cast "Hello, world!" --emotion preset --emotion-preset happy --emotion-intensity 2.0

# Whisper with low intensity
cast "Hello, world!" --emotion preset --emotion-preset whisper --emotion-intensity 0.5

# ssfm-v21 model
cast "Hello, world!" --model ssfm-v21 --emotion preset --emotion-preset sad

Voices

Interactive Picker

Browse, preview, and select voices interactively:

cast voices pick
cast voices pick --gender female --age young_adult
cast voices pick --text "Custom preview sentence"

Type to filter, then use these keys:

Key	Action
P	Preview with current model/emotion preset
E	Preview with smart emotion (ssfm-v30 only)
S	Set as default voice
C	Copy voice ID to clipboard
Enter	Confirm and print voice ID
Esc	Go back

Tournament

Find your favorite voice through head-to-head elimination:

cast voices tournament
cast voices tournament --gender female --size 16
cast voices tournament --text "Custom preview sentence"

Key	Action
P	Preview voice 1
Q	Preview voice 2
1	Pick voice 1
2	Pick voice 2

Random

Pick a random voice for experimentation:

cast voices random
cast voices random --gender female --age young_adult
cast "Hello!" --voice-id $(cast voices random --model ssfm-v30 --gender female)

List & Get

List voices with filters:

cast voices list
cast voices list --gender female
cast voices list --age young_adult
cast voices list --model ssfm-v30
cast voices list --use-case Audiobook
cast voices list --json

Available use cases: Announcer, Anime, Audiobook, Conversational, Documentary, E-learning, Rapper, Game, Tiktok/Reels, News, Podcast, Voicemail, AdsGet details for a specific voice:

cast voices get <voice_id>

Config

Set default values so you don’t have to pass flags every time:

cast config set voice-id tc_xxx
cast config set model ssfm-v21
cast config set volume 120

cast config list          # show current config
cast config unset volume  # remove a value

Available keys: voice-id, model, language, emotion, emotion-preset, emotion-intensity, volume, pitch, tempo, format Settings are resolved in the following priority:

--flag  >  environment variable  >  ~/.typecast/config.yaml  >  built-in default

Environment Variables

Any option can be set via environment variable using the TYPECAST_ prefix:

Variable	Flag Equivalent
`TYPECAST_API_KEY`	`--api-key`
`TYPECAST_VOICE_ID`	`--voice-id`
`TYPECAST_MODEL`	`--model`
`TYPECAST_LANGUAGE`	`--language`
`TYPECAST_EMOTION`	`--emotion`
`TYPECAST_EMOTION_PRESET`	`--emotion-preset`
`TYPECAST_EMOTION_INTENSITY`	`--emotion-intensity`
`TYPECAST_FORMAT`	`--format`
`TYPECAST_VOLUME`	`--volume`
`TYPECAST_PITCH`	`--pitch`
`TYPECAST_TEMPO`	`--tempo`

Recipes

Read text from a file

cast "$(cat script.txt)"

Pipe from another command

echo "System is ready." | cast
cast "$(curl -s https://example.com/status.txt)"

Batch generate audio files

cast "Chapter one." --out ch1.wav
cast "Chapter two." --out ch2.wav
cast "Chapter three." --out ch3.wav

Audiobook with emotion

# Narration in a calm tone
cast "It was a dark and stormy night." \
  --emotion preset --emotion-preset normal --emotion-intensity 0.5 --out intro.wav

# Exciting moment
cast "She opened the letter and gasped." \
  --emotion preset --emotion-preset happy --emotion-intensity 1.5 --out climax.wav

# Sad farewell
cast "He watched the train disappear into the fog." \
  --emotion preset --emotion-preset sad --out farewell.wav

Smart emotion for natural delivery

cast "I can't believe we actually made it!" --emotion smart \
  --prev-text "We've been working on this for three years." \
  --next-text "Let's celebrate tonight!"

Reproducible output with a fixed seed

cast "Hello, world!" --seed 42 --out hello.wav
# Running again with the same seed produces identical audio
cast "Hello, world!" --seed 42 --out hello2.wav

Use a different language

cast "Bonjour le monde" --language fra
cast "こんにちは" --language jpn

Adjust delivery style

cast "Buy now, limited time offer!" --tempo 1.3 --pitch 2
cast "Relax and take a deep breath." --tempo 0.85 --volume 90

Troubleshooting

cast: command not found

Verify the installation completed successfully
Homebrew: Run brew list neosapience/tap/cast to check
Go: Ensure $GOPATH/bin is in your PATH
Try opening a new terminal session

Authentication error

Run cast login to re-enter your API key
Verify your key is valid at Typecast API Console
Run cast logout then cast login to reset

No audio playback

Try saving to a file instead: cast "test" --out test.wav
Check your system audio output device
Ensure your system volume is not muted

Resources

GitHub

Source code and releases

API Reference

Explore the Typecast API

Voice Library

Browse available voices

Typecast API Console

API home

GET STARTED

SDKs

INTEGRATIONS

Installation

Quick Start

Features

Options

Models

Emotions

Voices

Config

Environment Variables

Recipes

Troubleshooting

Resources

GitHub

API Reference

Voice Library

Typecast API Console

GET STARTED

SDKs

INTEGRATIONS

Documentation Index

​Installation

​Quick Start

​Features

​Options

​Models

​Emotions

​Voices

​Config

​Environment Variables

​Recipes

​Troubleshooting

​Resources

GitHub

API Reference

Voice Library

Typecast API Console

Installation

Quick Start

Features

Options

Models

Emotions

Voices

Config

Environment Variables

Recipes

Troubleshooting

Resources