Muse2ps

Overview

The muse2ps program is a command-line version of the autoset, mskpage and pspage programs which are usually run within the dmuse editor using the built-in zbex language interpreter. The muse2ps program reads MuseData stage2 data or page file data from standard input and converts them into PostScript data representing graphical musical notation which is sent to standard output. The following diagram illustrates the flow of data through muse2ps:

The muse2ps program can accept two forms of input. By default, the muse2ps program will read multi-file stage2 data from standard input. MuseData stage2 files contain primarily symbolic musical data with possibly a little bit of formatting information (such as system and page breaks). The muse2ps program will format this symbolic music internally into page files which give explicit information about the placement of notes, slurs, beams, dynamics, lyrics, etc. on each page of music.

Alternatively, if the =p option is given as an argument to muse2ps, the program can read multi-file page files directly from standard input. Typically, stage2 files are converted automatically into pages files and then further processing is done on these page files in order to produce a final typeset score of the graphical music notation. For example, the vskpage is used to refine the vertical spacing of staves and systems on a page of music within page files, and eskpage is used to interactively edit the position of graphical elements within page files.

The only output from muse2ps (besides error messages) is PostScript data which describes the graphical music notation in a printable score of the music. This data can be further processed, such as sending directly to a PostScript printer, or converting into PDF files for web distrubution of the notated music. The representation of music notation within the PostScript file is in the form of bit-mapped musical fonts. The musical fonts are designed for use with 300 DPI resolution printers when printed at the native resolution (originally these fonts were designed for PCL-based printers). These fonts have the unique feature of dithered edges on sloped beams to minimize the visual effect of pixel stepping at 300 DPI resolution. Minor notation editing can be done on the PostScript/PDF files in programs such as Adobe Illustrator. If you print via PDF files, you may want to uncheck the page-scaling option in the printing program in order to avoid aliasing artifacts in the hard copy due to changing the intended size of the music on the page.

Two other forms of data can be embedded within the PostScript output. If the =M option is given as an argument to the muse2ps program, then the original stage2 data will be stored within comments in the PostScript data. Likewise, if the =P option is given, the page file data will be included in the PostScript output as comments. The page file data will either come from automatic generation using autoset/mskpage, or from standard input if you use the =p option.

There are also numerous options which primarily deal with the formatting of stage2 files with the autoset and mskpage program components. See the options section below for a complete list of the options.

Download

The muse2ps program executables for various operating systems or the source code can be downloaded from the following table. Instructions for setting up the program for use can be found here.

File	Description
muse2ps.tar.bz2	Tar file containing source code and test examples.
muse2ps-linux	Program executable compiled statically for linux.
muse2ps-osx	Program executable compiled for Apple OS X, version 10.4 and higher.
muse2ps.exe	Program executable compiled for Microsoft Windows (prone to stack overflows in older versions of Windows). It is currently advised to download the source code and compile within a Cygwin terminal if you want to run on Windows (not suitable for the amateur Windows user who is not familiar with Unix).

Online

The muse2ps program can be run online at http://www.musedata.org/mdconverter . If you click on icons next to data found on the http://www.musedata.org website, the musical data will be loaded into this online converter from which PostScript, PDF, or PNG images of the music can be generated.

For example, click on the icon on the information page for this Bach chorale, then click on the Submit button on the converter page to generate a PDF file of the chorale with the default settings. Then try setting some options, such as using "[(.)(.)(.)(.)]" for the System spine option to prevent barlines from being drawn between staves in the score.

You can create your own MuseData content and print with the online converter as well. Copy and paste the following MuseData content: beethoven.md2 into into the MuseData online converter to generate graphical music, which should result in this graphical music notation:

Command-line examples

The simplest use of muse2ps is to send it MuseData stage2 files as standard input, and save standard output from the program into a PostScript file:

cat bach-wtc1p01.md2 | muse2ps > bach-wtc1p01.ps

You may need to use "./muse2ps" instead of "muse2ps" in the above command if the muse2ps program file is in the current directory, but the current directory is not in your command search path. The PostScript output can then be further processed in an external program. Usually it is more convenient to work with the data as a PDF file. The process of converting PostScript to PDF can be done by many methods. For example, Acrobat Distiller or Acrobat Professional will convert PostScript files into PDF files. There are online converters, such as this one: http://www.ps2pdf.com/convert.htm . And on most linux computers you can convert PostScript into PDF files using the ps2pdf command:

ps2pdf bach-wtc1p01.ps

This will create the file bach-wtc1p01.pdf (replacing the .ps extension with a .pdf extention automatically when saving the PDF file). If you click on the PDF file link in the previous sentence, you should see the musical notation for J.S. Bach's Well-Tempered Clavier, Book I, Prelude 1 in C major.

An alternate method of using ps2pdf to generate a PDF file in a single step in conjunction with muse2ps would be with this command-line construction:

cat bach-wtc1p01.md2 | muse2ps | ps2pdf - > bach-wtc1p01.pdf

Last system justification

By default muse2ps does not right-justify the last system of the music on the last page of the output (as can be seen in bach-wtc1p01.pdf). If you want to justify the last system, use the =j option as an argument to muse2ps:

cat bach-wtc1p01.md2 | muse2ps =j | ps2pdf - > bach-wtc1p01-j.pdf

The muse2ps (or more precisely, the internal mskpage component) will possibly adjust line breaks on one or more of the previous systems in the score in order to fill enough music onto the last system, and then stretch or contract the music on the last system to fit the width between margins exactly. The =j option can potentially take significantly more time to process the input data than when it is omitted. The reason for the increased processing time can be seen by comparing bach-wtc1p01.pdf and bach-wtc1p01-j.pdf. In order to right-justify the last system of the music, all systems in the music were recursively re-typeset so that the first system in the music contains only three measures instead of four.

Grand-Staff vertical spacing

The distance between staves in the grand staff (which is used for instruments such as the piano) can be controlled by the =g option. An integer number follows after the letter "g" in the option which specifies the distance between the two staves in terms of 1/10ths of the distance between staff lines. The default value for this option is =g100 which means that the distance between the top line of each staff is 10 staff lines.

Here is an example of reducing the spacing between the staves to nothing. The =g50 option in this case means that the distance between the top of each staff is 5 staff lines. And since this is the height of a single staff, there will be no space between the two staves:

     cat bach-wtc1p01.md2 | muse2ps =g50 | ps2pdf - > bach-wtc1p01-g50.pdf

Single-staff spacing in a system

A system is a collection of staves which represent different instruments playing at the same time. The distance between these staves can be controlled with the =v option. Following =v is a list of comma-separated integers (with no intervening spaces). The unit for these numbers is the same as in the =g option: 1/10th of the distance between successive staff lines.

The default spacing between staves will depend on whether they are supposed to be barred together or not. Here is the default spacing for four staves of a string quartet:

     cat haydn-op54n2-2.md2 | muse2ps | ps2pdf - > haydn-op54n2-2.pdf

Using multiple options

In the previous examples, the prelude is printed on two pages, with a single orphan system occurring on the second page. One way to force the music to fit onto a single page is to set the top margin from 120 pixels to 0 pixels with the option =t0 and the printable length on the page to 3000 pixels (10 inches) with the option =l3000. When supplying multiple optional settings to muse2ps, there is only one option string which starts with the equals character (=) and is followed by all options with no spaces. Here is an example of using the =t0, =l3000 and =j options at the same time, resulting in a single page of music:

cat bach-wtc1p01.md2 | muse2ps =jt0l3000 | ps2pdf - > bach-wtc1p01-jt0l3000.pdf

The order of the options in the option string is not important, so for example, "=l3000t0j" would yield the same results as "=jt0l3000".

Instead of adjusting the vertical margins with the =t and =l options, you can also decrease the spacing between staves globally on the system. To do this, use the =v option followed by a list of distances between each staff on the system. In this example there are two staves in each system, so one value is expected after "=v". If there were three or more staves, then the vertical spacing values are separated by commas (and no spaces).

cat bach-wtc1p01.md2 | muse2ps =v160jt300 | ps2pdf - > bach-wtc1p01-v160jt300.pdf

In the above example, "=v160" means make the spacing between staves on the system slightly more than 1/2 an inch; "=j" means to right-justify the last system of music; and "t300" means add an extra inch to the top margin (the default setting is "=t120".

Music size

The muse2ps program can typeset music in several sizes: 6, 14, 16, 18 and 21. These numbers refer to the pixel count (at 300 DPI) between successive staff lines. For example, here is a zoom-in of music typeset using the size 6 font, where each staff line is one pixel wide, and there are 5 pixels in the gap between lines, making each staff line spaced every 6 pixels and hence the name "size 6":

The default size that muse2ps will typeset music in is size 14. To display the music at other sizes, use the =z option followed by the size. Here is the example prelude printed in all sizes (with right-justification of the last system using =j also added to the option string):

cat bach-wtc1p01.md2 | muse2ps =z6j  | ps2pdf - > bach-wtc1p01-z6j.pdf
cat bach-wtc1p01.md2 | muse2ps =z14j | ps2pdf - > bach-wtc1p01-z14j.pdf
cat bach-wtc1p01.md2 | muse2ps =z16j | ps2pdf - > bach-wtc1p01-z16j.pdf
cat bach-wtc1p01.md2 | muse2ps =z18j | ps2pdf - > bach-wtc1p01-z18j.pdf
cat bach-wtc1p01.md2 | muse2ps =z21j | ps2pdf - > bach-wtc1p01-z21j.pdf

Full-scores are typically printed at size 14 (particularly scores with many parts). Parts for performers are typically printed at sizes 18 or 21. Piano music is typically printed at size 16, and Size 18 has dither on two-pixel wide staff lines. The approximate equivalents to point sizes in regular text (multiplying by the factor 72/300 and then multiplying by 3):

MuseData music size	Staff height (mm)	Approximate text font size	Musical application
6	2.03 mm	4 pt	none
14	4.74 mm	10 pt	full scores
16	5.42 mm	11.5 pt	piano music, vocal scores
18	6.10 mm	13 pt	instrumental parts
21	7.11 mm	15 pt	large-size instrumental parts

Extracting MPG intermediate data

When a MuseData stage2 file is converted into graphical music notation as PostScript output from muse2ps, it will pass through two data transformation steps. The first step is a conversion from stage2 data into non-page-specific i-files which is accomplished with the autoset component. Then these "non-page-specific" i-files are converted into "page-specific" i-files (or Music Page (MPG) files) which describe the precise position of musical elements on each page of typeset music. This music page data can be extracted from the program surreptitiously by using the "=P" option. This will cause the MPG data to be embedded in comments within the PostScript output. Each page of MPG data will be stored in a sequence of comments starting with "%=BeginMPGData: 1", where 1 is the data for page one. And each page of MPG data is ended by the comment "%=EndMPGData: 1".

All MuseData/dmuse related comments in the PostScript output start with the comment marker "%=", so the MPG data can easily be separated from the PostScript content and other irrelevant comments in a manner such as this:

cat bach-wtc1p01.md2 | muse2ps =P | grep "^%=" > mpg-comments.txt

The regular expression search string "^%=" used in the grep command means extract lines from the input which start with the two characters "%=".

A PERL utility program, called unpackmpg, for extracting the MPG data from the comments is included with the source code for muse2ps:

cat bach-wtc1p01.md2 | muse2ps  =Pg85jt200l3000 | unpackmpg > mpg-comments.mpg

In the above command the options mean:

• =P: Output music page data.
• =g85: Set the distance between the staves in the grand staff to 8.5 staff lines (default is 100, or 10 staff lines).
• =j: Right-justify the last system of the music.
• =t200: Set the top margin to 2/3 of a inch below the base position.
• =l3000: Set the vertical printable region to 10 inches.

Inputting MPG data (adding a title)

The extracted music page data from the previous section can be edited (such as to add a title) and then can be reprocessed by muse2ps to generate PostScript output:

cat mpg-with-title.mpg | muse2ps =p | ps2pdf - > bach-wtc1p01-title.pdf

In this case the file mpg-with-title.mpg is the equivalent to the MPG data generated by muse2ps in the previous section: mpg-comments.mpg, but with these three lines added to generate a title for the first page:

X 14
X 46 1200C 0 Well-Tempered Clavier, Book I, Prelude 1 in C major
X 37 1200C 50 BWV 846

The first line sets the font indexes relative to music size 14. The second line places the line at "1200C 0" which means center the line horizontally at location 1200 (4 inches from the left margin), and position the line vertically at position 0 (0 inches below the top margin).

Music page data for many of the score on http://www.musedata.org are available as both stage2 files and music page files. Using the music page files as input to muse2ps will generate better graphical notation results, since the automatically typeset data from the stage2 files has been proofread and adjusted by a human.

Options

Below is a list of the options which muse2ps understands. Options are given as the first (and only) argument to the program, starting with an equals sign (=), then followed by the options in any order, with no spaces between the options. For example, to set the music size to 18 and right-justify the last system on the last page, use the option string =z21j:

cat file.md2 | muse2ps =z21j > file.ps

When using characters which may be parsed by the command-line interpreter, you will have to enclose the option string in single quotes (you can do this all of the time if you are uncertain of the conditions in which they would be required):

cat file.md2 | muse2ps '=z21js^{(..}}^T^title^' | ps2pdf - > file.pdf

In option strings such as "=c<#>", replace <#> with an integer. [#] indicates an optional number.

muse2ps option index

=c compression =C composer =d diagnostics =D dash spacing =E eof insertion =f fill by staff =F fill by system =g grand staff spacing =G group selection =h note space =i indentation flag =I indentation amount =j justification =k display options =l page length =m left margin =M embed stage2 data =n number of systems =p page files input =P embed page files =Q minimum distance duration =s system spine =S title/system space =t top margin =T title =u subtitle =v staff spacing =w system width =W thin barlines =x no suggestions =X no last barline =y no line controls =Y no initial time signature =z music size

See also the Dmuse text file options.dm, or the HTML equivalent options.html for a brief description of each option.

=c<#>	Compression factor: This is measured as a percentage of the default. 100 = no compression (100%). Use smaller values to decrease the spacing between notes (allowing fewer pages in the score). Values larger than 100 will expand the distance between notes (increasing the number of pages in the score). This option is useful to force the last system of music to occur at the bottom of a page.
=C^string^	Display the string as the composer's name at the top right side of the first page. See =T for the title, and =u for the sub-title.
=d<#>	Diagnostics and Error Messages. bit 0 of #: ON = print error messages bit 1 of #: ON = print all diagnostics bit 2 of #: ON = print diagnostics from autoset bit 3 of #: ON = print diagnostics from mskpage bit 4 of #: ON = print diagnostics from pspage no number = 0x01: print error messages For example, =d31 turns on all error message toggles. This option is useful if the output PostScript data from muse2ps is empty. The messages go to standard error, while the PostScript data goes to standard output. Therefore, you can print the error messages and still save or pipe the PostScript data without the error messages mixing with the output data.
=D	Spacing between dashes. Will override spacing in stage2 files: 0 = use default, >0 = space between dashes (units are dash-length).
=E	/END = /eof. The muse2ps program allows for multiple parts to be entered from standard input in a single stream of data. Normally the data files representing each part are separated from each other by a line containing only "/eof" (lowercase; meaning "End of File"). Separate MuseData stage2 files do not typically end in "/eof", but rather, they are required to contain the line "/END" (uppercase) to indicate the end of the data. After "/END", any textual comments are allowed. With the =E option, you do not need to separate files by "/eof", and instead, the next file in the sequence will start on the line coming after "/END". Note, however, that you cannot use the =E option if there is any commentary after "/END" in a file.
=f	Fill pages to the bottom by proportionally stretching all spacings. Default is don't change the vertical spacings.
=F	Fill pages to the bottom by adding to the intersystem space only. Default is don't change the vertical spacings.
=g<#>	Grand staff intra-space measured in multiples of ledger lines times 10. The default is 100, which is 10 ledger lines. Note that this distance reference is different from the =v values which define the distance from the top of one staff to the top of the next staff. For the =g, option, the distance is from the bottom of the top staff to the top of the bottom staff.
=G^group-name^	Group name to process. The default is "score". Available groups are found on data line 11 at the top of each MuseData stage2 file (excluding any single- or multi-line comments). Other possibilities might be "part" or "data".
=h<#>	Alter the minimum allowed space between notes. This is measured as a percentage of the default. 100 = no change (100%).
=i<#>	Initial system indentation options flag. 0 = use program defaults (set indentation with =I option) 1 = no indentation of first system of music 2 = indent first system, and after every forced system break
=I<#>	Specify the indentation amount for the first system in the music. If zero, then default indentation amount will be used. (see the =i option for turning off indentation).
=j	Right-justify the last system of the music so that it extends all of the way across the page. The default is NOT to right justify. Right-justification is a recursive process where measures from previous systems may be moved ahead in the score to cause all systems to have approximately the same note density.
=k^0x#^	Display alternative options. Options are stored in a hexadecimal number prefixed with the string "0x" (C program-styled hex number). The default values are the 0 bit settings. The meaning of the bits in the hexadecimal number are (from least significant to most significant bit): bit meaning 0 k-option activation flag 1: k option is active; read options in more significant bits 0: k option is inactive; used to turn off this option as a command-line override 1 Sforzando/rfz flag 0: display sforzando as sf (rf) 1: display sforzando as sfz (rfz) 2 Sub-edit flag 0: display editorial markup differently from regular data (such as adding brackets around editorial elements) 1: do not display editorial data differently from regular data 3 No-editorial flag 0: display editorial markup data 1: do not display editorial markup data 4 Editorial markup in Roman font flag 0: use cue-size music fonts for editorial marks 1: use Times-Roan font for editorial marks: tr, dynamics 5 Ligature flag 0: do not use ligatures in text 1: use ligatures for "ffl", "ffi", "ff", "fl", and "fi" 6 Figured harmony flag 0: place figured harmony (figured bass) below the staff 1: place figured harmony (figured bass) above the staff 7 mheavy4 barline style flag 0: mheavy4 barline represented by two heavy lines 1: mheavy4 barline represented by one thin, one thick, and then another thin line 8 Multi-voice augmentation dot option 0: allow overstrike of dots in different voices 1: do not allow overstrike 9 New key signatures option 0: don't print a new key signature if it is the same as the previous one on the staff 1: print a new key signature even if it repeats the previous key signature on the staff 10 Mixed duration chords 0: don't allow a mixture of white and black notes in chords 1: allow mixture of white and black notes in chords 11 Suppress key signature flag 0: display key signatures 1: suppress printing of the key signature (such as for timpani parts) 12 Editorial slurs flag 0: all slurs are regular 1: { } and z x slurs are editorial slurs (dashed slurs) 13 New clef sign flag 0: large clefs at start of system, cue-size clefs for clef changes 1: always use large clefs
=l<#>	Length of a page. Distance is measured dots, at 300 dots to the inch. Default is 2740 dots. The default starting height is 120 dots. This will not be lowered, but may be raised to accommodate a longer page.
=m<#>	Left margin, measured in at 300 dots/inch. The default is 200 dots.
=M	Include the contents of the MuseData source files in the trailer section of the file embedded in PostScript comments (if MuseData stage2 files are used as input.
=n<#>	Maximum number of systems on a page. The default is no maximum.
=p	The source is a concatenated set of page specific i-files (also called .mpg files), not a set of MuseData files.
=P	Include listings of the page specific i-files, which are the source of the output PostScript data. Each page is separated.
=Q<#>	Duration which is assigned the minimum distance. 1 = whole notes ... . . . 8 = eighth notes 16 = sixteenth notes, etc.
=s^string^	Custom left-hand spine. If the format is incorrect for any reason, the program will revert to the default. example: =s^[(....)][(..)](.)[({..}..)]^ Each dot in the system bracketing string represents one part, with the first dot in the string representing the top staff of the system. If a grand staff is used for any part, then use the colon character (:) for that part. Staves which should be bracketed together are enclosed in square brackets: []. Staves which should be braced together are enclosed in curly braces: {}. Staves which should be barred together (barlines connecting between staves) are enclosed in parentheses: (). The caret character (^) is used to mark the start and top of the option string. Subsequent options occur immediately after the second caret character with no intervening space.
=S<#>	Add extra space between the title and the first system of music: 0 = use default, >0 = lower the first system (units are 1/300th of an inch).
=t<#>	Top of page. Default is 120 dots.
=T^string^	Display the string as a title at the top of the (first) page. See =u for sub-title, and =C for composer.
=u^string^	Display the string as a sub-title at the top of the (first) page. See =T for the title, and =C for the composer.
=v<#,#,#...#>	Custom spacings. If the format is incorrect for any reason, the program will revert to the default. example: =v192,192,192,208,192,208,176,176,176,200 The above example setting for the =v option can be used for a system with 8 parts (such as 4 woodwinds, 2 horns, and 4 string instruments). The first seven values describe the spacing between each staff in the system, and the last value is the spacing between systems on the page. The spacing between staves and systems is constant with muse2ps. The spacing values are 1/10th of the distance between two staff lines, and the spacing value is the distance from the top of one staff to the top of the next staff (or the top of the last staff on a system to the top of the staff on the next system for the last value in the list). See the =g option for spacing the staves of a grand staff (such as for piano music). When a grand staff is part of a system with more parts, then the distance between the grand staff and the next system is the distance between the top of the bottom staff of the grand-staff pair and the top of the next staff.
=w<#>	System width, measured in at 300 dots/inch. The default is 2050 dots.
=W[#]	Thin barline flag. 0 = use regular barlines. 1 = use thin barlines. No number after =W means the same as =W0.
=x	Defeat all part inclusion suggestions in the data
=X[#]	Leave off the last barline (for short examples). 0 = print last bar, 1 = don't print last bar, =X without a number is equivalent to =X1. Note: you can add extra staff-line space in the last bar by putting in irests, but you must put irests in all parts, and they must all represent the same note-type (duration). Note also: If the last barline is anything but a regular measure line, it will continue to print.
=y	Defeat all line control suggestions in the data.
=Y<#>	Suppress printing first time signature in score. Used for printing small examples which have a time signature in the data, but none desired in graphical notation. You can also use a time signature in the data of "T:9/0" to generate a hidden time signature, and not giving a time signature at the start of a file will result in not time signature being printed. 0 = print initial time signatures (used to override options embedded in data). 1 = suppress first time signature (=Y is equivalent to =Y1).
=z<#>	Music size: choices are 6,14,16,18,21. 14 is the default. This value describes the distance between staff lines in units of 300 dots per inch.

Multi-file input specification

Normally individual MuseData stage2 files contain a single part. These part files are concatenated together and sent via standard input into the muse2ps program. In order for the muse2ps program to be able to segment the separate part files from the original stream the marker "/eof" is added after the last line in each file, and the marker "//" is required after the end of all datafile input into muse2ps.

Typically the last line of a stage2 MuseData file consists of the string "/END" (in uppercase), so add the line "/eof" (in lowercase) after it:

/END
/eof

The very last three lines of input to muse2ps should look like this:

/END
/eof
//

If you specify the =E option when running muse2ps, the "/END" markers will be used to segment the separate part files internally.

The PERL script collatemd2 (included with the source code to muse2ps) can be used to concatenate multiple stage2 part files into a single input stream for muse2ps. The output of the PERL script can be saved to a file for later processing with muse2ps. In this case the recommended file extension for the multi-file MuseData content is .md2 . Here are example uses of collatemd2:

  collatemd2 01 02 03 04 | muse2ps | ps2pdf - > haydn-op54n2-2.pdf

You many have to type "./collatemd2" instead of "collatemd2" if the PERL program is in the current directory and the current directory is not in the command search path. If you download the program from this page, remove the .pl extension when saving (and use a lowercase first letter for the filename). You may have to set the permissions to allow it to be run as a program with the unix command: chmod 0755 collatemd2.

Alternatively, you can save the output from collatemd2 into a file for later use with muse2ps:

  collatemd2 01 02 03 04 > haydn-op54n2-2.md2
  cat haydn-op54n2-2.md2 | muse2ps | ps2pdf - > haydn-op54n2-2.pdf

When downloading MuseData stage2 files from http://www.musedata.org , the parts are all combined into a single multi-file MuseData file which is the equivalent to the output from collatemd2.

Multiple Music Page files

When concatenating multiple Music Page (MPG) files, separate each file's content with a line with the single capital letter "P" on it. Example of how to do this on the command line, creating a PDF file:

for i in ??
do
   cat $i
   echo P
done | muse2ps =p | ps2pdf - - > output.pdf

N.B.: Probably two slashes also need to be added at the end of the last page; otherwise, it will not print:

  //

Color highlighting

A soon-to-be-released update of muse2ps will allow for coloring of notes in the score. This colorization can be used in conjunction with displaying search results, or highlighting notes in an example.

If you place an "R" character in column 14 for note (or rest) records, That note will be highlighted red. A capital "R" will also highlight the stem of the note, while a lower case "r" will color only the notehead. If multiple colored notes all share a common beam, then that beam is also highlighted.

The letter "B" can be used in column 14 to color notes blue, and the letter "G" can be used to color notes green. The lowercase versions "r" and "g" can be used to color only the noteheads and not the stems.

Embedded options

The muse2ps program can read options sent in the input data stream. Options can be embedded in the input data as single-line comments. In stage2 files, single-line comments start with an at-sign (@) in the first column of the line. Following the comment marker comes an option identification string "muse2psv1", with "v1" being the option version level (currently level 1, and can be used in the future to keep options backwards and forwards compatible. Default options, listed in the previous section describing the options, can be overridden by using the default-option setting method which adds two equal signs in a row, followed by any options. Multiple default-option comments may occur to prevent the length of the line from getting too long (it is a good idea to limit the length of the line for full backwards compatibility with dmuse and stage2 files, although the current line limit in dmuse/muse2ps is 900 characters).

Option for specific music sizes can be set by placing the size option between the two equals signs in the option comment. Here is an example option comment header:

@muse2psv1==z18
@muse2psv1==T^Bach Chorale^u^bwv-277^C^J.S. Bach (1685-1750)^
@muse2psv1=z14=v200,155,155,155j
@muse2psv1=z18=v240,195,195,195j
@muse2psv1=z21=v300,230,230,230j

The first two lines are default-option settings for all music sizes. The first line sets the default music size to 18 if no size is given on the command line to muse2ps. The second line sets the title, subtitle, and composer fields on the title page. The last three lines set the vertical spacing between staves at various music sizes; the first for size 14, then size 18, and the last line for size 21.

ps2pdf options

The default behavior of the ps2pdf program is to assume that the input data is formatted for A4 paper. The default output size for muse2ps is US letter. In order for ps2pdf to generate output pages with the correct dimensions, add the option -sPAPERSIZE=letter as an argument to the program:

   ps2pdf -sPAPERSIZE=letter

Another pair of useful options (not needed for output from muse2ps, but useful when adding footers later) embeds the fonts used in the file:

   ps2pdf -sPAPERSIZE=letter -dCompatibilityLevel=1.4 -dPDFSETTINGS=/prepress

For example the Symbol font is not present on the Apple iPad PDF viewer. When using the options in this example, the Symbol font (or the portion used) would be embedded in the file and therefore viewable on an iPad.

Creating images

Graphical images can be created in various ways. A good method is to convert PostScript output from muse2ps to a bitmap image with the unix command-line program pstopnm. For smaller examples and converting to other image formats, Imagemagick's convert is another command-line program which is useful. Both pstopnm and convert are often pre-installed on linux computers, and both are available for free on the internet. They should also work with OS X, and can be used in MS Windows using cygwin.

To create an image, pipe the output from muse2ps into pstopnm, and convert to a bitmapped image at 300 dots per inch. Next pipe the resulting image to convert for further processing. In the following example, the image is first trimmed from a full page to just the area which contains the printed music, then the image is resized to 33% of the original size for use on the web, and saved into a PNG file.

  cat scale.md2 | muse2ps | pstopnm -dpi=300 | \
     convert - -trim -resize '33%' scale.png

Transparent background

Use the options -negate -alpha copy -negate to make the background of the image transparent so that it can be displayed on any background color. Here is the example image which was just created with the above command:

Notice that the background color of the image is white, which becomes noticeable when placing the image on a non-white background color. Now create an image with a transparent background:

  cat scale.md2 | muse2ps | pstopnm -dpi=300 | \
     convert - -trim -negate -alpha copy -negate \
             -resize '33%' scale.png

Images for printed publications

To insert musical examples in a Microsoft or similar word-processing program, do not resize the image, but leave it at the 300 dots per inch size of the original. Then you can rescale the image in the word processor as necessary. This will optimize the quality of the image in the final printout from the word processor.

  cat scale.md2 | muse2ps | pstopnm -dpi=300 | \
     convert - -trim scale.png

Humdrum interface

The muse2ps program can be used in conjunction with the hum2muse program. Here is an example of how to create graphical music notation using the following Humdrum data as an example:

<htmlet>beethoven-kern</htmlet>

hum2muse file.krn | muse2ps \ | ps2pdf - - > file.png

Images can be generated from Humdrum data online by pasting/typing data into the Humdrum online editor. For example, copy and paste the above Humdrum data into the left black box on the Humdrum online editor page, then click on the red "Generate" button to produce an image of the graphical music using the default settings.

Here is the intermediate MuseData which is passed between hum2muse and muse2ps: beethoven.md2. Try copying / pasting this data into the MuseData online converter to generate graphical music, which should result in the same music notation as seen above.

Zbex programs

In the muse2ps source code directory, the sub-directory zprogs contains the zbex programs used to generate the file zfun32.c. Most necessary files needed to create zfun32.c are in that directory, but perhaps not all of them. These programs are not used directly by muse2ps, but are compiled into zbex executable code within zfun32.c. The muse2ps program is essentially a non-interactive version of dmuse (see http://dmuse.ccarh.org). The dmuse program is a text editor which also has a built-in zbex language interpreter and graphical music display capabilities. The interpreter portion of dmuse has been extracted for non-interactive use in muse2ps.

Examples

Further examples of MuseData stage2 files converted into graphical music notation with muse2ps can be found on the MuseData examples page.

Feature requests and bug reports

See the page: Muse2ps feature requests and bug reports.