Software Documentation

Software Documentation


Hobbyist Pro Last updated: May 7, 2022

16 Programmer documentation: DMX setup events — preparing channels before the effect begins

DMX fixtures with gobos or moving heads or color wheels require setting up the wheels or head angles in advance of when the effect begins.  The time between the events that setup these conditions and the events that turn the effect on is called the DMX setup timeFinale 3D effects automatically add the setup events in the exported script, so users generally do not need to worry about setup events or setup time at all, except if:

  1. You are examining the exported script and you want to understand why it contains events whose times don’t seem to correspond to the script window in Finale 3D.
  2. Your show has separately triggered tracks that begin with an effect that requires setup time, and you want to shorten the setup time to make the track start more responsively when triggered.

Regarding the first reason, a full explanation is given in The DMX Patch field.  The DMX Patch of an effect may specify setup events to prepare DMX channels, along with the ideal setup time to ensure the fixture motors accomplish preparing the wheels or angles by the time the effect begins.  If you insert an effect in the show at 10 seconds, and the effect has a 340ms DMX setup time, then the setup events would be inserted at 9.66 seconds — unless the fixture has other effects ending closer to 10 seconds, in which case the setup events will be inserted with less of a time delta, to avoid overlap.

Also, the Prefire column has a special meaning for exported DMX effects: it is the maximum “reach back” time for Move-To effects; and it is ignored for all other effects.  In spite of the fact that the Event Time in the script window takes the Prefire into account for all effects — including DMX effects — the DMX events in the exported script are based solely on the Effect Time and the setup time, not the Event Time and not the Prefire.  The reach back time is the time between a Move-To effect and the previous effect that defines the “from” angle.

Regarding the second reason, if your show contains separately triggered tracks, the event times in the track are relative to the first event in the track.  If the first effect in the track adds setup events in advance of the visual effect, then the track will be relative to the earliest of those setup events, which creates a delay between when the track is triggered and the appearance of its first visual effect.

Setup times in effects are conservatively long, giving the fixture motors enough time in even the worst conditions.  There’s no reason for the setup times not to be conservative in a designed show, because it doesn’t hurt to be a little early in preparation.  But for the first effect in a separately triggered track, the conservative setup time might introduce more latency than you want, relative to the consequences of possibly being a little late in preparation.

The per-show setting called maxInitialDmxSetupDelayMs gives you the ability to shorten the maximum setup time in your show for the specific situation of the first effects in separately triggered tracks.  You can set this setting to any value, including zero, to limit the latency between when a track is triggered and when its first visual effect occurs.


Table 1 – Per-show settings that affect setup time

Function name Type Meaning
maxInitialDmxSetupDelayMs Integer count of milliseconds Limits setup time of first effect in separately triggered tracks