MIDI Input

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

Connecting a controllerCopy Anchor Link

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

USBCopy Anchor Link

Most controllers connect over USB.

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

5-pin DINCopy Anchor Link

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)Copy Anchor Link

macOS can carry MIDI over the network.

1. Open Audio MIDI Setup.
2. Choose Window > Show MIDI Studio.
3. Open MIDI Network Setup.
4. 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 controllersCopy Anchor Link

All connected controllers are active at once, and each has its own assigned mapping. One unit can then drive transport and master while another handles layers. If two controllers send the same note or CC, their controls overlap. To prevent this, put them on separate MIDI channels or give each its own mapping. Mapping pages let several controllers share one mapping while each sits on its own page.

Devices paneCopy Anchor Link

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

ToolbarCopy Anchor Link

• Reload devices: scans for newly connected or disconnected MIDI devices.

Status indicatorsCopy Anchor Link

• Online (green badge): the device is connected and active.
• Offline (outline badge): the device is not connected.

Assigning a mappingCopy Anchor Link

Each device row has a dropdown. Pick one of the mappings defined in the Mapping pane. To clear the assignment, choose No mapping.

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

Device not appearingCopy Anchor Link

1. Check the physical connection.
2. Click Reload devices in the toolbar.
3. Disconnect and reconnect the device.
4. Restart Spectralite.
5. Check the MIDI settings in macOS.

Device shows as offlineCopy Anchor Link

1. Check that the device is powered on and connected.
2. Click Reload devices to rescan.
3. Check whether another application uses the MIDI device.
4. Try a different USB port.

Mapping paneCopy Anchor Link

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.

SidebarCopy Anchor Link

Last MIDI Message shows the most recently received MIDI message:

• Device: the MIDI device that sent it.
• Type: Control Change, Note On, or Note Off.
• Channel: the MIDI channel number.
• Controller/Note: the CC number or note number.
• Value: the received value.

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

• Import mapping: imports a mapping from the Library Manager.
• Add mapping: creates a new named mapping.

Each mapping row has a Duplicate button and a Delete button. Duplicate copies the mapping and its assignments as <name> (copy). The row's right-click menu offers both actions too.

With a mapping selected, Cmd+C copies it and Cmd+V pastes it as a new mapping, in this project or another one. A paste never replaces the selected mapping. The pasted copy drops any reference to a layer, fixture or library color that the project does not have. See Copy and paste.

Assignment listCopy Anchor Link

The main area groups the selected mapping's assignments by what they control. For example, a bump's trigger button, solo button, and status light sit together under one row. Each bump layer, timeline layer, and fixture parameter gets a group, and a Console group holds 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 to see 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. A Recall Position entry names its group and position, such as All Spots / Upstage line, and the other position actions name their group.
• Type: Control Change, Note On, or Note Off.
• Ch: the MIDI channel.
• Note/CC: the CC or note number.

Each row also has Edit, Duplicate and Delete buttons, which its right-click menu offers too. Duplicate opens the entry editor on a copy of the entry. When you save the copy, it becomes a new entry. If you delete the last input binding that drives a status light, Spectralite asks whether to remove the light too. Removing both is a single undo step.

The toolbar has two buttons:

• Export Mapping: saves the mapping to a file.
• Add assignment: creates a new input or output assignment.

Batch editing groupsCopy Anchor Link

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

• Shift notes/CCs: moves every note and CC in the selected groups by an offset. Use it to move a whole bank, for example when you chain a second controller. If any note would land outside 0-127, Spectralite blocks the shift.
• Channel: moves every binding in the selected groups to a channel.
• Delete: removes all assignments in the selected groups.

Adding an assignmentCopy Anchor Link

1. Select a mapping in the sidebar.
2. Click Add assignment in the toolbar.
3. Choose Input (MIDI controls Spectralite) or Output (Spectralite sends MIDI).
4. Set the assignment type and MIDI settings.
5. 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 show its layer's state. Unless a device LED profile matches, the light goes 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 dataCopy Anchor Link

While you create or edit an assignment, the dialog shows the last received MIDI message. Click Apply to fill in the MIDI type, channel, and controller from that message.

Manual entryCopy Anchor Link

To enter an assignment by hand:

1. Click Add assignment.
2. Enter the MIDI details:
   • Type: Control Change, Note On, or Note Off.
   • Channel: the MIDI channel number.
   • Controller: the CC number or note number.
3. Set the action type and target.
4. Click Submit.

Input assignment typesCopy Anchor Link

Input assignments let MIDI messages control Spectralite.

Timeline layer controls act on layers in the Timeline panel:

• Layer opacity (specific layers): sets the opacity of the selected layers (range 0-127).
• Layer opacity (by position): sets the opacity of Timeline layers at the given positions.
• Adjust layer opacity (specific layers / by position): nudges layer opacity up or down by a delta per tick of a relative encoder.
• Layer solo (specific layers / by position): toggles solo on layers.
• Layer opacity override (specific layers / by position): toggles opacity override on layers.
• Layer toggle opacity (specific layers / by position): toggles layer opacity between 0 and 1.
• Layer exclusive on (specific layers / by position): turns the chosen layers on and every other Timeline layer off. If you choose a layer in a group, its group turns on and the group's other layers turn off. Locked layers keep their opacity, and so does a group that holds a locked layer.
• Set layer timing (specific layers / by position): sets speed, beat offset, or hold time. With no maximum set, the control spans the property's own range: speed 0 to 64, beat offset -4 to 4, hold time 0 to 30.
• Adjust layer timing (specific layers / by position): nudges the chosen timing property by a delta per tick of a relative encoder.

Bump layer controls act on layers in the Bumps panel:

• Bump trigger (specific bumps): fires the chosen Bump layers while the input is held.
• Bump trigger (by position): fires the Bump layers at the given positions while the input is held.
• Bump solo (specific bumps): toggles solo on the chosen Bump layers.
• Bump solo (by position): toggles solo on the Bump layers at the given positions.

By-position targets pick items by index within the action's own panel. A timeline action counts the Timeline panel, and a bump action counts the Bumps panel. Index N picks the Nth item in that panel's order. As a result, index 0 of a timeline action and index 0 of a bump action point at different layers. A layer group takes one index, and the layers inside it take none. A by-position action on a group therefore acts on the group: its intensity, its Solo, its Opacity Override, or for a bump group its button.

Specific-layer targets pick a particular layer or group, again from the action's own panel. A timeline action offers only layers from the Timeline panel, and a bump action offers only layers from the Bumps panel. The list names a group's layers after the group, and it is the only way to reach one layer inside a group. Bump layers have no opacity, so the bump actions cover trigger and solo only.

Position controls act on the groups in the Positions panel:

• Recall Position: recalls the chosen position of the chosen group.
• No Position: lets the group go, so its heads fade back to their own pan and tilt.
• Next Position: recalls the group's next position. After the last position it wraps to the first, and when no position is active it recalls the first.
• Set Group Fade: sets the group's fade time. The control spans 0 to 2 s until you set another minimum or maximum.
• Adjust Group Fade: nudges the group's fade time by a delta per tick of a relative encoder, in seconds. Turning down stops at 0 s. Turning up stops at the maximum, which is 2 s until you change it. A fade that you typed above the maximum stays where it is until you turn it down.

Selection controls turn the heads you selected in 3D Aim on the live stage, whichever position 3D Aim is editing. They move the lights from where they point now: a pan or tilt held by a recalled position changes in that position, and any other changes the fixture's own pan or tilt. With nothing selected they do nothing.

• Set Pan of Selection / Set Tilt of Selection: sets the pan or tilt of every selected head. On Auto the control spans each head's own range; set a minimum and maximum, in degrees, to give every head the same range.
• Adjust Pan of Selection / Adjust Tilt of Selection: turns every selected head by a delta per tick of a relative encoder, 1° until you change it, so the heads keep their spread. Each head stops at the end of its own range.

Timing controls:

• BPM: sets the BPM, mapping 0-127 to a configurable min/max range.
• Tap Tempo: sets the BPM from the timing of repeated taps.
• Double BPM / Halve BPM: doubles or halves the current BPM.
• Adjust BPM: raises or lowers the BPM by a delta.
• Time offset: sets the timeline time offset.
• Adjust time offset: raises or lowers the offset.
• Cue / Align Beat: aligns the current moment to beat 1.

Transport controls (see Pausing and scrubbing):

• Play / Pause: pauses the show in place, or plays on from the held position.
• Return to Start: moves the show to the first beat of the timeline.

Color controls:

• Set primary/secondary/tertiary color hue: sets a color's hue from the MIDI value.
• Adjust primary/secondary/tertiary color hue: rotates the hue by a delta.
• Set color from active library: selects a color from the active library items.
• Set color from library: selects a color from the full color library.

Parameter controls:

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

Controlled value controls act on the values a layer's effect exposes in the Layer Settings panel:

• Set controlled value: sets a Number value, or one axis of a vector value, from the MIDI value scaled into the range below. On a Boolean value, the control turns on above the midpoint of the range, so a note pair works as a momentary switch. If you bind from the Layer Settings panel, Spectralite copies the value's own range into the assignment.
• Adjust controlled value: nudges a Number or vector-axis value by a delta per tick of a relative encoder, clamped to the range the effect declares.
• Toggle controlled value: flips a Boolean value on each press.

A controlled value belongs to one layer and one effect. If you swap the layer's effect or remove the value from it, the binding stays in the mapping. It does nothing until the value exists again. The assignment list marks it as missing.

Mapping page controls switch mapping pages:

• Next mapping page / Previous mapping page: steps the sending device to the next or previous defined page.
• Set mapping page: switches the sending device to a chosen page number.

Output assignment typesCopy Anchor Link

Output assignments send MIDI messages from Spectralite to your controller.

• LED Feedback: drives one status light on the controller.
• Layer Opacity (by layer / by index): sends a Timeline layer's opacity as a MIDI value, for motorized faders or ring encoders.
• Parameter Value: sends a fixture parameter value as MIDI.
• Controlled Value: sends a layer's Number or vector-axis controlled value as MIDI, scaled from the range the effect declares.

An LED Feedback assignment controls one physical light. First pick the source, which is what the light follows:

• Bump (by position / specific bump): a layer in the Bumps panel.
• Timeline layer (by index / specific layer): a layer in the Timeline panel.
• Fixture parameter: a parameter's on/off state.
• Layer controlled value: a Boolean controlled value's on/off state. A Number reads on while it is not zero.
• Page indicator: on while the device is 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 or a controlled value is Off or On.

The light shows one state at a time. When several states apply, the strongest wins (Soloed beats Active, Active beats Idle). Every state that you enable gets its own note or CC, channel, and value. For a tri-color pad that maps colors to different notes, give each state its note. States that you leave unstyled turn the light dark. To fill a row's binding from the last received MIDI message, use the lightning button on that row.

By-position sources pick items by index within their own panel, the same way the input targets do. A timeline source counts the Timeline panel, and a bump source counts the Bumps panel. Index N reads the Nth item in that panel's order, and a group takes one index. Specific-layer sources pick a particular layer or group from their own panel. A bump source offers layers from the Bumps panel, and a timeline source offers layers from the Timeline panel.

A group's light follows the group. A timeline group is Enabled while its intensity is above 0 or its Opacity Override is held, and Soloed while its Solo is held. A bump group is Active while its button is held and Soloed while it is soloed. A layer inside a timeline group shows Enabled only while its group lets it through. When the group's intensity is at 0, the layer shows Disabled until you raise the group or hold its Opacity Override. When you let go of a bump, its light goes to Idle at once, but the bump itself still fades out over its hold time.

Device LED profilesCopy Anchor Link

When a controller's MIDI device name matches one of the shipped profiles, every status light that Spectralite creates for you uses that device's own color scheme. This applies to the lights from these controls:

• The Add status light on this button checkbox.
• The Lights capture setting in Mapping Mode.
• The correction card's 💡 switch.
• The status-light controls in the chip popover.

The scheme is red for idle or disabled, green for enabled or active, and amber for soloed. Spectralite ships these profiles:

• Allen & Heath Xone:K2: lights buttons red, amber, or green through offset notes. The LEDs of the Layer and Exit Setup buttons use a different scheme. The device needs no setup.
• Launchpad S / Mini (legacy): Spectralite sends colors as velocity or CC values on the pad's own note or CC. The device needs no setup.
• 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 one Spectralite supports. 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.

To override name matching for one device, use the LED profile select on its row in the Devices pane. Pick a shipped profile to apply it regardless of the name. This helps with MIDI proxies or renamed ports. Generic (no profile) forces the plain velocity scheme, and Auto shows which profile the name matches.

Input settingsCopy Anchor Link

Which of these settings an input assignment has depends on its type:

• Min / Max: the range for range-type inputs. Set parameter value leaves both on Auto, which spans each target parameter's own scale: 0-255 for an 8-bit parameter, 0-65535 for a 16-bit one. Type a number to fix a bound, or press the x beside it to go back to Auto.
• Delta: the step size for delta-type inputs (encoders).
• Threshold: the trigger threshold for boolean-type inputs.

Saving and loadingCopy Anchor Link

The project file stores your MIDI mappings, so Project > Save project saves them and Project > Load project restores them. The Export Mapping toolbar button writes a mapping to a file, and Import mapping brings one in from the Library Manager.

Active mapping highlightCopy Anchor Link

When a mapped MIDI control sends a message, the matching assignment row and its group header highlight in the accent color. A collapsed group therefore still flashes. Use this to check that assignments fire.

Mapping pagesCopy Anchor Link

Pages let one mapping hold several layouts that you switch between live. A single controller can then drive different banks of layers or effects without swapping mappings. Each device has its own current page, so two controllers that share one mapping can be 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. In a mapping with no pages, every assignment is always active.

If you remove a page that still holds bindings, Spectralite asks for confirmation. It then reassigns those bindings to Global. Any device on that page moves to a remaining page, or to page 1 when none remain. If you remove an empty page, it goes at once, with no prompt.

Each assignment belongs to one 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 global assignments 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 filters the list. A page chip shows the bindings on that page, and the Global chip shows the untagged bindings that stay active everywhere. When you select a page, the list hides global bindings, so combine chips when you want both. The chips work together with the text filter.

Group and assignment rows show a badge for each page they contain. The group batch bar also gains a Move to page control that reassigns every binding in the selected groups. To clear the page, choose Global.

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

• Next mapping page / Previous mapping page: steps to the next or previous defined page, and stops at the first or last page.
• Set mapping page: jumps to a chosen page number.

When you bind Set mapping page, Spectralite also adds a global page-indicator light on that button. The pad then lights up while the device is on the target page. You can switch a device's page by hand from the Current page dropdown on its row in the Devices pane. That dropdown appears only when the assigned mapping defines pages.

A page switch leaves a held control alone. A bump you hold down while you change pages still releases on the page you pressed it on.

Mapping ModeCopy Anchor Link

Mapping Mode is an overlay for creating MIDI or DMX assignments. You click the controls that you want to map, and you do not need to open the MIDI or DMX input dialogs.

Entering Mapping ModeCopy Anchor Link

To enter Mapping Mode, do one of the following:

• Press Cmd+M.
• 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 mappingCopy Anchor Link

While Mapping Mode is active, a bar docks along the bottom of the window. It contains:

• Source toggle: switches between MIDI and DMX as the binding source. It is a text-only segmented control, with a light fill on the active source.
• Active mapping picker: picks which mapping receives new bindings. If no mapping is selected, you cannot arm controls.
• Capture cluster (MIDI only): three controls that decide how Spectralite builds the next binding. See below.
• Universe filter (DMX only): accepts bindings only from messages on a single universe. Use it when several sources send into the same mapping.

Capture settingsCopy Anchor Link

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

• Lights: on by default. It applies to button controls: bump pads, layer solo and opacity-override buttons, and Boolean controlled values. When you bind one of these to a note, Spectralite also adds an LED feedback entry on the same note. The controller's pad then lights up to show the target's state. When you bind a controlled value to a CC, Spectralite adds a Controlled Value output on the same CC instead. A motorized fader or ring encoder then follows the value. Undo removes the binding and its light in one step. If the mapping already holds a light for the same target, Spectralite keeps the existing one.
• Pair notes: on by default. For press/release-style controls (bump pads, solo, flash, opacity, parameters), a note binding creates entries for both note-on and note-off. Press and release then both reach the target. Turn it off to bind only the message type you send. Play only a note-on, or only a note-off, and Spectralite binds just that type.
• CC (Auto | Set | Adjust): how continuous controls bind. Auto watches the first second of CC movement, while the status area shows Capturing… with a message count. If the movement has the tick pattern of a relative encoder, Auto binds the target's adjust action. Any other movement 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 controlCopy Anchor Link

While the mode is active, every mappable control draws a dashed outline. These controls are mappable:

• 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.
• Fixture parameter rows.
• The Positions panel's position pads.
• No position pads.
• Group names and fade fields.
• The controlled value rows in Layer Settings, with one outline per vector axis.

Click a control to arm it, and the outline turns into a solid orange ring. When you send a MIDI message or change a DMX value on the chosen source, Spectralite adds the binding to the active mapping. To cancel the arm, press Esc or click elsewhere. The arm also cancels after 30 seconds.

You can arm a control only when a mapping is picked in the bar and a device is on the chosen source. If either is missing when you click the control, the status area says what is missing.

When the active mapping defines pages, the overlay bar adds a Page selector (the segment labeled PAGE). It lists Global and each page, and it decides where new bindings go. When you pick a page, every device on the mapping switches to it. The pads and their lights then follow while you capture bindings tagged to that page. Pick Global to bind controls that stay active on every page without moving any device.

When you switch the active mapping, the selector starts on the page its devices share, or on Global when the devices are on different pages. Page-less mappings bind every control globally.

Correction cardCopy Anchor Link

After each MIDI bind, the bar's status area shows a card with the bound address and target. The card also has one-click switches that reverse the choices the capture settings just made. DMX binds show only the status sentence.

• → adjust / → set: swaps between the relative and absolute action. It appears only when the target has both, and settings carry across the swap. A switch to adjust also removes the paired note entry and the status light. A switch back to set does not restore them.
• pair / unpair: adds or removes the opposite note type on a note binding.
• 💡: adds or removes the status light.

Each switch rewrites the binding in place as a single undo step, and the chips always match what the mapping contains. The card also shows any notices from the bind. For example, a notice appears when the target had no adjust action and Spectralite bound it as set. Another appears when Spectralite kept an existing status light. The card stays until you arm the next control, exit the mode, or about ten seconds pass.

Chips on bound controlsCopy Anchor Link

Once bound, a control shows a small chip near its top-right corner. The chip glyph shows the binding source (MIDI or DMX), and the count next to it shows how many bindings the target has. Click a chip to open a popover with the binding's action type, input settings, source mapping name, and a delete button.

If you delete the last binding that drives a status light, Spectralite asks whether to remove the light too. Removing both is a single undo step. For button bindings that support LED feedback, the popover also has a Status light row where you can add a light or remove the paired one. A chip for a source other than the current one appears dimmed. When you click it, the source selector switches to that source.

Bind-in-place from the input editorsCopy Anchor Link

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

TroubleshootingCopy Anchor Link

MIDI not detected

• Check the device connection.
• Check that the device shows Online in the Devices pane.
• Check the MIDI channel settings.

Wrong parameter changing

• Review the assignment target.
• Look for duplicate assignments on the same MIDI channel and controller.
• Check the MIDI channel.

RelatedCopy Anchor Link

• DMX Input Dialog: Art-Net and sACN receivers and mapping.
• Parameters: parameter targets for MIDI mapping.