@mevdragon/vidfarm-devcli 0.2.8 → 0.2.9

package/auto-create-templates/production-graph.schema.json

@@ -0,0 +1,276 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Vidfarm Auto Template Production Graph",
+  "type": "object",
+  "required": [
+    "format_summary",
+    "classification",
+    "viral_mechanics",
+    "viral_steering",
+    "visual_preservation",
+    "visual_system",
+    "timeline",
+    "replaceable_slots",
+    "production_strategy",
+    "dependencies",
+    "validation"
+  ],
+  "properties": {
+    "format_summary": {
+      "type": "object",
+      "required": ["title", "one_sentence", "source_kind", "duration_ms"],
+      "properties": {
+        "title": { "type": "string" },
+        "one_sentence": { "type": "string" },
+        "source_kind": { "type": "string" },
+        "duration_ms": { "type": "integer", "minimum": 0 },
+        "aspect_ratio": { "type": "string" },
+        "resolution": { "type": "string" }
+      }
+    },
+    "classification": {
+      "type": "object",
+      "required": ["difficulty", "primary_container", "recognition_mode", "recommended_architecture"],
+      "properties": {
+        "difficulty": { "enum": ["easy", "medium", "hard"] },
+        "primary_container": { "type": "string" },
+        "recognition_mode": { "enum": ["presentation-centric", "character-centric", "vibe-centric", "mixed"] },
+        "recommended_architecture": {
+          "enum": [
+            "static_composite",
+            "ai_image",
+            "ai_native_reference",
+            "slideshow_remotion",
+            "captioned_source_clip",
+            "ui_shell_remotion",
+            "ugc_edit",
+            "storyboard_to_video",
+            "full_ai_character_video",
+            "animated_explainer",
+            "hybrid"
+          ]
+        }
+      }
+    },
+    "viral_mechanics": {
+      "type": "object",
+      "properties": {
+        "hook": { "type": "string" },
+        "curiosity_gap": { "type": "string" },
+        "emotional_trigger": { "type": "string" },
+        "payoff": { "type": "string" },
+        "loop_or_rewatch_driver": { "type": "string" }
+      }
+    },
+    "viral_steering": {
+      "type": "object",
+      "required": ["must_preserve", "must_not_dilute", "generation_rules", "validation_checks"],
+      "properties": {
+        "must_preserve": { "type": "array", "items": { "type": "string" } },
+        "must_not_dilute": { "type": "array", "items": { "type": "string" } },
+        "generation_rules": { "type": "array", "items": { "type": "string" } },
+        "validation_checks": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "visual_preservation": {
+      "type": "object",
+      "required": ["importance", "preserve_because", "preserve", "can_change"],
+      "properties": {
+        "importance": { "enum": ["critical", "supportive", "optional", "low"] },
+        "preserve_because": { "type": "string" },
+        "preserve": { "type": "array", "items": { "type": "string" } },
+        "can_change": { "type": "array", "items": { "type": "string" } },
+        "decision_notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "visual_system": {
+      "type": "object",
+      "properties": {
+        "must_preserve": { "type": "array", "items": { "type": "string" } },
+        "can_adapt": { "type": "array", "items": { "type": "string" } },
+        "caption_rules": { "type": "array", "items": { "type": "string" } },
+        "layout_rules": { "type": "array", "items": { "type": "string" } },
+        "style_rules": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "timeline": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "start_ms", "end_ms", "duration_ms", "role", "asset_kind", "replaceability", "implementation"],
+        "properties": {
+          "id": { "type": "string" },
+          "start_ms": { "type": "integer", "minimum": 0 },
+          "end_ms": { "type": "integer", "minimum": 0 },
+          "duration_ms": { "type": "integer", "minimum": 0 },
+          "role": { "type": "string" },
+          "description": { "type": "string" },
+          "asset_kind": {
+            "enum": [
+              "source_video",
+              "generated_video",
+              "generated_image",
+              "uploaded_image",
+              "uploaded_video",
+              "rendered_ui",
+              "text",
+              "audio",
+              "shape",
+              "effect"
+            ]
+          },
+          "replaceability": { "enum": ["fixed", "variable", "optional", "generated"] },
+          "implementation": {
+            "enum": [
+              "remotion",
+              "html_canvas",
+              "ai_image",
+              "ai_video",
+              "tts",
+              "stt",
+              "ocr",
+              "user_upload",
+              "external_clip",
+              "media_search",
+              "manual_review"
+            ]
+          },
+          "inputs": { "type": "array", "items": { "type": "string" } },
+          "outputs": { "type": "array", "items": { "type": "string" } },
+          "timing_notes": { "type": "string" },
+          "layout_notes": { "type": "string" },
+          "safe_area_notes": { "type": "string" },
+          "validation_notes": { "type": "string" }
+        }
+      }
+    },
+    "timing_controls": {
+      "type": "object",
+      "properties": {
+        "total_duration_ms": { "type": "integer", "minimum": 0 },
+        "user_configurable": { "type": "boolean" },
+        "default_scene_duration_ms": { "type": "integer", "minimum": 0 },
+        "default_transition_ms": { "type": "integer", "minimum": 0 },
+        "default_hold_ms": { "type": "integer", "minimum": 0 },
+        "min_slot_duration_ms": { "type": "integer", "minimum": 0 },
+        "max_slot_duration_ms": { "type": "integer", "minimum": 0 },
+        "caption_timing_mode": {
+          "enum": ["transcript_word_timestamps", "fixed_groups", "manual_timestamps", "none"]
+        },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "typography_controls": {
+      "type": "object",
+      "properties": {
+        "user_configurable": { "type": "boolean" },
+        "recommended_font": { "type": "string" },
+        "fallback_fonts": { "type": "array", "items": { "type": "string" } },
+        "font_size_rules": { "type": "array", "items": { "type": "string" } },
+        "caption_style_rules": { "type": "array", "items": { "type": "string" } },
+        "tiktok_native_match_notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "replaceable_slots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "kind", "required", "description"],
+        "properties": {
+          "name": { "type": "string" },
+          "kind": {
+            "enum": ["text", "image", "video", "audio", "product", "person", "app_screen", "url", "stat", "brand", "style", "cta"]
+          },
+          "required": { "type": "boolean" },
+          "description": { "type": "string" },
+          "constraints": { "type": "array", "items": { "type": "string" } },
+          "default_generation_prompt": { "type": "string" }
+        }
+      }
+    },
+    "production_strategy": {
+      "type": "object",
+      "required": ["architecture_fit", "stages"],
+      "properties": {
+        "architecture_fit": {
+          "enum": ["remotion", "ai_native_reference", "hybrid", "manual_review"]
+        },
+        "remotion_ceiling_risk": {
+          "enum": ["low", "medium", "high"]
+        },
+        "architecture_rationale": { "type": "string" },
+        "ai_native_reference_plan": {
+          "type": "object",
+          "properties": {
+            "needed": { "type": "boolean" },
+            "reference_inputs": { "type": "array", "items": { "type": "string" } },
+            "prompt_contract": { "type": "array", "items": { "type": "string" } },
+            "when_to_avoid_remotion": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "character_workflow": {
+          "type": "object",
+          "properties": {
+            "detected": { "type": "boolean" },
+            "consistency_level": { "enum": ["none", "light", "strict", "identity_locked"] },
+            "characters": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["name", "role", "visual_identity"],
+                "properties": {
+                  "name": { "type": "string" },
+                  "role": { "type": "string" },
+                  "visual_identity": { "type": "array", "items": { "type": "string" } },
+                  "wardrobe": { "type": "array", "items": { "type": "string" } },
+                  "props": { "type": "array", "items": { "type": "string" } },
+                  "reference_card_requirements": { "type": "array", "items": { "type": "string" } }
+                }
+              }
+            },
+            "required_operations": {
+              "type": "array",
+              "items": {
+                "enum": ["create_character_cards", "create_storyboard", "generate_scene_videos", "stitch_video"]
+              }
+            },
+            "storyboard_requirements": { "type": "array", "items": { "type": "string" } },
+            "scene_video_requirements": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "stages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "purpose", "tools"],
+            "properties": {
+              "name": { "type": "string" },
+              "purpose": { "type": "string" },
+              "tools": { "type": "array", "items": { "type": "string" } },
+              "outputs": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "dependencies": {
+      "type": "object",
+      "properties": {
+        "needs_remotion": { "type": "boolean" },
+        "needs_ai_image": { "type": "boolean" },
+        "needs_ai_video": { "type": "boolean" },
+        "needs_tts": { "type": "boolean" },
+        "needs_stt": { "type": "boolean" },
+        "needs_ocr": { "type": "boolean" },
+        "provider_notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "properties": {
+        "checks": { "type": "array", "items": { "type": "string" } },
+        "known_risks": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/auto-create-templates/runbook.md

@@ -0,0 +1,140 @@
+# Auto-Create Template Runbook
+
+Use this runbook when a source TikTok/video should become a Vidfarm template.
+
+## 1. Create A Run Folder
+
+```bash
+RUN_ID="<format-slug>-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "auto-create-templates/runs/${RUN_ID}"/{source,frames,audio,transcripts,ocr,motion,dna,extraction,plan}
+```
+
+Copy source media and notes into `source/`.
+
+## 2. Extract Basic Media Artifacts
+
+```bash
+ffprobe -v error -show_entries format=duration:stream=codec_type,width,height,avg_frame_rate -of json source/source.mp4 \
+  > "auto-create-templates/runs/${RUN_ID}/source/ffprobe.json"
+
+ffmpeg -y -i source/source.mp4 \
+  -vf "fps=1/2,scale=240:-1,tile=3x4" \
+  -frames:v 1 "auto-create-templates/runs/${RUN_ID}/frames/contact-sheet.jpg"
+
+ffmpeg -y -i source/source.mp4 \
+  -vn -ac 1 -ar 16000 "auto-create-templates/runs/${RUN_ID}/audio/source.wav"
+```
+
+Add scene detection, OCR, and STT with whichever local tool/provider is available. The important part is writing results into the run folder so the extraction prompt can cite concrete timing and text.
+
+## 3. Scaffold Template And Run DNA
+
+```bash
+npx @mevdragon/vidfarm-devcli generate-template \
+  --slug-id <slug_id> \
+  --template-dir ./templates/vidfarm_template_<slug> \
+  --source-notes-path ./drafts/<format_slug>/source.md \
+  --source-preview-dir ./drafts/<format_slug>/preview \
+  --link-to-original "<original_url>"
+```
+
+If DNA did not run during scaffold:
+
+```bash
+npx @mevdragon/vidfarm-devcli analyze-viral-dna --template-dir ./templates/vidfarm_template_<slug>
+npx @mevdragon/vidfarm-devcli analyze-visual-dna --template-dir ./templates/vidfarm_template_<slug>
+```
+
+Copy `research/viral_dna.extraction.json` and `research/visual_dna.extraction.json` into the run folder.
+
+## 4. Decide Viral Steering And Visual Preservation
+
+Before generating the production graph, create:
+
+```txt
+auto-create-templates/runs/<run_id>/dna/preservation_decision.json
+```
+
+This decision must be viral-first:
+
+- extract the hook, tension, payoff, retention, and share/save mechanics from viral DNA
+- decide which visual traits materially support those mechanics
+- mark visual preservation as `critical`, `supportive`, `optional`, or `low`
+- list what must be preserved and what can vary
+
+Do not preserve visual traits blindly. Some formats win because of the visual container; others win because of premise, pacing, voice, or story.
+
+## 5. Decide Architecture Fit
+
+Before generating the production graph, also decide whether the format is:
+
+- `remotion`: deterministic layout/edit assembly is robust
+- `ai_native_reference`: source-faithful prompt/reference generation is more robust than layer reconstruction
+- `hybrid`: AI generates complex assets; Remotion assembles, captions, crops, times, and packages
+- `manual_review`: legal, likeness, copyright, or complexity risk needs human approval
+
+Mark `remotion_ceiling_risk` as `low`, `medium`, or `high`. High risk means the source has organic visual style, complex character acting, cinematic motion, dense texture, or too many brittle layers to rebuild deterministically.
+
+Also detect whether this is a `full_ai_character_video`. If the same generated character, mascot, clay figure, anime figure, game character, or illustrated persona appears across multiple scenes, plan the character workflow:
+
+- `create_character_cards`
+- `create_storyboard`
+- `generate_scene_videos`
+- `stitch_video`
+
+The key decision is whether identity consistency is `light`, `strict`, or `identity_locked`. Strict and identity-locked workflows should create reusable character cards before storyboarding.
+
+## 6. Generate Production Graph
+
+Send the extractor prompt, source notes, media artifacts, DNA files, preservation decision, and contact sheet to a multimodal model.
+
+Write the result to:
+
+```txt
+auto-create-templates/runs/<run_id>/extraction/production_graph.json
+```
+
+Validate against:
+
+```txt
+auto-create-templates/production-graph.schema.json
+```
+
+## 7. Generate Template Plan
+
+Send the template planner prompt plus `production_graph.json`.
+
+Write the result to:
+
+```txt
+auto-create-templates/runs/<run_id>/plan/template_plan.json
+```
+
+Validate against:
+
+```txt
+auto-create-templates/template-plan.schema.json
+```
+
+## 8. Implement
+
+Implementation should usually happen in this order:
+
+1. update `src/template.ts` metadata and schemas
+2. persist viral steering and visual preservation rules in metadata, prompt constants/comments, and docs
+3. implement operation workflows
+4. add Remotion composition only when the architecture fit calls for it
+5. wire storage outputs and manifests
+6. update template-local `SKILL.md`
+7. add representative smoke test payloads
+
+## 9. Validate
+
+```bash
+npx @mevdragon/vidfarm-devcli validate-template --template-id <slug_id>
+npx @mevdragon/vidfarm-devcli session
+```
+
+Launch at least one local job through the standard operation endpoint and inspect output artifacts.
+
+The generated output should be checked for viral compliance, not just render correctness.

package/auto-create-templates/template-plan.schema.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Vidfarm Auto Template Plan",
+  "type": "object",
+  "required": [
+    "template",
+    "viral_steering",
+    "visual_preservation",
+    "architecture_fit",
+    "character_workflow",
+    "provider_requirements",
+    "config_schema",
+    "timing_controls",
+    "typography",
+    "operations",
+    "jobs",
+    "artifacts",
+    "remotion",
+    "skill_md",
+    "validation"
+  ],
+  "properties": {
+    "template": {
+      "type": "object",
+      "required": [
+        "slug_id",
+        "title",
+        "description",
+        "viral_dna",
+        "visual_dna",
+        "proposal_generator",
+        "skeleton_prompt",
+        "sample_prompts"
+      ],
+      "properties": {
+        "slug_id": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "viral_dna": { "type": "string" },
+        "visual_dna": { "type": "string" },
+        "proposal_generator": { "type": "string" },
+        "skeleton_prompt": { "type": "string" },
+        "sample_prompts": { "type": "array", "items": { "type": "string" }, "minItems": 3 }
+      }
+    },
+    "viral_steering": {
+      "type": "object",
+      "required": ["rules", "persistence_points", "validation_checks"],
+      "properties": {
+        "rules": { "type": "array", "items": { "type": "string" } },
+        "persistence_points": { "type": "array", "items": { "type": "string" } },
+        "prompt_instructions": { "type": "array", "items": { "type": "string" } },
+        "validation_checks": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "visual_preservation": {
+      "type": "object",
+      "required": ["importance", "enforced_rules", "allowed_variations", "rationale"],
+      "properties": {
+        "importance": { "enum": ["critical", "supportive", "optional", "low"] },
+        "enforced_rules": { "type": "array", "items": { "type": "string" } },
+        "allowed_variations": { "type": "array", "items": { "type": "string" } },
+        "rationale": { "type": "string" }
+      }
+    },
+    "architecture_fit": {
+      "type": "object",
+      "required": ["mode", "remotion_ceiling_risk", "rationale"],
+      "properties": {
+        "mode": { "enum": ["remotion", "ai_native_reference", "hybrid", "manual_review"] },
+        "remotion_ceiling_risk": { "enum": ["low", "medium", "high"] },
+        "rationale": { "type": "string" },
+        "remotion_responsibilities": { "type": "array", "items": { "type": "string" } },
+        "ai_native_responsibilities": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "character_workflow": {
+      "type": "object",
+      "required": ["detected", "consistency_level", "operations"],
+      "properties": {
+        "detected": { "type": "boolean" },
+        "consistency_level": { "enum": ["none", "light", "strict", "identity_locked"] },
+        "character_card_plan": {
+          "type": "object",
+          "properties": {
+            "needed": { "type": "boolean" },
+            "cards": { "type": "array", "items": { "type": "string" } },
+            "manifest_fields": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "storyboard_plan": {
+          "type": "object",
+          "properties": {
+            "needed": { "type": "boolean" },
+            "frame_count_rule": { "type": "string" },
+            "keyframe_fields": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "scene_video_plan": {
+          "type": "object",
+          "properties": {
+            "needed": { "type": "boolean" },
+            "clip_generation_rule": { "type": "string" },
+            "reference_usage": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "operations": {
+          "type": "array",
+          "items": {
+            "enum": ["create_character_cards", "create_storyboard", "generate_scene_videos", "stitch_video"]
+          }
+        }
+      }
+    },
+    "provider_requirements": {
+      "type": "object",
+      "properties": {
+        "text": { "type": "array", "items": { "type": "string" } },
+        "layout_analysis": { "type": "array", "items": { "type": "string" } },
+        "image": { "type": "array", "items": { "type": "string" } },
+        "video": { "type": "array", "items": { "type": "string" } },
+        "tts": { "type": "array", "items": { "type": "string" } },
+        "stt": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "config_schema": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type", "default", "description"],
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "type": "string" },
+          "default": {},
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "timing_controls": {
+      "type": "object",
+      "required": ["exposed_to_user", "defaults", "input_fields"],
+      "properties": {
+        "exposed_to_user": { "type": "boolean" },
+        "defaults": {
+          "type": "object",
+          "properties": {
+            "total_duration_ms": { "type": "integer", "minimum": 0 },
+            "scene_duration_ms": { "type": "integer", "minimum": 0 },
+            "slide_duration_ms": { "type": "integer", "minimum": 0 },
+            "transition_ms": { "type": "integer", "minimum": 0 },
+            "hold_ms": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "input_fields": { "type": "array", "items": { "type": "string" } },
+        "clamping_rules": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "required": ["recommended_default", "tiktok_native", "configurable_fields"],
+      "properties": {
+        "recommended_default": { "type": "string" },
+        "tiktok_native": { "type": "boolean" },
+        "font_files": { "type": "array", "items": { "type": "string" } },
+        "fallback_fonts": { "type": "array", "items": { "type": "string" } },
+        "configurable_fields": { "type": "array", "items": { "type": "string" } },
+        "style_rules": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "description", "input_schema", "smoke_test_payload", "workflow"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "input_schema": { "type": "object" },
+          "smoke_test_payload": { "type": "object" },
+          "workflow": { "type": "string" }
+        }
+      }
+    },
+    "jobs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["workflow", "steps"],
+        "properties": {
+          "workflow": { "type": "string" },
+          "steps": { "type": "array", "items": { "type": "string" } },
+          "failure_modes": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "properties": {
+        "manifest_shape": { "type": "object" },
+        "files": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "remotion": {
+      "type": "object",
+      "properties": {
+        "needed": { "type": "boolean" },
+        "composition_id": { "type": "string" },
+        "props_shape": { "type": "object" },
+        "layout_notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "skill_md": {
+      "type": "object",
+      "properties": {
+        "must_include": { "type": "array", "items": { "type": "string" } },
+        "sample_requests": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "properties": {
+        "commands": { "type": "array", "items": { "type": "string" } },
+        "artifact_checks": { "type": "array", "items": { "type": "string" } },
+        "visual_checks": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}