zz

abc2xml

abc2xml is a command line utility that translates ABC notation into MusicXML.

For example, when the abc code of bwv539 is translated with abc2xml, the resulting xml file produces this output with MuseScore. And the abc code of Schubert's Ave Maria generates an xml file that produces this output with MuseScore.

Most elements from ABC are translated, but some translations are only partially implemented. In general %%commands are not implemented except:

%%abc-include. Allows you to include another .abc file. The included file, however, is not further checked for %%abc-include lines.
%%score, %%staves. When multiple %%score instructions are present only the first one is honoured.
%%scale, %%pagewidth, %%pageheight, %%leftmargin and %%rightmargin. The scale value is the distance between two stafflines in millimeters. The other values are also in millimeters unless they are followed by a unit (cm,in,pt).
%%MIDI program and %%MIDI channel (or I:MIDI ..) are translated when used in a current voice (i.e. after a V: definition). Instrument/channel changes mid-voice are translated to a text direction which carries the midi parameters as playback setting. In %%MIDI program num, the number should range from 0 to 127. In %%MIDI channel num, the number is starts from one. The midi translation supports mapping multiple voices whith different instruments to one stave. (i.e. the resulting xml part will have multiple instruments). This feature, though present in MusicXML is not supported by MuseScore, nor by Finale Notepad. These programs only allow one instrument per stave.
%%MIDI transpose is translated and has the same effect as transpose= in the clef, i.e. only play back is transposed, not notation.
%%MIDI drummap is translated to an equivalent I:percmap
All %%instructions can be inlined: %%command ... == [I:command ...]

Usage:

When you have Python installed:

> python abc2xml.py [-h] [-r] [-t] [-b] [-f] [-m SKIP NUM] [-o DIR] [-p PFMT] [-z MODE] [--meta MAP] file1 [file2 ...]

When you use the Win32 executable:

> abc2xml.exe [-h] [-r] [-t] [-b] [-f] [-m SKIP NUM] [-o DIR] [-p PFMT] [-z MODE] [--meta MAP] file1 [file2 ...]

Translates all .abc files in the file list to MusicXML. Output goes to stdout unless the -o option is given. Wildcards in file names are expanded.

Option -h prints help message with explanation of the options
Option -r shows whole measure rests in a merged staff. Otherwise (default), when a voice has no notes in a particular measure, the corresponding rest (of a whole measure) will not be shown when the voice is merged with other voices that do have notes in that measure.
Option -m skip num skips skip tunes and then reads at most num tunes. Can be used when abc files contain multiple tunes (tune books) to select only a subset of the tunes. The default skips nothing (skip=0) and reads 1 tune (num=1).
Option -o dir translates every .abc file to a separate .xml file with the same name into directory dir. For example, -o. puts all xml files into the same directory where the input files reside.
Option -p fmt sets the page format of the ouput. fmt should be a string with 7 floating point values sepatated by comma's without any spaces. The values are: scale, page-height, -width, and page margin left, -right, -top, -bottom. A scale value of 1.0 sets the distance between two staff lines to 6pt (2.117 mm). When the -p option is omitted the values default to A4 with left/right margins of 18 mm, top/bottom marings of 10 mm and scale = 0.75. The margin values are in millimeters.
Option -z mode or --mxl mode writes compressed xml files with extention .mxl. If mode is a or add both .xml and .mxl files will be written. If mode is r or replace only .mxl files are written.
Option --meta map defines a mapping of ABC info fields onto MusicXML meta data types. The map is a string without spaces and using comma as separator. It specifies the MusicXML tag name for one or more ABC info field headers. For instance: --meta R:poet,Z:translator maps the R: info field onto the poet meta data type, and the Z: info field onto the translator meta data type. Valid MusicXML meta data types are: composer, lyricist, poet, arranger, translator and rights. It depends on the music editor used, where and if the meta data appears on the score front page. MuseScore, for instance, displays composer, poet and translator in various useful positions in the header of the score. The rights type can be (mis)used to display a block of text below the score.
There are two default mappings: C: is mapped to the composer meta data type and S: is mapped to the source meta data type. All other ABC info fields: R:,Z:,N:,O:,A:,G:,H:,B:,D:,F:,W: are by default translated to the miscellaneous meta data type, unless the user provides a mapping for them with the --meta option.
When multiple lines of the same field type appear, the lines are contatenated with a new line as separator. Also W: fields are treated in this way (concatenated). With the command line option --meta W:rights all W: lines appear as one block of text at the bottom of the score (with MuseScore).
Option -t Use the first title field (T:) as file name. Question mark, comma and quote are replaced by underscore.
Option -b The default line break character is set to EOL in stead of $ (the default).
Option -f forces abc2xml to calculate string/fret allocations for all notes in each tab staff. These allocations are added as notation elements to the XML file. Without -f no string/fret notation elements will be added to the XML file, leaving the allocation to the score editor that reads the XML file. The current allocation algorithm in abc2xml is very simple and will produce unplayable results in many cases. Explicit string numbers (finger decorations) can be added to the ABC code to get correct results. See tablature paragraph and tutorial.
Option - A single minus - in stead of an input file name will make abc2xml read from standard input. For example (Linux):
```
> cat test.abc | abc2xml.py -o. -
```
does the same as
```
> abc2xml.py -o. test.abc
```

Download

The python script: abc2xml.py-245.zip (the change log)

Stand alone win32 executable: abc2xml.exe-245.zip

Blechtrottel.net has developed abc2xmlGUI, a graphical user interface for both abc2xml and xml2abc.

Non standard additions:

Jazz chord symbols
A whole bunch of them. When a chord symbol is not recognized it is translated as text annotation.
Glissando's
are implemented as decorations of the note where the glissando starts and the note where it ends. For instance: !-(! C D E !-) F G draws a glissando from C to F. A glissando can start and end on notes within a chord. There may be more parallel glissando's. There is a wavy glissando and one with a streight line: !-(! ... !-)! and !~(! ... !~)!
Tremolo
Single or between two chords (or notes). A single tremolo is indicated by a decoration: !/!, !//! or !///!. The number of slashes translates to the number of bars of the tremolo. A tremolo between two chords (or notes) is given by decorating the first one with !/-!, !//-! or !///-!. For instance: !/-![CGE][CGE] or !///-!CC.
Tablature (see also the tutorial)
Syntax:
```
V:n [clef=]tab [strings=E2,A2,...] [nostems] [capo=n] [diafret] [other voice fields]
```
- tab The only required field (optionally preceded by clef=). The current voice will be translated to a tablature staff. When more voices are mapped to the same staff (with I:score), the clef will be the one of the first voice.
- strings=... This optional field specifies the tuning of the strings (and implicitly the number of strings). It is a comma separated list (without spaces) of pitches from top string to bottom string. The attribute defaults (when omitted) to a guitar tuning (strings=E2,A2,D3,G3,B3,E4). The tuning pitches are not ABC notes, but pairs of step/octave values. E2 is an E in the second octave (E,, in ABC). The pitches correspond to string numbers in the score: 6,5,4,3,2,1. These are the lines of the tablature, where string 1 is the topmost line.
- capo=n indicates the presence of a capodastro on fret position n. This modifies the tuning accordingly, and results in fret positions relative to the capodastro. (MuseScore does not honour the capo element of MusicXML, but Finale Notepad does.)
- nostems When present in the tab definition, no stems and no beams will be generated for this voice. Normally a tablature staff is created with stems (and beams where appropriate) on all notes.
- diafret indicates an instrument with diatonic fretting. The fret numbers will correspond to scale steps on a diatonic scale (Mixolydian). This feature is not present in the current MusicXML specification and is therefore not supported by any software, except xml2abc, which will generate ABC code with diatonic fret numbers (with the -t option, see readme).
For a tab staff notes are automatically translated to (optimal) fret positions on the strings. When the automatic layout does not provide the desired result, ABC notes can be manually decorated with string numbers. The fingering decoration is used for this pupose. For example:
```
X:1
K:C
V:1 clef=tab octave=-1
[CEG]2 [!6!C!5!E!4!G]2 [CE!4!G]4 |
```
produces a guitar tablature staff with the first chord on strings 3 (G3), 4 (D3) and 5 (A2), on frets 0, 2 and 3 respectively. The second chord is forced on strings 4, 5 and 6. The fret positions then become: 5,7,8.

As you can see from the third chord in the example, only forcing the G on the 4th string is already sufficient to get the C and E on string 6 and 5, because there is no other possibility. Note that we also used octave=-1 with the tab clef as guitar parts are normally notated with a treble-8 clef. In this way one can use the same notes in a normal staf and in a tablature staff. For instance:
X:1 K:F# V:1 clef=treble-8 CD EF GA ^Bc | V:2 clef=tab octave=-1 CD EF GA ^Bc |
The following example is taken from http://moinejf.free.fr/abcm2ps-doc/banjo.xhtml. It is a tablature for a 5-string Banjo of a fragment of the "Blue Moon Of Kentucky".
The ABC code for abc2xml only needs the tuning of the Banjo and a couple of explicit sting annotations, mostly !5!g to get the g on the 5th string (otherwise it is allocated to the fifth fret of the first string).
```
X:1
M:4/4
L:1/4
V:1 treble-8
V:2 tab strings=G4,D3,G3,B3,D4 octave=-1 nostems
K:C
%
[V:1] z[Bg]   [cg]   [^cg]    |: ^c/[dd]/ g/d/       d/g/       d/d/ | B/d/ B/d/ A/d/ G/d/ |
[V:2] z[B!5!g][c!5!g][^c!5!g] |: ^c/[dd]/ !5!g/!2!d/ d/!5!g/ !2!d/d/ | B/d/ B/d/ A/d/ G/d/ |
%
[V:1] E/c/ G/d/    g/G/ d/g/    | G/e/    g/G/ e/G/ E/e/ | D/d/    g/G/ d/g/    B/d/ |
[V:2] E/c/ G/d/ !5!g/G/ d/!5!g/ | G/e/ !5!g/G/ e/G/ E/e/ | D/d/ !5!g/G/ d/!5!g/ B/d/ |
```
The second measure has a unison [dd]. The automatic layout happens to do a good job here by allocating the d's to string 1 and 2 respectively. We used the "nostems" attribute on the tab staff, because stems and beams are quite redundant when also a normal staff is present.
Percussion maps (see also the tutorial)
Syntax:
```
I:percmap abc-note [staff-step] drum-sound [xml-notehead]
```
- abc-note: The abc note name as it appears in the music code (tune).
- staff-step (optional) An abc note without accidental (E,). This determines where the note appears on the staff. When omitted (or *), the step value is taken from abc-note.
- drum-sound A General Midi (channel 10) drum sound name like: bass-drum-1, side-stick, acoustic-snare. The spaces used in the official names have to be replaced by a minus character (drum sound names are case insensitive). The parts of a name may be abbreviated: ba-dr-1 in stead of bass-drum-1 also works, or sid even works in stead of side-stick, as long as the substring is unique in the set of GM drum sound names.
  In stead of a sound name also a 0-based midi number, or an equivalent abc note like F,, for 41 can be specified. Also an * is allowed, which copies its value from abc-note. The * can even be omitted if no notehead follows.
- xml-notehead (optional) This should be one of the notehead names defined in MusicXML: slash, triangle, diamond, square, cross, x, circle-x, normal, cluster, inverted triangle, arrow down, arrow up, slashed, back slashed, do, re, mi, fa, so, la, ti, or none.
  Spaces in a name (like: arrow down) should be replaced by a minus sign (arrow-down). An appended plus/minus sign translates to a filled/open noteshape (e.g. diamond+, square+, normal-). A filled halve note will look like a quarter. An empty quarter looks like a halve note. Without appended sign the filling is determined by the duration of the note (default behaviour).
  
  Note that Musescore only supports some of the standard note shapes (triangle, diamond, x, circle-x).
Examples:
```
I:percmap E bass-drum-1 diamond
```
The ABC note E appears as an E on the staff (staff-step is omitted) with a diamond shape and is mapped to the GM percussion instrument called bass-drum-1 (= midi number 36 on channel 10).
```
I:percmap F,, E * circle-x
```
The ABC note F,, appears as an E on the staff with a circle-x shape. No instrument name is specified (*), thus the midi number of F,, is used as GM percussion instrument (F,, = midi number 41 = Low Floor Tom).
```
I:percmap E hand-clap
```
ABC note E appears as an E on the staff with a normal note shape (no shape is specified) and is mapped to the GM percussion instrument called hand-clap (= midi number 39)
```
I:percmap E 41
```
ABC note E appears as an E on the staff and the midi number 41 is used as GM percussion instrument (= Low Floor Tom).

Here is an example of a standard drum kit in more or less standard notation (suggested to me by Stéphane David, percussionist of the Paris Opera orchestra)
```
X:1
L:1/4
K:D clef=perc
I:percmap  E acoustic-bass-drum
I:percmap  D pedal-high-hat x
I:percmap  c acoustic-snare
I:percmap  g closed-hi-hat  x
I:percmap ^g open-hi-hat    circle-x
I:percmap  a crash-cymbal-1 x
I:percmap  d hi-mid-tom
I:percmap  A low-mid-tom 
I:percmap  G low-tom
I:percmap  e cow-bell       triangle
I:percmap _d hi-wood-block  triangle
I:percmap  f ride-cymbal-1
   E          D       c        g     | ^g      a         d       A      | G   e    _d       f   |
w: acoustic   pedal   acoustic closed  open    crash     hi\-mid low\-    low cow  hi\-wood ride
w: bass\-drum hi\-hat snare    hi\-hat hi\-hat cymbal\-1 tom     mid\-tom tom bell block    cymbal\-1 
```
The next example shows the use of filled and open note shapes. The first measure uses filled note shapes (+) and the second measure has open note shapes (-). Without +/- the duration of a note determines if a shape is filled or not (<1/2 filled, >=1/2 open). The second measure also shows the use of abbreviated drum sound names.
```
X:1
L:1/4
K:C clef=perc
I:percmap  E Bass-Drum-1     diamond+   % full sound names, filled noteheads (+)
I:percmap ^g Open-Hi-Hat     x+
I:percmap _d Hi-Wood-Block   triangle+
I:percmap  G low-tom         normal+
%
I:percmap  F ac-snare        diamond-   % abbreviated sound names, open noteheads (-)
I:percmap ^a cl-hi-hat       x-
I:percmap _e lo-wo-bl        triangle-
I:percmap  A lo-mi-tom       normal- 
%
E ^g _d G | F ^a _e A |
```
An I:percmap is valid for all voices in the part in which it occurs (from the metrical position onwards). When defined in the header it is valid for all voices.
When clef=perc or map=perc is found and no percmap is present, suitable percmap entries are derived. The new entries map encountered abcnotes to an equivalent midi note number. Also accidentals ^_ are mapped to noteheads x and circle-x. (when I:percmap instructions were present in the abc code, also a warning message is issued that an entry is missing)

The mappings defined by I:percmap only work for a percussion voice. Normally that is a voice with the percussion clef (clef=perc). But the mapping can also be switched on for other clefs by using the inline field [K:map=perc]. Also the percussion mapping can be switched off again mid-voice by using [K:map=off].

When more voices are mapped to one staff (using I:score) the current percussion map works for all voices of that staff. (when more staves are grouped in I:score using braces, the percussion maps work for all voices of that group.)

The scope of a percmap is either global, when defined in the header, or local when defined in a voice. Also, a percmap can be redefined anywhere (also inline [I:permap ...]).