CuePool — Theatre Show Control

CuePool is a theatre sound, video, and lighting cue player — a QLab-style show-control app, ported to Rust from QPlayer and renamed CuePool to avoid confusion with the original project. You build a list of cues (sound, video, lighting, OSC, …), then fire them one after another with the GO button during a performance.

Under the hood: audio decode via symphonia with a custom DSP chain on cpal, video via FFmpeg with GPU YUV→RGB conversion, DMX over sACN or Art-Net, and OSC / MIDI show control.

Start with Getting Started to build the app and program your first show.

The main window

AreaWhat it is
TopMenu bar + transport (GO / Stop / Pause, standby readout, master meter)
LeftActive Cues — every playing cue with state, volume meter, and a progress bar (elapsed / total −remaining; yellow = paused)
CenterCue list — the show, in playback order. The standby cue (what GO will fire) carries a chevron in the left gutter and an outlined row; playing cues are green with a ▶ marker, paused cues amber, idle standby blue
RightInspector — full editor for the selected cue
BottomStatus bar — playing-cue count, mode, cue total, unsaved marker, nonzero master gain indicator, and the live Video / Audio indicators

Extra panels live in the Window menu: Log, Waveform, Video Output, Projection Mapping, and Lighting.

Edit mode vs Show mode

The app has two modes. Edit mode enables all editing; Show mode locks the cue list so a stray click can't rearrange your show mid-performance.

Projects

Projects are JSON .qproj files (the file format is compatible with the original QPlayer). While a project is dirty, an autosave thread writes a backup every 60 seconds, rotating through five slots (autoback_1.qproj … autoback_5.qproj in the per-user config directory), and a crash handler saves crash_recovery.qproj on the way down. File → Pack… copies all referenced media next to the project file for touring.

OSC receive/transmit ports and the network interface live in Project Settings (defaults: receive 9000, transmit 8000).

Chapters

Developer documentation

See Contributing for build requirements, checks, and a map of the codebase. The automation API and pixel feed have separate references.

Getting Started

Build & run

CuePool needs Rust and native audio/video development libraries. Follow the platform setup instructions, then run from the repository root:

cargo run --release --locked -p cuepool

Command-line options

cuepool [--show-mode] [--zero-copy | --no-zero-copy] [--project <path> | <path>]
cuepool --version

--version prints the version, source identity and compiled ASIO support, then exits without opening windows, loading settings or accessing audio devices. Use it on its own, including while another CuePool instance is running.

Use --project <path> or a single positional path to open a project at startup. When running through Cargo, put app options after --:

cargo run --release --locked -p cuepool -- --project MyShow.qproj

The legacy positional form, cuepool MyShow.qproj, remains supported. CuePool is single-instance: launching a second copy while one is running shows an error and exits with a nonzero status; it does not forward the project to the running instance.

--show-mode starts the app in Show mode with cue editing locked. The Show/Edit button still works normally; the flag only chooses the starting mode. Without it, the app starts in Edit mode.

--zero-copy opts into the Windows D3D12VA zero-copy video path; --no-zero-copy forces the stock readback path. The two options are mutually exclusive. When neither is supplied, the QPLAYER_ZEROCOPY fallback is used: the zero-copy path is enabled only when its value is exactly 1. Either command-line option takes precedence over that environment variable.

For separate process profiles and API control, see the automation reference.

Your first show

  1. New project — Cmd/Ctrl+N, then File → Project Settings… to set the show title, author, and audio output device.
  2. Add a sound cue — Cmd/Ctrl+T, a toolbar button above the cue list, or right-click → Add Sound Cue. Pick a file in the Inspector (File:).
  3. Shape it — still in the Inspector: volume (dB), pan, fade in/out seconds, and the fade curve. The Start / Duration fields trim the clip.
  4. GO — press Space. The cue appears in Active Cues on the left with a meter and progress bar. Esc stops everything.
  5. Build a sequence — set the next cue's trigger to WithLast (fires together with the previous cue) or AfterLast (fires when it finishes), optionally with a Delay. A single GO then plays the whole chain.
  6. Save — Cmd/Ctrl+S writes a .qproj file. File → Pack… copies all referenced media next to the project file for touring.

Editing the cue list (Edit mode)

  • Rename / renumber inline — the # and Name cells are text fields; click and type. Cue numbers commit when the field loses focus (Enter or click away; Esc cancels), names commit as you type. Renumbering follows references: group members, Stop/Volume/Goto cues targeting the old number, and the selection all move to the new number. Duplicate numbers are rejected.
  • Add cues — toolbar buttons above the list, or right-click → Add … Cue. New cues are numbered after the selected cue by decimal subdivision (after cue 1 comes 1.1, then 1.2, …).
  • Right-click menu — Move Up/Down, Duplicate, Delete, Add cue.
  • Reorder / group — drag the ≡ handle. Drop a cue onto a Group (or one of its members) to join the group — members draw indented under the group header. Drop on the strip below the list to ungroup / move to the end.
  • Delete — right-click → Delete, or select and press Delete/Backspace.

Keyboard shortcuts

KeyAction
SpaceGO (fire the standby cue)
EscStop all
↑ / ↓Move the standby cue up / down the list
Home / EndStandby the first / last cue
Cmd/Ctrl+Z / Shift+ZUndo / Redo
Cmd/Ctrl+N / O / SNew / Open / Save project
Cmd/Ctrl+TAdd sound cue
Cmd/Ctrl+DDuplicate selected cue
Cmd/Ctrl+↑ / ↓Move selected cue up / down
Delete / BackspaceDelete selected cue

While a text field has keyboard focus — renaming a cue, editing a Q number — the field keeps its keystrokes. Only New, Open, Save, Duplicate and Add sound cue stay live; the rest resume when the edit ends.

Individual cues can also have their own hotkey, MIDI, wall-clock, and timecode triggers.

Cue Reference

Properties every cue has

PropertyMeaning
# (QID)The cue number — a decimal, so 1.5 sorts between 1 and 2. Referenced by Stop/Volume/Goto cues and OSC commands.
Name / DescriptionFree text shown in the list and inspector.
ColourRow tint in the cue list.
TriggerGo (waits for the GO button), WithLast (fires together with the previous cue), AfterLast (fires when the previous cue finishes).
DelaySeconds to wait after being triggered before actually starting.
EnabledDisabled cues are skipped.
LoopOneShot, Looped (× Loop Count), LoopedInfinite, HoldLast (hold the final frame/state).
RetriggerableWhen off, firing the cue again while it is still playing is ignored — prevents stacked audio or flashing video from a double GO.
Remote NodeFire this cue on a named remote node instead of locally. Pick from the detected machines rather than typing — the Inspector flags a name nothing answers to.
TriggersOptional per-cue hotkey / MIDI / wall-clock / timecode triggers — see Show Control.

Cue types

Sound

Plays an audio file (anything symphonia decodes: WAV, FLAC, MP3, OGG, AAC, ALAC, …). Properties: file, start time and duration (clip trim), volume (dB), pan, fade in/out with a selectable curve, a per-cue EQ, and output routing.

Video

Plays a video file (anything FFmpeg decodes) onto the projection canvas, with the same audio properties as a Sound cue for its soundtrack.

Image / Text

Draw a still image or a text overlay on the canvas. Text cues have a font size, colour, and an optional font file (.ttf/.otf; leave unset for the built-in font — packed with the project like other media). Both cue types have a Fit mode that scales the content (for text, the rendered text block) onto the canvas: Stretch, Fit (letterbox), or Fill (center-crop).

Text renders on an overlay layer above whatever video or image is playing (supertitles over a running clip, for example). A new Text cue replaces the overlay; a Stop cue targeting the text (or Stop All) clears it.

Group

A container. Drag cues onto the group header to nest them; the group fires its members according to their trigger modes.

Stop

Stops another cue: target Q#, Immediate or LoopEnd (finish the current loop first), with an optional fade-out time and curve. A video cue's picture and its audio track fade out together. Targeting a Group stops every member, nested groups included, and a stop also cancels a target still waiting on its Delay. Stop All stops everything instead of one target — with a fade it brings the whole show down gently, while the transport's Stop button is always an instant cut.

Volume

Fades a playing Sound/Video cue to a target level: target Q#, target dB, fade time, fade curve.

Goto

Moves the playhead to the target Q#, so the next GO fires from there. Useful for skips and loops in the show structure.

OSC

Sends an OSC message when fired. The command format is /address,arg1,arg2,… — e.g. /mixer/scene,3. Arguments are parsed as ints, floats, or strings. See Show Control.

TimeCode

Defines a point or interval on the show clock for AfterLast followers, with a start time and duration. GO on a TimeCode cue also starts a stopped clock at zero; it does not seek the clock to the cue's start time.

Lighting

Crossfades patched DMX fixtures to a saved look. Fixtures not included in the cue's snapshot keep their current state (LTP tracking). Tick 🔴 Live in the inspector to see edits on the rig as you program. See Lighting.

DMX Show

Plays a recorded DMX stream (.dmxrec) to the lighting output, merged against Lighting-cue looks by sACN-style priority. See DMX Show cues.

PixelMap

Plays a video or still into the dedicated pixel-map texture that LED segments sample by default — LED content independent of the projector picture. Looping follows the cue's Loop mode; a OneShot end blanks to black.

Dummy

Does nothing. A placeholder / structural marker.

Fade curves

Wherever a fade has a Type, the options are Linear, S-Curve (default), Square, and Inverse Square.

Audio

CuePool decodes with symphonia (all formats enabled — WAV, FLAC, MP3, OGG/Vorbis, AAC, ALAC, …), resamples to the device rate, and mixes every playing cue through a per-cue DSP chain (fade → EQ → pan → routing) into a master bus with a master gain, metering, and an optional limiter. Output is via cpal.

The master gain is the room trim: Master Volume in Project Settings → Audio (double-click for 0 dB), or /qplayer/volume from a venue control system. Both edit the same show setting. It sits ahead of the limiter, ranges −96 dB (silence) to +12 dB, and is saved with the show. Loading another show loads its gain; rebuilding an audio device reapplies the current show's gain. The status bar indicates a nonzero master level and opens Project Settings when clicked. Each settled change is reported in Window → Log. Controllers can query and confirm the setting.

Project audio settings

File → Project Settings… → Audio:

SettingMeaning
Output driverAudio host. System (the platform default) is the only choice on macOS and Linux. Windows additionally offers WASAPI, Wave, DirectSound, and ASIO — ASIO uses CPAL's separate ASIO host when the build enables it.
Output deviceA device enumerated from the selected driver host. The exact name is saved in the project.
LatencyRequested output latency in ms (default 10).
Channel offsetShift all output channels — useful on interfaces where outputs 1-2 are not the mains.
Exclusive modeWindows-only output preference.
Master VolumeOverall programme gain, −96 to +12 dB; 0 dB is unity. Saved with the show.
LimiterMaster-bus brick-wall limiter: input gain, threshold, attack, release.

WASAPI, Wave, and DirectSound are retained as legacy show-file values and use CPAL's platform-default host, as older CuePool builds did — a show saved with one of them on Windows presents as System when opened on macOS or Linux. ASIO is the only alternate CPAL host selected by this setting.

Building with ASIO on Windows

ASIO is opt-in so normal builds on Windows, macOS, and Linux keep their existing dependencies:

$env:CPAL_ASIO_DIR = 'C:\SDKs\asiosdk'
$env:LIBCLANG_PATH = 'C:\Program Files\LLVM\bin'
cargo run --release -p cuepool --features asio

Install LLVM (including libclang) and the Steinberg ASIO SDK first. CPAL_ASIO_DIR must point to the extracted SDK root. The feature forwards to CPAL's asio feature and therefore only builds the SDK bindings on Windows. Enabling --features asio on another operating system deliberately adds no native backend; choosing ASIO there reports that ASIO is Windows-only.

Dante Virtual Soundcard should be running in ASIO mode at 48 kHz with at least 8 x 8 channels. CuePool supports Dante's native 16-, 24-, and 32-bit ASIO encodings, requests eight output channels, and keeps the existing per-cue pair/matrix routing. Older CuePool builds based on CPAL 0.15 require DVS's 32-bit encoding as a lossless compatibility workaround for 24-bit audio.

Output errors

CuePool never substitutes another host or device for a saved non-empty device name. If ASIO support was not compiled, the ASIO host is unavailable, the saved driver is missing, or the device cannot open its stream, the Project Settings window shows the configured driver/device, the reason, and any devices that were available from that host. Audio playback stays disabled until a valid output is selected; the project remains open and non-audio cues remain usable.

Per-cue level, pan & fades

Every Sound and Video cue has volume (dB), pan, and fade in/out times with a selectable curve. Stop and Volume cues perform fade-outs and level rides on already-playing cues.

Per-cue EQ

Each Sound/Video cue can enable a 4-band parametric EQ plus high-pass and low-pass filters, edited in the Inspector.

Routing

Routing in the Inspector has two levels:

  • Pair routing (default) — the cue's stereo signal goes to one output pair (Pair 0 = outs 1-2, 1 = outs 3-4, …) at a Send level.
  • Crosspoint matrix — add crosspoints to route any source channel to any output channel at a gain. This overrides the pair route and handles multichannel sources such as 5.1 files.

Metering & waveform

The transport bar shows the master meter and the status bar indicates master gain when it is away from 0 dB; each entry in Active Cues has its own meter. Window → Waveform opens a waveform view of the selected sound cue — handy when setting start/duration trims.

Video & Projection

Video, Image, and Text cues all render onto a shared canvas — a virtual surface (default 1920×1080) that one or more output windows display regions of. Video is decoded by FFmpeg on a worker thread with vsync-paced backpressure; YUV→RGB conversion happens on the GPU.

The Video Output window

Window → Video Output opens a single window showing the whole canvas — the simplest setup: drag it onto the projector and fullscreen it.

Projection mapping

Window → Projection Mapping is the multi-output editor. Set the canvas size, then add outputs — one per projector. Each output has:

PropertyMeaning
Source regionThe rectangle of the canvas this projector shows (x, y, w, h in canvas pixels).
Output sizeThe projector's native resolution.
Fullscreen monitorWhich monitor the output window fullscreens onto. Assignments are remembered by monitor identity (name + geometry), so they survive unplugs and OS re-ordering.
Edge blendPer-edge (left/right/top/bottom) feathering: enable, blend width in pixels, and gamma.

Overlap the source regions of adjacent projectors by the blend width and enable edge blending on the touching edges to get a seamless wide image. The 3×1 edge-blend preset sets up a 5400×1080 canvas across three 1920×1080 projectors with the overlaps pre-configured — a good starting point to study.

Content fit

Video/Image/Text cues have a Fit mode controlling how their content maps to the canvas:

  • Fit (default) — preserve aspect ratio, letterbox/pillarbox.
  • Fill — preserve aspect ratio, cover the whole canvas, center-crop the overflow.
  • Stretch — fill the canvas exactly, ignoring aspect ratio.

The canvas is also what lighting pixel-map segments sample by default, so LEDs can mirror the projector picture.

Video status indicator

The status bar shows the current clip's decode path. Green means GPU decoding is active with no reported fallback. Amber with a ⚠ means decoding has fallen back to the CPU or a slower GPU path. Hover over the indicator for the reason and source file; Help > Status provides more detail.

The path is named as the decoder reports it: hap gpu-native, d3d12va zero-copy (<adapter>), d3d11va readback, hardware (videotoolbox), or software. The indicator stays amber after a fallback even if decoding still uses the GPU, such as when zero-copy was lost.

Lighting & Pixel Mapping

CuePool sends DMX over sACN (E1.31) or Art-Net, built on the same rustjay-lighting crate as the rest of the engine. Everything lives in Window → Lighting and is saved in the project file.

DMX output

At the top of the Lighting panel: enable output, pick the protocol, and set an optional unicast destination IP (leave empty for sACN multicast / Art-Net broadcast). The refresh rate defaults to 44 fps.

Patching fixtures

Patch lists your rig: each fixture is a profile at a universe + 1-based DMX address (the channel footprint is shown next to it). Each fixture can also set its own unicast IP — useful when several Art-Net or sACN nodes each expect their universes on their own address; leave it empty to use the panel-level destination. Overlap warnings are checked per destination, so the same universe on different nodes doesn't collide. Built-in profiles:

ProfileChannels
RGB / GRB / BGR3-channel colour in the named order
RGBWColour + white
RGB + Dimmer / Dimmer + RGBColour with a dimmer channel after/before
DimmerSingle channel
Moving Head (16-bit)Pan/tilt (16-bit) + dimmer + colour + beam

+ New Profile builds a custom profile from channel roles (colour, dimmer, pan/tilt coarse+fine, zoom, strobe, gobo, static values for fixed channels, …). User profiles override a built-in with the same id.

Profiles

Profiles define a fixture's channel layout. In the profile editor, channel chips drag to reorder (the order is the DMX layout), right-click to delete, and hovering names the channel type. Import GDTF… loads a manufacturer .gdtf fixture file: pick a DMX mode and the channels map to CuePool roles automatically (dimmer, RGB+W/A/UV, 16-bit pan/tilt, zoom, strobe, gobo); anything unrecognized becomes a constant channel holding its GDTF default value, so footprints and mode bytes stay correct.

Export sheet… (next to the patch) saves a CSV patch sheet: one summary row per fixture with per-channel detail rows underneath, plus pixel-map segment spans (one row per universe crossed), sorted by universe/address — with a Notes column flagging any address overlaps.

Lighting cues

A Lighting cue stores a look — dimmer, colour, white, pan/tilt, and beam (zoom / strobe / gobo) values — for any subset of the patch, and crossfades the rig to it over Fade (s) with a selectable curve.

Fixtures not included in a cue continue their existing fades or hold their completed looks (LTP tracking). Fades from different cues can run together, each with its own fade time and curve. A new cue takes over only the fixtures it includes, starting from their current mid-fade looks.

Live programming

Tick 🔴 Live at the top of a Lighting cue's inspector to stream every look edit straight to the fixtures while you program — what you see on stage is what the cue will play. The toggle is session-only (not saved) and follows LTP: fixtures not included in the cue continue their existing fades or hold their completed looks.

DMX Show cues

A DMX Show cue plays a recorded DMX stream (a .dmxrec file) straight to the lighting output — raw universe data captured from a console or recorder, bypassing the fixture patch.

Recordings merge with Lighting-cue looks sACN-style: every source has a priority (0–255, default 100); on each channel, the highest-priority source with data there wins. A recording only owns the channels it actually touches; the look engine owns patched fixtures' channels (its priority is a project-level setting, default 100 — at equal priority the recording wins). Fade In/Out crossfade the recording's channels against whatever is underneath, so pan/tilt fade as movement, not a dip to zero.

Loop follows the cue's Loop mode: OneShot releases its channels at the end (with the tail fade), HoldLast holds the final frame until stopped, Looped/Looped ∞ wrap hard from last frame to first. A Stop cue targeting the DMX Show fades it out and releases its channels.

DMX Recorder

Window → DMX Recorder captures incoming sACN (:5568) and Art-Net (:6454) — unicast or broadcast — into a .dmxrec take: program on your console (or stageLX), record the wire, play it back as a DMX Show cue.

Pick or create a take file, hit ⏺ Record, perform the pass, ⏹ Stop & Keep. Recording over an existing take is a punch-in pass: each channel overwrites the old take only from the moment its incoming value first deviates, and stays live until the pass ends — channels you don't touch keep their old data, and after the pass end the old take resumes. Discard throws the pass away; Revert swaps back to the previous take (one level, kept as <take>.prev).

Monitor (default on) streams the merged result — old take playing plus your live punches — to the lighting output while you record, above playback and looks in the merge. The raw pass also streams to <take>.pass as it happens, so a crash loses seconds, not the take. ▶ Preview plays the take through the lighting output without needing a cue.

Take Editor

✏ Edit… in the recorder panel opens the take as per-channel curves — value over time, one channel at a time (universe/channel picker). On the canvas: drag a point to move it (time stays between its neighbours), double-click empty space to insert one, right-click a point to delete it, and drag on empty canvas to scrub the playhead ("Output scrub" sends the frame at the playhead to the rig). Zoom is logarithmic with a scroll slider for long takes.

Channel ops: Delete channel (hands its addresses back to other sources) and Shift (ms) (time-shift one channel, clamped at zero). Range ops: Trim take (keeps only the window — values held at the window start become the new baseline) and Flatten (holds the selected channel at a constant over the range; the old curve resumes after it).

Edits live in memory until Save, which keeps the previous version as .prev — same single-level revert as recording. One level of Undo covers the last operation. Bigger fixes are usually faster as a punch-in re-record than as mouse surgery.

Live input (OSC / MIDI)

/dmx/{universe}/{channel} <0–1> sets channels directly — from touchOSC or anything speaking OSC — and MIDI CC does the same on a configurable universe (CC# = channel). Live input is a bridge: it outputs even when not recording, at high merge priority (150) so a hand on a fader overrides playback; while a pass runs it is recorded like wire input. Values are held until Clear. Transport verbs (/recorder/record …) are listed in Show Control.

Close other sACN listeners (e.g. sACNView) while recording unicast — port sharing can route packets to the other app. Broadcast is unaffected.

Pixel-map segments

Segments stream video onto LED fixtures, vjarda-style. Each segment samples a rectangle of a source texture, downsamples it to a cols × rows grid, and writes one fixture-profile-worth of channels per cell starting at a universe/address, walking the grid in the chosen scan order (row/column order, serpentine, …).

PropertyMeaning
SourcePixelMap (default — a dedicated texture fed by PixelMap cues, LED content independent of the projector picture) or Canvas (mirror what the projectors show). Projects saved before the default changed keep their explicit Canvas — flip the dropdown if you want PixelMap cues to drive those segments.
RegionNormalized rectangle of the source to sample.
Gridcols × rows cells — one fixture per cell.
Profile / U / ChFixture profile, universe, and 1-based start address of the first cell.
ScanCell-to-address walking order.
Brightness / Gamma / WhiteColour pipeline: output gamma (default 2.2) maps the display-referred canvas to LED-linear intensity; the white mode controls RGBW derivation (use Off for plain RGB).
Derive A/UVOff by default: profiles with Amber/UV channels emit 0 on them. Tick to approximate Amber ((R+G)/2) and UV (0.8·B) from the sampled colour.

While a segment has content it streams continuously, and its channels override lighting-cue looks on the same addresses.

PixelMap cues

A PixelMap cue plays a video or still into the dedicated pixel-map texture. Point segments at the PixelMap source to drive LEDs with it; a OneShot cue blanks the texture to black when it ends.

Show Control

CuePool can be driven by OSC, MIDI, MIDI Show Control, wall-clock time, and its own show clock — and can drive other machines running CuePool as remote nodes.

OSC

Project Settings → OSC / Remote sets the network interface and ports (defaults: receive 9000, transmit 8000).

Incoming commands (the address namespace is kept as /qplayer for compatibility with the original QPlayer remote protocol and existing controller rigs):

AddressArgumentsAction
/qplayer/gooptional cue #GO — or fire a specific cue
/qplayer/stopoptional cue #Stop all — or one cue
/qplayer/pauseoptional cue #Pause all — or one cue
/qplayer/unpauseoptional cue #Resume all — or one cue
/qplayer/preloadcue #, timeDecode a cue and hold it Ready
/qplayer/selectcue #Move the selection
/qplayer/save—Save the project
/qplayer/volumedB (float), optional request ID (int32)Set master gain, −96 (silence) to +12 dB; saved with the show. With an ID, reply after applying the setting
/qplayer/volume/getrequest ID (int32)Read the current master-volume setting through the application command queue

The cue number can also ride in the address instead of the argument list — /qplayer/go/1.1 is the same command as /qplayer/go with "1.1" as its argument (likewise stop, pause, unpause, preload, select). Handy for controllers that template the address rather than the arguments.

/qplayer/up and /qplayer/down from the original QPlayer protocol are not supported — move the selection with /qplayer/select and a cue number.

An incoming message whose address matches nothing CuePool subscribes to is discarded and reported in Window → Log, once per address so a fader on a wrong address does not fill it. A controller that appears to do nothing is worth checking there before the network.

Outbound messages are sent by OSC cues — command format /address,arg1,arg2,….

Master-volume feedback

Send /qplayer/volume/get with one OSC int32 argument, for example 41. CuePool replies with /qplayer/volume/state 41 -12.0: the same int32 ID and the current gain as an OSC float32 in dB. The reply goes directly to the requesting IP address and source UDP port, from CuePool's receive socket; the configured OSC transmit host/port are not used. Send and listen on the same controller socket. Remote-control client mode swaps the configured receive/transmit ports; use the actual listening port shown in CuePool's log.

To confirm an adjustment, send /qplayer/volume -18.0 42 (type tags ,fi). Its reply is /qplayer/volume/state 42 -18.0 (,if). Setters and queries are processed in arrival order through the application's command queue, so the confirmation follows the applied change. Even an unchanged value receives a confirmation. The original single-argument setter remains valid and sends no reply. Queries do not change the gain or dirty the show.

Request IDs are opaque signed 32-bit integers, including zero and negative values. Missing, non-int32 or extra query arguments are ignored. An invalid optional setter ID or extra setter arguments cause the whole request to be ignored. Volume retains the existing numeric conversion and clamping: −96 dB or below is silence, +12 dB is the ceiling, and NaN becomes 0 dB. Always use finite float32 dB values in controllers, not percentages or strings.

Feedback reads the clamped ShowSettings.master_volume_db at processing time, so polling observes Project Settings edits, show loads and audio-device rebuilds. The value is saved with the show, not per machine; OSC edits mark the show dirty just like the GUI. Readback reports the master setting, not measured audio output or proof of a functioning audio device. The gain remains ahead of the limiter.

For a Nodel slider, poll once per second and give each outstanding request a fresh ID. Keep pending user input separate from confirmed state, reject late replies, throttle previews and always confirm the final adjustment. After repeated timeouts, mark state unavailable and refresh by reading on reconnect. Do not send another setter in response to feedback. A complete recipe, slider, integration contract and automated tests are in examples/nodel-volume.

OSC uses UDP here: IDs correlate replies but do not provide delivery guarantees, server-side deduplication or global ordering between different senders. Clients must not treat an old response as confirmation of a newer adjustment.

DMX recorder

The DMX Recorder listens on the same OSC port:

AddressArgumentsAction
/dmx/{universe}/{channel}float 0–1 (or int 0–255)Set a DMX channel (1-based) — live bridge, recorded while a pass runs
/recorder/record—Start a pass on the selected take; again = stop & keep
/recorder/stop—Stop the pass (keep) — or stop preview when idle
/recorder/play—Preview the selected take on the lighting output
/recorder/selecttake name/pathChoose the target take (.dmxrec appended if missing)
/recorder/discard—Throw the in-flight pass away
/recorder/revert—Swap the take with its previous version

Build a touchOSC layout of faders addressed /dmx/1/1, /dmx/1/2, … and you have a hand-held DMX console; values are held (latest wins) until Clear in the recorder panel. MIDI CC works the same way: enable MIDI CC → universe in the panel and CC# = channel. Status feedback (recording LEDs etc.) is not implemented yet.

A ready-made layout ships at assets/CuePool-DMX-Recorder.touchosc — 16 faders (universe 1, ch 1–16, two pages) plus REC / STOP / PLAY / DISCARD / REVERT. It's the classic .touchosc format: open it directly in TouchOSC Mk1, or File → Import in current TouchOSC. Point the connection's send host at the CuePool machine on the OSC RX port from Settings. Buttons fire on press only — the release value of 0 is ignored.

Show clock & timecode

The transport bar shows the show clock — the clock timecode triggers fire against — as HH:MM:SS.ff (green = running, yellow = paused, --:--:--.-- while stopped). The frame part is display-only; set its rate under Settings → Timecode (triggers are stored in seconds). Next to it, the next armed trigger is shown as next: Q12 @ 00:03:15.00.

GO starts a stopped clock at zero when it reaches a Sound, Video, Image, Text, PixelMap, DMX Show, or TimeCode cue. The clock includes the cue's Delay. Groups take their clock behavior from the members they trigger. Network, Lighting, Volume, Goto, Dummy, and targeted Stop cues leave the clock as they found it, so a control-only pre-show chain keeps it stopped. Use a TimeCode cue to start a show made only of control cues.

Stop All resets the clock. A RESET followed by playback in the same GO starts it again at zero; a terminal Stop All leaves it stopped. Firing a cue directly through a per-cue trigger does not start the clock.

Pause freezes the show clock and no timecode triggers fire while paused. While paused, ⏭ / ⏮ frame-step move the current video one frame forward or back with the clock following in lockstep — creep up on the exact moment, then either hit Capture on a cue's timecode trigger or just add a new cue: cues created while the clock is live are pre-filled with a timecode trigger at the current time. Triggers stepped past while paused fire on resume. (Stepping back briefly re-seeks the decoder, so the first back-step can take a moment on long-GOP files.)

Per-cue triggers

Every cue has an optional Triggers section in the Inspector, in addition to the GO chain:

  • Hotkey — a key that fires the cue directly.
  • MIDI — Note On / Note Off / CC on a channel, with a minimum velocity.
  • Wall clock — a time of day (12/24-hour), once or daily. Useful for house music, pre-show loops, and installations.
  • Timecode — a time on the show clock. Entered as HH:MM:SS.FF (matching the show clock display; a bare number is plain seconds). A capture button stamps the trigger with the current show time.

A triggered cue starts its WithLast cues with it and its AfterLast cues follow, the same chain GO would play; the standby cue does not move. Leave triggers off the WithLast cues themselves, or they can fire twice.

MIDI Show Control (MSC)

Project Settings → MSC enables MSC over the network (default ports 6004, receive device 0x70, transmit device 0x71, optional executor/page filters), so a lighting desk can GO CuePool — or vice versa.

Remote nodes

Project Settings → OSC / Remote also enables remote control: multiple CuePool machines discover each other over OSC by node name. Each machine takes its hostname as its node name, so two of them are already distinguishable before you configure anything. One node is the host; the others are clients. With sync show file on save enabled, saving on the host pushes the project to the clients. Set a cue's Remote Node field to make it fire on that named machine instead of locally — e.g. a video machine at front of house triggered from the sound desk.

The field takes free text, because a node that has not broadcast yet still has to be nameable, but the ⏷ picker beside it lists the machines actually detected. The Inspector says so when a cue would not play where you meant it to:

  • The named node has never been detected. The cue is still sent — a network that filters broadcast can hide a node that is really there — but nothing answers if the name is simply wrong, and the cue plays nowhere at all.
  • The node was detected but has gone quiet. Usually the machine is off or off the network. This clears within a few seconds of the node answering, so a warning that persists after loading a show file is a real one.
  • Remote control is off. The cue falls back to this machine.
  • The name is this machine's own node name. The cue plays here.

The last two are deliberate fallbacks rather than errors, but neither is silent: each raises an operator alert if it happens during a show, and is logged to Window → Log.

Timecode Follow

A video cue with Follow Timecode enabled plays under external timecode from a master — typically Pro Tools on another machine. CuePool chases either flavor, selected in File → Project Settings… → Timecode → Chase source:

  • MTC — MIDI Timecode, e.g. Pro Tools over RTP-MIDI. CuePool listens on all MIDI ports, so there is nothing to select.
  • LTC — Linear Timecode decoded from an audio input. Pick the driver, device, and channel carrying the LTC feed in the same settings section.

Either way the video plays silent (the soundtrack comes from the master), and CuePool's transport bar gains a timecode readout labeled MTC or LTC per the source (green while the master's transport is rolling, gray when stopped) with the source name and, while a follow cue is active, the current drift.

What a follow cue does

Enable Follow Timecode on a video cue in the Inspector and set its Timecode start — the timecode position that maps to the first frame of the video (default 01:00:00:00, the Pro Tools convention of starting the program at one hour). Locates before that offset clamp to frame 0.

  • GO loads the video and holds it on frame 0 until timecode plays.
  • Locate (master scrubbing / full-frame messages) snaps the video to the matching frame and freezes it there.
  • Play rolls the video in sync; stop freezes on the current frame — including past the end of the clip (the follow cue never loops or blanks on its own; the timecode master owns position).
  • While rolling, drift against the master is corrected in three zones: under 40 ms nothing happens (deadband — just presentation jitter); 40–250 ms the playback clock is slewed gently (max 5 % rate, no re-seek); over 250 ms the video hard-seeks to the target.
  • On timecode dropout the video snaps to the last received position and freezes there (the source counts as stopped after 500 ms without a decoded frame).

Stop All releases the follow cue; GO on a plain (non-follow) video cue takes the output back over.

The video must be 25 fps — CuePool expects 25 fps timecode and logs a warning if the source sends another rate.

Wiring it up (MTC)

Windows (CuePool machine)

Install Tobias Erichsen's rtpMIDI, create a session, enable it, and connect to the Mac's session. The session appears as an ordinary MIDI port — CuePool listens on all MIDI ports, so there is nothing to select.

macOS / Pro Tools (master machine)

  1. Audio MIDI Setup → MIDI Studio → Network: create/enable a network session and connect the CuePool machine.
  2. Pro Tools → Setup → Peripherals → Synchronization: set the MTC generator port to the network session, then enable MTC generation (Setup → External Sync / the Transport's sync mode).

Network

Use wired ethernet, not Wi-Fi. MTC itself is light, but Wi-Fi jitter lands directly in lip-sync — the 40 ms deadband can't absorb a congested wireless link.

Wiring it up (LTC)

Run the master's LTC output into any audio input the CuePool machine can see — an interface channel, or a software loopback. Select that driver, device, and channel under Project Settings… → Timecode with Chase source set to LTC. Keep the feed in a healthy line-level range: the decoder tolerates dropouts of a few frames, but a marginal signal shows up as locate-seeks rather than smooth chase.

Testing without Pro Tools

The workspace ships a tiny MTC sender:

cargo run --example mtc_send -p cuepool-protocols

On one Mac, create an IAC Driver bus in Audio MIDI Setup and pass its name as the argument. Then type commands:

  • play 01:00:00:00 — stream timecode from one hour (the follow cue starts rolling)
  • locate 01:05:00:00 — jump without playing (the video snaps and holds)
  • stop — freeze
  • quit