@mevdragon/vidfarm-devcli 0.2.13 → 0.3.0

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

@@ -1,56 +0,0 @@
-{
-  "$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

@@ -1,118 +0,0 @@
-# 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

@@ -1,314 +0,0 @@
-{
-  "$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
-    }
-  }
-}

package/auto-create-hyperframe-templates/runbook.md

@@ -1,198 +0,0 @@
-# Auto-Create HyperFrame Template Runbook
-
-Use this runbook when a simple MP4 or slideshow should become an editable HyperFrames composition and production Lambda site.
-
-## 1. Create A Run Folder
-
-```bash
-RUN_ID="<format-slug>-$(date -u +%Y%m%dT%H%M%SZ)"
-mkdir -p "auto-create-hyperframe-templates/runs/${RUN_ID}"/{source,frames,audio,transcripts,ocr,motion,extraction,plan,output}
-```
-
-Copy source media and notes into `source/`.
-
-If running through automation, create `manifest.json` matching `input-manifest.schema.json` before copying media:
-
-```json
-{
-  "mode": "autocreate-hyperframe-template",
-  "input_path": "drafts/example/preview/source.mp4",
-  "output_path": "drafts/example",
-  "slug_id": "example",
-  "source_mode": "auto",
-  "render_defaults": {
-    "width": 720,
-    "height": 1280,
-    "fps": 30
-  },
-  "lambda": {
-    "stack_name": "hyperframes-vidfarm-prod",
-    "region": "us-east-1",
-    "memory_strategy": "estimate"
-  },
-  "publish": {
-    "prestage_site": false,
-    "output_url_policy": "signed_https_final_output_only"
-  }
-}
-```
-
-## 2. Extract Media Artifacts
-
-For MP4:
-
-```bash
-ffprobe -v error -show_entries format=duration:stream=codec_type,width,height,avg_frame_rate -of json source/source.mp4 \
-  > "auto-create-hyperframe-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-hyperframe-templates/runs/${RUN_ID}/frames/contact-sheet.jpg"
-
-ffmpeg -y -i source/source.mp4 \
-  -vn -ac 1 -ar 16000 "auto-create-hyperframe-templates/runs/${RUN_ID}/audio/source.wav"
-```
-
-For slideshows, probe each image and create a contact sheet:
-
-```bash
-ffprobe -v error -show_entries stream=width,height -of json source/slide-01.png \
-  > "auto-create-hyperframe-templates/runs/${RUN_ID}/source/slide-01.ffprobe.json"
-```
-
-Add scene detection, OCR, STT, and layout/subject-region detection with whichever local or provider tool is available. The important part is to write concrete timing, text, and bounding boxes into the run folder before planning.
-
-## 3. Decide Source Mode
-
-Classify the input:
-
-- `single_video`: one MP4 drives the full timeline
-- `scene_split_video`: one MP4 should be split into editable timed scene clips
-- `slideshow`: images become timed slides
-- `mixed_media`: video, images, audio, and HTML overlays need explicit composition
-
-Record whether source media contains baked text that should be extracted as deterministic captions/HTML overlays.
-
-## 4. Generate Production Graph
-
-Send `extractor-system-prompt.md`, source notes, artifacts, contact sheet, transcript, OCR, and scene cuts to a multimodal model.
-
-Write:
-
-```txt
-auto-create-hyperframe-templates/runs/<run_id>/extraction/production_graph.json
-```
-
-Validate against:
-
-```txt
-auto-create-hyperframe-templates/production-graph.schema.json
-```
-
-## 5. Generate HyperFrame Template Plan
-
-Send `template-planner-prompt.md` plus `production_graph.json`.
-
-Write:
-
-```txt
-auto-create-hyperframe-templates/runs/<run_id>/plan/template_plan.json
-```
-
-Validate against:
-
-```txt
-auto-create-hyperframe-templates/template-plan.schema.json
-```
-
-## 6. Write Composition Artifacts
-
-Create or update the target source folder:
-
-```txt
-drafts/<format_slug>/
-  composition.html
-  composition.json
-  lambda-site.json
-```
-
-For simple MP4/slideshow inputs, the local bridge can do this step directly:
-
-```bash
-node auto-create-hyperframe-templates/scripts/create-hyperframe-template.mjs drafts/<format_slug>/preview/source.mp4
-node auto-create-hyperframe-templates/scripts/create-hyperframe-template.mjs drafts/<format_slug>/preview --stage-site
-```
-
-Implementation order:
-
-1. write `composition.json` from `template_plan.layers`
-2. write `composition.html` from the same layer manifest
-3. include root `data-composition-id`, `data-width`, `data-height`, `data-duration`, and `data-source-folder`
-4. write `lambda-site.json` with stack, region, memory, render defaults, and site upload status
-5. run local editor smoke test
-
-## 7. HyperFrames Layer Rules
-
-Use these data attributes in `composition.html`:
-
-- `data-hf-id`
-- `data-layer-kind`
-- `data-layer-mode`
-- `data-start`
-- `data-duration`
-- `data-track-index`
-- `data-label`
-- `data-media-start` for timed media slices
-- `data-playback-start` for editor/publish compatibility
-- `data-src` when using a timeline proxy
-
-For video scene clips, prefer timed real `<video>` elements or a timeline proxy that publish normalization rewrites into a real `<video>`. A preview-only `data-vf-playback-source` may help editor scrubbing, but it must not be the publish source of truth.
-
-## 8. Estimate Lambda Memory
-
-Use `lambda-memory-estimator.md`.
-
-Recommended baseline:
-
-- `2048` MB: static images, simple slideshows, minimal HTML, no video decode pressure
-- `3072` MB: default for vertical social video with one decoded video stream and deterministic overlays
-- `4096` MB: 1080p video, multiple streams, heavy captions, large shadows, masks, or long audio
-- `6144+` MB: high-resolution, many active layers, complex filters, or measured failures
-
-Write both the recommendation and the reasoning into `composition.json` and `lambda-site.json`.
-
-## 9. Stage Production Lambda Site
-
-After the project folder is valid, pre-stage it for repeat publishing:
-
-```bash
-hyperframes lambda sites create drafts/<format_slug> \
-  --stack-name hyperframes-vidfarm-prod \
-  --region us-east-1
-```
-
-If using the SDK or demo API instead of the CLI, write the returned content-addressed site id into `lambda-site.json`.
-
-The frontend should show the final signed output URL after publish. Do not expose S3 Console or Step Functions Console links as user-facing CTAs.
-
-## 10. Validate Publish
-
-Run one local render and one Lambda publish:
-
-```bash
-hyperframes lambda render drafts/<format_slug> \
-  --stack-name hyperframes-vidfarm-prod \
-  --region us-east-1 \
-  --site-id <site_id> \
-  --width 720 \
-  --height 1280 \
-  --wait
-```
-
-Check:
-
-- final output reflects deleted/hidden scene layers
-- caption timing matches the editor timeline
-- blank gaps remain blank when no media layer covers them
-- audio does not silently disappear after scene splitting
-- output URL is accessible without AWS Console login when surfaced in the product