Skip to Content
Starlight

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 transform places things. A text, image or shape has no x or y of its own. Put it inside a transform and set the position there. A position: 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 are loop, a clock's period, a layer's span and delay, the markers and a video's offset.
  • 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 .yaml or .yml. The file name without the ending is the scene's name. You use this name in defaultScene, 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 in fonts/.
  • Asset paths start at the project folder: assets/logo.svg, fonts/Knockout-HTF.otf. A file in a linked media folder is media:<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 fit is 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: or room: 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 }
KeyDefaultMeaning
scenerequiredThe scene's name. Keep it the same as the file name.
schemaVersion3The format version of the file (see Edit a scene by hand)
loop4sThe scene's length. Everything repeats within it. It must be more than 0.
fps30Frames per second, for exports and for frame steps. More than 0, at most 240.
design1920x1080The 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 its use: comp. Layers under children: [ … ] 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:

Edit a scene by hand

Change a scene file in a text editor, then load it into the app.

  1. In the app, save your work with ⌘S / Ctrl+S.
  2. Open the scene file in any text editor. Make your change and save the file.
  3. 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 scene and the scene's name, for example scene 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 schemaVersion is 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 4 when you animate a gradient. Write 5 when a video has an offset:. Write 11 when a video has a version:.
  • 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, 0 is the first node of comp main. 1 is the second child inside its transform. fill is 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.yaml shows in the middle of the canvas, after error —. 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:

MessageWhat 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 presentOne 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 $xThe token is not defined (see How a token finds its colour).
expected WxHA size not written like 1920x1080. Both sides must be more than 0.
expected a duration like 4s or 250msA 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 groupA 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 smallA value is out of range, for example opacity: 1.5 or fps: 300.

Value formats

These are the ways to write single values.

Size1920x1080 (or 1920×1080), or { width, height }. Use whole numbers in the 1920x1080 form. Both sides must be more than 0.
Duration4s, 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
AngleDegrees. A positive angle turns clockwise.
FractionA number from 0 to 1: phase, opacity, a gradient stop's offset
On or offtrue or false
Colour"#rgb", "#rgba", "#rrggbb", "#rrggbbaa", or a $token. Always put hex colours in quotes: a # without quotes starts a YAML comment.
TokenA name that starts with $, for example $team.gold
  • When the app saves, it writes each value in one standard form. For example, 4000ms becomes 4s, and scale: { x: 2, y: 2 } becomes scale: 2.

On this page