Type any phrase to search documentation

Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediateLast updated: July 2, 2021

5 Apex

Finale 3D supports the Apex firing system and modules, including the M32, M144 and M156. Exported scripts are also compatible with the older ATF brand versions of the Apex modules. To create and download a script for the Apex firing system, please follow these steps:

  1. Address the show (“Addressing > Address show”).
  2. Export the script (“File > Export > Export firing scripts“).
  3. Export the sound track as a WAV file to the same directory (“File > Export > Export soundtrack…”).
  4. Use the Apex software to download the script and sound track to your controller.

Step 2 creates the script file, which is a text file with a “SHO” extension. It is possible to edit this file in a text editor, but obviously the user must be careful not to make changes that make it incompatible with the Apex controller software.

 

 

Figure 1 – The Apex firing system controller CIM2 controls up to 128 independently addressed modules.

 

Table 1 – File format and encoding

File formatExtensionText encodingField delimiterEnd-of-line
Text.SHOASCIICommaCRLF

 

The script contains rows for the firing events, i.e., unique combinations of module, slat, 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 characteristicsDescription
Sort order of rowsRows are sorted ascending by event time.
What rows representEach 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.
HeaderThe exported script file contains a header identifying the sound track and the communications port, in addition to a mapping of position names to an index beginning with 1, and a list of calibers, and a mapping of module numbers to module types.

In the example below the rows beginning with “area” contain the names of the positions (“M32-1” and “M32-2” and so on in this example) and an index.

The rows beginning with “caliber” enumerate the sizes used in the show. In this example, “na” stands for “not applicable” and “2” stands for 2 inch.

The rows beginning with “module” comprise a sorted list of module numbers used in the show, and the corresponding module types: “m32” or “m144” or “m156”.

REM, Script file exported by Finale 3D for ATF and Apex Firing Systems
music,C:\Users\will\Downloads\test-apex01.wav
comm,1
area,M32-1,1
area,M32-2,2
area,M32-3,3
area,M32-4,4
area,M32-5,5
area,M32-6,6
area,M32-7,7
area,M32-8,8
area,M32-9,9
area,M156-1,10
area,M156-2,11
caliber,na
caliber,2
module,1,m156
module,2,m156
module,3,m32
module,4,m32
module,5,m32
module,6,m32
module,7,m32
module,8,m32
module,9,m32
module,10,m32
module,11,m32

The position names are limited to 6 characters, and must not include space, backslash, double quote, newline, tab, or comma. Finale 3D will automatically truncate positions names that are too long and if necessary add letters to make them unique, as in changing “ABCDEFGX” and “ABCDEFGY” and “BBCDEFG” to “ABCD~a” and “ABCD~b” and “BBCDEF”. Caliber strings are limited to 40 characters, though that usually isn’t an issue.

Time resolutionThe Apex digital systems support 1/30th second time resolution (“frames”). Older ATF hardware has a requirement that events on the same module are separated by at least 1/15th second (2 frames), so if you get a warning message in your ATF software you may need to edit the event times manually to separate them, or separate them manually in the script.
Module numberingThe M32 32-pin module numbers are integers beginning with 1.

The M144 and M156 module numbers are also integers beginning with 1; and their 12-pin slats are enumerated with letters from ‘a’ to ‘l’ or ‘a’ to ‘m’ respectively.

All modules share the same module numbering universe, regardless of their type.

Electrical constraintsIn the export function, Finale 3D automatically adjust times if necessary to accommodate two electrical constraints of Apex and ATF hardware:

  1. If multiple pins fire at the same time on the same module, separate them by one frame.
  2. If pins on more than 20 modules fire simultaneously, separate those beyond 20 as necessary by one frame.

 

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 nameDescription
Position indexThe index of the position in the positions map in the header (see Table 2, above).
CaliberThe effect size.
Module numberThe module number from 1 to 128 (see Table 2, above).
Slat letterThe slat letter “a” to “l” for M144 modules, “a” to “m” for M156 modules, or blank for M32 modules (see Table 2, above).
Pin numberThe pin number 1-32 for M32 modules and 1-12 for slats.
Event timeThe firing ignition time, formatted HH:MM:SS:FF, where FF is a frames count 0-29.
DescriptionThe effect description, up to 127 characters, and not including space, backslash, double quote, newline, tab, or comma (which Finale 3D will remove when exporting).

 

An example script is shown below. The two M156 positions, M156-1 and M156-2, share a common module (01) but do not share slats, which is a common addressing pattern for Apex systems because a module with 144 or 156 total pins can often serve more than one position, yet it is useful to constrain slats to one position each so as not to require long e-matches. See Slats, virtual slats, and splitter boxes for further explanation of addressing techniques involving slats.

 

REM, Script file exported by Finale3D for ATF and Apex Firing Systems
music,C:\Users\will\Downloads\test-apex01.wav
comm,1
area,M32-1,1
area,M32-2,2
area,M32-3,3
area,M32-4,4
area,M32-5,5
area,M32-6,6
area,M32-7,7
area,M32-8,8
area,M32-9,9
area,M156-1,10
area,M156-2,11
caliber,na
caliber,2
module,1,m156
module,2,m156
module,3,m32
module,4,m32
module,5,m32
module,6,m32
module,7,m32
module,8,m32
module,9,m32
module,10,m32
module,11,m32
1,2,3,,1,00:00:02:23,Red Chrysanthemum
2,2,4,,1,00:00:03:23,Red Chrysanthemum
3,2,5,,1,00:00:04:23,Red Chrysanthemum
4,2,6,,1,00:00:05:23,Red Chrysanthemum
5,2,7,,1,00:00:06:23,Red Chrysanthemum
6,2,8,,1,00:00:07:23,Red Chrysanthemum
7,2,9,,1,00:00:08:23,Red Chrysanthemum
8,2,10,,1,00:00:09:23,Red Chrysanthemum
9,2,11,,1,00:00:10:23,Red Chrysanthemum
10,2,1,a,1,00:00:17:11,Red Comet
10,2,1,a,2,00:00:17:26,Red Comet
10,2,1,a,3,00:00:18:11,Red Comet
10,2,1,a,4,00:00:18:26,Red Comet
10,2,1,a,5,00:00:19:11,Red Comet
10,2,1,a,6,00:00:19:26,Red Comet
10,2,1,a,7,00:00:20:11,Red Comet
10,2,1,a,8,00:00:20:26,Red Comet
10,2,1,a,9,00:00:21:11,Red Comet
10,2,1,a,10,00:00:21:26,Red Comet
10,2,1,a,11,00:00:22:11,Red Comet
10,2,1,a,12,00:00:22:26,Red Comet
10,2,1,b,1,00:00:23:11,Red Comet
10,2,1,b,2,00:00:23:26,Red Comet
10,2,1,b,3,00:00:24:11,Red Comet
10,2,1,b,4,00:00:24:26,Red Comet
10,2,1,b,5,00:00:25:11,Red Comet
10,2,1,b,6,00:00:25:26,Red Comet
10,2,1,b,7,00:00:26:11,Red Comet
10,2,1,b,8,00:00:26:26,Red Comet
10,2,1,b,9,00:00:27:11,Red Comet
10,2,1,b,10,00:00:27:26,Red Comet
10,2,1,b,11,00:00:28:11,Red Comet
10,2,1,b,12,00:00:28:26,Red Comet
10,2,1,c,1,00:00:29:11,Red Comet
10,2,1,c,2,00:00:29:26,Red Comet
10,2,1,c,3,00:00:30:11,Red Comet
10,2,1,c,4,00:00:30:26,Red Comet
10,2,1,c,5,00:00:31:11,Red Comet
10,2,1,c,6,00:00:31:26,Red Comet
10,2,1,c,7,00:00:32:11,Red Comet
10,2,1,c,8,00:00:32:26,Red Comet
11,2,2,a,1,00:00:33:11,Red Comet
11,2,2,a,2,00:00:33:26,Red Comet
11,2,2,a,3,00:00:34:11,Red Comet
11,2,2,a,4,00:00:34:26,Red Comet
11,2,2,a,5,00:00:35:11,Red Comet
11,2,2,a,6,00:00:35:26,Red Comet
11,2,2,a,7,00:00:36:11,Red Comet
11,2,2,a,8,00:00:36:26,Red Comet
11,2,2,a,9,00:00:37:11,Red Comet
11,2,2,a,10,00:00:37:26,Red Comet
11,2,2,a,11,00:00:38:11,Red Comet
11,2,2,a,12,00:00:38:26,Red Comet
11,2,2,b,1,00:00:39:11,Red Comet
11,2,2,b,2,00:00:39:26,Red Comet
11,2,2,b,3,00:00:40:11,Red Comet
11,2,2,b,4,00:00:40:26,Red Comet
11,2,2,b,5,00:00:41:11,Red Comet
11,2,2,b,6,00:00:41:26,Red Comet
11,2,2,b,7,00:00:42:11,Red Comet
11,2,2,b,8,00:00:42:26,Red Comet
11,2,2,b,9,00:00:43:11,Red Comet
11,2,2,b,10,00:00:43:26,Red Comet
11,2,2,b,11,00:00:44:11,Red Comet
11,2,2,b,12,00:00:44:26,Red Comet
11,2,2,c,1,00:00:45:11,Red Comet
11,2,2,c,2,00:00:45:26,Red Comet
11,2,2,c,3,00:00:46:11,Red Comet
11,2,2,c,4,00:00:46:26,Red Comet
11,2,2,c,5,00:00:47:11,Red Comet
11,2,2,c,6,00:00:47:26,Red Comet
11,2,2,c,7,00:00:48:11,Red Comet
11,2,2,c,8,00:00:48:26,Red Comet

Figure 2 – Example Apex script

 

Table 4 – Example files

Download linkExplanation
test-apex01.shoExample exported script
test-apex01.finExample show file