Chapter 2: Features

This document is not up to date. All rendered examples of course are current, but the rest probably isn't. Adjusting the tutorial was considered more important than writing the reference manual. We apologize for the inconvenience.

This document describes the the GNU LilyPond input format, which is an effective language for defining music. We call this language (rather arrogantly) The Musical Definition Language or Mudela, for short. (If anybody comes up with a better name, we'd gladly take this. Gourlay already uses Musical Description Language, G-Sharp Score Definition Language. ISO standard 10743 defines a Standard Music Description Language. We're not being original here.)

The first aim of Mudela is to define a piece of music, being complete from both from a musical typesetting, as from a musical performing point of view.

The Musical Definition Language (Mudela), has a logical structure, making use of identifiers, that allows for flexible input, and definition reuse. See the documentation file MANIFESTO, included with the LilyPond sources for reasons and design considerations.

The below is included for explanatory purposes only (i.e., for a complete and up-to-date definition, see lily/parser.yy and lily/lexer.ll).

As a related note, you should take a look at the examples and the init files, as this document does not cover every aspect of Mudela yet, and may be out of date. (Ok, I am being pessimistic here. This just is a disclaimer. Docs usually are written after the program itself.) This document intends to give an idea of how it works. It is not a guide on how to use it.

2.1: Files

The de-facto extension of Mudela is .ly. Files may be included by entering \include at the start of a line:


\include "a_file.ly"

2.2: Comments

Line comments are introduced by a %. Block comments are delimited by %{ and %}. They do not nest.

2.3: Versions

Occasionally, small changes in syntax across different versions of Mudela might give syntax errors. To warn you about possible incompatibilities, you can specify the Mudela version for which the inputfile was written,


\version "0.0.50";

A Python-script which tries to convert to newer versions (convert-mudela) is included in the LilyPond distribution.

2.4: Keywords

Keywords are preceded by a backslash: \. They contain alphabetic characters only.

2.5: Nesting characters

Mudela uses the brace, `{' and `}' for most hierarchical structures. For chords the < and the > are used as nesting braces.

2.6: Constants


"I am a string"
-1.2e3          % a real
12              % an int

2.7: Identifiers

When assigning identifiers you use


string = ...

If you reuse identifiers, then the previous contents will be thrown away after the right hand is evaluated, e.g.


bla = \melodic { \bla }

is legal

When using identifiers they have to be escaped:


oboe = \melodic { ... }
\score{ \melodic { \oboe }}

The left-hand part of the assignment is really a string, so


"Foo bar 4 2 " = \melodic { .. }

is also a valid assignment (but you would have trouble referencing to it)

2.8: Hierarchical structures

The general structure consists of declarations:


IDENTIFIER = \TYPE{
        <type specific data>
}

and instantiations:


\TYPE{ <type specific data> }

(Currently, \score is the only type that can be instantiated at top level.)

Most instantiations that use an IDENTIFIER are specified as follows:


\TYPE{ \IDENTIFIER [...] }

Some exceptions on this rule have been made to prevent inputting Mudela becoming tedious

2.9: Modes:

To simplify different aspects of music definition (entering the notes and manipulating them) Mudela has a number of different input "modes":

Normal mode

At the start of parsing, Mudela assumes normal mode. In Normal mode, a word is looked up in the following order:

word
string

"string"
string

\word
keyword, identifier
In normal mode, a word is assumed to start with an alphabetic character, followed by alpha-numeric characters.

Note mode
Note mode is introduced by the keyword \melodic. In Note mode, a word is looked up in the following order:

word
notename, string

"string"
string

\word
keyword, identifier

In Note mode a word is considered to have alphabetic characters only, so the underscore (_) is invalid. If you accidently mistype a notename, the parser will assume that you are entering a string (and it will most likely complain that you should be in \lyric mode to do lyrics)

Lyric mode
Lyrics mode is introduced by the keyword \lyric. Because of the various control characters that can appear in lyrics, e.g., foreign language accents, the inputting a string containing these has been made very easy.

In Lyrics mode, a word is looked up in the following order:

word
string (thus a lyric)

"string"
string

\word
keyword, identifier

In Lyric mode every sequence of non-digit and non-white characters starting with an alphabetic character or the _ is considered a word.


a&@&@&TSI|{[    % a word
1THtrhortho     % not a "word"
Leise Fl\"u\ss{}teren meine Sapfe       % 4 words
_ _ _ _         % 4 words: 4 spaces

These modes are of a lexical nature. Normal and Note mode largely resemble each other, save the possibility of entering Reals, meaning of _ and the resolution of words

Durations are entered as their reciprocal values

a'1 a'2 a'4 a a'8 a a'16 a'32 a'64 [mudela.yo-2.9.1.gif]

Notice that you only have to specify the duration when it changes: Lily assumes a note has the same duration as the previous one.

Now we can already write a little tune

c' d' e' c' | c' d' e' c' | e' f' g'2 [mudela.yo-2.9.2.gif]

As you'll probably have guessed, the vertical bar | may be used to mark measures.

In the scale shown above we left-out the last c note of the next octave. Postfixing the pitch with a quote ' produces a note by one octave higher

c c' c'' [mudela.yo-2.9.3.gif]

Postfixing the pitch with a comma, , produces a note by one octave lower

a a, a,, [mudela.yo-2.9.4.gif]

2.10: Slurs and Ties

A tie connects two adjacent note heads

e' ~ e' [mudela.yo-2.10.1.gif]

Whereas a slur rather connects `chords', and tries to avoid crossing stems

e'( )e' [mudela.yo-2.10.2.gif]

And of course, such a (legato) slur can span several notes

c'( d' e' )f' [mudela.yo-2.10.3.gif]

2.11: Beams and Tuplets

A beam is

[a'8 a'] [a'16 a' a' a'] [mudela.yo-2.11.1.gif]

Here's a beamed triplet

[/3 a'8 a' a']/1 [mudela.yo-2.11.2.gif]

a triplet without a beam

\[/3 a'4 a'8\] [mudela.yo-2.11.3.gif]

and a combination

[/3 a'8 a'16 a'] a'8 \] [mudela.yo-2.11.4.gif]

Abbreviations

c'1:16 [:16 e'1 g'] [mudela.yo-2.11.5.gif]

c'4:32 [:16 c'8 d'8] [mudela.yo-2.11.6.gif]

2.12: Notenames

Lily has predefined sets of notenames for various languages (These are Dutch, English, German, Italian and Swedish. Simply include the language specific init file language.ly.). The default set are the ones we like best are the Dutch notenames.

A sharp is formed by adding is

cis' dis' eis' fis' gis' ais' bis' [mudela.yo-2.12.1.gif]

and a flat is formed by adding es

ces' des' es' fes' ges' as' bes' [mudela.yo-2.12.2.gif]

With the obvious names for double sharps

cisis' disis' eisis' fisis' gisis' aisis' bisis'

[mudela.yo-2.12.3.gif]

and double flats

ceses' deses' eses' feses' geses' ases' beses'

[mudela.yo-2.12.4.gif]

There are two special `notenames', the rest

r16 [a' a' a'] [mudela.yo-2.12.5.gif]

and the space

a'2 s-"diminuendo" | a' [mudela.yo-2.12.6.gif]

2.13: Commands

\clef "bass"; c [mudela.yo-2.13.1.gif]

and a clef-change

\clef "treble"; f' e' \clef "alto"; d' c' [mudela.yo-2.13.2.gif]

\time 3/4; c' g' g' | [mudela.yo-2.13.3.gif]

\key d; g a b cis' d' e' fis' g' [mudela.yo-2.13.4.gif]

Note how Mudela allows you to convey a musical message and doesn't force you to produce a list of typesetting commands. If the music has a cis, you type a cis. Depending on the key and context of the note Lily will determine what accidentals to typeset.

A reminder accidental can be forced by using an exclamation mark ! on a pitch a reminder accidental

cis' d' e' cis' | c'! d' e' c' | [mudela.yo-2.13.5.gif]

\time 2/4; \bar "|:"; c' c' \bar ":|:"; c' c' \bar ":|"; c' c' \bar "|.";

[mudela.yo-2.13.6.gif]

2.14: Chords and Voices

Here's a simple chord

<c e g> [mudela.yo-2.14.1.gif]

here are a few

< { c'()d'()c' } { e'()f'()e' } { g'()a'()g' } > [mudela.yo-2.14.2.gif]

and similarly voices

< { \voiceone c'4 g' c' g' } { \voicetwo c2 g2 } >

[mudela.yo-2.14.3.gif]

2.15: A complete example

A Mudela file needs some red tape

\score{ \melodic { c' d' e' c' | c' d' e' c' | e' f' g'2 | } }

[mudela.yo-2.15.1.gif]

2.16: Lyrics

Lyrics are entered like notes, with pitches substituted by text.

All syllables are entered separately, separated by whitespace


Twin-4 kle4 twin-4 kle4 ... 

Two syllables or words that compose a single duration entry are bound together using an underscore


He_could4 not4

\score{ < \melodic \transpose c'' { c d e c | c d e c | e f g'2 | e'4 f g'2 \bar "|."; } \type Lyrics \lyric{ Fr\`e-4 re Ja- que Fr\`e- re Ja- que Dor- mez vous?2 Dor-4 mez vous?2 } > } [mudela.yo-2.16.1.gif]

2.17: Composition: forming bigger structures

The computer savy user may be interested in a more formal specification. We can capture what have learned about forming sentences in Mudela in a context-free grammar.

Music : Note
| Rest
| { MusicList }
| < MusicList >
| Command
| \type string = string Music
;
MusicList : empty
| MusicList Music
;

In mathematics you can form expressions by combining expressions, which are ultimately some kind of atom or terminal symbol. The same goes for Mudela: there are some basic building blocks, and by combining those you create complex music.

You can combine music in three ways:

  • If you enclose a sequence of music-elements in braces ( { and } ), then you form another kind of music called sequential music with those pieces. The duration of sequential composition is the sum of the durations of its elements
    
          { c c g g a a g2 }      % twinkle twinkle
          { { c c g g} { a a g2 } }
      
    
  • You can stack music by enclosing a sequence of music elements with < and >. This is called simultaneous music. The duration of a simultaneous composition is the union of the durations of its elements Example:
    
            <a4 {cis8 cis8} e'4>      % a-major chord
        
    
  • You can form music by transposing music:
    
        \transpose  
            d       % from c to the d that's almost one octave down
                    { e4 f4 }       % the horizontal music
    
    
  • \type
    
  • \property
    
  • \translator
    
  • \relative
    
  • Of course you can also combine these three mechanisms.

    
    { c <c e> <c e g> <c e g \transpose d' dis > }  % 4 increasing chords
    
    

    2.18: Durations

    A duration always starts with the duration type (1,2,4 etc), and then any optional multipliers/dots. `Gregrorian' durations can be entered as follows

    
    c'\breve
    gis'\longa
    
    

    2.19: Time signatures/groupings

    A time signature specification has this form:

    
    \time 3/4 ;
    
    

    Rhythmic grouping is a concept closely associated with this. For example, in a 5/8 time signature, the counts are grouped 2+3. In Mudela this is entered as

    
    \grouping  8*2 8*3 ;
    
    

    You can start the piece with a partial measure, the command takes a duration as an argument

    
    \partial 16*3;
    
    

    Make the piece start with a upstep lasting 1 3/4 quarter notes.

    These commands constitute `Music', and have a duration of 0.

    2.20: Properties

    By default the same accidentals are valid for all octaves, but this can be changed with the property specialaccidentals.

    The identifier \specialkey sets the property for the Staff. A key with two flats in one octave and three sharps in the next can be declared with

    \specialkey
    \accidentals bes es fis' cis' gis';
    

    2.21: Music fragments

    Sometimes you only need to print a small fragment of music, perhaps something much like one of the examples in this document. Back in section 1.4 we told you that the music you enter should be encapsulated in something like:

    
    \score<
            \melodic\relative c{
    		d
    	}
    	\paper{ }
    	\midi{ }
    >
    
    
    where the only interesting information is this particular example is
    
    	d
    
    
    The rest of the above example was already nicknamed `red tape'. You may easily get bored if you have to provide this same red tape for every fragmenty you try (Of course, in most cases your favourite text editor (TM) will help you out.).

    Luckily there's a trick around this, and it's called .fly files. If you use the extension .fly for Mudela file foo, LilyPond will embed your foo.fly in (Or something very similar. If you want to know exactly, see init/init.fly):

    
    \score<
            \melodic\relative c{
    		<<foo.ly>>
    	}
    	\paper{ }
    	\midi{ }
    
    

    Here's how it works. If you run LilyPond on your file bar.ly, you may notice that she starts-off by reading quite a number of files before she actually reaches your bar.ly. There's no magic going on, Lily by default reads an initialisation file (init/init.ly). In the initialisation process a lot of things are defined that you'll need for normal operation, such as notenames and various other mudela shortcuts, engraver and perforer definitions, font sizes, musical dimensions and paper sizes. When you use the extension .fly, Lily just starts reading another initialisation file (init/init.fly), that includes the red tape for you too.