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
containerWidthset - 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>
{
"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"
}
}