Reelify Motion Kit 0.1 preview
Docs/Working with it

Editing

Three ways to change a scene without rewriting it: patch operations with JSON Pointer paths, the bridge (snapshot, act, history), and Motion Lang for edits on a talking video.

A change to a scene should be as big as the change, and no bigger. Rewriting a 1,700 character film to alter one number risks everything that was not meant to change. The kit has three edit formats. All three apply whole or not at all, and all three leave what they did not name untouched.

FormatAddresses things byUse it for
Patch operationsJSON Pointer pathFilms: reorder, retime, add or remove scenes, change any value.
The bridgeA ref from a snapshotScenes edited by a person and an agent together, with undo per author.
Motion LangA line per pieceThe edit laid over a talking video.

Patch operations#

A patch is a JSON list of operations. Each has an op and a path.

OperationFieldsWhat it does
replacepath, valueSets what is at the path. The path must already exist.
addpath, valueCreates a key in a record, or inserts into a list at an index. - as the index adds at the end.
removepathDeletes a key, or takes an item out of a list.
movefrom, pathTakes what is at from and adds it at path.

Paths#

A path is a JSON Pointer into the scene: it starts with / and names each step. List items count from 0. /root/children/0/scenes/2/len is the length of the third scene of the Sequence that is the root's first child. A / inside a key is written ~1 and a ~ is written ~0.

For move, the item is removed first, so path is an index in the list as it is after the removal.

All or none#

If any operation cannot be applied, none is. The scene comes back unchanged with one error per failed operation. Each error says what is at that place:

text
/root/children/0/scenes/5/len: nothing at "root/children/0/scenes/5" (there is a list of 3)
/root/children/0/scenes/0/length: there is no "length" to replace (there is a record with len, node); use add to create it

The duration rule#

A film's duration must equal the sum of its scenes' len. A patch that adds or removes a scene, or changes a len, must also replace /duration. A patch that lets the scenes outrun duration leaves a film that does not compile, and the CLI refuses it.

An example#

The film before: three scenes of two seconds.

json
{
  "size": [1280, 720],
  "duration": 6,
  "background": "ground",
  "tokens": { "claim": "Record once", "proof": "Post all week", "name": "reelify" },
  "root": {
    "el": "box", "dir": "stack", "w": "fill", "h": "fill", "fill": "ground",
    "children": [
      { "el": "Sequence", "scenes": [
        { "len": 2, "node": { "el": "KineticLine", "text": "$claim", "size": 120 } },
        { "len": 2, "transition": "push", "node": { "el": "KineticLine", "text": "$proof", "size": 120 } },
        { "len": 2, "transition": "blur", "node": { "el": "Lockup", "name": "$name", "size": 110 } }
      ] }
    ]
  }
}

The request: "change the second transition, and add a number before the closing card". The patch:

json
[
  { "op": "replace", "path": "/root/children/0/scenes/1/transition", "value": "rise" },
  { "op": "add", "path": "/root/children/0/scenes/2", "value": {
    "len": 2.6, "transition": "zoom",
    "node": { "el": "StatReveal", "value": 30, "suffix": " s", "label": "$statLabel", "size": 170 } } },
  { "op": "add", "path": "/tokens/statLabel", "value": "from a twelve minute take" },
  { "op": "replace", "path": "/duration", "value": 8.6 }
]

Four operations: one value changed, one scene inserted before the closing card, the word it needs added to the product's tokens, and the duration brought up to 2 + 2 + 2.6 + 2. The film after:

The result of the patch. The first and last scenes are byte for byte what they were.

The CLI#

sh
npx tsx cli.ts patch film.json ops.json > edited.json

patch applies the operations, compiles the result, and prints the new film. If an operation fails, or the patched film has a compile problem, it prints the messages to standard error, prints no film, and exits with code 1.

In code#

ts
import { applyPatch, compile, starter, type PatchOp, type Spec } from "./motion-kit/src/index";

const ops: PatchOp[] = [{ op: "replace", path: "/duration", value: 5 }];
const { doc, errors } = applyPatch(film, ops);
if (errors.length) throw new Error(errors.join("\n"));
const problems = compile(doc as Spec, starter()).problems;

applyPatch never changes its input. It returns a new document, or the original and a list of errors. It does not compile: call compile on the result yourself.

A fast general model given the kit's edit task file and a film applied 6 of 6 change requests as patch operations on the first try: 1 to 5 operations and 73 to 387 characters, against films of 906 and 1,724 characters. See Benchmarks.

The bridge#

The bridge edits a scene through named things instead of paths. It has three parts.

snapshot#

snapshot(spec, registry) returns a short list of what is in the scene. Each entry has a ref, what it is, a label made from its words, the values set on it, its parts, its slots, its own behaviors, and the actions it accepts.

json
{ "ref": "statReveal2", "kind": "component", "name": "StatReveal",
  "label": "StatReveal \"props only\"",
  "values": { "value": 82, "suffix": "%", "label": "props only", "size": 150 },
  "parts": { "root": "box", "value": "text", "bar": "shape", "label": "text" },
  "actions": ["set", "retime", "part", "addMotion", "wrap", "remove"] }

A ref is the node's id if it has one, or its name and a counter. The first entry is always scene. A node inside $each is one entry: the pattern, not each copy.

act#

act(spec, registry, steps, source) applies a list of steps. A step is { "ref", "action", "args" }.

json
[
  { "ref": "statReveal2", "action": "set", "args": ["label", "from a twelve minute take"] },
  { "ref": "statReveal2", "action": "part", "args": ["value", { "color": "good" }] },
  { "ref": "scene", "action": "set", "args": ["duration", 5] }
]
ActionArgsWhat it does
set[prop, value]Changes one value. null removes it. On scene: duration, speed, background.
retime[seconds or cue]When the thing starts.
cue[name, seconds]On scene: moves or adds a cue.
part[partName, props]Restyles one part of a component, or gives it motion.
motion[position, options]Changes one of the node's own behaviors.
addMotion, removeMotion[behavior], [position]Adds or takes off a behavior.
slot, appendSlot[name, nodes], [name, node]Replaces or adds to a slot's contents. [name, null] restores the fallback.
wrap[wrapper node]Puts the thing inside a wrapper component.
remove[]Takes it out.
insert[node, position]Adds a child to a box.

The result is { ok, spec, results, changes }. All steps apply together or none do. A step is refused if its ref does not exist, its value is invalid, or the scene would gain a problem. A refusal names the real options:

text
bounce: 4 is above the maximum 0.9
Nothing called "nothing". There are: scene, box1 (box), statReveal2 (StatReveal "props only"), …

Each change records the ref, the action, the previous value, the new value and the source that made it.

History#

ts
import { createHistory, starter } from "./motion-kit/src/index";

const history = createHistory(scene, starter());
history.act([{ ref: "statReveal2", action: "set", args: ["label", "from a twelve minute take"] }], "agent");
history.act([{ ref: "statReveal2", action: "part", args: ["value", { color: "good" }] }], "person");

history.undoSource("agent");   // the label is back; the person's colour stays
const current = history.spec();

createHistory keeps every accepted call with its source. undo() takes back the last call. undoSource(source) takes out everything one author did and replays everyone else's steps on the original, so their work survives. It returns anything of theirs that no longer applied.

From the CLI: npx tsx cli.ts snapshot scene.json prints the snapshot, and npx tsx cli.ts apply scene.json steps.json prints the edited scene.

Patch or bridge#

  • A patch reaches anything in the JSON, including tokens, kit fields and the order of scenes. It is checked by compiling the result.
  • A bridge step reaches only what the snapshot lists, is checked against the prop's declaration before it is applied, and is recorded with its author.
  • Use patches for films. Use the bridge when a person and an agent edit the same scene and either may undo the other.

Motion Lang#

An edit over a talking video is a short list of pieces, each pinned to a moment. Motion Lang writes that list one statement per line.

text
video interview
style bold
caps  = Captions(bold)
big   = BigWord("20")                 @ "20" -> "experience,"  behind
bolt  = Sticker(bolt)                 @ "years" for 1.5        top-right
stat  = StatChip(20, label: "years")  @ 3.2 for 2
punch = Punch(1.16)                   @ "know" for 0.9

A statement is id = Component(args) @ WHEN LAYER PLACE.

PartWritten as
argsThe component's props in order. name: value sets one by name. Leave out what the style should decide: colours, type, corners, curves.
WHEN@ T (from T to the end), @ T -> T, or @ T for SECONDS. No WHEN means the whole take.
TSeconds, or a spoken word in quotes. "know" is the moment that word is said. "to"#2 is the second time it is said.
LAYERbehind (between the picture and the speaker's cut-out) or front.
PLACEtop, top-left, top-right, left, center, right, bottom, bottom-left, bottom-right, middle, edge, full, or (x, y) as fractions. Also scale N and tilt DEGREES.

Punch is not a component. It is a quick push in on the footage itself.

ts
import { PACKS, compile, editToSpec, parseEdit, printEdit, starter } from "./motion-kit/src/index";

const registry = starter();
const { edit, errors } = parseEdit(text, registry);       // errors: [{ line, message }]
const problems: string[] = [];
const scene = editToSpec(edit, footage, PACKS[edit.style], problems);
const compiled = compile(scene, registry);
const again = printEdit(edit, registry);                  // back to text
  • parseEdit reports a line it cannot read with its number and skips it. The other lines still apply. An unknown component name lists the ones that exist.
  • footage is { size, duration, transcript, film, matte?, audio? }: the frame, the timed words, the take as a node, and optionally the speaker's cut-out as a node.
  • An edit is data: { video, style, layers }. Text and data are two views of the same list, so an editor's buttons and an agent's lines change the same thing.
  • A quoted word that is not spoken in the take is added to the problems list passed as the fourth argument.

Motion Lang is the format the director answers in. There a follow-up is the whole edit sent again, a few hundred characters, and what changed is computed by comparing the two edits.

Reelify Motion Kit 0.1 preview. Built 2026-11-21.llms.txt · SKILL.md · 109 pages