7 * Introduction:: Introduction
8 * The first tune:: The first tune
9 * Lyrics and chords:: Lyrics and chords
10 * Piano music:: Piano music
11 * end of tutorial:: The end
18 LilyPond prints music from a specification that you, the user, supply.
19 You have to give that specification using a @emph{language}. This
20 document is a gentle introduction to that language, which is called
21 Lilypond, an acronym of Music Definition Language.
23 This tutorial will demonstrate how to use Lilypond by presenting
24 examples of input along with resulting output. We will use English
25 terms for notation. In case you are not familiar with those, you may
26 consult the glossary that is distributed with LilyPond.
28 The examples discussed are included in the distribution, in the
29 subdirectory @file{input/tutorial/}. It is recommended that you
30 experiment with writing Lilypond input yourself, to get a feel for
34 @section The first tune
37 To demonstrate what LilyPond input looks like, we start off with a
38 full fledged, yet simple example. It is a convoluted version
39 of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
42 % lines preceded by a percent are comments which
43 % are ignored by Lilypond.
47 \relative c'' \sequential{
52 d4 g,8 a b c d4 g, g |
53 e'4 c8 d e fis g4 g, g |
54 c4 d8()c b a( )b4 c8 b a g |
55 a4 [b8 a] [g fis] g2. |
60 g4 e8 fis g d cis4 b8 cis a4 |
61 a8-. b-. cis-. d-. e-. fis-.
68 % standard settings are too wide for a book
74 Enter it (or copy it, the filename is @file{menuet.ly}), compile it
75 with LilyPond and view the output. Details of this procedure may vary
76 from system to system. To create the output, one would issue the
77 command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
78 the job of running LilyPond and @TeX{}, handling of titles and
79 adjusting of page margins.
81 If all goes well, the file @file{menuet.dvi} will be created.
82 To view this output, issue the command `@code{xdvi menuet}'.
84 Now that we are familiar with the procedure of producing output, we
85 will analyse the input, line by line.
87 % lines preceded by a percent are comments which
88 % are ignored by Lilypond.
90 The percent sign, `@code{%}', introduces a line comment. If you want to
91 make larger comments, you can use block comments. These are delimited
92 by `@code{%@{}' and `@code{%@}}'
98 By default, LilyPond will use definitions for a 20
99 point@footnote{A point is the standard measure of length for
100 printing. One point is 1/72.27 inch.} high staff. We want smaller
101 output (16 point staff height), so we must import the settings for
102 that size, which is done.
108 A lilypond file combines music with directions for outputting that
109 music. The music is combined with the output directions by putting
110 them into a @code{\score} block.
116 This makes LilyPond ready for accepting notes.
122 As we will see, pitches are combinations of octave, note name and
123 chromatic alteration. In this scheme, the octave is indicated by
124 using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
125 `@code{,}'). The central C is denoted by @code{c'}. The C one octave
126 higher is @code{c''}. One and two octaves below the central C is
127 denoted by @code{c} and @code{c,} respectively.
129 For pitches in a long piece you might have to type many quotes. To
130 remedy this, LilyPond has a ``relative'' octave entry mode. In this
131 mode, octaves of notes without quotes are chosen such that a note is
132 as close as possible (graphically, on the staff) to the the preceding
133 note. If you add a high-quote an extra octave is added. The lowered
134 quote (a comma) will subtract an extra octave. Because the first note
135 has no predecessor, you have to give the (absolute) pitch of the note
142 What follows is sequential music, i.e.,
143 notes that are to be played and printed after each other.
149 This command changes the time signature of the current piece: a 3/4
150 sign is printed. This command is also used to generate bar lines in
157 This command changes the current key to G-major. Although this
158 command comes after the @code{\time} command, in the output, the key
159 signature comes before the time signature: LilyPond knows about music
160 typesetting conventions.
166 This command tells LilyPond that the following piece of music must
167 be played twice; @code{"volta"} means that volta brackets should be used
168 for alternatives---if there were any.
174 The subject of the repeat is again sequential music. Since
175 @code{\sequential} is such a common construct, a shorthand is provided:
176 just leave off @code{\sequential}, and the result is the same.
182 This is a note with pitch @code{d} (determined up to octaves). The
183 relative music was started with a @code{c''}, so the real pitch of this
184 note is @code{d''}. The @code{4} designates the duration of the note
185 (it is a quarter note).
191 These are notes with pitch @code{a} and @code{b}. Because their
192 duration is the same as the @code{g}, there is no need to enter the
193 duration (You may enter it anyway, e.g. @code{a4 b4})
199 Three more notes. The `@code{|}' character is a `bar check'. When
200 processing the music, LilyPond will verify that bar checks are found at
201 the start of a measure. This can help you track down errors.
203 So far, no notes were chromatically altered. Here is the first one
204 that is: @code{fis}. Lilypond by default uses Dutch note names, and
205 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
206 sharp sign in the output. The program keeps track of key signatures,
207 and will only print accidentals if they are needed.
213 LilyPond guesses were beams can be added to eighth and shorter notes.
214 In this case, a beam over 4 eighths is added.
217 c4 d8( )c b a( )b4 c8 b a g |
220 The next line shows how to make a slur:
221 the beginning and ending note of the slur is marked with an opening and
222 closing parenthesis respectively. In the line shown above, this is
223 done for two slurs. Slur markers (parentheses) are put between
230 Automatic beaming can be overridden by inserting beam marks
231 (brackets). Brackets are put around the notes you want beamed.
237 A duration with augmentation dot is notated
238 with the duration number followed by a period.
244 This ends the sequential music to be repeated. LilyPond will typeset
251 This line shows that Lily will print an accidental if that is
252 needed: the first C sharp of the bar will be printed with an accidental,
253 the second one without.
256 a8-. b-. cis-. d-. e-. fis-.
259 You can enter articulation signs either in a verbose form using a
260 shorthand. Here we demonstrate the shorthand: it is formed by a dash
261 and the character for the articulation to use, e.g. `@code{-.}' for
262 staccato as shown above.
269 Rests are denoted by the special notename `@code{r}'. You can also enter
270 an invisible rest by using the special notename `@code{s}'.
276 All articulations have a verbose form, like @code{\fermata}. The
277 command `@code{\fermata}' is not part of the core of the language (most
278 of the other discussed elements are), but it is a shorthand for a more
279 complicated description of a fermata. @code{\fermata} names that
280 description and is therefore called an @emph{identifier}.
295 This specifies a conversion from music to notation output. Most of
296 the details of this conversions (font sizes, dimensions, etc.) have
297 been taken care of, but to fit the output in this document, it has
298 to be smaller. We do this by setting the line width to 14 centimeters
299 (approximately 6 inches).
305 The last brace ends the @code{\score} block.
307 There are two things to note here. The format contains musical
308 concepts like pitches and durations, instead of symbols and positions:
309 the input format tries to capture the meaning of @emph{music}, and not
310 notation. Therefore Second, the format tries to be @emph{context-free}:
311 a note will sound the same regardless of the current time signature,
314 The purpose of LilyPond is explained informally by the term `music
315 typesetter'. This is not a fully correct name: not only does the
316 program print musical symbols, it also makes esthetic decisions. All
317 symbols and their placement is @emph{generated} from a high-level musical
318 description. In other words, LilyPond would be best
319 described by `music compiler' or `music to notation compiler'.
321 @node Lyrics and chords
322 @section Lyrics and chords
324 In this section we show how to typeset a song of unknown
325 origin.@footnote{The author would welcome information about the origin
330 title = "The river is flowing";
331 composer = "Traditional (?)";
333 \include "paper16.ly"
334 melody = \notes \relative c' @{
338 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
339 c4 c8 d [es () d] c4 | d4 es8 d c4.
344 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
345 ri -- ver is flo -- wing down to the sea.
348 accompaniment =\chords @{
350 c2:3- f:3-.7 d:min es4 c8:min r8
351 c2:min f:min7 g:7^3.5 c:min @}
356 \context ChordNames \accompaniment
359 \context Staff = mel @{
360 \property Staff.noAutoBeaming = ##t
361 \property Staff.automaticMelismata = ##t
364 \context Lyrics \text
366 \midi @{ \tempo 4=72;@}
367 \paper @{ linewidth = 10.0\cm; @}
372 The result would look this@footnote{The titling and font size shown
373 may differ, since the titling in this document is not generated by
376 @center @strong{The river is flowing}
381 title = "The river is flowing";
382 composer = "Traditional (?)";
384 \include "paper16.ly"
385 melody = \notes \relative c' {
389 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
390 c4 c8 d [es () d] c4 | d4 es8 d c4.
395 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
396 ri -- ver is flo -- wing down to the sea.
399 accompaniment =\chords {
401 c2:3- f:3-.7 d:min es4 c8:min r8
402 c2:min f:min7 g:7^3.5 c:min }
407 \context ChordNames \accompaniment
410 \context Staff = mel {
411 \property Staff.noAutoBeaming = ##t
412 \property Staff.automaticMelismata = ##t
415 \context Lyrics \text
417 \midi { \tempo 4=72;}
418 \paper { linewidth = 10.0\cm; }
422 Again, we will dissect the file line by line.
428 Information about the music you are about to typeset goes into a
429 @code{\header} block. The information in this block is not used by
430 LilyPond, but it is included in the output. @file{ly2dvi} uses this
431 information to print titles above the music.
434 title = "The river is flowing";
435 composer = "Traditional (?)";
437 the @code{\header} block contains assignments. An assignment starts
438 with a string. (which is unquoted, in this case). Then comes the
439 equal sign `@code{=}'. After the equal sign comes the expression you
440 want to store. In this case, you want to put in strings. The
441 information has to be quoted here, because it contains spaces. Each
442 assignment is finished with a semicolon.
445 \include "paper16.ly"
448 Smaller size for inclusion in a book.
451 melody = \notes \relative c' @{
454 The structure of the file will be the same as the previous one, a
455 @code{\score} block with music in it. To keep things readable, we will
456 give names to the different parts of music, and use the names to
457 construct the music within the score block.
463 The piece starts with an anacrusis of one eighth.
467 The key is C minor: we have three flats.
471 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
472 c4 c8 d [es () d] c4 | d4 es8 d c4.
477 We use explicit beaming. Since this is a song, we will turn automatic
478 beams off, and use explicit beaming where needed.
484 This ends the definition of @code{melody}. Note that there are no
485 semicolons after assignments at top level.
491 Another identifier assignment. This one is for the lyrics.
492 Lyrics are formed by syllables that have duration, and not by
493 notes. To make LilyPond parse words as syllables, switch it into
494 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
495 is a shorthand for @code{\sequential @{}.
498 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
499 ri- ver is flo- __ wing down to the sea.
503 The syllables themselves are separated by spaces. You can get syllable
504 extenders by entering `@code{__}', and centered hyphens with
505 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
506 in length (hence the @code{4}), and use a feature to align the
507 syllables to the music (which obviously isn't all quarter notes.)
510 accompaniment =\chords @{
513 We'll put chords over the music. There is a special mode (analogous
514 to @code{\lyrics} and @code{\notes} mode) where you can give the names
515 of the chords you want, instead of the notes comprising the chord.
521 There is no accompaniment during the anacrusis.
527 A chord is started by the tonic of the chord. The
528 first one lasts a half note. An unadorned note creates a major
529 triad, while a minor triad is wanted. @code{3-} modifies the third to
530 be small. @code{7} modifies (adds) a seventh, which is small by default
531 to create the @code{f a c es} chord. Multiple modifiers must be
538 Some modifiers have predefined names, eg. @code{min} is the same as
539 @code{3-}, so @code{d-min} is a minor @code{d} chord.
542 c2:min f:min7 g:7^3.5 c:min @}
545 A named modifier @code{min} and a normal modifier @code{7} do not have
546 to be separated by a dot. Tones from a chord are removed with chord
547 subtractions. Subtractions are started with a caret, and they are
548 also separated by dots. In this example, @code{g:7^3.5} produces a
549 minor seventh. The brace ends the sequential music.
556 We assemble the music in the @code{\score} block. Melody, lyrics and
557 accompaniment have to sound at the same time, so they should be
558 @code{\simultaneous}.
564 Chord mode generates notes grouped in @code{\simultaneous} music. If
565 you remove the comment sign, you can see the chords in normal
566 notation: they will be printed as note heads on a separate
570 \context ChordNames \accompaniment
573 Normally, the notes that you enter are transformed into note heads.
574 The note heads alone make no sense, they need surrounding information:
575 a key signature, a clef, staff lines, etc. They need @emph{context}. In
576 LilyPond, these symbols are created by objects called `interpretation
577 contexts'. Interpretation contexts only exist during a run of
578 LilyPond. Interpretation contexts that are for printing music (as
579 opposed to playing music) are called `notation contexts'.
581 By default, LilyPond will create a Staff context for you. If you
582 removed the @code{%} sign in the previous line, you would see that
585 We don't want default contexts here, because we want chord names, not
586 note heads. An interpretation context can also created upon explicit
587 request. The keyword for such a request is @code{\context}. It takes
588 two arguments. The first is the name of an interpretation context.
589 The name is a string, it can be quoted with double quotes). The
590 second argument is the music that should be interpreted in this
591 context. For the previous line, we could have written @code{\context
592 Staff \accompaniment}, and get the same effect.
598 The lyrics need to be aligned with the melody. This is done by
599 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
600 pieces of music (usually a melody and lyrics, in that order) and
601 aligns the syllables of the second piece under the notes of the
602 first piece. If you would reverse the order, the notes would be
603 aligned on the lyrics, which is not very useful. (Besides, it looks
607 \context Staff = mel @{
610 This is the argument of @code{\addlyrics}. We instantiate a
611 @code{Staff} context explicitly: should you chose to remove the comment
612 before the ``note heads'' version of the accompaniment, the
613 accompaniment will be on a nameless staff. The melody has to be on a
614 different staff as the accompaniment. This is accomplished by giving
615 the melody staff a different name.
618 \property Staff.noAutoBeaming = ##t
621 An interpretation context has variables that tune its behaviour. One
622 of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
623 true) LilyPond will not try to put automatic beaming on the current
627 \property Staff.automaticMelismata = ##t
630 Similarly, we don't want to print a syllable when there is
631 a slur. This sets up the Staff context to signal slurs while
632 @code{\addlyrics} is processed.
639 Finally, we put the melody on the current staff. Note that the
640 @code{\property} directives and @code{\melody} are grouped in sequential
641 music, so the property settings are done before the melody is
645 \context Lyrics \text
648 The second argument of @code{\addlyrics} is the text. The text also
649 should not land on a Staff, but on a interpretation context for
650 syllables, extenders, hyphens etc. This context is called
657 This ends @code{\simultaneous}.
660 \midi @{ \tempo 4=72;@}
663 This makes the music go to a MIDI file. MIDI is great for
664 checking music you enter. You listen to the MIDI file: if you hear
665 something unexpected, it's probably a typing error. @code{\midi} is an
666 `output definition', a declaration that specifies how to output music
667 analogous to @code{\paper @{ @}}. You can specify the tempo using the
668 @code{\tempo} command, in this case the tempo of quarter notes is set
669 to 72 beats per minute.
672 \paper @{ linewidth = 10.0\cm; @}
675 We also want notation output. The linewidth is short so the piece
676 will be set in two lines.
687 Our third subject is a piece of piano music. The fragment in the input
688 file is a piano reduction of the G major Sinfonia by Giovanni Battista
689 Sammartini. It was composed around 1740.
694 \include "paper16.ly";
696 viola = \notes \relative c' \context Voice = viola {
703 oboes = \notes \relative c'' \context Voice = oboe {
704 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
705 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
707 { \times 2/3 { a8 g c } \! c2 }
708 \context Voice = oboeTwo {
711 \property Grace.Stem \override #'direction = #-1
716 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
717 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
718 [<c16( e> < )e8. g>] <c8 e,>
721 hoomPah = \notes \transpose c' {
722 c8 \translator Staff = top \stemDown
723 c'8 \translator Staff = bottom \stemUp }
725 hoomPahHoomPah = { [\hoomPah \hoomPah] }
727 bassvoices = \notes \relative c' {
729 \repeat unfold 4 {\hoomPahHoomPah}
730 \stemDown [c8 c'8] r4
732 < {\stemUp r2 <e4 c'> <c8 g'> }
733 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
737 \context PianoStaff \notes <
738 \context Staff = top < \time 2/2;
742 \context Staff = bottom < \time 2/2; \clef bass;
749 linewidth = 15.0 \cm; }
753 If it looks like incomprehensible gibberish to you@dots{} Then you are
754 right. The author has doctored this example to have as many quirks in
755 one system as possible.
759 Lilypond and the Lilypond language is still under development, therefore
760 it is useful to indicate the Lilypond version of the file. Lilypond
761 will check the version number and warn you when the syntax has
762 changed. Also, the @code{convert-ly} program will be able to
763 update most of the syntax changes automatically.
765 viola = \notes \relative c' \context Voice = viola @{
767 In this example, you can see multiple parts on a staff. Each part is
768 associated with one notation context. This notation context handles
769 stems and dynamics (among others). The name of this context is
770 @code{Voice}. For each part we have to make sure that there is
771 precisely one Voice context.
775 @code{<} and @code{>} are short hands for @code{\simultaneous @{} and
776 @code{@}}. So the expression enclosed in @code{<} and @code{>} is a
777 chord. @code{\f} places a forte symbol under the chord.
781 \property Voice.verticalDirection = \down
783 @code{verticalDirection} is a property of the voice context. It
784 controls the directions of stems, articulations marks and other
787 If @code{verticalDirection} is set to @code{\down}
788 (identifier for the integer -1) the stems go down,
789 @code{\up} (identifier for the integer 1) makes the stems go up.
793 Relative octaves work a little differently with chords. The starting
794 point for the note following a chord is the first note of the chord. So
795 the @code{g} gets an octave up quote: it is a fifth above the starting
796 note of the previous chord (the central C).
801 @code{s} is a `spacer' rest. It does not print anything, but it does
802 have the duration of a rest.
804 oboes = \notes \relative c'' \context Voice = oboe @{
806 Now comes a part for two oboes. They play homophonically, so we
807 print the notes as one voice that makes chords. Again, we insure that
808 these notes are indeed processed by precisely one context with
811 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
813 @code{\stemUp} is an identifier reference. It is shorthand for
814 @code{\property Voice.verticalDirection = \up}. If possible, you
815 should use predefined identifiers like these for setting properties.
816 Your input will be less dependent upon the implementation of LilyPond.
818 \grace <e8( g> < )d4 f> <c2 e>
820 @code{\grace} introduces grace notes. It takes one argument, in this
821 case a chord. The slur started on the @code{e} of the chord
822 will be attached to the next note.@footnote{LilyPond will squirm
823 about unended Slurs. In this case, you can ignore the warning}.
827 Tuplets are made with the @code{\times} keyword. It takes two
828 arguments: a fraction and a piece of music. The duration of the
829 second argument is multiplied by the first argument. Triplets make
830 notes occupy 2/3 of their notated duration, so in this case the
833 @{ <d8 \< f> <e g> <f a> @}
835 The piece of music to be `tripletted' is sequential music containing
836 three notes. On the first chord (the @code{d}), a crescendo is started
841 At this point, the homophonic music splits into two rhythmically
842 different parts. We can't use a sequence of chords to enter this, so
843 we make a `chord' of sequences to do it. We start with the upper
844 voice, which continues with upward stems:
846 @{ \times 2/3 @{ a8 g c @} \! c2 @}
848 The crescendo is ended at the half note by the escaped exclamation
851 \context Voice = oboeTwo @{
854 We can't share stems with the other voice, so we have to create a new
855 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
856 it from the other context. Stems go down in this voice.
860 When a grace section is processed, a @code{Grace} context is
861 created. This context acts like a miniature score of its own. It has
862 its own time bookkeeping, and you can make notes, beams, slurs
863 etc. Here we fiddle with a property and make a beam. The argument of
864 @code{\grace} is sequential music.
867 \property Grace.verticalDirection = \down
871 Normally, grace notes are always stem up, but in this case, the upper
872 voice interferes. We set the stems down here.
874 As far as relative mode is concerned, the previous note is the
875 @code{c'''2} of the upper voice, so we have to go an octave down for
882 This ends the two-part section.
885 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
887 @code{\stemBoth} ends the forced stem directions. From here, stems are
888 positioned as if it were single part music.
890 The bass has a little hoom-pah melody to demonstrate parts switching
891 between staffs. Since it is repetitive, we use identifiers:
893 hoomPah = \notes \transpose c' @{
895 Transposing can be done with @code{\transpose}. It takes two
896 arguments; the first specifies what central C should be transposed to.
897 The second is the to-be-transposed music. As you can see, in this
898 case, the transposition is a no-op. Central C is transposed to
901 The purpose of this no-op is circumventing relative mode. Relative
902 mode can not be used in conjunction with transposition, so relative
903 mode will leave the contents of @code{\hoomPah} alone. We can use it
904 without having to worry about getting the motive in a wrong
905 octave@footnote{@code{hoomPah = \relative @dots{}} would be more
906 intuitive to use, but that would not let me plug @code{\transpose}
909 c8 \translator Staff = top \stemDown
911 We assume that the first note will be put in the lower staff. After
912 that note we switch to the upper staff with @code{\translator}. To be
913 precise, this @code{\translator} entry switches the current voice to a
914 @code{Staff} named @code{top}. So we have to name the upper staff
915 `@code{top}'. Stem directions are set to avoid interfering with the
918 c'8 \translator Staff = bottom \stemUp @}
920 Then a note is put on the upper staff, and we switch again. We have
921 to name the lower staff `@code{bottom}'.
923 hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
925 Put two of these fragments in sequence, and beam them.@example
926 bassvoices = \notes \relative c' @{
928 \repeat unfold 4 @{\hoomPahHoomPah @}
930 Entering the bass part is easy: the hoomPahHoomPah variable is
931 repeated four times; @code{unfold} means that all four repetitions
932 should be written out.
934 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
936 After skipping some lines, we see @code{~}. This mark makes ties.
940 For piano music, a special context is needed to get cross staff
941 beaming right. It is called @code{PianoStaff}.
943 \context Staff = bottom < \time 2/2; \clef bass;
945 The bottom staff must have a different clef.
949 To make some more room on the line, the first (in this case the only)
950 line is not indented. The line still looks very cramped, but that is due
951 to the format of this tutorial.
953 This example shows a lot of features, but the organisation isn't
954 perfect. For example, it would be less confusing to use a chord
955 containing sequential music than a sequence of chords for the oboe
958 [TODO: demonstrate Hara-Kiri with scores and part extraction.]
960 @node end of tutorial
963 That's all folks. From here, you can either try fiddling with input
964 files, or you can read the reference manual.