Nightingale Notelist described

THE NIGHTINGALE NOTELIST by Tim Crawford (with Donald Byrd and John Gibson)

(This is the full text of Chapter 21 of the book Beyond MIDI: The Handbook of Musical Codes, edited by Eleanor Selfridge-Field (MIT Press, 1997), except for a long concluding example of a notelist [and some small edits in August, 2000]. It describes the notelist format as of Nightingale 3.0A; for changes in versions 3.5 through 4.5, see the file "N'Gale Notelist Tech. Update" distributed with Nightingale 4.5 and below. Copyright (c) 1997, Center for Computer Assisted Research in the Humanities (CCARH). Reprinted with the kind permission of CCARH and of MIT Press.)

The musical notation program Nightingale was developed for the Apple Macintosh computer by a team led by Donald Byrd at Advanced Music Notation Systems. It makes the fullest use of the graphical user interface of the Macintosh operating system developed by Apple Computer, and in accordance with the ideals of this system, encoding methods for data input are avoided entirely. In the case of note entry, for example, the user chooses a symbol from an on-screen palette by means of the mouse pointer (or uses one of the user-configurable keyboard shortcuts), thus causing the cursor itself to change shape to that symbol. Symbols chosen in this way are then placed in the score by a simple mouse-click. Alternatively, a MIDI keyboard can be used for note entry in step- or real-time. The symbols can be entered in more or less any order and any position on any page of the score (subject to certain logical restraints). They do not have to be entered in a temporal sequence, and one measure does not need to be filled before music can be entered into the next. By analogy with working with conventional manuscript paper and pencil, a score does not have to be "complete" at any stage. This has clear advantages for the working practice of composers or arrangers. It enables the production of music examples, which can later be incorporated into page-layout programs as Encapsulated PostScript (EPS) files. These may represent sketches, fragments, or otherwise incomplete musical extracts, as well as complete and logically consistent scores.

21.1 General Description

21.1.1 Data-Sharing Provisions of Nightingale

21.1.2 Notelist and Nightingale's Data Structure

Notelist can best be described as a snapshot of the structural features of a native Nightingale file. It does not, therefore, aim to represent fully the graphical appearance of the score (as is the avowed intention of codes such as NIFF) or simply the sequence of musical events within individual voices (as does a Format-1 MIDI file). Musical events are listed as they occur in time. After an initial code letter identifying the type of musical event, the first parameter for most musical events in a score is the time at which that event occurs (measured from the beginning of the score). This time parameter is calculated from the logical notated durations of previously occurring objects, not from performance data. In this respect, a Notelist is unlike a MIDI file, which takes account of tempo fluctuations and ignores notational aspects altogether. Certain types of events, however, are not explicitly time-stamped, and are simply inserted in their sequential position in the Notelist. Their temporal location must be inferred from the context. These include key and time signatures, tuplets, tempo markings, dynamics, and text strings. Notes or rests belonging to a tuplet group are explicitly flagged as such in the Notelist. In a single tuplet group all notes and rests must belong to the same voice and part (or instrument), although the notes and rests may appear on different staves within the part. Each tuplet group is represented by a single "Tuplet" record, which must be inserted into the Notelist at some point before the first note or rest in the group. A bar line may not intervene between the tuplet record and the final note or rest in the tuplet group. (In other words, tuplets cannot extend over bar lines.) Notelist does, however, incorporate the data necessary for performance of a score. As well as the timing data of a note's onset and its pitch (as the MIDI note number), it includes MIDI velocity and "play duration," which corresponds to the difference between Note_On and Note_Off times in a MIDI data stream. Notelist, however, shares with its parent program the ability to cope with music written without bar lines or without time signatures. Alignment of music within measures is dependent on the timing information. If this information disagrees with the logical duration of the notes in the measure as given in the Notelist, the consequences may be unpredictable. As a general rule, if the logical duration (ldur) of a note implies an elapse of time less than the difference between that note's onset and that of the next event applying to the same voice as given by the timing data (deltaT), Nightingale's data structure can accommodate a gap in that voice. If, however, ldur is greater than deltaT (implying events overlapping within a voice), an illegal situation has occurred. Nightingale's "Open Notelist" routine would generate an error message and probably reject the file in such a situation. Notelist also records the "play duration" of notes, allowing the incorporation of articulation or pedalization; this performance information, being concerned only with note-release time offsets, is independent of the logical duration and timing data, and is thus not restricted.

21.1.3 Comments and Header Information

Comments can be added as records anywhere in a Notelist. They are identified by a percentage sign (%) at the beginning of the line. For comments longer than a single line, a new percentage character must begin each line. In order to simplify the task of parsing a Notelist file in order to recreate a score, it has been found necessary to add a simple structured-comment record type (as in PostScript) to the Notelist specification to carry important global data otherwise inferable only by scanning the entire file. At present, this is limited to the name of the file from which the Notelist was generated (by Nightingale, for example), and a listing of the basic structure of the score extract encoded. This concept may be extended in future.

21.1.4 Limitations and Caveats

A. Limits of Notation
A Notelist file is restricted to the limits of normal musical notation as represented in the extensive capabilities of Nightingale itself. This fact should be borne in mind by those considering producing their own Notelists for import into Nightingale. It is, for example, necessary that a score is fully quantized in the MIDI sense, and that highly complex or nested tuplet groups are avoided. For tuplets, the Notelist format merely records that a note forms part of a tuplet group; the parsing program must infer the structure of the tuplet from the timing data and the logical ("as notated") durations of its members.
B. Text and Other Graphics
In the interests of comprehensibility, the Notelist is restricted to the basic musical data most likely to be of use to musicologists and composers, rather than including graphical details of importance to publishers or engravers. Purely graphical items (lines, boxes, circles, and graphics created by the use of non-standard font characters) are not recorded in the Notelist. It is unlikely that musical data recorded in graphical forms of notation can be meaningfully shared between programs in any case, without declaring the kind of standardized prescriptions for their use that such notations are designed to avoid.

21.1.5 "Incomplete" Notelists

Nightingale allows the user to select either a contiguous region of a score (a "continuous" selection) or non-adjacent objects from anywhere in the score. A Notelist can be generated for any such selection regardless of the musical result. It is the responsibility of the parsing routine to test the timing data and sequence of logical durations in the Notelist for these conditions, and reject or accept it depending on the use to which the data is to be put.

21.1.6 Invisible Objects

A. Bar lines
Bar lines in individual voices can be made invisible in Nightingale, thus enabling the user to "fake" the appearance of a score with different barrings in different voices, for example; within the data structure, however, each bar line's occurrence in time applies across the entire score and a bar line will be recorded in the Notelist.
B. Notes
Noteheads, or entire notes or rests, can be made "invisible" in Nightingale. They exist in the data structure, but are not seen on the screen and they will not be printed (in the default situation, that is; a global command is provided which makes invisible objects visible on screen and in print). Invisible notes may or may not have performance implications, so they do carry MIDI information like any other notes. They thus appear in the Notelist, but with their appearance (appear=) parameter set to 0. It is the responsibility of the parsing program to decide whether or not to ignore them, or even make them invisible.

21.1.7 Unusual Notational Effects and Data Structure

A. Moveable Objects in the Score
One important aspect of Nightingale's flexibility is the ability to move objects graphically some distance from their default positions. The Notelist only records their default or original entry position, not the visual displacement. This can have unforeseen consequences when, for example, slurs have been adjusted to extend over notes not included within the region of the score to which they were originally attached.
B. Appearance and Pitch
Just as notes may be made invisible within Nightingale, their appearance can be altered from the normal defaults. In some cases, this could lead to an apparent conflict with the musical intentions of the score. For example, in violin and guitar music, harmonics are often (but not universally) indicated by combining on a single stem a normal note representing the fingerboard position to be stopped with a diamond-shape note showing the harmonic node to be touched. Neither note has any real musical meaning: the actual sounding pitch is different from the written pitch, but the difference depends on the combination. Nightingale by default records the notated pitch of the notes but allows the user to change the pitch of any note as well as its appearance. The Notelist will reflect such changes, which may or may not indicate the sounding pitch.
C. Octave Transposition
Passages requiring transposition by one (8va) or two (15ma) octaves are recorded in a Nightingale Notelist at sounding pitch.
D. Transposing Instruments
Transposing instruments are recorded in a Nightingale Notelist as they are notated in the score. It is the responsibility of the parsing program to recalculate pitches if necessary.

21.1.8 File Size

Since the Notelist format was designed to be readable by human beings as well as machines, it is not as economical in terms of file size as it might be were it intended only for machines. In the description that follows, it will be seen that there is much redundant repetition of field identifiers, each of which is followed by an "equals" sign (=). The field identifiers and the equals signs may be omitted from the Notelist; all parsing routines should ignore them. This can considerably reduce the necessary disk space occupied by a Notelist file.

21.1.9 Plans for Further Development

This description, while it is as accurate as possible at the time of writing, does not constitute a final, binding definition of the Notelist format. There will possibly be some minor changes to the format in the future. The description should at least provide a sound working basis for the use of Notelists, and should be supplemented by reference to the documentation of Nightingale available from the publishers, Adept Music Notation Solutions, Inc.

21.2 Code Description

The Nightingale Notelist is an ASCII text file consisting of records delimited by return characters. Each record, or line of the text file, relates to an individual musical event and thus to an object in a Nightingale score. Within each record, fields are delimited by space characters.
For each object, the first field contains a single symbol to identify the type of object:
Time-stamped Sequentially located
N note % comment
G grace note %% structured comment/header info
R rest
C clef
/ bar line
K key signature
T time signature
P tuplet
M tempo marking
A text string
D dynamic
For each object in the column headed "time-stamped," the second field gives the logical time (t=n) elapsed from the beginning of the score to the point at which the event occurs. Logical time refers to the sum of the time intervals between previous events as indicated in the notation alone, ignoring any effects due to expression marks or performance indications. The units are 480ths of a quarter note. The remainder of the parameters in the Notelist are dependent on the object type. All numbers in Notelists are integers.

21.2.1 Notes

[N] Note records are initiated with the character N. The order of elements used in the specification of a note is as follows: N t= v= npt= stf= dur= dots= nn= acc= eAcc= pDur= vel= ...... appear= mods=
Each of these parameters is explained below.

A. Time [t=] The time in 480ths of a quarter note elapsed from the beginning of the score to the onset of the note (1..32000).
B. Voice [v=] The number of the polyphonic voice within a part, or instrument, to which the note is assigned (1..31).
C. Part Number [npt=] The part (or instrument) number (1..64).
D. Staff [stf=] The number of the staff in the system on which the note occurs (1..64).
E. Duration Code [dur]
0 unknown duration [displayed as a stemless quarter note]
1 double whole note (breve)
2 whole note (semibreve)
3 half note (minim)
4 quarter (crotchet)
5 eighth (quaver)
6 sixteenth (semiquaver)
7 thirty-second (demisemiquaver)
8 sixty-fourth (hemidemisemiquaver)
9 one-hundred-twenty-eighth

F. Number of Dots [dots=] The number of augmentation dots associated with the note. The range depends on the duration of the note:
128ths 0
64ths 0..1
32nds 0..2
16ths 0..3
eighth 0..4
quarters 0..5
half notes 0..6
whole notes 0..7
breves 0..8

G.MIDI Note Number [nn=] The note's pitch expressed in semitones, with Middle C = 60, the C sharp above it = 61, etc. (0..127).
H. Accidental Code [acc=] The explicit accidental sign displayed with the note (0..5). The codes are:
0 no accidental
1 double flat
2 flat
3 natural
4 sharp
5 double sharp

I. Effective Accidental Code [eAcc=] The implicit effective accidental applying to the note (1..5; values as for the acc field described above.)
J. Play Duration [pDur=] The actual duration (1.32000) for which the note should be sounded, regardless of the notation. This parameter is principally used for articulation and pedalling effects. In a Nightingale Notelist, this would usually be different from the logical (notated) duration, either by a default user-definable percentage or as the actual duration of the note as recorded over MIDI. Units are as for time (t=).
K. MIDI ON Velocity [vel=] A numerical value (0..127) representing the downward velocity of the sounding keystroke on a synthesizer or other MIDI instrument. This parameter usually corresponds to audio volume. A MIDI velocity of 0 represents a non-sounding note, equivalent to a rest.
L. Note-Attribute Flags [......] A series of six characters (not separated by spaces, and not preceded by an equal sign [=]) representing certain attributes of a note. Each character can either be a period (default) or another character (Char. below) depending on its position (Pos.) in the series: Pos. Char. Meaning
1 + main note (carrying the stem) in a chord
1 - other note in a chord
2 ) tied to the preceding note
3 ( tied to the following note
4 > slurred to the preceding note
5 < slurred to the following note
6 T note is a member of a tuplet group

M. Appearance Code [appear=] A number code for the appearance of the note. This parameter usually applies only to the notehead, but it also allows "chord slashes" as used in jazz lead-sheets, etc., and invisible notes inserted for the convenience of the user but usually without any musical significance. Invisible notes can, however, carry MIDI data e.g., for the realization of ornament signs so they should be tested by the parsing routine.
0 invisible notehead
1 normal appearance
2 x-shape notehead
3 "harmonic" notehead
4 hollow square notehead
5 filled square notehead
6 hollow diamond notehead
7 filled diamond notehead
8 half-note notehead
9 chord slash
10 note invisible (including stem and dots)

N. Modifier Codes [mods=] A number code for various types of note-modifying symbols. Code Meaning Symbol
1 1 (finger number) 1
2 2 (finger number) 2
3 3 (finger number) 3
4 4 (finger number) 4
5 5 (finger number) 5
6..9 (unassigned)
10 fermata
11 trill tr
12 accent >
13 heavy accent
14 staccato .
15 wedge
16 tenuto
17 mordent
18 inverted mordent
19 turn
20 plus sign +
21 circle
22 up-bow
23 down-bow
24 tremolo (1 slash)
25 tremolo (2 slashes)
26 tremolo (3 slashes)
27 tremolo (4 slashes)
28 tremolo (5 slashes)
29 tremolo (6 slashes)
30 heavy accent with staccato
31 long inverted mordent

Multiple modifiers may be attached to a note by listing them separated by commas without spaces, e.g., mods=22,14 (up-bow, staccato).

O. Modifier Data Values Any modifier may optionally carry an associated data value in the range 128 to +127. The data value follows the modifier code after a colon character without any spaces, e.g., mods=22,14:54 (up-bow, staccato with data value of 54).

21.2.2 Grace Notes (G)

Grace-note records are introduced by the character G. The number and order of elements used in the specification of a grace note are the same as those for ordinary notes, e.g. G t= v= npt= stf= dur= dots= nn= acc= eAcc= pDur= vel= ...... appear= mods= except with respect to the codes for duration (dur=), dots (dots=), accidentals (acc=), and attributes (......). These parameters are explained below.

A. Duration Code [dur] The following grace-note durational values are allowed:
4 quarter (crotchet)
5 eighth (quaver)
6 sixteenth (semiquaver)
7 thirty-second (demisemiquaver)

B. Number of Dots [dots=] The number of augmentation dots associated with the grace note.
C. Accidental Code [acc=] The following grace-note accidentals are allowed:
0 no accidental
1 double flat
2 flat
3 natural
4 sharp
5 double sharp

D. Grace-Note Attribute Flag [......] A series of six characters (not separated by spaces, and not preceded by "=") representing certain attributes of a grace note. Each character can either be a period (default) or another character depending on its position in the series: Pos. Char. Meaning
1 + main note (carrying the stem) in a chord
1 - other note in a chord
2* ) tied to the preceding grace note
3* ( tied to the following grace note
4* > slurred to the preceding note or grace note
5* < slurred to the following note or grace note
6* T grace note is a member of a tuplet group

21.2.3 Rests (R)

Rest records are introduced by the character R. The order of elements in a rest specification is as follows: R t= v= npt= stf= dur= dots= ...... appear= mods= Parameters for pitch and velocity are obviously irrelevant.

A. Duration Code [dur=]
-1 whole-measure rest (normally centered in the measure)
-2 to -127 multi-measure rests: number = number of measures
1 double whole note (breve)
2 whole note (semibreve)
3 half note (minim)
4 quarter (crotchet)
5 eighth (quaver)
6 sixteenth (semiquaver)
7 thirty-second (demisemiquaver)
8 sixty-fourth (hemidemisemiquaver)
9 one-hundred-twenty-eighth

G. Rest-Attribute Flags [......] A series of six characters (not separated by spaces nor preceded by an equal sign [=]) representing certain attributes of a rest. Each character can be either a period (default) or another character depending on its position in the series: Pos. Char. Meaning
1 . [no meaning; always "."]
2 ) tied to the preceding note or rest
3 ( tied to the following note or rest
4 > slurred to the preceding note or rest
5 < slurred to the following note or rest
6 T rest is a member of a tuplet group

21.2.4 Bar Lines [/]

Bar-line records are introduced by the forward slash (/). The order of elements in a bar-line specification is as follows: / t= type=
A. Time [t=]
The time in 480ths of a quarter note elapsed from the beginning of the score to the logical end of the previous measure (1..32000).
B. Bar-Line Type Code [type=]
A number code for the appearance of the bar line (1..7).
1 normal bar line
2 double bar line
3 final double bar line
4 heavy double bar line
5 repeat-left double bar line (||:)
6 repeat-right double bar line (:||)
7 repeat-both double bar line (:||:)

21.2.5 Comments [%]

A comment is introduced by the percentage sign (%). The order of elements in a comment specification is as follows:

% <text>