API Timelines

Three ways to build

1. In code, for motion graphics. Import @nodetool-ai/sandbox-timeline: scenes of shapes, text and images, keyframed in frames, and saved with saveTimeline in one call. Read nodetool.packs.docs("@nodetool-ai/sandbox-timeline") first. This is the path for a dense, layered piece.
2. setDocument, for a whole document you already hold. It replaces the stored document field for field, so read get(id) and send it back changed. Missing bookkeeping is filled in: track index, visible, locked; clip sourceType, status, locked, versions; animation and effect ids; markers. Pass expected_updated_at to refuse the write when someone changed the timeline after you read it.
3. edit(id, ops), for targeted changes. Start with {op: "get_state"} to read the ids. Check failed and the ok of each entry in ops before a dependent edit. A batch can save its good ops even when a later one fails.

await nodetool.timelines.edit(id, [
  { op: "add_track", type: "audio", name: "Music" },
  { op: "add_text_clip", text: "Hi", startMs: 0, durationMs: 2000 },
  { op: "animate_clip", target: "Hi", animations: [{ role: "in", preset: "fade" }] },
  { op: "set_effects", target: "Hi", effects: [{ type: "blur", radius: 8 }] }
]);

Existing media goes on with {op: "add_media_clip", asset: "asset://<id>.mp4"}, which appends after the last clip on the track. One call for each asset lays them end to end. set_effects replaces the whole chain, and an unknown effect parameter is refused.

The loop: validate, look, fix

1. Study an example before a showcase piece. examples.list(), then examples.get(slug) for the scene catalog, then examples.get(slug, {scene_id}) for one scene. Page long scenes with clip_offset: next_clip_offset until truncated is false. Return only the fields you study; the excerpts are large.
2. Validate. validate(id, {tier: "showcase"}) adds warnings about the count of scene groups, custom animations per visible second, effect variety, clip density, fast motion without blur, the finish, camera depth and concurrent layers. Each warning names an example. Warnings do not change ok. For an inline document, pass normalize: true to fill in the bookkeeping as setDocument does.
3. Look. Validation cannot judge the picture. Preview real frames:
   • times_ms (up to 8) or count (default 3) for single frames.
   • range: {from_ms, to_ms, count} (up to 24) to sweep a move, with sheet: true for one labelled contact sheet.
   • width (default 640, max 1280) and motion_blur_samples with shutter_angle.
   • The sheet comes back as sheet.image. Pass its asset_id to view_image. Without a sheet, each frame has its own image.
   • Sample the middle of an animation, not its ends.
   • A frame's degraded list names where the preview draws differently from the export, and effects_not_applied names effects it cannot draw.
4. Fix and compare. After a change nobody asked for, run compare({timeline_id: id, version: n}, id) to prove which frames it touched. A difference of 0 everywhere means the edit was cosmetic.
5. Render before you call the cut done. render(id, {preview_scale: 0.5}) is a fast draft. wait: true blocks up to timeout_ms (default 180000, clamped to 300000). On a timeout the job keeps going; wait on it with nodetool.jobs.wait(job_id).

Render options

format is mp4 (default), webm, mov or png_sequence. Only webm, mov and png_sequence carry alpha. Also video_codec, bitrate (a number or "8M"), motion_blur_samples with shutter_angle, include_audio (default true) and preview_scale.

Documents from other surfaces

A storyboard or a script assembles into a timeline of its own media (nodetool.storyboards.assembleTimeline, nodetool.scripts.assembleTimeline). For anything else, create your own timeline instead of editing one the user has open.