@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/tools/video/comfy-workflow-template.js

@@ -0,0 +1,194 @@
+/** Validation and pure patching for operator-exported ComfyUI API workflows. */
+const KEYFRAME_FLUX_CONTRACT = {
+    id: 'keyframe-flux',
+    required: [
+        { classType: 'CLIPTextEncode', count: 2 },
+        { classType: 'RandomNoise', count: 1 },
+        { classType: 'EmptySD3LatentImage', count: 1 },
+        { classType: 'SaveImage', count: 1 },
+    ],
+    roles: {
+        seed: [{ classType: 'RandomNoise', input: 'noise_seed' }],
+        prompt: [{ classType: 'CLIPTextEncode', input: 'text', title: 'Positive Prompt' }],
+        negative: [{ classType: 'CLIPTextEncode', input: 'text', title: 'Negative Prompt' }],
+        resolution: [
+            { classType: 'EmptySD3LatentImage', input: 'width' },
+            { classType: 'EmptySD3LatentImage', input: 'height' },
+        ],
+        outputPrefix: [{ classType: 'SaveImage', input: 'filename_prefix' }],
+    },
+};
+const I2V_BASE_REQUIRED = [
+    { classType: 'WanVideoModelLoader', count: 2 },
+    { classType: 'WanVideoSampler', count: 2 },
+    { classType: 'WanVideoImageToVideoEncode', count: 1 },
+    { classType: 'WanVideoTextEncode', count: 1 },
+    { classType: 'LoadImage', count: 1 },
+    { classType: 'VHS_VideoCombine', count: 1 },
+];
+const I2V_BASE_ROLES = {
+    seed: [{ classType: 'WanVideoSampler', input: 'seed', all: true }],
+    prompt: [{ classType: 'WanVideoTextEncode', input: 'positive_prompt' }],
+    negative: [{ classType: 'WanVideoTextEncode', input: 'negative_prompt' }],
+    inputImage: [{ classType: 'LoadImage', input: 'image' }],
+    frames: [{ classType: 'WanVideoImageToVideoEncode', input: 'num_frames' }],
+    resolution: [
+        { classType: 'WanVideoImageToVideoEncode', input: 'width' },
+        { classType: 'WanVideoImageToVideoEncode', input: 'height' },
+    ],
+    outputPrefix: [{ classType: 'VHS_VideoCombine', input: 'filename_prefix' }],
+};
+export const KEYFRAME_FLUX_TEMPLATE_CONTRACT = KEYFRAME_FLUX_CONTRACT;
+export const I2V_WAN_LIGHTX2V_TEMPLATE_CONTRACT = {
+    id: 'i2v-wan-lightx2v', required: I2V_BASE_REQUIRED, roles: I2V_BASE_ROLES,
+};
+export const I2V_WAN_FLF2V_TEMPLATE_CONTRACT = {
+    id: 'i2v-wan-flf2v',
+    required: I2V_BASE_REQUIRED.map((requirement) => (requirement.classType === 'LoadImage' ? { ...requirement, count: 2 } : requirement)),
+    roles: {
+        ...I2V_BASE_ROLES,
+        inputImage: [{ classType: 'LoadImage', input: 'image', title: 'Start Image' }],
+        endImage: [{ classType: 'LoadImage', input: 'image', title: 'End Image' }],
+    },
+};
+export const UPSCALE_SEEDVR2_TEMPLATE_CONTRACT = {
+    id: 'upscale-seedvr2',
+    required: [
+        { classType: 'VHS_LoadVideo', count: 1 },
+        { classType: 'SeedVR2LoadDiTModel', count: 1 },
+        { classType: 'SeedVR2LoadVAEModel', count: 1 },
+        { classType: 'SeedVR2VideoUpscaler', count: 1 },
+        { classType: 'VHS_VideoCombine', count: 1 },
+    ],
+    roles: {
+        seed: [{ classType: 'SeedVR2VideoUpscaler', input: 'seed' }],
+        inputVideo: [{ classType: 'VHS_LoadVideo', input: 'video' }],
+        frames: [{ classType: 'SeedVR2VideoUpscaler', input: 'batch_size' }],
+        resolution: [{ classType: 'SeedVR2VideoUpscaler', input: 'resolution' }],
+        outputPrefix: [{ classType: 'VHS_VideoCombine', input: 'filename_prefix' }],
+    },
+};
+export const INTERPOLATE_RIFE_TEMPLATE_CONTRACT = {
+    id: 'interpolate-rife',
+    required: [
+        { classType: 'VHS_LoadVideo', count: 1 },
+        { classType: 'RIFE VFI', count: 1 },
+        { classType: 'VHS_VideoCombine', count: 1 },
+    ],
+    roles: {
+        inputVideo: [{ classType: 'VHS_LoadVideo', input: 'video' }],
+        frames: [{ classType: 'RIFE VFI', input: 'multiplier' }],
+        outputPrefix: [{ classType: 'VHS_VideoCombine', input: 'filename_prefix' }],
+    },
+};
+export const TEMPLATE_CONTRACTS = {
+    'keyframe-flux': KEYFRAME_FLUX_TEMPLATE_CONTRACT,
+    'i2v-wan-lightx2v': I2V_WAN_LIGHTX2V_TEMPLATE_CONTRACT,
+    'i2v-wan-flf2v': I2V_WAN_FLF2V_TEMPLATE_CONTRACT,
+    'upscale-seedvr2': UPSCALE_SEEDVR2_TEMPLATE_CONTRACT,
+    'interpolate-rife': INTERPOLATE_RIFE_TEMPLATE_CONTRACT,
+};
+function cloneGraph(graph) {
+    return structuredClone(graph);
+}
+function parseGraph(json) {
+    if (!json || typeof json !== 'object' || Array.isArray(json)) {
+        throw new Error('ComfyUI API workflow must be an object keyed by node id');
+    }
+    const graph = json;
+    if (Object.keys(graph).length === 0)
+        throw new Error('ComfyUI API workflow must contain nodes');
+    for (const [nodeId, candidate] of Object.entries(graph)) {
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            throw new Error(`ComfyUI API workflow node ${nodeId} must be an object`);
+        }
+        const node = candidate;
+        if (typeof node.class_type !== 'string' || !node.class_type.trim()) {
+            throw new Error(`ComfyUI API workflow node ${nodeId} is missing class_type`);
+        }
+        if (!node.inputs || typeof node.inputs !== 'object' || Array.isArray(node.inputs)) {
+            throw new Error(`ComfyUI API workflow node ${nodeId} is missing inputs`);
+        }
+    }
+    return cloneGraph(graph);
+}
+function nodesOfClass(graph, classType) {
+    return Object.entries(graph).filter((entry) => entry[1].class_type === classType);
+}
+export function loadWorkflowTemplate(json, contract) {
+    const graph = parseGraph(json);
+    for (const requirement of contract.required) {
+        const actual = nodesOfClass(graph, requirement.classType).length;
+        if (actual !== requirement.count) {
+            throw new Error(`Template ${contract.id} requires exactly ${requirement.count} ${requirement.classType} node(s); found ${actual}`);
+        }
+    }
+    const roleBindings = {};
+    for (const [role, selectors] of Object.entries(contract.roles)) {
+        const bindings = [];
+        for (const selector of selectors) {
+            let candidates = nodesOfClass(graph, selector.classType);
+            if (selector.title) {
+                candidates = candidates.filter(([, node]) => node._meta?.title === selector.title);
+            }
+            else if (!selector.all && candidates.length > 1) {
+                throw new Error(`Template ${contract.id} role ${role} is ambiguous for ${selector.classType}; disambiguate with _meta.title`);
+            }
+            if (candidates.length === 0) {
+                throw new Error(`Template ${contract.id} cannot resolve role ${role} to ${selector.classType}` +
+                    (selector.title ? ` titled "${selector.title}"` : ''));
+            }
+            for (const [nodeId, node] of candidates) {
+                if (!(selector.input in node.inputs)) {
+                    throw new Error(`Template ${contract.id} role ${role} expects input ${selector.input} on node ${nodeId} (${selector.classType})`);
+                }
+                bindings.push({ nodeId, input: selector.input });
+            }
+        }
+        roleBindings[role] = bindings;
+    }
+    return { graph, contract, roleBindings };
+}
+function assertInteger(value, role) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${role} patch must be a non-negative safe integer`);
+}
+export function patchWorkflow(template, patches) {
+    const graph = cloneGraph(template.graph);
+    for (const patch of patches) {
+        const bindings = template.roleBindings[patch.role];
+        if (!bindings || bindings.length === 0) {
+            throw new Error(`Template ${template.contract.id} does not resolve patch role ${patch.role}`);
+        }
+        if (patch.role === 'seed' || patch.role === 'frames')
+            assertInteger(patch.value, patch.role);
+        if (patch.role === 'resolution') {
+            const dimensions = typeof patch.value === 'number'
+                ? { width: patch.value, height: patch.value }
+                : patch.value;
+            assertInteger(dimensions.width, 'resolution width');
+            assertInteger(dimensions.height, 'resolution height');
+            for (const binding of bindings) {
+                const node = graph[binding.nodeId];
+                node.inputs[binding.input] = binding.input === 'height' ? dimensions.height : dimensions.width;
+            }
+            continue;
+        }
+        for (const binding of bindings)
+            graph[binding.nodeId].inputs[binding.input] = patch.value;
+    }
+    return graph;
+}
+export function assertAllSeedsPinned(graph) {
+    for (const [nodeId, node] of Object.entries(graph)) {
+        for (const input of ['seed', 'noise_seed']) {
+            if (!(input in node.inputs))
+                continue;
+            const value = node.inputs[input];
+            if (!Number.isSafeInteger(value) || value < 0) {
+                throw new Error(`ComfyUI workflow seed ${nodeId}.${input} must be explicitly pinned to a non-negative integer`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=comfy-workflow-template.js.map

package/dist/tools/video/describe-frame.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Frame describer — turns a single keyframe into text, local-first ($0).
+ *
+ * Reuses the same local-VLM path as the sensory vision reaction
+ * (`loadImageFromFile` + `buildMultimodalContent` + `CodeBuddyClient.chat` against
+ * Ollama, `CODEBUDDY_VISION_MODEL`, default moondream). For **code on screen** an
+ * optional OCR pass (`OcrTool`, tesseract) is layered in — OCR reads source code far
+ * more faithfully than a vision description does, so when `withOcr` is on the OCR
+ * text is prepended as literal evidence and the VLM prose follows as context.
+ *
+ * The VLM call and the OCR call are both injectable so the orchestrator's fusion is
+ * fully unit-testable without a real Ollama/tesseract. Never throws — any failure
+ * degrades to whatever partial text we have (possibly `''`).
+ *
+ * @module tools/video/describe-frame
+ */
+export interface DescribeFrameDeps {
+    /** Injectable VLM describer (default: local Ollama vision model). */
+    analyze?: (imagePath: string, prompt: string) => Promise<string>;
+    /** Injectable OCR (default: `OcrTool`/tesseract). */
+    ocr?: (imagePath: string, language: string) => Promise<string>;
+    /** Also run OCR and prepend the on-screen text (best for code screencasts). */
+    withOcr?: boolean;
+    /** OCR language code when `withOcr` is on (default 'eng'). */
+    ocrLanguage?: string;
+    /** Override the vision model id (default `CODEBUDDY_VISION_MODEL` / moondream). */
+    visionModel?: string;
+    /** Override the vision base URL (default `CODEBUDDY_VISION_BASE_URL` / local Ollama). */
+    visionBaseURL?: string;
+}
+/**
+ * Describe one keyframe → a compact text of what is SHOWN. Runs the VLM, and when
+ * `withOcr` is set also runs OCR and prepends the on-screen text as literal evidence.
+ * Never throws; returns `''` when nothing could be produced.
+ */
+export declare function describeFrame(imagePath: string, prompt?: string, deps?: DescribeFrameDeps): Promise<string>;

package/dist/tools/video/describe-frame.js

@@ -0,0 +1,68 @@
+/**
+ * Frame describer — turns a single keyframe into text, local-first ($0).
+ *
+ * Reuses the same local-VLM path as the sensory vision reaction
+ * (`loadImageFromFile` + `buildMultimodalContent` + `CodeBuddyClient.chat` against
+ * Ollama, `CODEBUDDY_VISION_MODEL`, default moondream). For **code on screen** an
+ * optional OCR pass (`OcrTool`, tesseract) is layered in — OCR reads source code far
+ * more faithfully than a vision description does, so when `withOcr` is on the OCR
+ * text is prepended as literal evidence and the VLM prose follows as context.
+ *
+ * The VLM call and the OCR call are both injectable so the orchestrator's fusion is
+ * fully unit-testable without a real Ollama/tesseract. Never throws — any failure
+ * degrades to whatever partial text we have (possibly `''`).
+ *
+ * @module tools/video/describe-frame
+ */
+import { logger } from '../../utils/logger.js';
+const DEFAULT_PROMPT = "Décris précisément ce qui est montré à l'écran en une à deux phrases : s'il s'agit d'un éditeur de code, d'un terminal, d'un navigateur, d'un diagramme, et ce qui y apparaît d'important.";
+/** Default VLM describer — mirrors `sensory/vision-reaction.ts::defaultAnalyze`. */
+async function defaultAnalyze(imagePath, prompt, visionModel, visionBaseURL) {
+    try {
+        const { loadImageFromFile, buildMultimodalContent } = await import('../image-input.js');
+        const { CodeBuddyClient } = await import('../../codebuddy/client.js');
+        const img = await loadImageFromFile(imagePath);
+        const content = buildMultimodalContent(prompt, [img]);
+        const model = visionModel || process.env.CODEBUDDY_VISION_MODEL || 'moondream';
+        const baseURL = visionBaseURL || process.env.CODEBUDDY_VISION_BASE_URL || 'http://127.0.0.1:11434/v1';
+        const client = new CodeBuddyClient(process.env.OLLAMA_API_KEY || 'ollama', model, baseURL);
+        const resp = await client.chat([{ role: 'user', content }], []);
+        return (resp?.choices?.[0]?.message?.content ?? '').trim();
+    }
+    catch (err) {
+        logger.warn(`[video] frame VLM describe failed: ${err instanceof Error ? err.message : String(err)}`);
+        return '';
+    }
+}
+/** Default OCR — lazy `OcrTool` (tesseract). Returns `''` on any failure. */
+async function defaultOcr(imagePath, language) {
+    try {
+        const { OcrTool } = await import('../vision/ocr-tool.js');
+        const text = await OcrTool.getInstance().extractText(imagePath, language);
+        return text.trim();
+    }
+    catch (err) {
+        logger.debug(`[video] frame OCR failed: ${err instanceof Error ? err.message : String(err)}`);
+        return '';
+    }
+}
+/**
+ * Describe one keyframe → a compact text of what is SHOWN. Runs the VLM, and when
+ * `withOcr` is set also runs OCR and prepends the on-screen text as literal evidence.
+ * Never throws; returns `''` when nothing could be produced.
+ */
+export async function describeFrame(imagePath, prompt = DEFAULT_PROMPT, deps = {}) {
+    const analyze = deps.analyze ?? ((p, q) => defaultAnalyze(p, q, deps.visionModel, deps.visionBaseURL));
+    const ocrLanguage = deps.ocrLanguage ?? 'eng';
+    const [desc, ocrText] = await Promise.all([
+        analyze(imagePath, prompt).catch(() => ''),
+        deps.withOcr ? (deps.ocr ?? defaultOcr)(imagePath, ocrLanguage).catch(() => '') : Promise.resolve(''),
+    ]);
+    const parts = [];
+    if (ocrText)
+        parts.push(`Texte à l'écran (OCR):\n${ocrText}`);
+    if (desc)
+        parts.push(deps.withOcr && ocrText ? `Description: ${desc}` : desc);
+    return parts.join('\n\n').trim();
+}
+//# sourceMappingURL=describe-frame.js.map

package/dist/tools/video/film-assemble.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Film assembly — chain multiple video clips into ONE longer film with
+ * transitions, then optionally lay a background-music track (with ducking)
+ * and a voiceover over the whole thing.
+ *
+ * This is the montage brick that `video_generate` never had: it takes the
+ * short clips produced by the media backend (or any local mp4s) and welds
+ * them into a coherent long-form video via a single ffmpeg `filter_complex`
+ * pass.
+ *
+ * Design (mirrors `frame-sample.ts`):
+ *  - Every OS-touching bit (spawn / ffprobe / gl-filter probe) is injectable.
+ *  - The argv/filter-graph builders are PURE and unit-testable — no ffmpeg
+ *    needed to assert the cumulative xfade offsets or the normalize chain.
+ *  - Fail-open: a missing ffmpeg, an unprobeable clip, or a dead render
+ *    returns a structured `success:false` result — it never throws.
+ *
+ * Two transition engines, selectable at call time:
+ *  - `xfade` (default): the native ffmpeg `xfade` (video) + `acrossfade`
+ *    (audio) filters — ~50 built-in transitions, zero extra dependency.
+ *  - `gl`: the `gltransition` filter (ffmpeg-gl-transition) IF the local
+ *    ffmpeg was built with it — otherwise it falls back to `xfade` with a
+ *    warning. We never build a custom ffmpeg or add a native dependency.
+ *
+ * The crossfade math (the heart, unit-tested): for normalized clip durations
+ * d0..dn and per-boundary transition durations T0..T_{n-2},
+ *   offset_k = (Σ_{i=0..k} d_i) − (Σ_{i=0..k} T_i)
+ * and the final film duration ≈ Σ d_i − Σ T_k. Normalization (same
+ * W×H / fps / SAR / pix_fmt / sample-rate) MUST run first or xfade errors.
+ *
+ * @module tools/video/film-assemble
+ */
+import { spawn as realSpawn } from 'child_process';
+export type TransitionEngine = 'xfade' | 'gl';
+export type FilmFit = 'contain' | 'cover';
+/** ffprobe result for a single input clip. */
+export interface ClipProbe {
+    path: string;
+    /** Duration in seconds (0 when unknown — the clip is then treated as absent). */
+    duration: number;
+    width: number | null;
+    height: number | null;
+    fps: number | null;
+    hasAudio: boolean;
+    sar: string | null;
+    pixFmt: string | null;
+}
+/** A single transition between two adjacent clips. */
+export interface TransitionSpec {
+    /** xfade transition name (fade, wipeleft, slideup, circleopen, dissolve…) or 'cut'. */
+    type: string;
+    /** Transition duration in seconds (0 ⇒ hard cut). */
+    duration: number;
+}
+export interface OutputProfile {
+    width: number;
+    height: number;
+    fps: number;
+}
+export interface LoudnormMasteringOptions {
+    targetLufs?: number;
+    truePeakDb?: number;
+    lra?: number;
+}
+export interface LoudnormMeasurement {
+    inputI: number;
+    inputTruePeakDb: number;
+    inputLra: number;
+    inputThreshold: number;
+    targetOffset: number;
+}
+export interface AssembleFilmInput {
+    /** Ordered clip paths to weld together. */
+    clips: string[];
+    /** A single transition name applied at every boundary, or one spec per boundary. */
+    transitions?: string | TransitionSpec[];
+    /** Default per-boundary transition duration in seconds (default 1). */
+    transitionDuration?: number;
+    /** Transition engine (default 'xfade'). */
+    engine?: TransitionEngine;
+    /** Output short-side preset ('1080p', '720p', …) or explicit 'WxH'. */
+    resolution?: string;
+    /** Output aspect ratio ('16:9', '9:16', '1:1', …). */
+    aspectRatio?: string;
+    /** Output frame rate (default: first clip's fps, else 30). */
+    fps?: number;
+    /** Fit clips inside the target canvas: letterbox (`contain`) or center-crop (`cover`). */
+    fit?: FilmFit;
+    /** Optional background music path (looped + trimmed to film length). */
+    music?: string;
+    /** Music volume 0..1 (default 0.25). */
+    musicVolume?: number;
+    /** Duck the music under dialogue/voiceover (default true when music present). */
+    ducking?: boolean;
+    /** Optional full-length voiceover/narration path (mixed at full volume). */
+    voiceover?: string;
+    /** Optional two-pass loudness mastering, applied to the assembled program output. */
+    mastering?: LoudnormMasteringOptions;
+    /** Optional .cube grade, applied to the assembled program output. */
+    lut?: {
+        path: string;
+    };
+    /** Explicit output path; otherwise auto-generated under .codebuddy/media-generation/films/. */
+    output?: string;
+    /** Project root (default cwd). */
+    rootDir?: string;
+    /** Film name (used for the auto output filename + sidecar). */
+    name?: string;
+}
+export interface AssembleFilmDeps {
+    spawn?: typeof realSpawn;
+    ffmpegBin?: string;
+    ffprobeBin?: string;
+    createId?: () => string;
+    /** Injectable probe (tests) — bypasses ffprobe. */
+    probeClips?: (paths: string[]) => Promise<ClipProbe[]>;
+    /** Injectable gl-transition availability probe (tests). */
+    detectGl?: () => Promise<boolean>;
+    /** Render timeout in ms (default 30 min). */
+    timeoutMs?: number;
+}
+export interface AssembleFilmResult {
+    kind: 'film_assemble_result';
+    success: boolean;
+    outputPath?: string;
+    /** `MEDIA:<path>` marker consumed by the media library, mirroring video_generate. */
+    mediaPath?: string;
+    engine: TransitionEngine;
+    clipCount: number;
+    transitionCount: number;
+    targetWidth: number;
+    targetHeight: number;
+    fps: number;
+    /** Σd − ΣT, computed from the probed clip durations. */
+    estimatedDuration: number;
+    /** ffprobe duration of the actual render (when it succeeded). */
+    probedDuration?: number;
+    hasAudio: boolean;
+    /** Measured on the final encoded file, never inferred from pass 2. */
+    outputLoudness?: {
+        integratedLufs: number;
+        truePeakDbtp: number;
+        targetLufs: number;
+        toleranceLu: number;
+        maxTruePeakDbtp: number;
+    };
+    transitions: TransitionSpec[];
+    warnings: string[];
+    error?: string;
+}
+/** The commonly-available ffmpeg `xfade` transitions (pass-through, for validation/hints). */
+export declare const XFADE_TRANSITIONS: readonly string[];
+/** Parse the JSON object printed by ffmpeg's first loudnorm pass. */
+export declare function parseLoudnormMeasurement(output: string): LoudnormMeasurement;
+/** Build the complete second-pass loudnorm argv for an assembled master. */
+export declare function buildLoudnormPass2Args(source: string, destination: string, measurement: LoudnormMeasurement, options?: LoudnormMasteringOptions, videoFilter?: string): string[];
+/** Escape a filesystem path for use as a lut3d filename inside a filtergraph. */
+export declare function buildLut3dFilter(lutPath: string): string;
+/**
+ * Cumulative xfade offsets — THE core formula.
+ * `offset_k = Σ(d[0..k]) − Σ(T[0..k])`, one per boundary (n−1 total).
+ */
+export declare function computeXfadeOffsets(durations: number[], transitions: number[]): number[];
+/** Duration of a timeline after subtracting every effective crossfade. */
+export declare function computeCrossfadedDuration(durations: number[], transitions: number[]): number;
+/**
+ * Normalize the `transitions` input into exactly `boundaries` specs, then clamp
+ * each transition duration so it fits inside both adjacent clips (xfade requires
+ * the crossfade region to live within both). Returns clamped specs + warnings.
+ */
+export declare function normalizeTransitions(transitions: string | TransitionSpec[] | undefined, boundaries: number, defaultDuration: number, durations: number[]): {
+    specs: TransitionSpec[];
+    warnings: string[];
+};
+/** Parse '1080p' / '720p' / '4k' / 'WxH' + aspect ratio into an even-dimensioned target. */
+export declare function resolveOutputProfile(input: Pick<AssembleFilmInput, 'resolution' | 'aspectRatio' | 'fps'>, probes: ClipProbe[]): OutputProfile;
+/** Per-input video normalization filter → label `[v{i}]` (pure). */
+export declare function buildVideoNormalizeSegment(index: number, profile: OutputProfile, fit?: FilmFit): string;
+/** Per-input audio normalization filter → label `[a{i}]` (pure). `audioRef` is `<inputIdx>:a`. */
+export declare function buildAudioNormalizeSegment(index: number, audioRef: string): string;
+/**
+ * Build the video half of the filter graph after normalization: an xfade chain
+ * (engine xfade/gl) or a hard-cut concat. Returns the segments + the final label.
+ */
+export declare function buildVideoGraph(n: number, specs: TransitionSpec[], offsets: number[], glFilter: string | null): {
+    segments: string[];
+    finalLabel: string;
+};
+/**
+ * Build the audio half: crossfade (acrossfade) chain mirroring the video xfade,
+ * or a concat for the all-hard-cut case. Returns segments + final label.
+ */
+export declare function buildClipAudioGraph(n: number, specs: TransitionSpec[]): {
+    segments: string[];
+    finalLabel: string;
+};
+/**
+ * Layer voiceover + ducked background music over the assembled clip audio.
+ * `baseLabel` is the crossfaded clip audio; `voiceRef`/`musicRef` are `<idx>:a`.
+ * Returns the extra segments + the final audio label.
+ */
+export declare function buildAudioMixGraph(baseLabel: string, opts: {
+    voiceRef?: string;
+    musicRef?: string;
+    musicVolume: number;
+    ducking: boolean;
+    totalDuration: number;
+}): {
+    segments: string[];
+    finalLabel: string;
+};
+export interface FilmArgvPlan {
+    args: string[];
+    videoLabel: string;
+    audioLabel: string;
+    filterComplex: string;
+}
+/**
+ * Build the complete ffmpeg argv for a film assembly. Pure: given the probes +
+ * resolved options it returns the exact command, with no I/O. This is the main
+ * unit-test seam.
+ */
+export declare function buildFilmArgs(probes: ClipProbe[], profile: OutputProfile, specs: TransitionSpec[], opts: {
+    ffmpegBin: string;
+    outputPath: string;
+    engine: TransitionEngine;
+    glFilter: string | null;
+    music?: string;
+    musicVolume: number;
+    ducking: boolean;
+    voiceover?: string;
+    fit?: FilmFit;
+}): FilmArgvPlan;
+export declare function assembleFilm(input: AssembleFilmInput, deps?: AssembleFilmDeps): Promise<AssembleFilmResult>;