@kitsra/kavio-ffmpeg 0.1.0

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these
+terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import type { CompositionTiming, KavioAudioAsset, KavioAudioTrack, KavioExportPreset, KavioFit, KavioVideoAsset, KavioVideoCrop, KavioVideoLayer } from "@kitsra/kavio-schema";
+export type FfmpegPlanStepKind = "input" | "filter" | "map" | "output" | "argument";
+export interface FfmpegPlan {
+    steps: FfmpegPlanStep[];
+}
+interface FfmpegPlanStepBase {
+    id: string;
+    kind: FfmpegPlanStepKind;
+    description: string;
+    args: string[];
+    notes?: string[];
+}
+export interface FfmpegInputPlanStep extends FfmpegPlanStepBase {
+    kind: "input";
+    inputIndex: number;
+    source: string;
+}
+export interface FfmpegFilterPlanStep extends FfmpegPlanStepBase {
+    kind: "filter";
+    chains: FfmpegFilterChain[];
+}
+export interface FfmpegMapPlanStep extends FfmpegPlanStepBase {
+    kind: "map";
+    labels: string[];
+}
+export interface FfmpegOutputPlanStep extends FfmpegPlanStepBase {
+    kind: "output";
+    target: string;
+}
+export interface FfmpegArgumentPlanStep extends FfmpegPlanStepBase {
+    kind: "argument";
+}
+export type FfmpegPlanStep = FfmpegInputPlanStep | FfmpegFilterPlanStep | FfmpegMapPlanStep | FfmpegOutputPlanStep | FfmpegArgumentPlanStep;
+export interface FfmpegDimensions {
+    width: number;
+    height: number;
+}
+export interface FfmpegFilterChain {
+    inputLabels: string[];
+    filters: string[];
+    outputLabel: string;
+    expression: string;
+}
+export interface FfmpegBaseVideoPlanOptions {
+    asset: Pick<KavioVideoAsset, "src" | "trimStartFrames" | "trimEndFrames" | "loop">;
+    layer: Pick<KavioVideoLayer, "id" | "asset" | "durationFrames" | "fit" | "crop" | "playbackRate">;
+    output: FfmpegDimensions | Pick<CompositionTiming, "width" | "height"> | Pick<KavioExportPreset, "width" | "height">;
+    fps: number;
+    inputIndex?: number;
+    inputLabel?: string;
+    outputLabel?: string;
+    background?: string;
+}
+export interface FfmpegBaseVideoSequencePlanOptions {
+    segments: FfmpegBaseVideoPlanOptions[];
+    outputLabel?: string;
+}
+export interface FfmpegInputTrimOptions {
+    source: string;
+    startFrame?: number;
+    durationFrames?: number;
+    fps: number;
+}
+export interface FfmpegFitFilterOptions {
+    dimensions: FfmpegDimensions;
+    fit?: KavioFit;
+    crop?: KavioVideoCrop;
+    background?: string;
+}
+export interface FfmpegOverlayCompositingOptions {
+    baseLabel: string;
+    overlayLabel: string;
+    outputLabel?: string;
+    x?: string | number;
+    y?: string | number;
+    startFrame?: number;
+    durationFrames?: number;
+    fps?: number;
+    shortest?: boolean;
+}
+export interface FfmpegOverlayFrameInputOptions {
+    framePattern: string;
+    fps: number;
+    inputIndex?: number;
+    inputLabel?: string;
+    outputLabel?: string;
+    startNumber?: number;
+}
+export interface FfmpegOverlayCompositingPlanOptions {
+    baseLabel: string;
+    frames: FfmpegOverlayFrameInputOptions;
+    outputLabel?: string;
+    x?: string | number;
+    y?: string | number;
+    startFrame?: number;
+    durationFrames?: number;
+    fps?: number;
+    shortest?: boolean;
+}
+export interface FfmpegConcatFilterOptions {
+    segmentLabels: string[];
+    outputLabel?: string;
+}
+export interface FfmpegAudioTrackPlanOptions {
+    asset: Pick<KavioAudioAsset | KavioVideoAsset, "src" | "trimStartFrames" | "trimEndFrames" | "loop">;
+    track: Pick<KavioAudioTrack, "id" | "asset" | "role" | "startFrame" | "durationFrames" | "offsetFrames" | "volume" | "fadeInFrames" | "fadeOutFrames" | "loop" | "duck">;
+    inputIndex?: number;
+    inputLabel?: string;
+    outputLabel?: string;
+}
+export interface FfmpegAudioMixPlanOptions {
+    tracks: FfmpegAudioTrackPlanOptions[];
+    fps: number;
+    outputLabel?: string;
+    normalizeLoudness?: boolean | FfmpegLoudnessNormalizationOptions;
+}
+export interface FfmpegLoudnessNormalizationOptions {
+    integratedLufs?: number;
+    truePeakDb?: number;
+    loudnessRange?: number;
+}
+export declare function createEmptyPlan(): FfmpegPlan;
+export declare function appendPlanStep(plan: FfmpegPlan, step: FfmpegPlanStep): FfmpegPlan;
+export declare function renderFfmpegArgs(plan: FfmpegPlan): string[];
+export declare function framesToSeconds(frames: number, fps: number): number;
+export declare function formatFfmpegTimestamp(seconds: number): string;
+export declare function buildInputTrimArgs(options: FfmpegInputTrimOptions): string[];
+export declare function buildFitVideoFilters(options: FfmpegFitFilterOptions): string[];
+export declare function buildBaseVideoFilterChain(options: FfmpegBaseVideoPlanOptions): FfmpegFilterChain;
+export declare function planBaseVideo(options: FfmpegBaseVideoPlanOptions): FfmpegPlan;
+export declare function planBaseVideoSequence(options: FfmpegBaseVideoSequencePlanOptions): FfmpegPlan;
+export declare function buildOverlayCompositingFilterChain(options: FfmpegOverlayCompositingOptions): FfmpegFilterChain;
+export declare function buildOverlayCompositingArgs(options: FfmpegOverlayCompositingOptions): string[];
+export declare function buildOverlayFrameInputArgs(options: FfmpegOverlayFrameInputOptions): string[];
+export declare function buildOverlayFrameFilterChain(options: FfmpegOverlayFrameInputOptions): FfmpegFilterChain;
+export declare function planOverlayCompositing(options: FfmpegOverlayCompositingPlanOptions): FfmpegPlan;
+export declare function buildConcatFilterChain(options: FfmpegConcatFilterOptions): FfmpegFilterChain;
+export declare function buildAudioMixFilterChains(options: FfmpegAudioMixPlanOptions): FfmpegFilterChain[];
+export declare function planAudioMix(options: FfmpegAudioMixPlanOptions): FfmpegPlan;
+export declare function buildFilterComplexArgs(chains: FfmpegFilterChain[]): string[];
+export declare function createInputStep(options: {
+    id: string;
+    description: string;
+    args: string[];
+    inputIndex: number;
+    source: string;
+    notes?: string[];
+}): FfmpegInputPlanStep;
+export declare function createFilterStep(options: {
+    id: string;
+    description: string;
+    chains: FfmpegFilterChain[];
+    notes?: string[];
+}): FfmpegFilterPlanStep;
+export declare function createMapStep(options: {
+    id: string;
+    description: string;
+    labels: string[];
+    notes?: string[];
+}): FfmpegMapPlanStep;
+export declare function createOutputStep(options: {
+    id: string;
+    description: string;
+    target: string;
+    args?: string[];
+    notes?: string[];
+}): FfmpegOutputPlanStep;
+export declare function createArgumentStep(options: {
+    id: string;
+    description: string;
+    args: string[];
+    notes?: string[];
+}): FfmpegArgumentPlanStep;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,691 @@
+export function createEmptyPlan() {
+    return { steps: [] };
+}
+export function appendPlanStep(plan, step) {
+    return { steps: [...plan.steps, step] };
+}
+export function renderFfmpegArgs(plan) {
+    return plan.steps.flatMap((step) => step.args);
+}
+export function framesToSeconds(frames, fps) {
+    assertNonNegativeFrame(frames, "frames");
+    assertPositiveFiniteNumber(fps, "fps");
+    return frames / fps;
+}
+export function formatFfmpegTimestamp(seconds) {
+    assertFiniteNumber(seconds, "seconds");
+    return formatDecimal(seconds);
+}
+export function buildInputTrimArgs(options) {
+    assertPositiveFiniteNumber(options.fps, "fps");
+    if (options.source.length === 0) {
+        throw new Error("FFmpeg input source must not be empty.");
+    }
+    const args = [];
+    if (options.startFrame !== undefined) {
+        assertNonNegativeFrame(options.startFrame, "startFrame");
+        if (options.startFrame > 0) {
+            args.push("-ss", formatFfmpegTimestamp(framesToSeconds(options.startFrame, options.fps)));
+        }
+    }
+    if (options.durationFrames !== undefined) {
+        assertPositiveFrame(options.durationFrames, "durationFrames");
+        args.push("-t", formatFfmpegTimestamp(framesToSeconds(options.durationFrames, options.fps)));
+    }
+    args.push("-i", options.source);
+    return args;
+}
+export function buildFitVideoFilters(options) {
+    const dimensions = normalizeDimensions(options.dimensions);
+    const fit = options.fit ?? "cover";
+    const background = escapeFilterValue(options.background ?? "black");
+    const width = String(dimensions.width);
+    const height = String(dimensions.height);
+    switch (fit) {
+        case "cover":
+            return [
+                `scale=${width}:${height}:force_original_aspect_ratio=increase`,
+                buildCoverCropFilter(width, height, options.crop),
+                "setsar=1"
+            ];
+        case "contain":
+            return [
+                `scale=${width}:${height}:force_original_aspect_ratio=decrease`,
+                `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=${background}`,
+                "setsar=1"
+            ];
+        case "fill":
+            return [`scale=${width}:${height}`, "setsar=1"];
+        case "none":
+            return ["setsar=1"];
+        default:
+            throw new Error(`Unsupported video fit "${fit}".`);
+    }
+}
+export function buildBaseVideoFilterChain(options) {
+    assertPositiveFiniteNumber(options.fps, "fps");
+    assertPositiveFrame(options.layer.durationFrames, "layer.durationFrames");
+    const inputIndex = options.inputIndex ?? 0;
+    const inputLabel = options.inputLabel ?? streamLabel(inputIndex, "v");
+    const outputLabel = options.outputLabel ?? `${sanitizeLabelPart(options.layer.id)}_base`;
+    const playbackRate = options.layer.playbackRate ?? 1;
+    assertPositiveFiniteNumber(playbackRate, "layer.playbackRate");
+    const fitOptions = {
+        dimensions: normalizeDimensions(options.output)
+    };
+    if (options.layer.fit !== undefined) {
+        fitOptions.fit = options.layer.fit;
+    }
+    if (options.layer.crop !== undefined) {
+        fitOptions.crop = options.layer.crop;
+    }
+    if (options.background !== undefined) {
+        fitOptions.background = options.background;
+    }
+    const filters = [
+        `setpts=${playbackRate === 1 ? "PTS-STARTPTS" : `(PTS-STARTPTS)/${formatDecimal(playbackRate)}`}`,
+        ...buildFitVideoFilters(fitOptions)
+    ];
+    return createFilterChain([inputLabel], filters, outputLabel);
+}
+function buildCoverCropFilter(width, height, crop) {
+    if (crop?.mode !== "subject") {
+        return `crop=${width}:${height}`;
+    }
+    const x = escapeFilterExpression(buildSubjectCropExpression(crop, "x"));
+    const y = escapeFilterExpression(buildSubjectCropExpression(crop, "y"));
+    return `crop=${width}:${height}:${x}:${y}`;
+}
+function buildSubjectCropExpression(crop, axis) {
+    const focus = buildSubjectFocusExpression(crop, axis);
+    const dimensionExpression = axis === "x" ? "iw-ow" : "ih-oh";
+    return `min(max((${dimensionExpression})*(${focus}),0),${dimensionExpression})`;
+}
+function buildSubjectFocusExpression(crop, axis) {
+    const points = [];
+    const staticValue = crop[axis];
+    const keyframes = crop.keyframes ?? [];
+    if (keyframes.length === 0 && typeof staticValue === "number") {
+        assertNormalizedUnit(staticValue, `crop.${axis}`);
+        points.push({ frame: 0, x: crop.x ?? 0.5, y: crop.y ?? 0.5 });
+    }
+    for (const keyframe of keyframes) {
+        assertNonNegativeFrame(keyframe.frame, "crop.keyframes.frame");
+        assertNormalizedUnit(keyframe.x, "crop.keyframes.x");
+        assertNormalizedUnit(keyframe.y, "crop.keyframes.y");
+        points.push({ ...keyframe });
+    }
+    if (points.length === 0) {
+        return "0.5";
+    }
+    const sorted = [...points].sort((a, b) => a.frame - b.frame);
+    if (sorted.length === 1) {
+        return formatDecimal(sorted[0][axis]);
+    }
+    let expression = formatDecimal(sorted[sorted.length - 1][axis]);
+    for (let index = sorted.length - 2; index >= 0; index -= 1) {
+        const current = sorted[index];
+        const next = sorted[index + 1];
+        const currentValue = formatDecimal(current[axis]);
+        const nextValue = formatDecimal(next[axis]);
+        const segment = next.frame === current.frame
+            ? currentValue
+            : `${currentValue}+(${nextValue}-${currentValue})*(n-${current.frame})/${next.frame - current.frame}`;
+        expression = `if(lte(n,${next.frame}),${segment},${expression})`;
+    }
+    const first = sorted[0];
+    return `if(lte(n,${first.frame}),${formatDecimal(first[axis])},${expression})`;
+}
+export function planBaseVideo(options) {
+    const inputIndex = options.inputIndex ?? 0;
+    const inputStep = buildBaseVideoInputStep(options, inputIndex);
+    const filterChain = buildBaseVideoFilterChain(options);
+    const steps = [
+        inputStep,
+        createFilterStep({
+            id: `${sanitizeLabelPart(options.layer.id)}:base-filter`,
+            description: `Normalize base video layer "${options.layer.id}" to ${options.output.width}x${options.output.height}.`,
+            chains: [filterChain]
+        })
+    ];
+    return { steps };
+}
+export function planBaseVideoSequence(options) {
+    if (options.segments.length === 0) {
+        throw new Error("At least one base video segment is required.");
+    }
+    const inputSteps = [];
+    const chains = [];
+    const segmentLabels = [];
+    options.segments.forEach((segment, index) => {
+        const inputIndex = segment.inputIndex ?? index;
+        const fallbackLabel = `${sanitizeLabelPart(segment.layer.id)}_base`;
+        const segmentLabel = options.segments.length === 1 ? (options.outputLabel ?? segment.outputLabel ?? fallbackLabel) : (segment.outputLabel ?? `base_segment_${index}`);
+        const plannedSegment = withBaseVideoLabels(segment, inputIndex, segmentLabel);
+        inputSteps.push(buildBaseVideoInputStep(plannedSegment, inputIndex));
+        chains.push(buildBaseVideoFilterChain(plannedSegment));
+        segmentLabels.push(segmentLabel);
+    });
+    if (options.segments.length > 1) {
+        chains.push(buildConcatFilterChain({ segmentLabels, outputLabel: options.outputLabel ?? "base_concat" }));
+    }
+    return {
+        steps: [
+            ...inputSteps,
+            createFilterStep({
+                id: "base-video:filter",
+                description: options.segments.length === 1
+                    ? "Normalize one base video segment."
+                    : `Normalize and concatenate ${options.segments.length} base video segments.`,
+                chains
+            })
+        ]
+    };
+}
+export function buildOverlayCompositingFilterChain(options) {
+    const outputLabel = options.outputLabel ?? "composited";
+    const x = formatOverlayCoordinate(options.x ?? 0);
+    const y = formatOverlayCoordinate(options.y ?? 0);
+    const overlayOptions = [`x=${x}`, `y=${y}`, "format=auto"];
+    if (options.shortest !== undefined) {
+        overlayOptions.push(`shortest=${options.shortest ? "1" : "0"}`);
+    }
+    const enableExpression = buildOverlayEnableExpression(options);
+    if (enableExpression !== undefined) {
+        overlayOptions.push(`enable='${enableExpression}'`);
+    }
+    return createFilterChain([options.baseLabel, options.overlayLabel], [`overlay=${overlayOptions.join(":")}`], outputLabel);
+}
+export function buildOverlayCompositingArgs(options) {
+    return buildFilterComplexArgs([buildOverlayCompositingFilterChain(options)]);
+}
+export function buildOverlayFrameInputArgs(options) {
+    assertPositiveFiniteNumber(options.fps, "fps");
+    if (options.framePattern.length === 0) {
+        throw new Error("Overlay frame pattern must not be empty.");
+    }
+    const args = ["-framerate", formatDecimal(options.fps)];
+    if (options.startNumber !== undefined) {
+        assertNonNegativeFrame(options.startNumber, "startNumber");
+        args.push("-start_number", String(options.startNumber));
+    }
+    args.push("-i", options.framePattern);
+    return args;
+}
+export function buildOverlayFrameFilterChain(options) {
+    const inputIndex = options.inputIndex ?? 1;
+    const inputLabel = options.inputLabel ?? streamLabel(inputIndex, "v");
+    const outputLabel = options.outputLabel ?? "overlay_frames";
+    return createFilterChain([inputLabel], ["format=rgba", "setpts=PTS-STARTPTS"], outputLabel);
+}
+export function planOverlayCompositing(options) {
+    const inputIndex = options.frames.inputIndex ?? 1;
+    const overlayLabel = options.frames.outputLabel ?? "overlay_frames";
+    const frames = withOverlayFrameLabels(options.frames, inputIndex, overlayLabel);
+    const compositeOptions = buildOverlayCompositingPlanFilterOptions(options, overlayLabel);
+    return {
+        steps: [
+            createInputStep({
+                id: "overlay-frames:input",
+                description: `Read transparent overlay frame sequence "${options.frames.framePattern}".`,
+                args: buildOverlayFrameInputArgs(frames),
+                inputIndex,
+                source: options.frames.framePattern
+            }),
+            createFilterStep({
+                id: "overlay-frames:composite",
+                description: "Prepare transparent overlay frames and composite them over the base video.",
+                chains: [buildOverlayFrameFilterChain(frames), buildOverlayCompositingFilterChain(compositeOptions)]
+            })
+        ]
+    };
+}
+export function buildConcatFilterChain(options) {
+    if (options.segmentLabels.length === 0) {
+        throw new Error("At least one segment label is required for concat planning.");
+    }
+    return createFilterChain(options.segmentLabels, [`concat=n=${options.segmentLabels.length}:v=1:a=0`], options.outputLabel ?? "base_concat");
+}
+export function buildAudioMixFilterChains(options) {
+    return buildAudioMixPlanParts(options).chains;
+}
+export function planAudioMix(options) {
+    const parts = buildAudioMixPlanParts(options);
+    return {
+        steps: [
+            ...parts.inputSteps,
+            createFilterStep({
+                id: "audio-mix:filter",
+                description: `Mix ${options.tracks.length} audio track${options.tracks.length === 1 ? "" : "s"}.`,
+                chains: parts.chains,
+                notes: parts.notes
+            })
+        ]
+    };
+}
+export function buildFilterComplexArgs(chains) {
+    if (chains.length === 0) {
+        return [];
+    }
+    return ["-filter_complex", chains.map((chain) => chain.expression).join(";")];
+}
+export function createInputStep(options) {
+    return withOptionalNotes({
+        id: options.id,
+        kind: "input",
+        description: options.description,
+        args: [...options.args],
+        inputIndex: options.inputIndex,
+        source: options.source
+    }, options.notes);
+}
+export function createFilterStep(options) {
+    return withOptionalNotes({
+        id: options.id,
+        kind: "filter",
+        description: options.description,
+        chains: options.chains.map(cloneFilterChain),
+        args: buildFilterComplexArgs(options.chains)
+    }, options.notes);
+}
+export function createMapStep(options) {
+    return withOptionalNotes({
+        id: options.id,
+        kind: "map",
+        description: options.description,
+        labels: [...options.labels],
+        args: options.labels.flatMap((label) => ["-map", bracketLabel(label)])
+    }, options.notes);
+}
+export function createOutputStep(options) {
+    return withOptionalNotes({
+        id: options.id,
+        kind: "output",
+        description: options.description,
+        target: options.target,
+        args: [...(options.args ?? []), options.target]
+    }, options.notes);
+}
+export function createArgumentStep(options) {
+    return withOptionalNotes({
+        id: options.id,
+        kind: "argument",
+        description: options.description,
+        args: [...options.args]
+    }, options.notes);
+}
+function withBaseVideoLabels(options, inputIndex, outputLabel) {
+    return {
+        ...options,
+        inputIndex,
+        outputLabel
+    };
+}
+function buildBaseVideoInputStep(options, inputIndex) {
+    const trimStartFrames = options.asset.trimStartFrames ?? 0;
+    assertNonNegativeFrame(trimStartFrames, "asset.trimStartFrames");
+    const playbackRate = options.layer.playbackRate ?? 1;
+    assertPositiveFiniteNumber(playbackRate, "layer.playbackRate");
+    const requestedInputFrames = Math.ceil(options.layer.durationFrames * playbackRate);
+    const availableInputFrames = options.asset.trimEndFrames === null || options.asset.trimEndFrames === undefined
+        ? undefined
+        : Math.max(0, options.asset.trimEndFrames - trimStartFrames);
+    const durationFrames = availableInputFrames === undefined || options.asset.loop ? requestedInputFrames : Math.min(requestedInputFrames, availableInputFrames);
+    const notes = [];
+    if (availableInputFrames !== undefined && availableInputFrames < requestedInputFrames && !options.asset.loop) {
+        notes.push("asset trimEndFrames is shorter than the requested layer duration at the configured playback rate");
+    }
+    if (options.asset.loop) {
+        notes.push("asset.loop is recorded for inspection; loop expansion is not emitted by this primitive yet");
+    }
+    return createInputStep({
+        id: `${sanitizeLabelPart(options.layer.id)}:input`,
+        description: `Read video asset "${options.layer.asset}" for layer "${options.layer.id}".`,
+        args: buildInputTrimArgs({
+            source: options.asset.src,
+            startFrame: trimStartFrames,
+            durationFrames,
+            fps: options.fps
+        }),
+        inputIndex,
+        source: options.asset.src,
+        notes
+    });
+}
+function withOverlayFrameLabels(options, inputIndex, outputLabel) {
+    return {
+        ...options,
+        inputIndex,
+        outputLabel
+    };
+}
+function buildOverlayCompositingPlanFilterOptions(options, overlayLabel) {
+    const compositeOptions = {
+        baseLabel: options.baseLabel,
+        overlayLabel,
+        outputLabel: options.outputLabel ?? "video_composited"
+    };
+    if (options.x !== undefined) {
+        compositeOptions.x = options.x;
+    }
+    if (options.y !== undefined) {
+        compositeOptions.y = options.y;
+    }
+    if (options.startFrame !== undefined) {
+        compositeOptions.startFrame = options.startFrame;
+    }
+    if (options.durationFrames !== undefined) {
+        compositeOptions.durationFrames = options.durationFrames;
+    }
+    if (options.fps !== undefined) {
+        compositeOptions.fps = options.fps;
+    }
+    if (options.shortest !== undefined) {
+        compositeOptions.shortest = options.shortest;
+    }
+    return compositeOptions;
+}
+function buildAudioMixPlanParts(options) {
+    assertPositiveFiniteNumber(options.fps, "fps");
+    if (options.tracks.length === 0) {
+        throw new Error("At least one audio track is required for mix planning.");
+    }
+    const voiceoverCount = options.tracks.filter((track) => track.track.role === "voiceover").length;
+    if (voiceoverCount > 1) {
+        throw new Error("MVP audio mix planning supports at most one voiceover track.");
+    }
+    const resolvedTracks = options.tracks.map((track, index) => resolveAudioTrackPlan(track, index));
+    const chains = [];
+    const notes = [];
+    const inputSteps = resolvedTracks.map((resolved) => {
+        notes.push(...resolved.notes.map((note) => `${resolved.option.track.id}: ${note}`));
+        const trimOptions = {
+            source: resolved.option.asset.src,
+            startFrame: resolved.sourceStartFrame,
+            fps: options.fps
+        };
+        if (resolved.durationFrames !== undefined) {
+            trimOptions.durationFrames = resolved.durationFrames;
+        }
+        return createInputStep({
+            id: `${sanitizeLabelPart(resolved.option.track.id)}:audio-input`,
+            description: `Read ${resolved.option.track.role} audio asset "${resolved.option.track.asset}" for track "${resolved.option.track.id}".`,
+            args: buildInputTrimArgs(trimOptions),
+            inputIndex: resolved.inputIndex,
+            source: resolved.option.asset.src,
+            notes: resolved.notes
+        });
+    });
+    for (const resolved of resolvedTracks) {
+        chains.push(buildAudioTrackFilterChain(resolved, options, resolved.outputLabel));
+    }
+    const mixLabels = new Map();
+    for (const resolved of resolvedTracks) {
+        mixLabels.set(resolved.option.track.id, resolved.outputLabel);
+    }
+    for (const resolved of resolvedTracks) {
+        const duck = resolved.option.track.duck;
+        if (duck === undefined) {
+            continue;
+        }
+        const sidechain = findAudioTrackByRole(resolvedTracks, duck.against, resolved.option.track.id);
+        const sidechainDuration = sidechain.durationFrames ?? sidechain.option.track.durationFrames;
+        if (sidechainDuration === undefined) {
+            throw new Error(`Audio ducking against "${duck.against}" requires the sidechain track durationFrames.`);
+        }
+        const duckedLabel = `${sanitizeLabelPart(resolved.option.track.id)}_ducked`;
+        chains.push(createFilterChain([mixLabels.get(resolved.option.track.id) ?? resolved.outputLabel], [buildAudioDuckingFilter(duck, sidechain.option.track.startFrame, sidechainDuration, options.fps)], duckedLabel));
+        mixLabels.set(resolved.option.track.id, duckedLabel);
+        notes.push(`${resolved.option.track.id}: ducking represented as a timeline volume envelope against ${duck.against}; sidechain compression execution is deferred`);
+    }
+    const finalTrackLabels = resolvedTracks.map((resolved) => mixLabels.get(resolved.option.track.id) ?? resolved.outputLabel);
+    const mixFilters = [`amix=inputs=${finalTrackLabels.length}:duration=longest:dropout_transition=0`];
+    if (options.normalizeLoudness !== false) {
+        mixFilters.push(buildLoudnessNormalizationFilter(options.normalizeLoudness));
+    }
+    chains.push(createFilterChain(finalTrackLabels, mixFilters, options.outputLabel ?? "audio_mix"));
+    return { inputSteps, chains, notes };
+}
+function resolveAudioTrackPlan(option, index) {
+    assertNonNegativeFrame(option.track.startFrame, "track.startFrame");
+    const inputIndex = option.inputIndex ?? index;
+    const inputLabel = option.inputLabel ?? streamLabel(inputIndex, "a");
+    const outputLabel = option.outputLabel ?? `${sanitizeLabelPart(option.track.id)}_audio`;
+    const assetTrimStartFrames = option.asset.trimStartFrames ?? 0;
+    const offsetFrames = option.track.offsetFrames ?? 0;
+    assertNonNegativeFrame(assetTrimStartFrames, "asset.trimStartFrames");
+    assertNonNegativeFrame(offsetFrames, "track.offsetFrames");
+    const sourceStartFrame = assetTrimStartFrames + offsetFrames;
+    assertNonNegativeFrame(sourceStartFrame, "audio source start frame");
+    const notes = [];
+    const trimEndFrames = option.asset.trimEndFrames === null ? undefined : option.asset.trimEndFrames;
+    let durationFrames = option.track.durationFrames;
+    if (durationFrames !== undefined) {
+        assertPositiveFrame(durationFrames, "track.durationFrames");
+    }
+    if (trimEndFrames !== undefined) {
+        assertNonNegativeFrame(trimEndFrames, "asset.trimEndFrames");
+        const availableFrames = Math.max(0, trimEndFrames - sourceStartFrame);
+        if (durationFrames === undefined) {
+            durationFrames = availableFrames;
+        }
+        else if (!option.track.loop && !option.asset.loop) {
+            durationFrames = Math.min(durationFrames, availableFrames);
+        }
+    }
+    if (option.track.loop || option.asset.loop) {
+        notes.push("loop is recorded for inspection; audio loop expansion is not emitted by this primitive yet");
+    }
+    const resolved = {
+        option,
+        inputIndex,
+        inputLabel,
+        outputLabel,
+        sourceStartFrame,
+        notes
+    };
+    if (durationFrames !== undefined) {
+        resolved.durationFrames = durationFrames;
+    }
+    return resolved;
+}
+function buildAudioTrackFilterChain(resolved, options, outputLabel) {
+    const track = resolved.option.track;
+    const filters = ["asetpts=PTS-STARTPTS", "aresample=async=1"];
+    if (track.volume !== undefined) {
+        assertNonNegativeFiniteNumber(track.volume, "track.volume");
+        if (track.volume !== 1) {
+            filters.push(`volume=${formatDecimal(track.volume)}`);
+        }
+    }
+    if (track.fadeInFrames !== undefined) {
+        assertNonNegativeFrame(track.fadeInFrames, "track.fadeInFrames");
+        if (track.fadeInFrames > 0) {
+            filters.push(`afade=t=in:st=0:d=${formatFfmpegTimestamp(framesToSeconds(track.fadeInFrames, options.fps))}`);
+        }
+    }
+    if (track.fadeOutFrames !== undefined) {
+        assertNonNegativeFrame(track.fadeOutFrames, "track.fadeOutFrames");
+        if (track.fadeOutFrames > 0) {
+            if (resolved.durationFrames === undefined) {
+                throw new Error(`Audio track "${track.id}" requires durationFrames or trimEndFrames to plan fadeOutFrames.`);
+            }
+            const fadeOutSeconds = framesToSeconds(track.fadeOutFrames, options.fps);
+            const durationSeconds = framesToSeconds(resolved.durationFrames, options.fps);
+            filters.push(`afade=t=out:st=${formatFfmpegTimestamp(Math.max(0, durationSeconds - fadeOutSeconds))}:d=${formatFfmpegTimestamp(fadeOutSeconds)}`);
+        }
+    }
+    if (track.startFrame > 0) {
+        filters.push(`adelay=${formatFfmpegTimestamp(framesToSeconds(track.startFrame, options.fps) * 1000)}:all=1`);
+    }
+    return createFilterChain([resolved.inputLabel], filters, outputLabel);
+}
+function findAudioTrackByRole(tracks, role, excludingTrackId) {
+    const track = tracks.find((candidate) => candidate.option.track.id !== excludingTrackId && candidate.option.track.role === role);
+    if (track === undefined) {
+        throw new Error(`Audio ducking requires a track with role "${role}".`);
+    }
+    return track;
+}
+function buildAudioDuckingFilter(duck, sidechainStartFrame, sidechainDurationFrames, fps) {
+    assertNonPositiveFiniteNumber(duck.amountDb, "duck.amountDb");
+    const amount = formatDecimal(Math.pow(10, duck.amountDb / 20));
+    const start = formatFfmpegTimestamp(framesToSeconds(sidechainStartFrame, fps));
+    const end = formatFfmpegTimestamp(framesToSeconds(sidechainStartFrame + sidechainDurationFrames, fps));
+    const attackFrames = duck.attackFrames ?? 0;
+    const releaseFrames = duck.releaseFrames ?? 0;
+    assertNonNegativeFrame(attackFrames, "duck.attackFrames");
+    assertNonNegativeFrame(releaseFrames, "duck.releaseFrames");
+    const attack = formatFfmpegTimestamp(framesToSeconds(attackFrames, fps));
+    const release = formatFfmpegTimestamp(framesToSeconds(releaseFrames, fps));
+    let expression;
+    if (attackFrames === 0 && releaseFrames === 0) {
+        expression = `if(between(t,${start},${end}),${amount},1)`;
+    }
+    else if (attackFrames === 0) {
+        expression = `if(lt(t,${start}),1,if(lte(t,${end}),${amount},if(lt(t,${end}+${release}),${amount}+(1-${amount})*(t-${end})/${release},1)))`;
+    }
+    else if (releaseFrames === 0) {
+        expression = `if(lt(t,${start}),1,if(lt(t,${start}+${attack}),1-(1-${amount})*(t-${start})/${attack},if(lte(t,${end}),${amount},1)))`;
+    }
+    else {
+        expression = `if(lt(t,${start}),1,if(lt(t,${start}+${attack}),1-(1-${amount})*(t-${start})/${attack},if(lte(t,${end}),${amount},if(lt(t,${end}+${release}),${amount}+(1-${amount})*(t-${end})/${release},1))))`;
+    }
+    return `volume='${escapeFilterExpression(expression)}'`;
+}
+function buildLoudnessNormalizationFilter(options) {
+    const normalizedOptions = typeof options === "object" ? options : {};
+    const integratedLufs = normalizedOptions.integratedLufs ?? -14;
+    const truePeakDb = normalizedOptions.truePeakDb ?? -1.5;
+    const loudnessRange = normalizedOptions.loudnessRange ?? 11;
+    assertFiniteNumber(integratedLufs, "integratedLufs");
+    assertFiniteNumber(truePeakDb, "truePeakDb");
+    assertPositiveFiniteNumber(loudnessRange, "loudnessRange");
+    return `loudnorm=I=${formatDecimal(integratedLufs)}:TP=${formatDecimal(truePeakDb)}:LRA=${formatDecimal(loudnessRange)}`;
+}
+function createFilterChain(inputLabels, filters, outputLabel) {
+    if (inputLabels.length === 0) {
+        throw new Error("At least one filter input label is required.");
+    }
+    if (filters.length === 0) {
+        throw new Error("At least one FFmpeg filter is required.");
+    }
+    return {
+        inputLabels: inputLabels.map(unbracketLabel),
+        filters: [...filters],
+        outputLabel: unbracketLabel(outputLabel),
+        expression: `${inputLabels.map(bracketLabel).join("")}${filters.join(",")}${bracketLabel(outputLabel)}`
+    };
+}
+function buildOverlayEnableExpression(options) {
+    if (options.startFrame === undefined && options.durationFrames === undefined) {
+        return undefined;
+    }
+    if (options.fps === undefined) {
+        throw new Error("fps is required when overlay startFrame or durationFrames is provided.");
+    }
+    const startFrame = options.startFrame ?? 0;
+    assertNonNegativeFrame(startFrame, "startFrame");
+    const startSeconds = formatFfmpegTimestamp(framesToSeconds(startFrame, options.fps));
+    if (options.durationFrames === undefined) {
+        return `gte(t,${startSeconds})`;
+    }
+    assertPositiveFrame(options.durationFrames, "durationFrames");
+    const endSeconds = formatFfmpegTimestamp(framesToSeconds(startFrame + options.durationFrames, options.fps));
+    return `between(t,${startSeconds},${endSeconds})`;
+}
+function formatOverlayCoordinate(value) {
+    if (typeof value === "number") {
+        assertFiniteNumber(value, "overlay coordinate");
+        return formatDecimal(value);
+    }
+    if (value.length === 0) {
+        throw new Error("Overlay coordinate expression must not be empty.");
+    }
+    return escapeFilterValue(value);
+}
+function streamLabel(inputIndex, stream) {
+    assertNonNegativeFrame(inputIndex, "inputIndex");
+    return `${inputIndex}:${stream}`;
+}
+function bracketLabel(label) {
+    const value = unbracketLabel(label);
+    return `[${value}]`;
+}
+function unbracketLabel(label) {
+    if (label.startsWith("[") && label.endsWith("]")) {
+        return label.slice(1, -1);
+    }
+    return label;
+}
+function sanitizeLabelPart(value) {
+    const normalized = value.trim().replaceAll(/[^A-Za-z0-9_]+/g, "_").replaceAll(/^_+|_+$/g, "");
+    return normalized.length > 0 ? normalized : "layer";
+}
+function normalizeDimensions(dimensions) {
+    assertPositiveFrame(dimensions.width, "width");
+    assertPositiveFrame(dimensions.height, "height");
+    return { width: dimensions.width, height: dimensions.height };
+}
+function escapeFilterValue(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll(":", "\\:").replaceAll("'", "\\'");
+}
+function escapeFilterExpression(value) {
+    return escapeFilterValue(value).replaceAll(",", "\\,");
+}
+function cloneFilterChain(chain) {
+    return {
+        inputLabels: [...chain.inputLabels],
+        filters: [...chain.filters],
+        outputLabel: chain.outputLabel,
+        expression: chain.expression
+    };
+}
+function withOptionalNotes(step, notes) {
+    if (notes === undefined || notes.length === 0) {
+        return step;
+    }
+    return { ...step, notes: [...notes] };
+}
+function formatDecimal(value) {
+    assertFiniteNumber(value, "value");
+    if (Number.isInteger(value)) {
+        return String(value);
+    }
+    return value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+function assertPositiveFrame(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer.`);
+    }
+}
+function assertNonNegativeFrame(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer.`);
+    }
+}
+function assertPositiveFiniteNumber(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a positive finite number.`);
+    }
+}
+function assertNonNegativeFiniteNumber(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative finite number.`);
+    }
+}
+function assertNonPositiveFiniteNumber(value, name) {
+    if (!Number.isFinite(value) || value > 0) {
+        throw new Error(`${name} must be a non-positive finite number.`);
+    }
+}
+function assertNormalizedUnit(value, name) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`${name} must be between 0 and 1.`);
+    }
+}
+function assertFiniteNumber(value, name) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`${name} must be finite.`);
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kitsra/kavio-ffmpeg",
+  "version": "0.1.0",
+  "description": "FFmpeg planning primitives for Kavio rendering.",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@kitsra/kavio-schema": "0.1.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/self-check.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && node dist/self-check.js"
+  }
+}