videoclaw 3.0.0-alpha.1

package/src/video/assemble/stitch.ts

@@ -0,0 +1,918 @@
+/**
+ * Stitch keystone for the assemble stage (sub-slice 3h).
+ *
+ * Source of truth (ported VERBATIM):
+ *  - `skills/video-replicator/scripts/stitch_bunty.py` — the bunty stitch. Uses
+ *    the concat **demuxer** path (`ffmpeg -y -f concat -safe 0 -i concat.txt
+ *    -c copy output`) — a single ffmpeg invocation regardless of segment count,
+ *    chosen deliberately so it survives the sandbox's per-session FFmpeg limit.
+ *  - `skills/video-replicator/scripts/ffmpeg_wrapper.py:concat_via_filter` — the
+ *    concat **filter** fallback (`-filter_complex
+ *    "[0:v][0:a]...concat=n=N:v=1:a=1[outv][outa]"` + re-encode). Used for 8+
+ *    segments where demuxer-accumulated AV drift across boundaries matters, OR
+ *    when a segment has incompatible codec params and the demuxer rejects it.
+ *  - `skills/video-replicator/scripts/assembly_utils.py:add_background_music` —
+ *    the music-bed mix (loops the music under the narration at low volume with a
+ *    tail fade-out, via amix).
+ *
+ * bunty (stitch_bunty.py) and nex (nex_assemble.py) collapse into ONE
+ * parameterized stitch driven by brand-profile-derived knobs:
+ *  - bunty: pre-encoded segments → demuxer concat, no music, intro/outro by
+ *    lip-sync scene segments. (`_concat_via_demuxer`, demuxer-first with a
+ *    filter fallback.)
+ *  - nex: normalized segments → filter concat (drift-free for 8+), optional
+ *    background-music bed, optional title-card prepend. (`concat_via_filter`
+ *    + `add_background_music`.)
+ * These differences become StitchInput fields: `concatStrategy`
+ * (demuxer | filter | auto), `intro` / `outro` segment paths, and the optional
+ * `music` block (track + volume + tail fade). The demuxer-vs-filter selection in
+ * `auto` mode flips at `FILTER_FALLBACK_SEGMENT_THRESHOLD` segments — the real
+ * sandbox-survival + drift lesson from the Python.
+ *
+ * AV-drift note (stitch_bunty.py ~L471-479): demuxer `-c copy` preserves exact
+ * packet timing and accumulates no re-encode drift, BUT it requires every
+ * segment to share encoding params. The per-segment AV-lock from 3e
+ * (1280×720@24, H.264 libx264 preset-fast crf20, AAC 44100 stereo) guarantees
+ * that, so the demuxer path is the primary one. Filter concat re-encodes (and so
+ * can introduce its own drift) but tolerates mismatched inputs — it is the
+ * fallback.
+ *
+ * IMPORTANT — testing boundary (SAME as 3e): the PURE arg-builders
+ * (`buildConcatDemuxerArgs`, `buildConcatFilterArgs`, `buildMusicMixArgs`) are
+ * the unit-tested surface (arg-shape only). `stitch` actually spawns ffmpeg and
+ * writes the concat list; verifying that the final MP4 looks/sounds right on
+ * real media is a HUMAN integration checkpoint, explicitly OUT OF SCOPE for the
+ * unit tests. Tests use the dry-run path and never run ffmpeg or require media.
+ */
+import { writeFile, mkdir, stat } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { runFfmpeg, ffprobeDuration, isValidMp4, trimTailArgs, letterboxFilter, type RunFfmpegOptions } from './ffmpeg.js';
+import { VclawError } from '../errors.js';
+
+/**
+ * Segment-count threshold at which `auto` strategy switches from the
+ * concat demuxer to the concat filter. Mirrors the Python lesson that the
+ * demuxer accumulates audible AV drift across "8+ segments"
+ * (ffmpeg_wrapper.concat_via_filter docstring). At or above this many segments
+ * `auto` prefers the filter path.
+ */
+export const FILTER_FALLBACK_SEGMENT_THRESHOLD = 8;
+
+/** Default background-music mix level (nex_assemble.py --music-volume default 0.05). */
+export const DEFAULT_MUSIC_VOLUME = 0.05;
+/** Default tail fade-out for the music bed in seconds (add_background_music default 3.0). */
+export const DEFAULT_MUSIC_FADE_OUT_SEC = 3.0;
+/** AAC bitrate for re-encode paths (filter concat + music mix). Matches the Python "192k". */
+export const STANDARD_AUDIO_BITRATE = '192k';
+
+/**
+ * Named post-production color grades → FFmpeg video-filter chains (WS9+). Applied
+ * in the per-segment prep pass, so different segments can carry different grades —
+ * which is exactly the reference advert's narrative color language (cool-steel
+ * "normal ops" -> crimson "breach" -> electric-blue "resolution"). These are real
+ * post transforms on the rendered footage (colorbalance/eq), NOT prompt hints.
+ * `kodak-500t` approximates the Vision3 500T tungsten stock (cool shadows, warm
+ * highlights, mild desat). For a true film LUT, pass a `.cube` via `gradeLut`.
+ */
+const GRADE_FILTERS: Record<string, string> = {
+  'cool-steel': 'colorbalance=rs=-0.08:gs=-0.04:bs=0.12,eq=saturation=0.82:contrast=1.06',
+  'crimson-threat': 'colorbalance=rs=0.18:gs=-0.06:bs=-0.08,eq=saturation=1.05:contrast=1.12',
+  'electric-blue': 'colorbalance=rs=-0.06:gs=0.04:bs=0.18,eq=saturation=1.00:contrast=1.05',
+  'kodak-500t': 'colorbalance=bs=0.08:rh=0.05:bh=-0.05,eq=saturation=0.90:contrast=1.05',
+  'bleach-bypass': 'eq=saturation=0.50:contrast=1.32',
+  'desaturated': 'eq=saturation=0.70:contrast=1.08',
+  'teal-orange': 'colorbalance=rs=0.05:bs=0.10:rh=0.08:bh=-0.06,eq=saturation=1.08',
+};
+
+/** Stable list of the named grade ids (for CLI validation / docs). */
+export const GRADE_FILTER_IDS = Object.keys(GRADE_FILTERS);
+
+/**
+ * Resolve a named grade id to its FFmpeg filter chain. Returns '' for an
+ * undefined/empty/unknown id (the prep pass then applies no grade) — callers that
+ * want a hard failure on an unknown id should validate against {@link GRADE_FILTER_IDS}.
+ */
+export function resolveGradeFilter(id: string | undefined): string {
+  if (!id) return '';
+  return GRADE_FILTERS[id] ?? '';
+}
+
+/** Which concat path to use. `auto` picks demuxer/filter by segment count. */
+export type ConcatStrategy = 'demuxer' | 'filter' | 'auto';
+
+export interface MusicMixSettings {
+  /** Path to the background-music track. Looped under the narration. */
+  trackPath: string;
+  /** Mix level for the music bed (0..1). Defaults to {@link DEFAULT_MUSIC_VOLUME}. */
+  volume?: number;
+  /** Tail fade-out duration in seconds. Defaults to {@link DEFAULT_MUSIC_FADE_OUT_SEC}. */
+  fadeOutSec?: number;
+}
+
+export interface StitchInput {
+  /**
+   * Ordered body segment paths (the slide segments). These sit between the
+   * optional intro and outro segments. From 3e every segment conforms to
+   * 1280×720@24 / H.264 / AAC 44100 stereo, so demuxer concat is valid.
+   */
+  segments: string[];
+  /** Optional ordered intro segment paths, prepended before `segments`. */
+  intro?: string[];
+  /** Optional ordered outro segment paths, appended after `segments`. */
+  outro?: string[];
+  /** Where the final stitched MP4 is written. */
+  outputPath: string;
+  /**
+   * Path for the concat-demuxer list file. Defaults to `concat.txt` alongside
+   * the output. Only used by the demuxer path.
+   */
+  concatListPath?: string;
+  /**
+   * Concat strategy. `auto` (default) uses the demuxer up to
+   * {@link FILTER_FALLBACK_SEGMENT_THRESHOLD} segments, then the filter.
+   * bunty maps to `auto`/`demuxer`; nex maps to `filter`.
+   */
+  concatStrategy?: ConcatStrategy;
+  /** Optional background-music bed (the nex-brand knob). Omit for bunty. */
+  music?: MusicMixSettings;
+  /**
+   * Optional EXTRA global audio layers (dialogue / sfx / additional voice)
+   * mixed over the concatenated video at the stitch step, BEYOND the `music`
+   * bed above. Presence-driven and additive: when this is empty/undefined the
+   * stitch is byte-identical to legacy (the music-only {@link buildMusicMixArgs}
+   * path, or the no-audio path). When non-empty, the music bed (if any) is
+   * prepended as a `music` layer and the whole set is mixed via
+   * {@link buildMultiLayerMixArgs}. See assemble.ts Step 6 (dialogue/sfx wiring).
+   */
+  audioLayers?: AudioLayer[];
+  /**
+   * Optional per-clip tail cut (WS9). When set, each ordered segment is
+   * re-encoded with `-t <clipMaxSeconds>` before concat, dropping the dead /
+   * freeze frames AI generators append. Omit for byte-identical legacy behavior.
+   */
+  clipMaxSeconds?: number;
+  /**
+   * Optional letterbox normalization (WS9). When set (e.g. `2.39:1`), each
+   * segment is scaled+padded onto the {@link letterboxCanvas} (default
+   * 1280×720) before concat, producing cinematic bars. Omit to disable.
+   */
+  letterboxRatio?: string;
+  /**
+   * Canvas for {@link letterboxRatio}. Defaults to the 3e segment standard
+   * (1280×720) so normalized segments stay uniform for demuxer concat.
+   */
+  letterboxCanvas?: { width: number; height: number };
+  /**
+   * Path to a `.cube`/`.3dl` LUT applied to every segment via `lut3d` (e.g. a
+   * Kodak Vision3 500T film-stock LUT). Omit to skip. Triggers the prep pass.
+   */
+  gradeLut?: string;
+  /**
+   * Named color grade applied to every segment (see {@link GRADE_FILTER_IDS}).
+   * A real post transform on the footage, not a prompt hint. Omit to skip.
+   */
+  gradeId?: string;
+  /**
+   * Per-segment grade overrides, indexed to {@link orderedSegments} (intro +
+   * body + outro). A defined entry overrides {@link gradeId} for that segment —
+   * this is how the narrative color language is realized (e.g. cool-steel for the
+   * calm scenes, crimson-threat for the breach, electric-blue for the resolution).
+   */
+  segmentGradeIds?: Array<string | undefined>;
+}
+
+export interface StitchPlannedStep {
+  /** What this step does. */
+  kind: 'segment-prep' | 'concat-demuxer' | 'concat-filter' | 'music-mix' | 'multi-layer-mix';
+  /** The ffmpeg args (everything after the binary and the auto-prepended `-y`). */
+  args: string[];
+  /** The output this step writes. */
+  outputPath: string;
+}
+
+export interface StitchResult {
+  status: 'complete' | 'dry-run';
+  /** Final MP4 path. */
+  outputPath: string;
+  /** Ordered list of every segment that went into the concat. */
+  orderedSegments: string[];
+  /** Which concat path was actually used. */
+  concatStrategy: 'demuxer' | 'filter';
+  /** Whether a music bed was mixed. */
+  music: boolean;
+  /** The planned ffmpeg command sequence (always populated, incl. dry-run). */
+  plan: StitchPlannedStep[];
+  /** Final video duration in milliseconds (0 on dry-run — no probe). */
+  durationMs: number;
+}
+
+/** Assemble the full ordered segment list: intro + body + outro. */
+export function orderedSegments(input: StitchInput): string[] {
+  return [...(input.intro ?? []), ...input.segments, ...(input.outro ?? [])];
+}
+
+/**
+ * Choose the effective concat path. `demuxer`/`filter` are honored directly;
+ * `auto` flips to the filter at {@link FILTER_FALLBACK_SEGMENT_THRESHOLD}
+ * segments (the drift lesson from the Python).
+ */
+export function selectConcatStrategy(
+  strategy: ConcatStrategy,
+  segmentCount: number,
+): 'demuxer' | 'filter' {
+  if (strategy === 'demuxer' || strategy === 'filter') return strategy;
+  return segmentCount >= FILTER_FALLBACK_SEGMENT_THRESHOLD ? 'filter' : 'demuxer';
+}
+
+/** Render the concat-demuxer list file body: one `file '<abspath>'` line per segment. */
+export function buildConcatListContent(segments: string[]): string {
+  // Mirrors stitch_bunty._concat_via_demuxer: file '<os.path.abspath(seg)>'.
+  // DEVIATION from the Python (which had this bug): single quotes in the path
+  // are escaped ('\'') — an apostrophe anywhere in a parent directory name
+  // would otherwise corrupt the concat list for every segment.
+  return segments.map((seg) => `file '${resolvePath(seg).replace(/'/g, `'\\''`)}'\n`).join('');
+}
+
+/**
+ * Build the concat-DEMUXER ffmpeg args (PURE). The primary path.
+ *
+ * Ported VERBATIM from stitch_bunty._concat_via_demuxer (L240):
+ *   ffmpeg -y -f concat -safe 0 -i concat.txt -c copy output
+ * (`-y` is prepended by `runFfmpeg`, so it is NOT included here.)
+ *
+ * A single ffmpeg invocation regardless of segment count — survives the
+ * sandbox's per-session FFmpeg limit. Requires all segments to share encoding
+ * params (true for 3e segments).
+ */
+export function buildConcatDemuxerArgs(
+  _segments: string[],
+  concatListPath: string,
+  outputPath: string,
+): string[] {
+  return ['-f', 'concat', '-safe', '0', '-i', concatListPath, '-c', 'copy', outputPath];
+}
+
+export interface BuildConcatFilterOptions {
+  /** H.264 CRF (Python default 20). */
+  crf?: number;
+  /** AAC bitrate (Python default "192k"). */
+  audioBitrate?: string;
+  /** Audio sample rate Hz (Python default 44100). */
+  sampleRate?: number;
+  /** Audio channel count (Python default 2). */
+  channels?: number;
+}
+
+/**
+ * Build the concat-FILTER fallback ffmpeg args (PURE). For 8+ segments where
+ * demuxer drift accumulates, or when a segment has incompatible codec params.
+ *
+ * Ported VERBATIM from ffmpeg_wrapper.concat_via_filter (L296-326):
+ *   -i f0 -i f1 ... -i f{n-1}
+ *   -filter_complex "[0:v][0:a][1:v][1:a]...concat=n=N:v=1:a=1[outv][outa]"
+ *   -map [outv] -map [outa]
+ *   -c:v libx264 -preset fast -crf 20
+ *   -c:a aac -b:a 192k -ar 44100 -ac 2
+ *   -movflags +faststart output
+ */
+export function buildConcatFilterArgs(
+  segments: string[],
+  outputPath: string,
+  opts: BuildConcatFilterOptions = {},
+): string[] {
+  const crf = opts.crf ?? 20;
+  const audioBitrate = opts.audioBitrate ?? STANDARD_AUDIO_BITRATE;
+  const sampleRate = opts.sampleRate ?? 44100;
+  const channels = opts.channels ?? 2;
+
+  const inputArgs: string[] = [];
+  for (const seg of segments) {
+    inputArgs.push('-i', seg);
+  }
+
+  // [0:v][0:a][1:v][1:a]...[n-1:v][n-1:a]concat=n=N:v=1:a=1[outv][outa]
+  let filterInputs = '';
+  for (let i = 0; i < segments.length; i += 1) {
+    filterInputs += `[${i}:v][${i}:a]`;
+  }
+  const filterComplex = `${filterInputs}concat=n=${segments.length}:v=1:a=1[outv][outa]`;
+
+  return [
+    ...inputArgs,
+    '-filter_complex',
+    filterComplex,
+    '-map',
+    '[outv]',
+    '-map',
+    '[outa]',
+    '-c:v',
+    'libx264',
+    '-preset',
+    'fast',
+    '-crf',
+    String(crf),
+    '-c:a',
+    'aac',
+    '-b:a',
+    audioBitrate,
+    '-ar',
+    String(sampleRate),
+    '-ac',
+    String(channels),
+    '-movflags',
+    '+faststart',
+    outputPath,
+  ];
+}
+
+export interface BuildSegmentPrepOptions {
+  /** Per-clip tail cut in seconds (WS9 trimTailArgs). Omit/<=0 disables the trim. */
+  clipMaxSeconds?: number;
+  /** Letterbox target ratio label (WS9 letterboxFilter). Omit/'' disables the filter. */
+  letterboxRatio?: string;
+  /** Path to a `.cube`/`.3dl` LUT applied via `lut3d` (e.g. a Kodak Vision3 500T LUT). Omit to skip. */
+  gradeLut?: string;
+  /** Resolved FFmpeg grade filter chain (from {@link resolveGradeFilter}). Omit/'' to skip. */
+  gradeFilter?: string;
+  /** Letterbox canvas width. Default 1280 (3e segment standard). */
+  width?: number;
+  /** Letterbox canvas height. Default 720. */
+  height?: number;
+  /** Output frame rate. Default 24. */
+  fps?: number;
+  /** H.264 CRF. Default 20. */
+  crf?: number;
+  /** AAC bitrate. Default {@link STANDARD_AUDIO_BITRATE}. */
+  audioBitrate?: string;
+  /** Audio sample rate Hz. Default 44100. */
+  sampleRate?: number;
+  /** Audio channels. Default 2. */
+  channels?: number;
+}
+
+/**
+ * Build the per-segment normalization ffmpeg args (PURE, WS9). Re-encodes one
+ * clip to the 3e segment standard (1280×720@24 / libx264 preset-fast crf20 / AAC
+ * 44100 stereo) while optionally trimming its tail ({@link trimTailArgs}) and
+ * letterboxing it onto a canvas ({@link letterboxFilter}). Re-encoding to the
+ * standard keeps the normalized segments uniform, so the demuxer `-c copy` concat
+ * stays valid. `-t` is placed just before the output path so it caps the OUTPUT.
+ */
+export function buildSegmentPrepArgs(
+  segment: string,
+  outputPath: string,
+  opts: BuildSegmentPrepOptions = {},
+): string[] {
+  const width = opts.width ?? 1280;
+  const height = opts.height ?? 720;
+  // Compose the vf chain in deterministic order: letterbox (geometry) → LUT
+  // (film-stock emulation) → named grade (state color). Each is optional; empties
+  // are dropped, so default behavior is no `-vf` at all.
+  const vf = [
+    letterboxFilter(opts.letterboxRatio, width, height),
+    opts.gradeLut ? `lut3d=${opts.gradeLut}` : '',
+    opts.gradeFilter ?? '',
+  ]
+    .filter((f) => f !== '')
+    .join(',');
+  const args: string[] = ['-i', segment];
+  if (vf) args.push('-vf', vf);
+  args.push(
+    '-r', String(opts.fps ?? 24),
+    '-c:v', 'libx264', '-preset', 'fast', '-crf', String(opts.crf ?? 20),
+    '-c:a', 'aac', '-b:a', opts.audioBitrate ?? STANDARD_AUDIO_BITRATE,
+    '-ar', String(opts.sampleRate ?? 44100), '-ac', String(opts.channels ?? 2),
+    '-movflags', '+faststart',
+  );
+  // -t (when set) just before the output path → caps the output duration.
+  args.push(...trimTailArgs(opts.clipMaxSeconds), outputPath);
+  return args;
+}
+
+export interface BuildMusicMixOptions {
+  /** Mix level for the music bed (0..1). Default {@link DEFAULT_MUSIC_VOLUME}. */
+  volume?: number;
+  /** Tail fade-out seconds. Default {@link DEFAULT_MUSIC_FADE_OUT_SEC}. */
+  fadeOutSec?: number;
+  /**
+   * Total video duration in seconds — used to compute the fade-out start
+   * (`total - fadeOut`) and the `-t` cap. The caller probes this via
+   * `ffprobeDuration`. Defaults to 0 (fade starts at 0 / `-t 0`), only used by
+   * the dry-run / pure-builder path where the duration is not yet known.
+   */
+  totalDurationSec?: number;
+}
+
+/** Format a number the way the Python f-strings do (`:.2f` / `:.3f`). */
+function fixed(value: number, digits: number): string {
+  return value.toFixed(digits);
+}
+
+/**
+ * Build the background-music mix ffmpeg args (PURE). Loops the music under the
+ * narration at a low volume with a tail fade-out, then mixes via amix.
+ *
+ * Ported VERBATIM from assembly_utils.add_background_music (L408-435):
+ *   -i video -stream_loop -1 -i music
+ *   -filter_complex "[0:a]volume=1.0[v];
+ *     [1:a]volume={vol},afade=t=out:st={fade_start}:d={fade_out}[m];
+ *     [v][m]amix=inputs=2:duration=first:dropout_transition=600:normalize=0[a]"
+ *   -map 0:v -map [a]
+ *   -c:v copy -c:a aac -b:a 192k
+ *   -movflags +faststart
+ *   -t {total} output
+ *
+ * fade_start = max(0, total - fade_out). `dropout_transition=600` prevents early
+ * audio cutoff on silent sections; `normalize=0` keeps the narration at full
+ * level while the music stays at `volume`.
+ */
+export function buildMusicMixArgs(
+  videoPath: string,
+  musicPath: string,
+  outputPath: string,
+  opts: BuildMusicMixOptions = {},
+): string[] {
+  const volume = opts.volume ?? DEFAULT_MUSIC_VOLUME;
+  const fadeOut = opts.fadeOutSec ?? DEFAULT_MUSIC_FADE_OUT_SEC;
+  const totalDur = opts.totalDurationSec ?? 0;
+  const fadeStart = Math.max(0, totalDur - fadeOut);
+
+  const filterComplex =
+    `[0:a]volume=1.0[v];` +
+    `[1:a]volume=${volume},afade=t=out:st=${fixed(fadeStart, 2)}:d=${fadeOut}[m];` +
+    `[v][m]amix=inputs=2:duration=first:dropout_transition=600:normalize=0[a]`;
+
+  return [
+    '-i',
+    videoPath,
+    '-stream_loop',
+    '-1',
+    '-i',
+    musicPath,
+    '-filter_complex',
+    filterComplex,
+    '-map',
+    '0:v',
+    '-map',
+    '[a]',
+    '-c:v',
+    'copy',
+    '-c:a',
+    'aac',
+    '-b:a',
+    STANDARD_AUDIO_BITRATE,
+    '-movflags',
+    '+faststart',
+    '-t',
+    fixed(totalDur, 3),
+    outputPath,
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Multi-layer audio mix
+// ---------------------------------------------------------------------------
+
+/**
+ * A single audio layer to mix under or alongside the video's native audio.
+ */
+export interface AudioLayer {
+  /** Path to the audio track file. */
+  trackPath: string;
+  /**
+   * Semantic role of this layer.
+   * - `'music'`     — background music bed (low volume, looped).
+   * - `'narration'` — voice-over narration track (full volume, no loop).
+   * - `'dialogue'`  — on-screen dialogue (full volume, no loop).
+   * - `'sfx'`       — sound-effect track (mixed alongside, NOT a ducking
+   *                   sidechain signal; does not by itself enable ducking).
+   */
+  role: 'music' | 'narration' | 'dialogue' | 'sfx';
+  /** Mix level (0..1). Defaults: music → {@link DEFAULT_MUSIC_VOLUME}, voice → 1.0. */
+  volume?: number;
+  /**
+   * Whether to loop this track to fill the video duration.
+   * Default: `true` for `music` layers, `false` for `narration`/`dialogue`.
+   */
+  loop?: boolean;
+}
+
+export interface BuildMultiLayerMixOptions {
+  /**
+   * When `true` AND at least one `narration`/`dialogue` layer is present,
+   * music layers are sidechained under the voice via `sidechaincompress`
+   * (threshold −12 dB / 0.25 linear, ratio 4:1, attack 5 ms, release 200 ms)
+   * so the music ducks automatically whenever voice is active.
+   * Falls back to static-volume amix when there are no voice layers.
+   * Default: `false`.
+   */
+  duckMusicUnderVoice?: boolean;
+  /**
+   * Global music-bed volume applied to every `music` layer that does not
+   * set its own `volume`. Individual `layer.volume` takes precedence.
+   * Default: {@link DEFAULT_MUSIC_VOLUME} (0.05).
+   */
+  musicVolume?: number;
+  /** Reserved for callers that need to override the ffmpeg binary path. */
+  ffmpegBin?: string;
+}
+
+/**
+ * Build ffmpeg args that mix the video's own audio together with N additional
+ * audio layers. **PURE** — returns only the arg-string array; never spawns
+ * processes, reads files, or has side-effects.
+ *
+ * ## Input numbering
+ * - Input 0 : the video file (carries video + its original audio).
+ * - Inputs 1…N : the supplied `layers`, in order.
+ *
+ * ## Filter graph — static-volume path (default)
+ * ```
+ * [1:a]volume=<v1>[l1]; [2:a]volume=<v2>[l2]; …
+ * [0:a][l1][l2]…amix=inputs=N+1:duration=first:dropout_transition=600:normalize=0[a]
+ * ```
+ *
+ * ## Filter graph — ducking path (`duckMusicUnderVoice=true` + voice layer present)
+ * ```
+ * per-layer volume chains as above …
+ * [voice_labels…]amix=…[voice]          (or direct passthrough for single voice)
+ * [voice]asplit=M+1[vs0]…[vsM-1][vsfinal]
+ * [l_music0][vs0]sidechaincompress=…[duck0]; [l_music1][vs1]sidechaincompress=…[duck1]; …
+ * [0:a][duck0][duck1]…[vsfinal][sfx…]amix=inputs=M+2+S:…[a]
+ * ```
+ * where M = number of music layers and S = number of sfx layers.
+ * SFX layers are mixed in at their own volume but are NEVER used as a
+ * sidechain signal and do NOT by themselves enable ducking (only
+ * `narration`/`dialogue` layers count as voice for the `duckMusicUnderVoice`
+ * gate).
+ *
+ * ## Output mapping
+ * `-map 0:v -map [a] -c:v copy -c:a aac -b:a 192k -movflags +faststart <output>`
+ */
+export function buildMultiLayerMixArgs(
+  videoPath: string,
+  layers: AudioLayer[],
+  outputPath: string,
+  opts: BuildMultiLayerMixOptions = {},
+): string[] {
+  if (layers.length === 0) {
+    throw new Error('buildMultiLayerMixArgs: at least one layer is required');
+  }
+
+  const doDuck = opts.duckMusicUnderVoice ?? false;
+  const globalMusicVol = opts.musicVolume ?? DEFAULT_MUSIC_VOLUME;
+
+  // ── Input args ────────────────────────────────────────────────────────────
+  // Video is always input 0. Each layer follows; music layers get -stream_loop.
+  const inputArgs: string[] = ['-i', videoPath];
+  for (const layer of layers) {
+    const shouldLoop = layer.loop ?? layer.role === 'music';
+    if (shouldLoop) inputArgs.push('-stream_loop', '-1');
+    inputArgs.push('-i', layer.trackPath);
+  }
+
+  // ── Per-layer volume chains ───────────────────────────────────────────────
+  // Build these first (index-stable); categorise into music vs voice labels.
+  const filterParts: string[] = [];
+  const allLayerLabels: string[] = [];   // [l1], [l2], … (in layer order)
+  const musicLayerLabels: string[] = []; // subset with role === 'music'
+  const voiceLayerLabels: string[] = []; // subset with role narration|dialogue
+  const sfxLayerLabels: string[] = [];   // subset with role === 'sfx' (mixed, never a sidechain)
+
+  for (let i = 0; i < layers.length; i += 1) {
+    const layer = layers[i];
+    const inputIdx = i + 1; // 0 is video
+    const label = `[l${inputIdx}]`;
+    allLayerLabels.push(label);
+
+    const vol =
+      layer.volume !== undefined
+        ? layer.volume
+        : layer.role === 'music'
+          ? globalMusicVol
+          : 1.0;
+
+    filterParts.push(`[${inputIdx}:a]volume=${vol}${label}`);
+
+    if (layer.role === 'music') {
+      musicLayerLabels.push(label);
+    } else if (layer.role === 'sfx') {
+      // SFX is mixed alongside everything else but must never serve as a
+      // sidechain signal and must not by itself enable music ducking.
+      sfxLayerLabels.push(label);
+    } else {
+      // narration | dialogue → genuine voice signal that drives ducking.
+      voiceLayerLabels.push(label);
+    }
+  }
+
+  const hasVoice = voiceLayerLabels.length > 0;
+  const hasMusic = musicLayerLabels.length > 0;
+
+  if (doDuck && hasVoice && hasMusic) {
+    // ── Sidechain-ducking path ──────────────────────────────────────────────
+    //
+    // Step 1: Merge all voice labels into a single [voice] stream.
+    //   - One voice label  → simple volume=1.0 passthrough (rename).
+    //   - Multiple labels  → amix down to mono [voice].
+    const voiceLabel = '[voice]';
+    if (voiceLayerLabels.length === 1) {
+      filterParts.push(`${voiceLayerLabels[0]}volume=1.0${voiceLabel}`);
+    } else {
+      const joined = voiceLayerLabels.join('');
+      filterParts.push(
+        `${joined}amix=inputs=${voiceLayerLabels.length}:duration=first:dropout_transition=600:normalize=0${voiceLabel}`,
+      );
+    }
+
+    // Step 2: asplit [voice] into M+1 copies:
+    //   [vs0]…[vsM-1] → one per music layer (sidechain signal)
+    //   [vsfinal]     → passed into the final amix so voice stays audible
+    const numMusicLayers = musicLayerLabels.length;
+    const totalSplits = numMusicLayers + 1;
+    const splitOutputLabels = Array.from(
+      { length: totalSplits },
+      (_, k) => (k < numMusicLayers ? `[vs${k}]` : '[vsfinal]'),
+    );
+    filterParts.push(`${voiceLabel}asplit=${totalSplits}${splitOutputLabels.join('')}`);
+
+    // Step 3: Sidechain-compress each music layer against its voice copy.
+    //   sidechaincompress: [main][sidechain] → [duckN]
+    const duckLabels: string[] = [];
+    for (let mi = 0; mi < numMusicLayers; mi += 1) {
+      const duckLabel = `[duck${mi}]`;
+      filterParts.push(
+        `${musicLayerLabels[mi]}[vs${mi}]sidechaincompress=threshold=0.25:ratio=4:attack=5:release=200${duckLabel}`,
+      );
+      duckLabels.push(duckLabel);
+    }
+
+    // Step 4: Final amix — video audio + all ducked music + the final voice
+    //   copy + any sfx layers (mixed at full/own volume, NOT ducked).
+    //   inputs = 1 (video) + M (ducked music) + 1 (vsfinal) + S (sfx)
+    const finalMixInputs = ['[0:a]', ...duckLabels, '[vsfinal]', ...sfxLayerLabels].join('');
+    const finalMixCount = 1 + duckLabels.length + 1 + sfxLayerLabels.length;
+    filterParts.push(
+      `${finalMixInputs}amix=inputs=${finalMixCount}:duration=first:dropout_transition=600:normalize=0[a]`,
+    );
+  } else {
+    // ── Static-volume amix path (default / legacy-compatible) ───────────────
+    // Mix: [0:a] + [l1] + [l2] + … → amix → [a]
+    const allInputs = ['[0:a]', ...allLayerLabels].join('');
+    const totalInputs = 1 + allLayerLabels.length;
+    filterParts.push(
+      `${allInputs}amix=inputs=${totalInputs}:duration=first:dropout_transition=600:normalize=0[a]`,
+    );
+  }
+
+  // ── Output args ───────────────────────────────────────────────────────────
+  return [
+    ...inputArgs,
+    '-filter_complex',
+    filterParts.join(';'),
+    '-map',
+    '0:v',
+    '-map',
+    '[a]',
+    '-c:v',
+    'copy',
+    '-c:a',
+    'aac',
+    '-b:a',
+    STANDARD_AUDIO_BITRATE,
+    '-movflags',
+    '+faststart',
+    outputPath,
+  ];
+}
+
+/**
+ * Compose the full ordered layer list for the multi-layer mix step: the
+ * `music` bed (if present) first as a looped `music` layer, then the extra
+ * `audioLayers` (dialogue/sfx/voice) in order. Pure. Only called when
+ * `input.audioLayers` is non-empty, so the result always has ≥1 layer.
+ */
+function combinedAudioLayers(input: StitchInput): AudioLayer[] {
+  const musicLayer: AudioLayer[] = input.music
+    ? [
+        {
+          trackPath: input.music.trackPath,
+          role: 'music',
+          loop: true,
+          ...(input.music.volume !== undefined ? { volume: input.music.volume } : {}),
+        },
+      ]
+    : [];
+  return [...musicLayer, ...(input.audioLayers ?? [])];
+}
+
+export interface StitchOptions extends RunFfmpegOptions {
+  /** Override the ffprobe binary (forwarded to `ffprobeDuration`). */
+  ffprobeBin?: string;
+  /**
+   * Skip the pre-concat MP4-validity guard. Default OFF (validation ON) for
+   * real runs. The guard probes each input segment with {@link isValidMp4} and
+   * fails fast on a truncated/no-moov MP4 instead of letting ffmpeg concat die
+   * with a cryptic "Invalid data found when processing input". Always skipped on
+   * dry-run (no real files to probe).
+   */
+  skipSegmentValidation?: boolean;
+}
+
+/**
+ * Orchestrate the stitch: write the concat list (demuxer path), pick the
+ * demuxer-vs-filter path, run via `runFfmpeg`, optionally mix a music bed, and
+ * return the final MP4 path + a plan of the executed command sequence.
+ *
+ * On `dryRun`, returns the planned command sequence WITHOUT writing the concat
+ * list, spawning ffmpeg, or probing durations (music fade-start is computed
+ * from 0). This is the path unit tests use.
+ *
+ * NOTE: the real-spawn path. The final-MP4 quality check is a HUMAN integration
+ * checkpoint — out of scope here.
+ */
+export async function stitch(
+  input: StitchInput,
+  opts: StitchOptions = {},
+): Promise<StitchResult> {
+  const segs = orderedSegments(input);
+  if (segs.length === 0) {
+    // Defensive: nothing to concat. Caller is expected to pass >=1 segment.
+    throw new Error('stitch: no segments to concatenate');
+  }
+
+  const strategy = selectConcatStrategy(input.concatStrategy ?? 'auto', segs.length);
+  const hasMusic = input.music !== undefined;
+  // Extra (dialogue/sfx/voice) global layers beyond the music bed. Presence
+  // here flips the mix step from the legacy single-music buildMusicMixArgs path
+  // to the multi-layer buildMultiLayerMixArgs path. Empty/undefined ⇒ legacy.
+  const hasExtraLayers = (input.audioLayers?.length ?? 0) > 0;
+  // Any audio mix at all (music bed and/or extra layers) requires the
+  // concat→intermediate→mix two-step. When neither is present, concat targets
+  // the final output directly (byte-identical legacy no-audio path).
+  const hasAudioMix = hasMusic || hasExtraLayers;
+  const concatListPath =
+    input.concatListPath ?? resolvePath(dirname(input.outputPath), 'concat.txt');
+
+  // When audio is mixed, concat writes an intermediate file and the mix step
+  // produces the final output (mirrors nex_assemble's concat_no_music.mp4).
+  const concatOutput = hasAudioMix
+    ? resolvePath(dirname(input.outputPath), 'concat_no_music.mp4')
+    : input.outputPath;
+
+  const plan: StitchPlannedStep[] = [];
+
+  // --- Optional per-segment normalization pre-pass (WS9) ---
+  // When a tail-cut or letterbox is requested, each ordered segment is
+  // re-encoded to the standard (dropping dead tail frames / adding cinematic
+  // bars) before concat; the concat then consumes the normalized clips. Default
+  // (neither field set) emits no prep steps and is byte-identical to legacy.
+  const hasGrade =
+    (typeof input.gradeLut === 'string' && input.gradeLut !== '') ||
+    (typeof input.gradeId === 'string' && input.gradeId !== '') ||
+    (input.segmentGradeIds?.some((g) => typeof g === 'string' && g !== '') ?? false);
+  const needsPrep =
+    (input.clipMaxSeconds !== undefined && input.clipMaxSeconds > 0) ||
+    (typeof input.letterboxRatio === 'string' && input.letterboxRatio !== '') ||
+    hasGrade;
+  const prepDir = resolvePath(dirname(input.outputPath), '.prep');
+  const concatSegs = needsPrep
+    ? segs.map((_, i) => resolvePath(prepDir, `seg-${String(i).padStart(3, '0')}.mp4`))
+    : segs;
+  if (needsPrep) {
+    segs.forEach((seg, i) => {
+      // Per-segment grade override realizes the narrative color language; falls
+      // back to the uniform gradeId.
+      const gradeFilter = resolveGradeFilter(input.segmentGradeIds?.[i] ?? input.gradeId);
+      plan.push({
+        kind: 'segment-prep',
+        args: buildSegmentPrepArgs(seg, concatSegs[i], {
+          clipMaxSeconds: input.clipMaxSeconds,
+          letterboxRatio: input.letterboxRatio,
+          width: input.letterboxCanvas?.width,
+          height: input.letterboxCanvas?.height,
+          gradeLut: input.gradeLut,
+          gradeFilter,
+        }),
+        outputPath: concatSegs[i],
+      });
+    });
+  }
+
+  // --- Concat step ---
+  const concatArgs =
+    strategy === 'demuxer'
+      ? buildConcatDemuxerArgs(concatSegs, concatListPath, concatOutput)
+      : buildConcatFilterArgs(concatSegs, concatOutput);
+  plan.push({
+    kind: strategy === 'demuxer' ? 'concat-demuxer' : 'concat-filter',
+    args: concatArgs,
+    outputPath: concatOutput,
+  });
+
+  // --- Audio-mix step (optional) ---
+  // Two mutually-exclusive paths:
+  //   * hasExtraLayers → multi-layer mix (music bed prepended + dialogue/sfx).
+  //   * music-only     → the EXACT legacy buildMusicMixArgs path (byte-identical).
+  // Neither ⇒ no mix step (legacy no-audio path).
+  if (hasExtraLayers) {
+    const layers = combinedAudioLayers(input);
+    const mixArgs = buildMultiLayerMixArgs(concatOutput, layers, input.outputPath);
+    plan.push({ kind: 'multi-layer-mix', args: mixArgs, outputPath: input.outputPath });
+  } else if (hasMusic && input.music) {
+    // The fade-start / -t cap need the concat duration; on dry-run we leave it 0.
+    const musicArgs = buildMusicMixArgs(concatOutput, input.music.trackPath, input.outputPath, {
+      volume: input.music.volume,
+      fadeOutSec: input.music.fadeOutSec,
+      totalDurationSec: 0,
+    });
+    plan.push({ kind: 'music-mix', args: musicArgs, outputPath: input.outputPath });
+  }
+
+  if (opts.dryRun) {
+    return {
+      status: 'dry-run',
+      outputPath: input.outputPath,
+      orderedSegments: segs,
+      concatStrategy: strategy,
+      music: hasMusic,
+      plan,
+      durationMs: 0,
+    };
+  }
+
+  // --- Pre-concat corruption guard ---
+  // useapi sometimes reports a generation 'complete' while the downloaded mp4
+  // is truncated (no moov atom): it passes existence/size checks but ffmpeg
+  // concat later dies with "Invalid data found when processing input". Probe
+  // each real input segment up front so the corrupt one is named clearly.
+  // Only the actual segment inputs are probed (not derived intermediates).
+  if (!opts.skipSegmentValidation) {
+    for (const seg of segs) {
+      const ok = await isValidMp4(seg, { ffprobeBin: opts.ffprobeBin });
+      if (!ok) {
+        throw new VclawError(
+          'ffmpeg_failed',
+          `stitch input segment is a corrupt or truncated MP4 (ffprobe could not read a valid duration): ${seg}`,
+          { segment: seg },
+        );
+      }
+    }
+  }
+
+  // --- Real execution ---
+  await mkdir(dirname(input.outputPath), { recursive: true });
+
+  // Per-segment normalization pre-pass: concat then reads the normalized clips.
+  if (needsPrep) {
+    await mkdir(prepDir, { recursive: true });
+    for (const step of plan) {
+      if (step.kind === 'segment-prep') await runFfmpeg(step.args, opts);
+    }
+  }
+
+  if (strategy === 'demuxer') {
+    await mkdir(dirname(concatListPath), { recursive: true });
+    await writeFile(concatListPath, buildConcatListContent(concatSegs), 'utf8');
+  }
+
+  await runFfmpeg(concatArgs, opts);
+
+  let finalPath = concatOutput;
+  if (hasExtraLayers) {
+    // Multi-layer mix: dialogue/sfx (+ optional music bed) over the concat.
+    // buildMultiLayerMixArgs uses duration=first (driven by the video input),
+    // so it needs no probed total — the args are already final from planning.
+    const mixStep = plan.find((s) => s.kind === 'multi-layer-mix');
+    const mixArgs = mixStep?.args ?? buildMultiLayerMixArgs(concatOutput, combinedAudioLayers(input), input.outputPath);
+    await runFfmpeg(mixArgs, opts);
+    finalPath = input.outputPath;
+  } else if (hasMusic && input.music) {
+    // Probe the concat output to compute the real fade-start + -t cap.
+    const concatMs = await ffprobeDuration(concatOutput, { ffprobeBin: opts.ffprobeBin });
+    const musicArgs = buildMusicMixArgs(concatOutput, input.music.trackPath, input.outputPath, {
+      volume: input.music.volume,
+      fadeOutSec: input.music.fadeOutSec,
+      totalDurationSec: concatMs / 1000,
+    });
+    // Refresh the plan's music step with the duration-resolved args.
+    const musicStep = plan.find((s) => s.kind === 'music-mix');
+    if (musicStep) musicStep.args = musicArgs;
+    await runFfmpeg(musicArgs, opts);
+    finalPath = input.outputPath;
+  }
+
+  const durationMs = await ffprobeDuration(finalPath, { ffprobeBin: opts.ffprobeBin });
+  // Touch stat so a 0-byte output surfaces as a runtime failure path-side.
+  await stat(finalPath);
+
+  return {
+    status: 'complete',
+    outputPath: finalPath,
+    orderedSegments: segs,
+    concatStrategy: strategy,
+    music: hasMusic,
+    plan,
+    durationMs,
+  };
+}