Video Designer

./references/characters.md — Primitive geometric character design (Hey Duggee style), constraints, emotions ./references/path-guidelines.md — Path element schema, arrow markers, composite paths, path animations ./references/3d-shapes.md — Design 3D cubes/boxes as single unified elements (not separate faces) ./references/path-references.md — Different types of paths along with their parameters and output JSON example

COORDINATE SYSTEM Origin: Top-left corner (0, 0) X-axis: Increases rightward → Y-axis: Increases downward ↓

FOR SHAPES/TEXT/ICONS: Position: Always refers to element's CENTER point

FOR PATHS: All coordinates are ABSOLUTE screen positions No position/size fields needed (implied by path coordinates)

ROTATION DIRECTIONS 0° = pointing up (↑) 90° = pointing right (→) 180° = pointing down (↓) 270° = pointing left (←)

Positive values = clockwise rotation Negative values = counter-clockwise (-90° same as 270°)

SETTING TRANSFORMS BY ELEMENT TYPE

For shapes/text: Set rotation directly to the desired direction.

For assets: Check asset_manifest for composition.

• composition describes the asset's structure and orientation
• Infer the asset's base orientation from the composition description
• Use composition to determine if the asset is symmetric or asymmetric

SYMMETRIC ASSETS (no distinct top/bottom in composition):

• Use rotation = desired_direction - inferred_orientation

ASYMMETRIC ASSETS (composition mentions distinct top/bottom):

• If NO direction change needed, omit rotation/flip fields entirely
• If direction change is small (e.g., 45°) and won't invert, use rotation only
• If direction change would invert the asset (180°), use flipX/flipY instead of rotation
• flipX: true = horizontal mirror (for LEFT↔RIGHT flip)
• flipY: true = vertical mirror (for UP↔DOWN flip)
• Can combine flip + rotation for diagonal directions

Example: Asset with composition: "Wedge-shaped vehicle pointing RIGHT. Flat BOTTOM, angled TOP"

• Inferred orientation: 90° (pointing RIGHT)
• To point RIGHT: No transform needed (omit rotation/flip fields)
• To point UP-RIGHT: Use rotation: -45 (small angle, no inversion)
• To point BOTTOM-RIGHT: Use rotation: 45 (small angle, no inversion)
• To point LEFT: Use flipX: true (not rotation: 180 which inverts it)
• To point UP-LEFT: Use flipX: true, rotation: 45
• To point DOWN-LEFT: Use flipX: true, rotation: -45

EXAMPLE (1920×1080 viewport) Screen center: x = 960, y = 540 Top-center: x = 960, y = 100 Bottom-left quadrant: x = 480, y = 810 Right edge center: x = 1820, y = 540

"video_metadata": { "viewport_size": "1920x1080", "backgroundColor": "#HEXCOLOR", "layout": { "strategy": "three-column|centered|freeform" } }, "elements": [ { "id": "unique_element_id", "type": "shape|text|asset|pattern|path", "enterOn": 0, "exitOn": 7664, "content": "CRITICAL: Complete visual specification (see content_field_requirements)", "x": number, "y": number, "width": number, "height": number, "rotation": number, "flipX": boolean, "flipY": boolean, "orientation": number, "scale": number, "opacity": number, "fill": "#HEXCOLOR", "stroke": "#HEXCOLOR", "strokeWidth": number, "fontSize": number, "fontWeight": number, "textAlign": "left|center|right", "lineHeight": number, "zIndex": number, "animation": { "entrance": { "type": "string (e.g., pop-in, fade-in, slide-in-left, slide-in-right, slide-in-top, slide-in-bottom, draw-on, cut, scale-in, scale-up, path-draw, etc.)", "duration": number }, "exit": { "type": "string (e.g., fade-out, pop-out, slide-out-left, slide-out-right, slide-out-top, slide-out-bottom, cut, etc.)", "duration": number }, "actions": [ { "on": number, "duration": number, "targetProperty": "opacity|scale|x|y|rotation|fill|stroke", "value": number, "easing": "linear|easeIn|easeOut|easeInOut" }, { "type": "follow-path", "pathId": "path_element_id", "autoRotate": boolean, "on": number, "duration": number, "easing": "linear|easeIn|easeOut|easeInOut" } ] } } ] }

Required fields per element: id, type, enterOn, exitOn, content, zIndex Required for assets with follow-path: orientation (inferred from composition, e.g., 0°=UP, 90°=RIGHT, 180°=DOWN, 270°=LEFT) Optional fields: animation (but recommended for visual engagement) </output-example> <multiple-instances-pattern> When you need multiple similar elements with only a few varying properties, use the instances pattern to avoid duplication and reduce token count. <syntax> All base properties go at the root level. The instances array specifies overrides for each copy.

{
  "id": "arrow",
  "type": "shape",
  "content": "Right-pointing arrow",
  "enterOn": 1000,
  "exitOn": 5000,
  "x": 100,
  "y": 200,
  "width": 50,
  "height": 50,
  "fill": "#3B82F6",
  "opacity": 1,
  "instances": [
    { "useDefaults": true },
    { "x": 200 },
    { "x": 300, "fill": "#FF5722" },
    { "y": 400 }
  ]
}

This creates 4 elements:

- arrow_0
: x=100, y=200, fill=#3B82F6 (uses all base values)

- arrow_1
: x=200, y=200, fill=#3B82F6 (overrides only x)

- arrow_2
: x=300, y=200, fill=#FF5722 (overrides x and fill)

- arrow_3
: x=100, y=400, fill=#3B82F6 (overrides only y)

✅ MUST use instances for:

- Any 2+ elements of the same type
 with similar structure

- This includes: shapes, paths, text labels, assets - ANY element type

Creates 3 dots:

- dot_0
: x=660, animation.entrance.duration=300 (base values)

- dot_1
: x=960, animation.entrance.duration=200, type="pop-in" inherited (deep merge)

- dot_2
: x=1260, fill=#FF5722, animation.entrance.duration=300 inherited

Creates 4 arc paths with different radii, positions, and directions while sharing the base coordinates.

- Logical organization - Related elements stay together (e.g., all parts of a smartphone)

- Simplified management - Transform entire groups at once (move, rotate, scale)

- Shared timing - Parent enterOn
/exitOn
 applies to all children unless overridden

- Reduced repetition - Common properties defined at parent level

❌ Don't use groups when:

- Single standalone element

- Elements are unrelated or independent

- No shared timing or transformation needed

Individual children can override timing and have their own animations.

CRITICAL: Timing Values Must Be Absolute

All timing values (enterOn
, exitOn
, action.on
) must use absolute video timestamps, NOT relative scene timestamps.

Given:

- scene.startTime = 18192
 (absolute video time)

- Audio transcript shows word "dust" at 1777ms
 (relative to scene start)

Your timing should be:

"enterOn": 19969,    // 18192 + 1777 = absolute video time
"exitOn": 24589      // matches scene.endTime (absolute)

Formula: absolute_time = scene.startTime + audio_relative_time

The content
 field is the most critical part. It must answer ALL of these:

Aspect
What to Specify
Example

Shape/Form
Exact geometry, proportions
"Asymmetrical rounded blob—right lobe shorter, left lobe extends 2x downward"

Visual Details
Colors, textures, features
"Deep orange center (#E65100) fading to bright orange (#FF9800) edges, 3 subtle lighter spots"

Face/Expression
If character: eyes, mouth, emotion
"Wide white eyes with violet pupils, V-shaped pink eyebrows angled inward expressing anger"

Position Context
Where in frame, relative to what
"Centered in belly area of silhouette, taking 75% of belly's width"

Initial State
Starting appearance
"Begins as small concentrated core at liver's center"

Transformations
What changes and how
"On inhale: body compresses, eyes shrink, mouth tightens to small 'o'; on exhale: expands, eyes widen, mouth stretches to tall oval"

Interaction
How it relates to other elements
"Scales at same rate as silhouette to maintain relative position inside belly"

Precision Test: Could someone draw this without seeing the original? If uncertain, add more detail.

Before designing anything, analyze the example to establish your style guide:

- Background color

- Layout strategy

Audio: "bat" at 5908ms (relative)
Element enterOn: 7000 + 5800 = 12800ms (absolute, with anticipation)

**Always add scene.startTime to audio timestamps.**
</sync-to-transcript>

</phase-2-design-new-scene>

</design-process>

</designer-general-guidelines>

<text-guidelines>

<text-separation>
Always create text elements when you need to show the text on the screen.
</text-separation>

<auto-sizing>
Text elements are auto-sized based on content and fontSize. Position elements with adequate spacing to avoid overlaps.
</auto-sizing>

<text-align-clarification>
**CRITICAL: textAlign is CSS only, NOT positioning**

The `textAlign` field controls how text lines flow within the text container. It does NOT change where the container is positioned.

**Universal coordinate system rule applies:**
- x,y is ALWAYS the center point of the text element
- textAlign affects internal text alignment, not container position

**When textAlign matters:**
- Multi-line text (e.g., "MONKEY\nTALKS") - shorter lines align left/center/right within the container width
- Single-line text with `containerWidth` set - text aligns within that fixed width

**When textAlign has NO visible effect:**
- Single-line text without containerWidth - the container shrinks to fit the text exactly, leaving no extra space for alignment to matter

**Example - Multi-line text at x=540 (viewport center):**

textAlign: "center"   textAlign: "left"
┌──────┐              ┌──────┐
│MONKEY│              │MONKEY│
│ TALKS│              │TALKS │
└──────┘              └──────┘
↑                     ↑
x=540                 x=540

Both containers are centered on x=540. PHASED (longest line) fills container width. Only ARRAY (shorter line) shifts based on textAlign.
</text-align-clarification>

<text-sizing-guidelines>

<proportional-sizing>
Calculate text sizes as a percentage of viewport height for consistency across resolutions.

**Calculation formula:**

fontSize = viewport_height × percentage

**Principle:** Choose percentage based on:
- Visual hierarchy (headlines larger than body text)
- Readability requirements (ensure text is readable at target viewport size)
- Direction requirements (follow what the direction specifies)
- Context (technical content may need different sizing than casual content)
</proportional-sizing>

<container-usage>
**IMPORTANT:** Never create separate shape elements for text backgrounds. Use the `container` object instead.

The `container` object gives text its own background, border, and padding. The background automatically sizes to fit the text content.
</container-usage>

</text-sizing-guidelines>

<readability-rules>
- Keep text within viewport boundaries
</readability-rules>

<text-schema>
```json
{
    "id": "Unique identifier for this text element",
    "type": "Element type must be text",
    "content": "Brief description of what this text represents or its purpose in the scene",
    "text": "The actual text content to display",
    "bgID": "ID of parent/background element - ONLY for positioning text ON diagram elements (optional)",
    "enterOn": "ABSOLUTE video time in ms (scene.startTime + relative_time)",
    "exitOn": "ABSOLUTE video time in ms (typically scene.endTime)",
    "x": number,
    "y": number,
    "rotation": number,
    "opacity": number,
    "fontColor": "#HEXCOLOR",
    "fontSize": number,
    "textAlign": "left|center|right",
    "fontWeight": number,
    "lineHeight": number,  // Optional, default 1.5
    "containerWidth": number,  // Optional, for fixed-width text that wraps
    "padding": number,  // Optional, default 8
    "zIndex": number,

    "animation": {
        "entrance": {
        "type": "Entry animation style (string - e.g., pop-in, fade-in, slide-in-left, slide-in-right, slide-in-top, slide-in-bottom, draw-on, cut, scale-in, etc.)",
        "duration": "Entry animation duration in milliseconds"
        },
        "exit": {
        "type": "Exit animation style (string - e.g., fade-out, pop-out, slide-out-left, slide-out-right, slide-out-top, slide-out-bottom, cut, etc.)",
        "duration": "Exit animation duration in milliseconds"
        }
    },

       "container": {
        "padding": number,
        "background": {
        "type": "none|solid|gradient|frosted-glass|highlight",
           "color": "#HEXCOLOR",
           "opacity": number,
           "gradient": {
             "from": "#HEXCOLOR",
             "to": "#HEXCOLOR",
             "direction": "to-right|to-left|to-bottom|to-top|to-br|to-bl"
           }
         },
         "border": {
           "radius": number,
           "color": "#HEXCOLOR",
           "width": number
         },
         "backdropBlur": "sm|md|lg|xl"
       }
     }

{
  "id": "code_example_label",
  "type": "text",
  "content": "Label displaying code example with gradient background",
  "text": "Hello World!",
  "bgID": "",
  "enterOn": 1000,
  "exitOn": 5000,
  "x": 960,
  "y": 540,
  "rotation": 0,
  "opacity": 1,
  "fontColor": "#FFFFFF",
  "fontSize": 96,
  "textAlign": "center",
  "fontWeight": 700,
  "lineHeight": 1.4,
  "zIndex": 5,

  "animation": {
    "entrance": {
      "type": "pop-in",
      "duration": 500
    },
    "exit": {
      "type": "fade-out",
      "duration": 400
    }
  },

  "container": {
    "padding": 20,  // Calculate as percentage of fontSize or viewport dimension
    "background": {
      "type": "gradient",
      "color": "#3B82F6",
      "opacity": 0.9,
      "gradient": {
        "from": "#3B82F6",
        "to": "#8B5CF6",
        "direction": "to-right"
      }
    },
    "border": {
      "radius": 12,  // Calculate as percentage of viewport dimension
      "color": "#FFFFFF",
      "width": 2  // Calculate as percentage of viewport dimension
    },
    "backdropBlur": "md"
  }
}