Skip to content

Editing ​

This page is for building a video editor on CutCraft. In such an editor the user drags, trims and types on a timeline and a preview, every gesture can be undone, and each change lands in the file's text. The model that wrote the file then reads a file that differs from what it wrote by exactly what the user did.

@cutcraft/kit has the pieces, in the order you need them:

PieceDoesSection
The resolverPlaces every element in time, for the timeline and the player.Place every element
ActionsRun each gesture, check it, and undo it.Run a gesture
The patch logHolds what the user changed, over the file.The patch log
The foldWrites the log back into the file's text.Write the edit into the file
LintChecks the file follows the conventions an editor relies on.Lint

An editor's state is the file plus a log of patches. Gestures run actions, the resolver applies the log over the file, and at sync points the log is folded into the file's text.

Place every element ​

The resolver turns the file into absolute placements: when each element starts and ends.

ts
const tree = collectModule(file);          // walk the element tree, expand pure helpers, index by id
const state = resolve(tree, manifest, log); // absolute placements, memoised per log version

ResolvedState holds:

FieldIs
composition settingsSize, frame rate and the rest of the <Composition>.
tracksThe tracks, in order.
itemsA Map<id, Placement>, each with start, end, duration, source, parsed props, editable, lockedProps and errors.
errorsThe typed error list.

Placements that did not change between resolves are the same object, so a UI can memoise on them. A change costs about 2 µs per element.

Run a gesture ​

Every gesture is an action. The Executor checks it, records it and keeps the history for undo:

ts
const exec = new Executor({ tree, manifest });
const result = exec.execute({ type: "clip/trim", params: { id: "hook", edge: "out", value: "word:22.end" } });
result.ok;        // validation passed, patches appended, history entry pushed
result.inverse;   // the action that undoes it
exec.undo(); exec.redo();
exec.beginGroup("drag"); … exec.endGroup();   // one history entry for a gesture

The action reference lists all 115.

Undo. History auto-groups rapid same-type, same-target updates (a slider drag) within 100 ms, and keeps explicit groups (beginGroup, endGroup) for gestures.

What each action is made of

Every handler has four faces:

FaceInputOutput
validateaction, resolved stateok, or typed errors (ELEMENT_NOT_FOUND, TRACK_LOCKED, LOCKED_PROP, OUT_OF_BOUNDS, NOT_ADJACENT, …)
applyaction, patch logappends set, text, insert, remove, move, bake patches
invertaction, state beforethe inverse action, never null
foldaction, source indexsource edits, when the generic fold is not enough

The patch log ​

Actions append patches to a log. The resolver overlays the log's net effect on the collected tree, and untouched nodes keep their identity.

How the net effect is reduced

The log keeps every patch and a reduced net effect per element:

  • last write wins per prop;
  • a removal of an inserted element forgets it;
  • an insert after a remove of the same id replaces it.

Write the edit into the file ​

The fold turns the log into edits to the file's text, at sync points:

ts
const { text: next, edits, baked } = foldToSource(text, exec.log(), exec.state());

After the fold the model reads a file that differs from what it wrote by exactly what the user did.

How each patch becomes an edit

The source index maps every id to its ranges in the text.

PatchBecomes
set on a literal propOne edit covering the old value token.
insertThe element printed in place, with the parent's indentation.
removeThe element's range deleted.
Any patch on a generated elementThe helper's output baked into literals first; then the file is re-indexed and folded again.

When the model rewrites the file ​

When the model writes the file, reset the executor with the new tree (replaceTree). The log and history belong to the previous version of the file.

Actions that change structure ​

Three actions rewrite structure rather than a value, and fold the same way. Nothing moves in time.

track/setLayout converts a track.

  • To free: every sequenced child gets its resolved start, a transition between siblings becomes an edge transition on the outgoing clip, and gaps go.
  • To sequence: children are reordered by start, holes become <Gap>s and starts are dropped. Overlapping items are refused, since a sequence cannot express them.

multicam/flatten replaces a <Multicam> on a free track by one literal <Clip> per cut, at the time and source range the cut resolved to. A cut that ran past its source is cut short where the source ends.

nested/extract writes a scene's tracks into the file: one free track per inner track, inserted after the nested element's track, every item at the time it played. On a sequence track a <Gap> keeps the slot. A nested element with in, out or a transform is refused, as are scenes with transitions.

Lint ​

Lint checks a file's text against the conventions that keep it editable, and flags cuts and code that will look wrong.

ts
lint(text, { manifest })   // Diagnostic[] with rule, severity, message, range, id, prop

The file. These keep a file editable:

RuleSeverity
literal-idserror
unique-idserror
no-start-on-sequenceerror
pure-helperserror
expression-lockedwarning
one-captionserror
ambiguous-durationerror
file-shapeerror
missing-asseterror

The cut. These warnings check the cut rather than the file:

RuleReports
sequence-gapA <Gap> on the first sequence track, which is black unless another track covers it.
cut-inside-wordA numeric in or out that lands strictly inside a transcript word. It needs the manifest, and names the word:N reference to use instead.
cut-near-shotAn in just before a shot change or an out just after one, which flashes a few frames of the other shot. It reads the source's cuts from the manifest's shots, and names the shot:N edge to use.
shot-change-inside-cropOne transform.crop over a range the camera cuts inside, so the framing the crop was set for ends mid-clip. Split there.
repeated-sourceTwo clips on one track playing overlapping stretches of the same asset, usually a split that kept the old clip.

What will be drawn. These warnings look at the picture:

RuleReports
stray-htmlHTML straight in a track, where nothing draws it.
free-code-clockFree code off the video's clock (Free code).
not-renderedOne of the few things the renderers draw differently from what the file says, listed in What renders.

A font picker ​

A font picker lists the fonts a user can choose, and choosing one is one action. List FONT_CATALOG (the bundled families and a short list from Google Fonts, each with its category, its weights, what it suits and a line on how it looks) and the families the file itself declares, which are on state.fonts.

ts
exec.execute({ type: "font/use", params: { id: "headline", family: "Bebas Neue" } });
exec.execute({ type: "font/use", params: { role: "heading", family: "Oswald", weight: 700 } });
ParamNames
idA title or the captions.
roleA theme font: heading, body or mono.
familyThe family. It must be bundled, declared by the file, or in the catalogue.
weightA weight the family has.

A Google family the file does not declare yet is added to state.fonts at once, so the preview loads it and shows it. On fold the file gains the declaration and the use site names it:

tsx
import { Composition, Title, Track, googleFont } from "@cutcraft/kit";

const bebasNeue = googleFont("Bebas Neue");

<Title id="headline" font={bebasNeue}>…</Title>

A weight added to a family the file already declares is added to that declaration's weights. Undo takes the font and the face to load away together. The same write-back applies to any action that sets a catalogue family as a font, such as text/update.

Next ​

MIT licensed.