Difference between revisions of "Muse2ps"

From CCARH Wiki
Jump to navigation Jump to search
Line 22: Line 22:
 
== Download ==
 
== Download ==
  
The ''dmuse2ps'' program executables for various operating systems or source code can be downloaded from the following table.  Instructions on setting up the program for use can be found [[Muse2ps_installation_instructions| here]].
+
The ''dmuse2ps'' 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 [[Muse2ps_installation_instructions| here]].
  
  

Revision as of 21:15, 19 December 2010

Overview

The dmuse2ps 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 dmuse2ps 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:


Muse2ps-dataflow.svg

The dmuse2ps program can accept two forms of input. By default, the dmuse2ps 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 dmuse2ps 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.

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 mskpag program components. See the options section below for a complete list of the options.

Download

The dmuse2ps 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

Command-line example usages

To compile dmuse2ps, type the command:

   make

Once the program has been compiled, you can go into the tests/ directory and type either "make" to create PostScript files for three test works, or type "make pdf" to create PDFs for the test works. Example output of dmuse2ps can be found in tests/pdf.

Input and output files

Options can be given to muse2ps. For example, "z21" is the option which sets the music size to 21 (21 pixels at 300 dpi between staves):

    cat work.md2 | muse2ps =z21 > work.ps

When inputting MPG (Music PaGe) files you must specify the "P" option:

    cat work.mpg | muse2ps =P > work.ps

If you are inputting multiple MPG files (each MPG file represents one page of a score or part), add the letter "P" on a line by itself after the single-page MPG content.


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

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.
=d<#> putc 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
=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.
=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. The default is NOT to right justify.
=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,192,208,176,176,176,200
=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<#> notesize: choices are 6,14,16,18,21. 14 is the default.
=M include a listing of the MuseData source files in the Trailer section of the file
=P include listings of the page specific i-files, which are the source of the .ps files
=p The source is a concatinated set of page specific i-files (also called .mpg files), not a set of Musedate files.
=G^group-name^ group name to process. The default is "score"
=E /END = /eof

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