Export Script to Finale Generic CSV

Overview

The Finale Generic CSV is an interchange format for fireworks shows that is human readable and editable. Finale can export and import scripts in this format without loss of information, allowing you to export a script from Finale in the Finale Generic CSV format, work on it in Excel or some other software program, and re-import it back into Finale.

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, custom shell labels, etc.

CSV Format for Tables

The term "CSV" at one time stood for "comma separated values", indicating the manner in which fields are delimited in a row of text. Today the term CSV is applied to a variety of conventions for representing a table of information in a text file so its definition is somewhat murky, but it generally implies a text file that can be viewed and edited in Excel. That's probably all you need to know, but if you are interested in the CSV formatting rules that Finale follows, a full explanation is given here. The explanation also covers Finale's handling of internationalization issues like non-English character sets, commas as decimal points, and non-ASCII character encodings. If you are having problems importing or exporting Finale Generic CSV into other applications, or if you are writing an import/export application yourself, please take a look at the explanation.

Rows in the Table

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.

Firing Rows

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.

The Fields in Each Row

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.

Field

Explanation

(Row Type)

All firing rows begin with the first field, FIRING_DATA_ROW.

Time Cue Number

The number identifying the time cue associated with the ignition, if any. In computer fired shows it is possible for ignitions at different times to be associated with the same time cue since effects with different prefires may be aligned to time cues based on their effect time. This field is blank if the ignition does not have an associated time 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

The X Y Z coordinates of the launch position in meters from the show's reference point, with X to the right from the audience perspective, Y up, and Z toward the audience. In the format of three floating point numbers separated by spaces.

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.

Unused4

Reserved for future use.

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 GUID or URL or other textual representation depending on the software program that generated it. It is guaranteed to be globally unique across different software programs. 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.

Unused8

Reserved for future use.

Unused9

Reserved for future use.

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 short string of up to three characters 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.

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,

Effect Time = Ignition Event Time + Device Delay + Prefire Delay

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.

Strict Format And Comparing Files

It is useful in many circumstances to compare two exported scripts to test if they have equivalent meaning. For example, two Finale Generic CSV scripts that have the same firing rows but in different orders can be said to be equivalent because they represent exactly the same show; the order of the rows has no effect. Unfortunately it is isn't easy for a human to tell if two scripts are equivalent by inspecting them. The optional strict format for Finale Generic CSV files comes the rescue.

The idea of the strict format is to make the equivalence of scripts easy to test by comparing the files to see if they match exactly, character for character. If the two files are both in strict Finale Generic CSV format, then the files are equivalent if and only if they are exactly the same.

To facilitate comparing scripts, when Finale exports a script in Finale Generic CSV format, it always exports the script according to the strict format requirements. Thus if you export a script, then import it, then export it again, you will always get exactly the same file, which you can verify in Excel or with a binary comparison tool.

There is one limitation. Finale is only able to import scripts that use a single firing system, and it requires the Module Description field to match the default firing description field for the supported firing systems.

Finale does not require the strict format for scripts that it imports. Thus you can export a script, edit it or process it in another application, and then re-import it again even if it no longer follows the strict format requirements. You'll end up with exactly the same show.

Strict Format Requirements

The strict format requirements are:

  1. No extra characters are in the CSV file (extra columns, rows, whitespace, etc.).
  2. The rows are sorted according to the strict format sort criteria table (below).
  3. No two rows have the save values for all of their signature fields (see table below). They should be combined if so.
  4. The chain identifiers are numbers counting up from 1 in the order in which the chains are referenced by the sorted rows. The chain identifier for rows not referencing chains is 0.

Field

Sort priority

Comparison method

Signature field

Ignition Event Time

1

Numerical *

YES

Module Address

2

Numerical

YES

Slat Address

3

Numerical

YES

Pin Address

4

Numerical

YES

Device Ignition Time *

5

Numerical

YES

Launch Position Name

6

Lexicographic

YES

Product ID

7

Lexicographic

YES

Manufacturer Product ID

8

Lexicographic

YES

Effect Name

9

Lexicographic

YES

Category Name

10

Lexicographic

YES

Prefire Delay

11

Numerical

YES

Caliber

12

Lexicographic

YES

Track Identifier

13

Lexicographic

YES

Lockout Identifier

14

Lexicographic

YES

Module Description

15

Lexicographic

YES

Unique Animation ID

16

Lexicographic

YES

Notes

17

Lexicographic

YES

Location Primary

18

Lexicographic

YES

Location Secondary

19

Lexicographic

YES

Mortar Caliber

20

Lexicographic

YES

Time Cue Number

21

Numerical

YES

Animation Description

22

Lexicographic

YES

Price Per Device

23

Numerical

YES

Sort Order Of Chain *

24

Lexicographic

NO

Chain Identifier

(not in sort criteria)

YES

* The numerical comparisons accommodate decimal, hexadecimal (for Pyrodigital systems), and alphabetical values. The Device Ignition Time of a Finale Generic CSV row is the sum of the Ignition Event Time and the Device Delay fields of the row. The Sort Order Of Chain is the priority of the chain that the row represents or is part of, based on the priorities of all the shells in the chain, in order, according to 1-23. Because chains may consist of different effects, angles, notes, etc, it may require multiple rows to represent a single chain.


Categories: Category_Firing_System_Export