Scenes and layers
How a scene video is built: scenes, transitions, backgrounds, layers, keyframes and captions, with units, limits and the verbs for editing one scene at a time.
A scene video is a declarative timeline. The spec is data, never code.
Units#
- Positions are percent of the frame.
- Time is in seconds.
- Text sizes are type-scale tokens, so they adapt to the frame.
A scene#
Scenes run in order. Each has:
- a duration (up to 60 seconds),
- a transition to the next: fade, slide, push, zoom, wipe or match-cut,
- a background: solid, gradient or grain,
- layers, a title and, optionally, a chapter marker.
Layers#
| Layer | What it does |
|---|---|
| Text | Type-scale tokens, safe areas, reveals by line, word or character |
| Shape | Rectangles, lines, underlines and more |
| Image | A picture or screenshot (storage:<id>) |
| Device frame | A phone, laptop or browser with a screen slideshow and camera moves |
| Group and mask | Layers that move and clip together |
Layers have keyframes with easings. A video can also have captions.
Limits#
A spec is at most 900 KB of JSON, with up to 300 scenes, 40 layers per scene, 12 keyframes per layer and 1,000 captions. A video can be 30 minutes long. Pictures are references (storage:<id>); a data URL counts against the 900 KB.
Editing one scene at a time#
Every scene has a stable id (sc-xxxxxx). You add, update, remove, move and duplicate scenes, or copy scenes from another video. Each action is one atomic edit that validates the whole spec and, when something is wrong, names the scene and field: "Scene 4 (id sc-ab12, "Intro") - spec.scenes[3]…". The video goes back to draft with a new revision.
The quality bar#
lint reads the video the way a viewer would. It warns about text-only scenes, too little shown (under 35 percent of the running time with a device, picture, cards or graphics), more than 32 words on a scene, too little time to read (3.5 words a second plus 0.7 s), text outside the safe area, scenes with no motion, contrast under WCAG (3:1 large, 4.5:1 other) and text under 15 px in a 720-high frame. A layer whose id starts with deco is decoration and counts for little.
Warnings never block a save.