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
| Area | What it is |
|---|---|
| Top | Menu bar + transport (GO / Stop / Pause, standby readout, master meter) |
| Left | Active Cues — every playing cue with state, volume meter, and a progress bar (elapsed / total −remaining; yellow = paused) |
| Center | Cue 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 |
| Right | Inspector — full editor for the selected cue |
| Bottom | Status 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
- Getting Started — build, run, and program your first show
- Cue Reference — every cue type and its properties
- Audio — devices, routing, EQ, fades, and the limiter
- Video & Projection — the canvas, output windows, and edge blending
- Lighting & Pixel Mapping — DMX patch, lighting cues, and LED segments
- Show Control — OSC, MIDI/MSC, hotkeys, timecode, and remote nodes
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
- New project —
Cmd/Ctrl+N, then File → Project Settings… to set the show title, author, and audio output device. - 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:). - Shape it — still in the Inspector: volume (dB), pan, fade in/out seconds, and the fade curve. The Start / Duration fields trim the clip.
- GO — press
Space. The cue appears in Active Cues on the left with a meter and progress bar.Escstops everything. - 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.
- Save —
Cmd/Ctrl+Swrites a.qprojfile. File → Pack… copies all referenced media next to the project file for touring.
Editing the cue list (Edit mode)
- Rename / renumber inline — the
#andNamecells 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
| Key | Action |
|---|---|
| Space | GO (fire the standby cue) |
| Esc | Stop all |
| ↑ / ↓ | Move the standby cue up / down the list |
| Home / End | Standby the first / last cue |
| Cmd/Ctrl+Z / Shift+Z | Undo / Redo |
| Cmd/Ctrl+N / O / S | New / Open / Save project |
| Cmd/Ctrl+T | Add sound cue |
| Cmd/Ctrl+D | Duplicate selected cue |
| Cmd/Ctrl+↑ / ↓ | Move selected cue up / down |
| Delete / Backspace | Delete 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
| Property | Meaning |
|---|---|
# (QID) | The cue number — a decimal, so 1.5 sorts between 1 and 2. Referenced by Stop/Volume/Goto cues and OSC commands. |
| Name / Description | Free text shown in the list and inspector. |
| Colour | Row tint in the cue list. |
| Trigger | Go (waits for the GO button), WithLast (fires together with the previous cue), AfterLast (fires when the previous cue finishes). |
| Delay | Seconds to wait after being triggered before actually starting. |
| Enabled | Disabled cues are skipped. |
| Loop | OneShot, Looped (× Loop Count), LoopedInfinite, HoldLast (hold the final frame/state). |
| Retriggerable | When off, firing the cue again while it is still playing is ignored — prevents stacked audio or flashing video from a double GO. |
| Remote Node | Fire 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. |
| Triggers | Optional 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:
| Setting | Meaning |
|---|---|
| Output driver | Audio 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 device | A device enumerated from the selected driver host. The exact name is saved in the project. |
| Latency | Requested output latency in ms (default 10). |
| Channel offset | Shift all output channels — useful on interfaces where outputs 1-2 are not the mains. |
| Exclusive mode | Windows-only output preference. |
| Master Volume | Overall programme gain, −96 to +12 dB; 0 dB is unity. Saved with the show. |
| Limiter | Master-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:
| Property | Meaning |
|---|---|
| Source region | The rectangle of the canvas this projector shows (x, y, w, h in canvas pixels). |
| Output size | The projector's native resolution. |
| Fullscreen monitor | Which monitor the output window fullscreens onto. Assignments are remembered by monitor identity (name + geometry), so they survive unplugs and OS re-ordering. |
| Edge blend | Per-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:
| Profile | Channels |
|---|---|
| RGB / GRB / BGR | 3-channel colour in the named order |
| RGBW | Colour + white |
| RGB + Dimmer / Dimmer + RGB | Colour with a dimmer channel after/before |
| Dimmer | Single 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, …).
| Property | Meaning |
|---|---|
| Source | PixelMap (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. |
| Region | Normalized rectangle of the source to sample. |
| Grid | cols × rows cells — one fixture per cell. |
| Profile / U / Ch | Fixture profile, universe, and 1-based start address of the first cell. |
| Scan | Cell-to-address walking order. |
| Brightness / Gamma / White | Colour 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/UV | Off 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):
| Address | Arguments | Action |
|---|---|---|
/qplayer/go | optional cue # | GO — or fire a specific cue |
/qplayer/stop | optional cue # | Stop all — or one cue |
/qplayer/pause | optional cue # | Pause all — or one cue |
/qplayer/unpause | optional cue # | Resume all — or one cue |
/qplayer/preload | cue #, time | Decode a cue and hold it Ready |
/qplayer/select | cue # | Move the selection |
/qplayer/save | — | Save the project |
/qplayer/volume | dB (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/get | request 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:
| Address | Arguments | Action |
|---|---|---|
/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/select | take name/path | Choose 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)
- Audio MIDI Setup → MIDI Studio → Network: create/enable a network session and connect the CuePool machine.
- 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— freezequit