hypercolor

TypeScript SDK for authoring Hypercolor RGB lighting effects.

One declarative function call turns your idea into a shippable artifact. The SDK handles the render loop, control UI generation, audio pipeline, palette sampling, and HTML bundling so you stay focused on the pixels.

Quick start

Scaffold a fresh workspace with the companion create-hypercolor package:

bun create hypercolor my-effects --template canvas
cd my-effects
bun run build

That gives you an effect to edit and the full build/validate/install loop.

Write an effect:

import { audio, canvas, num } from "hypercolor";

export default canvas(
  "Pulse",
  {
    palette: ["SilkCircuit", "Aurora", "Synthwave"],
    speed: num("Speed", [1, 10], 5),
  },
  (ctx, time, controls) => {
    const { width, height } = ctx.canvas;
    const pal = controls.palette as (t: number, alpha?: number) => string;
    const a = audio();

    ctx.fillStyle = "rgba(4, 2, 14, 0.22)";
    ctx.fillRect(0, 0, width, height);

    const radius = Math.min(width, height) * (0.2 + a.beatPulse * 0.3);
    ctx.fillStyle = pal(0.7, 0.6 + a.bass * 0.4);
    ctx.beginPath();
    ctx.arc(width * 0.5, height * 0.5, radius, 0, Math.PI * 2);
    ctx.fill();
  },
  { audio: true },
);

Build, validate, and install:

bun run build
bun run validate
bun run ship:daemon

Three authoring paths

• TypeScript canvas effects via canvas(): declarative draw functions with full audio and palette access.
• GLSL shader effects via effect(): fragment shaders with auto-mapped uniforms, including all audio bands.
• Raw LightScript HTML: standalone HTML files with meta-tag metadata, for porting and one-offs.

Authoring CLI

Inside any scaffolded workspace, the hypercolor CLI drives the full loop:

bunx hypercolor build --all    # compile every effect into dist/
bunx hypercolor validate dist/*.html
bunx hypercolor install dist/my-effect.html           # local filesystem copy
bunx hypercolor install dist/my-effect.html --daemon  # upload via daemon API
bunx hypercolor add ember --template canvas           # scaffold another effect

Scaffolded workspaces expose the same flow through bun run build, bun run validate, bun run ship, and bun run ship:daemon.

Documentation

Full docs live at the Hypercolor documentation site. Highlights:

• Effects overview: pick your authoring path
• Setup: Bun, scaffolding, SDK spec recipes
• Dev workflow: studio, build, validate, install
• TypeScript effects
• GLSL effects
• Raw HTML effects
• Controls
• Audio
• Palettes
• Color science for RGB LEDs

Prerequisites

• Bun 1.2 or newer
• Node 24 or newer if invoking the scaffolder's create-hypercolor-effect bin from a Node shell

Status

Early release (0.1.x): the API tracks the Hypercolor engine and may change between minor versions. Install straight from npm:

bun add -d hypercolor

To develop against a local Hypercolor engine checkout instead, point the dependency at it with a file: spec:

{
  "devDependencies": {
    "hypercolor": "file:../hypercolor/sdk/packages/core"
  }
}

The scaffolder's --sdk-spec flag and the HYPERCOLOR_SDK_PACKAGE_SPEC environment variable both accept this form.

Display faces

The SDK also builds full-screen faces for LCD displays (pump screens, the Push 2 strip) via face() — DOM + canvas pages with display-shape variants, typed data sources (sensors, audio, media, net, lighting), and the shared cinematic atmosphere kit. The authoring guide lives at docs/content/effects/display-faces.md; just face-dev <name> runs the build-install-preview loop against both simulator form factors.

License

Apache-2.0