@alpha2-sh/editor 0.0.0 → 0.1.0

package/dist/core/commands.d.ts

@@ -0,0 +1,413 @@
+import type { InputKey } from "./compositions.js";
+import type { Project, Clip, Track, ClipEffect, CaptionCue, Composition, CompositionNode, MediaSource, EffectResource } from "alpha2/project";
+import type { EditorDocument, TrackMetadata, ClipMetadata, AssetDescriptor, Marker, Result, GraphLayout, GraphPosition } from "./document.js";
+/**
+ * An edit of an {@link EditorDocument}, run by {@link executeCommand} or
+ * `EditorSession.dispatch`. Times are timeline ticks unless a variant says otherwise. Ids that
+ * name an entity the document lacks are refused, and so is any change to a locked track.
+ */
+export type Command = 
+/**
+ * Adds a transition of `duration` ticks between two clips of a track; the incoming clip and
+ * those chained after it move earlier to overlap the outgoing one.
+ */
+{
+    readonly type: "transition.add";
+    readonly trackId: string;
+    readonly fromId: string;
+    readonly toId: string;
+    readonly duration: number;
+    readonly effect: ClipEffect;
+}
+/**
+ * Gives a transition, named by its instance id, a new duration; the incoming clips move to match.
+ */
+ | {
+    readonly type: "transition.resize";
+    readonly trackId: string;
+    readonly instanceId: string;
+    readonly duration: number;
+}
+/**
+ * Removes a transition; the incoming clip and its chain move later to where the outgoing clip
+ * ends.
+ */
+ | {
+    readonly type: "transition.remove";
+    readonly trackId: string;
+    readonly instanceId: string;
+}
+/** Runs `commands` in order as one edit: all apply, or none does. */
+ | {
+    readonly type: "transaction";
+    readonly commands: readonly Command[];
+}
+/** Replaces the project's name, settings or master audio with the patch's fields. */
+ | {
+    readonly type: "project.update";
+    readonly patch: Partial<Pick<Project, "name" | "settings" | "audio">>;
+}
+/**
+ * Adds a track on top of the others. Like `clip.insert`, each of its clips whose composition
+ * something else draws shows its own copy of it.
+ */
+ | {
+    readonly type: "track.add";
+    readonly track: Track;
+} | {
+    readonly type: "track.remove";
+    readonly id: string;
+}
+/** Puts the tracks in the order `ids` lists them; `ids` must name every track once. */
+ | {
+    readonly type: "track.reorder";
+    readonly ids: readonly string[];
+}
+/** Replaces the track's fields the patch has. */
+ | {
+    readonly type: "track.update";
+    readonly id: string;
+    readonly patch: Partial<Pick<Track, "name" | "audio" | "captions" | "transitions">>;
+}
+/** Merges `patch` into the track's editor metadata. Unlocking is allowed on a locked track. */
+ | {
+    readonly type: "track.metadata";
+    readonly id: string;
+    readonly patch: TrackMetadata;
+}
+/** Merges `patch` into the clip's editor metadata. */
+ | {
+    readonly type: "clip.metadata";
+    readonly id: string;
+    readonly patch: ClipMetadata;
+}
+/**
+ * Adds a clip to a track as it is: nothing makes room for it. A clip whose composition something
+ * else draws shows its own copy of it (and of the group definitions in it), so a duplicate edits
+ * independently of its original. `compositions` are those the clip drew when it was copied: it
+ * shows a copy of them, whether or not the document still has them.
+ */
+ | {
+    readonly type: "clip.insert";
+    readonly trackId: string;
+    readonly clip: Clip;
+    readonly name?: string;
+    readonly compositions?: readonly Composition[];
+}
+/**
+ * Puts a clip down at `at` on a track: `insert` makes room by moving later content (on
+ * sync-locked tracks too), `overwrite` replaces what is there, `append` goes after the track's
+ * last clip. A clip the new one cuts in two keeps its id on the left; the right part is
+ * `splitId`. Like `clip.insert`, a clip whose composition something else draws shows its own copy
+ * of it.
+ */
+ | {
+    readonly type: "clip.place";
+    readonly mode: "insert" | "overwrite" | "append";
+    readonly trackId: string;
+    readonly clip: Clip;
+    readonly at: number;
+    readonly splitId?: string;
+    readonly name?: string;
+}
+/** Shows another part of a clip's source in the same place, `delta` source ticks later. */
+ | {
+    readonly type: "clip.slip";
+    readonly id: string;
+    readonly delta: number;
+}
+/** Moves a clip `delta` ticks between its neighbours, which give and take the time. */
+ | {
+    readonly type: "clip.slide";
+    readonly id: string;
+    readonly delta: number;
+}
+/**
+ * Gives a clip a new length from where it starts: its speed, for a clip that plays forward or
+ * reversed. `ripple` moves what follows (on sync-locked tracks too); `keyframes` keeps or
+ * stretches its keyframes, fades, and composition time.
+ */
+ | {
+    readonly type: "clip.retime";
+    readonly id: string;
+    readonly duration: number;
+    readonly reverse?: boolean;
+    readonly ripple?: boolean;
+    readonly keyframes?: "keep" | "stretch";
+}
+/** Adds a marker; its id must be new. */
+ | {
+    readonly type: "marker.add";
+    readonly marker: Marker;
+}
+/** Applies `patch` to a marker; a field patched to `undefined` is removed. */
+ | {
+    readonly type: "marker.update";
+    readonly id: string;
+    readonly patch: Partial<Omit<Marker, "id">>;
+} | {
+    readonly type: "marker.remove";
+    readonly id: string;
+}
+/** Moves the cut between two clips that meet, keeping their total length. */
+ | {
+    readonly type: "clip.roll";
+    readonly leftId: string;
+    readonly rightId: string;
+    readonly at: number;
+}
+/** Moves a clip to start at `at`, onto track `trackId` when given. */
+ | {
+    readonly type: "clip.move";
+    readonly id: string;
+    readonly at: number;
+    readonly trackId?: string;
+}
+/**
+ * Moves several clips as one: only where they all land must be valid, whatever order `moves`
+ * lists them in.
+ */
+ | {
+    readonly type: "clips.move";
+    readonly moves: readonly {
+        readonly id: string;
+        readonly at: number;
+        readonly trackId?: string;
+    }[];
+}
+/**
+ * Moves a clip's `edge` to `at`, showing more or less of its source. `ripple` moves what follows
+ * by the same amount (on sync-locked tracks too).
+ */
+ | {
+    readonly type: "clip.trim";
+    readonly id: string;
+    readonly edge: "start" | "end";
+    readonly at: number;
+    readonly ripple?: boolean;
+}
+/** Cuts a clip in two at `at`: the left part keeps its id, the right part is `newId`. */
+ | {
+    readonly type: "clip.split";
+    readonly id: string;
+    readonly at: number;
+    readonly newId: string;
+}
+/**
+ * Removes a clip and its transitions. `ripple` closes the gap by moving what follows (on
+ * sync-locked tracks too).
+ */
+ | {
+    readonly type: "clip.delete";
+    readonly id: string;
+    readonly ripple?: boolean;
+}
+/** Replaces the clip's fields the patch has. A `cache` of `auto` removes the field. */
+ | {
+    readonly type: "clip.update";
+    readonly id: string;
+    readonly patch: Partial<Pick<Clip, "visual" | "audio" | "blend_mode" | "masks" | "matte" | "time_map" | "source_range" | "cache">>;
+}
+/**
+ * Adds an effect on top of clip `id`'s effect stack as `instanceId`. The `effect.*` commands are
+ * refused for a clip whose composition is a graph rather than a stack (see `effectStack`).
+ */
+ | {
+    readonly type: "effect.add";
+    readonly id: string;
+    readonly instanceId: string;
+    readonly effect: ClipEffect;
+}
+/** Replaces an effect of clip `id`'s stack. */
+ | {
+    readonly type: "effect.update";
+    readonly id: string;
+    readonly instanceId: string;
+    readonly effect: ClipEffect;
+    /** Whether the effect is switched off; unchanged when omitted. */
+    readonly bypass?: boolean;
+}
+/** Removes an effect from clip `id`'s stack; an empty stack removes the clip's composition. */
+ | {
+    readonly type: "effect.remove";
+    readonly id: string;
+    readonly instanceId: string;
+}
+/**
+ * Puts clip `id`'s effects in the order `ids` lists them, bottom first; `ids` names each once.
+ */
+ | {
+    readonly type: "effect.reorder";
+    readonly id: string;
+    readonly ids: readonly string[];
+}
+/** Gives a clip without one a composition that shows its picture. */
+ | {
+    readonly type: "graph.create";
+    readonly clipId: string;
+    /** The new composition's id; a free one based on `<clip>-fx` when omitted. */
+    readonly compositionId?: string;
+}
+/** Adds a node to a composition; its id must be new there. */
+ | {
+    readonly type: "graph.node.add";
+    readonly compositionId: string;
+    readonly node: CompositionNode;
+    /** Where the node editor draws it. */
+    readonly position?: GraphPosition;
+}
+/** Replaces a node's operation and bypass; its id stays. */
+ | {
+    readonly type: "graph.node.update";
+    readonly compositionId: string;
+    readonly node: CompositionNode;
+}
+/** Removes nodes, disconnecting every input that read them. */
+ | {
+    readonly type: "graph.node.remove";
+    readonly compositionId: string;
+    readonly ids: readonly string[];
+}
+/**
+ * Connects node `from`'s picture to input `input` of node `to`; `"layer"` adds a merge layer on
+ * top.
+ */
+ | {
+    readonly type: "graph.connect";
+    readonly compositionId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly input: InputKey | "layer";
+}
+/** Disconnects input `input` of node `to`; a merge layer's slot is removed with its wire. */
+ | {
+    readonly type: "graph.disconnect";
+    readonly compositionId: string;
+    readonly to: string;
+    readonly input: InputKey;
+}
+/** Makes node `nodeId` the composition's output; `null` leaves it without one. */
+ | {
+    readonly type: "graph.output";
+    readonly compositionId: string;
+    readonly nodeId: string | null;
+}
+/**
+ * Folds nodes into a group node that draws a new composition of them; the picture does not
+ * change. Ids are free ones based on `group` and `<composition>-group` when omitted.
+ */
+ | {
+    readonly type: "graph.group";
+    readonly compositionId: string;
+    readonly ids: readonly string[];
+    readonly groupId?: string;
+    readonly definitionId?: string;
+    /** What the group is called in the node editor. */
+    readonly name?: string;
+}
+/** Adds a composition, such as a group definition a macro brings. */
+ | {
+    readonly type: "composition.add";
+    readonly composition: Composition;
+}
+/** Replaces a group node with the nodes it draws; the picture does not change. */
+ | {
+    readonly type: "graph.ungroup";
+    readonly compositionId: string;
+    readonly nodeId: string;
+}
+/** Gives a composition another group input, unconnected on every group node that uses it. */
+ | {
+    readonly type: "graph.port.add";
+    readonly compositionId: string;
+    readonly name: string;
+}
+/** Exposes a node's effect parameter to the group nodes that use its composition. */
+ | {
+    readonly type: "graph.control.add";
+    readonly compositionId: string;
+    readonly control: {
+        readonly name: string;
+        readonly node: string;
+        readonly param: string;
+    };
+}
+/** Stops exposing a control, dropping the values group nodes set for it. */
+ | {
+    readonly type: "graph.control.remove";
+    readonly compositionId: string;
+    readonly name: string;
+}
+/**
+ * Makes a composition a Library item: a composition source that shows it, which clips place like
+ * media. It starts with a background to build on.
+ */
+ | {
+    readonly type: "composition.create";
+    readonly compositionId: string;
+    readonly sourceId: string;
+    readonly name: string;
+}
+/** Moves nodes in the node editor; the picture does not change. */
+ | {
+    readonly type: "graph.layout";
+    readonly compositionId: string;
+    readonly positions: Readonly<Record<string, GraphPosition>>;
+}
+/** Adds a cue to a caption track under a new `instanceId`, in its place by time. */
+ | {
+    readonly type: "cue.add";
+    readonly trackId: string;
+    readonly instanceId: string;
+    readonly cue: CaptionCue;
+}
+/** Replaces the cue `instanceId` names; a cue given another time moves to its place by it. */
+ | {
+    readonly type: "cue.update";
+    readonly trackId: string;
+    readonly instanceId: string;
+    readonly cue: CaptionCue;
+} | {
+    readonly type: "cue.remove";
+    readonly trackId: string;
+    readonly instanceId: string;
+}
+/**
+ * Adds or replaces a bin asset, with the project source or effect resource of the same id when
+ * given. `contentRevision` may not go below the replaced asset's.
+ */
+ | {
+    readonly type: "asset.put";
+    readonly asset: AssetDescriptor;
+    readonly source?: MediaSource;
+    readonly resource?: EffectResource;
+}
+/**
+ * Removes a bin asset and its project source or effect resource; a clip still reading it is
+ * refused.
+ */
+ | {
+    readonly type: "asset.remove";
+    readonly id: string;
+}
+/** Replaces the document metadata fields the patch has. */
+ | {
+    readonly type: "metadata.update";
+    readonly patch: Partial<Pick<EditorDocument["metadata"], "markers" | "exportRange" | "graphLayout" | "graphNames">>;
+};
+/** The names the node editor shows for group compositions, by composition id. */
+export declare function graphNames(document: EditorDocument): Readonly<Record<string, string>>;
+/** The node editor positions a document stores. */
+export declare function graphLayout(document: EditorDocument): GraphLayout;
+/**
+ * Applies `command` to `document` and validates the result. `gesture` checks only what a pointer
+ * move can change (see `validateDocumentShape`); the gesture validates in full once, when it
+ * commits.
+ *
+ * Never throws: a refusal is `{ ok: false }` with an `EditorError` (`invalid_command`, `locked`, a
+ * validation code, or an edit code from `alpha2/edit`). `document` and `command` are not modified;
+ * compositions the edit leaves undrawn are removed from the result.
+ */
+export declare function executeCommand(document: EditorDocument, command: Command, { gesture }?: {
+    gesture?: boolean;
+}): Result<EditorDocument>;