Authoring scenes in YAML
Each scene is a plain text file in YAML format. This part is the reference for writing those files by hand.
The settings of each node type are in Node types. Surfaces and fit are in Surfaces & fit. Colours and fonts are in Brand kit & tokens.
Three rules to remember
These three rules prevent most mistakes.
- Only a
transformplaces things. Atext,imageorshapehas noxoryof its own. Put it inside atransformand set thepositionthere. Aposition:anywhere else stays in the file but does nothing. - Keyframes use phase (0 to 1), not seconds. Phase is the position inside one cycle of a clock (see Time and motion). Because of this, a loop never jumps. If you change a clock's length, the whole animation follows. So if you edit
loop:by hand, every key on a clock that follows the loop moves. The app's duration field keeps the key times instead (Set the scene's length). Times and lengths use seconds instead. Examples areloop, a clock'speriod, a layer'sspananddelay, themarkersand a video'soffset. - Put hex colours in quotes. Write
fill: "#FFB81C". Without quotes, YAML reads the#as the start of a comment. The colour is then empty, and Starlight shows an error.
Where the files are
The folder layout is in What is in a project. For YAML you need only these facts:
- The project settings, the surfaces and the brand kit are in
project.yaml. - Each scene is one file in
scenes/, ending in.yamlor.yml. The file name without the ending is the scene's name. You use this name indefaultScene, for example. - A scene name can use letters, digits, dots, dashes and underscores. Keep the
scene:key inside the file the same as the file name. When you rename or duplicate a scene in the app, Starlight changes both. - Images, videos and sounds go in
assets/. Subfolders are fine. Brand font files go infonts/. - Asset paths start at the project folder:
assets/logo.svg,fonts/Knockout-HTF.otf. A file in a linked media folder ismedia:<root>/<path>(see Use linked media).
project.yaml
This file names every surface once and holds the brand kit. Each entry under surfaces: is one surface.
schemaVersion: 1
project: bolts-demo # the name key is `project:`
defaultScene: 01-game-open # opened when no last-open scene is remembered
surfaces: # every surface in the building, named once
jumbotron: { size: 1920x1080 }
ribbon-main: { size: 10080x84, fit: tile-x }
vomitory: { size: 384x640, fit: cover }
brand:
theme:
team.gold: "#FFB81C" # dotted OR nested keys, both work
team.navy: "#0B162A"
ink.white: "#F4F7FB"
fonts:
knockout-heavy: fonts/Knockout-HTF.otf
assets: assets
- Each surface needs a
size, in pixels (WxH). A surface without a size is an error. - A surface's
fitis the default for every scene (see Surfaces & fit). - Only the surfaces named here show on the canvas and go into exports. A scene cannot add a surface.
- To add a surface, add a line here with its name and size. Save the file, then choose File › Reload Project from Disk.
- Colour tokens and fonts: see Brand kit & tokens.
All the keys:
project: | Required. The project's name. |
schemaVersion: | The format version of this file. It is 1. |
surfaces: | Every surface: its size and an optional fit |
brand: | The brand kit: theme: (colour tokens) and fonts: (font files) |
defaultScene: | The scene that opens when the app does not remember a last open scene. Write the scene's file name without the ending. If no scene has that name, the first scene by file name opens. |
id: | A fixed project id. It stays the same when you rename the project. Starlight never writes it for you. |
export: | Delivery defaults: naming, formats, fps, aliases, quality, dither and motionBlur (see Project defaults) |
room: | The Glimpse venue: venueUrl, feedWidth (512, 1024 or 2048) and feedFps (15, 30 or scene). See Feed size. |
media: | Linked media folders: a short root name, then a folder (see Use linked media) |
shared: | true forces shared-project mode, false turns it off (see Share a project) |
assets: | The app writes assets: assets. Starlight always uses the assets/ folder, so another value has no effect. |
- An
export:orroom:value that Starlight cannot use stays in the file but is ignored. There is no error, so check the spelling.
Scene file
A scene file sets the loop and the design size (the size you design comps at). It also says what each surface shows.
scene: 01-game-open # name key is `scene:`
loop: 4s # everything loops within this (default 4s)
fps: 30 # export / stepping rate (default 30, max 240)
design: 1920x1080 # the size you design comps at (the default)
theme: # scene-level token aliases
primary: $team.gold
ink: $ink.white
clocks: # named clocks that layers can share
heartbeat: { period: 2s, mode: loop }
half: { period: scene/2 } # derived: scene loop ÷ 2
cues: # named moments (phases) on the scene loop
hit: 0.25
comps: # named groups of layers, placed on surfaces
main:
- text: "GAME DAY" # the first node draws at the back
band:
- shape: rect # a comp made at the ribbon's height
size: 1920x84
fill: $primary
surfaces: # what each surface shows
jumbotron: { use: main }
ribbon-main: { use: band, fit: tile-x, design: 1920x84 }
| Key | Default | Meaning |
|---|---|---|
scene | required | The scene's name. Keep it the same as the file name. |
schemaVersion | 3 | The format version of the file (see Edit a scene by hand) |
loop | 4s | The scene's length. Everything repeats within it. It must be more than 0. |
fps | 30 | Frames per second, for exports and for frame steps. More than 0, at most 240. |
design | 1920x1080 | The design size. A surface can have its own (see Output size and design size). |
theme | — | The scene's own colour tokens (see Use a token) |
clocks | — | Named clocks that layers can share (see Clocks) |
cues | — | Named phases (0 to 1) on the scene loop (see Cues) |
comps | — | Named groups of layers. Each comp is a list of nodes. |
surfaces | — | What each surface shows (see Feed a surface) |
- A comp is a named group of layers that you can place on surfaces.
- Each entry under
surfaces:is a surface. It shows itsuse:comp. Layers underchildren: [ … ]draw on top of it (see Feed a surface). - Inside a comp, the file order is the drawing order. The first layer is at the back.
- In the app, you set the loop and the fps on the scene clock. This is the large dial in the node graph (see Set the scene's length and fps).
The app also writes some keys for you. They are never drawn on a surface:
graphLayout,graphColors,graphNotes: where you moved, coloured and noted things in the node graph (see Colour and note nodes).markers: the timeline markers (see Add timeline markers).stages: 3D sketches of shots (see Stages).
Edit a scene by hand
Change a scene file in a text editor, then load it into the app.
- In the app, save your work with ⌘S / Ctrl+S.
- Open the scene file in any text editor. Make your change and save the file.
- In the app, choose File › Reload Project from Disk (⌘R / Ctrl+R).
- A normal project does not notice a change on disk by itself. Reload after each edit.
- A shared project watches its folder, so it usually picks up the change by itself (see When another artist saves).
- If the app has unsaved changes, it asks you first. If you go on, it keeps your unsaved edits as a recovery draft. You can get them back after the reload (see Get unsaved edits back).
- If the file has a mistake, the surfaces keep the last good version. The error shows in red at the bottom left of the canvas. It starts with
sceneand the scene's name, for examplescene 03-touchdown:(see Read an error message). The line goes away when the scene loads without a mistake, or when you save the scene. - When the app saves a scene, it writes the whole file again. Your YAML comments, line breaks and spacing are lost (see Saving and versions). Keep notes in sticky notes on the node graph instead.
- The app keeps most unknown keys and ignores them. So a spelling mistake in a key often does nothing, with no error. If a change has no effect, check the spelling.
The version number. schemaVersion tells Starlight which format the file uses.
- A scene with no
schemaVersionis read as version 3. This Starlight reads versions up to 11. Version 11 is for a scene where a video layer plays a version of its clip (version:). - A higher number is refused with an error:
this scene is schemaVersion 12, written by a newer Starlight. Update Starlight to open it. - When the app saves, it raises the number if the scene needs it. It never lowers it.
- This Starlight reads your hand edits, even with the old number. Still, raise the number yourself when you edit by hand.
- Write
4when you animate a gradient. Write5when a video has anoffset:. Write11when a video has aversion:. - Then an older Starlight refuses the file. It does not show the scene wrongly.
Read an error message
An error message names the file, the key and what is wrong. Use it to find the line to fix.
scenes/03-touchdown.yaml: surfaces.ribbon-main.size — expected WxH
- First comes the file. Then the path to the key, with a dot between each step. After the dash comes what Starlight expected.
- A number in the path is the place of an item in a list. Counting starts at 0.
- Example: in
comps.main.0.transform.1.fill,0is the first node of compmain.1is the second child inside its transform.fillis the key. - If there are several mistakes, the line on the canvas shows the first one and how many more, for example (+2 more). The log has the full list.
- A YAML mistake, such as a wrong indent or a missing colon, names the line and the column instead.
- When Starlight starts, an error in
project.yamlshows in the middle of the canvas, aftererror —. No surfaces show then. A broken scene does not stop the start: Starlight opens another scene and names the broken one at the bottom left (Where a mistake shows).
Common errors and what they mean:
| Message | What is wrong |
|---|---|
expected a node keyword (text, image, …) | The node has no keyword, or its keyword is spelt wrong. The keywords are in All node keywords. |
ambiguous node — multiple keywords present | One map has two keywords, for example text and image. Often a missing - joined two nodes into one. |
expected a colour … (got nothing — quote a hex colour …) | A hex colour without quotes. Write "#ffffff". |
expected a colour … (got "white") | A colour name. Use a hex value or a $token. |
unknown comp "x" — valid comps: … | A use: names a comp that does not exist. The message lists the comps that do. |
unresolved token $x | The token is not defined (see How a token finds its colour). |
expected WxH | A size not written like 1920x1080. Both sides must be more than 0. |
expected a duration like 4s or 250ms | A time written another way, for example 4 sec |
unknown named clock "x" — valid clocks: … | A clock: { use: … } names a clock that does not exist (see Clocks). |
expected ONE node — wrap several in a group | A matte's content or matte is a list. Put the nodes in a group (see matte). |
| A message about a number that is too big or too small | A value is out of range, for example opacity: 1.5 or fps: 300. |
Value formats
These are the ways to write single values.
| Size | 1920x1080 (or 1920×1080), or { width, height }. Use whole numbers in the 1920x1080 form. Both sides must be more than 0. |
| Duration | 4s, 1.5s, 250ms, or a plain number (milliseconds). A few keys take a minus sign, for example a video's offset. |
| Speed | -120px/s, or a plain number (pixels per second) |
| Point | [x, y], { x, y }, or one number for both, in pixels |
| Angle | Degrees. A positive angle turns clockwise. |
| Fraction | A number from 0 to 1: phase, opacity, a gradient stop's offset |
| On or off | true or false |
| Colour | "#rgb", "#rgba", "#rrggbb", "#rrggbbaa", or a $token. Always put hex colours in quotes: a # without quotes starts a YAML comment. |
| Token | A name that starts with $, for example $team.gold |
- When the app saves, it writes each value in one standard form. For example,
4000msbecomes4s, andscale: { x: 2, y: 2 }becomesscale: 2.