Quick start
New to Starlight? Read this page first. A copy of it, docs/quick-start.md, is the page to send to new artists.
The examples use an arena with six surfaces: N 6400×1600, E1 3200×1600, E2 3840×1600, S 4800×1600, W 6400×1600 and STAGE 1920×1080. Together, N to W make the 24640×1600 panorama. Keys show the Mac key first, then the Windows key (How keys are written).
Install
Install Starlight on a Mac or a Windows PC. The builds are not signed yet, so the system warns you the first time. This is expected, and you only do it once.
On a Mac (Apple Silicon):
- Unzip the
.zipfile. - Drag Starlight.app to Applications.
- Double-click it.
- If macOS says that it cannot check the app, click Done.
- Open System Settings › Privacy & Security. Scroll down and click Open Anyway.
- Click Open.
- Does macOS say that the app "is damaged and can't be opened"? Then the download is only blocked. In Terminal, run
xattr -dr com.apple.quarantine /Applications/Starlight.app. Then open the app again. - The first time Starlight opens a folder, macOS asks for access to Documents. Allow it.
On Windows (x64):
- Run
Starlight-<version> Setup.exe. - SmartScreen says "Windows protected your PC". Click More info.
- Click Run anyway.
Export needs nothing else: ffmpeg (the video encoder) is built in.
The first launch. Starlight copies a demo project to Documents/Starlight/bolts-demo and opens it. After that, it opens the project you used last.
- If Starlight cannot open a project when it starts, it shows the projects screen with the error. Click retry, or open another project (The Projects screen).
- Only one Starlight runs at a time. If you open it again while it is open, the open window comes to the front.
Open a shared project
Open your team's project from Dropbox. Several artists use it at the same time, as a shared project. Scenes, assets and renders sync through Dropbox. Your versions, caches and panel layout stay on your computer.
- Choose File › Open Project… (⌘O / Ctrl+O).
- Pick the project folder in Dropbox: the folder with
project.yamlin it. You can also pickproject.yamlitself. The owner gives you the path. - A notice may say that some files are online-only (not on this computer yet). Then open Assets (⇧A / Shift+A) and click make available offline.
- Set your name once. Open Settings: click the gear at the top right, or press ⌘, / Ctrl+,.
- Click project, then type your name in artist name. The other artists see this name on the scenes you edit (Project settings).
You can always look at any scene. Your first edit locks it: the padlock next to the scene name (top right) closes. The other artists then see the scene read-only. The lock ends when you click the padlock, change scene or quit. A scene that you leave with unsaved edits stays locked until you save them (Lock a scene).
- A padlock with a name means that artist is editing. You can still look at the scene.
- To take over the scene, click the padlock, or click edit anyway on the bar. Starlight asks first.
- If another artist takes the lock while you have unsaved edits, click save as a copy. Your edits become a new scene.
- If two artists save the same file at once, Dropbox keeps both. The second file is a conflicted copy, and a bar tells you about it. Click review, then keep mine or use theirs (Resolve a conflicted copy).
- Every save (⌘S / Ctrl+S) is a version. To bring back any version, click the v button at the top right (Save and go back to a version).
Start a new project
Make a new project: a new folder with its own surfaces and scenes.
- Choose File › New Project… (⇧⌘N / Ctrl+Shift+N).
- Type a name in name.
- To choose where it goes, click the folder button on the location row. The default is
~/Documents/Starlight. A folder in Dropbox, or in another synced folder, makes a shared project. - Under surfaces, click blank 1920×1080 for one surface. Or click copy from and pick a recent project, for example one with the arena's six surfaces.
- Click create, or press ⏎ / Enter in the name field.
- Starlight makes the folder, a first scene (
01-main) and its version history. Then it opens the project. - copy from copies only the surfaces. It does not copy the scenes, the brand kit or the assets.
- The line under location shows the new folder. Its name is the project name in lower case, with dashes: Halcyon Arena becomes
halcyon-arena. - Starlight never writes over files. The folder must be new, or empty.
- File › Projects shows your recent projects, each with a small map of its surfaces. Click one to open it (The Projects screen, Make a new project).
The canvas and Glimpse
The canvas is where you work. It shows every surface flat, side by side, at its true size.
- Click a layer to select it. Drag it to move it.
- Scroll or pinch to zoom.
- To pan, drag empty space, drag with the middle mouse button, or scroll with ⇧ / Shift held.
- Press ⇧1 / Shift+1 to fit everything on screen. Press 1 for 100% (Zoom, pan, fit). The zoom shows at the bottom right, for example
88.3%. Click it to pick a zoom from a list, or drag its slider.
Glimpse (⇧R / Shift+R) shows the real room in 3D, with the live canvas on every wall. Use it to judge the piece, not to edit it.
- Click a camera button to jump to a view.
- Choose walk (move with the keys W A S D) or orbit (drag to turn around the room).
- Double-click the room to go back to the start view. ▶ tour plays the walk-through (Look around the room).
- Glimpse shows the surfaces smaller than their real size: 1024 px on the long side by default. Keep this setting on a MacBook Air.
- To check the real size, publish to Glimpse (Feed size, not full size).
Surfaces and comps. Each surface in the project feeds the real wall with the same name. A comp is a group of layers that you can place on several surfaces. In the example arena, five surfaces share the panorama comp.
- At the top level, a click on the panorama selects the whole comp on that surface.
- To select a layer inside the comp, double-click the layer on the canvas. This selects the layer's transform, so you can drag it at once. The node graph steps into the comp too (Select a layer). You can also open the node graph (g) and double-click the comp there (Step into a comp).
- Inside the comp, double-click a comp layer to go one level deeper.
- To go back to the top level, click another surface or empty canvas, or press Esc.
Panels. Properties, Assets, Generations, Glimpse and Claude are panels.
- To move a panel, drag it by its title.
- To dock it, drop it on the window edge or just inside the canvas edge. You can also drop it on another panel (Float, dock and pin a panel).
- Window › Layouts saves your arrangement (Save and restore a layout).
Scenes
A scene is one piece of content for the whole room. A project has many scenes (Scenes).
- Press s for the scene list. Press ⌘PageUp / Ctrl+PageUp or ⌘PageDown / Ctrl+PageDown for the previous or next scene.
- You can leave a scene before you save it. Its changes stay, still unsaved. A dot in the scene list marks every scene with unsaved changes. File › Save All (⌥⌘S / Ctrl+Alt+S) saves them all.
- Each scene in the list has a picture of its first surface (the top-left surface that the scene shows content on). The two buttons at the top of the list change it to a gallery of bigger pictures, and back to the list (Open the scene list). Drag a scene to change the order of the scenes (Change the scene order).
- To make a scene, click + new scene in the list. The new scene starts from a template, with one sample word on every surface.
- Right-click a scene in the list, or the scene name at the top right. The menu has open, rename scene, duplicate scene, new scene and delete scene.
- delete scene asks first, and makes a version. You cannot delete the last scene.
- To open a scene by its name, press / for the command palette and type the name.
- Press Space to play. Every scene loops with no jump at the end.
Import media
Import copies your files into the project and prepares them for fast playback.
- Drag files into the Starlight window. Or open Assets (⇧A / Shift+A) and click import….
- The Assets panel opens and shows the new tiles.
- To place a video or audio file, drag its tile from Assets onto a surface (Place an asset on a surface).
- An image that you drop on the canvas is imported and also placed on that surface. If the node graph is inside a comp, the image goes into that comp.
- A video or audio file that you drop on the canvas is only imported.
What import does (Import media, Video ingest and proxies):
- Video becomes an all-intra working file: every frame is stored whole. So scrubbing (dragging through time) and looping are instant.
- Video bigger than 1920 px on its long side also gets a quarter-size proxy: a small copy for fast playback.
- This work runs in the background. The notice line shows the progress.
- Video with transparency (ProRes 4444, Animation, PNG-in-MOV) keeps it.
- A folder of numbered frames becomes one video at 30 fps.
- HEIC, TIFF and EXR stills become PNG. PNG, JPG, SVG, GIF and audio stay as they are.
- A font file (
.ttf,.otf,.woffor.woff2) goes tofonts/. You can pick it at once (Fonts). - The original file stays untouched in
assets/originals/. Scenes use the working file. - In a shared project, the file stays as you imported it. The working file goes to this computer's media cache instead.
- Let an import finish before you quit. A stopped import does not start again by itself. To finish it, click ingest in Assets.
Masks
A mask cuts a layer to a shape that you draw.
- Select the layer.
- Press ⇧M / Shift+M. The pen opens.
- Click to add a corner. Drag to add a curve.
- Click the first point to close the shape.
- ⏎ / Enter finishes an open path. The layer is then masked along its line.
- ⌫ / Backspace removes the last point. Esc cancels.
- Hold ⇧ / Shift to keep a click or a handle horizontal or vertical.
- The layer goes inside a matte node. The layer is the matte's content, and the shape is its matte. The shape is not drawn; it only cuts.
Change the mask (Mask a layer):
- Select the matte node, or the layer that it cuts. Find the matte section in Properties (⇧P / Shift+P).
- There, set mode (alpha or luma), invert, feather px (a soft edge) and opacity. An opacity of 0 shows the layer uncut.
- On the matte node, ✎ draws a new shape. ⤺ removes the cut: both become normal layers again.
- To cut a layer by another layer that already exists, select it. Then click + on the title row of its matte section. The ✎ there draws a new shape instead.
- In the node graph, hold ⌥ / Alt and drag a layer onto the matte node's
contentormatteport to connect it. - Press b on the matte node to see the layer uncut.
- Double-click the shape to edit its points. While you edit, drag the lavender knob to soften the edge (Edit a path's points).
- With the viewer on (v), select the shape to see the mask in white on black.
Colour and blend modes
Change a layer's colours with the colour tools in Properties.
- Select the layer.
- In Properties, click the + on the title row of the effects section. A list opens: colour tools on the left (color), other effects on the right.
- Pick a tool: exposure, brightness-contrast, hue-saturation, levels, curves, color-balance, temperature-tint, invert or lut. A lut uses a
.cubefile inassets/.
- A card shows the settings that you changed, and the main ones. Click N more to see the rest.
- All colour tools on a layer join into one LUT (a colour table). So they cost almost nothing (Add effects and colour ops).
Blend modes. The blend row sets how a layer mixes with the layers below it (Set a blend mode).
- The row shows by itself when the blend is not normal. Otherwise, click ⋯ in the top strip of Properties to show it.
normal,multiply,screenandaddare free. Every other mode costs an extra render pass, which takes more GPU time.- For example, an
overlayvideo on all six surfaces at full size takes a frame from 6 ms to 18 ms. At room zoom, the scene still plays in real time.
AI tools: compose, Generations and Claude
Three AI tools help you make content. All three need the internet.
Add your API keys once in Settings › Keys: Magnific, videorouter, Higgsfield and Atlas Cloud. Starlight stores them encrypted, on this computer only. ⌘K compose and the Claude panel need no key. Settings › Generation sets who plans ⌘K compose, and your spend limits.
⌘K compose (/ or ⌘K / Ctrl+K, then ask Claude): describe a change in plain words, for example "a slow gold shimmer on the N surface".
- Your words go to the Claude panel as a message. Claude edits the scene, and you watch the canvas.
- Claude asks before it spends money on a generation.
Generations (⇧G / Shift+G): AI images, video and upscales (Make an image or video).
- Click + new to open the form.
- Fill it in. Every job shows its price before you click generate.
- When a job is done, click import to copy the result into your assets.
Stage: plan a shot in 3D before you spend money. Select a surface and press ⇧S / Shift+S, or choose Window › Stage. The Stage panel opens beside the canvas, with grey boxes and figures that you can pose, seen through a real lens.
Claude (⌃` / Ctrl+`): Claude Code in a terminal, working in this project.
- It uses your own Claude Code install. If Claude Code is missing, the panel shows the install command.
- While you type in it, Starlight's shortcuts are off. Press ⇧Esc / Shift+Esc to give the keys back to the canvas.
The project remembers your chats, your ⌘K turns and the brief (your direction and decisions). It also keeps the prompt, cost and grade of each generation (What the project remembers).
Export
Export makes one video file per surface, for the media server.
- Press ⌘E / Ctrl+E to open the export sheet.
- Pick the format, the fps (30 or 60), the surfaces and the destination folder.
- Press ⏎ / Enter, or click export. Starlight renders (makes) the video files.
- The sheet remembers your last choice in each project. The first time, it starts on ProRes 422 HQ on a Mac, and on HEVC 10-bit on Windows.
- HEVC 10-bit (
.mp4) is for the room. ProRes 422 HQ (.mov) is the master copy. - HAP Q is only for a media server that asks for HAP. H.264 is only for previews (Pick a format).
- The files go to
renders/<scene>/, with names likeopener_N_6400x1600_60fps_hevc10.mp4. The end of the name is the codec, so two formats never share a file. - If a file with that name is already there, the sheet lists it. Press replace… two times to replace it. The old file stays until the new one is finished (Replace an older export).
- In a shared project,
renders/is in the project folder in Dropbox. So the other artists get the files too (Where the files land). - Never make one 24640-px file: media servers stop at 16384 px.
- Export renders every frame of every surface at full size. So long loops on big surfaces take minutes.
- Before it starts, the export checks every file. A missing, online-only or broken file stops it, and the sheet names the file (When a file cannot render).
- ⇧⌘E / Ctrl+Shift+E exports the reel: every scene, one file per surface.
- To cancel an export, point at the export ring next to the time and click stop. Esc also cancels, but only when nothing else is open, and it asks first (Follow or cancel).
- While an export runs, the computer does not go to sleep. Quit and Open Project ask first (Quit or switch during an export).
- You can keep working while an export runs. The export renders in the background, so the canvas, the panels and the Claude panel stay fast.
- Nothing heavy runs beside an export, so the export gets the whole computer. Video ingest, new versions of a clip, node pre-renders, tracking and the scene list's pictures wait, and go on by themselves after it. An ingest, a new version or a pre-render that was halfway through when the export started starts again from the beginning (Video ingest and proxies). A still, a cutout or a stage capture you ask for still runs at once.
Publish to Glimpse
Publishing puts a scene on the Glimpse website, in the 3D room, for the team and the client. Starlight renders every surface (as H.264) and uploads them as a look. Starlight also uploads two smaller playback copies so surfaces play smoothly in browsers. If you publish the same scene again, Claude asks before it replaces the look. Claude can also publish into any other look, even one uploaded in the browser.
- Save the scene. Publishing uses the saved scene.
- The first time, open Settings › Keys and click Connect to Glimpse. Or paste a token there.
- Ask Claude to "publish 01-panorama to Glimpse". Use the Claude panel, or Claude Code connected to Starlight. There is no button yet.
- Claude does a test run first, then publishes.
- Each surface's video is its own length, because Glimpse loops each surface on its own (Publish to Glimpse).
- Before Claude replaces a look, it asks you: Replace the look 'Electric Forest' (made by Beti, updated 28 October 2026 at 14:05)? It replaces the look only after you say yes.
- Six surfaces take about ten minutes on a MacBook Air.
- Only the surfaces are published, not the panorama comp (Publish to Glimpse).
Heavy scenes
How to keep a big scene fast on a laptop.
Work at room zoom on the MacBook Air. Check full size on the Windows PCs.
- Room zoom is the view that fits the whole room on screen (⇧1 / Shift+1). The surfaces then play their proxies (small copies), and a MacBook Air plays the scene in real time.
- Only the surfaces that you can see on the canvas draw. A surface outside the canvas costs nothing, and its videos pause (after 5 seconds while the scene plays; When your computer cannot keep up).
- At 100%, each surface that you can see draws at full size, and its videos play their full-size files. Six full-size surfaces are too much for a MacBook Air. The surfaces outside the canvas cost nothing.
- At 100%, each extra blend or mask pass also covers 16 times more pixels. Zoom in on one surface only to place things.
- To work on one surface, select its comp, or a layer in it. Then press f, or click focus at the top right of the canvas (Focus on one comp).
- The other surfaces then hide and stop rendering. Press f again to bring them back. Glimpse and export always use every surface.
- Before you deliver, play the scene at full size (1) on a Windows PC. These PCs play surface-size video in hardware. Export always renders at full size.
Shortcuts
The keys you use every day. Every shortcut is in Keyboard & mouse.
| Key | Does |
|---|---|
| ⌘O / Ctrl+O | Open a project |
| ⇧⌘N / Ctrl+Shift+N | New project |
| ⌘S / Ctrl+S | Save the open scene, and make a version. Works from a field too |
| ⌥⌘S / Ctrl+Alt+S | Save All: every scene with unsaved changes |
| ⌘R / Ctrl+R | Reload the project from disk, after an edit in a text editor |
| ⌘Z / Ctrl+Z, ⇧⌘Z / Ctrl+Shift+Z | Undo, redo |
| ⌘, / Ctrl+, | Settings |
| Space | Play or pause |
| , . | One frame back, one frame forward. With ⇧ / Shift: 10 frames |
| i o | Start and end of a part to loop (the work area), at the playhead |
| ⇧1 / Shift+1, 1 | Fit all, 100% |
| s | Scene list |
| p | Projects |
| ⌘PageUp / Ctrl+PageUp, ⌘PageDown / Ctrl+PageDown | Previous scene, next scene |
| /, ⌘/ / Ctrl+/, ⌘K / Ctrl+K | Command palette: run a command, or ask Claude (AI) |
| ⌘F / Ctrl+F | Find a node in the graph. Over Properties: filter its rows. In the scene list: search the scenes |
| g | Node graph |
| ⇧T / Shift+T, ⌥T / Alt+T | Timeline. Switch its view (layers or curves) |
| ⇧P ⇧A ⇧G ⇧R / Shift+P A G R | Properties, Assets, Generations, Glimpse |
| ⌃` / Ctrl+` | Claude |
| ` | Make the panel you work in fill the window. Press again to put the layout back (Make a panel fill the window) |
| ⇧M / Shift+M | Draw a mask on the selected layer |
| b | Bypass the selected layer: switch off what it adds. A transform or group keeps showing its layers, without its own position, animation and effects. A picture, shape, text or video hides |
| v | Viewer: the surface shows the selected node's result, with a thin grey frame round it. Press again for the final output |
| f | Focus: show only the surfaces that the selected comp feeds. Press again for every surface |
| ⌘E / Ctrl+E, ⇧⌘E / Ctrl+Shift+E | Export the scene, export the reel |
| Esc | Close what is open, such as the scene list or the timeline. Otherwise, clear the selection. During an export, with nothing else open: ask to cancel it |
| ? | This guide |
The keys that show or hide a panel or a view, in one list:
- ⇧T / Shift+T timeline · ⇧P / Shift+P properties · ⇧A / Shift+A assets
- ⇧G / Shift+G generations · ⇧R / Shift+R glimpse · ⇧S / Shift+S stage · ⌃` / Ctrl+` claude
- v viewer · f focus · ` fill the window with the panel you work in
The curves view is the timeline's second view. Press ⌥T / Alt+T to switch to it (Open a lane's curve). The Stage panel opens with ⇧S / Shift+S or Window › Stage (Open and close the Stage panel).
Start here
This guide explains Starlight, with one section for each part of the app. New to Starlight? Read the quick start first. Then make your first graphic .
What it is
Starlight is a desktop app. You use it to make the content for every display in a venue: LED walls, video screens and ribbon displays.