Basic Manual for the xml2hum program
Craig Stuart Sapp <craig@ccrma.stanford.edu>
Sun Jun 27 21:22:39 PDT 2004
==============================

To run the xml2hum program, type:
   ./xml2hum file.xml
where file.xml is a MusicXML file.

To save the output to a Humdrum file, type:
   ./xml2hum file.xml > file.krn

-----------------------------------------------------------------

Basic Help for xml2hum program:

If the xml2hum program complains about a file, you might have to
extract the separate parts.  For example, a two-part file could
be conerted to Humdrum like this:
   ./xml2hum.exe file.xml > file.krn

If that does not work to create a humdrum file, then extract 
each part to a separate file:
   ./xml2hum.exe file.xml -s1 > file1.krn
   ./xml2hum.exe file.xml -s2 > file2.krn
where the -s option specifies the staff number to extract.
This method is necessary when the durations of the staves do not
match (due to a rhythm error in the music, or a rhythm which is not
understood by the xml2hum program (such as very large rhythm values above
a whole note).  Also, gracenotes are not fully implemented, and having
more than two voices on a single staff does not yet work properly.

Then you can use the Humdrum assemble command to join the files
file1.krn and file2.krn together into one score.  You will need to
set the timebase for each file to match the largest <divisions> value you
find in file.xml (if you look at it in a text editor).  Usually a value
of 96 will work:
   timebase -t 96 file1.krn > file1tb.krn
   timebase -t 96 file2.krn > file2tb.krn
   assemble file2tb.krn file1tb.krn | rid -d > file.krn
Note that the file ordering is backward in assemble, because
the lowest part is traditionally found in the first spine of
a Humdrum file, although this does not really matter.
If the individual parts do not line up after assembly, then you can
examine the combined file to see where the barlines do not line
up and fix the individual parts and assemble again.

In particular, any grace note in the music will mess up my program at
the moment.  So if you have grace notes, then you will have to extract
the voices in the score separately and use the timebase/assemble Humdrum
programs to create the full score until I get that feature working.

If you need to find out how many parts are in a file, you can
run this command:
   ./xml2hum.exe -i file.xml

If you import a MIDI file into Sibelius/Finale, and then export the file
as a MusicXML file from Sibelius/Finale, the accidentals determined by
Sibelius/Finale are sometimes poor choices (augmented seconds instead of
minor seconds for example).  If you want to fix these accidental
errors (only works well for monophonic music), you can use the -x option:
   ./xml2hum.exe -x file.xml
This would correct things like a melodic pattern of D-D#-D into D-Ef-D, or 
E-Gf-Gn into E-F#-Gn.

If you do not care about encoding notation specific items you can use
the -N option:
   ./xml2hum -N file.xml

If you do now want to encode particular notation items there are
options to not encode stem directions:
   ./xml2hum -S file.xml
to not encode beaming information:
   ./xml2hum -B file.xml
to not encode dynamics (only partially complete conversion right now):
   ./xml2hum -D file.xml

By default, lyric verses are converted to the Humdrum format along
with the music.  To prevent the lyrics from being converted, use the
-T option to prevent text from being converted:
   ./xml2hum -T file.xml

A complete brief listing of options can be genearted by typing:
   ./xml2hum --options

The following list is generated:
	debug=b
	x|midifix|accidentals=b
	s|staff=i:-1
	i|info=b
	S|no-stems=b
	B|no-beams=b
	D|no-dynamics=b
	N|no-notation=b
	M|no-measure-number-fix=b
	T|no-text=b
	author=b
	version=b
	example=b
	h|help=b

For example, 
   ./xml2hum --debug file.xml
will print some debugging information that is useful for finding errors
in the conversion from MusicXML to Humdrum.

The two command options:
   ./xml2hum -x
and 
   ./xml2hum --midifix
are identical.