3 DEFINEMACRO(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
8 COMMENT( This document contains Mudela fragments. You need at least
9 Yodl-1.30.18 to convert this to tex or html.
16 htmlbodyopt(bgcolor)(white)
17 htmlcommand(<font color=black>)
19 latexpackage()(a4wide)
21 %\usepackage[latin1]{inputenc}
25 whenlatex(notableofcontents())
26 whentexinfo(notableofcontents())
28 article(Mudela, the Music-Definition Language)
29 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
30 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
34 * paragraphs have too much space.
39 latexcommand(\def\interexample{})
40 latexcommand(\def\preexample{\par})
41 latexcommand(\def\postexample{\par\medskip})
42 latexcommand(\def\file#1{{code(#1)}})
46 This document is written in url(Yodl)(ftp://pcnov095.win.tue.nl/pub/yodl)
47 and should foremost produce nice LaTeX() output.
48 In other formats, such as html, some things will look a bit different,
49 while other things will be simply left out.
50 Therefore, the authoritive version of this document is the PostScript version,
55 label(tutorial:introduction)
56 latexcommand(\parindent2pc)
58 If you are reading this, you probably are interested in printing
59 music. LilyPond is a program that can print music from a
60 specification that you, the user, supply. Using LilyPond may be a bit
61 quaint in the beginning, because you have to give that specification
62 using a em(language). That might not be what you expect if you are
63 familiar with graphical interfaces. But there are some big
64 advantages: first, once you master the language, entering music can be
65 done quite efficiently. Secondly, it is possible to explain exactly
66 what the meaning of a language is, i.e., the semantics are much
67 clearer. Thirdly, since the program is not interactive, no tradeoffs
68 have to be made between processing speed and beauty of the output.
70 This chapter is a gentle introduction to Mudela, the language that
71 instructs LilyPond to typeset music. We will explain Mudela by
72 presenting a series of examples of Mudela input. The corresponding
73 output will be shown on the right or below, just as it was produced by
76 We will assume that you more or less understand the basics of music notation.
77 If you are not familiar with the English terms for music notation, you
78 should consult bind(Appendix)ref(glossary): it contains a glossary
79 of musical terms along with translations in some other languages.
81 If you want to try the examples given here, you should have look a
82 look at bind(Section)ref(sec:running-lilypond) first.
84 sect(Music copying, music definition and music entry)
85 label(tutorial:copying-vs-def-vs-entry)
87 If you have copied music before, using LilyPond may seem awkward
88 to you in the beginning. The purpose of LilyPond informally is
89 explained by the term `music typesetter'.
91 This may give the impression that the program is like a drawing tool
92 and that it lets you control precisely how the music is formatted.
93 This is not the case: not only does the program print musical symbols,
94 LilyPond also tries to make esthetic decisions---to be precise, we
95 programmed her to do what we find nop(pretty.)footnote(We formed our
96 taste by looking at, and reading all about fine music engraving. Of
97 course, our taste is also bound by all the accepted rules of common
98 music notation.) You do not have complete control over what is
99 happening. Usually that is not a big loss, since good engraving is a
100 very complex trade. In other words, you don't have control, so you do
101 not have to worry about what is happening precisely.
103 Secondly, we expect you to enter the meaning of the music, not the
104 sheet music itself. The input to LilyPond is a music definition,
105 which is something different than notation: notation is a graphical
106 system. Put more concretely: your input to LilyPond should contain
107 information like ``a dotted quarter note, pitch nop(d)sups(2).''
108 LilyPond will figure out from the musical information that a black
109 note head with a stem but without flag, fourth staff line, with dot
112 When you are copying music by hand from a printed score, you don't have
113 to know what the score means; you just copy the symbols. With LilyPond
114 such a thing is not possible. You have to enter the meaning of the
115 symbols, and this might not always be as easy. On the other hand, once
116 entered, any piece of music can be played and transposed automatically.
118 Finally, in some spots we will cheat a bit when it comes to musical
119 definition. Mudela has some entry modes that help to make typing
120 Mudela pleasant. For example, the phrase ``a dotted quarter note,
121 pitch nop(d)sups(2)'' translates to the following longhand:
123 \musicalpitch { 1 2 0 } \duration { 2 1 })
125 This data is what we consider the musical em(definition). Mudela
126 has a special entry mode where you can conveniently abbreviate this to
127 `code(d''4.)'. There are some features that also make the quotes and
128 numbers in `code(d''4.)' superfluous in some cases.
130 For those who are curious, the numbers in `code(\musicalpitch { 1 2 0
131 })' example mean octave, notename, and accidental respectively. The
132 numbers in `code(\duration { 2 1 })' are the (negative) logarithm of the
133 duration (2 is a quarter note, 3 is an eighth note, etc.) and the number
134 of augmention dots respectively.
136 sect(When you know the notes to nop(print)ellipsis())
138 The basic building block of music is the note. You can have LilyPond
139 print a note by specifying its pitch and duration. The pitch of the
140 central C is written as code(c'). This is in line with musicological
141 notation; there this pitch is transcribed as nop(c)sups(1) or c'. A
142 quarter-note duration is written as code(4). So, to print a quarter
143 note whose pitch is central C, you enter the following:
144 mudela(fragment,verbatim,center)( c'4 )
149 The duration of a note is specified as a number: a whole note is
150 denoted by 1, a half note by 2, a quarter by 4, and so on. If you
151 want to augment a duration with a dot, simply affix a period to the
152 number. Here are some random notes to show how it works.
154 mudela(fragment,verbatim)(
155 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
158 subsect(Basic pitches)
160 The pitch code(c') actually consists of two parts: one part for the
161 note name, and one for the octave. The letter specifies which note
162 name to use: note names simply are the letters code(a) to code(g).
163 The number of apostrophes specifies the octave to use: the central C
164 is denoted by code(c').footnote(By convention, the A above central C
165 at concert pitch is the tone that is used to tune instruments. Its
166 frequency is about 440 Hz.) The C which is an eighth higher (the C in
167 the ``two-line octave'') is denoted by code(c''): every octave adds a
168 quote. A note name without quotes designates the pitch below code(c')
169 (the C in the ``small octave''). If you want to go down even further,
170 commas should be added, e.g., the C in the ``contra octave'' is
171 expressed as code(c,,).footnote(The comma is meant to represent a
175 This example demonstrates octaves:
176 mudela(fragment,verbatim,center)(
177 c,,4 c,4 c4 c'4 c''4 c'''4
180 And this example demonstrates notenames:
181 mudela(center,fragment,verbatim)(
182 c'4 d'4 e'4 f'4 g'4 a'4 b'4 c''4
185 A rest can be entered as a note with the special name code(r), e.g.,
186 mudela(fragment,verbatim,center)(r4)
188 This already gives us enough material to make simple songs. In
189 bind(Figure)ref(fig:twinkle1) a portion of the traditional song
190 ``Twinkle Twinkle Little Star'' is shown.
192 latexcommand(\begin{figure}[h])
194 mudela(fragment,verbatim)(
198 latexcommand(\caption{Twinkle twinkle little star (version 1)})
201 latexcommand(\end{figure})
206 We have so far ignored chromatically altered pitches. The names `a'
207 to `g' for entering pitches are convenient: they are short,
208 pronounceable and they resemble the words for pitches in normal
211 Enter flats and sharps. In English there is no standard terse word
212 for C sharp or C flat. For this reason, we implemented a different,
213 non-English convention for entering altered pitches: a note is made
214 sharp by adding the suffix `--is' to its name, and flat by adding the
215 suffix `--es'. For a double sharp another `--is' suffix is added, for
216 flats another `--es' suffix. The names for the alterations of C are
217 given in bind(Table)ref(notename-tab).
219 latexcommand(\begin{table}[h])
222 row(cell(english)cell(LilyPond))
224 row(cell(c double flat)cell(ceses))
225 row(cell(c flat)cell(ces))
226 row(cell(c natural)cell(c))
227 row(cell(c sharp)cell(cis))
228 row(cell(c double sharp)cell(cisis))
231 latexcommand(\caption{Default note names})
233 latexcommand(\end{table})
235 Variations on this convention are used in a number of germanic
236 languages, notably Dutch, German, Swedish, and Norwegian. To be
237 precise, LilyPond actually defaults to Dutch notenames, with
238 code(aes), code(aeses), code(ees) and code(eeses) added for
241 Throughout this document we will continue to use the Dutch names. To make
242 (Dutch) pronunciation easier, the a-flat and e-flat are contracted to
243 code(as) and code(es). Similarly, the a double flat and e double flat are
244 contracted to code(ases) and code(eses).
246 If you are not comfortable with these names, you can make your own.
247 Note names for different languages are included with the example
248 initialisation files, amongst others English (C sharp is abbreviated
249 to code(cs)), Italian, Swedish and Norwegian. If you want to use
250 these names, you should look at bind(Section)ref(subsect:include) for
251 information on how to use include files.
253 sect(Running LilyPond)
254 label(sec:running-lilypond)
256 In the previous section some basic elements of Mudela were presented.
257 We didn't want to bore you too much with repetitive details, so we
258 left out some red tape that's needed for a of Mudela in a form that is accepted
260 be precise, we wrote code(X Y Z), when we really meant
265 We will continue to leave out the red tape this, until the time is fit to explain what the
269 Because LilyPond uses a language, it is a so called em(batch)
271 This means, that you use a
272 text editor (such as code(emacs) or code(vi)) to create an input
273 file. When you are done editing your input file, you save it, and you
274 run LilyPond on the file. If Lily finds any errors in your input file
275 then nop(she)footnote(We're sure that if computer programs could have
276 gender, LilyPond would be a female computer program. So we will
277 refer to the program as a she. This gender-bending is not to tease
278 you, dear reader. We do it in real life as well. In the past two
279 years LilyPond has become sort of a baby daughter to us, keeping us
280 awake at night, but also providing us with lots of joy. We hope you do
281 not mind our little aberration from the traditions of computer-manual
283 The name LilyPond is actually sort of a girl's name. Can you guess which
285 will complain. If everything went well, then she'll generate a file, that
286 you can process further to view or print.
288 Using LilyPond to print or view some music is a four-step procedure.
289 To get you started we'll run down the full procedure for you once.
293 Fire up your favourite editor (if you don't
294 know any editors, try code(joe silly.ly)),
295 and key in the example from bind(Figure)ref(fig:twinkle1), with red tape:
306 Save your file as file(twinkle.ly).footnote(The default extension for Mudela
310 Run LilyPond on your newly created file: enter code(lilypond twinkle).
311 LilyPond will then print all kinds of mumbo jumbo that can safely be
312 ignored. You might see something like this:
314 GNU LilyPond 0.1.55/FlowerLib 1.1.39
315 Parsing ... [/home/hanwen/musix/spacer/init/lily-init.ly[/home/hanwen/
317 ... stuff left out here ...
319 ] Documentation/twinkle.ly]
320 Interpreting music ...[1] (time: 0.04 seconds)
321 Preprocessing elements...
322 Calculating column positions ... [2]
323 Approximated: 1 lines, (with an average of 4.0 columns)
325 warning: Can not solve this casting problem exactly; revert to Word_wrap
326 [2]Time: 0.00 seconds
328 Postprocessing elements...
329 TeX output to twinkle.tex ...
332 All has gone well; there were some warnings but no errors. The run
333 resulted in output, a TeX file called file(twinkle.tex).
335 file(TeX) is usually spelled TeX(). It is a batch program for
336 typesetting text. It was developed by the great programmer and
337 scientist Donald Knuth to typeset his famous bookseries em(The Art of
338 Computer Programming). As you can see, TeX() can be adapted to do a
339 lot more. whenlatex(In fact, the document that you are reading now was also
340 produced with TeX().) COMMENT(ugh.)
344 To do something useful with the output you have to run TeX() on it
345 first. Run the command code(tex twinkle). The output should resemble this:
347 This is TeX, Version 3.14159 (C version 6.1)
349 Babel <v3.6h> and hyphenation patterns for american, dutch, loaded.
350 (/home/hanwen/lib/texmf/tex/lilypond/lilyponddefs.tex
351 (/home/hanwen/lib/texmf/tex/lilypond/dyndefs.tex)
352 (/home/hanwen/lib/texmf/tex/lilypond/fetdefs.tex
353 (/home/hanwen/lib/texmf/tex/lilypond/feta20.tex)
354 (/home/hanwen/lib/texmf/tex/lilypond/lily-ps-defs.tex))) [1] )
355 Output written on twinkle.dvi (1 page, 3084 bytes).
356 Transcript written on twinkle.log.
358 The human translation is ``everything went OK, the result is one
359 page long, and I put it in file(twinkle.dvi).''
361 it()The file(twinkle.dvi) file is a description of how a piece of
362 text looks when it is printed. You can view it, or print it. If you
363 are using a Unix system equipped with X-Windows, then you can issue
364 the command file(xdvi twinkle) to view the result. If this is not the
365 case, consult your local TeX() guru on printing and viewing DVI files.
366 What is in your window should approximately look like this:
373 \paper { linewidth = 13.\cm; }
378 If you want to print file(twinkle.dvi), you should invoke the command
379 code(dvips twinkle). Running this command should generate a
380 PostScript file called file(twinkle.ps). This file can be printed on
381 any PostScript compatible printer. You should not use any other
382 tools: the output from LilyPond contains fragments of PostScript which
383 will not print correctly if you don't use PostScript. If your printer
384 doesn't understand PostScript, you should check out GhostScript, a
390 The four-pass procedure sketched above is a bit clumsy. Moreover, the
391 result is pretty crude: the page does not include prettily printed
392 titles and if you are unlucky, the margins don't come out well. Jan
393 Arne Fagertun wrote a tool to take the above steps out of your hands,
394 make neat margins and print titling. The tool is called file(ly2dvi),
395 and it should be on your system if you use Lily on a Unix platform.
396 If you use file(ly2dvi), then you can do verb(ly2dvi twinkle.ly ) in
397 stead of steps 2 and 3. You will feel the real advantage of using
398 file(ly2dvi) when you add titling to the music. This is something
399 that we will discuss in bind(Section)ref(tutorial:titling).
402 COMMENT(This document does not cover all of Mudela. Due to technical details,
403 the precise working of Mudela is coupled to the innards of LilyPond.
404 If you really want to know all the details, your best bet would be to
405 get the sources to LilyPond and read the parser and scanner source.
406 They are in file(lilypond-x.y.z/lily/parser.yy) and
407 file(lilypond-x.y.z/lily/lexer.ll).)
413 Up till now we have only considered music that was rather simple. All
414 the music had notes going in one direction, from left to right, one
415 note following the other. You might be wondering if this is all Lily
416 can do, or whether it is possible to stack notes as well (creating
417 em(chords)). Rest assured: we designed LilyPond while keeping in mind
418 that she must be able to handle any notation construct that can be
419 expressed conveniently. Of course we did not leave out chords.
421 In Mudela you can form a chord of several notes by enclosing them in
422 pointed parentheses, bind(i.e.)bind(langle())bind(and)rangle(). ASCII
423 doesn't really have these delimiters, so Mudela uses the larger-than
424 (code(>)) and smaller-than (code(<)) signs instead. For example, a
425 D-major nop(chord)footnote(Recall what was said in the previous
426 section about flats and sharps: the word code(fis) means an f sharp.)
427 can be described by the following fragment:
428 mudela(fragment,verbatim,center)(
432 Chords can be entered in the music in the same places that notes
433 can. As an example we give a snippet of ``Twinkle Twinkle Little
434 Star'' in chords. The chords may seem, slightly unconventional, but they
435 only serve to show how chords work. We've aligned the chords
436 in the input on their starting beat just to help you reading it.
437 This layout does not influence the typesetting result in any way.
439 mudela(verbatim, fragment)(
440 c''4 c''4 <c''4 g''4> <c''4 e''4 g''4>
441 <c''4 e''4 a''4> <b'4 d''4 a''4> <b'2 d''2 g''2>
442 <a'4 d''4 f''4> <bes'4 d''4 f''4> <bes'4 c''4 e''4> <g'4 c''4 e''4>
443 <e'4 a'4 d''4> <a4 g'4 cis''4> <d'2 f'2 d''2>
448 sect(Shortcuts for duration)
450 If you typed the last example into a Mudela file, you will have
451 noticed that the input has lots of repetitions. You will probably
452 have made some errors with the right durations and number of
454 To save keystrokes and prevent errors Mudela
455 has some handy shortcuts. The simplest is the shortcut for
456 durations. You don't have to type the duration if it
457 is the same as the last duration entered. This saves a considerable
458 number of keystrokes, and thus reduces the potential for errors. The
459 previous example can be reduced to verb(
460 c''4 c'' <c'' g''> <c'' e'' g''>
461 <c'' e'' a''> <b' d'' a''> <b'2 d'' g''>
462 <a'4 d'' f''> <bes' d'' f''> <bes' c'' e''> <g' c'' e''>
463 <e' a' d''> <a g' cis''> <d'2 f' d''>
467 If you entered this, you probably made some little errors with the
468 right amount of quotes as well. To remedy this, mudela has another
469 feature called `relative octaves', which reduces the amount of quotes
470 needed. If you want to enter large pieces of music em(now) we
471 recommend you make an excursion to
472 bind(Section)ref(sec:relativeoctaves) and learn about relative
479 If you want to make some private notes about the Mudela code that you
480 entered, you can do so by inserting comments into your file. The
481 contents of these comments are ignored by LilyPond. Mudela has two comment
482 styles: line comments and block comments. The line comment
483 is introduced by the percent sign:
486 c''4 % shouldn't this be a different pitch?
489 Block comments are enclosed in code(%{) and code(%}).
494 Ludwig van Bavaria's original manuscript has an fffff dynamic sign.
495 Clearly one can see the onset of paranoid schizophrenia in the
496 composer from these subtle nuances in his writings.
502 sect(Adding nuances: articulation and dynamics)
504 Having just chords and notes does not give you real music. Real music
505 has more liveliness to it: music can have articulation, dynamics
506 (louder and softer), etc. This liveliness has notation, so LilyPond
507 can print it. We'll start out by explaining how to obtain the
508 smallest grains of nuance: the articulation of a single note. Articulation
509 is entered by writing a dash and the name of the desired articulation
510 mark. You have to add a backslash in front of the name to distinguish
511 it from the name of a note. mudela(fragment,verbatim)(
515 Typing a lot of staccato notes in this syntax will get tedious very
516 quickly. Therefore, Mudela has some handy abbreviations for
517 articulation marks such as staccato and tenuto. They are shown in the
522 \property Voice.textstyle = typewriter
528 c''4-^_"c''4-\\^{ }" s4 }
529 \paper { linewidth = 12.\cm; }})
533 Text and digits for fingering can be entered in the same manner: add a
534 dash and the text or digit to be printed:
535 mudela(fragment,verbatim)(
536 c''4-1 g''4-5 c''-"Sul tasto" )
537 Currently, the meaning of the
538 syntax `note-dash-digit/articulation/text' is just ``add a superscript to this
539 note.'' This is not in line with our goal to em(define) music with
540 Mudela. We hope that this will be fixed in a future version of the
541 language. In the meantime you can abuse this: the super- and
542 subscripts can be forced into up or down position respectively by entering an
543 a caret (code(^)) or an underscore, code(_) instead of the dash:
544 mudela(fragment,verbatim,center)(
545 c'4-^ c'4^^ c'''4-^ c'''4_^
548 Dynamic markings are another way to add a nuance to a note. They are
549 entered by adding the name for the dynamic sign after the note. You
550 should not enter a dash between the name and the note.footnote(This
551 is inconsistent. We hope that this will be fixed in a later
552 version of the language.)
553 mudela(verbatim,fragment)(
554 c4 \ff c4 \fp c4 c4 \ppp c4 c4 \sfz
558 sect(Bridging the notes: beams, slurs and ties)
560 Up till now most of the typesetting concerned simple fixed symbols
561 only. Now we turn to variable symbols: symbols that run from one note
562 to another. In LilyPond terminology, such a symbol is called a
563 em(spanner). To print a spanner, you have to attach a marker to the
564 note that begins it and to the one that ends it.
567 The first example of such a symbol is the slur. For the slur, the
568 start marker is the opening parenthesis. It won't be a surprise that
569 the stopping marker is the closing parenthesis.
571 mudela(fragment,center,verbatim)( c'4( )c'4 )
573 otice that the parentheses should be between the notes.footnote(The
574 location of the parentheses might be changed in a future version of
577 It is your job to make sure that each slur that you start also ends.
578 If it doesn't end, then Bad Things are likely to happen. The slur is
579 quite flexible: you can nest nop(slurs,)footnote(This is inconsistent when
580 compared to the syntax for articulation hints. This will probably be
581 fixed soon.) and you can connect a note with a slur on both the left and the
584 mudela(fragment,verbatim,center)(
585 c'4(( )c''4 )c'4( )g'4
588 Another spanner is the beam (see bind(Figure)ref(mud:beam)). It
589 indicates the duration of the connected notes, and thus it acts like an
590 extended version of the flag. Secondly, the pattern of
591 left/right-pointing beams hints at the metric structure of the
595 latexcommand(\begin{figure}[h])
597 mudela(fragment)([c'8 c'8] [c'16 c'16 c'16 c'16] [c'16. c'32 c'32 c'16.] )
598 latexcommand(\caption{Some beams})
601 latexcommand(\end{figure})
604 Strictly speaking, a beam is not a musical concept. The pattern of a
605 beam can be derived from the structure of the time signature and the durations
606 of the notes. It is merely a device that helps you understand the
607 rhythms notated. Unfortunately, LilyPond is not smart enough to insert
608 beams into your music on her own. You will have to instruct her by
609 marking the starting and stopping point of the beam with `code([)' and
610 `code(])' respectively, e.g.
612 mudela(fragment,verbatim,center)(
616 LilyPond has code that guesses what the pattern should look like, so
617 that you don't have to specify the beaming for complicated
618 patterns.footnote(Unfortunately the algorithm used is not foolproof yet:
619 code([c8. c32 c32]) will produce incorrect results.)
621 Again, it is your responsibility to make sure that you end every beam
624 A third spanner is similar to the slur: the tie. The tie looks like a
625 slur, but a slur connects whole chords, whereas the tie connects
626 note heads. Tied notes should be played as one long note.
627 In analogy with TeX()'s tie (which ties together words with a
628 space), LilyPond's tie is entered as a tilde, ~.
629 mudela(verbatim,center,fragment)(c''1 ~ c''4)
631 The input convention for the tilde is somewhat peculiar when used in
632 conjunction with chords. Internally, the extra information that is
633 represented by the tilde has to be attached to a note (or to a rest,
634 for that matter). For this reason, you can't put the tilde between
635 two chords (as in code( <c' g'> ~ <c' g'>)). The tilde sign must be
636 directly after a note of the chords. It does not matter which
637 one. The following example demonstrates this:
638 mudela(fragment,verbatim,center)(
639 <c'1 ~ g' es''> <c'4 g' es''>
645 Up till now, we only printed notes, and correspondingly only entered
646 notes. But notation contains many other constructs, constructs that
647 help you with reading those notes. Examples of such constructs are
648 clefs, time signatures, keys etc.
650 If you look carefully at the example in
651 bind(Figure)ref(fig:twinkle1), you will notice that the output
652 includes some bar lines and clefs, and that there are no references to
653 those in the input. They were generated automatically.
655 Not all such hints can be inserted automatically, and you can also
656 override some of the settings. This can be done by inserting various
657 commands between the music. The general form of these commands is
659 em(keyword) sc(arguments)
662 em(keyword)s are words that have a special meaning to the parser of
663 Mudela. Because the parser must be able to distinguish the keywords
664 from note names, they have to be preceded by a so-called escape
665 character, the backslash, `code(\)'. To separate the arguments from
666 any notes that might follow the arguments, you have to end your
667 command with a semicolon. An added benefit of this construction is
668 that the commands stand out between your notes, because of the
671 So the general form actually is `code(\keyword argument argument ... ;)'
672 Let us review these commands:
675 dit(code(\clef) var(clefname)) This command sets the current clef for notation,
676 i.e., a clef symbol is printed and the notes following this command
677 are shifted vertically. The argument is a string, the name of the
678 new clef. The default clef is the treble clef.
679 mudela(fragment,verbatim)(
684 dit(code(\key) var(pitch)) This command changes the current key signature. The
685 key signature is printed at the start of every line. The argument
686 is the name of the corresponding major key. The key of C-minor can
687 thus be specified as `code(\key es)'.
689 dit(code(\accidentals) var(pitchlist))
691 This command changes the current key signature. The signature is
692 given in the form of a list of accidentals, which can be useful for
693 unconventional keys. The key of C-minor can be specified as
694 `code(\accidentals bes es as)'. The command `code(\accidentals fis es
695 bis)' provides a more exotic example.
698 dit(code(\time) var(numerator)code(/)var(denominator))
699 This command chages the current time signature. LilyPond uses the
701 calculate where to place the bars that start a measure. These bars
702 in turn are the places where a system can be broken into lines.
704 The default value for this time signature is common time (4/4). You
705 can also tell this from the Twinkle ``Twinkle Little
706 Star'' example in bind(Figure)ref(fig:twinkle1). This
707 song actually has a 2/4 time signature, so a metrically more correct
708 version would start with as follows:
709 mudela(fragment,center,verbatim)(
710 \time 2/4; c'4 c' g' g'
714 dit(code(\cadenza) var(togglevalue)) When typesetting music without a
715 regular meter (such as an ad libitum cadenza), no bar lines should be
716 printed. In LilyPond you can achieve this by issuing the command
717 `code(\cadenza 1)': it turns off the automatically
720 You switch them on again with `code(\cadenza 0)', and then a bar line
721 is printed. LilyPond will act as if you are again at the start of a
724 dit(code(\bar) var(bartype))
725 This command lets you print special bar lines, such as repeats. You
726 can also use it to allow line breaks when entering cadenzas. The
727 argument var(bartype) is a string that describes what kind of bar line to print.
729 mudela(fragment,verbatim)(
730 \bar "|:"; c'4 \bar ":|:"; c'4 \bar ":|"; c'4 \bar "||";
731 c'4 \bar "empty"; c'4 \bar "|.";
733 The command `code(\bar "empty")' does not create any visible bar
734 line, but it does tells LilyPond to allow a linebreak
737 dit(code(\partial) var(duration)) some music starts with a measure that
738 isn't fully filled, a so-called upstep. The code(\partial) command
740 upsteps. The argument is a duration similar to the duration of a note.
742 mudela(fragment,verbatim)(
745 [d'8 dis'] e' c''4 e'8 c''4
748 dit(code(\grouping) var(durationslist)) sets the metric structure of the measure.
749 Its effect can best be shown by an example:
750 mudela(fragment,verbatim)(
760 In practice, you won't be needing this command very often: the
761 grouping is switched automatically when you issue a code(\time)
762 command. It is set to a combination of groups
763 of 2 and 3 beats, with as many groups of
764 3 as possible (in other words: 4/4 is divided in two times two beats
768 The commands that are described above aren't really music, but they
769 can be used in the same places as notes. This makes the grammar of the
770 language simpler. It is possible to put a command into a chord.
771 For example, the following two snippets of Mudela produce identical output.
779 sect(Complex music: more than one staff)
780 label(tutorial:more-staffs)
783 Now we explain how to typeset music that runs in multiple staffs.
784 Consider the following---somewhat unrealistic---example:
787 \type GrandStaff <e'4 {\clef bass; g4^""} >
790 The music consists of two notes. Perhaps this is sheet music for a
791 piano player, and one note is meant to be played with the left hand,
792 and the other with the right hand. That music would sound the same if
793 it were written as a single chord on a single staff, i.e.,
799 This is another example where we can see that there can be a difference
800 between a musical idea, and the way it is expressed in notation.
802 The Mudela construct for multiple staffs reflects the similarity
803 between the two examples: to get multiple staffs in Mudela you enter a
804 chord, with an additional instruction to tell LilyPond that the chord
805 does not represent notes stacked together, but staffs stacked
808 If a piece of music is to be interpreted as a staff, then this can be
809 expressed with the code(\type) construct. The following input says
810 ``the quarter note with pitch e should be put on a staff.''
816 The same can be done for the other note, i.e.,
822 If you want to stack these staffs, you must create a chord of both:
830 This looks reasonable, but the effect of this input is not what you
831 might expect (try it!). When interpreting this chord LilyPond will
832 start with the first entry. She'll look for a (nameless) staff. Such a
833 staff is not found, so it is created. On this staff the code(e) note
834 is put. When the second code(\type) entry is read, LilyPond will
835 start looking for a nameless staff. The staff that contains the
836 code(e) is found, and the code(g) is put there as well.
838 The correct solution is to label both code(\type) constructs with
839 different names, for example code(trebleStaff) and code(bassStaff).
840 This makes LilyPond distinguish between them, and create two staffs:
842 mudela(verbatim,fragment)(
843 < \type Staff = trebleStaff e'4
844 \type Staff = bassStaff g4
848 The names that you choose do not matter just as long as they are
849 different. This is almost right, except for the brace at the left and
850 the clef of the second staff. The bass clef will be taken care of in
851 the next section. If you want a brace, then you have to tell LilyPond
852 that the chord you just formed is to be interpreted as a so-called
853 grand staff. This is also done with the code(\type) command.
854 mudela(verbatim,fragment)(
856 \type Staff = treblestaff e'4
857 \type Staff = bassstaff g4
861 sect(Appending instead of stacking: sequential music)
862 label(tutorial:voice)
864 The previous section dealt with a pretty hypothetical situation: sheet
865 music with two staffs and each staff containing only one single note.
866 In real-life situations staffs contain more than one note. They
867 contain music that has to be played in sequence. A staff can contain
868 a em(voice). We haven't learned how to make a voice yet: we need a
869 new construct to express this notion of `voice'.
871 The construct is called em(sequential) music. A list of musical
872 objects (e.g., notes, chords or commands) can be made into sequential
873 music by enclosing the list in braces; for example:
875 mudela(fragment,verbatim,center)(
878 mudela(fragment,verbatim,center)(
883 We could have called this construct more colloquially `voice', but
884 this would cause confusion later on, when a second kind of voice
885 enters the scene. Similar confusion might arise from the word
886 `chord', therefore from now on, we will talk about `simultaneous
887 music', when we refer to items enclosed in < and >.
890 The notion of a em(new) construct needs some explanation: we have been
891 using sequential music all the time, except that it was hidden in the
892 red tape in bind(Section)ref(tutorial:introduction).
896 If we want to put whole voices onto a staff, then we have to
897 substitute sequential music for the single notes in the example from
898 the previous section. A code(\clef) command in the second piece of
900 music will also set the clef in
902 mudela(fragment,verbatim)(
904 \type Staff = treblestaff { e'4 f'}
905 \type Staff = bassstaff {\clef "bass"; g a }
909 COMMENT(You can nest simultaneous music and chords in any way you want. If
910 you are interested in the entire story, you should consult
911 bind(Chapter)ref(chap:features), which has a grammar in
912 bind(Section)ref(sec:grammar).)
914 sect(Notation context)
916 This section is about translation contexts, a topic of LilyPond that
917 is somewhat advanced. You don't have to understand this to use
918 LilyPond to print simple music. If you don't want to typeset fancy
919 polyphonic music or tweak the LilyPond notation engine, you can skip
920 the next two sections.
922 In bind(Section)ref(tutorial:more-staffs) it was explained, that there
923 are more ways to notate a simple chord: as a single voice on a single
924 staff or in multiple staffs (and we'll soon see, that you can typeset
925 it as multiple voices on a staff). Obviously the concept of staff is not
926 really something musical. But what is it then?
929 The most simplistic explanation is: a staff is a peculiarity of the
930 notation system. In other words, a staff is a graphic device, a
931 special picture of five lines on which one can print note heads. To
932 avoid confusion, we will call this view on the concept of staff
933 `staff symbol' from now on.
936 There is more to it than meets the eye and mind. A staff
937 contains---besides a staff symbol--- some more components:
939 it()A staff can a have a key signature (printed at the left)
940 it()A staff has bar lines
941 it()A staff has a clef (printed at the left)
943 To explain what a staff really is, we'll try to print music without
944 these components. If these components aren't printed, it is still
945 possible to print music:
947 \melodic \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
950 Staff = \translator {
951 \type "Line_group_engraver_group";
953 defaultclef = violin;
955 \consists "Timing_engraver";
956 \consists "Separating_line_group_engraver";
963 As you can see, one can still make out the general form of the melody
964 and the rhythm that is to be played, but the notation is difficult to
965 read and the musical information is not complete. The stress pattern
966 in the notes can't be deduced from this output. For this, we need a
971 \melodic \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
974 Staff = \translator {
975 \type "Line_group_engraver_group";
976 defaultclef = violin;
977 \consists "Time_signature_engraver";
978 \consists "Separating_line_group_engraver";
984 Technically speaking you know where the strong and weak beats are, but
985 it is difficult to find them quickly. Bar lines help you in finding
986 the location within the measure of the notes:
989 \melodic \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
992 Staff = \translator {
993 \type "Line_group_engraver_group";
994 defaultclef = violin;
995 \consists "Bar_engraver";
996 \consists "Time_signature_engraver";
997 \consists "Separating_line_group_engraver";
1003 We can remedy part of the difficulties with reading pitches by adding a staff
1007 \melodic\relative c' { \time 2/4; g'4 c,4
1008 a'4 f4 e c d2 } \paper {
1010 Staff = \translator {
1011 \type "Line_group_engraver_group";
1013 defaultclef = violin;
1014 \consists "Bar_engraver";
1015 \consists "Time_signature_engraver";
1016 \consists "Staff_sym_engraver";
1017 \consists "Separating_line_group_engraver";
1024 This makes the output decidedly easier to read, but you still don't
1025 know what the pitches of the notes above are. So this is still not
1026 enough. But suppose you see the following notation:
1028 \melodic \relative c' {\clef alto; \time 2/4; g'4 c,4 a'4 f4 e c d2 }
1031 Staff = \translator {
1032 \type "Line_group_engraver_group";
1034 defaultclef = violin;
1035 \consists "Bar_engraver";
1036 \consists "Time_signature_engraver";
1037 \consists "Clef_engraver";
1038 \consists "Staff_sym_engraver";
1039 \consists "Timing_engraver";
1040 \consists "Separating_line_group_engraver";
1047 Now you know the pitch of the notes: you look at the start of the line
1048 and see a clef, with this clef, you can determine the notated pitches.
1049 You have found the em(context) in which the notation is to be
1052 So the context determines the relationship between a piece of music
1053 and its notation: you, the reader, use context to deduce music from
1054 notation. Because LilyPond is a notation ``writer'' instead of a
1055 reader, context works the other way around for Lily: with context a
1056 piece of music can be converted to notation.
1057 The components of a staff form context, and context is needed to read
1058 and write notation. This motivates the following definition.
1061 A bf(notation context) is a conversion from music to notation.
1064 The example focused mainly on on staffs, but a staff is not the only
1065 type of notation context. Notation contexts may be nested: you can
1066 print polyphonic music by putting multiple `Voice' contexts in one
1067 `Staff' context. The arguments of the code(\type) command (Staff,
1068 GrandStaff) were in fact all names of different contexts.
1069 The notions of ``current clef'' and ``current position within the
1070 measure'' are all properties of notation contexts. Commands like
1071 code(\clef) and code(\cadenza) change these properties.
1074 The following is a list of the contexts that are supported by
1078 dit(Voice) The code(Voice) context is a context that corresponds to a
1079 voice on a staff. This context handles the conversion of noteheads,
1080 dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests
1082 dit(Staff) The code(Staff) context handles clefs, bar lines, keys,
1083 accidentals. A code(Staff) context can contain multiple code(Voice)
1086 dit(RhythmicStaff) The code(RhythmicStaff) context is like the staff,
1087 but much simpler: the notes are printed on one line, and pitches are
1088 ignored. code(RhythmicStaff) can contain code(Voice) contexts.
1090 dit(GrandStaff) A code(GrandStaff) context contains code(Staff)
1091 contexts, and it adds a brace to the output at the
1092 nop(left.)footnote(This is a major deficiency in the current
1093 implementation. Currently stems,
1094 slurs and beams cannot be printed across two staffs.
1095 In reality, a grand staff is a hybrid of one big staff and two stacked staffs.)
1097 A code(GrandStaff) context can contain multiple
1098 code(Staff)s. Typically, it will contain two code(Staff)s, one
1099 treble staff, and one bass staff. The bar lines of the contained
1100 staffs are connected vertically.
1102 dit(StaffGroup) A code(StaffGroup) context contains code(Staff) or
1103 code(Lyrics) contexts, and prints a bracket at the left. The bar
1104 lines in the participating staffs are connected.
1106 dit(Lyrics) As its name suggests, The code(Lyrics) context deals with
1107 typesetting lyrics. This topic will be covered in
1108 bind(Section)ref(tutorial:lyrics).
1110 dit(Score) The code(Score) context is the toplevel context: no context can
1111 contain a code(Score) context. The code(Score) context handles the
1112 administration of time signatures. It also makes sure that items
1113 such as clefs, time signatures, and key-signatures are aligned across staffs.
1115 The code(Score) can contain code(Staff), code(StaffGroup), code(Lyrics), code(GrandStaff) and
1116 code(RhythmicStaff) contexts.
1118 COMMENT(do ChoireStaff)
1122 Later on, in bind(Section)ref(tutorial:engravers) we will
1123 explain how you can create your own contexts.
1125 If you are familiar with structured documents (like HTML, SGML or
1126 LaTeX()), you might see the analogy of a context with a stylesheet: a
1127 stylesheet is neither presentation nor information, but rather a
1128 recipe em(how) a specific piece of information should be presented.
1129 Analogously, a notation context is neither music nor notation, but the
1130 conversion between the two. The big difference with text is that in
1131 music notation the elements provided by context are essential to
1132 understanding what is notated.
1136 sect(Polyphonic music (or: Notation context properties))
1138 In the last section we explained that a notation context can have
1139 properties that influence the conversion from music to notation. A
1140 simple example of such a property is the clef: the type of clef partially
1141 determines the vertical position of note heads in a staff. Some of
1142 these properties can be modified by commands such as code(\clef) and
1143 code(\time). But there is more: notation contexts also have
1144 properties are settable in a generic fashion. We will demonstrate
1145 this feature by printing multiple voices on a staff.
1147 In polyphonic (keyboard) music and orchestral scores often more than
1148 one voice is printed on one staff. We'll explain how to achieve this
1149 effect with LilyPond. The effect is not unlike the two stacked staffs
1150 from bind(Section)ref(tutorial:more-staffs), except that we don't want
1151 to stack staffs but voices. Thus, the general template is the following:
1154 \type Voice = one ...
1155 \type Voice = two ...
1159 On the ellipsis there should be music going from left to right, in
1160 otherr words, there should be sequential music, notes enclosed in
1161 braces. Let us try the following simple melodies:
1163 mudela(fragment,verbatim)(
1165 \type "Voice" = "one" { r4 as'4 () as'4 g'4 }
1166 \type "Voice" = "two" { g'2 f'4 e'4 }
1169 As you can see the result is not quite perfect. The notes on the last
1170 two beats look like plain chords and not like separate voices. What
1171 really happened was that the stems of the upper and lower voices were
1172 printed on top of each other. If you have tried running this example, you will probably
1173 have noticed a complaint about ``too many
1174 clashing notecolumns'' during the LilyPond run.
1175 This complaint refers to the overlapping stems.
1177 To remedy this, engravers traditionally make the stems of the upper
1178 and lower voice point in different directions: the stems of the lower
1179 voice point down, and the stems of the upper up, as shown in
1180 bind(Figure)ref(tutorial:multi-voice-fig).
1182 Surely the direction of a single stem is a property of the stem as a
1183 graphical object. But the fact that all of the stems in a voice point
1184 in the same direction is not directly graphical. Since this is a
1185 property shared by all the stems in the voice, it is logical to
1186 consider this property to be a property of the context code(Voice).
1187 And this is how it's done in LilyPond: the context code(Voice) has an
1188 attribute whose value is the direction to use
1189 for stems. You can change it to `up'
1190 by issuing the following phrase:footnote(The name code(ydirection) is
1191 no mistake. The property also controls the up/down directions of
1192 super-/subscripts, slurs, ties, etc.)
1195 \property "Voice"."ydirection" = "1"
1198 This command should be read as ``change the property called
1199 code(ydirection) within the current code(Voice) context to the value
1200 code(-1).'' For the property code(ydirection) the value code(1) means
1201 `up', and code(-1) means `down'. The proper way to code the
1202 polyphonic example is given in bind(Figure)ref(tutorial:multi-voice-fig).
1204 latexcommand(\begin{figure}[h])
1205 mudela(fragment,verbatim,center)(
1207 \type "Voice" = "one" {
1208 \property Voice.ydirection = "1"
1209 r4 as'4 () as'4 g'4 }
1210 \type "Voice" = "two" {
1211 \property Voice.ydirection = "-1"
1215 latexcommand(\caption{multiple voices})
1216 label(tutorial:multi-voice-fig)
1217 latexcommand(\end{figure})
1219 Other properties can also be set, and they can be within different
1220 contexts. In general, you can set a property by specifying
1221 code(\property) var(contexttype)code(.)var(propertyname) code(=)
1222 var(value). Both var(ContextType), var(PropertyName) and var(Value)
1225 The effect of a property is pretty much hardwired into the
1226 implementation (and thus subject to change), so we will not deal with
1227 all the possible properties in detail. Among other characteristics that
1228 can be set are the layout of slurs and beams. The initialisation file
1229 file(property.ly) explains most properties.
1231 We conclude this section with another example of a context property.
1232 Polyphonic music that has three or four voices can't be printed by
1233 simply changing the directions of the stems for each voice, obviously.
1234 Traditionally, some chords are shifted horizontally to print if this many
1235 voices have to be printed.
1236 LilyPond can also do this, and the property that controls the
1237 horizontal shifting is called code(hshift). The notes in a
1238 code(Voice) context that has code(hshift) set to a true value (i.e.,
1239 non-zero or non-empty), will be shifted horizontally in the case of a
1240 collision. The following example demonstrates the effect.
1242 mudela(fragment,verbatim)(
1244 \type "Voice" = "one" {
1245 \property Voice.ydirection = "1"
1246 r4 as'4 () as'4 g'4 }
1247 \type "Voice" = "two" {
1248 \property Voice.ydirection = "1"
1249 \property Voice.hshift = 1
1251 \type "Voice" = "three" {
1252 \property Voice.ydirection = "-1"
1253 [d'8 dis'] [d' cis'] [c' b] c'4
1259 label(tutorial:lyrics)
1261 Now for something completely different: Lyrics. Lyrics are also
1262 considered to be music, although a lyric by itself does not have any
1263 pitch. Producing lyrics has two aspects. First, you have to enter the
1264 text, i.e., the syllables along with their durations.
1265 After this, you have to specify how to convert these to graphics.
1267 Lyrics consist of syllables, which are strings together with
1268 durations. Previously we only entered note names, so for entering
1269 lyrics we have to instruct LilyPond that what we enter are not note
1270 names but words---or rather: strings. This instruction is the keyword
1271 code(\lyric). After entering this keyword you can enter a musical
1272 construct---sequential music, simultaneous music, code(\type)
1273 entries, etc.--- but with syllables in stead of pitches. For example:
1274 verb( \lyric { 'got8 me on my knees4, Le-8 lie! })
1276 The effect of code(\lyric) can be compared with the effect of the
1277 doublequote character, code("), for it also changes the lexical
1278 meaning of spaces and characters. This mode is another example of a
1279 handy input feature of the language.
1281 Next comes the conversion to notation. LilyPond can't (yet) figure
1282 out that lyrics need different treatment than notes. As a result, the
1283 default conversion will try to put the text you entered as note heads
1284 onto a staff, and this will fail. This default must be overriden with
1285 a code(\type) keyword. Printing syllables of text in a line is done
1286 by a context called code(Lyrics). You can select this context with
1287 the code(\type) keyword. Here is a simple example:
1289 mudela(fragment,verbatim)(
1290 \type Lyrics \lyric { 'got8 me on my knees,4 Le-8 lie! })
1292 The result is technically more or less correct, but without a melody it
1293 just doesn't work, so let's add a blob of cream:
1294 mudela(fragment,verbatim)(
1296 \type Staff { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1297 \type Lyrics \lyric { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
1301 The strings that makes up each syllable in the lyrics block are passed
1302 along to TeX() verbatim, so if you are proficient with TeX() you can
1303 do various nifty things. Just keep in mind that a syllable either
1304 starts with a letter (a character in the range `code(a)' to `code(z)'
1305 or `code(A)' to `code(Z)'), or it is a string enclosed quotes. It ends
1306 with either a number for the duration, or a space. A last feature
1307 that should be mentioned is the space-lyric: if you want to enter
1308 a single ``syllable'' that consists of multiple words, i.e., words
1309 separated by spaces, you should use an
1310 underscore instead of a space. All these tricks are demonstrated in
1311 the following example:
1314 \type Lyrics \lyric { 'got_m\textbf{e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1315 \type Lyrics \lyric { 'got_m{\bf e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1318 mudela(fragment,verbatim)(<
1319 \type Staff { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1320 \type Lyrics \lyric { 'got_me4 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
1324 The spacing in the above example is a bit skewed because Lily can't
1325 tell that the long syllables you entered are not ordinary characters,
1326 but expand to really small symbols.
1331 COMMENT(Rood is de kleur van geluk.)
1332 COMMENT(Dat geldt ook voor haar.)
1335 sect(Toplevel Mudela)
1337 Now the time has come to unravel the red tape that we have hidden from
1338 you in the introduction. Mudela has a hierarchical structure for we
1339 have seen that sequential and simultaneous music can be nested.
1340 Mudela also has other `blocks' that can be nested. The general syntax
1341 for a block is code(\keyword { ... }).
1343 When you run LilyPond, what happens is that you define music, and
1344 specify one (or more) conversions to apply to that music, for example
1345 a conversion to notation. This is done by putting the definition of
1346 the music and the definition of the conversion together in a
1347 code(\score) block, e.g.,
1354 This is almost the context that should be around all
1355 of the previous examples. The precise context reads thus:
1361 On the ellipsis, you entered what shown as the example input.
1362 You can see that in the
1363 above example, the code(\melodic { ... }) forms the music, the
1364 code(\paper {}) is a conversion to paper (notation, that is). The
1365 code(\paper) definition is copied from a default definition
1366 (which is in the initialisation file file(paper16.ly)).
1367 The paper part also contains
1368 the definition of the contexts.
1370 The keyword code(\melodic) is analogous to the code(\lyric) keyword. It
1371 will switch the tokenizer into a mode that interprets plain words as
1372 note names. If it can't recognize the words as a note name, it will
1373 assume that they are strings. That is the reason why you can write
1374 code(\clef bass) in stead of code(\clef "bass"); most of the strings
1375 in code(\melodic) mode can be written without quotes.
1377 The braces that you see after the code(\melodic) keyword are the
1378 braces that are around sequential music. Because of these braces, the
1379 sequences of notes in our simple examples were sequential (and not
1380 simultaneous). As a result the notes were printed from left to right,
1386 Now that we are comfortable with the toplevel entries in a mudela
1387 file, we can investigate some more of the recreations on toplevel, in
1388 particular em(identifiers). Generally you can define an identifier by
1389 entering code(identifierName = ... )
1390 where there can be a variety of things on the ellipsis.
1392 Here is a (partial) list of what you can abbreviate with identifiers
1395 it()The code(\score) block
1396 it()The code(\paper) block
1397 it()The code(\midi) block (to be explained in
1398 bind(Section)ref(tutorial:sound))
1399 it()Music (sequential music, simultaneous music etc.)
1402 it()Translators (to be explained in bind(Section)ref(tutorial:engravers))
1408 to the abbreviated entity, you must precede code(identifierName)
1409 with a backslash, i.e., code(\identifierName). For example:
1411 czerny = \melodic { [c16 g e g] }
1413 \melodic \type GrandStaff <
1415 { \clef bass; \czerny \czerny \czerny \czerny}
1419 stem_length = 12.0*\internote;
1426 Another interesting feature of this example are the assignments within
1427 the paper block. Some blocks, such as code(\paper), have a scope of
1428 their own. In the case of the code(\paper) block, these variables
1429 influence the characteristics of the output. As is shown, you can
1430 tune quantities like the stemlength, and enter simple expressions.
1431 The purpose of the negative linewidth is to prevent the music from
1432 being justified. The identifiers that are meaningful are for the
1433 paper block is strongly implementation dependent, so they will not be
1434 listed here. Moreover, since most of the values are predefined to
1435 sensible defaults, there usually is no need to tune these values.
1437 Recall the properties of a context, that could be set with
1438 code(\property). It is a very general mechanism to tune the output of
1439 the music, that is neatly separated from the real music.
1440 Unfortunately, it is not convenient to type or read, and the precise
1441 effect of a setting property isn't always apparent from its
1442 definition. To remedy this, we can use an identifier to capture the
1443 meaning of a code(\property).
1446 stemup = \property Voice.ydirection = "1"
1447 stemdown = \property Voice.ydirection = "-1"
1448 shift = \property Voice.hshift = "1"
1450 \type "Staff" \melodic <
1451 \type "Voice" = "one" {
1453 r4 as'4 () as'4 g'4 }
1454 \type "Voice" = "two" {
1458 \type "Voice" = "three" {
1460 [d'8 dis'] [d' cis'] [c' b] c'4
1463 \paper{ linewidth = -1.0\pt; }
1467 Several abbreviations like code(\stemup) are defined in the
1468 standard initialisation file file(property.ly). Setting or changing
1469 context properties can have a similar effect as the commands that were
1470 discussed in bind(Section)ref(sec:commands). Don't be fooled by the
1471 similarity in appearance between a declared property-setting entry
1472 and a real command. Real commands are hardcoded into the language
1473 and they have to be terminated by semicolons.
1475 You can also use identifiers to break up the heavy nesting that can occur
1476 in the code(\score) block. Another useful application is
1477 parametrisation of the music: if you use identifiers in the
1478 code(\score) block, you can make variations of the music by simply
1479 redefining those identifiers. One particular application of this is
1480 part extraction: by using identifiers and redefining them, one can
1481 print extracted parts and a full orchestral score from the same
1487 label(tutorial:sound)
1489 You get output by combining music with definition a conversion to
1490 output. Up till now we have only focused on the graphic output of
1491 traditional engraving. But there is no reason why that should be the
1492 only form of output for music. LilyPond currently supports one other
1493 conversion: the conversion from abstract music to sound. You can have
1494 LilyPond play the music that you entered. The format that is used
1495 for this output is MIDI.
1497 The only information that you need to enter is the
1498 nop(tempo)footnote(Unfortunately,
1499 this the only thing that can be tuned at this
1500 time. This is a limitation: the tempo of music can vary throughout
1501 the music.) for the performance. The syntax for the tempo is
1502 code(\tempo )var(duration) = var(beatsperminute);), for example:
1506 \midi { \tempo 4 = 76; }
1510 The most useful purpose of this sound output is to prooflisten your
1511 files: typing errors (especially if they involve accidentals) stand
1512 out when you listen.
1513 The output was implemented in a very rudimentary manner, so it is
1514 probably not worth listening to for any other reason.
1517 sect(Contexts revisited: engravers)
1518 label(tutorial:engravers)
1520 As was promised, we will now take a dive into the more wizardrous parts
1521 of LilyPond: redefining (notation) contexts. We previously explained
1524 it()is a conversion from music to notation,
1525 it()can contain other contexts
1526 it()handles specific notation constructs
1529 This characterization almost automatically explains what the definition of a
1530 context should look like:
1532 it()It should be part of the ``notation output definition,'' i.e., the
1535 It should contain a specification of what other contexts may be contained
1536 in the context we're defining.
1538 It should contain a list of the notation constructs to be
1542 In practice, the context definition
1547 \type "Engraver_group_engraver";
1556 propertyname = "value";
1557 propertyname = "value";
1561 This is encoded by the
1563 The code(\translator) keyword opens the block for translation (or
1564 context) definition. The code(\type) keyword explains to Lily that
1565 the context should be formed by taking an (empty) instance of
1566 code(Engraver_group_engraver). The code(Engraver_group_engraver) is a
1567 C++ class from the source code to Lily. The code(\accepts) entries
1568 explain what kind of contexts this context could contain. If we were
1569 to define a context for a staff, the definition would typically
1570 contain code(\accepts "Voice";).
1572 The code(\consists) entries specify which notation constructs should
1573 be handled. This needs a little explanation: LilyPond contains the
1574 code for quite a large number of basic building blocks for notation
1575 generation, and each building block handles only one notation
1576 construct. The name of such a building block is `engraver'. You can
1577 specify which notation construct a context should handle by specifying
1578 which engravers should be part of the context. The code(\consists
1579 "Foobar") entry really means ``add an instance of code(Foobar) to the
1580 translation group.''
1583 For example if this context should print time signatures, the definition
1584 should include `code(\consists "Time_signature_engraver";)'. Again
1585 code(Time_signature_engraver) is a class from the source code of LilyPond.
1589 Finally, one can pre-set some properties in a context definition.
1591 As a practical example, we will show you how to typeset polymetric
1592 music, i.e., music where the meter can differ for each staff. The
1593 solution is not very complicated: normally all timing information
1594 (time signature, rhythmic grouping) is synchronised across each staff. In
1595 LilyPond this is expressed by having only one registration for timing
1596 information for all staffs. To be precise, there is only one
1597 code(Timing_engraver), and it is located in the top level context, the
1598 code(Score) context.
1600 All staffs use the information in the global code(Timing_engraver)
1601 for generating bar lines and time signatures. In polymetric music, this timing
1602 information can be different for every staff, so we should redefine
1603 the code(Staff) context to include and the code(Score) context to exclude the
1604 code(Timing_engraver).
1607 polymetricpaper = \paper {
1608 Score = \translator {
1609 \type Score_engraver;
1610 \consists "Score_priority_engraver";
1611 \consists "Priority_horizontal_align_engraver";
1612 \consists "Vertical_align_engraver";
1613 % \consists "Timing_engraver"; % removed Timing_engraver
1617 Staff = \translator {
1618 \type "Line_group_engraver_group";
1620 defaultclef = violin;
1622 \consists "Bar_engraver";
1623 \consists "Clef_engraver";
1624 \consists "Key_engraver";
1625 \consists "Local_key_engraver";
1626 \consists "Time_signature_engraver";
1627 \consists "Timing_engraver"; % added Timing_engraver
1628 \consists "Staff_sym_engraver";
1629 \consists "Separating_line_group_engraver";
1636 \type Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1637 \type Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1639 \paper { \polymetricpaper
1645 As you can see, we used the identifier code(polymetricpaper) to break
1646 up the large score block. More of these context definitions appear in
1647 the standard initialisation file file(engraver.ly).
1649 sect(Urtexts and context selection)
1650 label(tutorial:urtext)
1652 In bind(Section)ref(tutorial:more-staffs), we have shown you how to make
1653 multiple staffs, and explained that you have to label every staff (or
1654 more precisely: different contexts), to make sure that new ones are
1655 created when you need them. In this section, the real power of this
1656 mechanism will unveiled.
1658 By naming other contexts that you create, you can reference other contexts
1659 than the current context from within the music. For example, from within the music that you
1660 enter for staff code(One), one could enter a small piece of music,
1661 and send it to staff code(Two), e.g.,
1662 mudela(fragment,verbatim)(
1664 \type Staff = one { c''4 \type Staff = two { c4 c4 } c''4 }
1665 \type Staff = two { \clef bass; g,4 g,4 g,4 g,4 }
1670 Another useful application of this feature is making Urtexts.
1671 em(Urtext) is the German word for `original text'. The Urtext
1672 edition of a piece of music, is an edition that reflects the original
1673 writing of the composer. Such editions are useful for musicologists,
1674 and performers that want to perform authentic interpretations. However,
1675 for mere mortals, the Urtext can be quite hard to read. It might not
1676 contain fingering and beaming, and typically it is full of footnotes.
1677 Moreover, common interpretations may have emerged---after the composer
1678 died. For this reason, the music that can be had as Urtext usually is also
1679 available in enhanced and edited editions.
1681 The mechanism of context selection can be used to fabricate an Urtext
1682 and an edited edition from em(one source). We will use the first few
1683 bars of bind(J.)bind(S.)Bach's lovely Cello suite bind(no.)I to
1684 demonstrate this. The example makes heavy use of space rests: a space
1685 rest is a like a rest that doesn't print anything. It can be used as
1686 a placeholder, to attach articulation marks to. It is entered as a
1687 note with the name code(s).
1690 bach = \melodic { [c16 g e' d'] [e' g e' g] }
1692 staffStuff = \melodic { \clef bass; \time 4/4; s1 \bar "|."; }
1694 slursOne = \melodic { s16( s s s s16 s s )s }
1695 slursTwo = \melodic { s16-. s s() s s16() s s ()s }
1698 { < \type Voice = celloVoice { \bach \bach }
1699 \type Voice = celloVoice { \slursOne \slursOne }
1703 \type Voice = celloVoice { \bach \bach }
1704 \type Voice = celloVoice { \slursTwo \slursTwo }
1712 The slurs that you define should be put on the music that is defined
1713 by the code(\bach) identifier. By labeling a code(Voice) context, and
1714 directing both the articulation and the notes to that same code(Voice)
1715 context, the articulation is put over the right notes.
1719 label(tutorial:more-grammar)
1721 COMMENT(In this section, we will complete the grammar for Music that was
1723 One of the things that you can do with music is
1724 em(transposing) it. If you want to transpose a piece of music, then
1725 you should prefix the keyword code(\transpose) along with the pitch
1726 (relative to the central C) for the transposition.footnote(the
1727 code(\type Staff) is to make sure that no separate staffs are created
1728 for the code(\scale) and code(\transpose cis' \scale) part.)
1732 scale = \melodic \relative c' { [c8 d e f] }
1735 \type Staff { \scale \transpose cis' \scale }
1737 \paper { linewidth = -1.0; }
1741 sect(Staff switching)
1743 We have seen that contexts can be nested. This means that they form a
1744 tree. It is possible to edit this tree: for example, a code(Voice)
1745 context can be taken out of a code(Staff) context, and put into
1746 another. This has the effect of the voice switching staffs (something
1747 that often happens in keyboard music). The syntax for this operation
1748 with these particular contexts is code(\translator Staff = newStaffName).
1750 The effect is analogous to the first example in section
1751 ref(tutorial:urtext), but with the code(\translator) construction it
1752 is possible to split the real music and the commands that determine in
1753 which staff the music is printed. For example:
1758 aVoice = \type Voice = voiceA \melodic { c''4 c4 c4 c''4 }
1759 bVoice = \type Voice = voiceB \melodic { g,4 g,4 g,4 g,4 }
1761 % staff switching stuff
1762 switch = \type Voice = voiceA \melodic { s4 \translator Staff = staffB s4
1763 s4 \translator Staff = staffA s4 }
1767 \type Staff = staffA < \aVoice \switch >
1768 \type Staff = staffB < \bVoice \clef bass; >
1770 \paper { linewidth = -1.; }
1774 Don't try to switch staffs when you are in the middle of a slur or
1775 beam, though. It doesn't work yet.
1777 sect(Hairy durations: triplets)
1779 In the previous section we explained an operation that changes the
1780 pitches of music, transposition. In this section we will explain an
1781 operation that modifies the duration of the notes that you enter.
1782 When notes are part of a triplet, then the real of duration of the
1783 notes are 2/3 part of what their shape indicates:
1785 \[/3 c'4 c'4 c'4 \]/1
1788 To support this notion, Mudela allows you to modify the duration of a
1789 note by multiplication or division. A code(c'4) note that would be in a
1790 triplet is written as code(c'4*2/3). If you sequence a few of these
1791 notes, you get a triplet.footnote(We added a normal staff in the example to
1792 show the difference.)
1793 mudela(fragment,verbatim)(
1794 < \type Staff = staffA { c'8*2/3 c'8*2/3 c'8*2/3 c'4}
1795 \type Staff = staffB { c''8 c''8 c''4 } >)
1797 LilyPond knows that these notes are no normal eighth notes, but the
1798 reader doesn't yet. To help the reader a beam or a bracket with a `3'
1799 should be printed. The special beam command `code([2/3)' and the
1800 matching close beam `code(]1/1)' will take care of that, and
1801 they also abbreviate the code(*2/3) part. If you want brackets in
1802 stead of beams, you can use `code(\[2/3])' and `code(\]1/1)'.
1803 mudela(fragment,verbatim)(
1804 < \type Staff = staffA {
1805 [2/3 c'8 c'8 c'8 ]1/1
1806 \[2/3 c'8 c'8 c'8 \]1/1
1808 \type Staff = staffB { [c''8 c''8 c''8 c''8] }
1811 Other tuplets can be entered in the same way.
1812 mudela(fragment,verbatim)(
1813 < \type Staff = staffA {
1815 [7/6 c'8 c'8 c'8 c'8 c'8 c'8 ]1/1
1817 \type Staff = staffB {
1819 [c''8 c''8 c''8 c''8 c''8 c''8 c''8] } >
1822 For your convenience, code([2/3) can be further abbreviated to code([/3), and
1823 you can abbreviate code(]1/1) on the closing beam marker to code(]/1).
1825 mudela(fragment,verbatim)(
1826 < \type Staff = staffA {
1827 [/3 c'8 c'8 c'8 ]/1 c'4
1829 \type Staff = staffB { [c''8 c''8] c''4 } >
1833 bf(Important) the construct with code([/3) and
1834 code([/1) is a hack that sets a mode in the parser. This means that
1835 verb(id = \melodic { c8 c8 c8 }
1836 notATriplet =\melodic { [2/3 \id ]1/1 })
1837 does not produce a triplet. It will hopefully
1838 soon be replaced by a construction that mixes more elegantly with the
1842 sect(Shortcuts for octaves)
1843 label(sec:relativeoctaves)
1845 Plain Mudela contains a lot of quotes to get the octaves right. This
1846 need for quotes can be reduced: most of the pitch intervals in
1847 conventional music are small. Therefore, it makes sense to leave out
1848 the quotes when the interval is small. We have built a mode that does
1849 exactly this. It is called the relative mode for octaves. You can
1850 switch it on by entering code(\relative). Then LilyPond will
1851 interpret every note as if they mean the note with the same name
1852 closest to the previous. You have to specify the first pitch because
1853 the first note of a list obviously has no predecessor. So, you can
1854 enter a scale without using octavation quotes, e.g.,
1856 mudela(fragment,verbatim)(
1857 \relative c' { c d e f g a b c }
1860 For chords, the relative mode works slightly differently. In a
1861 sequence of chords, the first note of a chord gives the starting point
1862 for the next chord. We can demonstrate this with our twinkle twinkle example
1866 <c e a> <b d a'> <b2 d g>
1867 <a4 d f> <bes d f> <bes c e> <g c e>
1868 <e a d> <a, g' cis'> <d2 f d'>
1872 LilyPond converts any music with code(\relative) prepended to absolute
1873 music immediately when it is read. Internally it is stored it in
1874 absolute pitches. Since the tutorial mainly deals with how to specify
1875 musical information, and not how to enter it conveniently, the
1876 tutorial doesn't use it.
1880 label(tutorial:large-pieces)
1882 In our quest for a clean and powerfull music language, we took the effort
1883 of entering some larger pieces of music as well. From this we learned
1884 certain things that lead to direct improvements of Mudela, such as the
1885 relative mode. We also gained some practial experience, that resulted in a
1886 compilation of tips that may be of use to you.
1888 Entering a large piece of music will often imply the need to produce a
1889 conductor's score, as well as individual parts for all instruments. This
1890 can most easily be achieved making use of identifiers and including mudela
1893 subsect(Identifiers)
1895 Briefly introduced before, identifiers are your biggest help in structurising
1896 a large piece of music. As an example, we'll consider a string quartet.
1897 In short, it will look like this: verb(
1898 global = \melodic{ }
1899 violinoOne = \melodic \relative c { .. }
1900 violinoTwo = \melodic \relative c { .. }
1901 viola = \melodic \relative c { .. }
1902 violoncello = \melodic \relative c { .. }
1905 The code(\global) part contains everything that is global, i.e., the
1906 same, for each instrument. This may include time signature, key, repeat
1907 signs, different bar types, time signature- and key changes, rehearsal
1910 For each instrument, you'll have something vaguely resembling verb(
1911 violinoOneStaff = \type Staff = violinoOne <
1912 \property Staff.midi_instrument = "violin"
1913 \property Staff.instrument = "Violino I"
1914 \property Staff.instr = "Vl. I"
1921 [Versions, relative mode,
1922 barchecks, splitting of files]
1924 subsect(Including Mudela files)
1925 ref(subsect:include)
1927 You can include other Mudela files with the command code(\include):
1929 \include "paper13.ly"
1932 \paper { \paper_thirteen }
1935 The file is looked for in the standard search path.
1938 subsect(Grouping of staffs)
1943 label(tutorial:titling)
1945 A piece of sheet music isn't complete without proper opening and
1946 closing titles. LilyPond does not have any real support for setting
1947 text: that is a job best left to TeX(). But you can pass messages to
1948 TeX() from the input file. You can write TeX() macros to handle
1950 To do this, you add a code(\header) block
1951 to your input file. The format is quite simple,
1961 When the results of the music typesetting are output, the contents of
1962 code(\header) are also up into the TeX() file. Tools like
1963 code(ly2dvi) can use this information to generate pretty titling for
1964 your input file. Consult the manual page of code(ly2dvi) for more
1968 The code(\header) block should be at toplevel in mudela, and
1969 preferably at the top of the file. If you have an input file with
1970 multiple code(\score) blocks, you should add a header to every score,
1971 describing the different sub parts of the music piece, eg.
1975 "composer" = "Ludwig Van Bavaria";
1976 "title" = "Symphonie Megalomane";
1980 \header { movement = "Mit roher Kraft wild herausfahrend!"; }
1984 ... % some more music
1985 \header { movement = "Saut\'e comme un oeuf."; }
1990 If you want you can also put the code(\header) block at the top of the
1991 input file; it will then be put into every output file automatically.
1992 This will make it clear what the file contains as soon as you open it.