@officexapp/vidfarm-devcli 0.21.31 → 0.21.33

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.33",
   "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'",