View source for Muse2ps

__TOC__

== Overview == 

The <b>muse2ps</b> 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'':


<center>
[[File:muse2ps-dataflow.svg]]
</center>

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 <tt>=p</tt> 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 [http://en.wikipedia.org/wiki/Printer_Command_Language PCL-based printers]).  These fonts have the unique feature of [http://en.wikipedia.org/wiki/Dither 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 <tt>=M</tt> 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 <tt>=P</tt> 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 <tt>=p</tt> 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| 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.  <b>Instructions for setting up the program for use can be found ''[[Muse2ps_installation_instructions| here]]''.</b>


<center>
{{muse2psdownloadtable}}
</center>

== Online ==

The ''muse2ps'' program can be run online at http://www.musedata.org/mdconverter .  If you click on [[File:E-button.png||||||link=http://www.musedata.org/cgi-bin/mdconverter?action=load&composer=bach&edition=bg&genre=chorals&work=0428&movement=01]] 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 [[File:E-button.png||||||link=http://www.musedata.org/cgi-bin/mdconverter?action=load&composer=bach&edition=bg&genre=chorals&work=0428&movement=01]] icon on the information page for this [http://www.musedata.org/encodings/bach/bg/chorals/0428/ Bach chorale], then click on the {{keypress|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 "<tt>[(.)(.)(.)(.)]</tt>" for the <b>System spine</b> 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: [[Media:beethoven-kern.md2 | beethoven.md2]] into into the [http://www.musedata.org/mdconverter MuseData online converter] to generate graphical music, which should result in this graphical music notation:
<center>
[[Image:beethoven-kern.png]]
</center>

== 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 [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps > [[Media:bach-wtc1p01.ps|bach-wtc1p01.ps]]

You may need to use "<tt>./muse2ps</tt>" instead of "<tt>muse2ps</tt>" in the above command if the ''muse2ps'' program file is in the current directory, but the current directory is not in your [http://en.wikipedia.org/wiki/PATH_%28variable%29 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 [http://pages.cs.wisc.edu/~ghost/doc/gnu/5.50/Ps2pdf.htm ps2pdf] command:
 ps2pdf [[Media:Bach-wtc1p01.ps|bach-wtc1p01.ps]]
This will create the file [[Media:Bach-wtc1p01.pdf|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 [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps | ps2pdf - > [[Media:bach-wtc1p01.pdf|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 [[Media:Bach-wtc1p01.pdf|bach-wtc1p01.pdf]]).  If you
want to justify the last system, use the <tt>=j</tt> option as an argument to ''muse2ps'':
 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =j | ps2pdf - > [[Media:bach-wtc1p01-j.pdf|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 <tt>=j</tt> 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 [[Media:bach-wtc1p01.pdf|bach-wtc1p01.pdf]] and [[Media:bach-wtc1p01-j.pdf|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 [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =g50 | ps2pdf - > [[Media:bach-wtc1p01-g50.pdf|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 [[Media:haydn-op54n2-2.md2|haydn-op54n2-2.md2]] | muse2ps | ps2pdf - > [[Media:haydn-op54n2-2.pdf|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 <tt>=t0</tt> and the printable length on the page to 3000 pixels (10 inches) with the option <tt>=l3000</tt>.  When supplying multiple optional settings to muse2ps, there is only one option string which starts with the equals character (<tt>=</tt>) and is followed by all options with no spaces.  Here is an example of using the <tt>=t0</tt>, <tt>=l3000</tt> and <tt>=j</tt> options at the same time, resulting in a single page of music:
 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =jt0l3000 | ps2pdf - > [[Media:bach-wtc1p01-jt0l3000.pdf|bach-wtc1p01-jt0l3000.pdf]]
The order of the options in the option string is not important, so for example, "<tt>=l3000t0j</tt>" would yield the same results as "<tt>=jt0l3000</tt>".

Instead of adjusting the vertical margins with the <tt>=t</tt> and <tt>=l</tt> 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 [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =v160jt300 | ps2pdf - > [[Media:bach-wtc1p01-v160jt300.pdf|bach-wtc1p01-v160jt300.pdf]]

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

=== 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":

<center>
[[File:Dmuse-size6.png|411px]]
</center>


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

 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =z6j&nbsp;&nbsp;| ps2pdf - > [[Media:bach-wtc1p01-z6j.pdf|bach-wtc1p01-z6j.pdf]]
 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =z14j | ps2pdf - > [[Media:bach-wtc1p01-z14j.pdf|bach-wtc1p01-z14j.pdf]]
 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =z16j | ps2pdf - > [[Media:bach-wtc1p01-z16j.pdf|bach-wtc1p01-z16j.pdf]]
 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =z18j | ps2pdf - > [[Media:bach-wtc1p01-z18j.pdf|bach-wtc1p01-z18j.pdf]]
 cat [[Media:bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =z21j | ps2pdf - > [[Media:bach-wtc1p01-z21j.pdf|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):

<center>
{|  class="wikitable" cellpadding="0" cellspacing="0" border="0"
|- |- {{Style|table header}}
! scope="col" align="left" | MuseData music size
! scope="col" align="left" | Staff height (mm)
! score="col" align="left" | Approximate text font size
! score="col" align="left" | 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
|}
</center>

=== 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" [[page files|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 "<tt>%=BeginMPGData: 1</tt>", where <tt>1</tt> is the data for page one.  And each page of MPG data is ended by the comment <tt>"%=EndMPGData: 1"</tt>.

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 [[Media:Bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps =P | grep "^%=" > [[Media:Mpg-comments.txt|mpg-comments.txt]]
The [[regular expression]] search string "<tt>^%=</tt>" used in the [http://en.wikipedia.org/wiki/Grep grep] command means extract lines from the input which start with the two characters "<tt>%=</tt>".

A PERL utility program, called [[Media:unpackmpg.pl|unpackmpg]], for extracting the MPG data from the comments is included with the source code for ''muse2ps'':
 cat [[Media:Bach-wtc1p01.md2|bach-wtc1p01.md2]] | muse2ps  =Pg85jt200l3000 | [[Media:unpackmpg.pl|unpackmpg]] > [[Media:Mpg-comments.mpg|mpg-comments.mpg]]
In the above command the options mean:
* <tt>=P</tt>: Output [[music page]] data
* <tt>=g85</tt>: Set the distance between the staves in the grand staff to 8.5 staff lines (default is 100, or 10 staff lines).
* <tt>=j</tt>: Right-justify the last system of the music.
* <tt>=t200</tt>: Set the top margin to 2/3 of a inch below the base position.
* <tt>=l3000</tt>: 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 [[Media:Mpg-with-title.txt|mpg-with-title.mpg]] | muse2ps =p | ps2pdf - > [[Media:Bach-wtc1p01-title.pdf|bach-wtc1p01-title.pdf]]

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

<pre>
X 14
X 46 1200C 0 Well-tempered Clavier, Book I, prelude 1 in C major
X 37 1200C 50 BWV 846
</pre>

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, staring 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 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 '=z21js^{(..}}^T^title^' | ps2pdf - > file.pdf

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

{|class="wikitable" cellpadding="0" cellspacing="0" border="0" style="width:100%"
|- {{Style|table header}}
! scope="col" width="100px" align="center"| muse2ps option index
|-
| <div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* {{nowrap|{{mopt|c}} compression}}
* {{nowrap|{{mopt|C}} composer}}
* {{nowrap|{{mopt|d}} diagnostics}}
* {{nowrap|{{mopt|D}} dash spacing}}
* {{nowrap|{{mopt|E}} eof insertion}}
* {{nowrap|{{mopt|f}} fill by staff}}
* {{nowrap|{{mopt|F}} fill by system}}
* {{nowrap|{{mopt|g}} grand staff spacing}}
* {{nowrap|{{mopt|G}} group selection}}
* {{nowrap|{{mopt|h}} note space}}
* {{nowrap|{{mopt|i}} indentation flag}}
* {{nowrap|{{mopt|I}} indentation amount}}
* {{nowrap|{{mopt|j}} justification}}
* {{nowrap|{{mopt|k}} display options}}
* {{nowrap|{{mopt|l}} page length}}
* {{nowrap|{{mopt|m}} left margin}}
* {{nowrap|{{mopt|M}} embed stage2 data}}
* {{nowrap|{{mopt|n}} number of systems}}
* {{nowrap|{{mopt|p}} page files input}}
* {{nowrap|{{mopt|P}} embed page files}}
* {{nowrap|{{mopt|Q}} min. dist. dur.}}
* {{nowrap|{{mopt|s}} system spine}}
* {{nowrap|{{mopt|S}} title/system space}}
* {{nowrap|{{mopt|t}} top margin}}
* {{nowrap|{{mopt|T}} title}}
* {{nowrap|{{mopt|u}} subtitle}}
* {{nowrap|{{mopt|v}} staff spacing}}
* {{nowrap|{{mopt|w}} system width}}
* {{nowrap|{{mopt|W}} thin barlines}}
* {{nowrap|{{mopt|x}} no suggestions}}
* {{nowrap|{{mopt|X}} no last barline}}
* {{nowrap|{{mopt|y}} no line controls}}
* {{nowrap|{{mopt|Y}} no initial time sig.}}
* {{nowrap|{{mopt|z}} music size}}
</div>
|}
<br>

See also the Dmuse text file [[Media:muse2ps-options.dm | options.dm]], or the HTML equivalent [[Media:muse2ps-options.html| options.html]] for a brief description of each option.

{| style="background-color:white" cellpadding="4"
|- valign="top"
|  {{anchor|c_option}}<b>=c</b><#>||  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.

|- valign="top"
|{{anchor|C_option}}<b>=C</b>^string^ || Display the ''string'' as the composer's name at the top right side of the first page.  See <b>=T</b> for the title, and <b>=u</b> for the sub-title. <!-- option added Jan 2011 -->

|- valign="top"
|  {{anchor|d_option}}<b>=d</b><#> || 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.

|- valign="top"
|  {{anchor|D_option}}<b>=D</b>   ||  spacing between dashes.  Will over-ride spacing in stage2 files: 0 = use default, >0 = space between dashes (units are dash length)

|- valign="top"
|  {{anchor|E_option}}<b>=E</b>  ||   <tt>/END</tt> = <tt>/eof</tt>.  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 "<tt>/eof</tt>" (lowercase; meaning "End of File").  Separate MuseData [[stage2]] files do not typically end in "<tt>/eof</tt>", but rather, they are required to contain the line "<tt>/END</tt>" (uppercase) to indicate the end of the data.  After "<tt>/END</tt>", any textual comments are allowed.  With the =E option, you do not need to separate files by "<tt>/eof</tt>", and instead, the next file in the sequence will start on the line coming after "<tt>/END</tt>".  Note, however, that you cannot use the =E option if there is any commentary after "<tt>/END</tt>" in a file.

|- valign="top"
|  {{anchor|f_option}}<b>=f</b>   ||  Fill pages to the bottom by proportionally stretching all spacings.  Default is don't change the vertical spacings.

|- valign="top"
| {{anchor|F_option}}<b>=F</b>   ||  Fill pages to the bottom by adding to the intersystem space only.  Default is don't change the vertical spacings.

|- valign="top"
| {{anchor|g_option}}<b>=g</b><#>||  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.

|- valign="top"
| {{anchor|G_option}}<b>=G</b>^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".

|- valign="top"
| {{anchor|h_option}}<b>=h</b><#> || Alter the minimum allowed space between notes.  This is measured as a percentage of the default. 100 = no change (100%).

|- valign="top"
|{{anchor|i_option}}<b>=i</b><#> || Initial system indentation options flag.
* 0 = use program defaults (set indentation with <tt>=I</tt> option).
* 1 = no indentation of first system of music
* 2 = indent first system, and after every forced system break.

|- valign="top"
| {{anchor|I_option}}<b>=I</b><#> || Specify the indentation amount for the first system in the music.   If zero, then default indentation amount will be used. (see the <tt>=i</tt> option for turning off indentation).

|- valign="top"
|{{anchor|j_option}}<b>=j</b>   ||  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.

|- valign="top"
| {{anchor|k_option}}<b>=k</b>^0x<tt>#</tt>^   || Display alternative options.  Options are stored in a hexadecimal number prefixed with the string "<tt>0x</tt>" (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):

<table cellpadding=0 cellspacing=0>
<tr valign=baseline><th>bit</th><td width=10></td><th>meaning</th></tr>

<tr valign=baseline><td>0</td><td></td><td>
<b>k-option activation flag</b>
* 1: <i>k</i> option is active, read options in more significant bits.
* 0: <i>k</i> option is inactive. Used to turn off this option as a command-line over-ride.
</td></tr>

<tr valign=baseline><td>1</td><td></td><td>
<b>Sforzando/rfz flag</b>
* 0: display sforzando as sf (rf)
* 1: display sforzando as sfz (rfz)
</td></tr>

<tr valign=baseline><td>2</td><td></td><td>
<b>Sub-edit flag</b>
* 0: diplay editorial markup differently from regular data (such as adding brackets around editorial elements).
* 1: do not display editorial data differently from regular data.
</td></tr>

<tr valign=baseline><td>3</td><td></td><td>
<b>No-editorial flag</b>
* 0: display editorial markup data.
* 1: do not display editorial markup data.
</td></tr>

<tr valign=baseline><td>4</td><td></td><td>
<b> Editorial markup in Roman font flag</b>
* 0: use cue-size music fonts for editorial marks.
* 1: use Times-Roan font for editorial marks: tr, dynamics
</td></tr>

<tr valign=baseline><td>5</td><td></td><td>
<b>Ligature flag</b>
* 0: do not use ligatures in text.
* 1: use ligatures for "ffl", "ffi", "ff", "fl", and "fi".
</td></tr>

<tr valign=baseline><td>6</td><td></td><td>
<b>figured harmony flag</b>
* 0: place figured harmony (figured bass) below the staff.
* 1: place figured harmony (figured bass) above the staff.
</td></tr>

<tr valign=baseline><td>7</td><td></td><td>
<b> mheavy4 barline style flag</b>
* 0: mheavy4 barline represented by two heavy lines.
* 1: mheavy4 barline represented by one thin, one thick, and then another thin line.
</td></tr>

<tr valign=baseline><td>8</td><td></td><td>
<b>Multi-voice augmentation dot option</b>
* 0: allow overstrike of dots in different voices.
* 1: do now allow overstrike
</td></tr>

<tr valign=baseline><td>9</td><td></td><td>
<b>New key signatures option</b>
* 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.
</td></tr>

<tr valign=baseline><td>10</td><td></td><td>
<b>Mixed rhythm chords</b>
* 0: Don't allow a mixture of white and black notes in chords.
* 1: Allow mixture of white and black notes in chords.
</td></tr>

<tr valign=baseline><td>11</td><td></td><td>
<b>Suppress key signature flag </b>
* 0: display key signatures
* 1: suppress printing of the key signature (such as for timpani parts).
</td></tr>

<tr valign=baseline><td>12</td><td></td><td>
<b>Editorial slurs flag</b>
* 0: all slurs are regular.
* 1: <tt>{ }</tt> amd <tt>z x</tt> slurs are editorial slurs (dashed slurs).
</td></tr>

<tr valign=baseline><td>13</td><td></td><td>
<b>New clef sign flag </b>
* 0: Large clefs at start of system, cue-size clefs for clef changes.
* 1: Always use large clefs.
</td></tr>

</table>

|- valign="top"
| {{anchor|l_option}}<b>=l</b><#>||  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.

|- valign="top"
| {{anchor|m_option}}<b>=m</b><#> || Left margin, measured in at 300 dots/inch.  The default is 200 dots

|- valign="top"
|  {{anchor|M_option}}<b>=M</b>   ||  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.

|- valign="top"
| {{anchor|n_option}}<b>=n</b><#>  || Maximum number of systems on a page.  The default is no maximum.

|- valign="top"
| {{anchor|p_option}}<b>=p</b>    || The source is a concatenated set of page specific i-files (also called .mpg files), not a set of MuseData files.

|- valign="top"
| {{anchor|P_option}}<b>=P</b>   ||  include listings of the page specific i-files, which are the source of the output PostScript data.  Each page is separated

|- valign="top"
| {{anchor|Q_option}}<b>=Q</b><#> || Duration which is assigned the minimum distance
               1 = whole notes
              ...   . . .
               8 = eighth notes
              16 = sixteenth notes, etc

|- valign="top"
| {{anchor|s_option}}<b>=s</b>^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: <tt>[]</tt>.  Staves which should be braced together are enclosed in curly braces: <tt>{}</tt>.  Staves which should be barred together (barlines connecting between staves) are enclosed in parentheses: <tt>()</tt>.  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.

|- valign="top"
| {{anchor|S_option}}<b>=S</b><#> || 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).

|- valign="top"
|{{anchor|t_option}}<b>=t</b><#> || Top of page.  Default is 120 dots.

|- valign="top"
| {{anchor|T_option}}<b>=T</b>^string^ || Display the ''string'' as a title at the top of the (first) page. See <b>=u</b> for sub-title, and <b>=C</b> for composer. <!-- option added Jan 2011 -->

|- valign="top"
| {{anchor|u_option}}<b>=u</b>^string^ || Display the ''string'' as a sub-title at the top of the (first) page.  See <b>=T</b> for the title, and <b>=C</b> for the composer. <!-- option added Jan 2011 -->

|- valign="top"
| {{anchor|v_option}}<b>=v</b><#,#,#...#> || 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 <tt>=g</tt> 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.

|- valign="top"
| {{anchor|w_option}}<b>=w</b><#> || System width, measured in at 300 dots/inch.  The default is 2050 dots

|- valign="top"
| {{anchor|W_option}}<b>=W</b>[#] || Thin barline flag.  0 = use regular barlines. 1 = use thin barlines.  No number after <tt>=W</tt> means the same as <tt>=W0</tt>.

|- valign="top"
| {{anchor|x_option}}<b>=x</b>  ||   Defeat all part inclusion suggestions in the data

|- valign="top"
| {{anchor|X_option}}<b>=X</b>[#]  ||  Leave off the last barline (for short examples). 0  = print last bar, 1 = don't print last bar, <tt>=X</tt> without a number is equivalent to <tt>=X1</tt>.  Note: you can add extra staff line space in the last bar by putting in <tt>irest</tt>s, but you must put <tt>irest</tt>s in all parts ,and they must all represent the same note type (duration). Note also:  If the last bar line is anything but a regular measure line, it will continue to print.

|- valign="top"
|{{anchor|y_option}}<b>=y</b>   ||  Defeat all line control suggestions in the data

|- valign="top"
|{{anchor|Y_option}}<b>=Y</b><#>   ||  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 "<tt>T:9/0</tt>" to generate a <i>hidden</i> 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 (<tt>=Y</tt> is equivalent to <tt>=Y1</tt>).

|- valign="top"
| {{anchor|z_option}}<b>=z</b><#> || 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 marked "<tt>/eof</tt>" is added after the last line in each file, and the marker "<tt>//</tt>" is ''required'' after the end of all datafile input into muse2ps.  

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

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

 /END
 /eof
 //

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

The PERL script [[Media:collatemd2.pl|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 <b>.md2</b> .  Here are example uses of [[Media:collatemd2.pl|collatemd2]]:
   [[Media:collatemd2.pl|collatemd2]] [[Media:haydn-op54n2-2-01.md2|01]] [[Media:haydn-op54n2-2-02.md2|02]] [[Media:haydn-op54n2-2-03.md2|03]] [[Media:haydn-op54n2-2-04.md2|04]] | muse2ps | ps2pdf - > [[Media:haydn-op54n2-2.pdf|haydn-op54n2-2.pdf]]

You many have to type "<tt>./collatemd2</tt>" instead of "<tt>collatemd2</tt>" 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 lower-case 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: <tt>chmod 0755 collatemd2</tt>.

Alternatively, you can save the output from [[Media:collatemd2.pl|collatemd2]] into a file for later use with muse2ps:
   [[Media:collatemd2.pl|collatemd2]] [[Media:haydn-op54n2-2-01.md2|01]] [[Media:haydn-op54n2-2-02.md2|02]] [[Media:haydn-op54n2-2-03.md2|03]] [[Media:haydn-op54n2-2-04.md2|04]] > [[Media:haydn-op54n2-2.md2|haydn-op54n2-2.md2]]
   cat [[Media:haydn-op54n2-2.md2|haydn-op54n2-2.md2]] | muse2ps | ps2pdf - > [[Media:haydn-op54n2-2.pdf|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 [[Media:collatemd2.pl|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:

<source lang="bash">
for i in ??
do
   cat $i
   echo P
done | muse2ps =p | ps2pdf - - > output.pdf
</source>

N.B.: Probably two slashes also need to be added at the end of the last page (`//`).

== 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 <i>muse2ps</i> 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 (<tt>@</tt>) in the first column of the line.  Following the comment marker comes an option identification string "<tt>muse2psv1</tt>", with "<tt>v1</tt>" 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 <tt>-sPAPERSIZE=letter</tt> 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 at later states in data program) embed 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 images formtas, Imagemagick's convert is another command-line 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 [http://www.cygwin.com 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 [[Media:scale.md2|scale.md2]] | muse2ps | pstopnm -dpi=300 | \
      convert - -trim -resize '33%' [[Media:scale.png|scale.png]]

=== Transparent background ===

Use the options <tt>-negate -alpha copy -negate</tt> 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:

 [[Image:scale.png]]

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 [[Media:scale.md2|scale.md2]] | muse2ps | pstopnm -dpi=300 | \
      convert - -trim -negate -alpha copy -negate \
              -resize '33%' [[Media:scale-transparent.png|scale.png]]
<center>
<table cellspacing=0 cellpadding=3><tr bgcolor=#ffffff><td bgcolor=#4499aa>
[[Image:scale-transparent.png]]
</td><td width=10>
<td bgcolor=#ffaa44>[[Image:scale-transparent.png]]
</td></tr></table></center>


=== 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 [[Media:scale.md2|scale.md2]] | muse2ps | pstopnm -dpi=300 | \
      convert - -trim [[Media:scale-large.png|scale.png]]

== Humdrum interface ==

The muse2ps program can be used in conjunction with the [http://extra.humdrum.org/man/hum2muse hum2muse] program.  Here is an example of how to create graphical music notation using the following Humdrum data as an example:

<table cellspacing=0><tr bgcolor=white valign=top><td><htmlet>beethoven-kern</htmlet></td>
<td width=10></td>
<td> 
<pre>
hum2muse file.krn | muse2ps \
    | ps2pdf - - > file.png
</pre>
[[Image:beethoven-kern.png]]    
<br>
<br>
<br>
</td>
</tr>
</table>

Images can be generated from Humdrum data online by pasting/typing data into the [http://kern.humdrum.org/cgi-bin/kern/kseditor Humdrum online editor].  For example, copy and paste the above Humdrum data into the left black box on the Humdrum online editor page, and the 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 [http://extra.humdrum.org/man/hum2muse hum2muse] and muse2ps: [[Media:beethoven-kern.md2 | beethoven.md2]].  Try copying / pasting
this data into the [http://www.musedata.org/mdconverter 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 <tt>zprogs</tt> contains the [[zbex]] programs used to generate the file zfun32.c.  Most necessary files needed to create [http://www.ccarh.org/software/muse2ps/muse2ps/zfun32.c 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 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]].