<commit_before>= MIDI Mapping and Beat Sync
<NAME> <<EMAIL>>
:icons: font
:experimental:

// Set up support for relative links on GitHub; add more conditions
// if you need to support other environments and extensions.
ifdef::env-github[:outfilesuffix: .adoc]

Afterglow is designed to work with MIDI controllers and DJ equipment.
You can bind physical controller elements to trigger cues and adjust
show variables, and sync the BPM of the show master metronome to MIDI
clock pulses from a DJ controller or mixer. (Although if you have
professional Pioneer gear, you are better off syncing the metronome to
the Pro DJ Link via an Ethernet cable.)

NOTE: These examples assume you are in a Clojure REPL with Afterglow loaded,
in the namespace `afterglow.examples`. This is the default namespace you
get if you check out the project and run `lein repl`. The sample show is
assumed to be running; if not, `(show/start!)`

== Mapping Cues to a Controller

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 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.

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
<<finding-mapping-details,below>>. Once you have the cue created and
the control identified, you can create the mapping using
http://deepsymmetry.org/afterglow/doc/afterglow.show.html#var-add-midi-control-to-cue-mapping[afterglow.show/add-midi-control-to-cue-mapping], like:

[source,clojure]
----
(show/add-midi-control-to-cue-mapping "nano" 0 :control 46 0 6)
----

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.

If the controller has LEDs associated with the controls, and you can
configure it so that its LEDs are in external control mode, Afterglow
will even give you feedback about when the cue is running, by lighting
up the pad or button when the cue starts (whether or not you started
it using this controller), and darkening it when the cue ends.

== Mapping a Control to a Variable

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
https://github.com/brunchboy/afterglow/blob/master/doc/cues.adoc#cue-variables[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 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):

[source,clojure]
----
(show/add-midi-control-to-var-mapping
  "Slider" 0 16 :knob-1 :max 360)
----

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

[source,clojure]
----
(show/add-effect! :color (global-color-effect
  (params/build-color-param :s 100 :l 50 :h :knob-1)))
----

== Finding Mapping Details

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...

[source,clojure]
----
(afterglow.midi/identify-mapping)
----

...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:

[source,clojure]
----
; -> {:command :control-change, :channel 0, :note 32, :velocity 127,
;     :device {:name "SLIDER/KNOB",
;              :description "nanoKONTROL2 SLIDER/KNOB"}}
----

____
Notice that even for control changes, the controller number is
identified as `:note` (32 in this example).
____

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

[source,clojure]
----
; -> nil
----

If this happens, remember that you need to have all of your MIDI devices
hooked up before you start Afterglow, because of limitations in the Java
MIDI implementation. Try quitting and restarting Afterglow. If that
doesn’t help, you will need to troubleshoot your MIDI setup.

NOTE: These examples show how to perform low-level MIDI mapping. Over
time, you might find that someone has written a rich user interface
binding for your controller, as is happening for the
http://deepsymmetry.org/afterglow/doc/afterglow.controllers.ableton-push.html[Ableton
Push], which would let you jump right in without having to worry about
such details. These examples can still help explain how your
controller's binding works, or encourage you to write and share a
binding for a new controller that you happen to have.

== Syncing to MIDI Clock

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
<<syncing-to-pro-dj-link,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.

____
TODO: Explain how to set Traktor up to send MIDI clock.
____

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:

[source,clojure]
----<commit_msg>Add link to Traktor config article.<commit_after>= MIDI Mapping and Beat Sync
<NAME> <<EMAIL>>
:icons: font
:experimental:

// Set up support for relative links on GitHub; add more conditions
// if you need to support other environments and extensions.
ifdef::env-github[:outfilesuffix: .adoc]

Afterglow is designed to work with MIDI controllers and DJ equipment.
You can bind physical controller elements to trigger cues and adjust
show variables, and sync the BPM of the show master metronome to MIDI
clock pulses from a DJ controller or mixer. (Although if you have
professional Pioneer gear, you are better off syncing the metronome to
the Pro DJ Link via an Ethernet cable.)

NOTE: These examples assume you are in a Clojure REPL with Afterglow loaded,
in the namespace `afterglow.examples`. This is the default namespace you
get if you check out the project and run `lein repl`. The sample show is
assumed to be running; if not, `(show/start!)`

== Mapping Cues to a Controller

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 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.

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
<<finding-mapping-details,below>>. Once you have the cue created and
the control identified, you can create the mapping using
http://deepsymmetry.org/afterglow/doc/afterglow.show.html#var-add-midi-control-to-cue-mapping[afterglow.show/add-midi-control-to-cue-mapping], like:

[source,clojure]
----
(show/add-midi-control-to-cue-mapping "nano" 0 :control 46 0 6)
----

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.

If the controller has LEDs associated with the controls, and you can
configure it so that its LEDs are in external control mode, Afterglow
will even give you feedback about when the cue is running, by lighting
up the pad or button when the cue starts (whether or not you started
it using this controller), and darkening it when the cue ends.

== Mapping a Control to a Variable

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
https://github.com/brunchboy/afterglow/blob/master/doc/cues.adoc#cue-variables[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 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):

[source,clojure]
----
(show/add-midi-control-to-var-mapping
  "Slider" 0 16 :knob-1 :max 360)
----

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

[source,clojure]
----
(show/add-effect! :color (global-color-effect
  (params/build-color-param :s 100 :l 50 :h :knob-1)))
----

== Finding Mapping Details

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...

[source,clojure]
----
(afterglow.midi/identify-mapping)
----

...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:

[source,clojure]
----
; -> {:command :control-change, :channel 0, :note 32, :velocity 127,
;     :device {:name "SLIDER/KNOB",
;              :description "nanoKONTROL2 SLIDER/KNOB"}}
----

____
Notice that even for control changes, the controller number is
identified as `:note` (32 in this example).
____

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

[source,clojure]
----
; -> nil
----

If this happens, remember that you need to have all of your MIDI devices
hooked up before you start Afterglow, because of limitations in the Java
MIDI implementation. Try quitting and restarting Afterglow. If that
doesn’t help, you will need to troubleshoot your MIDI setup.

NOTE: These examples show how to perform low-level MIDI mapping. Over
time, you might find that someone has written a rich user interface
binding for your controller, as is happening for the
http://deepsymmetry.org/afterglow/doc/afterglow.controllers.ableton-push.html[Ableton
Push], which would let you jump right in without having to worry about
such details. These examples can still help explain how your
controller's binding works, or encourage you to write and share a
binding for a new controller that you happen to have.

== Syncing to MIDI Clock

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
<<syncing-to-pro-dj-link,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.

TIP: Native Instruments has an informative Knowledge Base article
which
http://www.native-instruments.com/en/support/knowledge-base/show/750/how-to-send-a-midi-clock-sync-signal-in-traktor/[explains]
how to configure Traktor to send the MIDI clock pulses that Afterglow
can sync to.

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:

[source,clojure]
----
{'fraction_non_alphanumeric': 0.06315954037364184, 'fraction_numerical': 0.0063315875869616196, 'mean_word_length': 4.150563607085346, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6847943', 'n_tokens_mistral': 3763, 'n_tokens_neox': 3501, 'n_words': 1936}