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.
Add a clock to a layer
A layer's clock: block holds its timing and its keyframes. This page uses these words (see also Glossary › Time and motion):
- Loop
- The length of the scene. You set it with the scene's
loop:key. If you leave it out, the loop is 4s. Playback and export repeat it without end. - Clock
- A timer that runs in cycles, again and again. It moves the keyframes that use it.
- Period
- How long one cycle of a clock takes, for example
2s. - Phase
- The position inside one cycle: 0 is the start, 1 is the end.
- Keyframe (key)
- A value at a phase. Starlight fills in the values between two keys.
- Track
- The list of keyframes for one property, for example
scale.
Keyframes sit at phases, not at seconds. So a loop never jumps where it starts again. If you change a clock's period, everything it moves changes speed with it.
clock:
period: 2s # omit it to use the scene loop; must divide the loop
mode: loop # loop (default) · once · pingpong
tracks:
scale: [1, 1.16, 1] # SHORTHAND: values spread evenly over phase 0..1 (smooth ease)
skewX: # LONG FORM: explicit phase + ease
- { phase: 0.0, value: 0, ease: snap }
- { phase: 0.08, value: -12 }
- { phase: 0.30, value: 0, ease: overshoot }
- { phase: 1.0, value: 0 }
- Properties you can animate:
x,y,scale,scaleX,scaleY,rotate,skewX,skewYandopacity. Any other name is an error. - Effect parameters and gradient values can animate too. You write the keys in place of the value (Effects, gradient).
periodis a duration:2s,500ms, or a plain number, which means milliseconds. Leave it out to use the scene loop.- Shorthand, for example
[a, b, a]: the values spread evenly from phase 0 to 1. Each key except the last gets thesmoothease. - Long form: each key is
{ phase, value, ease }, with aphasefrom 0 to 1. A phase outside 0 to 1 is an error. If you leave outphase, the keys spread evenly. - One track uses one form. A list that mixes plain numbers and
{ phase, value }keys is an error. - You can write the keys in any order. Starlight plays them in phase order.
- A steady spin needs a
linearease, becausesmoothslows down at both ends. Write it like this:rotate: [{ value: 0, ease: linear }, { value: 360 }].
How tracks combine with the layer
A track does not replace the layer's static value (its value with no animation). It combines with it like this:
xandyadd to the layer's position. Withx: 170and a trackx: [0, 40], the layer moves from 170 to 210.scalemultipliesscaleX,scaleYand the static scale. Animatescalefor a clean pop. AnimatescaleXalone for a squash.rotate,skewXandskewYare in degrees. They add to the static values.opacitygoes from 0 to 1. It multiplies the static opacity.- Animated scale, rotate and skew turn around the transform's
anchor. This is the same point that the fixed (static) scale and rotation turn around. - With no
anchor, animated scale, rotate and skew turn around the layer's centre: the middle of the box around the layer (its bounding box). Older scenes work this way, so they play as before. A layer with its own clock that is not a transform (for example atextwith aclock) also turns around its centre. To choose the point, put the layer in a transform and set itsanchor. - Ends hold. Before the first key and after the last key, the value stays flat. With keys at 0.3 and 0.8, the value holds from 0 to 0.3 and from 0.8 to 1.
The period rule
Follow this rule, so that a loop plays with no jump.
The loop divided by the period must be a whole number. For a 4s loop, a 2s period works ✓ and a 3s period does not ✗. If it does not divide, the clock jumps where the loop starts again. This jump is called a seam.
The dial then turns amber, and Properties shows "does not divide the scene clock — seam at export". A derived period, scene/N (the loop divided by N), divides evenly when N is a whole number, for example scene/4. A fraction such as scene/1.5 does not.
- A seam is a warning, not an error. The scene still plays and exports, but the loop is not clean.
- To check all named clocks at once, select the scene dial. Its sheet says all clocks divide the loop, or seam at export: followed by the names of the clocks that seam. With no named clocks, it says no named clocks.
Play modes
The mode: key sets what a clock does at the end of each cycle.
- loop (the default) starts again at phase 0. Make the last keyframe equal to the first, or use a belt that wraps.
- pingpong plays forward, then backward, so one full cycle takes
2 × period. Use it for a breathing motion with no jump back, for examplescale: [1, 1.04]. - With pingpong, one round trip (
2 × period) must divide the scene loop. If it does not, the clock gets the amber loop-seam warning (its dial turns amber), like any other clock that seams. A pingpong clock with no period of its own takes the loop as its period, so it gets only halfway and seams too. - once plays one time, then holds the last value. It plays again when the scene loop starts again.
The scene clock always loops. A layer's own clock and named clocks can use all three modes.
Easing
An ease is the shape of the motion between two keyframes. You set it on the key where the motion starts, and it shapes the way to the next key. The last keyframe needs no ease. A key with no ease gets smooth.
- A name:
linear,ease,ease-in,ease-out,ease-in-out,smooth,snap,overshoot,expo-in,expo-out,expo-in-out,back-in,back-in-out,hold,elastic,bounceorspring. An unknown name is an error. - Steps:
steps(4)makes 4 equal jumps, each at the end of its step.steps(4, start)jumps at the start of each step. The number must be a whole number, 1 or more.steps(1)is the same ashold, and it saves ashold. - A custom curve:
cubic-bezier(.2,0,.8,1),[.2, 0, .8, 1]or{ x1: .2, y1: 0, x2: .8, y2: 1 }. In all three forms,x1andx2must be from 0 to 1.y1andy2can go outside 0 to 1, to overshoot. - A custom curve that matches a named ease saves back as that name.
- Eases work on transform tracks, effect parameters and gradient keys. They never work on a
gate.
For every ease, what it does and how to shape one by eye, see Eases in Curves and eases.
Named clocks — one source, many users
A named clock is a clock that many layers can share. You set it at the scene level, under clocks:. Change it once, and every layer that uses it changes timing.
clocks:
heartbeat: { period: 2s, mode: loop } # a shared source, NO tracks of its own
quarter: { period: scene/4 } # derived: the scene loop ÷ 4
comps:
main:
- text: "A"
clock: { use: heartbeat, tracks: { scale: [1, 1.1, 1] } }
- text: "B"
clock: { use: heartbeat, tracks: { opacity: [0.5, 1, 0.5] } }
- A named clock holds only timing:
periodandmode, plus optionalcuesand atrigger. It has no tracks. Each layer keeps its own tracks. - A named clock with no
perioduses the scene loop. With nomode, it loops. clock: { use: X, tracks: {…} }takes the period and the mode fromX.- A
periodormodenext touse:is an error. Ause:that names no clock is also an error. The message lists the clocks that exist. scene/Nis the scene loop divided by N, andscenealone is the whole loop. It changes when the scene loop changes. N must be more than 0. It can be a fraction, but then the clock seams (the period rule).- The old spelling
main/Nstill opens. It saves back asscene/N. - Beat clocks: select an audio layer and click + beat clocks from N bpm ↗ in Properties. (bpm means beats per minute.) The button shows once the analysis has found a tempo.
- It adds two named clocks:
beat(one beat long) andbar(four beats long). Both line up with the first downbeat found in the song. - Beat clocks carry
offset:, which is where phase 0 falls in the song. They also carryunwrapped: true: they keep counting with the song when the loop starts again.
Make a named clock in the app.
- Open the command palette (/, or ⌘/ / Ctrl+/), choose clock and type a name. With no name, it is called
clock. Its period is the scene loop. Its dial appears in the graph, and its sheet opens in Properties. - Or right-click a layer that has its own animation and choose promote to named clock. The layer's period and mode move to a new named clock, named after the layer. The tracks stay on the layer.
- If that period divides the loop, the new clock uses
scene/N. If not, it keeps the period in ms. - Edit a named clock's name, period (in ms, or as scene ÷ N) and mode in its sheet (A clock's sheet).
Cues — named moments on a clock
A cue is a named moment on a clock, written as a phase from 0 to 1. A trigger can start another clock at a cue.
- Cues on the scene clock go at the scene root, under
cues:. - Cues on a named clock go inside that clock.
- Each clock has its own cue names. A phase outside 0 to 1 is an error.
cues: # cues on the SCENE clock (the loop)
impact: 0.25
finale: 0.75
clocks:
heartbeat: { period: 2s, cues: { beat: 0.5 } } # a cue on a named clock
In the app, each clock is a round dial in the node graph. Cues sit on the dial's cue band (Use the clock dials). A cue that no trigger uses does nothing. It is only a label.
Triggers — chaining one clock to another
A trigger starts a named clock when another clock reaches a cue. You write the trigger on the clock that starts.
clocks:
heartbeat: { period: 2s, cues: { hit: 0.5 } }
pulse: { period: 1s, trigger: { from: heartbeat, cue: hit } } # starts on heartbeat's "hit"
fromis a named clock orscene. Withfrom: scene, the cue comes from the scene'scues:. A trigger never starts the scene clock itself.- The trigger moves the started clock's phase 0 to the moment of the cue. Before that moment, the clock waits at phase 0.
- Chains add up: in A → B → C, C starts at its cue on B, and B starts at its cue on A. If a chain would start a clock after the loop ends, the start wraps back into the loop.
- These are errors: a clock that triggers itself, an unknown
from, a missing cue, or a cycle (A → B → A). The error message names the clock. - A triggered clock loops cleanly only if it starts on a whole cycle of its own period.
- If it does not, the dial turns amber. Properties shows "starts (trigger / offset) off a whole cycle — seam at export".
- In the app, drag a cue off its band onto another dial. A dashed arrow joins the two dials. To remove a trigger, right-click the started dial and choose clear trigger.
The gate — a timed in/out
A gate shows and hides a layer in time. It is a gate: track on a clock, with keys of 0 (off) or 1 (on). Its keys always hold: they jump, with no blend between them.
- The layer draws only while the gate is on. Before the first key, the gate is off.
- Shorthand:
gate: [0, 1, 0]. Long form:[{ phase: 0.25, value: 1 }, { phase: 0.75, value: 0 }]. - A key value other than 0 or 1 is an error. An
easeon a gate key is also an error. gate:goes in the clock block, besidetracks:, not inside it.- A gated layer appears and disappears in every cycle of its clock.
- For one appearance in scene time, use the layer's
spaninstead (Trim a layer). - With both a gate and a span, the layer shows only where both are on.
Add a gate in the app.
- Select the layer.
- In Properties, click ◇ on the top strip. This adds a gate that is on for the first half of the cycle.
- The gate opens in the timeline. There, trim and slide its spans (the stretches where the layer shows).
- To remove the gate, click the lit ◇ again. The layer then shows for the whole loop.
Band drivers — audio → motion
A drive moves a property with the music. It follows the energy of one band of an audio track. A band is one part of the sound, for example the bass. A drive works like After Effects' audio amplitude, but live.
You write a drive in YAML, in a clock's drive: key: drive: { scale: { band: bass, range: [1, 1.4] } }. These are its keys:
| Key | What it does |
|---|---|
band | Required. bass, mid or high. Or kick, snare or hat, which are detected drum hits. Or energy, the overall intensity of the track. Use energy with a range to move a whole scene with the song. |
range | Required. [atSilence, atFullEnergy]: the value at silence and the value at full energy. Swap the two numbers to dip on the beat. |
audio | The id of an audio layer. The default is the scene's first audio layer. |
smooth | Smooths fast changes: Starlight averages the value over this time. The default is 80ms. |
mode: punch | Optional. Fires a pulse that fades out on each detected hit. Without it, the drive follows steady energy (level mode, mode: level). |
release | Optional. In punch mode, how long the pulse takes to fade (default 200ms). In level mode, it makes the value fall slowly, like a sound level meter. Level mode has no release by default. |
shape | Optional. More than 0. 1 (the default) is straight. 2 makes peaks stronger. 0.5 makes quiet parts stronger. |
floor | Optional, from 0 to 1. Levels under this value count as silence. For example, 0.1 removes low rumble. |
normalize | Optional. false turns off auto-gain. Auto-gain (on by default) maps the band's real range onto the full range. |
- A drive follows the song's own time, not the loop phase.
- A drive replaces the keyframes of its property.
- With no audio layer in the scene, a drive does nothing.
- Preview and export read the same stored (cached) analysis of the song.
- You add a drive in YAML, or ask Claude. Properties lists each drive in its drives section, for example
scale ← kick · punch [1‥1.35]. - In that section, ⧉ bakes the drive (Bake), and × removes it.
This logo snaps on the kick and then fades back:
drive:
scale: { band: kick, range: [1, 1.35], release: 180ms, shape: 1.5 }
Bake a driver to keyframes
Baking turns a drive into ordinary keyframes that you can edit.
- Move the playhead to the part of the song that you want.
- Select the layer.
- In Properties, find the drive in the drives section.
- Click ⧉. Its tooltip says bake → keyframes.
- The keys cover one cycle of the layer's clock: the cycle that the playhead is in.
- Attacks (the sharp start of each hit) stay sharp. The rest uses the fewest keys that stay within 1.5% of the range, with at most 96 keys. The keys use the
linearease. - The keyframes replace the drive. The timeline opens on the new lane.
- Bake works only on a clock in
loopmode. On another mode, Starlight says, for example, cannot bake onto a once clock — bake supports loop mode. - If the song is not analysed yet, Starlight says cannot bake — audio analysis not ready.
- Bake when you want to make a hit bigger by hand, or to keep the motion if you swap the audio track.
- One undo reverses the bake.
The musical map
Starlight analyses every audio track and makes a musical map of it. The map holds:
- the BPM (beats per minute) and the beats
- the kick, snare and hat hits
- an intensity curve with the drops, the builds and the climax
- sections, grouped by how alike they sound (every chorus gets the same letter)
- the musical key
- The audio layer's Properties shows the length and the tempo. It also shows the key (when Starlight is sure of it), the sections, the drops and the climax, for example
sections: A@0:00 B@0:32. - While the analysis runs, Properties says analyzing…. If it finds no tempo, it says tempo not detected.
- The audio dial shows the map too (audio dial).
- Claude reads the whole map, builds included, with the
music_maptool to pace a scene to the song.
fps & frames
A scene's fps: (frames per second) sets how many frames each second has.
- The default is 30. Use 60 for fast motion. The most is 240.
- To change it in the app, select the scene dial and edit fps in its sheet (A clock's sheet). The loop keeps its length in seconds.
- fps sets frame stepping, the frame readouts and the export.
- A frame number is
round(seconds × fps). - A seamless loop has exactly
loop × fpsframes. Frame 0 is at t = 0. - The last frame comes just before t = loop. A frame at t = loop would repeat frame 0.
- Click the time in the centre of a dial to switch the app between seconds and frames.
In the app
You can do all of this with the mouse. Each clock is a round dial in the node graph (Use the clock dials).
- In Properties, click a property's ◇ to animate it. Or drag the ◇ onto a dial (Keyframe a property).
- Edit the keys in the timeline.
- Shape their eases in the timeline's curves view.