edgespeak-broadcast

EdgeSpeak Broadcast

Turn text into speech, entirely on-device — the text never leaves the machine. Broadcast is EdgeSpeak's speech feature; under the hood this skill calls edgespeak-cli speech (alias: synthesize). When the EdgeSpeak desktop app is running, the CLI talks to its local gateway (OpenAI-compatible, 127.0.0.1:1117) and reuses the warm model (proxy mode); when the app is not running, the CLI launches the bundled on-device engine itself (standalone mode). Standalone is a normal mode, not an error.

Version compatibility. The frontmatter pins this skill's version and the oldest CLI it is written against (minCliVersion). If edgespeak-cli --version reports something older, run edgespeak-cli update (or re-run the installer) before relying on the flags documented here. Same-numbered builds can still differ, so --help is the tiebreaker for flags — a flag documented here but missing from the installed --help means update, don't route around it.

--help is not the tiebreaker for model ids: speech --help names only a subset of the installed TTS models. The live, authoritative list is the gateway's /v1/models — see "Pick a model and a voice".

Inputs to confirm

The text to speak (or the file it comes from).
Output WAV path.
Any requested voice, style instructions, speed, language, or reproducibility (seed) preferences.
Whether the user wants a named voice (a specific, reusable EdgeSpeak voice identity), a cloned voice (their own user: voice), or a designed voice (invented from a text description) — the answer decides the model, not just the --voice value.

How to do it

Check the runtime first:

edgespeak-cli status

Command not found → the CLI isn't installed. Tell the user and point them to the install steps at https://edgespeak.com/docs/cli#install (a self-contained one-line installer on macOS Apple Silicon and Linux x86_64, with CUDA auto-detected on Linux; on Windows x64 the EdgeSpeak desktop app ships the CLI). The user runs the installer; do not run it yourself.
License not activated / locked → run edgespeak-cli login to sign in via the browser (purchased accounts activate this machine directly, new accounts start a free 7-day trial; signing in also replaces an anonymous trial with your account credentials), or edgespeak-cli activate <KEY> with an existing key. No account and no browser at hand? edgespeak-cli trial starts an instant anonymous 7-day trial (device-bound, one per device). Non-interactive runs (agents, pipes, CI) fail fast with license_required instead of prompting.
Gateway not running (standalone) → this is fine; speech will launch the bundled on-device engine itself.

Pick a model and a voice together. They are not independent choices — every TTS model accepts one family of voices and rejects the others (see "Pick a model and a voice" below).

Synthesize:

edgespeak-cli speech "<text>" -o out.wav [options]

# Default: the general-purpose clone-capable model with a preset voice
edgespeak-cli speech "<text>" -o out.wav --voice builtin:warm-neighbor

# A specific official named voice (needs a CustomVoice model)
edgespeak-cli speech "<text>" -o out.wav \
  -m Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --voice builtin:Serena

# Named voice plus a speaking style (of the two CustomVoice models, only 1.7B honors --instructions)
edgespeak-cli speech "<text>" -o out.wav \
  -m Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --voice builtin:Aiden \
  --instructions "a calm news anchor, measured and clear"

# Voice design: invent a voice from a text description (no reference audio needed)
edgespeak-cli speech "<text>" -o out.wav \
  -m Qwen/Qwen3-TTS-1.7B-VoiceDesign --voice builtin:auto \
  --instructions "a warm, calm narrator with a low voice"

The WAV is written to -o and a JSON result is printed to stdout. Engine logs go to stderr — when scripting, parse stdout only.

Do not silently overwrite an existing output file. speech clobbers an existing -o WAV without warning. If the requested path already exists and the user did not explicitly ask to overwrite or regenerate that exact file, confirm with the user first (or agree on a different path); if you cannot ask, write to a new non-conflicting path and say so in your answer.

Pick a model and a voice

Ask the gateway what the installed TTS models can do (the app must be running):

curl -s http://127.0.0.1:1117/v1/models

Local authentication on the gateway is off by default. If the user has turned it on (EdgeSpeak app → Local gateway → Local authentication), ask them for the key and add -H "Authorization: Bearer <key>"; do not read the key from their environment or files.

Every model whose supported_endpoints include /v1/audio/speech declares a features array:

Feature	Meaning
`named_voice`	Accepts EdgeSpeak's official named voices — and only those
`voice_clone`	Accepts the cloneable preset voices, your own `user:<uuid>` voices, and `builtin:auto`
`instruct`	Actually honors `--instructions` style text
`live_audio_streaming`	The engine can emit audio while still synthesizing (this is what the app's Broadcast player uses to start speaking early; `speech` still writes one finished WAV, so it changes nothing for this skill)

Those features resolve to the local model ids below. Pass the id verbatim, and treat /v1/models as the live list — a model the user has not installed will not be there:

Model id	Voices it accepts	`instruct`	Streaming
`k2-fsa/OmniVoice` (CLI default)	presets, `user:` clones, `builtin:auto`	no	no
`openbmb/VoxCPM2`	presets, `user:` clones, `builtin:auto`	yes	yes
`Qwen/Qwen3-TTS-0.6B-Base`	presets, `user:` clones, `builtin:auto`	no	yes
`Qwen/Qwen3-TTS-12Hz-1.7B-Base`	presets, `user:` clones, `builtin:auto`	no	yes
`Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice`	official named voices only	no	yes
`Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`	official named voices only	yes	yes
`Qwen/Qwen3-TTS-1.7B-VoiceDesign`	`builtin:auto` only	yes (required)	no
`IndexTeam/IndexTTS-2.5`	presets, `user:` clones, `builtin:auto`	no	no
`FireRedTeam/FireRedTTS3`	presets, `user:` clones, `builtin:auto`	no	yes
`FireRedTeam/FireRedTTS3-Instruct`	presets, `user:` clones, `builtin:auto`	yes	yes

Four of them also answer to a short alias: k2-fsa/OmniVoice → omnivoice, openbmb/VoxCPM2 → voxcpm2, Qwen/Qwen3-TTS-0.6B-Base → qwen3-tts-0.6b-base, and Qwen/Qwen3-TTS-1.7B-VoiceDesign → qwen3-tts-1.7b-voice-design. Do not invent aliases for the others — a guessed id (qwen3-tts-12hz-1.7b-customvoice, …) returns HTTP 404 model_not_found.

Languages a model will accept

Each speech model in /v1/models publishes supported_languages. A language outside that list is rejected with HTTP 422 language_unsupported — it is not quietly ignored and handed to the engine any more, because that used to return a confidently mispronounced WAV. Read the list before passing --language, or omit the flag and let the model decide.

FireRedTeam/FireRedTTS3 additionally publishes its Chinese dialects as zh-x-<name> tags (for example zh-x-sichuan). Only that spelling is accepted; older dialect spellings have to be rewritten.

`clone_mode` (API and MCP only)

POST /v1/audio/speech and the MCP tool edgespeak_create_speech take an optional clone_mode: quick (faster to start) or ultimate (closer to the reference). There is no --clone-mode CLI flag — do not invent one. Omitting it uses the model's default, which never errors.

Only the models that publish clone_mode.values in /v1/models accept it — currently Qwen/Qwen3-TTS-0.6B-Base, Qwen/Qwen3-TTS-12Hz-1.7B-Base, and openbmb/VoxCPM2, all with clone_mode.default_value of quick. Naming a mode a model cannot deliver fails with clone_mode_unsupported_by_model; naming one the chosen voice was not built for fails with clone_mode_unsupported_by_voice — that second one means change the voice, not the model.

Then list the local voice library (JSON to stdout):

edgespeak-cli voices list

Each entry has an id, supported_languages, and a compatibility array naming the models that can use it. Pick an id whose compatibility entry for your chosen model is "ready" — that array, not the voice's name, is the reliable pairing check. The library splits in two:

Official named voices — builtin:Vivian, builtin:Serena, builtin:Uncle_Fu, builtin:Dylan, builtin:Eric, builtin:Ryan, builtin:Aiden, builtin:Ono_Anna, builtin:Sohee. Nine stable identities across ten languages, usable only with the two CustomVoice models. Their names / descriptions objects are empty, so refer to them by id when presenting choices to the user.
Cloneable voices — the presets (builtin:bright-girl, builtin:energetic-boy, builtin:warm-neighbor, …) plus every user:<uuid> the user added. These carry localized names / descriptions (en-US, zh-CN) and work only with the voice_clone models.

Pairing errors

What you sent	Response
A `CustomVoice` model with `builtin:auto`, a preset, or a `user:` clone	HTTP 400 `custom_voice_requires_official_named_voice`
A `voice_clone` model with an official named voice	HTTP 409 `voice_not_ready`
A model id absent from `/v1/models` (including an invented short alias)	HTTP 404 `model_not_found`
A `language` outside the model's `supported_languages`	HTTP 422 `language_unsupported`
A parameter the engine rejects outright	HTTP 400 `bad_request`

Recover by re-reading /v1/models and voices list and re-pairing. Never retry the same combination, and if you have to change the user's requested voice or model to make the pair valid, say so.

None of these are transient. The engine now refuses a bad synthesis request with 400 bad_request or 422 language_unsupported instead of collapsing it into a 500, so back-off-and-retry logic written against 5xx will loop forever on the identical answer. Treat both as "change the voice, the language, or the model" — never as a busy server.

--instructions is silently ignored by models without instruct. Only the models whose features include instruct honor it — openbmb/VoxCPM2, Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice, Qwen/Qwen3-TTS-1.7B-VoiceDesign, and FireRedTeam/FireRedTTS3-Instruct. Everywhere else the call still returns success with an empty warnings array and byte-identical audio — same seed in, same WAV out. If the user asked for a speaking style, move them to one of those models rather than reporting a style that was never applied.

Option map

User asks for	Use with `speech`	Notes
A specific voice	`--voice builtin:<id>` or `--voice user:<uuid>`	Must be compatible with `-m` — see "Pick a model and a voice". Default `builtin:auto` lets the engine pick and is rejected by the two `CustomVoice` models. OpenAI voice aliases (e.g. `alloy`) are also accepted on the clone-capable models.
Speaking style ("cheerful", "slow news anchor tone", …)	`--instructions "<style>"`	Free-form style text, honored only by models carrying the `instruct` feature in `/v1/models`; silently ignored on every other model. Conflicts with `--disable-style`.
Ignore the style saved with the voice	`--disable-style`	Explicitly disables the voice's default style.
Faster / slower speech	`--speed <N>`	Default 1.0. The local model may support a narrower range than OpenAI's 0.25–4.0.
Language of the text	`--language zh-CN` or `--language en-US`	Selects the internal reference for the voice. Must be one of the model's `supported_languages` in `/v1/models`, otherwise the call fails with 422 `language_unsupported`. Omit it to let the model decide.
Reproducible output	`--seed <N>`	Non-negative. Same seed + same inputs → same audio. The seed actually used is reported in the result JSON (`seed_used`).
A different local model	`-m <model-id>`	See the table in "Pick a model and a voice". Default is `k2-fsa/OmniVoice`. `speech --help` names only a subset, so read `/v1/models`, not `--help`, when choosing.
A specific named voice identity	`-m Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice` (or the `1.7B` one) `--voice builtin:<Name>`	The only way to reach the nine official named voices. The `1.7B` variant additionally honors `--instructions`; the `0.6B` variant is faster.
Design a new voice from a description	`-m Qwen/Qwen3-TTS-1.7B-VoiceDesign --voice builtin:auto --instructions "<voice description>"`	Voice design invents a voice from free-form text. It requires `--voice builtin:auto` and `--instructions`. Short alias `qwen3-tts-1.7b-voice-design` also works.
Generation quality knobs	`--guidance-scale <0–5>`, `--inference-steps <1–64>`	Omit either for the model default.
Run on a specific compute backend	`--device cpu\|cuda\|cuda:<N>\|metal\|auto`	Case-insensitive; `metal` is macOS, `gpu` means Metal on macOS / CUDA elsewhere. Standalone mode only — with the app gateway reachable the flag errors explicitly; an unavailable backend also errors rather than silently falling back.

Input is limited to 4096 characters per call (OpenAI input limit). For longer text, split it into ≤4096-character parts at natural boundaries (paragraphs/sentences), synthesize each part, and concatenate the WAVs afterwards (ffmpeg -f concat). Keep the same --voice and --seed across parts for a consistent result.

Result JSON (stdout)

Real output shape — long input is synthesized in chunks automatically and reported per chunk:

{
  "output_path": "/abs/path/out.wav",
  "format": "wav",
  "size_bytes": 90284,
  "sample_rate": 24000,
  "duration_seconds": 1.88,
  "seed_used": 3862347868,
  "infer_seconds": 7.49,
  "warnings": [],
  "chunks": [
    { "index": 0, "character_count": 21, "duration_seconds": 1.88,
      "seed_used": 3862347868, "infer_seconds": 7.49, "warnings": [] }
  ]
}

Read sample_rate from the response rather than assuming a fixed rate — it comes from the model. Surface non-empty warnings to the user, but do not treat an empty warnings array as proof that every option took effect: an --instructions string dropped by a model without instruct produces no warning at all.

Voice management

# List all voices (JSON)
edgespeak-cli voices list

# Clone a voice from reference audio + its exact transcript
edgespeak-cli voices add ref.wav --ref-text "<exact words spoken in ref.wav>" \
  --name "My voice" [--language zh-CN] [--speaker-description "<optional description>"] --consent

# Delete a user-created voice (by id or exact name); built-in voices cannot be deleted
edgespeak-cli voices delete user:<uuid>
edgespeak-cli voices delete "My voice"

--consent is required for voices add: it asserts the user has permission to use the reference recording. Never add a voice without the user explicitly confirming they have the right to use that recording; refuse to clone third-party voices without consent.
--ref-text must be the exact transcript of the reference audio — a mismatch degrades cloning quality.
voices delete with a name requires an exact, unique match; ambiguous or unknown names fail with a clear error.
After adding, use the returned/listed user:<uuid> id with speech --voice.

MCP and API equivalents

Through the EdgeSpeak MCP server (edgespeak-cli mcp or the app's MCP endpoint), the same capabilities are exposed as tools: edgespeak_create_speech, edgespeak_list_voices, edgespeak_add_voice, edgespeak_delete_voice. Prefer MCP tools when an EdgeSpeak MCP server is already configured. edgespeak_create_speech accepts the same model ids as the CLI, plus the optional clone_mode the CLI has no flag for (see "clone_mode" above), and returns {artifact_path, sample_rate, duration, seed_used, chunks[], warnings[]}.
Do not take model ids from the MCP schemas. edgespeak_create_speech's own model description lists an outdated set, and edgespeak_list_models returns only {id, capabilities, locality, owned_by} — no features. For which model supports named voices, cloning, or instruct, read HTTP /v1/models.
With the app running, the local gateway also serves OpenAI-compatible POST /v1/audio/speech (JSON body {model, input, voice, response_format}, plus the optional clone_mode; WAV bytes back). Stay with the CLI unless the user specifically needs raw API access or clone_mode.

Boundaries / gotchas (read this)

Requires edgespeak-cli 0.5.6 or newer (see the version compatibility note up top). Older runtimes do not publish supported_languages or clone_mode, and they accepted out-of-table languages instead of rejecting them. If a flag documented here is missing from --help, run edgespeak-cli update first.
First use needs activation (edgespeak-cli login for browser sign-in — it also upgrades an anonymous trial to your account, activate <KEY> with an existing key, or edgespeak-cli trial for an instant anonymous 7-day trial), same as the other EdgeSpeak skills. Surface license errors; don't work around them. Non-interactive runs fail fast instead of prompting.
More model ids work than speech --help names — see "Pick a model and a voice". Do not conclude a model is unavailable because --help omits it, and do not invent short aliases. The app's Broadcast workspace offers the same models with richer UI workflows.
Model and voice must match. A mismatch fails fast with custom_voice_requires_official_named_voice (400), voice_not_ready (409), or model_not_found (404) — recover per "Pairing errors", don't retry unchanged. The same goes for 400 bad_request and 422 language_unsupported: they are verdicts about the request, not server trouble, so retrying or backing off changes nothing. Some gateway builds additionally reject the CLI's default --voice builtin:auto with HTTP 400 unsupported_auto_voice; the same recovery applies, so prefer choosing an explicit voice upfront over relying on the default.
Synthesis is slower than real time on most machines (a short sentence can take ~10–20 s in standalone mode; the first run may also decrypt/load or download the model). Don't assume it hung.
Output is WAV only. If the user wants MP3/M4A/OGG, synthesize WAV first and convert with ffmpeg afterwards.
stdout vs stderr: the result JSON is on stdout; engine progress/logs are on stderr. Never parse stderr.
If speech errors, show the error — do not fabricate audio or claim success without the output file existing.