Metadata-Version: 2.4
Name: voicestudio-cli
Version: 0.1.0
Summary: Command-line interface for Voice Studio - text-to-speech, voice cloning, voice design, and transcription from your shell.
Project-URL: Homepage, https://aiaudiogen.com
Project-URL: Repository, https://github.com/aiworkmagic/voicestudio
Project-URL: Issues, https://github.com/aiworkmagic/voicestudio/issues
Author: Voice Studio
License: MIT
Keywords: cli,speech,tts,voice-cloning,voice-studio
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# Voice Studio CLI

A shell-friendly command-line wrapper around [Voice Studio](https://aiaudiogen.com) - 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):

```bash
pipx install voicestudio-cli
```

Or with regular pip:

```bash
pip install voicestudio-cli
```

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

```bash
python -m voicestudio_cli --help
```

## Requirements

- Python 3.11+
- The Voice Studio desktop app installed (download at [aiaudiogen.com](https://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:

```bash
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

```bash
# 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.
