Surfaces & fit
A surface is one LED output, like N, E1 or STAGE. In YAML, each entry under surfaces: is a surface.
You name every surface once, in project.yaml. Each scene then says what each surface shows.
Output size and design size
Every surface has two sizes. They do different jobs.
- The output resolution (YAML
size) is the number of pixels Starlight renders for the surface. On an LED wall, this is its pixel map: the real number of LEDs across and down. Theproject.yamlfile sets it, and a scene can change it. - The design size (YAML
design) is the area you lay out the content on. Properties calls it the artboard. It is the scene'sdesign(1920×1080 if not set), or the surface's own. - The fit scales the design size into the output resolution.
Starlight renders each surface at its exact pixel count. Zoom in on the canvas and you see the real LED grid.
To see a surface's sizes:
- Click the surface's label on the canvas, or its node in the node graph.
- Look at the rows under surface in Properties.
| Row | What it shows |
|---|---|
| comp | The comp that the surface shows. You cannot edit it here. It shows only when the surface has a comp. |
| output resolution | W × H. Type or drag a value to change it for this scene. It takes whole pixels, 8 or more. |
| fit | The fit. The first choice is the fit that the surface gets from elsewhere. It also says where that comes from, for example none (project) or none (default). Pick it to remove this scene's own fit. |
| artboard | The design size. When it is the same as the output resolution, the row shows same as output ▸. Click that to open the row and edit it. |
- If this scene's size is different from the project's, a note under output resolution says overridden in this scene. It also shows the project's value and a reset button.
- If the scene sets the same size as the project, the note says set in this scene (same as project). Click reset to remove the extra key.
- When the surface has its own artboard, a note under artboard shows the scene's artboard and a reset button.
- Point at a row to see its YAML key. Your edits change only this scene, never
project.yaml.
Feed a surface
A scene says what each surface shows.
use: <comp>shows a comp on the surface. A comp is a named group of layers.children: [ … ]adds layers that draw on top of the comp.- You can use one, both or neither. A surface with neither (
N: {}) is empty and shows black. A surface that the scene does not list is empty too. - One comp can feed many surfaces.
- To change which comp a surface shows, rewire it in the node graph (see Wire and reorder layers). This changes only its
use. - Layers in
childrenuse the design size, and the fit scales them like a comp. Put them in atransformto place them. - A surface entry can also set
size,fitanddesignfor this scene only. - A scene can only use the surfaces in
project.yaml. A name that is not there shows in the node graph, so you can rewire it or remove it. Nothing else uses it: it is not shown, rendered, exported or published, and its videos do not play. When you open such a scene, a warning names these surfaces, for example: This scene uses a surface named main-4k, but the project has no surface with that name. - To add a surface, add it under
surfaces:inproject.yaml, with its size (see project.yaml). Then choose File › Reload Project from Disk. A shared project reloads by itself. There is no button for it, and Claude has no tool for it.
surfaces:
N: { use: main } # a comp
E1: { use: main, fit: cover } # the same comp, its own fit
STAGE:
use: main
children: # drawn on top of the comp
- transform:
- text: "LIVE"
position: [80, 60]
S: {} # empty: black
Fit modes
The fit says how the design size maps onto the surface's pixels. A scene can set fit. If it does not, the surface uses the fit in project.yaml. If that is not set either, the fit is none.
| Fit | What it does |
|---|---|
none (default) | Draws the design 1:1 from the surface's top-left corner. No scaling. |
fill | Stretches to the surface. The aspect ratio can change. |
cover / contain | Scales and keeps the aspect ratio, centred on the surface. cover crops; contain adds empty bars. |
tile-x / tile-y | Scales to the surface's height (tile-y: its width), then repeats along the surface. Best for ribbons. At most 64 tiles. |
- Anything outside the surface's edges is cut off.
- With
tile-x, the first tile starts at the left edge. Withtile-y, it starts at the top. The last tile is cut off at the surface's edge. - Any other word in
fitis an error.
Lay out a ribbon
A ribbon is a long, thin surface, about 84 px high and over 10,000 px wide. Give it its own design size.
If you tile a 1920×1080 comp onto it, tile-x shrinks 1080 px to 84 px. Everything becomes about 13 times too small. Instead, do this:
- Make a comp for the ribbon, with layers made for a height of 84 px.
- Give the ribbon surface the same height as its design size:
design: 1920x84. - Set
fit: tile-x.
comps:
band: # designed at 1920x84, the real ribbon height
- clone: { of: assets/bolt-rib.svg, count: 6, gap: 480, direction: x, drift: -240px/s }
surfaces:
ribbon-main: { size: 10080x84, use: band, fit: tile-x, design: 1920x84 }
- Now
tile-xdraws the comp 1:1 and repeats it in 6 tiles across the 10080 px. The last tile is cut off. - On a ribbon, use repeated bold marks. Do not crowd it with words.
- Starlight asks your graphics card for the largest image it can hold. On most desktop cards this is 16384 px, so a 10080 px surface shows every pixel.
- A surface can be wider than that limit. An example is 20000 px on a card with a 16384 px limit. Such a surface shows at lower resolution in the preview. It is a little soft there, but its edges never show steps. The developer console shows a warning. Export is not affected: it renders every surface at full resolution.
Node types
This is the YAML reference for every node type: what it draws or does, and its props (settings). A node is a map with exactly one keyword key. That key picks its kind.
Clocks & animation
All motion in Starlight runs on clocks. This is the YAML reference for clocks, keyframes, eases, cues, triggers, gates and audio drives. To animate with the mouse, see In the app .