XOSC
← All docs
Ideas

DMX milestone — plan index

> Status: plan only. No code is written for any of this yet. This folder is a self-contained brief: a fresh agent can read it from cold and produce v0.6.

Why

XOSC is feature-complete for v0.5 except DMX. Closing that turns it from "Resolume + USB inputs" into "full lighting + Resolume + USB inputs in one node graph" — the actual unique competitive position the user wants.

Reference implementation: saintpetejackboy/TagTable. TagTable is an Electron RFID kiosk; its src/main/dmx.js (820 lines) and src/renderer/app.js lighting-template engine are production-tested for ~6 months across 5 hardware backends (USB serial in 3 modes, Art-Net, sACN/E1.31). We borrow shamelessly. What TagTable does not have — multi-universe, fixture profiles, additive/max mixing, beat-synced clocks — we design ourselves.

End goal (v0.6.0)

> A USB key press fires a Resolume clip + a saved lighting cue. A Resolume parameter feeds a DMX channel. All in the same graph.

Two new node kinds plus a new top-level Sequences panel. Existing graph machinery (router, transforms, dispatch modes, throttle, cycle detection, monitor) covers them without rewrite.

Parallel-track split

The work cleanly halves into two independent tracks. Track A finishes first as v0.6.0-alpha (graph-only DMX, shippable). Track B follows as v0.6.0 (sequences). They share one contract — the universe frame buffer write API — and otherwise touch disjoint files.

| Track | Owner | Scope | Reads |
|---|---|---|---|
| A — Hardware + Graph | one agent | DMX engine in main, 5 hardware backends, frame buffer per universe, dmx-out + dmx-in node kinds, fixture-profile library, inspector UI | 01-hardware-backends.md, 02-fixtures.md, 03-graph-integration.md, 08-logging-and-diag.md, 09-themes-and-ui.md, HANDOFF-A-hardware.md |
| B — Sequences + Pads | other agent | Cue-list templates, layer engine with priority + mix modes, Sequences pad surface, master clock + tap-tempo, mixer that feeds the universe buffer | 04-sequence-engine.md, 05-pad-launcher.md, 06-mixer.md, 07-clock-and-tempo.md, 08-logging-and-diag.md, 09-themes-and-ui.md, HANDOFF-B-sequences.md |

The contract between tracks

Track A owns the universe frame buffer. Track B writes to it via a single API:

// in src/features/dmx/universeBus.ts (Track A creates this)
export const universeBus = {
  // Stage a write to a universe slot. Multiple writers compose via the
  // mixer (Track B implements the mixer; Track A ships a placeholder
  // "last-write-wins" implementation so graph-only DMX works from day 1).
  write(universeId: string, channel: number, value: number, source: WriteSource): void,
  writeMany(universeId: string, writes: Array<[channel: number, value: number]>, source: WriteSource): void,
  // Track B reads composed frames; Track A reads them inside the main-process tick.
  snapshot(universeId: string): Uint8Array,  // 512 bytes
};

interface WriteSource {
  kind: "graph" | "pad" | "art-net-in";  // who wrote it; mixer uses this for slot rules
  nodeId?: string;                         // graph-node id or pad layer id
  priority?: number;                       // optional, used by Track B's mixer
}

Both tracks write to this bus. Track A's dmx-out node calls write. Track B's pad layers call writeMany. The mixer's first version is dumb (last-write-wins); Track B replaces it.

How to use this folder

  • If you're picking up Track A: read HANDOFF-A-hardware.md first. It points you at the four design docs you need plus the cross-cutting docs on logging and theming.
  • If you're picking up Track B: read HANDOFF-B-sequences.md first. Same idea.
  • If you're alone and doing both: read in numerical order (01- through 10-) then both handoffs.

Non-goals (the handoffs reiterate these)

  • No audio-reactive BPM detection. Tap-tempo and external clock sources only.
  • No DMX-over-MIDI clock with sub-millisecond phase lock. Node.js can't deliver that.
  • No fixture-profile editor in v0.6 — eight built-ins ship; users edit JSON for now.
  • No Companion / Stream Deck integration. Wire those in via OSC.
  • No cloud sync of templates. Local JSON files only.

Order of milestones

1. v0.6.0-alpha — Track A done. dmx-out + dmx-in work end-to-end with one of the 5 hardware backends. Direct graph wiring; no pads. Ship this.
2. v0.6.0-beta — Track A all 5 backends + fixture library. Still no pads.
3. v0.6.0 — Track B done. Pad launcher, layered priority, mix modes, master clock.
4. v0.6.1 — bug fixes from real DMX hardware testing the user does on Windows.

10-rollout-plan.md has the full phasing.