Welcome to Nightfall

Nightfall is a lighting controller for building looks, playing cue sequences and effects, and synchronizing lighting with a timeline. Use the 3D Visualizer to work before connecting a lighting rig.

Visit nightfall.live for the project and Downloads for available builds. This guide describes the desktop application and its connected web UI. The browser demo runs locally in your browser with a curated show; it does not connect to lighting hardware and is not a substitute for saving a desktop showfile.

Start with Your first show, then keep the panel guide nearby. Flows are experimental and are outside the first-release workflow covered here.

The working model

Patch fixtures so Nightfall knows their attributes, modes, and addresses.
Select fixtures and set values in the Programmer to build a look.
Store cues in a Sequence to keep those looks and their transition timing.
Create a Clip to give a sequence or effect playback controls.
Arrange actions on a Timeline when playback should follow time.
Save the showfile to preserve your work.

The programmer is live. Its values can continue to affect output after you store a cue. Clear it before checking playback so you see what the stored cue produces.

Find your way around

Click the top-toolbar Search icon, or press Ctrl+Shift+P (Cmd+Shift+P on macOS), to open the Command Palette. Search for a panel by the names in this guide. The palette also finds show objects. Contextual editors such as Cue Editor and Timeline open from their respective lists.

Drag panel tabs to rearrange the workspace, group tabs together, or split an area. Some panels begin collapsed along a window edge; open them from the palette to expand them. Reopen a closed panel from the palette. Layout controls let you save and restore arrangements.

Keep Properties open beside the panel you are using. It follows the active panel and its selected object; an empty Properties panel often means there is no applicable selection.

Tables commonly offer search, filters, and a column-visibility menu. If an object appears to be missing, clear the search and filters first. Click an editable cell and press Enter or double-click it to edit; confirm the edit with Enter. Row selection, fixture selection, and the active cell serve different purposes, so watch which rows are highlighted before bulk operations.

Saving and recovery

Use the application menu's Save Showfile action. Open Showfile opens the Showfiles dialog, which lists saved shows and their available revisions and drafts. Saving records the show; saving a layout alone does not save fixture programming.

If startup offers to resume unsaved work, Load Draft restores the draft and Keep Saved discards it in favor of the saved show. Read the show name and timestamps before choosing. A backup revision can be opened from the showfile picker; use a named save such as save recovered-show if you want to preserve the current version too.

To delete a show, hover its row in Showfiles and click the trash icon. The show, its draft, and its backup revisions move to Recently deleted at the bottom of the picker, where Restore brings them back for 7 days. Empty trash removes them permanently right away. The show that is currently open cannot be deleted; open another show first.

For a display that stops updating, first check the connection indicator. Allow a few seconds for a newly opened UI to connect. See Status Display, Console, and Instrumentation when diagnosing a problem.

Your first show

This tutorial builds two looks, plays them from a clip, and saves the result. Use a new desktop showfile so the example IDs are free. No physical lights are required.

1. Create a practice show

Install a build from Downloads and launch Nightfall. In the startup showfile picker choose New showfile, or use the application menu's new-show action. Name it First show.

Open I/O Transports through the Command Palette and leave Network output and USB output off while practicing. Open Patch, Programmer, Properties, Sequences, Clips, and 3D Visualizer as you need them. You can return to the palette at any time with Ctrl+Shift+P / Cmd+Shift+P.

2. Add one fixture

Download the Tutorial RGBI Par fixture definition (save the linked JSON file, preserving its filename). Open Fixture Library, choose Upload fixture, and select that file. It describes a virtual light for this tutorial, not a physical product.

In Patch, use the add-fixture button to open the wizard:

Select nightfall / Tutorial RGBI Par, then choose its 4 channel mode. Inspect the parameter preview: intensity, red, green, and blue each use one channel.
Set Quantity to 1 and Label to Par 1.
Leave Assign Console DMX enabled. In Patch, enter universe 1 in the Univ box and start address 1 in the box after the dot. This only assigns console channels; nothing is sent to hardware until you route them to an output target.
Review the mode and channel footprint, then choose Finish.

The fixture should appear in Patch and Fixtures. Note its numeric ID; the commands below use 1. Substitute your fixture's ID if it differs. If the library is empty, install fixture definitions before continuing; see Fixture Library.

3. Make a red look

Click the command input in the top toolbar, enter each line below, and press Enter after each one:

fixture 1 @ 100
fixture 1 red @ 100 green @ 0 blue @ 0

The first command sets intensity to 100 percent. The second sets RGB color. The Programmer should show the fixture and those values. Open Fixtures to see the resulting attribute values and color. The tutorial OFL profile supplies channel information; detailed 3D geometry is available with suitable fixture profiles, such as GDTF.

You can also edit attribute cells in Programmer directly. If the fixture stays dark, verify its mode exposes these attributes, check the Masters levels, and inspect Layers for other output affecting it. Some real fixture modes also need a shutter or other enable attribute.

4. Store two cues

In Sequences, choose Add sequence. Nightfall creates the next available sequence (ID 1 in an empty show) and opens its editor. Open Properties, click the Sequence Editor tab again so Properties follows it, change Sequence label to First sequence, and press Enter. In Programmer, click Store cue. Set Sequence ID to 1, Cue ID to 1, and Label to Red; confirm Store Cue.

Change the programmer color:

fixture 1 red @ 0 green @ 0 blue @ 100

Store again with Sequence ID 1, Cue ID 2, and Label Blue.

Open sequence 1 from Sequences. Its Sequence Editor should contain both cues. Keep Properties expanded beside Sequence Editor, then click the Blue cue in the editor and set its Trigger to Manual in Properties. This makes the second cue wait for Go; the default Follow Previous advances automatically when the previous cue finishes. Leave fade timing at the defaults for the first playback; once it works, try a longer fade and compare the transition. Cues and timing explains inherited timing and tracking.

5. Play the sequence from a clip

Open Clips, choose Add clip, and give it ID 1 and label First playback. Select the clip and open Properties. Set its source to Sequence and select First sequence.

Clear the programmer before playback. The Programmer toolbar's Clear programmer button clears selection first and values on the next press; press it until the programmer values are gone. This is different from setting intensity to zero, which would leave a live instruction.

Right-click the clip and choose Start Clip. Check Status Display for a running instance and look at the fixture output in Fixtures. Enter clip 1 go in the command input to advance to the next cue. For a dedicated Go button, drag the clip to an empty fader in the Clips panel. You should see red and then blue. Stop the clip when finished using Stop Clip from its context menu. An active instance can also be stopped from Status Display.

If the look does not change, check that the clip points to the intended sequence, that both cues contain the expected values, and that the programmer is clear. Stop other active playbacks while learning this sequence.

6. Save and reopen

Use Save Showfile from the application menu. Stop playback before closing the application. Relaunch Nightfall and use Open Showfile to expand First show. Choose its saved showfile row; if a draft is also present, the saved row is the Revert to saved showfile action. This checks the saved version rather than resuming unsaved work.

Check that Par 1, the two cues, and First playback are still present. Start the clip once more, verify the same looks, and stop it. You now have a saved show you can expand.

Next, store a Group for repeated fixture selections, try an FX, or place clip actions on a Timeline. Connect hardware only after reviewing Patch and I/O Transports.

Patching fixtures with DMX

Patching tells Nightfall which lights are in your rig and which DMX channels control each one. You patch a fixture by choosing its definition and mode, giving it a fixture ID, and assigning it a universe and start address.

How DMX addresses work

DMX sends lighting data in universes. A universe holds 512 channels, numbered as addresses 1 to 512. Each channel carries one value from 0 to 255, such as the level of a red LED or the position of a pan motor.

A fixture listens to a block of consecutive channels that begins at its start address. The size of the block is the fixture's channel count, which depends on its mode. For example, a fixture with a 48-channel mode at universe 1, address 481 uses addresses 481 to 528. Address 528 does not exist, so this fixture doesn't fit and needs a lower start address or another universe.

Two fixtures that share a channel react to the same value, so give each fixture its own block. Set the same mode and start address on the physical light that you set in Nightfall. If they differ, commands change the wrong attribute or the wrong light.

Fixture IDs and addresses are separate

The fixture ID is the number you type to select a light, as in fix 701. It identifies the fixture in commands, groups, and cues, and doesn't depend on where its DMX starts. You can repatch a fixture to a new address without changing its ID, and your programming keeps working.

Choose ID ranges that make sense for your rig, for example 101 to 112 for front washes and 201 to 206 for moving heads.

Patch new fixtures

Open Patch from the Command Palette.
In the Fixtures view, select Add fixture (+) to open the wizard.
Filter the library and select a fixture definition, then select Next. If the fixture is not in the library, switch to GDTF Share to search and install it.
Select the mode set on the physical light, then select Next.
Set Quantity and First fixture ID. The wizard numbers the other fixtures after the first one. Leave First fixture ID empty to use the next ID after the highest one in the show.
Keep Assign Console DMX selected and set the universe and start address under Patch. The wizard starts on the first universe and address with room for every new fixture. Select Next available to find that spot again after changing the quantity or mode. Each next fixture starts right after the previous one.
Check the summary, then select Finish.

The new fixtures appear in the Fixtures view. Each one gets a DMX route to its console universe and address, listed in the DMX Routes view.

Send the patch to your lights

Console universes are Nightfall's own DMX space. To reach real lights, route console universes to an output target such as sACN, Art-Net, or a USB interface. See Patch for routes and I/O Transports for output targets.

Storing and recalling looks

The programmer holds your current selection and live attribute instructions. Storing copies programming into a show object so it can be recalled or played later. A stored cue is not a screenshot of everything currently on stage: output from other playback layers is separate from the programmer's instructions.

Store a cue

Use Store cue in Programmer. Choose the sequence and cue IDs and a label, then confirm. A cue ID such as 1.2 means cue 2 in sequence 1.

From the command input:

store cue 1.2

When storing over an existing cue, choose the behavior deliberately:

Mode	Effect
Default / replace	Replace the target's stored programming with the current programmer content.
`/merge`	Add programmer instructions and overwrite matching stored attributes while retaining other programming.
`/update`	Update matching existing programming without adding new attributes.
`/remove`	Remove matching attributes identified by the programmer from the stored cue.

For example, store cue 1.2 /merge changes a subset without rebuilding the entire look. Inspect the result in Cue Editor, especially after bulk stores or stores involving multi-element fixtures.

Selection and reusable values

Store group saves a fixture selection, including ordering used by effects; it does not save a lighting look. Blueprints store reusable attribute values. Normal blueprint recall retains references, so updating the blueprint can update dependent programming. Absolute recall copies concrete values instead. Use References to inspect dependencies before changing or removing shared values.

Do not assume a fixture is stored simply because it is visible in Programmer: selected fixtures can have empty attribute cells. Review the instructions you intend to keep.

Check the result

After storing, clear the programmer and play the cue's sequence through a clip. Saving a cue changes the working show; use Save Showfile to save that show to disk. Use Undo Stack to inspect reversible editing operations, and keep a saved revision before broad changes.

Cues and timing

A cue stores fixture attribute instructions. Cues belong to sequences and use addresses such as 1.2: sequence 1, cue 2. Open a cue from Cues or from its Sequence Editor to inspect the actual stored attributes.

Transitions

A fade moves an attribute from its current value to the incoming cue's target over time. Delay postpones that change. Fade-in and fade-out can differ, and sequence defaults provide timing when a cue does not override it. Inherited timing is different from an explicit zero: zero requests an immediate transition.

In Sequence Editor, select a cue and use Properties to inspect its timing and tracking overrides. Use the preview controls to step through transitions before assigning the sequence to a live clip. Stop preview when finished.

Color Paths choose the route between colors. An assignment on cue 1.2 controls the transition into that cue, not the transition out of it.

Cue triggers

New cues default to Follow Previous, which advances when the preceding cue finishes its delays and fades. Use Manual on a cue that should wait for Go. After Delay measures from the preceding cue's start; At schedules against the sequence start. Select a cue in Sequence Editor and change Trigger in Properties.

Tracking

Tracking determines what happens to attributes that a cue does not explicitly change. In a tracking sequence, earlier values can continue into later cues. Consequently, deleting an instruction is different from storing a value of zero. Review sequence tracking mode and per-cue overrides when a look depends on earlier cues.

The Sequence Editor's tracking preview helps distinguish values stored in the cue from values inherited through playback. Cue Editor is the place to inspect the cue's own instructions. When troubleshooting unexpected values, compare both views and inspect Layers.

Cue parts

A cue may have multiple parts so different subsets of fixtures or attributes can use different timing. Expand the cue's parts in Sequence Editor, select a part, and open its part editor. Part-specific settings override inherited timing for that part. Review conflict indicators when more than one part addresses the same fixture attribute.

Setup and release

Sequences have setup and release programming as well as numbered cues. Setup prepares the sequence; release controls how its contribution leaves output. Stopping a clip may therefore involve a release transition rather than an instant change. Use Status Display to distinguish playing and releasing instances.

Cues, groups, and blueprints

Use cues for looks in playback order, groups for reusable fixture selections, and blueprints for shared attribute values. The first-release UI calls its reusable value objects Blueprints; use that panel when looking for palette-style workflows.

Show tempo and tap tempo

Nightfall keeps one tempo for the whole show. The Tempo panel shows it as a BPM readout with a row of beat dots, where the larger dot is beat 1 of the bar, and holds the Tap pad and the controls below. Open it from the Command Palette, or keep it in your performance layout. To tap from a busking board, add a Tempo element to the board: it shows the BPM and beat dots, and pressing it taps. Everything that follows the tempo, such as the Show Tempo flow node and effects and sequences whose Timing is set to Beats in the FX Editor or Sequence Editor, reads this same clock.

Tapping a tempo

Press Tap in the Tempo panel on the beat. The button responds the moment you press it, so tap on the attack of the beat rather than on release.

The first tap marks beat 1. If you haven't tapped for more than 3.5 seconds, your next tap is treated as a downbeat. It moves the bar so that tap becomes beat 1 and leaves the tempo unchanged.
Each tap after that refines the tempo. From the second tap on, Nightfall fits a steady beat through your recent taps. The BPM comes from their spacing, and the beat is pulled into line with where you tapped.
Only your last 8 taps count. Tapping longer does not keep averaging. Once you have tapped about 8 times, the tempo follows the most recent 8 taps (roughly two bars). That lets you keep tapping to follow a song that speeds up or slows down, and older taps stop influencing the result.
A stray tap starts a fresh count. A tap that lands more than 40% early or late compared with the current beat spacing is not averaged in. A double tap or a skipped beat are typical examples. Nightfall keeps the current tempo and starts counting again from that tap, so the next few taps set the tempo.
Taps are timed where you make them. The Tap button records the moment you pressed it on your own device, so network delay and the engine's frame rate do not change the tempo you tap. Taps from two devices are not mixed: a tap from a different device starts a fresh count.
Stopping is safe. When you stop tapping, the tempo keeps running at the last value.

For the steadiest result, tap 8 or more beats evenly. To mark where the bar starts, pause for a few seconds and then tap on the "1".

Changes never jump

Tempo changes glide rather than jump, so chases and effects running on the beat keep playing smoothly instead of skipping or restarting.

New tempos glide in over about one beat. Going from 120 to 128 BPM takes about half a second.
Beat alignment changes from taps, Resync or Nudge are spread over about one bar. The beat runs slightly fast or slow until it lines up, never more than 25% off speed. Larger corrections take longer: in 4/4, shifting the beat by two whole beats takes about two bars.

Jump to next downbeat is the one exception. It moves straight to the start of the next bar.

Tempo controls

The Tempo panel has these controls next to the Tap pad.

Control	What it does
Tempo (BPM)	Type a tempo between 20 and 300 BPM, or use the − and + buttons. Typed values apply when you press Enter, leave the field, or pause typing.
Beats per bar	Sets the bar length from 1 to 16 beats. The bar you are in keeps its downbeat and the bar count carries on, so changing the length mid-song does not shift where bars start.
Half time / Double time	Halves or doubles the tempo.
Resync to downbeat	Makes this moment beat 1 of a bar without changing the tempo. Use it when the tempo is right but the "1" has drifted.
Jump to next downbeat	Skips straight to the start of the next bar.

Launch quantize

Launch quantize in the Tempo panel makes live clip launches land on the beat. It is a show setting with three choices:

Off: clips start and stop as soon as you press them.
Beat: starts, Go presses and stops wait for the next beat.
Bar: they wait for the next downbeat.

A press that lands just after the beat or downbeat (within a twentieth of a beat) fires straight away rather than waiting a whole beat or bar. While a clip waits, its slot button and any board button for it pulse. Pressing the same button again before the beat cancels the launch, and stopping a clip that is still waiting to start cancels its start.

Launch armed clips now (the lightning button in the Tempo panel toolbar, also available as a mappable action) fires everything that is waiting straight away.

Held Flash and Swop buttons always act at once, and timeline and flow playback never wait.

Commands

The command line controls the same tempo.

tempo 128
tempo tap
tempo half
tempo double
tempo resync
tempo snap
tempo nudge -0.25
tempo bar 3

tempo snap jumps to the next downbeat. tempo nudge shifts the beat by a number of beats: a positive value moves the beat earlier, a negative value moves it later. tempo bar sets the beats per bar.

Because tempo, tap, half, double, resync, snap, nudge and bar are command words, they can't be used as custom attribute names.

MIDI and OSC

In the MIDI Input and OSC Input mapping tables, these actions control the tempo:

Action	Effect
`TapTempo`	One tap, with the same rules as the Tap button.
`ResyncTempo`	Resync to downbeat.
`SetTempo(128)`	Sets the tempo in BPM.
`MultiplyTempo(0.5)`	Multiplies the tempo, for example `0.5` for half time and `2` for double time.
`NudgeTempo(-0.25)`	Shifts the beat by the given number of beats.

Tempo actions run when a button is pressed and ignore the release. Taps from a MIDI or OSC controller are timed the moment the message arrives.

Flows

The Show Tempo node outputs the current BPM, the Beat within the bar and the Bar count (both starting at 1), and the Phase through the current beat from 0 to 1. Its On Beat and On Bar triggers fire once for every beat and every downbeat.

Saved with the show

The tempo, beats per bar and launch quantize mode are saved in the showfile. Opening a show restores them straight away, without gliding from the previous tempo. A new show starts at 120 BPM in 4/4.

Color Paths

Color paths control how a fixture moves between two colors during a fade. They are useful when the straight-line or fixture-native fade passes through colors you do not want, such as a white flash, a muddy middle color, or the wrong side of a hue wheel.

A color path is evaluated at playback time from the actual start color to the incoming cue's destination color. It is not a stored list of absolute color values, so tracking changes, manual output, and edits to earlier cues can change the start color while keeping the same path assignment.

Built-In Paths

New showfiles include these built-in color paths:

ID	Name	Behavior
`1`	RGB	Interpolate directly through RGB emitter space.
`2`	HSV	Interpolate hue, saturation, and value. This is often useful for hue-wheel style fades.
`3`	CMY	Interpolate through cyan, magenta, and yellow components.

Built-in paths can be selected and assigned, but they are read-only. Create a custom path when you need a reusable path with different labels or editable settings.

Assignment Semantics

Color path assignment belongs to the destination cue or fixture default, not to the source cue.

For example, if cue 1.2 has color path 2 assigned, then the transition from cue 1.1 into cue 1.2 uses HSV interpolation. The transition from cue 1.2 into cue 1.3 is controlled by cue 1.3, or by the fixture default if cue 1.3 has no explicit color path.

Resolution order is:

The color path assigned to the incoming cue's color instruction.
The fixture or fixture-element color path default.
Native fixture fade behavior.

Color paths apply only to color-capable instructions, such as RGB, RGBW, RGBA, CMY, and color-mix emitter attributes. Assigning a path to a cue with no supported color instruction has no effect.

Cue Usage

Assign a path to a cue when that cue's destination color needs a specific route:

cue 1.2 path 2

This makes the fade into cue 1.2 use the HSV path.

Clear the explicit cue assignment with:

cue 1.2 path clear

After clearing, the cue falls back to the fixture default or native behavior.

Fixture Defaults

Assign a path to a fixture when most fades for that fixture should use the same route:

fixture 301 path 3

Fixture elements can also have defaults:

fixture 301.2 path 3

Clear a fixture default with:

fixture 301 path clear

Fixture defaults are useful for lights whose native color fade is rarely the desired operator behavior. Cue assignments still override fixture defaults when a specific cue needs a different route.

Managing Custom Paths

Use path IDs outside the built-in range for custom paths:

store path 101 label "No Green"
cp path 101 102
rm path 102

path is the shorthand object name for color-path, which is also accepted:

store color-path 101
cp color-path 101 102

The generic move syntax renumbers a path and updates cue and fixture-default references:

mv path 101 202

Built-in paths 1 through 3 cannot be relabeled, overwritten, duplicated into, or removed.

Timing Controls

Custom paths can adjust how the transition behaves over time:

Curve changes the shape used to sample the path.
In Color controls when the destination color starts entering the fade.
Out Color controls when the source color leaves the fade.
Brightness controls the midpoint brightness of the fade without changing either endpoint.

These controls affect the transition into the destination cue. They do not rewrite the cue's stored start or destination color values.

Basic command syntax

The top-toolbar command input and Console submit the same command language. Type a command, inspect validation and completion suggestions, then press Enter. An accepted command can still report an execution error if its referenced object does not exist.

Fixtures and values

fixture 1 @ 50
fixture 1 red @ 100 green @ 0 blue @ 0
fixture 1>4 @ 100

@ sets a value; without an explicit attribute it sets intensity. These values are percentages. 1>4 selects fixtures 1 through 4. A fixture element uses a dotted address, such as fixture 1.2. Use only attributes available in the fixture's selected mode.

Selection order matters for fanned values and effects. Use Selection Inspector to inspect structured selections before simplifying or storing them.

Store and play

store cue 1.2
store cue 1.2 /merge
clip 1 start
clip 1 go
clip 1 stop
macro 3 start
macro 3 stop

Create the sequence and configure the clip's source in their panels first. Cue 1.2 belongs to sequence 1; clip 1 is a separate object with its own ID. macro 3 start runs the commands of macro 3 in order. See Storing and recalling looks for overwrite modes.

Tempo

tempo 128
tempo tap
tempo half

tempo sets, taps, halves or doubles the show tempo, and can resync or nudge the beat. See Show tempo and tap tempo for every form and how taps are interpreted.

Clear, save, and recover

clear
save
undo
redo

Clear removes programmer state; inspect Programmer to confirm values have been released. The Programmer toolbar additionally exposes a staged clear action that clears selection before values. Saving persists the current showfile. Undo and redo apply to recorded editing operations, not every live playback action.

Console keeps command history and reports errors. Use the UI's completion suggestions for less common commands rather than guessing object names or option syntax. The application menu's Keyboard Shortcuts reference shows the active shortcuts for your platform.

Controllers and keybindings

Nightfall can run its actions from MIDI controllers, OSC senders, and your keyboard. Starting a clip, setting a master's level, toggling timeline playback, or opening a panel are all actions. Anything you bind runs exactly as if you had clicked it.

MIDI and OSC bindings are saved in the showfile, so save the show to keep them. Keybindings belong to the browser you made them in.

Some MIDI controllers light their buttons to show what each binding is doing. Supported controllers lists the ones Nightfall knows and which have been tested.

Mapping a control

The quickest way to bind a controller is mapping mode:

Turn on mapping mode with the plug button in the header, or run Toggle Controller Mapping Mode from the Command Palette. On a phone, the palette is the only way to turn it on. A banner across the top confirms you are mapping.
Press a button, move a fader, or send an OSC message. The banner names the control it heard.
Click one of the highlighted controls on screen, such as a clip's Go button, a master's fader, or the timeline's play button. Controls the touched control cannot drive are dimmed.
Choose how the binding behaves from the menu that appears. Nightfall suggests the most likely choice: a fader follows a level, and a button acts on press.

Repeat steps 2 to 4 for each control, then press Done in the banner or press Escape.

To bind an action that has no button on screen, touch the control and then choose the action from the Command Palette. To see what is already bound to an on-screen control, click it without touching a controller first.

While anyone is mapping, Nightfall pauses all MIDI and OSC actions. A control touched while mapping is never fired by accident. Other people connected to the show see a banner saying actions are paused. Loading a show ends mapping mode for everyone.

Binding a control that already has a binding replaces it. Nightfall says which binding it replaced, and Undo restores it.

Behaviors

Each binding has a behavior that decides what pressing and releasing the control does:

On press runs the action when the button goes down. On a fader, Follow fader sets the level as the fader moves.
On release runs the action when the button comes back up.
While held runs the action on press and its opposite on release. For example, a toggle master stays on only while you hold the button, and a clip plays only while you hold it.
Flash to full pushes a level to full while the button is held and restores the previous level on release.

An action only offers the behaviors that make sense for it. You can change a binding's behavior later from the MIDI Input or OSC Input panel.

Keybindings

Open Settings and choose Keyboard to add your own keybindings:

Choose Add keybinding, then Record keys, and press the key combination.
Pick the action to run.

If the combination is already in use, Nightfall lists what it would replace and asks you to confirm. You can also turn off built-in shortcuts you never use, so they stop catching keys meant for something else. The application menu's Keyboard Shortcuts reference lists every active shortcut.

Some actions belong to a panel, such as inserting a timeline action. Their keybindings only work while that panel is open. Pressing one while the panel is closed shows a message saying the action is not available right now.

When a binding does nothing

The Status column in MIDI Input and OSC Input flags bindings that cannot run, for example because the clip or master they control was deleted. A message also appears when a bound action fails, naming the action, the reason, and which control sent it.

If a MIDI controller was renamed or replaced, its bindings show its old name marked "(not connected)". Pick the new device in the Device column to move them across. Select several rows first to move them all at once.

Supported controllers

Nightfall recognizes the controllers below by their MIDI port name and lights their buttons to show what each binding is doing. You pick LED colors by name, such as "Green" or "Amber flashing", instead of typing the numbers the controller expects. Controllers not listed here still work. Their bindings run as usual, and you can turn on LED feedback and enter LED values by hand.

None of these profiles has been fully checked on real hardware yet. Each one is built from the manufacturer's documentation and the QLC+ input profiles, so a color or port name might be wrong. For controllers nobody on the team owns, LED feedback stays off until you turn on LED feedback beside the device in MIDI Input.

Controller	Tested on hardware	LED feedback starts	Notes
Novation Launchpad (original), Launchpad S, Launchpad Mini mk1 and mk2	Not yet, original Launchpad on hand	On	The Launchpad S and Mini use the same protocol and port name, so they share the profile.
Novation Launchpad MK2	No	Off	Pads use the Session layout: notes 11 to 88, with the top row as controllers 104 to 111.
Novation Launchpad Mini MK3	No	Off	Map the LPMiniMK3 MIDI port (MIDIIN2 on Windows), not DAW, with the Launchpad in Programmer mode. To switch modes, hold Session, then press the orange scene button.
Novation Launchpad X	No	Off	Map the LPX MIDI port (MIDIIN2 on Windows), not DAW. While LED feedback is on, the Launchpad stays in Programmer mode.
Novation Launchpad Pro MK3	No	Off	Map the LPProMK3 MIDI port, not DIN or DAW. While LED feedback is on, the Launchpad stays in Programmer mode.
Akai APC mini (original)	No	Off	Green, red, and yellow, steady or blinking.
Akai APC mini mk2	No	Off	Pads light at full brightness. Track and scene buttons have one LED color each.
Akai APC40 mkII	No	Off	While LED feedback is on, the APC40 runs in Ableton Live mode so Nightfall controls its LEDs.
Akai APC Key 25 mk2	No	Off	Map the Control port (MIDIIN2 on Windows) for the pads and buttons. Pads light at full brightness.
Behringer X-Touch and X-Touch Extender	No	Off	Set the controller to MIDI mode, not MC or HUI. Buttons are on, off, or flashing, and motor faders follow the level they control.
Behringer X-Touch Compact	No	Off	Its buttons light from different notes than they send. In X-Touch Editor, set each button to send its LED note (0 to 38) on the global channel.
Intech Grid modules	Not yet, button and encoder modules on hand	On	Enable MIDI receive for each control in Grid Editor, and set its color there.

The Launchpad MK2, Mini MK3, X, and Pro MK3, and the APC mini mk2, APC40 mkII, and APC Key 25 mk2 share one 128-color palette. Their pads offer steady colors only, because these controllers choose blinking by MIDI channel.

Help test a controller

If you own one of these controllers:

Connect it and open MIDI Input. Under Connected MIDI Devices, check that the controller's name appears beside its port. If it does not, the port name does not match the profile.
Turn on LED feedback for the device, bind a few buttons, and check that each LED color matches its name.
Report the port name and anything that looked wrong, so the profile can be marked as tested or fixed.

Panel guide

Open panels from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Cue Editor, Sequence Editor, FX Editor, Timeline, and Board open from their object lists. This guide covers every first-release panel; experimental Flows is excluded.

Patch

Patch defines the fixtures in your show and their DMX routing. Open Patch from the Command Palette.

Add or change fixtures

Use the add-fixture wizard to select a library definition and mode, set quantity, first fixture ID, and label, choose a console universe and start address, and review the result before Finish. Assign Console DMX can be disabled when you only need a virtual fixture. A mode's channel footprint must match the physical light's mode. For how universes, addresses, and fixture IDs relate, see Patching fixtures with DMX.

The Fixtures tab lists IDs, labels, make/model, mode, channel width, and 3D placement. Edit labels and placement cells here. Fixture IDs identify lights in commands; DMX addresses are separate. Multi-element fixtures can expose several controllable cells under one fixture ID.

Route DMX

The DMX Routes tab lists every DMX route. Group by fixture or universe to inspect them, and check Source, Target, Priority, and Clone values. Resolve highlighted conflicts before outputting to hardware; overlapping addresses can make one command affect the wrong light.

A console address alone does not select a network destination or USB device. Configure output targets in I/O Transports, then add DMX routes from console channels to those targets. Use Console DMX to inspect console universe values, or the wire frames each transport sends.

Output is sent only where a DMX route sends it: a fixture or console range with no output route sends nothing. To stop output, remove the route, for example rm patch fix 12 @ artnet:1. Only inputs can be patched to disabled, which ignores incoming DMX that matches the source.

Some GDTF modes split their channels across several DMX breaks, such as a lamp with an accessory scroller that has its own start address. A fixture's route covers break 1. Give each additional break its own route to an output target, for example patch fix 12 break 2 @ artnet:2.1. The Fixture Library's Mode Parameters list shows which break each channel belongs to.

Changing fixture mode changes how channels represent attributes. Review the wizard's version/mode warnings and confirm your routing after a change. Save the showfile when the patch is correct.

Fixture Library

Fixture Library lists the fixture definitions available to the engine. Open it from the Command Palette and open Properties beside it.

Search or filter by make and model. Select a definition, then inspect its modes, channel count, details, and Mode Parameters in Properties. The mode must match the mode configured on the physical fixture; similarly named modes can have different channel layouts.

Use the preview to check the attributes you need before patching. A fixture with color channels may also require intensity or shutter parameters to emit light. Once you have chosen a definition, use Patch to create instances in the show.

GDTF Share is the shared online library of GDTF fixture definitions. It needs a free account: sign in under Settings > Accounts > GDTF Share on the computer running Nightfall. Every device connected to that computer then uses the same account.

Select Search GDTF Share in the toolbar and type a make, model, or mode name. Select a result to see its revision and modes, then select Install to download it into the library; a bar shows the download as it arrives. Results already in the library say In library; select Show library copy to inspect the copy you have, or Install this revision to add the online revision next to it.

The patch wizard has the same search: switch its fixture list from In library to GDTF Share, or select Search GDTF Share when no library fixture matches your filter. Installing from the wizard selects the new fixture so you can continue patching.

Nightfall saves a copy of the GDTF Share list, so searching works without an internet connection once it has been fetched. The list refreshes itself daily; select the refresh button beside the search field to fetch it now. Installing still needs a connection. GDTF Share is not available in the browser demo.

If the list is empty

Use Upload fixture in the toolbar to import a .gdtf or Open Fixture Library (OFL) .json definition. Select the imported fixture and inspect its modes before patching. The library reads installed fixture data; it is separate from the fixtures already stored in a show. Fixture data belongs in the application's fixtures directory:

Platform	Directory
macOS	`~/Library/Application Support/com.nightfall.nightfall/fixtures/`
Linux	`~/.local/share/nightfall/fixtures/`
Windows	`%APPDATA%\nightfall\nightfall\data\fixtures\`

Use Nightfall-compatible fixture definitions. For source builds, NIGHTFALL_DATA_DIR changes the application data root, so inspect that location if the expected library is missing. Restart the engine after installing definitions if they have not appeared. A saved show's fixture data and an installed library version may differ; review any version-mismatch prompt when adding or morphing fixtures.

Fixtures

Fixtures shows patched fixtures and their current attribute values. Open it from the Command Palette to monitor the result of programmer values and playback together.

Select fixtures here when building a look, then use the command input or Programmer to set attributes. Fixture-wide rows and element rows let you work at different levels of a multi-cell light. Use the row-type and attribute filters to focus the table, and the column menu to expose relevant attributes.

Compare this panel with Programmer: Programmer shows working instructions, while Fixtures shows current fixture state. A value can appear in Fixtures even when Programmer is empty because a running clip contributes it. Layers helps identify the source.

Use Patch to change profile, mode, placement, and routing. If a fixture seems missing, clear table filters and check its ID in Patch before adding a duplicate.

Programmer

Programmer is the live workspace for building looks. Open it from the Command Palette; select fixtures from Fixtures or by command to populate it.

Build a look

Set values using the command input, for example fixture 1 @ 50, or edit the table's attribute cells. Open Properties for the active programmer selection. Fixture-wide and element rows distinguish a whole fixture from individual cells. Empty cells on a selected row are not instructions to set those attributes to zero.

Right-click attribute cells for the available value and clear operations. Filters and hidden columns can hide programmed attributes, so review them before storing a look.

Keep or release your work

Store cue saves instructions into a sequence/cue address. Store group saves a fixture selection. See Storing and recalling looks for overwrite behavior and reusable blueprints.

Clear programmer in this panel clears selection first, then values on another press. Continue until the live values are released before checking cue playback. Setting intensity to zero leaves a programmer instruction; it is different from clearing it.

If a running clip looks wrong, clear the programmer and inspect Layers. Store only the intended instructions, then use Save Showfile to preserve the changes.

Properties

Properties displays settings for the active panel and its selected object. Open it from the Command Palette and dock it beside the panel you are editing.

Select a cue, sequence, clip, fixture, timeline action, or another supported object in its own panel. Properties updates to that context. Changing focus can therefore change the controls you see; check the object label before editing.

Use Properties for detailed settings that do not fit the source table: clip source and priority, sequence and cue timing, fixture information, or timeline behavior. Commit a text or numeric edit using the control's normal confirmation behavior, then check the resulting value.

An empty panel does not necessarily indicate an error. The active panel may not provide properties, or no object may be selected. Return to the source panel and select the object again. Contextual editor pages explain their specific settings.

Groups

Groups stores reusable fixture selections. Open it from the Command Palette. To save your current fixtures, select them in Programmer and use Store group there. New Group in this panel creates an empty group; it does not capture the programmer selection.

Give each group an ID and a descriptive label such as Front wash. Select an existing group through its Select Group context action to reuse the selection. Remove from Programmer Selection removes its fixtures from the working selection. Use Edit Group and Rename to maintain the saved definition.

A group contains selection information, not intensity or color programming. Selection order can matter to effects and fanned values. Inspect complex groups with Selection Inspector before flattening or editing them.

Search narrows the list, and selection mode supports multiple-row operations. Review the selected groups before deleting them; programming that references a group may depend on its contents.

Blueprints

Blueprints holds reusable attribute values for palette-style programming. Open it from the Command Palette. Use New Blueprint to create an empty blueprint with an ID and label. Build the desired values in Programmer, then use Store/Update from Programmer on that blueprint to fill or update it.

Reference or copy

Recall Blueprint recalls referenced values. Programming that retains those references can follow later blueprint changes. Recall Blueprint Absolute uses concrete values instead, useful when a look should remain independent of later edits.

Use clear labels such as Warm white or Stage left position, and inspect Attributes and Refs in the list. The context menu's Dependents entry helps reveal objects using the blueprint; References gives a broader dependency view.

Before updating a shared blueprint, inspect its dependents and compare resulting playback. Updating reusable values can affect multiple cues. Save the showfile after the intended changes are confirmed.

Cues

Cues lists stored cue objects across the show. Open it from the Command Palette, then search for a cue number or label. Cue addresses include their owning sequence: 1.2 means cue 2 of sequence 1.

Select a cue to inspect its properties; open it to enter Cue Editor. Use this list to locate a look when you know its label but are not already in its Sequence Editor. Store new programmer content using Programmer's Store cue action.

A cue's stored instructions are distinct from the tracked output at that point in its sequence. If a cue appears to omit a value you see on stage, inspect the sequence's tracking behavior and preceding cues.

Use Sequences and Sequence Editor for playback order, preview, setup/release programming, and timing. Review Storing and recalling looks before overwriting an existing cue.

Cue Editor

Cue Editor edits the fixture instructions stored in a cue or cue part. Open a cue from Cues, or select a cue/part in Sequence Editor and use its editor action. It is a contextual editor rather than a standalone palette entry.

Check the editor title for the selected cue, then edit attribute cells. Fixture-wide and element rows preserve the distinction between programming a complete fixture and programming a cell. Column visibility and filters help inspect wide fixtures; clear filters when auditing an entire cue.

Removing an attribute removes its stored instruction. Setting it to zero keeps an explicit instruction, which has different tracking behavior. Invalid values are rejected rather than silently becoming valid programming; correct the cell and confirm the result.

Properties provides contextual controls for the selected cue. For timing between cues and inherited defaults, use Sequence Editor. After editing, preview the sequence with Programmer cleared, then save the showfile.

Sequences

Sequences lists ordered cue playbacks. Open it from the Command Palette. Use Add sequence to create the next available ID and open its editor. Rename it through Sequence label in Properties, then inspect its tracking mode.

Store looks into the sequence from Programmer using addresses such as sequence 1, cue 1. Open a sequence using Open Sequence to edit its cue order and timing. Select it to inspect sequence settings in Properties.

Use Duplicate Sequence when you want to adapt an existing sequence, and rename the copy before editing. Search and the cue-count column help find existing material. Deleting a sequence affects the programming and playback that depend on it, so check clip sources first.

A sequence definition is not itself a clip. Use Clips to create a reusable playback control pointing to the sequence, or use Sequence Editor to preview while programming.

Sequence Editor

Sequence Editor arranges and previews a sequence's cues. Open it from the Sequences list. Select rows to inspect cue settings in Properties or open the selected cue part editor.

The table exposes cue timing, triggers, and tracking. Sequence defaults apply where a cue has no override. An inherited value and an explicit zero have different meanings. Expand cue parts to give subsets independent timing, and inspect conflict indicators where parts overlap.

Timing in Properties sets whether the sequence runs on the clock or on the beat. With Seconds, trigger times, delays and fades are seconds. With Beats, they are beats of the show tempo: the table shows them with a b suffix, and you can type a number of beats or a fraction such as 3/4. A chase whose cues follow each other after 1 beat then keeps time with every tap and tempo change, and a speed master at 50% or 200% plays it at half or double time. A beat-timed sequence starts on the beat that is playing when you launch it. On a timeline, it follows the timeline's BPM, so seeking lands on the same cue and fade as playing through.

Use the toolbar to duplicate cues, move them up or down, or delete selected cues/parts. Review setup and release programming as well as numbered cues. Changing order can change tracked output even if the individual cue instructions stay the same.

Preview

Preview go, Preview back, and Jump preview to selected cue let you inspect the sequence while editing. Preview options control transitions and tracking. Clear the programmer so it does not obscure the result, then stop preview when finished.

For operator playback, create a Clip whose source is this sequence. See Cues and timing for the distinction between stored values, tracking, and release.

Clips

Clips provides reusable playback definitions and a bank of faders. Open it from the Command Palette. Use Add clip to create an ID and label, then select the clip and open Properties.

Configure and play

Choose a source kind and an existing source object: a Sequence or an FX variant. Set priority and other playback options in Properties. The source is a reference; renaming a clip does not create a copy of its sequence or effect.

Right-click a clip for Start Clip, Stop Clip, and Show Properties. The State column distinguishes Active from Idle. For sequence playback, Go advances cues; starting and advancing are separate operations.

The Faders section below the clip list accepts drag-and-drop assignments, so frequently used clips get a dedicated fader and button. A fader can also hold a master. Check each fader's label before operating it.

Each fader's button has a mode, chosen from the arrow next to it and saved with the show:

Mode	Clip	Master
Go (default)	Starts the clip, or advances a running sequence	Toggles a toggle-mode master
Back	Steps a running sequence back one cue	Not available
Flash	While held, plays the clip at full whatever its fader says, starting it if it was idle	While held, pushes the master to full
Swop	Like Flash, and also takes every other playback out while held	Not available
Toggle	Starts the clip, or stops it if it is running	Toggles a toggle-mode master
Release	Stops the running clip	Not available

Letting go of Flash or Swop returns the clip to its fader level, and stops it again if the flash started it; a flashed master goes back to its earlier level unless it was moved meanwhile. The button lights up while held. When the button is held from several places, such as the screen and a MIDI pad, the flash lasts until the last one lets go, and a device that disconnects lets go of anything it held. Swop takes out everything other playbacks contribute, colour and movement included, so the swopped clip shows on its own; the Programmer and effect editor previews stay live.

While a Flash or Swop is held, the clip it plays is tagged Flash or Swop in yellow, and every playback a Swop takes out is tagged Swopped in grey. The tags show on the faders, as the state in the Status Display and in the Layers panel, so a button stuck down by a controller that never let go cannot silently blank the stage. Run Release held buttons from the command palette to let go of every held Flash and Swop at once.

A MIDI or OSC button mapped to the fader's button follows the same mode, so changing the mode changes what the controller does too. To keep a controller button on Go whatever the mode, map it to Go fader instead.

Use Status Display to inspect running instances and Layers to see their contribution to fixtures. Clear Programmer before evaluating playback. After changing a clip's source, stop its existing playback and start again to verify the intended definition.

Boards

Boards lists the show's boards: pages of buttons you arrange yourself for busking. Open it from the Command Palette. Use Add board (N) to create an empty board, which opens straight away in a Board panel in edit mode with its settings open so you can name it. New Board in the Command Palette does the same from anywhere.

Switch between the grid and list views with the buttons on the right of the toolbar. Each board shows its ID, label, number of elements, and whether the layout switcher lists it. Search by ID or label.

Click a card, press Enter, or Alt+click a row to open that board in its own Board panel; if a panel already shows it, that panel is brought to the front. Use Edit selected board (E) to change a board's ID or label; an ID another board already uses is refused. The right-click menu offers Open, Rename, and Delete, and Properties renames the selected board. Deleting a board removes it for every device; any Board panel showing it offers the other boards instead.

You can also open a board by typing its name in the object palette (Ctrl+P / Cmd+P).

Boards in the layout switcher

Boards are listed after your layouts in the layout switcher at the top of the window. Picking one fills the whole workspace with that board, which suits a busking surface on a dedicated screen. Pick a layout, or open any panel, to return to your layout exactly as you left it. Which board is showing this way is remembered only on this device, for this session.

To keep a board out of the switcher, open Manage layouts (the + after the switcher) and clear its Show in switcher checkbox under Boards. This is saved in the showfile, so it applies on every device.

Boards are saved in the showfile and shared by every connected device. Board edits can be undone.

Board

A Board panel shows one board, named in its tab. Open boards from Boards, the object palette, or New Board in the Command Palette. You can open several boards side by side and keep Board panels in saved layouts next to any other panel.

Operating

In Operate mode, pressing a button runs that object's usual action:

Clip: start it, or stop it if it is running.
Group: select it in the Programmer.
Blueprint: apply it to the current selection, or release it if it is already applied.
Master: toggle it.
Macro: run it, or stop it if it is running.

Buttons light up from the live show, so they stay correct when something changes from the command line or another device. A blueprint button is half-lit when only part of the selection carries it. A button whose object was deleted has a dashed outline.

A frame or collection set to Solo lets only one of its buttons be on at a time: pressing another button releases the one that was on, and pressing the lit button releases it. This suits color and position pickers.

Editing

Switch to Edit with the Operate / Edit switcher in the panel toolbar. The gear at the right end opens the board's settings, where you can rename or delete it. While editing, the board shows a grid of small square cells across the whole panel, and elements snap to it.

Add elements from the + menu, drag across empty cells to add one sized to that area, or right-click an empty cell. A board can hold:

Buttons pinned to a clip, group, blueprint, master, or macro.
Collections that fill themselves from a filter, such as "blueprints 1-10 whose label contains wash", and pick up matching objects as they are created.
Frames that group buttons under a title.
Labels for notes and headings.
Tempo pads that show the show tempo with its beat dots. Pressing one in Operate mode taps the tempo; see Show tempo and tap tempo.

You can also drag clips, groups, blueprints, masters, and macros straight onto a board from their own panels, in either mode; a highlight shows where the button will land.

Drag an element to move it, and drag its corner handle to resize it. Elements can't overlap: a drag stops at the last free spot. Frames may sit over other elements and move by their title bar. With the keyboard, arrow keys move the selected element, Shift+arrows resize it, and Delete removes it. Ctrl/Cmd+C, X, and V copy, cut, and paste elements, including between boards.

Each element has a gear for its settings (target, label, color, filter, Solo, and whether a frame or collection shows its title) and a right-click menu with Solo, Show title, Cut, Copy, Paste, and Remove. Properties shows the same settings for the selected element, or for the board when nothing is selected.

Macros

A macro is a numbered list of commands that runs with one press. Macros lists the show's macros. Open it from the Command Palette, and use Add macro (N) to create one. The new macro opens in Properties, ready for its commands.

Write a macro

Type one command per line in Commands, exactly as you would type it in the command line. You can also put several commands on one line separated by ;. Use sleep to wait between commands:

group 1 @ 0
sleep 2s
clip 4 stop
group 2 @ 100

Properties checks each line as you type and lists the lines it can't understand, with the line number. Your changes are saved when you leave the field or press Ctrl+Enter (Cmd+Enter). Escape puts back the saved text. The label and the commands are saved in the showfile, and edits can be undone.

On release holds commands that run whenever the macro ends: when its commands finish, when one fails, when you stop it, or when you let go of a held button that started it, such as a MIDI pad. Use it to put things back, for example to fade down what the macro brought up. Letting go of a held button stops the remaining commands and runs On release straight away. Leave it empty and letting go does nothing, so a quick tap runs every command.

Run a macro

Click a card, press Enter on the selected macro, or Alt+click a row to run it. The card shows which line is running, and clicking it again stops the macro. Run and Stop in the toolbar run or stop every selected macro. Run in Properties saves any text you typed, then runs the macro. On the command line, macro 3 start and macro 3 stop do the same.

Stopping a macro runs its On release commands. Stopping it again while those run stops them too.

Commands run in order, each one after the previous one finishes. A macro stops at the first command that fails, and an error names the line, for example "Macro 3 stopped at line 2 (clip 99 start)". Starting a macro that is already running does nothing.

A macro can start another macro, and waits for it to finish. Stopping the first macro also stops the one it started. A macro that would start itself is refused.

Editing a running macro stops it and runs its On release commands. Deleting a running macro or loading a show stops it without them. Pressing Undo while a macro runs stops it, skips On release, and undoes what it did so far.

Undo

A macro that runs without interruption is one undo step. If you change something while a macro is running, the commands the macro runs after your change form a new undo step above it, so undoing never brings back a value from before your change.

Map a macro

Macros appear in the action picker under Macros wherever you can bind an action, such as MIDI and OSC mappings, keyboard shortcuts and timeline events. Start macro runs it, Stop macro stops it, and a held binding to Start macro runs the release commands when you let go.

Macros can also go on a board, as a single button or as a collection of macros. Pressing the button runs the macro, or stops it if it is running. Drag a macro card onto a board to add its button.

You can also find a macro by typing its name in the object palette (Ctrl+P / Cmd+P).

FX List

FX List collects effects by ID, label, type, and details. Open it from the Command Palette. The list includes waveform FX, step FX, and installed module FX.

Use New Effect to create a waveform effect, or Open Effect to edit an existing waveform effect. Step FX and module FX are listed here, but this panel currently does not open editors for those types. Installed modules depend on the engine's data. Search by label or use the Type column to distinguish similar effects.

An effect needs a fixture selection and applicable attributes to produce output. Configure those in FX Editor, then preview or assign the effect to a clip. If no fixtures respond, verify selection and attribute compatibility before increasing output levels.

Renaming helps distinguish variants. Before deleting an effect, check clips and timeline actions that refer to it. Save the showfile after editing definitions.

FX Editor

FX Editor configures an effect's selection, affected attributes, and movement over time. Open a waveform effect from FX List. Step FX and module FX entries do not currently open in this editor.

For waveform effects, choose a waveform such as Sine, Triangle, Sawtooth, Square, or Pulse and set its parameters. Choose the fixture selection and attributes explicitly. Relative values offset another value; absolute values specify the effect's own targets.

Timing sets whether the effect runs on the clock or on the beat. With Seconds, each Cycle length is a time in seconds. With Beats, each cycle length is a number of beats of the show tempo, so a 4-beat cycle always lasts one bar in 4/4 and follows every tap, nudge and tempo change. A beat-timed effect starts on the beat that is playing when you launch it. On a timeline, it follows the timeline's BPM instead of the live tempo.

Changes are local to the editor until you choose Save. Save the effect before assigning it to a clip, and then save the showfile to persist the show. Closing a dirty editor prompts before discarding its changes.

Use Toggle FX preview to observe the result in Fixtures and 3D Visualizer. Clear unrelated programmer instructions first and stop preview when finished. For repeated operation, assign the effect as the source of a Clip.

Selection order changes how effects distribute across a rig. Use Selection Inspector to check complex selections.

Color Paths

Color Paths manages the interpolation routes used for color fades. Open it from the Command Palette and select a path to inspect its properties.

The built-in RGB, HSV, and CMY paths have IDs 1, 2, and 3. They are read-only. Create a custom path when you need editable curve, In Color, Out Color, or Brightness settings, and label it by the intended result.

Assign a path to the incoming cue's color instructions or as a fixture/element default. A cue assignment takes precedence over the fixture default. Paths affect the route through a fade, not the endpoint color stored in the cue.

Test the result from more than one starting color: playback uses the actual start color, so a path is not a fixed sequence of colors. See Color Paths for assignment commands, built-in behavior, and custom path management.

Selection Inspector

Selection Inspector displays the structure and order of a fixture selection. Open it from the Command Palette when working with groups, multi-element fixtures, or distributed effects.

The expression input accepts structured selections, for example Fixture 1>8 | Grid 4 | Wings 2. Choose Apply to update the programmer selection, then inspect the resulting arrangement and ordering. Reset restores the expression from the current selection. The panel exposes selection structure and transformations that can be difficult to infer from a flat fixture list.

Use this view to find unexpected gaps, repeated entries, or ordering before storing a group or using a selection in FX. Selections based on physical position need useful fixture placement information; explicit grid and wing transforms describe selection structure independently.

Flattening a structured selection discards its structure. Read the confirmation before doing so, particularly if later changes should preserve wings or grid relationships. For ordinary look programming, return to Programmer.

References

References shows relationships between show objects. Open it from the Command Palette when preparing to edit or delete reusable programming.

Use the filter to narrow the reference tables. Inspect which objects depend on the target and which objects it uses. Follow available reveal actions to inspect the corresponding object in its panel.

This is especially useful for Blueprints: a shared value change can affect several cues. It also helps trace a clip back to the sequence or effect it plays.

A reference describes a stored relationship, not necessarily a running playback. Use Status Display for active instances and Layers for current fixture contributions. Review dependents before deleting shared objects, then validate playback and save.

Masters

Masters controls intensity or playback speed over a selected scope. Open it from the Command Palette.

Every new show starts with two masters at 100%: Global Intensity Master (master 1) scales intensity across the whole rig, and Global Speed Master (master 2) scales the speed of everything playing. Edit or delete them like any other master.

Use New intensity global for an intensity master across the rig, or choose a group and New group master for a subset. New speed global creates a speed master for everything playing; select clips and use New clip speed to scope it to their instances. At 100% a speed master leaves playback as written, 200% runs twice as fast and 50% half as fast. It scales everything about a playback together: steps, effect cycles, fades, delays and follow times. On a beat-timed effect, 50% plays it at half time and 200% at double time against the show tempo.

A speed master's fader settles on 25%, 50%, 100% and 200% when you release it close to one of them, and you can still type any value. When mapping a speed master to a MIDI or OSC control, you can also choose Speed ×½, Speed ×2 or Speed ×1. Each press halves the speed (down to 25%), doubles it (up to 200%), or returns it to 100%.

Each row shows the master, its mode, level, and enabled state. Change the level to scale the affected output or playback speed. An inhibitive intensity master limits intensity; it does not create a look in an otherwise empty programmer.

Drag a master to a fader in Clips for convenient operation. If fixtures are unexpectedly dark or playback is unusually slow, inspect all applicable masters and their enabled states before changing cue programming.

Save the showfile to preserve master definitions and assignments.

Layers

Layers explains how programmer and playback contributions combine into fixture output. Open it from the Command Palette when a value does not match the cue you expected.

Inspect the available layer sources and select a layer to view fixture and element attributes. Filters and column visibility help narrow a large rig. The source reveal action opens the corresponding show object when one is available.

Compare a layer's values with Fixtures, which shows the resulting fixture state. More than one active layer can address the same attribute; priority and merge behavior determine the contribution that reaches output.

A live programmer instruction can continue to influence output after a cue is stored. Clear Programmer, stop unrelated instances in Status Display, and inspect masters when isolating a playback problem. Editing a source definition and observing its output are separate steps.

Status Display

Status Display summarizes running playback instances. Open it from the Command Palette during operation or while debugging playback.

Use the displayed instance identity, source, state, and timing to distinguish active playback from a stored clip definition. A sequence or FX can have running instances even when its editor is closed. Releasing instances may remain visible while their release finishes.

Use Stop instance to stop a specific running instance. Confirm the source before acting when several playbacks are active. For normal operation use the clip's own controls; this panel is useful when you need to find a playback affecting output.

The Timecodes section also shows clock position, rate, source, and state, with Start timecode, Pause timecode, and Stop timecode controls. Check the clock label before using them because a timeline may follow that clock.

If an expected playback is absent, check the clip source and command errors. If it is present but the fixture does not respond, inspect Layers, Programmer, and Masters.

Timelines

Timelines lists the show's time-based arrangements. Open it from the Command Palette, create a timeline with an ID and label, and use Open Timeline to edit it.

A timeline schedules actions against a linked timecode. Select it and use Properties to inspect its linked clock and configuration. Creating a timeline also needs the corresponding timecode relationship; the creation controls handle this pairing.

Use descriptive labels for songs or show sections and search to find existing timelines. Renaming a timeline does not change the individual action targets it contains. Before deleting one, inspect its actions and confirm it is not running.

Use Timeline for tracks, playback, audio, and action editing; use Timecodes to monitor the linked clock.

Timeline

Timeline edits actions arranged on tracks over time. Open a timeline from Timelines. Keep Properties visible for the timeline or selected action.

Arrange actions

Right-click a track and choose Insert Action..., then select the appropriate existing target and action. Drag actions to position them. Select an action to set its label, position, duration, and target-specific settings in Properties. Track context actions rename, mute, solo, or remove a track.

Audio can be dropped onto the timeline to provide a waveform for alignment. Beatgrid controls expose BPM and beats per bar; beat detection availability depends on the build and installed model. Check detected timing against the music before using it as an editing grid.

Navigate and rehearse

Use zoom, scroll mode, markers, regions, and the jump control to navigate longer arrangements. Jump accepts labels, time expressions such as t 1:05:05, and bar expressions such as b 45:04. Loop controls rehearse a range.

Properties includes linked timecode (with its source; change the source in Timecodes), start/end, audio, lookahead, trigger mode, seek behavior, and stop behavior. Seeking can affect scheduled actions; choose its behavior deliberately before rehearsing command actions or other actions with side effects.

Use Play timeline, Pause timeline, and Stop timeline for transport. Pausing and stopping have distinct behavior. Stop the timeline when finished, including after recording or rehearsal, and check Status Display for remaining instances. Save the showfile to keep the arrangement.

Timecodes

Timecodes monitors the clocks used by timelines. Open it from the Command Palette.

The table shows each timecode's ID, current time in hours/minutes/seconds/frames, and running status. Select a row to keep the clock of interest highlighted. An inactive clock can remain at its current position; an empty table means no timecodes are present in the loaded show.

Following external timecode

Select a timecode here and choose its Source and Rate in Properties; the change applies to every timeline sharing that timecode. A timecode can follow a timecode sender instead of the engine clock, so its timelines chase the playback deck, DAW, media server, or console sending it:

MIDI timecode follows MIDI timecode (MTC) from any connected MIDI input.
Art-Net follows Art-Net timecode (ArtTimeCode) arriving on the network interface used for Art-Net input. Network input must be enabled (see I/O Transports).
LTC follows SMPTE linear timecode arriving as audio. Pick the Audio input and Channel carrying it under the source; each LTC timecode can read its own input. Default input follows the system's default input device. The input opens only while the timecode is started, so the first start may ask for microphone access. If the device is missing or unplugged, the timecode shows No signal and reconnects within a few seconds once the device is back.

All three behave the same way:

Start arms the timecode. It runs only while timecode arrives, and its timelines play and pause with the sender. Pause and Stop stop following the sender.
When the sender locates without playing, the timecode jumps to that position and stays paused.
If timecode stops arriving, the timecode keeps running on its own for its Freewheel time (0.5 seconds unless you set one in Properties) to ride out a glitch. It then returns to the last frame it received and holds there, and its timelines pause until timecode returns. Set Freewheel to 0 to stop as soon as the signal stops.
Loops on a timeline that follows external timecode don't seek, since the sender decides the position.

The status shows No signal while an armed timecode is waiting for the sender, Receiving while timecode arrives, and Freewheel during a dropout. When the sender's frame rate differs from the timecode's rate, the source names the rate it sends.

The browser demo has no MIDI, network, or audio input, so external timecodes there always show No signal.

Start and stop the selected timecode with the panel toolbar or the transport controls of a linked timeline. Timeline Properties shows which timecode a timeline follows and its source.

When a timeline appears stationary, check that its linked timecode is the one running here. When two views show unexpected timing, compare their clock identities before changing action positions.

Tempo

The Tempo panel shows and sets the show tempo. Open it from the Command Palette. It is also in the default layout's right-hand edge panels.

The top of the panel shows the current BPM and a row of beat dots that follows the beat, with the larger dot marking beat 1 of the bar. Below that are fields for the exact tempo and the bar length, and a Tap pad to tap along with the music. While the panel has focus, any letter, number or the space bar also taps, so you can tap from the keyboard without aiming at the pad; typing in the tempo fields does not tap. The toolbar holds Half time, Double time, Resync to downbeat and Jump to next downbeat.

See Show tempo and tap tempo for how tapping and tempo changes behave.

Tap Pattern

Tap Pattern turns rhythmic taps into a cue sequence's timing structure. Open it from the Command Palette.

Arm capture with Arm, then tap in the capture area to record a rhythm. Inspect the tap timeline and analysis. Delete last removes the most recent tap; Restart clears the captured taps for another attempt. Disarm capture when you are done so further input does not add taps.

Adjust Sensitivity and Granularity to examine how taps are grouped. Compare the grouped pattern with your intended rhythm before choosing Create Sequence.

The generated sequence contains timing structure and empty cues; it does not invent lighting looks. Open it in Sequence Editor, store programmer looks into its cues, and rehearse the result through preview or a Clip. Save the showfile after adding programming.

3D Visualizer

3D Visualizer previews fixture output and scene geometry. Open it from the Command Palette. Patched fixture profiles and placement determine what it can display.

Select fixtures or scene objects and use the available camera and editing controls to inspect the stage. Position and rotation are also available numerically in Patch and Scene Objects, useful when precise placement matters. Properties follows the visualizer's active selection.

Use the visualizer while setting programmer values or previewing cues and FX. Its view is a programming aid; it cannot prove that a physical fixture is correctly addressed, connected, or in the correct mode. Check Console DMX and I/O routing separately before relying on physical output.

If the view does not reflect a look, check Fixtures for live values, confirm intensity and color/shutter requirements, and inspect Masters and Layers. Scene objects come from Object Library and are managed in Scene Objects.

Object Library

Object Library contains reusable 3D scene assets. Open it from the Command Palette and select an object to inspect its preview and metadata in Properties.

Search and filter by name, category, or tags. Inspect scale before adding an object to the scene; a model authored in a different unit system may appear unexpectedly large or small.

Use the library's create/import workflow to add a .glb model and fill in its name, category, scale, description, and tags. The Add Object workflow creates an instance in the show from a library object. Installed assets and placed scene instances are separate things.

Manage placed instances in Scene Objects, and verify their placement in 3D Visualizer. Save the showfile after arranging the scene; keep the assets needed by the show available when moving it between machines.

Scene Objects

Scene Objects lists 3D objects placed in the current show's scene. Open it from the Command Palette.

Select an object to identify it in 3D Visualizer. Edit its available placement fields to position, rotate, and scale it. Use labels that describe the placed item, especially when several instances share one library asset.

Add new instances through Object Library and the Add Object workflow. Deleting a placed object changes the scene; it is different from removing the reusable library asset. Undo can recover recorded scene editing operations.

Scene objects provide geometry for visualization and layout. They are separate from patched lighting fixtures and do not acquire DMX channels simply by being placed. Save the showfile to preserve the scene.

Console DMX

Console DMX displays DMX channel values, either as Nightfall's console universes or as the frames each output transport sends. Open it from the Command Palette, pick a view in the Transport select, then choose the universe you want to inspect.

Console and wire numbering

Nightfall numbers DMX in two places:

Console universes are where fixtures are assigned with Assign Console DMX. They are internal to Nightfall; a console universe sends nothing on its own.
Wire universes are the universe numbers an output transport (sACN, Art-Net, USB) actually sends to the network or a device.

A console universe reaches the network only through an explicit console-to-transport DMX route in Patch. For example, patch console:2 @ sacn:10 sends console universe 2's channels as sACN universe 10. A fixture can also be patched directly to a transport, such as patch fix 12 @ artnet:1.1, without needing a console universe. On the wire, a direct fixture route wins over a console universe routed to the same channels, and an input passthrough wins over both, so a wire universe can differ from the console universe routed to it.

To set a raw channel, ch 2.10 @ 255 writes console universe 2, which reaches the wire only through its DMX route. Prefix the channel with an output name to set a wire channel directly: ch sacn:10.10 @ 255 holds sACN universe 10 channel 10 at 255 over anything patched there, even when nothing else sends that universe. The output name is the one used in Patch, so configured outputs work too, for example ch stage-left:1.1>1.4 @ 0. A held channel stays until release ch sacn:10.10 (or release ch sacn:10. for the whole universe) or a plain release.

Transport select

With Output selected, the Transport select chooses which numbering the universe tabs use:

Console lists console universes by their console number. It is listed whenever fixtures or channels occupy console universes, and on its own when nothing is being output at all.
Each output transport lists the frames it actually sends, numbered by wire universe. Broadcast output appears as sACN or Art-Net, while unicast targets and USB devices get their own entries, such as sACN → 10.0.0.4 or USB (<device>).

Use Console to check a fixture's assigned channels, and a transport view to check what a node or device receives. If a console universe has values that no transport view carries, it has no console-to-transport route.

With Input selected, the select lists the transports receiving DMX. External, on by default, discards frames Nightfall itself sent that loop back to its inputs. This is an engine setting, not only a display filter: discarded frames also do not drive input routes.

Reading channels

Use the channel grid to check whether a fixture's channels are changing. Compare the channel range with its mode's footprint in Patch or Fixture Library. Color indicators help associate channel activity with fixture output, but a raw channel value is interpreted according to that fixture profile.

A transport view shows the frame Nightfall composes for that wire universe, not proof that a packet reached a network node or USB device. If channels change but a physical light does not, check Patch DMX routes, I/O Transports target status, and the light's universe/address/mode.

If channels do not change, first inspect Programmer, clip playback, and Masters. Fixtures without console DMX assignment or an output route can still be controlled virtually without occupying channels here.

I/O Transports

I/O Transports configures the physical transport targets used by patch routing. Open it from the Command Palette.

Network DMX

Network input and Network output enable the respective network DMX directions. Add an output target with a unique ID, select its protocol and delivery mode, and enter an IP when that mode requires one. Review the validation/status cell before adding it. The interface summary helps identify the available network adapters.

Art-Net and sACN targets are destinations for DMX data. Connect them to the appropriate console channels through Patch DMX routes. A configured target does not by itself route every universe to it. Check send failures and output status when diagnosing a destination.

External control

External control allows remote clients to reach the engine's control interface. It starts off. When enabled, Interface defaults to All; choose a specific IPv4 network interface to limit where remote clients can connect. Local access through 127.0.0.1 stays available.

Changes apply immediately and connected clients may reconnect. If a selected adapter is missing, the engine stays accessible locally and shows an error instead of opening every interface. These are settings for this computer, separate from the showfile, so loading a show does not enable external control. Enable remote access only on a trusted network.

Open on another device

While External control is on, the section lists a link for each network address another device can use, such as http://192.168.1.20:3030/. Select a link to copy it. Point at the QR code button, or select it on a touch screen, to show a QR code. Scanning it opens Nightfall on the phone or tablet and pairs it in one step, because the code also carries the PIN. A copied link leaves the PIN out, so whoever opens it still has to enter the PIN.

When developing Nightfall, the link points at the Vite dev server, which only accepts other devices when started with --host.

Pairing PIN

A phone, tablet or other computer must enter the Pairing PIN shown under External control before it can control the show. The computer running Nightfall never needs it. Each device enters the PIN once: it stays paired, and reconnects on its own after a network drop, until Nightfall restarts. The PIN stays the same until Nightfall restarts or you select New PIN, which also signs out every paired device. After five wrong PINs, a device must wait before trying again, and the wait grows with each further miss.

The PIN keeps casual visitors on your network out; it does not protect against an attacker on it. Nightfall serves other devices over plain HTTP, so anyone who can watch network traffic can capture the PIN or a paired device's session and take control. Use External control only on networks you trust.

USB

Choose a detected USB device for an output target, give the target a unique ID, and enable USB output when ready. Review Missing device or duplicate-device status before attempting output. If no device is listed, check the physical connection and host access to the device.

Keep physical output off while rehearsing changes that should only affect the visualizer. Test one fixture and destination first, then expand the routing. Use Console DMX to separate programming problems from transport problems.

MIDI Input

MIDI Input lists connected MIDI devices and every MIDI binding in the show. Open it from the Command Palette. For the quickest way to bind controls, use mapping mode, described in Controllers and keybindings.

When you plug in a controller while Nightfall is running and the show has no bindings for it yet, a notification names it and offers Open MIDI Input, which opens this panel. Tick Don't show this again to stop these notifications on the computer or tablet you are using. To bring them back, choose Show again next to Hidden prompts in Settings, under General.

Connected MIDI Devices shows the controllers Nightfall can hear. Press a button or move a fader and Last Input shows the device, the control, and its channel. To bind that control from here, pick an action and a behavior beside Last Input and choose Add Mapping.

Each row in the table is one binding:

Device is the controller the binding listens to. A device that is not connected is marked "(not connected)". Pick a connected device to move the binding to it, for example after replacing a controller.
Control, Channel, and Number identify the button, fader, or knob. Channel and Number can be edited.
Behavior decides what pressing and releasing the control does. See Behaviors.
Action is what the control runs. Select one row to change its action with the picker above the table.
Status flags bindings that cannot run, such as one whose clip was deleted.

Edits apply to every selected row. Select rows and choose Delete to remove them. Filters and hidden columns can hide existing bindings, so clear them when a control seems to trigger something unexpected.

If nothing appears in Last Input, check that the controller is connected and shows up under Connected MIDI Devices. Save the showfile to keep your bindings.

OSC Input

OSC Input shows the OSC listener and every OSC binding in the show. Open it from the Command Palette. For the quickest way to bind controls, use mapping mode, described in Controllers and keybindings.

The listener section shows whether Nightfall is listening and on which address and port. Point your OSC sender there. Send a message and it appears under Known Sources and Last Input. To bind the control that sent it from here, pick an action and a behavior beside Last Input and choose Add Mapping.

Each row in the table is one binding:

Source limits the binding to one sender. Leave it blank to accept messages from any sender.
Address is the OSC address the binding listens to.
Arg Index picks which argument to read, and Arg Match runs the binding only when that argument has a given value. Release Match is the value the control sends when a button is let go.
Min and Max describe the range a fader sends, for example 0 to 127. Leave them blank for the usual 0 to 1. Setting Min above Max reverses the fader.
Behavior decides what pressing and releasing the control does. See Behaviors.
Action is what the message runs. Select one row to change its action with the picker above the table.
Status flags bindings that cannot run, such as one whose clip was deleted.

Edits apply to every selected row. Select rows and choose Delete to remove them.

If a binding does not run, first check that the message appears in Last Input, then check its address and argument matching. Save the showfile to keep your bindings.

Console

Console shows command input, history, and command results. Open it from the Command Palette or use Shift+backtick. The top-toolbar command input operates the same engine command language.

Type a command, use completion suggestions to inspect available syntax, and press Enter to submit. History search helps reuse earlier commands. An error message can distinguish invalid syntax from a valid command whose referenced object is missing.

Start with Basic command syntax. Use the panel's history to review exactly what you submitted when a fixture or cue changes unexpectedly. Repeating a store or delete command can change show data again, so inspect recalled text before execution.

Console is useful evidence for a bug report: include the failing command, the response, the relevant object IDs, and the expected result. Use Instrumentation for runtime performance information.

Undo Stack

Undo Stack displays recorded editing history and the operations available to undo or redo. Open it from the Command Palette before undoing a series of unfamiliar changes.

Inspect the descriptions and ordering to identify the operation you want to reverse. Use the application's Undo and Redo actions, then confirm the affected object in its own panel. New edits after an undo can replace the redo path.

Not every action is a reversible edit: starting playback, receiving external input, and saving a file serve different purposes. Stop playback with its transport controls rather than assuming Undo will stop it.

Undo history is useful during a session, but a saved showfile and its revisions provide recovery across sessions. Save before broad edits and use Open Showfile to inspect available backups.

Instrumentation

Instrumentation displays runtime measurements for diagnosing responsiveness and update problems. Open it from the Command Palette after reproducing the behavior you want to inspect.

Compare frontend and backend activity, frame/update measurements, and transport-related statistics shown by the panel. Observe an idle baseline, perform the troublesome action, then note which values change. Keep the fixture count, open panels, and active playback comparable between observations.

A connected UI can still be waiting on a slow operation; a high update rate also does not prove the visualizer is rendering correctly. Check the visible result alongside measurements. Use Console for command errors and the connection indicator for transport state.

For a useful bug report, record the application version, operating system, reproduction steps, and a screenshot of the relevant measurements. Remove private show labels or local paths before sharing screenshots or logs. More targeted developer options are described in the developer reference.

Glossary

Term	Meaning
Attribute	A controllable fixture property, such as intensity, pan, or red.
Blueprint	Reusable attribute values that other programming can reference.
Clip	A playback definition pointing to a sequence or effect, with its own options and controls.
Color path	The interpolation route used when fading into a destination color.
Console DMX	Nightfall's internal universe/channel address space before transport routing.
Cue	Stored fixture instructions within a sequence.
Cue part	A subset of cue programming with its own timing overrides.
Cycle length	How long one loop of an effect takes, such as 2 seconds, or 4 beats when the effect's timing is in beats.
DMX route	A connection in Patch that carries DMX: from fixtures or console channels to an output, or from an input to fixtures, console channels, another output, or `disabled` to ignore it.
Element	An independently addressable cell or part of a fixture.
Fader	One numbered strip in the Clips panel's fader bank, with a level and a button, that a clip or master can be assigned to. MIDI and OSC controls map to it by number.
Fixture	A patched light with a profile, operating mode, and optional DMX assignment.
Fixture profile	The definition translating fixture attributes to the channels and ranges of a mode.
Group	A reusable fixture selection, including its ordering.
HTP	Highest takes precedence: the highest applicable value wins a merge.
Instance	A running playback created from a sequence, effect, or clip. Multiple instances can contribute output.
Layer	One contribution to the composed fixture output.
LTP	Latest takes precedence: the most recently asserted applicable value wins a merge.
Master	A control that scales intensity or playback speed for a defined scope.
Programmer	The working selection and live instructions used to create looks.
Release	Removal of a playback's contribution, potentially with a transition.
Sequence	Ordered cues with timing, tracking, setup, and release behavior.
Showfile	The saved collection of a show's fixtures, programming, routing, and associated state.
Speed	A multiplier on how fast a playback runs: ×2 runs twice as fast, ×½ half as fast. Set per clip, or for many playbacks at once with a speed master. Unlike some consoles, a speed master has no BPM of its own; the show has one tempo.
Timecode	A clock position used to coordinate time-based playback.
Tempo	The show's beats per minute, set by tapping or typing in the Tempo panel.
Timing	Whether an effect's or sequence's times are Seconds, which run on the clock, or Beats, which follow the show tempo.
Timeline	Tracks of actions scheduled against a linked timecode.
Tracking	Carrying earlier attribute values into later cues that do not explicitly change them.
Universe	A bank of 512 DMX channels.

Nightfall User Manual