Skip to content


James Elliott edited this page Apr 8, 2016 · 20 revisions

If you are having trouble getting started, or with any aspect of Afterglow, your fastest option is probably to ask questions in the Afterglow room Gitter, but for longer-term community documentation please edit this page and ask here. (If you aren’t seeing a response, you can also email the author, but starting here might help others in the future.) As categories of questions reveal deficiencies in the main documentation, that will also evolve and improve.

Getting Started

OLA and Windows

It wasn't until well after the first couple releases of Afterglow that I noticed that there is not yet a Windows port of the Open Lighting Architecture. That possibility never occurred to me; I am so used to the Mac being late to the porting party.

All is not lost, however. Even though Afterglow was designed with the idea that it would be talking to a local OLA daemon, and that remains the most efficient option, you do not need to port OLA to windows yourself, or wait for someone to do that. Afterglow now supports configuration options to let you run OLA on a different host. You can follow the Open Lighting Architecture's guidelines for how to work with it in Windows. There are three choices:

  1. Run OLA in a virtual machine. This is probably the fastest way to get started, but will not give you ideal performance, and may have issues communicating with USB DMX interfaces, so a more practical and supported choice is to:

  2. Run OLA on a Raspberry Pi. This will set you back around $50 in hardware and a little setup time to get the Linux and OLA image booting, but will let you actually run Afterglow light shows from Windows even in the absence of a finished OLA port.

  3. Run OLA on some other Linux machine or Mac you have lying around, even when you are running Afterglow on Windows.

In any of these scenarios, you need to configure Afterglow to know where to find the OLA daemon, and make sure there is a fast, reliable network connection to it. As noted above, current builds of Afterglow support this, and here is how you do it:

(require 'afterglow.ola-client)
(reset! afterglow.ola-client/olad-host "")

Of course you would use the actual address of the machine you have olad running on in place of the in the example. As long as you do this at startup, before you try to create and start any Afterglow shows, it will find the OLA daemon at the address you have specified.

If, for some reason, you have olad configured to listen to a port other than its default of 9010, you can configure that in a similar way:

(require 'afterglow.ola-client)
(reset! afterglow.ola-client/olad-host "")
(reset! afterglow.ola-client/olad-port 12345)

If you need to change only the port, because you are running olad locally but on a nonstandard port, simply omit the line which sets olad-host.

I don't have any Windows machines to test this stuff on, so if anyone succeeds at getting Afterglow up and running in a configuration like this, please share details about your efforts, and correct anything that may be wrong in these instructions.

MIDI from Java on the Mac

Unfortunately, there are some long-standing bugs in the Java MIDI implementation on the Mac, and Oracle has continued to kick the problem down the road. The most serious issue is that System Exclusive messages do not work at all, which means that there is no way to update the text display on the Ableton Push controller, making the Afterglow binding for it far less useful. Another frustrating limitation is that there is no way to communicate with devices that were not already connected to your system when you launched Afterglow.

Both of these problems have been fixed on Java 7 or later by Afterglow embedding the CoreMIDI4J MIDI Service Provider Implementation. As long as you are using Java 7 or later, CoreMIDI4J will be loaded and used for communicating with MIDI devices, allowing you to properly control the Push display, and connect and remove devices without having to shut down and restart Afterglow.

CoreMIDI4J is in early release right now, and the developer of Afterglow has been helping finish and test it. It is already the best answer for working with MIDI in Java on the Mac, and we expect it to get even better over time. And since it is open source, others will be able to fix it in the future if its current developers are unavailable.

What about Java 6?

If you need to work with Java 6 on the Mac, for example in Max/MSP, you can use the Humatic MMJ MIDI driver. Even though their web page optimistically thought in 2009 that their driver was no longer needed, that is sadly still not true in 2016 if you can’t use CoreMIDI4J. Place the downloaded mmj.jar and libmmj.jnilib in your /Library/Java/Extensions/ folder before starting Afterglow, and it will be loaded and used for communicating with the Ableton Push.

The MMJ implementation has fallen behind OS releases, and no longer supports hot-plugging of MIDI devices. So you will need to have all MIDI controllers that you want to use with Afterglow connected before you start it. If you can use Java 7 or later, you are much better off with the current, supported CoreMIDI4J solution.

If you need to work both with Max/MSP and more modern Java MIDI environments, you can install both MMJ and CoreMIDI4J, and Afterglow will use the best option it can find. But if you have no need to work in a Java 6 environment, it is slightly more efficient to avoid installing MMJ (or remove it, if you have already installed it).

Defining Fixtures

If you are working on a fixture definition and looking for help, try pasting your efforts so far here. And once it is working great, definitely put it here so we can add it to Afterglow (or submit it as a Pull Request if you know how to put one together, to be even more helpful).

:star2: Note that as of version 0.1.3, Afterglow can translate fixture definitions from QLC+, which has a whole bunch of them. This could get you most of the way there if your fixture is supported by QLC+!

A simple RGB fixture

dandaka asked in Issue #5 for some help in mapping a fixture of his:

For example, I have RGB LED light on universe 1 on 1,2,3 DMX channels.

This will be a common kind of request: Unfortunately, every fixture is completely different, so there is no way we can include examples of how to work with fixtures you actually have, unless you are incredibly lucky. As time goes on, we will include examples of more and more fixtures, but it also helps that we can now translate the hundreds of fixture definitions that exist for QLC+. The code in american-dj.clj, blizzard.clj and chauvet.clj are examples of fixture definitions for the lights that I have here or have had access to so far in clubs nearby. Some of them are pretty complex, but by comparing the Clojure code to the DMX charts in the manuals (linked in the source code where available), hopefully they can help show how it is done.

The Chauvet file has some of the simplest fixture definitions in it. The Geyser RGB fogger might be the best starting point for this question: even though it has a few extra channels, we can use it as an example, since its red, green, and blue channels are easy to see. If your light really only has a red, green, and blue intensity channel and nothing else, it could look something like the following (I will call it my-rgb since you did not tell me the brand or name, and note that I am typing this right into the browser, so the code may well have mistakes):

(defn my-rgb
  "A simple RGB light"
  {:channels [(chan/color 1 :red)
              (chan/color 2 :green)
              (chan/color 3 :blue)]
   :name "Simple RGB"})

If that is the correct set of channels, and the correct order for them, once you have loaded this function definition, you can patch it into your show universe 1 at DMX address 1, giving it the identifier :rgb-1 as follows:

(show/patch-fixture! :rgb-1 (my-rgb) 1 1)

Now, if this light has additional channels, or perhaps different modes which add channels, let me know and we can talk about how to extend the fixture definition to include them as well.

Patching Fixtures into Shows

Creating Cues

Running Cues

Creating Effects

Mapping Controllers

Clone this wiki locally
You can’t perform that action at this time.