@mevdragon/vidfarm-devcli 0.2.12 → 0.2.13

package/auto-create-hyperframe-templates/extractor-system-prompt.md

@@ -0,0 +1,128 @@
+# HyperFrames Production Graph Extractor Prompt
+
+You are a HyperFrames production analyst.
+
+Your job is to inspect one MP4, screenshot set, or PNG/JPG/WebP slideshow and extract the repeatable HyperFrames production process as structured JSON. Do not merely describe the media. Convert it into an editable composition graph that can become `composition.html`, `composition.json`, and a production Lambda site.
+
+Return only JSON matching `production-graph.schema.json`.
+
+## Inputs You May Receive
+
+- source notes
+- source video or slides
+- contact sheet
+- representative frames
+- ffprobe metadata
+- scene cut list
+- STT transcript with word timestamps
+- OCR text from frames
+- layout analysis with bounding boxes
+- existing `composition.html` or `composition.json`
+- desired output dimensions and fps
+
+## Extraction Rules
+
+- Treat all supplied media as one reusable HyperFrames format.
+- Separate source media, deterministic overlays, captions, audio, and generated assets.
+- Identify which visual surfaces are editable layers and which are source-media content.
+- Important readable text should default to deterministic HTML/caption layers, not baked generated media.
+- Extract exact or inferred timing for scenes, slides, captions, overlays, transitions, zooms, holds, and loop points.
+- Record source media slices with `media_start` when a layer uses a segment from a longer MP4.
+- Preserve blank gaps as intentional timeline ranges when no layer should be visible.
+- Do not depend on an always-on source video for publish correctness. Preview playback sources are allowed only as editor affordances.
+- Distinguish `mode: "both"`, `mode: "editor"`, and `mode: "publish"`.
+- Use percent geometry for layer placement: `x`, `y`, `width`, `height`.
+- Use seconds for `start`, `duration`, `media_start`, and `media_end`.
+- Track source audio separately from source video if audio should continue across scene cuts.
+- Keep one editable timeline track collision-free unless the track is explicitly marked as composited.
+- Identify caption safe areas and collisions with TikTok/Reels chrome.
+- Record Lambda memory estimate inputs: resolution, duration, active video streams, source resolution, layer count, DOM complexity, effects, audio mixing, and known risk flags.
+
+## Required Analysis Dimensions
+
+Extract:
+
+- format summary and source mode
+- output dimensions, fps, and total duration
+- source asset inventory
+- scene or slide timeline
+- layer decomposition
+- deterministic caption and text surfaces
+- HTML overlay surfaces
+- media replacement slots
+- audio plan
+- safe areas and subject bounds
+- caption positioning and wrapping rules
+- visual rules that must survive adaptation
+- editable controls
+- generated asset needs, if any
+- Lambda memory estimate
+- production Lambda site readiness
+- validation checklist
+
+## Layer Classification
+
+For every meaningful visual or audio element choose one kind:
+
+- `video`: timed video layer or scene slice
+- `image`: timed image/slide layer
+- `audio`: timed audio layer
+- `caption`: text intended as subtitle/creator caption
+- `html`: custom deterministic HTML overlay, UI card, comment, notification, or app shell
+- `shape`: non-text geometric layer
+- `effect`: deterministic transform/filter/mask/highlight
+
+For every layer choose one source of truth:
+
+- `source_media`: the original media asset is the visual/audio content
+- `deterministic_html`: HTML/CSS/text is the source of truth
+- `generated_asset`: AI/generated media is the source of truth
+- `user_asset`: caller-provided replacement asset is required
+- `computed_effect`: derived motion, mask, crop, zoom, or highlight
+
+## Caption Rules
+
+Strongly identify typography:
+
+- font family match
+- fallback font stack
+- font weight
+- case
+- color
+- outline, stroke, radial halo, shadow
+- background chip style
+- line wrapping
+- line height
+- alignment
+- safe area
+- phone-size legibility
+
+When captions have colored backgrounds, classify them as inline highlight chips unless the source clearly uses a panel. Chips must hug measured wrapped lines.
+
+When captions are white TikTok-native captions, distinguish radial black halo/outline from a web-style directional shadow.
+
+For multiline captions, require one shared font size and line height for the block. Do not recommend per-line rendered images.
+
+## Lambda Memory Estimate Rules
+
+Estimate memory from composition complexity, not vibes.
+
+Use these defaults:
+
+- `2048` MB for static/slideshow/simple image compositions with low DOM complexity.
+- `3072` MB for standard 720x1280 or 1080x1920 social video with one active video stream and deterministic overlays.
+- `4096` MB for 1080p video, multiple active videos, heavy captions, masks, filters, or long audio.
+- `6144` MB or higher only when high resolution, many simultaneous layers, or prior failures justify it.
+
+Return both a recommendation and a confidence. Include benchmark guidance only when the source sits near a threshold.
+
+## Output Bias
+
+Be concrete. A production graph should be implementable.
+
+Bad: "Add captions around the video."
+
+Good: "Render a 2-line white TikTok Sans Semibold caption block at x=8, y=42, width=84, height=14, fontSize=46, lineHeight=1.08, black radial halo, max 18 chars per line, timed 0.0-2.4s."
+
+Publish correctness bias: if a source video is split into scenes, every scene must be its own timed layer or publish proxy. Deleting scene 2 must delete scene 2 from the final render.
+

package/auto-create-hyperframe-templates/input-manifest.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Auto-Create HyperFrame Input Manifest",
+  "type": "object",
+  "required": [
+    "mode",
+    "input_path",
+    "output_path",
+    "slug_id",
+    "source_mode",
+    "render_defaults",
+    "lambda",
+    "publish"
+  ],
+  "properties": {
+    "mode": { "const": "autocreate-hyperframe-template" },
+    "harness_entry": { "type": "string" },
+    "input_path": { "type": "string" },
+    "output_path": { "type": "string" },
+    "slug_id": { "type": "string" },
+    "source_mode": { "enum": ["auto", "single_video", "scene_split_video", "slideshow", "mixed_media"] },
+    "source_notes_path": { "type": "string" },
+    "render_defaults": {
+      "type": "object",
+      "required": ["width", "height", "fps"],
+      "properties": {
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "fps": { "type": "number", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "lambda": {
+      "type": "object",
+      "required": ["stack_name", "region", "memory_strategy"],
+      "properties": {
+        "stack_name": { "type": "string" },
+        "region": { "type": "string" },
+        "memory_strategy": { "enum": ["estimate", "fixed"] },
+        "fixed_memory_mb": { "enum": [2048, 3072, 4096, 6144, 8192, 10240] }
+      },
+      "additionalProperties": false
+    },
+    "publish": {
+      "type": "object",
+      "required": ["prestage_site", "output_url_policy"],
+      "properties": {
+        "prestage_site": { "type": "boolean" },
+        "output_url_policy": { "enum": ["signed_https_final_output_only"] }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}
+

package/auto-create-hyperframe-templates/lambda-memory-estimator.md

@@ -0,0 +1,118 @@
+# HyperFrames Lambda Memory Estimator
+
+Use this rubric to estimate Lambda memory before benchmarking.
+
+The goal is not perfect prediction. The goal is a sane first render configuration that avoids the historical overpowered default while keeping publish reliable.
+
+## Recommended Buckets
+
+| Memory | Use For |
+| --- | --- |
+| `2048` MB | Static image, simple slideshow, low DOM, no video decode pressure, 720p target. |
+| `3072` MB | Default vertical social video: one active video stream, 720x1280 or 1080x1920, deterministic captions/HTML overlays. |
+| `4096` MB | 1080p video with heavy overlays, multiple active video streams, masks/filters, large shadows, long audio, or >30s timelines. |
+| `6144` MB | High-resolution outputs, many simultaneous media layers, complex CSS filters/masks, prior 3GB/4GB failure, or large generated assets. |
+| `8192` MB+ | Exceptional cases only. Use after measured failure or very high complexity. |
+| `10240` MB | Last resort, not a default. |
+
+## Scoring
+
+Start at `1536` MB.
+
+Add output pixel score:
+
+- `0` MB for <= 1.0 megapixel output
+- `512` MB for <= 2.1 megapixel output
+- `1024` MB for <= 4.0 megapixel output
+- `2048` MB for > 4.0 megapixel output
+
+Add media score:
+
+- `0` MB for no video layers
+- `768` MB for one active video stream
+- `512` MB for each additional simultaneous active video stream
+- `256` MB for each additional unique source video decoded across the timeline
+- `512` MB if source media is much larger than output resolution
+
+Add DOM/caption score:
+
+- `0` MB for <= 10 simple layers
+- `256` MB for 11-30 layers
+- `512` MB for > 30 layers
+- `256` MB for frequent timed captions
+- `512` MB for word-level caption highlighting or many HTML overlays
+
+Add effect score:
+
+- `256` MB for large text shadows, outlines, or chips on many layers
+- `512` MB for masks, blend modes, blur, filter chains, or large CSS transforms
+- `1024` MB for several effects active over video at once
+
+Add duration/audio score:
+
+- `0` MB for <= 30 seconds
+- `256` MB for 31-60 seconds
+- `512` MB for 61-180 seconds
+- `1024` MB for > 180 seconds
+- `256` MB for continuous audio mix
+- `512` MB for multiple audio streams or heavy audio processing
+
+Round up to the next bucket: `2048`, `3072`, `4096`, `6144`, `8192`, or `10240`.
+
+Clamp ordinary compositions to `2048`-`4096` unless risk flags justify more.
+
+## Fast Rules
+
+- If there is no video and the output is <= 1080x1920, start at `2048`.
+- If there is exactly one active video stream and ordinary captions, start at `3072`.
+- If there are two or more simultaneous videos, start at `4096`.
+- If output is 4K or the source is 4K and actively decoded, start at `6144`.
+- If 3GB succeeds with similar wall time to 4GB, keep 3GB.
+- If 2GB succeeds but wall time grows enough to erase savings, keep 3GB.
+
+## Output Shape
+
+```json
+{
+  "recommended_memory_mb": 3072,
+  "confidence": "medium",
+  "complexity_scores": {
+    "output_pixels": 921600,
+    "output_pixel_score_mb": 0,
+    "max_simultaneous_video_streams": 1,
+    "media_score_mb": 768,
+    "layer_count": 8,
+    "dom_caption_score_mb": 256,
+    "effect_score_mb": 0,
+    "duration_seconds": 12.7,
+    "duration_audio_score_mb": 256,
+    "raw_estimate_mb": 2816,
+    "rounded_bucket_mb": 3072
+  },
+  "risk_flags": [
+    "source_video_decode",
+    "continuous_audio"
+  ],
+  "rationale": "One active 720x1280 video stream with a small deterministic HTML overlay and continuous source audio fits the 3GB baseline.",
+  "benchmark_override": null
+}
+```
+
+## Cost Estimate
+
+Use this rough formula:
+
+```txt
+lambda_cost = memory_gb * billed_seconds_total * 0.0000166667
+step_functions_cost = state_transitions * 0.000025
+estimated_cost = lambda_cost + step_functions_cost
+```
+
+For planning, estimate billed seconds from similar templates:
+
+- static/slideshow: 20-60 billed seconds
+- 10-20s social video: 90-180 billed seconds at 3GB
+- 30-60s social video: 180-420 billed seconds at 3GB
+
+Record the estimate, but treat the first production render as the real calibration.
+

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

@@ -0,0 +1,314 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "HyperFrames Production Graph",
+  "type": "object",
+  "required": [
+    "format_summary",
+    "input_contract",
+    "visual_system",
+    "timeline",
+    "layer_decomposition",
+    "caption_system",
+    "lambda_memory_estimate",
+    "deployment",
+    "validation"
+  ],
+  "properties": {
+    "format_summary": {
+      "type": "object",
+      "required": ["slug_id", "title", "source_type", "summary", "width", "height", "duration_seconds"],
+      "properties": {
+        "slug_id": { "type": "string" },
+        "title": { "type": "string" },
+        "source_type": { "enum": ["single_video", "scene_split_video", "slideshow", "mixed_media"] },
+        "summary": { "type": "string" },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "fps": { "type": "number", "minimum": 1 },
+        "duration_seconds": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "input_contract": {
+      "type": "object",
+      "required": ["source_assets", "replaceable_slots"],
+      "properties": {
+        "source_assets": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/sourceAsset" }
+        },
+        "replaceable_slots": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "kind", "required", "description"],
+            "properties": {
+              "name": { "type": "string" },
+              "kind": { "enum": ["text", "image", "video", "audio", "html", "style", "duration", "cta"] },
+              "required": { "type": "boolean" },
+              "description": { "type": "string" },
+              "constraints": { "type": "array", "items": { "type": "string" } }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "viral_mechanics": {
+      "type": "object",
+      "properties": {
+        "hook_mechanic": { "type": "string" },
+        "retention_mechanic": { "type": "string" },
+        "payoff": { "type": "string" },
+        "must_preserve": { "type": "array", "items": { "type": "string" } },
+        "must_not_dilute": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "visual_system": {
+      "type": "object",
+      "required": ["safe_areas", "layout_rules", "style_rules"],
+      "properties": {
+        "safe_areas": { "$ref": "#/$defs/safeAreas" },
+        "layout_rules": { "type": "array", "items": { "type": "string" } },
+        "style_rules": { "type": "array", "items": { "type": "string" } },
+        "subject_regions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "role", "geometry"],
+            "properties": {
+              "id": { "type": "string" },
+              "role": { "type": "string" },
+              "geometry": { "$ref": "#/$defs/geometry" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "timeline": {
+      "type": "object",
+      "required": ["total_duration_seconds", "beats"],
+      "properties": {
+        "total_duration_seconds": { "type": "number", "minimum": 0 },
+        "beats": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "start", "duration", "role", "coverage"],
+            "properties": {
+              "id": { "type": "string" },
+              "start": { "type": "number", "minimum": 0 },
+              "duration": { "type": "number", "exclusiveMinimum": 0 },
+              "role": { "type": "string" },
+              "coverage": { "enum": ["media", "html_overlay", "caption_only", "blank_background", "audio_only"] },
+              "notes": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "layer_decomposition": {
+      "type": "object",
+      "required": ["composition_id", "background_color", "layers"],
+      "properties": {
+        "composition_id": { "type": "string" },
+        "background_color": { "type": "string" },
+        "layers": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/layer" }
+        },
+        "track_policy": {
+          "type": "object",
+          "properties": {
+            "collision_free_by_default": { "type": "boolean" },
+            "composited_tracks": { "type": "array", "items": { "type": "integer" } }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "caption_system": {
+      "type": "object",
+      "required": ["surfaces", "default_style"],
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "layer_ids", "placement", "safe_area_notes"],
+            "properties": {
+              "id": { "type": "string" },
+              "layer_ids": { "type": "array", "items": { "type": "string" } },
+              "placement": { "$ref": "#/$defs/geometry" },
+              "safe_area_notes": { "type": "string" },
+              "wrap_rules": { "type": "array", "items": { "type": "string" } }
+            },
+            "additionalProperties": false
+          }
+        },
+        "default_style": { "$ref": "#/$defs/textStyle" }
+      },
+      "additionalProperties": false
+    },
+    "lambda_memory_estimate": { "$ref": "#/$defs/lambdaMemoryEstimate" },
+    "deployment": {
+      "type": "object",
+      "required": ["stack_name", "region", "site_strategy", "output_url_policy"],
+      "properties": {
+        "stack_name": { "type": "string" },
+        "region": { "type": "string" },
+        "site_strategy": { "enum": ["pre_stage_site", "stage_on_publish", "manual"] },
+        "output_url_policy": { "enum": ["signed_https_final_output_only"] },
+        "render_defaults": {
+          "type": "object",
+          "properties": {
+            "width": { "type": "integer", "minimum": 1 },
+            "height": { "type": "integer", "minimum": 1 },
+            "fps": { "type": "number", "minimum": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "validation": {
+      "type": "object",
+      "required": ["checks"],
+      "properties": {
+        "checks": { "type": "array", "items": { "type": "string" } },
+        "known_risks": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "sourceAsset": {
+      "type": "object",
+      "required": ["id", "type", "path"],
+      "properties": {
+        "id": { "type": "string" },
+        "type": { "enum": ["video", "image", "audio", "font", "json", "html"] },
+        "path": { "type": "string" },
+        "width": { "type": "integer", "minimum": 0 },
+        "height": { "type": "integer", "minimum": 0 },
+        "duration_seconds": { "type": "number", "minimum": 0 },
+        "role": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "geometry": {
+      "type": "object",
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number", "exclusiveMinimum": 0 },
+        "height": { "type": "number", "exclusiveMinimum": 0 },
+        "unit": { "const": "percent" }
+      },
+      "additionalProperties": false
+    },
+    "safeAreas": {
+      "type": "object",
+      "properties": {
+        "top_percent": { "type": "number", "minimum": 0 },
+        "right_percent": { "type": "number", "minimum": 0 },
+        "bottom_percent": { "type": "number", "minimum": 0 },
+        "left_percent": { "type": "number", "minimum": 0 },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "textStyle": {
+      "type": "object",
+      "properties": {
+        "font_family": { "type": "string" },
+        "font_weight": { "type": "integer" },
+        "font_size_px": { "type": "number" },
+        "line_height": { "type": "number" },
+        "color": { "type": "string" },
+        "background": { "type": "string" },
+        "background_style": { "enum": ["plain", "outline", "radial_halo", "highlight_solid", "highlight_translucent", "panel"] },
+        "text_align": { "enum": ["left", "center", "right"] },
+        "max_lines": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "layer": {
+      "type": "object",
+      "required": ["id", "kind", "start", "duration", "track", "z", "mode", "source_of_truth", "geometry", "viral_alignment"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "enum": ["video", "image", "audio", "caption", "html", "shape", "effect"] },
+        "start": { "type": "number", "minimum": 0 },
+        "duration": { "type": "number", "exclusiveMinimum": 0 },
+        "track": { "type": "integer", "minimum": 0 },
+        "z": { "type": "integer" },
+        "mode": { "enum": ["both", "editor", "publish"] },
+        "source_of_truth": { "enum": ["source_media", "deterministic_html", "generated_asset", "user_asset", "computed_effect"] },
+        "geometry": { "$ref": "#/$defs/geometry" },
+        "media": {
+          "type": "object",
+          "properties": {
+            "src": { "type": "string" },
+            "asset_id": { "type": "string" },
+            "media_start": { "type": "number", "minimum": 0 },
+            "media_end": { "type": "number", "minimum": 0 },
+            "fit": { "enum": ["cover", "contain", "fill", "none"] },
+            "muted": { "type": "boolean" },
+            "volume": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "text": {
+          "type": "object",
+          "properties": {
+            "content": { "type": "string" },
+            "style": { "$ref": "#/$defs/textStyle" }
+          },
+          "additionalProperties": false
+        },
+        "html_contract": {
+          "type": "object",
+          "properties": {
+            "description": { "type": "string" },
+            "required_classes": { "type": "array", "items": { "type": "string" } },
+            "editable_fields": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        },
+        "viral_alignment": { "type": "string" },
+        "publish_notes": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "lambdaMemoryEstimate": {
+      "type": "object",
+      "required": ["recommended_memory_mb", "confidence", "complexity_scores", "rationale", "risk_flags"],
+      "properties": {
+        "recommended_memory_mb": { "enum": [2048, 3072, 4096, 6144, 8192, 10240] },
+        "confidence": { "enum": ["low", "medium", "high"] },
+        "complexity_scores": { "type": "object", "additionalProperties": { "type": ["number", "integer", "string", "boolean"] } },
+        "rationale": { "type": "string" },
+        "risk_flags": { "type": "array", "items": { "type": "string" } },
+        "benchmark_override": {
+          "type": ["object", "null"],
+          "properties": {
+            "memory_mb": { "enum": [2048, 3072, 4096, 6144, 8192, 10240] },
+            "reason": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}