Finale Generic CSV file format
The Finale Generic CSV is an interchange format for fireworks shows that is human readable and editable. A number of fireworks software applications export and import scripts in this format without loss of information, allowing you to export a script from one program in the Finale Generic CSV format, work on it in Excel or some other software application, and re-import it back into the original application.
Scripts in this format can be used as the basis for custom reports or translated into a firing script for just about any firing system available. The format contains all the information to generate an inventory report or pick list, loading report, break time report, firing script, chain building report, custom shell labels, etc.
Table 1 – File format and encoding
| File format | Extension | Text encoding | Field delimiter | End-of-line |
| Text | .txt or .csv | UTF-8 or UTF-16 | Tab or comma | CRLF or LF or CR |
The script contains a single header row with row type FIRING_HEADER_ROW, and multiple rows with row type FIRING_DATA_ROW to represent the events in the show. For readability, multiple rows can be combined into one if all of their fields are identical except the angle field, which can be consolidated in the single row without loss of information as described below. Although rows can be combined in these circumstances, they are not required to be combined. The special characteristics of the script are shown in the following table:
Table 2 – Special characteristics
| Special characteristics | Description |
| Sort order of rows | Rows are unsorted.. |
| What rows represent | Each FIRING_DATA_ROW contains the field shown in the table below. The fields have no overlapping information, so some common terms like “Effect Time” must be derived from information in other fields. The rows can be sorted in any order without any change to the meaning of the script. Thus you can cut and paste between script files to combine them, and you can re-sort them at will without generating any inconsistencies. If you cut and paste scripts together, you only need to ensure that the chain identifiers and time cue identifiers from the files don’t accidentally overlap. |
| Special characters | If the file is saved with comma field delimiters, then fields containing a double-quote character (“) or comma will be enclosed in “ on both ends, and any internal “ characters will be doubled up, following the Excel quoting convention. If the file is saved with tab field delimiters, then no such quoting is required, though programs that read Finale Generic CSV are encouraged to support the Excel quoting convention even in that circumstance. |
| Row Type | The CSV file represents a table of information. In Finale Generic CSV, each row begins with a row type identifying what kind of row it is. The first row begins with FIRING_HEADER_ROW; the other fields in this row are the names of the columns. Subsequent rows begin with FIRING_DATA_ROW; the other fields in these rows represent the devices in the script. In the future, the script format can be extended to contain other information like rack layouts or time cue comments. For a firing script, though, the only two types of rows that matter are the FIRING_HEADER_ROW and the FIRING_DATA_ROWs. |
| Time representation | Times in Finale Generic CSV are represented as floating point seconds to eliminate ambiguity between different time bases and to avoid problems editing files in Excel. Excel interprets some time formats incorrectly and loses information, but floating point numbers are safe. Each row includes only the Ignition Event Time, Device Delay, and Prefire Delay times. The time of visual impact of an effect, often called the “Effect Time” or “View Time” or “Script Time”, can be calculated for each device as,
Usually the Device Delay is zero, so the Effect Time calculation is the familiar equation. The Device Delay term enables representation of delay chains and devices whose ignitions are delayed from the firing system event with a delay fuse or sequencer. In these cases, the full equation involving a Device Delay is necessary to represent the full state of affairs. |
| Representation of chains | In the Finale Generic CSV format, each firing row beginning with FIRING_DATA_ROW represents a collection of devices that are identical in every respect except their launch angle. Identical devices with different launch angles can be combined in a single row. Consequently a chain or flight of identical shells could also be represented by a single row, even if the shells were at different angles. However a chain consisting of different kinds of shells would require multiple rows to represent. Rows include a “Chain Identifier” field that enables multiple rows representing parts of the same chain to be brought together to reconstitute a representation of the full chain.
Using the chain identifier you can construct a chain building report that details the required assembly of fuse delays for the chains, or an inventory report that counts full chains as items instead of their individual devices. The chain identifier field also enables you to calculate the precise number of e-matches required for the show, since chains require only a single e-match in contrast with flights of shells that are e-matched together. |
Finale Generic CSV has a single row header of column names, followed by a list of rows representing the firing events. Each row has the following fields in any order, identified by the column name in the header row:
Table 3 – Specifications of script fields
| Field name | Description |
| (Row Type) | All firing rows begin with the first field, FIRING_DATA_ROW. |
| Time Cue Number | The number identifying the cue number associated with the ignition, if any. In computer fired shows it is possible for ignitions at different times to be associated with the same cue number since effects with different prefires may have the same cue number. This field is blank if the ignition does not have an associated cue. |
| Ignition Event Time | The exact time of the firing system’s “ignition event” (application of a voltage to a pin) that ignites one or more e-matches or triggers a sequencer that ultimately leads to the ignition of the devices represented by this row. Format is in seconds with two digits after the decimal point. |
| Number Of Devices | The total number of devices represented by the row. A single row may represent multiple independent devices launching at the same time, or multiple devices that are part of the same chain. A single chain, however, may require multiple rows to represent it if the devices in the chain are different effects or have different angles. A device is any pyrotechnic package that cannot trivially be separated into smaller units, such as a shell, candle, cake, or even multi-break peanut shell. Chains are considered to consist of multiple devices connected by fuse. |
| Duration | The duration has one of two meanings, depending on the type of effect. For cakes, candles, and chains with multiple shots, the duration represents the time between the first and last shot’s launch times. For other effects, 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. |
| Coordinates | Nine floating point numbers: X Y Z HEADING PITCH ROLL PAN TILT SPIN. X, Y, and Z are the coordinates of the launch position in world coordinates (meters from the show’s reference point). HEADING, PITCH, and ROLL are the heading, pitch, and roll of the position in world coordinates. PAN, TILT, and SPIN are the angles of the effect relative to the position. The coordinate systems and conventions for angles are explained in Racks and positions coordinate system: heading, pitch, roll and Effects coordinate system: pan, tilt, spin. |
| Chain Identifier | An identifier used to associate the devices of a chain if they are split across multiple rows. Rows that are part of the same chain have the same chain identifier. Rows that are not part of a chain have a blank value in this field. A single row is never part of more than one chain. |
| Lockout Identifier | A short string of up to three characters identifying the hazard group that the effects are assigned to, or empty string if they are not assigned to any hazard group. Some firing systems such as the Pyrodigital have a feature to disable ignitions of hazard groups in real time as the display is being fired. This field is left blank to indicate no hazard group. |
| Device Delay | The delay from the firing system’s ignition event to the ignition of the device or devices represented by this row, in seconds with two digits after the decimal point. Do not confuse the device delay with the prefire delay. The device delay is the delay before the device is ignited. The prefire delay is the delay after the device is ignited, but before its visual effect is perceived. Typically the device delay is zero. It is non-zero for devices involving delay chains, delay fuses, and sequencers. For chains, the device delay is the delay from the ignition of the chain to the ignition of the specific device in the chain. For devices ignited in series with delays or by a sequencer, the device delay is zero for the earliest of the devices, and is the respective cumulative delay for each of the others. |
| Prefire Delay | The delay from when the device is ignited to its perceived visual effect, in seconds with two digits after the decimal point. If the row represents devices in a chain, the Prefire Delay refers to the devices themselves. The prefire of the chain is the time from the chain’s ignition to the earliest effect time, which is typically but not necessarily the effect time of the first device in the chain. |
| Effect Name | The name of the effect. |
| Caliber | The device caliber, which also serves as the default internal diameter of the required mortar tube if no explicit Mortar Caliber is provided (see below). The format of the caliber is either a number followed by double-quote for inches or “mm” for millimeters, or the string “NA” for effects for which the caliber term is not applicable. |
| Category | One of six pre-defined English named categories of fireworks: Shells, Comets, Mines, Candles, Cakes, or Other. Chains of shells are listed in the Shells category. Lance work and other ground items are listed as Other. |
| Angles | An ASCII art representation of the angles of the devices on this shot, made with backslash, vertical line, and forward slash characters, followed by the decimal degree angles of the devices ordered left to right, separated with spaces, with negative angles meaning left aiming and zero meaning up. If the angle or angles are all straight up, the decimal degree representation is elided, for ease of reading. |
| Position Name | The name of the launch position from which the device is fired. |
| Animation Description | An English language description of the effect. If provided, the animation description is usually just a verbose effect name, something like 49 Shot 20s Time Rain Comet Cake. If the row represents a chain or part of a chain, the Animation Description should indicate a chain of N, where N is the number of devices in the full chain, e.g., Red Peony (Chain Of 10). |
| Module Description | The textual description of the module and optionally additional configuration information specific to the firing system. |
| Module Address | The module number. The empty string is a valid value, as are numbers in hexadecimal, like $11. |
| Slat Address | The slat number or letter, for firing system modules that use slats. In addition to numbers and letters, the empty string is a valid value, as are numbers in hexadecimal, like $11. |
| Pin Address | The pin number or letter. In addition to numbers and letters, hexadecimal (e.g., $11) is a valid format. However empty string is not possible as a pin address. |
| Firing Notes | The notes for the devices represented by this row, as pertaining to the show. Firing notes do not include the product notes associated with the effect definitions. In other words, a device inserted into the show initially has no firing notes. |
| Product ID | A user-assigned text string identifier for the effect type represented by this row, typically the display company’s internal part number. The Finale Generic format does not specify whether Product IDs for chains represent the entire chains or the devices comprising the chains (the Number Of Devices field is unambiguous either way). This value can be in any format, and is not guaranteed to be unique. |
| Manufacturer Product ID | The manufacturer part number. |
| Animation ID | A unique, computer-assigned text string identifier for the animation represented by this row. The Unique ID may be a hash or GUID or URL or other textual representation depending on the software program that generated it. If the row represents a chain or part of a chain, the referenced animation should represent the complete chain, not just a single device in the chain. |
| Location Primary | Name of the storage location from which the item is pulled to be boxed for the show, e.g., Magazine-A7. |
| Location Secondary | Additional description of storage location, e.g., Bin-53. |
| Price Per Device | The price per device, formatted as a floating point number with four digits after the decimal point, no units. The extra precision in the number allows for per-chain and per-case prices to be re-calculated from device prices to the penny. |
| Mortar Caliber | The internal diameter of the required mortar tube, or empty string to indicate the device caliber should be used. Small caliber items and candles are often sleeved in larger diameter mortars. This field, in combination with the Caliber field (above), allow both calibers to be represented. |
| Track Identifier | A string identifying the track that the effects are assigned to, or empty string if they are not assigned to any track. Some firing systems, such as the Cobra-18R2, use tracks to identify multiple, triggered sequences contained in a single script, and use the track identifiers to indicate the trigger buttons on the controller. The track identifier can also be used merely as an editing tool or for other custom purposes. |
The example script below shows an exported script in Finale Generic CSV format, saved with tab field delimiters..
FIRING_HEADER_ROW Time Cue Number Ignition Event Time Number Of Devices Duration Coordinates Chain Identifier Lockout Identifier Device Delay Prefire Delay Effect Name Caliber Category Angles Position Name Animation Description Module Description Module Address Slat Address Pin Address Firing Notes Product ID Manufacturer Product ID Animation ID Location Primary Location Secondary Price Per Device Mortar Caliber Track Identifier
FIRING_DATA_ROW 0.2 1 10.0 12.5 0.0 -8.0 2.5 2.3 8 Shot Red Comet Candle 30mm Candles Pos-06 10s 8 Shot Red Comet Candle cobra_18m_100ths 00 01 00380 M00380 2.0
FIRING_DATA_ROW 2.8 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 01 firing1 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 2.9 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 02 firing2 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.0 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 03 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.1 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 04 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.2 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 05 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.3 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 06 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.4 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 07 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.5 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 08 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.6 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 09 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.7 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 10 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.8 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 11 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 3.9 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 12 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 4.0 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 13 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 4.1 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 14 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 4.2 1 1.02 0.0 0.0 -8.0 0.0 2.2 White Chrysanthemum 2" Shells ????? White Chrysanthemum cobra_18m_100ths 01 15 G2SH1001 G2SH1001 1.45
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.0 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.05 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.1 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.15 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.2 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.25 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.3 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
FIRING_DATA_ROW 55.327 1 1.532 12.5 0.0 -8.0 1 0.35 3.02 Red Peony Chain 3" Shells Pos-06 Red Peony Chain 10358
Figure 1 – Example Finale Generic CSV script
Table 4 – Example files
| Download link | Explanation |
| test_finale_generic_32_pin_modules.csv | Example exported file (CSV) |
| test_finale_generic_32_pin_modules.fin | Example show file |
| test_finale_generic_32_pin_modules_8_pin_slats2.csv | Example exported file (CSV) |
| test_finale_generic_32_pin_modules_8_pin_slats.fin | Example show file |