Difference between revisions of "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.

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):

Extracting PAG 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 PAG 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.

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

            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

              1 = whole notes
             ...   . . .
              8 = eighth notes
             16 = sixteenth notes, etc.

            	=s^[(....)][(..)](.)[({..}..)]^

            =v192,192,192,208,192,208,176,176,176,200

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 (PAG) 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.: 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:

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.