(Revised 1/11/01) Multivoice abc - can we all use the V: field? The development of abc has proceeded ahead of the standard, and this has led to some incompatibility problems between different programs. Multivoice abc is one of the more complex areas, and has given rise to the most disagreement between developers. The object of this page is to document the way in which the various programs handle multivoice abc and to highlight the differences. Currently the following programs support multivoice abc: abc2ly (Unix) abc2midi (Unix, Windows, Mac) abc2nwc (Windows) abc2ps (and variants, including abctab2ps, jcabc2ps, abcm2ps and jaabc2ps) (Unix, Windows, Mac)* BarFly (Mac) Melody Assistant (Windows, Mac) Muse (Windows) Virtual Composer (Mac) yaps (Unix, Windows, Mac) * Not all abc2ps variants are available for all platforms yet. the abc2ps family and yaps convert abc to postscript files; Melody Assistant, Muse and Virtual Composer are GUI music editors which export and import abc (VC only exports). abc2midi converts abc to standard midi files, while BarFly is an integrated program which edits, displays and plays abc files. Virtual Composer follows BarFly closely in its abc syntax, and needs no further mention. abc2ly converts abc to source code for Lilypond (another text-based music system), and closely follows abc2ps, while abc2nwc converts abc to Noteworthy Composer (a GUI music editor) format. The information given here is taken from the documentation supplied with the programs. Excerpts from the programs' documentation are attached as an appendix. Documentation is mostly quite sparse, with the notable exceptions of abctab2ps and BarFly. The documentation of Muse and Melody Assistant do not mention multivoice abc at all, and the information given here was obtained by experiment. ---------------------------------------------------------------------- Common ground. Multivoice abc was introduced first by James Allwright, the author of abc2midi, and the basic format is supported (more or less) by all of the programs. The header of a multivoice tune is constructed exactly in the same way as a single voice tune, but the tune section is broken up into a number of segments, each of which is labelled by means of a V: field containing a number. The following example is taken from the demo files supplied with abc2midi: X: 4 T: Candlemas Eve S: Hymn 126 Arr. R. Herrick from an old church-gallery book M:4/4 L:1/8 Q:1/8=400 N:from an old church-gallery book H:The old church-gallery book was discovered by the Rev. L.J.T. Darwall. H:The source has a 4-part harmony. O:English R:Reel K:G V: 1 % soprano D2 |\ G2 G2 B2 G2 | E2 F2 G2 Bd | c2 B2 A2 G2 | A6 Bc | d2 B2 G2 AB | c2 A2 F2 GA | B2 G2 E2 F2 | G6 Bc | d2 d2 d2 B2 | e2 c2 A2 Bd | c2 B2 A2 G2 | d6 B2 | e2 d2 c2 B2 | A2 G2 F2 GA | B2 G2 E2 F2 | G6 z2 || V: 2 % alto D2 |\ D2 C2 B,2 D2 | C2 C2 D2 D2 | G2 G2 E2 E2 | F6 G2 | G2 F2 E2 D2 | C2 E2 D2 E2 | D2 D2 C2 C2 | D6 G2 | G2 G2 G2 G2 | G2 G2 F2 D2 | G2 G2 E2 G2 | F6 D2 | C2 D2 EF G2 | E2 E2 D2 E2 | D2 B,2 C2 D2 | D6 z2 || V: 3 % tenor D,2 |\ G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 | E2 D2 C2 B,2 | D6 D2 | D2 D2 B,2 G,2 | E,2 A,2 A,2 C2 | G,2 G,2 G,2 A,2 | B,6 DC | B,2 D2 B,2 D2 | C2 E2 D2 B,2 | C2 D2 C2 G,2 | A,6 G,2 | G,2 G,2 C2 D2 | CD CB, A,2 C2 | G,2 G,2 A,2 A,2 | B,6 z2 || V: 4 % bass up one octave D2 |\ B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 | E2 G2 A2 E2 | D6 GA | B,2 D2 E2 E2 | A,2 C2 D2 C2 | B,2 A,B, C2 A,2 | G,6 G,2 | G2 B2 G2 G2 | c2 C2 D2 G2 | E2 G2 C2 E2 | D6 G2 | C2 B,2 A,2 G,2 | A,2 C2 D2 C2 | B,2 E2 A,2 D2 | G,6 z2 || In this case, each V: label occurs only once, and the complete part for that voice follows. V: labels can be used multiple times, so it is permitted (and even desirable) that the abc be laid out in the same format as the printed music would be - with the lines of music interleaved with one another as follows: X: 4 T: Candlemas Eve S: Hymn 126 Arr. R. Herrick from an old church-gallery book M:4/4 L:1/8 Q:1/8=400 N:from an old church-gallery book H:The old church-gallery book was discovered by the Rev. L.J.T. Darwall. H:The source has a 4-part harmony. O:English R:Reel K:G V:1 D2 |\ G2 G2 B2 G2 | E2 F2 G2 Bd | c2 B2 A2 G2 | A6 Bc | V:2 D2 |\ D2 C2 B,2 D2 | C2 C2 D2 D2 | G2 G2 E2 E2 | F6 G2 | V:3 D,2 |\ G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 | E2 D2 C2 B,2 | D6 D2 | V:4 D2 |\ B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 | E2 G2 A2 E2 | D6 GA | % V:1 d2 B2 G2 AB | c2 A2 F2 GA | B2 G2 E2 F2 | G6 Bc | V:2 G2 F2 E2 D2 | C2 E2 D2 E2 | D2 D2 C2 C2 | D6 G2 | V:3 D2 D2 B,2 G,2 | E,2 A,2 A,2 C2 | G,2 G,2 G,2 A,2 | B,6 DC | V:4 B,2 D2 E2 E2 | A,2 C2 D2 C2 | B,2 A,B, C2 A,2 | G,6 G,2 | % V:1 d2 d2 d2 B2 | e2 c2 A2 Bd | c2 B2 A2 G2 | d6 B2 | V:2 G2 G2 G2 G2 | G2 G2 F2 D2 | G2 G2 E2 G2 | F6 D2 | V:3 B,2 D2 B,2 D2 | C2 E2 D2 B,2 | C2 D2 C2 G,2 | A,6 G,2 | V:4 G2 B2 G2 G2 | c2 C2 D2 G2 | E2 G2 C2 E2 | D6 G2 | % V:1 e2 d2 c2 B2 | A2 G2 F2 GA | B2 G2 E2 F2 | G6 z2 || V:2 C2 D2 EF G2 | E2 E2 D2 E2 | D2 B,2 C2 D2 | D6 z2 || V:3 G,2 G,2 C2 D2 | CD CB, A,2 C2 | G,2 G,2 A,2 A,2 | B,6 z2 || V:4 C2 B,2 A,2 G,2 | A,2 C2 D2 C2 | B,2 E2 A,2 D2 | G,6 z2 || The second layout more closely resembles printed music, and permits the corresponding notes on different voices to be vertically aligned so that the chords can be read directly from the abc. The addition of a single comment symbol "%" between the grouped staves also makes the abc more legible, but neither is required by any of the programs. ---------------------------------------------------------------------- Syntax variations. Both formats are acceptable to most programs, with the exception that BarFly requires the lines of abc to be in the same order that they are to be displayed, so it will not display the first example correctly (although it will play it). This is not a serious problem, however, as the program has a utility built in to rearrange the abc into either format as required. Melody assistant appears to require the first format, only allowing each V: label to appear once, and in addition requires the key, metre and default note length to be stated again at the beginning of each voice, even if they have already been stated in the header. ---------------------------------------------------------------------- Labels. The abc2ps family permit non-numerical voice labels to be used, so you could have the first line of the above tune as: V:Soprano D2 |\ G2 G2 B2 G2 | E2 F2 G2 Bd | c2 B2 A2 G2 | A6 Bc | V:Alto D2 |\ D2 C2 B,2 D2 | C2 C2 D2 D2 | G2 G2 E2 E2 | F6 G2 | V:Tenor D,2 |\ G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 | E2 D2 C2 B,2 | D6 D2 | V:Bass D2 |\ B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 | E2 G2 A2 E2 | D6 GA | This format is not acceptable to abc2nwc, BarFly, Muse, abc2midi or yaps, which all require numerical voice labels. BarFly requires the labels to be contiguous integers and used in order starting from 1; abc2midi and yaps will accept numerical sequences with gaps. ---------------------------------------------------------------------- Text layout. BarFly permits each line of music to follow on directly from the label, producing a very compact and readable format: V:1 D2 | G2 G2 B2 G2 | E2 F2 G2 Bd | c2 B2 A2 G2 | A6 Bc | V:2 D2 | D2 C2 B,2 D2 | C2 C2 D2 D2 | G2 G2 E2 E2 | F6 G2 | V:3 D,2 | G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 | E2 D2 C2 B,2 | D6 D2 | V:4 D2 | B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 | E2 G2 A2 E2 | D6 GA | This is not acceptable to any of the other programs, and users are advised in the program documentation not to use it for tunes which are to be uploaded. abc2ps, abcm2ps, abc2midi and yaps allow inline V: fields: [V:1] D2 | G2 G2 B2 G2 | E2 F2 G2 Bd | c2 B2 A2 G2 | A6 Bc | [V:2] D2 | D2 C2 B,2 D2 | C2 C2 D2 D2 | G2 G2 E2 E2 | F6 G2 | [V:3] D,2 | G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 | E2 D2 C2 B,2 | D6 D2 | [V:4] D2 | B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 | E2 G2 A2 E2 | D6 GA | The next version of BarFly will also support this, while abc2nwc, Muse and Melody Assistant currently do not. There is also some variation in the way in which the line-continuation character \ is handled. In single voice abc this character at the end of a line implies that the music continues on the next line without a break. BarFly applies the same principle everywhere, including multivoice, so the above example could be broken in mid-line as follows: [V:1] D2 | G2 G2 B2 G2 | E2 F2 G2 Bd |\ c2 B2 A2 G2 | A6 Bc | [V:2] D2 | D2 C2 B,2 D2 | C2 C2 D2 D2 |\ G2 G2 E2 E2 | F6 G2 | [V:3] D,2 | G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 |\ E2 D2 C2 B,2 | D6 D2 | [V:4] D2 | B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 |\ E2 G2 A2 E2 | D6 GA | The abc2ps family will accept this, but will also permit the second half of each line to be grouped together further down the page: [V:1] D2 | G2 G2 B2 G2 | E2 F2 G2 Bd |\ [V:2] D2 | D2 C2 B,2 D2 | C2 C2 D2 D2 |\ [V:3] D,2 | G,2 G,2 G,2 G,2 | G,2 A,2 B,2 B,2 |\ [V:4] D2 | B,2 A,2 G,2 B,2 | C2 A,2 G,2 G2 |\ [V:1] c2 B2 A2 G2 | A6 Bc | [V:2] G2 G2 E2 E2 | F6 G2 | [V:3] E2 D2 C2 B,2 | D6 D2 | [V:4] E2 G2 A2 E2 | D6 GA | This is not acceptable to BarFly, which always requires the lines of music to appear in the abc in the same order in which they are to be drawn to the screen. This difference becomes more troublesome when dealing with music which has lyrics aligned using the w: field. w: lines can also be continued with a backslash character, and you can have multiple w: lines after each line of music. Here, the abc2ps family requires that the w: lines be grouped together immediately after the segment of music with which they are associated and that each should start with a w: field identifier, while BarFly requires the continued segment of any line to follow immediately after the line with the backslash, and with no additional field symbol. ---------------------------------------------------------------------- Clefs. While this is not specifically a multivoice issue, the use of clefs other than the treble clef is uncommon in single-voice abc, but very common in multivoice, represents a major area of disagreement, and so needs to be dealt with here. Most of the programs permit a clef to be specified in the K: field, and when placed in the K: field at the end of the header this sets the default clef for all of the voices which follow, so in the tune above, you could write: K:G clef=bass and then all four voices would be drawn on staves which commence with a bass clef. If no clef specification is present, the default clef is treble. The "clef=" part of the specification is optional, so "K:G bass" would have exactly the same effect. Clef changes within the tune can be specified by inserting a K: field, either on a line by itself or within square brackets using the inline field format. If the clef change is not accompanied by a key change the key part of the K: field may be omitted, and you can simply write K:bass or [K:bass]. Clef changes (like other in-tune fields) apply only to the voice in which they occur, and can occur anywhere, including in the middle of a beam. Problems arise, however, in the interpretation of clefs other than the treble. abc2midi and BarFly's player ignore clefs, and simply play the notes as written. The abc2ps family change their interpretation of pitch, such that the symbol c always represents the C nearest to the centre line of the staff. Thus if a bass clef is present the note d is drawn on the centre line of the bass staff, rather than five leger lines above. abc2nwc, BarFly, Muse and yaps keep the same pitch interpretation, simply drawing the notes in a different vertical position to suit the clef in current use. In this case the symbol C always refers to middle C, and is drawn one leger line above the bass staff or one leger line below the treble staff. The result of this discrepancy is that tunes which are transcribed for abc2ps/abcm2ps using the bass clef are drawn and played two octaves high in BarFly and Muse, while those transcribed for BarFly or exported by Muse are drawn two octaves lower by abc2ps (but play normally in abc2midi). The unregistered version of Melody Assistant which I tested did not permit clefs other than the treble clef; most abc directives in this program have to be placed in lines which start with %! which makes it totally different to other abc programs. As a step towards resolving this difficulty, Muse, BarFly and jcabc2ps have adopted the use of the "middle" directive, which allows the transcriber to explicitly declare the relationship between abc symbols and their vertical position on the staff. The middle directive can be placed anywhere you can put a clef directive, and in practice normally follows a clef change. It can be written as "middle = x" or "m=x" where x is a note in abc format, specifying that the note x is to be placed on the middle line of the staff. So, a tune which has been transcribed for abc2ps using the bass clef could have the following in its K: field: K:G bass m=d and it would then display correctly in both BarFly and Muse, as well as in the program which originated it. A similar tune transcribed in BarFly using the default pitch relationship for that program would include: K:G bass middle = D, and (if the abc2ps family supported it) it would then display correctly in those programs. While the middle directive can be used to shift the display pitch by any amount, it should normally only be used to shift the position by a multiple of an octave. Yaps and abc2midi support a simpler version of this, where the directive octave=-2 causes every note to be treated as having a pitch two octaves below the written pitch. abcm2ps can decide automatically which clef to use if no clef is explicitly indicated. A similar directive "transpose" performs the same task for player programs. This has exactly the same effect as the %%MIDI transpose command in abc2midi, allowing the played pitch to be shifted by a given number of semitones. Again, it can be written as transpose = n or t=n. A tune transcribed for abc2ps which contained the following K: field: K:G bass m=d t=-24 will display and play correctly in both BarFly and Muse. The abc2ps family support treble, alto and bass clefs, abc2nwc and BarFly support these three plus the tenor clef (and in BarFly the eight gregorian clefs which are irrelevant to this discussion). Muse supports only the treble and bass clefs. jcabc2ps permits clefs to be specified by the note which they label on the staff, so "clef=G" means the treble clef, "clef=C" means alto and "clef=F" means bass. As it only supports those three clefs this is unambiguous, but it should be noted that both the alto and tenor clefs are C clefs, and the other clefs may (rarely) be placed on other lines as well. ---------------------------------------------------------------------- Placing of directives. abc2midi uses a long list of directives placed in %%MIDI lines within voices to set various playing options for each voice, including program, channel, volume and pan settings. Similar options for BarFly's player have to be placed in V: fields within the tune header. BarFly has limited support for the %%MIDI directives, applying the first set encountered to all voices in the tune if there are no V: header fields. abc2nwc requires the initial clef directive to be in a K: field at the start of the voice. The abc2ps family also read directives placed on the same line as the first instance of each V: field; in the case of abcm2ps and jaabc2ps this may be either in the header or at the beginning of the voice in the tune. BarFly will not work with directives placed in V: fields in the tune, while abc2ps and abctab2ps will not work with directives placed in the header. ---------------------------------------------------------------------- Staff grouping. Unless otherwise specified, each voice is drawn on a separate staff. abcm2ps and jaabc2ps use a special directive %%staves placed at the start of the tune to modify this. The definition following a %%staves directive must include all of the voice labels grouped together with a combination of square brackets [], braces {}, or parentheses(). When connected by square brackets the voices are grouped together by a bracket at the start of the line. Voices grouped by braces are written to a pair of staves (keyboard staff), and a maximum of four voices can be so grouped. Finally, any number of voices can be merged onto a single staff by enclosing them in parentheses. Examples Two voices on a single staff (e.g. guitar): %%staves (1 2) Three voices, 3 staves, voice 1 vocal, voice 2 and 3 piano: %%staves 1 [{2 3}] Four voices, 2 staves (piano), with 1 & 2 on the right hand, 3 & 4 on the left: %%staves [{1 2 3 4}] or %%staves [(1 2) (3 4)] Five voices, two staves (harpsichord), 1 & 2 on right hand, 3 - 5 on the left: %%staves [(1 2) (3 4 5)] Six voices, trumpet, first & second violins and organ R, L & pedal: %%staves 1 [2 3][4 5 6] BarFly controls staff grouping by means of keywords placed in V fields in the header. If two voices or more are to be drawn on the same staff, you can place the word "merge" on the second and subsequent V: lines to accomplish this. Brackets at the left of the staff are controlled by "bracketon" and "bracketoff" on V: lines corresponding to the first and last voice of the bracketed group. In the absence of these directives, each voice is drawn on a separate staff, and all of the voices are joined by a single bracket. It is not necessary to include empty V lines. Examples: Two voices on a single staff (e.g. guitar): V:2 merge Three voices, 3 staves, voice 1 vocal, voice 2 and 3 piano: V:2 bracketon V:3 bracketoff Four voices, 2 staves (piano), with 1 & 2 on the right hand, 3 & 4 on the left: V:2 merge V:4 merge (the two staves will be bracketed together) Five voices, two staves (harpsichord), 1 & 2 on right hand, 3 - 5 on the left: V:2 merge V:4 merge V:5 merge Six voices, trumpet, first & second violins and organ R, L & pedal: V:2 bracketon V:3 bracketoff V:4 bracketon V:6 bracketoff ---------------------------------------------------------------------- Stem directions Where two voices are merged onto one staff, it is normal to specify that one voice is drawn with all the note stems upwards, and the other with stems down, in order to differentiate visually between the voices. This is accomplished by entering "stems=up" or "stems=down" in the appropriate V: field. As usual, BarFly must have this directive in a V: field in the header, abc2ps must have it in the body of the tune, and abcm2ps/jaabc2ps will accept either. BarFly does not require the "stems=" part; the words "up" or "down" are sufficient. I note that abc2ps supports this option even though (apparently) there is no option to merge multiple voices onto one staff (or if there is, I've been unable to find any mention of it in the docs). ---------------------------------------------------------------------- Long barlines By default, abcm2ps, jaabc2ps and BarFly join the aligned barlines together with a vertical line which crosses the space between the staves. abcm2ps/jaabc2ps permit this line to be suppressed (e.g. where the space is needed for lyrics) by inserting a bar symbol "|" between the pair of voices in the %%staves directive. So, the second example from above could be written as follows: Three voices, 3 staves, voice 1 vocal, voice 2 and 3 piano, no barlines between voices 1 and 2: %%staves 1 | [{2 3}] BarFly places long barlines between any pair of staves which are enclosed by a bracket at the left, so long barlines and brackets cannot be independantly controlled. ---------------------------------------------------------------------- Still to be added: List of directives supported by each program Appendix - excerpts from program documents