Voice with Guaardvark
Read setup first. Expressive voices need the audio_foundry plugin running;
Piper works without it. B=${GUAARDVARK_URL:-http://localhost:5000}.
Which engine
| engine |
route |
when |
| Chatterbox |
Audio Foundry backend: "chatterbox" |
expressive, emotion presets, cloning |
| Kokoro |
Audio Foundry backend: "kokoro" |
fast, clean, 10+ built-in voices (af_heart default) |
| Piper |
/api/voice/text-to-speech |
offline fallback, no GPU |
GET $B/api/audio-foundry/voices lists what is installed. GET $B/api/voice/voices lists Piper voices.
Speak a line or a script
curl -s -X POST $B/api/audio-foundry/generate/voice -H 'Content-Type: application/json' -d '{
"text": "The line to speak.",
"backend": "auto", # auto | chatterbox | kokoro
"voice_id": "af_heart", # Kokoro voice, or omit
"emotion": "calm", # Chatterbox preset, or omit
"exaggeration": 0.5, "cfg_weight": 0.5, "temperature": 0.8, # Chatterbox knobs, optional
"seed": 7, "output_format": "wav", "async": true
}'
- Short text returns the file directly (
path, document_id). With "async": true or long
text you get 202 {"job_id"}: poll GET $B/api/audio-foundry/jobs/<job_id> until status
is done; the result has path and document_id. Cancel: POST .../jobs/<job_id>/cancel.
- Multi-section narration with pauses:
POST $B/api/voice/narrate
{"script": "...", "engine": "kokoro", "voice": "...", "pause_between_sections": 0.6, "output_format": "wav"}.
- Piper only:
POST $B/api/voice/text-to-speech {"text", "voice": "libritts"} returns audio_url.
Clone a voice (consent-gated)
- The reference must go through the upload route; that is what records consent. Arbitrary
file paths are refused with 403.
curl -s -X POST $B/api/audio-foundry/voice-clips/upload -F file=@/abs/path/ref.wav -F name="Dean sample"
The response gives the stored path. GET $B/api/audio-foundry/voice-clips lists clips.
- Generate with
"backend": "chatterbox", "reference_clip_path": "<that path>".
- Before uploading, ask whether the voice belongs to the user or someone who consented. Do not
clone a public figure or anyone who has not agreed. Refuse politely if unclear.
Rules
- 10 to 20 seconds of clean speech is enough for a clone; more is not better.
- Say which engine ran (the response reports it);
auto falls back to Kokoro on a Chatterbox error.
- Audio files are local under
data/outputs/; they also appear in the Audio library page.
1---2name: voice3description: Narration and text-to-speech on the user's machine through Guaardvark's Audio Foundry (Chatterbox, Kokoro, Piper) and consent-gated voice cloning from a reference clip. Use when the user wants a voiceover, narration of a script, a spoken line, or "make it sound like this voice".4---56# Voice with Guaardvark78Read `setup` first. Expressive voices need the `audio_foundry` plugin running;9Piper works without it. `B=${GUAARDVARK_URL:-http://localhost:5000}`.1011## Which engine1213| engine | route | when |14|---|---|---|15| Chatterbox | Audio Foundry `backend: "chatterbox"` | expressive, emotion presets, **cloning** |16| Kokoro | Audio Foundry `backend: "kokoro"` | fast, clean, 10+ built-in voices (`af_heart` default) |17| Piper | `/api/voice/text-to-speech` | offline fallback, no GPU |1819`GET $B/api/audio-foundry/voices` lists what is installed. `GET $B/api/voice/voices` lists Piper voices.2021## Speak a line or a script2223```bash24curl -s -X POST $B/api/audio-foundry/generate/voice -H 'Content-Type: application/json' -d '{25 "text": "The line to speak.",26 "backend": "auto", # auto | chatterbox | kokoro27 "voice_id": "af_heart", # Kokoro voice, or omit28 "emotion": "calm", # Chatterbox preset, or omit29 "exaggeration": 0.5, "cfg_weight": 0.5, "temperature": 0.8, # Chatterbox knobs, optional30 "seed": 7, "output_format": "wav", "async": true31}'32```33- Short text returns the file directly (`path`, `document_id`). With `"async": true` or long34 text you get `202 {"job_id"}`: poll `GET $B/api/audio-foundry/jobs/<job_id>` until `status`35 is `done`; the result has `path` and `document_id`. Cancel: `POST .../jobs/<job_id>/cancel`.36- Multi-section narration with pauses: `POST $B/api/voice/narrate`37 `{"script": "...", "engine": "kokoro", "voice": "...", "pause_between_sections": 0.6, "output_format": "wav"}`.38- Piper only: `POST $B/api/voice/text-to-speech {"text", "voice": "libritts"}` returns `audio_url`.3940## Clone a voice (consent-gated)41421. The reference must go through the upload route; that is what records consent. Arbitrary43 file paths are refused with 403.44 ```bash45 curl -s -X POST $B/api/audio-foundry/voice-clips/upload -F file=@/abs/path/ref.wav -F name="Dean sample"46 ```47 The response gives the stored path. `GET $B/api/audio-foundry/voice-clips` lists clips.482. Generate with `"backend": "chatterbox", "reference_clip_path": "<that path>"`.493. Before uploading, ask whether the voice belongs to the user or someone who consented. Do not50 clone a public figure or anyone who has not agreed. Refuse politely if unclear.5152## Rules5354- 10 to 20 seconds of clean speech is enough for a clone; more is not better.55- Say which engine ran (the response reports it); `auto` falls back to Kokoro on a Chatterbox error.56- Audio files are local under `data/outputs/`; they also appear in the Audio library page.
guaardvark