1 mailto(gnu-music-discuss@gnu.org)
4 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
7 COMMENT( This document contains Mudela fragments. You need at least
8 Yodl-1.30.18 to convert this to tex or html.
12 pipethrough(date) sucks.
14 paragraphs have too much space.
19 Mainly written by Han-Wen Nienhuys,
21 with help of (among others)
33 htmlbodyopt(bgcolor)(white)
34 htmlcommand(<font color=black>)
38 \textheight 53\baselineskip
39 \advance\textheight by \topskip
40 \marginparwidth 1 in % Width of marginal notes.
41 \oddsidemargin 0.25 in % Note that \oddsidemargin = \evensidemargin
42 \evensidemargin 0.25 in
43 \marginparwidth 0.75 in
44 \textwidth 5.875 in % Width of text line.
48 whenlatex(notableofcontents())
49 whentexinfo(notableofcontents())
51 article(Typesetting music with LilyPond)
52 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
53 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
56 latexcommand(\def\interexample{})
57 latexcommand(\def\preexample{\par})
58 latexcommand(\def\postexample{\par\medskip})
59 latexcommand(\def\file#1{{code(#1)}})
62 includefile(html-disclaimer.yo-urg)
67 label(tutorial:introduction)
68 latexcommand(\parindent2pc)
70 LilyPond prints music from a specification that you, the user, supply.
71 You have to give that specification using a em(language). This
72 document is a gentle introduction to that language, which is called
73 Mudela, an abbreviation for Music Definition Language.
75 We will demonstrate Mudela by presenting examples of input along with
76 resulting output. We will use English terms for notation, so if you
77 are not familiar with those, you should consult the glossary that is
78 distributed with LilyPond.
83 To demonstrate what LilyPond input looks like, we start off with a
84 full fledged, yet simple example. It is a convoluted version
85 of the famous menuet in bind(J.)bind(S.)Bach's em(Klavierbuechlein).
87 mudela(verbatim)(% lines preceded by a percent are comments.
96 d4 g,8 a b c d4 g, g |
97 e'4 c8 d e fis g4 g, g |
98 c4 d8()c b a( )b4 c8 b a g |
99 a4 [b8 a] [g fis] g2. |
104 g4 e8 fis g d cis4 b8 cis a4 |
105 a8-. b-. cis-. d-. e-. fis-.
112 linewidth = 14.0 \cm; % standard settings are too wide for a book
116 You can try to enter and save this text with a text editor. It is also
117 included with in the package as file(input/menuet.ly). Compile it
118 with LilyPond and view the output. Details of this procedure may vary
119 from system to system. To create the output, one would issue
120 code(ly2dvi menuet). file(ly2dvi) is a program that does the
121 job of calling LilyPond and TeX() and adjusting page margins.
123 If all goes well, this will create the file file(menuet.dvi).
124 To view this output, issue the command code(xdvi menuet).
126 Now that we are familiar with the procedure to produce output, we will
127 analyse the input itself, line by line.
129 verb(% lines preceded by a percent are comments.)COMMENT(
131 )The percent sign, `code(%)', introduces a line comment. If you want to
132 make larger comments, you can use block comments. These are delimited
133 by `code(%{)' and `code(%})'COMMENT(
135 )verb(\input "paper16.ly")COMMENT(
137 )By default, LilyPond will use definitions for a staff of 20
138 nop(point)footnote(A point is the standard measure of length for
139 printing. One point is 1/72.27 inch.) high. We want smaller output
140 (16 point staff height), you have to import the settings for that
141 size, which is done.COMMENT(
143 )verb(\score {) COMMENT(
145 ) A mudela file combines music with directions for outputting that
146 music. The music is combined with the output directions by putting
147 them into a code(\score) block.
152 )This makes LilyPond ready for accepting notes.
157 ) As we will see, pitches are combinations of octave, note name and
158 chromatic alteration. In this scheme, the octave is indicated by
159 using raised quotes (`code(')') and ``lowered'' quotes (commas:
160 `code(,)'). The central C is denoted by code(c'). The C one octave
161 higher is code(c''). One and two octaves below central C is denoted
162 by code(c) and code(c,) respectively.
164 For pitches in a long piece you might have to type many quotes. To
165 remedy this, LilyPond has a ``relative'' octave entry mode. In this
166 mode, octaves of notes without quotes are chosen such that a note is
167 as close as possible to the the preceding note. If you add a
168 high-quote an extra octave is added. The lowered quote (a comma) will
169 subtract an extra octave. Because the first note has no predecessor,
170 you have to give the (absolute) pitch of the note to start with.
177 ) What follows is sequential music, i.e.,
178 notes that are to be played and printed after each other.
185 ) This command changes the time signature of the current piece: a 3/4
186 sign is printed. This commond is also used to generate bar lines
187 in the right spots.COMMENT(
193 ) This command changes the current key to G-major. Although this
194 command comes after the code(\time) command, in the output, the key
195 signature comes before the time signature: LilyPond knows about music
196 typesetting conventions. COMMENT(
198 )verb( \repeat "volta" 2 ) COMMENT(
200 ) This command tells LilyPond that the following piece of music must
201 be played twice; code("volta") volta brackets should be used for
202 alternatives---if there were any.
207 )The subject of the repeat are again sequential notes. Since
208 code(\sequential) is such a common construct, a abbreviation is
209 provided: just leave off code(\sequential), and the result is the
214 ) This is a note with pitch code(d) (determined up to octaves). The
215 relative music was started with a code(c''), so the real pitch of this
216 note is code(d''). The code(4) designates the duration of the note
217 (it is a quarter note). COMMENT(
223 )These are notes with pitch code(a') and code(b'). Because their
224 duration is the same as the code(g), there is no need to enter the
225 duration (You may enter it anyway, eg. code(a4 b4)) COMMENT(
231 ) Three more notes. The `code(|)' character is a `barcheck'. When processing the
232 music, LilyPond will check that barchecks are found at the start of
233 a measure. This can help you track down errors.
240 ) So far, no notes were chromatically altered. Here is the first one
241 that is: code(fis). Mudela by default uses Dutch note names, and
242 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
243 sharp sign in the output. The program keeps track of key signatures,
244 and will only print accidentals if they are needed.
247 )verb(c8 d e fis)COMMENT(
249 )LilyPond guesses were beams can be added to eighth and shorter notes.
250 In this case, a beam over 4 eighths is added.
254 c4 d8( )c b a( )b4 c8 b a g |
257 ) The next line shows how to make a slur:
258 the beginning and ending note of the slur is marked with an opening and
259 closing parenthesis respectively. In the line shown above this is
260 done for two slurs. Slur markers (parentheses) are between
266 )Automatic beaming can be overridden by inserting beam marks
267 (brackets). Brackets are put around notes you want beamed.COMMENT(
271 )A duration with augmentation dot is notated
272 with the duration number followed by a period.COMMENT(
277 ) This ends the sequential music to be repeated. LilyPond will typset
278 a repeat bar. COMMENT(
284 )This line shows that Lily will print an accidental if that is
285 needed: the first C sharp will be printed with an accidental, the
286 second one without. COMMENT(
288 )verb( a8-. b-. cis-. d-. e-. fis-. )COMMENT(
290 )You can enter articulation signs either in a verbose or in an
291 abbreviated form. Here we demonstrate the abbreviated form: it is
292 formed by a dash and the the character for the articulation to use,
293 e.g. code(-.) for staccato as shown above. COMMENT(
300 Rests are denoted by the special notename code(r). You can also enter
301 an invisible rest by using the special notename code(s).
306 )All articulations have a verbose form, like code(\fermata). The
307 `command' code(\fermata) is not part of the
308 core of the language (most of the other discussed elements are), but
309 it is an abbreviation of a more complicated description of a fermata.
310 code(\fermata) names that description and is therefore called an
311 em(identifier). COMMENT(
323 )This specifies a conversion from music to notation output. Most of
324 the details of this conversions (font sizes, dimensions, etc.) have
325 been taken care of, but to fit the output in this document, it has
326 to be smaller. We do this by setting the line width to 10 centimeters
327 (approximately 4 inches).
334 )The last brace ends the code(\score) block.
336 There are two things to note here. The format contains musical
337 concepts like pitches and durations, instead of symbols and positions:
338 the input format tries to capture the meaning of em(music), and not
339 notation. Therefore Second, the format tries to be em(context-free):
340 a note will sound the same regardless of the current time signature,
343 The purpose of LilyPond informally is explained by the term `music
344 typesetter'. This is not a fully correct name: not only does the
345 program print musical symbols, it also makes esthetic decisions. All
346 symbols and their placement is em(generated) from a high-level musical
347 description. In other words, LilyPond would be best
348 described by `music compiler' or `music to notation compiler'.
350 The most interesting part of the input is the music
351 itself, in this case the sequence of notes. We will therefore focus
352 on music for now. Consequently, when we mean COMMENT(
358 ) we will leave out the the repetitive details for now and only print
362 sect(When you know the notes to nop(print)ellipsis())
364 The basic building block of music is the note. Here comes the full
365 explanation A note is made of a pitch and a duration. The pitch of
366 the central C is written as code(c'). This is in line with
367 musicological notation; there this pitch is transcribed as
368 nop(c)sups(1) or c'. A quarter-note duration is written as code(4).
369 So, to print a quarter note whose pitch is central C, you enter the
374 The duration of a note is specified as a number: a whole note is
375 denoted by 1, a half note by 2, a quarter by 4, and so on. If you
376 want to augment a duration with a dot, simply affix a period to the
377 number. You can also print notes longer than a whole. You do this by
378 using identifiers (code(\breve) and code(\longa)):
379 Here are some random notes to show how it works.
383 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
390 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
394 \translator { \type "Score_engraver";
396 \consists "Note_heads_engraver";
397 \consists "Stem_engraver";
398 \consists "Rhythmic_column_engraver";
403 subsect(Basic pitches)
405 The pitch code(c') consists of two parts: one part for the note name,
406 and one for the octave. The letter specifies which note name to use:
407 note names simply are the letters code(a) to code(g). The number of
408 apostrophes specifies the octave to use: the C below central C is denoted by
409 code(c).footnote(By convention, the A above central C at concert
410 pitch is the tone that is used to tune instruments. Its frequency is
411 about 440 Hz.) Octaves can be added and substracted by adding quotes
412 (code(')) and adding commas (code(,)).
413 mudela(fragment,verbatim,center)(
414 c,,4 c, c c' c'' c''' d'4 e'4 f'4 g'4
420 The names `a' to `g' for entering pitches are convenient: th7ey are
421 short, pronounceable and they resemble the words for pitches in normal
424 Enter flats and sharps. In English there is no standard terse word
425 for C sharp or C flat. For this reason, mudela uses a different,
426 non-English convention for entering altered pitches: a note is made
427 sharp by adding the suffix `--is' to its name, and flat by adding the
428 suffix `--es'. For a double sharp another `--is' suffix is added, for
429 flats another `--es' nop(suffix.)footnote(Variations on this
430 convention are used in a number of germanic languages, notably Dutch,
431 German, Swedish, and Norwegian.) The names for the alterations of C
432 are given in bind(Table)ref(notename-tab).
434 latexcommand(\begin{table}[h])
437 row(cell(English)cell(LilyPond))
439 row(cell(c double flat)cell(ceses))
440 row(cell(c flat)cell(ces))
441 row(cell(c natural)cell(c))
442 row(cell(c sharp)cell(cis))
443 row(cell(c double sharp)cell(cisis))
446 latexcommand(\caption{Default note names})
448 latexcommand(\end{table})
450 Throughout this document we will continue to use these names.footnote(
451 Mudela defaults to Dutch notenames. To make (Dutch) pronunciation
452 easier, the a-flat and e-flat are contracted to code(as) and
453 code(es). Similarly, the a double flat and e double flat are
454 contracted to code(ases) and code(eses). For consistency, the Dutch
455 names also include code(aes), code(aeses), code(ees) and
458 If you are not comfortable with these names, you can make your own.
459 Note names for different languages are included with the example
460 initialisation files, among others English (C sharp is abbreviated to
461 code(cs)), Italian, Swedish and Norwegian. If you want to use these
462 names, issue code(\include "LANGUAGE.ly") where you could substitute
463 code(italiano), code(deutsch) etc. for LANGUAGE. You should include
464 these files at toplevel, i.e., before opening a code(\score) block.
472 You can also use LilyPond to typeset chords. You do this by
473 expressing in mudela simultaneous music, i.e., notes that are to be
476 subsect(Where the chords have no names)
478 In Mudela you can form simultaneous music by entering
479 code(\simultaneous {)var(stuff)code( }). A D-major chord is expressed
483 \simultaneous { d'8 fis'8 a'8 d''8 }
484 )mudela(fragment,verbatim,center)(
485 \context Voice \simultaneous { d'8 fis'8 a'8 d''8 }
488 Simultaneous music are often used, so they an abbreviated form:
489 You can enter code(\simultaneous {)var(stuff)code( }) as
490 code(< )var(stuff)code( >).
492 Chords can be entered in the music in the same places that notes can.
493 As an example we give a snippet of ``Twinkle Twinkle Little Star'' in
494 chords. We've aligned the chords in the input on their starting beat
495 to help you reading it. This layout does not influence the
496 typesetting result in any way.
498 mudela(verbatim, fragment)(
502 <c e a> <b d a'> <b2 d g>
503 <a4 d f> <bes d f> <bes c e> <g c e>
504 <e a d> <a, g' cis'> <d2 f d'>
508 There is one thing to note, in sequences of chords, the (relative)
509 pitch of a is taken with reference to the first note of the previous
512 You can nest simultaneous and sequential music in any way you want,
515 )mudela(verbatim,fragment,center)(
517 { c'8 <c' e'> c' <c' e'> } >
521 As you can see, LilyPond has difficulty typesetting this
522 elegantly. To adequately solve this, you have to persuade LilyPond to
523 make separate stems for both sequential music lists. This is a topic
524 that is covered in bind(Section)ref(sec:polyphonic).
527 subsect(Chords with names)
529 In the previous section we have been talking more about `stacked notes'
530 rather than `chords'.
531 If you need to enter a lot of chords that have proper names, you can use
532 the code(\chords) mode as an alternative:
534 )mudela(verbatim,fragment,center)(
535 \chords\transpose c''{ c1 d e }
538 \chords\relative c''{ c1 d e }
541 subsect(Names with chords)
543 A more common problem is the typesetting of chord names. LilyPond has
544 a special kind of staff for this, the code(ChordNames) staff.
545 The code(ChordNames) staff accepts music like a normal staff,
546 but typesets only the name of each chord:
549 )mudela(verbatim,center)(
551 \context ChordNames {
553 { c1 d-min e-maj5+.9 }
561 ) Because the ChordNames staff accepts normal music, it can be transposed,
562 and you may enter it any way you like, either as chords or as notes.
564 sect(Adding nuances: articulation and dynamics)
566 Articulation is entered by writing a dash and the name of the
567 desired articulation mark. You have to add a backslash in front of
568 the name to distinguish it from the name of a note. COMMENT(
570 )mudela(fragment,verbatim)(
572 c''4-\tenuto )COMMENT(
574 )Typing a lot of staccato notes in this syntax will get tedious very
575 quickly. However, there are handy abbreviations for a few
576 articulations. They are shown in the following example: COMMENT(
580 \property Voice.textStyle = typewriter
588 % \paper { linewidth = 12.\cm; }
591 )Text and digits for fingering can be entered in the same manner: add a
592 dash and the text or digit to be printed:
595 )mudela(fragment,verbatim)(c''4-1 g''4-5 c''-"Sul tasto" )
597 Dynamic markings are another way to add a nuance to a note. They are
598 entered by adding the name for the dynamic sign after the note. COMMENT(
600 )mudela(verbatim,fragment)(
601 c4-\ff c4-\fp c4 c4-\ppp c4 c4-\sfz
606 sect(Bridging the notes: beams, slurs and ties)
608 A lot of symbols in notation have variable shape;they run from one
609 note to another. In LilyPond terminology, such a symbol is called a
610 em(spanner). To print a spanner, you have to attach a marker to the
611 note that begins it and to the one that ends it. These are the
612 spanners that are entered like this:
616 The slur has the opening parenthesis as
617 start marker is. The stopping marker is the closing parenthesis.
619 mudela(fragment,center,verbatim)( c'4( )c'4 )
621 You can nest nop(slurs,)footnote(This is
622 inconsistent when compared to the syntax for articulation hints. This
623 will be fixed some time, we hope.) and you can connect a note with a
624 slur on both the left and the right side:
626 mudela(fragment,verbatim,center)(
627 c'4(( )c''4 )c'4( )g'4
632 The starting marker for the beam is the opening bracket, the ending
633 marker is the closing bracket. The brackets have to be em(around) the
634 beamed notes. LilyPond has code that guesses what the pattern should
635 look like, so that you don't have to specify the beaming for
636 complicated patterns. COMMENT(
638 )mudela(fragment,verbatim)(
639 [c'8 c'] [c'16 c' c' c'] [c'16. c'32 c' c'16.]
642 The brackets themselves have no duration, so they are grammatically
643 equivalent to the barcheck.
645 dit(Tie) LilyPond's tie is entered as a tilde, `code(~)', in analogy
646 with TeX()'s tie (which ties together words with a space), The tie is
647 similar to the slur: it looks like a slur, but a slur connects whole
648 chords, whereas the tie connects note heads.
650 The following example demonstrates the use of ties:
651 mudela(fragment,verbatim,center)(
653 <c'2. g' es''> ~ <c'4 g' es''>
656 Since the tie is thought to be inbetween the notes, it has no
657 duration, and is grammatically equivalent to the barcheck.
660 Crescendi and decrescendi can be printed in hairpin style. The
661 starting marker for the crescendo is code(\<), and for the decrescendo
662 code(\>). Both have code(\!) as the ending marker.
663 mudela(fragment, verbatim)(
664 \relative c'' { c4 \< \! c4 \> \! c2
666 { s4 \< \! s4 \> \! s2 } > }
668 This example shows a trick: by attaching the markings to space rests
669 that run parallel to the whole note, you can have dynamic markings
674 It is your job to make sure that each spanner that you start, also
675 ends. If it doesn't, then Bad Things are likely to happen. If you end
676 spanners that are not started, LilyPond will warn you about invalid
682 Music notation constructs with no duration, like clefs and key
683 signatures, can be entered by inserting various
684 commands between the music. The general form of these commands is
687 )center(code(\keyword argument argument ... ;))COMMENT(
689 )These are the commands that are currently supported in alfabetic order:
691 dit(code(\bar) var(bartype))
692 This command makes LilyPond print special bar
693 lines and repeat symbols. You can also use it to allow line breaks
694 when entering cadenzas. The argument var(bartype) is a string that
695 describes what kind of bar line to print.
698 )mudela(fragment,verbatim)(
699 \bar "|:"; c'4 \bar ":|:"; c'4 \bar ":|"; c'4 \bar "||";
700 c'4 \bar "empty"; c'4 \bar "|.";
703 )The command `code(\bar "empty")' does not create any visible bar
704 line, but it tells LilyPond to allow a linebreak at that position.
705 The `code(\bar)' command prints the specified symbol where you enter
706 it. If you give a `code(\bar)' command at the end of a measure then
707 the specified symbol replaces the automatic bar line.
709 The code(\bar) command does not affect metric structure.
711 dit(code(\cadenza) var(togglevalue)) This command toggles the
712 automatic printing of barlines. `code(\cadenza 1)' turns off the
713 automatically generated bar lines. They are switched on again with
714 `code(\cadenza 0)'. Then a bar line is printed, and LilyPond will act
715 as if you are again at the start of a measure.
718 This is useful when typesetting music without a meter (such as an ad
721 dit(code(\clef) var(clefname)) This command sets the current clef for notation,
722 i.e., a clef symbol is printed and the notes following this command
723 are shifted vertically. The argument is a string, the name of the
724 new clef. The default clef is the treble clef.
725 mudela(fragment,verbatim)(
731 dit(code(\key) var(pitch) var(type)) This command changes the current
732 key signature. The key signature is printed at the start of every
733 line. The var(type) argument is an integer. Useful values are
734 available as the predefined identifiers code(\major) and
735 code(\minor). Omitting the second argument gives major keys. The
736 key of C-minor can be specified as `code(\key es)' or
737 `code(\key c \minor)'.
739 dit(code(\keysignature) var(pitchlist))
741 This command changes the current key signature. Unlike the
742 `code(\key)' command, this command can produce arbitrary key
743 signatures, which can be useful for unconventional keys or modes. The
744 key signature is given in the form of a list of notes. The notes will
745 be printed in the key signature in the order that they appear on the
746 list. For example, the key of C-minor can be specified as
747 `code(\keysignature bes es as)'. The command `code(\keysignature fis
748 es bis)' provides a more exotic example.
751 dit(code(\time) var(numerator)code(/)var(denominator))
752 This command changes the current time signature.
753 The default value for this time signature is common time (4/4).
755 dit(code(\partial) var(duration))
756 This command allows you to make
757 upsteps at the start of a piece.
758 The var(duration) argument has the same form as the duration of a
761 The `code(\partial)' command cannot be used to generate partial
762 measures in the middle of the music.
764 mudela(fragment,verbatim)(
767 [d'8 dis'] e' c''4 e'8 c''4
771 The commands described above do not give music that you could hear,
772 but within the language, they are "Music": they are grammatically
773 equivalent to notes, so they can appear in the same places as notes.
775 sect(Notation context)
778 There are different ways to print multiple parts: as chords on a
779 single staff, as voices on a single staff, or in multiple staffs. The
780 concept of staff is not something musical. But what is it then?
783 The most simplistic explanation is: a staff is a graphic peculiarity
784 of the notation system. In other words, a staff is a picture of five
785 lines on which one can print note heads. We will call this view on
786 the concept of staff `staff symbol' from now on.
789 there is more to a staff than the symbol. A staff
790 contains---besides a staff symbol--- more components:
794 it()A staff can have a key signature (printed at the left)
795 it()A staff can have a time signature (printed at the left)
796 it()A staff has bar lines
797 it()A staff has a clef (printed at the left)
801 To explain what a staff really is, we'll try to print music without
802 these components. Without those, it is still
803 possible to print music:
805 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
810 \remove "Time_signature_engraver";
811 \remove "Bar_engraver";
812 \remove "Staff_symbol_engraver";
813 \remove "Clef_engraver";
814 \remove "Key_engraver";
819 ) As you can see, you can still make out the general form of the
820 melody and the rhythm that is to be played, but the notation is
821 difficult to read. Moreover, the musical information is not complete.
822 The stress pattern in the notes can't be deduced from this output.
823 For this, we need a time signature:
827 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
832 \remove "Bar_engraver";
833 \remove "Staff_symbol_engraver";
834 \remove "Clef_engraver";
835 \remove "Key_engraver";
839 )Technically speaking you can find out where the strong and weak beats are, but
840 it is difficult to find them quickly. Bar lines help you in finding
841 the location of the notes within the measure:
844 \notes \relative c' { \time 2/4; g'4 c,4 a'4 f4 e c d2 }
849 \remove "Staff_symbol_engraver";
850 \remove "Clef_engraver";
851 \remove "Key_engraver";}
856 We can remedy part of the difficulties with reading pitches by adding a staff
860 \notes\relative c' { \time 2/4; g'4 c,4
861 a'4 f4 e c d2 } \paper {
866 \remove "Clef_engraver";
867 \remove "Key_engraver";
873 This makes the output decidedly easier to read, but you still don't
874 know what the pitches of the notes above are. So this is still not
875 enough. But suppose you see the following notation:
877 \notes \relative c' {\clef alto; \time 2/4; g'4 c,4 a'4 f4 e c d2 }
883 ) Now you know the pitch of the notes: you look at the start of the line
884 and see a clef, and with this clef, you can determine the notated pitches.
885 You have found the em(context) in which the notation is to be
888 So the context determines the relationship between a piece of music
889 and its notation: you, the reader, use context to deduce music from
890 notation. Because LilyPond writes notation, context works the
891 other way around for LilyPond: with context a piece of music can be
892 converted to notation.
894 We see that a staff forms context, and that context is needed to
895 convert between notation and music. In LilyPond we turn around this
896 reasoning: LilyPond has a notion of notation context, and the staff is
897 an example of a notation context. In fact, the arguments of the
898 code(\context) command (Staff, GrandStaff) were all names of different
899 contexts. A notation context is a conversion between music and
902 A score can contain many staffs and a staff can contain many voices.
903 This suggests that notation contexts are objects that can contain
904 other notation contexts.
906 The following is a list in alfabetic order of the contexts that are
907 supported by LilyPond. Each notation context is characterised by its
908 name, the notation elements it creates, and the contexts that it can
909 contain. description(
912 dit(GrandStaff) A code(GrandStaff) context contains code(Staff)
913 contexts, and it adds a brace to the output at the
914 nop(left.)footnote(The GrandStaff is limited, LilyPond can not do
915 cross staff beaming and slurring.)
917 A code(GrandStaff) context can contain code(Staff)s. Typically, it
918 will contain two code(Staff)s, one treble staff, and one bass
919 staff. The bar lines of the contained staffs are connected
922 dit(Lyrics) The code(Lyrics) context deals with
923 typesetting lyrics. This topic will be covered in
924 bind(Section)ref(tutorial:lyrics).
926 dit(Score) The code(Score) context is the toplevel context: no context
927 can contain a code(Score) context. The code(Score) context handles
928 the administration of time signatures. It also makes sure that
929 items such as clefs, time signatures, and key-signatures are aligned
930 in columns across staffs.
932 The code(Score) can contain code(Staff), code(StaffGroup),
933 code(Lyrics), code(GrandStaff) and code(RhythmicStaff) contexts.
935 dit(RhythmicStaff) The code(RhythmicStaff) context is like the staff,
936 but much simpler: the notes are printed on one line, and pitches are
937 ignored. code(RhythmicStaff) can contain code(Voice)
941 dit(Staff) The code(Staff) context handles clefs, bar lines, keys,
942 accidentals. A code(Staff) context can contain code(Voice)
945 dit(StaffGroup) A code(StaffGroup) context contains
946 code(Staff) or code(Lyrics) contexts, and prints a bracket at the
947 left. The bar lines in the participating staffs are connected.
950 dit(Voice) The code(Voice) context is a context that corresponds to a
951 voice on a staff. This context handles the conversion of noteheads,
952 dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests
954 COMMENT(do ChoireStaff)
958 If you are familiar with structured documents, you might see the
959 analogy of a context with a stylesheet: a stylesheet is neither
960 presentation nor information, but a recipe em(how) a specific piece of
961 information should be presented. Contrary to stylesheet, in music
962 notation the elements provided by context are essential to
963 understanding what is notated.
965 The notions of ``current clef'' and ``current position within the
966 measure'' are all properties of notation contexts. Commands like
967 code(\clef) and code(\cadenza) change these properties, and this
968 explains why they are fundamentally different from musical expressions
969 like notes and rests.
971 A notation context is not a primitive element of LilyPond: in
972 bind(Section)ref(tutorial:engravers) it will be explained how you can
973 form your own notation contexts.
975 sect(Nested music: multiple staffs)
976 label(tutorial:more-staffs)
978 Now we explain how to typeset music that runs in multiple staffs.
979 Consider the following---unrealistic---example:
982 \context GrandStaff <e'4 {\clef bass; g4^""} >
985 In this example the music consists of two notes. The above would
986 sound the same if it were written as a single chord on a single staff,
993 ) The Mudela construct for multiple staffs reflects the similarity
994 between the two examples: to get multiple staffs in Mudela you enter a
995 chord, with an additional instruction to tell LilyPond that the chord
996 does not represent notes stacked together, but staffs stacked
999 If a piece of music is to be interpreted as a staff, then this can be
1000 expressed with the code(\context) construct. The following input says
1001 ``the quarter note with pitch e should be put on a staff.''
1007 ) The same can be done for the other note, i.e.,
1013 ) If you want to stack these staffs, you must create a chord of both:
1016 < \context Staff e'4
1021 This looks reasonable, but the effect of this input is not what you
1024 < \context Staff e'4
1029 ) Since there are no names specified for the desired staffs, LilyPond
1030 thinks your wishes are fullfilled by putting the code(g) on the same
1031 staff as the code(e). The correct solution is to label both staffs
1032 with different names, for example code(trebleStaff) and
1033 code(bassStaff). This makes LilyPond distinguish between them, and
1036 mudela(verbatim,fragment)(
1037 < \context Staff = trebleStaff e'4
1038 \context Staff = bassStaff g4
1042 ) The names that you choose do not matter as long as they are
1043 different. This is almost right, except for the brace at the left and
1044 the clef of the second staff. If you want a brace, then you have to
1045 tell LilyPond that the chord you formed is to be interpreted as a
1046 so-called grand staff. This is also done with the code(\context)
1047 command. The bass clef is made with a clef command: COMMENT(
1049 ) mudela(verbatim,fragment)(
1050 \context GrandStaff <
1051 \context Staff = treblestaff e'4
1052 \context Staff = bassstaff { \clef "bass"; g4 }
1057 sect(Polyphonic music (or: Notation context properties))
1058 label(sec:polyphonic)
1060 In the section on notation contexts we explained that a notation
1061 context can have properties that influence the conversion from music
1062 to notation. A simple example of such a property is the clef: the
1063 type of a clef helps determines the vertical position of note heads in
1064 a staff. Some of these properties can be modified by commands such as
1065 code(\clef) and code(\time). But notation contexts can have other
1066 properties, that are settable in
1067 a generic fashion. We will demonstrate this feature by printing
1068 multiple voices on a staff.
1070 Printing more than one voice on a staff is like printing multiple
1071 staffs stacked together. This suggests that the template to follow is
1076 \context Voice = one ...
1077 \context Voice = two ...
1081 ) On the ellipsis there should be music going from left to right, in
1082 other words, notes enclosed in braces. Let us try the following counterpoint:COMMENT(
1084 )mudela(fragment,verbatim)(
1086 \context "Voice" = "one" { r4 as'4 () as'4 g'4 }
1087 \context "Voice" = "two" { g'2 f'4 e'4 }
1090 As you can see the result is not perfect. The notes on the last
1091 two beats look like plain chords and not like separate voices. What
1092 happened was that the stems of the upper and lower voices were
1093 printed on top of each other.
1095 To remedy this, engravers traditionally make the stems of the lower
1096 voice point down, and the stems of the upper up, as shown in
1097 bind(Figure)ref(tutorial:multi-voice-fig).
1099 Surely the direction of a single stem is a property of the stem as a
1100 graphical object. But the fact that all of the stems in a voice point
1101 in the same direction is not directly graphical. Since this is a
1102 property shared by all the stems in the voice, this property is a
1103 property of the context code(Voice). The context code(Voice) has an
1104 attribute whose value is the direction to use for stems. You can
1105 change it to `up' by issuing the following phrase:
1107 \property "Voice"."verticalDirection" = "1"
1110 This command should be read as ``change the property called
1111 code(verticalDirection) within the current code(Voice) context to the value
1112 code(-1).'' For the property code(verticalDirection) the value code(1) means
1113 `up', and code(-1) means `down'. So, the
1114 proper way to code the polyphonic example is given in
1115 bind(Figure)ref(tutorial:multi-voice-fig).
1117 latexcommand(\begin{figure}[h])
1118 mudela(fragment,verbatim,center)(
1120 \context "Voice" = "one" {
1121 \property Voice.verticalDirection = "1"
1122 r4 as'4 () as'4 g'4 }
1123 \context "Voice" = "two" {
1124 \property Voice.verticalDirection = "-1"
1128 latexcommand(\caption{Multiple voices})
1129 label(tutorial:multi-voice-fig)
1130 latexcommand(\end{figure})
1132 As you can see, this property also controls the directions of slurs.
1134 Other properties can also be set, and they can be within different
1135 contexts. In general, you can set a property by specifying
1136 code(\property) var(contexttype)code(.)var(propertyname) code(=)
1137 var(value). Both var(contexttype), var(propertyname) and var(value)
1140 The effect of a property is pretty much hardwired into the
1141 implementation (and thus subject to change), so we will not deal with
1142 all the possible properties in detail. Among other characteristics
1143 that can be set are the layout of slurs and beams. The initialisation
1144 file file(property.ly) and the reference manual contain explanations
1148 label(tutorial:lyrics)
1150 Since a lyrics can have durations like notes, we consider them to
1151 be music too. Entering lyrics in mudela has two aspects. First, you
1152 have to enter the text, i.e., the syllables along with their
1153 durations. After this, you have to specify how to convert these to
1156 Lyrics consist of syllables, which are strings together with
1157 durations. For entering lyrics we have to instruct LilyPond that what
1158 we enter are not note names but strings. This instruction is the
1159 keyword code(\lyrics). After entering this keyword you can enter a
1160 musical construct---sequential music, simultaneous music, code(\context)
1161 entries, etc.--- but with syllables instead of pitches. For example:
1164 )verb(\lyrics { 'got8 me on my knees4, Le-8 lie! })COMMENT(
1166 ) Next comes the conversion to notation. LilyPond can't (yet) figure
1167 out that lyrics need different treatment than notes. As a result, the
1168 default conversion will try to put the text you entered as note heads
1169 onto a staff, and this will fail. This default must be overridden
1170 with a code(\context) keyword. Printing syllables of text in a line is
1171 done by a context called code(Lyrics). You can select this context
1172 with the code(\context) keyword. Here is a simple example with output:
1175 )mudela(fragment,verbatim)(
1176 \context Lyrics \lyrics { 'got8 me on my knees,4 Le-8 lie! })COMMENT(
1178 )The result is technically correct, but it needs a melody to make it
1179 perfor0mable: COMMENT(
1181 )mudela(fragment,verbatim)(
1184 \property Voice.beamAuto = "0" % no beams in melody
1185 c''8. c''16 bes'8. a'16 g'4 f'8 g'4.
1187 \context Lyrics \lyrics { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
1191 ) The strings that makes up each syllable in the lyrics block are
1192 passed along to TeX() verbatim, so if you are proficient with TeX()
1193 you can do various nifty things. Keep in mind that a syllable
1194 either starts with a letter (a character in the range `code(a)' to
1195 `code(z)' or `code(A)' to `code(Z)'), or it is a string enclosed
1196 double quotes. It ends with either a number for the duration, or a space.
1197 These tricks are demonstrated in the following example:
1201 \context Lyrics \lyrics { 'got8 m\textbf{e}8 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1202 \context Lyrics \lyrics { 'got8 m{\bf e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1205 )mudela(fragment,verbatim)(<
1207 \property Voice.beamAuto = "0" % no beams in melody
1208 c''8. c''16 bes'8. a'16 g'4 f'8 g'4.
1210 \context Lyrics \lyrics { 'got8 me8 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
1215 ) COMMENT(Groen is de kleur van geluk. Dat geldt zeker voor Bj"ork)
1217 sect(Toplevel Mudela)
1219 Back in bind(Section)ref(sec:firsttune) we said we would ignore
1220 toplevel constructions (e.g., code(\score)) until a later moment.
1221 Now we will look at these constructions.
1224 Mudela allows you to name constructs of the language. This is done by
1225 using an em(identifier). Generally you can define an
1226 identifier by entering code(identifierName = ... ) where there can be
1227 a variety of things on the ellipsis.
1229 Here is a (partial) list of what you can abbreviate with identifiers
1232 it()The code(\score) block
1233 it()The code(\paper) block
1234 it()The code(\midi) block (to be explained in
1235 bind(Section)ref(tutorial:sound))
1236 it()Music (sequential music, simultaneous music etc.)
1239 it()Translators (to be explained in bind(Section)ref(tutorial:engravers))
1246 to the abbreviated entity, you must precede code(identifierName)
1247 with a backslash, i.e., code(\identifierName). For example:
1249 czerny = \notes { [c16 g e g] }
1251 \notes \context GrandStaff <
1253 { \clef bass; \czerny \czerny \czerny \czerny}
1261 You can also see identifiers in action within the code(\paper) block:
1262 the value code(-1.0) is assigned to code(linewidth). Within the
1263 code(\paper) block, identifiers are not used as abbreviation only:
1264 assigning to some identifiers can influence the output: in this case,
1265 the music line is printed at natural width.
1267 Recall the properties of a context, that could be set with
1268 code(\property). It is a very general mechanism to tune the output of
1269 the music, that is neatly separated from the real music.
1270 Unfortunately, it is not convenient to type or read, and the precise
1271 effect of a setting property isn't always apparent from its
1272 definition. To remedy this, we can use an identifier to capture the
1273 meaning of a code(\property).
1276 stemup = \property Voice.verticalDirection = "1"
1277 stemdown = \property Voice.verticalDirection = "-1"
1278 shift = \property Voice.hshift = "1"
1280 \context "Staff" \notes <
1281 \context "Voice" = "one" { \stemup r4 as'4 () as'4 g'4 }
1282 \context "Voice" = "two" { \stemup \shift g'2 f'4 e'4 }
1283 \context "Voice" = "three" { \stemdown [d'8 dis'] [d' cis'] [c' b] c'4 } >
1284 \paper{ linewidth = -1.0\pt; }
1287 Several abbreviations like code(\stemup) are defined in the standard
1288 initialisation file file(property.ly). Setting or changing context
1289 properties can have a similar effect as the commands that were
1290 discussed in bind(Section)ref(sec:commands). Don't be fooled by the
1291 similarity in appearance between a declared property-setting entry and
1292 a real command like code(\clef) or code(\bar). Real commands are
1293 hardcoded into the language and they have to be terminated by
1297 label(tutorial:sound)
1299 You get output by combining music with definition a conversion to
1300 output. LilyPond currently supports one other conversion besides
1301 notation: the conversion from abstract music to sound. You can have
1302 LilyPond play the music that you entered. The format that is used for
1303 this output is MIDI. The result is not very pretty, but it is useful
1304 for prooflistening your files: typing errors stand out when you
1305 listen, especially if they involve accidentals.
1307 The only information that you need to enter is the
1308 tempo (Unfortunately, at this time, this the only thing that can be
1309 tuned.). The syntax for the tempo is code(\tempo )var(duration) =
1310 var(beatsperminute);, for example: COMMENT(
1315 \midi { \tempo 4 = 76; }
1320 sect(Contexts revisited: engravers)
1321 label(tutorial:engravers)
1325 As was promised, we will now take a dive into the more wizardrous parts
1326 of LilyPond: redefining (notation) contexts. We previously explained
1330 it()is a conversion from music to notation,
1331 it()can contain other contexts
1332 it()handles specific notation constructs
1335 This characterization almost automatically explains what the definition of a
1336 context should look like:
1338 it() It should define a name
1339 it()It should be part of the ``notation output definition,'' i.e., the
1342 It should contain a specification of what other contexts may be contained
1343 in the context we're defining.
1345 It should contain a list of the notation constructs to be
1349 LilyPond can create notation for a large number of symbols. This code
1350 is split up into basic building blocks. Each building block is called
1351 an em(engraver), and an engraver generally handles only one notation
1352 construct: the code(Clef_engraver) takes care of the clefs, the
1353 code(Time_signature_engraver) takes care of printing time signatures,
1356 A notation context is formed by a group of engravers. A special class
1357 in LilyPond---the code(Engraver_group_engraver)---allows engravers to
1358 cooperate in a group, thus forming a notation context.
1360 The following definition shows a simplified Staff context: COMMENT(
1365 \context "Engraver_group_engraver";
1368 \consists "Bar_engraver";
1369 \consists "Clef_engraver";
1370 \consists "Key_engraver";
1371 \consists "Local_key_engraver";
1372 \consists "Time_signature_engraver";
1373 \consists "Staff_symbol_engraver";
1375 defaultClef = treble;
1380 ) This context, named Staff, puts its graphic objects into a compound
1381 object (a so-called ``Line group''). At Staff level, bars, clefs,
1382 keys, accidentals, time signatures and the staff symbol are handled.
1383 A staff can contain a Voice context. You can also preset properties
1384 of contexts: for instance, the clef that is printed upon starting a
1385 Staff, is the treble clef.
1389 As a practical example, we will show how to typeset polymetric music,
1390 i.e., music where the meter can differ for each staff. The solution
1391 is not very complicated: normally all timing information (time
1392 signature, rhythmic grouping) is synchronised across each staff. This
1393 is done by having only one administration for timing information: in
1394 the default configuration there is only one code(Timing_engraver), in
1395 the code(Score) context.
1397 All staffs use the information in code(Score) context's the
1398 code(Timing_engraver) for generating bar lines and time signatures.
1399 So, we can have different timing for every staff, by moving the
1400 code(Timing_engraver) into the Staff context.
1402 You can also declare contexts, and reference them. This is useful in
1403 combination with code(\remove "..."): code(\remove) does the opposite
1404 of code(\consists). This example demonstrates how to move the
1405 code(Timing_engraver) from code(Score) context into code(Staff)
1412 \context Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1413 \context Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1419 \remove "Timing_engraver";
1423 \consists "Timing_engraver";
1429 The context definitions provided as a default are in the standard
1430 initialisation file file(engraver.ly).
1433 sect(Urtexts and context selection)
1434 label(tutorial:urtext)
1436 In bind(Section)ref(tutorial:more-staffs), we have shown you how to
1437 make multiple staffs, and explained that you have to label every staff
1438 (or more precisely: different contexts), to make sure that new ones
1439 are created when you need them. In this section, the real power of
1440 this mechanism will be unveiled.
1442 By naming other contexts that you create, you can reference other
1443 contexts than the current context from within the music. For example,
1444 from within the music that you enter for staff code(One), one could
1445 enter a small piece of music, and send it to staff code(Two), e.g.,
1448 ) mudela(fragment,verbatim)(
1450 \context Staff = one { c''4 \context Staff = two { c4 c4 } c''4 }
1451 \context Staff = two { \clef bass; g,4 g,4 g,4 g,4 }
1457 The mechanism of context selection can be used to fabricate an
1458 nop(Urtext)footnote(em(Urtext) is the German word for `original text'.
1459 The Urtext edition of a piece of music, is an edition that reflects
1460 the original writing of the composer. Such editions are useful for
1461 musicologists, and performers that want to perform authentic
1462 interpretations. However, for mere mortals, the Urtext can be
1463 hard to read. It might not contain fingering and beaming, and
1464 typically it is full of footnotes. Moreover, common interpretations
1465 may have emerged---after the composer died. For this reason, the
1466 music that can be had as Urtext usually is also available in enhanced
1467 and edited editions. ) and an edited edition from em(one source). We
1468 will use the first few bars of bind(J.)bind(S.)Bach's first Cello
1469 suite to demonstrate this. The example makes heavy use of space
1470 rests; here they are used as a placeholder to attach articulation
1474 bachMotive = \notes \relative c { g16 d' b' a b d, b' d, }
1475 bach = \sequential { \clef bass; \time 4/4; \bachMotive \bachMotive \bar "|."; }
1476 slursOne = \notes { s16( s s s s16 s s )s }
1477 slursTwo = \notes { s16-. s s() s s16() s s ()s }
1481 \context Voice = celloVoice { \bach}
1482 \context Voice = celloVoice { \slursOne \slursOne }
1485 \context Voice = celloVoice { \bach }
1486 \context Voice = celloVoice { \slursTwo \slursTwo }
1489 \paper { linewidth = -1.;}
1493 The slurs that you define should be put on the music that is defined
1494 by the code(\bach) identifier. By labeling a code(Voice) context, and
1495 directing both the articulation and the notes to that same code(Voice)
1496 context, the articulation is put over the right notes.
1500 label(tutorial:more-grammar)
1503 One of the things that you can do with music is em(transposing) it.
1504 If you want to transpose a piece of music, then you should prefix it
1505 with the keyword code(\transpose) along with the pitch (relative to
1506 the central C, i.e., code(c')) for the transposition.footnote(the
1507 code(\context Staff) is to make sure that no separate staffs are created
1508 for the code(\scale) and code(\transpose cis' \scale) part.)
1512 scale = \notes \relative c' { [c8 d e f] }
1515 \context Staff { \scale \transpose cis' \scale }
1517 \paper { linewidth = -1.0; }
1521 sect(Staff switching)
1523 We have seen that contexts can be nested. This means that they form a
1524 tree. It is possible to edit this tree: for example, a code(Voice)
1525 context can be taken out of a code(Staff) context, and put into
1526 another. This has the effect of the voice switching staffs (something
1527 that often happens in keyboard music). The syntax for this operation
1528 with these particular contexts is code(\translator Staff = newStaffName).
1530 The effect is analogous to the first example in section
1531 ref(tutorial:urtext), but with the code(\translator) construction it
1532 is possible to split the real music and the commands that determine in
1533 which staff the music is printed. For example:
1538 aVoice = \context Voice = voiceA \notes { c''4 c4 c4 c''4 }
1539 bVoice = \context Voice = voiceB \notes { g,4 g,4 g,4 g,4 }
1541 % staff switching stuff
1542 switch = \context Voice = voiceA \notes { s4 \translator Staff = staffB s4
1543 s4 \translator Staff = staffA s4 }
1547 \context Staff = staffA < \aVoice \switch >
1548 \context Staff = staffB < \bVoice \clef bass; >
1550 \paper { linewidth = -1.; }
1554 If you want to switch staffs you are in the middle of a slur or a
1555 beam, the staffs should have a fixed distance. You do this by using the PianoStaff context.
1556 mudela(verbatim,center)(
1558 \context PianoStaff <
1559 \context Staff=one \notes{ s2 }
1560 \context Staff=two \notes\relative c{
1563 [c8( e \translator Staff=one g )c]
1574 The notes in a triplet take 2/3 of their notated duration. The syntax
1575 for triplet in LilyPond reflects this. To make a triplet, you enter
1578 )mudela(verbatim,fragment,center)(
1579 \times 2/3 { c''4 c''4 c''4 }
1584 Of course, you can also use different ratios, and use beamed notes or
1588 \context Voice \times 4/5 { [c''8 c''16 c''16] r8 [g'8 g'8] }
1591 If you make a tuplet of beamed notes, where the beam is as wide as
1592 the bracket, the bracket is omitted.
1596 A repeated piece of music can consist of two parts: one part to be
1597 repeated, and optionally, a list of alternative endings:
1600 )mudela(verbatim,fragment,center)(
1604 \repeat "volta" 2 { b c }
1610 ) The number code(repeat-count) defines how many times the piece should be
1611 played. You may leave out the code(\alternative) part. There must not
1612 be more alternative endings than the code(repeat-count).
1614 A less intuitive form may be needed for lyrics, when there are
1615 a couple alternatives, but nothing is repeated. The code(\repeat) command
1616 must be present, but it may specify an empty music list:
1619 )mudela(verbatim,fragment,center)(
1620 \context Lyrics \lyrics {
1621 \repeat "fold" 2 { }
projects / lilypond.git / blob