To create and export a script as a CSV for a do-it-yourself firing system, please follow these three steps:
- Design the show.
- Address the show (“Addressing > Address show”).
- Export the script (“File > Export > Export firing scripts“).
Step 3 creates the script file, which is a CSV file that you can import into your firing system software, or Excel.
Figure 1 – A do-it-yourself firing system that could use CSV scripts
The CSV is a human-readable text file that contains the essential information for a firing system controller to fire the show. You may be wondering about the difference between exporting the script for the “CSV firing system” versus exporting the show in the Finale Generic CSV format. Both formats are CSV files, and they have some similar fields.
The difference is that the Finale Generic CSV format is an interchange format for the full show that is not firing system specific. You can address your show for any firing system or multiple firing systems, and then export the entire show as a Finale Generic CSV file. The interchange format also contains more information than is generally needed to fire the show, such as the coordinates of launch positions, or inventory locations of product, etc., which you might need if you were importing the show into other software, such as an inventory management system, or label printer. The full show interchange format also includes multiple rows for chains or flights of shells shot at the same time, so little or no information is lost in the export process. You can export a show in the Finale Generic CSV format from Finale 3D and then import it again and end up with almost the same show, other than the sound track, background image, custom settings and whatnot.
By contrast, the CSV firing system export contains just enough information for a firing system to fire the show and for a human to be able to read it an follow along. Each line in the CSV firing system export represents a unique ignition of a firing system pin, including all of the effects triggered by that ignition. Since multiple kinds of effects at multiple angles could be triggered by the same ignition, the file format is necessarily does not contain all the information in the show. The effect name field, for example, may be “(3) Red Peony, …” to indicate three different kinds of effects including a Red Peony, without indicating what the other two effects might be.
The advantage of the layout of information in the CSV firing system export format is that it is easy for a firing system to interpret the information in the file without needing to lookahead or do much manipulation of the text. Additionally the features of Finale 3D that enable you to use multiple kinds of firing systems in the same show will support using the CSV firing system along with other firing systems.
Table 1 – File format and encoding
|File format||Extension||Text encoding||Field delimiter||End-of-line|
The script contains five header lines, followed by a single header row with the column names of the rows, followed by the rows themselves. The special characteristics of the script are shown in the following table:
Table 2 – Special characteristics
|Sort order of rows||Rows are sorted by ignition time if they do not have Track values. If rows have Track values (see below), they are sorted by ignition time within their track groups, and the track groups are sorted along with any non-grouped rows relative to each other by comparison of their earliest ignition times.|
|What rows represent||Each row identifies a unique firing pin ignition (i.e., unique rail address, pin address, ignition time).|
|Module types||Rows in the script can represent multiple types of modules: |
csv_8ch — 8 pins
Modules without slats need only need a single number XXX to identify the module. Modules with slats require two-part addresses XXX-YYY to identify both the module and the slat. The script format supports both syntaxes for rail addresses, XXX and XXX-YYY, as described below. If your do-it-yourself firing system has a configuration that is similar to one of these options but not exactly the same, you can make a custom module type based on one of these, from the options in the “Addressing” menu.
|Special characters||Fields include any Unicode characters except: ‘ , ; ” \ tab and newline and other control characters.|
|Support for semi-autonomous firing||The Cue and Track fields support semi-autonomous firing modes. Cue numbers begin at one and increment with each new ignition time or each new track group of effects. The Track is an optional identifier associating a collection of rows that are to be fired together as a “step” in a sequence of steps or as a “macro” triggered by an associated button on the firing system. Cue numbers do not increment within a track group of effects.|
Each script row has the fields shown in Table 3.
Table 3 – Specifications of script fields
|Cue||The cue count, beginning with one and incrementing at each new ignition time or at each new track group of effects. The cue count does not increment within a track group of effects even if the effects in the track group have different ignition times.|
|Event Time||The exact time of the firing system’s “ignition event” (application of a voltage to a pin) that ignites e-matches or triggers a sequencer that ultimately leads to the ignition of effects. Format is HH:MM:SS.DDD.|
|Prefire||The delay from the ignition time to the perceived visual effect. This delay typically includes the lift time (for shells) plus any fuse time between the ignition time and the first launch of the effect. Format is in seconds with two digits after the decimal point.|
|Effect Time||The time of the first visual effect triggered by the firing system’s ignition event, which is generally the break time for shells, and just a small delay or no delay after the event time for ground effects. Format is HH:MM:SS.DDD.|
|Duration||The duration represents the lifetime of the perceived visual effect, which is usually interpreted for shells as the time from break to dissipation of the stars. Format is in seconds with two digits after the decimal point.|
|Device Count||The number of devices (shells) represented by the row. May be more than one in the case of chains or multiple e-matches connected to the same firing system pin.|
|Description||The name of the effect.|
|Size||The device caliber. Format is either a number followed by double-quote for inches or “mm” for millimeters, or the string “NA” or blank for effects for which the caliber term is not applicable.|
|Category||A user defined string identifying the category of the effect.|
|Type||One of several pre-defined terms that have specific meaning in Finale 3D (see Why is ‘Type’ so important? What depends on it?).|
|Position||The name of the launch position.|
|Module Type||The type of module or slat: csv_8ch, csv_16ch, csv_32ch, csv_100ch, csv_1000ch, csv_8ch_slats, csv_16ch_slats, csv_32ch_slats, csv_100ch_slats, csv_1000ch_slats.|
|Rail Address||The module number XXX in the case of modules without slats, or a two-part module-slat combination XXX-YYY in the case of modules with slats, where XXX identifies the module and YYY identifies the slat.|
|Pin Address||The pin number.|
|Angle||An ASCII art representation of the angles of the devices on this shot, made with backslash, vertical line, and forward slash characters.|
|Hazard||A string identifying a group of effects that can be disabled by pressing the associated button on the firing system controller during the performance, due to conditions.|
|Notes||Firing notes from the script pertaining to this row.|
|Part Number||A user-defined identifier for the effect.|
|Track||A string identifying a group of effects that are to be fired as a sequence with a single trigger if the firing system is in semi-autonomous mode.|
The example script below shows an exported script with nine pairs of shots and two different types of modules. The cue numbers are the same for both effects in each pair. The last four rows of the script have the same track number/identifier (“Finale”), which causes them to share the same cue number (8). If a firing system were shooting in semi-automatic mode, the rows with cue number 8 would be triggered as a sequence/macro by a single trigger.
The rail address of the csv_8ch_slats module type rows contain two numbers to identify the module and the slat independently. The slat is identified by a letter, to make it easy to read.
Cue Event Time Prefire Effect Time Duration Device Count Description Size Category Type Position Module Type Rail Address Pin Address Angle Hazard Notes Part Number Track 1 00:00:02.760 2.24 00:00:05.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-01 csv_16ch 01 1 | G2SH1000 1 00:00:02.760 2.24 00:00:05.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-01 csv_16ch 01 2 | G2SH1000 2 00:00:05.260 2.24 00:00:07.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-02 csv_16ch 02 1 | G2SH1000 2 00:00:05.260 2.24 00:00:07.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-02 csv_16ch 02 2 | G2SH1000 3 00:00:07.760 2.24 00:00:10.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-03 csv_16ch 03 1 | G2SH1000 3 00:00:07.760 2.24 00:00:10.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-03 csv_16ch 03 2 | G2SH1000 4 00:00:10.260 2.24 00:00:12.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-04 csv_8ch_slats 04-A 1 | G2SH1000 4 00:00:10.260 2.24 00:00:12.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-04 csv_8ch_slats 04-A 2 | G2SH1000 5 00:00:12.760 2.24 00:00:15.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-05 csv_8ch_slats 04-B 1 | G2SH1000 5 00:00:12.760 2.24 00:00:15.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-05 csv_8ch_slats 04-B 2 | G2SH1000 6 00:00:15.260 2.24 00:00:17.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-06 csv_8ch_slats 04-C 1 | G2SH1000 6 00:00:15.260 2.24 00:00:17.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-06 csv_8ch_slats 04-C 2 | G2SH1000 7 00:00:17.760 2.24 00:00:20.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-07 csv_8ch_slats 04-D 1 | G2SH1000 7 00:00:17.760 2.24 00:00:20.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-07 csv_8ch_slats 04-D 2 | G2SH1000 8 00:00:20.260 2.24 00:00:22.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-08 csv_8ch_slats 05-A 1 | G2SH1000 Finale 8 00:00:20.260 2.24 00:00:22.500 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-08 csv_8ch_slats 05-A 2 | G2SH1000 Finale 8 00:00:22.760 2.24 00:00:25.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-09 csv_8ch_slats 05-B 1 | G2SH1000 Finale 8 00:00:22.760 2.24 00:00:25.000 1.02 1 Red Chrysanthemum 2" 2 Assorted shell Pos-09 csv_8ch_slats 05-B 2 | G2SH1000 Finale
Figure 2 – Example CSV firing system script for do-it-yourself controllers
Table 4 – Example files