voicestudio-cli 0.1.0

Command-line interface for Voice Studio - text-to-speech, voice cloning, voice design, and transcription from your shell.

Voice Studio CLI

A shell-friendly command-line wrapper around Voice Studio - text-to-speech, voice cloning, voice design, and transcription, all driven from your terminal. The CLI talks to a locally running Voice Studio desktop app over HTTP, so all processing happens on your machine; no data leaves your computer.

Installation

End users (recommended):

pipx install voicestudio-cli

Or with regular pip:

pip install voicestudio-cli

After install, the voicestudio command is on your PATH. You can also run it as a module:

python -m voicestudio_cli --help

Requirements

• Python 3.11+
• The Voice Studio desktop app installed (download at aiaudiogen.com). The CLI auto-launches the app when needed; if it lives somewhere non-standard, set VS_APP_PATH to point at the .app bundle (macOS) or .exe (Windows).

Commands

All audio-producing commands save WAV files to ~/Documents/VoiceStudio/integrations-out/ by default. Override with --out PATH per command, or set VS_OUTPUT_DIR for a global default.

Command	What it does	Example
voices	List built-in + cloned voices	voicestudio voices
say	Text-to-speech with a built-in voice	voicestudio say "Hello world" --voice Narrator
say-with-profile	TTS with a saved cloned profile	voicestudio say-with-profile "Welcome back" --profile-id 3
clone	Clone a voice from a reference audio file	voicestudio clone sample.wav --name "My Voice"
profiles	List saved cloned voice profiles	voicestudio profiles
design	Design a voice from a description, then synthesize	voicestudio design "Hi there" --as "warm British female voice, mid-30s"
transcribe	Transcribe an audio file to text	voicestudio transcribe interview.wav
history	List recent generations	voicestudio history --limit 50
download	Re-download a past generation	voicestudio download 42 --out clip.wav
delete	Delete a history record	voicestudio delete 42 --yes
account	Print account state (paid / free tier, free generations left)	voicestudio account
status	Print backend health + loaded service	voicestudio status
free	Manually unload all ML models (free RAM)	voicestudio free

Run voicestudio <command> --help for the full flag list of any command.

JSON output

Pass --json before any command to get machine-readable output instead of pretty tables. Useful for piping into jq or scripting:

voicestudio --json voices | jq '.[] | .name'
voicestudio --json profiles | jq '.[] | select(.language == "en") | .id'
voicestudio --json history --limit 100 | jq -r '.[] | [.id, .voice, .text] | @tsv'
voicestudio --json status | jq '.current_service'

--json is supported on every command, but is most useful on voices, profiles, history, account, and status.

Pipe examples

# Speak the contents of a file
cat speech.txt | xargs -0 voicestudio say --voice Narrator

# Transcribe an audio file and grep for a keyword
voicestudio transcribe meeting.wav | grep -i "action item"

# Delete every history record older than X (with care)
voicestudio --json history --limit 500 \
  | jq -r '.[] | select(.created_at < "2026-01-01") | .id' \
  | xargs -I{} voicestudio delete {} --yes

Notes

• Auto-launch: the CLI launches the Voice Studio desktop app on first use. Cold starts can take a few seconds while the app boots. Subsequent commands reuse the running app.
• Service swaps: Voice Studio loads only one ML pipeline at a time (TTS, Clone, Design, or ASR). If you switch from say to transcribe, expect a one-time model-swap delay (~5-15 seconds depending on hardware) the first time the new model loads. Repeated calls to the same command are fast.
• Memory: if a long-running shell needs to free RAM (for example, between generations on a memory-constrained machine), call voicestudio free to unload everything.
• Output location: --out writes to the exact path you give. Without --out, the CLI prints the absolute path of the auto-saved WAV. Override the auto-save folder with VS_OUTPUT_DIR=/some/path.
• Custom backend port: if you have multiple Voice Studio installs, set VS_BACKEND_PORT to point at the right one (default 58391).

License

MIT.