Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: August 1, 2019

18 Merlin

To create and export a script for the Merlin firing system, please follow these steps:

  1. Address the show (“Addressing > Address show”).
  2. Export the script (“File > Export > Export firing scripts“).

Step 2 creates the script file, which is a standard format CSV file with a “CSV” extension.  The file format details are described in this section.

 

Figure 1 – Merlin firing system

 

Table 1 – File format and encoding

File format Extension Text encoding Field delimiter End-of-line
Text .CSV ASCII Comma CRLF

The script contains rows for the firing events, i.e., unique combinations of module, pin, and ignition-time.  Multiple effects can be combined on a single cue.  The special characteristics of the script are shown in the following table:

 

Table 2 – Special characteristics

Special characteristics Description
Sort order of rows Rows sorted ascending by event time, then by module number, then by pin number.
What rows represent Each row represents a unique firing event, a module/pin/event-time combination.  For example, a chain of five shells will be one row, not five.  A pair of shells shot together from the same position will be one row, not two, even if the shells are different effects.  A flight of shells shot together from multiple positions with the same module-pin using scab wire is still one row.
Header The file contains a single header row with the column names: Shot Number,Shot Time,Break Time,Number Of Devices,Devices Per Piece,Number Of Pieces,Product ID,Mfg And Mfg ID,Item Name,Caliber,Angles,Position Name,Module Type,Module Address,Slat Address,Pin Number,Notes.
Time resolution The Merlin system supports hundredth of a second resolution.
Special characters The CSV file follows Excel rules for quoting double quotes and commas within the fields. Except for those two characters, all other printable ASCII characters are allowed. Non-ASCII characters and unprintable ASCII characters (control characters like linefeed and tab) are filtered out.

After the header, each row in the script has a number of fields separated by the comma character.   If any field contains a comma or double quote character, the field will be surrounded in double quotes and any internal double quotes will be doubled-up, following the Excel CSV convention.  The names of the fields and their descriptions are the following:

Table 3 – Specifications of script fields

Field name Description
Shot Number A count of unique module/pin/event-times, starting with 1. Scripts exported from Finale 3D represent every unique module/pin/event-time as a firing row, consolidating all events with that module/pin/event-time into the row. Thus the Shot Number is a simple incrementing row count for scripts exported from Finale 3D. Scripts exported from Finale Business may contain multiple firing rows with the same module/pin/event-time, if the script contains multiple events with the same module/pin/event-time but differing in other respects, such as angle or part number. The Shot Number in scripts exported from Finale Business does not increment between rows having the same module/pin/event-time.
Shot Time Time of ignition in the format MM:SS.DD.
Break Time The earliest effect time of the effects represented by the firing row, in the format MM:SS.DD. For example, if the row represented a 3″ and 5″ shell ignited by the same pin, the effect time would be that of the 3″ shell since it breaks earlier than the 5″ shell ignited at the same time.
Number Of Devices Total number of shells represented by the firing row, e.g., a chain of 5 implies Number Of Devices = 5.
Devices Per Piece The number of devices represented by each stock keeping unit for the part number represented by the row, e.g., for some companies a chain of 5 is a single stock keeping unit, for which the Devices Per Piece is thus 5. Finale 3D always writes 1 in this field.
Number Of Pieces Total number of stock keeping units represented by this row, e.g., for some companies a chain of 5 is a single stock keeping unit and thus one piece. Finale 3D always writes the total number of devices for this field.
Product ID Part number.
Mfg And Mfg ID The manufacturer name followed by, in parentheses, the manufacturer’s part number for the item represented by the row; unless either such field is blank, in which case this field just includes the non-blank value, if any.
Item Name Description.  If the row represents multiple effects, the description begins with the number of effects in parentheses, continues with the first effect name, and ends with elipsis (…) as an indication the row represents more than is being displayed in this single field.
Caliber Size.
Angles Angle graphic in ASCII art, showing the angles of the represented effects in backslash, vertical line, and slash characters.
Position Name Position name.
Module Type Module type.
Module Address Module number, starting with 1.
Slat Address Blank.
Pin Number Pin number, starting with 1.
Notes Script notes.

An example script containing six (11) shells across nine (9) firing rows is shown in Figure 1 and included for download in Table 4.  In this script, the last two rows each represent two effects ignited from the same pin.

Shot Number,Shot Time,Break Time,Number Of Devices,Devices Per Piece,Number Of Pieces,Product ID,Mfg And Mfg ID,Item Name,Caliber,Angles,Position Name,Module Type,Module Address,Slat Address,Pin Number,Notes
1,00:02.76,00:05.00,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-01,merlin_32ch,1,,1,
2,00:02.86,00:05.10,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-02,merlin_32ch,2,,1,
3,00:02.96,00:05.20,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-03,merlin_32ch,3,,1,
4,00:03.06,00:05.30,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-04,merlin_32ch,4,,1,
5,00:03.16,00:05.40,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-05,merlin_32ch,5,,1,
6,00:03.26,00:05.50,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-06,merlin_32ch,6,,1,
7,00:03.36,00:05.60,1,1,1,G2SH1003,,Green Chrysanthemum,"2""",|,Pos-07,merlin_32ch,7,,1,
8,00:03.46,00:05.70,2,1,2,G2SH1003,,(2) Green Chrysanthemum ...,"2""",||,Pos-08,merlin_32ch,8,,1,
9,00:03.56,00:05.80,2,1,2,G2SH1003,,(2) Green Chrysanthemum ...,"2""",||,Pos-09,merlin_32ch,9,,1,

Figure 1 – Example Merlin script

 

Table 4 – Example files

Download link Explanation
test_merlin.fin Example show file
test_merlin.csv Example exported file (CSV)