Muscript 3.4

Muscript is a language for typesetting music, and either a Lua script, or a Perl script, which translates this language either into PostScript, or into Encapsulated PostScript, or into MIDI, or into MusicXML, and there is a script muscriptps2svg to translate muscript into SVG.
Muscript was written by Peter Billam to typeset his own compositions and arrangements; it started life as an awk script, and was announced to the world in 1996.
The current versions of muscript are 3.4h (Lua), and 3.4f (Perl)

This page describes the text input syntax: boundingbox, systems, barlines, new bar, staves, clefs, keysigs, timesigs, rhythms, rests, notes, pitches, accidentals, stems, beams, ties and slurs, note-options, chords, words, MIDI, comments and variables

It ends with details of how to download and install muscript, on page size issues, some tools for manipulating muscript files; then after a history of changes and a list of proposed enhancements, there are some pointers to some of the other free music-typesetting software. In a separate directory, there are some samples available to get you started with muscript syntax.

Usage

muscript filename > filename.ps     (generates PostScript)
muscript filename | lpr             (direct to the printer)
muscript foo | gs -q -sDEVICE=pdfwrite -sOutputFile=foo.pdf - (generates PDF)
muscript -letter foo > foo.ps       (US Letter pagesize)
muscript -midi foo > foo.mid        (generates MIDI output)
muscript -xml foo > foo.xml         (generates MusicXML output)
musicxml2ly foo.xml                 (generates LilyPond)
muscript -pp foo > foo_expanded     (runs variables through the PreProcessor)
muscript -v                         (version information)
muscript -h                         (helpful list of calling options)

Text Input Syntax

The muscript language is designed, in the spirit of eqn and pic, to reflect the way one musician might describe a score in detail over the phone to another musician. The language is quite compact, and a page of music can be described in not much more than a page of ascii text. In fact with a little practice a musician can sight-read the score in its muscript form.

Muscript text input consists of a number of commands, mostly on separate lines. The Backslash \ as last character on a line will continue the command on the next line.

Describing a page of music in muscript corresponds to the way you'd write the page; so first you draw the staves, then on each stave you draw the barlines, then for each bar you fill in the clefs, notes, etc.

Each page consists of several systems, each of which consists of one or more bars, each of which consists of one or more staves, each of which contains one or more notes or words.

BoundingBox

If the very first line in the file is e.g.:
boundingbox 65 53
then muscript will generate output in Encapsulated PostScript (EPS) format, 65 points wide and 53 points high in this example. This EPS output can then be inserted into word-processor or desktop-publishing documents, or it can be converted into JPG or PNG format and used in web pages. See the eps2img script, and the kdf.txt file in the samples.

Systems

The first line on each page draws the systems of staves. For example, a typical piece for flute, 'cello, etc might be:
12 systems /20/20/20/20/20/20/20/20/20/20/20/20/

The numbers between slashes are the height of each stave, in point. Or a typical piece for piano might be
6 systems /20-40-20/20-40-20/20-40-20/20-40-20/20-40-20/20-40-20/

The intermediate numbers (40 here) are the height of the gaps between the staves. The dashes cause barlines to join between the staves. So the piano part of a violin sonata might be:
4 systems /14 30 20-40-20/14 30 20-35-20/14 30 20-40-20/14 30 20-42-20/

A trailing gap in a system is respected, and can be used to reserve space, for example for low stem-down notes on multiple ledger lines. A top gap, to be reserved above the first system, is indicated by a number before the first slash, e.g.
2 systems 80 / 13 30 19-40-19 / 13 30 19-40-19 30/

If there are fewer systems specified than needed, then muscript repeats the last one as necessary. For example, twelve single-stave systems can be written:
12 systems / 19 /

Titles

Titles use a title Blurb Blurb syntax, and are printed in big bold font, centered at the top of the page.

Page numbers

Page numbers use a pagenum 7 syntax. They are printed in the top outer corner; that is, odd page numbers print in the top right corner, even page numbers in the top left. If a number is not specified (e.g. pagenum ) then the number will auto-increment from the previous page number.

Headers

Headers use a innerhead Blurb blub syntax. These are printed in small italic font in the the inner top corner - the opposite top corner from the page-number. If there is no page-number on the current page, you can use the explicit lefthead and righthead commands. If high notes on the top stave get mixed up with the headers and titles, then put a gap ahead of the top system, as in the next example.

Footers

Left Footers, using a leftfoot Blurb blub syntax, are printed in small italic font in the bottom left corner. Right Footers use a rightfoot Blurb blub syntax, and are printed in small italic in the bottom right corner. If low notes on the bottom stave of the bottom system are getting mixed up with the footers, then put a trailing gap into the lowest system, e.g.

6 systems 12/19-30-19/19-35-19/19-33-19/19-30-19/19-30-19/19-33-19 15/
title Squishy Macaroons
pagenum 1
innerhead Kylie Bloggs, 2003
rightfoot Typeset by Gina Bloggs, 2005
midi channe1 1 patch 3

These systems specifications are persistent, so if muscript runs off the end of a page, it reuses the previous specification for the new page (except that it increments the page number, and it doesn't reprint a title but prepends the title to the innerheader).

Then, once the systems have been set up, the simple command
/

causes muscript to start typesetting the bars of the next system.

Bar-Lines

After the / command, the first thing is to draw the barlines. For this, muscript has to know how many bars, and how they are spaced. For example, for four bars:
4 bars | 1 | 1.2 | 1 | 1 |

Here the numbers between the | lines are the proportions of the bar lengths. In the above example, the second bar obviously needs a bit more space than the others. If just one part of a bar needs stretching (perhaps because it has a lot of semiquavers) then you put more than one number in the bar. For example, if there are five bars, but the second quarter of the fourth bar needs more space, you could use:
5 bars | 2 | 2 | 2 | 0.5 0.7 0.5 0.5 | 2 |

These barline specifications are persistent, so if muscript runs off the end of a system, it reuses the previous specification for the new system.

When muscript works out the proportions, it reserves extra space automatically for a clef at the beginning of the line. You can also reserve space for time signatures and key signatures at the beginning of a line (note that this reserves space, but does not draw anything; they will be drawn later). For example:
4 bars | 3b 4/4 1 | 1.2 | 1 | 1 |

Double-bars are indicated || and repeat marks with :
5 bars | 10 | 9 :|| 11 | 10 | 9 ||

A Segno sign (to be used by a later "Dal Segno" instruction) is indicated with Segno
5 bars | 10 :|| Segno 3b 4/4 11 | 10 | 9 |

If there are fewer proportion-numbers than bars needed, then muscript repeats the last one as necessary. For example, eleven evenly-spaced bars can be written:
11 bars | 2# 6/8 12 | 12 |

As from version 2.7g, the last barline can be ommitted. This can be used for bar-less music, for example:
1 bars | 50
or to split a bar between two systems:
3 bars ||: 16 | 16 | 8

New Bar

Then, once the barlines have been set up, the simple command
|

causes muscript to start typesetting the next bar within the current system. As from version 2.3, the | can also be followed by numbers to tell MIDI about the tempo within the bar; see the MIDI section below.

Back to the top or to the samples. . .

Staves

After the | command, you fill in the staves (of the current bar) one by one. The first (or only) stave is =1 and the second is =2 etc. These numbers can be followed with a , or a ' to set a default stem direction; this is very useful if two voices share one stave, one tail-up and one tail-down. For example, a piano piece might begin 

|
=1' bass 4b 2/4 4 c~ b
=1,      4b 2/4 16 [a e a e] [g e g e]
=2' bass 4b 2/4 4 A d

Clefs and Key Signatures are persistent, within a given stave-number. Muscript remembers them from bar to bar, and reprints them automatically at the beginning of each new system.

Clefs

The principal clefs are treble, alto, tenor and bass. Also available are treble8va, treble8vab, and bass8va, bass8vab, which put a small "8" above or below the clef to indicate instruments that transpose by one octave. Since version 3.3k, also available is percussion, for untuned persussion.
Clefs can occur within a bar, as well as at the beginning.

The null clef clefspace prints nothing, but reserves one clef's-width of space; this can be useful for lining up the other parts when a clef change occurs in one part. As you can see from the above example, clefspace is unnecessary at the beginning of a line; muscript reckons there's always a clef there, so it reserves space anyway.

Key Signatures

The are written simply as   1# ,   3b ,   4#   etc. The special key signature 0 means "return to Cmaj", and will print the natural signs necessary to cancel any previous key signature. A key signature can only occur at the beginning of a bar, and before the time signature (if any).

Time Signatures

The are written simply as fractions, for example   2/4,   6/8,   12/8,   etc. A time signature can only occur at the beginning of a bar, and after the key signature (if any).

Then we can start writing the rhythms and notes (and in-stave MIDI instructions).

Rhythms

The rhythms are written either in abbreviated English syntax, or in a numeric, International syntax.
The breve (de: doppelte Taktnote) is written bre in both syntaxes:

 
English syntax  bre   smb   min   cro   qua   smq   dsq   hds 
International syntax   bre 1 2 4 8 16 32 64

Triplet notes are written with a three; e.g.  qua3  or  83
Duplet notes are written with a two; e.g.  cro2  or  42  (two duplet crotchets last three normal quavers)
Quadruplets are written with a four; e.g.  qua4  or  84  (four quadruplet quavers last three normal quavers)
Quintuplets are written with a five; e.g.  smq5  or  165  (five quintuplet semiquavers last one normal crotchet)
Septuplets are written with a seven; e.g.  smq7  or  167  (seven septuplet semiquavers last one normal crotchet)
Dotted notes are written with a dot; e.g.  min.  or  2.  or  qua3.  or  83.
Double-dotted notes are written with two dots; e.g.  min..  or  2..
Tremolandi have a  /  or  // or /// suffix; e.g. a dotted whole-note divided into semiquavers is  smb.//  or  1.//
and a quaver divided into semiquavers is   qua/   or   8/
Tremolando minims (half-notes) joined by a beam form a "Brille-Bass" eg:   2// [F A]
Small notes (e.g. ornaments) have a  -s  option at the end; e.g.  smq-s  or 16-s  or  qua3.-s  or  163.-s
Cross-head notes (as also used in percussion clefs) have a  -x  option at the end; e.g.  8-x  or  83.-x
Small cross-head notes have a  -sx  option at the end; e.g.  8-sx  or  83.-sx

A rhythm remains valid for all notes and rests in that stave, until changed.

Rests and Blanks

A rest in the centre of the stave is written rest
It can be moved to the top line by rest' or further by rest'' or rest''' etc.,
or to the bottom line by rest, or further by rest,, or rest,,, etc..

A blank space on a stave is written blank

Back to the top or to the samples. . .

Notes

  1. A note begins with the start of a beam, if any
  2. then the start of a chord, if any
  3. then the pitch including any accidental
  4. then any instructions to cross the note to the other side of the stem, or shift the note rightwards, or shift the accidental leftwards, or to override the default stem-direction
  5. then the starts or finishes of any ties or slurs
  6. then a dash-separated list of any options
  7. then the end of a chord, if any
  8. and finally the end of a beam, if any.

Beams

By default, Quavers, Semiquavers and Demisemiquavers get tails. For example:
8 F 16 A G       [qua_tails.gif]

You can start a beam with a [ character right at the beginning of the note-string, or end it with a ] character right at the end. On each stave, muscript keeps track of two beams, one for stem-up notes, and one for stem-down; so make sure that all the notes you wish to be joined by the same beam have the same stem-direction. For example:
8 [F 16 A G] [qua_beams.gif]

Similarly, by default, a tremolando minim gets little tremolando-marks crossing its stem. You can start a beam with a [ or end it with a ] as above, and this joins up two tremolando minims to form a Brille-Bass. For example:
2// G [F A] [min_beams.jpg]

Chords

Simultaneous notes are expressed with angle brackets, for example:
2 <C Eb G c'> [min_chord.jpg]     or:     8 [<E G> <F A>] [qua_chord.jpg]

Pitches

Near the middle of each clef there is a "c". This note is written c, and the notes above it are written c# d eb en f f# g g# a bb b c~ c~# d~ e~b and so on up to b~ and then further with c~~ up to f~~#. Likewise, the notes below c are B Bb A Ab G F# F E Eb D C# C B_ B_b A_ and so on down to C_ and then further with B__ and A__. Thus on each clef you can write a range of nearly five octaves without "8va" signs.

Accidentals

Flats, sharps, naturals, double-flats and double-sharps are written b, #, n, bb and ## after the note, just like they're pronounced. Where there are accidentals and octave sign on the same note, the octave sign must be first, e.g. A_b

Crossing the note over to the other side of the stem

In chords with neighbouring tones on one stem, one note-blob has to be moved across to the other side of the note-stem. This is done with an x
For example: 2 <C Dx G> [x_chord.gif]

Semibreves have no note-stems, and the x always shifts them rightwards.

Shifting the note (or chord) rightwards, or the accidental leftwards

If one note neighbours a note in a different voice, one of them has to be shifted rightwards, together with its stem. (So if the note forms part of a chord, the whole chord gets shifted rightwards.) This is done with an r. For example:

=1' 4 rest c# d
=1, 4 blank 2 <G Br>
 

If neighbouring tones both have accidentals, it improves clarity to shift the accidentals leftwards. This is done with an l, for example:

=1' 4 rest c#l d
=1, 4 blank 2 <Gr Bbl>
 

Overriding the Default Stem Direction

By default, stems go up if the note is below the centre line; otherwise they go down. This default can be changed to all-up or all-down by the stave command, e.g. =1' or =1,  Stems on individual notes can be forced up with a ' or down with a , after the note: for example 8 A, B c d 16 c' B' A G#

Ties and Slurs

Ties unite two notes of the same pitch into one longer note; they are written with brackets ( ).
Slurs associate a sequence of notes into one melodic phrase, generally played legato; they are written with curlie-braces { }
Ties and slurs are printed the same, but are handled differently by MIDI.

Ties above the note are started with (1 or (3 or (5 or (7 or (9 and finished at a later note in the same stave with )1 or )3 or )5 or )7 or )9 respectively.
Ties below the note are started with (2 or (4 or (6 or (8 and finished at a later note in the same stave with )2 or )4 or )6 or )8 respectively.

Slurs above the note are started with {1 or {3 or {5 or {7 or {9 and finished at a later note in the same stave with }1 or }3 or }5 or }7 or }9 respectively.
Slurs below the note are started with {2 or {4 or {6 or {8 and finished at a later note in the same stave with }2 or }4 or }6 or }8 respectively.

By default, ties and slurs end close to the note-blob. If you want one to end higher, at the top of an upward stem, then insert one or more ' between the bracket and the number. Or if you want one to end lower, beneath a downward stem, then insert one or more , between the bracket and the number. For example: 

|
=1' treble 5/8 8 rest' [d{'1 f(3] [f)3 d}'1]
=1, treble 5/8 4. G(2 4 G)2
|
=1 bass b{1-. d-. G-., C}'1-.,

Ties which are ended without having being begun are deemed to begin at the nearest double-bar, or at the start of the line if there's no double-bar in the way. This copes with a note being tied into a second-time-bar.

Note Options

Options attaching to a note appear, separated by -'s, after any ties or slurs, and just before any end-chord or end-beam sign. For example:
4 rest B-. 2 c(1-tr-fermata 43 c)1 B-I3 A

The available options are: blank (or the empty string, see below), creNN (crescendo, see below), down (), emph (emphasis, ), fermata (), the guitar-string options gs1 (  ) to gs6 (  ), mordent (), P or * (pedal, see below), stacc or . (staccato), tr (trill), turn (), ten (tenuto), up (), and the text options rSomeText, bSomeBoldText, iSomeItalicText, ISomeBoldItalicText, rsSomeRegularSmallText, bsSomeBoldSmallText, isSomeItalicSmallText and IsSomeBoldItalicSmallText.

Text to be printed can be protected by double-quotes, e.g.   -I"sf"   or   -s"3 - 4"

Trills with a flat, natural, or sharpened upper note are expressed by trb, trn or tr#

Multiple options on the same note are printed in order, starting close to the stave and moving away. The blank option does not print anything, but just leaves a gap where the option would have been printed; this can be used to avoid options colliding with things like slurs. An empty option works the same as a blank option, so that A-blank-blank-s4 can also be written as A---s4

Options are, by default, printed above the stave. They can be printed below the stave by appending a comma (,) to the individual option, e.g.
4 B,-., 2 c,(1-tr-fermata,

Crescendo and diminuendo within a note can be produced with the -cre and -dim options. Currently these do not affect the printed output; they adjust MIDI's expression controller on the note's MIDI-channel, The expression parameter (cc11) starts each note at a level of 100, and can be varied from 0 to 127. For example,   2. c-cre20   produces a moderate crescendo, or   2. c-cre20-dim30   produces a crescendo for the first half of the note, followed by a slightly stronger diminuendo in the second half. You can use the number 0, for example:   2. c-dim0-dim20   produces a note which fades away during its second half.

The piano sustain-pedal is taken, or retaken, with the -P option, and released with the -* option, the sostenuto-pedal is taken, or retaken, with the -Sos option, and released with -*Sos and the Una-Corda-pedal is taken with the -Una and released with -Tre

Back to the note-syntax, or to the top, or to the samples. . .

Words

Words can be printed above the top stave in the bar, or in the gaps between staves, or beneath the bottom stave.

Font: The first bit of the command is a letter or two; r means regular font, i means italic font, b means bold font, I (uppercase i) means bold italic font; and these can be followed by an optional s which means small, or l (lowercase L) which means large. These font sizes are relative; they are scaled according to the average stave height in the current system.

ISO-8859-1 character encoding is respected, so that e.g. octal 374 is printed as Ü (U-umlaut).
UTF-8 character encoding is also respected, but only for characters within the ISO-8859-1 character-set (due to a PostScript limitation) and also for œ which is mapped to oe

Vertical Spacing: These letters can then be followed immediately (no space !) with a decimal number which determines the vertical position of the words as a proportion of the stave gap. The next space is a separator, and the rest of the command is the text to be printed.

Horizontal Spacing of text is mostly done by numbers beginning with a decimal point and followed by one, two or three digits. These numbers are treated as reserved words within the text strings, and they space the following text to start at that proportion of the bar's width. Multiple spaces between text-words, or before the first word, are displayed as such, and this can be used for small spacings, as in "Freu  -" or in "bl1.1   First"

Indicating Tempos:   Since 3.3o, you can include notes (unpitched, but with duration) in the text. The duration is introduced with a backslash and ends at the next space. For example, \8. = 144 appears as:

Examples: 

r0.5 .01 Drink .33 to .67 me    ( Regular font, good for song words )
r0.5 .01 Freu  - .25 de .5 schö   - .75 ne    ( iso-8859-1 or utf-8 )
I0.9 .97 ff                   ( Bold Italic font, good for dynamics )
i0.05 .62 rallentando            ( Italic font, good for expression )
is0.8 .10 Fred Bloggs, Symphony No. 10, 5th Mvt.    ( small italics )
bl1.1   First Movement           ( bold large font, good for titles )
r0.7   approximately \4 = 88                              ( Andante )

Back to the top or to the sample. . .

MIDI

Within muscript, there are three types of MIDI commands: Global commands which affect all staves, the New-Bar command which governs the tempo, and In-A-Stave commands which affect just one stave (like either =1 or =2).
Also MIDI-related are the -cre and -dim note-options, which do changes of dynamic within the note.

Global MIDI Commands

Trailing comments can be introduced by a # character, and will be ignored by muscript.

There are commands that apply to a specific channel:
    channel, bank, patch, vibrato, rate, delay, pan, reverb, chorus, transpose
and system-wide commands that apply to all channels:
    gm, cents, temperament, barlines, pause, off, on

midi channel 2 bank 87,65 patch 56
This instructs the synthesiser to select Bank MSB=87 LSB=65, and to assign its Patch 56 to MIDI channel 2. The word "Patch" is MIDI-speak for a particular instrumental sound. This command would usually come near the top of the muscript file.
The channel-number can be anything from 0 to 15 (except 9 is reserved in General-MIDI).
The patch-number can be anything from 0 to 127.
The bank-number is in two parts, separated by a comma (no spaces!). The first part is the MSB (most-significant-byte) and the second is the LSB (least-significant-byte); either byte can be anything from 0 to 127. Since version 3.1g the LSB can be omitted (many synths ignore it anyway). It only makes sense to specify the bank if your synth is in Patch mode (in fact, specifying a bank may force your synth into its Patch mode) see below:
  • Usually your synthesiser will be in General-MIDI mode; the General-MIDI standard defines particular numbers for common instruments, like 0 is a grand piano, 25 a steel-string acoustic guitar, 65 an alto saxophone, etc; General-MIDI channel 9 is reserved for percussion sounds.
  • If your synth is in Patch mode, then you should set it up to listen on some particular Channel (be aware that your synth may number the Channels 1-16). Then muscript will only be able to use that Channel and you will only be able to play one Patch at once; "Patch mode" is not "multi-timbral" :-(
  • If your synth is in Performance mode, hopefully you have already selected a Performance and configured its various Channels (or "Parts")... Consult your synth manual for details.
midi channel 2 vibrato 60 rate 40 delay 70
This asks the synth to adjust the Vibrato parameters on Channel 2. In all these numbers, 50 represents the default vibrato settings of this Patch, 100 represents the maximum, and 0 the minimum. For note-by-note changes to the vibrato depth there is a corresponding In-Stave command.
midi channel 5 pan 80 reverb 45 chorus 90
This asks the synth to Pan Channel-5 80% over towards the right speaker, to add moderate (45%) Reverb, and to add a heavy (90%) Chorus effect.
The pan-number can be anything from 0 (full left) to 100 (full right). For note-by-note changes there is a corresponding In-Stave command.
The reverb-number can be from 0 (dry) through 50 (default) to 100 (reverberant as possible).
The chorus-number can be from 0 to 100.
midi channel 5 patch 73 transpose 12
This will transpose all notes on channel 5 up one octave (twelve semitones).
For note-by-note changes governing all notes on a particular stave, there is a corresponding In-Stave command.
midi gm 2
This forces the synth into General-MIDI mode (see above), General-MIDI-2 in this example. Other possible values are gm 1 for General-MIDI-1, or gm off which puts the synth into one of its non-General-MIDI modes, see your synth manual for more details.
The gm 1 and gm 2 commands are incompatible with the bank command above.
See: wikipedia's Comparison of MIDI standards.
midi pause 3.9
This inserts a pause in the output, of 3.9 seconds in this example, such as you might use to separate two movements, or two songs. Small pauses, such as .02 or .04 seconds, can be used as an expressive device between bars, like the luftpause in classical music. This command is only useful between bars, not between different staves in the same bar.
midi cents -100 temperament kirnberger
This command sets up the tuning and temperament, to A=415 and Kirnberger temperament in this example (a typical choice for baroque music).
cents can, since version 3.1u, be any number; for example, -100 means a semitone down (A=415), +250 means two-and-a-half semitones up.
cents is a global command (it invokes the GM2 Master Fine Tuning and Master Coarse Tuning sysexes) and applies to all channels.
The temperament can be either equal (the default, in which the missing comma is shared by all twelve fifths), or vanbiezen (the missing comma is shared among six of the fifths F-C-G-D-A-E-B), or kirnberger (the comma is shared among the four fifths C-G-D-A-E, and C-E is perfect)
midi barlines on   and   midi barlines off
If barlines are turned on, then marker-events are inserted into the MIDI output, to mark the barlines.
midi off   and   midi on
These commands switch midi output off and on, and are useful for suppressing first-time bars, or for proofreading while typing a piece in (so as not to have to listen to the whole piece every time you save and make).

MIDI New-Bar Commands

The new-bar command | is the place to tell MIDI about tempo. First comes a time signature (this is just MIDI's understanding of the time signature; it doesn't get printed) and then comes the length of the bar in seconds. For example, the new-bar command for a piece in 4/4 time at 120 beats/min could be:
| 4/4 2.0

As in the bars command, we can specify the lengths of parts of the bar. For example, if we wanted a ritardando we might use:
| 4/4 0.5 0.54 0.6 0.68

This can also be used to generate swung quavers in jazz, or inégale quavers in Baroque music or in Irish music, or for Viennese waltzes. For example, an Irish Jig might begin:
| 6/8 .19 .14 .17 .19 .14 .17
=1' treble 2# 6/8 8 [A B A] [A F D]

Upbeats, or in general bars of varying lengths, have to be given their own ad-hoc lengths. For example:
| 1/4 .55
=1 bass 2b 4 F
| 4/4 2.2
=1 2 B 4 A B

As an alternative to seconds, you can also specify a tempo, in beats per minute. Muscript decides what a "beat" means by consulting its time-signature. In 2/4 or 3/4 or anything/4 then a beat is a crotchet, and in 2/2 or 3/2 or anything/2 then a beat is a minim. But in 3/8 or 6/8 or 9/8 etc. the beat is a dotted crotchet, whereas in 2/8 or 4/8 or 5/8 or 7/8 etc. the beat is a quaver. Similarly for 3/16 or 6/16 or 9/16. (Muscript still needs to know the timesignature, so you still have respecify bars when their length varies.)

This tempo information is persistent; muscript remembers it from bar to bar, and re-applies it automatically.

In-A-Stave MIDI Commands

These are all one-word commands (no spaces!) that can intermix with notes and rhythms in a stave line. They change settings for that particular stave (like =1 or =2). They take effect immediately, and remain in force on that same stave in subsequent bars. All these commands can be abbreviated to their first three letters.

cha2   or   cha3+5
This sets the midi channel, to 2 in the first example.
General-MIDI channel 9 is reserved for a "rhythm-set", i.e. drumkits, percussion, etc; if it's any other channel number, hopefully you have already assigned a patch to it.
If your synth is in "Patch mode" this command must specify the same Channel that the synth is listening to, see Patch mode above.
Since 3.1v, a single stave can emit notes on multiple channels, to channels 3 and 5 in the second example. This allows automatic doubling of different patches on the one stave. In conjunction with the transpose global-midi option, it also allows doubling at the octave, eg: cello doubled by contrabass an octave down, or violin doubled by flute an octave above.
tra-2
This causes notes to be generated 2 semitones lower than notated, which is what you might use on a stave for a trumpet in Bb. For a piccolo you might use tra+12 (unless you've already given it a treble8va clef).
vol73   or   vol+10   or   vol-10
This sets the volume, in a range from 0 to 127 (the default volume is 100).
Also allowed are incremental volume changes, such as vol+10 or vol-5
The G-emph note-option works the same as vol+10 G vol-10 except that the note-option gets printed as part of the score, whereas the vol command does not get printed, it is part of the interpretation. The vol command uses MIDI's velocity parameter to set the starting-volume; changes of dynamic within the note are done with the -cre and -dim note-options, which use MIDI's expression controller.
leg99
This sets the legato, to 99 in this example. leg100 produces a full legato; you can actually go beyond 100, producing an over-legato. The default legato is 85, a sort of medium-détaché. The -stacc note-option decreases a note's legato by about half.
vib80
This sets the vibrato depth, to 80 or 50 in these examples. As above in the Global MIDI section, 50 represents the default vibrato depth setting of this Patch, and 100 represents the maximum possible.
pan73   or   pan+10   or   pan-10
This pans the channel. As in the Global MIDI section, the pan can range from 0 (left) through 50 (centre) to 100 (right), but here incremental changes are also allowed, e.g. pan+10 or pan-5
bend73   or   bend+1   or   bend-10
This pitch-bends the channel, using the MIDI pitch_wheel command. The bend can range from 0 (by default 2 semitones down) through 50 (normal tuning) to 100 (by default 2 semitones up). Incremental changes are also allowed, e.g. bend+2 or bend-1
cc73=108
This sets any of the MIDI Control-Change parameters; in this example Controller 73 (attack-time) is set to 108 (0..127). Be aware that the actual effect that these CC parameters have on the sound is often quite synthesiser-dependent.
slide-11-2-110
Introduced in 3.3w, this is unlike the other In-A-Stave MIDI commands in that it has a duration, just like a note has. It imitates the movement of a slider on a synthesiser. In this example, Controller 11 will slide evenly from 2 to 110 during the duration.
It is neatest to give the slide commands their own stave line, for example:
    midi channel 0 patch 60
    | 6.0
    =1 cha0 leg109 2 <G(2 B c#> 1 <G)2 Bb d>
    =1 1 slide-11-15-110 2 slide-11-110-15

Back to the top or to the samples. . .

Comments

Any line beginning with % is treated as a comment, and will appear as a comment in the PostScript output. In -midi mode it appears as a MIDI "marker" event at the start of the current bar.

Since version 3.1h, two mode-dependent, conditional comments are introduced. Any line beginning with #P is ignored as a comment except in PostScript-mode, when it just gets those two characters stripped of and is treated as a normal line. Likewise, any line beginning with #M is ignored as a comment except in MIDI-mode, when it gets those two characters stripped of and is treated as a normal line. This allows a line to be given a PostScript-version to be printed in the score, and a MIDI-version (e.g. ornamented) to be performed.

Otherwise, any line beginning with # is treated as a comment, and ignored completely.

Page Size

Output can be generated for various page sizes:

muscript -a4 foo > foo.ps          ( A4, the default )
muscript -letter foo > foo.ps      ( US Letter )
muscript -compromise foo > foo.ps  ( A4 width, Letter height )
muscript -auto foo > foo.ps        ( autodetect A4 and Letter )

Auto only works as long as the output remains in PostScript form; if it is translated into PDF the autodetect power is lost and the page size becomes fixed by the translation process. Therefore, if you want to generate PDF to publish scores globally, you should use the -compromise option. See also the a42us utility script.

Back to the top . . .

Download

As from version 3.2h, muscript is available in two implementations, one in Lua, and the original one in Perl. But the Perl version will not run on Perl 5.32 or later, and also the Lua version runs more than twice as fast.

The version of muscript for Lua needs Lua 5.2 or greater, and is available by http at muscript_lua.
To install it, save it to disc, rename it muscript and move it into your $PATH, make it executable, and if necessary edit the first line to reflect where Lua 5.2 or 5.3 is installed on your system.
You'll also need to install the MIDI.lua module
( see pjb.com.au/comp/lua/MIDI.html or peterbillam.gitlab.io/pjb_lua/lua/MIDI.html )
by :     luarocks install midi

The version of muscript for Perl has just been re-written to run on Perl 5.32 or later, though it is not yet fully tested. It is available by http at muscript_pl. To install it, save it to disc, move it into your $PATH, make it executable, and if necessary edit the first line to reflect where perl is installed on your system.
You'll also need to install the MIDI and the Text::ParseWords modules from cpan.org

All these files are now on gitlab and can be downloaded by:
  git clone https://gitlab.com/peterbillam/muscript

Tools

Various tools exist to manipulate muscript input and PostScript output and MIDI output. To install one of the scripts, move it into your $PATH, make it executable, and if necessary edit the first line to reflect where perl is installed on your system.

Tools for handling muscript input:
8va
This simple filter transposes up or down the octave. For example, in vi, !!8va raises the current bar one octave, or !!8vab lowers the current bar one octave.
8vab
This transposes down the octave. (It is the same file as 8va; its behaviour changes according to the name under which it is invoked.)
transpose
This filter transposes up or down a given number of semitones. It now handles keysignatures, and persistence of accidentals within a bar. E.g. this would transpose its input up seven semitones:
transpose +7
There is a -k option to force a keysignature onto the input. E.g. in vi, this would transpose the current line down 3 semitones, considering it to have a 4-flats keysig even if that's not explicit in the current line (i.e. if it was set earlier in the file):
!!transpose -3 -k 4b
There is also a -a option which generates output without a keysig, using accidentals only, e.g: !!transpose +2 -a
There is also a -s option to transpose only one stave. E.g. this might convert a piece for flute and piano, into a piece for Bb-clarinet and piano:
transpose +2 -s 1
tempo
This filter changes the midi tempo of a muscript file by a fixed proportion. It has no effect on the PostScript output. For example, tempo 1.05 speeds a piece up by 5 percent. Or, tempo 0.95 makes a piece 5 percent slower. E.g. to generate multiple practice-versions of a piece, with different tempi: 
for t in 0.73 0.81 0.90 1.00 ; do 
   tempo $t a_piece | muscript -midi > a_piece_$t.mid
done
4hands2score
This converts muscript for piano-four-hands (i.e. with one player reading the left-hand page and the other reading the right-hand page) into a single score, for example for feeding into muscript -midi for proofreading.
 
muscript2video
This converts muscript into an .avi video ready for uploading into youtube. You will have to repaginate the file specially to the 1280x720 format. It generates a soundtrack using muscript -midi feeding into timidity, and typesets each page using muscript and eps2jpg and synchronises the page-turns with the soundtrack. Then it uses ffmpeg or avconv or mencoder to convert the .jpg files to the .avi file.
This program was used to generate Youtube-videos, for example the Trio with Guitar and the Droplet Video

Tools for handling PostScript output:
muscriptps2svg
This script converts PostScript (or EPS) output produced by muscript (2.8i or greater) into SVG (Scaleable Vector Graphics) format. It has a -p option to convert a particular page. It needs the SVG Perl module, available from search.cpan.org
eps2img
When the input file contains a boundingbox command, then muscript will generate Encapsulated-PostScript (EPS) output, which can be inserted into word-processing or desktop-publishing documents.
The Lua script eps2img converts this EPS into JPG or PNG format, which can be used in web pages.
When called with the -t option it converts the EPS into PNG format with a transparent background, which can be used in web pages even if they have non-white backgrounds.
There is also a   -s 1.9   option, which increases the size of the image, by 1.9 times in this example.
Sample usage:   eps2img f.eps f.jpg   or   eps2img f.eps f.png
See:   perldoc eps2img
a42us
This converts the muscript PostScript output from A4 page size to US Letter page size. There is also a a42us -c option which generates the global-distribution compromise format (A4 width and Letter height). See also PageSize.

Tools for handling MIDI output:
midiecho
Simulates a tape-delay reverb on a particular MIDI-channel by issuing repeated note_on events with diminishing volume.
midiedit
Edits a MIDI file in a human-readable text-format.
mididump
Dumps a MIDI file contents in a human-readable text-format.
midisox
Midisox is a tool for working on MIDI files, with a calling interface modelled, as far as possible, on that of SoX, which is a well-established tool for working on audio files.

Back to the top . . .

Future Enhancements

Back to the top . . .

Other Music-Typesetting software

You might also want to check out

Back to the top . . .

Peter Billam     pjb.com.au