Note-List Reference

File Format

Note lists are text files with a .txt extension. Data in a note list is space-delimited. Each line of text is called a statement. Each statement starts with a text identifier, traditionally known as an “opcode”.

There are two kinds of statements. header and body. Body statements have timing information; header statements do not.

Note-List Header Statements

The header-statement opcodes are:

• orch — statements have one text parameter, the orchestra file path. A note list must contain exactly one orch statement, which must be the first statement in the file.
• set — statements have one text parameter and one numeric parameter. A note list may not contain more than one set statement of any specific type.
• In a set rate statement, the numeric parameter controls the sampling rate. A note list may contain at most one set rate statement. If no set rate statement is present, the orchestra's default sampling rate is used.
• In a set bits statement, the numeric parameter controls the number of bits per sample. The numeric value may be either 16 or 32. The Sound engine always represents samples in memory as double-precision floating-point numbers, and all calculations are taken to this accuracy. However the WAV file format used to store audio signals stores values either as short (16-bit) integers or long (32-bit) integers. A note list may contain at most one set bits statement. If no set bits statement is present, the orchestra's default sample quantization is used.
• In a set norm statement, the numeric parameter controls wavefile normalization. The parameter value may be either 0 (normalization declined) or 1 (normalization accepted). Normalization means that sample values are originally written to a temporary file with 32-bit accuracy, and that during this first pass, the largest sample magnitude is detected. The sample values are then reprocessed in a second pass, which rescales values so that the largest sample magnitude is 32767. Normalization thus optimizes the signal-to-noise ratio of the final WAV file.
  
  When normalization is elected, the synthesis run will error out whenever any output unit or stereo unit attempts to buffer out a value which causes the combined sample magnitude to exceed 32767. When normalization is deselected, out-of-range samples will not abort the synthesis run. Rather, sample magnitudes exceeding 32767 will be clipped: samples greater than 32767 will write to file as 32767, while samples less than -32767 will write to file as -32767. For this reason it is recommended that you verify that a synthesis run will complete without clipping before engaging normalization.
  
  A note list may contain at most one set norm statement. If no set norm statement is present, the wavefile will not be normalized.
• In a set trace statement, the numeric parameter controls whether or not the output text includes a trace of score events. The parameter value may be either 0 (trace declined) or 1 (trace accepted). A note list may contain at most one set trace statement. If no set trace statement is present, score events will not be traced.
• name — statements have one text parameter, the filename (minus the .wav extension) which which will receive the audio signal. The output file will be created in the same directory as the note list; if a .wav file of the same name already exists, the older file will be overwritten. A note list may contain at most one name statement. If no name statement is present, the notelist name will be used.
• file — statements have three numeric parameters and one text parameter. A note list may contain any number of file statements, or none, but each file present must have a unique ID.
  • Parameter #1 is the file number, which must be a positive integer and which must be unique among the group of file statements.
  • Parameter #2 is the wavefile path. Wavefiles are described here.
  • Parameter #3 is the reference amplitude of the signal, which should range from 0 to 32767.
  • Parameter #4 is the reference frequency of the signal, which should range from circa 16 Hz to well below the Nyquist limit
  • Parameter #5 is the starting sample number, which must be zero or a positive integer.
  • Parameter #6 is the ending sample number, which must be a positive integer.
  • Parameter #7 is the loopback sample number, which must be an integer. When the end-of-file is reached, the wavefile reader loops back to this point. If the loopback number is negative, no loopback occurs.
  The starting sample, ending sample and loopback sample numbers all range from 0 (beginning of file) to the total number of samples per channel channel (end of file). Each of these three numbers should represent points where the signal crosses zero in an ascending direction.

The required order for header statements is:

• orch
• set
• name
• file

Note-List Body Statements

The note-list body opcodes are:

• start — statements have one numeric parameter, the note list starting time in seconds. The start statement is optional, the intent being to test a snippet that will be incorporated into a longer note list. There may be at most one start statement in every note list.
• note — statements have only numeric parameters, of which the first six have fixed definitions. A note list may contain any number of note statements, but each note must have a unique ID.
  • Parameter #1 is the note ID, which must be a positive integer and which must be unique among the group of note statements. When two notes with the same voice ID's play simultaneously, calculations are performed first for the note with the lower note ID.
  • Parameter #2 is the voice ID, which must be zero or a positive integer. If this parameter is 0, no voice is referenced. If this parameter is a positive integer, then a voice with the corresponding ID must be declared in the orchestra. When two notes with different voice ID's play simultaneously, calculations are performed first for the note with the lower voice ID. Combined with the calculation-order rule for note ID's, this means if one note shares information with a second note using a voice-level signal, then both notes must share the same voice id, and the transmitting note must have a lower ID than the receiving note.
  • Parameter #3 is the instrument ID, which must be a positive integer. An instrument with the corresponding ID must be declared in the orchestra.
  • Parameter #4 is the slur-from ID, which must be zero or a positive integer. If this parameter is 0 then the present note is not slurred. If this parameter is a positive integer, then the note list must contain another note (the slur-from note) whose ID matches this value. In addition, the slur-from note must end when the present note starts and must employ the same instrument number (parameter #3).
  • Parameter #5 is the note start time, in seconds. This parameter must be a non-negative decimal number, rounded to the nearest hundredth.
  • Parameter #6 is the note duration, in seconds. This parameter must be a positive decimal number, rounded to the nearest hundredth.
• ramp — statements have six numeric parameters, all of which have fixed definitions. A note list may contain any number of ramp statements, but each contour's ramp statements must fill the time period from 0 to the note-list end time without overlaps.
  • Parameter #1 is the voice ID, which must be zero or a positive integer. If this parameter is 0, no voice is referenced. If this parameter is a positive integer, then a voice with the corresponding ID must be declared in the orchestra.
  • Parameter #2 is the contour ID, which be a positive integer. A contour with the corresponding ID must be declared in the orchestra, as a component of the voice referenced by parameter #2. Understand that if two or more voices share contours with both the same ID and the same index, then ramp statements provided for any voice will affect all voices concerned.
  • Parameter #3 is the ramp start time, in seconds. This parameter must be a non-negative decimal number, rounded to the nearest hundredth.
  • Parameter #4 is the ramp duration, in seconds. This parameter must be a positive decimal number, rounded to the nearest hundredth.
  • Parameter #5 is the ramp origin, which is decimal. If the contour identified by parameters 2 and 3 has an exponential calculation mode, then this parameter must be positive; otherwise the parameter is optionally restricted using limits set within the orchestra.
  • Parameter #6 is the ramp goal, which is decimal. If the contour identified by parameters 2 and 3 has an exponential calculation mode, then this parameter must be positive; otherwise the parameter is not optionally restricted using limits set within the orchestra.
• end — statements have one numeric parameter, the note list ending time in seconds. There must be exactly one end statement in every note list.

The suggested order for body statements is:

• start
• ramp
• note
• end