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: a command or flag documented here but missing from the installed --help also means update — don't route around it.

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.

How to do it

1. Check the runtime first:

   edgespeak-cli status
   

   • Command not found → the CLI isn't installed. On Windows x64, tell the user to install the EdgeSpeak desktop app, which ships the CLI. On macOS Apple Silicon or Linux x86_64, use curl -fsSL https://edgespeak.com/install.sh | sh (self-contained, no desktop app needed; on Linux the installer auto-detects NVIDIA GPUs and installs a CUDA-enabled runtime).
   • 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). (If edgespeak-cli trial --help describes a browser sign-in, the installed CLI predates the instant trial — run edgespeak-cli update first.) 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.

2. Optionally pick a voice. List the local voice library (JSON to stdout):

   edgespeak-cli voices list
   

   Each entry has an id (builtin:<slug> for presets, user:<uuid> for user-created voices), localized names / descriptions (en-US, zh-CN), supported_languages, and a compatibility array telling which local models can use it. Pick an id whose compatibility for the chosen model is "ready".

3. Synthesize:

   edgespeak-cli speech "<text>" -o out.wav [options]
   
   # Voice design: invent a voice from a text description (no reference audio needed)
   edgespeak-cli speech "<text>" -o out.wav \
     -m qwen3-tts-1.7b-voice-design --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.

Option map

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": 215084,
  "sample_rate": 48000,
  "duration_seconds": 2.24,
  "seed_used": 2711317933,
  "infer_seconds": 12.55,
  "warnings": [],
  "chunks": [
    { "index": 0, "character_count": 21, "duration_seconds": 2.24,
      "seed_used": 2711317933, "infer_seconds": 12.55, "warnings": [] }
  ]
}

sample_rate comes from the model (do not assume a fixed rate). Surface non-empty warnings to the user.

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_generate_speech, edgespeak_list_voices, edgespeak_add_voice, edgespeak_delete_voice. Prefer MCP tools when an EdgeSpeak MCP server is already configured.
• With the app running, the local gateway also serves OpenAI-compatible POST /v1/audio/speech. Stay with the CLI unless the user specifically needs raw API access.

Boundaries / gotchas (read this)

• Requires a current edgespeak-cli (see the version compatibility note up top): older versions lack speech / voices entirely, and only the newest builds add the Qwen3-TTS model ids and --device. When in doubt, 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.
• Three model ids work here: omnivoice (default), qwen3-tts-0.6b-base, and qwen3-tts-1.7b-voice-design — other ids are unavailable through speech and fail, even if an installed CLI's --help still lists them. Voice design (qwen3-tts-1.7b-voice-design) requires --voice builtin:auto plus --instructions; the app's Broadcast workspace offers the same models with richer UI workflows.
• If synthesis fails with HTTP 400 unsupported_auto_voice: this gateway build does not accept the CLI's default --voice builtin:auto. Recover by running edgespeak-cli voices list and passing an explicit voice (--voice builtin:<id>); when the user has no preference, prefer listing voices and choosing one upfront so the default is never relied on.
• 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.