Glossary

This glossary defines the canonical terms used throughout Luma's codebase and documentation.

Data Flow

Library (syncs to cloud)              Venues (per-room)
|-- Patterns                          |-- Patched Fixtures
|   '-- Implementations (graphs)      |   |-- DMX Universe + Address
|-- Tracks                            |   '-- 3D Position + Rotation
|   |-- Beats (BPM, beat grid)        |-- Groups
|   |-- Stems (drums/bass/vocals)     '-- Scores
|   |-- Roots (chord analysis)            '-- Annotations (Track Scores)
|   '-- Waveforms                             |-- Pattern reference
'-- Categories                                |-- Time range + z-index
                                              |-- Blend mode
                                              '-- Argument values

Core Concepts

Venue

A project container representing a physical space. Contains fixture patches, groups, and scores. Venues translate abstract patterns into concrete hardware instructions.

Patched Fixture

A fixture instance assigned to a venue at a specific DMX universe and address, with 3D position and rotation.

Head

An independently-controllable segment of a multi-head fixture. A pixel bar with 12 pixels has 12 heads. A simple par can has 1 head. Head positions are computed from the fixture definition's physical dimensions and the fixture's 3D placement.

• Addressing: fixture_id:head_index (e.g., "abc123:0", "abc123:1")

DMX Universe

A group of 512 DMX channels (addresses 1-512). Standard DMX-512 protocol term. A venue can span multiple universes.

Group

A logical collection of fixtures organized by role and spatial position, not by DMX address. Groups are the bridge between abstract patterns and physical hardware -- they enable venue portability. Each group has a descriptive snake_case name (e.g., front_wash, floor_ring, back_movers).

• Spatial Axes: axis_lr (left/right), axis_fb (front/back), axis_ab (above/below) -- each -1.0 to +1.0

Selection Expression

A boolean query over group names used by pattern Selection arguments to target fixtures. Operators: & (AND), | (OR), ^ (XOR), ~ (NOT), > (fallback), with parentheses for grouping.

Examples: front_wash & left_truss, floor_ring & ~dj_booth, strobes > front_wash.

Pattern

A reusable, venue-agnostic light behavior defined as a visual node graph. Contains one or more implementations (graph versions).

Implementation

A specific node graph version of a pattern. Contains the serialized graph (nodes, edges, pattern arguments).

Graph

The node-and-edge data flow graph within an implementation. Nodes are processing units, edges connect output ports to input ports, and pattern arguments expose configurable parameters.

Signal

A 3D tensor -- the fundamental data type flowing through pattern graphs. Three dimensions:

• N (spatial): Number of fixtures (or 1 for uniform)
• T (temporal): Time samples across the pattern duration
• C (channel): Data channels per sample (1=scalar, 2=pan/tilt, 3=RGB, 4=RGBA, 12=chroma)
• Broadcasting: Dimensions of size 1 expand to match larger operands (like NumPy)

Score

A named collection of annotations for a track within a venue. Each track can have multiple scores per venue -- for example, different users can create their own light shows for the same track. Scores are listed in a score picker when you select a track to edit.

Annotation (Track Score)

A pattern placement on a score's timeline. Defines when a pattern plays, its stacking order, blend mode, and argument values.

Blend Mode

How overlapping annotations combine during compositing. Applied per-layer in z-index order (bottom to top):

Track

An audio file with metadata and analysis data (beat grid, waveforms, separated stems, chord analysis).

PrimitiveState

Runtime output values for a single fixture/head at a single moment. Contains dimmer (0-1), color (RGB 0-1), strobe (0-1), position (pan/tilt in degrees), and speed (0/1).

UniverseState

All fixture states at a single point in time. Despite the name, represents fixture output state, not a DMX universe.