Motion Graphics

Motion Graphics → Timeline Agent

Before the first edit of a new piece

When starting a piece from a brief, load motion-direction and motion-principles with load_skill before the first timeline edit. Use them to set the motion language and timing for the whole piece. Do not start animating from this file alone.

If the piece has a title layout or an end card, also load frame-composition before that first edit. If it has an end card, load logo-reveal too. These loads are required even when this skill was the only one selected from the catalog.

For showcase, hero, launch, or "best" briefs, follow motion-direction's depth plan and example timelines before writing scenes.

Motion is built, then checked. Author with the pack or with ops (below), then look at the frames with preview_timeline_frame. A change you have not looked at is not done.

Load other craft skills for the job

This file is the build loop and the entry point, not the op contract. After the required loads above, load other relevant craft skills for the job and come back here to pick the authoring surface.

Three are neighbours rather than layers. caption-titles decides what text says and when it appears. video-audio-continuity decides, before the first clip renders, whether a multi-scene piece's sound comes from one generated clip or from a track of your own — a decision this file's ops cannot undo. The board skills (explainer-storyboard, commercial-beat-sheet, launch-commercial, music-video-treatment, trailer-template) decide the shots before there is a timeline to animate; assemble_storyboard_timeline is where their board becomes this file's document.

Anything generated for the timeline — a bed, a sting, a voice, a clip — has a model line with its own guide. find_model returns prompting_skill on a route it covers; load_skill it before writing that prompt.

The build loop

Build a piece in four moves: direct (fix the motion language and the scene list before writing anything — motion-direction and, when there is a title or end card, frame-composition/logo-reveal), build (write the scenes in code, one v.scene per beat), save (v.save() attaches the code; read saved.code and saved.warnings), review (the pass below). Revise by editing that script — see below — and repeat the last two steps. A piece that renders clean on the first save has not been looked at yet.

Choose the authoring surface

Two ways to touch a timeline document. Pick by what changed, not by habit.

Code, for a new cut. In a JS script or a Code node, import { video } from "@nodetool-ai/sandbox-timeline". Its video() builds a document of scenes (v.scene(name, seconds, fn), local time in seconds), lays them out with v.series([...]), and v.save(nodetool.timelines, {...}) writes the whole document in one call and returns {timeline_id, errors, warnings}. A cut with hundreds of keyframed clips costs a handful of API calls this way, instead of one edit_timeline op per clip. NodeTool's shipped example timelines (Cadence, Kite, Prism, Voltra, Tidewater, T minus 30) are built with it. Its full signatures, options and gotchas are the pack's own skill — read nodetool.packs.docs("@nodetool-ai/sandbox-timeline") before writing scenes, not this file. frame-composition covers how to lay out what goes inside a scene; this file covers the build loop and the ops surface below.

Ops, for an edit. edit_timeline takes a timeline ID and an ops array, run in order, up to 60 per call:

{"timeline_id":"<id>","ops":[{"op":"animate_clip","target":"Title","animations":[{"role":"in","preset":"fade","durationMs":400}]}]}

Its full op shapes, what each op refuses, and when a change instead needs a whole-document set_timeline_document write are timeline-edit-ops — load it before a batch of ops, not this file.

A compact two-scene piece

The build loop end to end: a backdrop, a laid-out title block, a counter, a transition, a finish pass, save, then read the warnings.

import { video } from "@nodetool-ai/sandbox-timeline";

const v = video({
  width: 1920, height: 1080, fps: 30,
  palette: { ink: "#06110e", ink2: "#0c2a21", text: "#f4fbf8", accent: "#34d399" },
  fonts: { display: "Space Grotesk", body: "Inter" }
});

const hello = v.scene("Hello", 2.5, (s) => {
  s.backdrop();
  const kicker = s.kicker("LIVE");
  const title = s.text("Round-ups", { size: 120, weight: 700, font: "display" });
  const sub = s.text("on every card", { size: 40, color: "#8fb3a6" });
  s.stack([kicker, title, sub], { gap: 20 }); // frame-composition: a title block
  title.enter({ from: { scale: 1.2, opacity: 0 }, dur: 0.3, ease: "outExpo" });
  sub.enter({ from: { offsetY: 24, opacity: 0 }, at: 0.15, dur: 0.25 });
});

const outro = v.scene("Outro", 1.8, (s) => {
  s.backdrop({ colors: ["#0f3b2e", "#06110e"] });
  const counter = s.text("$0.00", { size: 96, font: "display" });
  counter.count({ from: 0, to: 1.6, dur: 1.2, prefix: "$", decimals: 2 });
  s.finish({ vignette: 0.2, grain: 0.05 });
});

v.series([hello, v.transition("wipe", 0.3, { direction: "left" }), outro]);

const saved = await v.save(nodetool.timelines, { name: "Round-ups", showcase: true });
if (saved.warnings.length) {
  // read them before calling this done — see Review pass below
}

Author and revise with code

v.save(nodetool.timelines, {...}) attaches the code that rebuilds the timeline as its source — no separate code.set call. The stored code is the retained program: the scene callbacks and the helpers they use, with every research result, generated asset id and loop value written in as a literal. The calls that produced those values ran once, in your action, and a rebake never repeats them. saved.code.embedded is false, with the reason in saved.code.warnings, when a scene callback calls nodetool.*, uses Math.random()/Date.now(), or reads a value that is not plain data. Do the research and generation at the top level, then build the scenes from the results. To attach code after the fact, nodetool.timelines.code.set(timeline_id, code) bakes the code, which must build the timeline without a capability call.

Revising a code-backed timeline is: code.get(id) → code.edit(id, edits) with a few small exact string replacements (each old matches exactly once) → read the conflicts and warnings it answers → look at frames. This is the review → revise → rerun loop from the build loop above, made cheap — a two-line diff instead of a 500-line resend. edit_timeline ops still apply for a timeline with no code, or a deliberate hand tweak — timeline-edit-ops owns that contract and what it costs a code-backed scene. The pack's own skill (@nodetool-ai/sandbox-timeline) covers what code-backed identity means for scene names and clip ids; api-timelines owns the full code.* call contract.