3 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
6 COMMENT( This document contains Mudela fragments. You need at least
7 Yodl-1.30.18 to convert this to tex or html.
11 pipethrough(date) sucks.
13 paragraphs have too much space.
18 Mainly written by Han-Wen Nienhuys,
20 with help of (among others)
32 htmlbodyopt(bgcolor)(white)
33 htmlcommand(<font color=black>)
37 \textheight 53\baselineskip
38 \advance\textheight by \topskip
39 \marginparwidth 1 in % Width of marginal notes.
40 \oddsidemargin 0.25 in % Note that \oddsidemargin = \evensidemargin
41 \evensidemargin 0.25 in
42 \marginparwidth 0.75 in
43 \textwidth 5.875 in % Width of text line.
47 whenlatex(notableofcontents())
48 whentexinfo(notableofcontents())
50 article(Mudela -- Using LilyPond to typeset music)
51 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
52 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
55 latexcommand(\def\interexample{})
56 latexcommand(\def\preexample{\par})
57 latexcommand(\def\postexample{\par\medskip})
58 latexcommand(\def\file#1{{code(#1)}})
61 includefile(html-disclaimer.yo-urg)
66 label(tutorial:introduction)
67 latexcommand(\parindent2pc)
69 If you are reading this, you probably are interested in printing
70 music. LilyPond is a program that can print music from a
71 specification that you, the user, supply. Using LilyPond may be a bit
72 quaint in the beginning, because you have to give that specification
73 using a em(language). This document is a gentle introduction to that
74 language, which is called Mudela, an abbreviation for Music Definition
77 We will demonstrate the working of Mudela by presenting examples of
78 input alongside with the resulting output. We will comment on these
79 examples using English terms for notation, so if you are not familiar
80 with these terms, you should consult the glossary that is distributed
81 with LilyPond: it contains a list of musical terms along with
82 explanations and translations in some other languages.
87 To demonstrate what LilyPond input looks like, we start off with a
88 full fledged, yet simple, example. It is somewhat convoluted version
89 of one of the menuets in bind(J.)bind(S.)Bach's em(Clavierbuchlein).
92 % lines preceded by a percent are comments.
100 d4 [g,8 a b c] d4 g, g |
101 e'4 [c8 d e fis] g4 g, g |
102 c4 [d8( )c b a( ] )b4 [c8 b a g] |
103 a4 [b8 a g fis] g2. |
109 g4 [e8 fis g d] cis4 [b8 cis] a4 |
110 [a8-. b-. cis-. d-. e-. fis-. ]
117 linewidth = 14.0 \cm; % standard settings are too wide for a book
121 Before we will discuss the contents of the above, it would be best if
122 you would try to enter and save this text with a text editor, compile
123 it with LilyPond and view the output. Details of this procedure may
124 vary from system to system. On a Unix system, you should enter the
125 input in a file ending in file(.ly), such as file(menuet.ly). To
126 create the output, one would issue code(ly2dvi menuet).
128 file(ly2dvi) is a little program that does the job of calling the
129 LilyPond and TeX() and adjusting page margins.
131 If all goes well, this will create the output file file(menuet.dvi).
132 To view this output, issue the command code(xdvi menuet). Now that we
133 are familiar with the procedure to view the output, we will analyse
134 the input itself, line by line.
136 verb(% lines preceded by a percent are comments.)COMMENT(
138 )The percent sign (code(%)) introduces a line comment. If you want
139 make larger comments, you can use block comments. These are delimited
140 by code(%{) and code(%})
143 verb(\input "paper16.ly")
145 By default, LilyPond will use definitions for a staff of 20 point
146 high. If you want smaller output (e.g., 16 point), you have to import
147 the setting for that size. You can do this by including a file.
148 code(\include "file") is replaced by the contents of code(file).
154 ) A mudela file combines music with directions for outputting that
155 music. The music is combined with the output directions by putting
156 them into a code(\score) block.
161 )This makes LilyPond ready for accepting notes.
166 ) As we will see, pitches are combinations of octave, note name and
167 chromatic alteration. In this scheme, the octave is indicated by
168 using raised quotes (`code (')') and ``lowered'' quotes (commas:
169 `code(,)'). The central C is denoted by code(c'). The C one octave
170 higher is code(c''). One and two octaves below central C is denoted
171 by code(c) and code(c,) respectively.
173 If you have to indicate the pitches in a long piece that is written in
174 either a high or very low octave, you would have to type very many
175 quotes. To remedy this, LilyPond has a so-called "relative" octave
176 entry mode. In this mode, notes without quotes are chosen in such an
177 octave that they are the closest to the preceding note. If you add a
178 high-quote an extra octave is added. The lowered quote will substract
179 an octave. Because the first note obviously has no predecessor, you
180 have to give the (absolute) pitch of the note to start with.
184 { % sequential music follows
187 ) The brace indicates that what follows is sequential music, i.e.,
188 notes that are to be played and printed after each other. This is in
189 contrast with simultaneous music: notes that are to be played like a
190 chord. You should be careful not to confuse this brace with the one
191 coming after code(\score).
195 \time 3/4; % set the time signature.
198 ) This command changes the time signature of the current piece: this
199 prints a 3/4 sign. The 3/4 value is also used to generate bar lines
205 ) This command changes the current key to G-major. Although
206 this command comes after the code(\time) command, in the
207 output, the key comes before the time signature: LilyPond knows about
208 music typesetting conventions.
213 ) This is a code(d) note. The relative music was started with a
214 code(c''), the real pitch of this note is code(d''). The 4
215 designates the duration of the note (it is a quarter note). COMMENT(
221 )The open bracket starts a beam. This bracket is connected to the
222 following note, which is an eighth with pitch code(g') (remember
223 relative mode for pitches!)
230 )These are notes with pitch code(a') and code(b'). Because their
231 duration is the same as the code(g), there is no need to enter the
232 duration (It is not illegal to enter it anyway. Then you would have
233 to enter code(a8 b8))
240 ) This ends the beam started four notes earlier, at the code(g). In
241 the output, you will notice a measure bar following this note. You do
242 not have to enter anything to make LilyPond create a bar. Instead
243 Lily will deduce where bars have to be by comparing durations of notes with
244 the current time signature. COMMENT(
250 ) Three more notes: The code(|) is a "barcheck". When processing the
251 music, LilyPond will check that barchecks are found at the start of
252 a bar precisely. This makes it easy to spot where notes are forgotten.
257 ) So far, no notes were chromatically altered. Here is the first one
258 that is: code(fis). Mudela by default uses Dutch note names, and
259 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
260 sharp sign in the output. The program keeps track of key signatures,
261 and will only print accidentals if they are needed.
263 c4 [d8( )c b a( ] )b4 [c8 b a g] |
266 ) The next line shows something new: a slur is a symbol that is
267 printed over several notes. In mudela, one enters a slur by marking
268 the beginning and ending note of the slur with an opening and closing
269 parenthesis respectively. In the line shown above this is done for
270 two slurs. Note that parentheses (slur markers) are between the
271 notes, and the brackets (beam markers) around the notes. As you can
272 see, the brackets and parentheses do not have to nest.
275 a4 [b8 a g fis] g2. |
278 ) A duration that is to be augmented with a duration dot, is notated
279 with a duration number followed by periods, as many as you want
280 augmentation dots.COMMENT(
283 \bar ":|"; % a repeat sign
287 Lily can not detect where you want your music to be repeated, so you
288 have to instruct her: a special bar symbol can be entered by the
289 code(\bar) command followed by a string that signifies the bar symbol
290 that you want. Then comes a semicolon to separate the string from the
291 rest of the notes, analogously with code(\key) and code(\time).
297 This line shows that Lily will print an accidental if that is needed:
298 the first C sharp will be printed with an accidental, the second without.
300 [a8-. b-. cis-. d-. e-. fis-. ] % try some super and subscripts.
304 There is more to music than just pitches and rhythms. An important
305 aspect is articulation. You can enter articulation signs either in an
306 abbreviated form, by a dash and the the character for the
307 articulation to use, e.g. code(-.) for staccato as shown above.
315 Rests are denoted by the special notename code(r). You can also make
316 an invisible rest by using the special notename code(s).
321 ) Finally, all articulations have a verbose form, like code(\fermata).
322 The ``command'' COMMENT(Hi Adrian :-) code(\fermata) is not part of
323 the core of the language (most of the other discussed elements are),
324 but it is an abbreviation of a more complicated description of a
325 fermata. code(\fermata) refers to that abbreviation and is therefore
326 called an em(identifier).
333 This ends the sequential music.
338 This specifies a conversion from music to notation output. Most of
339 the details of this conversions (font sizes, dimensions, etc.) have
340 been taken care of, but to fit the output in this document, it has
341 to be smaller. We do this by setting the line width to 10 centimeter
342 (approximately 4 inches).
347 Finally, the last brace ends the code(\score) block.
351 There are a couple of things to note here. The input format tries to
352 capture the meaning of em(music), and not notation. Therefore the
353 format contains musical concepts like pitches and durations, instead
354 of symbols and positions. Second, the format tries to be
355 em(context-free): a note will sound the same regardless of the current
356 time signature, the key nop(etc.)
358 The purpose of LilyPond informally is explained by the term `music
359 typesetter'. As you may have figured out by now, this is not a really
360 adequate name: not only does the program print musical symbols, it
361 also tries to make esthetic decisions, and it also em(generates) both
362 the symbols and the decisions from a high-level musical description.
363 In other words, the function of LilyPond would be best described by
364 `music compiler' or `music to notation compiler'.
366 We find that ---once you master the language--- there are big
367 advantages of using LilyPond over GUI oriented programs: first,
368 entering music is quite efficient. Second, it is possible to explain
369 exactly what the meaning piece of mudela is, and you can transform
370 these pieces automatically (eg, by transposing them). Third, the
371 program that is not interactive, so much less tradeoffs have to be
372 made between processing speed and the beauty of the output: you get
373 prettier output by using LilyPond.
376 As you can see, the most interesting part of the input is music
377 itself, in this case the sequence of notes. We will therefore focus
378 on entering music for now. Consequently, when we mean
384 ) we will leave out the the repetitive details for now and just print
389 sect(When you know the notes to nop(print)ellipsis())
391 The basic building block of music is the note. We lightly touched
392 notes in the previous example. Here comes the full explanation A note
393 is made of a pitch and a duration. The pitch of the central C is
394 written as code(c'). This is in line with musicological notation;
395 there this pitch is transcribed as nop(c)sups(1) or c'. A
396 quarter-note duration is written as code(4). So, to print a quarter
397 note whose pitch is central C, you enter the following code(c'4).
401 The duration of a note is specified as a number: a whole note is
402 denoted by 1, a half note by 2, a quarter by 4, and so on. If you
403 want to augment a duration with a dot, simply affix a period to the
404 number. You can also print notes longer than a whole. You do this by
405 using identifiers (code(\breve) and code(\longa):
406 Here are some random notes to show how it works.
410 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
417 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
421 \translator { \type "Score_engraver";
423 \consists "Note_heads_engraver";
424 \consists "Stem_engraver";
425 \consists "Rhythmic_column_engraver";
430 subsect(Basic pitches)
432 The pitch code(c') consists of two parts: one part for the
433 note name, and one for the octave. The letter specifies which note
434 name to use: note names simply are the letters code(a) to code(g).
435 The number of apostrophes specifies the octave to use: the central C
436 is denoted by code(c').footnote(By convention, the A above central C
437 at concert pitch is the tone that is used to tune instruments. Its
438 frequency is about 440 Hz.) The C which is an eighth higher (the C in
439 the ``two-line octave'') is denoted by code(c''): every octave adds a
440 quote. A note name without quotes designates the pitch below code(c')
441 (the C in the ``small octave''). If you want to go down even further,
442 commas should be added, e.g., the C in the ``contra octave'' is
443 expressed as code(c,,).footnote(The comma is meant to represent a
446 This example demonstrates pitches
447 mudela(fragment,verbatim,center)(
448 c,,4 c, c c' c'' c''' d'4 e'4 f'4 g'4
454 We have so far ignored chromatically altered pitches. The names `a'
455 to `g' for entering pitches are convenient: they are short,
456 pronounceable and they resemble the words for pitches in normal
459 Enter flats and sharps. In English there is no standard terse word
460 for C sharp or C flat. For this reason, mudela uses a different,
461 non-English convention for entering altered pitches: a note is made
462 sharp by adding the suffix `--is' to its name, and flat by adding the
463 suffix `--es'. For a double sharp another `--is' suffix is added, for
464 flats another `--es' nop(suffix.) footnote(Variations on this
465 convention are used in a number of germanic languages, notably Dutch,
466 German, Swedish, and Norwegian.) The names for the alterations of C
467 are given in bind(Table)ref(notename-tab).
469 latexcommand(\begin{table}[h])
472 row(cell(english)cell(LilyPond))
474 row(cell(c double flat)cell(ceses))
475 row(cell(c flat)cell(ces))
476 row(cell(c natural)cell(c))
477 row(cell(c sharp)cell(cis))
478 row(cell(c double sharp)cell(cisis))
481 latexcommand(\caption{Default note names})
483 latexcommand(\end{table})
485 Throughout this document we will continue to use these names.footnote(
486 Mudela defaults to Dutch notenames. To make (Dutch) pronunciation
487 easier, the a-flat and e-flat are contracted to code(as) and
488 code(es). Similarly, the a double flat and e double flat are
489 contracted to code(ases) and code(eses). For consistency, the dutch
490 names also include code(aes), code(aeses), code(ees) and
493 If you are not comfortable with these names, you can make your own.
494 Note names for different languages are included with the example
495 initialisation files, amongst others English (C sharp is abbreviated
496 to code(cs)), Italian, Swedish and Norwegian. If you want to use
497 these names, issue code(\include "LANGUAGE.ly") where you could
498 substitute code(italiano), code(deutsch) etc. for LANGUAGE. You
499 should include these files at toplevel, i.e., before opening a
505 The previous examples all notes that were to be played sequentially, one
506 note following the other. You can also use LilyPond to typeset
507 chords. You do this by expressing in mudela simultaneous music,
508 i.e., notes that are to be played concurrently.
510 In Mudela you can form simultaneous music by enclosing notes in
511 pointed parentheses, bind(i.e.)bind(langle())bind(and)rangle(). ASCII
512 doesn't really have these delimiters, so Mudela uses the larger-than
513 (code(>)) and smaller-than (code(<)) signs instead. For example, a
514 D-major chord is expressed as
515 mudela(fragment,verbatim,center)(
519 Chords can be entered in the music in the same places that notes
520 can. As an example we give a snippet of ``Twinkle Twinkle Little
521 Star'' in chords. The chords may seem slightly unconventional, but
522 they only serve to show how chords work. We've aligned the chords in
523 the input on their starting beat just to help you reading it. This
524 layout does not influence the typesetting result in any way.
526 mudela(verbatim, fragment)(
530 <c e a> <b d a'> <b2 d g>
531 <a4 d f> <bes d f> <bes c e> <g c e>
532 <e a d> <a, g' cis'> <d2 f d'>
536 There is one thing to note, in sequences of chords, the (relative)
537 pitch of a is taken with reference to the first note of the previous
540 You can nest simultaneous and sequential music in any way you want,
543 )mudela(verbatim,fragment,center)(
545 { c'8 <c' e'> c' <c' e'> } >
549 As you can see, LilyPond has some difficulty typesetting this
550 elegantly. To adequately solve this, you have to persuade LilyPond to
551 make separate stems for both sequential music lists. This is a topic
552 that is covered in bind(Section)ref(sec:polyphonic).
554 [Chords and relative mode]
557 sect(Adding nuances: articulation and dynamics)
559 Having just chords and notes does not give you real music. Real music
560 has more liveliness to it: music can have articulation, dynamics
561 (louder and softer), etc. This liveliness has notation, so LilyPond
562 can print it. We'll start out by explaining how to obtain the
563 smallest grains of nuance: the articulation of a single note. Articulation
564 is entered by writing a dash and the name of the desired articulation
565 mark. You have to add a backslash in front of the name to distinguish
566 it from the name of a note. mudela(fragment,verbatim)(
570 Typing a lot of staccato notes in this syntax will get tedious very
571 quickly. Therefore, Mudela has some handy abbreviations for
572 articulation marks such as staccato and tenuto. They are shown in the
577 \property Score.textstyle = typewriter
586 \type Lyrics\lyrics {
587 "."4 "-" "+" "|" ">" "\^{ }" }
589 \paper { linewidth = 12.\cm; }
592 Text and digits for fingering can be entered in the same manner: add a
593 dash and the text or digit to be printed:
594 mudela(fragment,verbatim)(
595 c''4-1 g''4-5 c''-"Sul tasto" )
596 COMMENT(Currently, the meaning of the
597 syntax `note-dash-digit/articulation/text' is just ``add a superscript to this
598 note.'' This is not in line with our goal to em(define) music with
599 Mudela. We hope that this will be fixed in a future version of the
600 language. In the meantime you can abuse this: the super- and
601 subscripts can be forced into up or down position respectively by entering an
602 a caret (code(^)) or an underscore, code(_) instead of the dash:
603 mudela(fragment,verbatim,center)(
604 c'4-^ c'4^^ c'''4-^ c'''4_^
607 Dynamic markings are another way to add a nuance to a note. They are
608 entered by adding the name for the dynamic sign after the note. You
609 should not enter a dash between the name and the note.footnote(This
610 is inconsistent. We hope that this will be fixed in a later
611 version of the language.)
612 mudela(verbatim,fragment)(
613 c4 \ff c4 \fp c4 c4 \ppp c4 c4 \sfz
618 sect(Bridging the notes: beams, slurs and ties)
620 Music typesetting does not use fixed symbols only. A lot of symbols
621 are variable: they run from one note to another. In LilyPond
622 terminology, such a symbol is called a em(spanner). To print a
623 spanner, you have to attach a marker to the note that begins it and to
624 the one that ends it. These are the spanners that are entered like
629 The slur has the opening parenthesis as
630 start marker is. The stopping marker is the closing parenthesis.
632 mudela(fragment,center,verbatim)( c'4( )c'4 )
634 The slur is quite flexible: you can nest nop(slurs,)footnote(This is
635 inconsistent when compared to the syntax for articulation hints. This
636 will be fixed some time, we hope.) and you can connect a note with a
637 slur on both the left and the right side:
639 mudela(fragment,verbatim,center)(
640 c'4(( )c''4 )c'4( )g'4
645 Another spanner is the beam. The starting marker is the opening
646 bracket, then ending marker is the closing bracket. The brackets have
647 to be em(around) the beamed notes. footnote(Strictly speaking, a
648 beam is not a musical concept: beaming doesn't change the meaning of
649 music, it only clarifies the rhythmic structure. One might argue that
650 beams should not be present in a ``music'' language. Unfortunately,
651 LilyPond is not smart enough to insert beams into music on its own.
653 LilyPond does have code that guesses what the pattern should look
654 like, so that you don't have to specify the beaming for complicated
655 patterns. Alas, the algorithm used is not foolproof
656 yet: code([c8. c32 c32]) will produce incorrect results.)
658 mudela(fragment,verbatim)(
659 [c'8 c'] [c'16 c' c' c'] [c'16. c'32 c' c'16.]
662 dit(The tie) The tie is similar to the slur: it looks like a
663 slur, but a slur connects whole chords, whereas the tie connects note
664 heads. Tied notes should be played as one long note. In analogy with
665 TeX()'s tie (which ties together words with a space), LilyPond's tie
666 is entered as a tilde, `code(~)'.
668 The input convention for the tilde is somewhat peculiar when used in
669 conjunction with chords. Internally, the extra information that is
670 represented by the tilde has to be attached to a note (or to a rest,
671 for that matter). For this reason, you can't put the tilde between
672 two chords (as in code( <c' g'> ~ <c' g'>)). The tilde sign must be
673 directly after a note of the chords. It does not matter which
674 one. The following example demonstrates the use of ties:
675 mudela(fragment,verbatim,center)(
677 <c'2. ~ g' es''> <c'4 g' es''>
681 Crescendi and decrescendi can be printed in hairpin style. The
682 starting marker for the crescendo is code(\<), and for the decrescendo
683 code(\>). Both have code(\!) as the ending marker.
684 mudela(fragment, verbatim)(
687 { s4 \< \! s4 \> \! s2 } >
689 This example shows a trick: by attaching the markings to space rests
690 that run parallel to the whole note, you can have dynamic markings
695 It is your job to make sure that each spanner that you start, also
696 ends. If it doesn't, then Bad Things are likely to happen. If you end
697 spanners that are not started, LilyPond will warn you about illegal
703 We have focused on printing notes. Notation contains many other
704 constructs, constructs that help you with reading those notes.
705 Examples of such constructs are clefs, time signatures, keys etc.
706 LilyPond will try to generate these constructs as much as possible,
707 but not all such hints can be inserted automatically, and you can also
708 override some of the settings. This can be done by inserting various
709 commands between the music. The general form of these commands is
712 )center(code(\keyword argument argument ... ;))
714 These are the commands that are currently supported:
716 dit(code(\bar) var(bartype))
717 This command makes LilyPond print special bar
718 lines and repeat symbols. You can also use it to allow line breaks
719 when entering cadenzas. The argument var(bartype) is a string that
720 describes what kind of bar line to print.
722 mudela(fragment,verbatim)(
723 \bar "|:"; c'4 \bar ":|:"; c'4 \bar ":|"; c'4 \bar "||";
724 c'4 \bar "empty"; c'4 \bar "|.";
727 The command `code(\bar "empty")' does not create any visible bar
728 line, but it tells LilyPond to allow a linebreak at that
729 position. The `code(\bar)' command prints the specified symbol
730 immediately. If you give a `code(\bar)' command at the end of a
731 measure then the specified symbol replaces the automatic bar line;
732 otherwise the specified symbol appears in the middle of the measure.
733 The code(\bar) command does not affect metric structure.
735 dit(code(\cadenza) var(togglevalue)) This command toggles the
736 automatic printing of barlines. `code(\cadenza 1)' turns off the
737 automatically generated bar lines. They are switched on again with
738 `code(\cadenza 0)'. Then a bar line is printed, and LilyPond will act
739 as if you are again at the start of a measure.
742 This is useful when typesetting music without a meter (such as an ad
745 dit(code(\clef) var(clefname)) This command sets the current clef for notation,
746 i.e., a clef symbol is printed and the notes following this command
747 are shifted vertically. The argument is a string, the name of the
748 new clef. The default clef is the treble clef.
749 mudela(fragment,verbatim)(
755 dit(code(\key) var(pitch) var(type)) This command changes the current
756 key signature. The key signature is printed at the start of every
757 line. The var(type) argument is set to code(\major) or code(\minor)
758 to get major or minor keys, respectively. Omitting the second
759 argument gives major keys. The key of C-minor can thus be specified
760 as `code(\key es)' or `code(\key \c minor)'.
762 dit(code(\keysignature) var(pitchlist))
764 This command changes the current key signature. Unlike the
765 `code(\key)' command, this command can produce arbitrary key
766 signatures, which can be useful for unconventional keys or modes. The
767 key signature is given in the form of a list of notes. The notes will
768 be printed in the key signature in the order that they appear on the
769 list. For example, the key of C-minor can be specified as
770 `code(\keysignature bes es as)'. The command `code(\keysignature fis
771 es bis)' provides a more exotic example.
774 dit(code(\time) var(numerator)code(/)var(denominator))
775 This command changes the current time signature.
776 The default value for this time signature is common time (4/4).
778 dit(code(\partial) var(duration))
779 This command allows you to make
780 upsteps at the start of a piece.
781 The var(duration) argument has the same form as the duration of a
784 The `code(\partial)' command cannot be used to generate partial
785 measures in the middle of the music.
787 mudela(fragment,verbatim)(
790 [d'8 dis'] e' c''4 e'8 c''4
793 dit(code(\grouping) var(durationslist)) sets the metric structure of the measure.
794 Its effect can best be shown by an example:
795 mudela(fragment,verbatim)(
805 In practice, you won't be needing this command very often: the
806 grouping is switched automatically when you issue a code(\time)
807 command. It is set to a combination of groups
808 of 2 and 3 beats, with as many groups of
809 3 as possible (in other words: 4/4 is divided in two times two beats
813 The commands described above aren't really music, but they can best be
814 thought as as notes with no duration. Since they are grammatically
815 equivalent to notes, these commands can be used in the same places as
818 sect(Notation context)
820 COMMENT(This section is about translation contexts, a topic of LilyPond that
821 is somewhat advanced. You don't have to understand this to use
822 LilyPond to print simple music. If you don't want to typeset fancy
823 polyphonic music or tweak the LilyPond notation engine, you can skip
824 the next two sections.)
826 In bind(Section)ref(tutorial:more-staffs) it was explained that there
827 are more ways to notate a simple chord: as a single voice on a single
828 staff or in multiple staffs (and we'll soon see, that you can typeset
829 it as multiple voices on a staff). Obviously the concept of staff is
830 not really something musical. But what is it then?
832 The most simplistic explanation is: a staff is a graphic peculiarity
833 of the notation system. In other words, a staff is a graphic device,
834 a special picture of five lines on which one can print note heads. We
835 will call this view on the concept of staff `staff symbol' from now
839 there is more to a staff than just the symbol. A staff
840 contains---besides a staff symbol--- some more components:
842 it()A staff can have a key signature (printed at the left)
843 it()A staff can have a time signature (printed at the left)
844 it()A staff has bar lines
845 it()A staff has a clef (printed at the left)
849 To explain what a staff really is, we'll try to print music without
850 these components. Without those, it is still
851 possible to print music:
853 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
858 \remove "Time_signature_engraver";
859 \remove "Bar_engraver";
860 \remove "Staff_symbol_engraver";
861 \remove "Clef_engraver";
862 \remove "Key_engraver";
867 ) As you can see, you can still make out the general form of the
868 melody and the rhythm that is to be played, but the notation is
869 difficult to read. Moreover, the musical information is not complete.
870 The stress pattern in the notes can't be deduced from this output.
871 For this, we need a time signature:
875 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
880 \remove "Bar_engraver";
881 \remove "Staff_symbol_engraver";
882 \remove "Clef_engraver";
883 \remove "Key_engraver";
887 )Technically speaking you know where the strong and weak beats are, but
888 it is difficult to find them quickly. Bar lines help you in finding
889 the location of the notes within the measure:
892 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
897 \remove "Staff_symbol_engraver";
898 \remove "Clef_engraver";
899 \remove "Key_engraver";}
904 We can remedy part of the difficulties with reading pitches by adding a staff
908 \notes\relative c' { \time 2/4; g'4 c,4
909 a'4 f4 e c d2 } \paper {
914 \remove "Clef_engraver";
915 \remove "Key_engraver";
921 This makes the output decidedly easier to read, but you still don't
922 know what the pitches of the notes above are. So this is still not
923 enough. But suppose you see the following notation:
925 \notes \relative c' {\clef alto; \time 2/4; g'4 c,4 a'4 f4 e c d2 }
931 ) Now you know the pitch of the notes: you look at the start of the line
932 and see a clef, with this clef, you can determine the notated pitches.
933 You have found the em(context) in which the notation is to be
936 So the context determines the relationship between a piece of music
937 and its notation: you, the reader, use context to deduce music from
938 notation. Because LilyPond is a notation writer instead of a reader,
939 context works the other way around for Lily: with context a piece of
940 music can be converted to notation.
942 We see that a staff forms context, and that context is needed to
943 convert between notation and music. In LilyPond we turn around this
944 reasoning: LilyPond has a notion of notation context, and the staff is
945 just one example of a notation context. In fact, the arguments of the
946 code(\type) command (Staff, GrandStaff) were all names of different
949 We make one final observation before listing the standard notation
950 contexts. A score can contain many staffs; A staff can contain many
951 voices. This suggests that notation contexts are objects that can be
954 The following is a list of the contexts that are supported by
955 LilyPond. Each notation context is characterised by its name, the
956 notation elements it creates, and the contexts that it can contain.
958 dit(Voice) The code(Voice) context is a context that corresponds to a
959 voice on a staff. This context handles the conversion of noteheads,
960 dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests
962 dit(Staff) The code(Staff) context handles clefs, bar lines, keys,
963 accidentals. A code(Staff) context can contain code(Voice)
966 dit(RhythmicStaff) The code(RhythmicStaff) context is like the staff,
967 but much simpler: the notes are printed on one line, and pitches are
968 ignored. code(RhythmicStaff) can contain code(Voice) contexts.
970 dit(GrandStaff) A code(GrandStaff) context contains code(Staff)
971 contexts, and it adds a brace to the output at the
972 nop(left.)footnote(This is a major deficiency in the current
973 implementation. Currently stems, slurs and beams cannot be printed
974 across two staffs. In reality, a grand staff is a hybrid of one big
975 staff and two stacked staffs.)
977 A code(GrandStaff) context can contain
978 code(Staff)s. Typically, it will contain two code(Staff)s, one
979 treble staff, and one bass staff. The bar lines of the contained
980 staffs are connected vertically.
982 dit(StaffGroup) A code(StaffGroup) context contains code(Staff) or
983 code(Lyrics) contexts, and prints a bracket at the left. The bar
984 lines in the participating staffs are connected.
986 dit(Lyrics) As its name suggests, The code(Lyrics) context deals with
987 typesetting lyrics. This topic will be covered in
988 bind(Section)ref(tutorial:lyrics).
990 dit(Score) The code(Score) context is the toplevel context: no context can
991 contain a code(Score) context. The code(Score) context handles the
992 administration of time signatures. It also makes sure that items
993 such as clefs, time signatures, and key-signatures are aligned across staffs.
995 The code(Score) can contain code(Staff), code(StaffGroup),
996 code(Lyrics), code(GrandStaff) and code(RhythmicStaff) contexts.
998 COMMENT(do ChoireStaff)
1002 If you are familiar with structured documents, you might see the
1003 analogy of a context with a stylesheet: a stylesheet is neither
1004 presentation nor information, but rather a recipe em(how) a specific
1005 piece of information should be presented. The big difference with
1006 stylesheets is that in music notation the elements provided by context
1007 are essential to understanding what is notated.
1009 The notions of ``current clef'' and ``current position within the
1010 measure'' are all properties of notation contexts. Commands like
1011 code(\clef) and code(\cadenza) change these properties, and this
1012 explains why they are fundamentally different from musical expressions
1013 like notes and rests.
1015 A notation context is not a primitive element of LilyPond, but rather
1016 Later on, in bind(Section)ref(tutorial:engravers) we will explain
1017 how you can create your own contexts.
1020 sect(Nested music: multiple staffs)
1021 label(tutorial:more-staffs)
1023 Now we explain how to typeset music that runs in multiple staffs.
1024 Consider the following---somewhat unrealistic---example:
1027 \type GrandStaff <e'4 {\clef bass; g4^""} >
1030 In this example the music consists of two notes. The above would
1031 sound the same if it were written as a single chord on a single staff,
1038 ) The Mudela construct for multiple staffs reflects the similarity
1039 between the two examples: to get multiple staffs in Mudela you enter a
1040 chord, with an additional instruction to tell LilyPond that the chord
1041 does not represent notes stacked together, but staffs stacked
1044 If a piece of music is to be interpreted as a staff, then this can be
1045 expressed with the code(\type) construct. The following input says
1046 ``the quarter note with pitch e should be put on a staff.''
1052 ) The same can be done for the other note, i.e.,
1058 ) If you want to stack these staffs, you must create a chord of both:
1066 This looks reasonable, but the effect of this input is not what you
1074 ) Since there are no names specified for the desired staffs, LilyPond
1075 thinks your wishes are fullfilled by putting the code(g) on the same
1076 staff as the code(e). The correct solution is to label both staffs
1077 with different names, for example code(trebleStaff) and
1078 code(bassStaff). This makes LilyPond distinguish between them, and
1081 mudela(verbatim,fragment)(
1082 < \type Staff = trebleStaff e'4
1083 \type Staff = bassStaff g4
1087 ) The names that you choose do not matter just as long as they are
1088 different. This is almost right, except for the brace at the left and
1089 the clef of the second staff. If you want a brace, then you have to
1090 tell LilyPond that the chord you just formed is to be interpreted as a
1091 so-called grand staff. This is also done with the code(\type)
1092 command. The bass clef is made with a clef command: COMMENT(
1094 ) mudela(verbatim,fragment)(
1096 \type Staff = treblestaff e'4
1097 \type Staff = bassstaff { \clef "bass"; g4 }
1102 sect(Polyphonic music (or: Notation context properties))
1103 label(sec:polyphonic)
1105 In the section on notation contexts we explained that a notation
1106 context can have properties that influence the conversion from music
1107 to notation. A simple example of such a property is the clef: the
1108 type of a clef helps determines the vertical position of note heads in
1109 a staff. Some of these properties can be modified by commands such as
1110 code(\clef) and code(\time). But there is more: notation contexts
1111 also have properties are settable in a generic fashion. We will
1112 demonstrate this feature by printing multiple voices on a staff.
1114 Printing more than one voice on a staff, is not unlike printing
1115 multiple staffs stacked together. This suggests that the template
1119 \type Voice = one ...
1120 \type Voice = two ...
1124 ) On the ellipsis there should be music going from left to right, in
1125 other words, notes enclosed in braces. Let us try the following
1128 mudela(fragment,verbatim)(
1130 \type "Voice" = "one" { r4 as'4 () as'4 g'4 }
1131 \type "Voice" = "two" { g'2 f'4 e'4 }
1134 As you can see the result is not quite perfect. The notes on the last
1135 two beats look like plain chords and not like separate voices. What
1136 really happened was that the stems of the upper and lower voices were
1137 printed on top of each other.
1139 To remedy this, engravers traditionally make the stems of the lower
1140 voice point down, and the stems of the upper up, as shown in
1141 bind(Figure)ref(tutorial:multi-voice-fig).
1143 Surely the direction of a single stem is a property of the stem as a
1144 graphical object. But the fact that all of the stems in a voice point
1145 in the same direction is not directly graphical. Since this is a
1146 property shared by all the stems in the voice, this property is a
1147 property of the context code(Voice). The context code(Voice) has an
1148 attribute whose value is the direction to use for stems. You can
1149 change it to `up' by issuing the following phrase:
1151 \property "Voice"."ydirection" = "1"
1154 This command should be read as ``change the property called
1155 code(ydirection) within the current code(Voice) context to the value
1156 code(-1).'' For the property code(ydirection) the value code(1) means
1157 `up', and code(-1) means `down'. So, the
1158 proper way to code the polyphonic example is given in
1159 bind(Figure)ref(tutorial:multi-voice-fig).
1161 latexcommand(\begin{figure}[h])
1162 mudela(fragment,verbatim,center)(
1164 \type "Voice" = "one" {
1165 \property Voice.ydirection = "1"
1166 r4 as'4 () as'4 g'4 }
1167 \type "Voice" = "two" {
1168 \property Voice.ydirection = "-1"
1172 latexcommand(\caption{multiple voices})
1173 label(tutorial:multi-voice-fig)
1174 latexcommand(\end{figure})
1176 As you can see, this property also controls the directions of slurs,
1177 which explains the name code(ydirection).COMMENT(hmm)
1180 Other properties can also be set, and they can be within different
1181 contexts. In general, you can set a property by specifying
1182 code(\property) var(contexttype)code(.)var(propertyname) code(=)
1183 var(value). Both var(contexttype), var(propertyname) and var(value)
1186 The effect of a property is pretty much hardwired into the
1187 implementation (and thus subject to change), so we will not deal with
1188 all the possible properties in detail. Among other characteristics that
1189 can be set are the layout of slurs and beams. The initialisation file
1190 file(property.ly) explains most properties.
1193 label(tutorial:lyrics)
1195 Since a lyrics can have durations just like notes, we consider them to
1196 be music too. Entering lyrics in mudela has two aspects. First, you
1197 have to enter the text, i.e., the syllables along with their
1198 durations. After this, you have to specify how to convert these to
1201 Lyrics consist of syllables, which are strings together with
1202 durations. Previously we only entered note names, so for entering
1203 lyrics we have to instruct LilyPond that what we enter are not note
1204 names but strings. This instruction is the keyword
1205 code(\lyrics). After entering this keyword you can enter a musical
1206 construct---sequential music, simultaneous music, code(\type)
1207 entries, etc.--- but with syllables instead of pitches. For example:
1210 )verb(\lyrics { 'got8 me on my knees4, Le-8 lie! })COMMENT(
1212 ) Next comes the conversion to notation. LilyPond can't (yet) figure
1213 out that lyrics need different treatment than notes. As a result, the
1214 default conversion will try to put the text you entered as note heads
1215 onto a staff, and this will fail. This default must be overridden
1216 with a code(\type) keyword. Printing syllables of text in a line is
1217 done by a context called code(Lyrics). You can select this context
1218 with the code(\type) keyword. Here is a simple example:
1221 )mudela(fragment,verbatim)(
1222 \type Lyrics \lyrics { 'got8 me on my knees,4 Le-8 lie! })COMMENT(
1224 )The result is technically correct, but it needs a melody to make it
1225 performable: COMMENT(
1227 )mudela(fragment,verbatim)(
1229 \type Staff { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1230 \type Lyrics \lyrics { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
1234 ) The strings that makes up each syllable in the lyrics block are
1235 passed along to TeX() verbatim, so if you are proficient with TeX()
1236 you can do various nifty things. Just keep in mind that a syllable
1237 either starts with a letter (a character in the range `code(a)' to
1238 `code(z)' or `code(A)' to `code(Z)'), or it is a string enclosed
1239 quotes. It ends with either a number for the duration, or a space.
1240 These tricks are demonstrated in the following example:
1242 \type Lyrics \lyrics { 'got8 m\textbf{e}8 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1243 \type Lyrics \lyrics { 'got8 m{\bf e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1246 )mudela(fragment,verbatim)(<
1247 \type Staff { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1248 \type Lyrics \lyrics { 'got8 me8 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
1254 COMMENT(Groen is de kleur van geluk.)
1255 COMMENT(Dat geldt zeker voor Bj"ork)
1257 sect(Toplevel Mudela)
1259 Back in bind(Section)ref(sec:firsttune) we said we would defer
1260 discussion of toplevel constructions (e.g., code(\score)) to a later
1261 moment in time: and now we will look at these constructions. In
1262 general, Mudela looks like set of nested `blocks'. The general syntax
1263 for a block is code(\keyword { ... }).
1265 We will now discuss identifiers. Generally you can define an
1266 identifier by entering code(identifierName = ... ) where there can be
1267 a variety of things on the ellipsis.
1269 Here is a (partial) list of what you can abbreviate with identifiers
1272 it()The code(\score) block
1273 it()The code(\paper) block
1274 it()The code(\midi) block (to be explained in
1275 bind(Section)ref(tutorial:sound))
1276 it()Music (sequential music, simultaneous music etc.)
1279 it()Translators (to be explained in bind(Section)ref(tutorial:engravers))
1286 to the abbreviated entity, you must precede code(identifierName)
1287 with a backslash, i.e., code(\identifierName). For example:
1289 czerny = \notes { [c16 g e g] }
1291 \notes \type GrandStaff <
1293 { \clef bass; \czerny \czerny \czerny \czerny}
1297 stem_length = 6.0*\interline;
1303 Another interesting feature of this example are the assignments within
1304 the paper block. Some blocks, such as code(\paper), have a scope of
1305 their own. In the case of the code(\paper) block, these variables
1306 influence the characteristics of the output. As is shown, you can
1307 tune quantities like the stemlength, and enter simple
1308 nop(expressions.)footnote(The purpose of the negative linewidth is to
1309 prevent the music from being justified.) The identifiers that are
1310 meaningful are for the paper block is strongly implementation
1311 dependent, so they will not be listed here. Moreover, since most of
1312 the values are predefined to sensible defaults, there usually is no
1313 need to tune these values.
1315 Recall the properties of a context, that could be set with
1316 code(\property). It is a very general mechanism to tune the output of
1317 the music, that is neatly separated from the real music.
1318 Unfortunately, it is not convenient to type or read, and the precise
1319 effect of a setting property isn't always apparent from its
1320 definition. To remedy this, we can use an identifier to capture the
1321 meaning of a code(\property).
1324 stemup = \property Voice.ydirection = "1"
1325 stemdown = \property Voice.ydirection = "-1"
1326 shift = \property Voice.hshift = "1"
1328 \type "Staff" \notes <
1329 \type "Voice" = "one" { \stemup r4 as'4 () as'4 g'4 }
1330 \type "Voice" = "two" { \stemup \shift g'2 f'4 e'4 }
1331 \type "Voice" = "three" { \stemdown [d'8 dis'] [d' cis'] [c' b] c'4 } >
1332 \paper{ linewidth = -1.0\pt; }
1335 Several abbreviations like code(\stemup) are defined in the standard
1336 initialisation file file(property.ly). Setting or changing context
1337 properties can have a similar effect as the commands that were
1338 discussed in bind(Section)ref(sec:commands). Don't be fooled by the
1339 similarity in appearance between a declared property-setting entry and
1340 a real command like code(\clef) or code(\bar). Real commands are
1341 hardcoded into the language and they have to be terminated by
1344 You can also use identifiers to break up the heavy nesting that can
1345 occur in the code(\score) block. Another useful application is
1346 parametrisation of the music: if you use identifiers in the
1347 code(\score) block, you can make variations of the music by simply
1348 redefining those identifiers. One particular application of this is
1349 part extraction: by using identifiers and redefining them, one can
1350 print extracted parts and a full orchestral score from the same music
1355 label(tutorial:sound)
1357 You get output by combining music with definition a conversion to
1358 output. LilyPond currently supports one other conversion besides
1359 notation: the conversion from abstract music to sound. You can have
1360 LilyPond play the music that you entered. The format that is used for
1361 this output is MIDI. The result is not very pretty, but it is useful
1362 for prooflistening your files: typing errors stand out when you
1363 listen, especially if they involve accidentals.
1365 The only information that you need to enter is the
1366 tempo. (Unfortunately, at this time, this the only thing that can be
1367 tuned. The syntax for the tempo is code(\tempo )var(duration) =
1368 var(beatsperminute);), for example: COMMENT(
1374 \midi { \tempo 4 = 76; }
1379 sect(Contexts revisited: engravers)
1380 label(tutorial:engravers)
1382 As was promised, we will now take a dive into the more wizardrous parts
1383 of LilyPond: redefining (notation) contexts. We previously explained
1387 it()is a conversion from music to notation,
1388 it()can contain other contexts
1389 it()handles specific notation constructs
1392 This characterization almost automatically explains what the definition of a
1393 context should look like:
1395 it() It should have a name
1396 it()It should be part of the ``notation output definition,'' i.e., the
1399 It should contain a specification of what other contexts may be contained
1400 in the context we're defining.
1402 It should contain a list of the notation constructs to be
1406 LilyPond can create notation for a large number of symbols. This code
1407 is split up into basic building blocks. Each building block is called
1408 an em(engraver), and an engraver generally handles only one notation
1409 construct: the code(Clef_engraver) takes care of the clefs, the
1410 code(Time_signature_engraver) takes care of printing time signatures.
1412 A notation context is formed by a group of engravers. A special class
1413 in LilyPond---the code(Engraver_group_engraver)---allows engravers to
1414 cooperate in a group. A variant of this grouping object is the
1415 code(Line_group_engraver_group), which puts the output of all the
1416 engravers (clefs, bars, etc) into a compound object, so that these
1417 symbols can be treated as a whole.
1419 This explains the following definition, which is a simplified Staff context:
1423 \type "Line_group_engraver_group";
1426 \consists "Bar_engraver";
1427 \consists "Clef_engraver";
1428 \consists "Key_engraver";
1429 \consists "Local_key_engraver";
1430 \consists "Time_signature_engraver";
1431 \consists "Staff_symbol_engraver";
1433 defaultClef = treble;
1438 ) This context, named Staff, puts its graphic objects into a compound
1439 object (a so-called ``Line group''). At Staff level, bars, clefs,
1440 keys, accidentals, time signatures and the staff symbol are handled.
1441 A staff can contain a Voice context. You can also preset properties
1442 of contexts: for instance, the clef that is printed upon starting a
1443 Staff, is the treble clef.
1445 You can also declare contexts, and reference them. This is useful in
1446 combination with code(\remove "..."): code(\remove) does the opposite
1449 The real context definitions are in the standard initialisation
1450 file file(engraver.ly).
1452 As a practical example, we will show how to typeset polymetric music,
1453 i.e., music where the meter can differ for each staff. The solution
1454 is not very complicated: normally all timing information (time
1455 signature, rhythmic grouping) is synchronised across each staff. This
1456 is done by having only one administration for timing information: in
1457 the default configuration there is only one code(Timing_engraver), in
1458 the code(Score) context.
1460 All staffs use the information in the code(Timing_engraver) for
1461 generating bar lines and time signatures. So, we can have different
1462 timing for every staff, by moving the code(Timing_engraver) into the
1468 \type Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1469 \type Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1475 \remove "Timing_engraver";
1479 \consists "Timing_engraver";
1486 sect(Urtexts and context selection)
1487 label(tutorial:urtext)
1489 In bind(Section)ref(tutorial:more-staffs), we have shown you how to
1490 make multiple staffs, and explained that you have to label every staff
1491 (or more precisely: different contexts), to make sure that new ones
1492 are created when you need them. In this section, the real power of
1493 this mechanism will be unveiled.
1495 By naming other contexts that you create, you can reference other
1496 contexts than the current context from within the music. For example,
1497 from within the music that you enter for staff code(One), one could
1498 enter a small piece of music, and send it to staff code(Two), e.g.,
1501 ) mudela(fragment,verbatim)(
1503 \type Staff = one { c''4 \type Staff = two { c4 c4 } c''4 }
1504 \type Staff = two { \clef bass; g,4 g,4 g,4 g,4 }
1510 The mechanism of context selection can be used to fabricate an
1511 nop(Urtext)footnote(em(Urtext) is the German word for `original text'.
1512 The Urtext edition of a piece of music, is an edition that reflects
1513 the original writing of the composer. Such editions are useful for
1514 musicologists, and performers that want to perform authentic
1515 interpretations. However, for mere mortals, the Urtext can be quite
1516 hard to read. It might not contain fingering and beaming, and
1517 typically it is full of footnotes. Moreover, common interpretations
1518 may have emerged---after the composer died. For this reason, the
1519 music that can be had as Urtext usually is also available in enhanced
1520 and edited editions. ) and an edited edition from em(one source). We
1521 will use the first few bars of bind(J.)bind(S.)Bach's first Cello
1522 suite to demonstrate this. The example makes heavy use of space
1523 rests; here they are used as a placeholder to attach articulation
1527 bach = \notes \relative c { [g16 d' b' a] [b d, b' d,] }
1529 staffStuff = \notes { \clef bass; \time 4/4; s1 \bar "|."; }
1531 slursOne = \notes { s16( s s s s16 s s )s }
1532 slursTwo = \notes { s16-. s s() s s16() s s ()s }
1535 { < \type Voice = celloVoice { \bach \bach }
1536 \type Voice = celloVoice { \slursOne \slursOne }
1540 \type Voice = celloVoice { \bach \bach }
1541 \type Voice = celloVoice { \slursTwo \slursTwo }
1545 \paper { linewidth = -1.;}
1549 The slurs that you define should be put on the music that is defined
1550 by the code(\bach) identifier. By labeling a code(Voice) context, and
1551 directing both the articulation and the notes to that same code(Voice)
1552 context, the articulation is put over the right notes.
1556 label(tutorial:more-grammar)
1559 One of the things that you can do with music is
1560 em(transposing) it. If you want to transpose a piece of music, then
1561 you should prefix the keyword code(\transpose) along with the pitch
1562 (relative to the central C) for the transposition.footnote(the
1563 code(\type Staff) is to make sure that no separate staffs are created
1564 for the code(\scale) and code(\transpose cis' \scale) part.)
1568 scale = \notes \relative c' { [c8 d e f] }
1571 \type Staff { \scale \transpose cis' \scale }
1573 \paper { linewidth = -1.0; }
1577 sect(Staff switching)
1579 We have seen that contexts can be nested. This means that they form a
1580 tree. It is possible to edit this tree: for example, a code(Voice)
1581 context can be taken out of a code(Staff) context, and put into
1582 another. This has the effect of the voice switching staffs (something
1583 that often happens in keyboard music). The syntax for this operation
1584 with these particular contexts is code(\translator Staff = newStaffName).
1586 The effect is analogous to the first example in section
1587 ref(tutorial:urtext), but with the code(\translator) construction it
1588 is possible to split the real music and the commands that determine in
1589 which staff the music is printed. For example:
1594 aVoice = \type Voice = voiceA \notes { c''4 c4 c4 c''4 }
1595 bVoice = \type Voice = voiceB \notes { g,4 g,4 g,4 g,4 }
1597 % staff switching stuff
1598 switch = \type Voice = voiceA \notes { s4 \translator Staff = staffB s4
1599 s4 \translator Staff = staffA s4 }
1603 \type Staff = staffA < \aVoice \switch >
1604 \type Staff = staffB < \bVoice \clef bass; >
1606 \paper { linewidth = -1.; }
1610 Don't try to switch staffs when you are in the middle of a slur or
1611 beam, though: the spanners won't switch along.
1613 sect(Hairy durations: triplets)
1617 In the previous section we explained an operation that changes the
1618 pitches of music, transposition. In this section we will explain an
1619 operation that modifies the duration of the notes that you enter.
1620 When notes are part of a triplet, then the real of duration of the
1621 notes are 2/3 part of what their shape indicates:
1623 \times 2/3 { c'4 c'4 c'4 }
1626 To support this notion, Mudela allows you to modify the duration of a
1627 note by multiplication or division. A code(c'4) note that would be in a
1628 triplet is written as code(c'4*2/3). If you sequence a few of these
1629 notes, you get a triplet.footnote(We added a normal staff in the example to
1630 show the difference.)
1631 mudela(fragment,verbatim)(
1632 < \type Staff = staffA { \times 2/3 { c'8 c'8 c'8 } c'4}
1633 \type Staff = staffB { c''8 c''8 c''4 } >)
1635 LilyPond knows that these notes are no normal eighth notes, but the
1636 reader doesn't yet. To help the reader a beam or a bracket with a `3'
1637 should be printed. The special beam command `code([2/3)' and the
1638 matching close beam `code(]1/1)' will take care of that, and
1639 they also abbreviate the code(*2/3) part. If you want brackets in
1640 stead of beams, you can use `code(\[2/3])' and `code(\]1/1)'.
1641 mudela(fragment,verbatim)(
1642 < \type Staff = staffA {
1643 \times 2/3 { [ c'8 c'8 c'8 }
1644 \times 2/3 { c'8 c'8 c'8 }
1646 \type Staff = staffB { [c''8 c''8 c''8 c''8] }
1649 Other tuplets can be entered in the same way.
1650 mudela(fragment,verbatim)(
1651 < \type Staff = staffA {
1653 \times 7/6 { [c'8 c'8 c'8 c'8 c'8 c'8] }
1655 \type Staff = staffB {
1657 [c''8 c''8 c''8 c''8 c''8 c''8 c''8] } >
1660 For your convenience, code([2/3) can be further abbreviated to code([/3), and
1661 you can abbreviate code(]1/1) on the closing beam marker to code(]/1).
1663 mudela(fragment,verbatim)(
1664 < \type Staff = staffA {
1665 \times 2/3 { c'8 c'8 c'8 } c'4
1667 \type Staff = staffB { [c''8 c''8] c''4 } >
1671 bf(Important) the construct with code([/3) and
1672 code([/1) is a hack that sets a mode in the parser. This means that
1673 verb(id = \notes { c8 c8 c8 }
1674 notATriplet =\notes { [2/3 \id ]1/1 })
1675 does not produce a triplet. It will hopefully
1676 soon be replaced by a construction that mixes more elegantly with the
1684 label(tutorial:titling)
1686 A piece of sheet music isn't complete without proper opening and
1687 closing titles. LilyPond does not have any real support for setting
1688 text: that is a job best left to TeX(). But you can pass messages to
1689 TeX() from the input file. You can write TeX() macros to handle
1691 To do this, you add a code(\header) block
1692 to your input file. The format is quite simple,
1702 When the results of the music typesetting are output, the contents of
1703 code(\header) are also up into the TeX() file. Tools like
1704 code(ly2dvi) can use this information to generate pretty titling for
1705 your input file. Consult the manual page of code(ly2dvi) for more
1709 The code(\header) block should be at toplevel in mudela, and
1710 preferably at the top of the file. If you have an input file with
1711 multiple code(\score) blocks, you should add a header to every score,
1712 describing the different sub parts of the music piece, eg.
1716 "composer" = "Ludwig Van Bavaria";
1717 "title" = "Symphonie Megalomane";
1721 \header { movement = "Mit roher Kraft wild herausfahrend!"; }
1725 ... % some more music
1726 \header { movement = "Saut\'e comme un oeuf."; }
1731 If you want you can also put the code(\header) block at the top of the
1732 input file; it will then be put into every output file automatically.
1733 This will make it clear what the file contains as soon as you open it.