@mevdragon/vidfarm-devcli 0.20.4 → 0.20.6

package/dist/src/services/hyperframes.js

@@ -1550,10 +1550,47 @@ Return strictly valid JSON matching this schema:
       "arc": string,
       "peak_moment": string,
       "mechanism": string,
+      "contrast": string,
       "humor": string,
+      "audio_visual_tension": string,
       "delivery": string,
       "preserve": [string, ...]
     },
+    "static_vs_pivot": {
+      "summary": string,
+      "scene_replacement": {
+        "overall": "replace_most" | "replace_some" | "keep_most" | "keep_all",
+        "reason": string,
+        "must_keep": [string, ...],
+        "should_replace": [string, ...],
+        "load_bearing_scenes": [string, ...]
+      },
+      "narration": {
+        "overall": "keep_original" | "customize_script" | "optional",
+        "reason": string,
+        "same_timing_required": boolean,
+        "use_premium_tts_when_customizing": boolean
+      },
+      "music": {
+        "overall": "keep_original" | "recreate_under_narration" | "optional" | "none",
+        "reason": string,
+        "volume_guidance": string
+      },
+      "captions": {
+        "overall": "reuse_existing" | "retime_to_new_narration" | "optional" | "none",
+        "reason": string,
+        "animation_dependency": string
+      },
+      "visual_rebuild": {
+        "default_strategy": "ai_images_with_ken_burns" | "real_footage" | "mixed",
+        "reason": string
+      },
+      "viral_dna": {
+        "must_keep": [string, ...],
+        "flexible": [string, ...],
+        "do_not_change": [string, ...]
+      }
+    },
     "preserve": [string, ...],
     "avoid": [string, ...],
     "promotions": [string, ...],
@@ -1598,10 +1635,20 @@ VIRAL_DNA RULES:
   - "arc": how the feeling MOVES across the runtime (e.g. "curiosity → mounting tension → relief-laugh", "flat setup → sudden absurd turn").
   - "peak_moment": the single beat that lands the emotional hit — the punchline, the reveal, the gut-punch, the beat-drop — and roughly when.
   - "mechanism": WHY it lands — the technique doing the work (comedic timing, irony, subversion of expectation, escalation, deadpan intonation, relatability, a trending-sound drop synced to the visual). Weigh the AUDIO here: on TikTok/Reels the trending sound or music bed is frequently the single biggest driver of the emotional hit, so if a recognizable trending sound, a beat drop, or a music swell is doing the work, name it as the mechanism.
-  - "humor": if it's funny, state what the JOKE actually is and why it works, concretely enough that a remixer can rebuild the same joke with new subject matter; write "none" if the format is not comedic.
+  - "contrast": the specific mismatch / juxtaposition that creates the feeling. This is CRITICAL for irony- or sass-driven formats: identify the actual tension, not just the visible gesture. Examples: "hard, macho soundtrack over a dainty office-laptop scene", "overconfident delivery about a trivial preference", "luxury attitude applied to a mundane workflow". If there is no real mismatch, write "none".
+  - "humor": if it's funny, state what the JOKE actually is and why it works, concretely enough that a remixer can rebuild the same joke with new subject matter; write "none" if the format is not comedic. Focus on the underlying bit, not surface choreography.
+  - "audio_visual_tension": describe how the SOUND and VISUALS interact emotionally: whether the soundtrack / vocal cadence reinforces the visuals, undercuts them, or creates a deliberate mismatch. Name the exact pairing if that's the joke or swagger engine; write "none" only if audio contributes nothing.
   - "delivery": the performance cues to preserve so the vibe survives — speech intonation / cadence (from the AUDIO TRANSCRIPT), the pause held before the punchline, a facial beat or reaction, and especially the SOUND: the music / trending-audio bed, where the beat drop or lyric hit lands relative to the cut, a music swell, an sfx sting, the deadpan-then-cut. This is what keeps intonation, comedic timing, and the audio-driven vibe from being lost in a remix.
   - "preserve": 2-4 emotional beats a remix MUST keep to reproduce the same feeling (e.g. "keep the beat drop landing exactly on the reveal cut", "hold the silent beat before the reveal", "keep the flat unbothered delivery", "the payoff must undercut the buildup, not confirm it").
-  Use BOTH the frames and the AUDIO TRANSCRIPT block above. Never leave emotional_punch empty — infer the feeling from the frames, captions, and pacing even when there is no audio, and when the audio is music-only, treat the sound itself as the emotional engine.
+  Use BOTH the frames and the AUDIO TRANSCRIPT block above. Never leave emotional_punch empty — infer the feeling from the frames, captions, and pacing even when there is no audio, and when the audio is music-only, treat the sound itself as the emotional engine. Do NOT over-index on a single gesture or hand movement if the real emotional engine is the character attitude, the soundtrack choice, the setting mismatch, or the audio-vs-visual contrast.
+- "static_vs_pivot": this is the load-bearing reuse guidance for lazy prompts like "please recreate this video for my business". Make it operational, not vague.
+  - "summary": one sentence on what can change versus what must stay.
+  - "scene_replacement": decide whether most scenes should be replaced or only some, why, which scenes are load-bearing, and which scenes are the first candidates to swap.
+  - "narration": decide whether the original spoken audio can stay as-is (for example because it is a generic or trending sound) or whether it must be customized because the words are source-specific. Set "customize_script" whenever the spoken words would stop making sense after a subject swap. If narration is timing-sensitive, set same_timing_required true.
+  - "music": decide whether original music should stay, be recreated under a new narration, or is irrelevant. Include simple mix guidance like "keep low under VO" or "music is the main viral engine".
+  - "captions": decide whether existing caption timing/animation can be reused, whether they must be re-timed to new narration, or whether captions are not important. Call out if the animation is tightly coupled to the spoken words.
+  - "visual_rebuild": default strategy for replacement visuals. When the source mainly uses graphics, screenshots, product cards, or still-like scenes that do not need expensive motion video, prefer "ai_images_with_ken_burns" and explain that slow pan/zoom is enough.
+  - "viral_dna": separate format elements into "must_keep", "flexible", and "do_not_change" so an agent can preserve the viral structure while swapping subject matter.
 - "preserve": 3-5 concrete elements a remixer MUST keep to preserve the format (e.g., "Pinned comment stays on-screen the whole video", "Wedding dance payoff shot").
 - "avoid": 3-5 things that would break the format if changed (e.g., "Do not remove the on-screen text overlay", "Do not slow the cuts below 1.5s").
 - "promotions": 3-5 categories of product / service / offer this exact format could be reused to promote, WITHOUT changing the beat structure or hook mechanic. Each item is a concrete pitchable use-case, not a genre. Examples: "SaaS free-trial signup (before/after workflow)", "Fitness challenge (7-day transformation)", "Local restaurant grand-opening (line-out-the-door proof)", "Ebook / course launch (result-first payoff)", "Real-estate open-house (walk-through reveal)". Anchor each promotion to the same viral tactic captured in "hook" — do not invent unrelated verticals.
@@ -1781,10 +1828,36 @@ function resolveFontSize(input) {
     return normalizeFontSize(input.fontSize, input.canvasHeight);
 }
 const DEFAULT_EMOTIONAL_PUNCH = {
-    core_emotion: "", tone: "", arc: "", peak_moment: "", mechanism: "", humor: "", delivery: "", preserve: []
+    core_emotion: "",
+    tone: "",
+    arc: "",
+    peak_moment: "",
+    mechanism: "",
+    contrast: "",
+    humor: "",
+    audio_visual_tension: "",
+    delivery: "",
+    preserve: []
 };
 export const DEFAULT_VIRAL_DNA = {
-    trend_tagline: "", hook: "", retention: "", payoff: "", emotional_punch: { ...DEFAULT_EMOTIONAL_PUNCH }, preserve: [], avoid: [], promotions: [], keywords: []
+    trend_tagline: "",
+    hook: "",
+    retention: "",
+    payoff: "",
+    emotional_punch: { ...DEFAULT_EMOTIONAL_PUNCH },
+    static_vs_pivot: {
+        summary: "",
+        scene_replacement: { overall: "replace_some", reason: "", must_keep: [], should_replace: [], load_bearing_scenes: [] },
+        narration: { overall: "optional", reason: "", same_timing_required: false, use_premium_tts_when_customizing: true },
+        music: { overall: "optional", reason: "", volume_guidance: "" },
+        captions: { overall: "optional", reason: "", animation_dependency: "" },
+        visual_rebuild: { default_strategy: "mixed", reason: "" },
+        viral_dna: { must_keep: [], flexible: [], do_not_change: [] }
+    },
+    preserve: [],
+    avoid: [],
+    promotions: [],
+    keywords: []
 };
 function normalizeEmotionalPunch(value) {
     if (!value || typeof value !== "object")
@@ -1800,11 +1873,89 @@ function normalizeEmotionalPunch(value) {
         arc: asString(record.arc ?? record.emotional_arc),
         peak_moment: asString(record.peak_moment ?? record.peakMoment),
         mechanism: asString(record.mechanism),
+        contrast: asString(record.contrast),
         humor: asString(record.humor),
+        audio_visual_tension: asString(record.audio_visual_tension ?? record.audioVisualTension),
         delivery: asString(record.delivery),
         preserve: asStringArray(record.preserve).slice(0, 4)
     };
 }
+function normalizeStaticVsPivot(value) {
+    const fallback = DEFAULT_VIRAL_DNA.static_vs_pivot;
+    if (!value || typeof value !== "object") {
+        return {
+            ...fallback,
+            scene_replacement: { ...fallback.scene_replacement },
+            narration: { ...fallback.narration },
+            music: { ...fallback.music },
+            captions: { ...fallback.captions },
+            visual_rebuild: { ...fallback.visual_rebuild },
+            viral_dna: { ...fallback.viral_dna }
+        };
+    }
+    const record = value;
+    const asString = (v) => typeof v === "string" ? v.trim() : "";
+    const asStringArray = (v) => Array.isArray(v)
+        ? v.map((item) => (typeof item === "string" ? item.trim() : "")).filter((item) => item.length > 0)
+        : [];
+    const sceneReplacement = record.scene_replacement && typeof record.scene_replacement === "object"
+        ? record.scene_replacement
+        : {};
+    const narration = record.narration && typeof record.narration === "object"
+        ? record.narration
+        : {};
+    const music = record.music && typeof record.music === "object"
+        ? record.music
+        : {};
+    const captions = record.captions && typeof record.captions === "object"
+        ? record.captions
+        : {};
+    const visualRebuild = record.visual_rebuild && typeof record.visual_rebuild === "object"
+        ? record.visual_rebuild
+        : {};
+    const viralDna = record.viral_dna && typeof record.viral_dna === "object"
+        ? record.viral_dna
+        : {};
+    const oneOf = (v, allowed, fallbackValue) => {
+        const text = asString(v);
+        return allowed.includes(text) ? text : fallbackValue;
+    };
+    return {
+        summary: asString(record.summary),
+        scene_replacement: {
+            overall: oneOf(sceneReplacement.overall, ["replace_most", "replace_some", "keep_most", "keep_all"], "replace_some"),
+            reason: asString(sceneReplacement.reason),
+            must_keep: asStringArray(sceneReplacement.must_keep),
+            should_replace: asStringArray(sceneReplacement.should_replace),
+            load_bearing_scenes: asStringArray(sceneReplacement.load_bearing_scenes)
+        },
+        narration: {
+            overall: oneOf(narration.overall, ["keep_original", "customize_script", "optional"], "optional"),
+            reason: asString(narration.reason),
+            same_timing_required: narration.same_timing_required === true,
+            use_premium_tts_when_customizing: narration.use_premium_tts_when_customizing !== false
+        },
+        music: {
+            overall: oneOf(music.overall, ["keep_original", "recreate_under_narration", "optional", "none"], "optional"),
+            reason: asString(music.reason),
+            volume_guidance: asString(music.volume_guidance)
+        },
+        captions: {
+            overall: oneOf(captions.overall, ["reuse_existing", "retime_to_new_narration", "optional", "none"], "optional"),
+            reason: asString(captions.reason),
+            animation_dependency: asString(captions.animation_dependency)
+        },
+        visual_rebuild: {
+            default_strategy: oneOf(visualRebuild.default_strategy, ["ai_images_with_ken_burns", "real_footage", "mixed"], "mixed"),
+            reason: asString(visualRebuild.reason)
+        },
+        viral_dna: {
+            must_keep: asStringArray(viralDna.must_keep),
+            flexible: asStringArray(viralDna.flexible),
+            do_not_change: asStringArray(viralDna.do_not_change)
+        }
+    };
+}
 function normalizeViralDna(value) {
     if (!value || typeof value !== "object")
         return DEFAULT_VIRAL_DNA;
@@ -1819,6 +1970,7 @@ function normalizeViralDna(value) {
         retention: asString(record.retention),
         payoff: asString(record.payoff),
         emotional_punch: normalizeEmotionalPunch(record.emotional_punch ?? record.emotionalPunch),
+        static_vs_pivot: normalizeStaticVsPivot(record.static_vs_pivot ?? record.staticVsPivot),
         preserve: asStringArray(record.preserve),
         avoid: asStringArray(record.avoid),
         promotions: asStringArray(record.promotions),
@@ -1865,12 +2017,26 @@ function buildEditorHarnessPrompt(input) {
     const roleVocab = SCENE_ROLE_VOCAB.join(" | ");
     const formatVocab = CONTENT_FORMATS.join(" | ");
     const audioDigest = buildAudioDigestForPrompt(input.transcript ?? null);
+    const emotional = input.viralDna?.emotional_punch;
+    const emotionalSnapshot = emotional && [
+        emotional.core_emotion,
+        emotional.tone,
+        emotional.arc,
+        emotional.peak_moment,
+        emotional.mechanism,
+        emotional.contrast,
+        emotional.humor,
+        emotional.audio_visual_tension,
+        emotional.delivery
+    ].some((value) => value && value.trim().length > 0)
+        ? `\nVIRAL DNA FEELING SNAPSHOT (operationalize this in the harness; do NOT drift from it):\n- core_emotion: ${emotional.core_emotion || "—"}\n- tone: ${emotional.tone || "—"}\n- arc: ${emotional.arc || "—"}\n- peak_moment: ${emotional.peak_moment || "—"}\n- mechanism: ${emotional.mechanism || "—"}\n- contrast: ${emotional.contrast || "—"}\n- humor: ${emotional.humor || "—"}\n- audio_visual_tension: ${emotional.audio_visual_tension || "—"}\n- delivery: ${emotional.delivery || "—"}\n- preserve: ${(emotional.preserve || []).join("; ") || "—"}\n`
+        : "";
     return `You are Vidfarm's EDITING DIRECTOR. You are studying a short-form video to write an EDITOR HARNESS — a compact, technical brief that lets another AI editor recreate this video's STYLE (not its exact content) in one clean pass on a timeline editor (scenes, captions, audio, transitions, keyframes).
 
 This is DIFFERENT from "viral DNA" (why the video works / what to preserve). The harness is HOW to edit: pace, typography, b-roll usage, transitions, audio bed, and the role each scene plays. Be concrete and directive — every field should be something an editor can act on, not vibes.
 
 Video duration: ${input.durationSeconds.toFixed(2)} seconds.
-${frameListing}${cutListing}${audioDigest}${promptHint}
+${frameListing}${cutListing}${audioDigest}${emotionalSnapshot}${promptHint}
 Return strictly valid JSON matching this schema:
 {
   "format": string,                 // one of: ${formatVocab}
@@ -1933,7 +2099,7 @@ RULES:
 - Ground pacing numbers on the detected cuts + duration when cuts are supplied; otherwise estimate from the frames. Round avg_scene_seconds and cuts_per_10s to at most 2 decimals.
 - "scenes": 3-8 entries covering the whole runtime in order, each tied to a real moment you see. Reserve importance "critical" for the 1-3 beats that actually carry the style/retention (usually the hook + payoff).
 - Prefer the caption_style / transition / shot_kind vocabulary above so the editor can map straight to presets; a free-form label is fine when nothing fits.
-- "emotional": this is HOW to edit so the FEELING survives — the vibe, the joke, the intonation, and the SOUND are the first things a remix flattens, so make these directive. Use the AUDIO TRANSCRIPT block: on TikTok/Reels the trending sound / music bed is often the biggest carrier of the feeling. "target_feeling" = the emotion the recreated edit must produce; "tone" = the register to hold; "comedic_timing" = the exact editing move that sells the joke (the beat held before a cut, the deadpan-then-punch, the sfx sting or beat-drop on the button word) or "none"; "intonation" = the vocal delivery/cadence to preserve on any VO or on-cam speech (or "none" if silent) — flag it if the speech must be re-voiced in the SAME cadence; "vibe_anchors" = 2-4 concrete edit choices that carry the emotion, and include the audio ones (e.g. "keep the trending sound and land the beat drop on the reveal cut", "swell the music on the payoff", "hold a full beat of silence before the reveal cut", "cut hard on the punch word"). Infer the feeling from frames + pacing even without audio, and when the audio is music-only treat the sound as the emotional engine; never leave it empty.
+- "emotional": this is HOW to edit so the FEELING survives — the vibe, the joke, the intonation, and the SOUND are the first things a remix flattens, so make these directive. Use the AUDIO TRANSCRIPT block: on TikTok/Reels the trending sound / music bed is often the biggest carrier of the feeling. "target_feeling" = the emotion the recreated edit must produce; "tone" = the register to hold; "comedic_timing" = the exact editing move that sells the joke (the beat held before a cut, the deadpan-then-punch, the sfx sting or beat-drop on the button word) or "none"; "intonation" = the vocal delivery/cadence to preserve on any VO or on-cam speech (or "none" if silent) — flag it if the speech must be re-voiced in the SAME cadence; "vibe_anchors" = 2-4 concrete edit choices that carry the emotion, and include the audio ones (e.g. "keep the trending sound and land the beat drop on the reveal cut", "swell the music on the payoff", "hold a full beat of silence before the reveal cut", "cut hard on the punch word"). When the viral-DNA snapshot above names a contrast or audio_visual_tension, convert that into actionable edit moves instead of drifting to superficial gestures. Infer the feeling from frames + pacing even without audio, and when the audio is music-only treat the sound as the emotional engine; never leave it empty.
 - Keep every string tight and directive. Never invent audio you cannot infer — say "none"/"unknown" instead.
 - Output ONLY the JSON object.`;
 }
@@ -2030,7 +2196,8 @@ async function runEditorHarnessPass(input) {
         frameTimestamps: input.frames.map((f) => f.timestamp),
         sceneCuts: input.sceneCuts,
         userPrompt: input.userPrompt ?? null,
-        transcript: input.transcript ?? null
+        transcript: input.transcript ?? null,
+        viralDna: input.viralDna ?? null
     });
     const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
     return normalizeEditorHarness(attempt.result);
@@ -2437,13 +2604,12 @@ export async function smartDecomposeVideo(input) {
             sceneCuts,
             transcript
         });
-        // Phase 2 — vision, OCR, product-placement, and the editor harness run
-        // concurrently, all now transcript-aware. OCR and placement failures are
-        // non-fatal. The placement + harness calls are DELIBERATELY separate
-        // requests from the caption/scene vision call so they can never dilute
-        // timeline-layer quality — they reuse the same sparse frames (no extra
-        // ffmpeg) plus the transcript from phase 1.
-        const [attempt, ocrFrames, placementSurfaces, editorHarness] = await Promise.all([
+        // Phase 2 — vision, OCR, and product-placement run concurrently, all now
+        // transcript-aware. OCR and placement failures are non-fatal. The
+        // placement call is DELIBERATELY separate from the caption/scene vision
+        // call so it can never dilute timeline-layer quality — it reuses the same
+        // sparse frames (no extra ffmpeg) plus the transcript from phase 1.
+        const [attempt, ocrFrames, placementSurfaces] = await Promise.all([
             callVisionWithFallback({
                 prompt,
                 frames,
@@ -2461,19 +2627,6 @@ export async function smartDecomposeVideo(input) {
             }).catch((err) => {
                 console.error("smart decompose placement pass failed", err instanceof Error ? err.message : err);
                 return [];
-            }),
-            // Editor harness — technical editing direction. Isolated call in the same
-            // burst (reuses these frames + the detected cuts + the transcript); non-fatal.
-            runEditorHarnessPass({
-                frames,
-                keys: input.keys,
-                durationSeconds: meta.durationSeconds,
-                sceneCuts,
-                userPrompt: input.userPrompt ?? null,
-                transcript
-            }).catch((err) => {
-                console.error("smart decompose editor-harness pass failed", err instanceof Error ? err.message : err);
-                return DEFAULT_EDITOR_HARNESS;
             })
         ]);
         devLog("hyperframes.smart_decompose.ocr_completed", {
@@ -2559,6 +2712,21 @@ export async function smartDecomposeVideo(input) {
         if (input.trendTaglineHint && input.trendTaglineHint.trim().length > 0) {
             viralDna.trend_tagline = input.trendTaglineHint.trim();
         }
+        // Editor harness — technical editing direction. Run AFTER viral DNA is
+        // normalized so the harness can operationalize the exact emotional punch
+        // instead of guessing independently and drifting from the decompose result.
+        const editorHarness = await runEditorHarnessPass({
+            frames,
+            keys: input.keys,
+            durationSeconds: meta.durationSeconds,
+            sceneCuts,
+            userPrompt: input.userPrompt ?? null,
+            transcript,
+            viralDna
+        }).catch((err) => {
+            console.error("smart decompose editor-harness pass failed", err instanceof Error ? err.message : err);
+            return DEFAULT_EDITOR_HARNESS;
+        });
         // NOTE: the per-scene clip-annotation + content-format pass is deliberately
         // NOT run here — it is a separate vision call that would risk the ~60s origin
         // timeout on longer videos. /auto-decompose seeds scene-annotations.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "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": {
@@ -32,7 +32,7 @@
   "scripts": {
     "dev": "tsx --import ./src/instrument.ts watch src/index.ts",
     "dev:frontend": "node scripts/build-homepage-client.mjs --watch",
-    "dev:cli": "tsx src/cli.ts --help",
+    "dev:cli": "tsx src/cli.ts",
     "build:frontend": "node scripts/build-homepage-client.mjs",
     "build:hyperframes-editor": "cd demo && node scripts/build.mjs",
     "operator:template-artifact": "node scripts/platform-operator-template-artifact.mjs",