hum2muse manpage

COMMAND

hum2muse -- Convert Humdrum files into MuseData.

The hum2muse program converts Humdrum files into MuseData stage2 files. The MuseData files can be processed interactively in the dmuse IDE, or non-interactively with the muse2ps program which converts MuseData files into PostScript files of graphical music notation.

Basic usage

A typical use for hum2muse is to convert Humdrum data into MuseData which, in turn, is converted into PostScript with muse2ps, and then into PDF using ps2pdf (which typically comes pre-installed with most unix distributions):

   hum2muse test.krn | muse2ps | ps2pdf - - > test.pdf

This is equivalent to doing three separate commands which reveals the intermediate MuseData and PostScript files:

    hum2muse test.krn > test.md2
    cat test.md2 | muse2ps > test.ps
    ps2pdf test.ps
 

The ps2pdf program can receive standard input and produce standard output by replacing filenames in its argument list with dash characters (-), respectively, as demonstrated in the first usage given above. In the second example, only the input filename needs to be given to ps2pdf, since the output filename will contain the same basename with the extension change to .pdf (test.pdf in this case).

Muse2ps options are described in detail further below, but here is an example of using the largest music size available (6, 14, 16, and 18 being the other sizes). The options to muse2ps start with an equals sign and can include multiple options concatenated into a single string without spaces. In the following example, "=z21j" contains two options: (1) "z21" which means to typeset the music in size 21, and (2) "j" which means to right-justify the last system of music (only one system in this example).

   hum2muse test.krn | muse2ps =z21j | ps2pdf - - > testz21j.pdf

By default, ps2pdf uses the A4 paper dimensions when creating PDF files. However, muse2ps generates music notation for paper with the U.S. letter size. If you want to match the PDF to the default paper size output by muse2ps, you must add the -sPAPERSIZE=letter to ps2pdf:

   hum2muse test.krn | muse2ps =z21j | ps2pdf -sPAPERSIZE=letter - - > testletter.pdf

For this short example of music, the difference will not be very noticeable. For full pages of music, the top margin will appear larger when trying to print/display letter-sized music on A4 paper. If you want to create music typeset for A4 paper, then there are size options which can be given to muse2ps (to be described later).

Generating image files

The PostScript or PDF output from muse2ps can be used to create images. Here is an example of how to create a full-resolution PNG image of the scale example using ImageMagick's convert tool which typically comes pre-installed in linux distributions:

   hum2muse test.krn | muse2ps =z21j | pstopnm -dpi=300 | convert - -trim large.png
 

The native output resolution of muse2ps is 300 dots (pixels) per inch, so the above example extracts the equivalent-quality image as if the notation were printed without scaling. The above PNG output is suitable for generating PNG images for loading into more recent versions of MS Word for printing musical illustrations, for example. To use on webpages, a smaller size is needed:

   hum2muse test.krn | muse2ps =z21j | pstopnm -dpi=300 \
    | convert - -trim -resize '33%' small.png
 

Which generates the following image:


If you need a 10-pixel wide border around the tightly-trimmed image:

    hum2muse test.krn | muse2ps =z21j | pstopnm -dpi=300 \
       | convert - -trim -resize '33%' \
                 -bordercolor white -border 10x10 smallborder.png
 



As a fun example, the following image was generated by saving the MuseData to an intermediate file, then editing the file to add 'r' marks in column 14 of notes to color them red, and 'b' to color them blue. The --mo option to hum2muse is used to embed the option settings for muse2ps within the MuseData file.

    hum2muse test.krn --mo "z21j" > testcolor.md2
    cat testcolor2.md2 | muse2ps | pstopnm -dpi=300 \
         | convert - -trim -resize '33%' -bordercolor white -border 10x10 color.png
 



MuseData/muse2ps can only print three colors (red, green, and blue). However, these three colors can be modified by changing the color settings in the output PostScript data from muse2ps (note that "green" is "0.0 0.7 0.0"):

    cat testcolor2.md2 | muse2ps \
         | sed 's/1.0 0.0 0.0 setrgbcolor/1.0 0.5 0.0 setrgbcolor/' \
         | sed 's/0.0 0.0 1.0 setrgbcolor/0.5 0.0 1.0 setrgbcolor/' \
         | pstopnm -dpi=300 | convert - -trim -resize '33%' \
                  -bordercolor white -border 10x10 coloralt.png
 



The color encoding can also be handled by hum2muse, using embedded RDF markings. The following example uses more aggressive coloring of notes by using "R" for red notes and stems/flags, etc.

    hum2muse color.krn | muse2ps | pstopnm -dpi=300 \
         | convert - -trim -resize '33%' -bordercolor white -border 10x10 colorbeam.png
 



Here is an example of how to create a musical example with a transparent background so that it can be displayed on backgrounds of any color.

   hum2muse test.krn | muse2ps =z21j | pstopnm -dpi=300 | convert - -trim -negate \
       -alpha copy -resize '33%' -negate transparent.png
 



Here is an example of the same image displayed over a different background color:

Muse2ps options

Options can be passed to the muse2ps program from hum2muse by either using the --mo option, or embedding the options in global comments starting with "!!muse2ps:". For example, to set the title to be printed on the top of the first page, you can use the --mo option:

   hum2muse file.krn --mo 'T^This is the title^'

or the title option can be embedded in the input Humdrum data:

   !!muse2ps: T^This is the title^

or the option can be passed directly as an argument to muse2ps:

   hum2muse  file.krn | mus2ps '=T^This is the title^'

Note that the caret symbol (^) is used to quote strings of text in muse2ps options. Also note that the single-quote characters (') are recommended when giving the option string with the --mo option. This is done to prevent the command-line interpreter from trying to parse the content of the string before sending it to the program. The single quotes should not be used when encoding muse2ps option in "!!muse2ps:" global comments.

Only one --mo option string can be given to hum2muse, so multiple options must be concatenated together without spaces:

   --mo 'T^This is the title^u^this is the subtitle^z21j'

which is equivalent to embedding in a similar manner, or splitting out the options into separate comments within the Humdrum input data:

    !!muse2ps: T^This is the title^u^this is the subtitle^z21j

or

    !!muse2ps: T^This is the title^
    !!muse2ps: u^this is the subtitle^
    !!muse2ps: z21j 

The option string "z21j" is composed of two options: "z21" which means to print at music size 21 (21/300th of an inch between staff lines), and "j" which means to right-justify the last system in the music (possibly re-allocating measures amongst the systems throughout the composition.

Of course, muse2ps options can be directly applied to a program call to muse2ps:

    muse2ps '=z21jT^This is the title^u^this is the subtitle^'

When giving options to muse2ps as an argument, you must start the option string with an equals sign to indicate to the program that the string is an option string. The equals sign marker is optional when using either the --mo option of hum2muse, or in "!!muse2ps:" comments.

See the muse2ps documentation for a list of options which it understands. Here are some of the more common options:

z#	::	The size of the typeset music. Valid sizes are 6, 14, 16, 18, and 21. The default size is z14.
j	::	Right-justify the last system of music so that it ends at the right margin.
c#	::	Compression factor, where c100 is the default, smaller values compress notes closer together and larger values expand the spacing of the notes.
T^title^	::	The title to center at the top of the first page of music.
u^subtitle^	::	A sub-title placed just underneath the title on the first page of music.
C^composer^	::	The name of the composer which will be placed on the right side of the first system of music on the first page.
s^spine^	::	A symbolic graphical indicate of the bracing/bracketing on the left-hand side of the system. Dots represent staves, parentheses group staves according to how they are barred together, curly braces ({}) indicate the start and stop of a brace, and square brackets ([]) indicate the start and stop of a bracket. For example, a grand-staff encoded as two separate staves would be s^{(..))}^ -- two staves barred together and a brace grouping them together. String quartets would be displayed using s^[(....)]^ -- four staves barred together and one bracket containing all staves. Organ music would be s^{(..)}(.)^ . Four vocal parts with independent texts (so not barred together) would be s^[(.)(.)(.)(.)]^ .
v#,#,#,...	::	Vertical spacing in units which are 1/10th of the distance between staff lines. There values are separate by commands, and there is one number for each staff in the system. The last number represents the distance between the last staff in the system and the first staff in the next system. Example for a two-staff system: v180,200.
f	::	Fill page (vertically justify) with the music, adding extra space between all staves on the page.
F	::	Fill page (vertically justify) with the music, adding extra space only between systems, and keeping the height of each staff constant.

Excluding selected !!muse2ps: options

To suppress particular options from being included in the output data, use the -x option. The option takes a string which contains one or more option names which should be excluded. For example, "-x z" would mean to suppress any z option setting (which sets the music size). "-x zj" means to suppress the z and j options. If the option line in the file is:

    !!muse2ps: z21v90,120ju^subtitle^
 

Then the option setting: "-x zj" would produce the equivalent of:

    !!muse2ps: v90,120u^subtitle^
 

Automatic Stems

The muse2ps program reads MuseData which contains explicit stem directions. If a Humdrum file contains **kern data with no stem directions, they must be provided; otherwise, all stems in the music will be placed upwards by default. If you need to add stem directions to Humdrum data before printing, use the autostem program.

    autostem stemin.krn | hum2muse | muse2ps | ps2pdf - - > stemout.pdf
 

before autostem **kern *clefG2 *k[] *M4/4 =1- 8cL 8d 8e 8fJ 8gL 8a 8b 8ccJ =2 8ddL 8ee 8ff 8ggJ 8aaL 8bb 8ccc 8dddJ =3 *^ 4gg 4r 4ee 4c 4cc 4e 4g 4g *v *v 2e; 2g; 2cc; == *-

after autostem **kern *clefG2 *k[] *M4/4 =1- 8c/L 8d/ 8e/ 8f/J 8g/L 8a/ 8b/ 8cc/J =2 8dd\L 8ee\ 8ff\ 8gg\J 8aa\L 8bb\ 8ccc\ 8ddd\J =3 *^ 4gg/ 4r 4ee/ 4c\ 4cc/ 4e\ 4g/ 4g\ *v *v 2e/; 2g/; 2cc/; == *-

before autostem: after autostem:

Automatic Beaming

The muse2ps program reads MuseData which contains explicit beaming information. If a Humdrum file contains **kern data with no beaming information, they must be provided; otherwise, all notes will not be beams, and will instead have flags if they are eighth notes or smaller durations. Eventually, you can use the autobeam program to add beams to the Humdrum data.

Layout codes

The hum2muse program recognizes most of the notation layout codes described on the Humdrum wiki. The primary purpose of Humdrum data is to encode the logical content of the music. The layout codes provides extra visual information needed to generate a graphical score.

Slur orientation

Slurs can be forced above notes by placing the local layout code "!LO:S:a" immediately before the opening parenthesis of the slur. Use "!LO:S:b" to force a slur below notes.

**kern *clefG2 *M4/4 *k[] =1- (4c/ 4d/ 4e/ 4f/) =2 !LO:S:a (4c/ 4d/ 4e/ 4f/) =3 (4cc\ 4dd\ 4ee\ 4ff\) =4 !LO:S:b (4cc\ 4dd\ 4ee\ 4ff\) == *-	hum2muse input.krn \ | muse2ps =z21j \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps =z21c200 \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

The --ns option (no slurs) can be used to suppress parsing any slurs.

hum2muse input.krn > output.md2

hum2muse --ns input.krn > output.md2

Dynamics layout codes

Dynamics can be moved both horizontally or vertically from their automatically placed locations. Place a local layout code such as "LO:DY" immediately before a dynamic marking. Then append any of the parameters X, x, Y, y, Z, z. These parameters move the dynamic around in the music notation. All units are 1/10 of the distance between staff lines (inter-staff distance). Hairpin (wedges) for crescendos and decrescendos are controlled with !LO:HP for the start, and !LO:HPZ for the end.

X	=	place the dynamic before (negative values), or after (positive values) the left-hand edge of the note on which the dynamic is attached.
x	=	Similar to X but references the default placement location of the typesetting program
Y	=	Vertical placement of the baseline for the dynamic. Y=0 is the bottom line of the staff, one ledger line lower is Y=10 (down is positive), and the second line on the staff is at Y=-10 (up is negative).
y	=	Similar to Y, but relative to a default placement location of the symbol by the typesetting program.
Z	=	Similar to Y but the 0 point is the top line on the staff, and the direction of the units are reversed (up is positive direction, down is negative direction)
z	=	Similar to y but the units are negated (direction is reversed).

**kern **dynam *clefGs * *M5/4 * *k[] * ! !LO:HP:X=20 4.c/ p < 16d/LL ( 16g/JJ ( 4f/ ( 4.e/ ( ! !LO:HPZ:X=-20 16d/LL [ ! !LO:DY:y=5 16c/JJ f = = *^ * ! ! !LO:HP:Z=25:X=35 ! ! !LO:DY:Z=25 4B\ 8d/L mp > . 16e/L ) . 16f/JJ ) ! ! !LO:HPZ:x=-20 ! ! !LO:DY:X=10:Y=40 4A\ 8g/L ] mf . 8a/J . ! ! !LO:DY:Z=25 2.G\ 2.cc/ pp *v *v * == == *- *-	hum2muse input.krn \ | muse2ps =z21j \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps =z21c150 \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png


Use the --nd (no dynamics) option to turn off parsing of dynamics.

hum2muse input.krn > output.md2

hum2muse --nd input.krn > output.md2

There are special interpretations of hairpins in **dynam spines. If a crescendo hairpin is followed by an X character, then the hairpin will be suppressed, and the word cresc. will be inserted in its place. Also, decrescendo hairpins followed by an X will be converted into descrec.. Note that the matching ending points of the hairpins ([ or ]) must also have an X placed after them. If you want a dashed line after the cresc. or decresc., add the parameter dash to the !LO:HP layout code as demonstrated in the following example.

**kern **dynam *clefG2 * *M4/4 * *k[] * =1- =1- 4c/ pp 4d/ . ! !LO:HP:dash 4e/ <X 4f/ (X =2 =2 4g/ (X 4a/ (X 4b\ [X ! !LO:DY:y=10 4cc\ ff =3 =3 4b\ >X 4a/ )X 4g/ )X 4f/ )X =4 =4 4e/ )X 4d/ ]X 2c/ p == == *- *- !!muse2ps: z21c200	hum2muse input.krn \ | muse2ps \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

Other representational features

Accidentals

Cautionary accidentals

placing the letter "X" after an accidental mark will force that accidental to be printed, even if it is not necessary to print the accidental, such as when the accidental is present in the key signature. The "X" must immediately follow the accidental, since it is a contextual marker of whatever precedes it.

**kern *clefG2 *M2/4 *k[b-e-a-d-g-c-f-] 16c-/LL 16d-/ 16e-/ 16f-/JJ 4g-/ =2 16c-X/LL 16d-X/ 16e-X/ 16f-X/JJ 4g-X/ =3|| *k[] 16cnX/LL 16dnX/ 16enX/ 16fnX/JJ 4gnX/ =4 16c/LL 16d/ 16e/ 16f/JJ 4g/ == *-	hum2muse input.krn \ | muse2ps =z21c125 \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps =z21c125 \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

Musica ficta

Musica ficta, or any editorial accidental which should be placed above the notes can be indicated by adding a RDF reference record for **kern data in this format:

   !!!RDF**kern: i = musica ficta 

This indicates that an i character present in a **kern spine represents a musica ficta mark on the note. If the note has no accidental, but has a musica ficta mark, then a natural sign will be used as the ficta (editorial) mark. Other characters other than i which are suitable for use as RDF markers: l (lowercase L), N, U, Z, @, +, |, <, >.

**kern *clefG2 *M4/4 =1- 8e/L 8f/Ji 8g/L 8a/J 4cc\ 8b/L 8a/J =2 4g/ 8f#iL 8eJ 2g/; == *- !!!RDF**kern: i = musica ficta

hum2muse input.krn \ | muse2ps =z21c125 \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps =z21c125 \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

Mensural signs

Mensural signs can be encoded in Humdrum data as a metric symbol to replace any numeric time signature found in the data when printing graphical music notation.Here is a list of the mensural signs which muse2ps can understand and convert into graphical notation:


**kern *clefC3 *M3/1 *met(O) =-1 !LO:TX:X=-32:Y=30:t=*met(O) 1c\ 1d\ 1e\ !LO:TX:X=15:Y=30:t=*met(O:) =2 *M3/1 *met(O:) 1c\ 1d\ 1e\ !LO:TX:X=15:Y=30:t=*met(O.) =3 *M9/2 *met(O.) 1.c\ 1.d\ 1.e\ !LO:TX:X=25:Y=30:t=*met(O;) =4 *M9/2 *met(O;) 1.c\ 1.d\ 1.e\ !LO:TX:X=25:Y=30:t=*met(C) =5 *M2/1 *met(C) 1c\ 1d\ !!LO:LB:g=z21 =6 *M6/2 *met(C.) !LO:TX:X=-50:Y=30:t=*met(C.) 1.c\ 1.d\ !LO:TX:X=25:Y=30:t=*met(Cr) =7 *M2/0 *met(Cr) 0c\ 0d\ !LO:TX:X=15:Y=30:t=*met(C|) =8 *M2/1 *met(C|) 1c\ 1d\ !LO:TX:X=15:Y=30:t=*met(C2) =9 *M2/0 *met(C2) 0c\ 0d\ !LO:TX:X=15:Y=30:t=*met(O2) =10 *M3/0 *met(O2) 0c\ 0d\ 0e\ !LO:TX:X=15:Y=30:t=*met(O|) =11 *M3/1 *met(O|) 1c\ 1d\ 1e\ !!LO:LB:g=z21 =12 *M6/1 *met(C|3) !LO:TX:X=-40:Y=30:t=*met(C|3) 0.c\ 0.d\ !LO:TX:X=25:Y=30:t=*met(3) =13 *M3/1 *met(3) 1c\ 1d\ 1e\ !LO:TX:X=15:Y=30:t=*met(3/2) =14 *M3/1 *met(3/2) 1c\ 1d\ 1e\ !LO:TX:X=15:Y=30:t=*met(C|2) =15 *M2/0 *met(C|2) 0c\ 0d\ !LO:TX:X=15:Y=30:t=*met(2) =16 *M2/0 *met(2) 0c\ 0d\ !LO:TX:X=15:Y=30:t=*met(Oo) =17 *M3/1 *met(Oo) 1c\ 1d\ 1e\ !!LO:LB:g=z21 =18 *M3/4 *met(O) !LO:TX:X=-50:Y=35:t=*met(O) !LO:TX:i:X=-60:Z=10:t=with diminution: 8c\L 8d\J 8c\L 8d\J 8c\L 8d\J !LO:TX:X=15:Y=35:t=*met(O.) =19 *M9/8 *met(O.) 8c\L 8d\ 8e\J 8c\L 8d\ 8e\J 8c\L 8d\ 8e\J !LO:TX:i:Z=12:t=modern variants: !LO:TX:X=15:Y=35:t=*met(c) =20 *M4/4 *met(c) 4c\ 4d\ 4e\ 4f\ !LO:TX:X=15:Y=35:t=*met(c|) =21 *M2/2 *met(c|) 2c\ 2d\ == *- !!muse2ps: z21jv250c150

(Quasi) Mensural notation

Using the --mensural option will display notes in the white mensural style which can be used to simulate the display of mensural music. The mensural signs displayed above can be used to increase the similar in appearance to mensural notation. Currently MuseData does not have an "invisible" barline style, so long excerpts must contain barlines.
hum2muse input.krn > output.md2

hum2muse input.krn --mensural > output.md2

Text

Movement designation

If hum2muse finds an OMD reference record in the header of the file, it will be used to add that text to the start of the music. In addition, if an OMD record is found within the music, the text of the record will be placed above the first staff in the system.

!!!OMD: Allegro **kern **kern *clefF4 *clefG2 *M4/4 *M4/4 *k[] *k[] =1- =1- 1C 4c/ . 4d/ . 4e/ . 4f/ =2 =2 1D 4g/ . 4a/ . 4b/ . 4cc/ =3|| =3|| !!!OMD: Adagio 1E 4ccc\ . 4bb\ . 4aa\ . 4gg\ =4 =4 1F 4ff\ . 4ee\ . 4dd\ . 4cc\ == == *- *- !!muse2ps: s^[(..)]^z21c220v160	hum2muse input.krn \ | muse2ps \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

Generic text directions

Any arbitrary text can be placed in the music by using the "!LO:TX" layout code.

**kern **kern *clefG2 *clefG2 *k[f#] *k[f#] *M4/4 *M4/4 =1- =1- 4c/ 2aa\ 4d/ . 4e/ 2gg\ 4f/ . !LO:TX:i:rj:t=fine ! =2|| =2|| ! !LO:TX:bi:z=5:t=ritardando 4g/ 2ee\ 4a/ . 4b\ 2dd\ 4cc\ . =3 =3 4b\ 2dd#\ 4a/ . !LO:TX:b:X=-15:Z=15:t=ad lib. ! ! !LO:TX:Z=15:cj:t=reflectively 4g/ 2ee\ 4f/ . =4 =4 4e/ 2ff\ 4d/ . 2c/; 2gg\; !LO:TX:i:rj:X=20:t=D.C. al fine ! =:|! =:|! *- *- !!muse2ps: z21c200v190,200s^[(..)]^

hum2muse input.krn \ | muse2ps \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

Lyrics/Verses

Song lyrics can be displayed by adding one or more **text spines after the **kern spine under which they will be displayed. Each additional **text spine is an additional verse to display. Use the --vl # to limit the number of verses to display underneath the music, such as --vl 3 to show only the first three verses. This is useful, for example, the rest of the verses may be placed underneath the music as regular text for publication.

**kern **text **text *clefG2 * * *M4/4 * * *k[] * * 4e Ma- Ev'- 4d -ry -ry- 4c had -where 4d a that =2 =2 =2 4e lit- Ma- 4e -tle -ry 4e lamb, went, 4r % % =3 =3 =3 *- *- *- !!muse2ps: z21c175	hum2muse input.krn \ | muse2ps \ | ps2pdf - - > output.pdf hum2muse input.krn \ | muse2ps \ | pstopnm -dpi=300 | convert - \ -trim -negate -alpha copy \ -resize '33%' -negate \ output.png

The lyrics can be suppressed by using the --nt (no text) option:

hum2muse --nt input.krn > output.md2

Any Humdrum spine can be treated as lyrics text. To do this, use the --ls (lyrics spine) option. Following this option comes a string which starts with the letter "s", then the number of the staff on the system (1 = top staff of system), then a colon (:), then a list of spines in the file to print as verses for that staff, each spine separated from the previous with a comma (,). Spines are numbered from 1 for the left-most spine. Additional staff/spine assignments can follow the first, by adding ",s" instead of "s" for the subsequent staff number markers. Only the left-most token in a spine will be printed as lyrics (only the first sub-spine). In other words, if the spine splits, the right-hand side of the split will be ignored when printing lyrics.

**kern **kern **a **b **c *clefG2 *clefG2 * * * *M4/4 *M4/4 * * * *k[] *k[] * * * =1- =1- =1- =1- =1- 4c/ 4ee\ a B c 4d/ 4dd\ . B c 4e/ 4cc\ a B . 4f/ 4b\ a . c 4g/ 4a/ . B . 4a/ 4g/ a B si 4b\ 4f/ . . . 4cc\ 4e/ a bee sea 4dd\ 4d/ a B . 4ee\ 4c/ a . see == == == == == *- *- *- *- *-

hum2muse --ls 's1:2,4,3,4,s2:5,3' > output.md2

Note in the preceding example that spines can be repeated as lyrics on multiple staves as well as within the lyrics of the same staff. Also note that the order of the lyrics is given by their order in the --ls assignment string. Currently lyrics have to be printed with notes. Lyrics occurring between notes will be implemented in the future.

Other options

Multiple layers/voices on a staff

Staff layers are ordered from left to right for a spine. Each layer is stored in a separate subspine, which can be created by splitting an existing spine (or sub-spine) with the *^ spine manipulator. When there are multiple layers to display on a staff, the left-most is the first layer, which is inteneded for the highest voice on the staff. Generally the second layer is intended for the lowest voice on the staff.

When there are two voices on a staff, layer 1 should be displayed with stems-up, and layer 2 should be displayed with stems-down. If you switch the rolls of these layers (putting high notes in layer 2 with stems up and vice versa, other musical elements such as slurs will not be placed very well.


**kern *clefG2 *k[b-e-] *M4/4 =1- *^ 4ee-/ 2a\ 4ff/ . *v *v 4gg/ 4ee-/ =2 *^ (4ff/ 8ry . (8bn\ 2gg/ 4cc\) . 4ry *v *v 4ff/ =3 2dd\ 2ee-\) == *- !!muse2ps: z21c180

When there are three (or more) voices on a staff, the first layer should be the highest voice, the second should be the lowest voice, and the third layer should be the middle voice:


**kern *clefG2 *k[b-e-] *M6/8 =1- *^ 4dd/ 8.b-\L . 16a\k 8dd/ 8g\J 4cc/ 8.a\L . 16g\k * *^ 8cc/ [8f\J 8a/ =2 =2 =2 !LO:N:X=-4 !LO:N:X=10 !LO:N:X=0 4b-/ 8.f\]L 4g/ . 16f\k . 8b-/ [8en\J 8g/ !LO:N:X=-4 !LO:N:X=10 !LO:N:X=0 4a/ 8.e\L 4f/ . 16e\k . 8a/ 8d\J 8f/ * *v *v =3 =3 4g/ 8.d\L . 16d\k 8g/ 8c#\J 8.f/L 8d\ . 4A\ 16en/k . 8d/J . =4 =4 8.d/L 4B-\ 16en/k . 8c#/J 8A\ 4d/ 4A\ *v *v 8r =:|! *- !!muse2ps: z21

Visual appearance of notes

The appearance of notes can be changed from their logical display by using the "!LO:N:vis" parameter for notes and rests. Set the value of the parameter to the **recip rhythm of the visual type of note to display:

**kern *clefG2 =1- *^ 4f\ 4cc/ ! !LO:N:vis=2 4f\ 4cc/ ! !LO:N:vis=8 4f\ 4cc/ ! !LO:N:vis=4.. 4f\ 4cc/ ! !LO:N:vis=0 4f\ 4cc/ ! !LO:N:vis=000 4f\ 4cc/ *v *v = *- !!muse2ps: z21c200

A special value of dot for the vis parameter will cause the note to become a dot. This can be used to represent old notational styles where notes extend over barlines:

**kern 4c 4d 4e !LO:N:vis=2 4f = !LO:N:vis=dot 4f 4g 4a 4b == *- !!muse2ps: z21c200

Default duration option

The --dd option can be used to specify a default duration if the **kern data does not contain rhythmic information. This is useful for short examples which do not contain rhythms, or for monophonic Gregorian chant music where there are no rhythms in the music. If all notes in the input do not contain any rhythms, then the default duration value will be used as the duration for the notes. If any note in the data contains a rhythmic value, then all notes without durations will be treated as grace notes. The default default duration is "4" (quarter note). It can be set to any non-tuplet **recip rhythm in the range from a 256th note through a long, with up to 4 augmentation dots.

**kern *clefG2 =1- c/ d/ e/ f/ g/ a/ b\ cc\ dd\ ee\ ff\ gg\ aa\ = *-	hum2muse input.krn hum2muse --dd 1 input.krn hum2muse --dd 256 input.krn	hum2muse --dd 0 input.krn hum2muse --dd 00 input.krn hum2muse --dd 2. input.krn
	hum2muse --dd 8.... input.krn

Embedded Humdrum reference records

By default, reference records from the input Humdrum data file will be embedded in comments at the end of each part-file of the output data. Reference records will be stored as single-line MuseData comments between the lines:

    @@START: HUMDRUMREFERENCE
    @@END: HUMDRUMREFERENCE 

Reference records found at the start of the file before the first exclusive interpretation line are stored after the marker line "@@TOP". Reference records found after the last interpretation records are stored after the marker line "@@BOTTOM". Reference records found within the data are stored after marker lines such as @@POSITION:#", where # is the number of quarter-note duration units from the start of the file to the position of the reference record. If the reference record is found on a non-integer quarter-note position, then its position will be represented by a rational number containing an integer value, a plus sign, then the numerator, slash, and denominator for the fractional part.

hum2muse input.krn > output.md2
!!!ONB: Note at start of data **kern !!!ONB: comment after exclusive interpretation *clefG2 *k[] *M4/4 !!!ONB: another comment after exclusive interpretation =1- 1c !!!ONB: note at start of second measure =2 !!!ONB: another comment at start of second mesasure 1d =3 8e !!!ONB: note on offbeat 4.f 2g == !!!ONB: comment at end before last interpretation *- !!!ONB: Note at end of data		Header Record 1: optional copyright notice Header Record 2: optional file identification TIMESTAMP: FEB/14/2011 [md5sum:0d0a:93b46c8ee1917f96b1357c942acfe3ab] 02/14/2011 hum2muse WK#:1 MV#:1 Header Record 6: source Header Record 7: work title Header Record 8: movement title Header Record 10 Group memberships: score score: part 1 of 1 $ K:0 Q:2 T:4/4 C:4 C4 8 1 w measure 2 D4 8 1 w measure 3 E4 1 1 e F4 3 1 q. G4 4 1 h mheavy2 /END @@START: HUMDRUMREFERENCE @@TOP @!!!ONB: Note at start of data @@POSITION:0 @!!!ONB: comment after exclusive interpretation @!!!ONB: another comment after exclusive interpretation @@POSITION:4 @!!!ONB: note at start of second measure @!!!ONB: another comment at start of second mesasure @@POSITION:8+1/2 @!!!ONB: note on offbeat @@POSITION:12 @!!!ONB: comment at end before last interpretation @@BOTTOM @!!!ONB: Note at end of data @@EXTRA @!!!VTS: 2933917886 @!!!VTS-data: 2744438728 @@END: HUMDRUMREFERENCE /eof //

After the reference records which occur in the file are stored, there is an optional additional section starting with "@@EXTRA" which is used to store a real-time calculated "!!!VTS:" record (CRC32 checksum) for the input Humdrum data. If the Humdrum file contains a "!!!VTS:" record, and the VTS record matches the checksum for the input file, then no "@!!!VTS:" record will be output. Likewise, the @!!!VTS-data: record is used to only calculate the checksum of only the data lines in input Humdrum data.

The Humdrum reference records can be suppressed by using the -R option.

Header Record 1: optional copyright notice Header Record 2: optional file identification TIMESTAMP: FEB/14/2011 [md5sum:0d0a:0ed023e7fb2957a7a9480fbd1d91c3ea] 02/14/2011 hum2muse WK#:1 MV#:1 Header Record 6: source Header Record 7: work title Header Record 8: movement title Header Record 10 Group memberships: score score: part 1 of 1 $ K:0 Q:2 T:4/4 C:4 C4 8 1 w measure 2 D4 8 1 w measure 3 E4 1 1 e F4 3 1 q. G4 4 1 h mheavy2 /END /eof //

Reference recording mapping to MuseData records

The fourth fixed header line of a MuseData part contains a date and encoder name. If there is a "!!!END: reference record in the input file (for encoding date), then that date will be used on the fourth header line. If "!!!END" is not present, but an "EEV" date (for edition date), it will be used as the forth record's date. A "!!!ENC:" (for encoder) will be the person's name used on the fourth line. If there is not EMC record, then any EED (for edition editor) will be used). If neither an ENC or EED record is found, then the string "hum2use" will be used as the encoder's name. Use the --encoder option to override an encoder name extracted from the data.

The first fixed header line can be used for storing a copyright notice for the file. If the input Humdrum data has a YEC reference record, then that copyright notice will be used on the first header line. Use the --copy option to override any YEC reference records for the copyright notice.

The fifth fixed header line in MuseData parts consists of two files for the work and movement number. If an OPS (for opus) is found in the input Humdrum data, that will be used as the work. For music by J.S. Bach, any BWV entry found in an SCT reference record will be used instead of an OPS record. If an ONM record is found, it is added to the WK#: field after the main work number (such as "WK#:10/2" for "!!!OPS: op. 10" and "!!!ONM: no. 2". The Humdrum OMV reference record is mapped to the MuseData "WK#" field on the fifth header line.

The sixth fixed header record of MuseData parts is used to indicate the (primary) source edition used to create the encoding found in the file. If an SMS reference record (for source manuscript) is found in the input Humdrum data, then it will be used for this line.

The seventh fixed header record of MuseData parts is used for the title of the work. The first OTL record found in the input Humdrum data will be used for this line. The eighth fixed header line is for the movement title. The first Humdrum OMD record will be mapped to this line (and in the future the OMV record as well).

Data verification

The third fixed Header line of each part contains a TIMESTAMP and embedded checksum for monitoring changes in the MuseData output from hum2muse. The checksum is enclosed in square brackets, with the first field in the checksum being a string indicating what type of checksum is being used. Currently, only md5 checksums are processed by hum2muse.

This is followed by a colon character (:) and then an optional field indicating the newline convention used to calculate the checksum. In the newline field, the hex bytes of the newline character(s) are given without spaces. For example, "0d0a" is the default method used by hum2muse, which is the MS-DOS newline convention. Use the -U option for unix/linux style newlines (0a), or --MAC for old Apple Macintosh style newlines (0d). An empty string can be given if newlines were stripped off when calculating the checksum. The newline convention field ends in a colon character (:).

The third (or second) field in the checksum description is the actual checksum. The hum2muse program calculates md5 checksums which are 16-byte, 32-character strings of letters and numbers (hexadecimal digits). Here is what the TIMESTAMP line looks like:

    TIMESTAMP: FEB 12/2011 [md5sum:0d0a:e3b9c5e2f7ba851a17d985a9e8b662ea]

The TIMESTAMP line is echoed into the header of the PostScript output from muse2ps, one for each part, with the % character prepended to indicate that it is a comment in the PostScript files, followed by an equals sign (=) to indicate that the PostScript comment is muse2ps-related:

    %=TIMESTAMP: FEB 12/2011 [md5sum:0d0a:77a600245bc1b673d5f0ee7a0382dbdf]
    %=TIMESTAMP: FEB 12/2011 [md5sum:0d0a:596ff91197cb60271a21ba5d9fdd64e6] 

The checksum can be used to verify if the data has changed since it was created with the hum2muse program. To verify the data by hand, extract a single part to a separate file, including from the first fixed Header line (excluding any comment lines before the first Header line), up to but not including the "/eof" marker for that particular part (but including the newline character from the last line before the "/eof" marker line. Next, take note of the checksum encoded on the first TIMESTAMP line found in the part. If it is an md5sum checksum, then remove the contents of the square brackets on the TIMESTAMP line (but leave the square brackets), and run the md5sum command (in linux/unix):

   md5sum partfile

The value which the md5sum program returns should match the original one in the file before it was deleted. If the checksums do not match, then at least one character in the part data has changed. Make sure that the newlines of the extracted part file contain the correct newline character(s) according to the specification in the embedded checksum string.

To do the verification process automatically, use the -v option to verify the checksum for each part in a multi-file stage2 MuseData file. Currently only md5sum checksums can be automatically verified, and will be presumed. When using the -v option, the input data to hum2muse is MuseData rather than Humdrum data. Any mult-file stage2 MuseData file can be verified using hum2muse, not only the MuseData files output by hum2muse. Multiple files can be given as input when using the -v option, or alternately, standard input can be used for a single multi-part MuseData file.

When using the -v option, each part in each file which is given on the command line will generate a line of output consisting of three fields. The first being the filename, the second being the part enumeration (part_1 being the first part found in the file, etc., and not related to the Group Memberships enumerations. The final field on the line is the word "verified" if the checksum stored on the timestamp line matches the calculated checksum of the part, and "modified" otherwise. The hum2muse program will use the newline style listed in the checksum field in order to calculate a checksum, and will use MS-DOS style newlines if no format is given.

hum2muse -v *.md2
erk001.md2 part_1: modified erk001.md2 part_2: modified erk001.md2 part_3: modified mensural.md2 part_1: verified nodynamics.md2 part_1: modified noslurs.md2 part_1: modified options1.md2 part_1: verified slurs.md2 part_1: modified sonata01-1.md2 part_1: verified sonata01-1.md2 part_2: verified testcolor.md2 part_1: modified testcolor2.md2 part_1: modified

When standard input is used, a dot (.) replaces the filename:

hum2muse h://mozart/sonatas/sonata01-1.krn | hum2muse -v
. part_1: verified . part_2: verified

Individual MuseData stage2 part files can also be verified independently from the multi-part data structure. Note that any comments occurring before the first fixed Header line are not included in the checksum calculation, but comments occurring at the end of the file will be included in the calculation:

hum2muse -v singlepart.msd singlepart.msd part_1: verified Header Record 1: optional copyright notice Header Record 2: optional file identification TIMESTAMP: FEB 12/2011 [md5sum:0d0a:58ccef1ed946133b0b1e649d7e0130d7] 02/12/2011 hum2muse WK#:1 MV#:1 Header Record 6: source Header Record 7: work title Header Record 8: movement title Header Record 10 Group memberships: score score: part 1 of 1 $ Q:4 T:9/0 C:4 /END

hum2muse -v multipart.md2 multipart.md2 part_1: verified Header Record 1: optional copyright notice Header Record 2: optional file identification TIMESTAMP: FEB 12/2011 [md5sum:0d0a:58ccef1ed946133b0b1e649d7e0130d7] 02/12/2011 hum2muse WK#:1 MV#:1 Header Record 6: source Header Record 7: work title Header Record 8: movement title Header Record 10 Group memberships: score score: part 1 of 1 $ Q:4 T:9/0 C:4 /END /eof //

Updating timestamps

The --update option will update the timestamp line in one or more MuseData files given as arguments to hum2muse. If standard input is used, then only one multi-part file can be processed. When a file is updated, each part will be checked for changes. If any part does have changes the TIMESTAMP date will be changed to the current date, and the checksum will be recalculated. If standard input is used, then the resulting output will be sent to standard output. If files are given as arguments to the program, the files will be modified with the new contents.

When a part timestamp is updated, the hum2muse program will place the old timestamp line at the bottom of the part in a comment such as:

    @SUPERSEDES: TIMESTAMP: DEC/30/2005 [md5sum:a0c5c05442c0822fb7406eb469ab88ab]
    @REASON: additions and refinements 
 

In this case the @REASON: line gives the reason for updating the file from the DEC/30/2005 version. Additional updates are appended to the file after the most recent update (at the very bottom of the part-file). Use the --reason option to provide a reason string to be sorted on the @REASON: line. If the --reason option is not used, then only the @SUPERSEDES: entry will be inserted. If you do not want the @SUPERSEDES: line to be appended to the part-file when updating, add the --no-append option to suppress storing the old timestamp at the bottom of the part-file. Use the --remove-old to remove all old timestamps when updating the current timestamp.

Page Footer

The -f option can be used to store a page footer file within the output MuseData stream. Here is the basic structure of page footer description:

     @FOOT1: (C) 2011 Your name here
     @FOOT2: 
     @FOOT3: Beethoven: Symphony No. 1 in C Major, Op. 21
     @FOOT1R: %D
     @FOOT2R: %I
     @FOOT3R: page %P
     @END: FOOTER
 

The first three records FOOT1 to FOOT3 are placed at the bottom of the page on the left size, with FOOT1 in the lowest postion on the page. The records FOOT1R to FOOT3R are placed right-justified in the footer. Optional parameters, particularly @LOGO: can be placed within the footer description.

Abbreviations which can be used in the footer description:

%P	Page number
%I	Instrument name (if printing a part)
%D	Current date

In addition, reference records can be inserted into the footer description by enclosing the key of the reference record in curly braces and starting with an @ sign. For example, to insert the !!!OTL: title string into the footer, use this construction: @{OTL}.

To insert a footer description into the MuseData output to hum2muse, give a text string when embeds the 3 left, 3 right and optional additional records. The first character in the string is a separating character of your choice which does not occur in any data field. Next, comes the fields in this order: FOOT3, FOOT2, FOOT1, FOOT3R, FOOT2R, FOOT1R, and then any optional fields, including the initial @ symbols. Example:

   hum2muse -f "*line L1*line L2*line L3*line R1*line R2*line R3"

This would create the footer description:

     @START: FOOTER
     @FOOT1: line L3
     @FOOT2: line L2
     @FOOT3: line L1
     @FOOT1R: line R3
     @FOOT2R: line R2
     @FOOT3R: line R1
     @END: FOOTER
 

Dynamics placement example

    hum2muse h://beethoven/sonata/sonata01-1.krn > sonata01-1.md2
    cat sonata01-1.md2 | muse2ps | ps2pdf -sPAPERSIZE=letter - - > sonata01-1.pdf
 



Lyrics example

    humcat h://liederschatz/erk001.krn | hum2muse > erk001.md2
    cat erk001.md2 | muse2ps | ps2pdf -sPAPERSIZE=letter - - > erk001.pdf
 



More example usages of the hum2muse program are available on the hum2muse examples page

Input arguments or piped data which are expected to be Humdrum files can also be web addresses. For example, if a program can process files like this:

       program file.krn

It can also read the data over the web:

       program http://www.some-computer.com/some-directory/file.krn

Piped data works in a somewhat similar manner:

       cat file.krn | program

is equivalent to a web file using ths form:

       echo http://www.some-computer.com/some-directory/file.krn | program

Besides the http:// protocol, there is another special resource indicator prefix called humdrum:// which downloads data from the kernscores website. For example, using the URI humdrum://brandenburg/bwv1046a.krn:

      program humdrum://brandenburg/bwv1046a.krn

will download the URL:

http://kern.humdrum.org/cgi-bin/ksdata?file=bwv1046a.krn&l=/brandenburg&format=kern
Which is found in the Musedata Bach Brandenburg Concerto collection.

This online-access of Humdrum data can also interface with the classical Humdrum Toolkit commands by using humcat to download the data from the kernscores website. For example, try the command pipeline:

      humcat humdrum://brandenburg/bwv1046a.krn | census -k

• autostem -- use autostem when the input Humdrum data does not contain stem direction information.
• autodynam -- use autodynam to complete partially encoded crescendos/decrescendos.
• autobeam -- automatically beam notes together. Still needs to be written.

Program is under development, main problem is that muse2ps is sensitive to logical errors, such as unmatched slurs.

The compiled hum2muse program can be downloaded for the following platforms:
• Linux (i386 processors) (dynamically linked) compiled on 11 Dec 2013.
• Windows compiled on June 2 2010.
• Mac OS X/i386 compiled on 13 Nov 2013.

The source code for the program was last modified on 19 Aug 2013. Click here to go to the full source-code download page.