nodetool-video-post
Repair or re-generate footage already on a NodeTool timeline: cutouts, tracking, outpainting, upscaling, generated sound, voice replacement, lip sync. Covers the candidate review protocol these return.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 635
- Forks
- 91
01 前言 Front Matter
- name
- nodetool-video-post
- featured
- true
- description
- Repair or re-generate footage already on a NodeTool timeline: cutouts, tracking, outpainting, upscaling, generated sound, voice replacement, lip sync. Covers the candidate review protocol these return.
03 SKILL.md 正文
Post on a saved timeline
Footage already exists and something about it has to change. These tools act on one clip of a saved timeline sequence, not on a storyboard shot and not on a loose asset.
Directing a new piece belongs to storyboard-core
and its job skills. Cutting, animating, transitions and titles go through
edit_timeline, whose op list, presets and preview contract live in
timeline-edit-ops: load it with load_skill {name: "timeline-edit-ops"}
before the first edit_timeline call. Building a new cut belongs to
motion-graphics.
Pick the operation
| The problem | Tool | What it writes |
|---|---|---|
| Replace what is behind the subject | isolate_subject |
A generatedMatte on that clip |
| Make another clip follow a moving subject | track_object |
A document-level track others bind_to_track |
| The frame is the wrong aspect ratio | expand_frame |
An inactive video candidate |
| The footage is too soft or too small | upscale_video |
An inactive video candidate |
| The shot has no sound | video_to_audio |
An aligned inactive audio candidate |
| The recorded voice is wrong | recorded_voice_replacement |
An inactive audio candidate |
| The mouth does not match the new audio | lip_sync |
An inactive video candidate |
| A title or shape should move with the music | bake_audio_animation |
A custom animation on the target clip |
isolate_subject takes provider and a model that lists the matte_video
task. list_provider_models shows them. On FAL each BiRefNet variant is its
own model, such as fal-ai/birefnet/v2/video/Matting for hair and
fal-ai/birefnet/v2/video/Portrait for people. A clip with a current matte
gets it back for free unless regenerate: true.
Every other tool above except bake_audio_animation takes provider and
model from find_model. There is no default: an unset model fails the call
rather than spending on a model nobody chose.
Nothing is applied until it is accepted
expand_frame, upscale_video, video_to_audio, recorded_voice_replacement
and lip_sync all return an inactive candidate with its provenance. None of
them changes the accepted take, the sequence dimensions, or the existing
framing. Applying the result is a separate, explicit step:
inspect_video_production_candidates {candidates, preview?}refreshes their state and optionally builds a Preview take or draft from an explicit destination-to-candidateselection. Inspection writes nothing.accept_video_production_candidates {action, batch_id, document_id, project_id, candidates, selection, targets}applies one atomic manifest.actionisuse_takeoruse_draft. Each entry intargetscarriesexpected_target_revision, which the server rechecks before the apply, so a document that moved underneath is refused rather than overwritten.
Report the candidate ids and what each one is, then let the user choose. Never
describe a candidate as applied before an accept returned.
Generating a new take for a slot
A slot that needs fresh footage rather than a repair goes through the reviewed
production path, which covers all three document kinds:
timeline_clip, storyboard_shot and script_line.
prepare_video_production → submit_video_production → inspect → accept.
prepare is non-mutating. It resolves linked script speech, verifies owner,
project, target, references, capability route and timing, then freezes one to
three stable candidate identities before any provider spend. It requires
review: {status: "reviewed", plan_fingerprint} — the fingerprint of every
authoring input the reviewed plan read. The route is
reference_to_video, text_to_video, or audio_driven_performance, and
on-camera speech (speech_mode: "on_camera") requires
audio_driven_performance. submit re-runs preflight and authorization and
recovers an existing request id instead of resubmitting it, so a retry after a
dropped connection does not pay twice.
Per-tool notes
isolate_subject sends the clip's whole source asset and reads the mask
back at the clip's own source time, which is what lets a later trim, split or
speed change keep the cutout aligned. A clip with a current cutout is handed it
back for free unless regenerate: true, and a failed regenerate leaves the
working matte in place. Tune the result with the free set_generated_matte op
(invert, strength, feather, or an earlier version). Use set_matte instead for
a keyhole authored from another clip.
track_object needs initial_region normalized 0..1 over the source frame
plus start_ms and end_ms in absolute source milliseconds. The initial box
sits at start_ms for forward and both, at end_ms for backward. Box
tracks only in this build. A new run is refused before saving or spending when
the provider does not implement track_object.
lip_sync consumes an accepted recorded_voice_replacement candidate:
replacement_audio {asset_id, status, provenance}. Run the voice replacement,
accept it, then sync.
bake_audio_animation measures a clip's audio, with an envelope follower or
one pulse per onset in mode: "beats", and writes a source-anchored custom
animation on another clip's property, commonly scale. The write is additive: a
hand-authored pop or slide on the same channel composes with it rather than
being replaced. A re-bake replaces only the curve it produced before.
source_asset_id on the native media tools is an optional pin captured
before the call. A mismatch is stale and the call is refused. Pass it when
anything else may be editing the document.
Check the result
validate_timeline {timeline_id}after every edit pass.preview_timeline_frame {timeline_id, ...}composites one or more timecodes and returns a per-layer report. It is the cheap way to see a matte, a bake or an accepted take without rendering. Amodel3dlayer needs headless Chromium: with none on the host the layer is left out and reported as amodel3d_unavailabledegradation, never as an empty clip.compare_timeline_framesputs before and after side by side.render_timelineis the paid, final pass. Do not render to check an edit.- Snapshot before a destructive pass with
create_timeline_version.restore_timeline_versionsnapshots the pre-restore state first and re-validates against today's schema, so an old document may fail what it used to pass.
Verify from a shell
These are the nodetool CLI. From a NodeTool checkout the same commands run
as npm run dev:nodetool -- <command>.
nodetool timeline validate <timeline_id|sequence.json> --json
nodetool timeline debug <id> --interact '[{"tool":"add_track","input":{"type":"audio","name":"Music"}}]'
nodetool timeline versions list <timeline_id> --save-type manual
Rendering, playback, decode and generation are not simulated by the harness. The
report says so under notSimulated.
Reference
- The
storyboard-coresystem skill, § Timeline of its tool contract —load_skillit for the board-to-timeline calls.
In a NodeTool checkout, these repository sources go further:
docs/harnesses.md§ nodetool timeline validate / debugdocs/harnesses.md§ Generated mattesdocs/harnesses.md§ Audio-driven timeline motion
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.