Knowledge base

Documentation

Complete CUE/IO user, installation, and technical documentation. Choose a topic or search across all sections.

Quick help

Search checks headings and sections across every document.

Back to documentation
Using CUE/IO Operator

User Guide

The home page provides three large mode buttons:

  • RECORD — record Art-Net and optional audio;
  • TIMECODE — listen for LTC and control cue shows;
  • PLAYER — manually play prepared shows.

Only one mode can be active at a time. The user interface regularly reads the server-side state, so the mode displayed on screen is not merely a local button colour. When switching modes, CUE/IO first stops the previous threads and processes, closes audio, the network socket, and files, and only then activates the new mode.

System states are:

IDLE
RECORD_MODE → RECORDING
TIMECODE_MODE → TIMECODE_ARMED → TIMECODE_RECORDING
PLAYER_MODE → PLAYING
STOPPING
ERROR

If you see STOPPING, wait for the resources to close. If you see ERROR, read the displayed error and the Status/diagnostics information; do not press Start repeatedly in parallel.

Main navigation:

  • Home — the three modes;
  • Files — show library and imports;
  • Status — system, Art-Net, audio, and process status;
  • Scheduler — schedules and RTC;
  • More — Monitor, Benchmark, Settings, and Help.

The language menu at the top provides Latvian and English, search, download of a translation template, and import of a new catalogue.

RECORD mode

Before recording

  1. Select RECORD.
  2. Enter a clear show name.
  3. Select the Art-Net interface.
  4. If audio is required, enable audio recording and select an input.
  5. Check free space and warnings.
  6. Select how recording will start.

If audio is enabled but the device is not selected, cannot be found, or is busy, CUE/IO does not start recording. Before starting, it also checks the network interface, disk space, and that no other mode is active.

Recording start methods

Start immediately

Writing Art-Net data and, when selected, audio begins immediately after you press Start recording.

Wait for the first DMX packet

The session and audio are prepared, but writing DMX datagrams begins with the first valid packet received. Art-Net is the fully supported path; sACN uses an experimental direct forwarding path for raw UDP data.

DMX channel

Select the universe, a channel from 1–512, and start and stop values from 0–255. For stable hysteresis, the start value must be higher than the stop value. For example:

Universe 3, channel 1
start when value ≥ 125
stop when value ≤ 100

The panel can be collapsed; the selected channel value and waiting state still remain visible in the monitor above.

During recording

The screen displays:

  • session duration;
  • number of universes received;
  • packets per second;
  • combined Art-Net/audio file size;
  • free disk space;
  • audio level and live waveform.

Art-Net and audio use one session ID and one monotonic time base. Status updates do not themselves write every DMX packet to the log.

Stopping

Press Stop recording and wait until the state returns to RECORD_MODE. If free space falls below the critical threshold during recording, CUE/IO requests a safe automatic stop and records the error on the Status page.

TIMECODE mode

Timecode editor

The Timecode editor is a large section within the TIMECODE workspace. Before arming, configure:

  • whether Timecode is enabled;
  • FPS from 1–60;
  • the left or right LTC audio channel;
  • signal-loss timeout from 0.1–30 s;
  • startup timeout from 0.5–30 s;
  • one or more cue rules.

For each cue you can specify:

  • whether it is active;
  • a start Timecode value in HH:MM:SS:FF format;
  • the show to start;
  • an optional end Timecode value.

Active cues cannot have the same start frame, the end code must be after the start, and the end of one cue must not overlap the start of the next active cue. Saving uses version control; if another browser has changed the configuration in the meantime, the editor asks you to reload the latest version.

The configuration cannot be changed while the active LTC listener or cue resource is still running. Press Cancel first.

Operating sequence

  1. Select and test the audio input in Settings.
  2. Enable Timecode in the TIMECODE editor and save valid cues.
  3. Press Arm.
  4. CUE/IO first opens and checks the audio, then starts waiting for LTC.
  5. Once the signal is recognized, the Timecode value and Timecode detected appear.
  6. The corresponding show starts at the cue boundary; cue audio and Art-Net use one playback session.

Operator phases:

Not armed → Armed → Waiting for timecode → Timecode detected
                                      ↘ Recording / cue playback
Stopped or Error

If LTC disappears for longer than the configured timeout, the listener remains ready and returns to Waiting for timecode. When the signal returns, it resynchronizes; a cue that has already started is not duplicated. If the audio device is disconnected or the decoder stops, CUE/IO publishes a technical error and closes the resources.

Cue tracking from the middle of an interval is not supported. If the listener starts or the signal returns in the middle of a cue interval, CUE/IO does not arbitrarily start from the missed start boundary; it waits for the next cue boundary. A missed end boundary may be applied with late compensation so that an old cue does not remain active.

Cancel stops waiting and any active cue. Changing modes performs the same resource cleanup before starting the next mode.

PLAYER mode

  1. Select PLAYER.
  2. Select a show from the library on the left.
  3. Check its name, duration, audio status, and universe count.
  4. Press Play.

The position, progress, and audio status are displayed. On mobile, a compact fixed bar remains visible during PLAYER mode with the show name, time, Mute, Stop, and progress.

If you choose another show during playback, CUE/IO first stops the previous audio process and Art-Net transmission, closes files and the network socket, and only then starts the new show. Two Player or audio processes cannot run at the same time.

Control buttons

  • Play — starts the selected show;
  • Stop — always releases Player audio and Art-Net resources;
  • Loop — repeats the show until Stop;
  • Mute — immediately applies an effective level of 0%;
  • Volume 0–100% — changes the ALSA mixer without restarting Player.

Pause is not supported by the current audio architecture, so the button is disabled. Changing the volume does not alter the original audio file, restart playback, or change the Art-Net/audio time base. If the hardware mixer is unavailable, the user interface displays a warning.

Playlists

In the PLAYER library, switch from Shows to Playlists to arrange several finished shows into one exact sequence. A playlist does not change show files; it stores only their order and repeat counts.

Creating and starting a playlist

  1. Press New playlist and enter a clear name.
  2. Use Add show to add the first show, choose its name, and set its repeat count.
  3. Add the remaining shows. Use the arrow buttons to change their order and the bin button to remove an item.
  4. At the bottom, leave Repeat the whole playlist off to stop after the last show, or turn it on to begin again from the first show.
  5. Check the sequence summary and press Save.
  6. Press Play on the playlist card. CUE/IO completes each item before advancing to the next one.

For example, Intro × 10 → Finale × 5 plays Intro exactly ten times, followed by Finale exactly five times. With Repeat the whole playlist off, the playlist ends after the fifth Finale. With it on, the complete sequence begins again at Intro; the per-item counts remain exactly 10 and 5 in every cycle. The normal Player Repeat button does not control playlists. Each item accepts 1 to 1,000 repeats; one playlist can contain up to 64 items and up to 10,000 repeats in total. The device can store up to 100 playlists, and a playlist name may contain up to 100 characters.

Progress, stopping, and errors

The playback card displays the playlist name, current show, item number, current repeat, and overall playlist progress. For example, Finale · item 2 of 2 · repeat 3 of 5 means the first item is complete and the third Finale repeat is playing.

Stop playlist stops the current Player session, releases the audio and Art-Net resources, and prevents the next repeat or item from starting. Starting a different show manually, changing mode, or using CUE/IO's global Stop action also stops the playlist safely. The next start begins at the first item, not at the previous position.

In other words, Stop prevents the next item from starting even when the current show ends at almost the same moment. This also applies at the boundary between two whole-playlist cycles, so Stop, mode changes, updates, and shutdown cannot admit the first show of another cycle.

CUE/IO validates the complete sequence before starting. If a referenced show was later deleted or is damaged, the new playlist is not started, existing playback is left untouched, and an error is shown. Open the playlist editor, remove or replace the unavailable show, and save again. Stop an active playlist before editing or deleting it.

Saved playlists remain on the device after a CUE/IO update and Raspberry Pi restart. The definition persists, not its active progress: playback never resumes automatically after a restart. This prevents unexpected lighting or audio output after power is restored; an operator must start the playlist again.

Adjusting audio and DMX synchronization

The DMX playback offset (ms) setting applies in PLAYER mode and is read when a new playback session starts. You do not need to restart Raspberry Pi or CUE/IO. If a show is already playing, changing the offset automatically starts that same show again from the beginning with the new value and leaves the system in PLAYER mode. If no show is playing, the built-in sound-and-light test starts instead.

  • 0 ms keeps the recorded timing without an offset;
  • a positive value sends DMX later than audio; for example, +100 ms delays DMX by 100 ms;
  • a negative value sends DMX earlier than audio. If the light appears about 350 ms after the sound, start with -350 ms and refine it in 20–50 ms steps.

For calibration, use a short test segment with an audible click and a clearly visible flash of light. Adjust the offset by 20–50 ms; CUE/IO automatically restarts the active show or built-in test from the beginning, so you can check the result immediately without leaving Settings. Check several points in the show before choosing the final value.

Latency can be introduced by the audio interface and its ALSA buffer, the DAC or audio processor, the loudspeaker signal path, the Art-Net node or switch, the lighting fixture response, and the physical network path. Recalibrate after changing the audio interface, output device, Art-Net node, network hardware, or buffer settings.

The file manager's Art-Net duration is the timestamp of the last valid recorded Art-Net packet. It can be shorter than the audio if the console stops transmitting or holds the last value. This difference alone does not indicate lost packets or a synchronization error. Also inspect lost-packet and sequence- error counters and test actual playback.

Show file manager

The file table shows the name, creation time, duration, size, universes, audio presence, and audio filename. On a phone, primary actions are icons with tooltips; the remaining actions are grouped in one drop-down menu.

Available actions:

  • play;
  • rename;
  • duplicate;
  • trim;
  • delete;
  • download the complete ZIP;
  • download only artnet.dat;
  • download audio;
  • export/import a CUE/IO archive;
  • open the manual-show editor when the show is manual.

An active recording or Player show cannot be deleted or modified. Every show_id is validated; path separators, .., absolute paths, and leaving shows/ through a symbolic link are prohibited.

Trimming

In the trim dialog, use the dual-handle time slider or precise start/end fields. The browser audio preview helps you choose the boundaries.

Preview output plays only the selected interval through the real configured Art-Net and audio outputs. Use it only when the lighting and audio outputs may be activated. Before the actual trim, CUE/IO creates a backup, then trims Art-Net and audio identically and recalculates the shared duration.

Manual show

New manual show provides two builders.

Art-Net output routing

For a Manual show, the output destination belongs to the show itself and takes precedence over the global Art-Net targets:

  1. In the PLAYER show list, press Manual show, or press Edit on an existing Manual show.
  2. Under Art-Net output, choose Broadcast or Unicast to one IP address.
  3. In Unicast mode, enter exactly one Art-Net receiver IPv4 address in Target IP address.
  4. Save the show. The choice is stored with the Manual-show metadata.

This rule applies to every show whose type is manual: fixed scenes, Effect Generator shows, and Manual shows imported from another CUE/IO. Saved Unicast sends only to the show's one IP and ignores the global unicast list. Saved Broadcast also ignores the global unicast list and uses the configured broadcast address. A show's origin—recorded, imported, or generated—does not by itself select the route; the stored show type does.

Targets are global for every show whose type is not manual. Open Settings → Network → Art-Net unicast targets, enter one IPv4 address per line, and press Save and apply. When at least one valid address is present, CUE/IO sends to the valid unicast targets and does not use broadcast. When the list is empty or contains no valid address, CUE/IO returns to the configured broadcast address. To send non-Manual shows to only one receiver, leave only that one required IP address in the list.

Fixed scenes

The fixed-scene editor creates an Art-Net stream with or without audio. Specify the universe, FPS, start and end segment durations, and DMX values in channel=value form. When audio is selected, it is converted to audio.wav and defines the total show duration. Without audio, leave the file field empty and enter the total duration in seconds—for example, 120 for two minutes.

Use Start live test to check the current unsaved editor configuration on real fixtures. The audio-free test physically sends Art-Net to the selected Broadcast or Unicast destination for at most 30 seconds, does not save a show, and does not add an entry to Files. Stop live test, natural completion, or an error sends blackout. Use it only when people and fixtures are in a safe state. If an active show blocks an action, the Stop show button on the right side of that error safely stops it without leaving the editor. That button appears only when an active Record, Player, or Timecode session is the actual conflict. If another manual show is already being generated or saved, wait for it to finish and try again—the broad Stop action is not offered in that case and unrelated playback is not stopped.

If saving fails because of an input, CUE/IO opens the relevant builder tab or custom-fixture editor, highlights the exact invalid field, and names it in the selected UI language. Correct the first highlighted field and save again; a generic “Please fill out this field” message is no longer hidden on another tab.

Effect generator

The effect generator creates a complete playable Art-Net show without programming. In the PLAYER show list, press Manual show, select the Effect generator tab, and then choose one of eight effects:

  • Static — a constant colour from the selected palette;
  • Pulse — the colour brightness rises and falls periodically;
  • Chase — a light point with a tail moves across the selected fixtures;
  • Rainbow — the palette colours move continuously across the fixtures.
  • Unique random — reshuffles colours at every step while ensuring that no two fixtures emit the same RGB value;
  • Random — deterministically lights fixture groups in a random-looking pattern;
  • Rain — colour drops with adjustable density and tails travel across fixtures;
  • Wave — one or more flowing colour and brightness waves.

Preparing an effect

  1. Enter a show name. If the effect needs sound, attach an audio file—its length defines the generated effect and Art-Net data duration. Audio may be at most one hour long. For a silent effect, leave the audio field empty and enter a duration from 0.1 seconds to 3600 seconds.
  2. Choose the effect and one of 15 ready-made colour palettes, or build a custom palette. Use Intensity, Amount, Spacing, Variation, and Speed to shape it. Speed ranges from 1 to 240 cycles per minute; Static does not use it. Parameter help follows the selected effect—for example, Rain Amount changes the number of drops, while Spacing changes the empty distance between their tails.
  3. Choose one Art-Net universe and first DMX channel. The built-in library has only Generic RGB and Generic RGBW: use −/+ to choose a pixel quantity, and Add fixture inserts that whole group. Add custom profiles one at a time in installation order. One mixed-mode order may contain up to 170 fixtures. Drag a fixture by its grip to any position; the up/down buttons remain available for keyboard control. On drop, CUE/IO immediately recalculates the order and allocates each fixture's real footprint consecutively; press Show DMX address list to see every fixture's mode, universe, start/end address, and absolute fixed channels. The final channel cannot exceed 512. Generic RGB uses three channels and RGBW four; the quantity is automatically bounded to the remaining DMX addresses.
  4. Inspect the visual preview, then press Create show and wait for the completion message.
  5. Return to PLAYER, select the generated show, and press Play for its first real Art-Net output check.

The ready-made choices are Rainbow, RGB, Warm, Cool, White, and ten new palettes: Sunset, Ocean, Neon night, Aurora, Forest, Gold + violet, Candy, Pastels, Fire + ice, and Tropical. Each button shows its colour count; the presets contain between 1 and 10 coordinated shades. Use the custom-palette controls to add, remove, and reorder up to 16 colours (at least one colour is required). Their exact values and order are preserved when the show is saved. The built-in RGB palette is exactly red #ff0000, green #00ff00, and blue #0000ff. Intensity normally ranges from 1–100%. Unique random uses 2–100%, because at 2% the RGB cube already contains enough different non-black emitted values for all 170 supported fixtures. Its shuffle speed is 1–240 colour changes per minute; the other animated effects use 1–240 cycles per minute. Effect Art-Net data is always generated at a fixed 30 FPS.

Unique random creates a different-colour set sampled evenly across the palette for all fixtures. It shows only the controls it uses: Palette, Shuffle speed, Intensity, and Pattern number; Amount, Spacing, and Variation do not apply. After quantization, CUE/IO moves any collision deterministically to the nearest available RGB value inside the selected intensity limit, then assigns the same set to fixtures in a new order at every speed step. This keeps the guarantee even for a single-colour or duplicate palette, although a few fixture shades may be adjusted slightly. No fixture is black in this effect, and all emitted RGB triples in one step are pairwise different.

Audio is optional. When attached, CUE/IO creates a playback copy without modifying the source file, and its length determines both the show and generated Art-Net data duration. Without audio, the entered silent-show duration is used. Start live test is the only effect-testing path that deliberately does not use audio; it sends only the short generated Art-Net test for at most 30 seconds.

The Pattern number preserves the layout of Unique random, Random, Rain, Wave, and other variable effects. The same number with the same settings always generates an identical DMX show; New variation changes the number to produce another pattern. A “random” effect therefore does not become unpredictable during a performance.

Custom fixture profiles

If the fixture's DMX mode does not use simple consecutive colour channels, press Add custom fixture. Enter the mode's total channel count and copy the relative R, G, B, and optional W channel numbers from the fixture's official manual. A dimmer, shutter, or mode channel can be held at a fixed value from 0 to 255. One channel cannot have multiple roles. Select a profile under My fixtures and press Edit to reopen every field; revision protection stops an older browser tab from overwriting a newer change. The profile remains in the fixture library, while each generated show stores its own layout snapshot and continues to work if that profile is edited or deleted later. A profile removed from the built-in library can appear only as an existing show's saved snapshot while that show is being edited.

Fixed values apply only while that generated show is playing. Stop and end-of-show still send blackout (0), so the fixture is not left enabled. Test every new profile on the physical fixture at low intensity and compare it against the manufacturer's DMX table before production use.

The ordered fixture list submits only profile IDs. Addresses and channel maps shown in the browser are informative; the Raspberry Pi resolves every trusted profile again and assigns the consecutive addresses when generating or live testing the show. A deleted custom profile already stored with an edited show remains selectable only from that show's server-owned snapshot.

The visual preview is a simplified animation that runs locally in the browser only. It does not contact the Raspberry Pi output engine, transmit Art-Net packets, or use the network. On-screen colours help show direction and tempo; they are not a measurement of fixture colour or physical timing. Real channel data is created only after saving, and physical output starts only when the saved show is played in PLAYER.

The saved effect writes all 512 channels of its one universe in every frame. Channels outside the selected RGB or RGBW fixture range are 0. Use a dedicated universe for the effect unless blacking out the other channels on that universe is intentional. Before physical testing, confirm that the selected universe, first channel, fixture mode, and Art-Net destination match the console, node, and fixture addresses.

Press Edit in the PLAYER show list to open the same complete builder used to create a manual show. You can change the title, Broadcast/Unicast output, fixed DMX scenes, audio, every effect parameter, palette, fixture order, profile, address, and pattern number. You can also switch between Manual show and Effect generator. Saving safely regenerates the show while keeping its show ID and playlist references. The original creation time is also kept, as are user metadata and supported additional show files. CUE/IO creates a durable backup before replacing the existing show; an incomplete generation or storage error leaves the previous valid show in place.

When editing a fixed-scene or Effect Generator show with audio, explicitly choose Keep, Replace, or Remove. Browsers cannot prefill a file picker for security: Keep reuses the saved audio, Replace requires a new file, and Remove creates a silent show using the entered total duration. Saved audio also survives switching a show from Fixed Scenes to the Effect Generator and back in the editor while Keep remains selected.

If an effect used a custom fixture profile that was later deleted from the library, Edit still offers the trusted layout snapshot saved with that show. Keep it or replace it with a live library profile. The generated effect can still be played, trimmed, duplicated, exported, and imported. It behaves like any other show and can be added to a playlist, for example Pulse × 10 → Rainbow × 5; the same safe-stop and restart rules apply.

Scheduler and RTC

For a Scheduler rule, select a show, start time, and exactly one of:

  • end time;
  • duration in seconds.

A schedule can run every day, on weekdays, on weekends, on selected days of the week, or on a specific date. Loop and the rule itself can be enabled. CUE/IO rejects overlapping active schedules and shows the next action.

Rules are stored in scheduler.json, so they return after an application or Pi restart. The RTC panel displays DS3231 and NTP status. The software also works without RTC, but check the system time if the Pi has been without internet and power for an extended period.

Startup / Show Sequence

Settings → Autoplay provides:

  • Off — remain in IDLE after startup;
  • Player / Show Sequence — Warmup → Wait → Main Show → Loop or shutdown;
  • Timecode — select TIMECODE after startup and begin listening for LTC.

The Timecode startup mode cannot be saved when Timecode is disabled, no audio input is selected, or active cues refer to invalid shows. After an unexpected restart, CUE/IO does not resume an unfinished recording. Only conservative recovery of a Scheduler run or a precisely configured Loop show is allowed.

Live DMX monitor

In the PLAYER view, Live DMX opens a physical-output monitor for the show currently playing. It displays the network interface, target IP and UDP port, transmission rate, universes, and channel levels in the last frame sent. This is a sampled view (2 updates per second), not a log of every packet, so the monitor does not significantly load the Raspberry Pi or alter playback synchronization.

Select a universe and channel in the monitor. The moving graph shows recent values, current level from 0–255, number of active channels, source, packet count, and last-packet time. The monitor is intended for diagnostics and does not alter the DMX stream.

Status and statistics

Status displays:

  • CPU, RAM, swap, temperature, storage, and system uptime;
  • CUE/IO process uptime, CPU/RAM, threads, and open files;
  • Art-Net RX/TX, total and lost packets, sequence errors, FPS, and interface;
  • audio input/output, sample rate, channels, buffer underruns/overruns, and synchronization offset;
  • active mode/show, last error, version, restarts, and log size.

Data is cached and refreshed at a limited rate so the Status view does not itself place a significant load on the CPU.

Benchmark

Benchmark levels are 1, 4, 8, 16, 32, 64, and 128 universes. Specify FPS, duration, audio, and the scenario: record only, Player only, or full cycle.

The result shows Benchmark complete, the recommended universe count, and the first level that exceeded the safe limits. A strictly safe universe count is confirmed only by a full-cycle test with no packet loss or audio errors and with sufficient CPU and temperature headroom.

One Raspberry Pi's internal Benchmark does not test the complete physical Ethernet network, switch, cables, Broadcast load, and end nodes. Also run an external test with the real network before an event.

Settings

Sections:

  • Audio — input, output, and test;
  • DMX — Art-Net, experimental raw sACN UDP data, and playback offset;
  • Autoplay — Show Sequence or Timecode startup;
  • Network — Ethernet port, DHCP/static IP, subnet, Broadcast, global non-Manual Art-Net unicast targets, mDNS, and independent fallback Wi-Fi;
  • GPIO — four inputs and actions;
  • Device — diagnostics, restart, reboot, shutdown, and rainbow test.

The recording DMX start conditions are in the RECORD view rather than Settings because they relate directly to preparing a specific recording.

When several CUE/IO units share one network, assign a different device name to each under Network → Management access, then save the .local and access settings. The new name identifies the unit in the browser title, mobile header, and desktop sidebar; use the displayed http://<name>.local/ address afterwards.

Languages and help

The built-in languages are Latvian and English. The selection is stored in a browser cookie. From the language menu, you can download a complete JSON template, translate its values, and import a new catalogue. Do not alter the key structure or _meta fields. Translate only text values, retain every {placeholder}, and validate the file as UTF-8 JSON before importing it.

The Help page provides dynamic search. If a problem recurs, record the exact time, mode, show, and displayed error, then email info@cueio.app.

Documentation contents

More

Monitor Benchmark Settings Documentation Help