@officexapp/vidfarm-devcli 0.21.30 → 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/devcli/handoff.js

@@ -22,7 +22,7 @@
 // Both builders return plain text meant to be shown verbatim to the user, plus a
 // structured form for `--json` so an agent can render it its own way. No network,
 // no backend imports — this module is pure string assembly.
-import { pickPlateColor } from "./sticker-pack.js";
+import { pickPlateColor, keySafeArtInstruction } from "./sticker-pack.js";
 const DEFAULT_STYLE = "simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows, no text";
 /** Pick a sensible grid for N items (roughly square, wider than tall). */
 function gridFor(count) {
@@ -67,18 +67,22 @@ export function buildImageHandoff(input) {
             `CRITICAL: every object must be fully separated from the others by a clear margin of plain ${keyColor} background —`,
             `nothing touching, overlapping or connected, and nothing touching the image edge.`,
             `One consistent art style, line weight and palette across all objects. Front-facing, centered in its own cell.`,
+            // Load-bearing: the user is about to spend their own time on this sheet,
+            // and hollow/outline-only art comes back as rims around holes.
+            keySafeArtInstruction(keyColor),
             `Square image, high resolution.`
         ].join(" ")
         : [
             `${input.theme} — ${style} — isolated on a solid pure ${keyColor} background`,
             `(flat, evenly lit, no gradient, no shadow cast on the background, no text).`,
             `Center the subject with generous empty margin on all sides, crisp clean edges, single subject.`,
+            keySafeArtInstruction(keyColor),
             `Square image, high resolution.`
         ].join(" ");
     const steps = pack
         ? [
             "Open a FREE image generator you're already signed into (list below).",
-            "Paste the prompt below and generate. If any two objects come out touching, re-generate asking for wider spacing — touching objects get cut out as one sticker.",
+            "Paste the prompt below and generate. Two checks before you send it back: (a) if any two objects are touching, re-generate asking for wider spacing — touching objects get cut out as ONE sticker; (b) if any object is a hollow outline with the background showing through its middle, re-generate asking for solid fills — that interior gets deleted with the background and the sticker ends up as a rim around a hole.",
             "Download the image (PNG preferred) and tell me the file path — or drop it in this project folder.",
             `I'll split it into individual transparent stickers locally for $0: \`vidfarm sticker-pack <sheet> --out-dir ${outDir}\`.`
         ]

package/dist/src/devcli/sticker-pack.js

@@ -132,6 +132,42 @@ export async function detectPlateColor(sourcePath, opts = {}) {
     const hex = `#${avg.map((v) => v.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
     return { hex, rgb: avg };
 }
+// ── Key-safe ART instruction ─────────────────────────────────────────────────
+// Picking a plate the art doesn't use (above) is only HALF of surviving a chroma
+// key. The other half is what the art is made of, and it's the failure we see in
+// the wild: an image model hears "sticker on a green plate" and draws OUTLINE
+// art — a colored stroke with the shape's interior left as bare background. On
+// screen that looks fine. After the key, the interior is gone, and the sticker
+// composites as a rim floating around a see-through hole.
+//
+// The same failure arrives three other ways: a fill that's a near-shade of the
+// plate (keyed by tolerance, not by exact match), a translucent/glassy material
+// that lets the plate through, and a soft glow/drop-shadow that fades INTO the
+// plate at the edges.
+//
+// All four are prompt-preventable, so every generation path that mints art
+// destined for a key (cutout, sticker-pack, the hand-off brief the user pastes
+// into a free web tool) appends this clause. Detection after the fact is the net
+// (`detectEnclosedHoles` below) — this is the mechanism.
+/**
+ * The "your art has to survive the key" clause, worded for an image model.
+ * Append to any prompt whose output will be chroma-keyed on `keyColorHex`.
+ */
+export function keySafeArtInstruction(keyColorHex) {
+    const hex = keyColorHex.toUpperCase();
+    return (`KEY-SAFE ARTWORK (the ${hex} background gets deleted, so anything ${hex} on the art is deleted too): ` +
+        `every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a ` +
+        `different color. NO outline-only / hollow / line-art objects, and never leave a shape's interior as bare ` +
+        `background. No part of any object — fill, outline, highlight, gradient, glow, shading or detail — may be ${hex} ` +
+        `or any near-shade, tint or tone of ${hex}. No transparent, translucent, glassy, glowing, misty or ghosted ` +
+        `materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the ` +
+        `background. Keep the whole palette in strong contrast to ${hex}. The background must be visible ONLY around the ` +
+        `outside of the objects, never showing through inside them.`);
+}
+/** At/above this `hole_pct` a sticker is worth warning about: past ~a fifth of
+ *  its own box, "the key ate the fill" is far more likely than "the artist drew
+ *  a ring". Tuned to stay quiet on letter counters, handles and small gaps. */
+export const HOLE_WARN_PCT = 20;
 /** Read a still's alpha plane as raw 8-bit luma at a given size (bundle-safe:
  *  ffmpeg's `alphaextract` writes alpha as luma; rawvideo skips any decoding on
  *  our side). Returns exactly width*height bytes. */
@@ -199,6 +235,93 @@ function dilate(mask, w, h, radius) {
     }
     return out;
 }
+/**
+ * Find transparent islands that are fully SURROUNDED by opaque art — the exact
+ * signature of the "hollow sticker" bug: art drawn as an outline (or filled in a
+ * near-plate shade) has its middle deleted by the key, and composites as a rim
+ * around a see-through hole.
+ *
+ * Mechanically it's the complement of a background flood-fill: every transparent
+ * pixel reachable from the mask's border is the plate doing its job; every
+ * transparent pixel that is NOT reachable is a hole punched inside something.
+ * 4-connected on purpose — an 8-connected fill leaks through a 1px diagonal
+ * seam in antialiased line art and would under-report every real hole.
+ *
+ * Note this cannot distinguish a bug from a deliberate ring/donut/picture-frame,
+ * so callers WARN on the result, never reject it.
+ */
+export function detectEnclosedHoles(mask, w, h, opts = {}) {
+    const reachable = new Uint8Array(w * h);
+    const queue = new Int32Array(w * h);
+    let head = 0;
+    let tail = 0;
+    const push = (p) => {
+        if (!mask[p] && !reachable[p]) {
+            reachable[p] = 1;
+            queue[tail++] = p;
+        }
+    };
+    for (let x = 0; x < w; x++) {
+        push(x);
+        push((h - 1) * w + x);
+    }
+    for (let y = 0; y < h; y++) {
+        push(y * w);
+        push(y * w + (w - 1));
+    }
+    while (head < tail) {
+        const p = queue[head++];
+        const py = (p / w) | 0;
+        const px = p - py * w;
+        if (px > 0)
+            push(p - 1);
+        if (px < w - 1)
+            push(p + 1);
+        if (py > 0)
+            push(p - w);
+        if (py < h - 1)
+            push(p + w);
+    }
+    // Anything transparent and unreached is enclosed — group it into islands.
+    const minAreaPx = Math.max(1, Math.round(opts.minAreaPx ?? 4));
+    const seen = new Uint8Array(w * h);
+    const holes = [];
+    const stack = new Int32Array(w * h);
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] || reachable[start] || seen[start])
+            continue;
+        let top = 0;
+        stack[top++] = start;
+        seen[start] = 1;
+        const hole = { minX: w, minY: h, maxX: -1, maxY: -1, area: 0 };
+        while (top > 0) {
+            const p = stack[--top];
+            const py = (p / w) | 0;
+            const px = p - py * w;
+            hole.area++;
+            if (px < hole.minX)
+                hole.minX = px;
+            if (px > hole.maxX)
+                hole.maxX = px;
+            if (py < hole.minY)
+                hole.minY = py;
+            if (py > hole.maxY)
+                hole.maxY = py;
+            const neighbors = [px > 0 ? p - 1 : -1, px < w - 1 ? p + 1 : -1, py > 0 ? p - w : -1, py < h - 1 ? p + w : -1];
+            for (const q of neighbors) {
+                if (q < 0 || mask[q] || reachable[q] || seen[q])
+                    continue;
+                seen[q] = 1;
+                stack[top++] = q;
+            }
+        }
+        // Sub-threshold islands are antialiasing dropouts and despill speckle, not
+        // a missing fill — a real hollow interior is orders of magnitude bigger.
+        if (hole.area >= minAreaPx)
+            holes.push(hole);
+    }
+    return holes;
+}
 /**
  * Find every item on a keyed plate by segmenting its alpha channel into
  * connected islands of opaque pixels — the automatic replacement for measuring
@@ -312,22 +435,93 @@ export async function segmentAlphaComponents(input) {
     // ---- Map sample-space boxes back to source pixels --------------------------
     // One sample pixel of slack on each side covers the downscale's rounding, so a
     // subject's outermost antialiased edge never gets clipped off.
+    // ---- Attribute enclosed holes to the item that surrounds them --------------
+    // A hole lives strictly inside the art that encloses it, so its center falls
+    // in that item's box. Boxes can nest (a small icon inside a big backdrop), so
+    // the SMALLEST containing box wins — the nearest enclosing art is the owner.
+    const holes = detectEnclosedHoles(mask, sw, sh, { minAreaPx: Math.max(6, Math.round(total * 0.00005)) });
+    const holeArea = new Array(ordered.length).fill(0);
+    const holeCount = new Array(ordered.length).fill(0);
+    for (const hole of holes) {
+        const cx = (hole.minX + hole.maxX) / 2;
+        const cy = (hole.minY + hole.maxY) / 2;
+        let owner = -1;
+        let ownerArea = Infinity;
+        for (let i = 0; i < ordered.length; i++) {
+            const b = ordered[i];
+            if (cx < b.minX || cx > b.maxX || cy < b.minY || cy > b.maxY)
+                continue;
+            const boxArea = (b.maxX - b.minX + 1) * (b.maxY - b.minY + 1);
+            if (boxArea < ownerArea) {
+                owner = i;
+                ownerArea = boxArea;
+            }
+        }
+        if (owner >= 0) {
+            holeArea[owner] += hole.area;
+            holeCount[owner]++;
+        }
+    }
     const inv = 1 / scale;
     const components = ordered.map((b, i) => {
         const x0 = Math.max(0, Math.floor((b.minX - 1) * inv));
         const y0 = Math.max(0, Math.floor((b.minY - 1) * inv));
         const x1 = Math.min(dims.width, Math.ceil((b.maxX + 2) * inv));
         const y1 = Math.min(dims.height, Math.ceil((b.maxY + 2) * inv));
+        // Measured against the item's own silhouette (fill + holes), not the plate:
+        // "a fifth of THIS sticker is missing" is the question that matters.
+        const silhouette = b.area + holeArea[i];
         return {
             index: i + 1,
             x: x0,
             y: y0,
             width: Math.max(1, x1 - x0),
             height: Math.max(1, y1 - y0),
-            area_pct: Math.round((b.area / total) * 1000) / 10
+            area_pct: Math.round((b.area / total) * 1000) / 10,
+            holes: holeCount[i],
+            hole_pct: silhouette > 0 ? Math.round((holeArea[i] / silhouette) * 1000) / 10 : 0
         };
     });
-    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected };
+    const hollow = components.filter((c) => c.hole_pct >= HOLE_WARN_PCT).map((c) => c.index);
+    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected, hollow };
+}
+/**
+ * The single-subject version of the hollow-sticker check: does THIS keyed still
+ * have transparency punched through the middle of its art? Used by `cutout`,
+ * which has one subject and so needs no segmentation — just the same
+ * background-flood-fill complement over the whole alpha plane.
+ */
+export async function analyzeKeyedArt(sourcePath) {
+    if (!existsSync(sourcePath))
+        return null;
+    const dims = await probeImageDimensions(sourcePath);
+    if (!dims)
+        return null;
+    const longSide = Math.max(dims.width, dims.height);
+    const scale = longSide > 640 ? 640 / longSide : 1;
+    const sw = Math.max(1, Math.round(dims.width * scale));
+    const sh = Math.max(1, Math.round(dims.height * scale));
+    let alpha;
+    try {
+        alpha = await readAlphaPlane(sourcePath, sw, sh);
+    }
+    catch {
+        return null; // no alpha channel to read → nothing to say
+    }
+    const mask = new Uint8Array(sw * sh);
+    let opaque = 0;
+    for (let i = 0; i < mask.length; i++)
+        if (alpha[i] > 8) {
+            mask[i] = 1;
+            opaque++;
+        }
+    if (!opaque)
+        return null;
+    const total = sw * sh;
+    const holes = detectEnclosedHoles(mask, sw, sh, { minAreaPx: Math.max(6, Math.round(total * 0.00005)) });
+    const holeArea = holes.reduce((sum, h) => sum + h.area, 0);
+    const hole_pct = Math.round((holeArea / (opaque + holeArea)) * 1000) / 10;
+    return { holes: holes.length, hole_pct, hollow: hole_pct >= HOLE_WARN_PCT };
 }
 /**
  * Re-encode a transparent still as a transparent GIF — the format a lot of