Software Documentation

Time codeDocumentation

Last updated: September 30, 2019

1 Time code basic instructions

When you export a firing system script from Finale 3D, you produce a script file that contains a list of events, or triggers, at specific times.  Time code provides a mechanism for synchronizing these events to music.  Three resources are involved: the script, the time code recording, and the music recording.  The key to understanding time code is understanding the relationship between these resources.

Depending on the firing system, the script file may be a file that can be downloaded or copied to the controller directly, such as the CSV files for Pyromate and the “PDM” file for Pyrodigital, or it may be in a file format that you need to open in other software from the firing system company to transfer to the controller, such as the FIR files for FireOne or the GS2 files for Galaxis.  Regardless of whether you download the file directly to the controller or open it up in other software to transfer to the controller, the instructions for time code are the same.

To explain the time code process using a concrete example, we will consider the script file format that Finale 3D exports for Pyrodigital field controllers (a PDM file), which can be downloaded directly into Pyrodigital field controllers from the computer’s serial port.    You can download that file using the Finale 3D menu item “File > Download to controller” or alternatively you could also download the file using a terminal program from any PC.  Instructions for downloading with a terminal program are available from Innovative Pyrotechnik GmbH.

The PDM file contains a list of events, or triggers, at specific HH MM SS FF frames.  In Finale 3D, if you script in millisecond resolution, then when you export the PDM file the event times in the file will be rounded to the nearest frame.  Finale 3D gives you options for displaying the times in the script and timeline in frames instead of decimal times (“Show > Set effect time format”) and options for snapping to frame numbers when moving events on the timeline (“Show > Set timeline snap-to resolution”).  You also have the option to adjust effect times to match the desired resolution (“Script > Align > Align effect times to resolution”).  If you select all the effects in the show, and then align to 30fps, then when you export a PDM file for 30fps PD no additional rounding will be required.

By default, in Finale 3D the left edge of the timeline represents “zero” in time.  If you want to add an offset to the times that are exported in the PDM file, open the “Per-show settings” window and change or add a settings “offsetMs” with the signed integer value of the number of milliseconds to add to exported times.  For example, if you want to offset the exported times to begin at ten hours (10:00:00;00), you can set “offsetMs” to 10 hours * 60 minutes/hour * 60 seconds/minute * 1000 milliseconds/second = 36000000.  Similarly, if you want to adjust the exported times a small amount to compensate for minor delays in the controller’s time code decoding hardware, you can set the the “offsetMs” to whatever small adjustment factor you need, positive or negative, such as -66 to accelerate the times by two 30fps frames.  The “offsetMs” value applies when you create the PDM file with the function “File > Export > Export firing system scripts(s)”, not when you download the PDM file.  The function “File > Download to controller” will download the PDM file as is, unaffected by whatever the “offsetMs” setting is at the time of download.

The purpose of using time code is to synchronize the scripted events to the music.  After downloading the PDM file to the controller, the controller will contain the list of events at specific HH MM SS FF times.  When time code is played through the controller, the controller’s internal clock synchronizes to the time code and adjusts to match the HH MM SS FF times in the time code stream as they play through the controller.  When the controller’s internal clock advances past the frame time of an event in the list of events from the PDM file, the controller fires the module and pin number associated with that event (the old FC3 Pyrodigital controllers have some bugs with drop-frame 29.97fps DF SMPTE time code, as documented in Technical note: comparison of old and new Pyrodigital field controllers for SMPTE but there are no problems with 30fps NDF SMPTE time code, and there are no problems with the new FC-A controllers even for DF SMPTE).

Logically, synchronizing events to time code is the same as synchronizing events to music if the music and the timecode are played simultaneously and in perfect synchronization.  To guarantee the music and time code are played together, the common practice is to combine the music and time code in the same audio file, with the time code on one track and the music on other tracks.  When the audio file is played during the performance, the time code track is directed into the controller, and the music tracks are directed to speakers to play for the audience.

Theoretically, combining the time code and music using an audio editor is straight forward if you know the exact offset in the time code waveform that corresponds to the start of the show.  Let’s say they both begin at “zero.” That represents the “zero” scenario in the following table, which is good to understand but is generally not practical for reasons explained in the table.

Table 1 – Preparing your show for time code

Scenario Description
Start at “zero” scenario If the show begins at time “zero” and you have a time code waveform recording that begins at time “zero” and music recording that begins at time “zero”, then just combine the music and the time code together, beginning at the same time.  This works in theory, but in practice the problem with it is that the time code decoding hardware in the controllers requires some time to lock on to the time code signal. If there are events that fire near the beginning of the time code recording, those events could be skipped or fired late.
Start at known offset To give the firing system’s time code decoding hardware a chance to lock on to the time code signal, it is common practice to include some lead time in the time code waveform before the script and the music kick in.  In other words, start playing the time code waveform first and then start the music and the script after some delay, typically 10 seconds or a minute long. If you know the exact offset in the time code waveform that corresponds to the desired delay for starting the show (say one minute), then combine the music waveform with the timecode, starting the music at that offset (e.g., one minute into the timecode recording), and add one minute to the script’s events by setting “offsetMs” to 60000 prior to exporting the firing script.  Finally, remember to start playing the combined music and time code recording one minute before the show is set to begin.
Start at adjusted offset The firing system’s time code decoding hardware may introduce latency that’s large enough to matter.  The usual method to figure out and compensate for these internal delays is trial and error: 1) in Finale 3D, create a test show with a test shot firing at precisely the desired delay (the test shot’s event time, not its effect time); 2) in your audio editor, create a soundtrack with time code beginning at zero in the time code track, and a recognizable beep or test sound in the music track at your offset estimate corresponding to the desired delay; 3) play the test show through the controller, listening for the test sound while watching the display on the controller or watching LEDs hooked up to show the firing pins; 4) does the test sound occur after or before the test shot?  Adjust your estimate and repeat from step (2) until getting satisfactory alignment. Having determined the offset for the music, proceed as in “Start at known offset.”
Start at an offset in externally supplied time code If you are designing a show to match externally supplied time code, you can set the “offsetMs” amount to whatever time offset you are told is the beginning of the show, such as 36000000 for 10 hours.  You can also adjust the offsetMs to compensate for internal delays if you’ve determined through trial and error as in the last scenario that an adjustment is necessary.