abcm2ps - translate ABC music notation to PostScript

abcm2ps [options] [abc-file [file-options]] [...]

abcm2ps [-h]

abcm2ps translates tunes written in the ABC music notation format to customary sheet music scores in PostScript. It is based on abc2ps 1.2.5 and was developed mainly to print Baroque organ scores that have independent voices played on multiple keyboards and a pedal-board. The program has since been extended to support various other notation conventions in use for sheet music.

Options given immediately after the command name apply to the run as a whole; options given after an ABC file name apply to that file.

Formatting parameters can also be set in `format files' and in the ABC files themselves.

-0

Split tunes across page breaks if necessary.

+0

Start a new page if a tune doesn't fit on the current one (default).

-1

Output one tune per page.

+1

Output multiple tunes per page (default).

-a a

Maximal horizontal compression when staff breaks are chosen automatically. Must be between 0 and 1 (default: 0.65)

-B b

Try to typeset b bars on each staff line.

+B

Don't try to typeset a fixed number of bars on each staff line (default).

-b b

Start measure numbering at b.

-C

Obsolete option; ignored.

-c

The continuation symbol is implicitly appended to each music line. This amounts to automatic line breaking.

+c

Automatic line breaking is turned off (default).

-D directory

Search format files in directory.

-d length

Set the vertical interstaff space to length (default: 46pt)

-E

Output is generated in EPS format, one file per page.

+E

Output is generated in multipage PS format (default).

-e list

Select which tunes from an ABC file to print. list is a comma-separated list of tune numbers (as per the `X:' header). The -e option must occur after an ABC file name and applies to that file. Ranges of tune numbers may be specified like t1-t2; t2 may be omitted which means `all remaining tunes until the end of file'. Note that filtering may cause problems, e.g., with global (non-tune) definitions in the ABC file.

-F file

Read the format file file.fmt.

+F

Do not read the default format file.

-f

Enable flat beams in bagpipe tunes.

-G

Omit slurs on grace notes.

+G

Draw slurs on grace notes (default).

-g

Obsolete option; ignored.

-H

Display the current values of the formatting parameters.

-h

Display program usage hints and quit.

-I length

Indent the first line of the tune by length (default: 0).

-jb[b]

Output a measure number every b measures. If b is 0, the measure number appears at the left of each staff. The trailing b causes a box to be drawn around each measure number (default: no measure numbering).

+j

Don't output measure numbers.

-k

Equivalent to -j.

+k

Equivalent to +j.

-Lenc

Set the language encoding to ISO-Latin-enc, where enc can take on values from 0 to 6. The value 0 is equivalent to 1 but no PostScript encoding table is output (default: 0).

-l

Generate landscape output.

+l

Generate portrait output (default).

-M

Suppress lyrics.

+M

Include lyrics (default).

-m length

Set the left margin to length (default: 1.8cm)

-N[mode]

Number pages according to the mode:

0

no page numbers

1

page numbers at top left of page

2

page numbers at top right of page

3

page numbers at top left of even-numbered pages, top right of odd-numbered pages

4

page numbers at top right of even-numbered pages, top left of odd-numbered pages

For compatibility, -N is equivalent to -N2 (default: -N0).

+N

Equivalent to -N0 (no page numbering).

-n

Include notes and history from ABC tune `N:' fields.

+n

Omit notes and history from ABC tune `N:' fields (default).

-O name

Define the output file name. By default, the output file name is `Out.ps' for PostScript output and `Outnnn.eps' for EPS output (see -E). If this option is given, the output name will be name or namennn.eps, respectively. If name is `=', the output file name will be the name of the ABC source file with the extension `.ps' or `.eps'. If name is `-', the output is written to stdout.

+O

Revert to the default output file name (`Out.ps' or `Outnnn.eps')

-o

Obsolete option; ignored.

-P

Obsolete option; ignored.

-p

Obsolete option; ignored.

-Q

Print tempo (metronome) indications (default).

+Q

Omit tempo (metronome) indications.

-R

Obsolete option; ignored.

-S

Obsolete option; ignored.

-s scale

Set the page scale factor to scale. Note that the header and footer are not scaled (default: 0.75).

-T

Obsolete option; ignored.

-u

Use implicit decorations as in abc2ps (default: off)

-V

Output version number and quit.

-v

Obsolete option; ignored.

-W vp

Display a tin whistle tablature for the voice numbered v, where v is the internal voice number that is incremented as new voices are encountered; it is not the voice name. p is the base pitch of the tin whistle. Up to four tablatures may be defined, as in `-W1c -W2Bb'.

+W

Don't output tin whistle tablatures (default).

-w length

Adjust the right margin such that the staff width is length (default: none)

-x

Include the `X:' tune number in the title.

+x

Do not include the `X:' tune number in the title (default).

The following formatting parameters can be used in format files. They can also occur in ABC files when they are preceded by %%, or as I: headers (even in the middle of a music line).

aligncomposer int

Define where to display the composer field. A negative value displays it flush-left, a value of zero centered, and a positive value flush-right (default: 1).

annotationfont font [encoding] size

Set the annotation font to font with size size (default: Helvetica 12)

autoclef boolean

Adjust the clefs when they are not defined in `K:' or `V:' lines (default: 1).

barnumbers int

Synonym for measurenb.

barsperstaff int

Try to typeset with int bars per line (default: 0; command line: -b, +b)

beginps

Start a sequence of PostScript code lines extending until the next endps line. This parameter may only occur within ABC and format files, not on the command line.

botmargin length

Set the bottom margin to length (default: 1cm)

bstemdown boolean

If this is set, the stem of the note on the middle of the staff extends downwards. Otherwise it extends up or down depending on the preceding note (default:0).

combinevoices boolean

If this is set, simultaneous notes of the same duration belonging to voices on the same staff are combined into chords (default: 0).

composerfont font [encoding] size

Set the `composer' font to font with size size (default: Times-Italic 14)

composerspace length

Set the vertical space before the composer name to length (Default: 0.2cm)

contbarnb boolean

If this is not set, the bar numbers of second repeats are set to those of the corresponding first repeats. If this is set, all bars are numbered sequentially (default: 0).

continueall boolean

If this is set to true, ignore the line breaks in a tune (default: 0; command line: -c, +c)

dateformat format

Format for date and time output. The admissible values of this parameter are described in the documentation for the strftime(3) C library function. Note that percent signs need to be escaped (default: "%b %e, %Y %H:%M")

deco name c_func ps_func h wl wr [str]

Define a decoration. This is an experimental feature which is subject to change in future releases and requires good knowledge of the internals of abcm2ps. See the files format.txt and deco.abc for details.

dynalign boolean

When set, horizontally align dynamic marks (default: 1)

encoding enc

Set the language encoding to ISO-Latin-enc, where enc can take values from 0 to 6. The value 0 is the same as 1, but no PostScript encoding table is output.

Alternatively, enc may take one of the predefined values us-ascii, iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-9, iso-8859-10, or native (meaning encoding vectors will not be changed). If enc is anything else, it must be a string which is taken to be PostScript commands that set up a suitable encoding vector.

exprabove boolean

Draw expression decorations above the staff. If neither exprabove nor exprbelow are `true', expression decorations are drawn above the staff if there are lyrics on the staff, and below otherwise. exprabove takes precedence over exprbelow (default: 0).

exprbelow boolean

Draw expression decorations below the staff. If neither exprabove nor exprbelow are `true', expression decorations are drawn above the staff if there are lyrics on the staff, and below otherwise. exprabove takes precedence over exprbelow (default: 0).

flatbeams boolean

Draw flat beams in bagpipe tunes (default: 0; command line: -f)

font font [encoding]

Define a font and its encoding. Use this parameter when you want to refer to specific fonts in ABC files/tunes. It must occur before any PostScript output is written, generally in a format file. encoding defaults to the encoding set up by the encoding parameter.

footer text

Define the text printed at the bottom of every page. There may be one or two lines. When there are two lines, these must be separated by the characters `\n' (not a real newline). Each of the lines consists of three areas, left, center and right, which are separated by tabs (real tabs, not '\t') and may be empty - if the left area is empty, the text must be quoted.

The `$' character introduces variable expansion:

$d

The date and time of last modification of the ABC file

$D

The current date and time

$F

The current input file name

$P

The current page number

$P0

The current pagenumber (when even)

$P1

The current pagenumber (when odd)

$T

The current tune title

$V

`abcm2ps-' followed by the program's version number

For example, the command line option -N3 is equivalent to `%%header "$P0 $P1"' (note the two tabs). (Default: none)

footerfont font [encoding] size

Set the footer font to font with size size (default: Times-Roman 12)

format filename

Read the format file filename (default: none).

freegchord boolean

Prevent the characters `#', `b' and `=' to be displayed as the sharp sign, the flat sign, and the natural sign, respectively, in guitar chords. When this flag is set, the display of the accidentals may be forced by escaping the characters (`\#', `\b' and `\=') (default: 0)

gchordbox boolean

Draw a box around guitar chords. Can be set to `true' using `%%gchordfont' below. (Default: 0)

gchordfont font [encoding] size [box]

Set the guitar chord font to font with size size. If box is specified, draw a box around guitar chords (default: Helvetica 12, no box)

graceslurs boolean

Draw slurs on grace notes if true (default: 1; command line: -G, +G)

halfbeam boolean

If true, sequences of 1/32 (or shorter) notes will be beamed in groups, with a single beam leading from one group to the next. The groups will be sized to make up 1/8 note, i.e., 4 1/32 notes or 8 1/64 notes. (default: 1)

header text

Define the text printed at the top of every page. See the footer parameter above for the syntax (default: none)

headerfont font [encoding] size

Set the header font to font with size size (default: Times-Roman 12)

historyfont font [encoding] size

Set the font for history entries to font with size size (default: Times-Roman 16)

hyphencont boolean

If an under-staff lyrics line ends with a hyphen, put another hyphen at the beginning of the next line (default:0)

indent length

Indent the first line of a tune by length (default:0; command line: -I)

infofont font [encoding] size

Set the information line font to font with size size (default: Times-Italic 14)

infoline boolean

Display the rhythm (`R:'), the origin (`O:'), and the area (`A:') of the tune on a single `information line' (default: 0)

infospace length

Set the vertical space before the information line to length (default: 0).

landscape boolean

Set page orientation to landscape if true (default: 0; command line: -l, +l).

leftmargin length

Set the left margin to length (default: 1.8cm; command line: -m)

lineskipfac float

Set the factor for spacing between lines of text to float times the font size (default: 1.1)

maxshrink float

Set how much the output may be compressed horizontally when staff breaks are chosen automatically. float must be between 0 and 1 (default: 0.65; command line: -a)

maxstaffsep length

Set the maximum vertical inter-staff space to length (default: 800pt)

maxsysstaffsep length

Set the maximum vertical system inter-staff space to length (default: 800pt)

measurebox boolean

Draw a box around the measure numbers if true (default: 0; command line: -j or -k).

measurefirst int

Start measure numbering of the tune at int. This parameter is obsolete and should be replaced with %%setbarnb (outside the tune body)

measurefont font [encoding] size [box]

Set the font for measure numbers to font at size size. If [box] is specified, draw a box around the measure number (default: Times-Italic 14, no box).

measurenb int

Draw a measure number every int bars. If int is 0, the measure number appears at the left end of each staff. If int is -1, no measure numbers are displayed at all (default: -1; command line: -j or -k).

musiconly boolean

If true, no lyrics are output (default: 0; command line: -M, +M)

musicspace length

Set the vertical space before the first staff of a tune to length (default: 0.2cm)

notespacingfactor float

Set the note spacing factor to float. This value is used to compute the natural space notes take up. The base space of the crotchet (quarter note) is always 40pt. When the duration of a note type is twice that of another note type, the space it takes up is multiplied by this factor. The default value increases the note space by a factor of 2 when the corresponding note's value increases by a factor of 4. That is, the space of a semibreve is 80pt and that of a semiquaver is 20pt. Setting this value to 1 sets all note spaces to 40pt (default: 1.414).

oneperpage boolean

If true, output one tune per page; if false, multiple tunes are output per page if there is sufficient room (default: 0; command line: -1, +1).

pageheight length

Set the page height to length (default: hardcoded)

pagewidth length

Set the page width to length (default: hardcoded)

parskipfac float

Set the factor for spacing between text paragraphs to float (default: 0.4)

partsbox boolean

Draw a box around the part names if true (default: 0)

partsfont font [encoding] size [box]

Set the font for part names to font with size size. If box is specified, draw a box around the part names. (default: Times-Roman 15)

partsspace length

Set the vertical space before a new part to length (default: 0.3cm).

postscript text

Define a postscript sequence to be included in the header of the output file. This formatting parameter may be used to override any postscript function or to define new functions for use in deco. It should be processed before any output occurs, that is, in a format file or at the beginning of the first ABC file.

printparts boolean

Print the part indications (`P:' header) (default: 1).

printtempo boolean

Print tempo (metronome) indications (`Q:' header) if true (default: 1; command line: -Q, +Q).

pslevel int

Define the PostScript language level for output. Allowable values are 1, 2, or 3.(default: 2).

repeatfont font [encoding] size

Set the font for repeat bracket numbers/texts to font at size size.

rightmargin length

Set the right margin to length (default: 1.8cm)

scale float

Set the global page scale factor to float. This does not apply to headers and footers (default: 0.75; command line: -s).

setdefl boolean

When true, output some indications about the note/chord and/or decorations for purposes of customisation. These indications are stored in the PostScript variable defl. Note: This is a potential compatibility problem. The parameter was introduced in version 4.9.4. (default: 0)

setfont-1 font [encoding] size

setfont-2 font [encoding] size

setfont-3 font [encoding] size

setfont-4 font [encoding] size

Set up alternate fonts for strings. In most strings, you can switch to one of the alternate fonts using $1..$4; $0 switches back to the default value for that string. (default: Times-Roman 0)

shifthnote boolean

Usually in multi-voice tunes, when two voices are in unison and one has a half note and the other a note shorter than a quarter note, there is only one note head (the half note). If this flag is set, both heads are displayed (one is shifted). (default: 0)

slurheight float

Set the slur height factor to float (default: 1.0).

splittune boolean

If false, a tune is output on a new page if it doesn't fit on the one currently being output. If true, a tune may be split across page breaks (default: 0; command line: -0, +0).

squarebreve boolean

If true, display breve notes in a square shape (default: 0)

staffsep length

Set the vertical inter-staff space to length (default: 46pt; command line: -d)

staffwidth length

Set the right margin such that the staff width is length (default: none - but see paperwidth and rightmargin).

stemheight float

Set the stem height to float (default: 20.0)

straightflags boolean

If true, use straight flags on stems in bagpipe tunes (default: 0)

stretchlast boolean

If true, stretch the last staff of a tune to fill the whole line even though it may be underfull (default: 0)

stretchstaff boolean

If true, stretch all underfull staves to fill the whole line (default: 1)

subtitlefont font [encoding] size

Set the font for subtitles (second and subsequent `T:' headers in a tune) to font with size size (default: Times-Roman 16)

subtitlespace length

Set the vertical space before subtitles (second and subsequent `T:' headers in a tune) to length (default: 0.1cm).

sysstaffsep length

Set the vertical system interstaff space to length (default: 36pt).

tempofont font [encoding] size

Set the font for tempo (metronome) indications to font with size size (default: Times-Bold 15)

textfont font [encoding] size

Set the text font to font with size size (default: Times-Roman 16)

textoption int

Set the default text option to int. This option is used for text between %%begintext and %%endtext. int may be a keyword; see begintext for values.

textspace length

Set the vertical space before text blocks to length (default: 0.5cm).

titlecaps boolean

If true, output the tune title in uppercase letters (default: 0)

titlefont font [encoding] size

Set the title font to font with size size (default: Times-Roman 20)

titleleft boolean

If true, output the tune title flush left (instead of centered) (default: 0)

titlespace length

Set the vertical space before the tune title to length (default: 0.2cm).

topmargin length

Set the top margin to length (default: 1cm)

topspace length

Set the vertical space at the top of a tune to length (default: 0.8cm)

tuplets when what value

Define how to draw tuplets. The when parameter can be 0 (to decide automatically whether to draw a slur or bracket over the tuplet), 1 (to never draw one) or 2 (to always draw one). The what parameter defines what to draw: 0 means a bracket, 1 a slur; 2 extends beams across rests (does not work yet). The value parameter defines how to annotate the tuplet: 0 means to write a simple number (p), 1 writes nothing, and 2 writes a ratio (p:q).

vocalabove boolean

If true, output lyrics above the staff (instead of below it) (default: 0.8cm)

vocalfont font [encoding] size

Set the font for lyrics inside a tune to font with size size (default: Times-Bold 13)

vocalspace length

Set the vertical space between a staff and its lyrics to length (default: 23pt)

voicefont font [encoding] size

Set the font for voice names (default: Times-Bold 13).

withxrefs boolean

If true, print the number from the `X:' header in the tune title (default: 0; command line: -x, +x)

wordsfont font [encoding] size

Set the font for lyrics at the end of a tune to font with size size (default: Times-Roman 16)

wordsspace length

Set the vertical space before the end-of-tune lyrics to length (default: 0.5cm)

writehistory boolean

If true, output notes and history (`N:' and `H:' headers) (default: 0; command line: -n, +n)

The following formatting parameters can only occur inside tunes and not in a format file:

%%begintext [mode]

Start printing a free-form text. The text to be printed appears on the subsequent lines of the the input file up to a line containing %%endtext. The text lines may start with %%.

The parameter may be:

obeylines

Line breaks in the input file are kept (default)

align or justify

Lines are justified

ragged or fill

Line breaks are ignored but output is left-justified

center

Lines are centered

skip

The text lines are not printed at all

%%center text

Print one line of centered text

%%EPS filename

Include filename as an EPS file

%%endtext

Finish a block of free text started by %%begintext

%%multicol command

Define multicolumn printing. command may be:

start

Save the current vertical position and left and right margins. These margins may then be changed to print music or text.

new

Reset the vertical position to the place of the previous start and restore the left and right margins. These can then be changed again to display another column.

end

Restore the left and right margins and skip down the page to a `safe place'.

%%newpage [int]

Start a new page, restarting page numbering from int if applicable.

%%repbra int

Repetition brackets are normally displayed as written in a voice. %%repbra 0 suppresses them for the current voice.

%%sep [h1 h2 length]

Print a separator (line) of length length with vertical space h1 above and h2 below (defaults: h1 and h2: 0.5cm; length: 3cm)

%%setbarnb int

Set the measure number to int. When not inside a tune body, this is equivalent to %%measurefirst.

%%staff num

Put the following material on staff num. This will lead, e.g., to beams between notes in different staves. Useful for keyboard music; see, for example, sample4.abc.

%%staffbreak length

Leave a space of length in the current staff. If length is greater than 0.5cm, the left side of the staff (system) is redrawn. In a multi-voice tune, a staff break must be specified in each voice.

%%staves definition

See below.

%%text text

Output a single line of text.

%%vskip length

Leave vertical space of height length

Clefs

[clef=]type[line][+8|-8] [middle=pitch]          

Multi-voice typesetting

V:name definition ... 
 

Voice overlay

|F2A2Bc&F2c2bc| 
 

|!f!(&GG<G|GG F=E| E2  E(_D/E)|_D D  C      D |C4- |C 
     &DC<C|CC_D C|=B,2_B,B,   |_A,A,(G,/A,/)B,|F,4-|F,)zzD=E| 
 

Lyrics

edc2 edc2| 
w:Three blind mice, three blind mice 
 

Slurs and ties

Microtone pitches

EPS inclusion

The original documentation can be found in files features.txt, format.txt, and options.txt, which on a Debian system are in /usr/share/doc/abcm2ps.

This manual page was written by Anselm Lingnau <lingnau@debian.org> for the Debian system (but may be used by others). Permission is granted to copy, distribute and/or modify this document as long as its origin is not misrepresented.