Skip to Content
Starlight

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. The project.yaml file 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's design (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:

  1. Click the surface's label on the canvas, or its node in the node graph.
  2. Look at the rows under surface in Properties.
RowWhat it shows
compThe comp that the surface shows. You cannot edit it here. It shows only when the surface has a comp.
output resolutionW × H. Type or drag a value to change it for this scene. It takes whole pixels, 8 or more.
fitThe 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.
artboardThe 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 children use the design size, and the fit scales them like a comp. Put them in a transform to place them.
  • A surface entry can also set size, fit and design for 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: in project.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.

FitWhat it does
none (default)Draws the design 1:1 from the surface's top-left corner. No scaling.
fillStretches to the surface. The aspect ratio can change.
cover / containScales and keeps the aspect ratio, centred on the surface. cover crops; contain adds empty bars.
tile-x / tile-yScales 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. With tile-y, it starts at the top. The last tile is cut off at the surface's edge.
  • Any other word in fit is 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:

  1. Make a comp for the ribbon, with layers made for a height of 84 px.
  2. Give the ribbon surface the same height as its design size: design: 1920x84.
  3. 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-x draws 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.

On this page