MIDI Input

Open from Edit > Inputs > MIDI. The dialog is non-modal, so it stays open while you interact with the rest of the application. The left pane lists detected MIDI devices. The right pane is the mapping editor.

Connecting a controller

Spectralite works with any class-compliant MIDI controller. Fader banks, pad grids, DJ-style units, and MIDI keyboards all reach Spectralite the same way once the operating system reports them, and class-compliant hardware needs no driver install.

USB

Most controllers connect over USB:

Connect the controller to your computer.
Power it on.
Open Edit > Inputs > MIDI. The controller appears in the Devices pane automatically.

5-pin DIN

For hardware with traditional 5-pin DIN ports, connect it to a USB MIDI interface, then connect that interface to your computer. The device appears in the Devices pane under the interface's name.

Network MIDI (macOS)

macOS can carry MIDI over the network:

Open Audio MIDI Setup.
Choose Window > Show MIDI Studio.
Open MIDI Network Setup.
Create or join a session.

The session appears in the Devices pane as a MIDI device, and you assign it a mapping like any other.

Multiple controllers

Every connected controller stays active at once, each with its own assigned mapping, so one unit can drive transport and master while another handles layers. Where two controllers would send the same note or CC, separate their MIDI channels or give each its own mapping so their controls do not overlap. Mapping pages let several controllers share one mapping while each sits on its own page.

Devices pane

The left pane shows every MIDI device the OS reports to Spectralite. Each row displays the device name, a status badge (Online or Offline), an Input indicator, and a dropdown for assigning a mapping.

Reload devices - Scan for newly connected or disconnected MIDI devices

Status indicators

Online (green badge) - Device is connected and active
Offline (outline badge) - Device is not currently connected

Assigning a mapping

Each device row has a dropdown. Pick one of the mappings defined in the Mapping pane, or choose No mapping to clear the assignment. Only mappings that already exist appear in the dropdown.

When the assigned mapping defines pages, the row also shows a Current page dropdown that switches which page this device displays.

Device not appearing

Check physical connection
Click Reload devices in the toolbar
Disconnect and reconnect the device
Restart Spectralite
Check system MIDI settings

Device shows as offline

Verify device is powered on and connected
Click Reload devices to rescan
Check for conflicting applications using the MIDI device
Try a different USB port

Mapping pane

The right pane holds the mapping editor. A sidebar along its left edge shows the last received MIDI message and the list of defined mappings. The main area shows the assignments for the selected mapping.

Last MIDI Message displays the most recently received MIDI message:

Device - Which MIDI device sent the message
Type - Control Change, Note On, or Note Off
Channel - MIDI channel number
Controller/Note - CC number or note number
Value - The received value

Mappings lists every MIDI mapping. Select one to edit its assignments. The toolbar has:

Import mapping - Import a mapping from the Library Manager
Add mapping - Create a new named mapping

Each mapping row has a Duplicate button that creates a copy of the mapping (named <name> copy) with its assignments, and a Delete button that removes it. Both actions are also available from the row's right-click menu.

Assignment list

The main area groups the selected mapping's assignments by what they control, so a bump's trigger button, solo button, and status light sit together under one row. Groups exist for each bump layer, each timeline layer, each fixture parameter, and a Console group for global assignments such as BPM. Click a group row to expand it.

Each group header shows:

The target name and the number of assignments inside
A dot per styled LED state; hover a dot for the state, its note, and its value
The MIDI channels and note/CC numbers bound inside the group

Expanded rows show the individual assignments:

Direction - Input or Output
Assignment - The action or output type
Target - What the assignment controls
Type - Control Change, Note On, or Note Off
Ch - MIDI channel
Note/CC - CC or note number

Each row also has edit, copy, and delete buttons. Deleting the last input binding that drives a status light asks whether to remove the light too; removing both is a single undo step.

The toolbar has:

Export Mapping - Save the mapping to a file
Add assignment - Create a new input or output assignment

Batch editing groups

Tick the checkbox on one or more group rows to open the batch bar above the list:

Shift notes/CCs - Move every note and CC in the selected groups by an offset. Useful for retargeting a whole bank, for example when chaining a second controller. The shift is blocked if any note would land outside 0-127.
Channel - Move every binding in the selected groups to a channel.
Delete - Remove all assignments in the selected groups.

Adding an assignment

Select a mapping in the sidebar
Click Add assignment in the toolbar
Choose Input (MIDI controls Spectralite) or Output (Spectralite sends MIDI)
Configure the assignment type and MIDI settings
Click Submit

When the input is a note-bound button action with a single target (bump trigger, bump solo, layer solo, opacity override, toggle opacity, or exclusive on), the dialog shows a pre-checked Add status light on this button checkbox. Leave it checked to also create an LED feedback output, so the button lights up to reflect its layer. Unless a device LED profile matches (see Device LED profiles below), the light lands on the same note with default brightness values (dark when unassigned, dim when idle, bright when active); edit it afterwards like any other assignment.

Applying captured MIDI data

When creating or editing an assignment, the dialog shows the last received MIDI message. Click Apply to fill in the MIDI type, channel, and controller from that message instead of entering them by hand.

Manual entry

For precise control:

Click Add assignment
Enter MIDI details:
- Type - Control Change, Note On, or Note Off
- Channel - MIDI channel number
- Controller - CC number or note number
Configure the action type and target
Click Submit

Input assignment types

Input assignments let MIDI messages control Spectralite.

Timeline layer controls (address layers in the Timeline panel):

Layer opacity (specific layers) - Set opacity of selected layers (range 0-127)
Layer opacity (by position) - Set opacity of Timeline layers at given positions
Adjust layer opacity (specific layers / by position) - Nudge layer opacity up or down by a delta per tick of a relative encoder
Layer solo (specific layers / by position) - Toggle solo on layers
Layer opacity override (specific layers / by position) - Toggle opacity override on layers
Layer toggle opacity (specific layers / by position) - Toggle layer opacity between 0 and 1
Layer exclusive on (specific layers / by position) - Turn the chosen layers on and every other Timeline layer off

Bump layer controls (address layers in the Bumps panel):

Bump trigger (specific bumps) - Momentarily fire the chosen Bump layers while the input is held
Bump trigger (by position) - Momentarily fire the Bump layers at given positions while the input is held
Bump solo (specific bumps) - Toggle solo on the chosen Bump layers
Bump solo (by position) - Toggle solo on the Bump layers at given positions

By-position targets count layers within the action's own group. A timeline action numbers Timeline-panel layers; a bump action numbers Bump-panel layers. Position N picks the Nth layer in that group by layer order, so position 0 of a timeline action and position 0 of a bump action point at different layers.

Specific-layer targets pick layers by identity rather than position. They stay scoped to the action's own group: a timeline action lists only Timeline-panel layers to choose from, and a bump action lists only Bump-panel layers, so a timeline opacity action and a bump trigger never offer each other's layers. Bump layers have no opacity, so the bump actions cover trigger and solo only.

Timing controls:

BPM - Set the BPM (maps 0-127 to a configurable min/max range)
Tap Tempo - Tap repeatedly to set BPM from timing
Double BPM / Halve BPM - Multiply or divide current BPM
Adjust BPM - Increment or decrement BPM by a delta value
Time offset - Set the timeline time offset
Adjust time offset - Increment or decrement offset
Cue / Align Beat - Align current moment to beat 1

Color controls:

Set primary/secondary/tertiary color hue - Set a color hue from MIDI value
Adjust primary/secondary/tertiary color hue - Rotate hue by a delta
Set color from active library - Select a color from the active library items
Set color from library - Select a color from the full color library

Parameter controls:

Set parameter value - Set a fixture parameter value (maps 0-127 to the parameter's native range: 0-255 for an 8-bit parameter, 0-65535 for a 16-bit one, or a configurable min/max)
Adjust parameter value - Increment or decrement a parameter by a delta

Mapping page controls (see Mapping pages):

Next mapping page / Previous mapping page - Step the sending device to the next or previous defined page
Set mapping page - Switch the sending device to a chosen page number

Output assignment types

Output assignments send MIDI messages from Spectralite to your controller.

LED Feedback - Drive one status light on the controller
Layer Opacity (by layer / by index) - Send a Timeline layer's opacity as a MIDI value, for motorized faders or ring encoders
Parameter Value - Send a fixture parameter value as MIDI

An LED Feedback assignment owns one physical light. First pick the source, what the light watches:

Bump (by position / specific bump) - A Bump-panel layer
Timeline layer (by index / specific layer) - A Timeline-panel layer
Fixture parameter - A parameter's on/off state
Page indicator - On while the device sits on a chosen mapping page
Constant - Always on while the mapping is active

Then style its states. Each source has a fixed set of states: a bump is Unassigned, Idle, Active, or Soloed; a timeline layer is Unassigned, Disabled, Enabled, or Soloed; a parameter is Off or On. The light shows exactly one state at a time; when several apply, the strongest wins (Soloed beats Active, Active beats Idle). Every state you enable gets its own note or CC, channel, and value, so a tri-color pad that maps colors to different notes works by giving each state its note. States you leave unstyled turn the light dark. Use the lightning button on a row to fill its binding from the last received MIDI message.

By-position sources count layers within their own group, the same way the input targets do: a timeline source numbers Timeline-panel layers, a bump source numbers Bump-panel layers, and position N reads the Nth layer in that group by layer order. The specific-layer sources reference a layer by identity instead, and each stays scoped to its own group: a bump source picks from Bump-panel layers, a timeline source from Timeline-panel layers.

Device LED profiles

When a controller's MIDI device name matches one of the shipped profiles, every status light Spectralite creates for you (the Add status light on this button checkbox, the Lights capture setting in Mapping Mode, the correction card's 💡 flip, the status-light controls in the chip popover) uses that device's real color scheme instead of plain brightness levels: red for idle or disabled, green for enabled or active, amber for soloed.

Allen & Heath Xone:K2 - Lights buttons red, amber, or green via offset notes, except the Layer and Exit Setup buttons, whose LEDs use a different scheme. No device setup needed.
Launchpad S / Mini (legacy) - Colors are sent as velocity or CC values on the pad's own note or CC. No device setup needed.
Launchpad Mini MK3 - Put the device in Programmer mode (hold Session, then press the bottom Scene Launch button). Lighting Custom modes may also work, but Programmer mode is the supported path. Spectralite must also see the device's "LPMiniMK3 MIDI" port.

Devices without a matching profile get the plain velocity scheme on the button's own note: dark when unassigned, dim when idle, bright when active.

Name matching can be overridden per device: the LED profile select on a device's row in the Devices pane picks a shipped profile explicitly (useful for MIDI proxies or renamed ports), and Generic (no profile) forces the plain velocity scheme; Auto shows which profile the name currently matches.

Input settings

Each input assignment type has configurable settings:

Min / Max - Range mapping for range-type inputs
Delta - Step size for delta-type inputs (encoders)
Threshold - Trigger threshold for boolean-type inputs

Saving and loading

MIDI mappings are stored inside the project file.

Save: Project > Save project. Mappings save with the project.
Load: Project > Load project. Mappings restore with the project.
Export: Use the Export Mapping toolbar button to write a mapping to a file.
Import: Use Import mapping to pull a mapping from the Library Manager.

Active mapping highlight

When a mapped MIDI control sends a message, the matching assignment row and its group header highlight in the accent color, so a collapsed group still flashes. Use this to verify that assignments trigger as expected.

Mapping pages

Pages let one mapping hold several layouts that you switch between live, so a single controller can drive different banks of layers or effects without swapping mappings. Each device tracks its own current page, so two controllers sharing one mapping can sit on different pages at once.

Define pages in the Pages editor at the top of the assignment list. Add up to nine numbered pages and give each an optional label. A mapping with no pages defined behaves exactly as before, with every assignment always active. Removing a page that still holds bindings asks for confirmation, then reassigns those bindings to Global and moves any device parked on that page to a remaining page (or page 1 when none remain); removing an empty page happens right away with no prompt.

Each assignment belongs to a page, or to none:

A paged assignment is active only while its device is on that page.
A global assignment (no page) is active on every page. Use it for controls that should never change, such as a master fader or the page-switch buttons themselves.

Once a mapping has pages, the toolbar shows a Global chip followed by a filter chip per page. Each chip narrows the list by tag: a page chip shows the bindings on that page, and the Global chip shows the untagged bindings that stay active everywhere. Selecting a page does not surface global bindings, so combine chips when you want both. The chips compose with the text filter. Group and assignment rows show a badge for each page they contain, and the group batch bar gains a Move to page control that reassigns every binding in the selected groups (choose Global to clear the page).

To switch pages from the controller, bind a button to one of the page actions:

Next mapping page / Previous mapping page - Step to the next or previous defined page. Stays put once you reach the first or last page.
Set mapping page - Jump straight to a chosen page number.

Binding Set mapping page also adds a global page-indicator light on that button, so the pad lights up while the device sits on the target page. You can also switch a device's page by hand from the Current page dropdown on its row in the Devices pane (shown only when the assigned mapping defines pages).

Switching a page never interrupts a control you are already holding: a bump held down while you change pages still releases against the page you pressed it on.

Mapping Mode

Mapping Mode is a visual binding overlay that lets you create MIDI or DMX assignments directly on the controls you want to map, without opening the MIDI or DMX input dialogs first.

Entering Mapping Mode

Press Cmd + M (or Ctrl + M on Windows / Linux)
Choose Input > Enter Mapping Mode from the menu bar
Click Bind in place in the MIDI or DMX input dialog toolbar

The same shortcut exits the mode.

Source selector and active mapping

A docked bar appears along the bottom of the application while Mapping Mode is active. It contains:

Source toggle - Switch between MIDI and DMX as the binding source. It is a text-only segmented control, with the active source highlighted by a light fill.
Active mapping picker - Pick which mapping receives new bindings. If no mapping is selected, controls render as non-arming.
Capture cluster (MIDI only) - Three controls that decide how the next binding is built. See below.
Universe filter (DMX only) - Restrict commits to messages from a single universe. Useful when several sources stream into the same mapping.

Capture settings

With MIDI as the source, the bar shows a Capture cluster with three controls:

💡 Lights - On by default. Binding a button control (bump pads, layer solo and opacity-override buttons) to a note also adds an LED feedback entry on the same note, so the controller's pad lights up to reflect the target's state. Undo removes the binding and its light in one step. If the mapping already holds a light for the same target, the existing one is kept.
Pair notes - On by default. For press/release-style controls (bump pads, solo, flash, opacity, parameters), binding a note creates entries for both note-on and note-off, so press and release both reach the target. Turn it off to bind exactly the message type you send: play only a note-on (or only a note-off) and just that type is bound.
CC (Auto | Set | Adjust) - How continuous controls bind. Auto watches the first second of CC movement (the status area shows Capturing… with a message count): the tick pattern of a relative encoder binds the target's adjust action, anything else binds set. Set and Adjust skip detection and bind on the first message. Adjust falls back to set when the target has no adjust action, and the correction card says so.

Arming a control

Every mappable control (layer opacity faders, layer solo and opacity-override buttons, bump pads, BPM and offset readouts, hue wheels, color slots, library swatches, the BeatMatcher's nudge buttons, and fixture parameter rows) draws a dashed outline while the mode is active. Click a control to arm it; the outline switches to a solid orange ring. Send a MIDI message or change a DMX value on the chosen source and the binding commits to the active mapping. Pressing Escape, clicking elsewhere, or waiting 30 seconds cancels the arm.

When the active mapping defines pages, the overlay bar adds a Page selector (the segment labeled PAGE) listing Global and each page, which decides where new binds land. Pick a page and every device on the mapping switches to it, so the pads and their lights follow while you capture bindings tagged to that page. Pick Global to bind controls that stay active on every page without moving any device. Switching the active mapping seeds the selector from its devices' shared page, or Global when the devices sit on different pages. Page-less mappings bind every control globally.

Correction card

After each MIDI bind, the bar's status area shows a card with the bound address and target, plus one-click flips for the choices the capture settings just made (DMX binds show only the status sentence):

→ adjust / → set - Swap between the relative and absolute action. Shown only when the target has both; settings translate across the swap. Flipping to adjust also removes the paired note entry and the status light; flipping back to set does not restore them.
pair / unpair - Add or remove the opposite note type on a note binding.
💡 - Add or remove the status light.

Each flip rewrites the binding in place as a single undo step, and the chips always reflect what the mapping actually contains. The card also carries any notices from the bind, for example when adjust was unavailable and the target was bound as set, or when an existing status light was kept. It stays until you arm the next control, exit the mode, or about ten seconds pass.

Chips on bound controls

Once bound, a control shows a small chip near its top-right corner. The chip glyph matches the binding source (MIDI or DMX) and the count next to it reflects multiple bindings on the same target. Click a chip to open a popover with the binding's action type, input settings, source mapping name, and a delete button. Deleting the last binding that drives a status light asks whether to remove the light too; removing both is a single undo step. For button bindings that support LED feedback, the popover also shows a Status light row where you can add a light or remove the paired one. If a control has chips for a source other than the current one, the chip renders dimmed; clicking it flips the source selector for you.

Bind-in-place from the input editors

Both the MIDI Input dialog and the DMX Input dialog have a Bind in place button that toggles Mapping Mode with the current source pre-selected.

Troubleshooting

MIDI not detected

Check device connection
Verify the device shows Online in the Devices pane
Check MIDI channel settings

Wrong parameter changing

Review the assignment target
Check for duplicate assignments on the same MIDI channel and controller
Verify MIDI channel

DMX Input Dialog - ArtNet and sACN receivers and mapping
Parameters - Parameter targets for MIDI mapping