summaryrefslogtreecommitdiff
path: root/support/xml2pmx/doc/Readme.XML2PMX
blob: 75024a33b41acfc08d061bb825d61861d7df6336 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
XML2PMX Readme
(***************************************************************************)
(****************Copyright 2015 -- 2020 Dieter Gloetzel ******************)
(***************************************************************************)
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    
	You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>. 
	
1.  Introduction
	"MusicXML", ( http://www.musicxml.com/ ) originally developed by Recordare INC
	and now owned by Finale ( https://www.finalemusic.com/ ), is the leading 
	music data exchange format. XML2PMX provides an import facility for 
	sheet music stored in MusicXML format to PMX and MusiXTeX, the leading free 
	software for musical typesetting. Thus PMX is able to import published 
	MusicXML sources as well as MusicXML sources created by OCR scanning, 
	e.g. with Sharpeye of VISIV ( http://www.visiv.co.uk )or PhotoScore.

2. PMX  
	developed by Don Simons (dsimons(at)roadrunner(dot)com) is an easy to use, 
    yet powerful preprocessor for the musical typesetting system MusiXTeX.
        http://icking-music-archive.org/software/htdocs/index.html
	An excellent introduction to using PMX is
		http://icking-music-archive.org/software/pmx/pmxccn.pdf
	In order to work successfully with XML2PMX a good knowledge of 
	PMX is required, and of MusiXTeX will be helpful.

3. XML2PMX 
	has been developed by the author with "Oberon Plugin for Windows 
	Version 2.5" of ETHZ Zürich on Windows 10.
	https://github.com/Spirit-of-Oberon/ETH-Oberon-PlugIn-Win32
	and OLR (Oberon Linux Revival)
	http://oberon.wikidot.com/oberon-linux-revival-olr
	
    XML2PMX is available as Windows-EXE (32 Bit) and as Linux binary (32 Bit).
	XML2PMX requires a TeX, MusiXTeX and PMX installation.
	For Unix please see:   https://tug.org/texlive/
	For Windows please see: https://miktex.org/2.9/setup
	
4. Coverage of MusicXML features
	The following MusicXML features are detected and translated to PMX:
		- 24 staves/voices and 600 bars 
		- 83 notes per instrument and bar
    	- two voices per staff
    	- maximum of two staves per instrument
    	- notes and rests up to 64th, including tuplets and grace notes, 
    	- maximum of 2 dots
    	- chords, accidentals
    	- some annotations like Fermata, Staccato, Tremolo etc. 
    	- ties, slurs and beams
    	- definition of meter, fifths, clefs and their changes on the fly
    	- dynamic marks: hairpins, "ff" etc., piano damping pedal
    	- title and composer, and texts above or below the staff
    	- barlines, repeats, volta
    	- instrument names,
    	- Accepts Windows files  (records ended by 0DX OAX) 
		  as well as Unix files  (records ended by 0AX).
		- Resulting PMX-file on Unix has records ended by 0AX.
		- Resulting PMX-file on Windows has records ended by 0DX 0AX.
		- will not accept UTF16
	
5. Additional features:
	- command line input fields: "options" and "maxbar". 
	  "options" may contain one or several of the nine letters "pdvalstgr"
	  in arbitrary sequence in upper or lower case and without spaces.
	  Option "r" removes any note which has been marked in XML with  
	  print-object = "no".
	  "maxbar" is a limit on the number of bars to be processed. 
	  When maxbar = 0 then all bars will be processed.
	- With option = "L" Lyrics can be extracted and stored in a separate file: "songtext.txt".
	- Automatic detection of pickup
	
6. Limitations
	Some more elaborate situations like beams crossing staves or chords crossing staves
	have not yet been covered.
	MusicXML attributes are enclosed with double quotes.

7. Usage on MS Windows command line (quotes not required): 
    ============================================================================
	XML2PMX_2020.exe 
	"xml-file with path" "pmx-result-file with path" "output options" "maxbar"
	============================================================================
	There are two obligatory inputs: "xml-file" and "pmx-result-file".
	"output options" and "maxbar" are optional parameters. 
	"output options" contains a sequence (without blanks) of one or several of 
	the letters  "p", "d", "v", "a", "l", "r", "s", "t" and "g" .
	Their meaning is the following:
	 _____ _______________________________________________________
	|  p  | XML parser: can produce much output                   |
	|-------------------------------------------------------------|
	|  d  | information on "directions" (dynamical marks etc)     |
	|-------------------------------------------------------------|
	|  v  | distribution of voices over instruments and measures  |
	|-------------------------------------------------------------|
	|  a  | statistics of MusicXML tags like <note>, <measure>,   |
	|-------------------------------------------------------------|
	|  l  | extracts lyrics in a separate file                    |
	|-------------------------------------------------------------|
	|  s  | removes all slurs                                     |
	|-------------------------------------------------------------|
	|  t  | removes all ties                                      |
	|-------------------------------------------------------------|
	|  g  | uses PMX slur option inside grace note                |                 |
	|-------------------------------------------------------------|
	|  r  | remove Notes with Print-object = "no"                 |
    ---------------------------------------------------------------
	The generated PMX file will in general be complete and can be 
	processed by PMX.If not, you can often solve the problem with 
	minor changes in the PMX code. 

	Depending on the options chosen, you will find intermediate results in the 
	console window which may be helpful for debugging.

	
8.1 MusicXML test data 	
    You will find MusicXML-sources for testing under:

	http://www.musicxml.com/music-in-musicxml/example-set/
	
	The following pieces from this source (and a few more) have been tested:
	
	- Schubert: "Ave Maria" (Ellen’s Gesang III), D. 839 "SchbAvMaSample.xml"
	 
	- Beethoven: "An die ferne Geliebte", Op. 98 "BeetAnGeSample.xml"
	  
	- Mahler: "Lieder eines fahrenden Gesellen", "MahlFaGe4Sample.xml"
	
8.2 OCR scanned sheet music
	MusicXML results from the tool Sharpeye of VISIV 
	(http://www.visiv.co.uk/) have been tested successfully.

9.1 Contents for Windows:
	Main folder "XML2PMX_Windows_2020" contains:
		- this Readme.txt
		- Folder "XML", containing the MusicXML code of 
		  a Telemann Fantasy for Recorder: "Telemann.xml"
                - Folder "PMX", will take the test results  *.pmx, *.pdf 
		- Folder "example" with sample results for comparison  
		- Folder "source" with the Oberon source code for Windows
		- XML2PMX_2020.exe: Windows-Exe
		- GNU-GPL.txt: GNU Licence
        	- Runxml_Telemann.bat : sample batch file
9.2 Contents Linux:
	Main folder "XML2PMX_LINUX_2020" contains:
		- this Readme.txt
		- Folder "XML", containing the MusicXML code of 
		  a Telemann Fantasy for Recorder: "Telemann.xml" 
		- Folder "PMX" holds the test results *.pmx, *.pdf
		- Folder "example" with sample results for comparison
		- Folder "source" with the Oberon source code for LINUX
		- XML2PMX_2020: LINUX Binary
		- GNU-GPL.txt: GNU Licence
        	- RunTelemann : sample command
		
10. XML2PMX installation 
	10.1 Prerequisites: TeXLive installation on Unix or 
	     MikTeX installation on Windows  
	     including MusiXTeX and PMX.
	10.2 unpack the folder XML2PMX_LINUX_2020 
	     or XML2PMX_Windows_2020 to a convenient place.
	10.3 for Windows: register XML2PMX_2020.exe, i.e. doubleclick on 		     XML2PMX.reg.
        
	
11. Usage example

11.1 XML2PMX usage example Windows
	 double click on runxml_Telemann.bat

11.2 XML2PMX usage example Linux
	open a command line
	move to folder XML2PMX_LINUX_2020
	enter in the command line and execute:  ./RunTelemann

12. Contact: 
	Feel free to join me under <d.gloetzel(at)web(dot)de> in order to report 	 errors, propose improvements or other comments.