Mercurial > dottes

annotate abc2xml/Readme.txt @ 795:c979a83fdd26 build-default-299

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge with upstream.
author Jim Hague <jim.hague@acm.org>
date Thu, 26 Apr 2018 15:05:29 +0100
parents 4fab69a1027d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
484
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
1 ---- abc2xml ----
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
2
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
3 abc2xml is a command line utility that translates ABC notation into MusicXML.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
4
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
5 In principle all elements from ABC are translated, but some translations are only partially
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
6 implemented. Translated are:
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
7 - multiple lyric lines per voice
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
8 - mapping voices to staves, brackets and braces (%%score or %%staves)
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
9 - voice overlays (only single &-overlays, no multiple &&-overlays yet)
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
10 - dynamics, slurs, several decorations (ties between different voices are not possible in MusicXML
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
11 and are changed to slurs when present in ABC. Also (illegal) ties between different pitches are converted
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
12 to slurs. In both cases a warning message is issued)
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
13 - grace notes, tuplets
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
14 - keys (maj, min, mix, dor, phr, lyd, loc and none), meter, tempo
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
15 - clefs (only most common clef names, tranposition= and middle= are supported)
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
16 - jazz chord symbols and text annotations
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
17 - beaming. Only one beam per abc-beam group is translated at the moment, which is
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
18 sufficient for MuseScore. In musicXML every beam should be explicitly notated, so a 32th
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
19 note should start 3 beams.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
20 - scale, page size and page margins are recognized as either %% or I: directive. The scale value is
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
21 the distance between two stafflines in millimeters. The other values are also in millimeters unless
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
22 they are followed by a unit (cm,in,pt).
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
23 - %%MIDI program and %%MIDI channel (or I:MIDI ..) are translated when used in a current voice
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
24 (i.e. after a V: definition). The instrument of a voice cannot be changed in the middle of a tune.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
25 If one does so, only the last %%MIDI will be used for the whole voice. (and the earlier settings are
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
26 discarded). %%MIDI transpose is translated and has the same effect as transpose= in the clef, i.e.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
27 only play back is transposed, not notation. In %%MIDI program=num, the number should be between 0
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
28 and 127. Also in %%MIDI channel=num, the number is starts from zero. The midi translation supports
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
29 mapping multiple voices whith different instruments to one stave. (i.e. the resulting xml part will
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
30 have multiple instruments). This feature, though present in MusicXML is not supported by MuseScore,
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
31 nor by Finale Notepad. These programs only allow one instrument per stave.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
32 - multiple tunes within one abc file can be converted to a set of xml files, one file per tune.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
33
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
34 In conjunction with xml2abc the translation from xml -> abc -> xml works for all examples
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
35 in the set from MakeMusic. The translated examples produce reasonable score when typeset with MuseScore.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
36
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
37 ---- Usage: ----
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
38
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
39 When you have Python installed:
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
40 > python abc2xml.py [-h] [-m SKIP NUM] [-o DIR] [-p PFMT] [-z MODE] file1 [file2 ...]
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
41
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
42 When you use the Win32 executable:
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
43 > abc2xml.exe [-h] [-m SKIP NUM] [-o DIR] [-p PFMT] [-z MODE] file1 [file2 ...]
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
44
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
45 Translates all .abc files in the file list to MusicXML. Output goes to stdout unless the -o option
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
46 is given. Wildcards in file names are expanded.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
47 Option -h prints help message with explanation of the options
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
48 Option -m skip num skips skip tunes and then reads at most num tunes.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
49 Can be used when abc files contain multiple tunes (tune books) to select only a subset of the tunes.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
50 The default skips nothing (skip=0) and reads 1 tune (num=1).
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
51 Option -o dir translates every .abc file to a separate .xml file with the same name
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
52 into directory dir. For example, -o. puts all xml files into the same directory where
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
53 the input files reside.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
54 Option -p fmt sets the page format of the ouput. fmt should be a string with 7 float
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
55 values sepatated by comma's without any spaces. The values are: space, page-height, -width, and
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
56 page margin left, -right, -top, -bottom. space defines the scale of the whole score and equals the
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
57 distance between two staff lines in mm. When the -p option is omitted the values default to A4 with
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
58 10mm margins and space=1.764. All commandline values are in millimeters.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
59 Option -z mode or --mxl mode writes compressed xml files with extention .mxl.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
60 If mode is a or add both .xml and .mxl files will be written. If mode is r or replace only .mxl
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
61 files are written.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
62
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
63 ---- Download ----
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
64
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
65 The python script: abc2xml.py-58.zip
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
66 http://wim.vree.org/svgParse/abc2xml.py-58.zip
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
67
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
68 Stand alone win32 executable: abc2xml.exe-58.zip
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
69 http://wim.vree.org/svgParse/abc2xml.exe-58.zip
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
70
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
71 ---- ABC Syntax ----
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
72
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
73 ABC is recognized by a high level parser that reads the ABC syntax in a notation close to (E)BNF.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
74 The drawback of this approach is that many dialects of ABC will cause sytax errors.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
75 In addition, the high level parser implementation in pure python (pyparsing.py) is slow.
4fab69a1027d Add MusicXML conversion to tune pages.
Jim Hague <jim.hague@acm.org>
parents:
diff changeset
76 The pyparsing library is included (as a single python file) in abc2xml.py-58.zip