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.

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 then 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.

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 and 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 with the size 6 font, where each staff line is one pixel wide, and there are 5 pixels in the gap between lines:

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 size 21. Size 18 has dither on two-pixel wide staff lines.

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 argument to the program, staring with an equals sign (=) and 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 my 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 '=z21j' | ps2pdf - > file.pdf

In option strings such as "=c<#>", replace <#> with an integer.

=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.
=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.
=F	Fill pages to the bottom by adding to the intersystem space only. Default is don't change the vertical spacings.
=f	Fill pages to the bottom by proportionally stretching all spacings. 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.
=h<#>	Alter the minimum allowed space between notes. This is measured as a percentage of the default. 100 = no change (100%).
=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.
=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
=n<#>	Maximum number of systems on a page. The default is no maximum.
=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^[(....)][(..)](.)[({..}..)]^
=t<#>	Top of page. Default is 120 dots
=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
=x	Defeat all part inclusion suggestions in the data
=y	Defeat all line control suggestions in the data
=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.
=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.
=P	include listings of the page specific i-files, which are the source of the output PostScript data. Each page is separated
=p	The source is a concatenated set of page specific i-files (also called .mpg files), not a set of MuseData files.
=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".
=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.

Multi-file input specification

When inputting MuseData stage 2 files, each input file (which contains one part), should be ended by:

/END
/eof

The "/END" is probably optional. After "/END", any commentary text may occur which will be ignored by programs which process MuseData stage 2 files. The "/eof" marker is used specifically by muse2ps to locate the end of the current file (part). The very last line of input to muse2ps should be "//". So the end of the last part file send to muse2ps should look like this:

/END
/eof
//

Zprogs: autoset.z and pspage.z

The sub-directory zprogs contains programs used to generate the file zfun32.c. Most necessary files 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 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. The intepreter portion of dmuse has been extracted for non-interactive use in muse2ps.

Feature Requests and Bugs

Feature Requests

• For short examples which do not start at measure 1, it would be useful to allow adding a bar number at the start of the music.
• It would be useful to add components of the stage1 → stage2 process: (1) have an option which turns on automatic determination of stem directions, (2) have an option which turns on automatic determination of beaming. These would preferrably be separate options, since it is more likely that input data from other sources would have beaming information, but not stemming information.
• Allow for "invisible" time signatures.
• Allow for "invisible" barlines (such as ending a short example with an incomplete barline).
• Add the following line at the end of the DSC comment header in the PostScript output:

   %%DocumentPaperSizes: Letter

For example:

%!PS-Adobe-3.0
%%BoundingBox: (atend)
%%HiResBoundingBox: (atend)
%%HiResSystemBox: 59.76 95.76 552.00 722.64
%%Creator: muse2ps 1.0
%%CreationDate: Thu Dec 23 10:48:53 2010
%%Orientation: Portrait
%%Pages: 1
%%PageOrder: Ascend
%%DocumentPaperSizes: Letter
%%EndComments

Reference: http://en.wikipedia.org/wiki/Document_Structuring_Conventions

Bugs

• When there is no time signature present, the music is spaced in a weird manner.