@nodetool-ai/video-nodes 0.8.2 → 0.8.4-a13.1

package/dist/nodes/timeline.js

@@ -2,21 +2,22 @@
  * 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.
+ * RenderTimeline runs the editor's own exporter in headless Chromium
+ * (`timeline/browserRender.ts`): the compositor, scene model, WebCodecs decode
+ * and mux the Export button uses, 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 —
+ * and variable-frame-rate clips decode at their own timestamps.
  *
- * 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".
+ * Where no Chromium can be launched, the Node compositor renders instead
+ * (`timeline/compositeRender.ts`): the same scene model and compositor through
+ * Dawn, with ffmpeg decoding clip media into RGBA and encoding the result. It
+ * needs a WebGPU device; a host with no adapter falls back further, to the
+ * ffmpeg rough cut — video/image clips normalized and concatenated in start
+ * order — which ignores everything above. Each fallback is a `warning` on the
+ * job, and `metadata.render_mode` on the output says which path ran:
+ * "browser", "composited" or "rough_cut". `NODETOOL_TIMELINE_RENDERER=node`
+ * skips the browser.
  *
  * `format` picks the container and `alpha` decides whether the frames keep a
  * transparency channel: `webm` (VP9, `yuva420p`), `mov` (ProRes 4444,
@@ -32,7 +33,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 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, loadSamplerSamples, resolveTempo, timeRemapAudioSegments } from "@nodetool-ai/timeline";
+import { computeModel3DBakeHash, createTimeOrderedUuid, DEFAULT_MIDI_INSTRUMENT, effectiveAssetId, extractedAudioLinkIds as sharedExtractedAudioLinkIds, soundTrackSoloed, videoClipsWithOwnAudio, encodeWavPcm16, ffmpegFadeCurve, fillTimelineText, resolveClipFades, retargetSequence, hasTimeRemap, sourceRate, makeClip, makeSequence, makeTrack, renderMidiClip, loadSamplerSamples, resolveTempo, timeRemapAudioSegments, clipAudioTailSec } from "@nodetool-ai/timeline";
 import { tagAsNode, tagAsServer } from "@nodetool-ai/nodes-utils";
 import { promises as fs } from "node:fs";
 import os from "node:os";
@@ -40,6 +41,7 @@ import path from "node:path";
 import { AssetFiles, assetFileName } from "./timeline/assetFiles.js";
 import { atempoChain, execFfmpeg, execFfprobe, ffprobeDuration, FFMPEG_MAX_BUFFER, MissingBinaryError } from "./ffmpeg-helpers.js";
 import { CompositorUnavailableError, renderTimelineComposited } from "./timeline/compositeRender.js";
+import { BrowserRenderUnavailableError, renderTimelineInBrowser } from "./timeline/browserRender.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";
@@ -101,16 +103,20 @@ function renderableVideoClips(seq) {
 /**
  * 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).
+ * (they have no `currentAssetId` at all). An audio clip sounds under the same
+ * status rule its picture would be drawn under (`effectiveAssetId`).
  */
 function mixableAudioClips(seq) {
     const tracks = trackById(seq.tracks);
+    const hasSolo = soundTrackSoloed(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 (hasSolo && !track.solo)
+            return false;
         if (clip.durationMs <= 0)
             return false;
         if (track.type === "midi") {
@@ -118,32 +124,13 @@ function mixableAudioClips(seq) {
         }
         return (track.type === "audio" &&
             clip.mediaType === "audio" &&
-            !!clip.currentAssetId);
+            !!effectiveAssetId(clip));
     })
         .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.
- */
+/** The detached-audio linkIds of a sequence; see the shared rule. */
 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;
+    return sharedExtractedAudioLinkIds(seq.clips, seq.tracks);
 }
 /** Scale + letterbox to the sequence frame, normalize fps and pixel format. */
 function segmentVideoFilter(width, height, fps) {
@@ -234,25 +221,11 @@ async function encodeSegment(opts) {
 /**
  * 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.
+ * frame-by-frame composite has no audio at all. The preview and browser
+ * export pick the same clips through `videoClipsWithOwnAudio`.
  */
 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);
+    return videoClipsWithOwnAudio(seq.clips, seq.tracks).sort((a, b) => a.startMs - b.startMs);
 }
 /** Seconds, at millisecond resolution, for an ffmpeg filter argument. */
 function ffSeconds(ms) {
@@ -305,6 +278,7 @@ function audioClipFilter(clip, inputIndex, label) {
         steps.push(`volume=${clip.volumeDb}dB`);
     }
     steps.push(...clipFadeSteps(clip, 0));
+    steps.push(...clipEffectChainSteps(clip));
     const delay = Math.max(0, Math.round(clip.startMs));
     steps.push(`adelay=${delay}|${delay}`);
     return `[${inputIndex}:a]${steps.join(",")}[${label}]`;
@@ -332,7 +306,174 @@ function audioRemapSegmentFilter(clip, segment, inputIndex, label) {
     steps.push(`adelay=${delay}|${delay}`);
     return `[${inputIndex}:a]${steps.join(",")}[${label}]`;
 }
-/** Anything that draws: media, titles, shapes, or a caption riding a clip. */
+/** Clamp for an ffmpeg option that refuses values outside its range. */
+function clampTo(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Sample rate a track's effect chain runs at, the mix's own `-ar`. */
+const EFFECT_SAMPLE_RATE = 48000;
+/** A biquad frequency ffmpeg accepts, held below Nyquist as Web Audio holds it. */
+function biquadHz(frequency) {
+    return clampTo(frequency, 1, EFFECT_SAMPLE_RATE / 2 - 1);
+}
+/**
+ * Web Audio's compressor adds makeup gain of its own: the gain that brings a
+ * full-scale input back to full scale, raised to the power 0.6. ffmpeg's
+ * `acompressor` adds none, so it is computed here from the curve at 0 dBFS
+ * with a quadratic soft knee, which is close to but not exactly the spec's.
+ */
+function compressorMakeupGain(e) {
+    const threshold = clampTo(e.thresholdDb, -100, 0);
+    const ratio = clampTo(e.ratio, 1, 20);
+    const knee = clampTo(e.kneeDb, 0, 40);
+    const over = -threshold;
+    let gainDb;
+    if (2 * over < -knee) {
+        gainDb = 0;
+    }
+    else if (2 * Math.abs(over) <= knee) {
+        gainDb = ((1 / ratio - 1) * (over + knee / 2) ** 2) / (2 * Math.max(knee, 1e-6));
+    }
+    else {
+        gainDb = threshold + over / ratio;
+    }
+    return clampTo(Math.pow(10, (-gainDb * 0.6) / 20), 1, 64);
+}
+/**
+ * ffmpeg steps for one enabled effect, matching the Web Audio node
+ * `AudioGraph.buildEffectUnit` builds for the preview. The shelves use Web
+ * Audio's fixed slope of 1, a lowpass/highpass Q is in dB as it is there, and
+ * a bandpass Q is linear. The compressor detects peaks; its knee is capped at
+ * the 18 dB `acompressor` allows.
+ */
+function audioEffectSteps(effect) {
+    switch (effect.type) {
+        case "gain":
+            return [`volume=${effect.gainDb}dB`];
+        case "eq3":
+            return [
+                `lowshelf=f=${biquadHz(effect.lowFreq)}:g=${effect.lowGainDb}:t=s:w=1`,
+                `equalizer=f=${biquadHz(effect.midFreq)}:t=q:w=${Math.max(0.0001, effect.midQ)}:g=${effect.midGainDb}`,
+                `highshelf=f=${biquadHz(effect.highFreq)}:g=${effect.highGainDb}:t=s:w=1`
+            ];
+        case "filter": {
+            const q = effect.mode === "bandpass"
+                ? Math.max(0.0001, effect.q)
+                : Math.max(0.0001, Math.pow(10, effect.q / 20));
+            return [`${effect.mode}=f=${biquadHz(effect.frequency)}:t=q:w=${q}`];
+        }
+        case "compressor":
+            return [
+                "acompressor=" +
+                    [
+                        `threshold=${clampTo(Math.pow(10, effect.thresholdDb / 20), 0.000976563, 1)}`,
+                        `ratio=${clampTo(effect.ratio, 1, 20)}`,
+                        `attack=${clampTo(effect.attackMs, 0.01, 2000)}`,
+                        `release=${clampTo(effect.releaseMs, 0.01, 9000)}`,
+                        `knee=${clampTo(Math.pow(10, effect.kneeDb / 20), 1, 8)}`,
+                        `makeup=${compressorMakeupGain(effect)}`,
+                        "detection=peak"
+                    ].join(":")
+            ];
+        default:
+            return [];
+    }
+}
+/** Most taps an `aecho` is given, so a long feedback echo stays cheap. */
+const MAX_ECHO_TAPS = 32;
+/** A tap quieter than this (-60 dB) is left out. */
+const SILENT_TAP_GAIN = 0.001;
+/** Taps the reverb approximation spreads over its decay. */
+const REVERB_TAPS = 24;
+/** An `aecho` from a dry gain and taps of `[delayMs, gain]`. */
+function aechoStep(dryGain, taps) {
+    const delays = taps.map(([ms]) => clampTo(Math.round(ms), 1, 90000));
+    const decays = taps.map(([, gain]) => clampTo(gain, 0.0001, 1).toFixed(5));
+    return `aecho=${clampTo(dryGain, 0.001, 1).toFixed(5)}:1:${delays.join("|")}:${decays.join("|")}`;
+}
+/**
+ * ffmpeg steps for one clip effect, matching `audioEffectNodes.ts` in the
+ * browser. The track DSP types reuse {@link audioEffectSteps}.
+ *
+ * An echo is a delay line feeding itself; unrolled, it is a tap at every
+ * multiple of the delay, each `feedback` times the one before, which is what
+ * `aecho` plays. A reverb in the browser convolves with decaying noise, and
+ * ffmpeg has no convolver without a second input stream, so here it is a
+ * spread of taps on the same -60 dB envelope: the same decay and level, with
+ * a grainier tail.
+ */
+function clipAudioEffectSteps(effect) {
+    switch (effect.type) {
+        case "echo": {
+            const mix = clampTo(effect.mix, 0, 1);
+            const feedback = clampTo(effect.feedback, 0, 0.95);
+            const taps = [];
+            for (let k = 1; k <= MAX_ECHO_TAPS; k += 1) {
+                const gain = mix * Math.pow(feedback, k - 1);
+                if (k > 1 && gain < SILENT_TAP_GAIN)
+                    break;
+                taps.push([effect.delayMs * k, gain]);
+            }
+            return [aechoStep(1 - mix, taps)];
+        }
+        case "reverb": {
+            const mix = clampTo(effect.mix, 0, 1);
+            const decayMs = Math.max(50, effect.decaySec * 1000);
+            const times = Array.from({ length: REVERB_TAPS }, (_, i) => 10 + decayMs * 0.8 * Math.pow((i + 1) / REVERB_TAPS, 1.6));
+            // ln(1000): -60 dB at the end of the decay.
+            const raw = times.map((ms) => Math.exp((-Math.log(1000) * ms) / decayMs));
+            const norm = Math.sqrt(raw.reduce((sum, g) => sum + g * g, 0));
+            return [
+                aechoStep(1 - mix, times.map((ms, i) => [ms, (mix * raw[i]) / norm]))
+            ];
+        }
+        case "distortion": {
+            // tanh(k·x) / tanh(k), as the browser's wave shaper curve.
+            const drive = Math.pow(10, Math.max(0, effect.driveDb) / 20);
+            const normDb = -20 * Math.log10(Math.tanh(drive));
+            return [
+                `volume=${Math.max(0, effect.driveDb)}dB`,
+                "asoftclip=type=tanh",
+                `volume=${(effect.outputDb + normDb).toFixed(3)}dB`
+            ];
+        }
+        default:
+            return audioEffectSteps(effect);
+    }
+}
+/**
+ * A clip's real-time effects, after its gain and fades. The stream is padded
+ * by the effects' tail first, so an echo or reverb rings on past the clip's
+ * last sample instead of stopping with it.
+ */
+function clipEffectChainSteps(clip) {
+    const effects = (clip.audioEffects ?? []).filter((effect) => effect.enabled);
+    if (effects.length === 0)
+        return [];
+    const tailSec = clipAudioTailSec(effects);
+    return [
+        `aresample=${EFFECT_SAMPLE_RATE}`,
+        ...(tailSec > 0 ? [`apad=pad_dur=${tailSec.toFixed(3)}`] : []),
+        ...effects.flatMap(clipAudioEffectSteps)
+    ];
+}
+/**
+ * The DSP chain of a track, in array order. Only audio and midi tracks carry
+ * one, as in the preview, where `AudioGraph.updateTracks` applies effects to
+ * those tracks alone.
+ */
+function trackEffectSteps(track) {
+    if (!track || (track.type !== "audio" && track.type !== "midi"))
+        return [];
+    const steps = (track.effects ?? [])
+        .filter((effect) => effect.enabled)
+        .flatMap(audioEffectSteps);
+    return steps.length > 0 ? [`aresample=${EFFECT_SAMPLE_RATE}`, ...steps] : [];
+}
+/**
+ * Anything that draws: media, titles, shapes, a caption riding a clip, or a 3D
+ * clip whose bake still matches it (a live one draws only in the editor).
+ */
 function hasRenderableVisual(seq) {
     const tracks = trackById(seq.tracks);
     return seq.clips.some((clip) => {
@@ -347,7 +488,14 @@ function hasRenderableVisual(seq) {
             return !!clip.textStyle;
         if (clip.mediaType === "shape")
             return !!clip.shapeStyle;
-        return ((clip.mediaType === "video" || clip.mediaType === "image") &&
+        if (clip.mediaType === "model3d") {
+            const bake = clip.model3dStyle?.bake;
+            return (bake !== undefined &&
+                computeModel3DBakeHash(clip, seq) === bake.dependencyHash);
+        }
+        return ((clip.mediaType === "video" ||
+            clip.mediaType === "image" ||
+            clip.mediaType === "overlay") &&
             !!clip.currentAssetId);
     });
 }
@@ -534,10 +682,21 @@ async function renderRoughCut(opts) {
  * 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 { basePath, clips, tracks, baseHasAudio, assets, midi, workDir, extension, audioCodec } = opts;
     const inputs = ["-i", basePath];
     const filters = [];
     const labels = [];
+    // Each clip's stream(s), grouped by track so a track's effect chain runs
+    // over the sum of its clips, as the preview's chain does.
+    const trackLabels = new Map();
+    const labelsOf = (clip) => {
+        let list = trackLabels.get(clip.trackId);
+        if (!list) {
+            list = [];
+            trackLabels.set(clip.trackId, list);
+        }
+        return list;
+    };
     let inputIndex = 1;
     for (const [i, clip] of clips.entries()) {
         const audioPath = await audioSourcePath(clip, assets, midi);
@@ -554,7 +713,7 @@ async function mixAudioInto(opts) {
             inputs.push("-i", audioPath);
             const label = `a${i}`;
             filters.push(audioClipFilter(clip, inputIndex, label));
-            labels.push(`[${label}]`);
+            labelsOf(clip).push(`[${label}]`);
             inputIndex += 1;
             continue;
         }
@@ -577,19 +736,37 @@ async function mixAudioInto(opts) {
         // 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)) {
+        // Clip effects likewise run on the whole clip, after its fades.
+        const effectSteps = clipEffectChainSteps(clip);
+        if (segmentLabels.length > 0 &&
+            (hasClipFade(clip) || effectSteps.length > 0)) {
             const faded = `a${i}_fade`;
+            const clipSteps = [...clipFadeSteps(clip, clip.startMs), ...effectSteps];
             const steps = segmentLabels.length > 1
                 ? [
                     `amix=inputs=${segmentLabels.length}:duration=longest:normalize=0`,
-                    ...clipFadeSteps(clip, clip.startMs)
+                    ...clipSteps
                 ]
-                : clipFadeSteps(clip, clip.startMs);
+                : clipSteps;
             filters.push(`${segmentLabels.join("")}${steps.join(",")}[${faded}]`);
-            labels.push(`[${faded}]`);
+            labelsOf(clip).push(`[${faded}]`);
             continue;
         }
-        labels.push(...segmentLabels);
+        labelsOf(clip).push(...segmentLabels);
+    }
+    const byTrack = trackById(tracks);
+    for (const [trackId, streams] of trackLabels) {
+        const steps = trackEffectSteps(byTrack.get(trackId));
+        if (steps.length === 0) {
+            labels.push(...streams);
+            continue;
+        }
+        const label = `t${filters.length}`;
+        const head = streams.length > 1
+            ? [`amix=inputs=${streams.length}:duration=longest:normalize=0`]
+            : [];
+        filters.push(`${streams.join("")}${[...head, ...steps].join(",")}[${label}]`);
+        labels.push(`[${label}]`);
     }
     if (labels.length === 0)
         return basePath;
@@ -633,6 +810,7 @@ export async function mixCompositedTimelineAudio(opts) {
     return mixAudioInto({
         basePath,
         clips,
+        tracks: sequence.tracks,
         baseHasAudio: false,
         assets: { path: resolveAssetPath },
         midi: new MidiFiles(workDir, sequence, resolveAssetPath),
@@ -641,6 +819,13 @@ export async function mixCompositedTimelineAudio(opts) {
         audioCodec: output.audioCodec ?? "aac"
     });
 }
+/**
+ * Whether `RenderTimeline` tries headless Chromium first. On unless
+ * `NODETOOL_TIMELINE_RENDERER=node` asks for the Node compositor.
+ */
+function browserRendererEnabled() {
+    return process.env["NODETOOL_TIMELINE_RENDERER"]?.trim().toLowerCase() !== "node";
+}
 /** 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. */
@@ -746,66 +931,92 @@ export class RenderTimelineNode extends BaseNode {
             let baseHasAudio;
             let audioToMix;
             let renderMode;
-            try {
-                basePath = path.join(workDir, `composited.${output.extension}`);
-                const result = await renderTimelineComposited({
+            const browserPath = path.join(workDir, `rendered.${output.extension}`);
+            const renderedInBrowser = browserRendererEnabled()
+                ? await this.renderInBrowser(ctx, {
                     sequence: seq,
                     width,
                     height,
                     fps,
                     durationMs,
-                    resolveAssetPath: (assetId) => assets.path(assetId),
-                    outPath: basePath,
                     output,
-                    onProgress: this.progressReporter(ctx),
-                    signal: ctx.signal
-                });
-                const { skippedClips, fontsUnavailable } = result;
-                if (result.complete === false) {
-                    throw new Error(`Timeline export is incomplete: ${result.diagnostics.map((item) => `${item.clipId} (${item.startMs}–${item.endMs}ms): ${item.detail}`).join("; ")}`);
-                }
-                for (const name of skippedClips) {
-                    this.log(ctx, `Clip "${name}" was skipped — its media could not be decoded`, "warning");
-                }
-                for (const family of fontsUnavailable) {
-                    this.log(ctx, `Font "${family}" could not be resolved from Google Fonts — drawn in the fallback face`, "warning");
-                }
-                renderMode = "composited";
-                // A composite carries no sound: every audible clip is mixed in below,
-                // including the audio muxed into video clips.
+                    bitrate: Math.max(0, Number(this.bitrate) || 0),
+                    resolveAssetPath: (assetId) => assets.path(assetId),
+                    outPath: browserPath,
+                    workDir
+                })
+                : false;
+            if (renderedInBrowser) {
+                basePath = browserPath;
+                renderMode = "browser";
+                // The browser writes picture only: every audible clip is mixed in
+                // below, exactly as for a Node composite.
                 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.");
+            else
+                try {
+                    basePath = path.join(workDir, `composited.${output.extension}`);
+                    const result = await renderTimelineComposited({
+                        sequence: seq,
+                        width,
+                        height,
+                        fps,
+                        durationMs,
+                        resolveAssetPath: (assetId) => assets.path(assetId),
+                        outPath: basePath,
+                        output,
+                        onProgress: this.progressReporter(ctx),
+                        signal: ctx.signal
+                    });
+                    const { skippedClips, fontsUnavailable } = result;
+                    if (result.complete === false) {
+                        throw new Error(`Timeline export is incomplete: ${result.diagnostics.map((item) => `${item.clipId} (${item.startMs}–${item.endMs}ms): ${item.detail}`).join("; ")}`);
+                    }
+                    for (const name of skippedClips) {
+                        this.log(ctx, `Clip "${name}" was skipped — its media could not be decoded`, "warning");
+                    }
+                    for (const family of fontsUnavailable) {
+                        this.log(ctx, `Font "${family}" could not be resolved from Google Fonts — drawn in the fallback face`, "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;
                 }
-                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.
@@ -839,6 +1050,7 @@ export class RenderTimelineNode extends BaseNode {
                 ? await mixAudioInto({
                     basePath,
                     clips: audioToMix,
+                    tracks: seq.tracks,
                     baseHasAudio,
                     assets,
                     midi,
@@ -895,6 +1107,48 @@ export class RenderTimelineNode extends BaseNode {
             return;
         throw new MissingEncoderError(encoder, output.format);
     }
+    /**
+     * Render in headless Chromium. False when no browser could be launched,
+     * after a warning that the Node compositor renders instead.
+     */
+    async renderInBrowser(ctx, options) {
+        try {
+            const result = await renderTimelineInBrowser({
+                ...options,
+                onProgress: this.progressReporter(ctx),
+                signal: ctx.signal
+            });
+            const compositor = result.backend === "webgpu"
+                ? `the WebGPU compositor (${result.adapter ?? "unknown adapter"})`
+                : result.webgpuUnusable
+                    ? `the Canvas 2D compositor (WebGPU could not be read back: ${result.webgpuUnusable})`
+                    : "the Canvas 2D compositor (no WebGPU adapter)";
+            const encoding = result.encoding.kind === "png"
+                ? "PNG frames"
+                : `${result.encoding.codec} in ${result.encoding.container}`;
+            this.log(ctx, `Rendered ${result.frames} frames in headless Chromium (${result.browser}) ` +
+                `with ${compositor}, encoded as ${encoding}` +
+                `${result.transcoded ? " and transcoded with ffmpeg" : ""}.`, "info");
+            for (const family of result.fontsUnavailable) {
+                this.log(ctx, `Font "${family}" could not be resolved from Google Fonts — drawn in the fallback face`, "warning");
+            }
+            if (result.convertedSources > 0) {
+                this.log(ctx, `This browser cannot decode ${result.convertedSources} of the clips, so they were ` +
+                    "converted to VP9 before rendering. Google Chrome decodes them directly.", "warning");
+            }
+            if (result.degradedBakes > 0) {
+                this.log(ctx, `${result.degradedBakes} baked 3D clip(s) could not be decoded and were drawn from the live 3D layer instead.`, "warning");
+            }
+            return true;
+        }
+        catch (error) {
+            if (!(error instanceof BrowserRenderUnavailableError))
+                throw error;
+            this.log(ctx, `${error.message} Rendering with the Node compositor instead, which can ` +
+                "differ from the editor preview and decodes variable-frame-rate clips more slowly.", "warning");
+            return false;
+        }
+    }
     /** Post on the node's log channel, where the run has one. */
     log(context, content, severity) {
         if (!this.__node_id)