storyboard-core
Use NodeTool storyboard, entity-casting, rendering, and timeline-assembly tools for video production or debugging their contracts.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 635
- Forks
- 91
01 前言 Front Matter
- name
- storyboard-core
- featured
- true
- description
- Use NodeTool storyboard, entity-casting, rendering, and timeline-assembly tools for video production or debugging their contracts.
02 资源文件 1
- 参考文档prompt.md13.5 KB
03 SKILL.md 正文
The shared half of every NodeTool video job. The use-case skills carry the style, the shot pattern and the briefs; this carries the machinery they all assume.
Direct video on the storyboard surface, then finish in the timeline. Use a node graph when the user requests one or needs a reusable template, as
described in video-workflow.
Read the relevant part of Tool contract below before the first call in that tool family. Use the live tool schema when it differs from an example. Load other sections only when the task reaches them.
Pick the use-case skill
| Job | Skill |
|---|---|
| Phone-shot video with a person: UGC ad, testimonial, comedy, day-in-the-life, vlog | /ugc-video |
| Product film: pack shot, hero, brand spot, with or without talent | /product-commercial |
| Sound-off motion-graphics ad from real screenshots and product photos, no generated footage | /motion-ad |
| Rebuild an existing ad or clip you were given | /video-clone |
| Voiceover drives the picture: explainer, faceless video, narrated piece | /script-video |
| Narrative with dialogue, score and a title: short film, trailer, scene | /short-film |
| A campaign, not one video: entity sheets, still set, several cuts | /launch-kit |
| A template to re-run on new inputs | /video-workflow |
| Footage already exists and needs repair: cutout, upscale, outpaint, lip sync, generated sound | /nodetool-video-post |
| A screen someone clicks, over the workflows behind a piece | /nodetool-app-builder |
If none fits, run the loop below directly.
Those skills say what the picture looks like. A second set says where the beats go, and the two compose: load the job skill for the look and the structure skill for the spine.
| The structure question | Skill |
|---|---|
| Ad beats: hook, escalation, timecodes, VO discipline | /commercial-beat-sheet |
| A product page URL in, a finished cut and its cost out | /launch-commercial |
| A 30–120s explanation with a claim per beat | /explainer-storyboard |
| A treatment cut to a track's sections | /music-video-treatment |
| Eight audio-first beats, the drop at ~65%, a title card | /trailer-template |
These own their own briefs and beat budgets. The storyboard, entity and render call shapes live once, in Tool contract below. Every job and structure skill points here for them.
Two tool families, one board
| Headless | Browser | |
|---|---|---|
| Names | create_storyboard, get_storyboard, edit_storyboard, direct_storyboard, render_storyboard_stills, render_storyboard_clips, revise_storyboard_clip, assemble_storyboard_timeline, and the rest of Tool contract |
ui_storyboard_*: a browser twin for most headless ops, plus set_screenplay (table in Tool contract) |
| Needs | nothing open | the board open as a tab, listed in the ui_context system block |
| Shot target | id, 0-based index, or slug | id, 0-based index, or "selected" — no slug |
| Permission gate | yes | no (client tools bypass it) |
Every board tool in both families names its board explicitly (storyboard_id, or
storyboardId on the still-motion-graphics tools). There is no "act on whatever is
open" fallback.
Prefer headless. Reach for ui_storyboard_* when the user is watching the board fill
in, or when you need set_screenplay for title, logline or style_bible.
Headless edit_storyboard → set_board writes screenplay-level narration,
music_prompt and motion_design while preserving the other screenplay fields.
Bridge the two with ui_open_document {type: "storyboard", id}.
ui_storyboard_generate_keyframe, ui_storyboard_generate_clip and
ui_storyboard_revise_shot spend exactly what the headless renders spend, and no
permission prompt stands in front of them. Call them only inside a render the
user has already authorized.
The loop
- Find the board.
list_storyboards, or readui_context. No board yet →create_storyboard {name, brief, style, aspect_ratio}. - Cast the entities.
list_entitiesfirst. A new one needs an image asset —generate_imageor the user's upload — thencreate_entity {asset_id, kind, name, descriptor}. There is no create-from-text. - Attach the cast to the board:
edit_storyboard→{op: "set_board", entity_ids: [...]}, orui_storyboard_set_entities {storyboard_id, entity_ids}on an open board. Name matching only searches the board cast, so an entity cast nowhere seasons nothing, no matter what the shots say. An id in a shot's ownentity_idsis added to the board cast when the board is read. - Pin the models.
find_modelwithcapabilitytext_to_image, thenimage_to_videoortext_to_video; write both through{op: "set_board", image_model, video_model}. There is no default — an unset model fails the render rather than spending on a model nobody chose. - Direct. One
{op: "add_shot", ...}per shot. Report the shot count and selected models. Continue to the stages authorized by the request. A board-only request ends here. Honor any checkpoint the user requested. - Stills.
render_storyboard_stills {storyboard_id}— omittargetsfor every shot that still needs one. Cap 24 shots per call. - Take selection, when requested. Every render keeps the old still in
keyframe_versionsand the old clip inclip_versions, and makes the new one selected.edit_storyboard→{op: "select_version", target, kind: "keyframe"|"clip", version}selects another (0-based, oldest first). Pause if the user reserved the pick for themselves in the takes gallery. - Clips.
render_storyboard_clips {storyboard_id}within the requested generation scope and budget. Reuse prior authorization instead of asking again. - Revise one shot:
revise_storyboard_clip {target, instruction}. Needs an existing clip; it is video-to-video and touches no other shot. - Cut.
assemble_storyboard_timeline, thenvalidate_timeline. Re-running rebuilds the same sequence in place and keeps tracks the board does not own. - Finish with
edit_timelineops (Tool contract § Timeline, below). Loadtimeline-edit-opswithload_skillfor the full op list, the presets and the preview contract, andmotion-graphicsfor the build loop. A repair on a delivered clip belongs tonodetool-video-post.
Stills-only mode. When the user wants a board and frames but no motion — a spec
ad, a pitch, a look test — run steps 1 to 7 and stop. Adding the motion later is
update_shot on motion alone: action, wardrobe, set and cast stay put, so the
approved stills still describe the finished piece.
What actually reaches the model
The prompt is assembled from named fields, comma-joined, not from the whole shot:
| Field | Still | Clip, keyframe mode |
Clip, direct or reference mode |
|---|---|---|---|
action |
yes | yes | yes |
camera.framing |
"<framing> shot" |
— | "<framing> shot" |
camera.angle |
yes | — | yes |
camera.lens |
"<lens> lens" |
— | "<lens> lens" |
the shot's scene lighting |
yes | — | yes |
motion |
— | yes (first) | yes |
camera.movement, camera.equipment |
— | yes | yes |
board style |
yes | — | yes |
A keyframe-mode clip animates a still that already carries framing, lens,
lighting and style, so the clip prompt leaves them out. Write camera direction
into the camera object, not into action as well. dialogue, notes,
duration_seconds, end_state, sound and graphics never enter a per-shot
prompt (end_state and sound feed the one-take prompt only).
Entities season by plain name. A shot with entity_ids uses exactly those.
Otherwise: every style and location entity applies to every shot, and a character or
prop applies when its name appears in the shot's action, motion, dialogue,
narration or slug. Write Nova reaches for the bottle, not @Nova reaches....
@ is a chat-composer affordance that emits an entity://<id> token into your
message; it never becomes shot text.
Locks
- Keep one
descriptorper entity and let it do the work. Do not re-describe a face in shot text. - A state change (wet hair, a stained shirt, a second outfit) is a second entity, not an instruction inside one prompt.
- Product geometry, label and colour come from the product entity's descriptor and reference image. Never invent a logo.
- Give every shot a stable
slug(1a,2a, …) atadd_shottime. Headless targets accept it, and "fix 3a" then means one shot. - Render mode is per shot.
keyframe(default) is cheaper to iterate and holds a look steady.directskips the still — worth it for heavy motion, where first-frame conditioning stiffens the result, and for native-audio video models, which are weakest on their image path. - A native-audio model writes the sound per clip, so a board of one clip per shot
cuts the audio at every join. Before rendering, load the
video-audio-continuitysystem skill throughload_skill: either the whole piece is one shot carrying the cuts, or the continuity comes from a narration or music track and the shot audio is muted. A silent cut is also valid when sound is not requested. Reuse existing audio or keep the cut silent when extra generation would exceed the authorized scope.
Where the models will not do what the cut wants
Four constraints that are not bugs and have no tool to fix them. Each has a working shape.
A video model returns the lengths it offers. The render sends
duration_seconds, and the model snaps it to its own steps — a shot directed at
1.5s comes back at 5.184s on a model whose shortest clip is that long. For a run of
beats shorter than the model's shortest clip, render one generation with bracketed
timecodes in the prompt and record the split with covered_by. Tool contract
§ Fusing shots, below, has the call and the rule for when to fuse and when to
render each beat long and trim.
Moderation reads the words, not the story. A prompt naming institutional force — police grabbing someone, a raid, restraint — trips a safety filter that a shot of the same threat does not. Reframe with non-trigger vocabulary and keep the stakes: "two uniformed city officials approaching with a clipboard and caution tape" passes where "two aggressive police officers grabbing her arms" does not. Reframe once; do not retry the rejected prompt.
A music model cannot leave a hole. Ask for 1.5s of silence at 00:19.5 and the decoder fills it with reverb tail and room tone — there is no envelope gate in the prompt. Cut the silence on the timeline instead: generate the score in two parts, lay them as two clips with the gap between them, and fade the first out (~300ms) and the second in (~100ms) so the edges are not clicks.
Speech does not fit a 1.5s shot. An expressive take of a line runs 4s, and compressing it to the picture beat makes it sound processed. Let the words cross the cut: keep the voiceover clip on its own track and start it under the previous shot (J-cut) or run it past the cut into the next (L-cut). The picture cuts on the beat; the line finishes where it finishes. On a script-linked board that is automatic — each shot runs as long as the lines it covers — so use this on an unlinked board or where the picture has to stay on the beat.
Gating and spend
Permission mode decides what runs without asking. read tools always run.
| Mode | write / execute / external |
|---|---|
auto |
runs |
default |
asks the user |
plan |
blocked |
plan blocks create_storyboard and edit_storyboard too, so the board cannot be
written in it. Respect the active permission mode and tool approval responses. For a board-only
request, write the board and omit render calls. Do not switch modes or use browser
tools to evade a denied headless action. A tool being callable does not authorize
spend beyond the user's request.
You cannot price a render. No tool estimates it, and Shot.cost_estimate is not
populated. Report the shot count, the clip count and the models without inventing a
dollar estimate, and confirm that scope with the user before fanning out a clip
pass the request did not already size. If a user
budget cannot be checked before spending, resolve that constraint first. Report
actual spend afterwards with get_cost_summary. If authorization is missing,
prepare the board and explain the specific render action that needs approval.
Memory
memory_save is durable across every conversation — use it for the style bible, the
cast and the grade, with the entity and board ids in resources. share_result /
read_shared are run-scoped and discarded; they are for passing values inside one
turn, not for locking a look across sessions.
Follow-ups this loop already handles
Fix 3a only. Leave the rest.
Drop the contre-jour across the whole board — soft even daylight. Update the
board style, do not rewrite the shots.
New still on 2a. Keep the old take.
revise_storyboard_clip 5a: darker, add rain, same blocking.
Add a reaction shot after 3a and re-slug from there. Do not re-render 1a-3a.
Collapse 8, 9 and 10 into one 8s shot, keeping the lean-in as the last second.
The face drifted on 4a. Select still take 2, then regenerate the clip.
The label is unreadable on 2a. New macro still, then a clip from it.
Cut it. Assemble, validate, narration on its own track, mute Shot Audio on 1-6.
What is below
- Tool contract — every tool, its arguments, and the fields it refuses.
- Standing orders — an optional brief for users who explicitly want approval between stages. Its sample checkpoints do not add requirements to a different request.
Tool contract
The one copy of the storyboard contract; the job and structure skills point here. Exact arguments. Every field named here is checked in the implementation; an unrecognized field is refused with an error, not dropped.
Storyboard — headless
Work with no editor open. Shot target = shot id, 0-based index as a string, or slug.
| Tool | Arguments |
|---|---|
list_storyboards |
limit? → id, name, shots, with_keyframe, with_clip, timeline_id, updated_at |
create_storyboard |
name (required), brief?, style?, aspect_ratio? (default 16:9), project_id?, id? → {ok, storyboard_id, id, name, project_id, shots, updated_at, revision}; storyboard_id and id hold the same value |
get_storyboard |
storyboard_id → brief, style, aspect ratio, narration, music_prompt, motion_design, image_model, video_model, script link, revision, and every shot with id/index/slug/action/camera/motion/duration/status/has_keyframe/has_clip/covered_by |
edit_storyboard |
storyboard_id, ops[] — see below, expected_revision? (refused if the board changed since that revision) |
direct_storyboard |
storyboard_id, redirect?, shot_count? (default 6), provider?, model? — the Director writes scenes and shots from the board's brief, genre and style; set the brief with set_setup first. Renders nothing |
render_storyboard_stills |
storyboard_id, targets?, provider?, model?, style?, stale_only?, concurrency? |
render_storyboard_clips |
storyboard_id, targets?, provider?, model?, resolution?, mode? (keyframe|direct|reference), stale_only?, concurrency? |
revise_storyboard_clip |
storyboard_id, target, instruction, provider?, model? |
assemble_storyboard_timeline |
storyboard_id, name?, fps? (default 30) |
derive_shot_from_clip |
timeline_id, clip_id, frame_count? (1-8, default 3), action? — a new reference-mode shot after the source shot, conditioned on frames of that clip. Renders nothing |
extract_script_from_storyboard |
storyboard_id, name?, relink? |
delete_storyboard |
storyboard_id |
get_storyboard_one_take |
storyboard_id → prompt (the creator's), compiled (REFS, STEPS, AUDIO from the board), full_prompt, references with [Image N] (the shot stills, in shot order), shot windows, duration, settings (stored duration_seconds, aspect_ratio, resolution, model), effective (after board fallbacks), warnings |
update_storyboard_one_take |
storyboard_id, prompt?, duration_seconds?, aspect_ratio?, resolution?, model? {provider, id, name?} (null clears one), shots? [{shot_id, end_state?, sound?}], expected_revision? |
Render limits: 24 shots per call, concurrency default 3, max 8.
Omitting targets selects every shot that still needs that step. For stills that is
every shot with no keyframe that is not set to render directly; for clips, every shot
with no picture — its own or one it is covered by (§ Fusing shots). A keyframe-mode
shot that reaches render_storyboard_clips with no
still is reported in the results, not rendered — render its still first, or set its
render_mode to direct. Each render appends to keyframe_versions /
clip_versions and makes the new one selected.
edit_storyboard ops
Fifteen ops, applied in order, at most 60 per call:
| Op | Arguments |
|---|---|
add_shot |
shot fields below; action required; index? or after_shot_id? (inserts after that shot, in its scene) |
update_shot |
target + any shot fields |
remove_shot |
target |
reorder_shot |
target, index (board position) |
move_shot |
target, scene_id?, position (0-based inside the target scene) — how a shot changes scene |
duplicate_shot |
target — the copy lands right after it, without script links or coverage |
set_board |
board fields below |
set_setup |
brief?, genre?, stage? (the guided-setup answers direct_storyboard reads) |
update_scene |
scene_id, slugline?, lighting? |
create_scene |
after_scene_id?, slugline? — opens holding one blank shot |
merge_scene |
scene_id — folds it into the scene before it |
set_style |
entity_id (a style entity becomes the board preset and its descriptor the board style) or style (the descriptor alone) |
select_version |
target, kind (keyframe|clip), version (0-based, oldest first) — nothing re-renders |
delete_version |
target, kind, version — the asset stays in the library |
add_keyframe_version |
target, asset_id, flip_of? — attaches a stored image as a new still and selects it |
set_entities is accepted as an alias of set_board, and a few other near-miss
names resolve the same way; an unknown op is refused.
Shot fields (add and update both): action, slug, camera, motion, end_state,
sound, graphics, production, dialogue, narration, notes, duration_seconds,
duration_source (audio|manual), render_mode (keyframe|direct|reference),
entity_ids, location_id, covered_by, scene_id.
graphics is semantic design intent (mode, direction, exact text/assets in elements), not Timeline keyframes; pass null on update_shot to clear it.
production holds the shot's production requirements (media_strategy,
protected_inputs, …). A selection holding a shot with an asset in
protected_inputs makes render_storyboard_stills return an error, and one holding
a media_strategy: "still_motion_graphics" shot does the same to
render_storyboard_clips.
end_state (the picture the shot ends on) and sound (what is heard) are one-take
cues; update_storyboard_one_take sets them too.
A one take sends the shot stills as [Image N] by default. A still fixes the
framing and pose of one instant, so for an action shot the model holds that instant
instead of playing the action: a still of a splash at its peak renders as a shoe
hovering over frozen water. For a board with action, set reference_source: "entities" on update_storyboard_one_take. The take then sends the reference
image of each board entity the shots use, and the shot text sets framing and
motion. Give the cast and the location entities clean reference images first.
camera is {framing?, lens?, angle?, movement?, equipment?}.
covered_by is {shot_id, start_seconds?, end_seconds?} — this shot's picture is a
window into another shot's clip. See § Fusing shots below. null undoes it.
Board fields (set_board only): brief, style, aspect_ratio, entity_ids,
image_model, video_model, narration, music_prompt, motion_design. Any other
key is refused with an error naming this set. The two model fields
take a model object from find_model (its .ref), or null, and become the
defaults for both render tools. narration and music_prompt take strings and
update the screenplay; an empty string clears one. motion_design is
{direction?, transitions?: [{from_shot_id, to_shot_id, direction?}], continuities?: [{id, shot_ids, direction}]}, or null to clear it.
An edit cannot set keyframe, clip or status. Those belong to the render
tools; passing them raises an error naming the right tool. covered_by is the one
exception: coverage is a picture that arrived without a render, so setting it marks
the shot rendered and clearing it puts the shot back to keyframe_ready/planned.
An edit cannot set title, logline or style_bible at the board level.
Use ui_storyboard_set_screenplay for those fields. Per-shot narration remains
a shot field. Board narration and music are separate screenplay fields:
assemble_storyboard_timeline turns the music prompt into a draft music clip on
every board, and the board narration into a draft narration clip on a board with
no linked script (a linked board voices its script lines instead).
Fusing shots
A video model snaps the requested length to the ones it offers — 5.184s, 6s, 8s — so a beat shorter than its shortest clip still buys the whole clip. A cut whose beats run 1.5-2.5s is therefore cheaper to render as one generation covering a run of shots and split afterwards, than as one generation per shot: fifteen 1.5-2.5s beats bought one at a time is ~77s of footage for a 30s cut.
Fuse a run of consecutive short beats that one prompt can carry: the same location and cast, cuts the model can make inside one take. Render a beat as its own clip and trim it on the timeline when it needs a picture no neighbour can share, a different place, or its own still. Each of those clips is footage the cut throws away, so report how many clips the board will buy before the clip pass and get the user's go-ahead when that is more than the request implied.
Direct the run as one prompt with bracketed timecodes
([00:00 to 00:02.5] Event … [00:02.5 to 00:05.2] Reception), render it on the first
shot of the run, then tell the board which slice each sibling uses:
{"op": "update_shot", "target": "06",
"covered_by": {"shot_id": "05", "start_seconds": 2.5, "end_seconds": 5.184}}
The covered shot then reads has_clip: true with status: "rendered", is skipped by
render_storyboard_clips (so it is never generated twice), and
assemble_storyboard_timeline lays it down as that window of the covering clip
instead of skipping it, and the covering shot ends where the first covered shot takes
over. Without end_seconds the covered shot runs to the end of the covering clip.
One hop only: shot_id must name a shot that owns its clip, not another covered shot.
Removing the covering shot clears the coverage and reports which shots it uncovered.
Storyboard — browser (ui_storyboard_*)
The board must be open as a workspace tab; its id comes from the ui_context system
block. Not open → edit_storyboard edits the saved board. Use ui_open_document {type: "storyboard", id} to show it to the user. Target =
shot id, index as a string, or "selected". Slugs are not resolved here.
| Tool | Arguments |
|---|---|
ui_storyboard_get_state |
storyboard_id |
ui_storyboard_set_screenplay |
storyboard_id, screenplay |
ui_storyboard_set_entities |
storyboard_id, entity_ids (replaces the cast; [] clears it) |
ui_storyboard_add_shot |
storyboard_id, action, slug?, camera?, motion?, graphics?, production?, durationSeconds?, index?, afterShotId? |
ui_storyboard_update_shot |
storyboard_id, target, action?, slug?, camera?, motion?, graphics?, production?, dialogue?, notes?, durationSeconds?, durationSource?, status? |
ui_storyboard_remove_shot / _duplicate_shot |
storyboard_id, target |
ui_storyboard_move_shot |
storyboard_id, target, sceneId?, position |
ui_storyboard_set_setup |
storyboard_id, brief?, genre?, stage?, shotCount?, importSource?, directedFrom? |
ui_storyboard_direct |
storyboard_id, redirect, shotCount? |
ui_storyboard_update_scene |
storyboard_id, sceneId, slugline?, lighting? |
ui_storyboard_create_scene / _merge_scene |
storyboard_id, afterSceneId? / sceneId |
ui_storyboard_set_style |
storyboard_id, entityId? or descriptor? |
ui_storyboard_select_version / _delete_version |
storyboard_id, target, kind, version |
ui_storyboard_add_keyframe_version |
storyboard_id, target, assetId, flipOf? — adds the still without selecting it |
ui_storyboard_generate_keyframe |
storyboard_id, target, staleOnly? |
ui_storyboard_generate_clip |
storyboard_id, target, staleOnly? |
ui_storyboard_revise_shot |
storyboard_id, target, instruction |
ui_storyboard_assemble_timeline |
storyboard_id |
ui_storyboard_select_shot |
storyboard_id, target (nullable) |
ui_storyboard_extract_script / _relink_script / _reproject_shots |
storyboard_id (+ targets?) |
ui_storyboard_set_duration_source |
storyboard_id, targets, source |
The browser shot tools take no narration, entity_ids or render_mode, and
add_shot takes no dialogue. In the browser those arrive through
set_screenplay; headless, through edit_storyboard.
Generation is asynchronous: generate_keyframe / generate_clip start the job and
return the shot. Poll ui_storyboard_get_state for status.
Statuses: planned → keyframe_generating → keyframe_ready → clip_generating →
rendered, or failed. (approved is legacy and reads as "still ready"; nothing
sets it. Do not use it as a gate.)
screenplay for set_screenplay
{
"type": "screenplay",
"title": "…",
"logline": "…",
"brief": "…",
"styleBible": "…",
"aspectRatio": "9:16",
"narration": "…",
"musicPrompt": "…",
"entityIds": ["<asset id>"],
"shots": [
{
"slug": "1a",
"action": "Nova touches untreated hair, front-camera close",
"camera": { "framing": "close-up", "lens": "26mm", "angle": "eye", "movement": "handheld" },
"motion": "she lifts one section of hair and lets it fall, once",
"dialogue": "I wanted lighter hair…",
"durationSeconds": 4,
"entityIds": ["<asset id>"]
}
]
}
Ids, indexes and statuses are filled in. style is accepted as an alias of
styleBible. Only action is required per shot.
The top-level entityIds casts those entities on the board — that cast is what
seasons every shot's still and clip prompt. Use ui_storyboard_set_entities to
recast without replacing the shots; ui_storyboard_get_state reports the current
cast as entityIds. A shot's own entityIds overrides the board cast for that shot
([] means "no entities on this shot"); without one, styles and locations apply to
every shot and characters and props apply to the shots whose text names them.
Entities
| Tool | Arguments |
|---|---|
list_entities |
kind? (character|location|style|prop), query?, limit? |
get_entity |
entity_id |
create_entity |
asset_id, kind, name, descriptor (all required), description?, voice_id?, tags?, lora?, palette? |
update_entity |
entity_id + any field, including asset_id to move it to a new photo |
delete_entity |
entity_id — clears the marker, keeps the image |
apply_entities |
text, entity_ids? → seasoned prompt + reference asset ids |
An entity is an image asset carrying a marker. Its id is the asset id. To make one
from nothing: find_model (text_to_image) → generate_image → create_entity with
the returned asset id. To make one from a photo the user attached: find it with
asset_search / list_assets, then create_entity.
apply_entities is for seasoning a prompt you are about to send yourself
(generate_image, generate_video). The storyboard render tools season internally —
do not pre-season shot text with it.
Timeline
assemble_storyboard_timeline lays rendered clips end to end, stamps each with its
board and shot id, and gives every shot clip an audio twin on a "Shot Audio" track
(each surface mutes video elements and mixes audio clips only). Board narration and
music become draft clips on their own tracks.
Each shot is as long as its render, not as long as its duration_seconds — a shot
directed at 1.5s that came back at 5.184s occupies 5.184s of the cut. Shots that came
back off their directed length are returned in retimed_shots and warned about, so a
cut that runs longer than planned is visible without playing it. duration_seconds
only decides a shot whose footage has no measurable length. A board linked to a script
is the exception: there the words decide, and trimmed_shots names the shots whose
footage does not fill the slot its lines gave it.
edit_timeline {timeline_id, ops[]} carries the edit; timeline-edit-ops holds its
full op list. Start with get_state for ids.
To duck the shots' own sound under a voiceover: set_clip_params on the Shot Audio
clips with muted: true, or volumeDb: -18. set_clip_params also takes name,
opacity, speedMultiplier, fadeInMs, fadeOutMs, blendMode, borderRadius,
hidden, locked, textStyle, shapeStyle.
Every field goes on the op itself. A params / props wrapper is unwrapped, but the
flat form is the contract:
{"op": "set_clip_params", "target": "clip_1",
"textStyle": {"fontFamily": "Space Grotesk", "fontWeight": 800}}
textStyle is merged over the clip's own, so send only what you are changing —
re-sending the whole object is how the fields you did not mean to touch get
overwritten. fontWeight is a number, and the CSS keywords (bold, semibold,
extrabold) are accepted and stored as one.
Set a bundled family or none at all. sans-serif, serif, system-ui and the
other CSS generics are refused where the clip is authored: they name no typeface, so
the editor preview, the render and preview_timeline_frame each pick a different one.
NodeTool ships Inter (the default), Space Grotesk, Bebas Neue, Playfair Display, Lora
and JetBrains Mono. A named system font is still allowed and validate_timeline
reports it as font_not_portable.
validate_timeline {timeline_id | document, fps?} after every edit pass. It catches
overlaps, fades longer than their clip, unknown presets and incomplete bindings.
Other timeline tools: list_timelines, create_timeline, get_timeline,
delete_timeline, and the version family (list_/get_/create_/restore_/
delete_timeline_version). Browser twins are ui_timeline_*.
Script
Use a script when the words drive the cut. extract_script_from_storyboard projects a
board's dialogue and narration into a script and links the two: each shot keeps the
line ids it covers, and from then on the script owns the words. derive_storyboard_from_script
goes the other way, one shot per line, optionally with a director pass over the scaffold.
voice_script_lines synthesizes each line with its cast voice; assemble_script_timeline
lays the takes end to end.
Give the cast their voices first, then voice with no override. A line takes its
voice from its speaker: add_line without speaker leaves it with none, and
extract_script_from_storyboard creates the Narrator with no voice and each
character with at most its entity's voice_id and no provider or model. Either way
the line reads no_voice until its speaker is bound. A voice is the
triple {provider, model, voice} where voice is the voice's own name (Aoede,
Charon, alloy) — a provider and a model alone do not pick one, so
voice_script_lines {provider, model} is refused. Set each speaker once:
{"op": "set_speaker_voice", "target": "MOM",
"provider": "gemini", "model": "gemini-2.5-flash-preview-tts", "voice": "Aoede"}
The three keys sit on the op, though a voice: {provider, model, voice_id} object —
the shape get_script reports a voice in — is flattened onto it. Then call
voice_script_lines {script_id} with no override and every speaker resolves its own. On a linked board, assemble_storyboard_timeline cuts words
and picture together: each shot runs as long as the takes it covers and every voiced
line gets its own voiceover clip.
Others: list_scripts, get_script (line status: draft, stale, voiced,
no_voice), create_script, edit_script, delete_script. Browser twins are
ui_script_*.
Writing the lines
create_script makes an empty one. edit_script {script_id, ops[]} ops:
set_setup (brief, format, length, pace, language, stage), add_speaker,
set_speaker, set_speaker_voice, add_section, add_line, set_line_text,
set_line_speaker, remove_line, remove_speaker. Call get_script first for
line and speaker ids.
write_script {script_id, rewrite?, imported_text?} drafts the lines from the
setup and saves the cast and lines it produces, replacing what was there. Set
the brief with set_setup first. rewrite: true keeps the ids of the lines it
keeps, so their takes and storyboard links survive. Words passed as
imported_text are only split into lines and attributed to speakers, never
reworded. It records no take: voice the result with voice_script_lines.
Rewriting a line leaves its takes in place as stale, so a following
voice_script_lines re-records exactly those and nothing else.
Models
find_model {capability, query?, task?, provider_hint?, model_hint?, prefer_local?, limit?} is the only way to name a model. capability is required and is one of
text_to_image, image_to_image, segment_image, text_to_video, image_to_video,
reference_to_video, text_to_speech, text_to_music, audio_to_audio,
automatic_speech_recognition, generate_embedding, generate_message. query is the search box ("flux schnell"); task is a hint
matched against a model's supported tasks, not a search.
NodeTool ships curated ids under the nodetool provider, which are the sane defaults
when the user has no preference:
| Id | Use |
|---|---|
nodetool/flux-schnell |
cheapest stills, text prompts only |
nodetool/nano-banana |
sharper stills, takes reference images |
nodetool/seedream |
most detail, slowest |
nodetool/hailuo-fast |
cheapest clips, for blocking out a cut |
nodetool/kling-turbo |
steadier motion, mid price |
nodetool/kling-standard |
most faithful motion |
nodetool/kokoro |
eight TTS voices |
Media, outside the board
generate_image {provider, model, prompt, negative_prompt?, width?, height?, quality?, output_file?}, plus edit_image, generate_video, animate_image, generate_speech,
generate_music and transcribe_audio — each takes a find_model provider+model and
saves an asset:// result. model also accepts a whole find_model hit or its .ref,
in which case provider may be omitted.
understand_video {provider, model, video, prompt?, max_tokens?} reads a whole video
with a multimodal model (Gemini reads video natively); use it to break down a reference
cut. video takes an asset id, an asset:// URI, a URL or a data URI. view_image
puts pixels in your own context; read_media_bytes returns the bytes.
The Director node
nodetool.creative.Director is a workflow node, not a chat surface. It turns a
brief into a Screenplay (props: model, brief, style, shot_count, aspect_ratio,
max_tokens; outputs
screenplay, narration, music_prompt, title). Reach for it only inside a
reusable graph. In chat, direct_storyboard runs the same Director over a saved
board, or write the shots yourself with edit_storyboard.
Still-motion-graphics boards
A board whose shots carry production.media_strategy: "still_motion_graphics" renders
no clips: its stills and graphics elements become timeline layers.
preview_storyboard_design {storyboardId, expectedStoryboardRevision} reads the design
as a timeline preview with no save. layout_storyboard places every layer at each
shot's hold frame with a vision model. finish_storyboard writes the editable
timeline: strategy: "deterministic" (default, no provider) returns an unreviewed
scaffold, "agentic" composes the motion and reviews rendered frames. All three
need the board's current revision from get_storyboard.
Standing orders
Use this optional template only when the user wants a staged review with approval between the board, stills, clips, and cut. Its checkpoints express that user's chosen workflow. They do not apply to other requests or override authorization already given to finish a piece.
Respect the thread's existing permission mode. Plan mode blocks writes. Do not switch modes or use another tool family to evade a denial. The user can adapt the brief to authorize the desired stages and set a budget.
You are directing on the storyboard surface, then finishing in the timeline.
Do not build a node graph unless I ask for a reusable template.
SURFACES
Headless: create_storyboard, get_storyboard, edit_storyboard,
render_storyboard_stills, render_storyboard_clips, revise_storyboard_clip,
assemble_storyboard_timeline, extract_script_from_storyboard.
Browser (only for a board open as a tab): ui_storyboard_get_state,
ui_storyboard_set_screenplay, ui_storyboard_generate_keyframe,
ui_storyboard_generate_clip, ui_storyboard_revise_shot,
ui_storyboard_assemble_timeline. Use ui_open_document to open a board.
The ui_ generate and revise calls spend like the headless renders: same
approval rules.
LOOP
1. list_storyboards, or read ui_context. No board -> create_storyboard.
2. Cast before anything renders. list_entities first. A new entity needs an
image asset: generate_image (or my attachment), then create_entity with
{asset_id, kind, name, descriptor}. There is no create-from-text.
Each entity: one name, one kind, one canonical descriptor sentence.
3. edit_storyboard set_board {entity_ids, image_model, video_model,
brief, style, aspect_ratio, narration, music_prompt}. Models come from find_model — there is no
default and an unset model fails the render.
4. Direct with edit_storyboard add_shot, one op per shot. Give every shot a
slug (1a, 2a, ...). Fields: action, slug, camera {framing, lens, angle,
movement}, motion, dialogue, narration, duration_seconds, render_mode.
5. STOP after the board. Report shot count and the two model ids. Do not
estimate dollars — no tool prices a render. Wait for "stills".
6. render_storyboard_stills. I pick takes in the board's takes gallery, or
tell you which one; you apply it with edit_storyboard select_version.
Wait for "clips".
7. render_storyboard_clips. revise_storyboard_clip touches one shot only.
8. On "cut": assemble_storyboard_timeline, then validate_timeline.
WRITING THE SHOTS
The still prompt is action, camera framing, angle and lens, the scene
lighting and the board style. A keyframe clip prompt is motion, action,
camera movement and equipment; a direct clip gets all of these. Write camera
direction into the camera object once, not into action as well.
Name entities in plain text — "Nova reaches for the bottle", never "@Nova".
Entities season a shot when their name appears in its action, motion, dialogue,
narration or slug; styles and locations season every shot. A shot's entity_ids,
if set, overrides that entirely.
LOCKS
- The descriptor is the face. Do not re-describe an entity in shot text.
- Product geometry, label, cap and colour come from the product entity. No new
logos.
- A state change (wet, stained, new outfit) is a second entity, not a morph
instruction inside one prompt.
- Slugs stay stable. "Fix 3a" edits 3a and renders 3a.
- UGC: handheld phone, grain, natural audio, no score, no beauty filter.
Hero: locked grade in the style, smooth camera, score allowed.
- render_mode "keyframe" (default) for anything where the look must hold;
"direct" for heavy motion or a native-audio video model.
MEMORY
memory_save the style, the cast and the grade, with the entity and board ids in
`resources` — that survives into later threads. share_result/read_shared are
run-scoped and get discarded; do not use them to lock a look.
If the shot count looks expensive, propose a collapse before rendering clips.
04 同仓库更多 Skills
humanizer
Rewrite AI-sounding text so it reads like the writer without changing what it says. Use when editing or reviewing prose for AI tells: not-X-but-Y contrasts, one-line closers, staged openers, forced triads, dashes everywhere, inflated claims, sales language, stock AI words, bold labels, or filler.
nodetool
Use the NodeTool MCP server to build, validate, run, and debug visual AI workflows, and to work with assets, collections, and jobs. Use when the user mentions NodeTool or asks for a workflow graph, a node, or a media generation run on their NodeTool server.
wan-2-6-prompting
Prompt Alibaba's Wan 2.6 video — text-to-video with a global style line plus timing-bracketed shots, and image-to-video that describes only what changes over time. Covers the shot-mode switch per provider, the prompt budget, negative prompts, motion intensity wording, audio input and prompt expansion. Use whenever the model id names a Wan 2.6 video route (alibaba/wan-2.6/text-to-video, alibaba/wan-2.6/image-to-video, wan-video/wan-2.6-t2v, wan-video/wan-2.6-i2v, wan-video/wan2.6-i2v-flash) on generate_video, animate_image or a TextToVideo node. Not for Wan 2.5 or 2.7, or the Wan 2.6 image routes.
video-workflow
Build a reusable NodeTool video workflow for batches or repeated inputs. For a single finished piece, use a storyboard skill.
video-clone
Analyze a reference video and recreate its shot structure with a new product or cast in NodeTool.
video-audio-continuity
Keep sound continuous across a multi-scene piece cut from generated video — why one clip per scene hard-cuts the audio at every boundary, when to write all the scenes into a single generation instead, the sound-design vocabulary that survives a provider's copyright filter, and how to check the length, the aspect ratio and the mix of what came back. Use when a piece has more than one scene and the video model writes its own audio (Seedance 2, Veo 3, MiniMax H3, Kling 2.6 and later), or when a cut's sound drops out at the shot changes.