Skip to Content
Starlight

Extensions: make it your own app

Add your own effects and drawing tools to Starlight with one small JavaScript file per extension.

An extension is a file at <project>/extensions/<name>/index.js. It exports one function, export default function register(api), and imports nothing. Everything it needs comes in the api object. When you save the file, Starlight loads the new version at once.

  • Only index.js loads. Put all of the extension's code in that one file. Starlight skips a folder without an index.js.
  • The folder name is the extension's name. It shows in error lines and in the trust prompt.
  • The names you register (for example with registerEffect) are what scenes use. One extension can register more than one effect or node type.
  • The optional file extensions/manifest.json lists extensions with a name, a kind and a description. Extensions in it load first, in its order. The other folders load after them, in alphabetical order.
  • A project's extensions run only after you trust them (Trust a project's extensions).

What you can register

An extension can add three kinds of things. The built-in effects use the same plugin API.

  • Effects. A GPU shader that changes a layer's pixels: a grade, a style, a distortion. You write the same maths twice: in GLSL for WebGL2 and in WGSL for WebGPU. You also list its number params. It works in scene YAML and in the effect picker as soon as it loads.
  • Colour ops. A function that turns one colour into another. Starlight adds it to the layer's one colour lookup table (LUT), so it costs almost nothing.
  • Node types. A new kind of drawing, for example a score bar or a badge. You build it with the Pixi tools in api.pixi.

If an extension fails with an error, Starlight shows a one-line message on the canvas and skips that extension. The app keeps working. Starlight also removes anything that the extension registered before the error.

If you register a name that already exists, your version replaces the old one. So an extension that registers blur replaces the built-in blur while it is loaded. The picker still lists it with the built-in effects.

How a custom node type is saved in a scene file

A new node type loads and shows in the catalog and the command palette. In the scene file, you write it with the node: keyword. Its own settings sit beside it, at the same indent:

- transform:
    - node: badge        # the name the extension registered
      size: 120          # the extension's own settings
      fill: "#ff0000"
  position: { x: 400, y: 200 }

The common fields (id, clock, effects, blend, bypass, span, delay) work as on any layer. Every other key belongs to the extension, and Starlight keeps it as it is.

A scene that holds a custom node is saved as schemaVersion: 6. It opens and saves without the extension, but the node draws only while the extension is loaded and trusted. You cannot write a built-in type this way: node: text is an error, so use text:.

The injected api

These are all the tools an extension gets.

MemberWhat it does
registerEffect(name, def)Adds a GPU effect or a colour op. name is its YAML keyword and its name in the catalog.
defineShaderEffect(spec)The easy way to build an effect. Give it the two shader bodies and a list of number params. Pass the result to registerEffect.
definePointOp(compile)Builds a colour op. compile(params) runs once per LUT build and returns (rgb) => void.
registerNodeType(kind, def)Adds a node type. def.build(ctx, node) returns a Pixi Container.
pixiThe Pixi tools for node types: { Container, Graphics, Sprite, Text, TextStyle }. They are the only Pixi parts you can use.
zA small schema helper, because extensions cannot import zod: z.number/string/boolean/enum/object, each with .optional(). It only describes the params: Starlight does not check values against it.
EASING_PRESETSThe curve eases as bezier points: linear, ease, ease-in, ease-out, ease-in-out, smooth, snap, overshoot, expo-in, expo-out, expo-in-out, back-in, back-in-out.

The shader contract

These rules connect your params to the shader code.

Each param becomes one float uniform. Its name is u plus the param name with a capital first letter: gap → uGap, amount → uAmount, rHi → uRHi.

A colour is three floats, not one param

defineShaderEffect makes only float uniforms, so there is no colour param type. Pass a team colour as three floats, r, g and b, each from 0 to 1 (see the duotone below). If you pass a colour string, Starlight ignores it and uses the default.

GLSL (WebGL2)WGSL (WebGPU)Meaning
texture(uTexture, vTextureCoord)textureSample(uTexture, uSampler, uv)read the input pixels
vTextureCoorduvthe current pixel's UV
uInputSize.xy / .zwgfu.uInputSize.xy / .zw(w, h) in px / (1/w, 1/h), one pixel's size
u<Param>fx.u<Param>your float params
finalColor = …return vec4<f32>(…)write or return the result

Animate a param. Mark it animatable: true. Then it accepts a keyframe list, for example { amount: [0, 1, 0] }. The keyframes follow the layer's clock, or the effect's own clock:.

Declare reach if you read other pixels. Some shaders read pixels next to the one they write: a displacement, a cell snap, a blur. Add reach: how far it reads, in px, as a number or (params) => px.

Export renders very wide surfaces in strips. An effect without reach shows a seam at each strip edge.

In WGSL, the global filter values are on gfu: uInputSize, uInputPixel, uInputClamp, uOutputFrame, uGlobalFrame and uOutputTexture. Your params are on fx.

Example: the scanlines extension that comes with the demo project (demo-project/extensions/scanlines/index.js).

export default function register(api) {
  api.registerEffect('scanlines', api.defineShaderEffect({
    name: 'scanlines',
    params: [
      { name: 'gap',     default: 3,    animatable: true }, // → uGap
      { name: 'opacity', default: 0.35, animatable: true }, // → uOpacity
    ],
    glsl: `
      vec4 c = texture(uTexture, vTextureCoord);            // read input
      float row = vTextureCoord.y * uInputSize.y;           // height in px
      float line = mod(floor(row / max(uGap, 1.0)), 2.0);   // 0 or 1 per row
      finalColor = vec4(c.rgb * (1.0 - line * uOpacity), c.a);
    `,
    wgsl: `
      let c = textureSample(uTexture, uSampler, uv);
      let row = uv.y * gfu.uInputSize.y;
      let line = f32(i32(floor(row / max(fx.uGap, 1.0))) % 2);
      return vec4<f32>(c.rgb * (1.0 - line * fx.uOpacity), c.a);
    `,
  }));
}

Example effects

Each example is the inside of register(api), with the YAML that uses it.

Team-colour duotone grade

Maps the image's brightness from a shadow colour to a highlight colour. Use it to give all your footage the team look.

api.registerEffect('duotone', api.defineShaderEffect({
  name: 'duotone',
  params: [
    { name: 'rShadow', default: 0.04 }, { name: 'gShadow', default: 0.05 }, { name: 'bShadow', default: 0.12 },
    { name: 'rHi', default: 1.0 }, { name: 'gHi', default: 0.80 }, { name: 'bHi', default: 0.0 },
    { name: 'amount', default: 1.0, animatable: true },
  ],
  glsl: `
    vec4 base = texture(uTexture, vTextureCoord);
    float lum = dot(base.rgb, vec3(0.299, 0.587, 0.114));
    vec3 duo = mix(vec3(uRShadow,uGShadow,uBShadow), vec3(uRHi,uGHi,uBHi), lum);
    finalColor = vec4(mix(base.rgb, duo, uAmount), base.a);
  `,
  wgsl: `
    let base = textureSample(uTexture, uSampler, uv);
    let lum = dot(base.rgb, vec3<f32>(0.299, 0.587, 0.114));
    let duo = mix(vec3<f32>(fx.uRShadow,fx.uGShadow,fx.uBShadow), vec3<f32>(fx.uRHi,fx.uGHi,fx.uBHi), lum);
    return vec4<f32>(mix(base.rgb, duo, fx.uAmount), base.a);
  `,
}));
effects:
  - duotone: { rHi: 0.98, gHi: 0.74, bHi: 0.0, amount: 1 }   # gold highlights

LED-panel look

Snaps the picture to a grid of cells and darkens the gaps, so any content looks like it belongs on the LED wall. It reads each cell's centre, so it declares a reach.

api.registerEffect('led-grid', api.defineShaderEffect({
  name: 'led-grid',
  params: [{ name: 'size', default: 10, animatable: true }, { name: 'gap', default: 0.15 }],
  reach: (p) => Math.max(p.size, 2),   // reads up to a cell away
  glsl: `
    float cell = max(uSize, 2.0);
    vec2 px = uInputSize.zw; vec2 pos = vTextureCoord / px;
    vec2 center = (floor(pos / cell) + 0.5) * cell * px;
    vec4 c = texture(uTexture, center);
    vec2 f = fract(pos / cell);
    float d = min(min(f.x, 1.0 - f.x), min(f.y, 1.0 - f.y));
    finalColor = vec4(c.rgb * smoothstep(0.0, uGap, d), c.a);
  `,
  wgsl: `
    let cell = max(fx.uSize, 2.0);
    let px = gfu.uInputSize.zw; let pos = uv / px;
    let center = (floor(pos / cell) + vec2<f32>(0.5)) * cell * px;
    let c = textureSample(uTexture, uSampler, center);
    let f = fract(pos / cell);
    let d = min(min(f.x, 1.0 - f.x), min(f.y, 1.0 - f.y));
    return vec4<f32>(c.rgb * smoothstep(0.0, fx.uGap, d), c.a);
  `,
}));
effects:
  - led-grid: { size: 12, gap: 0.18 }

Vignette

Darkens the edges, with the correct shape for any surface size. It pulls the eye to the centre of the surface.

api.registerEffect('vignette', api.defineShaderEffect({
  name: 'vignette',
  params: [{ name: 'amount', default: 0.6, animatable: true }, { name: 'radius', default: 0.35 }, { name: 'softness', default: 0.35 }],
  glsl: `
    vec4 c = texture(uTexture, vTextureCoord);
    vec2 p = vTextureCoord - 0.5; p.x *= uInputSize.x / uInputSize.y;
    float v = 1.0 - smoothstep(uRadius, uRadius + uSoftness, length(p)) * uAmount;
    finalColor = vec4(c.rgb * v, c.a);
  `,
  wgsl: `
    let c = textureSample(uTexture, uSampler, uv);
    var p = uv - vec2<f32>(0.5); p.x = p.x * (gfu.uInputSize.x / gfu.uInputSize.y);
    let v = 1.0 - smoothstep(fx.uRadius, fx.uRadius + fx.uSoftness, length(p)) * fx.uAmount;
    return vec4<f32>(c.rgb * v, c.a);
  `,
}));

Wave displacement (animated)

A sideways sine wave, like a flag in the wind or hot air. Animate phase from 0 to 1 to make the wave travel. It reads amp px to the side, so that is its reach.

api.registerEffect('wave', api.defineShaderEffect({
  name: 'wave',
  params: [{ name: 'amp', default: 6 }, { name: 'freq', default: 40 }, { name: 'phase', default: 0, animatable: true }],
  reach: (p) => Math.abs(p.amp),
  glsl: `
    vec2 p = vTextureCoord;
    p.x += sin(p.y * uFreq + uPhase * 6.2831853) * uAmp * uInputSize.z;
    finalColor = texture(uTexture, p);
  `,
  wgsl: `
    var p = uv;
    p.x = p.x + sin(p.y * fx.uFreq + fx.uPhase * 6.2831853) * fx.uAmp * gfu.uInputSize.z;
    return textureSample(uTexture, uSampler, p);
  `,
}));
effects:
  - wave: { amp: 8, freq: 36, phase: [0, 1], clock: { period: 1200ms } }

Colour key to transparent

Makes pixels near one colour transparent. Use it to put a green-screen sponsor clip over the surface.

api.registerEffect('color-key', api.defineShaderEffect({
  name: 'color-key',
  params: [
    { name: 'rKey', default: 0.0 }, { name: 'gKey', default: 1.0 }, { name: 'bKey', default: 0.0 },
    { name: 'tol', default: 0.30, animatable: true }, { name: 'soft', default: 0.10 },
  ],
  glsl: `
    vec4 c = texture(uTexture, vTextureCoord);
    float a = smoothstep(uTol, uTol + uSoft, distance(c.rgb, vec3(uRKey,uGKey,uBKey)));
    finalColor = vec4(c.rgb, c.a * a);
  `,
  wgsl: `
    let c = textureSample(uTexture, uSampler, uv);
    let a = smoothstep(fx.uTol, fx.uTol + fx.uSoft, distance(c.rgb, vec3<f32>(fx.uRKey,fx.uGKey,fx.uBKey)));
    return vec4<f32>(c.rgb, c.a * a);
  `,
}));

Write a colour op

A colour op changes one colour at a time. It cannot see other pixels, the position, or the alpha (the transparency).

  1. Call registerEffect with a def that has a pointOp and no shader.
  2. Build the pointOp with api.definePointOp, as in the example below.
  3. Save the file. The op joins the layer's one colour LUT, in stack order with the built-in grades.
export default function register(api) {
  api.registerEffect('posterize', {
    schema: api.z.object({ levels: api.z.number().optional() }),
    defaults: { levels: 4 },
    animatableParams: ['levels'],
    separable: true,                     // each channel depends only on itself
    pointOp: api.definePointOp((p) => {
      const n = Math.max(2, p.levels) - 1;  // setup: once per bake
      return (rgb) => {                     // per colour, sRGB 0..1, in place
        for (let c = 0; c < 3; c++) rgb[c] = Math.round(rgb[c] * n) / n;
      };
    }),
  });
}
  • Keep it pure. The same colour and params must give the same result, because Starlight caches the LUT by params. Starlight limits the results to 0..1 for you.
  • Set separable: true only when each output channel depends on that same channel alone (levels, curves, invert). It makes the op faster. A wrong true gives wrong colours.
  • Need alpha or other pixels? Write a shader effect instead.
  • In the picker, an extension's colour op shows in the extensions block. Its card sits in the color group, with the built-in colour ops.

Example node type: a score bar

A new drawing built with api.pixi. It loads and draws, and it saves in the scene file as - node: score-bar (see above).

export default function register(api) {
  const { Container, Graphics } = api.pixi;
  api.registerNodeType('score-bar', {
    schema: api.z.object({ value: api.z.number(), width: api.z.number().optional(), fill: api.z.string().optional() }),
    // build(ctx, node) → a Pixi Container. ctx: { assets, surface, design, buildNode, buildChildren, resolveComp, … }
    build(ctx, node) {
      const w = typeof node.width === 'number' ? node.width : 600, h = 40;
      const v = Math.max(0, Math.min(1, node.value ?? 0));
      const c = new Container();
      c.addChild(new Graphics().roundRect(0,0,w,h,h/2).fill('#1b1b1f'));           // track
      c.addChild(new Graphics().roundRect(0,0,Math.max(h,w*v),h,h/2).fill(node.fill ?? '#ffcc00')); // fill
      return c;
    },
  });
}

What you could build

Ideas, marked by type. [Effect] and [Colour op] work today. [Node] works too: it saves with the node: keyword.

  • A team's own grade: the duotone set to your two colours, on every video. [Effect]
  • A house look in one op: posterize, a split tone, or a brand-colour remap. [Colour op]
  • Stadium LED look: led-grid with a light glow, so content looks as if it was made for the LED wall. [Effect]
  • Sponsor chroma-key belt: color-key on a green-screen loop, on a drifting clone belt. [Effect]
  • Retro broadcast package: halftone, scanlines and chroma-shift together, for a replay in an old TV style. [Effect]
  • Flag-wave transitions: the wave effect across a full-frame graphic. [Effect]
  • Live-score node, a branded lower-third maker, sport widgets (a down-and-distance chip, pitch-count dots, a shot-clock ring). [Node]

Make one: scaffold, edit, use

Make a new extension from a template, then test it on a surface.

  1. Scaffold (make a starting template). Ask Claude in the Claude panel (⌃` / Ctrl+`) to make an effect. Or call the MCP tool scaffold_extension { name, kind, description }, where kind is effect or node. You can also make the folder by hand.
  2. The name must be lower-kebab-case and start with a letter, for example led-scan. If index.js already exists, the scaffold refuses and asks you to edit it.
  3. The scaffold writes a working template with TODO marks. The effect template darkens by an amount param. The node template draws a square with size and fill.
  4. It also records the extension in extensions/manifest.json. A scaffolded extension is trusted until you quit the app.
  5. Edit index.js. Keep the GLSL and WGSL maths the same. Save the file, and it loads again.
  6. Check. Open the effect picker in Properties. Your effect is in its extensions block. get_project also lists it, with extension: true.
  7. Use it. Add it from the picker, or in a layer's effects: list.
  8. Look. Render a still of a surface that uses it (render_still). Change the shader and look again.
  • A load error shows as one red line at the bottom left of the canvas: extension <name>: <message>.
  • A syntax error reads failed to load: …. A file with no register function reads extension has no default export function register(api).
  • While an extension is not loaded, Claude cannot write a scene that uses its effect. The write is refused with unknown effect "…".

Trust a project's extensions

Starlight asks before it runs a project's extensions, because they can do anything the app can do.

  1. Read the line at the top of the window. It names the extensions: this project runs its own code: led-scan, ticker — extensions get full access to the app. trust them? After three names, it adds +N more.
  2. Click trust only if you would run this code on your computer.
  3. Or click not now. The extensions stay off for this session. Starlight says extensions not loaded — trust them later from the palette.
  4. To answer later, open the command palette (⌘/ / Ctrl+/) and choose trust project extensions…. The prompt line comes back. If nothing is waiting, Starlight says no extensions waiting to be trusted.
  • When a trusted extension's file has changed, the line says, for example, led-scan changed since you trusted it — run the new code?
  • An extension you have not trusted does not run. Layers that use its effects draw without them.
Extensions have full access (no sandbox)

An extension can do everything the app can do, like an After Effects script. Starlight remembers your trust in its settings, for each project folder and for the exact code. If a file changes, Starlight asks again the next time it loads. The same extension in another folder also asks again.

Extensions you trusted or scaffolded in this session load your edits without asking, until you quit the app. The demo project's scanlines never asks, as long as its file is unchanged.

When an extension misbehaves

Find the symptom, then follow the fix.

SymptomFix
Not in the effect picker or in get_project
  1. Look for the trust line at the top of the window, and click trust. (get_project lists it under extensionsAwaitingTrust.)
  2. If there is a red line on the canvas, read it.
  3. Check that the file has export default function register(api).
A red line says failed to loadThe file has a syntax error. Fix the line it names, and save.
Layers that use the effect look plainThe extension is not loaded: it is not trusted yet, or it failed. Check the trust line and the red line on the canvas.
It renders wrong, or nothingThe GLSL and WGSL do different maths. Make them the same. Check that uniform names follow u<Capitalized>.
A seam in exports of very wide surfacesThe shader reads other pixels but has no reach. Add one.
A colour param is ignoredParams are floats only. Pass a colour as three floats, r, g, b (0 to 1).
A param does not animateWrite it as a keyframe list, and mark it animatable: true.
A new node type does not work in YAMLThis is expected for now. See What you can register.

On this page