# 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.

Source: https://video.geenius.io/docs/scenes-and-layers/

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.