Skip to content

keryx voice gen

Description

Synthesize voice-over narration. Two modes:

  • Standalone: --text "…" narrates a single line to an mp3 (--out, default vo.mp3).
  • Take mode: --takes N --workspace <slug> generates N candidate takes for a storyboard line (--line) into the workspace, for review with voice pick.

The voice id and all clone settings default to the resolved reel theme's voice and can be overridden per-run. The full ElevenLabs knob set is exposed: --stability, --similarity, --style (expression/exaggeration; higher drifts the accent), and --speed (0.7 slow … 1.2 fast). A storyboard card may also carry a per-line voice override for any of these.

For multi-author reels, a registered voice clone (config voices.<name>) can narrate specific lines: set the card's voice.speaker to that name and it becomes the line's base voice (overriding the reel theme's voice). Register a co-author's clone as another voices entry.

Usage

keryx voice gen [flags]

Flags

Flag Description Default Required
--text line to narrate (standalone mode)
--out output mp3 path vo.mp3
--voice override the clone voice id
--stability override voice stability (0–1)
--similarity override voice similarity (0–1)
--style voice style/exaggeration (0–1; higher = more expressive, can drift accent) 0
--speed speech rate (0.7 slow … 1.2 fast) 1.0
--theme reel theme for voice defaults
--workspace reel workspace slug (take mode)
--line storyboard line index for take generation 0
--lines re-roll exactly these lines in one pass (e.g. 3,5,7 or 3-6); needs --takes. --line N is the single-line alias
--takes number of candidate takes to generate 0
--model TTS model id (empty = theme/default eleven_multilingual_v2)
--allow-unknown-model accept a --model outside the known allowlist false

Model & pronunciation (spec 0022)

  • Model — resolved CLI --model > per-card voice.model > theme voice.model > default. The default stays eleven_multilingual_v2 (best clone fidelity; eleven_v3 nails IPA but drifts the accent). An id outside the known allowlist is a clear error unless --allow-unknown-model is set.
  • Pronunciation dictionary — a theme's voice.pronunciation: <dictionary_id> attaches ElevenLabs pronunciation_dictionary_locators to every line (on multilingual_v2 only alias rules apply — a curated, reviewable source of truth, not new phonetic power).
  • Per-line pronunciation — a storyboard card's voice.pronounce is a respelling used as that line's narration (any model); voice.ipa is a phonetic rendering used instead on a phoneme-capable model (eleven_v3 / eleven_flash_v2), and ignored on multilingual_v2.
  • The durable fix for pronunciation remains human-reviewed, locked vo/NN.mp3 clips — see reel lock (spec 0025).