Cues and FX¶
A cue stores a programmable lighting state. Its orders assign values to fixture functions, while fxs contains any dynamic effects. Cues can also link to a single FX palette
Cue fields¶
| Field | Type | Meaning | Notes |
|---|---|---|---|
fx_palette |
Integer | FX palette associated with the cue. | xFF appears to mean that no FX palette is selected. |
cue_id |
Integer | Stable identifier used by cuelists and other references. | Deleted IDs appear eligible for reuse; the allocation policy is unknown. |
visual_id |
Integer | Cue position in the cuelist the cue is in. | Examples: - 100 = 1.00 - 1620 = 16.20 |
fxs |
Array of maps | Dynamic effects stored in the cue. | See FX entries. |
fxs_channels |
Nested array | Channel-state data associated with cue effects. | The inner arrays have a consistent observed length of 16 values, but their schema is unknown. |
orders |
Array of maps | Static fixture-function values recorded in the cue. | See Cue order fields. |
name |
String | Display name of the cue. |
Identifiers are not single-byte-sized
Cue IDs and visual IDs can exceed 255, in which case will be stored using the xC? encoding MessagePack uses.
Cue order fields¶
Each order assigns a value to one function on one patched fixture. A single fixture can therefore contribute several orders to one cue.
| Field | Type | Meaning | Notes |
|---|---|---|---|
palette_id |
Integer | Palette association for the recorded value. | Its sentinel and lookup behavior need confirmation. |
universe |
Integer | Parameter universe used | |
section |
Integer | Parameter category for the order. | Known usage includes intensity and colour. |
receptor_type |
Integer | Identifies the target/receptor category. | Known values include 0 and 1; their mapping correlates with universe. |
patch_id |
Integer | Fixture receiving the value. | Matches the patch's id. |
ftype |
Integer | Fixture function/parameter receiving the value. | |
value |
Integer | Paramater value | |
channel |
Integer | Channel used by the affected fixture's parameter |
FX entries¶
Effects use the following hierarchy:
An FX entry defines targets and overall behavior. Layers choose functions and curves, while steps describe the detailed shape of an advanced effect.
| Field | Type | Meaning | Notes |
|---|---|---|---|
cyclos |
Integer | Cycle-related setting. | The user-interface meaning and enum mapping are unknown. |
direction |
Integer | Direction mode used to traverse the effect. | Several enum values are known, but their labels are not mapped. |
speed |
Integer | Effect speed setting. | Scale and units depend on related speed fields and require confirmation. |
group_steps |
Integer | Group-step setting for the effect. | Exact behavior is unresolved. |
size |
Integer | Overall effect-size parameter. | Frequently uses a normalized fixed-point scale. |
layers |
Array of maps | Parameter layers that compose the effect. | See Layer fields. |
patches |
Array of integers | Patched fixtures targeted directly by the effect. | Entries are expected to reference patch IDs. |
speed_in_bpm |
Boolean | Interprets speed using BPM mode. | When enabled, bpm supplies the tempo value. |
width |
Integer | Width of the effect waveform or active region. | Frequently uses the same normalized scale as size. |
spread |
Integer | Distributes phase or position across targets. | The interface range may differ from ordinary phase degrees. |
basic |
Boolean | Selects Basic rather than Advanced FX behavior. | |
gfxid |
Integer | Group-FX identifier. | Distinct from render_id and fx_ref. |
internal_speed |
Integer | Internal speed value used by the effect engine. | Relationship to speed and bpm remains to be established. |
fx_ref |
Integer or null | Reference to another FX resource or definition. | Null indicates no reference. |
splits |
Integer | Split setting used by Advanced FX. | Numeric mapping is unknown. |
groups |
Array of integers | Groups targeted by the effect. | Whether entries reference group_id directly needs confirmation. |
rect_width |
Integer | Width of the FX layout rectangle. | May derive from target layout; 255 appears to have sentinel behavior. |
name |
String | Display name of the effect. | |
phase_offset |
Integer or null | Entry-level phase offset. | A layer also has its own phase offset; their separate roles are unresolved. |
bpm |
Integer | Tempo value used when speed_in_bpm is enabled. |
Stored using a scaled integer representation. |
render_id |
Integer | Identifier used by the FX renderer. | |
mode |
Integer | Chooses the FX editing/targeting mode. | Observed mapping: 0 = grid, 1 = steps, 2 = groups. |
repeats |
Integer | Number of repetitions for an Advanced FX. | Determine whether 0 has unlimited-repeat semantics. |
rect_height |
Integer | Height of the FX layout rectangle. | Likely paired with rect_width. |
Normalized effect values
Values such as 10000 recur for effect size, width, and step limits and
appear to represent a normalized maximum. internal_speed commonly uses
values around 1000. These scales should be treated as observations until
verified against controls in the application.
Layer fields¶
An effect layer selects one or more fixture functions and describes the curve or step sequence applied to them.
| Field | Type | Meaning | Notes |
|---|---|---|---|
blind |
Boolean | Marks the layer as blind or excluded from normal output. | Exact behavior needs application-level verification. |
phase_offset |
Integer | Phase offset applied to this layer. | Distinct from the entry-level field of the same name. |
section |
Integer | Parameter category affected by the layer. | Known values correspond to intensity and colour categories. |
curve |
Integer | Curve identifier or encoded curve setting. | The mapping to visible curve shapes is unknown. |
steps |
Array of maps | Advanced FX step definitions. | Empty for layers that do not use explicit steps. |
ftypes |
Array of integers | Fixture functions controlled by the layer. | Can contain intensity, RGB, RGBA, or other compatible function types. |
id |
Integer | Layer identifier within the FX entry. | Appears to begin at 1. |
size |
Integer | Layer-level size parameter. | Commonly uses the same normalized scale as the FX entry. |
Function selection
An intensity layer can contain one ftype, whereas an RGBA layer can contain
four. A three-entry RGB layer may intentionally omit amber or may reflect
fixture compatibility; this distinction needs further testing.
Advanced FX step fields¶
Step fields describe one segment of an Advanced FX curve. Some key names are
Spanish (ancho means width and inicio means start), reflecting names used by
the LightShark data model.
| Field | Type | Meaning | Notes |
|---|---|---|---|
start_limit |
Integer or null | Lower/start limit applied to the step. | A normalized maximum is commonly stored when enabled. |
palette_type |
Integer | Palette or parameter category used by the step. | Complete enum mapping is unknown. |
name |
String | Step name shown in the editor. | |
ancho |
Integer | Width occupied by the step. | It may be measured against a 1,024-unit layer scale. |
curve_in |
Integer or null | Incoming curve amount or boundary. | |
curve_out |
Integer | Outgoing curve amount or boundary. | |
strength |
Integer | Strength or amplitude of the step. | Scale needs confirmation. |
curve_type |
Integer | Selects the curve shape. | Enum mapping is unknown. |
palette_value |
Integer | Palette-related value applied by the step. | Relationship to palette_type needs confirmation. |
inicio |
Integer | Starting position of the step. | Likely paired with ancho. |
end_limit |
Integer | Upper/end limit applied to the step. | Commonly uses the normalized effect scale. |
jumps |
Integer | Jump or discontinuity behavior for the step. | Enum or count semantics are unknown. |
Preserve unknown fields
Fields whose meanings are unresolved should still be round-tripped exactly. Their names, types, and relationships are more reliable than guesses based only on individual numeric values.