Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
// Ported from axcut/apps/server/src/lib/timeline.ts — pure interval math
// for the clip/trim model. No DOM, no IPC, no side effects. The caller
// (store, exporter, agent) feeds an AxcutDocument and gets back intervals
// or a new document with updated clips.
import { clampToBound } from "../../projectDefaults";
import type {
AxcutClip,
AxcutClipCropRegion,
AxcutDocument,
AxcutTranscript,
AxcutTrimRange,
} from "../schema";
/**
* What `resolvePlaybackSegments` returns: a clip-shaped slice of playable film.
*
* A plain clip, deliberately. An extension is one too by the time it gets here — `withExtensions`
* resolved it into a clip on its own asset upstream — so nothing below this line carries a
* notion of inserted media, and the trim arithmetic is the same it was before insertions existed.
*/
export type PlaybackSegment = AxcutClip;
import { pruneUnusedShaderEffects } from "../shaderEffects";
import { type Interval, subtractInterval } from "../timeline/intervals";
import { keptRawSpans } from "../timeline/programme-time";
import {
anchoredToRawSpanSec,
anchorRegionsWithDerivedMs,
dropPillById,
hasCompleteClipAnchor,
} from "../timeline/timelineMap";
import { dropTrimPillsByIds, trimAppliesToClip } from "../timeline/trim-mapping";
import {
cutTakeHead,
dropUnusedGeneratedMedia,
reanchorAudioTracks,
removeAudioTrack,
separateAudioLanes,
} from "./audioTracks";
import { createId } from "./ids";
import { layoutAt, layoutRuns, materializeLayouts, removeLayoutChange } from "./layout";
/** The region families a delete can target by id. Shared with the store so "which kinds
* exist" has exactly one definition. `trim` is a source-time cut; the rest are pill-merged
* effects (zoom / speed / annotation / camera-fullscreen). Clips are removed via
* {@link removeClip}, not here — deleting a clip reflows the whole timeline. */
export type RegionKind =
| "zoom"
| "trim"
| "annotation"
| "speed"
| "layout"
| "cameraFullscreen"
| "audio"
| "shaderEffect";
/** Length a clip is given before its media has been probed. Lives here, in the pure
* document layer, because that layer decides which clips are still waiting for a real
* duration (`applyProbedDuration`); the store re-exports it for its own callers. */
export const PLACEHOLDER_DURATION_SEC = 60;
export function byStart(a: { startSec: number }, b: { startSec: number }): number {
return a.startSec - b.startSec;
}
// Re-exported, not redefined: `programme-time.ts` needs the same subtraction and cannot
// import it from here without closing a dependency cycle (this module already imports from
// `../timeline`). Callers of `Interval` / `subtractInterval` from this module are unaffected.
export { type Interval, subtractInterval } from "../timeline/intervals";
export function normalizeIntervals(durationSec: number, intervals: Interval[]): Interval[] {
const bounded = intervals
.map((item) => ({
startSec: Math.max(0, Math.min(durationSec, item.startSec)),
endSec: Math.max(0, Math.min(durationSec, item.endSec)),
}))
.filter((item) => item.endSec > item.startSec)
.sort(byStart);
const merged: Interval[] = [];
for (const item of bounded) {
const last = merged.at(-1);
if (!last || item.startSec > last.endSec) {
merged.push({ ...item });
continue;
}
last.endSec = Math.max(last.endSec, item.endSec);
}
return merged;
}
export function primaryAssetDuration(document: AxcutDocument): number {
const asset =
document.assets.find((item) => item.id === document.project.primaryAssetId) ??
document.assets[0];
return asset?.durationSec ?? 0;
}
export function timelineIntervals(document: AxcutDocument): Interval[] {
return normalizeIntervals(
primaryAssetDuration(document),
document.timeline.clips.map((clip) => ({
startSec: clip.sourceStartSec,
endSec: clip.sourceEndSec ?? primaryAssetDuration(document),
})),
);
}
export function buildTimelineFromIntervals(
assetId: string,
intervals: Interval[],
options: {
origin: "system" | "agent" | "user";
reason: string;
transcript: AxcutTranscript | null;
},
): AxcutClip[] {
let cursor = 0;
return intervals.map((interval, index) => {
const duration = interval.endSec - interval.startSec;
const timelineStartSec = cursor;
const timelineEndSec = cursor + duration;
cursor = timelineEndSec;
return {
id: `clip_${index + 1}`,
assetId,
sourceStartSec: interval.startSec,
sourceEndSec: interval.endSec,
timelineStartSec,
timelineEndSec,
wordRefs: collectWordRefs(options.transcript, interval.startSec, interval.endSec),
origin: options.origin,
reason: options.reason,
};
});
}
function collectWordRefs(
transcript: AxcutTranscript | null,
startSec: number,
endSec: number,
): string[] {
if (!transcript) return [];
return transcript.words
.filter((word) => word.endSec > startSec && word.startSec < endSec)
.map((word) => word.id);
}
// Lay clips back-to-back from t=0, preserving each clip's own length. Called
// after any structural change (insert / move / remove / trim) so the timeline
// never has gaps or overlaps between clips. Shared by useTimeline (UI) and
// the agent tool executor (main process) so both enforce the same invariant.
export function resequenceClips(clips: AxcutClip[]): AxcutClip[] {
let cursor = 0;
return clips.map((c) => {
const timelineLen = c.timelineEndSec - c.timelineStartSec;
const sourceLen = (c.sourceEndSec ?? 0) - c.sourceStartSec;
const len = Math.max(0.001, timelineLen > 0 ? timelineLen : sourceLen);
const next = { ...c, timelineStartSec: cursor, timelineEndSec: cursor + len };
cursor += len;
return next;
});
}
/**
* Derived, ephemeral clip list for playback/native/export — never written back to
* `document.timeline.clips`. Each clip's own `[sourceStartSec, sourceEndSec]` (its media
* in/out, edited via the clip's own modal) is untouched as a concept; this only narrows the
* WINDOW of it handed to playback for the trimmed stretch(es), via `subtractInterval`
* (existing, tested — no new interval math). Trims are stored in source time, anchored to
* a clip (`AxcutTrimRange`), and may already be ventilated into multiple entries by
* `ventilateTimelineSpanToTrims` when the user drags one across a clip boundary — subtracting
* per matching clip naturally narrows however many clips that produces, no special-casing.
* Matching goes through `trimAppliesToClip`, so a cut authored on the second of two clips
* over the same media narrows only that clip; matching on `assetId` alone removed the span
* from BOTH, which is the same wrong-clip class the ruler and the transcript pane had.
* Everything else about the clip (id, assetId, webcam pairing/offset via the asset,
* origin/reason) carries through unchanged, which is what makes this apply to the webcam for
* free: webcam sync is derived from the clip's own asset, not recomputed here.
*/
export function resolvePlaybackSegments(
clips: AxcutClip[],
trimRanges: AxcutTrimRange[],
): PlaybackSegment[] {
const ordered = [...clips].sort((a, b) => a.timelineStartSec - b.timelineStartSec);
const result: PlaybackSegment[] = [];
let timelineCursor = 0;
for (const clip of ordered) {
const sourceEnd = clip.sourceEndSec ?? clip.sourceStartSec;
if (sourceEnd <= clip.sourceStartSec) {
// Duration not probed yet — pass through as a single segment, unchanged.
const dur = clip.timelineEndSec - clip.timelineStartSec;
result.push({
...clip,
timelineStartSec: timelineCursor,
timelineEndSec: timelineCursor + dur,
});
timelineCursor += dur;
continue;
}
let kept: Interval[] = [{ startSec: clip.sourceStartSec, endSec: sourceEnd }];
for (const trim of trimRanges) {
if (!trimAppliesToClip(trim, clip)) continue;
kept = subtractInterval(kept, { startSec: trim.startSec, endSec: trim.endSec });
}
const pieces = kept.filter((piece) => piece.endSec > piece.startSec);
pieces.forEach((piece, i) => {
const dur = piece.endSec - piece.startSec;
result.push({
...clip,
id: pieces.length === 1 ? clip.id : `${clip.id}_seg${i + 1}`,
sourceStartSec: piece.startSec,
sourceEndSec: piece.endSec,
timelineStartSec: timelineCursor,
timelineEndSec: timelineCursor + dur,
});
timelineCursor += dur;
});
}
return result;
}
/**
* Project a RAW/document-timeline second (the ruler where trims still occupy their space)
* onto the trim-COMPRESSED output programme — the concatenation of the kept segments that
* {@link resolvePlaybackSegments} produces and that `audio::mix_external_tracks` overlays on.
*
* Built from the SAME kept intervals as `resolvePlaybackSegments` (trims subtracted per clip
* via `subtractInterval`, then concatenated with a shared output cursor), so it agrees with the
* assembled programme in the two cases a naïve "raw − Σ trimmed-before" got wrong: OVERLAPPING
* trims (set subtraction counts the union once, not each trim) and RAW GAPS between clips (the
* cursor only advances on kept content, so a gap is removed just as the programme removes it).
*
* `output(T)` = how much kept content precedes `T`. A `T` inside a trimmed span (or an inter-clip
* gap) collapses to the output edge of the kept content just before it; a `T` past the last kept
* frame carries its raw overhang through unchanged, so a project with no clips is the identity and
* a track parked past the programme stays past it (the mixer then skips it). EXACT for trims; like
* the rest of the audio-track export path it does not model speed regions, which stay an approximation.
*
* Issue #350: imported audio tracks store their head in RAW seconds (seeded from the playhead),
* but the export mixes onto the compressed programme — passing the raw head through verbatim
* delayed every track by the total trim duration ahead of it. The preview already lands them
* correctly because its playhead jumps across trims; this makes the render agree.
*/
export interface PlaybackSpeedRegion {
startMs: number;
endMs: number;
speed: number;
}
/**
* The project's speed regions as every reader should see them. They live on the legacy editor
* envelope, which no schema checks, so this is where their bound applies: a region without a
* usable speed is dropped, as the scene always did, and one past the bound plays at it. A
* hand-edited or agent-written 100x can no longer reach the export while the preview stops at 16x.
*/
export function readSpeedRegions<T extends PlaybackSpeedRegion = PlaybackSpeedRegion>(
document: Pick<AxcutDocument, "legacyEditor">,
): T[] {
const stored = (document.legacyEditor as { speedRegions?: unknown } | null | undefined)
?.speedRegions;
if (!Array.isArray(stored)) return [];
return (stored as T[])
.filter((r) => typeof r?.speed === "number" && Number.isFinite(r.speed) && r.speed > 0)
.map((r) => ({ ...r, speed: clampToBound(r.speed, "playbackSpeed") }));
}
/**
* Output seconds a raw interval `[fromSec, toSec)` occupies once the speed
* regions covering it are applied: a 2x stretch of raw time takes half as long
* to play, so it contributes half its raw length to the programme.
*
* Subdivides at every speed boundary the interval crosses and integrates
* `1 / speed` piecewise. Regions are matched on the raw ruler, the same
* coordinate their pills are drawn in.
*/
function outputDurationOfRawSpan(
fromSec: number,
toSec: number,
speedRegions: PlaybackSpeedRegion[],
): number {
if (toSec <= fromSec) return 0;
if (speedRegions.length === 0) return toSec - fromSec;
// Every boundary inside the span, so each piece has one constant speed.
const cuts = new Set<number>([fromSec, toSec]);
for (const region of speedRegions) {
for (const edge of [region.startMs / 1000, region.endMs / 1000]) {
if (edge > fromSec && edge < toSec) cuts.add(edge);
}
}
const edges = [...cuts].sort((a, b) => a - b);
let out = 0;
for (let i = 0; i < edges.length - 1; i++) {
const start = edges[i];
const end = edges[i + 1];
const mid = (start + end) / 2;
const region = speedRegions.find(
(r) => mid >= r.startMs / 1000 && mid < r.endMs / 1000 && r.speed > 0,
);
out += (end - start) / (region?.speed ?? 1);
}
return out;
}
export function projectRawTimelineSecToPlayback(
clips: AxcutClip[],
trimRanges: AxcutTrimRange[],
rawSec: number,
/**
* Speed regions on the raw ruler. Supplied by the AUDIO paths, which overlay
* a 1x track onto the finished programme and so need its real, speed-adjusted
* clock; omitted by callers that only care about trims. Left out, the
* projection behaves exactly as it did before speed was modelled.
*/
speedRegions: PlaybackSpeedRegion[] = [],
): number {
const ordered = [...clips].sort((a, b) => a.timelineStartSec - b.timelineStartSec);
let outCursor = 0; // output length of the kept content walked so far
let lastRawEnd = 0; // raw end of the last kept segment, for the trailing overhang
let landed: number | null = null; // output(rawSec), once it falls in/before a kept segment
// The kept stretches come from `keptRawSpans`, which is this walk — it was lifted out of
// here so the transcript lanes and the audio mix could ask the same question and get the
// same answer (issue #560). Trims only REMOVE, so a kept span's RAW length is what
// survives; how long it takes to PLAY is a separate question `outputDurationOfRawSpan`
// answers, because a speed region scales it.
for (const seg of keptRawSpans(ordered, trimRanges)) {
if (landed === null && rawSec < seg.endSec) {
// `rawSec` is inside this segment, or before it in a trimmed/gap region (then
// the span clamps to nothing → the output edge just before the gap).
const within = Math.min(Math.max(rawSec, seg.startSec), seg.endSec);
landed = outCursor + outputDurationOfRawSpan(seg.startSec, within, speedRegions);
}
outCursor += outputDurationOfRawSpan(seg.startSec, seg.endSec, speedRegions);
lastRawEnd = seg.endSec;
}
// Past every kept frame: programme end plus whatever raw time hangs off the end (identity when
// there are no clips at all). A value ≥ programme length just means the mixer skips the track.
return landed ?? outCursor + Math.max(0, rawSec - lastRawEnd);
}
export function invertIntervals(intervals: Interval[], durationSec: number): Interval[] {
const cuts: Interval[] = [];
let cursor = 0;
for (const interval of normalizeIntervals(durationSec, intervals)) {
if (interval.startSec > cursor) {
cuts.push({ startSec: cursor, endSec: interval.startSec });
}
cursor = Math.max(cursor, interval.endSec);
}
if (cursor < durationSec) {
cuts.push({ startSec: cursor, endSec: durationSec });
}
return cuts;
}
/** Shape every stored modifier shares during the v5 transition: the clip anchor is
* the source of truth, `startMs`/`endMs` a derived cache. Anchor fields are optional
* because a not-yet-migrated region (see `anchorRegionsWithDerivedMs`) has none. */
type StoredRegion = {
id: string;
startMs: number;
endMs: number;
clipId?: string;
sourceStartSec?: number;
sourceEndSec?: number;
};
/** Apply `fn` to all four modifier collections (document-level + legacyEditor envelopes). */
export function mapAllRegionCollections(
document: AxcutDocument,
fn: (regions: StoredRegion[], prefix: string) => StoredRegion[],
): AxcutDocument {
const legacy = document.legacyEditor as Record<string, unknown> | null;
// The envelope is `z.object({}).passthrough()`, so zod validates NOTHING inside it: a
// project file whose `speedRegions` is a string loads clean and only detonates here, on
// the first clip edit (`regions.filter is not a function` — #356). Guard exactly as
// `upgradeV4DocumentToV5` already does, and for the same reason: a non-array is not a
// collection we can walk. Treating it as absent leaves it in place via the `...legacy`
// spread below, so the rest of the document still edits normally and nothing the user
// had is thrown away on our way past it.
const speedRegions = Array.isArray(legacy?.speedRegions)
? (legacy?.speedRegions as StoredRegion[])
: undefined;
const cameraFullscreenRegions = Array.isArray(legacy?.cameraFullscreenRegions)
? (legacy?.cameraFullscreenRegions as StoredRegion[])
: undefined;
// A clip edit can take a shader effect's last fragment with it: its definition goes too.
return pruneUnusedShaderEffects({
...document,
...(document.layoutRegions
? { layoutRegions: fn(document.layoutRegions, "layout") as AxcutDocument["layoutRegions"] }
: {}),
zoomRanges: fn(
document.zoomRanges as unknown as StoredRegion[],
"zoom",
) as unknown as AxcutDocument["zoomRanges"],
shaderEffectRanges: fn(
(document.shaderEffectRanges ?? []) as unknown as StoredRegion[],
"fxr",
) as unknown as AxcutDocument["shaderEffectRanges"],
annotations: fn(
document.annotations as unknown as StoredRegion[],
"ann",
) as unknown as AxcutDocument["annotations"],
// Repaired here rather than at each of the four call sites, so no structural edit
// can skip it (issue #560).
//
// `reanchorAudioTracks` first: the generic pipeline copies `offsetMs` verbatim into
// every fragment, which corrupts a split take's offsets — a live bug, unrelated to
// lanes, that this walk was already causing. Then `separateAudioLanes`, because the
// same pipeline can slide two disjoint takes into overlap with no audio code
// running, and each kind has to keep ONE row.
//
// Repair, never refusal: a schema refine here would turn an ordinary clip drag into
// a thrown save, and would make every existing document with overlapping same-kind
// pills unloadable.
audioTracks: separateAudioLanes(
reanchorAudioTracks(
fn(
document.audioTracks as unknown as StoredRegion[],
"audio",
) as unknown as AxcutDocument["audioTracks"],
document.timeline.clips,
() => createId("audio"),
),
),
legacyEditor:
legacy && (speedRegions || cameraFullscreenRegions)
? {
...legacy,
...(speedRegions ? { speedRegions: fn(speedRegions, "speed") } : {}),
...(cameraFullscreenRegions
? { cameraFullscreenRegions: fn(cameraFullscreenRegions, "camfull") }
: {}),
}
: document.legacyEditor,
});
}
/** A clamped fragment this short has no surviving content — treat it as fully
* trimmed away and drop it (also absorbs boundary rounding). Matches the coalescer's
* touch epsilon (`coalesceByIdentity`). */
const REGION_WINDOW_EPSILON_SEC = 0.001;
/**
* Reconcile every clip-anchored modifier with the given clip layout: clamp each
* fragment to its clip's CURRENT kept source window, drop the ones with nothing left,
* and refresh the transition `startMs`/`endMs` cache from the (possibly clamped) anchor.
*
* Structural ops that PRESERVE a clip's source window (move / duplicate / reorder) leave
* the anchors inside their window, so the clamp is a no-op and only the derived cache
* moves — that is what let the old `reprojectDocumentRegions` / `reprojectRegionsForReorder`
* machinery go away. A source-range EDIT (the clip's Edit modal / the agent's
* `update_clip_range`) narrows the window: a fragment now beyond it has lost its content,
* so it is shortened to the surviving overlap or dropped when it falls entirely outside —
* the same intersection the export/native path (`projectRegionsToSource`) already applies,
* now folded in here so the STORED document and the timeline pills match it and no façade
* can forget it. A fragment whose anchor clip no longer exists is dropped (content gone).
* A not-yet-probed clip (no real source window) is left un-clamped so a transient
* zero-width window can't nuke its fragments. Not-yet-anchored regions pass through
* untouched; the empty-clip case is guarded so a transient wipe can't delete everything.
*/
export function rederiveRegionMs(document: AxcutDocument, clips: AxcutClip[]): AxcutDocument {
if (clips.length === 0) return document;
const clipById = new Map(clips.map((c) => [c.id, c]));
return mapAllRegionCollections(document, (regions) =>
regions.flatMap((region) => {
if (!hasCompleteClipAnchor(region)) {
return [region];
}
const clip = clipById.get(region.clipId);
if (!clip) return [];
return rederiveAnchoredRegion(region, clip, clips);
}),
);
}
/** One region's share of {@link rederiveRegionMs}: clamp it to its clip's current
* source window, drop it when nothing survives, refresh its derived ms. Extracted
* so `replaceTimeline` can apply it to the regions whose clip SURVIVED while
* re-anchoring only the orphans — a rebuild used to re-anchor everything, which
* moved anchored regions onto whatever content had slid under their ruler
* position. Same body as before, one region at a time. */
function rederiveAnchoredRegion<
T extends StoredRegion & { clipId: string; sourceStartSec: number; sourceEndSec: number },
>(region: T, clip: AxcutClip, clips: AxcutClip[]): T[] {
let { sourceStartSec, sourceEndSec } = region;
// Only clamp against a real, probed window — an unprobed clip has
// `sourceEndSec` at/below `sourceStartSec` and must not shave its fragments.
if (clip.sourceEndSec !== undefined && clip.sourceEndSec > clip.sourceStartSec) {
sourceStartSec = Math.max(sourceStartSec, clip.sourceStartSec);
sourceEndSec = Math.min(sourceEndSec, clip.sourceEndSec);
if (sourceEndSec - sourceStartSec <= REGION_WINDOW_EPSILON_SEC) return [];
}
const span = anchoredToRawSpanSec({ clipId: region.clipId, sourceStartSec, sourceEndSec }, clips);
if (!span) return [];
return [
{
...cutTakeHead(region, sourceStartSec - region.sourceStartSec),
sourceStartSec,
sourceEndSec,
startMs: Math.round(span.startSec * 1000),
endMs: Math.round(span.endSec * 1000),
},
];
}
// ponytail: `reanchorRegions` used to live here — re-ventilate EVERY modifier
// from its RAW ruler ms after a rebuild, on the premise that `replaceTimeline`
// minted brand-new clip identities so no anchor could survive. It no longer
// does, and the premise was the bug: a region's ruler position is where it is
// DRAWN, its anchor is what it is ABOUT, and re-deriving the second from the
// first moves it onto whatever footage slid underneath (measured: a zoom on
// source 40–45 came back on 45–50). What is left of it is the orphan branch of
// `reconcileRegionsAfterReplace`, which is the only case where the ruler really
// is the last thing we know. Deleted rather than left exported: a dead helper
// that does the wrong thing is an invitation.
/** A clip that does not yet describe a real stretch of media: either it carries no
* source extent at all (what `migrateProjectDataToAxcutDocument` produces — the
* migration is pure, so it cannot probe the file for a duration), or it still sits at
* the pre-probe placeholder length. Both mean "waiting for the real duration". */
export function clipAwaitsProbedDuration(clip: AxcutClip, assetId: string): boolean {
if (clip.assetId !== assetId || clip.sourceStartSec !== 0) return false;
const end = clip.sourceEndSec ?? 0;
if (end <= clip.sourceStartSec) return true; // no extent at all (v2 migration)
return Math.abs(end - PLACEHOLDER_DURATION_SEC) < 0.01; // still the placeholder
}
/**
* Apply a freshly probed media duration to the clips still waiting for it, and bring
* the modifiers along.
*
* This is the moment a project imported from the legacy (v1.7 / `PROJECT_VERSION` 2)
* format becomes fully described. That format has no clip list at all — one recording
* plus regions — so migration mints a single clip with NO source extent and leaves
* every region UNANCHORED (anchoring needs a clip with real extent; dropping the
* regions instead would lose user data). The duration only shows up later, when the
* renderer loads the media. Without this step the clip keeps a zero extent forever and
* the regions never get anchored.
*
* Regions are handled by provenance, never wholesale: already-anchored ones only get
* their derived ms refreshed against the new layout (`rederiveRegionMs`), while
* unanchored ones are anchored from the RAW ms they still carry. Re-anchoring
* everything would mint fresh fragment ids for regions whose anchors are already
* correct.
*
* Returns the document unchanged when no clip is waiting, so callers can invoke it on
* every `loadedmetadata` without guarding.
*/
export function applyProbedDuration(
document: AxcutDocument,
assetId: string,
durationSec: number,
): AxcutDocument {
if (!Number.isFinite(durationSec) || durationSec <= 0) return document;
const clips = document.timeline.clips;
if (!clips.some((clip) => clipAwaitsProbedDuration(clip, assetId))) {
// A user may trim the placeholder before metadata arrives. Preserve that edit,
// but replace the asset's fallback so later timeline operations use real bounds.
const asset = document.assets.find((item) => item.id === assetId);
if (asset?.durationSec !== PLACEHOLDER_DURATION_SEC || asset.durationSec === durationSec) {
return document;
}
return {
...document,
assets: document.assets.map((item) =>
item.id === assetId ? { ...item, durationSec } : item,
),
};
}
// Widening a clip pushes everything after it down the ruler by the same delta.
let shiftSec = 0;
const nextClips = clips.map((clip) => {
const shifted = {
...clip,
timelineStartSec: clip.timelineStartSec + shiftSec,
timelineEndSec: clip.timelineEndSec + shiftSec,
};
if (!clipAwaitsProbedDuration(clip, assetId)) return shifted;
const previousLength = clip.timelineEndSec - clip.timelineStartSec;
shiftSec += durationSec - previousLength;
return {
...shifted,
sourceEndSec: clip.sourceStartSec + durationSec,
timelineEndSec: shifted.timelineStartSec + durationSec,
};
});
const withClips: AxcutDocument = {
...document,
assets: document.assets.map((asset) =>
asset.id === assetId ? { ...asset, durationSec: durationSec } : asset,
),
timeline: { ...document.timeline, clips: nextClips },
};
// Anchored regions: refresh the derived cache against the new layout.
const refreshed = rederiveRegionMs(withClips, nextClips);
// Unanchored regions: NOW anchorable — the clip finally has a real extent. Anchored
// one at a time so a region that ventilates into several fragments lands in place,
// and so an already-correct anchor is never re-minted.
return mapAllRegionCollections(refreshed, (regions, prefix) =>
regions.flatMap((region) =>
hasCompleteClipAnchor(region)
? [region]
: (anchorRegionsWithDerivedMs([region], nextClips, () =>
createId(prefix),
) as StoredRegion[]),
),
);
}
/**
* What a `loadedmetadata` event should write, or `null` for "write nothing".
*
* Lives here rather than in the component that fires it because it is pure document
* logic: `applyProbedDuration` above and `replaceTimeline` below are the whole body.
*
* `originatingProjectId` is the project that was open when the event fired. It matters
* because the write is queued (`NewEditorShell.handleLoadedMetadata` puts it on the
* shared timeline write queue): by the time this runs the user may have switched, and
* `knownSec` came off the OLD video, so applying it to the new project is simply a wrong
* number. `saveDocument`'s epoch check cannot catch that — the write is issued after the
* switch rather than across it.
*/
export function documentAfterProbedDuration(
doc: AxcutDocument | null,
assetId: string,
knownSec: number,
originatingProjectId: string | undefined,
): AxcutDocument | null {
if (!doc || doc.assets.length === 0) return null;
if (doc.project.id !== originatingProjectId) return null;
if (doc.timeline.clips.length === 0) {
// ponytail: replaceTimeline derives clip length from asset.durationSec, which
// import never populates — without this the first auto-created clip silently
// comes out empty (normalizeIntervals clamps against a 0 duration, dropping it).
const primaryAsset =
doc.assets.find((asset) => asset.id === doc.project.primaryAssetId) ?? doc.assets[0];
const primaryAssetId = primaryAsset.id;
// Only the asset that actually fired. `replaceTimeline` pins every clip it
// builds to the primary asset, and the seed sizes that clip from `knownSec` —
// so seeding on an event from any OTHER asset writes one video's length under
// another's id. Not a lost seed: the primary's own event does its own seeding.
if (!primaryAssetId || primaryAssetId !== assetId) return null;
const docWithDuration: AxcutDocument = {
...doc,
project: { ...doc.project, primaryAssetId },
// Only a length that was never measured, which is `applyProbedDuration`'s rule
// above widened to cover a stored 0 — the seed exists to give `replaceTimeline` a
// duration to clamp against, and a 0 defeats that exactly as a missing one does.
//
// An empty timeline is NOT proof the asset is unmeasured: the user can delete
// their only clip. And `knownSec` is the 60 s fallback whenever a MediaRecorder
// WebM reports a non-finite duration, so writing it unconditionally traded a real
// 26.517 for 60 under `history: false`, with no undo to get it back. Left alone,
// the recorded length is what the clip below is clamped against, which is the
// right number either way.
assets: doc.assets.map((a) =>
a.id === primaryAssetId && !(a.durationSec && a.durationSec > 0)
? { ...a, durationSec: knownSec }
: a,
),
};
return replaceTimeline(
docWithDuration,
[{ startSec: 0, endSec: knownSec }],
"Auto-created full-duration clip",
);
}
// The pure document layer patches only the clips of THIS asset that are still
// waiting for a real length (the pre-probe placeholder, or the extent-less clip a
// legacy v2 import mints), shifts what follows, and brings the modifiers along —
// anchoring the ones migration had to leave unanchored. It returns the document
// untouched when nothing is waiting, which is this function's "write nothing".
const next = applyProbedDuration(doc, assetId, knownSec);
return next === doc ? null : next;
}
/** One interval of a rebuilt timeline, plus the identity it inherits. `keepClipId`
* is set when the CALLER'S raw interval is (to the epsilon) an existing clip's own
* source window: the same stretch of media, so the same clip. */
export interface TimelineReplacementSlot {
interval: Interval;
keepClipId: string | null;
}
/**
* What a {@link replaceTimeline} would cost, computed before anything is applied.
*
* ponytail: this exists because `replaceTimeline` is the one tool an agent
* reaches for when it cannot find a better one, and until now it answered
* `ok: true` to requests it had silently mangled. Three mechanisms, all of them
* invisible from the outside:
* • `normalizeIntervals` SORTS, so a reorder request ([30-60], [0-30]) comes
* back in ascending order and the swap simply does not happen;
* • it also MERGES adjacent intervals, so handing back the timeline's own
* intervals collapsed two clips into one — the identity call was destructive;
* • the complement replaced `trimRanges` wholesale, so a cut the user made
* inside a kept interval disappeared with no mention anywhere.
* The plan names each of those so the caller can refuse with something the model
* can act on. It is computed on the RAW intervals, because that is the last point
* at which the caller's INTENT (the order they asked for) is still legible.
*/
export interface TimelineReplacementPlan {
assetId: string;
/** The intervals the rebuild would produce, in timeline order. */
slots: TimelineReplacementSlot[];
/** The raw intervals were not in ascending order: the caller meant to
* REORDER. This operation cannot — see {@link moveClip}. */
reorderRequested: boolean;
/** Clips that would cease to exist: merged with a neighbour, shortened,
* dropped, or belonging to another asset (a rebuild only lays out the
* primary one). */
lostClipIds: string[];
/** Trims whose id would disappear because the span they cut now falls
* entirely outside the kept intervals. The CUT survives — that stretch is
* excluded anyway — only the id and its reason are lost. */
absorbedTrimIds: string[];
/** Trims that would be narrowed to their surviving overlap. */
clippedTrimIds: string[];
/** Modifiers anchored to a clip in `lostClipIds`. They are re-ventilated from
* their RULER position, which is not the same as their content: they land on
* whatever footage moved under them. */
slidRegionIds: string[];
}
function intervalsIntersect(a: Interval, b: Interval): Interval | null {
const startSec = Math.max(a.startSec, b.startSec);
const endSec = Math.min(a.endSec, b.endSec);
return endSec - startSec > REGION_WINDOW_EPSILON_SEC ? { startSec, endSec } : null;
}
function sameInterval(a: Interval, b: Interval): boolean {
return (
Math.abs(a.startSec - b.startSec) <= REGION_WINDOW_EPSILON_SEC &&
Math.abs(a.endSec - b.endSec) <= REGION_WINDOW_EPSILON_SEC
);
}
/** Every anchored modifier of the document, all four families, as `{id, clipId}`. */
function anchoredRegionsOf(document: AxcutDocument): Array<{ id: string; clipId: string }> {
const legacy = document.legacyEditor as Record<string, unknown> | null;
const collections: StoredRegion[][] = [
...(document.layoutRegions ? [document.layoutRegions] : []),
document.zoomRanges as unknown as StoredRegion[],
document.annotations as unknown as StoredRegion[],
(legacy?.speedRegions as StoredRegion[] | undefined) ?? [],
(legacy?.cameraFullscreenRegions as StoredRegion[] | undefined) ?? [],
(document.shaderEffectRanges ?? []) as unknown as StoredRegion[],
];
return collections
.flat()
.filter(hasCompleteClipAnchor)
.map((region) => ({ id: region.id, clipId: region.clipId }));
}
export function planTimelineReplacement(
document: AxcutDocument,
intervals: Interval[],
): TimelineReplacementPlan {
const assetId = document.project.primaryAssetId ?? document.assets[0]?.id ?? "";
const duration = primaryAssetDuration(document);
const bounded = intervals
.map((item) => ({
startSec: Math.max(0, Math.min(duration, item.startSec)),
endSec: Math.max(0, Math.min(duration, item.endSec)),
}))
.filter((item) => item.endSec > item.startSec);
// Read the intent BEFORE sorting: after `byStart` there is nothing left to see.
const reorderRequested = bounded.some(
(item, index) => index > 0 && item.startSec < bounded[index - 1].startSec,
);
const clips = document.timeline.clips;
const claimed = new Set<string>();
const matchClip = (interval: Interval): string | null => {
const hit = clips.find(
(clip) =>
!claimed.has(clip.id) &&
clip.assetId === assetId &&
clip.sourceEndSec !== undefined &&
sameInterval({ startSec: clip.sourceStartSec, endSec: clip.sourceEndSec }, interval),
);
if (!hit) return null;
claimed.add(hit.id);
return hit.id;
};
const slots: TimelineReplacementSlot[] = [];
for (const interval of [...bounded].sort(byStart)) {
const keepClipId = matchClip(interval);
const last = slots.at(-1);
const overlaps = last
? interval.startSec < last.interval.endSec - REGION_WINDOW_EPSILON_SEC
: false;
const touches = last
? Math.abs(interval.startSec - last.interval.endSec) <= REGION_WINDOW_EPSILON_SEC
: false;
// Overlapping intervals MUST merge — clips may not overlap. Merely ADJACENT
// ones merge only when neither side is a clip we could keep, which is the
// one place this differs from `normalizeIntervals`: merging [0,30] and
// [30,60] when both name an existing clip is precisely how the identity
// rebuild destroyed a two-clip timeline.
if (last && (overlaps || (touches && !last.keepClipId && !keepClipId))) {
last.interval = {
startSec: last.interval.startSec,
endSec: Math.max(last.interval.endSec, interval.endSec),
};
if (overlaps) last.keepClipId = null;
continue;
}
slots.push({ interval: { ...interval }, keepClipId });
}
const kept = new Set(slots.map((slot) => slot.keepClipId).filter((id): id is string => !!id));
const lostClipIds = clips.filter((clip) => !kept.has(clip.id)).map((clip) => clip.id);
const slidRegionIds = anchoredRegionsOf(document)
.filter((region) => !kept.has(region.clipId))
.map((region) => region.id);
const keptIntervals = slots.map((slot) => slot.interval);
const absorbedTrimIds: string[] = [];
const clippedTrimIds: string[] = [];
for (const trim of document.timeline.trimRanges) {
if (trim.assetId !== assetId) continue;
const pieces = keptIntervals
.map((slot) => intervalsIntersect(slot, { startSec: trim.startSec, endSec: trim.endSec }))
.filter((piece): piece is Interval => piece !== null);
if (pieces.length === 0) absorbedTrimIds.push(trim.id);
else if (pieces.length > 1 || !sameInterval(pieces[0], trim)) clippedTrimIds.push(trim.id);
}
return {
assetId,
slots,
reorderRequested,
lostClipIds,
absorbedTrimIds,
clippedTrimIds,
slidRegionIds,
};
}
export interface ReplaceTimelineOptions {
/** Reuse the id / origin / reason / wordRefs of a clip whose source window a
* kept interval reproduces exactly. Default true — a rebuild that happens to
* keep a stretch of media keeps the clip that WAS that stretch of media. */
preserveIds?: boolean;
/** Carry the primary asset's existing cuts through the rebuild (narrowed to
* the kept intervals). Default true. `restoreFullTimeline` is the one caller
* whose whole point is to drop them. */
preserveTrims?: boolean;
}
export function replaceTimeline(
document: AxcutDocument,
intervals: Interval[],
reason: string,
origin: "system" | "agent" | "user" = "user",
options: ReplaceTimelineOptions = {},
): AxcutDocument {
const assetId = document.project.primaryAssetId ?? document.assets[0]?.id;
if (!assetId) {
throw new Error("Cannot update timeline without a primary asset.");
}
const preserveIds = options.preserveIds !== false;
const preserveTrims = options.preserveTrims !== false;
const duration = primaryAssetDuration(document);
const plan = planTimelineReplacement(document, intervals);
const clipById = new Map(document.timeline.clips.map((clip) => [clip.id, clip]));
let cursor = 0;
const clips: AxcutClip[] = plan.slots.map((slot, index) => {
const length = slot.interval.endSec - slot.interval.startSec;
const timelineStartSec = cursor;
cursor += length;
const existing = preserveIds && slot.keepClipId ? clipById.get(slot.keepClipId) : undefined;
return {
// ponytail: a slot with no ancestor gets a MINTED id, not `clip_${i+1}`.
// Positional ids are what let `trim_1` survive a rebuild while meaning a
// different cut, and mixing them with preserved ids would collide outright
// (a preserved `clip_1` sitting at index 1). The legacy positional naming
// survives only on the `preserveIds: false` path, which rebuilds from nothing.
id: existing?.id ?? (preserveIds ? createId("clip") : `clip_${index + 1}`),
assetId,
sourceStartSec: slot.interval.startSec,
sourceEndSec: slot.interval.endSec,
timelineStartSec,
timelineEndSec: timelineStartSec + length,
wordRefs:
existing?.wordRefs ??
collectWordRefs(document.transcript, slot.interval.startSec, slot.interval.endSec),
origin: existing?.origin ?? origin,
reason: existing?.reason ?? reason,
};
});
const keptIntervals = plan.slots.map((slot) => slot.interval);
const complement = invertIntervals(keptIntervals, duration).map((cut, index) => ({
id: preserveIds ? createId("trim") : `trim_${index + 1}`,
assetId,
startSec: cut.startSec,
endSec: cut.endSec,
origin,
reason,
}));
// Other assets' cuts are NEVER this operation's business — the rebuild only
// lays out the primary asset. Replacing `trimRanges` wholesale wiped them, the
// same bug `operations.ts` had already had to fix for `add_trim_range`.
const foreignTrims = document.timeline.trimRanges.filter((trim) => trim.assetId !== assetId);
const survivingTrims = preserveTrims
? document.timeline.trimRanges.flatMap((trim) => {
if (trim.assetId !== assetId) return [];
return keptIntervals
.map((slot) => intervalsIntersect(slot, { startSec: trim.startSec, endSec: trim.endSec }))
.filter((piece): piece is Interval => piece !== null)
.map((piece, index) => ({
...trim,
id: index === 0 ? trim.id : createId("trim"),
startSec: piece.startSec,
endSec: piece.endSec,
}));
})
: [];
const next: AxcutDocument = {
...document,
timeline: {
...document.timeline,
clips,
trimRanges: [...foreignTrims, ...survivingTrims, ...complement].sort(byStart),
gaps: [],
},
};
return reconcileRegionsAfterReplace(next, clips, new Set(clips.map((clip) => clip.id)));
}
/**
* Regions after a rebuild, by provenance — the fix for the quietest half of
* D-DESTRUCT.
*
* The old code ran `reanchorRegions` over everything, which re-ventilates each
* region from its RAW ruler ms. That is right for a region whose clip is gone
* (its ruler position is all that is left of it) and wrong for one whose clip
* survived: with the intervals [35-60], [0-25], a zoom anchored to clip_2 at
* source 40-45 came back anchored at source 50-55. Ten seconds into different
* footage, schema-valid, unreported. Anything whose anchor still resolves is
* therefore rederived — the anchor IS the content — and only the orphans are
* re-ventilated.
*
* The orphan branch also has to decide what "re-ventilation found nothing"
* means, and the answer depends on where the region came from.
* `anchorRegionsWithDerivedMs` passes such a region through UNCHANGED, which is
* right for a never-anchored one (a v2 migration keeps a region it cannot place
* rather than losing user data) and wrong for one whose clip was just deleted:
* that leaves it pointing at an id nothing resolves, invisible to the timeline
* and revivable by any future clip that happens to take the name. Its content
* is gone, so it goes with it — the same call `removeClip` and
* `setClipSourceRange` already make through `rederiveRegionMs`.
*/
function reconcileRegionsAfterReplace(
document: AxcutDocument,
clips: AxcutClip[],
surviving: Set<string>,
): AxcutDocument {
if (clips.length === 0) return document;
const clipById = new Map(clips.map((clip) => [clip.id, clip]));
return mapAllRegionCollections(document, (regions, prefix) =>
regions.flatMap((region) => {
if (hasCompleteClipAnchor(region) && surviving.has(region.clipId)) {
const clip = clipById.get(region.clipId);
if (clip) return rederiveAnchoredRegion(region, clip, clips);
}
const reventilated = anchorRegionsWithDerivedMs([region], clips, () =>
createId(prefix),
) as StoredRegion[];
const placed = reventilated.some(
(next) => hasCompleteClipAnchor(next) && surviving.has(next.clipId),
);
if (placed) return reventilated;
return hasCompleteClipAnchor(region) ? [] : reventilated;
}),
);
}
// ponytail: reorder an existing clip by removing it from its current
// position and inserting at `insertIndex` (clamped to the array length).
// Used for "move this clip there" / "swap these clips" — preserves all
// user-placed clip ids, origins, and source ranges. Mirrors axcut's
// apps/server/src/lib/timeline.ts#moveClip.
export function moveClip(
document: AxcutDocument,
clipId: string,
insertIndex: number,
origin: "system" | "agent" | "user" = "user",
reason: string = "",
): AxcutDocument {
const index = document.timeline.clips.findIndex((c) => c.id === clipId);
if (index < 0) {
throw new Error(`Unknown clip ${clipId}.`);
}
const movingClip = {
...document.timeline.clips[index],
origin,
reason: reason || document.timeline.clips[index].reason,
};
const remaining = document.timeline.clips.filter((c) => c.id !== clipId);
const bounded = Math.max(0, Math.min(insertIndex, remaining.length));
const reordered = [...remaining.slice(0, bounded), movingClip, ...remaining.slice(bounded)];
return withClipsChanged(document, reordered);
}
// ponytail: duplicate a clip (preserves the original): "make a copy". Mirrors axcut's
// apps/server/src/lib/timeline.ts#duplicateClip.
//
// The copy takes its own COPY of the original's trims, re-anchored to the new clip id.
// Before trims carried a `clipId` this happened by accident — a trim matched on `assetId`,
// so the duplicate (same asset) was born already cut the same way — and that accident is
// the behaviour a user expects from "duplicate": an identical clip. Now that a trim names
// its clip, the copy has to be made on purpose, and the two sets are independent
// afterwards, which is the point: editing the copy's cut no longer edits the original's.
// Only ANCHORED trims are copied — an un-anchored one already reaches the copy through
// the asset-wide fallback, so copying it would cut the same span twice.
//
// The modifiers anchored to the clip are copied the same way, across every collection
// `mapAllRegionCollections` walks; `withClipsChanged` then places the copies on the new
// clip. Imported audio is left out on purpose: a take is media on its own lane, not an
// effect on the clip.
export function duplicateClip(
document: AxcutDocument,
clipId: string,
origin: "system" | "agent" | "user" = "user",
reason: string = "",
): AxcutDocument {
const index = document.timeline.clips.findIndex((c) => c.id === clipId);
if (index < 0) {
throw new Error(`Unknown clip ${clipId}.`);
}
const original = document.timeline.clips[index];
const copy = {
...original,
id: createId("clip"),
origin,
reason: reason || original.reason,
};
const oldClips = document.timeline.clips;
const next = [...oldClips.slice(0, index + 1), copy, ...oldClips.slice(index + 1)];
const copiedTrims = document.timeline.trimRanges
.filter((t) => t.clipId === original.id)
.map((t) => ({ ...t, id: createId("trim"), clipId: copy.id }));
const withModifiers = mapAllRegionCollections(document, (regions, prefix) =>
prefix === "audio"
? regions
: [
...regions,
...regions
.filter((region) => hasCompleteClipAnchor(region) && region.clipId === original.id)
.map((region) => ({ ...region, id: createId(prefix), clipId: copy.id })),
],
);
return withClipsChanged(
{
...withModifiers,
timeline: {
...withModifiers.timeline,
trimRanges: [...withModifiers.timeline.trimRanges, ...copiedTrims],
},
},
next,
);
}
/**
* The single mutator for "place a clip of this asset at this position": the media panel's drop
* onto the timeline and the agent's `insertClip`. `index` counts the clips before it (0 first,
* `clips.length` last) and is clamped. The new clip goes through `withClipsChanged` like every
* other clip edit, so one whose media meets a neighbour's is folded into it. Pure.
*/
export function insertAssetClip(
document: AxcutDocument,
index: number,
clip: Pick<AxcutClip, "id" | "assetId" | "sourceStartSec" | "origin" | "reason"> & {
sourceEndSec: number;
},
): AxcutDocument {
const length = clip.sourceEndSec - clip.sourceStartSec;
const clips = [...document.timeline.clips];
clips.splice(Math.max(0, Math.min(clips.length, index)), 0, {
...clip,
timelineStartSec: 0,
timelineEndSec: length,
wordRefs: [],
});
const insertionTime =
document.timeline.clips[index]?.timelineStartSec ??
Math.max(0, (document.timeline.clips.at(-1)?.timelineEndSec ?? 0) - 0.0001);
const withLayouts: AxcutDocument = document.layoutRegions?.length
? {
...document,
layoutRegions: [
...materializeLayouts(document),
{
id: createId("layout"),
clipId: clip.id,
sourceStartSec: clip.sourceStartSec,
sourceEndSec: clip.sourceEndSec,
startMs: 0,
endMs: length * 1000,
preset: layoutAt(document, insertionTime),
},
],
}
: document;
return withClipsChanged(withLayouts, clips);
}
/**
* The single mutator for a clip's crop alone (the agent's crop-only `setClipRange`); with a range,
* `setClipSourceRange` takes the crop in the same pass.
* `null` clears it back to the full frame rather than storing the identity region. Through
* `withClipsChanged`, since crop is the one property that keeps two meeting clips apart. An
* unknown `clipId` is a no-op. Pure.
*/
export function setClipCrop(
document: AxcutDocument,
clipId: string,
cropRegion: AxcutClipCropRegion | null,
): AxcutDocument {
return withClipsChanged(
document,
document.timeline.clips.map((c) =>
c.id === clipId ? { ...c, cropRegion: cropRegion ?? undefined } : c,
),
);
}
/**
* The single mutator for "narrow/extend a clip's own source in/out" — the edit the
* clip's Edit modal, the renderer op dispatcher, and the LLM's `setClipRange` tool all
* perform. Extracted here (like `moveClip` / `duplicateClip`) so the recipe lives in one
* place instead of being re-derived per façade, which is what let the three drift apart
* (stale width, un-clamped pills). Pure — a plain document→document transform.
*
* Recipe: clamp + order the range, zero the clip's timeline extent so `resequenceClips`
* recomputes its RAW length from the new source window (a raw clip's timeline length equals
* its source length), lay everything back-to-back, then `rederiveRegionMs` clamps every
* anchored pill to the clip's kept window (dropping what the trim removed) and refreshes the
* derived ms of the clips that reflowed. An unknown `clipId` is a no-op.
*
* `cropRegion` is the Edit modal's crop, set in the same pass: `undefined` leaves it, `null`
* clears it. One pass, because the fold decides on range AND crop together: a range applied
* first can fold the clip into a neighbour whose crop the new one would have told apart.
*/
export function setClipSourceRange(
document: AxcutDocument,
clipId: string,
sourceStartSec: number,
sourceEndSec: number,
cropRegion?: AxcutClipCropRegion | null,
): AxcutDocument {
const clamp = (n: number) => (Number.isFinite(n) ? Math.max(0, n) : 0);
const lo = Math.min(clamp(sourceStartSec), clamp(sourceEndSec));
const hi = Math.max(clamp(sourceStartSec), clamp(sourceEndSec));
const arr = document.timeline.clips.map((c) =>
c.id === clipId
? {
...c,
sourceStartSec: lo,
sourceEndSec: hi,
timelineStartSec: 0,
timelineEndSec: 0,
...(cropRegion === undefined ? {} : { cropRegion: cropRegion ?? undefined }),
}
: c,
);
return withClipsChanged(document, arr);
}
/**
* The single mutator for "delete a region by id" — the edit the UI's delete key and the
* LLM's `removeTrim` / `removeModifier` tools all perform. Extracted here (like
* `setClipSourceRange`) so the recipe lives in one place: EVERY kind deletes the whole
* pill, i.e. every row that renders as one stripe with `id` under the merge rule. Modifiers
* go through `dropPillById`; trims need `dropTrimPillsByIds` instead, because `dropPillById`
* keys off `startMs`/`endMs` and a trim stores `startSec`/`endSec` plus a `clipId` anchor —
* different storage, same rule. Trims used to be the exception here (a bare id filter), so a
* cut grown across a clip boundary — necessarily 2+ rows — lost only the row that was
* clicked and kept cutting on the other side. Speed / camera-fullscreen live under
* `legacyEditor`. An id that matches nothing is a no-op. Pure.
*/
export function removeRegion(document: AxcutDocument, kind: RegionKind, id: string): AxcutDocument {
switch (kind) {
case "zoom":
return {
...document,
zoomRanges: dropPillById(document.zoomRanges, id) as AxcutDocument["zoomRanges"],
};
case "annotation":
return {
...document,
annotations: dropPillById(document.annotations, id, { annotations: true }),
};
case "audio":
// Not `dropPillById`: an audio track's fragments are grouped by
// `trackId`, and deleting the pill has to take the asset with it when
// nothing else references it.
return removeAudioTrack(document, id);
case "trim":
return {
...document,
timeline: {
...document.timeline,
trimRanges: dropTrimPillsByIds(document.timeline.trimRanges, document.timeline.clips, [
id,
]),
},
};
case "speed": {
const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
const prev = dropPillById(
(legacy.speedRegions as Array<{ id: string; startMs: number; endMs: number }>) ?? [],
id,
);
return { ...document, legacyEditor: { ...legacy, speedRegions: prev } };
}
case "layout":
return removeLayoutChange(document, id);
case "cameraFullscreen": {
const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
const prev = dropPillById(
(legacy.cameraFullscreenRegions as Array<{ id: string; startMs: number; endMs: number }>) ??
[],
id,
);
return { ...document, legacyEditor: { ...legacy, cameraFullscreenRegions: prev } };
}
case "shaderEffect":
// The definition goes with its last region: no dead code stays in the document.
return pruneUnusedShaderEffects({
...document,
shaderEffectRanges: dropPillById(document.shaderEffectRanges ?? [], id),
});
default: {
// ponytail: exhaustive — TS errors here if a new RegionKind is added.
const exhaustive: never = kind;
void exhaustive;
return document;
}
}
}
const legacyRegionCount = (document: AxcutDocument, key: string): number => {
const stored = (document.legacyEditor as Record<string, unknown> | null)?.[key];
return Array.isArray(stored) ? stored.length : 0;
};
const withLegacyRegionsCleared = (document: AxcutDocument, key: string): AxcutDocument =>
document.legacyEditor
? { ...document, legacyEditor: { ...document.legacyEditor, [key]: [] } }
: document;
/**
* The edit regions "Clear timeline" empties: one entry per `RegionKind` but `audio`. A Record
* rather than a list, so a new kind is a compile error here until someone decides whether it
* is an edit. `audio` is deliberately absent, like everything that is not a region at all:
* clips, media, transcripts, captions and the pauses added words made are content the user
* put there on purpose. (`timeline.speedRanges` is not the speed lane's store; the lane and
* the export read `legacyEditor.speedRegions`.)
*/
const EDIT_REGIONS: Record<
Exclude<RegionKind, "audio">,
{ count: (d: AxcutDocument) => number; clear: (d: AxcutDocument) => AxcutDocument }
> = {
zoom: { count: (d) => d.zoomRanges.length, clear: (d) => ({ ...d, zoomRanges: [] }) },
annotation: { count: (d) => d.annotations.length, clear: (d) => ({ ...d, annotations: [] }) },
trim: {
count: (d) => d.timeline.trimRanges.length,
clear: (d) => ({ ...d, timeline: { ...d.timeline, trimRanges: [] } }),
},
speed: {
count: (d) => legacyRegionCount(d, "speedRegions"),
clear: (d) => withLegacyRegionsCleared(d, "speedRegions"),
},
cameraFullscreen: {
count: (d) => legacyRegionCount(d, "cameraFullscreenRegions"),
clear: (d) => withLegacyRegionsCleared(d, "cameraFullscreenRegions"),
},
layout: {
count: (d) => Math.max(0, layoutRuns(d).length - 1),
clear: (d) => ({ ...d, layoutRegions: [] }),
},
shaderEffect: {
count: (d) => (d.shaderEffectRanges ?? []).length,
clear: (d) => ({ ...d, shaderEffectRanges: [], shaderEffects: [] }),
},
};
/** How many edit regions the document holds, stored rows and not pills. Pure. */
export function countEditRegions(document: AxcutDocument): number {
return Object.values(EDIT_REGIONS).reduce((sum, kind) => sum + kind.count(document), 0);
}
/** The document with every edit region gone (see {@link EDIT_REGIONS}). Pure. */
export function clearEditRegions(document: AxcutDocument): AxcutDocument {
return Object.values(EDIT_REGIONS).reduce((doc, kind) => kind.clear(doc), document);
}
/**
* The document, with its clip list changed to this one.
*
* The pass every clip mutation ends with, and where the clip list's one invariant lives:
* TWO ADJACENT CLIPS THAT ARE THE SAME MEDIA, THE SAME CROP, AND WHOSE MEDIA TIMECODES MEET
* ARE ONE CLIP.
*
* Media timecodes, not ruler ones. Clips are always laid back to back here, so every
* neighbouring pair touches on the ruler and that says nothing; what carries information is
* whether the left clip ENDS in the media where the right one BEGINS. Two clips of one
* recording are laid side by side precisely when they do NOT — a piece dropped between them,
* a different stretch, a different framing. When they do, and nothing distinguishes them,
* they already play as one clip and drawing them as two says nothing at all.
*
* Why it is safe to apply everywhere rather than at the one edit that needs it: given the
* invariant holds, no mutation can make it false in a way that loses anything.
* `duplicateClip` is the case that looks dangerous — a copy inserted after its original ends
* in the media where the original does, so it could meet the next clip. It cannot: the
* original was already adjacent to that clip and did not meet it, or they would be one clip
* already. The only states this can surprise are ones that already violated it, which is to
* say ones where the two clips were indistinguishable to begin with.
*
* The cost, stated so it is a decision: two such clips a user joined by hand fuse, and the
* way back is to move them apart. Cheaper than a marker on every cut, which would have to
* survive every move that makes it wrong.
*/
export function withClipsChanged(document: AxcutDocument, clips: AxcutClip[]): AxcutDocument {
const { clips: joined, absorbed } = joinContiguous(clips);
const laid = resequenceClips(joined);
const reanchored = absorbed.size === 0 ? document : reanchorRows(document, absorbed);
const next: AxcutDocument = {
...reanchored,
timeline: { ...reanchored.timeline, clips: laid },
};
// `rederiveRegionMs` bails on an empty clip list — a guard against a transient wipe
// dropping every region — so there is nothing to refresh against.
return laid.length === 0 ? next : rederiveRegionMs(next, laid);
}
/** Fold every run of same-media, same-crop, media-contiguous clips into one, reporting the
* ids that went away and the clip that now carries their content. */
function joinContiguous(clips: AxcutClip[]): {
clips: AxcutClip[];
absorbed: Map<string, string>;
} {
// ARRAY order, not `timelineStartSec`: the list IS the order, and at this point the
// positions are still the pre-edit ones. Sorting by them re-sorted a reorder back to
// where it came from.
const out: AxcutClip[] = [];
const absorbed = new Map<string, string>();
for (const clip of clips) {
const previous = out[out.length - 1];
if (previous && joinable(previous, clip)) {
out[out.length - 1] = {
...previous,
sourceEndSec: clip.sourceEndSec,
timelineEndSec: previous.timelineEndSec + (clip.timelineEndSec - clip.timelineStartSec),
wordRefs: [...previous.wordRefs, ...clip.wordRefs],
};
absorbed.set(clip.id, previous.id);
continue;
}
out.push(clip);
}
return { clips: out, absorbed };
}
/** Same media, media timecodes that meet, same framing. Crop is the only property a clip
* carries that two otherwise-identical neighbours could legitimately disagree on, so it is
* the whole of the guard. */
function joinable(left: AxcutClip, right: AxcutClip): boolean {
return (
left.assetId === right.assetId &&
left.sourceEndSec !== undefined &&
Math.abs(left.sourceEndSec - right.sourceStartSec) < 1e-6 &&
JSON.stringify(left.cropRegion ?? null) === JSON.stringify(right.cropRegion ?? null)
);
}
/** Move every row anchored to an absorbed clip onto the one that swallowed it. A trim, a
* zoom, an annotation and an audio take all name a clip the same way, and an id that no
* longer exists has to stop being named. */
function reanchorRows(document: AxcutDocument, absorbed: Map<string, string>): AxcutDocument {
const relabel = <T extends StoredRegion>(regions: T[]): T[] =>
regions.map((region) =>
hasCompleteClipAnchor(region) && absorbed.has(region.clipId)
? { ...region, clipId: absorbed.get(region.clipId) as string }
: region,
);
const moved = mapAllRegionCollections(document, relabel);
return {
...moved,
// Relabelled and nothing more. The walk above also re-cuts every take, but against the
// clips as they were, which put the absorbed id straight back and the rederive that
// follows dropped what the absorbed clip carried (#1011). That rederive re-cuts them
// against the joined clips.
audioTracks: relabel(document.audioTracks),
timeline: {
...moved.timeline,
trimRanges: moved.timeline.trimRanges.map((trim) =>
trim.clipId && absorbed.has(trim.clipId)
? { ...trim, clipId: absorbed.get(trim.clipId) }
: trim,
),
},
};
}
/**
* The single mutator for "delete a clip". Removing a clip closes the gap: the survivors are
* re-laid back-to-back (`resequenceClips`) and every anchored pill's derived ms is refreshed
* against the new layout (`rederiveRegionMs`) — pills anchored to the removed clip drop out,
* exactly like `setClipSourceRange`. Trims anchored to it go the same way: their content is
* gone, so keeping them would leave rows nothing can reach (they render on no clip and cut
* no clip) that a later duplicate of the same asset must not resurrect. Shared by the
* store's delete-clip action and the LLM's `removeClip` tool. An unknown `clipId` is a
* no-op. Pure.
*/
export function removeClip(document: AxcutDocument, clipId: string): AxcutDocument {
const oldClips = document.timeline.clips;
const arr = oldClips.filter((c) => c.id !== clipId);
if (arr.length === oldClips.length) return document;
const next: AxcutDocument = {
...document,
timeline: {
...document.timeline,
trimRanges: document.timeline.trimRanges.filter((t) => t.clipId !== clipId),
},
};
// The asymmetry with the trim filter three lines up is deliberate, and the obvious
// "cleanup" that makes the two match reintroduces #249.
//
// A trim's complete anchor IS a bare `clipId` -- it carries its own `startSec`/
// `endSec` in source time (`trimAppliesToClip`), so the clip going away takes the
// trim with it. A region carrying only a `clipId` and no source range is NOT
// anchored (`hasCompleteClipAnchor`): it is still placed by its RAW ms, so the clip
// does not own it and deleting the clip must not delete it.
//
// The cost of keeping it, stated so it is a decision and not an accident: that
// region is now unreachable but immortal. With clips [0-10s] and [10-20s] and a bare
// `clipId` zoom at raw 12000-14000ms, deleting the second clip leaves the zoom off
// the end of a 10s ruler -- no pill to click, dropped by `projectRegionsToSource`,
// and re-emitted by every rederive. Hitting "Restore full timeline" then re-anchors
// it from those stale raw ms onto whatever footage now sits at 12-14s. That is the
// same treatment fully-unanchored legacy regions already get, and losing the user's
// region outright is the worse of the two.
//
// Only the last-clip case needs the filter spelled out. With survivors,
// `rederiveRegionMs` already drops every anchored region whose `clipId` is absent
// from the new clips -- a strict superset of "anchored to the one just removed" --
// so running both walked all four region collections twice and spread the document
// twice per delete. `rederiveRegionMs` bails on an empty clip list (a guard against
// a transient wipe deleting everything), which is why the empty case is handled
// here rather than left to it.
if (arr.length === 0) {
const emptied = mapAllRegionCollections(
{ ...next, timeline: { ...next.timeline, clips: [] } },
(regions) =>
regions.filter((region) => !(hasCompleteClipAnchor(region) && region.clipId === clipId)),
);
return dropUnusedGeneratedMedia(emptied);
}
return dropUnusedGeneratedMedia(withClipsChanged(next, arr));
}
export function restoreFullTimeline(document: AxcutDocument): AxcutDocument {
const duration = primaryAssetDuration(document);
if (duration <= 0) return document;
// ponytail: the ONE caller whose semantics are "put it all back": a single
// clip covering the whole asset and not a single cut left. `replaceTimeline`
// preserves ids and trims by default now, which would quietly turn "restore"
// into "keep everything you already had" — the opposite of the button.
return replaceTimeline(
document,
[{ startSec: 0, endSec: duration }],
"Restore full timeline",
"user",
{
preserveIds: false,
preserveTrims: false,
},
);
}