The CSV and DMX CSV export formats provide a script representation that humans can read and use as-is or convert with AI to other formats for importing into software systems like Grand MA or do-it-yourself pyro firing systems. To create and export a script as a CSV or DMX CSV, please follow these three steps:
- Design the show.
- Address the show (“Addressing > Address show”; choose CSV firing system or DMX CSV firing system).
- Export the script (“File > Export > Export firing scripts“).
Step 3 creates the script file, which is a CSV file that you can adapt, or import into other software systems, or read in Excel or Notepad.
Figure 1 – A do-it-yourself firing system that could use CSV scripts
CSV for pyro firing systems
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.
DMX CSV for light desk software
The DMX CSV addressing choice produces files that include only the DMX script rows, whereas the CSV addressing choice includes the pyro and provides the option upon exporting whether or not to include DMX script rows.
DMX script rows in the exported CSV set or ramp a value for a single DMX channel. Thus, timeline events in Finale like “Flash Flame” or “Move-To While Red” correspond to multiple rows in the exported CSV that set the necessary fixture state to produce the overall effect, such as the angle and color for moving lights, or the height and spray trigger for flames or sparks. Various fields in the DMX CSV script row provide an association that connects the CSV event, which sets an individual channel value, with its corresponding user-level effect in Finale like “Flash Flame” or “Move-To While Red”.
The Part Number field for DMX events is of a specific format, XXX-YYY-ZZZZ, where XXX is a brand identifier, YYY is a Standard Fixture ID (see Supported DMX fixtures (and Standard Fixture IDs)), and ZZZZ is a Standard Effect ID. Thus the information contained within the part number itself identifies what the user-level effect actually is. For example, the information in part number “EXP-001-4124” breaks down as shown in Table 1.
Table 1 – Example decoding of information contained in the part number EXP-001-4124
| Segment Of Part Number | Meaning |
| EXP | Explo Ignition Systems |
| 001 | X2 Wave Flamer Flame Machine 6CH |
| 4124 | Predefined program #32, which is “Program 32: 15>>1” for the X2 Wave Flamer |
The part numbers of user-defined effects in Finale have a Standard Effect ID in the range 9000-9999. IDs in this range do not have a standardized meaning since they are user-defined. Thus a part number like EXP-001-4124 would knowably correspond to the X2 Wave Flamer Flame Machine 6CH fixture made by Explo Ignition Systems, but whether it is a predefined program or some other effect could not be ascertained from the information in the part number.
Table 2 – File format and encoding
| File format | Extension | Text encoding | Field delimiter | End-of-line |
| Text | CSV | UTF-8 | Tab | CRLF |
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 3 – Special characteristics
| Special characteristics | Description |
| 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_4ch — 4 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 4 – Specifications of all script fields, including pyro and DMX
| Field name | Description |
| 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 | The identifier for the effect definition. For DMX script rows, the Part Number is of a specific format, XXX-YYY-ZZZZ, where XXX is a brand identifier, YYY is a Standard Fixture ID (see Supported DMX fixtures (and Standard Fixture IDs)), and ZZZZ is a Standard Effect ID. |
| 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. |
| Custom Position Field | The custom position field string from the position of the event. |
| DMX Universe | The event’s DMX universe number (an integer). |
| DMX Channel | The event’s DMX channel, 1-512. |
| DMX Ramp From Value | The start DMX value of the event if the event is a ramp; otherwise blank. |
| DMX Value | The DMX value of the event or end DMX value if the event is a ramp. |
| DMX Ramp Or Hold Duration Ms | The duration of the event, or blank if the event sets the DMX value to hold forever. If the event is a ramp, then it must have a duration; and the DMX value will be held at the ending DMX value forever after the end of the duration. If the event is not a ramp, and if it has a duration, then the channel’s DMX value will be reset to zero at the end of the duration. |
| DMX Fixture Name | The name of the DMX fixture. |
| DMX Channel Base | The fixture’s first channel in its DMX Universe, 1-512. |
| DMX Channel Name | The name of the channel in the fixture’s DMX channel map / personality. |
| DMX Associated Event ID | An integer ID associating the event in the exported CSV file with the timeline event in the Finale script that generated it. A single timeline event in the Finale script such as “Flash Flame” or “Move-To While Red” generates multiple events in the exported CSV to produce the effect, such as setting the angle and color for moving lights, or the height and spray trigger for flames or sparks. |
| DMX Associated Event Effect Time | The event in the Finale script, as represented on the timeline and in the script table, has an “Effect Time” that is the nominal time at which the event occurs. Associated events in the exported CSV may have times before or after the nominal effect time. CSV event times before the nominal effect time are required to ensure the proper setup parameters like angle and color wheel values are set before the effect becomes visible (setting up the angle in advance is sometimes called “move-in-black”). CSV event times after the nominal effect time may be releasing or resetting the DMX value at the end of the duration, or may be stringing together multiple short ramp segments to approximate a smooth curve like a sine wave for animation effects like “Motion Loop: Rolling Circle”. |
| DMX Associated Event Duration Ms | The duration of the Finale timeline event associated with the CSV event. |
Pyro example
The example script below shows an exported pyro 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 pyro script for do-it-yourself controllers
Table 5 – Example files
| Download link | Explanation |
| test_csv.csv | Example exported file (CSV) |
| test_csv.fin | Example show file |