3 @c ugh: because of @include, we need to fill in these nodes?
4 @node Tutorial, , , Top
8 * Introduction:: Introduction
9 * The first tune:: The first tune
10 * Lyrics and chords:: Lyrics and chords
11 * Piano music:: Piano music
12 * end of tutorial:: The end
19 LilyPond prints music from a specification that you, the user, supply.
20 You have to give that specification using a @emph{language}. This
21 document is a gentle introduction to that language, which is called
22 Lilypond, an acronym of Music Definition Language.
24 This tutorial will demonstrate how to use Lilypond by presenting
25 examples of input along with resulting output. We will use English
26 terms for notation. In case you are not familiar with those, you may
27 consult the glossary that is distributed with LilyPond.
29 The examples discussed are included in the distribution, in the
30 subdirectory @file{input/tutorial/}. It is recommended that you
31 experiment with writing Lilypond input yourself, to get a feel for
35 @section The first tune
38 To demonstrate what LilyPond input looks like, we start off with a
39 full fledged, yet simple example. It is a convoluted version
40 of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
43 % lines preceded by a percent are comments which
44 % are ignored by Lilypond.
48 \relative c'' \sequential{
53 d4 g,8 a b c d4 g, g |
54 e'4 c8 d e fis g4 g, g |
55 c4 d8()c b a( )b4 c8 b a g |
56 a4 [b8 a] [g fis] g2. |
61 g4 e8 fis g d cis4 b8 cis a4 |
62 a8-. b-. cis-. d-. e-. fis-.
69 % standard settings are too wide for a book
75 Enter it (or copy it, the filename is @file{menuet.ly}), compile it
76 with LilyPond and view the output. Details of this procedure may vary
77 from system to system. To create the output, one would issue the
78 command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
79 the job of running LilyPond and @TeX{}, handling of titles and
80 adjusting of page margins.
82 If all goes well, the file @file{menuet.dvi} will be created.
83 To view this output, issue the command `@code{xdvi menuet}'.
85 Now that we are familiar with the procedure of producing output, we
86 will analyse the input, line by line.
88 % lines preceded by a percent are comments which
89 % are ignored by Lilypond.
91 The percent sign, `@code{%}', introduces a line comment. If you want to
92 make larger comments, you can use block comments. These are delimited
93 by `@code{%@{}' and `@code{%@}}'
99 By default, LilyPond will use definitions for a 20
100 point@footnote{A point is the standard measure of length for
101 printing. One point is 1/72.27 inch.} high staff. We want smaller
102 output (16 point staff height), so we must import the settings for
103 that size, which is done.
109 A lilypond file combines music with directions for outputting that
110 music. The music is combined with the output directions by putting
111 them into a @code{\score} block.
117 This makes LilyPond ready for accepting notes.
123 As we will see, pitches are combinations of octave, note name and
124 chromatic alteration. In this scheme, the octave is indicated by
125 using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
126 `@code{,}'). The central C is denoted by @code{c'}. The C one octave
127 higher is @code{c''}. One and two octaves below the central C is
128 denoted by @code{c} and @code{c,} respectively.
130 For pitches in a long piece you might have to type many quotes. To
131 remedy this, LilyPond has a ``relative'' octave entry mode. In this
132 mode, octaves of notes without quotes are chosen such that a note is
133 as close as possible (graphically, on the staff) to the the preceding
134 note. If you add a high-quote an extra octave is added. The lowered
135 quote (a comma) will subtract an extra octave. Because the first note
136 has no predecessor, you have to give the (absolute) pitch of the note
143 What follows is sequential music, i.e.,
144 notes that are to be played and printed after each other.
150 This command changes the time signature of the current piece: a 3/4
151 sign is printed. This command is also used to generate bar lines in
158 This command changes the current key to G-major. Although this
159 command comes after the @code{\time} command, in the output, the key
160 signature comes before the time signature: LilyPond knows about music
161 typesetting conventions.
167 This command tells LilyPond that the following piece of music must
168 be played twice; @code{"volta"} means that volta brackets should be used
169 for alternatives---if there were any.
175 The subject of the repeat is again sequential music. Since
176 @code{\sequential} is such a common construct, a shorthand is provided:
177 just leave off @code{\sequential}, and the result is the same.
183 This is a note with pitch @code{d} (determined up to octaves). The
184 relative music was started with a @code{c''}, so the real pitch of this
185 note is @code{d''}. The @code{4} designates the duration of the note
186 (it is a quarter note).
192 These are notes with pitch @code{a} and @code{b}. Because their
193 duration is the same as the @code{g}, there is no need to enter the
194 duration (You may enter it anyway, e.g. @code{a4 b4})
200 Three more notes. The `@code{|}' character is a `bar check'. When
201 processing the music, LilyPond will verify that bar checks are found at
202 the start of a measure. This can help you track down errors.
204 So far, no notes were chromatically altered. Here is the first one
205 that is: @code{fis}. Lilypond by default uses Dutch note names, and
206 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
207 sharp sign in the output. The program keeps track of key signatures,
208 and will only print accidentals if they are needed.
214 LilyPond guesses were beams can be added to eighth and shorter notes.
215 In this case, a beam over 4 eighths is added.
218 c4 d8( )c b a( )b4 c8 b a g |
221 The next line shows how to make a slur:
222 the beginning and ending note of the slur is marked with an opening and
223 closing parenthesis respectively. In the line shown above, this is
224 done for two slurs. Slur markers (parentheses) are put between
231 Automatic beaming can be overridden by inserting beam marks
232 (brackets). Brackets are put around the notes you want beamed.
238 A duration with augmentation dot is notated
239 with the duration number followed by a period.
245 This ends the sequential music to be repeated. LilyPond will typeset
252 This line shows that Lily will print an accidental if that is
253 needed: the first C sharp of the bar will be printed with an accidental,
254 the second one without.
257 a8-. b-. cis-. d-. e-. fis-.
260 You can enter articulation signs either in a verbose form using a
261 shorthand. Here we demonstrate the shorthand: it is formed by a dash
262 and the character for the articulation to use, e.g. `@code{-.}' for
263 staccato as shown above.
270 Rests are denoted by the special notename `@code{r}'. You can also enter
271 an invisible rest by using the special notename `@code{s}'.
277 All articulations have a verbose form, like @code{\fermata}. The
278 command `@code{\fermata}' is not part of the core of the language (most
279 of the other discussed elements are), but it is a shorthand for a more
280 complicated description of a fermata. @code{\fermata} names that
281 description and is therefore called an @emph{identifier}.
296 This specifies a conversion from music to notation output. Most of
297 the details of this conversions (font sizes, dimensions, etc.) have
298 been taken care of, but to fit the output in this document, it has
299 to be smaller. We do this by setting the line width to 14 centimeters
300 (approximately 6 inches).
306 The last brace ends the @code{\score} block.
308 There are two things to note here. The format contains musical
309 concepts like pitches and durations, instead of symbols and positions:
310 the input format tries to capture the meaning of @emph{music}, and not
311 notation. Therefore Second, the format tries to be @emph{context-free}:
312 a note will sound the same regardless of the current time signature,
315 The purpose of LilyPond is explained informally by the term `music
316 typesetter'. This is not a fully correct name: not only does the
317 program print musical symbols, it also makes esthetic decisions. All
318 symbols and their placement is @emph{generated} from a high-level musical
319 description. In other words, LilyPond would be best
320 described by `music compiler' or `music to notation compiler'.
322 @node Lyrics and chords
323 @section Lyrics and chords
325 In this section we show how to typeset a song of unknown
326 origin.@footnote{The author would welcome information about the origin
331 title = "The river is flowing";
332 composer = "Traditional (?)";
334 \include "paper16.ly"
335 melody = \notes \relative c' @{
339 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
340 c4 c8 d [es () d] c4 | d4 es8 d c4.
345 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
346 ri -- ver is flo -- wing down to the sea.
349 accompaniment =\chords @{
351 c2:3- f:3-.7 d:min es4 c8:min r8
352 c2:min f:min7 g:7^3.5 c:min @}
357 \context ChordNames \accompaniment
360 \context Staff = mel @{
361 \property Staff.noAutoBeaming = ##t
362 \property Staff.automaticMelismata = ##t
365 \context Lyrics \text
367 \midi @{ \tempo 4=72;@}
368 \paper @{ linewidth = 10.0\cm; @}
373 The result would look this@footnote{The titling and font size shown
374 may differ, since the titling in this document is not generated by
377 @center @strong{The river is flowing}
382 title = "The river is flowing";
383 composer = "Traditional (?)";
385 \include "paper16.ly"
386 melody = \notes \relative c' {
390 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
391 c4 c8 d [es () d] c4 | d4 es8 d c4.
396 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
397 ri -- ver is flo -- wing down to the sea.
400 accompaniment =\chords {
402 c2:3- f:3-.7 d:min es4 c8:min r8
403 c2:min f:min7 g:7^3.5 c:min }
408 \context ChordNames \accompaniment
411 \context Staff = mel {
412 \property Staff.noAutoBeaming = ##t
413 \property Staff.automaticMelismata = ##t
416 \context Lyrics \text
418 \midi { \tempo 4=72;}
419 \paper { linewidth = 10.0\cm; }
423 Again, we will dissect the file line by line.
429 Information about the music you are about to typeset goes into a
430 @code{\header} block. The information in this block is not used by
431 LilyPond, but it is included in the output. @file{ly2dvi} uses this
432 information to print titles above the music.
435 title = "The river is flowing";
436 composer = "Traditional (?)";
438 the @code{\header} block contains assignments. An assignment starts
439 with a string. (which is unquoted, in this case). Then comes the
440 equal sign `@code{=}'. After the equal sign comes the expression you
441 want to store. In this case, you want to put in strings. The
442 information has to be quoted here, because it contains spaces. Each
443 assignment is finished with a semicolon.
446 \include "paper16.ly"
449 Smaller size for inclusion in a book.
452 melody = \notes \relative c' @{
455 The structure of the file will be the same as the previous one, a
456 @code{\score} block with music in it. To keep things readable, we will
457 give names to the different parts of music, and use the names to
458 construct the music within the score block.
464 The piece starts with an anacrusis of one eighth.
468 The key is C minor: we have three flats.
472 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
473 c4 c8 d [es () d] c4 | d4 es8 d c4.
478 We use explicit beaming. Since this is a song, we will turn automatic
479 beams off, and use explicit beaming where needed.
485 This ends the definition of @code{melody}. Note that there are no
486 semicolons after assignments at top level.
492 Another identifier assignment. This one is for the lyrics.
493 Lyrics are formed by syllables that have duration, and not by
494 notes. To make LilyPond parse words as syllables, switch it into
495 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
496 is a shorthand for @code{\sequential @{}.
499 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
500 ri- ver is flo- __ wing down to the sea.
504 The syllables themselves are separated by spaces. You can get syllable
505 extenders by entering `@code{__}', and centered hyphens with
506 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
507 in length (hence the @code{4}), and use a feature to align the
508 syllables to the music (which obviously isn't all quarter notes.)
511 accompaniment =\chords @{
514 We'll put chords over the music. There is a special mode (analogous
515 to @code{\lyrics} and @code{\notes} mode) where you can give the names
516 of the chords you want, instead of the notes comprising the chord.
522 There is no accompaniment during the anacrusis.
528 A chord is started by the tonic of the chord. The
529 first one lasts a half note. An unadorned note creates a major
530 triad, while a minor triad is wanted. @code{3-} modifies the third to
531 be small. @code{7} modifies (adds) a seventh, which is small by default
532 to create the @code{f a c es} chord. Multiple modifiers must be
539 Some modifiers have predefined names, eg. @code{min} is the same as
540 @code{3-}, so @code{d-min} is a minor @code{d} chord.
543 c2:min f:min7 g:7^3.5 c:min @}
546 A named modifier @code{min} and a normal modifier @code{7} do not have
547 to be separated by a dot. Tones from a chord are removed with chord
548 subtractions. Subtractions are started with a caret, and they are
549 also separated by dots. In this example, @code{g:7^3.5} produces a
550 minor seventh. The brace ends the sequential music.
557 We assemble the music in the @code{\score} block. Melody, lyrics and
558 accompaniment have to sound at the same time, so they should be
559 @code{\simultaneous}.
565 Chord mode generates notes grouped in @code{\simultaneous} music. If
566 you remove the comment sign, you can see the chords in normal
567 notation: they will be printed as note heads on a separate
571 \context ChordNames \accompaniment
574 Normally, the notes that you enter are transformed into note heads.
575 The note heads alone make no sense, they need surrounding information:
576 a key signature, a clef, staff lines, etc. They need @emph{context}. In
577 LilyPond, these symbols are created by objects called `interpretation
578 contexts'. Interpretation contexts only exist during a run of
579 LilyPond. Interpretation contexts that are for printing music (as
580 opposed to playing music) are called `notation contexts'.
582 By default, LilyPond will create a Staff context for you. If you
583 removed the @code{%} sign in the previous line, you would see that
586 We don't want default contexts here, because we want chord names, not
587 note heads. An interpretation context can also created upon explicit
588 request. The keyword for such a request is @code{\context}. It takes
589 two arguments. The first is the name of an interpretation context.
590 The name is a string, it can be quoted with double quotes). The
591 second argument is the music that should be interpreted in this
592 context. For the previous line, we could have written @code{\context
593 Staff \accompaniment}, and get the same effect.
599 The lyrics need to be aligned with the melody. This is done by
600 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
601 pieces of music (usually a melody and lyrics, in that order) and
602 aligns the syllables of the second piece under the notes of the
603 first piece. If you would reverse the order, the notes would be
604 aligned on the lyrics, which is not very useful. (Besides, it looks
608 \context Staff = mel @{
611 This is the argument of @code{\addlyrics}. We instantiate a
612 @code{Staff} context explicitly: should you chose to remove the comment
613 before the ``note heads'' version of the accompaniment, the
614 accompaniment will be on a nameless staff. The melody has to be on a
615 different staff as the accompaniment. This is accomplished by giving
616 the melody staff a different name.
619 \property Staff.noAutoBeaming = ##t
622 An interpretation context has variables that tune its behaviour. One
623 of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
624 true) LilyPond will not try to put automatic beaming on the current
628 \property Staff.automaticMelismata = ##t
631 Similarly, we don't want to print a syllable when there is
632 a slur. This sets up the Staff context to signal slurs while
633 @code{\addlyrics} is processed.
640 Finally, we put the melody on the current staff. Note that the
641 @code{\property} directives and @code{\melody} are grouped in sequential
642 music, so the property settings are done before the melody is
646 \context Lyrics \text
649 The second argument of @code{\addlyrics} is the text. The text also
650 should not land on a Staff, but on a interpretation context for
651 syllables, extenders, hyphens etc. This context is called
658 This ends @code{\simultaneous}.
661 \midi @{ \tempo 4=72;@}
664 This makes the music go to a MIDI file. MIDI is great for
665 checking music you enter. You listen to the MIDI file: if you hear
666 something unexpected, it's probably a typing error. @code{\midi} is an
667 `output definition', a declaration that specifies how to output music
668 analogous to @code{\paper @{ @}}. You can specify the tempo using the
669 @code{\tempo} command, in this case the tempo of quarter notes is set
670 to 72 beats per minute.
673 \paper @{ linewidth = 10.0\cm; @}
676 We also want notation output. The linewidth is short so the piece
677 will be set in two lines.
688 Our third subject is a piece of piano music. The fragment in the input
689 file is a piano reduction of the G major Sinfonia by Giovanni Battista
690 Sammartini. It was composed around 1740.
695 \include "paper16.ly";
697 viola = \notes \relative c' \context Voice = viola {
704 oboes = \notes \relative c'' \context Voice = oboe {
705 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
706 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
708 { \times 2/3 { a8 g c } \! c2 }
709 \context Voice = oboeTwo {
712 \property Grace.Stem \override #'direction = #-1
717 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
718 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
719 [<c16( e> < )e8. g>] <c8 e,>
722 hoomPah = \notes \transpose c' {
723 c8 \translator Staff = top \stemDown
724 c'8 \translator Staff = bottom \stemUp }
726 hoomPahHoomPah = { [\hoomPah \hoomPah] }
728 bassvoices = \notes \relative c' {
730 \repeat unfold 4 {\hoomPahHoomPah}
731 \stemDown [c8 c'8] r4
733 < {\stemUp r2 <e4 c'> <c8 g'> }
734 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
738 \context PianoStaff \notes <
739 \context Staff = top < \time 2/2;
743 \context Staff = bottom < \time 2/2; \clef bass;
750 linewidth = 15.0 \cm; }
754 If it looks like incomprehensible gibberish to you@dots{} Then you are
755 right. The author has doctored this example to have as many quirks in
756 one system as possible.
760 Lilypond and the Lilypond language is still under development, therefore
761 it is useful to indicate the Lilypond version of the file. Lilypond
762 will check the version number and warn you when the syntax has
763 changed. Also, the @code{convert-ly} program will be able to
764 update most of the syntax changes automatically.
766 viola = \notes \relative c' \context Voice = viola @{
768 In this example, you can see multiple parts on a staff. Each part is
769 associated with one notation context. This notation context handles
770 stems and dynamics (among others). The name of this context is
771 @code{Voice}. For each part we have to make sure that there is
772 precisely one Voice context.
776 @code{<} and @code{>} are short hands for @code{\simultaneous @{} and
777 @code{@}}. So the expression enclosed in @code{<} and @code{>} is a
778 chord. @code{\f} places a forte symbol under the chord.
782 \property Voice.verticalDirection = \down
784 @code{verticalDirection} is a property of the voice context. It
785 controls the directions of stems, articulations marks and other
788 If @code{verticalDirection} is set to @code{\down}
789 (identifier for the integer -1) the stems go down,
790 @code{\up} (identifier for the integer 1) makes the stems go up.
794 Relative octaves work a little differently with chords. The starting
795 point for the note following a chord is the first note of the chord. So
796 the @code{g} gets an octave up quote: it is a fifth above the starting
797 note of the previous chord (the central C).
802 @code{s} is a `spacer' rest. It does not print anything, but it does
803 have the duration of a rest.
805 oboes = \notes \relative c'' \context Voice = oboe @{
807 Now comes a part for two oboes. They play homophonically, so we
808 print the notes as one voice that makes chords. Again, we insure that
809 these notes are indeed processed by precisely one context with
812 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
814 @code{\stemUp} is an identifier reference. It is shorthand for
815 @code{\property Voice.verticalDirection = \up}. If possible, you
816 should use predefined identifiers like these for setting properties.
817 Your input will be less dependent upon the implementation of LilyPond.
819 \grace <e8( g> < )d4 f> <c2 e>
821 @code{\grace} introduces grace notes. It takes one argument, in this
822 case a chord. The slur started on the @code{e} of the chord
823 will be attached to the next note.@footnote{LilyPond will squirm
824 about unended Slurs. In this case, you can ignore the warning}.
828 Tuplets are made with the @code{\times} keyword. It takes two
829 arguments: a fraction and a piece of music. The duration of the
830 second argument is multiplied by the first argument. Triplets make
831 notes occupy 2/3 of their notated duration, so in this case the
834 @{ <d8 \< f> <e g> <f a> @}
836 The piece of music to be `tripletted' is sequential music containing
837 three notes. On the first chord (the @code{d}), a crescendo is started
842 At this point, the homophonic music splits into two rhythmically
843 different parts. We can't use a sequence of chords to enter this, so
844 we make a `chord' of sequences to do it. We start with the upper
845 voice, which continues with upward stems:
847 @{ \times 2/3 @{ a8 g c @} \! c2 @}
849 The crescendo is ended at the half note by the escaped exclamation
852 \context Voice = oboeTwo @{
855 We can't share stems with the other voice, so we have to create a new
856 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
857 it from the other context. Stems go down in this voice.
861 When a grace section is processed, a @code{Grace} context is
862 created. This context acts like a miniature score of its own. It has
863 its own time bookkeeping, and you can make notes, beams, slurs
864 etc. Here we fiddle with a property and make a beam. The argument of
865 @code{\grace} is sequential music.
868 \property Grace.verticalDirection = \down
872 Normally, grace notes are always stem up, but in this case, the upper
873 voice interferes. We set the stems down here.
875 As far as relative mode is concerned, the previous note is the
876 @code{c'''2} of the upper voice, so we have to go an octave down for
883 This ends the two-part section.
886 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
888 @code{\stemBoth} ends the forced stem directions. From here, stems are
889 positioned as if it were single part music.
891 The bass has a little hoom-pah melody to demonstrate parts switching
892 between staffs. Since it is repetitive, we use identifiers:
894 hoomPah = \notes \transpose c' @{
896 Transposing can be done with @code{\transpose}. It takes two
897 arguments; the first specifies what central C should be transposed to.
898 The second is the to-be-transposed music. As you can see, in this
899 case, the transposition is a no-op. Central C is transposed to
902 The purpose of this no-op is circumventing relative mode. Relative
903 mode can not be used in conjunction with transposition, so relative
904 mode will leave the contents of @code{\hoomPah} alone. We can use it
905 without having to worry about getting the motive in a wrong
906 octave@footnote{@code{hoomPah = \relative @dots{}} would be more
907 intuitive to use, but that would not let me plug @code{\transpose}
910 c8 \translator Staff = top \stemDown
912 We assume that the first note will be put in the lower staff. After
913 that note we switch to the upper staff with @code{\translator}. To be
914 precise, this @code{\translator} entry switches the current voice to a
915 @code{Staff} named @code{top}. So we have to name the upper staff
916 `@code{top}'. Stem directions are set to avoid interfering with the
919 c'8 \translator Staff = bottom \stemUp @}
921 Then a note is put on the upper staff, and we switch again. We have
922 to name the lower staff `@code{bottom}'.
924 hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
926 Put two of these fragments in sequence, and beam them.@example
927 bassvoices = \notes \relative c' @{
929 \repeat unfold 4 @{\hoomPahHoomPah @}
931 Entering the bass part is easy: the hoomPahHoomPah variable is
932 repeated four times; @code{unfold} means that all four repetitions
933 should be written out.
935 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
937 After skipping some lines, we see @code{~}. This mark makes ties.
941 For piano music, a special context is needed to get cross staff
942 beaming right. It is called @code{PianoStaff}.
944 \context Staff = bottom < \time 2/2; \clef bass;
946 The bottom staff must have a different clef.
950 To make some more room on the line, the first (in this case the only)
951 line is not indented. The line still looks very cramped, but that is due
952 to the format of this tutorial.
954 This example shows a lot of features, but the organisation isn't
955 perfect. For example, it would be less confusing to use a chord
956 containing sequential music than a sequence of chords for the oboe
959 [TODO: demonstrate Hara-Kiri with scores and part extraction.]
961 @node end of tutorial
964 That's all folks. From here, you can either try fiddling with input
965 files, or you can read the reference manual.