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 to make small, very simple pieces of
48 music in LilyPond. If you have not seen LilyPond input files before,
49 this section is for you. The contents of this section are summarized
50 in the 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
59 then the result looks like this:
62 \property Score.timing = ##f
63 \property Staff.TimeSignature = \turnOff
64 \transpose c'' { c d e f g a b }
69 We continue showing LilyPond input like we did previously: first a
70 snippet of input, then the resulting output.
72 The length of a note is specified by adding a number, ``@code{1}'' for a
73 whole note, ``@code{2}'' for a half note, and so on:
80 @c missing clef seems to raise more questions than actual pitch of notes,
81 @c as these are snippets anyway
83 \property Score.timing = ##f
84 \property Staff.TimeSignature = \turnOff
85 \property Staff.autoBeaming = ##f
86 %\property Staff.Clef = \turnOff
87 \transpose c'' { a1 a2 a4 a16 a32 }
93 If you don't specify a duration, the previous one is used:
99 @c missing clef seems to raise more questions than actual pitch of notes,
100 @c as these are snippets anyway
102 \property Score.timing = ##f
103 \property Staff.TimeSignature = \turnOff
104 %\property Staff.Clef = \turnOff
105 \transpose c'' { a a a2 a }
111 A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
112 (@texiflat{}) by adding ``@code{es}'':
120 \property Score.timing = ##f
121 \property Staff.TimeSignature = \turnOff
122 \transpose c'' { cis1 ees fisis aeses }
128 Add a dot ``@code{.}'' after the duration to get a dotted note:
134 @c missing clef seems to raise more questions than actual pitch of notes,
135 @c as these are snippets anyway
137 \property Score.timing = ##f
138 \property Staff.TimeSignature \set #'transparent = ##t
139 %\property Staff.Clef = \turnOff
140 \transpose c'' { a2. a4 a8. a16 }
146 The meter (or time signature) can be set with the @code{\time} command:
155 @c a clef here may lead to confusion
157 \property Staff.Clef \set #'transparent = ##t
168 The clef can be set using the ``@code{\clef}'' command:
170 @c what is more common name treble or violin?
171 @c in Dutch, its violin.
181 \property Score.timing = ##f
182 \property Staff.TimeSignature = \turnOff
195 From these commands and notes, a piece of music can be formed. A piece
196 of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
197 LilyPond then knows that music follows (and not lyrics, for example):
211 At this point, the piece of music is ready to be printed. This is done
212 by combining the music with a printing command.
214 The printing command is the so-called ``@code{\paper}'' block. You
215 will see later that the \paper block is necessary to customize all
216 kinds of printing specifics. The music and the \paper block are
217 combined by enclosing them in ``@code{\score @{ ... @}}''. This is
218 what a full LilyPond source file looks like:
241 \paper { linewidth = 60 * \staffspace }
248 We continue with the introduction of the remaining musical constructs.
250 @c maybe legend here?
252 Normal rests are entered just like notes with the name ``@code{r}'':
260 \property Score.timing = ##f
261 \property Staff.Clef = \turnOff
262 \property Staff.TimeSignature = \turnOff
269 @c Tim wants to move this quotes example just before the: quotes-don't-work
270 @c score, but we'd need to remove quotes from the other two (key and
273 @c better to have this just before the `octaves are bad' snipped
274 @c but we'd need to remove the ', from \key and tie
275 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
276 the note name, to lower a note one octave, add a ``low quote'' @code{,}
277 (a comma). The central C is @code{c'}:
281 c'4 c'' c''' \clef bass c c,
285 \property Score.timing = ##f
286 \property Staff.TimeSignature = \turnOff
287 c'4 c'' c''' \clef bass c c,
292 A tie is created by entering a tilde ``@code{~}'' between the notes to
293 be tied. A tie between two notes means that the second note must not be
294 played separately, but just makes the first note sound longer:
297 @lilypond[fragment,verbatim]
303 The key signature is set with the command ``@code{\key}'':
313 \property Staff.TimeSignature = \turnOff
322 @c bit on the long/complex/scary taste
323 @c cheating a bit: two lines makes for a friendlier look
324 This example shows notes, ties, octave marks, and rests in action.
325 Don't worry about all the quotes.
334 r4 r8 d''8 cis''4 e''
336 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
349 r4 r8 d''8 cis''4 e''
351 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
354 \paper { linewidth = 50*\staffspace }
360 There are some interesting points to note in this example. Firstly,
361 accidentals (sharps and flats) don't have to be marked explicitly: you
362 just enter the note name, and LilyPond determines whether or not to
363 print an accidental. Secondly, bar lines and beams are drawn
364 automatically. Thirdly, LilyPond calculates line breaks for you; it
365 doesn't matter where you make new lines in the source file.
367 The example also indicates that a piece of music written in a high
368 register needs lots of quotes. This makes the input a bit unreadable,
369 and is therefore also a potential source of errors.
373 The solution is to use ``relative octave'' mode. In practice, most
374 music is entered using this mode.
376 To use relative mode, add @code{\relative} before the piece of music.
377 You must also give a note from which relative starts, in this case
380 @c In relative octave mode, quotes are used to mark large jumps in the
381 @c melody. Without any quotes or commas, the interval between a note and
382 @c its predecessor is assumed to be a fourth or less. Quotes and commas
383 @c add octaves in up and down direction.
385 If you type no octaviation quotes, relative mode chooses the note that
386 is closest to the previous one, which is often just the one you need.
387 @c don't use commas or quotes in this sentence
388 For example: @code{c f} goes up; @code{c g} goes down:
398 \property Score.timing = ##f
399 \property Staff.TimeSignature = \turnOff
407 @c needed better, maybe even redundant explanation
408 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
409 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
410 You can make a large interval by adding octaviation quotes. Note that
411 quotes or commas do not determine the absolute height of a note;
412 the height of a note is relative to the previous one.
413 @c don't use commas or quotes in this sentence
414 For example: @code{c f,} goes down; @code{f, f} are both the same;
415 @code{c c'} are the same; and @code{c g'} goes up:
425 \property Score.timing = ##f
426 \property Staff.TimeSignature = \turnOff
434 A slur is drawn across many notes, and indicates bound articulation
435 (legato). The starting note and ending note are marked with a
436 ``@code{(}'' and a ``@code{)}'' respectively:
439 @lilypond[fragment,relative 1, verbatim]
440 d4( )c16( cis d e c cis d )e( )d4
445 If you need two slurs at the same time (one for articulation, one for
446 phrasing), you can also make a phrasing slur with @code{\(} and
451 @lilypond[fragment,relative 1, verbatim]
452 a8(\( ais b ) c cis2 b'2 a4 cis, \) c
457 Beams are drawn automatically, but if you don't like the choices, you
458 can enter beams by hand. Surround the notes to be grouped with @code{[}
461 @lilypond[fragment,relative 1, verbatim]
467 To print more than one staff, each piece of music that makes up a staff
468 is marked by adding @code{\context Staff} before it. These
469 @code{Staff}'s can be grouped inside @code{<} and @code{>}, as is
473 @lilypond[fragment,verbatim]
475 \context Staff = staffA { \clef violin c'' }
476 \context Staff = staffB { \clef bass c }
481 In this example, @code{staffA} and @code{staffB} are names that are
482 given to the staves. For now, it doesn't matter what names you give, as
483 long as each staff has a unique name.
487 We can typeset a melody with two staves now:
493 < \context Staff = staffA {
496 \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
498 \context Staff = staffB {
509 Notice that the time signature is specified in one melody staff only
510 (the top staff), but is printed on both. LilyPond knows that the time
511 signature should be the same for all staves.
515 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
517 @lilypond[verbatim,relative 1]
523 Dynamic signs are made by adding the markings to the note:
525 @lilypond[verbatim,relative 1]
531 Crescendi are started with the commands @code{\<} and @code{\>}. The
532 command @code{\!} finishes a crescendo on the following note.
534 @lilypond[verbatim,relative 1]
535 c2\< \!c2-\ff \>c2 \!c2
540 Chords can be made by surrounding notes with @code{<} and @code{>}:
542 @lilypond[relative 0, fragment,verbatim]
550 @c hmm, te losjes, iig
551 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
552 happens at the same time, like in chords, or (like in the two-staff
553 example above) in a bunch of stacked staves.
556 Of course, you can combine beams and ties with chords. Notice that
557 beam and tie markings must be placed outside the chord markers:
559 @lilypond[relative 0, fragment,verbatim]
560 r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
564 When you want to combine chords with slurs and dynamics, technical
565 detail crops up: you have type these commands next to the notes, which
566 means that they have to be inside the @code{< >}:
569 @lilypond[relative 0, fragment,verbatim]
570 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
575 There is one golden rule that you should keep in mind when writing
578 @strong{DO NOT START A PIECE WITH A CHORD}
580 Of course, it is a allowed, but the result might not be what you expect:
582 @lilypond[verbatim,singleline]
583 \score { \notes <c'2 e'2> }
588 Of course, it is possible to typeset pieces that start with a chord,
589 but you must make explicit that the notes of chord are to be put on
590 the same staff, in the same voice. This is done by specifying
591 @code{\context Staff} for the notes:
594 @lilypond[verbatim,singleline]
595 \score { \notes \context Voice <c'2 e'2> }
604 [TODO add some more here
615 This is the end of the simple tutorial. You know the basic ingredients
616 of a music file, so this is the right moment to try your at hand at
617 doing it yourself: try to type some simple examples, and experiment a
620 When you're comfortable with the basics, then you might want to read the
621 rest of this chapter. It also a manual in tutorial-style, but it is much
622 more in-depth. It will also be very intimidating if you're not familiar
623 with the basics. It deals with some of the more advanced features of
624 LilyPond. Topics include lyrics, chords, orchestral scores and parts,
625 fine tuning output, polyphonic music, and integrating text and music.
628 @c refer to this section
633 @c need texinfo-4.0a or later for this
636 @c both Tim and my father came independently with a request for a
637 @c `legend' like this.
639 @c what should be in it?
644 @multitable @columnfractions .20 .20 .40
647 @item @code{1 2 8 16}
650 @lilypond[fragment, relative 1]
655 @tab augmentation dots
657 @lilypond[fragment, relative 1]
661 @item @code{c d e f g a b }
664 @lilypond[fragment, relative 1]
671 @lilypond[fragment, relative 2]
675 @item @code{-. -^ ->}
676 @tab articulations (1)
678 @lilypond[fragment, relative 2]
683 @item @code{-\trill -\fermata}
684 @tab articulations (2)
686 @lilypond[fragment, relative 2]
691 @item @code{\time 3/4 \time 6/8 \time 4/4 }
695 \property Staff.Clef \set #'transparent = ##t
705 @item @code{\clef treble \clef bass }
709 \property Staff.TimeSignature \set #'transparent = ##t
717 @item @code{\sfz \mf }
720 @lilypond[fragment,relative 1]
727 @lilypond[fragment, relative 1]
728 \property Score.timing = ##f
729 \property Staff.TimeSignature = \turnOff
730 \property Staff.autoBeaming = ##f
731 \property Staff.Clef = \turnOff
738 @lilypond[fragment, relative 1]
739 \property Score.timing = ##f
740 \property Staff.TimeSignature = \turnOff
741 \property Staff.autoBeaming = ##f
742 \property Staff.Clef = \turnOff
749 @lilypond[fragment, relative 1]
750 \property Score.timing = ##f
751 \property Staff.TimeSignature = \turnOff
752 \property Staff.autoBeaming = ##f
753 \property Staff.Clef = \turnOff
759 @lilypond[fragment, relative 1]
760 \property Score.timing = ##f
761 \property Staff.TimeSignature = \turnOff
762 \property Staff.autoBeaming = ##f
763 \property Staff.Clef = \turnOff
770 @lilypond[fragment, relative 1]
771 \property Score.timing = ##f
772 \property Staff.TimeSignature = \turnOff
773 \property Staff.autoBeaming = ##f
774 \property Staff.Clef = \turnOff
781 @lilypond[fragment, relative 1]
782 \property Score.timing = ##f
783 \property Staff.TimeSignature = \turnOff
784 \property Staff.autoBeaming = ##f
785 \property Staff.Clef = \turnOff
786 \context Voice { <a c> }
792 @lilypond[fragment, relative 1]
793 \property Score.timing = ##f
794 \property Staff.TimeSignature = \turnOff
795 \property Staff.autoBeaming = ##f
796 \property Staff.Clef = \turnOff
803 @lilypond[fragment, relative 1]
804 \property Score.timing = ##f
805 \property Staff.TimeSignature = \turnOff
806 \property Staff.autoBeaming = ##f
807 \property Staff.Clef = \turnOff
816 @node Running LilyPond
817 @section Running LilyPond
819 In the last section, we explained what kind of things you could enter
820 in a lilypond file. In this section we explain how to run LilyPond,
821 and how view or print the output. If you have not used LilyPond
822 before, want to test your setup of LilyPond, or try to run an example
823 file yourself, then read this section. The instructions that follow
824 are for running LilyPond on Unix-like systems. Some additional
825 instructions for running LilyPond on Windows are given at the end of
828 You begin with opening a terminal window, and start up a text editor.
829 For example, open an xterm and execute @code{joe}. In your text editor,
830 enter the following input, and save the file as @file{test.ly}:
835 \notes @{ c'4 e' g' @}
842 @c now this is weird, running ly2dvi to run LilyPond
843 @c (therefore name change proposal)
845 LilyPond is the program that computes the sheet music. All other
846 things, such as adding titles, page breaking and other page layout,
847 are done by a small wrapper program called
848 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
849 then adds the titling and page layout instructions. To process
850 @file{test.ly} with ly2dvi, proceed as follows:
858 You will see the following on your screen:
863 Now processing: `/home/fred/ly/test.ly'
865 Interpreting music...[1]
866 @emph{ ... more interesting stuff ... }
867 PS output to `test.ps'...
868 DVI output to `test.dvi'...
872 @cindex Viewing music
875 The results of the ly2dvi run are two files, @file{test.dvi} and
876 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
877 You can view the PS file using the program ghostview. If a version of
878 ghostview is installed on your system, one of these commands will
879 produce a window with some music notation on your screen:
889 If you are satisfied with the looks of the music displayed on your
890 screen, you can print the PS file by clicking File/Print inside
893 The DVI file (@file{test.dvi}) contains the same sheet music in a
894 different format. DVI files are more easily processed by the computer,
895 so viewing them usually is quicker. Execute @code{xdvi test.dvi}
896 to view the DVI file.
898 If your DVI viewer does not have a "Print" button, you can print the
899 file by executing @code{lpr test.ps}.
901 @c volgende alinea schrappen?
903 If you can't get the examples to print, then you should look into
904 installing and configuring ghostscript. Refer to GhostScript's website
905 at @uref{http://www.ghostscript.com}.
909 @cindex Printing output
912 @unnumberedsubsec Windows users
913 Windows users start the terminal by clicking on the LilyPond or Cygwin
914 icon. Notepad is sufficient for editing the LilyPond file. Viewing
915 the PS file can be done with:
918 @code{gsview32 test.ps}
921 You can also print from the command line by executing:
924 @code{gsview32 /s test.ps}
929 @node The first real tune
930 @section The first real tune
933 The rest of this tutorial will demonstrate how to use Lilypond by
934 presenting examples of input along with resulting output. We will use
935 English terms for notation. In case you are not familiar with those,
936 you may consult the glossary that is distributed with LilyPond.
938 The examples discussed are included in the distribution, in the
939 subdirectory @file{input/tutorial/}@footnote{When we refer to filenames,
940 they are relative to the top directory of the source package. }
942 To demonstrate what LilyPond input looks like, we start off with a
943 full-fledged, yet simple example. It is a convoluted version
944 of the famous minuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
945 is included in the distribution as @file{minuet.ly}.
946 @cindex Bach, Johann Sebastian
949 % all text after a percent sign is a comment
950 % and is ignored by LilyPond
951 \include "paper16.ly"
954 \relative c'' \sequential {
959 d4 g,8 a b c d4 g, g |
960 e'4 c8 d e fis g4 g, g |
961 c4 d8( )c b a( )b4 c8 b a g |
962 a4 [b8 a] [g fis] g2. |
967 g4 e8 fis g d cis4 b8 cis a4 |
968 a8-. b-. cis-. d-. e-. fis-.
975 % standard settings are too big and wide for a book
982 We will analyse the input, line by line.
985 % all text after a percent sign is a comment
986 % and is ignored by LilyPond
988 Percent signs introduce comments: everything after a percent sign is
989 ignored. You can use this If you want to write down mental notes to
990 yourself in a file, then you can enter preceded with a @code{%} sign.
991 These lines are called comments. If you have long winded mental notes,
992 you can make comments that span several lines by enclosing text in
993 @code{%@{} and @code{%@}}.
995 @cindex block comment
1000 \include "paper16.ly"
1003 @cindex @code{\include}
1004 @cindex point, printer's
1005 @cindex staff size, setting
1006 @cindex font size, setting
1008 By default, LilyPond will typeset the music in a size such that each
1009 staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output
1010 (16 point staff height), so we must import the settings for that size,
1018 Music is printed by combining a piece of music with directions for
1019 outputting it. This combination is formed in the @code{\score} block.
1026 Prepare LilyPond for accepting notes.
1027 @cindex octaves, choosing
1036 @c removed duplicate introduction to octave marks /MB
1037 @c Shorten even more?
1039 @c As we will see, each note is described by its note name, duration,
1040 @c octave and possibly a chromatic alteration. In this setup, the octave
1041 @c is indicated by using high quotes (@code{'}) and ``lowered quotes''
1042 @c (commas: @code{,}). The central C is denoted by @code{c'}. The C one
1043 @c octave higher is @code{c''}. One and two octaves below the central C is
1044 @c denoted by @code{c} and @code{c,} respectively.
1046 Even though a piece of music often spans a range of several octaves,
1047 often melodies move in small intervals. Such melodies can be entered
1048 easily using @code{\relative}. In this ``relative octave mode'',
1049 octaves of notes without quotes are chosen such that a note is as
1050 close as possible (graphically, on the staff) to the preceding note.
1051 If you add a high-quote an extra octave is added. A lowered quote (a
1052 comma) will subtract an extra octave.
1054 Absolute starting pitch for this relative mode is given as the
1055 argument to @code{\relative}. In this case it is the @code{c''}, one
1056 octave above central C.
1064 What follows is sequential music, i.e.,
1065 @cindex sequential music
1066 notes that are to be played and printed after each other.
1073 @cindex time signature, setting
1074 @cindex @code{\time}
1075 The @code{\time} command sets (or changes) the time signature of the
1076 current piece: a 3/4 sign is printed. This setting is also used to
1077 generate bar lines at the right spots.
1084 @cindex key signature, setting
1086 Set (or change) the current key signature to G-major. Although in this
1087 example, the @code{\key} command happened to be entered after the
1088 @code{\time} command, in the output the time signature will be printed
1089 after the key signature; LilyPond knows about music typesetting
1097 The following piece of music is played twice. The first argument
1098 indicates the type of repeat. In this case, @code{"volta"} means that
1099 prima volta/secunda volta brackets are used for the alternative
1100 endings---if there were any.
1102 A special notation for repeats allows you to get correct repeats in
1103 MIDI output. However, some extra trickery is needed to get this
1104 working, See @ref{Repeats and MIDI}.
1111 The subject of the repeat is again sequential music. Since
1112 @code{\sequential} is such a common construct, a shorthand is provided:
1113 just leave off @code{\sequential}, and the result is the same.
1120 Two notes. The first note is a quarter note with relative pitch
1121 @code{d}. The relative music was started with a @code{c''}, so the real
1122 pitch of this note is @code{d''}. The duration of a note is designated
1123 by a number; the @code{4} here represents a quarter note.
1125 The second note is an eight note with relative pitch @code{g,}. The
1126 pitch is taken relative to the previous @code{d''}, making this
1127 note have real pitch @code{g'}. The @code{8} represents an eight note.
1134 Two more notes, with pitch @code{a} and @code{b}. Because their
1135 duration is the same as the @code{g,8}, there is no need to enter the
1136 duration, but you may enter it anyway, i.e., @code{a8 b8}
1145 @cindex errors, finding
1146 Three more notes. The @code{|} character is a ``bar check''. LilyPond
1147 will verify that bar checks are found at the start of a measure. This can
1148 help you track down typing errors.
1150 @cindex alteration, chromatic
1151 @cindex chromatic alteration
1158 So far, no notes were chromatically altered. Here is the first one
1159 that is: @code{fis}. LilyPond uses Dutch note names, and ``Fis'' is
1160 the name for ``F sharp''. There is no sharp sign in the output. The
1161 program keeps track of key signatures, and will only print accidentals
1162 if they are needed. If you can not get used to Dutch names, then
1163 there also are names available in several other languages.
1166 For groups of eighth notes and shorter, LilyPond can determine how the
1167 notes should form a beam. In this case, the 4 eights are automatically
1172 c4 d8( )c b a( )b4 c8 b a g |
1175 The beginning and ending notes of a slur are marked with parentheses,
1176 @code{(} and @code{)} for start and end respectively. The line above
1177 indicates two slurs. These slur markers (parentheses) are entered
1178 between the slurred notes.
1185 Automatic beaming can be overridden by inserting beam marks, @code{[}
1186 and @code{]}. These beam markers (brackets) are put around the notes
1194 @cindex augmentation dot
1196 A period adds a dot to the note.
1203 The end of the sequential music to be repeated. LilyPond will typeset a
1211 Accidentals are printed whenever necessary: the first C sharp of the bar
1212 will be printed with an accidental, the second one without.
1216 a8-. b-. cis-. d-. e-. fis-.
1219 @cindex articulation
1220 Staccato signs are entered as a dash and a period. Some other
1221 articulations may also be entered in this short form.
1229 Rests are denoted by the special note name @code{r}.
1236 All articulations have a verbose form, like @code{\fermata}. The
1237 command @code{\fermata} is not part of the core of the language, but it
1238 is a shorthand for a more complicated description of a fermata symbol.
1239 @code{\fermata} names that description and is therefore called an
1242 @cindex @code{\fermata}
1248 Here the music ends. LilyPond does not automatically typeset an end
1249 bar, we must explicitly request one, using @code{"|."}.
1255 % standard settings are too big and wide for a book
1261 The @code{\paper} block specifies how entered music should be converted
1262 to notation output. Most of the details of the conversion (font sizes,
1263 dimensions, etc.) have been taken care of, but to fit the output in this
1264 document, it has to be narrower. We do this by setting the line width
1265 to 14 centimeters (approximately 5.5 inches).
1272 The last brace ends the @code{\score} block.
1277 @node Lyrics and chords
1278 @section Lyrics and chords
1280 In this section we show how to typeset a song. This file is
1281 included as @file{flowing.ly}.
1285 title = "The river is flowing"
1286 composer = "Traditional"
1288 \include "paper16.ly"
1289 melody = \notes \relative c' @{
1293 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1294 c4 c8 d [es () d] c4 | d4 es8 d c4.
1299 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
1300 ri -- ver is flo -- wing down to the sea.
1303 accompaniment =\chords @{
1305 c2:3- f:3-.7 d:min es4 c8:min r8
1306 c2:min f:min7 g:7^3.5 c:min @}
1311 \context ChordNames \accompaniment
1314 \context Staff = mel @{
1315 \property Staff.autoBeaming = ##f
1316 \property Staff.automaticMelismata = ##t
1319 \context Lyrics \text
1321 \midi @{ \tempo 4=72 @}
1322 \paper @{ linewidth = 10.0\cm @}
1327 The result would look this.@footnote{The titling and font size shown
1328 may differ, since the titling in this document is not generated by
1331 @center @strong{The river is flowing}
1336 title = "The river is flowing"
1337 composer = "Traditional"
1339 \include "paper16.ly"
1340 melody = \notes \relative c' {
1344 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1345 c4 c8 d [es () d] c4 | d4 es8 d c4.
1350 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
1351 ri -- ver is flo -- wing down to the sea.
1354 accompaniment =\chords {
1356 c2:3- f:3-.7 d:min es4 c8:min r8
1357 c2:min f:min7 g:7^3.5 c:min }
1362 \context ChordNames \accompaniment
1365 \context Staff = mel {
1366 \property Staff.autoBeaming = ##f
1367 \property Staff.automaticMelismata = ##t
1370 \context Lyrics \text
1372 \midi { \tempo 4=72 }
1373 \paper { linewidth = 10.0\cm }
1377 Again, we will dissect the file line by line.
1384 @cindex @code{\header}
1385 Information about the music you are about to typeset goes into a
1386 @code{\header} block. The information in this block is not used by
1387 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
1388 information to print titles above the music.
1392 title = "The river is flowing"
1393 composer = "Traditional (?)"
1396 @cindex identifier assignment
1397 the @code{\header} block contains assignments. In each assignment, a
1398 variable is set to a value.
1402 \include "paper16.ly"
1405 Smaller size for inclusion in a book.
1409 melody = \notes \relative c' @{
1412 The structure of the file will be the same as the previous one, a
1413 @code{\score} block with music in it. To keep things readable, we will
1414 give names to the different parts of music, and use the names to
1415 construct the music within the score block.
1422 @cindex @code{\partial}
1424 The piece starts with an anacrusis of one eighth.
1429 The key is C minor: we have three flats.
1434 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1435 c4 c8 d [es () d] c4 | d4 es8 d c4.
1440 @cindex manual beaming
1441 @cindex automatic beaming, turning off
1442 We use explicit beaming. Since this is a song, we turn automatic
1443 beams off, and use explicit beaming where needed.
1450 This ends the definition of @code{melody}.
1459 @cindex identifier assignment
1460 @cindex syllables, entering
1461 Another identifier assignment. This one is for the lyrics.
1462 Lyrics are formed by syllables that have duration, and not by
1463 notes. To make LilyPond parse words as syllables, switch it into
1464 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
1465 is a shorthand for @code{\sequential @{}.
1469 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
1470 ri- ver is flo- __ wing down to the sea.
1474 @cindex extenders, lyric
1475 @cindex hyphens, lyric
1476 The syllables themselves are separated by spaces. You can get syllable
1477 extenders by entering @code{__}, and centered hyphens with
1478 @code{-}@code{-}. We don't enter durations for the syllables. They
1479 are aligned with the melody later.
1483 accompaniment =\chords @{
1487 @cindex mode, chords
1488 We'll put chords over the music. To enter them, there is a special mode
1489 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1490 the names of the chords you want, instead of listing the notes
1491 comprising the chord.
1498 There is no accompaniment during the anacrusis.
1507 @cindex chord modifier
1508 @cindex modifier, chord
1509 This is a c minor chord, lasting half a note. Chord are entered by
1510 entering the tonic. Then notes can be changed. In this case, a small third
1511 is used. The cod for this is @code{3-}.
1517 Similarly, @code{7} modifies (adds) a seventh, which is small by
1518 default to create the @code{f a c es} chord. Multiple modifiers must be
1526 Some modifiers have predefined names, e.g. @code{min} is the same as
1527 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1531 c2:min f:min7 g:7^3.5 c:min @}
1534 @cindex named modifier
1536 A named modifier @code{min} and a normal modifier @code{7} do not have
1537 to be separated by a dot. Tones from a chord are removed with chord
1538 subtractions. Subtractions are started with a caret, and they are
1539 also separated by dots. In this example, @code{g:7^3.5} produces a
1540 minor seventh. The brace ends the sequential music.
1548 We assemble the music in the @code{\score} block. Melody, lyrics and
1549 accompaniment have to sound at the same time, so they should be
1550 @code{\simultaneous}.
1551 @cindex @code{\simultaneous}
1558 Chord mode generates notes grouped in @code{\simultaneous} music. If
1559 you remove the comment sign, you can see the chords in normal
1560 notation: they will be printed as note heads on a separate
1561 staff. To print them as chords names, they have to be interpreted as
1562 being chords, not notes. This is done with the following command:
1566 \context ChordNames \accompaniment
1570 @cindex interpretation context
1571 @cindex notation context
1574 Normally, the notes that you enter are transformed into note heads.
1575 Note heads alone make no sense, they need surrounding information: a key
1576 signature, a clef, staff lines, etc. They need @emph{context}. In
1577 LilyPond, these symbols are created by objects called `interpretation
1578 contexts'. Interpretation contexts exist for generating notation
1579 (`notation context') and for generating sound (`performance
1580 context'). These objects only exist during a run of LilyPond.
1582 When LilyPond interprets music, it will create a Staff context. If
1583 the @code{%} sign in the previous line were removed, you could see
1584 that mechanism in action.
1586 We don't want that default here, because we want chord names. The
1587 command above explicitly creates an interpretation context of
1588 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1595 @cindex @code{\addlyrics}
1596 @cindex lyrics and melody, combining
1597 @cindex combining lyrics and melody
1599 The lyrics should be aligned with the melody. This is done by
1600 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
1601 pieces of music (usually a melody and lyrics, in that order) and
1602 aligns the syllables of the second piece under the notes of the
1607 \context Staff = mel @{
1611 We place the melody on a staff called @code{mel}. We give it a name to
1612 differentiate it from the one that would contain note heads for the
1613 chords, if you would remove the comment before the ``note heads''
1614 version of the accompaniment. By giving this staff a name, it is
1615 forced to be different.
1619 \property Staff.autoBeaming = ##f
1623 @cindex context variables
1624 @cindex setting context variables
1625 An interpretation context has variables, called properties, that tune
1626 its behavior. One of the variables is @code{autoBeaming}. Setting
1627 this @code{Staff}'s property to @code{##f}, which is the boolean value
1628 @var{false}, turns the automatic beaming mechanism off for the current
1634 @cindex accessing Scheme
1635 @cindex evaluating Scheme
1638 LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
1639 language from the LISP family. You can learn more about Scheme at
1640 @uref{http://www.scheme.org}. It is used to represent data throughout
1641 the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
1642 code following the hash-sign is evaluated as Scheme. The boolean value
1643 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
1646 If Scheme scares you, don't worry. You don't need to know Scheme to
1647 create beautiful sheet music.
1654 \property Staff.automaticMelismata = ##t
1657 @cindex automaticMelismata
1659 @cindex @code{\addlyrics} and slurs
1660 Similarly, we don't want to print a syllable when there is
1661 a slur. This sets up @code{\addlyrics} to not put lyrics under each
1662 separate note while there is a slur.
1670 Finally, we put the melody on the current staff. Note that the
1671 @code{\property} directives and @code{\melody} are grouped in sequential
1672 music, so the property settings are done before the melody is
1677 \context Lyrics \text
1680 The second argument of @code{\addlyrics} is the text. The text also
1681 should not land on a Staff, but on a interpretation context for
1682 syllables, extenders, hyphens etc. This context is called
1687 \midi @{ \tempo 4=72@}
1690 MIDI (Musical Instrument Digital Interface) is a standard for
1691 connecting and recording digital instruments. So a MIDI file is like a
1692 tape recording of an instrument. The @code{\midi} block makes the
1693 music go to a MIDI file, so you can listen to the music you entered. It
1694 is great for checking the music. Whenever you hear something weird, you
1695 probably hear a typing error.
1697 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1698 also specifies an output method. You can specify the tempo using the
1699 @code{\tempo} command, in this case the tempo of quarter notes is set to
1700 72 beats per minute.
1704 \paper @{ linewidth = 10.0\cm @}
1707 We also want notation output. The linewidth is short so the piece
1708 will be set in two lines.
1710 @node More movements
1711 @section More movements
1713 [FIXME: merge here with, or move this to: Other ways to run LilyPond]
1715 You probably ran @file{ly2dvi} on the last example, and ended up with a
1716 viewable @file{.dvi} file. However, between there are a few steps of
1717 which LilyPond is only one. To enhance your understanding of what's
1718 happening under the hood when you run @code{ly2dvi}, we explain what
1721 @code{ly2dvi} is a program that calls a number of programs in sequence.
1722 The first thing it does, is running LilyPond on the input file. After
1723 some calculations, a @file{.tex} is produced. The contents
1724 of this file are very low-level instructions.
1726 For example, consider the following file (@file{miniatures.ly})
1731 title = "Two miniatures"
1732 tagline = "small is beautiful"
1735 #(set! point-and-click line-column-location)
1737 \paper @{ linewidth = -1.0 @}
1740 \notes @{ c'4 d'4 @}
1746 \notes @{ d'4 c'4 @}
1753 The titling in this manual was not generated by ly2dvi, so we can't
1754 exactly show what it would look like, but the result should resemble this:
1756 @center @strong{Two miniatures}
1766 \paper { linewidth = -1.0 }
1778 \paper { linewidth = -1.0 }
1782 This file is produced by ly2dvi in a few stages, with the help of text
1783 formatting tools. LilyPond produces two output files,
1784 @file{miniatures.tex} and @file{miniatures-1.tex}. Both files contain
1785 only graphical music notation. @file{ly2dvi} looks at what output
1786 LilyPond produces, and adds page layout and titling to those files. The
1787 result is a DVI file called @file{miniatures.dvi}.
1789 Next, now we'll look at the example line by line to explain new things.
1795 Lilypond and its language are still under development, and occasionally,
1796 details of the syntax are changed. This fragment indicates for which
1797 version the input file was written. When you compile this file, the
1798 version number will be checked, and you will get a warning when the file
1801 This version number is also used by the @code{convert-ly} program (See
1802 @ref{convert-ly}), which is used to update the file to the latest lily
1808 title = "Two miniatures" @}
1810 This sets the titling information for the entire file.
1813 tagline = "small is beautiful"
1815 A signature line is printed at the bottom of the last page.
1816 This signature is produced from the @code{tagline} field of
1817 @code{\header}. Many people find the default "Lily was here,
1818 @var{version number}" too droll. If that is the case, assign
1819 something else to @code{tagline}, as shown above.
1822 #(set! point-and-click line-column-location)
1825 This piece of Scheme code sets the Scheme variable
1826 @code{point-and-click} to the value @var{line-column-location} (which
1827 itself is a Scheme procedure).
1829 Editing input files can be quite complicated if you're working with
1830 large files: if you're digitizing existing music, you have to
1831 synchronize the .ly file, the sheet music on your lap and the sheet
1832 music on the screen. The point-and-click mechanism makes it easy to
1833 find the origin of an error in the LY file: when you view the file with
1834 Xdvi and click on a note, your editor will jump to the spot where that
1835 note was entered. For more information, see @ref{Point and click}.
1842 The @code{\score} blocks that follow in the file don't have
1843 @code{\paper} sections, so the settings of this block are substituted: A
1844 paper block at top level, i.e. not in a @code{\score} block sets the
1845 default page layout.
1854 The variable @code{linewidth} normally sets the length of the systems on
1855 the page. However, a negative value has a special meaning. If
1856 @code{linewidth} is less than 0, no line breaks are inserted into the
1857 score, and the spacing is set to natural length: a short phrase takes up
1858 little space, a longer phrase more space.
1863 \notes @{ c'4 d'4 @}
1866 In previous examples, notes were specified in relative octaves,
1867 i.e. each note was put in the octave that is closest to its
1868 predecessor. Besides relative, there is also absolute octave
1869 specification, which you get when you don't specify @code{\relative}. In
1870 this input mode, the central C is denoted by @code{c'}. Going down, you
1871 get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
1874 When you're copying music from existing sheet music, relative octaves
1875 are probably the easiest to use: it's less typing work and errors are
1876 easily spotted. However, if you write LilyPond input directly, either by
1877 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1885 The @code{\header} is normally at the top of the file, where it sets
1886 values for the rest of the file. If you want to typeset different pieces
1887 from one file (for example, if there are multiple movements, or if
1888 you're making an exercise book), you can put different @code{\score}
1889 blocks into the input file. ly2dvi will assemble all LilyPond output
1890 files into a big document. The contents of \header blocks specified
1891 within each score, are used for the titling of each movement.
1897 For example, the Opus number is put at the right, and the piece string
1898 will be at the left.
1902 @node A piano excerpt
1903 @section A piano excerpt
1905 Our fourth subject is a piece of piano music. The fragment in the
1906 input file is a piano reduction of the G major Sinfonia by Giovanni
1907 Battista Sammartini. It was composed around 1740. It's in the source
1908 package under the name @file{sammartini.ly}.
1910 @lilypondfile[verbatim]{sammartini.ly}
1912 As you can see, this example features multiple voices on one staff. To
1913 make room for those voices, their notes have to be stemmed in opposite
1916 Printed symbols are internally represented by so-called Graphical
1917 Objects (more colloquially: Grobs). These statements concern the
1918 grob called `Stem'. Each grob is described by a bunch of settings. These
1919 setting determine the fonts, offsets, sub-routines to be called on the
1920 grob, etc. The initial values of these settings are set in the Scheme
1921 file @file{scm/grob-description.scm}.
1925 stemDown = \property Voice.Stem \override #'direction = #-1
1928 Set a property for all Stem grobs in the current Voice:
1929 @code{direction} is set to @code{-1}, which encodes down. The setting
1930 remains in effect until it is reverted.
1934 \property Voice.Stem \revert #'direction
1937 Revert the to the previous setting. The effect of precisely one
1938 @code{\stemDown} or @code{\stemUp} is neutralized.
1941 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1942 with some other commonly used formatting instructions, but to explain how
1943 it works, we wrote our own here. Of course, you should use predefined
1944 identifiers like these if possible: then you will be affected less by
1945 the implementation changes we occasionally make.
1949 viola = \notes \relative c' \context Voice = viola @{
1951 In this example, you can see multiple parts on a staff. Each part is
1952 associated with one notation context. This notation context handles
1953 stems and dynamics (among others). The type name of this context is
1954 @code{Voice}. For each part we have to make sure that there is
1955 precisely one @code{Voice} context, so we give it a unique name
1960 <c4-\f-\arpeggio g' c>
1962 The delimiters @code{<} and @code{>} are shorthands for
1963 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1964 @code{<} and @code{>} is a chord.
1971 @code{\f} places a forte symbol under the chord. The forte applies to
1972 the whole chord, but the syntax requires that commands like forte and
1973 arpeggio are attached to a note, so here we attach them to the first
1976 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1989 Relative octaves work a little differently with chords. The starting
1990 point for the note following a chord is the first note of the chord. So
1991 the @code{g} gets an octave up quote: it is a fifth above the starting
1992 note of the previous chord (the central C).
1998 @code{s} is a spacer rest. It does not print anything, but it does have
1999 the duration of a rest. It is useful for filling up voices that
2000 temporarily don't play. In this case, the viola doesn't come until one
2001 and a half measure later.
2005 oboes = \notes \relative c'' \context Voice = oboe @{
2007 Now comes a part for two oboes. They play homophonically, so we
2008 print the notes as one voice that makes chords. Again, we insure that
2009 these notes are indeed processed by precisely one context with
2013 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
2015 @code{\stemUp} is a reference to the @code{\property \override} command
2019 \grace <e8 g> < d4 f> <c2 e>
2021 @cindex @code{\grace}
2024 @code{\grace} introduces grace notes. It takes one argument, in this
2028 The slur started on the @code{e} of the chord
2029 will be attached to the next note.@footnote{LilyPond will squirm
2030 about unended Slurs. In this case, you can ignore the warning}.
2038 Tuplets are made with the @code{\times} keyword. It takes two
2039 arguments: a fraction and a piece of music. The duration of the piece
2040 of music is multiplied by the fraction. Triplets make notes occupy 2/3
2041 of their notated duration, so in this case the fraction is 2/3.
2044 @{ <d8 \< f> <e g> <f a> @}
2046 The piece of music to be `tripletted' is sequential music containing
2047 three notes. On the first chord, a crescendo is started with
2048 @code{\<}. To be precise, the crescendo start is syntactically attached
2049 to the preceding note, the @code{d}.
2059 At this point, the homophonic music splits into two rhythmically
2060 different parts. We can't use a sequence of chords to enter this, so
2061 we make a `chord' of sequences to do it. We start with the upper
2062 voice, which continues with upward stems:
2065 @{ \times 2/3 @{ a8 g c @} \! c2 @}
2070 The crescendo is ended at the half note by the escaped exclamation
2074 \context Voice = oboeTwo @{
2077 We can't share stems with the other voice, so we have to create a new
2078 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
2079 it from the other context. Stems go down in this voice.
2084 @cindex Grace context
2085 When a grace section is processed, a @code{Grace} context is
2086 created. This context acts like a miniature score of its own. It has
2087 its own time bookkeeping, and you can make notes, beams, slurs
2088 etc. Here we fiddle with a property and make a beam. The argument of
2089 @code{\grace} is sequential music.
2093 \property Voice.Stem \override #'direction = #-1
2095 \property Voice.Stem \revert #'direction
2098 Normally, grace notes are always stem up, but in this case, the upper
2099 voice interferes, so we set the stems down here.
2101 As far as relative mode is concerned, the previous note is the
2102 @code{c'''2} of the upper voice, so we have to go an octave down for
2110 This ends the two-part section.
2114 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
2119 @code{\stemBoth} ends the forced stem directions. From here, stems are
2120 positioned as if it were single part music.
2122 The bass has a little hoom-pah melody to demonstrate parts switching
2123 between staves. Since it is repetitive, we use repeats:
2126 hoomPah = \repeat unfold 8
2128 @cindex unfolded @code{\repeat}
2129 The unfolded repeat prints the notes in its argument as if they were
2130 written out in full eight times.
2133 \notes \transpose c' @{
2136 @cindex relative mode and transposing
2138 Transposing can be done with @code{\transpose}, which takes two arguments.
2139 The first specifies what central C should be transposed to. The second
2140 is the to-be-transposed music. As you can see, in this case, the
2141 transposition has no effect, as central C stays at central C.
2143 The purpose of this no-op is circumventing relative mode. Relative mode
2144 can not be used together with transposition, so @code{\relative} will
2145 leave the contents of @code{\hoomPah} alone. We can use it without
2146 having to worry about getting the motive in a wrong octave.
2149 bassvoices = \notes \relative c' @{
2151 \autochange Staff \hoomPah \context Voice
2153 @cindex staff switch, automatic
2154 @cindex cross staff voice, automatic
2155 @cindex @code{\autochange}
2157 Voices can switch between staves. The easiest way to get this, is to use
2158 @code{\autochange}. This command looks at the pitch of each note, and if
2159 necessary, will cross to the other staff. For this to work, the two
2160 staves must be called @code{"up"} and @code{"down"}.
2163 \translator Staff = down
2165 @cindex staff switch
2166 @cindex cross staff voice
2167 We want the remaining part of this melody on the lower staff, so we do a
2168 manual staff switch here.
2173 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
2177 After skipping some lines, we see @code{~}. This mark makes ties. Note
2178 that ties and slurs are different things. A tie can only connect two
2179 note heads of the same pitch, whereas a slur can connect many chords
2186 A special context is needed to get cross staff beaming right. This
2187 context is called @code{PianoStaff}.
2190 \context Staff = bottom < \time 2/2 \clef bass
2192 The bottom staff must have a different clef.
2197 To make some more room on the line, the first (in this case the only)
2198 line is not indented. The line still looks very cramped, but that is due
2199 to the page layout of this document.
2205 * font-size, multi-stanza.
2207 * Simple part combining in a Hymn
2211 @node Fine tuning a piece
2212 @section Fine tuning a piece
2216 @lilypondfile{brahms-original.ly}
2218 @lilypondfile{brahms-tweaked.ly}
2222 @node An orchestral score
2223 @section An orchestral score
2227 * Extracting an individual part::
2231 Our last two examples show a way to setup the music for an orchestral
2232 score. When typesetting a piece for several instruments, you'll want to
2233 create a conductor's full score, alongside several individual parts.
2235 LilyPond is well suited for this task. We will declare the music for
2236 each instrument individually, giving the music of each instrument its
2237 own name. These pieces of music are then combined in different
2238 @code{\score} blocks to produce different combinations of the score.
2240 This orchestral score example consists of three input files. In the
2241 first file, @file{os-music.ly}, we define the music for all instruments.
2242 This file will be used both for producing the score and the separate
2245 If you were to run LilyPond on this file, no printable output would be
2251 title = "Zo, goed lieverd?"
2252 subtitle = "How's, this babe?"
2261 Key = \notes \key as \major
2262 flautoI = \notes\relative c'' @{
2264 bes as bes as bes as bes as
2266 flautoII = \notes\relative c'' @{
2267 as8 bes as bes R1 d4 ~ d
2269 tromboI = \notes\relative c'' @{
2270 c4. c8 c8 c4. es4 r as, r
2272 tromboII = \notes\relative c'' @{
2273 as4. as8 as8 as4. R1*1/2 as4 es'
2275 timpani = \notes\relative c, @{
2276 \times 2/3 @{ f4 f f @}
2277 \times 4/5 @{ as8 as as as as @}
2280 corno = \notes\relative c' @{
2281 bes4 d f, bes d f, bes d
2285 We will not go through the input line by line, but only indicate and
2286 explain the new elements.
2293 \skip 2*4 \bar "|.";
2297 Declare setting to be used globally. The @code{\skip} command produces
2298 no output, but moves forward in time: in this case, the duration of a
2299 half note (@code{2}), and that four times (@code{*4}). This brings us
2300 to the end of the piece, and we can set the end bar.
2304 Key = \notes \key as \major
2306 Declare the key signature of the piece and assign it to the identifier
2307 @var{Key}. Later on, we'll use @code{\Key} for all staves except those
2308 for transposing instruments.
2310 @node The full score
2311 @subsection The full score
2314 The second file, @file{os-score.ly} reads the definitions of the first
2315 (@file{os-music.ly}), and defines the @code{\score} block for the full
2321 \include "os-music.ly"
2322 \include "paper13.ly"
2324 #(set! point-and-click line-column-location)
2325 #(define text-flat '((font-relative-size . -2)
2326 (music "accidentals--1")))
2331 \property Score.BarNumber \override #'padding = #3
2332 \context StaffGroup = woodwind <
2333 \context Staff = flauti <
2334 \property Staff.midiInstrument = #"flute"
2335 \property Staff.instrument = "2 Flauti"
2336 \property Staff.instr = "Fl."
2338 \context Voice=one @{ \voiceOne \flautoI @}
2339 \context Voice=two @{ \voiceTwo \flautoII @}
2342 \context StaffGroup = timpani <
2343 \context Staff = timpani <
2344 \property Staff.midiInstrument = #"timpani"
2345 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2346 \property Staff.instr = #"Timp."
2352 \context StaffGroup = brass <
2353 \context Staff = trombe <
2354 \property Staff.midiInstrument = #"trumpet"
2355 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2356 \property Staff.instr = #`(lines "Tbe." "(C)")
2358 \context Voice=one \partcombine Voice
2359 \context Thread=one \tromboI
2360 \context Thread=two \tromboII
2362 \context Staff = corni <
2363 \property Staff.midiInstrument = #"french horn"
2364 \property Staff.instrument = #`(lines "Corno"
2365 (columns "(E" ,text-flat ")"))
2366 \property Staff.instr = #`(lines "Cor."
2367 (columns "(E" ,text-flat ")"))
2368 \property Staff.transposing = #3
2369 \notes \key bes \major
2370 \context Voice=one \corno
2375 indent = 15 * \staffspace
2376 linewidth = 60 * \staffspace
2377 textheight = 90 * \staffspace
2379 \HaraKiriStaffContext
2388 @center @strong{Zo, goed lieverd?}
2390 @center How's, this babe?
2398 @lilypondfile{os-score.ly}
2402 \include "os-music.ly"
2404 First, we need to include the music definitions we made in
2409 #(set! point-and-click line-column-location)
2411 In a large orchestral score like this you're bound to make some small
2412 mistakes, so we enable point and click (See @ref{Point and click})
2417 #(define text-flat '((font-relative-size . -2)
2418 (music "accidentals--1")))
2421 When naming the tuning of the french horn, we'll need a piece of text
2422 with a flat sign. LilyPond has a mechanism for font selection and
2423 kerning called Scheme markup text (See @ref{Text markup}). The flat
2424 sign is taken from the music font, and its name is @code{accidentals--1}
2425 (The natural sign is called @code{accidentals-0}). The default font is
2426 too big for text, so we select a relative size of @code{-2}.
2433 Of course, all staves are simultaneous and use the same global settings.
2437 \property Score.BarNumber \override #'padding = #3
2439 LilyPond prints bar numbers at the start of each line, but
2440 unfortunately, they end up a bit too close to the staff in this example.
2441 A bar number internally is a Grob called @var{BarNumber}. BarNumber
2442 Grobs can be manipulated through their @var{side-position-interface}. One
2443 of the properties of a @var{side-position-interface} that can be tweaked
2444 is the @var{padding}: the amount of extra space that is put between this
2445 Grob and other Grobs. We set the padding to three staff spaces.
2447 You can find information on all these kind of properties in LilyPond's
2448 automatically generated documentation in
2450 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
2453 the online documentation.
2458 \context StaffGroup = woodwind <
2459 \context Staff = flauti <
2461 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2462 hold one or more @code{Staff}'s, and will print a big bracket at the
2463 left of the score. Start a new staff group for the woodwind section
2464 (just the flutes in this case). Immediately after that, we start the
2465 staff for the two flutes, that also play simultaneously.
2469 \property Staff.midiInstrument = #"flute"
2471 Specify the instrument for MIDI output (see @ref{MIDI instrument
2476 \property Staff.instrument = "2 Flauti"
2477 \property Staff.instr = "Fl."
2479 And define the instrument names to be printed in the margin,
2480 @code{instrument} for the first line of the score, @code{instr} for the
2487 The flutes play in the default key.
2491 \context Voice=one @{ \voiceOne \flautoI @}
2492 \context Voice=two @{ \voiceTwo \flautoII @}
2494 Last come the actual flute parts. Remember that we're still in
2495 simultaneous mode. We name both voices differently, so that LilyPond
2496 will actually create two Voice contexts. The flute parts are simple, so
2497 we specify manually which voice is which: @code{\voiceOne} forces the
2498 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2506 Close the flutes staff and woodwind staff group.
2510 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2512 The timpani staff only shows a new piece of scheme markup, it sets two
2517 \context Voice=one \partcombine Voice
2518 \context Thread=one \tromboI
2519 \context Thread=two \tromboII
2521 You have seen the notation contexts Staff and Voice, but here's a new
2522 one: Thread. One or more Threads can be part of a Voice. The Thread
2523 takes care of note heads and rests, the Voice combine note heads onto a
2526 For the trumpets we use the automatic part combiner (see @ref{Automatic
2527 part combining}) to combine the two simultaneous trumpet parts onto the
2528 trumpet staff. Each trumpet gets its own Thread context, which must be
2529 named @code{one} and @code{two}). The part combiner makes these two
2530 threads share a Voice when they're similar, and splits the threads up
2531 when they're different.
2535 \property Staff.instrument = #`(lines "Corno"
2536 (columns "(E" ,text-flat ")"))
2538 The french horn has the most complex scheme markup name, made up of two
2539 lines of text. The second line has three elements (columns), the @code{(E},
2540 the flat sign @code{text-flat} that we defined before and a final @code{")"}.
2541 Note that we use a backquote instead of an ordinary quote at the
2542 beginning of the Scheme expression to be able to access the
2543 @code{text-flat} identifier, `unquoting' it with a @code{,}.
2547 \property Staff.transposing = #3
2549 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
2550 transpose this staff by three steps.
2552 Note how we can choose different tuning for entering, printing and
2553 playing, using @code{\transpose} and the MIDI Staff property
2558 \notes \key bes \major
2560 Therefore, it has a different key.
2564 indent = 15 * \staffspace
2565 linewidth = 60 * \staffspace
2567 We specify a big indent for the first line and a small linewidth for this
2572 Usually, LilyPond's predefined setup of notation contexts (Thread,
2573 Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
2574 want a different type of Staff context.
2578 \HaraKiriStaffContext
2582 In orchestral scores, it often happens that one instrument has only
2583 rests during one line of the score. The @code{HaraKiriStaffContext} can
2584 be used as a regular @code{StaffContext} drop-in and will take care of
2585 the automatic removing of empty staves.
2587 @node Extracting an individual part
2588 @subsection Extracting an individual part
2590 The third file, @file{os-flute-2.ly} also reads the definitions of the
2591 first (@file{os-music.ly}), and defines the @code{\score} block for the
2595 \include "os-music.ly"
2596 \include "paper16.ly"
2600 \property Score.skipBars = ##t
2601 \property Staff.midiInstrument = #"flute"
2607 instrument = "Flauto II"
2610 linewidth = 80 * \staffspace
2611 textheight = 200 * \staffspace
2619 @center @strong{Zo, goed lieverd?}
2621 @center How's, this babe?
2622 @center @emph{Flauto II}
2629 @lilypondfile{os-flute-2.ly}
2632 Because we separated the music definitions from the @code{\score}
2633 instantiations, we can easily define a second score with the music of
2634 the second flute. This then is the part for the second flute player.
2635 Of course, we make separate parts for all individual instruments.
2641 In this individual part the second flute has a whole staff for itself,
2642 so we don't want to force stem or tie directions.
2647 instrument = "Flauto II"
2650 The @code{\header} definitions were also read from @file{os-music.ly},
2651 but we need to set the instrument for this particular score.
2655 \property Score.skipBars = ##t
2657 In the conductor's full score, all bars with rests are printed, but for
2658 the individual parts, we want to contract pieces of consecutive empty
2659 bars. LilyPond will do this if Score's @var{skipBars} property to
2663 @node Other ways to run LilyPond
2664 @section Other ways to run LilyPond
2666 Until now, you have been using @file{ly2dvi} to invoke LilyPond.
2667 There are three other routes. Firstly, there is a script called
2668 @code{lilypond-book}, that allows you to freely mix LilyPond input with
2669 Texinfo or \LaTeX input. For example, this manual was written using
2670 @code{lilypond-book}. It is discussed below and in @ref{lilypond-book}.
2673 Secondly, you can generate PostScript directly. This is useful if you
2674 can not or do not want to run @TeX{} on your system. To obtain direct
2675 PostScript output, invoke LilyPond as follows:
2676 @cindex PostScript output
2678 lilypond -f ps test.ly
2680 You have to set some environment variables to view or print this output.
2681 More information can be found in @ref{Invoking LilyPond}. Since the
2682 direct Postscript generation has some problems, it is recommended
2683 to use @file{ly2dvi}.
2686 Thirdly, if you want to do special things with your output, you can run
2687 invoke LilyPond directly:
2691 to produce plain @TeX{} output. Note that La@TeX{} will not work on the
2692 resulting @file{test.tex}. You must run plain @TeX{} on it.
2700 @node Integrating text and music
2701 @section Integrating text and music
2703 Sometimes, you might want to use music examples in a text that you are
2704 writing. For example, if you are writing a musicological treatise, a
2705 songbook, or (like us) the LilyPond manual. You can make such texts by
2706 hand, simply by importing a PostScript figure into your wordprocessor.
2707 However, there is a also an automated procedure:
2709 If you use La@TeX{} or texinfo, you can mix text and LilyPond code. A
2710 script called @code{lilypond-book} will extract the music fragments, run
2711 LilyPond on them, and put back the resulting notation. lilypond-book is
2712 described fully in @ref{lilypond-book}, but here we show a small
2713 example. Since the example also contains explanatory text, we won't
2714 comment on the contents.
2717 \documentclass[a4paper]@{article@}
2720 In a lilypond-book document, you can freely mix music and text. For
2723 \score @{ \notes \relative c' @{
2724 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2727 Notice that the music line length matches the margin settings of the
2730 If you have no \verb+\score+ block in the fragment,
2731 \texttt@{lilypond-book@} will supply one:
2737 In the example you see here, a number of things happened: a
2738 \verb+\score+ block was added, and the line width was set to natural
2739 length. You can specify many more options using \LaTeX style options
2742 \begin[verbatim,11pt,singleline,
2743 fragment,relative,intertext="hi there!"]@{lilypond@}
2747 \texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
2748 the default music size, \texttt@{fragment@} adds a score block,
2749 \texttt@{relative@} uses relative mode for the fragment, and
2750 \texttt@{intertext@} specifies what to print between the
2751 \texttt@{verbatim@} code and the music.
2753 If you include large examples into the text, it may be more convenient
2754 to put the example in a separate file:
2756 \lilypondfile[printfilename]@{sammartini.ly@}
2758 The \texttt@{printfilename@} option adds the file name to the output.
2763 Under Unix, you can view the results as follows.
2766 $ lilypond-book --outdir=out/ lilbook.tex
2767 lilypond-book (GNU LilyPond) 1.3.146
2768 Reading `input/tutorial/lilbook.tex'
2769 Reading `input/tutorial/sammartini.ly'
2770 @var{lots of stuff deleted}
2771 Writing `out/lilbook.latex'
2773 $ latex lilbook.latex
2774 @var{lots of stuff deleted}
2778 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2779 and running latex creates a lot of temporary files, and you wouldn't want
2780 those to clutter up your working directory. Hence, we have them created
2781 in a separate subdirectory.
2783 The result more or less looks like this:
2787 In a lilypond-book document, you can freely mix music and text. For
2790 \score { \notes \relative c' {
2791 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2794 Notice that the music line length matches the margin settings of the
2797 If you have no @code{\score} block in the fragment,
2798 @code{lilypond-book} will supply one:
2804 In the example you see here, a number of things happened: a
2805 @code{\score} block was added, and the line width was set to natural
2806 length. You can specify many more options using La@TeX{} style options
2809 @lilypond[verbatim,11pt,singleline,
2810 fragment,relative,intertext="hi there!"]
2814 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2815 the default music size, @code{fragment} adds a score block,
2816 @code{relative} uses relative mode for the fragment, and
2817 @code{intertext} specifies what to print between the
2818 @code{verbatim} code and the music.
2820 If you include large examples into the text, it may be more convenient
2821 to put the example in a separate file:
2823 @lilypondfile[printfilename]{sammartini.ly}
2825 The @code{printfilename} option adds the file name to the output.
2826 @node End of tutorial
2827 @section End of tutorial
2829 That's all folks. From here, you can either try fiddling with input
2830 files, or you can read the reference manual. You can find more example
2831 files in @file{input} and @file{input/test}. You can also look at some
2832 real music. The website @uref{http://www.mutopiaproject.org} has many
2833 examples of real music typeset by LilyPond.
2841 this should be on mutopia website.
2846 @c waar deze info? is uiteindelijk wel handig, schat ik.
2849 If you have a big music project, or just a lot of LilyPond input files,
2850 all generated output from LilyPond, @TeX{} and metafont will clutter
2851 your working directory. LilyPond comes with a one-size-fits-all
2852 pre-cooked makefile that helps you manage producing output. It will
2853 produce all output in the directory @file{out} , generate and track
2854 dependencies. Also, it helps in preparing your submission to @ref{Mutopia
2861 cp /usr/share/lilypond/make/ly.make GNUmakefile
2862 cp /usr/share/doc/lilypond/examples/input/tutorial/minuet.ly .
2865 Generated out/minuet.ps for target minuet.
2868 Type @samp{make help} to see possible targets.
2871 @file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
2877 [TODO: rewrite completely.]
2880 * Songs with additional verses::