raea/editor

The timeline the feed edits a film, a scene or a sound on, as data. A Timeline holds tracks of clips in whole frames, with keys, markers and transitions; apply and applyAll make an edit and hand back its inverse, so every change can be undone; the main track's magnet, snapping and linkage behave as the feed's timeline does. A film's scenes are read in with fromRender and its cut read back out with segmentsOf, as a composition's edit={{ segments }} takes it; a composition's sequences are read in with fromSequences, and seqEdits says what an operation does to them. Easings, speed curves, snapping, the frame store's keys and what a plugin adds are here too. No React and no DOM: an agent's script, the app's host and a test use the same model the app's timeline does. See the example for a timeline built, edited and undone.

import { ADJUST_KINDS, ADJUST_PROP_LIST, ADJUST_PROPS, adjustError } from "raea/editor"

raea/editor exports 63 functions, 28 values, 45 types. Bevy's counterpart: raea's own; Bevy has no timeline editor. Source: sdk/raea/src/editor.ts.

#Functions

#adjustError

What is wrong with a clip's adjustment props as they stand, or undefined: a value out of its range.

function adjustError(props?: Props): string | undefined

#adjustLook

How the editor's preview draws a clip's adjustment on its picture, as draws it: its SVG filter's id and steps (to put beside the picture), and its vignette's background (a layer over the picture). A wrong one draws nothing rather than throwing in the editor.

function adjustLook(props: Props | undefined, seed?: number): { filter?: { id: string; steps: FilterStep[]; } | undefined; vignette?: string; }

#adjustOf

A clip's adjustment read from its props: the kinds that aren't 0.

function adjustOf(props?: Props): Partial<Record<"saturation" | "fade" | "brightness" | "contrast" | "exposure" | "sharpen" | "highlights" | "shadows" | "temperature" | "tint" | "vignette" | "grain", number>>

#adjustProps

An adjustment as a clip's props, to three places: every kind, 0 for what it hasn't got, so a set puts it whole.

function adjustProps(a: Partial<Record<"saturation" | "fade" | "brightness" | "contrast" | "exposure" | "sharpen" | "highlights" | "shadows" | "temperature" | "tint" | "vignette" | "grain", number>>): Props

#ahead

The ranges to draw next while there is time: what isn't kept from the playhead on, nearest first, each at most chunk frames, then what is before it.

function ahead(length: number, kept: Range[], playhead: number, chunk: number): Range[]

#animStyle

The clip's style into frames from its start: coming in by its In, going out by its Out (each over no more of it than it has) and moving by its Combo, one of combos (a plugin's among them). Empty when none plays there.

function animStyle(c: Clip, into: number, combos?: ComboKind[]): EdgeStyle

#apply

The operation applied, or why it can't be.

function apply(t: Timeline, op: Op): Applied

#applyAll

Operations in order, stopping at the first refused: the timeline they give, and each one's inverse (last first).

function applyAll(t: Timeline, ops: Op[]): { timeline: Timeline; inverse: Op[]; refused?: { op: Op; why: string; } | undefined; }

Used in: manual: edits.

#bezier

y at x on the cubic bezier (0,0) (x1,y1) (x2,y2) (1,1): x is solved by Newton's steps, then bisection where the slope is too flat for them. The handles' x are kept in 0..1 so the curve is a function of time.

function bezier(x1: number, y1: number, x2: number, y2: number): (x: number) => number

#captionLines

The words gathered into caption lines: a line ends after a sentence does, at a pause, or once it holds as many words or characters as it may. Each line runs from its first word to its last and ends by the next line's start.

function captionLines(words: Said[], fps: number, o?: LineRules): Said[]

#changed

The frames whose picture or sound differ between two states of a timeline: wherever what is drawn over a frame isn't what was. Moving a clip from 2:00-2:05 to 2:10-2:15 gives those two ranges and nothing else; a split of footage gives none.

function changed(before: Timeline, after: Timeline): Range[]

#clipEdits

The file clips that differ between the timeline as it was read and as it stands, each with its span before and after: what a sound's hand edit carries (its clips). A clip that was removed or made here isn't one of these.

function clipEdits(read: Timeline, now: Timeline): { id: string; src: string; from: ClipSpan; to: ClipSpan; }[]

#clips

function clips(t: Timeline): Clip[]

#cut

The keys either side of a cut at frame (TL3d: a split clip's keys stay at their frames): the left clip's, and the right clip's in its own frames. A cut between two keys puts a key of the value there on both sides, so each half moves as the whole did up to the cut.

function cut(keys: Key[], frame: number): [Key[], Key[]]

#cutoutError

What is wrong with a clip's cutout props as they stand, or undefined: a mask kind or blend it hasn't got, a value out of range, a grey key.

function cutoutError(props?: Props): string | undefined

#cutoutLook

How the editor's preview draws a clip's cutout on its picture, as draws it in a composition: CSS for the picture, and the SVG filter its key needs (an feColorMatrix's values under id, to put beside the picture).

function cutoutLook(props: Props | undefined, width: number, height: number): { style: Record<string, string>; key?: { id: string; matrix: string; } | undefined; }

#cutoutOf

A clip's cutout read from its props: a mask when its kind is one, a blend other than normal, a key when it has a colour.

function cutoutOf(props?: Props): Cutout

#cutoutProps

A cutout as a clip's props: every one of them, what it hasn't got at its plain value, so a set takes off the rest. Values to five places.

function cutoutProps(c: Cutout): Props

#eased

How far along (0..1, or past it for a handle that overshoots) a value is at p of the way between two keys.

function eased(ease: Ease | undefined, p: number): number

#effectFilter

The CSS filter of kind at amount (0 to 1, clamped); undefined for a kind raea doesn't draw.

function effectFilter(kind: string, amount?: number): string | undefined

#effectParts

An effect clip's parts, kept in its props as JSON: read back when they are well formed.

function effectParts(v: unknown): EffectPart[] | undefined

#empty

function empty(fps?: number): Timeline

Used in: manual: edits.

#end

function end(c: Clip): number

Used in: manual: edits.

#evict

The keys to drop so the store is at most limit bytes: stale ones first, then the least recently played. What is under the playhead (hold) stays while anything else can go.

function evict(kept: Kept[], limit: number, hold?: Set<string>): string[]

#find

function find(t: Timeline, id: string): { track: Track; clip: Clip; } | undefined

#fits

Whether c has room on the track (it overlaps none of the others).

function fits(track: Track, c: Pick<Clip, "start" | "length" | "id">): boolean

#frameOf

The timeline frame at which clip id shows source frame source, when it does (a constant-speed clip).

function frameOf(t: Timeline, id: string, source: number): number | undefined

#fromRender

A film with no composition behind it: its scenes as clips of one main track (cut where the picture cuts). Each clip is the film's picture and its sound together, as footage is until its sound is extracted, so a cut, a move or a speed takes both. Its magnet is on: a scene removed closes up, as a cut of footage does.

function fromRender(o: { frames: number; fps: number; cuts?: number[]; captions?: { text: string; start: number; end: number; }[] | undefined; }): Timeline

#fromSequences

The composition's sequences as a timeline: a track a lane, the first lane on top as the strip draws it. The first lane is the main track, its magnet on, only when its clips already run from frame 0 with no gap: a composition's sequences are where its code puts them, and nothing here moves one that wasn't dragged.

function fromSequences(rows: SeqRow[], fps: number): Timeline

#fromTracks

A sound's tracks as a timeline: a sound track each, by its bus; a clip of a file keeps its place in the file (its offset) and its level. Notes and lines are clips too, locked here: they are edited where they are written (the roll, the words). No magnet: a mix's clips are where they were put.

function fromTracks(tracks: SoundTrack[], fps: number): Timeline

#gridFrames

The frames a snap grid marks in a timeline length frames long (none for a grid finer than a frame, or of more than 5,000 marks).

function gridFrames(grid: SnapGrid, fps: number, length: number): number[]

#heard

The words as the edited timeline says them. words are in the film's own frames (where its transcript has them); each is said where a main-track clip plays that part of the film, at that clip's speed. A word in a scene taken out is gone, a scene duplicated says its words twice, and a clip curved, reversed or frozen says none.

function heard(t: Timeline, words: Said[]): Said[]

#joined

Ranges in order, touching and overlapping ones joined, empty ones dropped.

function joined(ranges: Range[]): Range[]

#keyOf

What a range of kept frames is kept under: everything that draws it. Two states of a timeline that draw the range the same give the same key, so frames drawn before an edit elsewhere (or before an undo) are found again.

function keyOf(t: Timeline, [from, to]: Range, media?: (clip: Clip) => string): string

#length

The timeline's length: its last clip's end.

function length(t: Timeline): number

Used in: manual: edits.

#maskPlain

A mask's values when a kind is chosen: in the middle, half the frame's shorter side across, so a circle is round on any frame; a mirror a band a fifth of the frame's height.

function maskPlain(kind: "circle" | "line" | "rect" | "mirror" | "heart" | "star", width: number, height: number): Required<Mask>

#next

Where the player goes when what it is playing ends at timeline frame frame: the next clip's first frame (at or after it), or undefined at the film's end.

function next(t: Timeline, frame: number): number | undefined

#palette

Everything offered: raea's own, then each plugin's in order (a name a plugin before it took stays that one's).

function palette(plugins?: Adds[]): { eases: Record<string, Ease>; curves: Record<string, SpeedPoint[]>; transitions: TransitionKind[]; combos: ComboKind[]; tracks: TrackKindInfo[]; effects: EffectInfo[]; texts: TextStyle[]; tools: Preset[]; snaps: SnapGrid[]; }

#partsFilter

The CSS filter of an effect given as parts, at amount (0 to 1, clamped).

function partsFilter(parts: EffectPart[], amount?: number): string

#played

How many frames source frames of source take to play under the curve.

function played(curve: SpeedPoint[], source: number): number

#playLength

The timeline's length as it plays: its main track's end.

function playLength(t: Timeline): number

#points

The curve as points from 0 to 1 in order, each speed in range.

function points(curve: SpeedPoint[]): SpeedPoint[]

#presetError

Why p isn't a preset, or undefined when it is.

function presetError(p: unknown): string | undefined

#profile

The speed at each of n places along the clip's own time (the line drawn over the clip, TL6b).

function profile(curve: SpeedPoint[], source: number, n: number): number[]

#propsAt

A clip's props as they stand frame frames from its start: each keyed one at its value there, the rest as set (what a mask's, a key's or a crop's look is drawn from while its numbers are keyed, TL5a).

function propsAt(clip: { props?: Record<string, boolean | Value> | undefined; keys?: Record<string, Key[]> | undefined; }, frame: number): Record<string, boolean | Value>

#readAdds

A plugin's additions as written in its manifest, checked: what is well formed, and why the rest isn't.

function readAdds(raw: unknown): { adds: Adds; errors: string[]; }

#readTimeline

A timeline as an agent wrote it on a feed item or a controller's field (its own data: a schedule, a set list, a shot plan), checked and made whole: what is well formed, and why the rest isn't. Frames are rounded to whole ones; a track with no kind is an overlay; ids must be there and not repeat.

function readTimeline(raw: unknown): { timeline?: Timeline; errors: string[]; }

#ready

The timeline ranges that are ready to play, given the source ranges that are (frames of the file the player has buffered): each main-track clip's part whose source is in one of them.

function ready(t: Timeline, source: Range[]): Range[]

#segmentsOf

A render's cut, as the frames of the source played in order (the hand edit's segments): what a film's main track is after its scenes were moved, trimmed, split and removed.

function segmentsOf(t: Timeline): [number, number][]

#seqEdits

What the host is asked to do to the composition's sequences for op on timeline t (read from them), in order; or why this operation isn't one the sequences can take yet. Each edit names sequences as they are before it.

function seqEdits(t: Timeline, op: Op): SeqEdit[] | { why: string; }

#showing

What shows at timeline frame frame: the main-track clip over it, the source frame, and the rate. Undefined in a gap or past the end.

function showing(t: Timeline, frame: number): Showing | undefined

#slot

Where a track of this kind goes among the others: after the last of its own kind, else in ORDER's place.

function slot(tracks: Track[], kind: TrackKind): number

#snap

frame moved to the nearest target within within frames (8 px at the strip's zoom), and what it snapped to.

function snap(frame: number, to: Target[], within: number): { frame: number; to?: Target; }

#snapMove

A moved clip (its start and length) snapped by whichever of its edges is nearer a target: how far it moves.

function snapMove(start: number, len: number, to: Target[], within: number): { by: number; to?: Target; }

#sorted

The keys in time order (two at one frame: the later one written wins).

function sorted(keys: Key[]): Key[]

#sourceAt

The source frame showing time frames into the clip, under the curve over source frames of source.

function sourceAt(curve: SpeedPoint[], source: number, time: number): number

#speedOf

A clip's speed where it is constant.

function speedOf(c: Clip): number

#targets

Every frame an edge can snap to, leaving out the clips being moved (not).

function targets(t: Timeline, o?: { not?: string[]; playhead?: number; beats?: number[]; }): Target[]

#textStyleError

Why t isn't a text style, or undefined when it is.

function textStyleError(t: unknown): string | undefined

#textStyleOf

A text clip's style, kept in its props as JSON: read back when it is well formed.

function textStyleOf(v: unknown): TextStyle | undefined

#timecode

mm:ss:ff, drawn from frames.

function timecode(frames: number, fps: number): string

#valueAt

The property's value at frame (frames from its clip's start), or undefined with no keys.

function valueAt(keys: Key[] | undefined, frame: number): Value | undefined

Used in: manual: edits.

#without

ranges with cut taken out of them.

function without(ranges: Range[], cut: Range[]): Range[]

#Values

#ADJUST_KINDS

#ADJUST_PROP_LIST

The clip props an adjustment is held in.

#ADJUST_PROPS

Each adjustment as a clip's prop: brightness is adjustBrightness.

#ADJUSTS

CapCut's Adjust, in its order: each from -1 to 1 (0 as shot), but sharpen, fade, vignette and grain, from 0.

#BLEND_KINDS

#BLENDS

How a part is drawn over what is under it: CapCut's Blend modes that CSS has (Add is plus-lighter), in its order, then difference and exclusion.

#CODE_KINDS

The transitions a composition's draws (sdk/video edges.ts).

#COMBO_KINDS

#COMBOS

raea's own Combos: the kinds draws. A plugin adds its own as data the same way.

#CURVES

CapCut's curve presets, as points over the source; a plugin adds its own.

#CUTOUT_PROPS

Every prop a clip's cutout is held in.

#EASES

The easing presets raea registers; a plugin adds its own beside them.

#EFFECTS

#FASTEST

#KEY_NAMES

What a sequence's can key, as a clip's prop and its name: the placement, and the numbers inside its mask, its chroma key and its crop ("mask.x" for maskX).

#KEY_PROPS

A chroma key's values as a clip's props.

#KEYABLE

The clip props a sequence keys.

#KEYED

A sequence's placement, as still values and as keys (sdk/video nudge.tsx).

#MASK_KINDS

A mask's shapes, in CapCut's order: a line (what is above it is kept), a mirror (a band), a circle, a rectangle, a heart and a star.

#MASK_PROPS

A mask's values as a clip's props.

#ORDER

#PRESET_PROPS

The props a preset may set: a clip's placement (what the editor's own tools set).

#SLOWEST

#TEXT_PROPS

The CSS a text style may set: type and colour, nothing that lays the frame out.

#TEXTS

raea's own text styles. Sizes are the composition's pixels (a 1080-line frame).

#TRACKS

raea's own kinds of track, in the order they stack.

#TRANSITIONS

raea's own transitions: the kinds its draws (sdk/video transition.tsx). Two parts that only touch have no frames of each other to mix, so there is no dissolve: a fade goes through black.

#under

Kinds a plugin said stack under the picture, with the sound (registry.ts sets them).

#Types

#Adds

What one plugin adds.

#Adjust

A part's adjustments, each 0 (or left out) as shot: brightness, contrast, saturation, exposure, highlights, shadows, temperature (warm above 0) and tint (magenta above 0) from -1 to 1; sharpen, fade, vignette and grain from 0 to 1.

type Adjust = Partial<Record<AdjustKind, number>>

#AdjustKind

type AdjustKind = (typeof ADJUSTS)[number]["kind"]

#Anim

How a clip comes in or goes out on its own: a transition's kind over its own first or last frames.

#Applied

type Applied = { ok: true; timeline: Timeline; inverse: Op } | { ok: false; why: string }

#Blend

type Blend = (typeof BLENDS)[number]["kind"]

#ChromaKey

A chroma key: the colour taken out (a green or blue screen), how much of what is near it goes, and how softly.

#Clip

A span of something on a track: footage, a sound, words, a composition's sequence, an effect.

#ClipSpan

A clip's span and level, in seconds and dB: what the host writes back for a clip that was moved, trimmed or turned up or down (raea-feed host/clips.ts).

#ComboKind

A kind of Combo: its name, what the person sees, and its wave.

#ComboWave

How a part moves over one cycle of a Combo: each property's values, evenly spaced over the cycle and eased between, the cycle starting again where it ends. x and y move it by a share of its own size in percent, rotate turns it in degrees, scale sizes it, opacity fades it. A wave that ends where it starts plays once over the part as CapCut's Combo does, and loops seamlessly as its text Loop does.

#Cutout

A clip's mask, blend and key, each there only when it has one.

#Ease

How a value travels from one key to the next: a straight line, no travel (it holds, then jumps), or a cubic bezier's two handles [x1, y1, x2, y2] as CSS writes them.

type Ease = "linear" | "hold" | [number, number, number, number]

#EdgeStyle

What an edge does to the part at a frame: a move, a fade and a cut-away, as CSS writes them.

#EffectInfo

An effect the palette offers: raea's own by its kind, a plugin's with the parts that draw it.

#EffectKind

#EffectPart

An effect as data: each part one CSS filter function, its value going from from (amount 0, where it changes nothing) to to (amount 1), with its unit: ["blur", 0, 6, "px"].

type EffectPart = [fn: string, from: number, to: number, unit?: string]

#FilterStep

One step of an SVG filter: its tag and its attributes, so React and the DOM can each make it.

#Frames

A count of frames, always whole.

type Frames = number

#Kept

A drawn range in the store, as the clearing reads it.

#Key

A property's value at a frame of its clip (frames from the clip's start), and how it leaves for the next key.

#LineRules

How words are gathered into lines.

#Marker

A mark at a frame: a beat, a comment's time or one put there by hand.

#Mask

A mask, in shares of the part's frame.

#MaskKind

type MaskKind = (typeof MASK_KINDS)[number]

#Op

type Op = | { op: "move"; ids: string[]; by: Frames; track?: string } /** a clip's start or end dragged to the timeline frame `to` */ | { op: "trim"; id: string; edge: "start" | "end"; to: Frames } /** the clips `ids` split at `at`; with none named, every clip under it (Cmd+B, Cmd+Shift+B: TL3d) */ | { op:…

#Preset

A tool a plugin adds: one press sets these on every picked clip, as one edit each.

#Range

type Range = [from: Frames, to: Frames]

#Said

A word, or a line of them: its text, its first frame and the frame after it ends.

#SeqEdit

The host's edit to a sequence: its new span, a split, a delete.

type SeqEdit = | { op: "move"; i: number; from: number; to: number } | { op: "split"; i: number; at: number } | { op: "delete"; i: number } /** the sequence's keyed properties as they now stand: written as its <Nudge keys>, one a property (TL5d) */ | { op: "keys"; i: number; keys: Record<string, [number, number…

#SeqLook

A sequence's still placement: its 's props (sdk/video nudge.tsx). crop is left, top, right, bottom.

#SeqRow

A as the host lists it: its place among the file's elements, its span in the composition's frames, the lane it sits on (nested ones below their parent, overlapping ones apart), and why it can't be rewritten.

#Showing

What the player shows at a frame of the edited timeline.

#SnapGrid

Marks edges snap to that a plugin adds: a grid, one mark every every seconds from the start.

#SoundTrack

A track of a sound in the feed as its host lists it (raea-feed host/sounds.ts), in seconds of the render.

#SpeedPoint

A point of a speed curve: how fast the source plays at a place in it (0 its first frame shown, 1 its last).

#Target

A frame an edge snaps to.

#TextStyle

A way words are put on the picture: where they stand, and how they are drawn (CSS, as React writes it).

#Timeline

A whole timeline: its tracks top to bottom, its marks, its transitions and its three switches.

#Track

A row of clips that don't overlap, with its head's switches.

#TrackKind

A track's kind, in the order they stack from the top: effect, text, overlay, main, sound. A plugin adds its own; an unknown kind sorts with the overlays.

type TrackKind = "effect" | "text" | "overlay" | "main" | "sound" | (string & {})

#TrackKindInfo

A kind of track: what its head says, and where it stacks (with the tracks over the picture, or with the sound under it). A clip on it is of that kind.

#Transition

A transition on the cut between two clips that touch on one track: the cut is the end of clip after, so it follows that cut wherever an edit moves it.

#TransitionKind

#Value

A property's value: a number, a list of numbers (a colour, a point) or a string.

type Value = number | number[] | string