README.adoc

Afterglow Documentation

To keep page sizes manageable, this information is split into several pages. This page provides an introduction and overview, explains the built in web interface, and links to other sections as needed. It is worth reading through this whole page once if you are new to Afterglow, because the orientation it provides will be helpful, and it ends with a guide to help you get started on your way to creating your own light show. Once you know what you are looking for, you can also dive right into it by jumping to the page you want:

Effects	The building blocks of a dynamic light show, which have a lifecyle worth understanding, and a few examples to get you started.
Dynamic Parameters	Provide inputs to your effects which change over time and space, enabling much more interesting and complex appearance and behavior.
Cues	Provide a convenient way to organize and trigger effects.
Metronomes	Keep track of musical time, in terms of beats, bars, and phrases, and can be synced to DJ equipment and software.
Oscillators	Convert show timing information into waveforms that can drive your light show.
Fixture Definitions	Tell Afterglow how to work with different lighting hardware.
Show Space	Explores how to measure locations and orientations when hanging your lights so that Afterglow can properly calculate spatial and directional effects.
Working with Color	Introduces tools for expressing and manipulating color values when designing lighting effects.
Mapping and Sync	Looks at options for using MIDI controllers to run your show, and synchronizing its metronome with DJ equipment.
The Rendering Loop	Explains in detail how a frame of lighting control data is calculated and sent to the lights in the show. This is advanced, low-level information for people who are ready to create their own custom effect algorithms.

What is Afterglow?

Afterglow is a lighting controller designed to support live coding, written in Clojure, intended to enable people to produce spectacular and highly customizable light shows using modern stage and effect lighting, and which are related in deep ways to the phrasing of music being played. (Its creator is a DJ and producer of light and laser shows by avocation.) Currently, the lighting effects and fixture definitions are written and organized through Clojure code, so you will either need to learn Clojure or work with a Clojure programmer to create new ones, but they are controlled through MIDI control surfaces or Open Sound Control, so once they are set up, there is great flexibility in how you can perform them.

Someday a user interface for building shows and fixture definitions may be created, either within Afterglow, or as a companion project, but that is not currently planned. For now the focus is on building rich user interfaces for controlling shows, such as the Ableton Push mapping and web interface, while using the concise expressive power of Clojure for writing the fixture definitions, effects, and cues.

Afterglow communicates with the lighting hardware using the Open Lighting Architecture, so it supports a wide variety of communication methods and interfaces. Information about installing OLA is included in the project README.

How Afterglow Works

The fundamental task of Afterglow is to make light shows happen. It does this by controlling lights, communicating with them through the Open Lighting Architecture, which can work with several kinds of control protocols, most of which are derived from DMX512, or a faster implementation of its basic ideas over Ethernet. When a show is running, Afterglow runs a thread which periodically asks “what should all the lights be doing now?” (resulting in a single “frame” of control values representing that moment in time), and sends the results of that analysis to all of the OLA universes the show is configured to control. By default this happens thirty times each second, but the interval is configurable within the show, and should be decided based on the fastest refresh rate of any physical interfaces you have hooked up to Afterglow. This is described in more detail in the Rendering Loop section.

Tip	In principle you could have more than one show running at a time, each controlling a different set of OLA universes, but most people will not need this capability.

When you just create a show and call (show/start!), Afterglow will send a bunch of zero values to the show’s universes. To make interesting things happen you add Effects to the show. The default namespace you are put into when you launch the Afterglow project using lein repl has some example effects that can help get a feel for this concept. To get a full understanding of how to use (and create) effects, learn about the Effect Lifecycle.

The effects need to know what lights they are supposed to control, what capabilities they have, and how they are connected (what universe, what channels), as well as how they are arranged in space. This is accomplished by patching Fixture Definitions to the show. To work with the actual lights you have available, you will need to create fixture definitions for them, unless they happen to be ones already available in the Afterglow project. Since there are so many kinds of lights, with more being created every month, that seems unlikely unless the project really takes off… and, to that end, if you do create definitions for your lights, please contribute them to the project!

To learn how to install Afterglow and the Open Lighting Architecture, see the project README.

Since Afterglow was developed to create light shows for electronic music events, it is deeply driven by the notion of musical time, through its Metronomes, so it is worth learning how to configure and interact with them. It is also designed to work with MIDI controllers, both to trigger effects, and to synchronize with music, as described in MIDI Mapping and Beat Sync.

Of course, you are not going to want to have to type and evaluate Clojure expressions to create your effects in the heat of the moment of running a light show, so Afterglow shows incorporate a grid of Cues that you can trigger and adjust quickly, both through the embedded web interface described below, and with dedicated physical grid controllers or simpler MIDI controllers.

The Embedded Web Interface

Although a physical grid controller (especially one as well-designed as the Ableton Push) offers the ideal control surface for running a light show, you can do a lot with just the web interface built in to Afterglow. And even when you have a Push or other grid controller, the web interface makes it all the more powerful by adding at-a-glance documentation of cue names, as well as alternate ways of doing things, or the opportunity to interact with more than one section of the cue grid at once.

If you have started Afterglow by running the jar file, it will have opened a browser window on the web interface by default. Otherwise, you can bring it up by evaluating:

(core/start-web-server 16000 true)

Tip	The 16000 specifies the port number on which the web interface will run. You can use a different port number if you want: just pick an unused port and type it instead. The true requests the browser window; it will be opened on whatever port you told the web interface to use.

The home page offers some buttons which can take you to this documentation, the Open Lighting Architecture console in case you want to monitor DMX values or configure the universe(s) that your show will be using, and an embedded web REPL that can be used to evaluate arbitrary expressions to configure and control Afterglow. The primary interface, however, is the show page, which is reached by a link in the Shows section. However, when you first start Afterglow on its own, there will be no shows running. The Console can be used to change that:

Note

As menioned in the main project Readme, the web console is there for quick hacks, and is no substitute for a rich Clojure development environment. For any real work you will want to either start Afterglow from your development REPL in the first place, or to connect it via nrepl if you have launched Afterglow independently, such as through a jar file. Afterglow can offer an embedded nrepl server, which can be brought up via either command-line arguments, or by using the web console to invoke core/start-nrepl.

Show Control

Once you have the web interface open, and a show running, you will spend most of your time on the show page. Here is the bottom left corner of the cue grid that gets created for the sample show by afterglow.examples/make-cues:

There are a number of different things you can control from this page. The load indicator in the middle of the navigation bar gives you a sense of how much headroom your system has, by showing you what fraction of the time available for rendering the last few frames of lighting effects was used up. As you add more complex effects, the bar will fill in and turn red, warning you if Afterglow might not be able to keep up.

The red Stop button next to it can be used to temporarily shut down the show, blacking out all universes that it controls. Clicking it again restarts the show where it would have been had it not stopped. If there is a problem communicating with the Open Lighting Architecture daemon, the status indicator will show Error, and there will be a Details button you can click to get more information about the problem Afterglow is encountering.

Cues

The majority of the page is taken up by an 8×8 window on to the Cue grid attached to the show. You can activate any cue shown by clicking on it; running cues will light up, and darken again when they end. To stop a running cue, click it again. Some cues will end immediately, others will continue to run until they reach what they feel is an appropriate stopping point. While they are in the process of ending, the cue cell will blink. If you want the cue to end immediately even though it would otherwise run for a while longer, you can click the blinking cue cell and it will be killed right then.

The text labels within the cue cells are to help identify their purpose, and are established when the cues are created. Similarly, the colors are intended to help identify related cues.

Some cues (especially intense ones like strobes) are configured to run only as long as they are held down. In that case, when you click on the cue cell, a whitened version of its color is displayed as a hint that this is happening, and as soon as you release the mouse, the cue will end. If you want to override this behavior, you can hold down the Shift key as you click on the cue cell, and it will activate as a normal cue, staying on until you click it a second time.

Cues may be mutually exclusive by nature, and if they were created to reflect this (by using the same keyword to register their effects with the show), when you activate one, the other cues which use the same keyword are dimmed. This is a hint that when you activate one of them, it will replace the others, rather than running at the same time. In the image above, the “All Sine Bar”, “All Saw Up 2 Beat”, and “All Saw Down Beat” cues are dimmed because they would replace the running “All Dimmers” cue.

Scrolling and Linked Controllers

The show may have many more cues than fit on the screen at once; the diamond of blue arrows at the bottom right allow you to page through the larger grid. If there are more cues available in a given direction, that arrow will be enabled, otherwise it is dimmed. Clicking an active arrow scrolls the view one page in that direction. In this grid, it is currently possible to scroll up and to the right.

If you have any grid controllers you can attach them to the show. An Ableton Push would be bound as follows:

(require '[afterglow.controllers.ableton-push :as push])
(def controller (push/bind-to-show *show*))

Once this was done, you would see a link menu appear next to the scroll diamond, as shown in the above screen image. The link menu allows the web interface to be tied to a grid controller, so that each is always looking at the same page of cues. Using the scroll arrows on either the web interface, or on the controller itself if it has them (the Push does), will cause both to scroll simultaneously. This provides an excellent additional layer of information about the buttons on the physical controller.

Tip	Of course, there may be times you want to break this link, for example so you could have access to one set of cues on the physical buttons of your controller, while simultaneously being able to control others via the screen and mouse. To do that, simply use the link menu to turn off the link.

Metronome Control

The final section of the show control interface lets you view and adjust the Metronome that the show is using to keep time with the music that is being played. Since Afterglow’s effects are generally defined with respect to the metronome, it is important to keep it synchronized with the music. The metronome section shows the current speed, in Beats Per Minute, of the metronome, and the Tap Tempo button label flashes yellow at each beat. It also shows you the current phrase number, the bar within that phrase, and beat within that bar which has been reached.

The most basic way of synchronizing the metronome is to click the Tap Tempo button at each beat of the music. After a few clicks, the metronome will be approximately synchronized to the music. You can also adjust the BPM by dragging the slider along the bottom, or fine-tune it with the + and - buttons around the current BPM value.

In order to make longer chases and effects line up properly with the music, you will also want to make sure the count is right, that the beat number shows 1 on the down beat, and that the bar numbers are right as well, so that the start of a phrase is reflected as bar number 1. You can adjust those with the + and - buttons around the Bar and Beat numbers. A shortcut that you can use right as a phrase begins is to click the red x button above the phrase number, which resets the metronome to Phrase 1, Bar 1, Beat 1.

Trying to keep up with tempo changes during dynamic shows can be very difficult, so you will hopefully be able to take advantage of Afterglow’s metronome synchronization features. If you can get the DJ to feed you MIDI clock pulses or connect via a Local Area Network to Pioneer professional DJ gear to lock into the beat grid established by Pro DJ Link, Afterglow can keep the BPM (with MIDI) and even the beats (with Pro DJ Link) synchronized for you. To configure that synchronization, click the Sync button once you have the MIDI clock or network Pro DJ Link signals reaching the machine running Afterglow, and choose the sync source you want to use.

Tip	When you are synchronizing with Pro DJ Link, you will almost always want to sync to the mixer, rather than one of the CDJs, so you stay in sync as the DJs mix between tracks.

The actual list of choices you will see depends on what MIDI and DJ Link Pro traffic Afterglow has seen in the last few seconds, and will update as players and mixers start and stop sending clock or beat grid information.

Note

Limitations in the Java MIDI drivers (at least on the Mac) currently require any MIDI devices, whether real or virtual, to be connected when Afterglow first starts in order for them to be visible. We may write our own MIDI provider extension to resolve this issue, but it will involve a lot of tedious JNI code, and so far we have not wanted to delay other aspects of Afterglow to tackle this side project. It would be nice if Oracle solved this long-standing issue themselves, but they keep postponing it. DJ Link Pro does not suffer from such limitations.

Once your sync is established, the Tap Tempo button changes. If you are using MIDI clock to sync the BPM, it becomes a Tap Beat button, which simply establishes where the beat falls. If you are locked in to a Pro DJ Link beat grid, it becomes a Tap Bar button which, when pressed, indicates that the current beat is the down beat (start) of a bar. Similarly, if you press the metronome Reset button (the red x above the phrase counter) while synced to a Pro DJ Link beat grid, the beat itself will not move, but the beat closest to when you pressed the pad will be identified as Beat 1.

The Sync button also turns green to indicate that sync is in effect. If something interrupts the sync process (such as the network link being broken, or the DJ software’s MIDI clock generator being turned off), the button will turn red to warn you that it is not working. Pressing the Sync button again will give you more information to troubleshoot the problem.

Getting Started

There is a lot to Afterglow, and already a lot of documentation. In an effort to help you find your way through it, here is a guide to the steps you’ll want to take to get a basic light show up and running. Once you are there, you can branch off and explore extending it in any direction you like, and hopefully contribute back the fixture definitions and new effects and cues you come up with!

1. If you don’t know any Clojure, you are going to want to learn at least a little. Luckily, it is a fantastic, helpful community, and an amazing language (the existence of Afterglow after a couple of months of spare time work is good proof of that)! The Getting Started page on clojure.org has links to some great resources. Don’t miss Clojure for the Brave and True, a fun book under development which can be read in its entirety online.

2. Install Afterglow. For now the best way to do that is following the steps in the Installation section on the main project page, to install the Open Lighting Architecture, then create a new Clojure project with Leiningen that includes Afterglow as a dependency.

3. Set up your universe(s) in OLA. Their own Getting Started page may be helpful. Until OLA is successfully communicating with your lights, whether over a USB DMX interface, Artnet over a LAN, or the like, Afterglow will not be able to control them. Even though their examples show using the command-line tools to configure your interface, today you will likely find the web interface, especially the beta new UI, much more convenient and easy to learn. With a default installation, once you have olad running, you can find that at http://localhost:9090/new/.

4. Find or create fixture definitions. Once you are able to get your lights to do things by manipulating the Faders section of the OLA web interface, it is time to get Afterglow ready to talk to them. There are a vast number of fixture types out there, and at this early stage almost none of them are built in to Afterglow, so you will probably need to create your own. The documentation explains how, and links to existing fixture definitions as examples. You can also ask for help on the wiki.

At this point you are almost certainly writing enough code that you want to save it for later reuse. The Usage section of the project page explains how you can have Afterglow load files when it starts up when you are running it as a standalone jar, which makes it easier to use your own configuration files.

1. Patch your actual fixture channels and locations. Once you have working definitions for your fixtures, you will want to create a show that tells Afterglow what fixtures you have, and the DMX universes and channels you have them connected to, and how you have them arranged in physical space. You will want to create a namespace for your show along the lines of afterglow.examples, and a function like use-sample-show which sets up your own show.

2. Create the cues you want. Much as the make-cues function in the examples namespace creates a bunch of cues that work with the sample show’s fixtures, you will want cues that create effects to make your lights do interesting things, and which are arranged, labeled, and colored in a way that makes sense to you.

3. Map some cues to a controller, if you have one. If you have an Ableton Push, you are in luck because you will be able to take advantage of the built in support Afterglow offers. But even if you just have a simple MIDI controller with a few buttons and faders, or even a keyboard, you can map keys, buttons, and faders to do trigger cues and adjust variables used by the cues.

4. Run the show! With or without a physical controller, you can create your show by calling the function you wrote modeled on use-sample-show, then bring up the embedded web interface to trigger your cues and watch the results.

5. Create your own custom effects if you want to be fancy. Once you feel constrained by the limits of the effects that are built in to the current release of Afterglow, the whole point of the environment it offers is to enable people to imagine and create brand new effects. You have the full power of the language used to create Afterglow at your fingertips at every moment to create and explore new ideas; you are not constrained to the limited scripting environment that most lighting control software offers, if it offers any at all.

6. Don’t forget to contribute your fixture definitions and effects to the Afterglow community! If you are confident that you have fully mapped out the functions of a fixture, please make a pull request to include it in afterglow, either within the existing namespace for its manufacturer, or creating a new namespace for a new manufacturer. Similarly, if you have created an awesome new kind of effect, please consider a pull request to add it somewhere within the effects namespace hierarchy. And if you are just tinkering with something new and experimental, please post about it on the wiki!

License

Copyright © 2015 Deep Symmetry, LLC

Distributed under the Eclipse Public License 1.0, the same as Clojure. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software. A copy of the license can be found in resources/public/epl-v10.html within this project.