@nodetool-ai/video-nodes 0.8.1

package/dist/nodes/timeline.js

@@ -0,0 +1,1395 @@
+/**
+ * Timeline nodes — operate on persisted timeline sequences (the video
+ * editor's documents) referenced by the `timeline` type.
+ *
+ * RenderTimeline composites the sequence frame by frame through the same GPU
+ * compositor and scene model the editor's preview and its in-browser export
+ * use (`@nodetool-ai/timeline/render`), so a workflow render is the picture
+ * the user previewed: clip placement, transforms, opacity, blend modes,
+ * transitions, animations, effects, captions, text and shapes, across every
+ * visual track. ffmpeg decodes clip media into RGBA and encodes the result.
+ *
+ * Compositing needs a WebGPU device, which means the optional `webgpu` (Dawn)
+ * package and a working driver. Both profiles ship Dawn (D9,
+ * docs/plans/motion-graphics.md), and the Docker image installs lavapipe as its
+ * Vulkan driver, so a server render is composited too. A host that still has no
+ * adapter falls back to the older ffmpeg rough cut — video/image clips
+ * normalized and concatenated in start order — which ignores everything above.
+ * The fallback is a `warning` on the job and `metadata.render_mode` on the
+ * output says which path ran: "composited" or "rough_cut".
+ *
+ * `format` picks the container and `alpha` decides whether the frames keep a
+ * transparency channel: `webm` (VP9, `yuva420p`), `mov` (ProRes 4444,
+ * `yuva444p10le`) and `png_sequence` (a zip of PNGs plus a `manifest.json`)
+ * carry it, `mp4` does not and refuses the pair. The table is
+ * `timeline/outputFormats.ts`.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseNode, prop } from "@nodetool-ai/node-sdk";
+import { loadMediaRefBytes } from "@nodetool-ai/runtime";
+import { createTimeOrderedUuid, DEFAULT_MIDI_INSTRUMENT, encodeWavPcm16, ffmpegFadeCurve, fillTimelineText, resolveClipFades, retargetSequence, hasTimeRemap, sourceRate, makeClip, makeSequence, makeTrack, renderMidiClip, resolveTempo, timeRemapAudioSegments } from "@nodetool-ai/timeline";
+import { tagAsNode, tagAsServer } from "@nodetool-ai/nodes-utils";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { AssetFiles } from "./timeline/assetFiles.js";
+import { execFfmpeg, execFfprobe, ffprobeDuration, FFMPEG_MAX_BUFFER, MissingBinaryError } from "./ffmpeg-helpers.js";
+import { CompositorUnavailableError, renderTimelineComposited } from "./timeline/compositeRender.js";
+import { ALPHA_OUTPUT_FORMATS, MissingEncoderError, resolveTimelineOutput, TIMELINE_OUTPUT_FORMATS } from "./timeline/outputFormats.js";
+import { ffmpegHasEncoder } from "./timeline/rawFrames.js";
+import { stringValues } from "./placeholder-values.js";
+import { DEFAULT_SHUTTER_ANGLE, MAX_MOTION_BLUR_SAMPLES } from "@nodetool-ai/timeline/render";
+import { isNonEmptyString, isNumber, isPositiveNumber, isString } from "@nodetool-ai/node-sdk";
+async function loadTimelineSequence(ref, context) {
+    const timelineRef = (ref ?? {});
+    if (!timelineRef.id) {
+        throw new Error("Timeline input is empty — connect a Constant Timeline node and pick a timeline");
+    }
+    if (!context) {
+        throw new Error("Timeline nodes require a processing context");
+    }
+    const seq = (await context.getTimelineSequence(timelineRef.id));
+    if (!seq) {
+        throw new Error(`Timeline sequence not found: ${timelineRef.id}`);
+    }
+    return seq;
+}
+async function ffprobeHasAudio(filePath) {
+    try {
+        const { stdout } = await execFfprobe([
+            "-v",
+            "error",
+            "-select_streams",
+            "a",
+            "-show_entries",
+            "stream=codec_type",
+            "-of",
+            "default=noprint_wrappers=1:nokey=1",
+            filePath
+        ]);
+        return stdout.trim().length > 0;
+    }
+    catch (error) {
+        if (error instanceof MissingBinaryError)
+            throw error;
+        return false;
+    }
+}
+function trackById(tracks) {
+    return new Map(tracks.map((t) => [t.id, t]));
+}
+/** Clips that take part in the rough cut, in render order. */
+function renderableVideoClips(seq) {
+    const tracks = trackById(seq.tracks);
+    return seq.clips
+        .filter((clip) => {
+        const track = tracks.get(clip.trackId);
+        return (track?.type === "video" &&
+            track.visible !== false &&
+            !clip.hidden &&
+            (clip.mediaType === "video" || clip.mediaType === "image") &&
+            !!clip.currentAssetId &&
+            clip.durationMs > 0);
+    })
+        .sort((a, b) => a.startMs - b.startMs);
+}
+/**
+ * Clips the mix draws from: audio-track clips backed by an asset, and midi
+ * clips, whose sound is rendered from the notes they carry rather than fetched
+ * (they have no `currentAssetId` at all).
+ */
+function mixableAudioClips(seq) {
+    const tracks = trackById(seq.tracks);
+    return seq.clips
+        .filter((clip) => {
+        const track = tracks.get(clip.trackId);
+        if (!track || track.muted === true || clip.muted || clip.hidden) {
+            return false;
+        }
+        if (clip.durationMs <= 0)
+            return false;
+        if (track.type === "midi") {
+            return clip.mediaType === "midi" && (clip.notes?.length ?? 0) > 0;
+        }
+        return (track.type === "audio" &&
+            clip.mediaType === "audio" &&
+            !!clip.currentAssetId);
+    })
+        .sort((a, b) => a.startMs - b.startMs);
+}
+/**
+ * linkIds of audio-track clips that are the detached audio representation of a
+ * video clip. The mere presence of such a clip means the linked video's own
+ * muxed audio must be suppressed (the editor mutes the video element; audio
+ * comes only from audio-track clips). This is intentionally NOT gated on
+ * mute/hidden — those govern whether the audio clip is mixed in, not whether
+ * the video's embedded audio resurfaces. If the user deletes the audio clip,
+ * the store auto-unlinks the lone survivor, clearing the video's linkId, so the
+ * video's audio returns on its own.
+ */
+export function extractedAudioLinkIds(seq) {
+    const tracks = trackById(seq.tracks);
+    const ids = new Set();
+    for (const clip of seq.clips) {
+        const track = tracks.get(clip.trackId);
+        if (track?.type === "audio" &&
+            clip.mediaType === "audio" &&
+            isNonEmptyString(clip.linkId)) {
+            ids.add(clip.linkId);
+        }
+    }
+    return ids;
+}
+/** Scale + letterbox to the sequence frame, normalize fps and pixel format. */
+function segmentVideoFilter(width, height, fps) {
+    return (`scale=${width}:${height}:force_original_aspect_ratio=decrease,` +
+        `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=black,` +
+        `fps=${fps},format=yuv420p`);
+}
+/**
+ * Encode one clip into a uniform segment (same codec, resolution, fps,
+ * stereo AAC audio) so segments can be concatenated losslessly.
+ */
+async function encodeSegment(opts) {
+    const { clip, srcPath, segPath, width, height, fps, suppressEmbeddedAudio } = opts;
+    const durationS = clip.durationMs / 1000;
+    const filter = segmentVideoFilter(width, height, fps);
+    const silentAudio = [
+        "-f",
+        "lavfi",
+        "-t",
+        String(durationS),
+        "-i",
+        "anullsrc=channel_layout=stereo:sample_rate=48000"
+    ];
+    if (clip.mediaType === "image") {
+        await execFfmpeg([
+            "-y",
+            "-loop",
+            "1",
+            "-t",
+            String(durationS),
+            "-i",
+            srcPath,
+            ...silentAudio,
+            "-filter_complex",
+            `[0:v]${filter}[v]`,
+            "-map",
+            "[v]",
+            "-map",
+            "1:a",
+            "-c:v",
+            "libx264",
+            "-preset",
+            "veryfast",
+            "-c:a",
+            "aac",
+            "-shortest",
+            segPath
+        ], { maxBuffer: FFMPEG_MAX_BUFFER });
+        return;
+    }
+    const hasAudio = suppressEmbeddedAudio
+        ? false
+        : await ffprobeHasAudio(srcPath);
+    const seek = [];
+    if (isPositiveNumber(clip.inPointMs)) {
+        seek.push("-ss", String(clip.inPointMs / 1000));
+    }
+    if (isPositiveNumber(clip.outPointMs)) {
+        seek.push("-to", String(clip.outPointMs / 1000));
+    }
+    await execFfmpeg([
+        "-y",
+        ...seek,
+        "-i",
+        srcPath,
+        ...(hasAudio ? [] : silentAudio),
+        "-filter_complex",
+        `[0:v]${filter}[v]`,
+        "-map",
+        "[v]",
+        "-map",
+        hasAudio ? "0:a" : "1:a",
+        "-t",
+        String(durationS),
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-c:a",
+        "aac",
+        "-ar",
+        "48000",
+        "-ac",
+        "2",
+        segPath
+    ], { maxBuffer: FFMPEG_MAX_BUFFER });
+}
+/**
+ * Clips whose embedded audio the composited path must mix in itself: the
+ * rough cut carried a video clip's audio through its segment, but a
+ * frame-by-frame composite has no audio at all. Muted clips/tracks and clips
+ * whose audio was extracted onto an audio track (see
+ * {@link extractedAudioLinkIds}) are left out.
+ */
+function embeddedAudioClips(seq) {
+    const tracks = trackById(seq.tracks);
+    const suppressed = extractedAudioLinkIds(seq);
+    return seq.clips
+        .filter((clip) => {
+        const track = tracks.get(clip.trackId);
+        return ((track?.type === "video" || track?.type === "overlay") &&
+            track.muted !== true &&
+            !clip.muted &&
+            clip.mediaType === "video" &&
+            !!clip.currentAssetId &&
+            clip.durationMs > 0 &&
+            !(isString(clip.linkId) && suppressed.has(clip.linkId)));
+    })
+        .sort((a, b) => a.startMs - b.startMs);
+}
+/** Seconds, at millisecond resolution, for an ffmpeg filter argument. */
+function ffSeconds(ms) {
+    return (Math.max(0, ms) / 1000).toFixed(3);
+}
+/**
+ * `afade` steps for a clip's fades over a stream in which the clip begins at
+ * `clipStartInStreamMs`. Both edges read the curve the document authored, the
+ * same one the editor draws and the preview sounds: every `ClipFadeShape` maps
+ * to the `afade` curve with that gain function.
+ *
+ * Lengths come from `resolveClipFades`, so two fades longer together than the
+ * clip meet in its middle here exactly as they do on screen.
+ */
+function clipFadeSteps(clip, clipStartInStreamMs) {
+    const fades = resolveClipFades(clip, clip.durationMs);
+    const steps = [];
+    if (fades.fadeInMs > 0) {
+        steps.push(`afade=t=in:st=${ffSeconds(clipStartInStreamMs)}:d=${ffSeconds(fades.fadeInMs)}:curve=${ffmpegFadeCurve(fades.fadeInShape)}`);
+    }
+    if (fades.fadeOutMs > 0) {
+        const startMs = clipStartInStreamMs + clip.durationMs - fades.fadeOutMs;
+        steps.push(`afade=t=out:st=${ffSeconds(startMs)}:d=${ffSeconds(fades.fadeOutMs)}:curve=${ffmpegFadeCurve(fades.fadeOutShape)}`);
+    }
+    return steps;
+}
+/** Whether either edge of the clip carries a fade worth rendering. */
+function hasClipFade(clip) {
+    const fades = resolveClipFades(clip, clip.durationMs);
+    return fades.fadeInMs > 0 || fades.fadeOutMs > 0;
+}
+/**
+ * Per-clip audio chain: trim to in/out, apply gain, fade both edges, delay to
+ * timeline start. The fades precede the delay, so their times are measured
+ * from the clip's own start.
+ */
+function audioClipFilter(clip, inputIndex, label) {
+    const steps = [];
+    // A midi clip's WAV *is* its window: `renderMidiClip` already dropped
+    // everything before `inPointMs` and stopped at `durationMs`. Trimming by the
+    // source in/out again would cut the same window twice and lose the head of
+    // every trimmed clip.
+    const isMidi = clip.mediaType === "midi";
+    const inS = !isMidi && isNumber(clip.inPointMs) ? clip.inPointMs / 1000 : 0;
+    const outS = !isMidi && isPositiveNumber(clip.outPointMs)
+        ? clip.outPointMs / 1000
+        : inS + clip.durationMs / 1000;
+    steps.push(`atrim=start=${inS}:end=${outS}`, "asetpts=PTS-STARTPTS");
+    if (isNumber(clip.volumeDb) && clip.volumeDb !== 0) {
+        steps.push(`volume=${clip.volumeDb}dB`);
+    }
+    steps.push(...clipFadeSteps(clip, 0));
+    const delay = Math.max(0, Math.round(clip.startMs));
+    steps.push(`adelay=${delay}|${delay}`);
+    return `[${inputIndex}:a]${steps.join(",")}[${label}]`;
+}
+/** `rate` as atempo factors, each inside the filter's own 0.5–2 range. */
+function atempoChain(rate) {
+    const factors = [];
+    let remaining = rate;
+    while (remaining > 2) {
+        factors.push("2");
+        remaining /= 2;
+    }
+    while (remaining < 0.5) {
+        factors.push("0.5");
+        remaining *= 2;
+    }
+    factors.push(String(Number(remaining.toFixed(6))));
+    return factors;
+}
+/**
+ * One constant-rate stretch of a time-remapped clip: trim the source span the
+ * curve names, retime it to the stretch's timeline length, apply the clip's
+ * gain, and delay it to where the stretch starts.
+ *
+ * `atempo` retimes without moving the pitch and needs no knowledge of the
+ * input's sample rate, which `asetrate` would. The browser preview has no
+ * time-stretch to reach for — WebAudio offers only `playbackRate` — so a steep
+ * ramp is pitched there and is not here.
+ */
+function audioRemapSegmentFilter(clip, segment, inputIndex, label) {
+    const steps = [
+        `atrim=start=${segment.sourceStartMs / 1000}:end=${segment.sourceEndMs / 1000}`,
+        "asetpts=PTS-STARTPTS",
+        ...atempoChain(segment.rate).map((f) => `atempo=${f}`)
+    ];
+    if (isNumber(clip.volumeDb) && clip.volumeDb !== 0) {
+        steps.push(`volume=${clip.volumeDb}dB`);
+    }
+    const delay = Math.max(0, Math.round(segment.timelineStartMs));
+    steps.push(`adelay=${delay}|${delay}`);
+    return `[${inputIndex}:a]${steps.join(",")}[${label}]`;
+}
+/** Anything that draws: media, titles, shapes, or a caption riding a clip. */
+function hasRenderableVisual(seq) {
+    const tracks = trackById(seq.tracks);
+    return seq.clips.some((clip) => {
+        const track = tracks.get(clip.trackId);
+        if (!track || track.visible === false || clip.hidden)
+            return false;
+        if (clip.caption)
+            return true;
+        if (track.type !== "video" && track.type !== "overlay")
+            return false;
+        if (clip.mediaType === "text")
+            return !!clip.textStyle;
+        if (clip.mediaType === "shape")
+            return !!clip.shapeStyle;
+        return ((clip.mediaType === "video" || clip.mediaType === "image") &&
+            !!clip.currentAssetId);
+    });
+}
+/** The sequence's own length, or the end of its last clip when it has none. */
+function totalDurationMs(seq) {
+    if (seq.durationMs > 0)
+        return seq.durationMs;
+    return seq.clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0);
+}
+/**
+ * The file ffmpeg reads for each clip asset, resolved once per asset: the
+ * asset's own local file when it has one, else a copy in the work dir.
+ */
+/** Sample rate the midi renderer runs at, matching the mix's own `-ar`. */
+const MIDI_SAMPLE_RATE = 48000;
+/**
+ * Renders each midi clip's notes to a WAV on disk once, for ffmpeg to read.
+ *
+ * The buffer `renderMidiClip` returns is exactly the clip's window — it starts
+ * at the clip's timeline start and is `durationMs` long — so the file needs no
+ * source-side trim, only the `adelay` that puts it at its offset.
+ */
+class MidiFiles {
+    workDir;
+    files = new Map();
+    tracks;
+    bpm;
+    constructor(workDir, seq) {
+        this.workDir = workDir;
+        this.tracks = trackById(seq.tracks);
+        this.bpm = resolveTempo(seq).bpm;
+    }
+    path(clip) {
+        let pending = this.files.get(clip.id);
+        if (!pending) {
+            pending = this.write(clip);
+            this.files.set(clip.id, pending);
+        }
+        return pending;
+    }
+    async write(clip) {
+        // The instrument belongs to the track, not the clip.
+        const instrument = this.tracks.get(clip.trackId)?.instrument ?? DEFAULT_MIDI_INSTRUMENT;
+        const mono = renderMidiClip({
+            clip,
+            bpm: this.bpm,
+            instrument,
+            sampleRate: MIDI_SAMPLE_RATE
+        });
+        const file = path.join(this.workDir, `midi_${clip.id}.wav`);
+        await fs.writeFile(file, encodeWavPcm16(mono, MIDI_SAMPLE_RATE));
+        return file;
+    }
+}
+/**
+ * The file ffmpeg reads one audible clip from: the materialized asset, or the
+ * WAV rendered from a midi clip's notes.
+ */
+function audioSourcePath(clip, assets, midi) {
+    if (clip.mediaType === "midi")
+        return midi.path(clip);
+    return clip.currentAssetId
+        ? assets.path(clip.currentAssetId)
+        : Promise.resolve(null);
+}
+/**
+ * The pre-compositor rough cut, kept as the fallback for hosts without a GPU:
+ * each video/image clip is normalized to the sequence frame and the segments
+ * are concatenated in start order. Gaps, overlaps, transforms and every other
+ * layer property are lost — it is a cut, not a render.
+ */
+async function renderRoughCut(opts) {
+    const { seq, clips, audioClips, assets, workDir, width, height, fps } = opts;
+    const suppressedLinkIds = extractedAudioLinkIds(seq);
+    const segments = [];
+    for (const [i, clip] of clips.entries()) {
+        const srcPath = clip.currentAssetId
+            ? await assets.path(clip.currentAssetId)
+            : null;
+        if (!srcPath) {
+            console.warn(`RenderTimeline: skipping clip "${clip.name}" — asset ${clip.currentAssetId} not found`);
+            continue;
+        }
+        const segPath = path.join(workDir, `seg_${i}.mp4`);
+        await encodeSegment({
+            clip,
+            srcPath,
+            segPath,
+            width,
+            height,
+            fps,
+            suppressEmbeddedAudio: isString(clip.linkId) && suppressedLinkIds.has(clip.linkId)
+        });
+        segments.push(segPath);
+    }
+    const basePath = path.join(workDir, "base.mp4");
+    if (segments.length > 0) {
+        const listPath = path.join(workDir, "segments.txt");
+        await fs.writeFile(listPath, segments.map((p) => `file '${p}'`).join("\n"));
+        await execFfmpeg(["-y", "-f", "concat", "-safe", "0", "-i", listPath, "-c", "copy", basePath], { maxBuffer: FFMPEG_MAX_BUFFER });
+        return basePath;
+    }
+    // Audio-only cut: synthesize a black picture to carry the mix.
+    //
+    // `Math.max()` with no arguments is -Infinity, and spreading an empty array
+    // is exactly that call. A timeline holding neither video nor audio reached
+    // ffmpeg as `-t -Infinity` and died on "Invalid duration for option t",
+    // naming neither the timeline nor the absent clips. `totalDurationMs` above
+    // seeds a `reduce` for the same computation and is unaffected — one file,
+    // two idioms, one of them wrong. Nothing renders from an empty timeline, so
+    // say so here rather than build a command that cannot parse.
+    if (audioClips.length === 0) {
+        throw new Error("Timeline has no clips to render. Add at least one video, image or " +
+            "audio clip before rendering.");
+    }
+    const totalS = audioClips.reduce((end, c) => Math.max(end, c.startMs + c.durationMs), 0) /
+        1000;
+    await execFfmpeg([
+        "-y",
+        "-f",
+        "lavfi",
+        "-t",
+        String(totalS),
+        "-i",
+        `color=black:s=${width}x${height}:r=${fps}`,
+        "-f",
+        "lavfi",
+        "-t",
+        String(totalS),
+        "-i",
+        "anullsrc=channel_layout=stereo:sample_rate=48000",
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-c:a",
+        "aac",
+        basePath
+    ], { maxBuffer: FFMPEG_MAX_BUFFER });
+    return basePath;
+}
+/**
+ * Mix `clips` into `basePath` at their timeline offsets. `baseHasAudio` says
+ * whether the base video carries a soundtrack of its own to keep (the rough
+ * cut does; a composited render does not).
+ *
+ * The mux copies the video stream, so the container has to be the one the base
+ * was encoded into and the audio codec has to be legal inside it — AAC is not a
+ * WebM track, which is why `audioCodec` is passed rather than assumed.
+ */
+async function mixAudioInto(opts) {
+    const { basePath, clips, baseHasAudio, assets, midi, workDir, extension, audioCodec } = opts;
+    const inputs = ["-i", basePath];
+    const filters = [];
+    const labels = [];
+    let inputIndex = 1;
+    for (const [i, clip] of clips.entries()) {
+        const audioPath = await audioSourcePath(clip, assets, midi);
+        if (!audioPath) {
+            console.warn(`RenderTimeline: skipping audio of clip "${clip.name}" — asset ${clip.currentAssetId} not found`);
+            continue;
+        }
+        if (!baseHasAudio && !(await ffprobeHasAudio(audioPath)))
+            continue;
+        // Only a clip that plays at source rate can use the plain chain: a
+        // speedMultiplier is a rate too, and without atempo (and the wider source
+        // window it needs) a 2x clip's audio ran on past the clip.
+        if (!hasTimeRemap(clip) && sourceRate(clip) === 1) {
+            inputs.push("-i", audioPath);
+            const label = `a${i}`;
+            filters.push(audioClipFilter(clip, inputIndex, label));
+            labels.push(`[${label}]`);
+            inputIndex += 1;
+            continue;
+        }
+        // A remapped clip is not one span at one rate: the curve becomes
+        // constant-rate stretches and each is decoded, retimed and delayed on its
+        // own. A stretch the curve runs backwards over — or holds still on — is
+        // silent, as it is in the preview.
+        const segmentLabels = [];
+        for (const [j, segment] of timeRemapAudioSegments(clip).entries()) {
+            if (segment.reverse || !Number.isFinite(segment.rate))
+                continue;
+            inputs.push("-i", audioPath);
+            const label = `a${i}_${j}`;
+            filters.push(audioRemapSegmentFilter(clip, segment, inputIndex, label));
+            segmentLabels.push(`[${label}]`);
+            inputIndex += 1;
+        }
+        // A fade spans the clip, not one stretch of it, and a stretch that covers
+        // only part of the ramp cannot carry it — `afade` always runs a full 0→1.
+        // So a faded remapped clip is mixed back into one stream first, at its
+        // timeline offsets, and faded there. `normalize=0` keeps the level: the
+        // stretches abut rather than overlap, so nothing is summed.
+        if (segmentLabels.length > 0 && hasClipFade(clip)) {
+            const faded = `a${i}_fade`;
+            const steps = segmentLabels.length > 1
+                ? [
+                    `amix=inputs=${segmentLabels.length}:duration=longest:normalize=0`,
+                    ...clipFadeSteps(clip, clip.startMs)
+                ]
+                : clipFadeSteps(clip, clip.startMs);
+            filters.push(`${segmentLabels.join("")}${steps.join(",")}[${faded}]`);
+            labels.push(`[${faded}]`);
+            continue;
+        }
+        labels.push(...segmentLabels);
+    }
+    if (labels.length === 0)
+        return basePath;
+    const sources = baseHasAudio ? [`[0:a]`, ...labels] : labels;
+    const mix = sources.length === 1
+        ? `${sources[0]}apad[aout]`
+        : `${sources.join("")}amix=inputs=${sources.length}:duration=longest:normalize=0,apad[aout]`;
+    const outPath = path.join(workDir, `mixed.${extension}`);
+    await execFfmpeg([
+        "-y",
+        ...inputs,
+        "-filter_complex",
+        [...filters, mix].join(";"),
+        "-map",
+        "0:v",
+        "-map",
+        "[aout]",
+        "-c:v",
+        "copy",
+        "-c:a",
+        audioCodec,
+        "-ar",
+        "48000",
+        "-ac",
+        "2",
+        // `apad` runs the mix past the picture; stop at the shorter stream so the
+        // render is exactly as long as the video.
+        "-shortest",
+        outPath
+    ], { maxBuffer: FFMPEG_MAX_BUFFER });
+    return outPath;
+}
+/** Add the sequence's audible tracks and embedded video audio to a composited video. */
+export async function mixCompositedTimelineAudio(opts) {
+    const { sequence, basePath, workDir, output, resolveAssetPath } = opts;
+    if (output.format === "png_sequence")
+        return basePath;
+    const clips = [...embeddedAudioClips(sequence), ...mixableAudioClips(sequence)];
+    if (clips.length === 0)
+        return basePath;
+    return mixAudioInto({
+        basePath,
+        clips,
+        baseHasAudio: false,
+        assets: { path: resolveAssetPath },
+        midi: new MidiFiles(workDir, sequence),
+        workDir,
+        extension: output.extension,
+        audioCodec: output.audioCodec ?? "aac"
+    });
+}
+/** Shortest gap between two `node_progress` posts — four a second. */
+const PROGRESS_INTERVAL_MS = 250;
+/** Smallest draft render. Below this a frame says nothing about the cut. */
+const MIN_PREVIEW_SCALE = 0.1;
+/**
+ * The fraction of the sequence size this render runs at.
+ *
+ * Unset, non-finite, and anything at or above 1 mean full size; anything
+ * smaller is clamped up to {@link MIN_PREVIEW_SCALE} rather than refused, so a
+ * draft is never rendered at a size nobody could read.
+ */
+function previewScaleOf(value) {
+    const scale = Number(value);
+    if (!Number.isFinite(scale) || scale >= 1)
+        return 1;
+    return Math.max(MIN_PREVIEW_SCALE, scale);
+}
+/** A scaled edge, rounded to an even number — h.264 encodes nothing else. */
+function evenScaled(edge, scale) {
+    if (scale >= 1)
+        return edge;
+    return Math.max(2, Math.round((edge * scale) / 2) * 2);
+}
+/** An unset ref on the handle this render did not fill. */
+function emptyVideoRef() {
+    return { type: "video", uri: "", data: null, asset_id: null };
+}
+function emptyFramesRef() {
+    return { type: "document", uri: "", asset_id: null, data: null };
+}
+/**
+ * Store a finished render in the host's asset store and describe it by id.
+ *
+ * A minute of 1080p is tens of megabytes; base64 of that sits at V8's string
+ * cap, so encoding the artifact into the ref fails after the whole render has
+ * already been paid for. With an asset store the bytes go there and the ref
+ * carries `asset_id` plus an `asset://` uri and no inline `data`. A host
+ * without one (the CLI, a unit test) keeps the inline encoding, which is the
+ * only way those callers see the result at all.
+ */
+async function storeRenderArtifact(args) {
+    const bytes = await fs.readFile(args.filePath);
+    if (typeof args.context.createAsset !== "function") {
+        return { asset_id: null, uri: "", data: bytes.toString("base64") };
+    }
+    const created = (await args.context.createAsset({
+        name: args.name,
+        contentType: args.contentType,
+        content: new Uint8Array(bytes)
+    }));
+    const assetId = created && typeof created.id === "string" && created.id.length > 0
+        ? created.id
+        : null;
+    if (!assetId) {
+        return { asset_id: null, uri: "", data: bytes.toString("base64") };
+    }
+    return { asset_id: assetId, uri: `asset://${assetId}`, data: null };
+}
+export class RenderTimelineNode extends BaseNode {
+    static nodeType = "nodetool.timeline.RenderTimeline";
+    static title = "Render Timeline";
+    static description = "Render a timeline sequence to a video, composited exactly as the timeline editor previews it (tracks, transforms, transitions, effects, captions and text), with audio mixed in at each clip's offset. Writes MP4, WebM, MOV or a zipped PNG sequence, with an optional transparent background.\n    timeline, render, video, export, cut, alpha\n\n    Use cases:\n    - Turn an edit assembled in the timeline editor into a shareable video\n    - Export a title or lower third over transparency to composite elsewhere\n    - Feed a rough cut into captioning, review, or upload nodes\n    - Automate exports of timelines built by other workflow nodes";
+    static requiredRuntimes = ["ffmpeg"];
+    static metadataOutputTypes = {
+        output: "video",
+        frames: "document"
+    };
+    static inlineFields = ["timeline"];
+    static inputFields = ["timeline"];
+    async process(context) {
+        const seq = await loadTimelineSequence(this.timeline, context);
+        const ctx = context;
+        const scale = previewScaleOf(this.preview_scale);
+        const width = evenScaled(seq.width > 0 ? seq.width : 1920, scale);
+        const height = evenScaled(seq.height > 0 ? seq.height : 1080, scale);
+        const fps = seq.fps > 0 ? seq.fps : 30;
+        const includeAudio = this.include_audio !== false;
+        const audioClips = includeAudio ? mixableAudioClips(seq) : [];
+        if (!hasRenderableVisual(seq) && audioClips.length === 0) {
+            throw new Error(`Timeline "${seq.name}" has no renderable clips with media — generate or import clip media first`);
+        }
+        const durationMs = totalDurationMs(seq);
+        if (durationMs <= 0) {
+            throw new Error(`Timeline "${seq.name}" has zero duration`);
+        }
+        // Resolved before anything is decoded: an impossible format/alpha pair, or
+        // an ffmpeg with no encoder for it, must fail in a second rather than after
+        // a thousand composited frames.
+        const output = resolveTimelineOutput({
+            format: this.format,
+            alpha: this.alpha === true,
+            videoCodec: this.video_codec,
+            bitrate: this.bitrate,
+            motionBlurSamples: this.motion_blur_samples,
+            shutterAngle: this.shutter_angle
+        });
+        await this.assertEncoderAvailable(output);
+        const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "nodetool-timeline-"));
+        try {
+            const assets = new AssetFiles(workDir, ctx);
+            const midi = new MidiFiles(workDir, seq);
+            let basePath;
+            let baseHasAudio;
+            let audioToMix;
+            let renderMode;
+            try {
+                basePath = path.join(workDir, `composited.${output.extension}`);
+                const { skippedClips } = await renderTimelineComposited({
+                    sequence: seq,
+                    width,
+                    height,
+                    fps,
+                    durationMs,
+                    resolveAssetPath: (assetId) => assets.path(assetId),
+                    outPath: basePath,
+                    output,
+                    onProgress: this.progressReporter(ctx),
+                    signal: ctx.signal
+                });
+                for (const name of skippedClips) {
+                    this.log(ctx, `Clip "${name}" was skipped — its media could not be decoded`, "warning");
+                }
+                renderMode = "composited";
+                // A composite carries no sound: every audible clip is mixed in below,
+                // including the audio muxed into video clips.
+                baseHasAudio = false;
+                audioToMix = includeAudio
+                    ? [...embeddedAudioClips(seq), ...audioClips]
+                    : [];
+            }
+            catch (error) {
+                if (!(error instanceof CompositorUnavailableError))
+                    throw error;
+                // The rough cut is H.264 in MP4 over opaque black — it concatenates
+                // normalized segments and never touches the compositor. Handing that
+                // back for an alpha or non-MP4 request would answer a different
+                // question than the one asked, so the request fails instead.
+                if (output.format !== "mp4" || output.alpha) {
+                    throw new Error(`${error.message} The "${output.format}" format` +
+                        `${output.alpha ? " with transparency" : ""} needs the ` +
+                        "compositor; the rough-cut fallback only writes opaque MP4.");
+                }
+                this.log(ctx, `${error.message} Falling back to a rough cut — clip transforms, ` +
+                    "effects, transitions, captions and overlay tracks are not applied.", "warning");
+                basePath = await renderRoughCut({
+                    seq,
+                    clips: renderableVideoClips(seq),
+                    audioClips,
+                    assets,
+                    workDir,
+                    width,
+                    height,
+                    fps
+                });
+                renderMode = "rough_cut";
+                baseHasAudio = true;
+                audioToMix = audioClips;
+            }
+            // A PNG sequence is a zip of stills: there is no stream to mux a
+            // soundtrack onto, so the audio clips are reported rather than dropped
+            // silently.
+            if (output.format === "png_sequence") {
+                if (audioToMix.length > 0) {
+                    this.log(ctx, "A PNG sequence carries no audio; the timeline's audio clips were not mixed in.", "warning");
+                }
+                const stored = await storeRenderArtifact({
+                    context: ctx,
+                    filePath: basePath,
+                    name: `${seq.name || "timeline"}-frames.zip`,
+                    contentType: output.mimeType
+                });
+                return {
+                    output: emptyVideoRef(),
+                    frames: {
+                        type: "document",
+                        uri: stored.uri,
+                        asset_id: stored.asset_id,
+                        data: stored.data,
+                        metadata: {
+                            render_mode: renderMode,
+                            format: output.format,
+                            alpha: output.alpha,
+                            content_type: output.mimeType
+                        }
+                    }
+                };
+            }
+            const outPath = audioToMix.length > 0
+                ? await mixAudioInto({
+                    basePath,
+                    clips: audioToMix,
+                    baseHasAudio,
+                    assets,
+                    midi,
+                    workDir,
+                    extension: output.extension,
+                    audioCodec: output.audioCodec ?? "aac"
+                })
+                : basePath;
+            const duration = await ffprobeDuration(outPath);
+            const stored = await storeRenderArtifact({
+                context: ctx,
+                filePath: outPath,
+                name: `${seq.name || "timeline"}.${output.extension}`,
+                contentType: output.mimeType
+            });
+            return {
+                output: {
+                    type: "video",
+                    asset_id: stored.asset_id,
+                    uri: stored.uri,
+                    data: stored.data,
+                    format: output.extension,
+                    duration: duration > 0 ? duration : null,
+                    // Which of the two paths produced these bytes. The docker smoke test
+                    // asserts "composited": it is what proves the image renders the
+                    // picture the editor previews rather than a concatenation.
+                    metadata: {
+                        render_mode: renderMode,
+                        format: output.format,
+                        alpha: output.alpha
+                    }
+                },
+                frames: emptyFramesRef()
+            };
+        }
+        finally {
+            await fs.rm(workDir, { recursive: true, force: true });
+        }
+    }
+    /**
+     * Refuse a format this ffmpeg cannot encode, by name.
+     *
+     * ProRes and VP9 are both optional at ffmpeg build time. Without this the
+     * render composites every frame first and then dies on ffmpeg's own
+     * "Unknown encoder" line, which says nothing about what to pick instead.
+     */
+    async assertEncoderAvailable(output) {
+        const encoder = output.requiredEncoder;
+        // MP4/H.264 is the path every existing render already took, and probing it
+        // would turn "ffmpeg is not installed" into a message about an encoder.
+        if (!encoder || output.format === "mp4")
+            return;
+        if (await ffmpegHasEncoder(encoder))
+            return;
+        throw new MissingEncoderError(encoder, output.format);
+    }
+    /** Post on the node's log channel, where the run has one. */
+    log(context, content, severity) {
+        if (!this.__node_id)
+            return;
+        context.postMessage({
+            type: "log_update",
+            node_id: this.__node_id,
+            node_name: RenderTimelineNode.title,
+            content,
+            severity,
+            workflow_id: context.workflowId
+        });
+    }
+    /**
+     * A `node_progress` reporter for the frame loop, rate-limited to four posts a
+     * second. A minute of 1080p is thousands of frames and every post crosses the
+     * websocket; the final frame always posts, so the bar reaches its end.
+     */
+    progressReporter(context) {
+        const nodeId = this.__node_id;
+        let lastPostMs = 0;
+        return (frame, totalFrames) => {
+            if (!nodeId)
+                return;
+            const now = Date.now();
+            if (frame < totalFrames && now - lastPostMs < PROGRESS_INTERVAL_MS) {
+                return;
+            }
+            lastPostMs = now;
+            context.postMessage({
+                type: "node_progress",
+                node_id: nodeId,
+                progress: frame,
+                total: totalFrames,
+                workflow_id: context.workflowId
+            });
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "timeline",
+        default: { type: "timeline", id: null, data: null },
+        title: "Timeline",
+        description: "The timeline sequence to render."
+    })
+], RenderTimelineNode.prototype, "timeline", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: true,
+        title: "Include audio",
+        description: "Mix audio-track clips into the rendered video."
+    })
+], RenderTimelineNode.prototype, "include_audio", void 0);
+__decorate([
+    prop({
+        type: "enum",
+        default: "mp4",
+        title: "Format",
+        description: "Output container. mp4 is H.264. webm is VP9, mov is ProRes, and png_sequence is a zip of PNGs with a manifest.json — those three carry alpha.",
+        values: [...TIMELINE_OUTPUT_FORMATS]
+    })
+], RenderTimelineNode.prototype, "format", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: false,
+        title: "Transparent background",
+        description: "Composite over a transparent ground and keep the alpha channel. Needs a format that carries alpha: " +
+            `${ALPHA_OUTPUT_FORMATS.join(", ")}.`
+    })
+], RenderTimelineNode.prototype, "alpha", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "",
+        title: "Video codec",
+        description: "Override the container's default video encoder (mp4 only — webm pins VP9 and mov pins ProRes, the codecs that carry their alpha). Empty uses the default."
+    })
+], RenderTimelineNode.prototype, "video_codec", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 1,
+        title: "Motion blur samples",
+        description: "Average this many sub-frame instants into every frame, so fast motion " +
+            "smears instead of strobing. 1 is off. Each extra sample costs another " +
+            "full render pass.",
+        min: 1,
+        max: MAX_MOTION_BLUR_SAMPLES
+    })
+], RenderTimelineNode.prototype, "motion_blur_samples", void 0);
+__decorate([
+    prop({
+        type: "float",
+        default: DEFAULT_SHUTTER_ANGLE,
+        title: "Shutter angle",
+        description: "How far the shutter opens, in degrees of one frame. 180 is the film " +
+            "convention (open for half the frame); 360 smears across the whole " +
+            "frame. Ignored unless motion blur samples is above 1.",
+        min: 0,
+        max: 360
+    })
+], RenderTimelineNode.prototype, "shutter_angle", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 0,
+        title: "Bitrate",
+        description: "Target video bitrate in bits per second. 0 leaves the rate to the encoder.",
+        min: 0
+    })
+], RenderTimelineNode.prototype, "bitrate", void 0);
+__decorate([
+    prop({
+        type: "float",
+        default: 1,
+        title: "Preview scale",
+        description: "Render at this fraction of the sequence size. 0.5 is a quarter of the pixels and roughly a quarter of the time — a draft to look at before spending on the full render. 1 is full size."
+    })
+], RenderTimelineNode.prototype, "preview_scale", void 0);
+export class TimelineTranscriptNode extends BaseNode {
+    static nodeType = "nodetool.timeline.Transcript";
+    static title = "Timeline Transcript";
+    static description = "Extract the transcript of a timeline sequence as text.\n    timeline, transcript, text, script, voiceover\n\n    Use cases:\n    - Summarize or rewrite an edit's narration with an LLM\n    - Generate titles, descriptions, or chapters from the spoken script\n    - Translate a voiceover script before re-recording with TTS";
+    static metadataOutputTypes = {
+        text: "str",
+        lines: "list[str]"
+    };
+    static inlineFields = ["timeline"];
+    static inputFields = ["timeline"];
+    async process(context) {
+        const seq = await loadTimelineSequence(this.timeline, context);
+        const lines = (seq.transcript ?? []).map((line) => line.text);
+        return { text: lines.join("\n"), lines };
+    }
+}
+__decorate([
+    prop({
+        type: "timeline",
+        default: { type: "timeline", id: null, data: null },
+        title: "Timeline",
+        description: "The timeline sequence to read the transcript from."
+    })
+], TimelineTranscriptNode.prototype, "timeline", void 0);
+/** Content types AddClips falls back to when the bytes say nothing. */
+const CLIP_CONTENT_TYPE_FALLBACK = {
+    image: "image/png",
+    audio: "audio/wav",
+    video: "video/mp4"
+};
+const CLIP_CONTENT_TYPE_BY_EXTENSION = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+    flac: "audio/x-flac",
+    m4a: "audio/x-m4a",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime"
+};
+const startsWithBytes = (bytes, ascii, at = 0) => {
+    if (bytes.length < at + ascii.length)
+        return false;
+    for (let i = 0; i < ascii.length; i++) {
+        if (bytes[at + i] !== ascii.charCodeAt(i))
+            return false;
+    }
+    return true;
+};
+/** The content type the bytes themselves declare, or null when unrecognized. */
+function sniffContentType(mediaType, bytes) {
+    if (startsWithBytes(bytes, "RIFF") && startsWithBytes(bytes, "WAVE", 8)) {
+        return "audio/wav";
+    }
+    if (startsWithBytes(bytes, "RIFF") && startsWithBytes(bytes, "WEBP", 8)) {
+        return "image/webp";
+    }
+    if (startsWithBytes(bytes, "ID3"))
+        return "audio/mpeg";
+    // MPEG audio frame sync: 11 set bits. Two bytes is weak evidence, so trust
+    // it only where the clip is already known to be audio.
+    if (mediaType === "audio" &&
+        bytes.length >= 2 &&
+        bytes[0] === 0xff &&
+        (bytes[1] & 0xe0) === 0xe0) {
+        return "audio/mpeg";
+    }
+    if (startsWithBytes(bytes, "OggS"))
+        return "audio/ogg";
+    if (startsWithBytes(bytes, "fLaC"))
+        return "audio/x-flac";
+    if (startsWithBytes(bytes, "\x89PNG"))
+        return "image/png";
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+        return "image/jpeg";
+    }
+    if (startsWithBytes(bytes, "GIF8"))
+        return "image/gif";
+    // Matroska/WebM EBML header.
+    if (bytes.length >= 4 &&
+        bytes[0] === 0x1a &&
+        bytes[1] === 0x45 &&
+        bytes[2] === 0xdf &&
+        bytes[3] === 0xa3) {
+        return "video/webm";
+    }
+    if (startsWithBytes(bytes, "ftyp", 4)) {
+        if (startsWithBytes(bytes, "qt", 8))
+            return "video/quicktime";
+        if (startsWithBytes(bytes, "M4A", 8))
+            return "audio/x-m4a";
+        return "video/mp4";
+    }
+    return null;
+}
+/**
+ * The content type to store a clip's bytes under.
+ *
+ * The stored asset's file extension and the `Content-Type` the browser is
+ * served both come from this, so guessing by media kind alone mislabels
+ * anything that is not the kind's default container: a WAV voiceover saved as
+ * `audio/mpeg` reaches the player as a `.mp3` it cannot decode. Read the bytes
+ * first, then the source URI's extension, and only then fall back to the kind.
+ */
+export function clipContentType(mediaType, bytes, uri) {
+    const sniffed = sniffContentType(mediaType, bytes);
+    if (sniffed)
+        return sniffed;
+    const extension = (uri ?? "").toLowerCase().split(/[?#]/)[0].split(".").pop();
+    const byExtension = extension
+        ? CLIP_CONTENT_TYPE_BY_EXTENSION[extension]
+        : undefined;
+    if (byExtension)
+        return byExtension;
+    return CLIP_CONTENT_TYPE_FALLBACK[mediaType] ?? "application/octet-stream";
+}
+export class AddClipsToTimelineNode extends BaseNode {
+    static nodeType = "nodetool.timeline.AddClips";
+    static title = "Add Clips To Timeline";
+    static description = "Append media to a timeline sequence as clips (videos and images on the video track, audio on the audio track). Creates a new timeline when none is given.\n    timeline, clips, append, assemble, storyboard\n\n    Use cases:\n    - Assemble generated shots into an editable rough cut\n    - Turn a storyboard's images into an animatic\n    - Add a generated voiceover or soundtrack under an edit";
+    static requiredRuntimes = ["ffmpeg"];
+    static metadataOutputTypes = {
+        output: "timeline"
+    };
+    static inlineFields = ["name"];
+    static inputFields = ["timeline", "clips"];
+    async process(context) {
+        if (!context) {
+            throw new Error("AddClipsToTimeline requires a processing context");
+        }
+        const items = (Array.isArray(this.clips) ? this.clips : [])
+            .filter((item) => !!item && typeof item === "object")
+            .filter((item) => ["image", "video", "audio"].includes(String(item.type)));
+        if (items.length === 0) {
+            throw new Error("AddClipsToTimeline: no image/video/audio clips given");
+        }
+        const timelineRef = (this.timeline ?? {});
+        const seq = timelineRef.id
+            ? await loadTimelineSequence(timelineRef, context)
+            : makeSequence({
+                name: String(this.name ?? "Untitled video"),
+                projectId: "default"
+            });
+        const ensureTrack = (type) => {
+            const existing = seq.tracks.find((t) => t.type === type);
+            if (existing)
+                return existing;
+            const track = makeTrack({
+                type,
+                name: type === "video" ? "Video" : "Audio",
+                index: seq.tracks.length
+            });
+            seq.tracks.push(track);
+            return track;
+        };
+        const trackEnd = (trackId) => seq.clips
+            .filter((c) => c.trackId === trackId)
+            .reduce((end, c) => Math.max(end, c.startMs + c.durationMs), 0);
+        const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "nodetool-timeline-add-"));
+        try {
+            const cursor = {};
+            for (const [i, item] of items.entries()) {
+                const mediaType = String(item.type);
+                const bytes = await loadMediaRefBytes(item, context);
+                let assetId = isNonEmptyString(item.asset_id)
+                    ? item.asset_id
+                    : null;
+                if (!assetId) {
+                    if (!bytes) {
+                        console.warn(`AddClipsToTimeline: skipping clip ${i} — media has no resolvable bytes`);
+                        continue;
+                    }
+                    const contentType = clipContentType(mediaType, bytes, isString(item.uri) ? item.uri : undefined);
+                    const created = (await context.createAsset({
+                        name: `clip-${i + 1}`,
+                        contentType,
+                        content: bytes
+                    }));
+                    assetId = created.id;
+                }
+                let durationMs = Number(this.image_duration_ms ?? 3000);
+                if (mediaType !== "image") {
+                    if (!bytes) {
+                        console.warn(`AddClipsToTimeline: skipping clip ${i} — cannot probe duration without media bytes`);
+                        continue;
+                    }
+                    const probePath = path.join(workDir, `probe_${i}`);
+                    await fs.writeFile(probePath, bytes);
+                    const seconds = await ffprobeDuration(probePath);
+                    if (seconds <= 0) {
+                        console.warn(`AddClipsToTimeline: skipping clip ${i} — could not determine duration`);
+                        continue;
+                    }
+                    durationMs = Math.round(seconds * 1000);
+                }
+                const track = ensureTrack(mediaType === "audio" ? "audio" : "video");
+                const startMs = cursor[track.id] ?? trackEnd(track.id);
+                seq.clips.push(makeClip({
+                    trackId: track.id,
+                    name: `Clip ${seq.clips.length + 1}`,
+                    startMs,
+                    durationMs,
+                    mediaType,
+                    sourceType: "imported",
+                    status: "generated",
+                    currentAssetId: assetId
+                }));
+                cursor[track.id] = startMs + durationMs;
+            }
+        }
+        finally {
+            await fs.rm(workDir, { recursive: true, force: true });
+        }
+        seq.durationMs = seq.clips.reduce((end, c) => Math.max(end, c.startMs + c.durationMs), 0);
+        const saved = (timelineRef.id
+            ? await context.updateTimelineSequence(seq.id, seq)
+            : await context.createTimelineSequence(seq));
+        if (!saved) {
+            throw new Error("AddClipsToTimeline: failed to save timeline sequence");
+        }
+        return { output: { type: "timeline", id: saved.id } };
+    }
+}
+__decorate([
+    prop({
+        type: "timeline",
+        default: { type: "timeline", id: null, data: null },
+        title: "Timeline",
+        description: "Timeline to append to. Leave empty to create a new timeline."
+    })
+], AddClipsToTimelineNode.prototype, "timeline", void 0);
+__decorate([
+    prop({
+        type: "list",
+        default: [],
+        title: "Clips",
+        description: "Media to append: image, video, and audio references."
+    })
+], AddClipsToTimelineNode.prototype, "clips", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "Untitled video",
+        title: "Name",
+        description: "Name for the timeline when a new one is created."
+    })
+], AddClipsToTimelineNode.prototype, "name", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 3000,
+        title: "Image duration (ms)",
+        description: "Clip duration for still images, in milliseconds.",
+        min: 100,
+        max: 600000
+    })
+], AddClipsToTimelineNode.prototype, "image_duration_ms", void 0);
+// ── Template derivations (design docs/graph-resources/design.md § 4.4) ──
+const timelineRefDefault = {
+    type: "timeline",
+    id: null,
+    data: null
+};
+export class FillTimelineTextNode extends BaseNode {
+    static nodeType = "nodetool.timeline.FillTimelineText";
+    static title = "Fill Timeline Text";
+    static description = "Fill a template cut's {{key}} placeholders — in text clips and in captions — from a value bag, and save the result as a new timeline. The template is never written. A key with no value stays in the frame and is reported.\n    timeline, template, text, fill, batch\n\n    Use cases:\n    - Stamp a per-SKU name and price onto an approved cut\n    - Localize an overlay without re-editing the timeline\n    - Produce one variant per row of a feed";
+    static metadataOutputTypes = {
+        timeline: "timeline",
+        filled: "list[str]",
+        unresolved: "list[str]"
+    };
+    static inlineFields = ["timeline"];
+    static inputFields = ["timeline", "values"];
+    async process(context) {
+        if (!context) {
+            throw new Error("FillTimelineText requires a processing context");
+        }
+        const source = await loadTimelineSequence(this.timeline, context);
+        const result = fillTimelineText(source, stringValues(this.values));
+        // `fillTimelineText` is a text edit, so it leaves identity alone — an
+        // editor may run it on the sequence it has open. This node derives a row
+        // instead, so it mints the id and the lineage here.
+        const now = new Date().toISOString();
+        const saved = (await context.createTimelineSequence({
+            ...result.sequence,
+            id: createTimeOrderedUuid(),
+            templateId: source.id,
+            name: this.name?.trim() || source.name,
+            createdAt: now,
+            updatedAt: now
+        }));
+        if (!saved) {
+            throw new Error("FillTimelineText: failed to create the timeline");
+        }
+        return {
+            timeline: { type: "timeline", id: saved.id },
+            filled: result.filled,
+            unresolved: result.unresolved
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "timeline",
+        default: timelineRefDefault,
+        title: "Timeline",
+        description: "The template cut to fill."
+    })
+], FillTimelineTextNode.prototype, "timeline", void 0);
+__decorate([
+    prop({
+        type: "dict",
+        default: {},
+        title: "Values",
+        description: "Value per placeholder key, e.g. {name: \"Aero 9\"}."
+    })
+], FillTimelineTextNode.prototype, "values", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "",
+        title: "Name",
+        description: "Name for the new timeline. Defaults to the template's name."
+    })
+], FillTimelineTextNode.prototype, "name", void 0);
+export class RetargetTimelineNode extends BaseNode {
+    static nodeType = "nodetool.timeline.RetargetTimeline";
+    static title = "Retarget Timeline";
+    static description = "Derive a new timeline from an approved cut on another aspect ratio, keeping every trim, placement and edit. Cover scales each shot to fill the new frame and reports the clips it crops; contain letterboxes instead. Text sizes follow the short edge. The source cut is never written.\n    timeline, aspect ratio, resize, reframe, variant\n\n    Use cases:\n    - Turn a 16:9 film into 9:16 and 1:1 cuts\n    - Produce every placement's ratio from one approved edit\n    - See which shots lose their sides before rendering";
+    static metadataOutputTypes = {
+        timeline: "timeline",
+        cropped: "list[str]"
+    };
+    static inlineFields = ["aspect_ratio", "fit", "name"];
+    static inputFields = ["timeline"];
+    async process(context) {
+        if (!context) {
+            throw new Error("RetargetTimeline requires a processing context");
+        }
+        const source = await loadTimelineSequence(this.timeline, context);
+        const ratio = this.aspect_ratio?.trim() || "9:16";
+        const { sequence, croppedClipIds } = retargetSequence(source, ratio, this.fit === "contain" ? "contain" : "cover");
+        const saved = (await context.createTimelineSequence({
+            ...sequence,
+            name: this.name?.trim() || `${source.name} ${ratio}`
+        }));
+        if (!saved) {
+            throw new Error("RetargetTimeline: failed to create the timeline");
+        }
+        return {
+            timeline: { type: "timeline", id: saved.id },
+            cropped: croppedClipIds
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "timeline",
+        default: timelineRefDefault,
+        title: "Timeline",
+        description: "The approved cut to retarget."
+    })
+], RetargetTimelineNode.prototype, "timeline", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "9:16",
+        title: "Aspect Ratio",
+        description: "Target ratio, e.g. 9:16, 1:1, 4:5. The short edge is 1080px."
+    })
+], RetargetTimelineNode.prototype, "aspect_ratio", void 0);
+__decorate([
+    prop({
+        type: "enum",
+        default: "cover",
+        title: "Fit",
+        description: "cover fills the new frame and crops; contain fits it and letterboxes.",
+        values: ["cover", "contain"]
+    })
+], RetargetTimelineNode.prototype, "fit", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "",
+        title: "Name",
+        description: "Name for the new timeline. Defaults to the source's name plus the ratio."
+    })
+], RetargetTimelineNode.prototype, "name", void 0);
+export const TIMELINE_NODES = tagAsNode([
+    RenderTimelineNode,
+    TimelineTranscriptNode,
+    AddClipsToTimelineNode,
+    // Tagged first, so `tagAsNode` leaves them alone: neither derivation shells
+    // out to ffmpeg or writes a temp file, and both need the model interfaces.
+    ...tagAsServer([FillTimelineTextNode, RetargetTimelineNode])
+]);
+//# sourceMappingURL=timeline.js.map