lib-maestro-dmx

Node.js library for accessing MaestroDMX via OSC and show-relevant HTTP reads.

This version of the library is compatible with MaestroDMX firmware version 1.5.1.

Runtime

This library targets Node.js 24 LTS. It is published as a pure ESM package.

API

The library uses one shared host for both protocols:

• OSC writes are sent to port 7672
• HTTP reads are loaded from the Maestro Web API under /api/v1/...

import { createClient } from "lib-maestro-dmx";

const client = createClient({
  host: "maestro.local"
});

const liveState = await client.live.read();
const showState = await client.showState.read();
const colorPalettes = await client.colorPalettes.read();

console.log(liveState.primary.patternId);
console.log(showState.type);
console.log(colorPalettes.palettes[0]?.name);

await client.control.group(1).setPattern("Solid Color");
await client.control.group(1).setBrightness(0.75);
await client.control.global.setBrightness(0.9);
await client.control.show.play();

client.live.read() performs one explicit HTTP request and returns the full live snapshot. client.live.getLastRead() returns the most recently fetched snapshot without making a new request. The same read() / getLastRead() pattern is available for the other HTTP reader APIs. client.control provides typed OSC helpers for the full parameter list published in the MaestroDMX OSC specification. Continuous group and global value setters are throttled per OSC address with a leading-and-trailing window. Global brightness uses 300 ms, group brightness uses 310 ms, and the other throttled continuous value setters use 250 ms. Trigger commands and trigger parameter setters are sent immediately without throttling.

HTTP Read API

The library intentionally focuses on read access that is useful during show automation and cue orchestration. It includes typed readers for:

• /api/v1/live via client.live
• /api/v1/patterns via client.patterns
• /api/v1/patterns/available via client.patternsAvailable
• /api/v1/palettes via client.paletteAssignments
• /api/v1/palettes/color via client.colorPalettes
• /api/v1/palettes/fx via client.fxPalettes
• /api/v1/brightness via client.brightness
• /api/v1/show via client.show
• /api/v1/show/state via client.showState
• /api/v1/fixture_groups via client.fixtureGroups
• /api/v1/system_info via client.systemInfo

These readers are aimed at runtime metadata, palette and pattern catalogs, active palette assignment, cue inspection, and current playback state. Configuration-heavy endpoints such as stages, fixtures, active stage details, and frame driver setup are intentionally not wrapped by this library at the moment.

Reader Semantics

client.systemInfo

• Reads software and device metadata such as product name, software version, UI version, API version, release type, and build information.
• Useful for diagnostics, compatibility checks, and logging which MaestroDMX unit or software generation your automation is currently talking to.

client.brightness

• Reads the global brightness master for the whole stage.
• In MaestroDMX terms this is the top-level brightness control of the Show page, applied on top of fixture-group brightness and cue/live settings.

client.live

• Reads the current Live Control state for the four fixture groups: PRIMARY, SECONDARY, TERTIARY, and QUATERNARY.
• This corresponds to the real-time control area of the Show page where each fixture group has its own pattern, color palette, FX palette, parameters, and trigger-toggle permissions.
• Use it when you need to know what is currently active on stage right now, regardless of whether that state originated from manual live control, OSC, or a running cue.

client.patterns

• Reads the full pattern catalog, including manifests, pattern ids, display names, descriptions, regular parameters, and advanced parameters.
• MaestroDMX distinguishes between Maestro Patterns and Core Patterns.
• Maestro patterns are autonomous, music-driven “vibes” such as Still, Ambient, Dance, or Party.
• Core patterns are more explicit looks such as Solid Color, Wash, Spectrum, Chase, or All Black, and can often be used with or without audio input.

client.patternsAvailable

• Reads the flattened list of currently available pattern ids.
• This is useful as a quick existence check before trying to select or validate a pattern id from external automation.

client.paletteAssignments

• Reads the currently active color palette id and FX snapshot id per fixture group.
• This is helpful because Live Control exposes both the currently selected palette and the current active palette state for a group.
• In practice this gives you the palette selection that MaestroDMX is actively using for each param group at the moment.

client.colorPalettes

• Reads the color palette catalog from MaestroDMX.
• MaestroDMX distinguishes between Grouped Palettes and Individual/Extended Palettes.
• Grouped palettes contain multiple individual palettes and are especially important for Maestro patterns, because Maestro patterns intelligently move through the palettes in a group based on the music.
• Individual/Extended palettes represent either a single color or a gradient; extended palettes may also include Amber, White, and UV channel values.

client.fxPalettes

• Reads the available FX palette / snapshot definitions exposed by the Web API.
• In MaestroDMX terminology, snapshots are saved fixture configurations that can later be recalled through FX palettes.
• This is primarily useful when cues or live groups refer to FX palette selections that you want to resolve into a friendlier name or id.

client.show

• Reads the currently selected show and all of its cues.
• A show in MaestroDMX behaves like a playlist of cues; each cue contains fixture-group pattern, palette, FX palette, parameter, transition, and timing information.
• Use this to inspect the authored show structure, cue order, durations, and the pattern/palette content embedded in each cue.

client.showState

• Reads the runtime playback state of the active show.
• This includes whether MaestroDMX currently reports Stopped, Playing, or another state, which cue index is active, and the elapsed play time.
• Use it when you need transport-state awareness for automation, monitoring, or UI overlays.

client.fixtureGroups

• Reads the logical fixture groups on the stage and the fixtures assigned to them.
• MaestroDMX fixture groups are the central runtime grouping concept for patterns, palettes, brightness, pixel mapping, and trigger participation.
• This reader is intentionally limited to group-level runtime topology and does not expose full stage-editing or fixture-patching workflows.

const patterns = await client.patterns.read();
const availablePatterns = await client.patternsAvailable.read();
const paletteAssignments = await client.paletteAssignments.read();
const colorPalettes = await client.colorPalettes.read();
const fxPalettes = await client.fxPalettes.read();
const brightness = await client.brightness.read();
const show = await client.show.read();
const showState = await client.showState.read();
const fixtureGroups = await client.fixtureGroups.read();
const systemInfo = await client.systemInfo.read();

console.log(patterns.manifests[0]?.patterns[0]?.name);
console.log(availablePatterns.ids);
console.log(paletteAssignments.states[0]?.activeColorPaletteId);
console.log(colorPalettes.palettes[0]?.children);
console.log(fxPalettes.palettes);
console.log(brightness.value);
console.log(show.cues[0]?.primary.patternId);
console.log(showState.currentCue);
console.log(fixtureGroups.groups[0]?.fixtureIds);
console.log(systemInfo.version);

Common convenience lookups:

await client.live.read();
await client.patterns.read();
await client.patternsAvailable.read();
await client.paletteAssignments.read();
await client.colorPalettes.read();
await client.show.read();
await client.showState.read();
await client.fixtureGroups.read();

console.log(client.live.getGroup(1)?.patternId);
console.log(client.live.getPaletteId("SECONDARY"));

console.log(client.patterns.findPatternById("Wash")?.name);
console.log(client.patterns.findParameter("Wash", "brightness")?.name);
console.log(client.patternsAvailable.has("Wash"));

console.log(client.paletteAssignments.getActiveColorPaletteId("PRIMARY"));
console.log(client.colorPalettes.findById("110")?.name);
console.log(client.colorPalettes.resolveChildren("701").map((palette) => palette.name));

console.log(client.show.getCueByIndex(0)?.name);
console.log(client.show.getCueSlot(0, "PRIMARY")?.patternId);
console.log(client.showState.isPlaying());
console.log(client.showState.getCurrentCueName());

console.log(client.fixtureGroups.getGroupByParamGroup("PRIMARY")?.fixtureIds);

Convenience Method Reference

client.live.getGroup(paramGroup)

• Returns the current live slot for a fixture group using either 1..4 or PRIMARY..QUATERNARY.
• Useful when external code thinks in group names instead of the raw primary / secondary object keys.

client.live.getPatternId(paramGroup)

• Returns only the active pattern id of the selected live group.
• Useful for quick comparisons or logging.

client.live.getPaletteId(paramGroup)

• Returns only the active palette id of the selected live group.

client.patterns.listPatterns()

• Flattens all manifests into one list of pattern definitions.
• Useful when you do not care which manifest a pattern came from.

client.patterns.findManifestById(id)

• Finds a pattern manifest by id.
• Useful if you want to keep the distinction between manifests such as Maestro and Core pattern collections.

client.patterns.findPatternById(id)

• Finds one pattern definition by pattern id.
• This is usually the most useful pattern lookup when resolving live state or cue content to human-readable metadata.

client.patterns.findParameter(patternId, param)

• Resolves a regular or advanced parameter definition for a given pattern.
• Useful when building dynamic controls or showing labels and descriptions for pattern parameters.

client.patternsAvailable.has(id)

• Returns whether a pattern id is currently listed as available by MaestroDMX.

client.paletteAssignments.getAssignment(paramGroup)

• Returns the full active palette assignment object for a fixture group.

client.paletteAssignments.getActiveColorPaletteId(paramGroup)

• Returns only the currently active color palette id for a fixture group.

client.paletteAssignments.getActiveFxSnapshotId(paramGroup)

• Returns only the currently active FX snapshot id for a fixture group.

client.colorPalettes.findById(paletteId)

• Finds one color palette by id.

client.colorPalettes.findByName(name)

• Finds one color palette by its display name.

client.colorPalettes.listGroups()

• Returns only grouped palettes.
• Useful for UIs or automation flows that should only offer palette groups to Maestro patterns.

client.colorPalettes.listLeafPalettes()

• Returns only non-group palettes.
• Useful for cases where you want a concrete single palette or gradient instead of a palette collection.

client.colorPalettes.resolveChildren(paletteId)

• Resolves a grouped palette into its child palettes.
• Useful because Maestro patterns work particularly well with grouped palettes, while external tools often need to inspect the actual individual palettes contained inside.

client.fxPalettes.findById(id)

• Resolves an FX palette / snapshot id to its stored metadata.

client.show.getCueByIndex(index)

• Returns a cue from the selected show by zero-based array index.
• This is library indexing, not the OSC cue transport index.

client.show.findCueByName(name)

• Finds a cue by its cue name.

client.show.getCueSlot(index, paramGroup)

• Returns the slot state of one cue for one fixture group.
• Useful for questions like “what pattern does cue 7 use on SECONDARY?” without manually branching over primary, secondary, and so on.

client.showState.isPlaying()

• Returns true if the current show-state string ends in _PLAYING.

client.showState.isStopped()

• Returns true if the current show-state string ends in _STOPPED.

client.showState.getCurrentCueName()

• Extracts the current cue name from the runtime show-state payload when available.

client.fixtureGroups.getGroupById(id)

• Finds a fixture group by the internal group id.

client.fixtureGroups.getGroupByParamGroup(paramGroup)

• Resolves the stage fixture group that belongs to PRIMARY, SECONDARY, TERTIARY, or QUATERNARY.

client.fixtureGroups.listFixtureIds(group)

• Returns the fixture ids of a group, either by param-group name/index or by group id.

There is also a high-level lookup facade that combines already loaded snapshots:

await client.live.read();
await client.patterns.read();
await client.patternsAvailable.read();
await client.paletteAssignments.read();
await client.colorPalettes.read();
await client.fxPalettes.read();
await client.show.read();
await client.showState.read();
await client.fixtureGroups.read();

const livePrimary = client.lookup.resolveLiveGroupContext("PRIMARY");
const currentCuePrimary = client.lookup.resolveCurrentCueGroupContext("PRIMARY");

console.log(livePrimary?.pattern?.name);
console.log(livePrimary?.activeColorPalette?.name);
console.log(currentCuePrimary?.cue?.name);
console.log(currentCuePrimary?.slot?.paletteId);

High-Level Lookup API

client.lookup.resolveLiveGroupContext(paramGroup)

• Combines the last loaded snapshots of live, patterns, patternsAvailable, paletteAssignments, colorPalettes, fxPalettes, and fixtureGroups.
• Returns one merged object for a fixture group with:
• current live slot
• resolved pattern definition
• resolved active color palette
• resolved active FX palette
• fixture-group metadata
• patternAvailable boolean
• Use this when you want to inspect “what is PRIMARY doing right now?” in one call.

client.lookup.resolveCueGroupContext(cueIndex, paramGroup)

• Combines show, patterns, patternsAvailable, colorPalettes, and fixtureGroups for one cue slot.
• Use this when you want a structured view of one cue group, for example to render show-overview tooling or validate cue content.

client.lookup.resolveCurrentCueGroupContext(paramGroup)

• Uses the loaded showState to find the active cue index and then resolves the cue/group context for that runtime position.
• Useful for dashboards, stream overlays, or controller feedback that needs to know what the currently playing cue is doing on a specific fixture group.

OSC Control API

The low-level OSC transport remains available via client.osc.send(...). For MaestroDMX-specific commands, prefer client.control.

await client.control.audio.setInput("USB Audio");
await client.control.audio.nextInput();

await client.control.live.pause();
await client.control.live.resume();
await client.control.live.stop();

await client.control.group(1).setPattern("Solid Color");
await client.control.group(1).setPatternIndex(3);
await client.control.group(1).setPalette(12);
await client.control.group(1).setPaletteIndex(2);
await client.control.group(1).setFxPaletteIndex(1);
await client.control.group(1).setBrightness(0.8);
await client.control.group(1).setExcitement(0.5);
await client.control.group(1).setBackground(0.2);
await client.control.group(1).setMotionRange(0.6);
await client.control.group(1).setMotionSpeed(0.7);
await client.control.group(1).setSpeed(0.4);
await client.control.group(1).setEnergy(0.9);
await client.control.group(1).setVariance(0.3);
await client.control.group(1).setDecay(0.1);
await client.control.group(1).setAttack(0.8);
await client.control.group(1).setShape(4);

await client.control.show.loadByName("Main Show");
await client.control.show.loadByIndex(0);
await client.control.show.loadCueByIndex(1);
await client.control.show.nextCue();
await client.control.show.previousCue();
await client.control.show.next();
await client.control.show.previous();
await client.control.show.playPause();
await client.control.show.play();
await client.control.show.stop();

await client.control.triggers.setStrobe(true);
await client.control.triggers.toggleStrobe();
await client.control.triggers.setStrobeBrightness(1);
await client.control.triggers.setStrobeRate(0.7);
await client.control.triggers.setBlinder(true);
await client.control.triggers.toggleBlinder();
await client.control.triggers.setBlinderBrightness(0.9);
await client.control.triggers.setBlackout(true);
await client.control.triggers.toggleBlackout();
await client.control.triggers.setFog(true);
await client.control.triggers.toggleFog();
await client.control.triggers.setFogInterval(0.5);
await client.control.triggers.setFogDuration(0.2);
await client.control.triggers.setFogVolume(0.8);
await client.control.triggers.setFogSpeed(0.4);
await client.control.triggers.setEffect(true);
await client.control.triggers.toggleEffect();

OSC Method Reference

client.control.global.setBrightness(value)

• Sets the global stage brightness.
• MaestroDMX describes this as the global brightness of the lights on the Show page.
• This value multiplies with fixture-group brightness inside live state or cues, so it behaves like a stage-wide master dimmer rather than replacing per-group brightness.

client.control.audio.setInput(name)

• Selects the audio input by its configured input name.
• Useful when your automation needs to switch between built-in and USB audio devices by name.

client.control.audio.nextInput()

• Advances to the next configured audio input.
• Best suited for hardware-button or simple controller workflows where cycling inputs is easier than sending a named target.

client.control.live.pause()

• Pauses the current live show state.
• Use this when running in live mode and you want the current generated state to stop advancing temporarily.

client.control.live.resume()

• Resumes a previously paused live state.

client.control.live.stop()

• Stops the current live show.
• This is a live-mode transport action, not a show-playlist stop.

client.control.group(group).setPattern(name)

• Selects a pattern for a fixture group by pattern name.
• In MaestroDMX, patterns are the core lighting behaviors. Maestro patterns act like autonomous music-driven vibes, while Core patterns are more explicit looks.

client.control.group(group).setPatternIndex(index)

• Selects a pattern by its order in the current MaestroDMX list.
• Useful for controller surfaces with encoders, faders, or indexed selection rather than text labels.

client.control.group(group).setPalette(id)

• Selects a color palette by palette id.
• This is usually the better choice when your automation already works with palette ids returned by client.colorPalettes.

client.control.group(group).setPaletteIndex(index)

• Selects a palette by its order in the palette list.
• Mainly useful for generic controller UIs where you do not want to hard-code palette ids.

client.control.group(group).setFxPaletteIndex(index)

• Selects an FX palette by its order in the FX palette list.
• In MaestroDMX, FX palettes are used to recall saved snapshots and effect-related stage states.

client.control.group(group).setBrightness(value)

• Sets fixture-group brightness for the currently active live pattern.
• This is the per-group brightness described in Maestro pattern parameters and combines with global brightness.

client.control.group(group).setExcitement(value)

• Sets the Maestro pattern excitement parameter.
• MaestroDMX describes Excitement as controlling how fast, flashy, and sudden the autonomous effect feels; lower values are smoother and calmer.

client.control.group(group).setBackground(value)

• Sets the Maestro pattern background parameter.
• Higher background values keep more light present between accents; lower values increase contrast and make flashes feel more dramatic.

client.control.group(group).setMotionRange(value)

• Sets moving-head motion range for the group.
• MaestroDMX describes this as the amount of PAN/TILT movement, where 0 keeps movers near their configured offset position and higher values use more of the configured width.

client.control.group(group).setMotionSpeed(value)

• Sets moving-head motion speed for the group.
• This specifically affects PAN/TILT-style motion on fixtures with mover attributes.

client.control.group(group).setSpeed(value)

• Sets the pattern speed parameter.
• For many core patterns this directly controls how fast the effect evolves; on Maestro patterns it acts more like an advanced fine-tuning control.

client.control.group(group).setEnergy(value)

• Sets the pattern energy parameter.
• In MaestroDMX documentation this often influences how much of a palette is used and, depending on the pattern, overall brightness and color intensity.

client.control.group(group).setVariance(value)

• Sets the pattern variance parameter.
• MaestroDMX describes Variance as conceptually similar to an inverse background control for core patterns.

client.control.group(group).setDecay(value)

• Sets the pattern decay parameter.
• This usually controls how long pulses or effects fade out, or how wide/smeared an effect feels, depending on the pattern.

client.control.group(group).setAttack(value)

• Sets the pattern attack parameter.
• This usually controls how quickly an effect ramps in or how sharply pulses begin.

client.control.group(group).setShape(value)

• Sets the shape index used by supported patterns.
• According to the OSC spec this is especially relevant for core patterns and works best in 2D mappings.

client.control.show.loadByName(name)

• Loads a show by its stored name.
• In MaestroDMX a show is a playlist of cues including pattern, palette, FX palette, timing, and transition data.

client.control.show.loadByIndex(index)

• Loads a show by its order in the show list.

client.control.show.next()

• Advances to the next show in the show list.

client.control.show.previous()

• Goes to the previous show in the show list.

client.control.show.loadCueByIndex(index)

• Jumps to a specific cue number in the loaded show.
• This uses the OSC cue numbering expected by MaestroDMX, which starts at 1.

client.control.show.nextCue()

• Advances to the next cue in the currently loaded show.

client.control.show.previousCue()

• Goes back to the previous cue in the currently loaded show.

client.control.show.playPause()

• Toggles between playing and paused show playback.

client.control.show.play()

• Starts show playback from the loaded/current cue context.

client.control.show.stop()

• Stops show playback.

client.control.triggers.setStrobe(enabled)

• Engages or disengages the strobe trigger.
• Trigger buttons only work while MaestroDMX is actually playing, either in Live mode or from show cues.

client.control.triggers.toggleStrobe()

• Toggles the strobe trigger state.

client.control.triggers.setStrobeBrightness(value)

• Sets strobe brightness.

client.control.triggers.setStrobeRate(value)

• Sets strobe flash rate.

client.control.triggers.setBlinder(enabled)

• Engages or disengages the blinder trigger.
• MaestroDMX describes this as driving LED fixtures to full white or the configured white/blinder behavior of supported fixtures.

client.control.triggers.toggleBlinder()

• Toggles the blinder trigger state.

client.control.triggers.setBlinderBrightness(value)

• Sets blinder brightness.

client.control.triggers.setBlackout(enabled)

• Engages or disengages the blackout trigger so lights go dark.

client.control.triggers.toggleBlackout()

• Toggles the blackout trigger state.

client.control.triggers.setFog(enabled)

• Engages or disengages the fog trigger.
• The exact fixture reaction depends on whether stage fixtures expose FOG ON/OFF and related fog attributes.

client.control.triggers.toggleFog()

• Toggles the fog trigger state.

client.control.triggers.setFogInterval(value)

• Sets the fog interval parameter used for timer-style fog bursts.

client.control.triggers.setFogDuration(value)

• Sets the fog burst duration used for timer-style fog bursts.

client.control.triggers.setFogVolume(value)

• Sets fog volume for fixtures or machines that expose a Fog Volume attribute.

client.control.triggers.setFogSpeed(value)

• Sets fog speed for fixtures or machines that expose a Fog Speed attribute.

client.control.triggers.setEffect(enabled)

• Engages or disengages the generic EFFECT trigger.
• MaestroDMX positions this as a catch-all trigger for effect channels such as flame or custom effect hardware.

client.control.triggers.toggleEffect()

• Toggles the EFFECT trigger state.

Method Notes

• All continuous float setters in the control API use the normalized MaestroDMX OSC range 0.0 .. 1.0.
• client.control.group(group) accepts only fixture groups 1..4.
• client.control.show.loadCueByIndex(index) requires index >= 1 because MaestroDMX cue transport numbering is one-based.
• Brightness setters are throttled more conservatively than other continuous parameters to reduce chatter while still tracking manual slider movement well.

MaestroDMX Background

The descriptions above are aligned with the MaestroDMX knowledge base:

• MaestroDMX uses Fixture Groups as the runtime grouping for patterns, palettes, parameters, mapping, and trigger participation.
• Live Control is the real-time editing surface where each fixture group can have its own pattern, palettes, parameters, and trigger toggles.
• Show Control is a playlist-like sequence of cues with names, durations, transitions, and per-group content.
• Color Palettes are either grouped palettes or individual/extended palettes, and Maestro patterns are designed to move intelligently through grouped palettes based on the music.
• Trigger Buttons cover BLACKOUT, BLINDER, STROBE, FOG, and EFFECT and only work while MaestroDMX is actively playing.

Entwicklung

npm install
npm test

Live Test

The normal npm test run stays local and does not require a MaestroDMX device.

Run the opt-in live integration test explicitly:

npm run live-test

It talks to maestro.local and runs a fixed verification sequence on group 1:

• set brightness to 0.37
• set excitement to 0.63
• set pattern to Solid Color
• set pattern to Ambient
• set palette id to 223
• set palette index to 1 and verify that the reported paletteId is still 223

The script polls /api/v1/live until each change is visible again. It is intentionally opt-in because it mutates real MaestroDMX state.

There is also an opt-in latency experiment for brightness ramps:

npm run live-test:brightness-latency

The script sends a 1 second brightness ramp from 0.0 to 1.0 twice:

• once as raw OSC /live/1/brightness messages without library throttling
• once as HTTP PUT /api/v1/live updates with a full params object

Both runs poll /api/v1/live and report when each target brightness becomes visible again. This is meant for comparing transport behavior on a real MaestroDMX device.

Sandbox CLI

For ad hoc experiments there is also a small sandbox CLI:

npm run sandbox -- help

Examples:

npm run sandbox -- live:get
npm run sandbox -- live:watch 100
npm run sandbox -- osc:send /live/1/brightness f:0.5
npm run sandbox -- osc:brightness 1 0.5
npm run sandbox -- http:put-live '{"params":{"brightness":0.5}}'
npm run sandbox -- http:set-brightness 0.5

Notification WebSocket Test

For the WebSocket notification stream, there is a separate opt-in console test:

npm run live-test:notifications

It connects to ws://maestro.local/notifications, expects each frame to contain Base64-encoded GZIP data, decompresses it, and prints the decoded payload to the console. It connects to ws://maestro.local/notifications, decodes the Base64 payload, and prints the detected Protobuf structure to the console. The example payloads currently look like Protobuf envelopes with a type.googleapis.com/... type URL and a nested binary payload.

You can also pass a custom URL directly:

tsx test/notifications-live-test.ts ws://maestro.local/notifications