@officexapp/vidfarm-devcli 0.21.31 → 0.21.32

package/dist/src/devcli/dedupe-local.js

@@ -0,0 +1,209 @@
+// Bundle-safe LOCAL deduplication for the published devcli.
+//
+// Deduplication = nudging a finished render's geometry, color, timing and grain
+// by a couple of percent so a platform's duplicate-content fingerprint reads it
+// as a NEW upload, while a human sees no difference. It is what lets one good
+// video be posted across several accounts/slots without the second and third
+// posts being suppressed as reused content.
+//
+// This is a pure ffmpeg op with zero server dependency (exactly like
+// greenscreen-local.ts), so it runs FREE and offline in the shipped CLI. Every
+// transform comes from lib/dedupe-recipe.ts — the SAME module the cloud
+// primitive (services/media-processing.dedupeMediaAsset) uses — so local output
+// matches cloud output knob for knob. No backend module is imported here, which
+// keeps the pack guard happy.
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { resolveFfmpeg, resolveFfprobe, hasFfmpeg } from "../services/clip-curation/ffmpeg.js";
+import { buildDedupeFfmpegPlan, dedupeCrfForVariant, describeDedupeEffects, resolveDedupeEffects, DEDUPE_DEFAULT_PRESET } from "../lib/dedupe-recipe.js";
+export { DEDUPE_PRESETS, DEDUPE_DEFAULT_PRESET, describeDedupeEffects, isDedupePresetName, resolveDedupeEffects } from "../lib/dedupe-recipe.js";
+/** True when a usable ffmpeg is available (bundled ffmpeg-static or on PATH). */
+export async function localDedupeAvailable() {
+    return hasFfmpeg();
+}
+async function runFfmpeg(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 0, stderr }));
+    });
+}
+async function probe(filePath) {
+    const ffprobe = await resolveFfprobe();
+    const args = ["-v", "error", "-print_format", "json", "-show_format", "-show_streams", filePath];
+    const raw = await new Promise((resolve) => {
+        const child = spawn(ffprobe, args, { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        child.stdout.on("data", (d) => (out += d.toString()));
+        child.on("error", () => resolve(""));
+        child.on("close", () => resolve(out));
+    });
+    let parsed = {};
+    try {
+        parsed = JSON.parse(raw || "{}");
+    }
+    catch {
+        parsed = {};
+    }
+    const streams = (Array.isArray(parsed.streams) ? parsed.streams : []);
+    const video = streams.find((stream) => stream.codec_type === "video");
+    const format = (parsed.format ?? {});
+    let fps = null;
+    if (typeof video?.avg_frame_rate === "string") {
+        const [numerator, denominator] = video.avg_frame_rate.split("/").map(Number);
+        if (numerator && denominator)
+            fps = numerator / denominator;
+    }
+    return {
+        width: typeof video?.width === "number" ? video.width : null,
+        height: typeof video?.height === "number" ? video.height : null,
+        durationSec: Number(format.duration ?? video?.duration ?? 0) || 0,
+        fps,
+        hasAudio: streams.some((stream) => stream.codec_type === "audio"),
+        hasVideo: Boolean(video)
+    };
+}
+/**
+ * Deduplicate an image or video LOCALLY with ffmpeg — free, offline, no wallet.
+ * Cloud-parity: identical filter graph to `primitive:media_dedupe` (engine
+ * `ffmpeg`).
+ *
+ * Two things happen beyond the visible transforms:
+ *   • `-map_metadata -1` strips creation time / encoder / source handler, which
+ *     some platforms compare BEFORE they compare pixels.
+ *   • The CRF is walked ±1 per variant, so the coded bitstream differs even
+ *     where the decoded frames are near-identical.
+ *
+ * Retries without the `perspective` (skew) stage on ffmpeg builds compiled
+ * without vf_perspective rather than failing the whole pass.
+ */
+export async function dedupeMediaLocal(input) {
+    if (!existsSync(input.sourcePath))
+        throw new Error(`No such source file: ${input.sourcePath}`);
+    const info = await probe(input.sourcePath);
+    const mediaType = input.mediaType
+        ?? (info.hasVideo && info.durationSec > 0.25 ? "video" : "image");
+    const variant = Math.max(1, Math.round(input.variant ?? 1) || 1);
+    const preset = input.preset ?? DEDUPE_DEFAULT_PRESET;
+    const effects = resolveDedupeEffects({
+        preset,
+        effects: input.effects,
+        variant,
+        seed: input.seed,
+        jitter: input.jitter
+    });
+    const plan = buildDedupeFfmpegPlan({
+        effects,
+        mediaType,
+        width: info.width ?? input.width ?? 1080,
+        height: info.height ?? input.height ?? 1920,
+        outWidth: input.width ?? info.width ?? null,
+        outHeight: input.height ?? info.height ?? null,
+        sourceFps: info.fps,
+        tintColor: input.tintColor ?? null,
+        tintOpacity: input.tintOpacity ?? null
+    });
+    const crf = dedupeCrfForVariant(input.crf ?? 21, variant, input.seed ?? "");
+    const stripMetadata = input.stripMetadata ?? true;
+    const isWebp = /\.webp$/i.test(input.outputPath);
+    const isJpeg = /\.jpe?g$/i.test(input.outputPath);
+    const ffmpeg = await resolveFfmpeg();
+    const buildArgs = (videoFilter) => mediaType === "video"
+        ? [
+            "-hide_banner", "-y",
+            "-i", input.sourcePath,
+            "-map", "0:v:0",
+            "-map", "0:a:0?",
+            "-vf", videoFilter,
+            ...(plan.audioFilter && info.hasAudio ? ["-af", plan.audioFilter] : []),
+            ...(stripMetadata ? ["-map_metadata", "-1"] : []),
+            "-c:v", "libx264",
+            "-preset", input.x264Preset ?? "veryfast",
+            "-crf", String(crf),
+            "-pix_fmt", "yuv420p",
+            "-movflags", "+faststart",
+            "-c:a", "aac",
+            "-b:a", `${input.audioBitrateKbps ?? 128}k`,
+            "-ar", "48000",
+            input.outputPath
+        ]
+        : [
+            "-hide_banner", "-y",
+            "-i", input.sourcePath,
+            "-frames:v", "1",
+            "-vf", videoFilter,
+            ...(stripMetadata ? ["-map_metadata", "-1"] : []),
+            ...(isWebp ? ["-c:v", "libwebp", "-quality", "92"] : []),
+            ...(isJpeg ? ["-q:v", "3"] : []),
+            input.outputPath
+        ];
+    // Distinguish "this recipe has no shear" from "the shear was dropped": only
+    // the latter is worth warning about.
+    const skewRequested = plan.videoFilter !== plan.videoFilterWithoutSkew;
+    let skewApplied = skewRequested;
+    let run = await runFfmpeg(ffmpeg, buildArgs(plan.videoFilter));
+    if ((run.code !== 0 || !existsSync(input.outputPath)) && skewRequested) {
+        // Minimal ffmpeg builds ship without vf_perspective. Losing the shear beats
+        // losing the whole dedupe pass.
+        skewApplied = false;
+        run = await runFfmpeg(ffmpeg, buildArgs(plan.videoFilterWithoutSkew));
+    }
+    if (run.code !== 0 || !existsSync(input.outputPath)) {
+        throw new Error(`Local dedupe failed (ffmpeg exit ${run.code})${tail(run.stderr)}.`);
+    }
+    const skewDropped = skewRequested && !skewApplied;
+    return {
+        outputPath: input.outputPath,
+        mediaType,
+        effects,
+        preset,
+        variant,
+        notes: skewDropped ? [...plan.notes, "skew skipped — this ffmpeg has no vf_perspective"] : plan.notes,
+        effectiveZoom: plan.effectiveZoom,
+        speed: plan.speed,
+        crf,
+        skewApplied,
+        skewDropped,
+        sourceWidth: info.width,
+        sourceHeight: info.height,
+        bytes: safeSize(input.outputPath)
+    };
+}
+/** One-line summary of what a resolved recipe does, for CLI output. */
+export function describeLocalDedupe(result) {
+    const summary = describeDedupeEffects(result.effects, result.preset);
+    // A rotate forces a bigger centre-crop than asked for (the zoom that hides the
+    // black corners). Say so — on a tall frame it is a real framing change.
+    if (result.effectiveZoom > result.effects.zoom + 0.0005) {
+        const applied = `${((result.effectiveZoom - 1) * 100).toFixed(1)}%`;
+        return `${summary} → crops ${applied} to hide the rotate corners (--rotate 0 keeps your framing)`;
+    }
+    return summary;
+}
+/**
+ * Default output path next to a source: `<stem>.dedupe.<ext>` for a one-off,
+ * `<stem>.dedupe-02.<ext>` and up for batch variants (variant 1 keeps the plain
+ * name so a single-copy run reads cleanly).
+ */
+export function defaultDedupeOutPath(sourcePath, variant = 1) {
+    const ext = path.extname(sourcePath) || ".mp4";
+    const stem = path.basename(sourcePath, ext);
+    const suffix = variant > 1 ? `.dedupe-${String(variant).padStart(2, "0")}` : ".dedupe";
+    return path.resolve(path.dirname(path.resolve(sourcePath)), `${stem}${suffix}${ext}`);
+}
+function safeSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function tail(stderr) {
+    const trimmed = stderr.trim().split("\n").slice(-3).join("\n");
+    return trimmed ? `:\n${trimmed}` : "";
+}
+//# sourceMappingURL=dedupe-local.js.map

package/dist/src/lib/dedupe-recipe.js

@@ -0,0 +1,420 @@
+// Deduplication recipe — the SINGLE source of truth for "make this render
+// visually identical to a human but numerically distinct to a platform's
+// duplicate-content detector".
+//
+// Why this module exists: social platforms (TikTok, Reels, Shorts, X) hash
+// uploads with a perceptual fingerprint. Re-posting the SAME bytes — or the same
+// frames re-encoded — gets the second post suppressed or flagged as duplicate /
+// reused content. Nudging geometry, color, timing and grain by a couple of
+// percent moves the fingerprint far enough to read as a distinct upload while
+// staying invisible to a viewer.
+//
+// This file is PURE (no node/aws imports) so the exact same math drives:
+//   • cloud   — primitive:media_dedupe → services/media-processing.dedupeMediaAsset
+//   • local   — `vidfarm dedupe` → devcli/dedupe-local.ts
+//   • schemas — primitive-registry.ts REST payload validation
+// Keep it dependency-free: it is inside the published devcli's import closure.
+/** Every knob at its no-op value. */
+export const DEDUPE_NEUTRAL_EFFECTS = {
+    zoom: 1,
+    tilt: 0,
+    rotate: 0,
+    skew: 0,
+    saturation: 1,
+    speed: 1,
+    horizontal_flip: false,
+    contrast: 1,
+    brightness: 1,
+    hue_rotate: 0,
+    blur: 0,
+    noise: 0,
+    volume: 1
+};
+/**
+ * The standard transformation sets. `standard` is the house default and is the
+ * calibrated combination: skew 2%, zoom 3%, rotate 2°, speed +2%, saturation
+ * +4% — enough independent axes that a perceptual hash lands well outside the
+ * match threshold, small enough that nobody watching can tell.
+ *
+ * `legacy` reproduces the pre-ffmpeg composition-renderer defaults so old
+ * `media_dedupe` callers keep their exact output.
+ */
+export const DEDUPE_PRESETS = {
+    none: { ...DEDUPE_NEUTRAL_EFFECTS },
+    // Barely-there. For footage you have only lightly reused, or where framing is
+    // tight and you cannot afford a 3% crop.
+    light: {
+        ...DEDUPE_NEUTRAL_EFFECTS,
+        zoom: 1.02,
+        rotate: 0.75,
+        skew: 1,
+        saturation: 1.02,
+        speed: 1.01,
+        contrast: 1.01,
+        brightness: 1.01,
+        hue_rotate: 2,
+        noise: 0.5
+    },
+    // THE DEFAULT — the numbers the house standard is written around.
+    standard: {
+        ...DEDUPE_NEUTRAL_EFFECTS,
+        zoom: 1.03,
+        rotate: 2,
+        skew: 2,
+        saturation: 1.04,
+        speed: 1.02,
+        contrast: 1.03,
+        brightness: 1.02,
+        hue_rotate: 4,
+        noise: 1.5
+    },
+    // For a clip you are posting for the Nth time, or onto an account that already
+    // posted it. Starts to be noticeable side-by-side with the original.
+    strong: {
+        ...DEDUPE_NEUTRAL_EFFECTS,
+        zoom: 1.06,
+        rotate: 3,
+        skew: 3.5,
+        saturation: 1.08,
+        speed: 1.05,
+        contrast: 1.05,
+        brightness: 1.04,
+        hue_rotate: 8,
+        noise: 3
+    },
+    // Pre-ffmpeg composition-renderer defaults (media-dedupe.tsx lineage).
+    legacy: {
+        ...DEDUPE_NEUTRAL_EFFECTS,
+        zoom: 1.04,
+        tilt: 3,
+        rotate: 3,
+        saturation: 1.05,
+        speed: 1.05,
+        contrast: 1.05,
+        brightness: 1.05
+    }
+};
+export const DEDUPE_DEFAULT_PRESET = "standard";
+/** Back-compat alias for the composition renderer's old default table. */
+export const DEDUPE_DEFAULT_EFFECTS = DEDUPE_PRESETS.legacy;
+export function isDedupePresetName(value) {
+    return typeof value === "string" && Object.prototype.hasOwnProperty.call(DEDUPE_PRESETS, value);
+}
+export function resolveDedupeEffects(input = {}) {
+    const presetName = isDedupePresetName(input.preset) ? input.preset : DEDUPE_DEFAULT_PRESET;
+    const base = { ...DEDUPE_PRESETS[presetName] };
+    const variant = Math.max(1, Math.round(Number(input.variant ?? 1)) || 1);
+    const shouldJitter = input.jitter ?? variant > 1;
+    const jittered = shouldJitter && presetName !== "none"
+        ? jitterEffects(base, variant, input.seed ?? "")
+        : base;
+    // Explicit overrides always win over both preset and jitter — an operator who
+    // typed `--rotate 0` means zero, not "zero, jittered".
+    const merged = { ...jittered };
+    for (const [key, value] of Object.entries(input.effects ?? {})) {
+        if (value === undefined || value === null)
+            continue;
+        merged[key] = value;
+    }
+    return clampDedupeEffects(merged);
+}
+// Deterministic per-variant perturbation. Each knob's DISTANCE FROM NEUTRAL is
+// scaled by 0.7..1.3, and the signed knobs (rotate/skew/tilt/hue) flip sign on
+// alternating variants — a sign flip moves a perceptual hash much further than
+// a magnitude nudge, so alternating them keeps successive variants apart.
+function jitterEffects(base, variant, seed) {
+    const rand = mulberry32(hashSeed(`${seed}:${variant}`));
+    const spread = () => 0.7 + rand() * 0.6;
+    const flip = (index) => ((variant + index) % 2 === 0 ? -1 : 1);
+    return {
+        ...base,
+        zoom: 1 + (base.zoom - 1) * spread(),
+        tilt: base.tilt * spread() * flip(0),
+        rotate: base.rotate * spread() * flip(1),
+        skew: base.skew * spread() * flip(2),
+        saturation: 1 + (base.saturation - 1) * spread(),
+        speed: 1 + (base.speed - 1) * spread(),
+        horizontal_flip: base.horizontal_flip,
+        contrast: 1 + (base.contrast - 1) * spread(),
+        brightness: 1 + (base.brightness - 1) * spread(),
+        hue_rotate: base.hue_rotate * spread() * flip(3),
+        blur: base.blur * spread(),
+        noise: base.noise * spread(),
+        volume: base.volume
+    };
+}
+function hashSeed(value) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+function mulberry32(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function clampDedupeEffects(effects) {
+    const merged = { ...DEDUPE_NEUTRAL_EFFECTS, ...effects };
+    return {
+        zoom: clamp(round4(merged.zoom), 0.1, 10),
+        tilt: clamp(round4(merged.tilt), -90, 90),
+        rotate: clamp(round4(merged.rotate), -360, 360),
+        skew: clamp(round4(merged.skew), -45, 45),
+        saturation: clamp(round4(merged.saturation), 0, 10),
+        speed: clamp(round4(merged.speed), 0.1, 10),
+        horizontal_flip: Boolean(merged.horizontal_flip),
+        contrast: clamp(round4(merged.contrast), 0, 10),
+        brightness: clamp(round4(merged.brightness), 0, 10),
+        hue_rotate: clamp(round4(merged.hue_rotate), -360, 360),
+        blur: clamp(round4(merged.blur), 0, 50),
+        noise: clamp(round4(merged.noise), 0, 100),
+        volume: clamp(round4(merged.volume), 0, 2)
+    };
+}
+/** True when the resolved effects would leave the frame byte-identical. */
+export function isDedupeNoop(effects) {
+    return !effects.horizontal_flip
+        && near(effects.zoom, 1) && near(effects.saturation, 1) && near(effects.speed, 1)
+        && near(effects.contrast, 1) && near(effects.brightness, 1) && near(effects.volume, 1)
+        && near(effects.rotate, 0) && near(effects.skew, 0) && near(effects.tilt, 0)
+        && near(effects.hue_rotate, 0) && near(effects.blur, 0) && near(effects.noise, 0);
+}
+export function buildDedupeFfmpegPlan(input) {
+    const e = input.effects;
+    const width = Math.max(2, Math.round(input.width) || 2);
+    const height = Math.max(2, Math.round(input.height) || 2);
+    const outWidth = evenDim(input.outWidth ?? width);
+    const outHeight = evenDim(input.outHeight ?? height);
+    const notes = [];
+    const skewStage = [];
+    const mainStage = [];
+    if (e.horizontal_flip) {
+        mainStage.push("hflip");
+        notes.push("mirrored horizontally");
+    }
+    // --- color -------------------------------------------------------------
+    // ffmpeg `eq` takes brightness as an ADDITIVE -1..1 term while our knobs are
+    // multipliers around 1, so a 1.02 brightness becomes +0.02.
+    const eqParts = [];
+    if (!near(e.contrast, 1))
+        eqParts.push(`contrast=${fixed(e.contrast)}`);
+    if (!near(e.brightness, 1))
+        eqParts.push(`brightness=${fixed(clamp(e.brightness - 1, -1, 1))}`);
+    if (!near(e.saturation, 1))
+        eqParts.push(`saturation=${fixed(e.saturation)}`);
+    if (eqParts.length) {
+        mainStage.push(`eq=${eqParts.join(":")}`);
+        notes.push(`color ${eqParts.map((part) => part.replace("=", " ")).join(", ")}`);
+    }
+    if (!near(e.hue_rotate, 0)) {
+        mainStage.push(`hue=h=${fixed(e.hue_rotate)}`);
+        notes.push(`hue ${fixed(e.hue_rotate)}°`);
+    }
+    // --- geometry ----------------------------------------------------------
+    // Horizontal shear. `perspective` in its default sense=source mode maps the
+    // four given SOURCE points onto the output corners, so a slightly-sheared
+    // quad warps and fills the frame with no black wedges to crop away.
+    //
+    // `tilt` has no ffmpeg equivalent (it is a 3D rotateX in the composition
+    // renderer); fold it into the shear budget so the knob still perturbs the
+    // frame rather than silently doing nothing.
+    const shearPct = e.skew + e.tilt * 0.25;
+    if (!near(shearPct, 0)) {
+        const shiftPx = Math.round((Math.abs(shearPct) / 100) * width);
+        if (shiftPx >= 1) {
+            const [topShift, bottomShift] = shearPct >= 0 ? [shiftPx, -shiftPx] : [-shiftPx, shiftPx];
+            // Corner order is TL, TR, BL, BR.
+            skewStage.push(`perspective=x0=${topShift}:y0=0`
+                + `:x1=${width + topShift}:y1=0`
+                + `:x2=${bottomShift}:y2=${height}`
+                + `:x3=${width + bottomShift}:y3=${height}`
+                + `:interpolation=linear`);
+            notes.push(`skew ${fixed(shearPct)}% (${shiftPx}px shear)`);
+        }
+    }
+    if (!near(e.rotate, 0)) {
+        mainStage.push(`rotate=${fixed((e.rotate * Math.PI) / 180, 6)}:ow=iw:oh=ih:bilinear=1`);
+        notes.push(`rotate ${fixed(e.rotate)}°`);
+    }
+    // A rotation leaves black wedges in the corners. Compute the smallest zoom
+    // that crops them all away and take the max against the requested zoom, so
+    // "rotate 2°" never means "rotate 2° and four black triangles".
+    const requestedZoom = Math.max(1, e.zoom);
+    const coverZoom = rotationCoverZoom(e.rotate, width, height);
+    const effectiveZoom = Math.max(requestedZoom, coverZoom);
+    if (effectiveZoom > 1.0001) {
+        // crop=iw/Z:ih/Z centred, then scale back to the output size.
+        mainStage.push(`crop=iw/${fixed(effectiveZoom, 5)}:ih/${fixed(effectiveZoom, 5)}`);
+        if (effectiveZoom > requestedZoom + 0.0005) {
+            notes.push(`zoom ${pct(effectiveZoom)} (raised from ${pct(requestedZoom)} to hide the rotate corners)`);
+        }
+        else {
+            notes.push(`zoom ${pct(effectiveZoom)}`);
+        }
+    }
+    mainStage.push(`scale=${outWidth}:${outHeight}:flags=bicubic`, "setsar=1");
+    // --- surface texture ---------------------------------------------------
+    const tintOpacity = clamp(Number(input.tintOpacity ?? 0), 0, 1);
+    if (tintOpacity > 0.001) {
+        const tint = normalizeFfmpegHex(input.tintColor ?? "#FF8C00");
+        mainStage.push(`drawbox=x=0:y=0:w=iw:h=ih:color=${tint}@${fixed(tintOpacity, 3)}:t=fill`);
+        notes.push(`tint ${tint} @ ${fixed(tintOpacity, 3)}`);
+    }
+    if (e.blur > 0.001) {
+        mainStage.push(`gblur=sigma=${fixed(e.blur, 3)}`);
+        notes.push(`blur σ${fixed(e.blur, 2)}`);
+    }
+    if (e.noise > 0.001) {
+        // `allf=t+u` = temporal + uniform: grain that changes every frame, which
+        // defeats frame-averaged fingerprints as well as per-frame ones.
+        mainStage.push(`noise=alls=${Math.max(1, Math.round(e.noise))}:allf=t+u`);
+        notes.push(`grain ${fixed(e.noise, 1)}`);
+    }
+    // --- timing ------------------------------------------------------------
+    const speed = input.mediaType === "video" ? e.speed : 1;
+    const timingStage = [];
+    if (!near(speed, 1)) {
+        const fps = clamp(Number(input.sourceFps ?? 30) || 30, 1, 240);
+        // setpts compresses the timeline; fps= resamples it back to a constant rate
+        // so the shorter duration actually survives CFR encoding (see sourceFps).
+        timingStage.push(`setpts=PTS/${fixed(speed, 5)}`, `fps=${fixed(fps, 5)}`);
+        notes.push(`speed ×${fixed(speed, 3)}`);
+    }
+    const compose = (parts) => {
+        const chain = parts.filter(Boolean);
+        return chain.length ? chain.join(",") : "null";
+    };
+    const videoFilter = compose([...skewStage, ...mainStage, ...timingStage]);
+    const videoFilterWithoutSkew = compose([...mainStage, ...timingStage]);
+    // --- audio -------------------------------------------------------------
+    const audioParts = [];
+    if (!near(speed, 1))
+        audioParts.push(...atempoChain(speed));
+    if (!near(e.volume, 1)) {
+        audioParts.push(`volume=${fixed(e.volume, 3)}`);
+        notes.push(`volume ×${fixed(e.volume, 2)}`);
+    }
+    return {
+        videoFilter,
+        videoFilterWithoutSkew,
+        audioFilter: audioParts.length ? audioParts.join(",") : null,
+        effectiveZoom: round4(effectiveZoom),
+        requestedZoom: round4(requestedZoom),
+        speed: round4(speed),
+        notes
+    };
+}
+/**
+ * Smallest uniform scale that keeps a `width`×`height` frame fully covered after
+ * rotating by `degrees` — i.e. the zoom needed to crop every black corner away.
+ */
+export function rotationCoverZoom(degrees, width, height) {
+    if (near(degrees, 0))
+        return 1;
+    const radians = (Math.abs(degrees) * Math.PI) / 180;
+    const cos = Math.abs(Math.cos(radians));
+    const sin = Math.abs(Math.sin(radians));
+    const coverWidth = (width * cos + height * sin) / width;
+    const coverHeight = (width * sin + height * cos) / height;
+    // +0.5% safety margin for the bilinear edge pixels.
+    return Math.max(coverWidth, coverHeight) * 1.005;
+}
+/** ffmpeg's `atempo` only accepts 0.5..2.0, so a bigger change is a chain. */
+export function atempoChain(speed) {
+    const parts = [];
+    let remaining = clamp(speed, 0.1, 10);
+    let guard = 0;
+    while (remaining > 2 && guard < 8) {
+        parts.push("atempo=2.0");
+        remaining /= 2;
+        guard += 1;
+    }
+    while (remaining < 0.5 && guard < 16) {
+        parts.push("atempo=0.5");
+        remaining /= 0.5;
+        guard += 1;
+    }
+    if (!near(remaining, 1))
+        parts.push(`atempo=${fixed(remaining, 5)}`);
+    return parts;
+}
+/**
+ * Per-variant CRF jitter. Two encodes of the same frames at the same CRF produce
+ * near-identical bitstreams; a ±1 CRF walk changes the coded data as well as the
+ * pixels, which matters for the byte-level dupe checks some platforms run first.
+ */
+export function dedupeCrfForVariant(baseCrf, variant, seed = "") {
+    const rand = mulberry32(hashSeed(`crf:${seed}:${variant}`));
+    const offset = Math.round(rand() * 2) - 1;
+    return clamp(Math.round(baseCrf) + offset, 14, 34);
+}
+/** One-line human summary, e.g. `standard · zoom 3.0% · rotate 2.0° · speed ×1.020`. */
+export function describeDedupeEffects(effects, presetName) {
+    const bits = [];
+    if (presetName)
+        bits.push(presetName);
+    if (!near(effects.zoom, 1))
+        bits.push(`zoom ${pct(effects.zoom)}`);
+    if (!near(effects.rotate, 0))
+        bits.push(`rotate ${fixed(effects.rotate)}°`);
+    if (!near(effects.skew, 0))
+        bits.push(`skew ${fixed(effects.skew)}%`);
+    if (!near(effects.tilt, 0))
+        bits.push(`tilt ${fixed(effects.tilt)}°`);
+    if (!near(effects.speed, 1))
+        bits.push(`speed ×${fixed(effects.speed, 3)}`);
+    if (!near(effects.saturation, 1))
+        bits.push(`sat ${pct(effects.saturation)}`);
+    if (!near(effects.contrast, 1))
+        bits.push(`contrast ${pct(effects.contrast)}`);
+    if (!near(effects.brightness, 1))
+        bits.push(`bright ${pct(effects.brightness)}`);
+    if (!near(effects.hue_rotate, 0))
+        bits.push(`hue ${fixed(effects.hue_rotate)}°`);
+    if (effects.noise > 0.001)
+        bits.push(`grain ${fixed(effects.noise, 1)}`);
+    if (effects.blur > 0.001)
+        bits.push(`blur ${fixed(effects.blur, 2)}`);
+    if (effects.horizontal_flip)
+        bits.push("mirrored");
+    return bits.length ? bits.join(" · ") : "no-op";
+}
+// ---------------------------------------------------------------------------
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, value));
+}
+function round4(value) {
+    return Number.isFinite(value) ? Number(value.toFixed(4)) : 0;
+}
+function near(value, target, epsilon = 0.0005) {
+    return Number.isFinite(value) && Math.abs(value - target) < epsilon;
+}
+function fixed(value, digits = 4) {
+    return (Number.isFinite(value) ? value : 0).toFixed(digits).replace(/0+$/, "").replace(/\.$/, "") || "0";
+}
+function pct(multiplier) {
+    return `${((multiplier - 1) * 100).toFixed(1)}%`;
+}
+function evenDim(value) {
+    const rounded = Math.max(2, Math.round(Number(value) || 2));
+    return rounded % 2 === 0 ? rounded : rounded + 1;
+}
+/** ffmpeg wants `0xRRGGBB` (or a named color); anything else → the orange default. */
+function normalizeFfmpegHex(value) {
+    const trimmed = String(value ?? "").trim();
+    const hex = /^#?([0-9a-f]{6})$/i.exec(trimmed);
+    if (hex)
+        return `0x${hex[1]}`;
+    return /^[a-z]+$/i.test(trimmed) ? trimmed : "0xFF8C00";
+}
+//# sourceMappingURL=dedupe-recipe.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.31",
+  "version": "0.21.32",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "dist/src/devcli/clips.js",
     "dist/src/devcli/composition-edit.js",
     "dist/src/devcli/cost-mode.js",
+    "dist/src/devcli/dedupe-local.js",
     "dist/src/devcli/doctor.js",
     "dist/src/devcli/handoff.js",
     "dist/src/devcli/greenscreen-local.js",
@@ -97,6 +98,7 @@
     "test:studio-brand": "node --import tsx --test test/studio-brand.test.ts",
     "test:stickers": "node --import tsx --test test/sticker-pack.test.ts",
     "test:social-recycle": "node --import tsx --test test/social-recycle.test.ts",
+    "test:dedupe": "node --import tsx --test test/dedupe-recipe.test.ts",
     "check:skills": "node scripts/build-director-skill-rollup.mjs --check && node scripts/check-skill-routes.mjs",
     "benchmark:editor-chat": "node --import tsx scripts/benchmark-editor-chat-harness.mjs",
     "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",