Finale 3D can import shows directly from Show Director’s native SCX file format (“File > Import > Import show…“), but not export shows to that format. For people who need to import shows into Show Director or into other software in a Show Director format, Finale 3D exports a specific “Show Director CSV” format, which is defined in this specification.
If you plan to import into Show Director itself, please select the CSV file type option when choosing the filename. If you plan to import into Excel, then please select the XLSX file type (Excel notoriously imports hexadecimal Pyrodigital addresses as floating point numbers if you import TXT or CSV data and aren’t careful). Finale 3D exports all XLSX cells as text cells. In Excel if you need to convert text cells to number cells, select the cells you want to be convert and click the warning icon, then choose “Convert to numbers” from the context menu.
Finale 3D provides the export options shown in Figure 1. The default Show Director angle convention is “Left = 0, Up = 90” but you can choose other options from this dialog. The cue number column in Show Director can be used for multiple purposes. The default choice in Finale 3D‘s export dialog is simply a row count beginning with zero, but if you want rows with the same effect time to have the same cue number, then you can select that option. The frame rate choice is required to convert absolute times into the frame based representation in the Show Director CSV format. Chains are represented as a single row in Show Director CSV files, but the quantity column may contain the number 1 or the number of shells in the chain, depending on your preference.
Figure 1 – Show Director export options
File specification
The CSV header row defines the fields, which correspond to the columns in the software’s user interface. The specification given here includes a specific subset of fields known to import successfully into Show Director Version 8. However, for clarity and for reliability of importing into various software programs including Show Director itself, the set of fields in this specification has rigid and well-defined requirements for the data formatting of the fields, and does not include all the columns supported by the Show Director user interface.
Table 1 – File format and encoding
| File format | Extension | Text encoding | Field delimiter | End-of-line |
|---|---|---|---|---|
| Text | .csv | ASCII * | , (comma) | CRLF |
Like Finale Generic CSV, the Show Director CSV format is an interchange format, not a format that is loaded directly into firing systems, so the rows in the script contain more information than just the firing events. Although Show Director supports multiple firing systems, its script file format is closely related to the data format downloaded to the Pyrodigital firing system.
* This specification indicates ASCII encoding of the text for reliability of importing into various firing system software. However you may choose to export from Finale 3D in an alternate encoding to support non-English characters, as described in the bottom row of the table below.
Table 2 – Special characteristics
| Special characteristics | Description |
|---|---|
| Time representation | Effect times are represented in hours, minutes, seconds, and frames (HH, MM, SS, FF), based on 30 fps or 29.97 SMPTE DF or 25 fps or 24 fps frame rate, which cannot be determined from the file contents. When exporting from Finale 3D, which supports millisecond resolution, effect times will be rounded to nearest frame time.
Prefire times are represented in the Show Director CSV file in milliseconds. Thus the event times, equaling the effect times minus the prefire times, do not necessarily fall on exact frame times. |
| Sort order of rows | Rows sorted ascending by effect time. |
| What rows represent | Each row contains a set of fields defined in the table below. Field values may be blank if data is missing at the time of export. For example, if you export a show that does not have addresses assigned, the ADDR field will be blank.
Loosely speaking, a row is either a chain, or a group of identical effects fired together. 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, unless the shells are different, in which case it will be two rows. Technically, a row represents one or more effects with the same part number, fired at the same time, with the same address, from the same position. Rows do not combine multiple chains on the same row. Thus if a row represents multiple devices, those devices are all part of the same chain, or they are not part of chains. The quantity of devices represented by a row is determined by the TILT, and PAN fields, as described below, since the devices may be shot at different angles. The QTY field also specifies the number of devices, except for chains, in which case the QTY field specifies either (a) the number of chains each counting as one unit (in which case it will be “1”), or (b) the number of devices in the chain. In Finale 3D, the user specifies whether “Chains count as one unit” when exporting the Show Director CSV file. |
| Chains counting as one unit | Some display companies follow the convention that one chain is one unit for stock keeping records; others follow the convention that a chain of five shells is five units. The Show Director CSV file has a QTY field that represents the number of units. The meaning of this field for chains — whether it is the number of shells in the chain or just one per chain — cannot be determined from the file intrinsically. When you export a Show Director CSV file from Finale 3D, you are presented with a dialog asking if “Chains count as one unit?”. Similarly, if you import a Show Director CSV file into Finale 3D, you are given the option for whether chain quantities indicate the number of chains or devices. |
| Header | The file contains a single header row with the column names, in the same format as the CSV data rows themselves. |
| Special characters | Following the Excel quoting conventions for handling special characters, fields containing a double-quote character (“) or comma will be enclosed in “ on both ends, and any internal double-quote characters will be doubled up. |
| Text encoding for non-English characters | This specification indicates ASCII encoding of the text, which cannot represent non-English letters with accents or orthography from languages with different alphabets. ASCII is the most widely supported character set encoding for firing system software around the world, and ASCII is known to import successfully into Show Director Version 8 and obviously Finale 3D, so it is a good choice for reliability of import. However, since ASCII cannot represent non-English characters, you may prefer using an alternate encoding, such as UTF-8, UTF-16, or CodePage 1252, to represent characters in your language. In the file selection dialog for exporting, Finale 3D gives you the option of exporting the Show Director CSV format in a wide variety of encodings, including UTF-8, UTF-16, Code Page 1252, as well as options for different line endings, field delimiters, and byte-order-marks (BOM), so whatever encoding your software supports, you likely can export in exactly that encoding from Finale 3D. Notably, if you are using Show Director and you are from a Western European or Western country, you may prefer to export in the Code Page 1252 encoding, which can represent characters with accents, as in the French word, Chrysanthème. Although Show Director Version 8 is not able to import Unicode, it is able to import Code Page 1252, which provides some support for some non-English languages. |
After the header, each row in the script has a number of fields separated by the comma character. The names of these fields and their descriptions are the following:
Table 3 – Specifications of script fields
| Field name | Description |
|---|---|
| CUE | (integer, up to 99999) The row number in the script, beginning with 0. |
| HH | (integer, up to 23) The hours component of the effect time. |
| MM | (integer, up to 59) The minutes component of the effect time. |
| SS | (integer, up to 59) The seconds component of the effect time. |
| FF | (integer, from 0 to 29) The frames component of the effect time, based on the frame rate (see time representation in Table 2). |
| Event Description | (text, up to 128 characters) A description pertaining to the row (not the effect itself). Finale 3D exports the Script Notes to this field. |
| PFT | (integer, up to 99999) The prefire time, in milliseconds. |
| ADDR | (text, exactly three characters, or blank) If the controller specified in CONTROL is “pyrodigital”, then the three-character, upper case, hexadecimal string comprising a two-character hexadecimal module address and one-character hexadecimal pin address; or blank if the address is missing. |
| CONTROL | (text, up to 32 characters, or blank) The type of controller for this row of data, either “pyrodigital” or some other controller like “cobra” for example. |
| MODULE | (integer from 0 to 9999, or blank) If the controller specified in CONTROL is not “pyrodigital”, then this field contains the module number for the row, if it is representable as an integer. |
| PIN | (integer from 0 to 9999, or blank) If the controller specified in CONTROL is not “pyrodigital”, then this field contains the pin number for the row, if it is representable as an integer. |
| CGHZ | (integer from 0 to 99, or blank) A numerical hazard class identifier for disabling a group of effects based on show time circumstances. |
| POS | (text, up to 10 characters) The position name. |
| QTY | (integer, up to 9999) The number of devices represented by the row, except for chains, in which case either (a) the number of chains each counting as one unit (in which case it will be “1” since a row can represent at most one chain), or (b) the number of devices in the chain. In Finale 3D, the user specifies whether “Chains count as one unit” when exporting the Show Director CSV file. Since the meaning (a) versus (b) of QTY cannot be determined intrinsically from the file, it is unreliable to infer the number of devices from the QTY field itself. The TILT field, which is required in this specification, determines the quantity of devices represented by the row. |
| CAL | (integer up to 999, or blank) The size of the effect, in millimeters. |
| TYPE | (text, up to 36 characters) The type of effect, e.g., shell, comet, cake, etc. |
| DUR | (four digits, in SSFF format) The duration of the effect or chain. If the effect is a chain, the duration is the time from first to last shot in the chain. The duration is represented as seconds plus frames (see time representation in Table 2). The first two digits SS are the seconds; the second two digits FF are the frames. For example, 0115 means 1.5 seconds if 30 fps. |
| Effect Description | (text, up to 128 characters) Description of the effect, e.g., “Red Peony” |
| REF | (text, up to 50 characters) The part number of the effect. |
| MFG | (text, up to 64 characters) The manufacturer of the effect. |
| PRICE1 | (floating point number with dot character radix) The price per unit. If the row represents multiple, non-chained devices, each device is a unit. If the row represents a chain of devices, the price per unit is either (a) the price of the full chain, or (b) the price of a shell in the chain. In Finale 3D, the user specifies whether “Chains count as one unit” when exporting the Show Director CSV file. |
| CUSTOM1 | (text, up to 128 characters) Finale 3D writes the Universe field from the script |
| CUSTOM2 | (text, up to 128 characters) Finale 3D writes Section field from the script. |
| CUSTOM3 | (text, up to 128 characters) Finale 3D writes the Storage Location of the effect for this field. |
| CUSTOM4 | (text, up to 128 characters) Finale 3D writes script Notes 2 for this field. |
| CUSTOM5 | (text, up to 128 characters) Finale 3D writes script Notes 3 for this field. |
| PAN | (text, up to 255 characters) The pan field represents the rotation angle of the position about the UP-axis, with PAN = 0 being the orientation in which TILT of 0 fires to the left from audience perspective, and PAN = 90 being the orientation in which TILT of 0 toward the foreground. Finale 3D currently writes blank for this field. |
| TILT | (text, up to 255 characters) The tilt field represents the lateral firing angles (left/right from audience perspective) of the devices represented by the row, 0 meaning left, 90 meaning up, and 180 meaning right. If the row represents more than one device, the angles are combined with dashes, such as 60-75-90-105-120 for a fan of five devices in 15 degree intervals. |
An example script is shown below. Notice the first five rows are for Pyrodigital controllers and have the ADDR field included, the next two rows are missing addresses entirely, and the next two rows are for the Cobra controllers and have the MODULE and PIN fields included but not the ADDR field. The test file also includes some Russian words (Красный Пион) and French words (Chrysanthème Crépitant) to demonstrate text encoding differences with various example text encodings: ASCII, Code Page 1252, and UTF-8-NOBOM (Unicode), and UTF-16LE-BOM (Unicode).
CUE,HH,MM,SS,FF,Event Description,PFT,ADDR,CONTROL,MODULE,PIN,CGHZ,POS,QTY,CAL,TYPE,DUR,Effect Description,REF,MFG,PRICE1,CUSTOM1,CUSTOM2,CUSTOM3,CUSTOM4,CUSTOM5,PAN,TILT
0,00,00,05,00,notea,3020,010,pyrodigital,,,,Pos-01,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
1,00,00,05,00,noteb,3020,020,pyrodigital,,,,Pos-02,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
2,00,00,05,00,,3020,030,pyrodigital,,,,Pos-03,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
3,00,00,05,00,,3020,040,pyrodigital,,,,Pos-04,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
4,00,00,05,00,,3020,050,pyrodigital,,,,Pos-05,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
5,00,00,05,00,,3020,,,,,,Pos-06,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
6,00,00,05,00,,3020,,,,,,Pos-07,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
7,00,00,05,00,,3020,,cobra,0,0,,Pos-08,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
8,00,00,05,00,,3020,,cobra,1,1,3,Pos-09,1,76,shell,0116,Красный Пион,10386,lidu,0.0,,,,,,,90
9,00,00,12,07,notec,3020,011,pyrodigital,,,4,Pos-01,1,76,shell,0006,Salute Chain,10390,dominator,15.0,,,,,,,60-75-90-105-120
10,00,00,17,11,,3020,012,pyrodigital,,,4,Pos-01,1,76,shell,0003,Salute Chain,10390,dominator,9.0,,,,,,,60-75-90
11,00,00,17,11,,3020,013,pyrodigital,,,4,Pos-01,1,76,shell,0006,Salute Chain,10390,dominator,15.0,,,,,,,60-75-90-105-120
12,00,00,29,26,,2240,014,pyrodigital,,,,Pos-01,2,50,shell,0101,Chrysanthème Crépitant,G2SH1003,Generic,1.45,,,,,,,75-105
13,00,00,44,26,,2240,015,pyrodigital,,,,Pos-01,2,50,shell,0101,"3"" Orange Chrysanthemum",G2SH1007,Generic,1.45,,,,,,,75-105
14,00,00,44,26,,2240,015,pyrodigital,,,,Pos-01,2,50,shell,0101,"Variegated Chrys, BIG",G2SH1012,Generic,1.45,,,,,,,75-105
Figure 1 – Example Show Director CSV script
Table 4 – Example files
| Download link | Explanation |
|---|---|
| test_showdirectorcsv_ascii.csv | Example exported file, ASCII text encoding (CSV) |
| test_showdirectorcsv_codepage1252.csv | Example exported file, Code Page 1252 text encoding (CSV) |
| test_showdirectorcsv_utf16le_bom.csv | Example exported file, UTF-16LE with BOM Unicode text encoding (CSV) |
| test_showdirectorcsv_utf8_nobom.csv | Example exported file, UTF-8 no BOM Unicode text encoding (CSV) |
| test_showdirectorcsv.fin | Example show file |