Writing output

Universe mutators validate input, order work through the source, update persistence, and schedule network sends. Reads never start the scheduler; mutations do.

Snap

Set channels immediately (zero-duration write):

await universe.setChannels({ 1: 255, 2: 128 });

Maps must be non-empty. Keys are integers 1..512; values are integers 0..255.

Shared fade

One duration for every listed channel:

await universe.fadeChannels({ 1: 0, 2: 0 }, { durationMs: 1_000 });

Per-channel durations

await universe.transition([
  { channel: 1, value: 0, durationMs: 500 },
  { channel: 10, value: 255, durationMs: 2_000 },
]);

Full frame

Write all 512 slots. Optional shared fade:

import { SLOT_COUNT } from "@helioslx/core";

const frame = new Uint8Array(SLOT_COUNT);
frame[0] = 255;
frame[1] = 128;
await universe.write(frame, { durationMs: 2_000 });

What await means

Awaiting a mutation means:

Validation passed
The write is ordered behind earlier mutations
The durable target is saved (if using a store)
Scheduling has the new target

It does not mean the fade finished or that every receiver has applied the levels.

Overlapping writes

Later writes win for channels they mention. Channels left out keep their current transitions and targets.

Fades interpolate from the channel's then-current value when a later write arrives mid-fade.

Rates

While an output is dirty or fading, frames go out at activeFps (default 44). Stable outputs send keepalives at idleFps (default 2). Configure these on the source or per universe where needed.

Clear and inspect

const snapshot = await universe.get(); // null if absent; does not auto-start
const removed = await universe.clear(); // blackout + delete store record

clear() returns false when there was nothing to remove.

Mutators accept an optional signal. Aborting cancels waiting in the source queue when possible. It does not retract packets already on the wire. A timed-out send stays serialized until the transport promise settles so sends never overlap for that output.