api-scripts

nodetool.scripts

A script (a voice script) is a cast of speakers, each with a voice, and the lines they speak in reading order. Voicing a line makes an audio take. Assembling lays the takes into a timeline. A JavaScript script is a different document (nodetool-js-scripting). A video timed to a written voiceover is script-video.

Call	Does	Answers
list({limit})	Lists scripts, newest first, with cast size, line count, voiced count and the timeline it was assembled into.	Script rows
create(name, {project_id, id})	Creates an empty script. An existing id is returned as it is, so a retry makes no copy.	{script_id, …}
get(id)	Reads the cast and every line with its id, index, speaker, text, direction, pause, effective voice and voicing status.	The script
edit(id, ops)	Applies ops in order and saves. An open editor picks the change up live.	The result of each op
voice(id, opts)	Calls the TTS provider for the lines.	The takes it made
assembleTimeline(id, {name, fps})	Lays the voiced takes end to end into a timeline.	The timeline id, and the lines it skipped

Line status is draft (never voiced), stale (the text or voice changed since the take), voiced or no_voice (the speaker has no voice).

Ops

A line target is its id, its 0-based index in the whole script, or its exact text. A speaker target is its id or name. An argument an op does not take is refused.

Op	Arguments
set_setup	stage?, brief?, format?, length_seconds?, pace?, language?
add_speaker	name, color?, provider?, model?, voice?, entityId?
set_speaker	target, name?, color?, entityId? — renames or recolours a speaker
set_speaker_voice	target, provider, model, voice, settings?
remove_speaker	target
add_section	title?
add_line	text, speaker?, section?, direction?, pause_after_ms?, index?
set_line_text	target, text
set_line_speaker	target, speaker — the op that gives a line its speaker
remove_line	target

• format is voiceover, dialogue, interview, ad-read or tutorial.
• entityId makes the speaker a cast character from the entity library, so storyboard renders can use it.
• A rewritten line keeps its takes as stale, so the next voice() records exactly those again.

voice

• Omit targets to voice every line that is unvoiced or stale. A whole script is one call. Each line is a paid TTS call plus a transcription call, so confirm the scope with the user before you voice a long script.
• targets takes line ids, indexes or exact texts.
• Each line uses its own voice, else its speaker's. provider, model and voice together override every line. Pick the model with nodetool.models.pick("text_to_speech").
• speed, concurrency (default 3, max 8).
• Word timings are transcribed for captions (transcribe, default true; asr_provider and asr_model default to openai and whisper-1).
• Earlier takes are kept, and the new take becomes current.

const { script_id: id } = await nodetool.scripts.create("Launch VO");
await nodetool.scripts.edit(id, [
  { op: "add_speaker", name: "Narrator" },
  { op: "set_speaker_voice", target: "Narrator", provider, model, voice },
  { op: "add_line", text: "Meet the lamp that listens.", speaker: "Narrator" }
]);
await nodetool.scripts.voice(id);
const cut = await nodetool.scripts.assembleTimeline(id);

Each assembled clip carries its word timings, the speaker label and a link to its line, so a re-voiced line can round-trip into the cut. Running the assembly again rebuilds the same timeline in place. Validate it with nodetool.timelines.validate before a render.