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 need to rethink paper size stuff?
13 pipethrough(date) sucks.
15 paragraphs have too much space.
21 Mainly written by Han-Wen Nienhuys,
23 with help of (among others)
35 htmlbodyopt(bgcolor)(white)
36 htmlcommand(<font color=black>)
40 \textheight 53\baselineskip
41 \advance\textheight by \topskip
42 \marginparwidth 1 in % Width of marginal notes.
43 \oddsidemargin 0.25 in % Note that \oddsidemargin = \evensidemargin
44 \evensidemargin 0.25 in
45 \marginparwidth 0.75 in
46 \textwidth 5.875 in % Width of text line.
50 whenlatex(notableofcontents())
51 whentexinfo(notableofcontents())
53 article(Mudela -- Using LilyPond to typeset music)
54 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
55 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
58 latexcommand(\def\interexample{})
59 latexcommand(\def\preexample{\par})
60 latexcommand(\def\postexample{\par\medskip})
61 latexcommand(\def\file#1{{code(#1)}})
64 includefile(html-disclaimer.yo-urg)
69 label(tutorial:introduction)
70 latexcommand(\parindent2pc)
72 If you are reading this, you probably are interested in printing
73 music. LilyPond is a program that can print music from a
74 specification that you, the user, supply. Using LilyPond may be a bit
75 quaint in the beginning, because you have to give that specification
76 using a em(language). This document is a gentle introduction to that
77 language, which is called Mudela.
79 We will demonstrate the working of Mudela by presenting a examples of
80 input alongside with the resulting output. We will comment on these
81 examples using English terms for notation, so if you are not familiar
82 with these terms, you should consult the glossary that is distributed
83 with LilyPond: it contains a list of musical terms along with
84 explanations and translations in some other languages.
89 To demonstrate what LilyPond input looks like, we start off with a
90 full fledged (yet simple) example. It is somewhat convoluted version
91 of one of the menuets in bind(J.)bind(S.)Bach's em(Clavierbuchlein).
94 % lines preceded by a percent are comments.
97 \notes % let's start music
98 \relative c'' { % octave quotes are relative now
100 \time 3/4; % set the time signature.
102 d4 [g,8 a b c] d4 g, g |
103 e'4 [c8 d e fis] g4 g, g |
104 c4 [d8( )c b a( ] )b4 [c8 b a g] |
105 a4 [b8 a g fis] g2. |
107 \bar ":|"; % a repeat sign
112 g4 [e8 fis g d] cis4 [b8 cis] a4 |
113 [a8-. b-. cis-. d-. e-. fis-. ] % try some super and subscripts.
120 linewidth = 10.0 \cm; % standard settings are too wide for a book
124 Before we will discuss the contents of the above, it would be best if
125 you would try to enter and save this text with a text editor, compile
126 it with LilyPond and view the output. Details of this procedure may
127 vary from system to system. On a Unix system, you should enter the
128 input in a file ending in file(.ly), such as file(menuet.ly). To
129 create the output, one would issue
133 file(ly2dvi) is a little program that does the job of calling the LilyPond
135 TeX() and adjusting page margins.
137 If all goes well, this will create the output file file(menuet.dvi).
138 To view this output, isssue the command
145 Now for some explanation of the input itself, we will dissect the
148 verb(% lines preceded by a percent are comments.)COMMENT
150 )The percent sign (code(%)) introduces a line comment. If you want
151 make larger comments, you can use block comments. These are delimited
152 by code(%{) and code(%})
155 verb(\input "paper16.ly")
157 By default, LilyPond will use definitions for a staff of 20 point
158 high. If you want smaller output (e.g., 16 point), you have to import
159 the setting for that size. You can do this by including a file.
160 code(\include "file") is replaced by the contents of code(file).
166 ) A mudela file combines music with directions for outputting that
167 music. The music is combined with the output directions by putting
168 them into a code(\score) block.
170 \notes % get ready for notes
173 )This makes LilyPond ready for accepting notes.
175 \relative c'' % octave quotes are relative now
177 As we will see, pitches are combinations of octave, note name and
178 chromatic alteration. In this scheme, the octave is indicated by using raised
179 quotes (') and lowered" quotes (commas: code(,)). The central C is denoted
180 by code(c'). The C one octave higher is code(c''). One and two
181 octaves below central C is denoted by code(c) and code(c,)
184 If you have to indicate the pitches in a long piece that is written in
185 either a high or very low octave, you would have to type very many
186 quotes. To remedy this, LilyPond has a so-called "relative" octave
187 entry mode. In this mode, notes without quotes are chosen in such an
188 octave that they are the closest to the preceding note. If you add a
189 high-quote an extra octave is added. The lowered quote will substract
190 an octave. Because the first note obviously has no predecessor, you
191 have to give the (absolute) pitch of the note to start with.
194 { % sequential music follows
197 ) The brace indicates that what follows is sequential music, i.e.,
198 notes that are to be played and printed after each other. This is in
199 contrast with simultaneous music: notes that are to be played like a
200 chord. You should be careful not to confuse this brace with the one
201 coming after code(\score).
205 \time 3/4; % set the time signature.
208 ) This command changes the time signature of the current piece: this
209 prints a 3/4 sign. The 3/4 value is also used to generate bar lines
215 ) This command changes the current key to G-major. Although
216 this command comes after the code(\time) command, in the
217 output, the key comes before the time signature: LilyPond knows about
218 music typesetting conventions.
223 ) This is a code(d) note. The relative music was started with a
224 code(c''), the real pitch of this note is code(d''). The 4 is
225 designates the duration of the note (it is a quarter note).
229 The open bracket starts a beam. This bracket is connected to the
230 following note, which is an eighth pitch code(g') (remember relative mode)
234 These are notes with pitch code(a') and code(b'). Because their
235 duration is the same as the code(g), there is no need to enter the
236 duration (It is not illegal to enter it anyway. Then you would have
237 to enter code(a8 b8))
242 ) This ends the beam started four notes earlier, at the code(g). In the output,
243 you will notice a measure bar following this note. You do not have to
244 enter anything to make LilyPond create a bar. Instead Lily deduce
245 where bars have to be by comparing durations of notes with the current
251 ) Three more notes: The code(|) is a "barcheck". When processing the
252 music, LilyPond will check that barchecks are found at the start of
253 a bar precisely. This makes it easy to spot where notes are forgotten.
258 ) So far, no notes were chromatically altered. Here is the first one
259 that is: code(fis). Mudela by default uses Dutch note names, and
260 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
261 sharp sign in the output. The program keeps track of key signatures,
262 and will only print accidentals if they are needed.
264 c4 [d8( )c b a( ] )b4 [c8 b a g] |
267 ) The next line shows something new: a slur is a symbol that is
268 printed over several notes. In mudela, one enters a slur by marking
269 the beginning and ending note of the slur with an opening and closing
270 parenthesis respectively. In the line shown above this is done for
271 two slurs. Note that parentheses (slur markers) are between the
272 notes, and the brackets (beam markers) around the notes. As you can
273 see, the brackets and parentheses do not have to nest.
276 a4 [b8 a g fis] g2. |
279 ) A duration that is to be augmented with a duration dot, is notated
280 with a number followed by periods, as many as you want augmentation
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, e.g., by using code(-.) for staccato as shown above.
313 Rests are denoted by the special notename code(r). You can also make
314 an invisible rest by using the special notename code(s).
319 ) Finally, all articulations has a verbose form, like code(\fermata).
320 The ``command'' COMMENT(Hi Adrian :-) code(\fermata) is not part of
321 the core of the language (most of the other discussed elements are),
322 but it is an abbreviation of a more complicated description of a
323 fermata. code(\fermata) refers to that abbreviation and is therefore
324 called an em(identifier).
331 This ends the sequential music.
336 This specifies a conversion from music to notation output. Most of
337 the details of this conversions (font sizes, dimensions, etc.) have
338 been taken care of, but to fit the output in this document, it has
339 to be smaller. We do this by setting the line width to 10 centimeter
340 (approximately 4 inches).
345 Finally, the last brace ends the code(\score) block.
349 There are a couple of things to note here. The input format tries to
350 capture the meaning of em(music), and not notation. Therefore the
351 format contains musical concepts like pitches and durations, instead
352 of symbols and positions. Second, the format tries to be
353 em(context-free): a note will remain to sound the same regardless of
354 the current time signature, the key nop(etc.)COMMENT(footnote The
355 code(\relative) mode is a concession to this, but a )
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 parts 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 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' suffix. The names for the alterations of C are
465 given in bind(Table)ref(notename-tab).
467 latexcommand(\begin{table}[h])
470 row(cell(english)cell(LilyPond))
472 row(cell(c double flat)cell(ceses))
473 row(cell(c flat)cell(ces))
474 row(cell(c natural)cell(c))
475 row(cell(c sharp)cell(cis))
476 row(cell(c double sharp)cell(cisis))
479 latexcommand(\caption{Default note names})
481 latexcommand(\end{table})
483 Variations on this convention are used in a number of germanic
484 languages, notably Dutch, German, Swedish, and Norwegian.
486 Throughout this document we will continue to use these names.footnote(
487 Mudela defaults to Dutch notenames. To make (Dutch) pronunciation
488 easier, the a-flat and e-flat are contracted to code(as) and
489 code(es). Similarly, the a double flat and e double flat are
490 contracted to code(ases) and code(eses). For consistency, the dutch
491 names also include code(aes), code(aeses), code(ees) and
492 code(eeses)) consistency
494 If you are not comfortable with these names, you can make your own.
495 Note names for different languages are included with the example
496 initialisation files, amongst others English (C sharp is abbreviated
497 to code(cs)), Italian, Swedish and Norwegian. If you want to use
498 these names, issue code(\include "LANGUAGE.ly") where you could
499 substitute code(italiano), code(deutsch) etc. for LANGUAGE. You
500 should include these files at toplevel, i.e., before opening a
506 The previous examples all notes that were to be played sequentially, one
507 note following the other. You can also use LilyPond to typeset
508 chords. You do this by expressing in mudela simultaneous music,
509 i.e., notes that are to be played concurrently.
511 In Mudela you can form simultaneous music by enclosing notes in
512 pointed parentheses, bind(i.e.)bind(langle())bind(and)rangle(). ASCII
513 doesn't really have these delimiters, so Mudela uses the larger-than
514 (code(>)) and smaller-than (code(<)) signs instead. For example, a
515 D-major chord is expressed as
516 mudela(fragment,verbatim,center)(
520 Chords can be entered in the music in the same places that notes
521 can. As an example we give a snippet of ``Twinkle Twinkle Little
522 Star'' in chords. The chords may seem slightly unconventional, but
523 they only serve to show how chords work. We've aligned the chords in
524 the input on their starting beat just to help you reading it. This
525 layout does not influence the typesetting result in any way.
527 mudela(verbatim, fragment)(
531 <c e a> <b d a'> <b2 d g>
532 <a4 d f> <bes d f> <bes c e> <g c e>
533 <e a d> <a, g' cis'> <d2 f d'>
537 You can nest simultaneous and sequential music in any way you want,
539 mudela(verbatim,fragment)(
541 { c'8 <c' e'> c' <c' e'> } >
543 As you can see, LilyPond has some difficulty typesetting this
544 elegantly. To adequately solve this, you have to persuade LilyPond to
545 make separate stems for both sequential music lists. This is a topic
546 that is covered in bind(Section)ref(sec:polyphonic).
548 [Chords and relative mode]
551 sect(Adding nuances: articulation and dynamics)
553 Having just chords and notes does not give you real music. Real music
554 has more liveliness to it: music can have articulation, dynamics
555 (louder and softer), etc. This liveliness has notation, so LilyPond
556 can print it. We'll start out by explaining how to obtain the
557 smallest grains of nuance: the articulation of a single note. Articulation
558 is entered by writing a dash and the name of the desired articulation
559 mark. You have to add a backslash in front of the name to distinguish
560 it from the name of a note. mudela(fragment,verbatim)(
564 Typing a lot of staccato notes in this syntax will get tedious very
565 quickly. Therefore, Mudela has some handy abbreviations for
566 articulation marks such as staccato and tenuto. They are shown in the
571 \property Score.textstyle = typewriter
580 \type Lyrics\lyrics {
581 "."4 "-" "+" "|" ">" "\^{ }" }
583 \paper { linewidth = 12.\cm; }
586 Text and digits for fingering can be entered in the same manner: add a
587 dash and the text or digit to be printed:
588 mudela(fragment,verbatim)(
589 c''4-1 g''4-5 c''-"Sul tasto" )
590 Currently, the meaning of the
591 syntax `note-dash-digit/articulation/text' is just ``add a superscript to this
592 note.'' This is not in line with our goal to em(define) music with
593 Mudela. We hope that this will be fixed in a future version of the
594 language. In the meantime you can abuse this: the super- and
595 subscripts can be forced into up or down position respectively by entering an
596 a caret (code(^)) or an underscore, code(_) instead of the dash:
597 mudela(fragment,verbatim,center)(
598 c'4-^ c'4^^ c'''4-^ c'''4_^
601 Dynamic markings are another way to add a nuance to a note. They are
602 entered by adding the name for the dynamic sign after the note. You
603 should not enter a dash between the name and the note.footnote(This
604 is inconsistent. We hope that this will be fixed in a later
605 version of the language.)
606 mudela(verbatim,fragment)(
607 c4 \ff c4 \fp c4 c4 \ppp c4 c4 \sfz
612 sect(Bridging the notes: beams, slurs and ties)
614 Music typesetting does not use fixed symbols only. A lot of symbols
615 are variable: they run from one note to another. In LilyPond
616 terminology, such a symbol is called a em(spanner). To print a
617 spanner, you have to attach a marker to the note that begins it and to
618 the one that ends it.
620 It is your job to make sure that each spanner that you start, also ends.
621 If it doesn't, then Bad Things are likely to happen. If you end
622 spanners that are not started, LilyPond will
623 warn you about illegal ending markers.
625 LilyPond has a few spanners
628 The slur has the opening parenthesis as
629 start marker is. The stopping marker is the closing parenthesis.
631 mudela(fragment,center,verbatim)( c'4( )c'4 )
633 The slur is quite flexible: you can nest nop(slurs,)footnote(This is
634 inconsistent when compared to the syntax for articulation hints. This
635 will be fixed some time, we hope.) and you can connect a note with a
636 slur on both the left and the right side:
638 mudela(fragment,verbatim,center)(
639 c'4(( )c''4 )c'4( )g'4
644 Another spanner is the beam. The starting marker is the opening
645 bracket, then ending marker is the closing bracket. The brackets have
646 to be em(around) the beamed notes. footnote(Strictly speaking, a
647 beam is not a musical concept: beaming doesn't change the meaning of
648 music, it only clarifies the rhythmic structure. One might argue that
649 beams should not be present in a "music" language. Unfortunately,
650 LilyPond is not smart enough to insert beams into music on its own.
652 LilyPond does have code that guesses what the pattern should look
653 like, so that you don't have to specify the beaming for complicated
654 patterns. Alas, the algorithm used is not foolproof
655 yet: code([c8. c32 c32]) will produce incorrect results.)
657 mudela(fragment,verbatim)(
658 [c'8 c'] [c'16 c' c' c'] [c'16. c'32 c' c'16.]
661 dit(The tie) The tie is similar to the slur: it looks like a
662 slur, but a slur connects whole chords, whereas the tie connects note
663 heads. Tied notes should be played as one long note. In analogy with
664 TeX()'s tie (which ties together words with a space), LilyPond's tie
665 is entered as a tilde, `code(~)'.
667 The input convention for the tilde is somewhat peculiar when used in
668 conjunction with chords. Internally, the extra information that is
669 represented by the tilde has to be attached to a note (or to a rest,
670 for that matter). For this reason, you can't put the tilde between
671 two chords (as in code( <c' g'> ~ <c' g'>)). The tilde sign must be
672 directly after a note of the chords. It does not matter which
673 one. The following example demonstrates the use of ties:
674 mudela(fragment,verbatim,center)(
676 <c'2. ~ g' es''> <c'4 g' es''>
680 Crescendi and decrescendi can be printed in hairpin style. The
681 starting marker for the crescendo is code(\<), and for the decrescendo
682 code(\>). Both have code(\!) as the ending marker.
683 mudela(fragment, verbatim)(
686 { s4 \< \! s4 \> \! s2 } >
688 This example shows a trick: by attaching the markings to space rests
689 that run parallel to the whole note, you can have dynamic markings
697 We have focused on printing notes. Notation contains many other
698 constructs, constructs that help you with reading those notes.
699 Examples of such constructs are clefs, time signatures, keys etc.
700 LilyPond will try to generate these constructs as much as possible,
701 but not all such hints can be inserted automatically, and you can also
702 override some of the settings. This can be done by inserting various
703 commands between the music. The general form of these commands is
706 )center(code(\keyword argument argument ... ;))
708 These are the commands that are currently supported:
710 dit(code(\bar) var(bartype))
711 This command makes LilyPond print special bar
712 lines and repeat symbols. You can also use it to allow line breaks
713 when entering cadenzas. The argument var(bartype) is a string that
714 describes what kind of bar line to print.
716 mudela(fragment,verbatim)(
717 \bar "|:"; c'4 \bar ":|:"; c'4 \bar ":|"; c'4 \bar "||";
718 c'4 \bar "empty"; c'4 \bar "|.";
721 The command `code(\bar "empty")' does not create any visible bar
722 line, but it tells LilyPond to allow a linebreak at that
723 position. The `code(\bar)' command prints the specified symbol
724 immediately. If you give a `code(\bar)' command at the end of a
725 measure then the specified symbol replaces the automatic bar line;
726 otherwise the specified symbol appears in the middle of the measure.
727 The code(\bar) command does not affect metric structure.
729 dit(code(\cadenza) var(togglevalue)) This command toggles the
730 automatic printing of barlines. `code(\cadenza 1)' turns off the
731 automatically generated bar lines. They are switched on again with
732 `code(\cadenza 0)'. Then a bar line is printed, and LilyPond will act
733 as if you are again at the start of a measure.
736 This is useful when typesetting music without a meter (such as an ad
739 dit(code(\clef) var(clefname)) This command sets the current clef for notation,
740 i.e., a clef symbol is printed and the notes following this command
741 are shifted vertically. The argument is a string, the name of the
742 new clef. The default clef is the treble clef.
743 mudela(fragment,verbatim)(
749 dit(code(\key) var(pitch) var(type)) This command changes the current
750 key signature. The key signature is printed at the start of every
751 line. The var(type) argument is set to code(\major) or code(\minor)
752 to get major or minor keys, respectively. Omitting the second
753 argument gives major keys. The key of C-minor can thus be specified
754 as `code(\key es)' or `code(\key \c minor)'.
756 dit(code(\keysignature) var(pitchlist))
758 This command changes the current key signature. Unlike the
759 `code(\key)' command, this command can produce arbitrary key
760 signatures, which can be useful for unconventional keys or modes. The
761 key signature is given in the form of a list of notes. The notes will
762 be printed in the key signature in the order that they appear on the
763 list. For example, the key of C-minor can be specified as
764 `code(\keysignature bes es as)'. The command `code(\keysignature fis
765 es bis)' provides a more exotic example.
768 dit(code(\time) var(numerator)code(/)var(denominator))
769 This command changes the current time signature.
770 The default value for this time signature is common time (4/4).
772 dit(code(\partial) var(duration))
773 This command allows you to make
774 upsteps at the start of a piece.
775 The var(duration) argument has the same form as the duration of a
778 The `code(\partial)' command cannot be used to generate partial
779 measures in the middle of the music.
781 mudela(fragment,verbatim)(
784 [d'8 dis'] e' c''4 e'8 c''4
787 dit(code(\grouping) var(durationslist)) sets the metric structure of the measure.
788 Its effect can best be shown by an example:
789 mudela(fragment,verbatim)(
799 In practice, you won't be needing this command very often: the
800 grouping is switched automatically when you issue a code(\time)
801 command. It is set to a combination of groups
802 of 2 and 3 beats, with as many groups of
803 3 as possible (in other words: 4/4 is divided in two times two beats
807 The commands described above aren't really music, but they can best be
808 thought as as notes with no duration. Since they are grammatically
809 equivalent to notes, these commands can be used in the same places as
812 sect(Notation context)
814 COMMENT(This section is about translation contexts, a topic of LilyPond that
815 is somewhat advanced. You don't have to understand this to use
816 LilyPond to print simple music. If you don't want to typeset fancy
817 polyphonic music or tweak the LilyPond notation engine, you can skip
818 the next two sections.)
820 In bind(Section)ref(tutorial:more-staffs) it was explained that there
821 are more ways to notate a simple chord: as a single voice on a single
822 staff or in multiple staffs (and we'll soon see, that you can typeset
823 it as multiple voices on a staff). Obviously the concept of staff is
824 not really something musical. But what is it then?
826 The most simplistic explanation is: a staff is a graphic peculiarity
827 of the notation system. In other words, a staff is a graphic device,
828 a special picture of five lines on which one can print note heads. We
829 will call this view on the concept of staff `staff symbol' from now
833 there is more to a staff than just the symbol. A staff
834 contains---besides a staff symbol--- some more components:
836 it()A staff can have a key signature (printed at the left)
837 it()A staff can have a time signature (printed at the left)
838 it()A staff has bar lines
839 it()A staff has a clef (printed at the left)
843 To explain what a staff really is, we'll try to print music without
844 these components. Without those, it is still
845 possible to print music:
847 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
852 \remove "Time_signature_engraver";
853 \remove "Bar_engraver";
854 \remove "Staff_symbol_engraver";
855 \remove "Clef_engraver";
856 \remove "Key_engraver";
861 ) As you can see, you can still make out the general form of the
862 melody and the rhythm that is to be played, but the notation is
863 difficult to read. Moreover, the musical information is not complete.
864 The stress pattern in the notes can't be deduced from this output.
865 For this, we need a time signature:
869 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
874 \remove "Bar_engraver";
875 \remove "Staff_symbol_engraver";
876 \remove "Clef_engraver";
877 \remove "Key_engraver";
881 )Technically speaking you know where the strong and weak beats are, but
882 it is difficult to find them quickly. Bar lines help you in finding
883 the location of the notes within the measure:
886 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
891 \remove "Staff_symbol_engraver";
892 \remove "Clef_engraver";
893 \remove "Key_engraver";}
898 We can remedy part of the difficulties with reading pitches by adding a staff
902 \notes\relative c' { \time 2/4; g'4 c,4
903 a'4 f4 e c d2 } \paper {
908 \remove "Clef_engraver";
909 \remove "Key_engraver";
915 This makes the output decidedly easier to read, but you still don't
916 know what the pitches of the notes above are. So this is still not
917 enough. But suppose you see the following notation:
919 \notes \relative c' {\clef alto; \time 2/4; g'4 c,4 a'4 f4 e c d2 }
925 ) Now you know the pitch of the notes: you look at the start of the line
926 and see a clef, with this clef, you can determine the notated pitches.
927 You have found the em(context) in which the notation is to be
930 So the context determines the relationship between a piece of music
931 and its notation: you, the reader, use context to deduce music from
932 notation. Because LilyPond is a notation writer instead of a reader,
933 context works the other way around for Lily: with context a piece of
934 music can be converted to notation.
936 We see that a staff forms context, and that context is needed to
937 convert between notation and music. In LilyPond we turn around this
938 reasoning: LilyPond has a notion of notation context, and the staff is
939 just one example of a notation context. In fact, the arguments of the
940 code(\type) command (Staff, GrandStaff) were all names of different
943 We make one final observation before listing the standard notation
944 contexts. A score can contain many staffs; A staff can contain many
945 voices. This suggests that notation contexts are objects that can be
948 The following is a list of the contexts that are supported by
949 LilyPond. Each notation context is characterised by its name, the
950 notation elements it creates, and the contexts that it can contain.
952 dit(Voice) The code(Voice) context is a context that corresponds to a
953 voice on a staff. This context handles the conversion of noteheads,
954 dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests
956 dit(Staff) The code(Staff) context handles clefs, bar lines, keys,
957 accidentals. A code(Staff) context can contain code(Voice)
960 dit(RhythmicStaff) The code(RhythmicStaff) context is like the staff,
961 but much simpler: the notes are printed on one line, and pitches are
962 ignored. code(RhythmicStaff) can contain code(Voice) contexts.
964 dit(GrandStaff) A code(GrandStaff) context contains code(Staff)
965 contexts, and it adds a brace to the output at the
966 nop(left.)footnote(This is a major deficiency in the current
967 implementation. Currently stems, slurs and beams cannot be printed
968 across two staffs. In reality, a grand staff is a hybrid of one big
969 staff and two stacked staffs.)
971 A code(GrandStaff) context can contain
972 code(Staff)s. Typically, it will contain two code(Staff)s, one
973 treble staff, and one bass staff. The bar lines of the contained
974 staffs are connected vertically.
976 dit(StaffGroup) A code(StaffGroup) context contains code(Staff) or
977 code(Lyrics) contexts, and prints a bracket at the left. The bar
978 lines in the participating staffs are connected.
980 dit(Lyrics) As its name suggests, The code(Lyrics) context deals with
981 typesetting lyrics. This topic will be covered in
982 bind(Section)ref(tutorial:lyrics).
984 dit(Score) The code(Score) context is the toplevel context: no context can
985 contain a code(Score) context. The code(Score) context handles the
986 administration of time signatures. It also makes sure that items
987 such as clefs, time signatures, and key-signatures are aligned across staffs.
989 The code(Score) can contain code(Staff), code(StaffGroup),
990 code(Lyrics), code(GrandStaff) and code(RhythmicStaff) contexts.
992 COMMENT(do ChoireStaff)
996 If you are familiar with structured documents, you might see the
997 analogy of a context with a stylesheet: a stylesheet is neither
998 presentation nor information, but rather a recipe em(how) a specific
999 piece of information should be presented. The big difference with
1000 stylesheets is that in music notation the elements provided by context
1001 are essential to understanding what is notated.
1003 The notions of ``current clef'' and ``current position within the
1004 measure'' are all properties of notation contexts. Commands like
1005 code(\clef) and code(\cadenza) change these properties, and this
1006 explains why they are fundamentally different from musical expressions
1007 like notes and rests.
1009 A notation context is not a primitive element of LilyPond, but rather
1010 Later on, in bind(Section)ref(tutorial:engravers) we will explain
1011 how you can create your own contexts.
1014 sect(Nested music: multiple staffs)
1015 label(tutorial:more-staffs)
1017 Now we explain how to typeset music that runs in multiple staffs.
1018 Consider the following---somewhat unrealistic---example:
1021 \type GrandStaff <e'4 {\clef bass; g4^""} >
1024 In this example the music consists of two notes. The above would
1025 sound the same if it were written as a single chord on a single staff,
1032 ) The Mudela construct for multiple staffs reflects the similarity
1033 between the two examples: to get multiple staffs in Mudela you enter a
1034 chord, with an additional instruction to tell LilyPond that the chord
1035 does not represent notes stacked together, but staffs stacked
1038 If a piece of music is to be interpreted as a staff, then this can be
1039 expressed with the code(\type) construct. The following input says
1040 ``the quarter note with pitch e should be put on a staff.''
1046 ) The same can be done for the other note, i.e.,
1052 ) If you want to stack these staffs, you must create a chord of both:
1060 This looks reasonable, but the effect of this input is not what you
1068 ) Since there are no names specified for the desired staffs, LilyPond
1069 thinks your wishes are fullfilled by putting the code(g) on the same
1070 staff as the code(e). The correct solution is to label both staffs
1071 with different names, for example code(trebleStaff) and
1072 code(bassStaff). This makes LilyPond distinguish between them, and
1075 mudela(verbatim,fragment)(
1076 < \type Staff = trebleStaff e'4
1077 \type Staff = bassStaff g4
1081 ) The names that you choose do not matter just as long as they are
1082 different. This is almost right, except for the brace at the left and
1083 the clef of the second staff. If you want a brace, then you have to
1084 tell LilyPond that the chord you just formed is to be interpreted as a
1085 so-called grand staff. This is also done with the code(\type)
1086 command. The bass clef is made with a clef command: COMMENT(
1088 ) mudela(verbatim,fragment)(
1090 \type Staff = treblestaff e'4
1091 \type Staff = bassstaff { \clef "bass"; g4 }
1096 sect(Polyphonic music (or: Notation context properties))
1097 label(sec:polyphonic)
1099 In the section on notation contexts we explained that a notation
1100 context can have properties that influence the conversion from music
1101 to notation. A simple example of such a property is the clef: the
1102 type of a clef helps determines the vertical position of note heads in
1103 a staff. Some of these properties can be modified by commands such as
1104 code(\clef) and code(\time). But there is more: notation contexts
1105 also have properties are settable in a generic fashion. We will
1106 demonstrate this feature by printing multiple voices on a staff.
1108 Printing more than one voice on a staff, is not unlike printing
1109 multiple staffs stacked together. This suggests that the template
1113 \type Voice = one ...
1114 \type Voice = two ...
1118 ) On the ellipsis there should be music going from left to right, in
1119 other words, notes enclosed in braces. Let us try the following
1122 mudela(fragment,verbatim)(
1124 \type "Voice" = "one" { r4 as'4 () as'4 g'4 }
1125 \type "Voice" = "two" { g'2 f'4 e'4 }
1128 As you can see the result is not quite perfect. The notes on the last
1129 two beats look like plain chords and not like separate voices. What
1130 really happened was that the stems of the upper and lower voices were
1131 printed on top of each other.
1133 To remedy this, engravers traditionally make the stems of the lower
1134 voice point down, and the stems of the upper up, as shown in
1135 bind(Figure)ref(tutorial:multi-voice-fig).
1137 Surely the direction of a single stem is a property of the stem as a
1138 graphical object. But the fact that all of the stems in a voice point
1139 in the same direction is not directly graphical. Since this is a
1140 property shared by all the stems in the voice, this property is a
1141 property of the context code(Voice). The context code(Voice) has an
1142 attribute whose value is the direction to use for stems. You can
1143 change it to `up' by issuing the following phrase:
1145 \property "Voice"."ydirection" = "1"
1148 This command should be read as ``change the property called
1149 code(ydirection) within the current code(Voice) context to the value
1150 code(-1).'' For the property code(ydirection) the value code(1) means
1151 `up', and code(-1) means `down'. So, the
1152 proper way to code the polyphonic example is given in
1153 bind(Figure)ref(tutorial:multi-voice-fig).
1155 latexcommand(\begin{figure}[h])
1156 mudela(fragment,verbatim,center)(
1158 \type "Voice" = "one" {
1159 \property Voice.ydirection = "1"
1160 r4 as'4 () as'4 g'4 }
1161 \type "Voice" = "two" {
1162 \property Voice.ydirection = "-1"
1166 latexcommand(\caption{multiple voices})
1167 label(tutorial:multi-voice-fig)
1168 latexcommand(\end{figure})
1170 As you can see, this property also controls the directions of slurs,
1171 which explains the name code(ydirection).COMMENT(hmm)
1174 Other properties can also be set, and they can be within different
1175 contexts. In general, you can set a property by specifying
1176 code(\property) var(contexttype)code(.)var(propertyname) code(=)
1177 var(value). Both var(contexttype), var(propertyname) and var(value)
1180 The effect of a property is pretty much hardwired into the
1181 implementation (and thus subject to change), so we will not deal with
1182 all the possible properties in detail. Among other characteristics that
1183 can be set are the layout of slurs and beams. The initialisation file
1184 file(property.ly) explains most properties.
1187 label(tutorial:lyrics)
1189 Since a lyrics can have durations just like notes, we consider them to
1190 be music too. Entering lyrics in mudela has two aspects. First, you
1191 have to enter the text, i.e., the syllables along with their
1192 durations. After this, you have to specify how to convert these to
1195 Lyrics consist of syllables, which are strings together with
1196 durations. Previously we only entered note names, so for entering
1197 lyrics we have to instruct LilyPond that what we enter are not note
1198 names but strings. This instruction is the keyword
1199 code(\lyrics). After entering this keyword you can enter a musical
1200 construct---sequential music, simultaneous music, code(\type)
1201 entries, etc.--- but with syllables instead of pitches. For example:
1204 )verb(\lyrics { 'got8 me on my knees4, Le-8 lie! })COMMENT(
1206 ) Next comes the conversion to notation. LilyPond can't (yet) figure
1207 out that lyrics need different treatment than notes. As a result, the
1208 default conversion will try to put the text you entered as note heads
1209 onto a staff, and this will fail. This default must be overridden
1210 with a code(\type) keyword. Printing syllables of text in a line is
1211 done by a context called code(Lyrics). You can select this context
1212 with the code(\type) keyword. Here is a simple example:
1215 )mudela(fragment,verbatim)(
1216 \type Lyrics \lyrics { 'got8 me on my knees,4 Le-8 lie! })COMMENT(
1218 )The result is technically correct, but it needs a melody to make it
1219 performable: COMMENT(
1221 )mudela(fragment,verbatim)(
1223 \type Staff { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1224 \type Lyrics \lyrics { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
1228 ) The strings that makes up each syllable in the lyrics block are
1229 passed along to TeX() verbatim, so if you are proficient with TeX()
1230 you can do various nifty things. Just keep in mind that a syllable
1231 either starts with a letter (a character in the range `code(a)' to
1232 `code(z)' or `code(A)' to `code(Z)'), or it is a string enclosed
1233 quotes. It ends with either a number for the duration, or a space.
1234 These tricks are demonstrated in the following example:
1236 \type Lyrics \lyrics { 'got8 m\textbf{e}8 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1237 \type Lyrics \lyrics { 'got8 m{\bf e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1240 )mudela(fragment,verbatim)(<
1241 \type Staff { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1242 \type Lyrics \lyrics { 'got8 me8 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
1248 COMMENT(Groen is de kleur van geluk.)
1249 COMMENT(Dat geldt zeker voor Bj"ork)
1251 sect(Toplevel Mudela)
1253 Back in bind(Section)ref(sec:firsttune) we said we would defer
1254 discussion of toplevel constructions (e.g., code(\score)) to a later
1255 moment in time: and now we will look at these constructions. In
1256 general, Mudela looks like set of nested `blocks'. The general syntax
1257 for a block is code(\keyword { ... }).
1259 We will now discuss identifiers. Generally you can define an
1260 identifier by entering code(identifierName = ... ) where there can be
1261 a variety of things on the ellipsis.
1263 Here is a (partial) list of what you can abbreviate with identifiers
1266 it()The code(\score) block
1267 it()The code(\paper) block
1268 it()The code(\midi) block (to be explained in
1269 bind(Section)ref(tutorial:sound))
1270 it()Music (sequential music, simultaneous music etc.)
1273 it()Translators (to be explained in bind(Section)ref(tutorial:engravers))
1280 to the abbreviated entity, you must precede code(identifierName)
1281 with a backslash, i.e., code(\identifierName). For example:
1283 czerny = \notes { [c16 g e g] }
1285 \notes \type GrandStaff <
1287 { \clef bass; \czerny \czerny \czerny \czerny}
1291 stem_length = 6.0*\interline;
1297 Another interesting feature of this example are the assignments within
1298 the paper block. Some blocks, such as code(\paper), have a scope of
1299 their own. In the case of the code(\paper) block, these variables
1300 influence the characteristics of the output. As is shown, you can
1301 tune quantities like the stemlength, and enter simple
1302 nop(expressions.)footnote(The purpose of the negative linewidth is to
1303 prevent the music from being justified.) The identifiers that are
1304 meaningful are for the paper block is strongly implementation
1305 dependent, so they will not be listed here. Moreover, since most of
1306 the values are predefined to sensible defaults, there usually is no
1307 need to tune these values.
1309 Recall the properties of a context, that could be set with
1310 code(\property). It is a very general mechanism to tune the output of
1311 the music, that is neatly separated from the real music.
1312 Unfortunately, it is not convenient to type or read, and the precise
1313 effect of a setting property isn't always apparent from its
1314 definition. To remedy this, we can use an identifier to capture the
1315 meaning of a code(\property).
1318 stemup = \property Voice.ydirection = "1"
1319 stemdown = \property Voice.ydirection = "-1"
1320 shift = \property Voice.hshift = "1"
1322 \type "Staff" \notes <
1323 \type "Voice" = "one" { \stemup r4 as'4 () as'4 g'4 }
1324 \type "Voice" = "two" { \stemup \shift g'2 f'4 e'4 }
1325 \type "Voice" = "three" { \stemdown [d'8 dis'] [d' cis'] [c' b] c'4 } >
1326 \paper{ linewidth = -1.0\pt; }
1329 Several abbreviations like code(\stemup) are defined in the standard
1330 initialisation file file(property.ly). Setting or changing context
1331 properties can have a similar effect as the commands that were
1332 discussed in bind(Section)ref(sec:commands). Don't be fooled by the
1333 similarity in appearance between a declared property-setting entry and
1334 a real command like code(\clef) or code(\bar). Real commands are
1335 hardcoded into the language and they have to be terminated by
1338 You can also use identifiers to break up the heavy nesting that can
1339 occur in the code(\score) block. Another useful application is
1340 parametrisation of the music: if you use identifiers in the
1341 code(\score) block, you can make variations of the music by simply
1342 redefining those identifiers. One particular application of this is
1343 part extraction: by using identifiers and redefining them, one can
1344 print extracted parts and a full orchestral score from the same music
1349 label(tutorial:sound)
1351 You get output by combining music with definition a conversion to
1352 output. LilyPond currently supports one other conversion besides
1353 notation: the conversion from abstract music to sound. You can have
1354 LilyPond play the music that you entered. The format that is used for
1355 this output is MIDI. The result is not very pretty, but it is useful
1356 for prooflistening your files: typing errors stand out when you
1357 listen, especially if they involve accidentals.
1359 The only information that you need to enter is the
1360 tempo. (Unfortunately, at this time, this the only thing that can be
1361 tuned. The syntax for the tempo is code(\tempo )var(duration) =
1362 var(beatsperminute);), for example: COMMENT(
1368 \midi { \tempo 4 = 76; }
1373 sect(Contexts revisited: engravers)
1374 label(tutorial:engravers)
1376 As was promised, we will now take a dive into the more wizardrous parts
1377 of LilyPond: redefining (notation) contexts. We previously explained
1381 it()is a conversion from music to notation,
1382 it()can contain other contexts
1383 it()handles specific notation constructs
1386 This characterization almost automatically explains what the definition of a
1387 context should look like:
1389 it() It should have a name
1390 it()It should be part of the ``notation output definition,'' i.e., the
1393 It should contain a specification of what other contexts may be contained
1394 in the context we're defining.
1396 It should contain a list of the notation constructs to be
1400 LilyPond can create notation for a large number of symbols. This code
1401 is split up into basic building blocks. Each building block is called
1402 an em(engraver), and an engraver generally handles only one notation
1403 construct: the code(Clef_engraver) takes care of the clefs, the
1404 code(Time_signature_engraver) takes care of printing time signatures.
1406 A notation context is formed by a group of engravers. A special class
1407 in LilyPond---the code(Engraver_group_engraver)---allows engravers to
1408 cooperate in a group. A variant of this grouping object is the
1409 code(Line_group_engraver_group), which puts the output of all the
1410 engravers (clefs, bars, etc) into a compound object, so that these
1411 symbols can be treated as a whole.
1413 This explains the following definition, which is a simplified Staff context:
1417 \type "Line_group_engraver_group";
1420 \consists "Bar_engraver";
1421 \consists "Clef_engraver";
1422 \consists "Key_engraver";
1423 \consists "Local_key_engraver";
1424 \consists "Time_signature_engraver";
1425 \consists "Staff_symbol_engraver";
1427 defaultClef = treble;
1432 ) This context, named Staff, puts its graphic objects into a compound
1433 object (a so-called ``Line group''). At Staff level, bars, clefs,
1434 keys, accidentals, time signatures and the staff symbol are handled.
1435 A staff can contain a Voice context. You can also preset properties
1436 of contexts: for instance, the clef that is printed upon starting a
1437 Staff, is the treble clef.
1439 You can also declare contexts, and reference them. This is useful in
1440 combination with code(\remove "..."): code(\remove) does the opposite
1443 The real context definitions are in the standard initialisation
1444 file file(engraver.ly).
1446 As a practical example, we will show how to typeset polymetric music,
1447 i.e., music where the meter can differ for each staff. The solution
1448 is not very complicated: normally all timing information (time
1449 signature, rhythmic grouping) is synchronised across each staff. This
1450 is done by having only one administration for timing information: in
1451 the default configuration there is only one code(Timing_engraver), in
1452 the code(Score) context.
1454 All staffs use the information in the code(Timing_engraver) for
1455 generating bar lines and time signatures. So, we can have different
1456 timing for every staff, by moving the code(Timing_engraver) into the
1462 \type Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1463 \type Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1469 \remove "Timing_engraver";
1473 \consists "Timing_engraver";
1480 sect(Urtexts and context selection)
1481 label(tutorial:urtext)
1483 In bind(Section)ref(tutorial:more-staffs), we have shown you how to
1484 make multiple staffs, and explained that you have to label every staff
1485 (or more precisely: different contexts), to make sure that new ones
1486 are created when you need them. In this section, the real power of
1487 this mechanism will be unveiled.
1489 By naming other contexts that you create, you can reference other
1490 contexts than the current context from within the music. For example,
1491 from within the music that you enter for staff code(One), one could
1492 enter a small piece of music, and send it to staff code(Two), e.g.,
1495 ) mudela(fragment,verbatim)(
1497 \type Staff = one { c''4 \type Staff = two { c4 c4 } c''4 }
1498 \type Staff = two { \clef bass; g,4 g,4 g,4 g,4 }
1504 The mechanism of context selection can be used to fabricate an
1505 nop(Urtext)footnote(em(Urtext) is the German word for `original text'.
1506 The Urtext edition of a piece of music, is an edition that reflects
1507 the original writing of the composer. Such editions are useful for
1508 musicologists, and performers that want to perform authentic
1509 interpretations. However, for mere mortals, the Urtext can be quite
1510 hard to read. It might not contain fingering and beaming, and
1511 typically it is full of footnotes. Moreover, common interpretations
1512 may have emerged---after the composer died. For this reason, the
1513 music that can be had as Urtext usually is also available in enhanced
1514 and edited editions. ) and an edited edition from em(one source). We
1515 will use the first few bars of bind(J.)bind(S.)Bach's first Cello
1516 suite to demonstrate this. The example makes heavy use of space
1517 rests; here they are used as a placeholder to attach articulation
1521 bach = \notes \relative c { [g16 d' b' a] [b d, b' d,] }
1523 staffStuff = \notes { \clef bass; \time 4/4; s1 \bar "|."; }
1525 slursOne = \notes { s16( s s s s16 s s )s }
1526 slursTwo = \notes { s16-. s s() s s16() s s ()s }
1529 { < \type Voice = celloVoice { \bach \bach }
1530 \type Voice = celloVoice { \slursOne \slursOne }
1534 \type Voice = celloVoice { \bach \bach }
1535 \type Voice = celloVoice { \slursTwo \slursTwo }
1539 \paper { linewidth = -1.;}
1543 The slurs that you define should be put on the music that is defined
1544 by the code(\bach) identifier. By labeling a code(Voice) context, and
1545 directing both the articulation and the notes to that same code(Voice)
1546 context, the articulation is put over the right notes.
1550 label(tutorial:more-grammar)
1553 One of the things that you can do with music is
1554 em(transposing) it. If you want to transpose a piece of music, then
1555 you should prefix the keyword code(\transpose) along with the pitch
1556 (relative to the central C) for the transposition.footnote(the
1557 code(\type Staff) is to make sure that no separate staffs are created
1558 for the code(\scale) and code(\transpose cis' \scale) part.)
1562 scale = \notes \relative c' { [c8 d e f] }
1565 \type Staff { \scale \transpose cis' \scale }
1567 \paper { linewidth = -1.0; }
1571 sect(Staff switching)
1573 We have seen that contexts can be nested. This means that they form a
1574 tree. It is possible to edit this tree: for example, a code(Voice)
1575 context can be taken out of a code(Staff) context, and put into
1576 another. This has the effect of the voice switching staffs (something
1577 that often happens in keyboard music). The syntax for this operation
1578 with these particular contexts is code(\translator Staff = newStaffName).
1580 The effect is analogous to the first example in section
1581 ref(tutorial:urtext), but with the code(\translator) construction it
1582 is possible to split the real music and the commands that determine in
1583 which staff the music is printed. For example:
1588 aVoice = \type Voice = voiceA \notes { c''4 c4 c4 c''4 }
1589 bVoice = \type Voice = voiceB \notes { g,4 g,4 g,4 g,4 }
1591 % staff switching stuff
1592 switch = \type Voice = voiceA \notes { s4 \translator Staff = staffB s4
1593 s4 \translator Staff = staffA s4 }
1597 \type Staff = staffA < \aVoice \switch >
1598 \type Staff = staffB < \bVoice \clef bass; >
1600 \paper { linewidth = -1.; }
1604 Don't try to switch staffs when you are in the middle of a slur or
1605 beam, though: the spanners won't switch along.
1607 sect(Hairy durations: triplets)
1611 In the previous section we explained an operation that changes the
1612 pitches of music, transposition. In this section we will explain an
1613 operation that modifies the duration of the notes that you enter.
1614 When notes are part of a triplet, then the real of duration of the
1615 notes are 2/3 part of what their shape indicates:
1617 \times 2/3 { c'4 c'4 c'4 }
1620 To support this notion, Mudela allows you to modify the duration of a
1621 note by multiplication or division. A code(c'4) note that would be in a
1622 triplet is written as code(c'4*2/3). If you sequence a few of these
1623 notes, you get a triplet.footnote(We added a normal staff in the example to
1624 show the difference.)
1625 mudela(fragment,verbatim)(
1626 < \type Staff = staffA { \times 2/3 { c'8 c'8 c'8 } c'4}
1627 \type Staff = staffB { c''8 c''8 c''4 } >)
1629 LilyPond knows that these notes are no normal eighth notes, but the
1630 reader doesn't yet. To help the reader a beam or a bracket with a `3'
1631 should be printed. The special beam command `code([2/3)' and the
1632 matching close beam `code(]1/1)' will take care of that, and
1633 they also abbreviate the code(*2/3) part. If you want brackets in
1634 stead of beams, you can use `code(\[2/3])' and `code(\]1/1)'.
1635 mudela(fragment,verbatim)(
1636 < \type Staff = staffA {
1637 \times 2/3 { [ c'8 c'8 c'8 }
1638 \times 2/3 { c'8 c'8 c'8 }
1640 \type Staff = staffB { [c''8 c''8 c''8 c''8] }
1643 Other tuplets can be entered in the same way.
1644 mudela(fragment,verbatim)(
1645 < \type Staff = staffA {
1647 \times 7/6 { [c'8 c'8 c'8 c'8 c'8 c'8] }
1649 \type Staff = staffB {
1651 [c''8 c''8 c''8 c''8 c''8 c''8 c''8] } >
1654 For your convenience, code([2/3) can be further abbreviated to code([/3), and
1655 you can abbreviate code(]1/1) on the closing beam marker to code(]/1).
1657 mudela(fragment,verbatim)(
1658 < \type Staff = staffA {
1659 \times 2/3 { c'8 c'8 c'8 } c'4
1661 \type Staff = staffB { [c''8 c''8] c''4 } >
1665 bf(Important) the construct with code([/3) and
1666 code([/1) is a hack that sets a mode in the parser. This means that
1667 verb(id = \notes { c8 c8 c8 }
1668 notATriplet =\notes { [2/3 \id ]1/1 })
1669 does not produce a triplet. It will hopefully
1670 soon be replaced by a construction that mixes more elegantly with the
1678 label(tutorial:titling)
1680 A piece of sheet music isn't complete without proper opening and
1681 closing titles. LilyPond does not have any real support for setting
1682 text: that is a job best left to TeX(). But you can pass messages to
1683 TeX() from the input file. You can write TeX() macros to handle
1685 To do this, you add a code(\header) block
1686 to your input file. The format is quite simple,
1696 When the results of the music typesetting are output, the contents of
1697 code(\header) are also up into the TeX() file. Tools like
1698 code(ly2dvi) can use this information to generate pretty titling for
1699 your input file. Consult the manual page of code(ly2dvi) for more
1703 The code(\header) block should be at toplevel in mudela, and
1704 preferably at the top of the file. If you have an input file with
1705 multiple code(\score) blocks, you should add a header to every score,
1706 describing the different sub parts of the music piece, eg.
1710 "composer" = "Ludwig Van Bavaria";
1711 "title" = "Symphonie Megalomane";
1715 \header { movement = "Mit roher Kraft wild herausfahrend!"; }
1719 ... % some more music
1720 \header { movement = "Saut\'e comme un oeuf."; }
1725 If you want you can also put the code(\header) block at the top of the
1726 input file; it will then be put into every output file automatically.
1727 This will make it clear what the file contains as soon as you open it.