3 @c TODO: LilyPond LilyPond LilyPond
9 <!--- @@WEB-TITLE@@=Tutorial --->
13 * First steps:: Music language of LilyPond
15 * Running LilyPond:: Printing music
16 * The first real tune:: The first real tune
17 * Lyrics and chords:: Lyrics and chords
18 * More movements :: Joining separate pieces of music
19 * A piano excerpt:: Piano music
20 * Fine tuning a piece::
21 * An orchestral score:: Conductor's score and individual parts
22 * Other ways to run LilyPond:: Other ways to run LilyPond
23 * Integrating text and music:: Integrating text and music
24 * End of tutorial:: The end
27 Operating lilypond is done through text files: to print a piece of
28 music, you enter the music in a file. When you run lilypond, that
29 file is read, and after some computations, the program produces a file
30 containing the sheet music that you can print or view.
32 This tutorial starts with a small introduction to the LilyPond music
33 language. After this first contact, we will show you how to run
34 LilyPond to produce printed output; you should then be able to create
35 your first sheets of music. The tutorial continues with more and more
44 @c @node Music language of LilyPond
45 @c @section Music language of LilyPond
47 In this section, we show how can make small, very simple examples in
48 LilyPond. If you have not seen LilyPond input files before, this
49 section is for you. The contents of this section are summarized in the
50 Cheat Sheet (See @ref{Cheat sheet}).
52 You get a simple note by typing its note name, from @code{a} through
53 @code{g}. So if you enter
58 then the result looks like this:
60 \property Score.timing = ##f
61 \property Staff.TimeSignature = \turnOff
62 \transpose c'' { c d e f g a b }
67 We continue showing LilyPond input like we did previously: first a
68 snippet of input, then the resulting output.
70 The length of a note is specified by adding a number, ``@code{1}'' for a
71 whole note, ``@code{2}'' for a half note, and so on:
78 @c missing clef seems to raise more questions than actual pitch of notes,
79 @c as these are snippets anyway
81 \property Score.timing = ##f
82 \property Staff.TimeSignature = \turnOff
83 \property Staff.autoBeaming = ##f
84 %\property Staff.Clef = \turnOff
85 \transpose c'' { a1 a2 a4 a16 a32 }
91 If you don't specify a duration, the previous one is used:
97 @c missing clef seems to raise more questions than actual pitch of notes,
98 @c as these are snippets anyway
100 \property Score.timing = ##f
101 \property Staff.TimeSignature = \turnOff
102 %\property Staff.Clef = \turnOff
103 \transpose c'' { a a a2 a }
109 A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
110 (@texiflat{}) by adding ``@code{es}'':
118 \property Score.timing = ##f
119 \property Staff.TimeSignature = \turnOff
120 \transpose c'' { cis1 ees fisis aeses }
126 Add a dot ``@code{.}'' after the duration to get a dotted note:
132 @c missing clef seems to raise more questions than actual pitch of notes,
133 @c as these are snippets anyway
135 \property Score.timing = ##f
136 \property Staff.TimeSignature \set #'transparent = ##t
137 %\property Staff.Clef = \turnOff
138 \transpose c'' { a2. a4 a8. a16 }
144 The meter (or time signature) can be set with the @code{\time} command:
153 @c a clef here may lead to confusion
155 \property Staff.Clef \set #'transparent = ##t
166 The clef can be set using the ``@code{\clef}'' command:
168 @c what is more common name treble or violin?
169 @c in Dutch, its violin.
179 \property Score.timing = ##f
180 \property Staff.TimeSignature = \turnOff
193 From these commands and notes, a piece of music can be formed. A piece
194 of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
195 LilyPond then knows that music follows (and not lyrics, for example):
209 At this point, the piece of music is ready to be printed. This is done
210 by combining the music with a printing command.
212 The printing command is the so-called ``@code{\paper}'' block. You
213 will see later that the \paper block is necessary to customize all
214 kinds of printing specifics. The music and the \paper block are
215 combined by enclosing them in ``@code{\score @{ ... @}}''. This is
216 what a full LilyPond source file looks like:
239 \paper { linewidth = 60 * \staffspace }
246 We continue with the introduction of the remaining musical constructs.
248 @c maybe legend here?
250 Normal rests are entered just like notes with the name ``@code{r}'':
258 \property Score.timing = ##f
259 \property Staff.Clef = \turnOff
260 \property Staff.TimeSignature = \turnOff
267 @c Tim wants to move this quotes example just before the: quotes-don't-work
268 @c score, but we'd need to remove quotes from the other two (key and
271 @c better to have this just before the `octaves are bad' snipped
272 @c but we'd need to remove the ', from \key and tie
273 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
274 the note name, to lower a note one octave, add a ``low quote'' @code{,}
275 (a comma). The central C is @code{c'}:
279 c'4 c'' c''' \clef bass c c,
283 \property Score.timing = ##f
284 \property Staff.TimeSignature = \turnOff
285 c'4 c'' c''' \clef bass c c,
290 A tie is created by entering a tilde ``@code{~}'' between the notes to
291 be tied. A tie between two notes means that the second note must not be
292 played separately, but just makes the first note sound longer:
295 @lilypond[fragment,verbatim]
301 The key signature is set with the command ``@code{\key}'':
311 \property Staff.TimeSignature = \turnOff
320 @c bit on the long/complex/scary taste
321 @c cheating a bit: two lines makes for a friendlier look
322 This example shows notes, ties, octave marks, and rests in action.
323 Don't worry about all the quotes.
332 r4 r8 d''8 cis''4 e''
334 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
347 r4 r8 d''8 cis''4 e''
349 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
352 \paper { linewidth = 50*\staffspace }
358 There are some interesting points to note in this example. Firstly,
359 accidentals (sharps and flats) don't have to be marked explicitly: you
360 just enter the note name, and LilyPond determines whether or not to
361 print an accidental. Secondly, bar lines and beams are drawn
362 automatically. Thirdly, LilyPond calculates line breaks for you; it
363 doesn't matter where you make new lines in the source file.
365 The example also indicates that a piece of music written in a high
366 register needs lots of quotes. This makes the input a bit unreadable,
367 and is therefore also a potential source of errors.
371 The solution is to use ``relative octave'' mode. In practice, most
372 music is entered using this mode.
374 To use relative mode, add @code{\relative} before the piece of music.
375 You must also give a note from which relative starts, in this case
378 @c In relative octave mode, quotes are used to mark large jumps in the
379 @c melody. Without any quotes or commas, the interval between a note and
380 @c its predecessor is assumed to be a fourth or less. Quotes and commas
381 @c add octaves in up and down direction.
383 If you type no octaviation quotes, relative mode chooses the note that
384 is closest to the previous one, which is often just the one you need.
385 @c don't use commas or quotes in this sentence
386 For example: @code{c f} goes up; @code{c g} goes down:
396 \property Score.timing = ##f
397 \property Staff.TimeSignature = \turnOff
405 @c needed better, maybe even redundant explanation
406 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
407 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
408 You can make a large interval by adding octaviation quotes. Note that
409 quotes or commas do not determine the absolute height of a note;
410 the height of a note is relative to the previous one.
411 @c don't use commas or quotes in this sentence
412 For example: @code{c f,} goes down; @code{f, f} are both the same;
413 @code{c c'} are the same; and @code{c g'} goes up:
423 \property Score.timing = ##f
424 \property Staff.TimeSignature = \turnOff
432 A slur is drawn across many notes, and indicates bound articulation
433 (legato). The starting note and ending note are marked with a
434 ``@code{(}'' and a ``@code{)}'' respectively:
437 @lilypond[fragment,relative 1, verbatim]
438 d4( )c16( cis d e c cis d )e( )d4
443 If you need two slurs at the same time (one for articulation, one for
444 phrasing), you can also make a phrasing slur with @code{\(} and
449 @lilypond[fragment,relative 1, verbatim]
450 a8(\( ais b ) c cis2 b'2 a4 cis, \) c
455 Beams are drawn automatically, but if you don't like the choices, you
456 can enter beams by hand. Surround the notes to be grouped with @code{[}
459 @lilypond[fragment,relative 1, verbatim]
465 To print more than one staff, each piece of music that makes up a staff
466 is marked by adding @code{\context Staff} before it. These
467 @code{Staff}'s can be grouped inside @code{<} and @code{>}, as is
471 @lilypond[fragment,verbatim]
473 \context Staff = staffA { \clef violin c'' }
474 \context Staff = staffB { \clef bass c }
479 In this example, @code{staffA} and @code{staffB} are names that are
480 given to the staves. For now, it doesn't matter what names you give, as
481 long as each staff has a unique name.
485 We can typeset a melody with two staves now:
491 < \context Staff = staffA {
494 \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
496 \context Staff = staffB {
507 Notice that the time signature is specified in one melody staff only
508 (the top staff), but is printed on both. LilyPond knows that the time
509 signature should be the same for all staves.
513 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
515 @lilypond[verbatim,relative 1]
521 Dynamic signs are made by adding the markings to the note:
523 @lilypond[verbatim,relative 1]
529 Crescendi are started with the commands @code{\<} and @code{\>}. The
530 command @code{\!} finishes a crescendo on the following note.
532 @lilypond[verbatim,relative 1]
533 c2\< \!c2-\ff \>c2 \!c2
538 Chords can be made by surrounding notes with @code{<} and @code{>}:
540 @lilypond[relative 0, fragment,verbatim]
548 @c hmm, te losjes, iig
549 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
550 happens at the same time, like in chords, or (like in the two-staff
551 example above) in a bunch of stacked staves.
554 Of course, you can combine beams and ties with chords. Notice that
555 beam and tie markings must be placed outside the chord markers:
557 @lilypond[relative 0, fragment,verbatim]
558 r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
562 When you want to combine chords with slurs and dynamics, technical
563 detail crops up: you have type these commands next to the notes, which
564 means that they have to be inside the @code{< >}:
567 @lilypond[relative 0, fragment,verbatim]
568 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
573 There is one golden rule that you should keep in mind when writing
576 @strong{DO NOT START A PIECE WITH A CHORD}
578 Of course, it is a allowed, but the result might not be what you expect:
580 @lilypond[verbatim,singleline]
581 \score { \notes <c'2 e'2> }
586 Of course, it is possible to typeset pieces that start with a chord,
587 but you must make explicit that the notes of chord are to be put on
588 the same staff, in the same voice. This is done by specifying
589 @code{\context Staff} for the notes:
592 @lilypond[verbatim,singleline]
593 \score { \notes \context Voice <c'2 e'2> }
602 [TODO add some more here
613 This is the end of the simple tutorial. You know the basic ingredients
614 of a music file, so this is the right moment to try your at hand at
615 doing it yourself: try to type some simple examples, and experiment a
618 When you're comfortable with the basics, then you might want to read the
619 rest of this chapter. It also a manual in tutorial-style, but it is much
620 more in-depth. It will also be very intimidating if you're not familiar
621 with the basics. It deals with some of the more advanced features of
622 LilyPond. Topics include lyrics, chords, orchestral scores and parts,
623 fine tuning output, polyphonic music, and integrating text and music.
626 @c refer to this section
631 @c need texinfo-4.0a or later for this
634 @c both Tim and my father came independently with a request for a
635 @c `legend' like this.
637 @c what should be in it?
642 @multitable @columnfractions .20 .20 .40
645 @item @code{1 2 8 16}
648 @lilypond[fragment, relative 1]
653 @tab augmentation dots
655 @lilypond[fragment, relative 1]
659 @item @code{c d e f g a b }
662 @lilypond[fragment, relative 1]
669 @lilypond[fragment, relative 2]
673 @item @code{-. -^ ->}
674 @tab articulations (1)
676 @lilypond[fragment, relative 2]
681 @item @code{-\trill -\fermata}
682 @tab articulations (2)
684 @lilypond[fragment, relative 2]
689 @item @code{\time 3/4 \time 6/8 \time 4/4 }
693 \property Staff.Clef \set #'transparent = ##t
703 @item @code{\clef treble \clef bass }
707 \property Staff.TimeSignature \set #'transparent = ##t
715 @item @code{\sfz \mf }
718 @lilypond[fragment,relative 1]
725 @lilypond[fragment, relative 1]
726 \property Score.timing = ##f
727 \property Staff.TimeSignature = \turnOff
728 \property Staff.autoBeaming = ##f
729 \property Staff.Clef = \turnOff
736 @lilypond[fragment, relative 1]
737 \property Score.timing = ##f
738 \property Staff.TimeSignature = \turnOff
739 \property Staff.autoBeaming = ##f
740 \property Staff.Clef = \turnOff
747 @lilypond[fragment, relative 1]
748 \property Score.timing = ##f
749 \property Staff.TimeSignature = \turnOff
750 \property Staff.autoBeaming = ##f
751 \property Staff.Clef = \turnOff
757 @lilypond[fragment, relative 1]
758 \property Score.timing = ##f
759 \property Staff.TimeSignature = \turnOff
760 \property Staff.autoBeaming = ##f
761 \property Staff.Clef = \turnOff
768 @lilypond[fragment, relative 1]
769 \property Score.timing = ##f
770 \property Staff.TimeSignature = \turnOff
771 \property Staff.autoBeaming = ##f
772 \property Staff.Clef = \turnOff
779 @lilypond[fragment, relative 1]
780 \property Score.timing = ##f
781 \property Staff.TimeSignature = \turnOff
782 \property Staff.autoBeaming = ##f
783 \property Staff.Clef = \turnOff
784 \context Voice { <a c> }
790 @lilypond[fragment, relative 1]
791 \property Score.timing = ##f
792 \property Staff.TimeSignature = \turnOff
793 \property Staff.autoBeaming = ##f
794 \property Staff.Clef = \turnOff
801 @lilypond[fragment, relative 1]
802 \property Score.timing = ##f
803 \property Staff.TimeSignature = \turnOff
804 \property Staff.autoBeaming = ##f
805 \property Staff.Clef = \turnOff
814 @node Running LilyPond
815 @section Running LilyPond
817 In the last section, we explained what kind of things you could enter
818 in a lilypond file. In this section we explain how to run LilyPond,
819 and how view or print the output. If you have not used LilyPond
820 before, want to test your setup of LilyPond, or try to run an example
821 file yourself, then read this section. The instructions that follow
822 are for running LilyPond on Unix-like systems. Some additional
823 instructions for running LilyPond on Windows are given at the end of
826 You begin with opening a terminal window, and start up a text editor.
827 For example, open an xterm and execute @code{joe}. In your text editor,
828 enter the following input, and save the file as @file{test.ly}:
833 \notes @{ c'4 e' g' @}
840 @c now this is weird, running ly2dvi to run LilyPond
841 @c (therefore name change proposal)
843 LilyPond is the program that computes the sheet music. All other
844 things, such as titles and page layout, are done by a small wrapper
845 program called @code{ly2dvi}. @code{ly2dvi} calls lilypond to render
846 the music, and then adds the titling and page layout instructions. To
847 process @file{test.ly} with ly2dvi, proceed as follows:
855 You will see the following on your screen:
860 Now processing: `/home/fred/ly/test.ly'
862 Interpreting music...[1]
863 @emph{ ... more interesting stuff ... }
864 PS output to `test.ps'...
865 DVI output to `test.dvi'...
869 @cindex Viewing music
872 The results of the ly2dvi run are two files, @file{test.dvi} and
873 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
874 You can view the PS file using the program ghostview. If a version of
875 ghostview is installed on your system, one of these commands will
876 produce a window with some music notation on your screen:
886 If you are satisfied with the looks of the music displayed on your
887 screen, you can print the PS file by clicking File/Print inside
890 The DVI file (@file{test.dvi}) contains the same sheet music in a
891 different format. DVI files are more easily processed by the computer,
892 so viewing them usually is quicker. Execute @code{xdvi test.dvi}
893 to view the DVI file.
895 If your DVI viewer does not have a "Print" button, you can print the
896 file by executing @code{lpr test.ps}.
898 @c volgende alinea schrappen?
900 If you can't get the examples to print, then you should look into
901 installing and configuring ghostscript. Refer to GhostScript's website
902 at @uref{http://www.ghostscript.com}.
906 @cindex Printing output
909 @unnumberedsubsec Windows users
910 Windows users start the terminal by clicking on the LilyPond or Cygwin
911 icon. Notepad is sufficient for editing the LilyPond file. Viewing
912 the PS file can be done with:
915 @code{gsview32 test.ps}
918 You can also print from the command line by executing:
921 @code{gsview32 /s test.ps}
926 @node The first real tune
927 @section The first real tune
930 The rest of this tutorial will demonstrate how to use Lilypond by
931 presenting examples of input along with resulting output. We will use
932 English terms for notation. In case you are not familiar with those,
933 you may consult the glossary that is distributed with LilyPond.
935 The examples discussed are included in the distribution, in the
936 subdirectory @file{input/tutorial/}@footnote{When we refer to filenames,
937 they are relative to the top directory of the source package. }
939 To demonstrate what LilyPond input looks like, we start off with a
940 full-fledged, yet simple example. It is a convoluted version
941 of the famous minuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
942 is included in the distribution as @file{minuet.ly}.
943 @cindex Bach, Johann Sebastian
946 % all text after a percent sign is a comment
947 % and is ignored by LilyPond
948 \include "paper16.ly"
951 \relative c'' \sequential {
956 d4 g,8 a b c d4 g, g |
957 e'4 c8 d e fis g4 g, g |
958 c4 d8( )c b a( )b4 c8 b a g |
959 a4 [b8 a] [g fis] g2. |
964 g4 e8 fis g d cis4 b8 cis a4 |
965 a8-. b-. cis-. d-. e-. fis-.
972 % standard settings are too big and wide for a book
979 We will analyse the input, line by line.
982 % all text after a percent sign is a comment
983 % and is ignored by LilyPond
985 Percent signs introduce comments: everything after a percent sign is
986 ignored. You can use this If you want to write down mental notes to
987 yourself in a file, then you can enter preceded with a @code{%} sign.
988 These lines are called comments. If you have long winded mental notes,
989 you can make comments that span several lines by enclosing text in
990 @code{%@{} and @code{%@}}.
992 @cindex block comment
997 \include "paper16.ly"
1000 @cindex @code{\include}
1001 @cindex point, printer's
1002 @cindex staff size, setting
1003 @cindex font size, setting
1005 By default, LilyPond will typeset the music in a size such that each
1006 staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output
1007 (16 point staff height), so we must import the settings for that size,
1015 Music is printed by combining a piece of music with directions for
1016 outputting it. This combination is formed in the @code{\score} block.
1023 Prepare LilyPond for accepting notes.
1024 @cindex octaves, choosing
1033 @c removed duplicate introduction to octave marks /MB
1034 @c Shorten even more?
1036 @c As we will see, each note is described by its note name, duration,
1037 @c octave and possibly a chromatic alteration. In this setup, the octave
1038 @c is indicated by using high quotes (@code{'}) and ``lowered quotes''
1039 @c (commas: @code{,}). The central C is denoted by @code{c'}. The C one
1040 @c octave higher is @code{c''}. One and two octaves below the central C is
1041 @c denoted by @code{c} and @code{c,} respectively.
1043 Even though a piece of music often spans a range of several octaves,
1044 often melodies move in small intervals. Such melodies can be entered
1045 easily using @code{\relative}. In this ``relative octave mode'',
1046 octaves of notes without quotes are chosen such that a note is as
1047 close as possible (graphically, on the staff) to the preceding note.
1048 If you add a high-quote an extra octave is added. A lowered quote (a
1049 comma) will subtract an extra octave.
1051 Absolute starting pitch for this relative mode is given as the
1052 argument to @code{\relative}. In this case it is the @code{c''}, one
1053 octave above central C.
1061 What follows is sequential music, i.e.,
1062 @cindex sequential music
1063 notes that are to be played and printed after each other.
1070 @cindex time signature, setting
1071 @cindex @code{\time}
1072 The @code{\time} command sets (or changes) the time signature of the
1073 current piece: a 3/4 sign is printed. This setting is also used to
1074 generate bar lines at the right spots.
1081 @cindex key signature, setting
1083 Set (or change) the current key signature to G-major. Although in this
1084 example, the @code{\key} command happened to be entered after the
1085 @code{\time} command, in the output the time signature will be printed
1086 after the key signature; LilyPond knows about music typesetting
1094 The following piece of music is played twice. The first argument
1095 indicates the type of repeat. In this case, @code{"volta"} means that
1096 prima volta/secunda volta brackets are used for the alternative
1097 endings---if there were any.
1099 A special notation for repeats allows you to get correct repeats in
1100 MIDI output. However, some extra trickery is needed to get this
1101 working, See @ref{Repeats and MIDI}.
1108 The subject of the repeat is again sequential music. Since
1109 @code{\sequential} is such a common construct, a shorthand is provided:
1110 just leave off @code{\sequential}, and the result is the same.
1117 Two notes. The first note is a quarter note with relative pitch
1118 @code{d}. The relative music was started with a @code{c''}, so the real
1119 pitch of this note is @code{d''}. The duration of a note is designated
1120 by a number; the @code{4} here represents a quarter note.
1122 The second note is an eight note with relative pitch @code{g,}. The
1123 pitch is taken relative to the previous @code{d''}, making this
1124 note have real pitch @code{g'}. The @code{8} represents an eight note.
1131 Two more notes, with pitch @code{a} and @code{b}. Because their
1132 duration is the same as the @code{g,8}, there is no need to enter the
1133 duration, but you may enter it anyway, i.e., @code{a8 b8}
1142 @cindex errors, finding
1143 Three more notes. The @code{|} character is a ``bar check''. LilyPond
1144 will verify that bar checks are found at the start of a measure. This can
1145 help you track down typing errors.
1147 @cindex alteration, chromatic
1148 @cindex chromatic alteration
1155 So far, no notes were chromatically altered. Here is the first one
1156 that is: @code{fis}. LilyPond uses Dutch note names, and ``Fis'' is
1157 the name for ``F sharp''. There is no sharp sign in the output. The
1158 program keeps track of key signatures, and will only print accidentals
1159 if they are needed. If you can not get used to Dutch names, then
1160 there also are names available in several other languages.
1163 For groups of eighth notes and shorter, LilyPond can determine how the
1164 notes should form a beam. In this case, the 4 eights are automatically
1169 c4 d8( )c b a( )b4 c8 b a g |
1172 The beginning and ending notes of a slur are marked with parentheses,
1173 @code{(} and @code{)} for start and end respectively. The line above
1174 indicates two slurs. These slur markers (parentheses) are entered
1175 between the slurred notes.
1182 Automatic beaming can be overridden by inserting beam marks, @code{[}
1183 and @code{]}. These beam markers (brackets) are put around the notes
1191 @cindex augmentation dot
1193 A period adds a dot to the note.
1200 The end of the sequential music to be repeated. LilyPond will typeset a
1208 Accidentals are printed whenever necessary: the first C sharp of the bar
1209 will be printed with an accidental, the second one without.
1213 a8-. b-. cis-. d-. e-. fis-.
1216 @cindex articulation
1217 Staccato signs are entered as a dash and a period. Some other
1218 articulations may also be entered in this short form.
1226 Rests are denoted by the special note name @code{r}.
1233 All articulations have a verbose form, like @code{\fermata}. The
1234 command @code{\fermata} is not part of the core of the language, but it
1235 is a shorthand for a more complicated description of a fermata symbol.
1236 @code{\fermata} names that description and is therefore called an
1239 @cindex @code{\fermata}
1245 Here the music ends. LilyPond does not automatically typeset an end
1246 bar, we must explicitly request one, using @code{"|."}.
1252 % standard settings are too big and wide for a book
1258 The @code{\paper} block specifies how entered music should be converted
1259 to notation output. Most of the details of the conversion (font sizes,
1260 dimensions, etc.) have been taken care of, but to fit the output in this
1261 document, it has to be narrower. We do this by setting the line width
1262 to 14 centimeters (approximately 5.5 inches).
1269 The last brace ends the @code{\score} block.
1274 @node Lyrics and chords
1275 @section Lyrics and chords
1277 In this section we show how to typeset a song. This file is
1278 included as @file{flowing.ly}.
1282 title = "The river is flowing"
1283 composer = "Traditional"
1285 \include "paper16.ly"
1286 melody = \notes \relative c' @{
1290 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1291 c4 c8 d [es () d] c4 | d4 es8 d c4.
1296 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
1297 ri -- ver is flo -- wing down to the sea.
1300 accompaniment =\chords @{
1302 c2:3- f:3-.7 d:min es4 c8:min r8
1303 c2:min f:min7 g:7^3.5 c:min @}
1308 \context ChordNames \accompaniment
1311 \context Staff = mel @{
1312 \property Staff.autoBeaming = ##f
1313 \property Staff.automaticMelismata = ##t
1316 \context Lyrics \text
1318 \midi @{ \tempo 4=72 @}
1319 \paper @{ linewidth = 10.0\cm @}
1324 The result would look this.@footnote{The titling and font size shown
1325 may differ, since the titling in this document is not generated by
1328 @center @strong{The river is flowing}
1333 title = "The river is flowing"
1334 composer = "Traditional"
1336 \include "paper16.ly"
1337 melody = \notes \relative c' {
1341 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1342 c4 c8 d [es () d] c4 | d4 es8 d c4.
1347 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
1348 ri -- ver is flo -- wing down to the sea.
1351 accompaniment =\chords {
1353 c2:3- f:3-.7 d:min es4 c8:min r8
1354 c2:min f:min7 g:7^3.5 c:min }
1359 \context ChordNames \accompaniment
1362 \context Staff = mel {
1363 \property Staff.autoBeaming = ##f
1364 \property Staff.automaticMelismata = ##t
1367 \context Lyrics \text
1369 \midi { \tempo 4=72 }
1370 \paper { linewidth = 10.0\cm }
1374 Again, we will dissect the file line by line.
1381 @cindex @code{\header}
1382 Information about the music you are about to typeset goes into a
1383 @code{\header} block. The information in this block is not used by
1384 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
1385 information to print titles above the music.
1389 title = "The river is flowing"
1390 composer = "Traditional (?)"
1393 @cindex identifier assignment
1394 the @code{\header} block contains assignments. In each assignment, a
1395 variable is set to a value.
1399 \include "paper16.ly"
1402 Smaller size for inclusion in a book.
1406 melody = \notes \relative c' @{
1409 The structure of the file will be the same as the previous one, a
1410 @code{\score} block with music in it. To keep things readable, we will
1411 give names to the different parts of music, and use the names to
1412 construct the music within the score block.
1419 @cindex @code{\partial}
1421 The piece starts with an anacrusis of one eighth.
1426 The key is C minor: we have three flats.
1431 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1432 c4 c8 d [es () d] c4 | d4 es8 d c4.
1437 @cindex manual beaming
1438 @cindex automatic beaming, turning off
1439 We use explicit beaming. Since this is a song, we turn automatic
1440 beams off, and use explicit beaming where needed.
1447 This ends the definition of @code{melody}.
1456 @cindex identifier assignment
1457 @cindex syllables, entering
1458 Another identifier assignment. This one is for the lyrics.
1459 Lyrics are formed by syllables that have duration, and not by
1460 notes. To make LilyPond parse words as syllables, switch it into
1461 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
1462 is a shorthand for @code{\sequential @{}.
1466 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
1467 ri- ver is flo- __ wing down to the sea.
1471 @cindex extenders, lyric
1472 @cindex hyphens, lyric
1473 The syllables themselves are separated by spaces. You can get syllable
1474 extenders by entering @code{__}, and centered hyphens with
1475 @code{-}@code{-}. We don't enter durations for the syllables. They
1476 are aligned with the melody later.
1480 accompaniment =\chords @{
1484 @cindex mode, chords
1485 We'll put chords over the music. To enter them, there is a special mode
1486 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1487 the names of the chords you want, instead of listing the notes
1488 comprising the chord.
1495 There is no accompaniment during the anacrusis.
1504 @cindex chord modifier
1505 @cindex modifier, chord
1506 This is a c minor chord, lasting half a note. Chord are entered by
1507 entering the tonic. Then notes can be changed. In this case, a small third
1508 is used. The cod for this is @code{3-}.
1514 Similarly, @code{7} modifies (adds) a seventh, which is small by
1515 default to create the @code{f a c es} chord. Multiple modifiers must be
1523 Some modifiers have predefined names, e.g. @code{min} is the same as
1524 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1528 c2:min f:min7 g:7^3.5 c:min @}
1531 @cindex named modifier
1533 A named modifier @code{min} and a normal modifier @code{7} do not have
1534 to be separated by a dot. Tones from a chord are removed with chord
1535 subtractions. Subtractions are started with a caret, and they are
1536 also separated by dots. In this example, @code{g:7^3.5} produces a
1537 minor seventh. The brace ends the sequential music.
1545 We assemble the music in the @code{\score} block. Melody, lyrics and
1546 accompaniment have to sound at the same time, so they should be
1547 @code{\simultaneous}.
1548 @cindex @code{\simultaneous}
1555 Chord mode generates notes grouped in @code{\simultaneous} music. If
1556 you remove the comment sign, you can see the chords in normal
1557 notation: they will be printed as note heads on a separate
1558 staff. To print them as chords names, they have to be interpreted as
1559 being chords, not notes. This is done with the following command:
1563 \context ChordNames \accompaniment
1567 @cindex interpretation context
1568 @cindex notation context
1571 Normally, the notes that you enter are transformed into note heads.
1572 Note heads alone make no sense, they need surrounding information: a key
1573 signature, a clef, staff lines, etc. They need @emph{context}. In
1574 LilyPond, these symbols are created by objects called `interpretation
1575 contexts'. Interpretation contexts exist for generating notation
1576 (`notation context') and for generating sound (`performance
1577 context'). These objects only exist during a run of LilyPond.
1579 When LilyPond interprets music, it will create a Staff context. If
1580 the @code{%} sign in the previous line were removed, you could see
1581 that mechanism in action.
1583 We don't want that default here, because we want chord names. The
1584 command above explicitly creates an interpretation context of
1585 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1592 @cindex @code{\addlyrics}
1593 @cindex lyrics and melody, combining
1594 @cindex combining lyrics and melody
1596 The lyrics should be aligned with the melody. This is done by
1597 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
1598 pieces of music (usually a melody and lyrics, in that order) and
1599 aligns the syllables of the second piece under the notes of the
1604 \context Staff = mel @{
1608 We place the melody on a staff called @code{mel}. We give it a name to
1609 differentiate it from the one that would contain note heads for the
1610 chords, if you would remove the comment before the ``note heads''
1611 version of the accompaniment. By giving this staff a name, it is
1612 forced to be different.
1616 \property Staff.autoBeaming = ##f
1620 @cindex context variables
1621 @cindex setting context variables
1622 An interpretation context has variables, called properties, that tune
1623 its behavior. One of the variables is @code{autoBeaming}. Setting
1624 this @code{Staff}'s property to @code{##f}, which is the boolean value
1625 @var{false}, turns the automatic beaming mechanism off for the current
1631 @cindex accessing Scheme
1632 @cindex evaluating Scheme
1635 LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
1636 language from the LISP family. You can learn more about Scheme at
1637 @uref{http://www.scheme.org}. It is used to represent data throughout
1638 the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
1639 code following the hash-sign is evaluated as Scheme. The boolean value
1640 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
1643 If Scheme scares you, don't worry. You don't need to know Scheme to
1644 create beautiful sheet music.
1651 \property Staff.automaticMelismata = ##t
1654 @cindex automaticMelismata
1656 @cindex @code{\addlyrics} and slurs
1657 Similarly, we don't want to print a syllable when there is
1658 a slur. This sets up @code{\addlyrics} to not put lyrics under each
1659 separate note while there is a slur.
1667 Finally, we put the melody on the current staff. Note that the
1668 @code{\property} directives and @code{\melody} are grouped in sequential
1669 music, so the property settings are done before the melody is
1674 \context Lyrics \text
1677 The second argument of @code{\addlyrics} is the text. The text also
1678 should not land on a Staff, but on a interpretation context for
1679 syllables, extenders, hyphens etc. This context is called
1684 \midi @{ \tempo 4=72@}
1687 MIDI (Musical Instrument Digital Interface) is a standard for
1688 connecting and recording digital instruments. So a MIDI file is like a
1689 tape recording of an instrument. The @code{\midi} block makes the
1690 music go to a MIDI file, so you can listen to the music you entered. It
1691 is great for checking the music. Whenever you hear something weird, you
1692 probably hear a typing error.
1694 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1695 also specifies an output method. You can specify the tempo using the
1696 @code{\tempo} command, in this case the tempo of quarter notes is set to
1697 72 beats per minute.
1701 \paper @{ linewidth = 10.0\cm @}
1704 We also want notation output. The linewidth is short so the piece
1705 will be set in two lines.
1707 @node More movements
1708 @section More movements
1710 [FIXME: merge here with, or move this to: Other ways to run LilyPond]
1712 You probably ran @file{ly2dvi} on the last example, and ended up with a
1713 viewable @file{.dvi} file. However, between there are a few steps of
1714 which LilyPond is only one. To enhance your understanding of what's
1715 happening under the hood when you run @code{ly2dvi}, we explain what
1718 @code{ly2dvi} is a program that calls a number of programs in sequence.
1719 The first thing it does, is running LilyPond on the input file. After
1720 some calculations, a @file{.tex} is produced. The contents
1721 of this file are very low-level instructions.
1723 For example, consider the following file (@file{miniatures.ly})
1728 title = "Two miniatures"
1729 tagline = "small is beautiful"
1732 #(set! point-and-click line-column-location)
1734 \paper @{ linewidth = -1.0 @}
1737 \notes @{ c'4 d'4 @}
1743 \notes @{ d'4 c'4 @}
1750 The titling in this manual was not generated by ly2dvi, so we can't
1751 exactly show what it would look like, but the result should resemble this:
1753 @center @strong{Two miniatures}
1763 \paper { linewidth = -1.0 }
1775 \paper { linewidth = -1.0 }
1779 This file is produced by ly2dvi in a few stages, with the help of text
1780 formatting tools. LilyPond produces two output files,
1781 @file{miniatures.tex} and @file{miniatures-1.tex}. Both files contain
1782 only graphical music notation. @file{ly2dvi} looks at what output
1783 LilyPond produces, and adds page layout and titling to those files. The
1784 result is a DVI file called @file{miniatures.dvi}.
1786 Next, now we'll look at the example line by line to explain new things.
1792 Lilypond and its language are still under development, and occasionally,
1793 details of the syntax are changed. This fragment indicates for which
1794 version the input file was written. When you compile this file, the
1795 version number will be checked, and you will get a warning when the file
1798 This version number is also used by the @code{convert-ly} program (See
1799 @ref{convert-ly}), which is used to update the file to the latest lily
1805 title = "Two miniatures" @}
1807 This sets the titling information for the entire file.
1810 tagline = "small is beautiful"
1812 A signature line is printed at the bottom of the last page.
1813 This signature is produced from the @code{tagline} field of
1814 @code{\header}. Many people find the default "Lily was here,
1815 @var{version number}" too droll. If that is the case, assign
1816 something else to @code{tagline}, as shown above.
1819 #(set! point-and-click line-column-location)
1822 This piece of Scheme code sets the Scheme variable
1823 @code{point-and-click} to the value @var{line-column-location} (which
1824 itself is a Scheme procedure).
1826 Editing input files can be quite complicated if you're working with
1827 large files: if you're digitizing existing music, you have to
1828 synchronize the .ly file, the sheet music on your lap and the sheet
1829 music on the screen. The point-and-click mechanism makes it easy to
1830 find the origin of an error in the LY file: when you view the file with
1831 Xdvi and click on a note, your editor will jump to the spot where that
1832 note was entered. For more information, see @ref{Point and click}.
1839 The @code{\score} blocks that follow in the file don't have
1840 @code{\paper} sections, so the settings of this block are substituted: A
1841 paper block at top level, i.e. not in a @code{\score} block sets the
1842 default page layout.
1851 The variable @code{linewidth} normally sets the length of the systems on
1852 the page. However, a negative value has a special meaning. If
1853 @code{linewidth} is less than 0, no line breaks are inserted into the
1854 score, and the spacing is set to natural length: a short phrase takes up
1855 little space, a longer phrase more space.
1860 \notes @{ c'4 d'4 @}
1863 In previous examples, notes were specified in relative octaves,
1864 i.e. each note was put in the octave that is closest to its
1865 predecessor. Besides relative, there is also absolute octave
1866 specification, which you get when you don't specify @code{\relative}. In
1867 this input mode, the central C is denoted by @code{c'}. Going down, you
1868 get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
1871 When you're copying music from existing sheet music, relative octaves
1872 are probably the easiest to use: it's less typing work and errors are
1873 easily spotted. However, if you write LilyPond input directly, either by
1874 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1882 The @code{\header} is normally at the top of the file, where it sets
1883 values for the rest of the file. If you want to typeset different pieces
1884 from one file (for example, if there are multiple movements, or if
1885 you're making an exercise book), you can put different @code{\score}
1886 blocks into the input file. ly2dvi will assemble all LilyPond output
1887 files into a big document. The contents of \header blocks specified
1888 within each score, are used for the titling of each movement.
1894 For example, the Opus number is put at the right, and the piece string
1895 will be at the left.
1899 @node A piano excerpt
1900 @section A piano excerpt
1902 Our fourth subject is a piece of piano music. The fragment in the
1903 input file is a piano reduction of the G major Sinfonia by Giovanni
1904 Battista Sammartini. It was composed around 1740. It's in the source
1905 package under the name @file{sammartini.ly}.
1908 \include "paper16.ly"
1910 stemDown = \property Voice.Stem \override #'direction = #-1
1911 stemUp = \property Voice.Stem \override #'direction = #1
1912 stemBoth = \property Voice.Stem \revert #'direction
1914 viola = \notes \relative c' \context Voice = viola {
1915 <c4-\f-\arpeggio g' c>
1921 oboes = \notes \relative c'' \context Voice = oboe {
1922 \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1923 \grace <e8( g> <d4 )f> <c2 e>
1924 \times 2/3 { <d8 \< f> <e g> <f a> }
1926 { \times 2/3 { a8 g c } \! c2 }
1927 \context Voice = oboeTwo {
1930 \property Voice.Stem \override #'direction = #-1
1932 \property Voice.Stem \revert #'direction
1938 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1939 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1940 [<c16( e> < )e8. g>] <c8 e,>
1943 hoomPah = \repeat unfold 8 \notes
1944 \transpose c' { \stemUp c8 \stemBoth \stemDown g'8 \stemBoth }
1946 bassvoices = \notes \relative c' {
1948 \autochange Staff \context Voice \hoomPah
1949 \translator Staff = down
1950 \stemDown [c8 c'8] r4
1952 < {\stemUp r2 <e4 c'> <c8 g'> }
1953 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
1957 \context PianoStaff \notes <
1958 \context Staff = up < \time 2/2
1962 \context Staff = down < \time 2/2 \clef bass
1969 linewidth = 15.0 \cm }
1973 If this looks like incomprehensible gibberish to you, you are right.
1974 This example has been doctored to have as many quirks as possible.
1976 As you can see, this example features multiple voices on one staff. To
1977 make room for those voices, their notes have to be stemmed in opposite
1980 Printed symbols are internally represented by so-called Graphical
1981 Objects (more colloquially: Grobs). These statements concern the
1982 grob called `Stem'. Each grob is described by a bunch of settings. These
1983 setting determine the fonts, offsets, sub-routines to be called on the
1984 grob, etc. The initial values of these settings are set in the Scheme
1985 file @file{scm/grob-description.scm}.
1989 stemDown = \property Voice.Stem \override #'direction = #-1
1992 Set a property for all Stem grobs in the current Voice:
1993 @code{direction} is set to @code{-1}, which encodes down. The setting
1994 remains in effect until it is reverted.
1998 \property Voice.Stem \revert #'direction
2001 Revert the to the previous setting. The effect of precisely one
2002 @code{\stemDown} or @code{\stemUp} is neutralized.
2005 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
2006 with some other commonly used formatting instructions, but to explain how
2007 it works, we wrote our own here. Of course, you should use predefined
2008 identifiers like these if possible: then you will be affected less by
2009 the implementation changes we occasionally make.
2013 viola = \notes \relative c' \context Voice = viola @{
2015 In this example, you can see multiple parts on a staff. Each part is
2016 associated with one notation context. This notation context handles
2017 stems and dynamics (among others). The type name of this context is
2018 @code{Voice}. For each part we have to make sure that there is
2019 precisely one @code{Voice} context, so we give it a unique name
2024 <c4-\f-\arpeggio g' c>
2026 The delimiters @code{<} and @code{>} are shorthands for
2027 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
2028 @code{<} and @code{>} is a chord.
2035 @code{\f} places a forte symbol under the chord. The forte applies to
2036 the whole chord, but the syntax requires that commands like forte and
2037 arpeggio are attached to a note, so here we attach them to the first
2040 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
2053 Relative octaves work a little differently with chords. The starting
2054 point for the note following a chord is the first note of the chord. So
2055 the @code{g} gets an octave up quote: it is a fifth above the starting
2056 note of the previous chord (the central C).
2062 @code{s} is a spacer rest. It does not print anything, but it does have
2063 the duration of a rest. It is useful for filling up voices that
2064 temporarily don't play. In this case, the viola doesn't come until one
2065 and a half measure later.
2069 oboes = \notes \relative c'' \context Voice = oboe @{
2071 Now comes a part for two oboes. They play homophonically, so we
2072 print the notes as one voice that makes chords. Again, we insure that
2073 these notes are indeed processed by precisely one context with
2077 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
2079 @code{\stemUp} is a reference to the @code{\property \override} command
2083 \grace <e8 g> < d4 f> <c2 e>
2085 @cindex @code{\grace}
2088 @code{\grace} introduces grace notes. It takes one argument, in this
2092 The slur started on the @code{e} of the chord
2093 will be attached to the next note.@footnote{LilyPond will squirm
2094 about unended Slurs. In this case, you can ignore the warning}.
2102 Tuplets are made with the @code{\times} keyword. It takes two
2103 arguments: a fraction and a piece of music. The duration of the piece
2104 of music is multiplied by the fraction. Triplets make notes occupy 2/3
2105 of their notated duration, so in this case the fraction is 2/3.
2108 @{ <d8 \< f> <e g> <f a> @}
2110 The piece of music to be `tripletted' is sequential music containing
2111 three notes. On the first chord, a crescendo is started with
2112 @code{\<}. To be precise, the crescendo start is syntactically attached
2113 to the preceding note, the @code{d}.
2123 At this point, the homophonic music splits into two rhythmically
2124 different parts. We can't use a sequence of chords to enter this, so
2125 we make a `chord' of sequences to do it. We start with the upper
2126 voice, which continues with upward stems:
2129 @{ \times 2/3 @{ a8 g c @} \! c2 @}
2134 The crescendo is ended at the half note by the escaped exclamation
2138 \context Voice = oboeTwo @{
2141 We can't share stems with the other voice, so we have to create a new
2142 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
2143 it from the other context. Stems go down in this voice.
2148 @cindex Grace context
2149 When a grace section is processed, a @code{Grace} context is
2150 created. This context acts like a miniature score of its own. It has
2151 its own time bookkeeping, and you can make notes, beams, slurs
2152 etc. Here we fiddle with a property and make a beam. The argument of
2153 @code{\grace} is sequential music.
2157 \property Voice.Stem \override #'direction = #-1
2159 \property Voice.Stem \revert #'direction
2162 Normally, grace notes are always stem up, but in this case, the upper
2163 voice interferes, so we set the stems down here.
2165 As far as relative mode is concerned, the previous note is the
2166 @code{c'''2} of the upper voice, so we have to go an octave down for
2174 This ends the two-part section.
2178 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
2183 @code{\stemBoth} ends the forced stem directions. From here, stems are
2184 positioned as if it were single part music.
2186 The bass has a little hoom-pah melody to demonstrate parts switching
2187 between staves. Since it is repetitive, we use repeats:
2190 hoomPah = \repeat unfold 8
2192 @cindex unfolded @code{\repeat}
2193 The unfolded repeat prints the notes in its argument as if they were
2194 written out in full eight times.
2197 \notes \transpose c' @{
2200 @cindex relative mode and transposing
2202 Transposing can be done with @code{\transpose}, which takes two arguments.
2203 The first specifies what central C should be transposed to. The second
2204 is the to-be-transposed music. As you can see, in this case, the
2205 transposition has no effect, as central C stays at central C.
2207 The purpose of this no-op is circumventing relative mode. Relative mode
2208 can not be used together with transposition, so @code{\relative} will
2209 leave the contents of @code{\hoomPah} alone. We can use it without
2210 having to worry about getting the motive in a wrong octave.
2213 bassvoices = \notes \relative c' @{
2215 \autochange Staff \hoomPah \context Voice
2217 @cindex staff switch, automatic
2218 @cindex cross staff voice, automatic
2219 @cindex @code{\autochange}
2221 Voices can switch between staves. The easiest way to get this, is to use
2222 @code{\autochange}. This command looks at the pitch of each note, and if
2223 necessary, will cross to the other staff. For this to work, the two
2224 staves must be called @code{"up"} and @code{"down"}.
2227 \translator Staff = down
2229 @cindex staff switch
2230 @cindex cross staff voice
2231 We want the remaining part of this melody on the lower staff, so we do a
2232 manual staff switch here.
2237 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
2241 After skipping some lines, we see @code{~}. This mark makes ties. Note
2242 that ties and slurs are different things. A tie can only connect two
2243 note heads of the same pitch, whereas a slur can connect many chords
2250 A special context is needed to get cross staff beaming right. This
2251 context is called @code{PianoStaff}.
2254 \context Staff = bottom < \time 2/2 \clef bass
2256 The bottom staff must have a different clef.
2261 To make some more room on the line, the first (in this case the only)
2262 line is not indented. The line still looks very cramped, but that is due
2263 to the page layout of this document.
2269 * font-size, multi-stanza.
2271 * Simple part combining in a Hymn
2275 @node Fine tuning a piece
2276 @section Fine tuning a piece
2280 @lilypondfile{brahms-original.ly}
2282 @lilypondfile{brahms-tweaked.ly}
2286 @node An orchestral score
2287 @section An orchestral score
2291 * Extracting an individual part::
2295 Our last two examples show a way to setup the music for an orchestral
2296 score. When typesetting a piece for several instruments, you'll want to
2297 create a conductor's full score, alongside several individual parts.
2299 LilyPond is well suited for this task. We will declare the music for
2300 each instrument individually, giving the music of each instrument its
2301 own name. These pieces of music are then combined in different
2302 @code{\score} blocks to produce different combinations of the score.
2304 This orchestral score example consists of three input files. In the
2305 first file, @file{os-music.ly}, we define the music for all instruments.
2306 This file will be used both for producing the score and the separate
2309 If you were to run LilyPond on this file, no printable output would be
2315 title = "Zo, goed lieverd?"
2316 subtitle = "How's, this babe?"
2325 Key = \notes \key as \major
2326 flautoI = \notes\relative c'' @{
2328 bes as bes as bes as bes as
2330 flautoII = \notes\relative c'' @{
2331 as8 bes as bes R1 d4 ~ d
2333 tromboI = \notes\relative c'' @{
2334 c4. c8 c8 c4. es4 r as, r
2336 tromboII = \notes\relative c'' @{
2337 as4. as8 as8 as4. R1*1/2 as4 es'
2339 timpani = \notes\relative c, @{
2340 \times 2/3 @{ f4 f f @}
2341 \times 4/5 @{ as8 as as as as @}
2344 corno = \notes\relative c' @{
2345 bes4 d f, bes d f, bes d
2349 We will not go through the input line by line, but only indicate and
2350 explain the new elements.
2357 \skip 2*4 \bar "|.";
2361 Declare setting to be used globally. The @code{\skip} command produces
2362 no output, but moves forward in time: in this case, the duration of a
2363 half note (@code{2}), and that four times (@code{*4}). This brings us
2364 to the end of the piece, and we can set the end bar.
2368 Key = \notes \key as \major
2370 Declare the key signature of the piece and assign it to the identifier
2371 @var{Key}. Later on, we'll use @code{\Key} for all staves except those
2372 for transposing instruments.
2374 @node The full score
2375 @subsection The full score
2378 The second file, @file{os-score.ly} reads the definitions of the first
2379 (@file{os-music.ly}), and defines the @code{\score} block for the full
2385 \include "os-music.ly"
2386 \include "paper13.ly"
2388 #(set! point-and-click line-column-location)
2389 #(define text-flat '((font-relative-size . -2)
2390 (music "accidentals--1")))
2395 \property Score.BarNumber \override #'padding = #3
2396 \context StaffGroup = woodwind <
2397 \context Staff = flauti <
2398 \property Staff.midiInstrument = #"flute"
2399 \property Staff.instrument = "2 Flauti"
2400 \property Staff.instr = "Fl."
2402 \context Voice=one @{ \voiceOne \flautoI @}
2403 \context Voice=two @{ \voiceTwo \flautoII @}
2406 \context StaffGroup = timpani <
2407 \context Staff = timpani <
2408 \property Staff.midiInstrument = #"timpani"
2409 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2410 \property Staff.instr = #"Timp."
2416 \context StaffGroup = brass <
2417 \context Staff = trombe <
2418 \property Staff.midiInstrument = #"trumpet"
2419 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2420 \property Staff.instr = #`(lines "Tbe." "(C)")
2422 \context Voice=one \partcombine Voice
2423 \context Thread=one \tromboI
2424 \context Thread=two \tromboII
2426 \context Staff = corni <
2427 \property Staff.midiInstrument = #"french horn"
2428 \property Staff.instrument = #`(lines "Corno"
2429 (columns "(E" ,text-flat ")"))
2430 \property Staff.instr = #`(lines "Cor."
2431 (columns "(E" ,text-flat ")"))
2432 \property Staff.transposing = #3
2433 \notes \key bes \major
2434 \context Voice=one \corno
2439 indent = 15 * \staffspace
2440 linewidth = 60 * \staffspace
2441 textheight = 90 * \staffspace
2443 \HaraKiriStaffContext
2452 @center @strong{Zo, goed lieverd?}
2454 @center How's, this babe?
2462 @lilypondfile{os-score.ly}
2466 \include "os-music.ly"
2468 First, we need to include the music definitions we made in
2473 #(set! point-and-click line-column-location)
2475 In a large orchestral score like this you're bound to make some small
2476 mistakes, so we enable point and click (See @ref{Point and click})
2481 #(define text-flat '((font-relative-size . -2)
2482 (music "accidentals--1")))
2485 When naming the tuning of the french horn, we'll need a piece of text
2486 with a flat sign. LilyPond has a mechanism for font selection and
2487 kerning called Scheme markup text (See @ref{Text markup}). The flat
2488 sign is taken from the music font, and its name is @code{accidentals--1}
2489 (The natural sign is called @code{accidentals-0}). The default font is
2490 too big for text, so we select a relative size of @code{-2}.
2497 Of course, all staves are simultaneous and use the same global settings.
2501 \property Score.BarNumber \override #'padding = #3
2503 LilyPond prints bar numbers at the start of each line, but
2504 unfortunately, they end up a bit too close to the staff in this example.
2505 A bar number internally is a Grob called @var{BarNumber}. BarNumber
2506 Grobs can be manipulated through their @var{side-position-interface}. One
2507 of the properties of a @var{side-position-interface} that can be tweaked
2508 is the @var{padding}: the amount of extra space that is put between this
2509 Grob and other Grobs. We set the padding to three staff spaces.
2511 You can find information on all these kind of properties in LilyPond's
2512 automatically generated documentation in
2514 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
2517 the online documentation.
2522 \context StaffGroup = woodwind <
2523 \context Staff = flauti <
2525 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2526 hold one or more @code{Staff}'s, and will print a big bracket at the
2527 left of the score. Start a new staff group for the woodwind section
2528 (just the flutes in this case). Immediately after that, we start the
2529 staff for the two flutes, that also play simultaneously.
2533 \property Staff.midiInstrument = #"flute"
2535 Specify the instrument for MIDI output (see @ref{MIDI instrument
2540 \property Staff.instrument = "2 Flauti"
2541 \property Staff.instr = "Fl."
2543 And define the instrument names to be printed in the margin,
2544 @code{instrument} for the first line of the score, @code{instr} for the
2551 The flutes play in the default key.
2555 \context Voice=one @{ \voiceOne \flautoI @}
2556 \context Voice=two @{ \voiceTwo \flautoII @}
2558 Last come the actual flute parts. Remember that we're still in
2559 simultaneous mode. We name both voices differently, so that LilyPond
2560 will actually create two Voice contexts. The flute parts are simple, so
2561 we specify manually which voice is which: @code{\voiceOne} forces the
2562 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2570 Close the flutes staff and woodwind staff group.
2574 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2576 The timpani staff only shows a new piece of scheme markup, it sets two
2581 \context Voice=one \partcombine Voice
2582 \context Thread=one \tromboI
2583 \context Thread=two \tromboII
2585 You have seen the notation contexts Staff and Voice, but here's a new
2586 one: Thread. One or more Threads can be part of a Voice. The Thread
2587 takes care of note heads and rests, the Voice combine note heads onto a
2590 For the trumpets we use the automatic part combiner (see @ref{Automatic
2591 part combining}) to combine the two simultaneous trumpet parts onto the
2592 trumpet staff. Each trumpet gets its own Thread context, which must be
2593 named @code{one} and @code{two}). The part combiner makes these two
2594 threads share a Voice when they're similar, and splits the threads up
2595 when they're different.
2599 \property Staff.instrument = #`(lines "Corno"
2600 (columns "(E" ,text-flat ")"))
2602 The french horn has the most complex scheme markup name, made up of two
2603 lines of text. The second line has three elements (columns), the @code{(E},
2604 the flat sign @code{text-flat} that we defined before and a final @code{")"}.
2605 Note that we use a backquote instead of an ordinary quote at the
2606 beginning of the Scheme expression to be able to access the
2607 @code{text-flat} identifier, `unquoting' it with a @code{,}.
2611 \property Staff.transposing = #3
2613 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
2614 transpose this staff by three steps.
2616 Note how we can choose different tuning for entering, printing and
2617 playing, using @code{\transpose} and the MIDI Staff property
2622 \notes \key bes \major
2624 Therefore, it has a different key.
2628 indent = 15 * \staffspace
2629 linewidth = 60 * \staffspace
2631 We specify a big indent for the first line and a small linewidth for this
2636 Usually, LilyPond's predefined setup of notation contexts (Thread,
2637 Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
2638 want a different type of Staff context.
2642 \HaraKiriStaffContext
2646 In orchestral scores, it often happens that one instrument has only
2647 rests during one line of the score. The @code{HaraKiriStaffContext} can
2648 be used as a regular @code{StaffContext} drop-in and will take care of
2649 the automatic removing of empty staves.
2651 @node Extracting an individual part
2652 @subsection Extracting an individual part
2654 The third file, @file{os-flute-2.ly} also reads the definitions of the
2655 first (@file{os-music.ly}), and defines the @code{\score} block for the
2659 \include "os-music.ly"
2660 \include "paper16.ly"
2664 \property Score.skipBars = ##t
2665 \property Staff.midiInstrument = #"flute"
2671 instrument = "Flauto II"
2674 linewidth = 80 * \staffspace
2675 textheight = 200 * \staffspace
2683 @center @strong{Zo, goed lieverd?}
2685 @center How's, this babe?
2686 @center @emph{Flauto II}
2693 @lilypondfile{os-flute-2.ly}
2696 Because we separated the music definitions from the @code{\score}
2697 instantiations, we can easily define a second score with the music of
2698 the second flute. This then is the part for the second flute player.
2699 Of course, we make separate parts for all individual instruments.
2705 In this individual part the second flute has a whole staff for itself,
2706 so we don't want to force stem or tie directions.
2711 instrument = "Flauto II"
2714 The @code{\header} definitions were also read from @file{os-music.ly},
2715 but we need to set the instrument for this particular score.
2719 \property Score.skipBars = ##t
2721 In the conductor's full score, all bars with rests are printed, but for
2722 the individual parts, we want to contract pieces of consecutive empty
2723 bars. LilyPond will do this if Score's @var{skipBars} property to
2727 @node Other ways to run LilyPond
2728 @section Other ways to run LilyPond
2730 Until now, you have been using @file{ly2dvi} to invoke LilyPond.
2731 There are three other routes. Firstly, there is a script called
2732 @code{lilypond-book}, that allows you to freely mix LilyPond input with
2733 Texinfo or \LaTeX input. For example, this manual was written using
2734 @code{lilypond-book}. It is discussed below and in @ref{lilypond-book}.
2737 Secondly, you can generate PostScript directly. This is useful if you
2738 can not or do not want to run @TeX{} on your system. To obtain direct
2739 PostScript output, invoke LilyPond as follows:
2740 @cindex PostScript output
2742 lilypond -f ps test.ly
2744 You have to set some environment variables to view or print this output.
2745 More information can be found in @ref{Invoking LilyPond}. Since the
2746 direct Postscript generation has some problems, it is recommended
2747 to use @file{ly2dvi}.
2750 Thirdly, if you want to do special things with your output, you can run
2751 invoke LilyPond directly:
2755 to produce plain @TeX{} output. Note that La@TeX{} will not work on the
2756 resulting @file{test.tex}. You must run plain @TeX{} on it.
2764 @node Integrating text and music
2765 @section Integrating text and music
2767 Sometimes, you might want to use music examples in a text that you are
2768 writing. For example, if you are writing a musicological treatise, a
2769 songbook, or (like us) the LilyPond manual. You can make such texts by
2770 hand, simply by importing a PostScript figure into your wordprocessor.
2771 However, there is a also an automated procedure:
2773 If you use La@TeX{} or texinfo, you can mix text and LilyPond code. A
2774 script called @code{lilypond-book} will extract the music fragments, run
2775 LilyPond on them, and put back the resulting notation. lilypond-book is
2776 described fully in @ref{lilypond-book}, but here we show a small
2777 example. Since the example also contains explanatory text, we won't
2778 comment on the contents.
2781 \documentclass[a4paper]@{article@}
2784 In a lilypond-book document, you can freely mix music and text. For
2787 \score @{ \notes \relative c' @{
2788 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2791 Notice that the music line length matches the margin settings of the
2794 If you have no \verb+\score+ block in the fragment,
2795 \texttt@{lilypond-book@} will supply one:
2801 In the example you see here, a number of things happened: a
2802 \verb+\score+ block was added, and the line width was set to natural
2803 length. You can specify many more options using \LaTeX style options
2806 \begin[verbatim,11pt,singleline,
2807 fragment,relative,intertext="hi there!"]@{lilypond@}
2811 \texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
2812 the default music size, \texttt@{fragment@} adds a score block,
2813 \texttt@{relative@} uses relative mode for the fragment, and
2814 \texttt@{intertext@} specifies what to print between the
2815 \texttt@{verbatim@} code and the music.
2817 If you include large examples into the text, it may be more convenient
2818 to put the example in a separate file:
2820 \lilypondfile[printfilename]@{sammartini.ly@}
2822 The \texttt@{printfilename@} option adds the file name to the output.
2827 Under Unix, you can view the results as follows.
2830 $ lilypond-book --outdir=out/ lilbook.tex
2831 lilypond-book (GNU LilyPond) 1.3.146
2832 Reading `input/tutorial/lilbook.tex'
2833 Reading `input/tutorial/sammartini.ly'
2834 @var{lots of stuff deleted}
2835 Writing `out/lilbook.latex'
2837 $ latex lilbook.latex
2838 @var{lots of stuff deleted}
2842 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2843 and running latex creates a lot of temporary files, and you wouldn't want
2844 those to clutter up your working directory. Hence, we have them created
2845 in a separate subdirectory.
2847 The result more or less looks like this:
2851 In a lilypond-book document, you can freely mix music and text. For
2854 \score { \notes \relative c' {
2855 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2858 Notice that the music line length matches the margin settings of the
2861 If you have no @code{\score} block in the fragment,
2862 @code{lilypond-book} will supply one:
2868 In the example you see here, a number of things happened: a
2869 @code{\score} block was added, and the line width was set to natural
2870 length. You can specify many more options using La@TeX{} style options
2873 @lilypond[verbatim,11pt,singleline,
2874 fragment,relative,intertext="hi there!"]
2878 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2879 the default music size, @code{fragment} adds a score block,
2880 @code{relative} uses relative mode for the fragment, and
2881 @code{intertext} specifies what to print between the
2882 @code{verbatim} code and the music.
2884 If you include large examples into the text, it may be more convenient
2885 to put the example in a separate file:
2887 @lilypondfile[printfilename]{sammartini.ly}
2889 The @code{printfilename} option adds the file name to the output.
2890 @node End of tutorial
2891 @section End of tutorial
2893 That's all folks. From here, you can either try fiddling with input
2894 files, or you can read the reference manual. You can find more example
2895 files in @file{input} and @file{input/test}. You can also look at some
2896 real music. The website @uref{http://www.mutopiaproject.org} has many
2897 examples of real music typeset by LilyPond.
2905 this should be on mutopia website.
2910 @c waar deze info? is uiteindelijk wel handig, schat ik.
2913 If you have a big music project, or just a lot of LilyPond input files,
2914 all generated output from LilyPond, @TeX{} and metafont will clutter
2915 your working directory. LilyPond comes with a one-size-fits-all
2916 pre-cooked makefile that helps you manage producing output. It will
2917 produce all output in the directory @file{out} , generate and track
2918 dependencies. Also, it helps in preparing your submission to @ref{Mutopia
2925 cp /usr/share/lilypond/make/ly.make GNUmakefile
2926 cp /usr/share/doc/lilypond/examples/input/tutorial/minuet.ly .
2929 Generated out/minuet.ps for target minuet.
2932 Type @samp{make help} to see possible targets.
2935 @file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
2941 [TODO: rewrite completely.]
2944 * Songs with additional verses::