The FireOne CSV format is an interchange format defined by FireOne to facilitate compatibility with external software like Finale 3D and to expose the “Scripted DMX” capabilities of the new (2023) FireOne modules. If you want to design FireOne Scripted DMX in Finale 3D, you need to export your shows in the FireOne CSV format instead of the FIR or SEM file formats. Descriptions of the FIR and SEM formats are here.
To create and export a CSV script for the FireOne firing system, please follow these steps:
- Design the show. If you are creating a semi-automatic show (SEM file), then select the ranges of the effects on the timeline corresponding to triggered sequences and assign them a track number by right clicking on the selected group and doing “Edit properties…” from the context menu.
- Address the show (“Addressing > Address show”).
- Export the script (“File > Export > Export firing scripts“).
- Choose “FireOne CSV (CSV)” from the “Script Type” field on the export dialog.
Step 3 creates the script file, which is a comma separated text file. The file format details are described in this section.
Figure 1 – FireOne IFMx-32Q module with Scripted DMX capability
Table 1 – File format and encoding
| File format | Extension | Text encoding | Field delimiter | End-of-line |
|---|---|---|---|---|
| Text | .CSV | UTF-8, UTF-16, or ASCII |
Comma | CRLF |
CSV files are text files that you can open in a text editor or in Excel to inspect. For your convenience, Finale 3D has a function, “File > Tools > Open firing system script as generic table” which opens the CSV file as a generic table for you to view or copy/paste from if you have need.
Table 2 – Special characteristics
| Special characteristics | Description |
|---|---|
| Time representation | All times are represented as milliseconds, but rounded to the nearest hundredth in keeping with FireOne module time resolution. |
| Sort order of rows | Rows are sorted ascending by event time. Since the Event field can be set to any number according to the Track field in Finale 3D, the ascending event time sort order does not imply that the Event fields are increasing in the “Track number from Finale” export option; the Event fields will be increasing, starting with 1, for the “Sequence of tracks and launch times” export option. |
| What rows represent | Each row represents a unique module-pin-eventTime combination, and contains all the information in the script file that is associated with that module-pin-eventTime combination (the pin number in the Cue field), or a DMX command (the Cue field being blank). |
| Semi-automatic firing | Unlike FIR and SEM files, which are single-trigger shows and semi-automatic shows according to the file type, FireOne CSV files can represent single-trigger shows or semi-automatic shows, based on the use of the Event field. The FireOne CSV exporter provides three export options as described in Table 3. |
| Using only 30 pins | In the addressing dialog and the position properties dialog, you can choose the “FireOne Module, 30 Pins” instead of the standard “FireOne Module” if you want to leave the last two pins unused. You can also create a custom module in the “Addressing > Addressing settings” menu with an arbitrary maximum number of used pins. |
| Multi-hit pins | FireOne hardware, and the FireOne CSV file format, and Finale 3D all support multi-hit pins. Non-pyro effects like flames and relays can be triggered multiple times on the same module-pin. The standard pyro addressing functions in Finale 3D assign pins sequentially, so it may be easiest to address multi-hit pins in Finale 3D by editing the script table by hand and then locking the edited rows so the show can be re-addressed for pyro without affecting them. |
| Slats | While FireOne modules all have 32 pins, you may have hardware to divide the pins up into slats, such as four slats of 8 pins each, for the purpose of igniting effects at multiple launch positions without all the ematches extending all the way to the module. When using slats it is essential that the pin numbers used for effects at a position correspond only to the slats at that position.
Finale 3D’s addressing functions support addressing constraints based on slats to allow slats from the same module to be located at different positions. Although FireOne module/pin addresses don’t provide any indication of slats (each module’s pins are 1-32 no matter how you might partition them into slats), you can configure the modules in Finale 3D as having “virtual slats” in order to make use of the slat-based addressing constraints. Virtual slats allow you to partition the channels of a module into separate slats for which you can assign addressing constraints to guarantee good pin assignments for your physical layout. For example, suppose you have one module with 32 pins that are distributed out to four launch positions on four physical “slats” or “rails” with 8 pins each. It would be important to have the addressing constraint that each slat is restricted to a single launch position, for otherwise you might have wires running from position to position. To partition the pins into virtual slats, create a custom FireOne module with a rail address template like #99-D-#8 to split the 32 pin modules into four 8-pin slats, A, B, C, D. Because these are virtual slats, even though their addresses appear like “2-B” and “3” for module 2, slat B, pin 3 (of slat B), the addresses are converted automatically in the exported FIR or SEM script the contiguous 32-pin range of the module. The virtual slat address “2-B” and “3” convert to module 2, pin 11 (pins 1-8 correspond to slat A, so the third pin in slat B is pin 11). |
When you export a firing script for FireOne, Finale 3D presents an “Export Options” dialog with the option to export a FIR file or SEM file or CSV file, and options that are enabled for the CSV file choice for the Event field, as shown in Table 3.
Table 3 – Export options
| Option name | Description |
|---|---|
| Script Type | Choose Standard Script (FIR), or Semi-Automatic Script (SEM), or FireOne CSV (CSV) |
| Event name field contains | “The value 0 always”; or “Track number from Finale” or “Sequence of tracks and launch times” |
The FireOne CSV format has an Event Name field for semi-automatic shows. Finale 3D‘s export dialog has an “Event name field contains” selector with three options (enabled only for the FireOne CSV file format option):
- The value 0 always
- Track number from Finale
- Sequence of tracks and launch times
If you are exporting a script for a single trigger show, then select the first option. If you are exporting a script for a semi-automatic show, choose one of the other two options. The “Track number from Finale” option fills the Event Name field with the integer value of the Track field string. If you use this option, please ensure that all events in the show have an integer value in their Track field (unhide the Track field in the script table window to be sure). The integer values correspond to the FireOne events that trigger the sections of the show.
The “Sequence of tracks and launch times” option fills the Event Name field with a sequence of non-decreasing integers beginning with one. The sequence advances at each row with a different Track value from the previous row, and at each row that has a blank Track field and an Event Time that is different from the previous row’s Event Time. The purpose of this option is to make it easy to script a semi-automatic show that primarily groups each unique event time as a trigger, with the option for the user to select a range of events at different event times and group them together as a single-trigger unit by assigning them the same Track. With this option, the Track values can be anything; they do not need to be in order and they do not need to be integers; they are strictly a label that identifies a group of events to be treated as a unit with with a single trigger. The Track values are not themselves present in the exported script.
Table 4 – Specifications of CSV script fields
| Field name | Description |
|---|---|
| Row ID | Row number, starting with 1 |
| Launch Time | Event time in milliseconds, rounded to nearest hundredth of a second |
| Delay | Prefire time (difference between Launch Time and Effect Time) in milliseconds, rounded to nearest hundredth of a second |
| Event | 0 or an integer from 1-999 (see export options, above) |
| Module | Module address number, from 1-99; or the DMX Universe for DMX commands. The module number for FireOne modules is the DMX Universe of the fixture position, which you can set by right clicking the position and doing “Edit position properties” or “Configure as DMX fixture”. The DMX Universe of a fixture position gets copied into the “Rail Address” field of the script table when addressing the show. |
| Cue | Pin address number, from 1-32; or blank for DMX commands. |
| Quantity | Number of devices |
| Product ID | Part number, limited to 12 characters. |
| DMX Channel | 1-255, or blank for non-DMX row |
| DMX Value | 0-255, or blank for non-DMX row |
| DMX Duration | Integer milliseconds, or o for “Hold forever”, or blank for non-DMX row |
| DMX Rate | Integer tenths of a second duration (values 0-255 for 0-25.5 seconds) over which to ramp the old DMX channel value to the new value, at which time it will then be held for an additional duration as specified by the DMX Duration field; or 0 for immediate; or blank for non-DMX rows. As of 4/15/23 Finale 3D always writes 0 to this field for DMX rows, as Finale 3D’s DMX fixture implementations use the fixture’s motor speed to implement ramps instead of firing system capabilities. For users who want to manually employ the DMX Rate field for ramps or fades of lighting parameters or moving head angle values, Finale 3D provides options to write the relevant timing information to the Comment field, which users can copy into the DMX Rate field by manually or programmatically modifying the file. |
| Description | Effect description, limited to 80 characters; or for DMX commands, the effect description annotated with the DMX channel offset from the base channel of the fixture and the meaning of the channel, such as for example the “(+2)” and “Ignition” in the description output, “Showven Circle Flamer Program -90° Short // Ignition (+2)” |
| Comment | The Notes field from the script table in Finale 3D, limited to 60 characters. The Notes field in Finale 3D can contain comment variables in the form “@variableName” that are expanded in the output script CSV into DMX timing values that users may find useful for their own DMX parameter manipulation, such as using the DMX Rate field. The three comment variables are @nominalDurationMs, @nominalSetupMs, and @effectiveSetupMs, whose values follow the definitions of “Nominal Duration” and “Nominal Setup Time” and “Effective Setup Time” in Programmer documentation: The DMX Patch field. If the duration of an event is longer than the FireOne CSV file format can represent (25.5 seconds), Finale 3D will split up the associated DMX commands into multiple DMX commands back to back, and only the first of the commands for each channel will have a nominal duration in the exported FireOne CSV. |
| Priority | The lockout/hazard field from Finale 3D as an integer, limited to the range 1-16. The default value is 1 for anything undefined or outside that range. |
| Position | Position name, limited to 10 characters |
An example CSV script file export is shown in Figure 2. The DMX commands beginning with row 5 are all from the same event in Finale 3D. They set multiple channels of a Showven Circle Flamer fixture to the values that trigger pre-defined macro “Program” for a short flame burst at -90 degrees. The DMX Channel Base for the fixture is 50, and the offsets of the channels for the DMX commands are +1, +2, +3 and +4, as you can see in the Description field. The DMX Channel numbers are thus 51, 52, 53, and 54.
Row ID,Launch Time,Delay,Event,Module,Cue,Quantity,Product ID,DMX Channel,DMX Value,DMX Duration,DMX Rate,Description,Comment,Priority,Position
1,2760,2240,0,1,1,2,G2SH1001,,,,,White Chrysanthemum,,1,P-01
2,3250,2240,0,1,2,2,G2SH1001,,,,,(2) White Chrysanthemum ...,,1,P-01
3,3740,2240,0,1,3,2,G2SH1001,,,,,(2) White Chrysanthemum ...,,1,P-01
4,4240,2240,0,1,4,2,G2SH1001,,,,,(2) White Chrysanthemum ...,,1,P-01
5,5000,0,0,11,,0,SHV1002,51,0,,0,SVCFLM [0102] Program -90° Short // Speed (+1),,1,P-04
6,5000,0,0,11,,0,SHV1002,52,255,190,0,SVCFLM [0102] Program -90° Short // Ignition (+2),,1,P-04
7,5000,0,0,11,,0,SHV1002,53,0,,0,SVCFLM [0102] Program -90° Short // Open Time (+3),,1,P-04
8,5000,0,0,11,,0,SHV1002,54,7,,0,SVCFLM [0102] Program -90° Short // Macro (+4),,1,P-04
Figure 2 – Example FireOne CSV script with pyro and DMX rows
Table 6 – Downloadable files
| Download link | Explanation |
|---|---|
| FireOne CSV file format | CSV format specifications from FireOne |