Skip to content

Open source CapCut alternative.

TypeScript

feat(site): a spine resize carries the timeline with it [rebuild]

David Leed1640406627
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.ts
index 13d7ec86..3e1026b0 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -213,7 +213,7 @@ export const INSPECTOR_TOOLS = [
{
name: "set_speed",
description:
- "Set a video clip's playback speed. Faster shortens the clip on the timeline; slower stretches it. Later titles and captions shift to stay in sync.",
+ "Set a video clip's playback speed. Faster shortens the clip on the timeline; slower stretches it. Later clips, titles, captions, and soundtrack shift to stay in sync.",
inputSchema: obj({ clipId: str("Video clip id"), speed: num("Playback rate (1 = normal, no upper limit)") }, ["clipId", "speed"]),
},
{
diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.ts
index f7586554..cbc67480 100644
--- a/site/src/cut/components/Timeline.tools.ts
+++ b/site/src/cut/components/Timeline.tools.ts
@@ -57,7 +57,7 @@ export const TIMELINE_TOOLS = [
{
name: "trim_clip",
description:
- "Set a video clip's trim points inside its source media (seconds). Changing `in` hides the leading part; `out` the trailing part.",
+ "Set a video clip's trim points inside its source media (seconds). Changing `in` hides the leading part; `out` the trailing part. While track 0 is the only video track, a track-0 resize ripples: everything past the clip's tail — clips, titles, captions, soundtrack — rides the moved edge in both directions, and every existing gap keeps its width. With overlay video tracks present, growth pushes the track-0 run and a shrink leaves a gap.",
inputSchema: obj({ clipId: str("Video clip id"), in: num("New in point (optional)"), out: num("New out point (optional)") }, ["clipId"]),
},
{
@@ -125,7 +125,7 @@ export const TIMELINE_TOOLS = [
{
name: "delete_item",
description:
- "Delete a video clip (any track), soundtrack clip, or overlay element (title/shape/sticker) by id. While track 0 is the only video track, deleting a track-0 clip ripples: its footprint closes and everything after it — clips, titles, captions, soundtrack — slides left in sync; items wholly inside that span are removed with it, straddlers are trimmed. With overlay video tracks present the delete leaves its gap in place (remove_gap closes it). Deletes on other tracks remove just that item.",
+ "Delete a video clip (any track), soundtrack clip, or overlay element (title/shape/sticker) by id. Only the listed item leaves the project — anything else laid over it survives at full length. While track 0 is the only video track, deleting a track-0 clip ripples: its footprint closes and everything after it — clips, titles, captions, soundtrack — slides left in sync, while items standing over the footprint fall back to where it started. With overlay video tracks present the delete leaves its gap in place (remove_gap closes it). Deletes on other tracks remove just that item.",
inputSchema: obj({
kind: { type: "string", enum: ["clip", "audio", "overlay"], description: "Item kind — 'clip' is any video clip, whatever track; 'overlay' is any title-lane element" },
id: str("Item id"),
diff --git a/site/src/cut/lib/laneTracks.ts b/site/src/cut/lib/laneTracks.ts
index 52e2086f..d1f25fcb 100644
--- a/site/src/cut/lib/laneTracks.ts
+++ b/site/src/cut/lib/laneTracks.ts
@@ -30,7 +30,7 @@
import type React from "react";
import { refFromAsset, startPointerRefDrag } from "./assetRef";
import { startDrag } from "./drag";
-import { track0Clips, clipLen, getClipSpans, moveOverlayGroup, nextFreeStart, overlayLaneOrder, overlayLayers, projectDuration, useEditor } from "./store";
+import { track0Clips, clipLen, getClipSpans, moveOverlayGroup, nextFreeStart, overlayLaneOrder, overlayLayers, projectDuration, reanchorTransitions, startTrimRipple, useEditor } from "./store";
import { playheadAt } from "./playhead";
import type {
AudioClip,
@@ -150,8 +150,7 @@ const clipAdapter: LaneAdapter<VideoClip> = {
leftFloor: (c) => Math.max(0, c.start - c.in / speedOf(c)),
maxLen: videoMaxLen,
closesGap: true,
- assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId),
- onMoved: () => useEditor.getState().sortClips(),
+ assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId), onMoved: () => useEditor.getState().sortClips(),
};
const audioAdapter: LaneAdapter<AudioClip> = {
@@ -177,8 +176,7 @@ const audioAdapter: LaneAdapter<AudioClip> = {
maxLen: (s, a) =>
((s.assets.find((x) => x.id === a.assetId)?.duration ?? a.out) - a.in) / speedOf(a),
lanePatch: (a, lane) => ({ id: a.id, patch: { lane: lane > 0 ? lane : undefined } }),
- assetOf: (s, a) => s.assets.find((x) => x.id === a.assetId),
-};
+ assetOf: (s, a) => s.assets.find((x) => x.id === a.assetId),};
const textAdapter: LaneAdapter<Overlay> = {
minLen: 0.2,
@@ -219,8 +217,7 @@ const overlayClipAdapter: LaneAdapter<VideoClip> = {
leftFloor: (c) => Math.max(0, c.start - c.in / speedOf(c)),
maxLen: videoMaxLen,
closesGap: true,
- assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId),
-};
+ assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId),};
const cueAdapter: LaneAdapter<SubtitleCue> = {
minLen: 0.15,
@@ -1150,6 +1147,34 @@ export function startLaneTrim(
.raws(s)
.map((r) => ({ raw: r, view: ad.view(r) }))
.filter((x) => x.view.id !== id && x.view.lane === self.lane);
+ // While track 0 is the only video track, a spine trim ripples: everything
+ // past the clip's tail — clips, titles, captions, soundtrack — rides the
+ // moved edge in both directions, every gap keeping its width. With overlay
+ // video tracks present the engine is null (the delete gate) and the trim
+ // keeps its own track's push rules.
+ const ripple =
+ kind === "clip"
+ ? (startTrimRipple(s, id, self.start + self.len) as {
+ move: (shift: number, clipPatches: Patch<LaneRaw>[]) => void;
+ settle: (close?: { at: number; shift: number }) => void;
+ } | null)
+ : null;
+ // The clip layout the gesture started from, so a trim with no ripple engine
+ // behind it can still map the bars onto where it left the cuts.
+ const clips0 = kind === "clip" ? s.clips : null;
+ /** Close the gesture: the ripple settles the document when there is one,
+ * and either way the transition bars re-seat onto the cuts the trim moved.
+ * A dissolve follows its cut whether or not the project has overlay tracks. */
+ const settle = (close?: { at: number; shift: number }) => {
+ if (ripple) {
+ ripple.settle(close);
+ return;
+ }
+ if (!clips0) return;
+ const st = useEditor.getState();
+ if (st.transitions.length)
+ useEditor.setState({ transitions: reanchorTransitions(clips0, st.clips, st.transitions) });
+ };
if (side === "l") {
const start0 = self.start;
@@ -1242,30 +1267,44 @@ export function startLaneTrim(
const end = ad.revealLeftPatch
? Math.max(start, floor) + len0 + (start0 - reveal)
: start0 + len0;
- const delta = Math.max(0, end - nextStart);
- if (delta !== lastDelta) {
- patches.push(...followers.map((f) => ad.movePatch(f.raw, f.view.start + delta)));
- lastDelta = delta;
+ if (ripple) {
+ ripple.move(end - (start0 + len0), patches);
+ } else {
+ const delta = Math.max(0, end - nextStart);
+ if (delta !== lastDelta) {
+ patches.push(...followers.map((f) => ad.movePatch(f.raw, f.view.start + delta)));
+ lastDelta = delta;
+ }
+ ad.apply(patches);
}
- ad.apply(patches);
},
onUp: () => {
ui.onSnap(null);
releaseOvershoot();
const cur = ad.raws(useEditor.getState()).find((r) => ad.view(r).id === id);
const from = cur ? ad.view(cur).start : floor;
- if (from >= floor - 1e-4) return; // settled within the room
+ if (from >= floor - 1e-4) {
+ // Settled within the room. A head trimmed to the right left its
+ // trimmed footage as a gap; the ripple closes it, pulling the clip
+ // and everything after back onto the footage that survives.
+ settle(from > start0 + 1e-4 ? { at: start0, shift: start0 - from } : undefined);
+ return;
+ }
// Elastic spring back to the floor. `finish` lands the floor exactly,
// so an interrupting gesture settles rather than strands the trim.
// The rubber engages only past the source floor, so the sprung patch
// keeps the full reveal.
const t0 = performance.now();
- const finish = () => ad.apply([selfPatch(floor, srcFloor)]);
+ const finish = () => {
+ ad.apply([selfPatch(floor, srcFloor)]);
+ settle();
+ };
const step = (now: number) => {
const p = Math.min(1, (now - t0) / 240);
const v = Math.max(0, from + (floor - from) * easeOutBack(p));
ad.apply([selfPatch(p < 1 ? v : floor, srcFloor)]);
snapBack = p < 1 ? { raf: requestAnimationFrame(step), finish } : null;
+ if (p >= 1) settle();
};
snapBack = { raf: requestAnimationFrame(step), finish };
},
@@ -1306,33 +1345,48 @@ export function startLaneTrim(
end = ceil + rubberBand((desired - ceil) * ui.pps, RUBBER_PX) / ui.pps;
ui.onSnap(null);
}
- // Followers respond only to growth up to the ceiling, so the overshoot
+ // Followers respond only to travel up to the ceiling, so the overshoot
// gives visually without shoving the run — and springing back needs no
// re-lay, just as packed leaders hold at the floor on the left edge.
- const delta = Math.max(0, Math.min(end, ceil) - nextStart);
- const run =
- delta === lastDelta
- ? []
- : followers.map((f) => ad.movePatch(f.raw, f.view.start + delta));
- lastDelta = delta;
- ad.apply([ad.trimRightPatch(raw0, end), ...run]);
+ if (ripple) {
+ // The document rides the edge both ways, every gap keeping its width.
+ ripple.move(Math.min(end, ceil) - end0, [ad.trimRightPatch(raw0, end)]);
+ } else {
+ const delta = Math.max(0, Math.min(end, ceil) - nextStart);
+ const run =
+ delta === lastDelta
+ ? []
+ : followers.map((f) => ad.movePatch(f.raw, f.view.start + delta));
+ lastDelta = delta;
+ ad.apply([ad.trimRightPatch(raw0, end), ...run]);
+ }
},
onUp: () => {
ui.onSnap(null);
const cur = ad.raws(useEditor.getState()).find((r) => ad.view(r).id === id);
- if (!cur) return;
+ if (!cur) {
+ settle();
+ return;
+ }
const v = ad.view(cur);
const from = v.start + v.len;
- if (from <= ceil + 1e-4) return; // settled within the room
+ if (from <= ceil + 1e-4) {
+ settle();
+ return; // settled within the room
+ }
// Elastic spring back to the ceiling. `finish` lands it exactly, so an
// interrupting gesture settles rather than strands an over-ceiling trim.
const t0 = performance.now();
- const finish = () => ad.apply([ad.trimRightPatch(raw0, ceil)]);
+ const finish = () => {
+ ad.apply([ad.trimRightPatch(raw0, ceil)]);
+ settle();
+ };
const step = (now: number) => {
const p = Math.min(1, (now - t0) / 240);
const e2 = from + (ceil - from) * easeOutBack(p);
ad.apply([ad.trimRightPatch(raw0, p < 1 ? e2 : ceil)]);
snapBack = p < 1 ? { raf: requestAnimationFrame(step), finish } : null;
+ if (p >= 1) settle();
};
snapBack = { raf: requestAnimationFrame(step), finish };
},
diff --git a/site/src/cut/lib/store.test.ts b/site/src/cut/lib/store.test.ts
index 90d74c4c..675738dc 100644
--- a/site/src/cut/lib/store.test.ts
+++ b/site/src/cut/lib/store.test.ts
@@ -1,6 +1,6 @@
import { beforeEach, describe, expect, test } from "bun:test";
import { groupRemap } from "@donkeycut/effects-kit";
-import { adoptTransitionFields, clipLen, cutTranscribeSpec, deriveTransitionFields, docOverlays, getClipSpans, liftClipLooks, moveOverlayGroup, overlayLaneOrder, normalizeElementLanes, parkedTransitions, placeInRun, projectDuration, separateOverlaps, serializeDoc, useEditor } from "./store";
+import { adoptTransitionFields, clipLen, cutTranscribeSpec, deriveTransitionFields, docOverlays, getClipSpans, liftClipLooks, moveOverlayGroup, overlayLaneOrder, normalizeElementLanes, parkedTransitions, placeInRun, projectDuration, separateOverlaps, serializeDoc, startTrimRipple, useEditor } from "./store";
import { playheadAt, setPlayhead, setSkim } from "./playhead";
import { emptySubtitles } from "./types";
import type { AudioClip, MediaAsset, SubtitleCue, TextOverlay, VideoClip } from "./types";
@@ -747,6 +747,96 @@ describe("delete ripple and gaps", () => {
expect(s().overlays[0].start).toBeCloseTo(1);
});
+ test("a title on its own row survives the clip it was written over", () => {
+ const a = vclip({ track: 0, start: 0, out: 2 });
+ const b = vclip({ track: 0, start: 2, out: 2 });
+ const t = title({ start: 2.5, end: 3.5, lane: 1 });
+ useEditor.setState({
+ clips: [a, b],
+ overlays: [t],
+ selection: { kind: "clip", id: b.id },
+ });
+ s().deleteSelection();
+ // The clip goes; the title keeps its full second and falls back to where
+ // the footage under it used to start.
+ expect(s().overlays.map((o) => o.id)).toEqual([t.id]);
+ expect(s().overlays[0].start).toBeCloseTo(2);
+ expect(s().overlays[0].end).toBeCloseTo(3);
+ });
+
+ test("a soundtrack spanning the deleted clip keeps every second of it", () => {
+ const a = vclip({ track: 0, start: 0, out: 2 });
+ const b = vclip({ track: 0, start: 2, out: 2 });
+ const c = vclip({ track: 0, start: 4, out: 2 });
+ const bed = aclip({ start: 0, out: 6 });
+ useEditor.setState({
+ clips: [a, b, c],
+ audioClips: [bed],
+ selection: { kind: "clip", id: b.id },
+ });
+ s().deleteSelection();
+ expect(s().audioClips.map((x) => x.id)).toEqual([bed.id]);
+ expect(audioById(bed.id).start).toBeCloseTo(0);
+ expect(clipLen(audioById(bed.id))).toBeCloseTo(6);
+ expect(clipById(c.id).start).toBeCloseTo(2);
+ });
+
+ test("captions over the deleted footage stand, packed and in order", () => {
+ const a = vclip({ track: 0, start: 0, out: 2 });
+ const b = vclip({ track: 0, start: 2, out: 4 });
+ const q1 = cue({ start: 2.5, end: 3, words: [{ t0: 2.5, t1: 3, w: "one" }] });
+ const q2 = cue({ start: 3.5, end: 4 });
+ useEditor.setState({
+ clips: [a, b],
+ subtitles: { ...emptySubtitles(), cues: [q1, q2] },
+ selection: { kind: "clip", id: b.id },
+ });
+ s().deleteSelection();
+ const cues = s().subtitles.cues;
+ expect(cues.map((c) => c.id)).toEqual([q1.id, q2.id]);
+ expect(cues[0].start).toBeCloseTo(2);
+ expect(cues[0].end).toBeCloseTo(2.5);
+ expect(cues[0].words![0].t0).toBeCloseTo(2);
+ expect(cues[1].start).toBeCloseTo(2.5);
+ expectLaneSound(cues);
+ });
+
+ test("two titles on one row pulled back by a ripple stay apart", () => {
+ const a = vclip({ track: 0, start: 0, out: 2 });
+ const b = vclip({ track: 0, start: 2, out: 4 });
+ const t1 = title({ start: 2.5, end: 3 });
+ const t2 = title({ start: 3.5, end: 4 });
+ useEditor.setState({
+ clips: [a, b],
+ overlays: [t1, t2],
+ selection: { kind: "clip", id: b.id },
+ });
+ s().deleteSelection();
+ expect(s().overlays.map((o) => o.id)).toEqual([t1.id, t2.id]);
+ expectLaneSound(s().overlays);
+ expect(s().overlays.find((o) => o.id === t2.id)!.start).toBeCloseTo(2.5);
+ });
+
+ test("a grouped set crossing rows stays rigid through the ripple", () => {
+ const a = vclip({ track: 0, start: 0, out: 2 });
+ const b = vclip({ track: 0, start: 2, out: 6 });
+ // Lane 0 is crowded right where the group wants to land, so its member
+ // packs in behind the resident — and its peer on lane 1 comes along.
+ const resident = title({ start: 2.2, end: 2.9 });
+ const g1 = title({ start: 4, end: 5, groupId: "g" });
+ const g2 = title({ start: 4, end: 5, lane: 1, groupId: "g" });
+ useEditor.setState({
+ clips: [a, b],
+ overlays: [resident, g1, g2],
+ selection: { kind: "clip", id: b.id },
+ });
+ s().deleteSelection();
+ const byId = (id: string) => s().overlays.find((o) => o.id === id)!;
+ expect(s().overlays.length).toBe(3);
+ expect(byId(g1.id).start).toBeCloseTo(byId(g2.id).start);
+ expectLaneSound(s().overlays.filter((o) => (o.lane ?? 0) === 0));
+ });
+
test("delete with an overlay video track leaves the gap in place", () => {
const a = vclip({ track: 0, start: 0, out: 2 });
const b = vclip({ track: 0, start: 2, out: 2 });
@@ -838,6 +928,123 @@ describe("delete ripple and gaps", () => {
});
});
+describe("resize ripple", () => {
+ test("shrinking a clip pulls everything after it along, gaps kept", () => {
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const b = vclip({ track: 0, start: 4, out: 2 });
+ const t = title({ start: 4.5, end: 5.5 });
+ const au = aclip({ start: 5, out: 1 });
+ const q = cue({ start: 4.2, end: 4.8, words: [{ t0: 4.2, t1: 4.8, w: "hi" }] });
+ useEditor.setState({
+ clips: [a, b],
+ overlays: [t],
+ audioClips: [au],
+ subtitles: { ...emptySubtitles(), cues: [q] },
+ });
+ s().setClipTrim(a.id, 0, 3);
+ expect(clipById(b.id).start).toBeCloseTo(3);
+ expect(s().overlays[0].start).toBeCloseTo(3.5);
+ expect(audioById(au.id).start).toBeCloseTo(4);
+ expect(s().subtitles.cues[0].start).toBeCloseTo(3.2);
+ expect(s().subtitles.cues[0].words![0].t0).toBeCloseTo(3.2);
+ });
+
+ test("growing a clip pushes them right the same way", () => {
+ const av = asset(8);
+ const a = vclip({ track: 0, start: 0, out: 4, assetId: av.id });
+ const b = vclip({ track: 0, start: 5, out: 2, assetId: av.id }); // a 1s gap before b
+ const t = title({ start: 5, end: 6 });
+ useEditor.setState({ assets: [av], clips: [a, b], overlays: [t] });
+ s().setClipTrim(a.id, 0, 6);
+ expect(clipById(b.id).start).toBeCloseTo(7); // its gap survives
+ expect(s().overlays[0].start).toBeCloseTo(7);
+ });
+
+ test("growing into an abutting neighbor carries it along, never over it", () => {
+ const av = asset(8);
+ const a = vclip({ track: 0, start: 0, out: 4, assetId: av.id });
+ const b = vclip({ track: 0, start: 4, out: 2, assetId: av.id }); // butted joint
+ const t = title({ start: 4, end: 5 });
+ useEditor.setState({ assets: [av], clips: [a, b], overlays: [t] });
+ s().setClipTrim(a.id, 0, 6);
+ expect(clipById(b.id).start).toBeCloseTo(6);
+ expect(s().overlays[0].start).toBeCloseTo(6);
+ expectLaneSound(videoLane(0));
+ });
+
+ test("the gesture's tail growth rides the abutting run too", () => {
+ // The left handle's pinned reveal and the right handle's growth both feed
+ // the engine a positive shift; the clip butted against the tail moves.
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const b = vclip({ track: 0, start: 4, out: 2 });
+ useEditor.setState({ clips: [a, b] });
+ const engine = startTrimRipple(s(), a.id, 4)!;
+ engine.move(1, [{ id: a.id, patch: { out: 5 } }]);
+ expect(clipById(b.id).start).toBeCloseTo(5);
+ expectLaneSound(videoLane(0));
+ engine.move(0, [{ id: a.id, patch: { out: 4 } }]);
+ expect(clipById(b.id).start).toBeCloseTo(4);
+ engine.settle();
+ });
+
+ test("an item standing over the shortened tail falls back to the new end", () => {
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const t = title({ start: 3, end: 5 });
+ useEditor.setState({ clips: [a], overlays: [t] });
+ s().setClipTrim(a.id, 0, 2);
+ expect(s().overlays[0].start).toBeCloseTo(2);
+ expect(s().overlays[0].end).toBeCloseTo(4);
+ });
+
+ test("with an overlay video track a shrink keeps its own-track rules", () => {
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const b = vclip({ track: 0, start: 4, out: 2 });
+ const layer = vclip({ track: 1, start: 1, out: 2 });
+ useEditor.setState({ clips: [a, b, layer] });
+ s().setClipTrim(a.id, 0, 3);
+ expect(clipById(b.id).start).toBeCloseTo(4); // the gap stays
+ expect(clipById(layer.id).start).toBeCloseTo(1);
+ });
+
+ test("the trim gesture ripples live and a retreat flows everything back", () => {
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const b = vclip({ track: 0, start: 4, out: 2 });
+ const t = title({ start: 4.5, end: 5 });
+ useEditor.setState({ clips: [a, b], overlays: [t] });
+ const engine = startTrimRipple(s(), a.id, 4)!;
+ engine.move(-1, [{ id: a.id, patch: { out: 3 } }]);
+ expect(clipById(a.id).out).toBeCloseTo(3);
+ expect(clipById(b.id).start).toBeCloseTo(3);
+ expect(s().overlays[0].start).toBeCloseTo(3.5);
+ engine.move(0, [{ id: a.id, patch: { out: 4 } }]);
+ expect(clipById(b.id).start).toBeCloseTo(4);
+ expect(s().overlays[0].start).toBeCloseTo(4.5);
+ engine.settle();
+ });
+
+ test("settling a head trim closes the footage it removed", () => {
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const b = vclip({ track: 0, start: 4, out: 2 });
+ const t = title({ start: 5, end: 6 });
+ useEditor.setState({ clips: [a, b], overlays: [t] });
+ const engine = startTrimRipple(s(), a.id, 4)!;
+ // The left handle dragged right by 1: head trimmed, gap opened before.
+ engine.move(0, [{ id: a.id, patch: { start: 1, in: 1 } }]);
+ engine.settle({ at: 0, shift: -1 });
+ expect(clipById(a.id).start).toBeCloseTo(0);
+ expect(clipById(a.id).in).toBeCloseTo(1);
+ expect(clipById(b.id).start).toBeCloseTo(3);
+ expect(s().overlays[0].start).toBeCloseTo(4);
+ });
+
+ test("with an overlay video track the gesture engine stays off", () => {
+ const a = vclip({ track: 0, start: 0, out: 4 });
+ const layer = vclip({ track: 1, start: 0, out: 2 });
+ useEditor.setState({ clips: [a, layer] });
+ expect(startTrimRipple(s(), a.id, 4)).toBe(null);
+ });
+});
+
describe("spine grounding", () => {
test("deleting the last track-0 clip grounds the layers above it", () => {
const spine = vclip({ track: 0, start: 0, out: 2 });
diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.ts
index 0dc3582d..0aab81f9 100644
--- a/site/src/cut/lib/store.ts
+++ b/site/src/cut/lib/store.ts
@@ -415,12 +415,14 @@ export interface EditorState {
/** Place an effect element; a drop passes where it landed. */
addEffect: (effect: EffectId, aim?: { at?: number; lane?: number }) => void;
updateClip: (id: string, patch: Partial<VideoClip>) => void;
- /** Set a clip's playback rate (0.25–4). A longer footprint pushes the
- * following clips right by the overflow; a shorter one opens a gap. */
+ /** Set a clip's playback rate (0.25–4). The footprint change carries the
+ * timeline behind it the way a trim does (see resizeClipFootprint). */
setClipSpeed: (id: string, speed: number) => void;
- /** Set a clip's source trim points with the same run rules as a speed
- * resize: a longer footprint pushes the following clips right, a shorter
- * one opens a gap, and a live dissolve keeps its overlap. */
+ /** Set a clip's source trim points. While track 0 is the only video track,
+ * a track-0 resize ripples: everything past the clip's tail rides the moved
+ * edge both directions, gaps keeping their width. Otherwise the run rules
+ * stay on the clip's own track: growth pushes the following clips right, a
+ * shrink opens a gap, and a live dissolve keeps its contact. */
setClipTrim: (id: string, nextIn: number, nextOut: number) => void;
/** Set the transition into the next clip (seconds; 0 clears it), optionally
* changing its style; omitting the style keeps the current one. Upserts the
@@ -548,6 +550,14 @@ export interface EditorState {
updateAudiosTransient: (patches: { id: string; patch: Partial<AudioClip> }[]) => void;
updateCuesTransient: (patches: { id: string; patch: Partial<SubtitleCue> }[]) => void;
updateClipsTransient: (patches: { id: string; patch: Partial<VideoClip> }[]) => void;
+ /** Patch every collection in one write — a trim gesture's ripple lands the
+ * whole document per pointer move, so the frame renders once. */
+ updateDocTransient: (patches: {
+ clips?: { id: string; patch: Partial<VideoClip> }[];
+ audioClips?: { id: string; patch: Partial<AudioClip> }[];
+ overlays?: { id: string; patch: OverlayPatch }[];
+ cues?: { id: string; patch: Partial<SubtitleCue> }[];
+ }) => void;
updateClipTransient: (id: string, patch: Partial<VideoClip>) => void;
updateAudioTransient: (id: string, patch: Partial<AudioClip>) => void;
/** Keep the clips array sorted by start (consumers read `clips[0]` as the
@@ -635,14 +645,17 @@ export interface EditorState {
* from the original recording, so the word highlighter would otherwise drift). */
retimeCues: (entries: { id: string; start: number; end: number }[]) => void;
sortCues: () => void;
- /** Delete the current selection. While track 0 is the only video track and
+ /** Delete the current selection — and only the selection: a clip delete
+ * never takes a title, sticker, caption or soundtrack clip with it, whatever
+ * footage they were laid over. While track 0 is the only video track and
* some of its footage survives, a track-0 clip delete ripples: the footprint
- * it occupied closes and everything after it — clips, titles, captions,
- * soundtrack — slides left in sync (see exciseRange). With upper video
- * layers present the slide would shear them against track 0, and with track
- * 0 emptied there is nothing left for the close to keep contiguous, so both
- * leave the gap and everything laid over the footage stands; closing it is
- * `removeLaneGap`. Deletes on every other track remove just that item. */
+ * it occupied closes and everything after it slides left in sync, while
+ * anything standing over the hole falls back to where the footage started
+ * (see rippleAt). With upper video layers present the slide would shear
+ * them against track 0, and with track 0 emptied there is nothing left for
+ * the close to keep contiguous, so both leave the gap and everything stands
+ * where it was; closing it is `removeLaneGap`. Deletes on every other track
+ * remove just that item. */
deleteSelection: () => void;
/** Close the empty span on `lane` containing `at` — a video track, an audio
* track, or a title track. Only that row's later items slide left; every
@@ -948,38 +961,61 @@ function pushOverlaysClearOf(ids: Set<string>) {
}));
}
-/** Resize a clip's footprint to `newLen` (a trim or speed change), keeping its
- * own track sound: a cut the clip transitions over stays a cut (the run
- * follows the resize so the pair keeps its contact); otherwise a longer
- * footprint pushes the run right by the overflow and a shorter one just opens
- * a gap. Everything is scoped to the clip's track — resizing a track-0 clip
- * never drags the composited layers (or vice versa), so each track's
- * annotations keep the timing they were placed at. One undo step. */
+/** Resize a clip's footprint to `newLen` (a trim or speed change) and carry
+ * the timeline behind the moved tail. While track 0 is the only video track,
+ * a track-0 resize ripples the whole document: everything past the tail —
+ * clips, titles, captions, soundtrack — rides the edge in both directions and
+ * every pre-existing gap keeps its width, so annotations stay on the footage
+ * they were laid over. Layer clips, and a spine resize under overlay video
+ * tracks (where the slide would shear the layers), keep the run rules scoped
+ * to their own track: a cut the clip transitions over stays a cut, a longer
+ * footprint pushes the run right by the overflow, and a shorter one opens a
+ * gap. One undo step. */
function resizeClipFootprint(clip: VideoClip, patch: Partial<VideoClip>, newLen: number) {
useEditor.getState().pushHistory();
const before = useEditor.getState().clips;
- const next = useEditor
- .getState()
- .clips.filter((c) => c.id !== clip.id && c.track === clip.track && c.start >= clip.start)
- .reduce<VideoClip | null>((m, c) => (!m || c.start < m.start ? c : m), null);
- // Whether the pair makes the cut this clip's transition lives on, measured
- // before the resize lands.
- const keepContact = !!next && transitionOverlap(clip, next) > 1e-6;
+ const end0 = clip.start + clipLen(clip);
+ const newEnd = clip.start + newLen;
useEditor.getState().updateClipTransient(clip.id, patch);
- const nextStart = next?.start ?? Infinity;
- const delta = keepContact
- ? clip.start + newLen - nextStart
- : Math.max(0, clip.start + newLen - nextStart);
- if (Math.abs(delta) > 1e-6) {
- useEditor.setState((st) => ({
- clips: st.clips
- .map((c) =>
- c.id !== clip.id && c.track === clip.track && c.start >= clip.start
- ? { ...c, start: Math.max(0, c.start + delta) }
- : c
- )
- .sort((a, b) => a.start - b.start),
- }));
+ if (clip.track === 0 && !before.some((c) => c.track !== 0)) {
+ // The spine resize ripples: everything past the clip's tail — clips,
+ // titles, captions, soundtrack — rides the moved edge in both directions,
+ // every pre-existing gap keeping its width (see rippleAt).
+ useEditor.setState((st) => {
+ const out = rippleAt(
+ { clips: st.clips, audioClips: st.audioClips, overlays: st.overlays, cues: st.subtitles.cues },
+ Math.min(end0, newEnd),
+ newEnd - end0
+ );
+ return {
+ clips: out.clips === st.clips ? st.clips : [...out.clips].sort((a, b) => a.start - b.start),
+ audioClips: out.audioClips,
+ overlays: out.overlays,
+ ...(out.cues !== st.subtitles.cues ? { subtitles: { ...st.subtitles, cues: out.cues } } : {}),
+ };
+ });
+ } else {
+ // With upper video layers present the slide would shear them against the
+ // footage they were composed over, so growth pushes the same-track run
+ // and a shrink leaves the gap — except a live dissolve's partner, which
+ // follows the edge to keep the cut it blends.
+ const next = before
+ .filter((c) => c.id !== clip.id && c.track === clip.track && c.start >= clip.start)
+ .reduce<VideoClip | null>((m, c) => (!m || c.start < m.start ? c : m), null);
+ const keepContact = !!next && transitionOverlap(clip, next) > 1e-6;
+ const nextStart = next?.start ?? Infinity;
+ const delta = keepContact ? newEnd - nextStart : Math.max(0, newEnd - nextStart);
+ if (Math.abs(delta) > 1e-6) {
+ useEditor.setState((st) => ({
+ clips: st.clips
+ .map((c) =>
+ c.id !== clip.id && c.track === clip.track && c.start >= clip.start
+ ? { ...c, start: Math.max(0, c.start + delta) }
+ : c
+ )
+ .sort((a, b) => a.start - b.start),
+ }));
+ }
}
// The resized clip's own edge moved, and the run behind it with it, so the
// bars playing those cuts follow.
@@ -2933,6 +2969,43 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
};
}),
+ updateDocTransient: (patches) =>
+ set((s) => {
+ const out: Partial<EditorState> = {};
+ if (patches.clips?.length) {
+ const byId = new Map(patches.clips.map((p) => [p.id, p.patch]));
+ out.clips = s.clips.map((c) => {
+ const patch = byId.get(c.id);
+ return patch ? { ...c, ...patch } : c;
+ });
+ }
+ if (patches.audioClips?.length) {
+ const byId = new Map(patches.audioClips.map((p) => [p.id, p.patch]));
+ out.audioClips = s.audioClips.map((a) => {
+ const patch = byId.get(a.id);
+ return patch ? { ...a, ...patch } : a;
+ });
+ }
+ if (patches.overlays?.length) {
+ const byId = new Map(patches.overlays.map((p) => [p.id, p.patch]));
+ out.overlays = s.overlays.map((o) => {
+ const patch = byId.get(o.id);
+ return patch ? { ...o, ...patch } : o;
+ });
+ }
+ if (patches.cues?.length) {
+ const byId = new Map(patches.cues.map((p) => [p.id, p.patch]));
+ out.subtitles = {
+ ...s.subtitles,
+ cues: s.subtitles.cues.map((c) => {
+ const patch = byId.get(c.id);
+ return patch ? { ...c, ...patch } : c;
+ }),
+ };
+ }
+ return out;
+ }),
+
sortClips: () =>
set((s) => ({ clips: [...s.clips].sort((a, b) => a.start - b.start) })),
@@ -3242,18 +3315,17 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
let cues = s.subtitles.cues.filter((c) => !cueIds.has(c.id));
// Deleting a track-0 clip closes the hole it leaves: everything after
// it — clips, titles, captions, soundtrack — slides left with the
- // surviving footage, and anything living inside the hole annotated
- // footage that is gone, so it goes too. Two conditions gate that
- // ripple. Track 0 has to be the only video track, since with upper
- // layers surviving the slide would shear them against the footage they
- // were composed over. And some track-0 footage has to survive the
- // delete: clearing the whole track leaves no hole to close, and closing
- // it anyway would carry every title, card and caption in the project
- // into the excision. Either way the delete leaves the gap and closing
- // it is an explicit act (removeGap, via right-click on the empty
- // space). Deletes on every other track are plain removals (already
- // applied above). Holes close right-to-left so each one's coordinates
- // stay valid while the ones before it are unprocessed.
+ // surviving footage, and anything standing over the hole falls back to
+ // where the footage started. Nothing but the picked clip leaves the
+ // project. Two conditions gate that ripple. Track 0 has to be the only
+ // video track, since with upper layers surviving the slide would shear
+ // them against the footage they were composed over. And some track-0
+ // footage has to survive the delete, since clearing the whole track
+ // leaves no hole to close. Either way the delete leaves the gap and
+ // closing it is an explicit act (removeGap, via right-click on the
+ // empty space). Deletes on every other track are plain removals
+ // (already applied above). Holes close right-to-left so each one's
+ // coordinates stay valid while the ones before it are unprocessed.
const rippling = clips.some((c) => c.track === 0) && !clips.some((c) => c.track !== 0);
const holes = rippling
? s.clips
@@ -3270,10 +3342,10 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
// any gap that already existed after it survives.
const delta = Math.min(clipLen(gone), next - gone.start);
if (delta < 0.05) continue;
- ({ clips, audioClips, overlays, cues } = exciseRange(
+ ({ clips, audioClips, overlays, cues } = rippleAt(
{ clips, audioClips, overlays, cues },
gone.start,
- delta
+ -delta
));
}
clips = clips.sort((a, b) => a.start - b.start);
@@ -5280,13 +5352,27 @@ export function laneGapAt(
return null;
}
-/** Cut the timeline range [at, at + delta) out of the whole document — the
- * ripple half of a track-0 delete. Items past the hole slide left by delta;
- * items wholly inside it are removed; items straddling an edge keep the part
- * that survives (a layer/soundtrack clip spanning the hole splits around it,
- * excising those source seconds). Track-0 clips only shift: the hole is a
- * deleted track-0 clip's own footprint, so no survivor there can straddle it. */
-function exciseRange(
+/** Items grouped by the row they live on, each row in play order. */
+function byRow<T>(items: T[], row: (x: T) => number, startOf: (x: T) => number): Map<number, T[]> {
+ const rows = new Map<number, T[]>();
+ for (const item of items) {
+ const list = rows.get(row(item));
+ if (list) list.push(item);
+ else rows.set(row(item), [item]);
+ }
+ for (const list of rows.values()) list.sort((a, b) => startOf(a) - startOf(b));
+ return rows;
+}
+
+/** Slide everything on every row past `at` by `shift` seconds — how a track-0
+ * delete or resize carries the rest of the document. A negative shift closes
+ * the span [at, at - shift): items past it slide left in sync, an item
+ * standing over it falls back to `at`, and each row packs so no item overruns
+ * the one ahead of it. A positive shift opens that span, sliding items past
+ * `at` right together. Either way every item survives whole — same media,
+ * same length — pre-existing gaps keep their width, cue words ride along, and
+ * a grouped set of elements moves as one. Items at or before `at` stand. */
+export function rippleAt(
doc: {
clips: VideoClip[];
audioClips: AudioClip[];
@@ -5294,65 +5380,219 @@ function exciseRange(
cues: SubtitleCue[];
},
at: number,
- delta: number
+ shift: number
): typeof doc {
+ if (Math.abs(shift) < 1e-9) return doc;
const EPS = 0.001;
- const end = at + delta;
-
- const cutClip = <T extends VideoClip | AudioClip>(c: T): T[] => {
- const speed = c.speed && c.speed > 0 ? c.speed : 1;
- const stop = c.start + clipLen(c);
- if (stop <= at + EPS) return [c];
- if (c.start >= end - EPS) return [{ ...c, start: c.start - delta }];
- const pieces: T[] = [];
- if (c.start < at) pieces.push({ ...c, out: c.in + (at - c.start) * speed });
- if (stop > end) pieces.push({ ...c, id: pieces.length ? uid() : c.id, start: at, in: c.in + (end - c.start) * speed });
- return pieces.filter((p) => (p.out - p.in) / speed >= MIN_LEN);
+ /** The ripple's own pull on a time: past `at` it moves by the shift, and a
+ * close never drags anything in front of where the closed span began. An
+ * item sitting exactly on `at` — the clip abutting a growing tail — rides
+ * an open and stands through a close (a close cannot move it anyway). */
+ const pull =
+ shift > 0
+ ? (start: number) => (start < at - EPS ? start : start + shift)
+ : (start: number) => (start <= at + EPS ? start : Math.max(at, start + shift));
+
+ /** One kind of row re-laid: each item takes the ripple's pull, then gives
+ * way to whatever the item ahead of it on its row needs. Returns each
+ * item's move. */
+ const slides = <T,>(
+ items: T[],
+ row: (x: T) => number,
+ startOf: (x: T) => number,
+ lenOf: (x: T) => number
+ ): Map<T, number> => {
+ const out = new Map<T, number>();
+ for (const list of byRow(items, row, startOf).values()) {
+ let cursor = -Infinity;
+ for (const item of list) {
+ const start = startOf(item);
+ const landed = Math.max(pull(start), cursor);
+ out.set(item, landed - start);
+ cursor = landed + lenOf(item);
+ }
+ }
+ return out;
};
- const cutText = (o: Overlay): Overlay[] => {
- if (o.end <= at + EPS) return [o];
- if (o.start >= end - EPS) return [{ ...o, start: o.start - delta, end: o.end - delta }];
- const start = Math.min(o.start, at);
- const stop = o.end > end ? o.end - delta : at;
- return stop - start >= MIN_LEN ? [{ ...o, start, end: stop }] : [];
+ /** Elements re-lay the same way, with a grouped set held rigid: the group
+ * takes one move — the member with the least room pins the set — and a
+ * member crowded on its own lane raises it for all of them until every
+ * lane is clear. */
+ const elementSlides = (overlays: Overlay[]): Map<Overlay, number> => {
+ const unit = (o: Overlay) => o.groupId ?? o.id;
+ const tighter = (a: number, b: number) => (Math.abs(a) < Math.abs(b) ? a : b);
+ const moves = new Map<string, number>();
+ for (const o of overlays) {
+ const want = pull(o.start) - o.start;
+ const cur = moves.get(unit(o));
+ moves.set(unit(o), cur === undefined ? want : tighter(cur, want));
+ }
+ const lanes = byRow(overlays, (o) => o.lane ?? 0, (o) => o.start);
+ for (let pass = 0; pass <= overlays.length; pass++) {
+ let raised = false;
+ for (const list of lanes.values()) {
+ let cursor = -Infinity;
+ for (const o of list) {
+ if (o.start + moves.get(unit(o))! < cursor - 1e-9) {
+ moves.set(unit(o), cursor - o.start);
+ raised = true;
+ }
+ cursor = o.start + moves.get(unit(o))! + (o.end - o.start);
+ }
+ }
+ if (!raised) break;
+ }
+ return new Map(overlays.map((o) => [o, moves.get(unit(o))!]));
};
- const cutCue = (c: SubtitleCue): SubtitleCue[] => {
- if (c.end <= at + EPS) return [c];
- if (c.start >= end - EPS) {
- return [{
- ...c,
- start: c.start - delta,
- end: c.end - delta,
- words: c.words?.map((w) => ({ ...w, t0: w.t0 - delta, t1: w.t1 - delta })),
- }];
- }
- const start = Math.min(c.start, at);
- const stop = c.end > end ? c.end - delta : at;
- if (stop - start < MIN_LEN) return [];
- // Same convention as splitCue: a word sits left of a cut when it starts
- // before it. Words swallowed by the hole go with it; later ones slide left
- // and the text follows the surviving words.
- const words = c.words
- ?.filter((w) => w.t0 < at || w.t0 >= end)
- .map((w) => (w.t0 >= end ? { ...w, t0: w.t0 - delta, t1: w.t1 - delta } : w));
- return [{
- ...c,
- start,
- end: stop,
- words: words?.length ? words : undefined,
- text: words?.length ? words.map((w) => w.w).join(" ") : c.text,
- }];
+ const clipBy = slides(doc.clips, (c) => c.track, (c) => c.start, clipLen);
+ const audioBy = slides(doc.audioClips, (a) => a.lane ?? 0, (a) => a.start, clipLen);
+ const textBy = elementSlides(doc.overlays);
+ const cueBy = slides(doc.cues, (c) => c.lane ?? 0, (c) => c.start, (c) => c.end - c.start);
+ const moved = <T,>(item: T, moves: Map<T, number>) => {
+ const by = moves.get(item)!;
+ return Math.abs(by) < 1e-6 ? 0 : by;
};
+ /** Same array back when nothing on it moved, so an untouched collection
+ * keeps its identity (autosave tells an edit from a re-read by it). */
+ const keep = <T,>(orig: T[], next: T[]) => (next.some((x, i) => x !== orig[i]) ? next : orig);
return {
- clips: doc.clips.flatMap((c) =>
- c.track !== 0 ? cutClip(c) : c.start >= end - EPS ? [{ ...c, start: c.start - delta }] : [c]
+ clips: keep(
+ doc.clips,
+ doc.clips.map((c) => {
+ const by = moved(c, clipBy);
+ return by ? { ...c, start: c.start + by } : c;
+ })
+ ),
+ audioClips: keep(
+ doc.audioClips,
+ doc.audioClips.map((a) => {
+ const by = moved(a, audioBy);
+ return by ? { ...a, start: a.start + by } : a;
+ })
+ ),
+ overlays: keep(
+ doc.overlays,
+ doc.overlays.map((o) => {
+ const by = moved(o, textBy);
+ return by ? { ...o, start: o.start + by, end: o.end + by } : o;
+ })
),
- audioClips: doc.audioClips.flatMap(cutClip),
- overlays: doc.overlays.flatMap(cutText),
- cues: doc.cues.flatMap(cutCue),
+ cues: keep(
+ doc.cues,
+ doc.cues.map((c) => {
+ const by = moved(c, cueBy);
+ if (!by) return c;
+ return {
+ ...c,
+ start: c.start + by,
+ end: c.end + by,
+ words: c.words?.map((w) => ({ ...w, t0: w.t0 + by, t1: w.t1 + by })),
+ };
+ })
+ ),
+ };
+}
+
+/** The live ripple a trim-handle drag spreads while track 0 is the only video
+ * track: created at grab, fed the clip's footprint-end travel each pointer
+ * move, settled on release. Each move re-lays every other item from the
+ * grab-time layout through `rippleAt` — so a retreating drag flows everything
+ * back to where it stood — and lands the whole document in one write. Null
+ * when an overlay video track is present: the slide would shear the layers
+ * against the footage they were composed over, so those trims keep the run
+ * rules on their own track (the delete gate). */
+export function startTrimRipple(
+ s: Pick<EditorState, "clips" | "audioClips" | "overlays" | "subtitles" | "transitions">,
+ selfId: string,
+ end0: number
+): {
+ /** Apply one pointer move: `shift` is the footprint end's travel from where
+ * it stood at grab (negative = shorter), `clipPatches` the gesture's own
+ * clip writes — the trim itself, plus any leaders it re-laid. */
+ move: (shift: number, clipPatches: { id: string; patch: Partial<VideoClip> }[]) => void;
+ /** Land the gesture. A left-handle trim that moved the head rightward
+ * leaves its trimmed footage as a gap; `close` names where the head stood
+ * and how far everything behind it slides back to swallow it. Then the
+ * transition bars re-seat on the cuts the gesture moved. */
+ settle: (close?: { at: number; shift: number }) => void;
+} | null {
+ if (s.clips.some((c) => c.track !== 0)) return null;
+ const clips0 = s.clips;
+ const doc0 = {
+ clips: s.clips.filter((c) => c.id !== selfId),
+ audioClips: s.audioClips,
+ overlays: s.overlays,
+ cues: s.subtitles.cues,
+ };
+ // Where each rider last landed, so a move patches only what it changes and
+ // a retreat restores what an earlier move displaced.
+ const placed = new Map<string, number>();
+ for (const c of doc0.clips) placed.set(`c${c.id}`, c.start);
+ for (const a of doc0.audioClips) placed.set(`a${a.id}`, a.start);
+ for (const o of doc0.overlays) placed.set(`o${o.id}`, o.start);
+ for (const q of doc0.cues) placed.set(`q${q.id}`, q.start);
+ let dirty = false;
+ return {
+ move: (shift, clipPatches) => {
+ dirty = true;
+ // The trimmed clip rides along as its patch; `at` sits at the tail's
+ // earlier position, so a shrink pulls nothing in front of the new tail
+ // and growth carries everything past the old one.
+ const out = rippleAt(doc0, Math.min(end0, end0 + shift), shift);
+ const clips = [...clipPatches];
+ const audioClips: { id: string; patch: Partial<AudioClip> }[] = [];
+ const overlays: { id: string; patch: OverlayPatch }[] = [];
+ const cues: { id: string; patch: Partial<SubtitleCue> }[] = [];
+ for (const c of out.clips)
+ if (placed.get(`c${c.id}`) !== c.start) {
+ placed.set(`c${c.id}`, c.start);
+ clips.push({ id: c.id, patch: { start: c.start } });
+ }
+ for (const a of out.audioClips)
+ if (placed.get(`a${a.id}`) !== a.start) {
+ placed.set(`a${a.id}`, a.start);
+ audioClips.push({ id: a.id, patch: { start: a.start } });
+ }
+ for (const o of out.overlays)
+ if (placed.get(`o${o.id}`) !== o.start) {
+ placed.set(`o${o.id}`, o.start);
+ overlays.push({ id: o.id, patch: { start: o.start, end: o.end } });
+ }
+ for (const q of out.cues)
+ if (placed.get(`q${q.id}`) !== q.start) {
+ placed.set(`q${q.id}`, q.start);
+ cues.push({ id: q.id, patch: { start: q.start, end: q.end, words: q.words } });
+ }
+ useEditor.getState().updateDocTransient({ clips, audioClips, overlays, cues });
+ },
+ settle: (close) => {
+ if (close && close.shift < -1e-6) {
+ dirty = true;
+ useEditor.setState((st) => {
+ const out = rippleAt(
+ { clips: st.clips, audioClips: st.audioClips, overlays: st.overlays, cues: st.subtitles.cues },
+ close.at,
+ close.shift
+ );
+ return {
+ clips: out.clips,
+ audioClips: out.audioClips,
+ overlays: out.overlays,
+ ...(out.cues !== st.subtitles.cues ? { subtitles: { ...st.subtitles, cues: out.cues } } : {}),
+ };
+ });
+ }
+ if (!dirty) return;
+ const st = useEditor.getState();
+ // One mapping from the grab layout to where the gesture left the cuts,
+ // so every bar keeps playing the boundary it played.
+ if (st.transitions.length)
+ useEditor.setState({ transitions: reanchorTransitions(clips0, st.clips, st.transitions) });
+ st.sortClips();
+ },
};
}
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 0d177322..5ac88d96 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -84,13 +84,14 @@ Times are in seconds on the shared timeline. The playhead is currentTime; a skim
"timeline-editing": `# Timeline editing
- Every track is free-positioned: items carry a start time, gaps are allowed, and a track-0 gap plays black (and silence). videoTrack entries in editor_state report gapBefore where one exists.
-- While track 0 is the only video track, deleting a track-0 clip ripples: the span it occupied closes, later items on every track slide left together, items wholly inside the span go with it, and straddlers are trimmed. A gap that already existed stays. With overlay video tracks present the delete leaves its gap (remove_gap closes it by sliding that track's later clips left). Deletes on other tracks remove just that item.
+- A delete removes the item asked for and nothing else: a title, sticker, caption or soundtrack clip laid over a deleted clip is still there afterwards, at its full length. While track 0 is the only video track, deleting a track-0 clip ripples: the span it occupied closes, later items on every track slide left together, and anything standing over the span falls back to where the span started. A gap that already existed stays. With overlay video tracks present the delete leaves its gap (remove_gap closes it by sliding that track's later clips left). Deletes on other tracks remove just that item.
- Two ways to move a track-0 clip: place_clip sets its start (respects gaps, slides right if the spot is taken); move_clip reorders by index, opening a slot at the landing point — clips after it shift right, every other gap survives. Index-based inserts (freeze_frame, generated clips) open a slot the same way.
- add_clip puts a project asset on the timeline the way a drag does: video/image onto track 0 (a \`start\`, an \`index\` insert, or appended at the end), audio onto the soundtrack.
- Overlay video: a video/image asset can sit on a track above track 0 (track 1, 2… — topmost wins). A full-frame overlay covers everything below it; give it a layout to share the frame — top/bottom/left/right halves for a split screen, pip for a floating corner box, or a custom region rect. add_overlay_video creates one from a media asset; update_overlay_video moves/trims/regions/mutes/hides it. The user makes them by dragging media above track 0; they drag the region in the preview.
- A clip's timeline length is (out-in)/speed; total duration runs to the last clip's end, gaps included. Transitions blend at cuts and never change layout or length.
- trim_clip changes in/out inside the source media. in >= 0, out <= source duration, out-in >= 0.1.
-- set_speed sets a clip's playback rate; it changes the clip's timeline length, and later titles/captions ripple to stay in sync.
+- Resizes ripple the same way deletes do: while track 0 is the only video track, a track-0 trim or speed change slides everything past the clip's tail — clips, titles, captions, soundtrack — with the moved edge, in both directions, every existing gap keeping its width. With overlay video tracks present, growth pushes the track-0 run and a shrink leaves a gap.
+- set_speed sets a clip's playback rate; it changes the clip's timeline length and carries the timeline behind it like a trim.
- set_transition joins a clip into the next one (0–2s, ${TRANSITION_STYLE_IDS.length} styles); set_animation animates one clip's own entrance/exit — read the transitions-and-fades skill before styling cuts. Splitting or deleting clears the affected transition. A transition is a bar on its own row at an absolute time, so an edit can leave one lining up with nothing: every timeline mutation reports those as \`parkedTransitions\`, and clearing them (remove_transition) is part of finishing the edit. Grading a clip's picture is the color tools (set_color_preset, set_color_grade, set_color_curves, set_color_wheels, set_color_hsl — read the color-grading skill); a stylized post treatment (grain, VHS, halation…) is add_effect, dropped over the stretch of timeline it covers — as is a treatment on the sound (echo, reverb, telephone…).
- split_at cuts the track-0 clip under that time into two clips at the exact frame. With a soundtrack or overlay clip selected it splits that instead.
- The Media and Library panels take the same gestures: ⌘/⇧-click a tile, or sweep a rubber-band over the grid, and dragging any picked tile onto the timeline lays the whole set down one after another from the drop point.