voice

# Voice & Sound Effects Generator

Generate voiceovers (TTS) and sound effects. For TTS, choose a concrete
provider and voice before calling `submit_voice`.

## When to Use

- Generate voiceover/narration from text
- Create text-to-speech audio for videos
- Add, replace, or redo narration/voiceover for an existing video, timeline,
  screen recording, slide animation, product demo, B-roll edit, MG explainer, or
  other visual sequence
- Keep existing narration/voiceover aligned after trimming, speeding up, slowing
  down, moving, reordering, or replacing the visuals it describes
- Offer and audition TTS voice choices when the user has not picked a concrete voice
- Generate custom sound effects from text descriptions only after checking the Sound Effects library first

## TTS (Text-to-Speech)

If the current request has an existing visual target and the user wants
narration, voiceover, dubbing, or replacement speech for that target, read
[references/video-sync.md](references/video-sync.md) before drafting new
narration, using existing narration text to generate TTS, or placing audio. Do
this even when the user did not explicitly say "sync" or "match the visuals";
the existence of a visual target means narration timing and meaning may need to
follow on-screen content. Use the normal standalone TTS path only when there is
no visual target or the user just wants an audio asset from text.

Also read [references/video-sync.md](references/video-sync.md) when the timeline
already has narration/voiceover and the user asks to change the visuals while
keeping that voiceover aligned. This is a sync maintenance task even if no new
TTS is needed.

Use `submit_voice` to create a TTS audio asset. The current MCP tool contract is:

- `provider` is required. Configured choices may be `doubao`, `elevenlabs`,
  `minimax`, `inworld`, `fishaudio`, `speechify`, `openai`, `gemini`,
  `mistral`, or `cartesia`. All providers are opt-in; use only providers shown
  as configured in the capabilities prompt.
- `voiceId` is required, concrete, and provider-specific. The only exception is
  deliberate MiniMax `timbreWeights` mixing, where `voiceId` must be empty. Do
  not mix catalogs.
- The curated catalog in [references/voices.md](references/voices.md) covers
  only Doubao, ElevenLabs, and MiniMax. Other providers have no bundled preset
  or sample catalog in OpenChatCut. Require a concrete voice ID from the user or
  their provider account; never invent a preset or `/voice-samples/...` URL.
- AI SDK-backed fields are provider-specific: OpenAI supports `modelId`,
  `speed`, `outputFormat`, and `instructions`; Gemini supports `modelId`,
  `outputFormat`, and `instructions`; Mistral supports `modelId` and
  `outputFormat`; Cartesia supports `modelId`, `speed`, `languageCode`, and
  `outputFormat`. Omit unsupported or unrequested fields.
- Inworld, Fish Audio, and Speechify accept only `voiceId` plus optional
  `modelId`. Do not pass expressive, speed, language, or output controls to
  these providers.
- `submit_voice` creates an audio asset only. Timeline placement, replacement,
  trimming, and alignment happen later with timeline tools.
- For long narration, multiple `submit_voice` calls can be useful: split at
  natural pauses, sentence groups, or script beat boundaries when the workflow
  benefits from separately timed or placed voice clips.
- Doubao supports `speedRatio`, `loudnessRatio`, `pitch`, `emotion`,
  `emotionScale`, `performancePrompt`, and `explicitDialect`, but not every
  voice supports every expressive control. Check
  [references/voices.md](references/voices.md) before using them.
- ElevenLabs retains its official voice settings, language, seed, output,
  normalization, pronunciation-dictionary, continuity, logging, and latency
  controls. MiniMax retains its dedicated controls documented in
  [references/minimax-tts.md](references/minimax-tts.md).

Doubao control support for current curated voices:

- `vivi`, `xiaohe`, `yunzhou`, `xiaotian`, `naiqimengwa`, `yingtaowanzi`,
  `wenroumama`, `zhixingnv`, `dayi`, `jitangnv`, `liuchang`, `ruyayichen`,
  `morgan`, `qingcang`, `huiben`, `popo`, `yuanboxiaoshu`, `baqiqingshu`, and
  `tangseng` support explicit `emotion` / `emotionScale`,
  `performancePrompt`, and ASMR-style prompt directions.
- `shuanglangshaonian` supports `performancePrompt` and COT/QA-style
  instruction following, but does not support explicit `emotion` /
  `emotionScale` or ASMR-style control.
- `explicitDialect` is only supported by `vivi` and can be `dongbei`,
  `shaanxi`, or `sichuan`.

ElevenLabs control support for current curated voices:

- `amelia`, `brittney`, `hope`, `jessica`, `arabella`, `jane`, `maria`,
  `mark`, `frederick`, `peter`, `james`, `jon`, `sully`, `david`, and `alex`
  all support the same request-level controls; model-specific support is still
  validated by ElevenLabs.
- These controls are not per-voice guarantees of a specific acting style.
  Use the preset tags/samples to pick a naturally suitable voice, then use the
  controls for moderate delivery changes.
- For ElevenLabs `eleven_v3`, inline audio tags are available when the user
  asks for expressive delivery such as emotion, tone, nonverbal cues, accent
  hints, or local pacing. Official examples fit these useful TTS categories:
  emotion/tone tags such as `[happy]`, `[sad]`, `[angry]`, `[excited]`,
  `[curious]`, `[sarcastic]`, `[crying]`, `[annoyed]`, `[appalled]`,
  `[thoughtful]`, `[surprised]`, and `[mischievously]`; vocal delivery and
  nonverbal cue tags such as `[whispers]`, `[laughs]`, `[sighs]`, `[exhales]`,
  `[inhales deeply]`, `[clears throat]`, `[snorts]`, `[swallows]`,
  `[wheezing]`, and `[coughs]`;
  pacing/pause/local speed tags such as `[slowly]`, `[pause]`,
  `[short pause]`, `[long pause]`, `[rushed]`, and `[drawn out]`; and
  accent/special-performance tags such as
  `[strong X accent]`, for example `[strong French accent]`, plus `[sings]`,
  `[singing]`, `[woo]`, and `[pirate voic