Deprecated in favor of the more accurately named add-midi-to-cue-mapping.

Cause the specified cue from the *show* cue grid to be triggered by receipt of the specified note (when kind is :note) or controller-change (when kind is :control) message with a non-zero velocity or control value. This allows generic MIDI controllers, which do not have enough pads or feedback capabilities to act as a full grid controller like the Ableton Push, to still provide a physical means of triggering cues.

The device to be mapped is identified by device-filter. The first input port which matches using filter-devices will be used.

The desired cue is identified by passing in its x and y coordinates within the show cue grid.

Afterglow will attempt to provide feedback about the progress of the cue by sending note on/off or control-change values to the same controller when the cue starts and ends. The note velocities or control values used can be changed by passing in different values with :feedback-on and :feedback-off, and this behavior can be suppressed entirely by passing false with :feedback-on.

If the controller is pressure-sensitive and you would like to have the velocity information passed on to any cue variables which are configured to respond to it, pass true with :use-velocity. This is the default assumed if :use-velocity is omitted, and also enables responsiveness to aftertouch (polyphonic key pressure) messages, which can adjust the cue variable for as long as you are holding down the key or pad, if your controller sends them (and kind is :note).

If the controller is not pressure-sensitive, and you would like to have the cue react as if it was pressed with a particular velocity, you can pass a number from 0 to 127 with :use-velocity. Whenever the cue is activated, it will be activated with the specified velocity. If you pass :use-velocity with false, the cue will be activated with a default velocity. In any of these cases where use-velocity is not true, no attempt will be made to respond to aftertouch messages.

Afterglow assumes the control is momentary, meaning it sends a note off (or control value of 0) as soon as it is released, and a second press will be used to end the cue unless the cue uses the :held modifier to indicate it should be ended when the button is released. If your controller does not have momentary buttons and already requires a second press to turn off the note or control value, pass false with :momentary? and Afterglow will always end cues when it receives a control value of 0, even if cues are not marked as :held.

Returns the cue-triggering function which can be passed to remove-midi-to-cue-mapping if you ever want to stop the MIDI control or note from affecting the cue in the future.

Call the specified function merging all keys and values from the supplied cue variable map to the end of the provided argument list. Useful when creating an effect with optional keyword arguments whose values are being set by cue variables bound to the appropriate keys.

Creates a cue that runs an arbitrary chunk of Clojure code instead of starting an effect, for example to reset the metronome if the controller mapping doesn’t have a dedicated button for doing that.

The code argument must be a function that takes two arguments. It will be called with the show and metronome snapshot when the cue is started, and should return immediately, because this takes place on the effect rendering pipeline, so any lengthy operations must be performed on another thread. The effect won’t do anything else after calling code once, but the cue is configured to keep it “running” until you let go of that grid controller pad, so you can see visual feedback that it ran.

The label argument is a string which is used to identify the cue in the cue grid.

The optional keyword argument :color requests that the web interface and control surfaces draw the cue using the specified color rather than the default white to help the user identify it. This is only a request, as not all control surfaces support all (or any) colors. The color is passed to interpret-color, so it can be specified in a variety of ways.

Builds a dynamic cue color function which reports the color of a cue based on the content of a cue variable, given the cue variable map.

When the cue is running, we look up the value of the specified cue variable, and return that. If the variable is nil, the non-dynamic cue color is returned.

When the cue is not running, we try to look up the saved value for the variable if the cue’s x and y grid coordinates were supplied. If a saved value can be found for the variable, that color is returned. Failing that, we check whether the variable is a permanent show variable, which we can look up even when the cue is not running. If so, and the variable has a non-nil value, we return that color. Again, if all else fails, we return the non-dynamic cue color.

Builds a dynamic cue color function which reports the color of a cue based on the value of a dynamic parameter. If the parameter evaluates to nil, the non-dynamic cue color is returned.

Creates an effect which launches the specified cues from the grid, stays running as long as they are, and ends them all when it is asked to end. Takes a list of three-element tuples identifying the x and y coordinates within the cue grid of the subordinate cues to launch, and an optional map of cue variable overrides, which can be used to change the initial values of any temporary variables introduced by that cue.

Creates a cue for managing in a cue grid. show-key will be used as the effect keyword when the cue is triggered to add it to a show, ending any existing effect that was using that key. effect-fn is a function that will be called to obtain the effect to be started and monitored when this cue is triggered. It will be passed a map allowing lookup of any temporary variables introduced by the cue (see the :variables parameter below).

If supplied, :short-name identifies a compact, user-oriented name to be displayed in the web interface or controller display (if it has one) to help identify the cue, which can be helpful if the name of the underlying effect is ambiguous or overly long.

:color requests that the web interface and control surfaces draw the cue using the specified color rather than the default white to help the user identify it. This is only a request, as not all control surfaces support all (or any) colors. The color is passed to interpret-color, so it can be specified in a variety of ways. If omitted, a default color of white is used.

:color-fn, if present, is a function that will be called to determine the current color to be used in user interfaces for cues that have variable colors. This function will be called with the cue, the currently-running effect launched by that cue (if any), as returned by show/find-effect, the show, and metronome snapshot representing the time at which the user interface is being updated. If it returns a value, that will be used rather than the static color in :color. If it returns nil, :color is used instead. As with :color, the presence of this function is only a request, not all user interfaces support dynamic cue colors.

:end-keys introduces a sequence of keywords identifying other effects which should be ended whenever this one is started. This allows a set of grid cues to be set up as mutually exclusive, even if they use different keywords within the show for other reasons.

:priority assigns a sorting priority to the effect. If not assigned, a default priority of zero is used. The effect will be added to the show after any effects of equal or lower priority, but before any with higher priority. Effects are run in order, and later effects can override earlier ones if they are trying to affect the same things, so a higher priority and more recent effect wins.

If :held is passed with a true value, then the cue will be active only as long as the corresponding pad or button on the control surface is held down, for controllers which support this feature. This can be useful for very intense cues like strobes. Show operators can override the :held flag by holding down the Shift key when triggering the cue on interfaces which have Shift keys, like the web interface and Ableton Push.

To support controllers with animated graphical displays like the Push 2, a visualizer creation function can be passed with the optional keyword argument :visualizer. This function will be called when the controller wants to draw a visualization of the progression of the cue over time, and will be passed two arguments, the cue’s var-map (see below), and the show in which the cue is running. The function must return another function, which takes a metronome snapshot, and returns a value between 0 and 1 representing some meaningful numerical summary of the cue state at that time. It will be used to draw a moving strip chart of the cue’s activity around the current moment on the display. The example dimmer oscillator cues like make-sine-dimmer-cue show how this can be used to good effect.

:variables introduces a list of variable bindings for the cue, each of which is a map with the following keys:

• :key identifies the variable that is being bound by the cue (for easy adjustment in the user interface while the cue is running). If it is a string rather than a keyword, it identifies a temporary variable which need exist only for the duration of the cue. The actual name will be assigned when the cue is activated. In order for effect-fn to be able to access the correct variable, it is passed a map whose keys are keywords made from the string :key values supplied in the :variables list, and whose values are the actual keyword of the corresponding temporary show variable created for the cue.

• :name, if present, gives the name by which the variable should be displayed in the user interface for adjusting it. If not specified, the name of :key is used.

• :short-name, if present, is a shorter version of the name which can be used in interfaces with limited space.

• :min specifies the minimum value to which the variable can be set. If not supplied, zero is assumed.

• :max specifies the maximum value to which the variable can be set. If not supplied, 100 is assumed.

• :start specifies the value to assign to the variable at the start of the cue, if any. It can be a simple value, a keyword which will be replaced by the current value of a show variable by the same name when the cue begins, or a function which will be called to obtain a value for the variable.

• :type identifies the type of the variable, to help formatting its display. Supported values are :integer, :double, and :color. Other types may be supported in the future. If omitted or unrecognized, :double is assumed.

• :centered supplied with a true value requests that the gauge displayed when adjusting this variable’s value be like a pan gauge, showing deviation from a central value, for interfaces which support this.

• :resolution specifies the smallest amount by which the variable will be incremented or decremented when the user adjusts it using a continuous encoder on a physical controller. If not specified the resolution is up to the controller, but 1/256 of the range from :min to :max is a recommended default implementation, since that allows access to the full DMX parameter space for channel-oriented values.

• :velocity accompanied by a true value enables the variable to be set by strike pressure and adjusted by aftertouch pressure while the pad which launched the cue is held down on pressure-sensitive controllers.

• :velocity-min and :velocity-max specify the range into which MIDI velocity and aftertouch values will be mapped, if they are present. Otherwise the standard :min and :max values will be used.

Given a cue, an active effect map, and a metronome snapshot representing the moment for which the user interface is being rendered, return the color with which the cue should be rendered on a cue grid. If the cue is not currently running, active should be nil. Handles the delegation to the cue’s dynamic color function if one has been assigned. Useful dynamic color functions are built by color-fn-from-cue-var and color-fn-from-param.

Finds the keyword by which a cue variable is accessed; it may be directly bound to a show variable, or may be a temporary variable introduced for the cue, whose name needs to be looked up in the running effect’s variable map. If a temporary variable, the id of the effect which is expected to be running for the cue must be passed with :when-id, and this id must match the id of the actual effect currently running under that key, or nil will be returned.

If a show is passed with the :show optional keyword argument, the effect is looked up in that show. Otherwise, it is looked up in the default show.

Creates a cue that applies the specified function to the supplied fixtures or heads. Automatically adds a temporary variable for adjusting the function value if the function is not fixed over its range. show-key will be used as the effect keyword when the cue is triggered to add it to a show, ending any existing effect that was using that key. function identifies the fixture function to be activated by this cue, and fixtures lists the fixtures and heads can which should be affected (though only fixtures and heads which implement the specified function will actually participate).

Passing a value for :effect-name sets the name for the effect created by this cue. If none is provided, the name of the function is used.

If supplied, :short-name identifies a compact, user-oriented name to be displayed in the web interface or controller display (if it has one) to help identify the cue, which can be helpful if the name of the underlying effect is ambiguous or overly long.

:color requests that the web interface and control surfaces draw the cue using the specified color rather than the default white to help the user identify it. This is only a request, as not all control surfaces support all (or any) colors. The color is passed to interpret-color, so it can be specified in a variety of ways.

:level can be used to set the initial level for functions which have a variable effect over their range. Such functions will be automatically assigned a variable parameter which can be used to adjust the level while the cue runs, and which will be visible in the web interface and on controllers which support adjusting cue parameters. Function levels are expressed as a percentage, which is mapped onto the range of DMX values which are assigned to the function in the fixture definition. Functions with no variable effect will ignore :level and will not be assigned variables for adjustment.

If :htp is passed a true value, the created effect applies highest-takes-precedence (i.e. compares the value to the previous assignment for the channels implementing the function, and lets the highest value remain). See channel/function-effect for more details about the underlying effect.

:end-keys introduces a sequence of keywords identifying other effects which should be ended whenever this one is started. This allows a set of grid cues to be set up as mutually exclusive, even if they use different keywords within the show for other reasons.

:priority assigns a sorting priority to the effect. If not assigned, a default priority of zero is used. The effect will be added to the show after any effects of equal or lower priority, but before any with higher priority. Effects are run in order, and later effects can override earlier ones if they are trying to affect the same things, so a higher priority and more recent effect wins.

If :held is passed with a true value, then the cue will be active only as long as the corresponding pad or button on the control surface is held down, for controllers which support this feature. This can be useful for very intense cues like strobes. Show operators can override the :held flag by holding down the Shift key when triggering the cue on interfaces which have Shift keys, like the web interface and Ableton Push.

If the function being controlled has a variable effect, and thus a cue variable is being introduced to adjust it, :velocity, :velocity-min, and :velocity-max will be used when creating that variable, allowing it to be controlled by strike and aftertouch pressure on control surfaces which support that feature, as described in cue.

Finds the current value of the supplied cue variable, which may be directly bound to a show variable, or may be a temporary variable introduced for the cue, whose name needs to be looked up in the running effect’s variable map. If a temporary variable, the id of the effect which is expected to be running for the cue must be passed with :when-id, and this id must match the id of the actual effect currently running under that key, or nil will be returned.

Permanent variables associated with the cue can always be retrieved by omitting :with-id. If you want to only get the variable when a particular effect is running, however, you can do so by passing in that effect’s id with :with-id, and the same restriction will then be applied as is for temporary variables.

If a show is passed with the :show optional keyword argument, the effect is looked up in that show. Otherwise, it is looked up in the default show.

Deprecated in favor of the more accurately named remove-midi-to-cue-mapping.

Stop triggering the specified cue from the *show* cue grid upon receipt of the specified note or controller-change message. The desired cue is identified by passing in its x and y coordinates within the show cue grid. f is the handler function that was returned by add-midi-to-cue-mapping when the mapping was established.

Sets the current value of the supplied cue variable, which may be directly bound to a show variable, or may be a temporary variable introduced for the cue, whose name needs to be looked up in the running effect’s variable map. If a temporary variable, the id of the effect which is expected to be running for the cue must be passed with :when-id, and this id must match the id of the actual effect currently running under that key, or nothing will be set.

Permanent variables associated with the cue can always be set by omitting :with-id. If you want to only affect the variable when a particular effect is running, however, you can do so by passing in that effect’s id with :with-id, and the same restriction will then be applied as is for temporary variables.

If a show is passed with the :show optional keyword argument, the effect is looked up in that. Otherwise, it is looked up in the default show.

Returns a map containing the keys and current values of all variables used by the specified cue, which is suitable for saving via save-cue-vars!. The id of the effect currently running the cue must be passed as when-id to ensure that the cue is still running. If it is not running (or ends while the variable values are being looked up), nil is returned.

If a show is passed with the :show optional keyword argument, the effect is looked up in that show. Otherwise, it is looked up in the default show.