3 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
5 def(mycode)(1)(tt(ARG1))
7 COMMENT( This document contains Mudela fragments. You need at least
8 Yodl-1.30.18 to convert this to tex or html.
15 htmlbodyopt(bgcolor)(white)
16 htmlcommand(<font color=black>)
19 \setlength{\topmargin}{-0.25in}
20 \setlength{\textheight}{9in}
21 \setlength{\textwidth}{5.875in}
22 \setlength{\oddsidemargin}{0.25in}
23 \setlength{\evensidemargin}{0.25in}
27 whenlatex(notableofcontents())
28 whentexinfo(notableofcontents())
30 article(Mudela, reference manual)
31 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
32 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
38 * paragraphs have too much space.
43 latexcommand(\def\interexample{})
44 latexcommand(\def\preexample{\par})
45 latexcommand(\def\postexample{\par\medskip})
46 latexcommand(\def\file#1{{code(#1)}})
48 latexcommand(\def\texttt#1{\tt #1})
49 latexcommand(\def\textbf#1{\bf #1})
52 includefile(html-disclaimer.yo-urg)
54 bf(This document is not up to date). All rendered examples of course
55 are current, but the rest probably isn't. Adjusting the tutorial was
56 considered more important than writing the reference manual. We
57 apologize for the inconvenience.
60 This document describes the the GNU LilyPond input format, which is an
61 effective language for defining music. We call this language (rather
62 arrogantly) The Musical Definition Language or Mudela, for
63 short.footnote(If anybody comes up with a better name, we'd gladly
64 take this. Gourlay already uses Musical Description Language,
65 G-Sharp Score Definition Language. ISO standard 10743 defines a
66 Standard Music Description Language. We're not being original here.)
68 The first aim of Mudela is to define a piece of music, being complete
69 from both from a musical typesetting, as from a musical performing
72 The Musical Definition Language (Mudela), has a logical structure,
73 making use of identifiers, that allows for flexible input, and
74 definition reuse. See the documentation file file(MANIFESTO), included
75 with the LilyPond sources for reasons and design considerations.
77 The below is included for explanatory purposes only (i.e., for a
78 complete and up-to-date definition, see file(lily/parser.yy) and
81 As a related note, you should take a look at the examples and the init
82 files, as this document does not cover every aspect of Mudela yet, and
83 may be out of date.footnote(Ok, I am being pessimistic here. This
84 just is a disclaimer. Docs usually are written after the program
85 itself.) This document intends to give an idea of how it works. It is
86 not a guide on how to use it.
90 The de-facto extension of Mudela is file(.ly). Files may be included by
91 entering code(\include) at the start of a line:
93 verb(\include "a_file.ly")
98 COMMENT(I don't understand the syntax, so I can't write this
99 section very well. --Adrian)
101 A one line comment is introduced by a
103 Block comments are started
108 They cannot be nested.
110 Mudela supports three types of constants: strings, reals, and integers.
114 A string which contains no spaces can be written without the quotes.
115 However, in Note mode, unquoted text can be intepreted as note names
116 rather than as a string.
118 Pairs of braces `code({)' and `code(})' or pairs of angle brackets
119 `code(<)' and `code(>)' are used to identify the scope
120 of contexts and enable the construction of hierarchical structure.
121 Items in braces will be treated as serial; items in angle brackets
122 will be stacked into chords.
123 Braces are also used to group arguments for certain commands.
125 To assign an identifier you use:
127 To use an identifier, you must preceed it with a backslash: code(\).
128 verb(oboe = \notes { ... }
129 \score{ \notes { \oboe }})
130 The left-hand part of the assignment is really a string, so
131 verb("Foo bar 4 2 " = \notes { ... })
132 is also a valid assignment (but you would have trouble referencing it)
133 If you reuse identifiers, then the previous contents will be thrown
134 away after the right hand is evaluated, e.g.
135 verb(bla = \notes { \bla })
138 COMMENT(It's not clear to me what things are allowed on the RHS of
139 an identifier assignment.)
141 The following words are keywords. You can define an identifer whose
142 name is a keyword, but you will not be able to reference it.
144 verb(absdynamic font time penalty spandynamic
145 accepts grouping midi property symboltables
147 cadenza include multi relative tempo
148 clear lyric header score translator
149 clef key notenames script type
150 cm keysignature octave shape transpose
151 consists mark output skip version
152 contains notes partial staff
153 duration musicalpitch paper spandynamic)
155 COMMENT( I don't know the proper way to make this kind of table in
158 Also note: Lilypond should really give an error when I write
160 Instead, I get the error later, after I try to use my redefinition of
161 \lyric. The cause is much less clear. )
164 subsect(Hierarchical structures)
166 The general structure consists of declarations:
167 verb(IDENTIFIER = \TYPE{
172 verb(\TYPE{ <type specific data> })
174 (Currently, code(\score) is the only type that can be instantiated
177 Most instantiations that use an IDENTIFIER are specified as follows:
179 verb(\TYPE{ \IDENTIFIER [...] })
181 Some exceptions on this rule have been made to prevent inputting
182 Mudela becoming tedious
185 COMMENT(As far as I can tell, the last bit is simply a repetition of
186 the information on how to use an identifier, so it should be deleted.
188 But I'm uncertain about the meaning of \TYPE in the above section.
189 Different from \type? Does it refer to \notes, \lyric? In general,
190 the use of the word "type" seems to be a source of confusion.
196 To simplify different aspects of music definition (entering the notes
197 and manipulating them) Mudela has a number of different input "modes".
198 In each mode, words are identified on the input. If code("word") is
199 encountered, it is treated as a string. If code("\word") is
200 encountered it is treated as a keyword or as an identifier. The
201 behavior of the modes differs in two ways: different modes treat
202 unquoted words different, and different modes have different rules for
203 deciding what is a word.
208 At the start of parsing, Mudela is in normal mode.
209 In normal mode, a word is an alphabetic character followed by
210 alphanumeric characters. If code(word) is encountered on the input it
211 is treated as a string.
213 dit(Note mode) Note mode is introduced by the keyword
214 code(\notes). In Note mode, words can only contain alphabetic
215 characters. If code(word) is encountered, Lilypond first checks for a
216 notename of code(word). If no notename is found, then code(word) is
217 treated as a string. If you mistype a notename, the parser will most
218 likely complain that you should be in code(\lyric) mode to do lyrics.
220 dit(Lyric mode) Lyrics mode is introduced by the keyword
221 code(\lyric). Because of the various control characters that can
222 appear in lyrics, e.g., foreign language accents, the inputting a
223 string containing these has been made very easy. Every sequence of
224 non-digit and non-white characters starting with an alphabetic
225 character or the code(_) is considered a word. When code("word") is
226 encountered it is treated as a lyric (without the quotes). Likewise,
227 when code(word) is encountered, it is treated as a lyric. The code(_)
228 character is converted to a space; it provides a mechanism for
229 creating words that contain spaces.
230 verb(a&@&@&TSI|{[ % a word
231 1THtrhortho % not a "word"
232 Leise DOEXPAND(Fl\)DOEXPAND("u\)ss{}teren meine Sapfe % 4 words
233 _ _ _ _ % 4 words: 4 spaces
236 COMMENT(Well, " seems to present some problems. Also `` seems to be
237 problematic. So the above statement isn't quite right. Unless these
238 characters are considered to be "white")
241 These modes are of a lexical nature. Normal and Note mode largely
242 resemble each other, save the possibility of entering Reals,
243 meaning of code(_) and the resolution of words
245 What's this about reals? When can you enter them or not enter them?)
248 sect(Note Description)
250 subsect(Basic note specification)
252 A note specification has the form
253 var(pitch)[var(octavespec)][var(duration)].
254 The pitch of the note is specified by the note's name.
256 Lilypond has predefined note names for various languages. The default
257 names are the Dutch note names. The notes are specified by the
258 letters code(c) through code(b), where code(c) is an octave below
259 middle C and the letters span the ocatave above that C.
260 In Dutch, a sharp is formed by adding
261 code(is). A flat is formed by adding code(es).
262 Double sharps and double flats are obtained by adding code(isis) or
264 Lily has predefined sets of notenames
265 for various nop(languages)footnote(These
266 are Dutch, English, German, Italian and Swedish.
267 Simply include the language specific init file file(language.ly).).
268 Rests are specified with the note name code(r). There is also a note
269 name code(s) which produces a nonprinting note of the specified
272 The optional octave specification takes the form of a series of single
274 code(') characters or a series of comma code(,) characters. Each
275 code(') raises the pitch by one octave; each code(,) lowers the pitch
278 mudela(fragment,verbatim,center)(
279 c' d' e' f' g' a' b' c''
282 mudela(fragment,verbatim,center)(
283 cis' dis' eis' fis' gis' ais' bis'
286 mudela(fragment,verbatim,center)(
287 ces' des' es' fes' ges' as' bes'
290 mudela(fragment,verbatim,center)(
291 cisis' eisis' gisis' aisis' beses'
294 mudela(fragment,verbatim,center)(
295 ceses' eses' geses' ases' beses'
298 Whenever a C-sharp is desired, you must specify a C-sharp. Lilypond
299 will determine what accidentals to typeset depending on the key and
301 A reminder accidental can be forced by
302 using an exclamation mark code(!)
304 mudela(fragment,verbatim,center)(
305 cis' d' e' cis' c'! d' e' c'
309 Durations are entered as their reciprocal values
310 mudela(fragment,verbatim,center)(
311 a'1 a'2 a'4 a a'8 a a'16 a'32 a'64
313 mudela(fragment,verbatim,center)(
317 If the duration is omitted then it is set equal to the previous
318 duration. If there is no previous duration, then a quarter note is
320 The duration can be followed by a dot code(.) to obtain dotted note
322 mudela(fragment,verbatim,center)(
326 In addition, the duration can be followed by a multiplier which is
327 introduced with the asterisk code(*) and can be an integer or a
328 fraction. The multiplier changes the duration that Lilypond uses
329 internally for the note, but it does not change the symbol that is
331 mudela(fragment,verbatim,center)(
332 c'4*2 c'4*2 d'8*2/3 d'8*2/3
335 Extra long notes can be obtained using the code(\breve) and
336 code(longa) durations:
337 mudela(fragment,verbatim,center)(
342 subsect(Beams and Tuplets)
344 A beam is specified by surrounding the beamed notes with brackets
346 mudela(fragment,verbatim,center)(
347 [a'8 a'] [a'16 a' a' a']
350 In order to create triplets, you must use a length multiplier after
351 the brackets. An open bracket code([) followed by a fraction
352 instructs Lilypond to print a number over the beam, and it also
353 starts multiplying all note lengths by the fraction. The closing
354 bracket code(]) should be followed by the fraction code(1/1) in order
355 to restore normal note lengths. To create a triplet without a beam,
356 place a backslace code(\) before the opening and closing brackets.
358 For example, in an ordinary triplet, the notes have duration 2/3 as
360 mudela(fragment,verbatim,center)(
361 [2/3 a'8 a' a' ]1/1 \[2/3 b'4 b' b'\]1/1
364 There is a shorthand that can be used when you
365 want notes lengths multiplied by 2/n.
366 The 2 can be omitted after the open bracket
367 and the first 1 can be omitted after the closing bracket.
368 mudela(fragment,verbatim,center)(
369 [/3 b'8 b' b' ]/1 \[/3 a'4 a'8\]/1
372 COMMENT(The rest of this section needs to be rewritten. I don't
373 understand what's going on at all here. The meaning of the lone ] is
374 unclear. And the : syntax is also unclear. --Adrian)
376 Here is a combination
377 mudela(fragment,verbatim,center)(
378 [/3 a'8 a'16 a'] a'8 \]
382 mudela(fragment,verbatim,center)(
386 mudela(fragment,verbatim,center)(
391 subsect(Slurs and Ties)
393 A tie connects two adjacent note heads
395 mudela(fragment,verbatim,center)(
399 Whereas a slur rather connects `chords',
400 and tries to avoid crossing stems
402 mudela(fragment,verbatim,center)(
406 And of course, such a (legato) slur can span several notes
407 mudela(fragment,verbatim,center)(
414 Lyrics are entered like notes, with pitches replaced
415 by text. For example code(Twin-4 kle4 twin-4 kle4) enters four
416 syllables, each with quarter note duration. Two words can be bound
417 together by an underscore If a single duration
419 In order to instruct Lilypond to write lyrics underneath the
420 staff, you must enter the lyrics context with code(\type Lyrics).
421 Lyrics should be entered in lyrics mode which is entered with code(\lyric).
423 Two syllables or words that compose a single
424 duration entry are bound together using an underscore:
425 code(He_could4 not4). Here is a full example:
426 mudela(verbatim)(\score{
427 < \notes \transpose c'' {c d e c | c d e c | e f g'2 |
428 e'4 f g'2 \bar "|."; }
429 \type Lyrics \lyric {
430 DOEXPAND(Fr\)`e-4 re Ja- que DOEXPAND(Fr\)`e- re Ja- que
431 Dor- mez vous?2 Dor-4 mez vous?2 }
443 sect(Chords and Voices)
445 Here's a simple chord
446 mudela(fragment,verbatim,center)(
451 mudela(fragment,verbatim,center)(
460 mudela(fragment,verbatim)(
462 { \voiceone c'4 g' c' g' }
470 Lilypond aligns all musical objects according to the amount of time
471 they occupy. All of these objects have a duration. When music is
472 written in series using braces the duration is the sum of the
473 durations of the elements. When music is stacked using angle
474 brackets, the duration is the maximum of the durations of the
477 Because Lilypond knows the durations of all musical elements, the time
478 signature enables Lilypond to draw bar lines automatically. The time
479 signature is specified with the code(\time) command: code(\time 3/4).
480 If no time signature is given, Lilypond assumes 4/4. The automatic
481 generation of bar lines can toggled with the code(\cadenza) command,
482 and an incomplete measure at the start of the music can be created
483 using the code(\partial) command: code(\partial 8*2;) creates a
484 starting measure lasting two eighth notes.
486 In order to help with error checking, you can insert bar markers in
487 your music by typing code(|). Whenever Lilypond encounters a code(|)
488 that doesn't fall at a measure boundary, she prints a warning message.
490 Rhythmic grouping is a concept closely associated with this.
491 A default grouping is selected for the chosen time signature.
492 The default consists of combinations of 2 and 3 beats with as many
493 groups of 3 as possible, and the groups of 3 coming first. For
494 example, 4/4 is divided into 2+2 and 8/8 is divided into 3+3+2. This
495 default grouping can be changed using the \grouping command which
496 takes a list of durations to specify the grouping.
500 sect(A complete example)
501 COMMENT(%label(se:complete))
503 A Mudela file needs some red tape
516 sect(Composition: forming bigger structures)
519 The computer savy user may be interested in a more formal
520 specification. We can capture what have learned about forming
521 sentences in Mudela in a context-free grammar.
523 latexcommand(\smallskip)
526 row(cell(em(Music))cell(: em(Note)))
527 row(cell()cell(code(|) em(Rest)))
528 row(cell()cell(code(|) code({) em(MusicList) code(})))
529 row(cell()cell(code(|) code(<) em(MusicList) code(>)))
530 row(cell()cell(code(|) em(Command)))
531 row(cell()cell(code(|) code(\type) em(string) code(=) em(string) em(Music)))
533 row(cell(em(MusicList))cell(: em(empty)))
534 row(cell()cell(code(|) em(MusicList) em(Music)))
538 latexcommand(\smallskip)
540 In mathematics you can form expressions by combining expressions,
541 which are ultimately some kind of atom or terminal symbol. The same
542 goes for Mudela: there are some basic building blocks, and by
543 combining those you create complex music.
545 You can combine music in three ways:
547 it()If you enclose a sequence of music-elements in braces ( code({)
548 and code(}) ), then you form another kind of music called
551 The duration of sequential composition is the sum of the durations of its elements
553 { c c g g a a g2 } % twinkle twinkle
554 { { c c g g} { a a g2 } }
556 it()You can stack music by enclosing a sequence of music elements
557 with code(<) and code(>). This is called simultaneous music.
558 The duration of a simultaneous composition is the maximum of the durations
559 of its elements Example:
561 <a4 {cis8 cis8} e'4> % a-major chord
563 it()You can form music by transposing music:
566 d % from c to the d that's almost one octave down
567 { e4 f4 } % the horizontal music
571 it()verb(\translator)
575 Of course you can also combine these three mechanisms.
577 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
583 By default the same key signature is valid for all octaves, but
584 this can be changed with the property code(keyoctaviation).
587 The identifier code(\specialkey) sets the property for the Staff. A
588 key with two flats in one octave and three sharps in the next can be
589 declared with verb(\specialkey \keysignature bes es fis' cis' gis';)
591 sect(Music fragments)
592 label(tutorial:music-fragments)
594 Sometimes you only need to print a small fragment of music, perhaps
595 something much like one of the examples in this document. Back in
596 section ref(sec:running-lilypond) we told you that the music you
597 enter should be encapsulated in something like:
605 where the only interesting information is this particular example is verb(
608 The rest of the above example was already nicknamed `red tape'.
609 You may easily get bored if you have to provide this same red tape
610 for every fragmenty you nop(try)footnote(Of course, in most cases your
611 favourite text editor (TM)
614 Luckily there's a trick around this, and it's called file(.fly) files.
615 If you use the extension file(.fly) for Mudela file file(foo),
616 LilyPond will embed your file(foo.fly) nop(in)footnote(Or something very
617 similar. If you want to know exactly, see file(init/init.fly)):
624 Here's how it works. If you run LilyPond on your file file(bar.ly), you
625 may notice that she starts off by reading quite a number of files before
626 she actually reaches your file(bar.ly). There's no magic going on, Lily
627 by default reads an initialisation file (file(init/init.ly)). In the
628 initialisation process a lot of things are defined that you'll need for
629 normal operation, such as notenames and various other mudela shortcuts,
630 engraver and perforer definitions, font sizes, musical dimensions and
631 paper sizes. When you use the extension file(.fly), Lily just starts
632 reading another initialisation file (file(init/init.fly)), that includes the
633 red tape for you too.
638 Commands take the form of a keyword followed by a list of arguments
639 separated by spaces and terminated by a semicolon:
640 `code(\keyword argument argument ... ;)'
642 COMMENT(The above is wrong. Many commands have the form
644 with no semicolon, at least much of the time, and some commands
645 have obligatory braces as far as I can tell, which don't contain music.)
649 dit(mycode(\absdynamic))
651 dit(mycode(\accepts))
653 dit(mycode(\bar) var(bartype)) Prints a special bar symbol, or at
654 measure boundaries, replaces the regular bar symbol with a special
655 symbol. The argument var(bartype) is a string which specifies the
656 kind of bar to print. Options are code(":|"), code("|:"),
657 code(":|:"), code("||"), code("|."),
658 code(".|"), or code(".|."). These produce respectively a right repeat, a left
659 repeat, a double repeat, a double bar, a start bar, an end bar, or a
660 thick double bar. If var(bartype) is set to "empty" then nothing is
661 printed, but a line break is allowed at that spot.
663 dit(mycode(\cadenza) var(togglevalue)) Toggles the automatic generation
664 of bar lines. If var(togglevalue) is 0 then bar line generation is
665 turne off. If var(togglevalue) is 1 then a bar is immediately
666 printed and bar generation is turned on.
670 dit(mycode(\clef) var(clefname)) Sets the current clef. The argument
671 is the name of the clef. Possibilities are code(bass), code(alto),
672 and code(treble). Treble clef is the default.
674 dit(mycode(\cm)) Specify a width in centimeters.
676 dit(mycode(\consists))
678 dit(mycode(\contains))
680 dit(mycode(\duration) { var(length) var(dotcount) }) Specify note
681 duration. The parameter var(length) is the negative logarithm (base
682 2) of duration: 1 is a half note, 2 is a quarter note, 3 is an eighth
683 note, etc. The number of dots after the note is given by
688 dit(mycode(\grouping) var(durationlist)) Sets the metric structure of
690 COMMENT(elaboration is needed here.)
692 dit(mycode(\in)) Specify a width in inches.
694 dit(mycode(\include) var(file)) Include the specified file.
696 dit(mycode(\lyric) { var(list) } ) Parse var(list) in lyrics mode.
698 dit(mycode(\key) var(pitch)) Change key signature to that of var(pitch)-major.
700 dit(mycode(\keysignature) var(notelist))
701 Specify an arbitrary key signature. The notes from var(notelist) will
702 be printed in the key signature in the order that they appear on the list.
706 dit(mycode(\notes) var(music)) Enter note mode and process the
709 dit(mycode(\musicalpitch) { var(octave) var(note) var(shift) }) Specify
710 note pitch. The octave is specified by an integer, zero for the
711 octave containing middle C. The note is a number from 0 to 7, with 0
712 corresponding to C and 7 corresponding to B. The shift is zero for a
713 natural, negative to add flats, or positive to add sharps.
715 dit(mycode(\time) var(numerator)mycode(/)var(denominator)) Change the time
716 signature. The default time signature is 4/4.
718 dit(mycode(\midi)) Produce musical output. See code(\tempo) for setting
721 dit(mycode(\mm)) Specify a width in millimeters.
725 dit(mycode(\header) { var(key1) = var(val1); var(key2) = var(val2); ... })
726 Specifies information about the music. A header should appear at the
727 top of the file describing the file's contents. If a file has
728 multiple code(\score) blocks, then a header should appear in
729 each score block describing its contents. Tools like code(ly2dvi) can
730 use this information for generating titles. Some possible key values
731 are: title, opus, description, composer, enteredby, and copyright.
733 dit(mycode(\notenames) { var(list) }) Define new note names.
734 The argument var(list) is a list of definitions of the form
735 var(name) = var(pitch), where var(pitch) is specified with the
736 code(\musicalpitch) command.
739 dit(mycode(\nop(output)))
741 dit(mycode(\partial) var(duration)) Specify that the first measure of
742 the music lasts only for the specified duration.
744 dit(mycode(\paper) mycode({) [ mycode(linewidth = )var(width)mycode(;) ] mycode(}))
745 Appears in a score block to indicate that the music should be printed.
746 The line width can be set to -1. in order to prevent justification of
747 small fragments of music, or the width can be specified explicitly
748 using code(\cm), code(\in), code(\mm), or code(\pt) to specify the
751 dit(mycode(\penalty))
753 dit(mycode(\property))
755 dit(mycode(\pt)) Specify a width in points.
757 dit(mycode(\relative) var(pitch) var(music)) Processes the specified
758 var(music) in relative pitch
759 mode. In this mode, the octave of a pitch note is chosen so that the
760 note is closest to the preceeding note.
761 The argument var(pitch) is
762 the starting pitch for this comparision. In the case of chords, the
763 first note of a chord is used as the base for the pitches in the next
766 dit(mycode(\score)) Start a music definition.
776 dit(mycode(\spandynamic))
777 dit(mycode(\symboltables))
780 dit(mycode(\tempo) var(duration) = var(perminute)) Used when creating
781 MIDI output to specify the tempo. For example,
782 `code(\midi { \temp0 4 = 76})' requests output with 76 quarter notes
785 dit(mycode(\translator))
788 dit(mycode(\transpose) var(pitch) var(music)) Transposes the specified
789 music. Middle C is tranposed to var(pitch).
791 dit(mycode(\version) var(string)) Specify the version of Lilypond that
792 a file was written for. The argument is the version number,
793 for example code("1.0.4").