MIDI Mapping and Beat Sync

Although the most convenient and powerful way of running cues with Afterglow is to use a large grid controller with color feedback (like the Ableton Push or Novation Launchpad Pro, which can mirror the cue grid of the web interface) you can still accomplish a great deal with a simple controller with a few buttons. You will still want to start by creating the cues in the show cue grid, not only so you can see and manipulate them with the web interface, but also because that is how they can be mapped to MIDI controllers. (The rich Push and Launchpad family mappings are described in detail on their own pages.)

First you need to identify the MIDI messages that the controller sends when you press and release the interface element you want to assign the cue. Afterglow can help with that too, as described below. Once you have the cue created and the control identified, you can create the mapping using afterglow.effects.cues/add-midi-to-cue-mapping, like:

This would cause Afterglow to start or stop the cue at grid position (0, 6) when a pad on the device named "nano" is pressed and sends a MIDI control change message on control number 46. See the documentation for details on all the arguments.

If you want to be able to later remove this cue mapping, be sure to save the value returned by add-midi-to-cue-mapping in a variable, because you will need to pass it to remove-midi-to-cue-mapping. Or you can simply disconnect the controller from your system, and Afterglow will clean up any mappings that had been assigned to it.

Also be sure to see the section below that explains how you can arrange to have afterglow automatically call the relevant MIDI mapping functions to set up your device whenever it is connected.

You can also tie an encoder or fader on a MIDI control surface to a show variable, so that turning the encoder or sliding the fader changes the value of the variable. If you have set up cues to look at that variable, through cue-specific variable bindings, the control surface can then vary the look of the effect created by the cue, both before the cue is launched, and while it is running.

Here is a lower-level example of how I can use add-midi-control-to-var-mapping have a knob on one of my simple MIDI controllers set the hue of all the lights. It shows up with a MIDI port name of SLIDER/KNOB, and its first rotary controller is control 16 on channel 0. I can map that to set a show variable knob-1 to the values 0-360 (the legal hue values):

Then I can create a global color effect based on that variable:

It is also possible to perform arbitrary transformation of the MIDI value before storing it into the show variable, by passing add-midi-control-to-var-mapping a transformation function using the optional keyword argument :transform-fn. The function you supply will called with the MIDI value (already scaled, if you passed a value with :min or :max), and whatever it returns will be stored in the variable. Your function can contain whatever logic it needs, and does not even need to return a number. As a simple example, suppose you want to set up a :beat-ratio variable for configuring oscillators, and you want it to have the value 1, 2, 4, or 8, depending on how far a fader is raised. Since those are all powers of two, you could implement the varible binding like this:

If you want to be able to later remove this variable mapping, be sure to save the value returned by add-midi-control-to-var-mapping in a variable, because you will need to pass it to remove-control-mapping. Or you can simply disconnect the controller from your system, and Afterglow will clean up any mappings that had been assigned to it.

Also be sure to see the section below that explains how you can arrange to have afterglow automatically call the relevant MIDI mapping functions to set up your device whenever it is connected.

In the all-too likely event you don’t have all your MIDI port names and control channel and note numbers memorized, Afterglow can help. Just run…​

…​then twiddle the knob, slide the fader, or press the button you wish to map. Afterglow will report the first control-change or note message it receives:

If nothing is received for ten seconds, it will give up:

If this happens, and you are sure the device is connected, you will need to troubleshoot your MIDI setup. If you are on a Mac, and the device was not connected when you started Afterglow, be sure that you have installed CoreMIDI4J as discussed on the Afterglow Wiki.

You can tell Afterglow to watch for a particular device to be connected and call a function whenever it is present. This function can set up all of the MIDI bindings you want for that device. This is convenient because if the device is not there, nothing will happen (and there will be no errors), but if it is, the bindings will be set up. Even more importantly, in a performance context, if the device is accidentally disconnected or powered down, the bindings will be reconfigured as soon as it is reconnected.

To do this, set up a function like map-nano in the example below which creates all the MIDI bindings you want for your device, and then call afterglow.midi/watch-for to cause that function to be called whenever a device with a matching name or description is connected:

See the watch-for documentation for details about other ways you can configure it, such as adjusting how long it waits for the new device to stabilize before calling your function, and how to provide another function that gets called to clean up when the device is disconnected. You do not need to worry about cleaning up ordinary MIDI bindings, since Afterglow automatically does that whenever a device is disconnected, but if you have set up any of your own state that you would like to remove, you can use this mechanism to do so.

When you are working with colors for cues, Afterglow lets you put a color object in a show variable or cue parameter, rather than simply storing individual numeric components like the hue. Doing this lets the web and Ableton Push interfaces give the user a rich color picker interface for adjusting that variable or parameter, so it is usually a better approach than just storing the numbers that make up the color.

When you do that, you can still use any MIDI controller to adjust components of that color, using afterglow.controllers.color/add-midi-control-to-color-mapping.

Here is an example of how to tie the left six faders on one of my simple MIDI controllers to adjust all of the components that make up the color used by the sample show’s strobe effects. The controller shows up with a MIDI port name of SLIDER/KNOB, and its fader controllers are controls 0 through 7 on channel 0. Assigning the first six to adjust components of the strobe color looks like:

With this done, as I move the sliders on this MIDI controller, I can see the colors of the strobe cues in the web interface and on the Ableton Push and Novation Launchpad grids changing (and on the lights themselves if any strobe cue is running at the time).

The web interface and Ableton Push mapping have dedicated interfaces for controlling the show’s dimmer grand master, but you can map any MIDI controller fader or rotary controller to it, or to any other dimmer master that you have created to control your cues, using add-midi-control-to-master-mapping.

Here is an example of how to tie the leftmost fader on one of my simple MIDI controllers to the show’s dimmer grand master. The controller shows up with a MIDI port name of SLIDER/KNOB, and its first fader controller is control 0 on channel 0. I can map that to set the show grand master to the values 0-100 (the legal dimmer master values) by simply calling:

The rich grid controller bindings created for the Ableton Push and Novation Launch Pad provide very convenient metronome control using Tap Tempo buttons that flash on each beat of the show metronome, and respond to taps appropriately for any metronome synchronization (as described in the next sections) the show may have established.

Even if you don’t have such a controller, you can set up a button or pad on any MIDI controller you own to work the same way. Simply identify the mapping you need to interact with that button or pad as decribed above, then call afterglow.controllers.tempo/add-midi-control-to-tempo-mapping to set it up.

For example, to set this up for the Record button on a Korg nanoKONTROL2 controller, you can call:

From that point on, the Record button blinks on each beat of the show metronome, and when you press the button, it adjusts the tempo of the show. Assuming you have no metronone synchronization established for the show, tapping the button aligns the metronome to a beat, and if you tap it three or more times within two seconds of each preceding tap, sets the metronome’s BPM. Tap it as you hear each beat of the music, and after three or more taps, the speed of the metronome will be approximately synchronized with the music.

If the metronome’s BPM is already being synced automatically, via MIDI clock messages as described in the next section, then tapping the button will not change the BPM. Instead, it acts as a Tap Beat button, always moving the start of the current beat to match when you tapped the button.

If the metronome’s BPM and beat positions are both being synced automatically, either via the Traktor beat phase mapping or Pioneer Pro DJ Link (as described further below) then tapping the button acts as a Tap Bar button, telling Afterglow that the moment when you tapped the button is the down beat (the first beat of the current bar).

In addition to Tap Tempo buttons, the grid controllers have Shift buttons which modify the behavior of other buttons, including the Tap Tempo button. That can be very convenient, especially when you are not synced to a beat grid from Pioneer DJ Link Pro or Traktor, so you want to be able to set the tempo, the beat location, and the down beat. You can set up another button on your controller to act this way and work with your Tap Tempo button, but you need to map it before mapping the Tap Tempo button, so you can make use of it in setting up the Tap Tempo mapping.

To set up a Shift button on any MIDI controller you happen to have, start by identifying the mapping you need to interact with the button or pad you want to use, then call afterglow.controllers.tempo/add-midi-control-to-shift-mapping to set it up.

For example, to set this up for the Play button on a Korg nanoKONTROL2 controller, you can call:

Once you’ve done that, when you hold down that button Afterglow lights it up, and when you release it Afterglow darkens it. But more importantly, you can use the value it returned to set up a relationship between your Shift button and a Tap Tempo button:

This tells Afterglow to check the state of your Shift button whenever you it your Tap Tempo button. If the Shift button is not held down, the Tap Tempo button acts as described above, but if your Shift button is being held down, tempo taps act differently, synchronizing at one level higher.

So if your show metronome is unsynchronized, and the Tap Tempo button would normally align the beat or set the BPM, or if it is synchronized to MIDI clock and the button always simply aligns the beat, then tapping it while holding down your Shift key makes it act as a Tap Bar button, telling Afterglow that the moment when you tapped the button is the down beat (the first beat of a bar).

If the BPM and beat positions are both already being synced automatically, so the button would normally act as a Tap Bar button, then with Shift down it acts as a Tap Phrase button, telling Afterglow that the closest beat to when you tapped the button is the start of an entire phrase.

If you ever want to stop using the mapped buttons, there is a function to remove MIDI mappings. This would undo what we did above:

Simply detaching the MIDI controller also automatically removes any mappings that were created for it.

Many DJ mixers automatically send MIDI clock pulses to help synchronize to their BPM. Pioneer’s Nexus mixers send MIDI clock over both their physical MIDI connection, and over USB if you are connected that way, conveniently. But they offer far more useful sync information over the Ethernet port via Pro DJ Link packets, which Afterglow can also process.

If you are using a mixer or DJ software like Traktor which supports only MIDI clock sync, it is a lot better than nothing! Here is how to take advantage of it.

Once you have your MIDI clock pulses reaching the system on which Afterglow is running, start Afterglow. Because of limitations inherent in the Java MIDI API, only MIDI devices which were connected when the program started are available to it. Then, assuming you have only one device sending MIDI clock, you can just execute:

If there is ambiguity about which device’s MIDI clocks you want to process, Afterglow will complain. Resolve that by passing a device filter which matches the device you want to use. The simplest kind of filter you can pass is a string, which uniquely matches the name or description of the MIDI device that you want to sync to:

The documentation for afterglow.midi/filter-devices explains the other kinds of device filter you can use.

From then on, as the BPM of that device changes, Afterglow will track it automatically. To check on the sync status, you can invoke:

The calculated BPM of the synced show can be displayed like this:

It will bounce up and down near the actual BPM as clock pulses are received, but overall track the beat quite well. To get a rock-solid beat lock you need to have equipment that can provide Pro DJ Link syncing, as described below.

To shut down the syncing, just call sync-to-external-clock with no sync source:

If you are using Traktor as your source of MIDI clock synchronization, even though you cannot quite attain the kind of smoothly precise BPM lock as you can with Pro DJ Link, you can configure Traktor to send its beat phase information in a way that Afterglow can detect and analyze, giving you the same kind of beat grid synchronization.

In order to do that, download and unzip the Afterglow Traktor Controller Mapping, Afterglow.tsi, and import it into Traktor.

Following this procedure will create a Device named Clock, Afterglow within the Traktor Controller Manager:

Select and use that rather than the Generic MIDI device you would create in the process described in the Traktor Knowledge Base article linked above, and in addition to sending basic MIDI clock mesages, Traktor will send special MIDI messages that Afterglow will recognize and use to remain synchronized to the Traktor beat grid.

The way the Afterglow mapping works is that it sends out Control Change messages for all currently playing decks. These messages communicate the current beat phase on that deck. (Deck A is sent as controller 1, B as controller 2, C as controller 3, and D as controller 4). In order for Afterglow to know which deck to pay attention to if more than one is playing at the same time, whenever a different deck becomes the Tempo Master, a message identifying the new Master deck is sent out as a Control Change message on controller 0. (The same number to deck correspondence is used.) When no deck is Tempo Master, a Control Change with value 0 is sent on controller 0.

Whenever Afterglow detects a coordinated stream of messages on controllers 0 through 4 which are consistent with beat-phase information from this Traktor mapping, it offers that MIDI input device as a source of Traktor beat-phase synchronization, and if it is synchronizing a metronome with the MIDI clock messages on that port, will also synchronize the beats.

If you are working with Pioneer club gear, such as the Nexus line of CDJs and mixers, you can use Pro DJ Link to sync much more precisely. You just need to be on the same LAN as the gear (most easily by connecting an Ethernet cable between your laptop running Afterglow and the mixer, or a hub or router connected to the mixer. You don’t need to be connected to the Internet, the protocol works fine over self-assigned IP addresses. You just need to specify which device you want to use as the source of beat information, and that will generally be the mixer, since it will track whichever device is currently the tempo master (or perform BPM analysis if a non-DJ-Link, or even non-digital, source is being played). Like with MIDI sync, you can give a unique substring of the device name in the sync call:

As with MIDI, you can check on the sync status:

You can sync MIDI clock and respond to MIDI controller messages from hardware and software which is not directly attached to the machine running Afterglow. If you are on a Mac, this capability is built in, and can be configured using the Audio MIDI Setup utility (in the Utilities subfolder of your Applications folder). For Windows, you can install the excellent, free, and fully compatible rtpMIDI driver. Either of these approaches allow you to communicate with the network MIDI capabilities built in to iOS devices and applications.

If you are interested in using Open Sound Control (OSC) control surfaces with Afterglow, you should also check out the free TouchOSC package (also available for Android). The TouchOSC site also has a nice illustrated walk-through of setting up network MIDI communication.

To achive MIDI routing on a single machine, you need to set up a virtual MIDI bus. On the Mac you can use Core MIDI’s built-in IAC bus, and on Windows you could use the MIDI Yoke utility. You can find a good tutorial about the needed steps on the Ableton Live website.

An easy way to see how well your show is syncing the beat is to use the metronome-effect, which flashes a bright pink pulse on the down beat, and a less bright yellow pulse on all other beats of the show metronome. To set that up:

Then you can reset the metronome by hitting Return on the following command, right on the down beat of a track playing through your synchronized gear, and watch how Afterglow tracks tempo changes made by the DJ from then on:

When running live light shows you will almost certainly want to map a button on a MIDI controller to perform this beat resynchronization (although it is not necessary when you are using Pro DJ Link to synchronize with your mixer—but even then you will likely want the next two functions mapped, for realigning on bars and phrases). Here is how I do it for one of the buttons on my Korg nanoKontrol 2:

Then, whenever I press that button, the metronome is started at beat 1, bar 1, phrase 1.

You can add mappings to reset metronomes which are stored in show variables by adding the variable name as an additional parameter at the end of this function call.

As noted above, even when you have a rock solid beat sync with your mixer, you sometimes want to adjust when bars or phrases begin, especially when tricky mixing has been taking place. You can accomplish this by mapping other buttons with add-midi-control-metronome-align-bar-mapping and add-midi-control-metronome-align-phrase-mapping. These cause the MIDI control to call metro-bar-start and metro-phrase-start on the associated metronome to restart the current bar or phrase on the nearest beat, without moving the beat. This means you do not need to be as precise in your timing with these functions, so you can stay beat-locked with your synch mechanism, much like the “beat jump” feature in modern DJ software.

If the metronome flashes start driving you crazy, you can switch back to a static cue,

or even black things out:

Afterglow also embeds osc-clj so you can bind cues and variables to be controlled via Open Sound Control (OSC), using tools like hexler.net’s TouchOSC. The sample show in the afterglow.examples namespace uses this capability to offer wireless graphical X-Y-Z aiming of groups of moving heads:

The functions add-osc-cue-binding and add-osc-var-binding, and the ones near them in the namespace, show how this was done. They seem to work well enough that they will be fleshed out a bit and moved into a new OSC-support namespace in a future release of Afterglow. But for now, you can use them and tweak them as they are.

Afterglow ships with built-in mappings that take advantage of several excellent grid controllers. If you happen to own one, you are in luck! And if you don’t, reading about these capabilities may tempt you to buy one, or write a mapping for one that you own that is not yet supported.