Basic Concepts

1. Top-level model

The current protocol is:

{
  "meta": {},
  "assets": {},
  "tracks": []
}

Rules:

• meta describes the output canvas
• assets is an optional reference pool
• tracks[].clips contains the actual timeline content

2. Duration model

There is no required top-level video.duration in v2.

Behavior:

• Total duration is derived from top-level clips
• The project end time is the maximum actual clip end time
• video and audio can be shortened by source trimming

3. Tracks and clips

Each track is just a clip container:

{
  "id": "main",
  "clips": [
    {
      "type": "text",
      "start": 0,
      "duration": 3
    }
  ]
}

Each clip defines:

• what it is
• when it starts
• how long it lasts
• where it appears
• how it looks

4. Coordinate model

Percentage coordinates are center-based, not DOM-style top-left based.

Examples:

• x: "50%" means horizontal center
• y: "50%" means vertical center
• x: "0%" means far left
• y: "100%" means bottom

5. Asset references

When you want reusable media, declare it in assets and use $ref:

{
  "assets": {
    "images": [
      {
        "id": "cover",
        "src": "https://example.com/cover.jpg"
      }
    ]
  }
}

Then reference it:

{
  "type": "image",
  "start": 0,
  "duration": 5,
  "src": { "$ref": "cover" }
}

6. What to read next

• Want per-element details: read Element Reference Index
• Want a complete walkthrough: read Create Product Showcase
• Want animation details: read Use Animations