4 @node Tutorial, , , Top
6 * Introduction:: Introduction
7 * The first tune:: The first tune
8 * Lyrics and chords:: Lyrics and chords
9 * Piano music:: Piano music
10 * end of tutorial:: The end
13 @node Introduction, , , Tutorial
17 LilyPond prints music from a specification that you, the user, supply.
18 You have to give that specification using a @emph{language}. This
19 document is a gentle introduction to that language, which is called
20 Mudela, an acronym of Music Definition Language.
22 This tutorial will demonstrate how to use Mudela by presenting
23 examples of input along with resulting output. We will use English
24 terms for notation. In case you are not familiar with those, you may
25 consult the glossary that is distributed with LilyPond.
27 The examples discussed are included in the distribution, in the
28 subdirectory @file{input/tutorial/}. It is recommended that you
29 experiment with writing Mudela input yourself, to get a feel for
32 @node The first tune, , , Tutorial
33 @section The first tune
36 To demonstrate what LilyPond input looks like, we start off with a
37 full fledged, yet simple example. It is a convoluted version
38 of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
41 % lines preceded by a percent are comments.
45 \relative c'' \sequential{
50 d4 g,8 a b c d4 g, g |
51 e'4 c8 d e fis g4 g, g |
52 c4 d8()c b a( )b4 c8 b a g |
53 a4 [b8 a] [g fis] g2. |
58 g4 e8 fis g d cis4 b8 cis a4 |
59 a8-. b-. cis-. d-. e-. fis-.
66 % standard settings are too wide for a book
72 Enter it (or copy it, the filename is @file{menuet.ly}), compile it
73 with LilyPond and view the output. Details of this procedure may vary
74 from system to system. To create the output, one would issue the
75 command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
76 the job of running LilyPond and @TeX{}, handling of titles and
77 adjusting of page margins.
79 If all goes well, the file @file{menuet.dvi} will be created.
80 To view this output, issue the command `@code{xdvi menuet}'.
82 Now that we are familiar with the procedure of producing output, we
83 will analyse the input, line by line.
85 Let's try to redo this
88 % lines preceded by a percent are comments.
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{%@}}'
95 @multitable @columnfractions .60 .39
98 @c @example urg: no tt font
99 @c @exdent % lines preceded by a percent are comments.
100 @exdent @code{% lines preceded by a percent are comments.}
103 The percent sign, `@code{%}', introduces a line comment. If you
104 want to make larger comments, you can use block comments. These
105 are delimited by `@code{%@{}' and `@code{%@}}'
112 By default, LilyPond will use definitions for a 20
113 point@footnote{A point is the standard measure of length for
114 printing. One point is 1/72.27 inch.} high staff. We want smaller
115 output (16 point staff height), so we must import the settings for
116 that size, which is done.
122 A mudela file combines music with directions for outputting that
123 music. The music is combined with the output directions by putting
124 them into a @code{\score} block.
130 This makes LilyPond ready for accepting notes.
136 As we will see, pitches are combinations of octave, note name and
137 chromatic alteration. In this scheme, the octave is indicated by
138 using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
139 `@code{,}'). The central C is denoted by @code{c'}. The C one octave
140 higher is @code{c''}. One and two octaves below the central C is
141 denoted by @code{c} and @code{c,} respectively.
143 For pitches in a long piece you might have to type many quotes. To
144 remedy this, LilyPond has a ``relative'' octave entry mode. In this
145 mode, octaves of notes without quotes are chosen such that a note is
146 as close as possible (graphically, on the staff) to the the preceding
147 note. If you add a high-quote an extra octave is added. The lowered
148 quote (a comma) will subtract an extra octave. Because the first note
149 has no predecessor, you have to give the (absolute) pitch of the note
156 What follows is sequential music, i.e.,
157 notes that are to be played and printed after each other.
163 This command changes the time signature of the current piece: a 3/4
164 sign is printed. This command is also used to generate bar lines in
171 This command changes the current key to G-major. Although this
172 command comes after the @code{\time} command, in the output, the key
173 signature comes before the time signature: LilyPond knows about music
174 typesetting conventions.
180 This command tells LilyPond that the following piece of music must
181 be played twice; @code{"volta"} volta brackets should be used for
182 alternatives---if there were any.
188 The subject of the repeat is again sequential music. Since
189 @code{\sequential} is such a common construct, a shorthand is provided:
190 just leave off @code{\sequential}, and the result is the same.
196 This is a note with pitch @code{d} (determined up to octaves). The
197 relative music was started with a @code{c''}, so the real pitch of this
198 note is @code{d''}. The @code{4} designates the duration of the note
199 (it is a quarter note).
205 These are notes with pitch @code{a} and @code{b}. Because their
206 duration is the same as the @code{g}, there is no need to enter the
207 duration (You may enter it anyway, e.g. @code{a4 b4})
213 Three more notes. The `@code{|}' character is a `barcheck'. When
214 processing the music, LilyPond will verify that barchecks are found at
215 the start of a measure. This can help you track down errors.
217 So far, no notes were chromatically altered. Here is the first one
218 that is: @code{fis}. Mudela by default uses Dutch note names, and
219 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
220 sharp sign in the output. The program keeps track of key signatures,
221 and will only print accidentals if they are needed.
227 LilyPond guesses were beams can be added to eighth and shorter notes.
228 In this case, a beam over 4 eighths is added.
231 c4 d8( )c b a( )b4 c8 b a g |
234 The next line shows how to make a slur:
235 the beginning and ending note of the slur is marked with an opening and
236 closing parenthesis respectively. In the line shown above this is
237 done for two slurs. Slur markers (parentheses) are between
244 Automatic beaming can be overridden by inserting beam marks
245 (brackets). Brackets are put around notes you want beamed.
251 A duration with augmentation dot is notated
252 with the duration number followed by a period.
258 This ends the sequential music to be repeated. LilyPond will typeset
265 This line shows that Lily will print an accidental if that is
266 needed: the first C sharp will be printed with an accidental, the
270 a8-. b-. cis-. d-. e-. fis-.
273 You can enter articulation signs either in a verbose form using a
274 shorthand. Here we demonstrate the shorthand: it is formed by a dash
275 and the the character for the articulation to use, e.g. `@code{-.}' for
276 staccato as shown above.
283 Rests are denoted by the special notename `@code{r}'. You can also enter
284 an invisible rest by using the special notename `@code{s}'.
290 All articulations have a verbose form, like @code{\fermata}. The
291 command `@code{\fermata}' is not part of the core of the language (most
292 of the other discussed elements are), but it is a shorthand for a more
293 complicated description of a fermata. @code{\fermata} names that
294 description and is therefore called an @emph{identifier}.
309 This specifies a conversion from music to notation output. Most of
310 the details of this conversions (font sizes, dimensions, etc.) have
311 been taken care of, but to fit the output in this document, it has
312 to be smaller. We do this by setting the line width to 14 centimeters
313 (approximately 6 inches).
319 The last brace ends the @code{\score} block.
321 There are two things to note here. The format contains musical
322 concepts like pitches and durations, instead of symbols and positions:
323 the input format tries to capture the meaning of @emph{music}, and not
324 notation. Therefore Second, the format tries to be @emph{context-free}:
325 a note will sound the same regardless of the current time signature,
328 The purpose of LilyPond is explained informally by the term `music
329 typesetter'. This is not a fully correct name: not only does the
330 program print musical symbols, it also makes esthetic decisions. All
331 symbols and their placement is @emph{generated} from a high-level musical
332 description. In other words, LilyPond would be best
333 described by `music compiler' or `music to notation compiler'.
335 @node Lyrics and chords, , , Tutorial
336 @section Lyrics and chords
338 In this section we show how to typeset a song of unknown
339 origin.@footnote{The author would welcome information about the origin
344 title = "The river is flowing";
345 composer = "Traditional (?)";
347 \include "paper16.ly"
348 melody = \notes \relative c' @{
351 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
352 c4 c8 d [es () d] c4 | d4 es8 d c4.
357 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
358 ri -- ver is flo -- wing down to the sea.
361 accompaniment =\chords @{
363 c2:3- f:3-.7 d:min es4 c8:min r8
364 c2:min f:min7 g:7^3.5 c:min @}
369 \context ChordNames \accompaniment
372 \context Staff = mel @{
373 \property Staff.noAutoBeaming = "1"
374 \property Staff.automaticMelismata = "1"
377 \context Lyrics \text
380 \paper @{ linewidth = 10.0\cm; @}
385 The result would look this@footnote{The titling and font size shown
386 may differ, since the titling in this document is not generated by
389 @center @strong{The river is flowing}
394 title = "The river is flowing";
395 composer = "Traditional (?)";
397 \include "paper16.ly"
398 melody = \notes \relative c' {
402 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
403 c4 c8 d [es () d] c4 | d4 es8 d c4.
408 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
409 ri -- ver is flo -- wing down to the sea.
412 accompaniment =\chords {
414 c2:3- f:3-.7 d:min es4 c8:min r8
415 c2:min f:min7 g:7^3.5 c:min }
420 \context ChordNames \accompaniment
423 \context Staff = mel {
424 \property Staff.noAutoBeaming = "1"
425 \property Staff.automaticMelismata = "1"
428 \context Lyrics \text
431 \paper { linewidth = 10.0\cm; }
435 Again, we will dissect the file line by line.
441 Information about the music you are about to typeset goes into a
442 @code{\header} block. The information in this block is not used by
443 LilyPond, but it is included in the output. @file{ly2dvi} uses this
444 information to print titles above the music.
447 title = "The river is flowing";
448 composer = "Traditional (?)";
450 the @code{\header} block contains assignments. An assignment starts
451 with a string. (which is unquoted, in this case). Then comes the
452 equal sign `@code{=}'. After the equal sign comes the expression you
453 want to store. In this case, you want to put in strings. The
454 information has to be quoted here, because it contains spaces. The
455 assignment is finished with a semicolon.
458 \include "paper16.ly"
461 Smaller size for inclusion in a book.
464 melody = \notes \relative c' @{
467 The structure of the file will be the same as the previous one, a
468 @code{\score} block with music in it. To keep things readable, we will
469 give names to the different parts of music, and use the names to
470 construct the music within the score block.
476 The piece starts with an anacrusis of one eighth.
480 The key is C minor: we have three flats.
484 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
485 c4 c8 d [es () d] c4 | d4 es8 d c4.
490 We use explicit beaming. Since this is a song, we will turn automatic
491 beams off, and use explicit beaming where needed.
497 This ends the definition of @code{melody}. Note that there are no
498 semicolons after assignments at top level.
504 Another identifier assignment. This one is for the lyrics.
505 Lyrics are formed by syllables that have duration, and not by
506 notes. To make LilyPond parse words as syllables, switch it into
507 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
508 is a shorthand for @code{\sequential @{}.
511 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
512 ri- ver is flo- __ wing down to the sea.
516 The syllables themselves are separated by spaces. You can get syllable
517 extenders by entering `@code{__}', and centered hyphens with
518 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
519 in length (hence the @code{4}), and use a feature to align the
520 syllables to the music (which obviously isn't all quarter notes.)
523 accompaniment =\chords @{
526 We'll put chords over the music. There is a special mode (analogous
527 to @code{\lyrics} and @code{\notes} mode) where you can give the names
528 of the chords you want, instead of the notes comprising the chord.
534 There is no accompaniment during the anacrusis.
540 A chord is started by the tonic of the chord. The
541 first one lasts a half note. An unadorned note creates a major
542 triad, while a minor triad is wanted. @code{3-} modifies the third to
543 be small. @code{7} modifies (adds) a seventh, which is small by default
544 to create the @code{f a c es} chord. Multiple modifiers must be
551 Some modifiers have predefined names, eg. @code{min} is the same as
552 @code{3-}, so @code{d-min} is a minor @code{d} chord.
555 c2:min f:min7 g:7^3.5 c:min @}
558 A named modifier @code{min} and a normal modifier @code{7} do not have
559 to be separated by a dot. Tones from a chord are removed with chord
560 subtractions. Subtractions are started with a caret, and they are
561 also separated by dots. In this example, @code{g:7^3.5} produces a
562 minor seventh. The brace ends the sequential music.
569 We assemble the music in the @code{\score} block. Melody, lyrics and
570 accompaniment have to sound at the same time, so they should be
571 @code{\simultaneous}.
577 Chord mode generates notes grouped in @code{\simultaneous} music. If
578 you remove the comment sign, you can see the chords in normal
579 notation: they will be printed as note heads on a separate
583 \context ChordNames \accompaniment
586 Normally, the notes that you enter are transformed into note heads.
587 The note heads alone make no sense, they need surrounding information:
588 a key signature, a clef, staff lines, etc. They need @emph{context}. In
589 LilyPond, these symbols are created by objects called `interpretation
590 context'. Interpretation contexts only exist during a run of
591 LilyPond. Interpretation contexts that are for printing music (as
592 opposed to playing music) are called `notation context'.
594 By default, LilyPond will create a Staff contexts for you. If you
595 would remove the @code{%} sign in the previous line, you can see that
598 We don't want default contexts here, because we want names, not note
599 heads. An interpretation context can also created upon explicit
600 request. The keyword for such a request is @code{\context}. It takes
601 two arguments. The first is the name of a interpretation context.
602 The name is a string, it can be quoted with double quotes). The
603 second argument is the music that should be interpreted in this
604 context. For the previous line, we could have written @code{\context
605 Staff \accompaniment}, and get the same effect.
611 The lyrics need to be aligned with the melody. This is done by
612 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
613 pieces of music (usually a melody and lyrics, in that order) and
614 aligns the syllables of the second piece under the notes of the
615 first piece. If you would reverse the order, the notes would be
616 aligned on the lyrics, which is not very useful. (Besides, it looks
620 \context Staff = mel @{
623 This is the argument of @code{\addlyrics}. We instantiate a
624 @code{Staff} context explicitly: should you chose to remove comment
625 before the ``note heads'' version of the accompaniment, the
626 accompaniment will be on a nameless staff. The melody has to be on a
627 different staff as the accompaniment. This is accomplished by giving
628 the melody staff a different name.
631 \property Staff.noAutoBeaming = "1"
634 An interpretation context has variables that tune its behaviour. One
635 of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
636 true) LilyPond will not try to put automatic beaming on the current
640 \property Staff.automaticMelismata = "1"
643 Similarly, we don't want to print a syllable when there is
644 a slur. This sets up the Staff context to signal slurs while
645 @code{\addlyrics} is processed.
652 Finally, we put the melody on the current staff. Note that the
653 @code{\property} directives and @code{\melody} are grouped in sequential
654 music, so the property settings are done before the melody is
658 \context Lyrics \text
661 The second argument of @code{\addlyrics} is the text. The text also
662 should not land on a Staff, but on a interpretation context for
663 syllables, extenders, hyphens etc. This context is called
670 This ends @code{\simultaneous}.
676 This makes the music go to a MIDI file. MIDI is great for
677 checking music you enter. You listen to the MIDI file: if you hear
678 something unexpected, it's probably a typing error. @code{\midi} is an
679 `output definition', a declaration that specifies how to output music
680 analogous to @code{\paper @{ @}}.
683 \paper @{ linewidth = 10.0\cm; @}
686 We also want notation output. The linewidth is short so the piece
687 will be set in two lines.
695 @node Piano music, , , Tutorial
698 Our third subject is a piece piano music. The fragment in the input
699 file is a piano reduction of the G major Sinfonia by Giovanni Battista
700 Sammartini. It was composed around 1740.
704 \include "paper16.ly";
706 viola = \notes \relative c' \context Voice = viola {
708 \property Voice.verticalDirection = \down g'8. b,16
713 oboes = \notes \relative c'' \context Voice = oboe {
714 \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
715 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
717 { \times 2/3 { a8 g c } \! c2 }
718 \context Voice = oboeTwo {
721 \property Grace.verticalDirection = \down
726 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
727 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
728 [<c16( e> < )e8. g>] <c8 e,>
731 hoomPah = \notes \transpose c' {
732 c8 \translator Staff = top \stemdown
733 c'8 \translator Staff = bottom \stemup }
735 hoomPahHoomPah = { [\hoomPah \hoomPah] }
737 bassvoices = \notes \relative c' {
739 \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
740 \stemdown [c8 c'8] r4
742 < {\stemup r2 <e4 c'> <c8 g'> }
743 \context Voice = reallyLow {\stemdown g2 ~ | g4 c8 } >
747 \context PianoStaff \notes <
748 \context Staff = top < \time 2/2;
749 \context Voice = viola \viola
752 \context Staff = bottom < \time 2/2; \clef bass;
759 linewidth = 15.0 \cm; }
763 If it looks like incomprehensible gibberish to you@dots{} Then you are
764 right. The author has doctored this example to have as many quirks in
765 one system as possible.
767 viola = \notes \relative c' \context Voice = viola @{
769 In this example, you can see multiple parts on a staff. Each part is
770 associated with one notation context. This notation context handles
771 stems and dynamics (among others). The name of this context is
772 @code{Voice}. For each part we have to make sure that there is
773 precisely one Voice context@footnote{If @code{\context} would not
774 have been specified explicitly, three @code{Voice} contexts would be
775 created: one for each note in the first chord.}.
779 @code{<} and @code{>} are short hands for @code{\simultaneous @{} and
780 @code{@}}. So the expression enclosed in @code{<} and @code{>} is a
781 chord. @code{\f} places a forte symbol under the chord.
783 \property Voice.verticalDirection = \down
785 @code{verticalDirection} is a property of the voice context. It
786 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 fiddle with a property and make a beam. The argument of
865 @code{\grace} is sequential music.
867 \property Grace.verticalDirection = \down
870 Normally, grace notes are always stem up, but in this case, the upper
871 voice interferes. We set the stems down here.
873 As far as relative mode is concerned, the previous note is the
874 @code{c'''2} of the upper voice, so we have to go an octave down for
881 This ends the two-part section.
884 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
886 @code{\stemboth} ends the forced stem directions. From here, stems are
887 positioned as if it were single part music.
889 The bass has a little hoom-pah melody to demonstrate parts switching
890 between staffs. Since it is repetitive, we use identifiers:
892 hoomPah = \notes \transpose c' @{
894 Transposing can be done with @code{\transpose}. It takes two
895 arguments; the first specifies what central C should be transposed to.
896 The second is the to-be-transposed music. As you can see, in this
897 case, the transposition is a no-op. Central C is transposed to
900 The purpose of this no-op is circumventing relative mode. Relative
901 mode can not be used in conjunction with transposition, so relative
902 mode will leave the contents of @code{\hoomPah} alone. We can use it
903 without having to worry about getting the motive in a wrong
904 octave@footnote{@code{hoomPah = \relative @dots{}} would be more
905 intuitive to use, but that would not let me plug @code{\transpose}
908 c8 \translator Staff = top \stemdown
910 We assume that the first note will be put in the lower staff. After
911 that note we switch to the upper staff with @code{\translator}. To be
912 precise, this @code{\translator} entry switches the current voice to a
913 @code{Staff} named @code{top}. So we have to name the upper staff
914 `@code{top}'. Stem directions are set to avoid interfering with the
917 c'8 \translator Staff = bottom \stemup @}
919 Then a note is put on the upper staff, and we switch again. We have
920 to name the lower staff `@code{bottom}'.
922 hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
924 Put two of these fragments in sequence, and beam them.@example
925 bassvoices = \notes \relative c' @{
927 \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
930 Entering the bass part is easy: the hoomPahHoomPah variable is
931 referenced four times.
933 \context Voice = reallyLow @{\stemdown g2 ~ | g4 c8 @} >
935 After skipping some lines, we see @code{~}. This mark makes ties.
939 For piano music, a special context is needed to get cross staff
940 beaming right. It is called @code{PianoStaff}.
942 \context Staff = bottom < \time 2/2; \clef bass;
944 The bottom staff must have a different clef.
948 To make some more room on the line, the first (in this case the only)
949 line is not indented. The line still looks is very cramped, but that is due
950 to the format of this tutorial.
952 This example shows a lot of features, but the organisation isn't
953 perfect. For example, it would be less confusing to use a chord
954 containing sequential music than a sequence of chords for the oboe
957 [TODO: demonstrate Hara-Kiri with scores and part extraction.]
959 @node end of tutorial, , , Tutorial
962 That's all folks. From here, you can either try fiddling with input
963 files, or you can read the reference manual.