Command · Narration

narration.create

Narration from a script with the user's own voice provider (BYOK): each line spoken, over its rough-cut beat when the sequence is a rough cut (AI-11) or one after another, on a new "Narration" audio track with the Dialogue role and the other audio ducked under it, as one undo step.

v1
Capability EditProject
Tool narration_create

Request

{
  "command": "narration.create",
  "params": {
    "estimate": true,
    "text": "Welcome to Chiang Mai."
  }
}

Parameters

atinteger | string: Where the first line starts when not on beats (default the sequence's start). Timecode in the sequence's rate ("00:01:02:03") or ticks.
cloneVoiceboolean: Clone the speaker's own voice (ElevenLabs instant cloning) instead of a stock voice. Opt-in; needs rightsConfirmed and speaker; never for a speaker with redacted speech. The clone is deleted after the run.
ducknumber (-60.0..0.0): How far the other audio goes down under the narration, dB (default -12; 0 = not at all).
estimateboolean: Only plan and price the run; nothing is sent or changed (default false).
gapnumber (0.0..10.0): Seconds between lines when not on beats (default 0.5).
languagestring: The language spoken (ISO 639-1); dub default: the caption track's.
maxCostnumber (0.0..1000.0): The run's hard cap in USD: refused before anything is sent when it could cost more, stopped before a line that could pass it. Required for a run.
maxStretchnumber (0.0..0.5): How much faster a line may be played to fit (0.15 = 15 %, the default; pitch kept).
modelstring: Voice model (registry id): eleven_v3 / eleven_v4 (Thai and 70+ languages), eleven_flash_v2_5, gpt-4o-mini-tts, gemini-3.8-flash-tts. Default: the host's, else eleven_v3.
namestring: The new audio track's name.
onBeatsboolean: On a rough cut (roughcut.fromScript), line i over beat i when the counts match (default true).
rightsConfirmedboolean: The user confirmed: "I have the speaker's permission" to clone their voice.
sequenceinteger (1..): Sequence id; only needed when the project has several.
speakerinteger (1..): The project speaker whose voice is cloned.
stylestring: Delivery instructions ("warm, unhurried"), where the model takes them.
textstringRequired: The script: one line per beat (Markdown headings, bullets and [B-roll] cues are dropped).
voicestring: The model's voice (an ElevenLabs voice id, an OpenAI voice such as "marin", a Gemini voice such as "Kore"); default: the model's first.

Discussion

Run it with wabcut-cli cmd <project> --json, from an MCP client as narration_create, or from an extension. See Edit commands for requests, references and results.

narration.create

Capability EditProject

Tool narration_create

Parameters

atinteger | string

Where the first line starts when not on beats (default the sequence's start). Timecode in the sequence's rate ("00:01:02:03") or ticks.

cloneVoiceboolean

Clone the speaker's own voice (ElevenLabs instant cloning) instead of a stock voice. Opt-in; needs rightsConfirmed and speaker; never for a speaker with redacted speech. The clone is deleted after the run.

ducknumber (-60.0..0.0)

How far the other audio goes down under the narration, dB (default -12; 0 = not at all).

estimateboolean

Only plan and price the run; nothing is sent or changed (default false).

gapnumber (0.0..10.0)

Seconds between lines when not on beats (default 0.5).

languagestring

The language spoken (ISO 639-1); dub default: the caption track's.

maxCostnumber (0.0..1000.0)

The run's hard cap in USD: refused before anything is sent when it could cost more, stopped before a line that could pass it. Required for a run.

maxStretchnumber (0.0..0.5)

How much faster a line may be played to fit (0.15 = 15 %, the default; pitch kept).

modelstring

Voice model (registry id): eleven_v3 / eleven_v4 (Thai and 70+ languages), eleven_flash_v2_5, gpt-4o-mini-tts, gemini-3.8-flash-tts. Default: the host's, else eleven_v3.

namestring

The new audio track's name.

onBeatsboolean

On a rough cut (roughcut.fromScript), line i over beat i when the counts match (default true).

rightsConfirmedboolean

The user confirmed: "I have the speaker's permission" to clone their voice.

sequenceinteger (1..)

Sequence id; only needed when the project has several.

speakerinteger (1..)

The project speaker whose voice is cloned.

stylestring

Delivery instructions ("warm, unhurried"), where the model takes them.

textstringRequired

The script: one line per beat (Markdown headings, bullets and [B-roll] cues are dropped).

voicestring

The model's voice (an ElevenLabs voice id, an OpenAI voice such as "marin", a Gemini voice such as "Kore"); default: the model's first.

Discussion

Run it with wabcut-cli cmd <project> --json, from an MCP client as narration_create, or from an extension. See Edit commands for requests, references and results.