3 @c TODO: LilyPond LilyPond LilyPond
9 <!--- @@WEB-TITLE@@=Tutorial --->
13 * First steps:: Music language of LilyPond
14 * Running LilyPond:: Printing music
17 * A melody with chords ::
19 * More movements :: Joining separate pieces of music
20 * A piano excerpt:: Piano music
21 * Fine tuning a piece::
22 * An orchestral score:: Conductor's score and individual parts
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
41 We tsart off with showing how very simple music is entered in
42 LilyPond: you get a simple note by typing its note name, from
43 @code{a} through @code{g}. So if you enter
49 then the result looks like this:
52 \property Score.timing = ##f
53 \property Staff.TimeSignature = \turnOff
54 \transpose c'' { c d e f g a b }
59 We will continue with this format: first we show a snippet of input,
60 then the resulting output.
62 The length of a note is specified by adding a number, ``@code{1}'' for a
63 whole note, ``@code{2}'' for a half note, and so on:
70 @c missing clef seems to raise more questions than actual pitch of notes,
71 @c as these are snippets anyway
73 \property Score.timing = ##f
74 \property Staff.TimeSignature = \turnOff
75 \property Staff.autoBeaming = ##f
76 %\property Staff.Clef = \turnOff
77 \transpose c'' { a1 a2 a4 a16 a32 }
83 If you don't specify a duration, the previous one is used:
89 @c missing clef seems to raise more questions than actual pitch of notes,
90 @c as these are snippets anyway
92 \property Score.timing = ##f
93 \property Staff.TimeSignature = \turnOff
94 %\property Staff.Clef = \turnOff
95 \transpose c'' { a a a2 a }
101 A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
102 (@texiflat{}) by adding ``@code{es}'':
110 \property Score.timing = ##f
111 \property Staff.TimeSignature = \turnOff
112 \transpose c'' { cis1 ees fisis aeses }
118 Add a dot ``@code{.}'' after the duration to get a dotted note:
124 @c missing clef seems to raise more questions than actual pitch of notes,
125 @c as these are snippets anyway
127 \property Score.timing = ##f
128 \property Staff.TimeSignature \set #'transparent = ##t
129 %\property Staff.Clef = \turnOff
130 \transpose c'' { a2. a4 a8. a16 }
136 The meter (or time signature) can be set with the @code{\time} command:
145 @c a clef here may lead to confusion
147 \property Staff.Clef \set #'transparent = ##t
158 The clef can be set using the ``@code{\clef}'' command:
160 @c what is more common name treble or violin?
161 @c in Dutch, its violin.
171 \property Score.timing = ##f
172 \property Staff.TimeSignature = \turnOff
185 From these commands and notes, a piece of music can be formed. A piece
186 of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
187 LilyPond then knows that music follows (and not lyrics, for example):
201 At this point, the piece of music is ready to be printed. This is done
202 by combining the music with a printing command.
204 The printing command is the so-called ``@code{\paper}'' block. You
205 will see later that the @code{\paper} block is necessary to customize
206 printing specifics. The music and the @code{\paper} block are combined by
207 enclosing them in ``@code{\score @{ ... @}}''. This is what a full
208 LilyPond source file looks like:
231 \paper { linewidth = 60 * \staffspace }
238 @node Running LilyPond
239 @section Running LilyPond
241 In the last section, we explained what kind of things you could enter
242 in a lilypond file. In this section we explain how to run LilyPond,
243 and how view or print the output. If you have not used LilyPond
244 before, want to test your setup of LilyPond, or try to run an example
245 file yourself, then read this section. The instructions that follow
246 are for running LilyPond on Unix-like systems. Some additional
247 instructions for running LilyPond on Windows are given at the end of
250 You begin with opening a terminal window, and start up a text editor.
251 For example, open an xterm and execute @code{joe}. In your text editor,
252 enter the following input, and save the file as @file{test.ly}:
257 \notes @{ c'4 e' g' @}
264 @c now this is weird, running ly2dvi to run LilyPond
265 @c (therefore name change proposal)
267 LilyPond is the program that computes the sheet music. All other
268 things, such as adding titles, page breaking and other page layout,
269 are done by a small wrapper program called
270 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
271 then adds the titling and page layout instructions. To process
272 @file{test.ly} with ly2dvi, proceed as follows:
280 You will see the following on your screen:
285 Now processing: `/home/fred/ly/test.ly'
287 Interpreting music...[1]
288 @emph{ ... more interesting stuff ... }
289 PS output to `test.ps'...
290 DVI output to `test.dvi'...
294 @cindex Viewing music
297 The results of the ly2dvi run are two files, @file{test.dvi} and
298 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
299 You can view the PS file using the program ghostview. If a version of
300 ghostview is installed on your system, one of these commands will
301 produce a window with some music notation on your screen:
311 If you are satisfied with the looks of the music displayed on your
312 screen, you can print the PS file by clicking File/Print inside
315 The DVI file (@file{test.dvi}) contains the same sheet music in a
316 different format. DVI files are more easily processed by the computer,
317 so viewing them usually is quicker. Execute @code{xdvi test.dvi} or
318 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse buttons
319 activate magnifying glasses. Unfortunately, variable symbols, such as
320 beams and slurs won't show up in these.
322 If your DVI viewer does not have a "Print" button, you can print the
323 file by executing @code{lpr test.ps}.
325 @c volgende alinea schrappen?
327 If your system does not support printing PostScript files, then you
328 can install GhostScript, a PostScript emulator. Refer to
329 GhostScript's website at @uref{http://www.ghostscript.com}.
333 @cindex Printing output
337 A final option, is to use the popular PDF format. You can get a PDF
338 file by running @code{ly2dvi --pdf test.ly}. With the @code{--pdf},
339 you will get a DVI, PS and PDF file. The viewers for the PS files also
340 accept PDF files, but there are also many other applications for
343 If you are familiar with @TeX{}, then one warning is in place: do not
344 use other DVI drivers like @code{dvilj}. The @TeX{} coming out of
345 LilyPond uses embedded PostScript code, and will not render correctly
346 if you use anything different than @code{dvips}.
352 @unnumberedsubsec Windows users
353 Windows users start the terminal by clicking on the LilyPond or Cygwin
354 icon. Notepad is sufficient for editing the LilyPond file. Viewing
355 the PS file can be done with:
358 @code{gsview32 test.ps}
361 You can also print from the command line by executing:
364 @code{gsview32 /s test.ps}
371 To run LilyPond, enter a file, and run the command @code{ly2dvi} on
372 that file. The resulting files are either DVI or PostScript, and can
373 be viewed with @code{xdvi} (unix) and ghostview (unix and windows)
374 respectively. The following table summarizes the constructs that were
375 discussed in the previous two sections.
377 @multitable @columnfractions .3 .3 .4
383 @item @code{1 2 8 16}
386 @lilypond[fragment, relative 1]
387 \property Staff.TimeSignature = \turnOff
388 \property Staff.autoBeaming = ##f
389 \property Staff.Clef = \turnOff
394 @tab augmentation dots
396 @lilypond[fragment, relative 1]
397 \property Staff.TimeSignature = \turnOff
398 \property Staff.Clef = \turnOff
402 @item @code{c d e f g a b }
405 @lilypond[fragment, relative 1]
406 \property Staff.TimeSignature = \turnOff
407 \property Staff.Clef = \turnOff
411 @item @code{\clef treble \clef bass }
415 \property Staff.TimeSignature \set #'transparent = ##t
422 @item @code{\time 3/4 \time 4/4 }
426 \property Staff.Clef \set #'transparent = ##t
439 We continue with the introduction of the remaining musical constructs.
440 Normal rests are entered just like notes, but use the name
449 \property Score.timing = ##f
450 \property Staff.Clef = \turnOff
451 \property Staff.TimeSignature = \turnOff
458 @c Tim wants to move this quotes example just before the: quotes-don't-work
459 @c score, but we'd need to remove quotes from the other two (key and
462 @c better to have this just before the `octaves are bad' snipped
463 @c but we'd need to remove the ', from \key and tie
464 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
465 the note name, to lower a note one octave, add a ``low quote'' @code{,}
466 (a comma). The central C is @code{c'}:
470 c'4 c'' c''' \clef bass c c,
474 \property Score.timing = ##f
475 \property Staff.TimeSignature = \turnOff
476 c'4 c'' c''' \clef bass c c,
481 A tie is created by entering a tilde ``@code{~}'' between the notes to
482 be tied. A tie between two notes means that the second note must not be
483 played separately, but just makes the first note sound longer:
486 @lilypond[fragment,verbatim]
492 The key signature is set with the command ``@code{\key}'':
502 \property Staff.TimeSignature = \turnOff
511 @c bit on the long/complex/scary taste
512 @c cheating a bit: two lines makes for a friendlier look
513 This example shows notes, ties, octave marks, and rests in action.
522 r4 r8 d''8 cis''4 e''
524 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
537 r4 r8 d''8 cis''4 e''
539 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
542 \paper { linewidth = 50*\staffspace }
548 There are some interesting points to note in this example.
549 Accidentals (sharps and flats) don't have to be marked explicitly: you
550 just enter the note name, and LilyPond determines whether or not to
551 print an accidental. Bar lines and beams are drawn automatically.
552 LilyPond calculates line breaks for you; it doesn't matter where you
553 make new lines in the source file. Finally, the order of time, key and
554 clef changes is not relevant: lilypond will use standard notation
555 conventions for ordering these items.
557 The example also indicates that a piece of music written in a high
558 register needs lots of quotes. This makes the input less readable,
559 and is therefore also a potential source of errors.
561 The solution is to use ``relative octave'' mode. In practice, this is
562 the most convenient way to copy existing music. To use relative mode,
563 add @code{\relative} before the piece of music. You must also give a
564 note from which relative starts, in this case @code{c''}. If you type
565 no octavation quotes, relative mode chooses the note that is closest
566 to the previous one, which is often just the one you need.
567 @c don't use commas or quotes in this sentence
568 For example: @code{c f} goes up; @code{c g} goes down:
578 \property Score.timing = ##f
579 \property Staff.TimeSignature = \turnOff
587 @c needed better, maybe even redundant explanation
588 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
589 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
590 You can make a large interval by adding octavation quotes. Note that
591 quotes or commas do not determine the absolute height of a note;
592 the height of a note is relative to the previous one.
593 @c don't use commas or quotes in this sentence
594 For example: @code{c f,} goes down; @code{f, f} are both the same;
595 @code{c c'} are the same; and @code{c g'} goes up:
605 \property Score.timing = ##f
606 \property Staff.TimeSignature = \turnOff
617 The following table summarizes the syntax learned in this section.
619 @multitable @columnfractions .3 .3 .4
628 @lilypond[fragment, relative 1]
629 \property Staff.TimeSignature = \turnOff
630 \property Staff.Clef = \turnOff
638 @lilypond[fragment, relative 1]
639 \property Score.timing = ##f
640 \property Staff.TimeSignature = \turnOff
641 \property Staff.autoBeaming = ##f
642 \property Staff.Clef = \turnOff
647 @item @code{\key es \major }
651 \property Staff.TimeSignature \set #'transparent = ##t
660 @lilypond[fragment, relative 1]
661 \property Score.timing = ##f
662 \property Staff.TimeSignature = \turnOff
663 \property Staff.autoBeaming = ##f
664 \property Staff.Clef = \turnOff
671 @lilypond[fragment, relative 1]
672 \property Score.timing = ##f
673 \property Staff.TimeSignature = \turnOff
674 \property Staff.autoBeaming = ##f
675 \property Staff.Clef = \turnOff
681 A slur is drawn across many notes, and indicates bound articulation
682 (legato). The starting note and ending note are marked with a
683 ``@code{(}'' and a ``@code{)}'' respectively:
686 @lilypond[fragment,relative 1, verbatim]
687 d4( )c16( cis d e c cis d )e( )d4
692 If you need two slurs at the same time (one for articulation, one for
693 phrasing), you can also make a phrasing slur with @code{\(} and
698 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
699 @c chromatic thing pasted in front. (admittedly the original doesn't
700 @c have a phrasing slur. The problem is that we don't want the slur
701 @c and the Phrasing slur to collide. We're trying to make a good
705 @lilypond[fragment,relative 1, verbatim]
706 a8(\( ais b ) c cis2 b'2 a4 cis, \) c
711 Beams are drawn automatically, but if you don't like the choices, you
712 can enter beams by hand. Surround the notes to be grouped with @code{[}
715 @lilypond[fragment,relative 1, verbatim]
721 To print more than one staff, each piece of music that makes up a staff
722 is marked by adding @code{\context Staff} before it. These
723 @code{Staff}'s can be grouped inside @code{<} and @code{>}, as is
727 @lilypond[fragment,verbatim]
729 \context Staff = staffA { \clef violin c'' }
730 \context Staff = staffB { \clef bass c }
735 In this example, @code{staffA} and @code{staffB} are names that are
736 given to the staves. It doesn't matter what names you give, as long
737 as each staff has a unique name.
741 We can typeset a melody with two staves now:
744 @lilypond[verbatim,singleline]
747 < \context Staff = staffA {
750 \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
752 \context Staff = staffB {
763 Notice that the time signature is specified in one melody staff only
764 (the top staff), but is printed on both. LilyPond knows that the time
765 signature should be the same for all staves.
769 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
771 @lilypond[verbatim,relative 1]
777 Dynamic signs are made by adding the markings to the note:
779 @lilypond[verbatim,relative 1]
785 Crescendi are started with the commands @code{\<} and @code{\>}. The
786 command @code{\!} finishes a crescendo on the following note.
788 @lilypond[verbatim,relative 1]
789 c2\< \!c2-\ff \>c2 \!c2
794 Chords can be made by surrounding notes with @code{<} and @code{>}:
796 @lilypond[relative 0, fragment,verbatim]
804 @c hmm, te losjes, iig
805 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
806 happens at the same time, like in chords, or (like in the two-staff
807 example above) in a bunch of stacked staves.
810 Of course, you can combine beams and ties with chords. Notice that
811 beam and tie markings must be placed outside the chord markers:
813 @lilypond[relative 0, fragment,verbatim]
814 r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
818 When you want to combine chords with slurs and dynamics, technical
819 detail crops up: you have type these commands next to the notes, which
820 means that they have to be inside the @code{< >}:
825 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
827 @lilypond[relative 0, fragment]
829 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
834 There is one golden rule that you should keep in mind when writing
837 @strong{DO NOT START A PIECE WITH A CHORD}
839 Of course, it is a allowed, but the result might not be what you expect:
841 @lilypond[verbatim,singleline]
842 \score { \notes <c'2 e'2> }
847 If you have a piece that starts with a chord, then you must explicitly
848 state that the notes of the chord are to be put on the same staff, in
849 the same voice. This is done by specifying @code{\context Staff} for
853 @lilypond[verbatim,singleline]
854 \score { \notes \context Voice <c'2 e'2> }
863 @multitable @columnfractions .3 .3 .4
873 @lilypond[fragment, relative 1]
874 \property Score.timing = ##f
875 \property Staff.TimeSignature = \turnOff
876 \property Staff.autoBeaming = ##f
877 \property Staff.Clef = \turnOff
885 @lilypond[fragment, relative 1]
886 \property Score.timing = ##f
887 \property Staff.TimeSignature = \turnOff
888 \property Staff.autoBeaming = ##f
889 \property Staff.Clef = \turnOff
897 @lilypond[fragment, relative 1]
898 \property Score.timing = ##f
899 \property Staff.TimeSignature = \turnOff
900 \property Staff.autoBeaming = ##f
901 \property Staff.Clef = \turnOff
906 @item @code{< \context Staff ... >}
910 < \context Staff = SA { c'1 }
911 \context Staff = SB { c'1 } >
918 @lilypond[fragment, relative 1]
919 \property Staff.TimeSignature = \turnOff
920 \property Staff.Clef = \turnOff
925 @item @code{-\mf -\sfz}
928 @lilypond[fragment, relative 1]
929 \property Staff.TimeSignature = \turnOff
930 \property Staff.Clef = \turnOff
938 @lilypond[fragment, relative 1]
939 \property Score.timing = ##f
940 \property Staff.TimeSignature = \turnOff
941 \property Staff.autoBeaming = ##f
942 \property Staff.Clef = \turnOff
949 @lilypond[fragment, relative 1]
950 \property Score.timing = ##f
951 \property Staff.TimeSignature = \turnOff
952 \property Staff.autoBeaming = ##f
953 \property Staff.Clef = \turnOff
961 @lilypond[fragment, relative 1]
967 You know the basic ingredients of a music file, so this is the right
968 moment to try your at hand at doing it yourself: try to type some
969 simple examples, and experiment a little.
971 When you're comfortable with the basics, then you might want to read
972 the rest of this chapter. It also a manual in tutorial-style, but it
973 is much more in-depth, dealing with more advanced topics such as
974 lyrics, chords, orchestral scores and parts, fine tuning output,
975 polyphonic music, and integrating text and music.
981 @node Printing lyrics
982 @section Printing lyrics
985 In this section we shall explain how to typeset the following
986 fragment of The Free Software Song:
988 @lilypond[singleline]
989 \score { \notes { \addlyrics
990 \notes \relative c' {
992 d'2 c4 b16 ( a g a b a b ) c a2
993 b2 c4 b8 ( a16 g ) a4 g2 }
994 \context Lyrics \lyrics {
996 share the soft -- ware; }
998 \paper { linewidth = -1. }
1004 @cindex @code{\lyrics}
1007 To print lyrics, you must enter them, and then instruct lilypond to
1008 handle the lyrics by printing them.
1009 You can enter lyrics in a special input mode of LilyPond. This mode is
1010 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1011 The purpose of this mode is that you can enter lyrics as plain text,
1012 punctuation and accents without any hassle.
1014 Syllables are entered like notes, with pitches replaced by text. For
1015 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1016 the hyphen has no special meaning for lyrics, and does not introduce
1019 Spaces can be introduced into a lyric either by using quotes:
1020 @code{"He could"4 not4} or by using an underscore without quotes:
1021 @code{He_could4 not4}. All unquoted underscores are converted to
1024 These are the lyrics for the free software song:
1029 share the soft -- ware; @}
1032 As you can see, extender lines are entered as @code{__}. This will
1033 create an extender, a line that extends over the entire duration of
1034 the lyric. This line will run all the way to the start of the next
1035 lyric, so you may want to shorten it by using a blank lyric (using
1039 If you can use have hyphens at the end of a syllable, i.e.
1043 but then the hyphen will be attached to the to the end of the first
1046 If you want them centered between syllables you can use the special
1047 `@code{-}@code{-}' lyric as a separate word between syllables. The
1048 hyphen will have variable length depending on the space between
1049 syllables. It will be centered between the syllables.
1051 Normally, the notes that you enter are transformed into note heads.
1052 Note heads alone make no sense, they need surrounding information: a key
1053 signature, a clef, staff lines, etc. They need @emph{context}. In
1054 LilyPond, these symbols are created by objects called `interpretation
1055 contexts'. Interpretation contexts exist for generating notation
1056 (`notation context') and for generating sound (`performance
1057 context'). These objects only exist during a run of LilyPond.
1059 When LilyPond interprets music, it will create a Staff context.
1060 We don't want that default here, because we want lyric. The
1065 explicitly creates an interpretation context of
1066 @code{Lyrics} type to interpret the song text that we entered.
1068 The melody of the song doesn't offer anything new:
1070 \notes \relative c' @{
1072 d'2 c4 b16 ( a g a b a b ) c a2
1073 b2 c4 b8 ( a16 g ) a4 g2 @}
1076 Both can be combined with the @code{\addlyrics}:
1079 \notes \relative c' @dots{}
1080 \context Lyrics \lyrics @dots{}
1083 The lyrics are also music expressions, similar to notes. What happens
1084 here, is that each syllable of the lyrics is put under the a note of
1086 The complete file is listed here:
1089 \score @{ \notes @{ \addlyrics
1090 \notes \relative c' @{
1092 d'2 c4 b16 ( a g a b a b ) c a2
1093 b2 c4 b8 ( a16 g ) a4 g2 @}
1094 \context Lyrics \lyrics @{
1096 share the soft -- ware; @}
1098 \paper @{ linewidth = -1. @}
1104 @node A melody with chords
1105 @section A melody with chords
1107 In this section we show how to typeset a melody with chord
1108 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1111 \include "paper16.ly"
1112 melody = \notes \relative c' @{
1116 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1117 c4 c8 d [es () d] c4 | d4 es8 d c4.
1121 accompaniment =\chords @{
1123 c2:3- f:3-.7 d:min es4 c8:min r8
1124 c2:min f:min7 g:7^3.5 c:min @}
1129 \context ChordNames \accompaniment
1130 \context Staff = mel @{
1135 \midi @{ \tempo 4=72 @}
1136 \paper @{ linewidth = 10.0\cm @}
1141 The result would look this.
1144 \include "paper16.ly"
1145 melody = \notes \relative c' {
1149 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1150 c4 c8 d [es () d] c4 | d4 es8 d c4.
1154 accompaniment =\chords {
1156 c2:3- f:3-.7 d:min es4 c8:min r8
1157 c2:min f:min7 g:7^3.5 c:min }
1162 \context ChordNames \accompaniment
1164 \context Staff = mel {
1165 \property Staff.autoBeaming = ##f
1169 \midi { \tempo 4=72 }
1170 \paper { linewidth = 10.0\cm }
1174 Again, we will dissect the file line by line.
1179 \include "paper16.ly"
1182 Smaller size for inclusion in a book.
1186 melody = \notes \relative c' @{
1189 The structure of the file will be the same as the previous one, a
1190 @code{\score} block with music in it. To keep things readable, we will
1191 give names to the different parts of music, and use the names to
1192 construct the music within the score block.
1199 @cindex @code{\partial}
1201 The piece starts with an anacrusis of one eighth.
1206 The key is C minor: we have three flats.
1211 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1212 c4 c8 d [es () d] c4 | d4 es8 d c4.
1217 @cindex manual beaming
1218 @cindex automatic beaming, turning off
1219 We use explicit beaming. Since this is a song, we turn automatic
1220 beams off, and use explicit beaming where needed.
1227 This ends the definition of @code{melody}.
1236 @cindex identifier assignment
1237 @cindex syllables, entering
1242 accompaniment =\chords @{
1246 @cindex mode, chords
1247 We'll put chords over the music. To enter them, there is a special mode
1248 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1249 the names of the chords you want, instead of listing the notes
1250 comprising the chord.
1257 There is no accompaniment during the anacrusis.
1266 @cindex chord modifier
1267 @cindex modifier, chord
1268 This is a c minor chord, lasting half a note. Chord are entered by
1269 entering the tonic. Then notes can be changed. In this case, a small third
1270 is used. The cod for this is @code{3-}.
1276 Similarly, @code{7} modifies (adds) a seventh, which is small by
1277 default to create the @code{f a c es} chord. Multiple modifiers must be
1285 Some modifiers have predefined names, e.g. @code{min} is the same as
1286 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1290 c2:min f:min7 g:7^3.5 c:min @}
1293 @cindex named modifier
1295 A named modifier @code{min} and a normal modifier @code{7} do not have
1296 to be separated by a dot. Tones from a chord are removed with chord
1297 subtractions. Subtractions are started with a caret, and they are
1298 also separated by dots. In this example, @code{g:7^3.5} produces a
1299 minor seventh. The brace ends the sequential music.
1307 We assemble the music in the @code{\score} block. Melody, lyrics and
1308 accompaniment have to sound at the same time, so they should be
1309 @code{\simultaneous}.
1310 @cindex @code{\simultaneous}
1317 Chord mode generates notes grouped in @code{\simultaneous} music. If
1318 you remove the comment sign, you can see the chords in normal
1319 notation: they will be printed as note heads on a separate
1320 staff. To print them as chords names, they have to be interpreted as
1321 being chords, not notes. This is done with the following command:
1325 \context ChordNames \accompaniment
1329 @cindex interpretation context
1330 @cindex notation context
1333 Normally, the notes that you enter are transformed into note heads.
1334 Note heads alone make no sense, they need surrounding information: a key
1335 signature, a clef, staff lines, etc. They need @emph{context}. In
1336 LilyPond, these symbols are created by objects called `interpretation
1337 contexts'. Interpretation contexts exist for generating notation
1338 (`notation context') and for generating sound (`performance
1339 context'). These objects only exist during a run of LilyPond.
1341 When LilyPond interprets music, it will create a Staff context. If
1342 the @code{%} sign in the previous line were removed, you could see
1343 that mechanism in action.
1345 We don't want that default here, because we want chord names. The
1346 command above explicitly creates an interpretation context of
1347 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1352 \context Staff = mel @{
1356 We place the melody on a staff called @code{mel}. We give it a name to
1357 differentiate it from the one that would contain note heads for the
1358 chords, if you would remove the comment before the ``note heads''
1359 version of the accompaniment. By giving this staff a name, it is
1360 forced to be different.
1364 \property Staff.autoBeaming = ##f
1368 @cindex context variables
1369 @cindex setting context variables
1370 An interpretation context has variables, called properties, that tune
1371 its behavior. One of the variables is @code{autoBeaming}. Setting
1372 this @code{Staff}'s property to @code{##f}, which is the boolean value
1373 @var{false}, turns the automatic beaming mechanism off for the current
1384 Finally, we put the melody on the current staff. Note that the
1385 @code{\property} directives and @code{\melody} are grouped in sequential
1386 music, so the property settings are done before the melody is
1392 \midi @{ \tempo 4=72@}
1395 MIDI (Musical Instrument Digital Interface) is a standard for
1396 connecting and recording digital instruments. So a MIDI file is like a
1397 tape recording of an instrument. The @code{\midi} block makes the
1398 music go to a MIDI file, so you can listen to the music you entered. It
1399 is great for checking the music. Whenever you hear something weird, you
1400 probably hear a typing error.
1402 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1403 also specifies an output method. You can specify the tempo using the
1404 @code{\tempo} command, in this case the tempo of quarter notes is set to
1405 72 beats per minute.
1409 \paper @{ linewidth = 10.0\cm @}
1412 We also want notation output. The linewidth is short so the piece
1413 will be set in two lines.
1416 @section More stanzas
1421 If you have multiple stanzas printed underneath each other, the vertical
1422 groups of syllables should be aligned around punctuation. LilyPond can
1423 do this if you tell it which lyric lines belong to which melody.
1424 We show how you can do this by showing how you could print a frivolous
1425 fragment of a fictional Sesame Street duet.
1427 @lilypond[singleline,verbatim]
1430 \notes \relative c'' \context Voice = duet { \time 3/4
1432 \lyrics \context Lyrics <
1433 \context LyricsVoice = "duet-1" {
1434 \property LyricsVoice . stanza = "Bert"
1435 Hi, my name is bert. }
1436 \context LyricsVoice = "duet-2" {
1437 \property LyricsVoice . stanza = "Ernie"
1438 Ooooo, ch\'e -- ri, je t'aime. }
1443 To this end, give the Voice context an identity, and set the
1444 LyricsVoice to a name starting with that identity followed by a dash.
1445 In the following example, the Voice identity is @code{duet},
1447 \context Voice = duet @{
1452 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1454 \context LyricsVoice = "duet-1" @{
1455 Hi, my name is bert. @}
1456 \context LyricsVoice = "duet-2" @{
1457 Ooooo, ch\'e -- ri, je t'aime. @}
1460 We add the names of the singers. This can be done by setting
1461 @code{LyricsVoice.Stanza} (for the first system) and
1462 @code{LyricsVoice.stz} for the following systems. Notice how you must
1463 surround dots with spaces in @code{\lyrics} mode.
1466 \property LyricsVoice . stanza = "Bert"
1468 \property LyricsVoice . stanza = "Ernie"
1471 The convention for naming @code{LyricsVoice} and @code{Voice} must
1472 also be used to get melismata on rests correct.
1476 @node More movements
1477 @section More movements
1479 LilyPond only handles formatting sheet music. It doesn't concern
1480 itself with producing titles. This is the jobs of a simple wrapper
1481 program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
1482 sheet music formatting. Then it produces titles, and ties together all
1483 inputs into a single @file{dvi} file. In this section, we show some of
1484 the options for titling. We will show how you can produce a file
1485 that looks like this:
1487 @center @strong{Two miniatures}
1497 \paper { linewidth = -1.0 }
1509 \paper { linewidth = -1.0 }
1513 For example, consider the following file (@file{miniatures.ly})
1518 title = "Two miniatures"
1519 composer = "F. Bar Baz"
1520 tagline = "small is beautiful" @}
1522 \paper @{ linewidth = -1.0 @}
1526 Mental note: discuss Schenkerian analysis of these key pieces.
1532 \notes @{ c'4 d'4 @}
1538 \notes @{ d'4 c'4 @}
1545 The information for the global titling is in a so-called header block.
1546 The information in this block is not used by
1547 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
1548 information to print titles above the music.
1550 @cindex identifier assignment
1551 the @code{\header} block contains assignments. In each assignment, a
1552 variable is set to a value. The header block for this file looks like
1554 @cindex @code{\header}
1557 title = "Two miniatures"
1558 composer = "F. Bar Baz"
1559 tagline = "small is beautiful"
1563 When you process a file with ly2dvi, a signature line is printed at
1564 the bottom of the last page. This signature is produced from the
1565 @code{tagline} field of @code{\header}. The default "Lily was here,
1566 @var{version number}" is convenient for us programmers. Archived
1567 the layout of different versions can be compared using archived
1568 print-outs (that include a version number).
1570 @cindex Lily was here
1571 @cindex signature line
1574 Many people find the default tagline (``Lily was here'') too droll.
1575 If that is the case, assign something else to @code{tagline}, as shown
1584 A paper block at top level, i.e. not in a @code{\score} block sets the
1585 default page layout. The following @code{\score} blocks don't have
1586 @code{\paper} sections, so the settings of this block are substituted:
1588 The variable @code{linewidth} normally sets the length of the systems
1589 on the page. However, a negative value has a special meaning. If
1590 @code{linewidth} is less than 0, no line breaks are inserted into the
1591 score, and the spacing is set to natural length: a short phrase takes
1592 up little space, a longer phrase more space.
1597 Mental note: discuss Schenkerian analysis of these key pieces.
1602 Mental notes to yourself can be put into comments. There are two types
1603 of comments. Line comments are introduced by @code{%}, and block
1604 comments are delimited by @code{%@{} and @code{%@}}.
1609 \notes @{ c'4 d'4 @}
1612 In previous examples, notes were specified in relative octaves,
1613 i.e. each note was put in the octave that is closest to its
1614 predecessor. Besides relative, there is also absolute octave
1615 specification, which you get when you don't specify @code{\relative}. In
1616 this input mode, the central C is denoted by @code{c'}. Going down, you
1617 get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
1620 When you're copying music from existing sheet music, relative octaves
1621 are probably the easiest to use: it's less typing work and errors are
1622 easily spotted. However, if you write LilyPond input directly, either by
1623 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1631 The @code{\header} is normally at the top of the file, where it sets
1632 values for the rest of the file. If you want to typeset different pieces
1633 from one file (for example, if there are multiple movements, or if
1634 you're making an exercise book), you can put different @code{\score}
1635 blocks into the input file. ly2dvi will assemble all LilyPond output
1636 files into a big document. The contents of \header blocks specified
1637 within each score, are used for the titling of each movement.
1643 For example, the Opus number is put at the right, and the piece string
1644 will be at the left.
1651 title = "Two miniatures"
1652 composer = "F. Bar Baz"
1653 tagline = "small is beautiful" @}
1655 \paper @{ linewidth = -1.0 @}
1658 \notes @{ c'4 d'4 @}
1664 \notes @{ d'4 c'4 @}
1676 Lilypond and its language are still under development, and
1677 occasionally, details of the syntax are changed. This fragment
1678 indicates for which version the input file was written. When you
1679 compile this file, the version number will be checked, and you will
1680 get a warning when the file is too old. This version number is also
1681 used by the @code{convert-ly} program (See @ref{Older
1682 LilyPond versions}), which is used to update the file to the latest
1686 @node A piano excerpt
1687 @section A piano excerpt
1689 Our fourth subject is a piece of piano music. The fragment in the
1690 input file is a piano reduction of the G major Sinfonia by Giovanni
1691 Battista Sammartini. It was composed around 1740. It's in the source
1692 package under the name @file{input/tutorial/sammartini.ly}.
1694 @lilypondfile[smallverbatim]{sammartini.ly}
1696 As you can see, this example features multiple voices on one staff. To
1697 make room for those voices, their notes have to be stemmed in opposite
1700 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1701 with some other commonly used formatting instructions, but to explain how
1702 it works, we wrote our own here. Of course, you should use predefined
1703 identifiers like these if possible: then you will be affected less by
1704 the implementation changes we occasionally make.
1708 viola = \notes \relative c' \context Voice = viola @{
1710 In this example, you can see multiple parts on a staff. Each part is
1711 associated with one notation context. This notation context handles
1712 stems and dynamics (among others). The type name of this context is
1713 @code{Voice}. For each part we have to make sure that there is
1714 precisely one @code{Voice} context, so we give it a unique name
1721 The delimiters @code{<} and @code{>} are shorthands for
1722 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1723 @code{<} and @code{>} is a chord.
1727 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1735 We want the viola to have stems down, and have all the other
1736 characteristics of a second voice. This is enforced using the
1737 @code{\voiceTwo} command: it inserts instructions that makes stem,
1738 ties, slurs, etc. go down.
1746 Relative octaves work a little differently with chords. The starting
1747 point for the note following a chord is the first note of the chord. So
1748 the @code{g} gets an octave up quote: it is a fifth above the starting
1749 note of the previous chord (the central C).
1755 @code{s} is a spacer rest. It does not print anything, but it does have
1756 the duration of a rest. It is useful for filling up voices that
1757 temporarily don't play. In this case, the viola doesn't come until one
1758 and a half measure later.
1762 oboes = \notes \relative c'' \context Voice = oboe @{
1764 Now comes a part for two oboes. They play homophonically, so we
1765 print the notes as one voice that makes chords. Again, we insure that
1766 these notes are indeed processed by precisely one context with
1770 \voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
1773 The oboes should have stems up, so they should have stems up, to keep
1774 them from interfering with the staff-jumping bass figure.
1778 \grace <e8( g> < d4 )f> <c2 e>
1780 @cindex @code{\grace}
1783 @code{\grace} introduces grace notes. It takes one argument, in this
1784 case a chord. A slur is introduced starting from the @code{\grace}
1785 ending on the following chord.
1793 Tuplets are made with the @code{\times} keyword. It takes two
1794 arguments: a fraction and a piece of music. The duration of the piece
1795 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1796 of their notated duration, so in this case the fraction is 2/3.
1799 @{ <d8 f> <e g> <f a> @}
1801 The piece of music to be `tripletted' is sequential music containing
1808 At this point, the homophonic music splits into two rhythmically
1809 different parts. We can't use a sequence of chords to enter this, so
1810 we make a `chord' of sequences to do it. We start with the upper
1811 voice, which continues with upward stems:
1814 @{ \times 2/3 @{ a8 g c @} c2 @}
1821 The easiest way to enter multiple voices is demonstrated
1822 here. Separate the components of the voice (single notes or entire
1823 sequences) with @code{\\} in a simultaneous music expression. The
1824 @code{\\} separators split first voice, second voice, third voice, and
1827 As far as relative mode is concerned, the previous note is the
1828 @code{c'''2} of the upper voice, so we have to go an octave down for
1836 This ends the two-part section.
1840 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1845 @code{\stemBoth} ends the forced stem directions. From here, stems are
1846 positioned as if it were single part music.
1848 The bass has a little hoom-pah melody to demonstrate parts switching
1849 between staves. Since it is repetitive, we use repeats:
1852 hoomPah = \repeat unfold 8
1854 @cindex unfolded @code{\repeat}
1855 The unfolded repeat prints the notes in its argument as if they were
1856 written out in full eight times.
1859 \notes \transpose c' @{
1862 @cindex relative mode and transposing
1864 Transposing can be done with @code{\transpose}, which takes two arguments.
1865 The first specifies what central C should be transposed to. The second
1866 is the to-be-transposed music. As you can see, in this case, the
1867 transposition has no effect, as central C stays at central C.
1869 The purpose of this no-op is to protect it from being interpreted as
1870 relative notes. Relative mode can not be used together with
1871 transposition, so @code{\relative} will leave the contents of
1872 @code{\hoomPah} alone. We can use it without having to worry about
1873 getting the motive in a wrong octave.
1875 @cindex staff switch, manual
1876 @cindex cross staff voice, manual
1877 @cindex @code{\translator}
1880 \translator Staff = down
1883 \translator Staff = up
1887 Voices can switch between staves. Here you see two staff switching
1888 commands. The first one moves to the lower staff, the second one to
1889 the lower one. If you set stem directions explicitly (using the
1890 identifiers @code{\stemUp} and @code{\stemDown}.
1894 bassvoices = \notes \relative c' @{
1896 \autochange Staff \hoomPah \context Voice
1901 \translator Staff = down
1903 @cindex staff switch
1904 @cindex cross staff voice
1905 We want the remaining part of this melody on the lower staff, so we do a
1906 manual staff switch here.
1911 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1915 After skipping some lines, we see @code{~}. This mark makes ties. Note
1916 that ties and slurs are different things. A tie can only connect two
1917 note heads of the same pitch, whereas a slur can connect many chords
1924 A special context is needed to get cross staff beaming right. This
1925 context is called @code{PianoStaff}.
1928 \context Staff = bottom < \time 2/2 \clef bass
1930 The bottom staff must have a different clef.
1935 To make some more room on the line, the first (in this case the only)
1936 line is not indented. The line still looks very cramped, but that is due
1937 to the page layout of this document.
1943 * font-size, multi-stanza.
1945 * Simple part combining in a Hymn
1949 @node Fine tuning a piece
1950 @section Fine tuning a piece
1952 In this section, we show some ways to fine tune the final output of a
1953 piece. We do so using a single measure of a moderately complex piano
1954 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
1955 tuned and the untuned are in the @file{input/tutorial/}).
1957 The code for the untuned example shows us some new things.
1959 @lilypondfile[verbatim]{brahms-original.ly}
1969 The crescendo is ended at the half note by the escaped exclamation
1972 Hairpin dynamics can be indicated using @code{\>} to start a
1973 decrescendo, and @code{\!} to end one. The crescendo is started using
1974 @code{\<} and also ended using @code{\!}. Absolute dynamics can be
1975 entered using @code{\p}, @code{\mf}, etc. All these commands apply to
1976 the complete chord where they are entered, but for syntactical
1977 reasons, they must be attached to one of the notes of the chord.
1979 @cindex fingering instructions
1981 Fingering indications are entered simply using @code{-@var{N}}, where
1984 Now that we have the basic piece of music entered, we want to fine
1985 tune it, so we get something that resembles the original printed
1986 edition by Schott/Universal Edition:
1988 @lilypondfile{brahms-tweaked.ly}
1990 @cindex tuning grob behavior
1992 The basic process that we follow is that we override defaults in the
1993 printing system. We do this by setting variables in so-called grobs.
1994 Printed symbols are internally represented by Graphical Objects
1995 (Grobs). Each grob is described by a bunch of settings. Every
1996 setting is a variable: it has a name, and you can assign a value to
1997 the variable. These setting determine the fonts, offsets, sub-routines
1998 to be called on the grob, etc. The initial values of these settings
1999 are set in the Scheme file @file{scm/grob-description.scm}.
2001 @cindex slur attachments
2003 We start with the slur: the slur in the upper part, running from the F
2004 sharp to the A, runs from stem to stem in the printed edition, while
2005 ours starts from the note head at the left. The following property
2006 setting forces all slurs to run from stem to stem (and not from or to
2010 \property Voice.Slur \set #'attachment = #'(stem . stem)
2013 More precisely, this command extends the definition of the @code{Slur}
2014 object in the current @code{Voice}. The variable @code{attachment} is
2015 set to the pair of symbols @code{'(stem . stem)}.
2017 Although this is useful information, it is not very helpful: the
2018 lilypond backend supports approximately 240 variables like
2019 @code{attachment}, each with their own meaning and own type
2020 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2021 different types of Grobs, that may be created in 14 different context
2022 types besides Voice.
2024 @cindex internal documentation
2025 @cindex finding grobs
2026 @cindex grob descriptiosn
2028 The interesting information is how you can figure out which properties
2029 to tune for your own scores. To discover this, you must have a copy of
2030 the internals document. This is a set of HTML pages, which should be
2031 included if you run a binary distribution@footnote{You can also
2032 compile them by executing @code{make -C Documentation/user/
2033 out/lilypond-internals.html} in the source package.}. This document is
2034 also available on the web: go to the lilypond website, click
2035 ``Documentation: other'' on the side bar, click
2036 ``lilypond-internals'', under information for users.
2038 You might want to bookmark either the HTML files on disk, or the one
2039 on the web. One word of caution is in place here: the internals
2040 documentation is generated from the definitions that lily uses. For
2041 that reason, it is strongly tied to the version of LilyPond that you
2042 use. Before you proceed, please make sure that you are using the
2043 documentation that corresponds to the LilyPond version that you use.
2045 Suppose that you wanted to tune the behavior of the slur. The first
2046 step is to get some general information on slurs in lilypond. Turn to
2047 the index, and look up ``slur''. The section on slurs says
2049 The grob for this object is @internalsref{Slur}, generally in
2050 @internalsref{Voice} context.
2053 So the grob for this object is called @code{Slur}, and slurs are
2054 created in the @code{Voice} context. If you are reading this tutorial
2055 in the HTML version, then you can simply click Slur, otherwise, you
2056 must look it up the internal documentation: click ``grob overview'' ,
2057 and select ``slur'' (the list is alphabetical.)
2059 Now you get a list of all the properties that the slur object
2060 supports, along with their default values. Among the properties we
2061 find the @code{attachment} property with its default setting.
2062 The property documentation explains that the following setting will
2063 produce the desired effect:
2065 \property Voice.Slur \set #'attachment = #'(stem . stem)
2068 If you ran the previous example, you have unknowingly already used
2069 this kind of command. The @file{ly/property-init.ly} contains the
2070 definition of @code{\stemUp}
2072 stemUp = \property Voice.Stem \set #'direction = #1
2076 We also want to move around the fingering `3'. In the printed edition
2077 it is not above the stem, but a little lower, slightly left of the
2078 stem. From the user manual, we find that the associated grob is called
2079 @code{Fingering}, but how do we know if we should use @code{Voice} or
2080 @code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
2081 also deduce this information from the internals documentation: if you
2082 visit the documentation of @code{Fingering}, you will notice
2084 Fingering grobs are created by: Fingering_engraver
2089 Clicking @code{Fingering_engraver} will show you the documentation of
2090 the module responsible for interpreting the fingering instructions and
2091 translating them to a @code{Fingering} grob. Such a module is called
2092 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2095 Fingering_engraver is part of contexts: Voice and TabVoice
2097 so tuning the settings for Fingering should be done using either
2099 \property Voice.Fingering \set @dots{}
2103 \property TabVoice.Fingering \set @dots{}
2106 Since the @code{TabVoice} is only used for tab notation, we see that
2107 the first guess @code{Voice} was indeed correct.
2109 @cindex setting grob properties
2110 @cindex @code{extra-offset}
2112 For shifting the fingering, we use the grob property
2113 @code{extra-offset}. The following command manually adds an offset to
2114 the object. We move it a little to the left, and 1.8 staff space
2117 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2119 The @code{extra-offset} is a low-level feature: it moves around
2120 objects in the printout; the formatting engine is completely oblivious
2121 to these offsets. The unit of these offsets are staff-spaces.
2123 @cindex reverting grob properties
2124 @cindex undoing grob properties
2126 We only want to offset a single grob, so after the F-sharp, we must
2127 undo the setting. The technical term is to revert the grob property.
2129 \property Voice.Fingering \revert #'extra-offset
2132 @cindex property types
2133 @cindex translator properties
2134 @cindex grob properties
2135 @cindex music properties
2138 There is three different types of variables in LilyPond, something
2139 which is confusing at first (and for some, it stays like that).
2140 Variables such as @code{extra-offset} and @code{attachment} are called
2141 grob properties. They are something different from the translator
2142 properties, like @code{autoBeaming}. Finally, music expressions are
2143 internally also stored using properties, so-called music
2144 properties. You will encounter the latter type if you run Scheme
2145 functions on music using @code{\apply}.
2147 The second fingering instruction should be moved up a little, to avoid
2148 a collision with the slur. This could be achieved with
2149 @code{extra-offset}, but in this case, a simpler mechanism also
2150 works. We insert an empty text between the 5 and the note. The empty
2151 text pushes the fingering instruction away:
2153 a^" "^#'(finger "5")
2156 Lilypond tries to put fingering instructions closer to the notes as
2157 text instructions. To insert an empty text (@code{^" "}) between the
2158 finger and the note, we have disguised the fingering instruction as a
2159 text: @code{(finger "5")}.
2161 Normally, one would specify dynamics in a single voice, and start and
2162 end dynamics (such as @b{f} and @b{p}) will be aligned with
2163 hairpins. In this case, we want the decrescendo to be in a different
2164 place from the piano sign. We achieve this by putting the dynamic
2165 markings in different voices. The crescendo should be above the upper
2166 staff. This can be forced by the precooked command
2171 However, if you do that, the decrescendo will be too close to the
2172 upper voice, and collide with the stems. Looking at the manual for
2173 dynamics, we notice that ``Vertical positioning of these symbols is
2174 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2175 to the documentation of @code{DynamicLineSpanner}, we find that the
2176 @code{DynamicLineSpanner} supports several so-called
2177 `interfaces'. This grob not only puts dynamic objects next to the
2178 staff (@code{side-position-interface}), but it also groups dynamic
2179 objects (@code{axis-group-interface}), is considered a dynamic sign
2180 itself (@code{dynamic-interface}) and is a grob: it has the
2181 @code{grob-interface}, with all the variables that come with it.
2183 For the moment, we are interested in the side positioning:
2185 side-position-interface
2187 Position a victim object (this one) next to other objects (the
2188 support). In this case, the direction signifies where to put the
2189 victim object relative to the support (left or right, up or down?)
2191 Between the grob and its support (in this case: the notes in the voice
2192 going down), there should be more space. This space is controlled by
2193 @code{padding}, so we increase it.
2195 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2198 This command is almost like the command for setting slur attachments,
2199 but subtly different in its details. Grob properties can be
2200 manipulated with two commands: @code{\override} extends the grob
2201 variables with a setting, and @code{\revert} releases this
2202 setting. This has a certain theoretical appeal: the operations are
2203 simple and symmetric. For practical use, it can be cumbersome. Both
2204 commands act like parentheses: you should carefully balance the use of
2205 @code{\override} and @code{\revert}. The @code{\set} command is more
2206 friendly: it first does a @code{\revert} followed by @code{\override}.
2208 Finally, Brahms uses music notation is a slightly unorthodox way. Ties
2209 usually happen only within one voice. In this piece, the composer
2210 gladly produces ties that jump voices. We deal with this by faking
2211 these ties: whenever we need such a tie, we insert a notehead in a
2212 different voice, and blank the stem. This is done in the following
2216 \property Voice.Stem \set #'transparent = ##t
2218 \property Voice.Stem \revert #'transparent
2221 Finally, the last tie is forced up using @code{\tieUp}.
2224 @node An orchestral score
2225 @section An orchestral score
2229 * Extracting an individual part::
2233 Our last two examples show a way to setup the music for an orchestral
2234 score. When typesetting a piece for several instruments, you'll want to
2235 create a conductor's full score, alongside several individual parts.
2237 LilyPond is well suited for this task. We will declare the music for
2238 each instrument individually, giving the music of each instrument its
2239 own name. These pieces of music are then combined in different
2240 @code{\score} blocks to produce different combinations of the score.
2242 This orchestral score example consists of three input files. In the
2243 first file, @file{os-music.ly}, we define the music for all
2244 instruments. This file will be used both for producing the score and
2245 the separate parts. Other files reference this file by doing
2246 @code{\include "os-music.ly"}.
2248 If you were to run LilyPond on this file, no printable output would be
2254 title = "Zo, goed lieverd?"
2255 subtitle = "How's, this babe?"
2264 Key = \notes \key as \major
2265 flautoI = \notes\relative c'' @{
2267 bes as bes as bes as bes as
2269 flautoII = \notes\relative c'' @{
2270 as8 bes as bes R1 d4 ~ d
2272 tromboI = \notes\relative c'' @{
2273 c4. c8 c8 c4. es4 r as, r
2275 tromboII = \notes\relative c'' @{
2276 as4. as8 as8 as4. R1*1/2 as4 es'
2278 timpani = \notes\relative c, @{
2279 \times 2/3 @{ f4 f f @}
2280 \times 4/5 @{ as8 as as as as @}
2283 corno = \notes\relative c' @{
2284 bes4 d f, bes d f, bes d
2288 We will not go through the input line by line, but only indicate and
2289 explain the new elements.
2296 \skip 2*4 \bar "|.";
2300 Declare setting to be used globally. The @code{\skip} command produces
2301 no output, but moves forward in time: in this case, the duration of a
2302 half note (@code{2}), and that four times (@code{*4}). This brings us
2303 to the end of the piece, and we can set the end bar.
2307 Key = \notes \key as \major
2309 Declare the key signature of the piece and assign it to the identifier
2310 @var{Key}. Later on, we'll use @code{\Key} for all staves except those
2311 for transposing instruments.
2313 @node The full score
2314 @subsection The full score
2317 The second file, @file{input/tutorial/os-score.ly} reads the definitions of the first
2318 (@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
2324 \include "os-music.ly"
2325 \include "paper13.ly"
2327 #(set! point-and-click line-column-location)
2328 #(define text-flat '((font-relative-size . -2)
2329 (music "accidentals--1")))
2334 \property Score.BarNumber \override #'padding = #3
2335 \context StaffGroup = woodwind <
2336 \context Staff = flauti <
2337 \property Staff.midiInstrument = #"flute"
2338 \property Staff.instrument = "2 Flauti"
2339 \property Staff.instr = "Fl."
2341 \context Voice=one @{ \voiceOne \flautoI @}
2342 \context Voice=two @{ \voiceTwo \flautoII @}
2345 \context StaffGroup = timpani <
2346 \context Staff = timpani <
2347 \property Staff.midiInstrument = #"timpani"
2348 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2349 \property Staff.instr = #"Timp."
2355 \context StaffGroup = brass <
2356 \context Staff = trombe <
2357 \property Staff.midiInstrument = #"trumpet"
2358 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2359 \property Staff.instr = #`(lines "Tbe." "(C)")
2361 \context Voice=one \partcombine Voice
2362 \context Thread=one \tromboI
2363 \context Thread=two \tromboII
2365 \context Staff = corni <
2366 \property Staff.midiInstrument = #"french horn"
2367 \property Staff.instrument = #`(lines "Corno"
2368 (columns "(E" ,text-flat ")"))
2369 \property Staff.instr = #`(lines "Cor."
2370 (columns "(E" ,text-flat ")"))
2371 \property Staff.transposing = #3
2372 \notes \key bes \major
2373 \context Voice=one \corno
2378 indent = 15 * \staffspace
2379 linewidth = 60 * \staffspace
2380 textheight = 90 * \staffspace
2382 \HaraKiriStaffContext
2391 @center @strong{Zo, goed lieverd?}
2393 @center How's, this babe?
2401 @lilypondfile{os-score.ly}
2405 \include "os-music.ly"
2407 First, we need to include the music definitions we made in
2412 #(set! point-and-click line-column-location)
2415 This piece of Scheme code sets the Scheme variable
2416 @code{point-and-click} to the value @var{line-column-location} (which
2417 itself is a Scheme procedure).
2419 Editing input files can be complicated if you're working with large
2420 files: if you're digitizing existing music, you have to synchronize
2421 the .ly file, the sheet music on your lap and the sheet music on the
2422 screen. The point-and-click mechanism makes it easy to find the
2423 origin of an error in the LY file: when you view the file with Xdvi
2424 and click on a note, your editor will jump to the spot where that note
2425 was entered. For more information, see @ref{Point and click}.
2430 #(define text-flat '((font-relative-size . -2)
2431 (music "accidentals--1")))
2434 When naming the tuning of the french horn, we'll need a piece of text
2435 with a flat sign. LilyPond has a mechanism for font selection and
2436 kerning called Scheme markup text (See @ref{Text markup}). The flat
2437 sign is taken from the music font, and its name is @code{accidentals--1}
2438 (The natural sign is called @code{accidentals-0}). The default font is
2439 too big for text, so we select a relative size of @code{-2}.
2446 Of course, all staves are simultaneous and use the same global settings.
2450 \property Score.BarNumber \override #'padding = #3
2452 LilyPond prints bar numbers at the start of each line, but
2453 unfortunately, they end up a bit too close to the staff in this
2454 example. A bar number internally is a Grob called @var{BarNumber}.
2455 BarNumber Grobs can be manipulated through their
2456 @var{side-position-interface}. One of the properties of a
2457 @var{side-position-interface} that can be tweaked is the
2458 @var{padding}: the amount of extra space that is put between this Grob
2459 and other Grobs. We set the padding to three staff spaces.
2461 You can find information on all these kind of properties in LilyPond's
2462 automatically generated documentation in
2464 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
2467 the online documentation.
2472 \context StaffGroup = woodwind <
2473 \context Staff = flauti <
2475 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2476 hold one or more @code{Staff}'s, and will print a big bracket at the
2477 left of the score. Start a new staff group for the woodwind section
2478 (just the flutes in this case). Immediately after that, we start the
2479 staff for the two flutes, that also play simultaneously.
2483 \property Staff.midiInstrument = #"flute"
2485 Specify the instrument for MIDI output (see @ref{MIDI instrument
2490 \property Staff.instrument = "2 Flauti"
2491 \property Staff.instr = "Fl."
2493 And define the instrument names to be printed in the margin,
2494 @code{instrument} for the first line of the score, @code{instr} for the
2501 The flutes play in the default key.
2505 \context Voice=one @{ \voiceOne \flautoI @}
2506 \context Voice=two @{ \voiceTwo \flautoII @}
2508 Last come the actual flute parts. Remember that we're still in
2509 simultaneous mode. We name both voices differently, so that LilyPond
2510 will actually create two Voice contexts. The flute parts are simple, so
2511 we specify manually which voice is which: @code{\voiceOne} forces the
2512 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2520 Close the flutes staff and woodwind staff group.
2524 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2526 The timpani staff only shows a new piece of scheme markup, it sets two
2531 \context Voice=one \partcombine Voice
2532 \context Thread=one \tromboI
2533 \context Thread=two \tromboII
2535 You have seen the notation contexts Staff and Voice, but here's a new
2536 one: Thread. One or more Threads can be part of a Voice. The Thread
2537 takes care of note heads and rests, the Voice combine note heads onto a
2540 For the trumpets we use the automatic part combiner (see @ref{Automatic
2541 part combining}) to combine the two simultaneous trumpet parts onto the
2542 trumpet staff. Each trumpet gets its own Thread context, which must be
2543 named @code{one} and @code{two}). The part combiner makes these two
2544 threads share a Voice when they're similar, and splits the threads up
2545 when they're different.
2549 \property Staff.instrument = #`(lines "Corno"
2550 (columns "(E" ,text-flat ")"))
2552 The french horn has the most complex scheme markup name, made up of two
2553 lines of text. The second line has three elements (columns), the @code{(E},
2554 the flat sign @code{text-flat} that we defined before and a final @code{")"}.
2555 Note that we use a backquote instead of an ordinary quote at the
2556 beginning of the Scheme expression to be able to access the
2557 @code{text-flat} identifier, `unquoting' it with a @code{,}.
2561 \property Staff.transposing = #3
2563 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
2564 transpose this staff by three steps.
2566 Note how we can choose different tuning for entering, printing and
2567 playing, using @code{\transpose} and the MIDI Staff property
2572 \notes \key bes \major
2574 Therefore, it has a different key.
2578 indent = 15 * \staffspace
2579 linewidth = 60 * \staffspace
2581 We specify a big indent for the first line and a small linewidth for this
2586 Usually, LilyPond's predefined setup of notation contexts (Thread,
2587 Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
2588 want a different type of Staff context.
2592 \HaraKiriStaffContext
2596 In orchestral scores, it often happens that one instrument has only
2597 rests during one line of the score. The @code{HaraKiriStaffContext} can
2598 be used as a regular @code{StaffContext} drop-in and will take care of
2599 the automatic removing of empty staves.
2601 @node Extracting an individual part
2602 @subsection Extracting an individual part
2604 The third file, @file{os-flute-2.ly} also reads the definitions of the
2605 first (@file{os-music.ly}), and defines the @code{\score} block for the
2609 \include "os-music.ly"
2610 \include "paper16.ly"
2614 \property Score.skipBars = ##t
2615 \property Staff.midiInstrument = #"flute"
2621 instrument = "Flauto II"
2624 linewidth = 80 * \staffspace
2625 textheight = 200 * \staffspace
2633 @center @strong{Zo, goed lieverd?}
2635 @center How's, this babe?
2636 @center @emph{Flauto II}
2643 @lilypondfile{os-flute-2.ly}
2646 Because we separated the music definitions from the @code{\score}
2647 instantiations, we can easily define a second score with the music of
2648 the second flute. This then is the part for the second flute player.
2649 Of course, we make separate parts for all individual instruments.
2655 In this individual part the second flute has a whole staff for itself,
2656 so we don't want to force stem or tie directions.
2661 instrument = "Flauto II"
2664 The @code{\header} definitions were also read from @file{os-music.ly},
2665 but we need to set the instrument for this particular score.
2669 \property Score.skipBars = ##t
2671 In the conductor's full score, all bars with rests are printed, but for
2672 the individual parts, we want to contract pieces of consecutive empty
2673 bars. LilyPond will do this if Score's @var{skipBars} property to
2677 @node Integrating text and music
2678 @section Integrating text and music
2680 Sometimes, you might want to use music examples in a text that you are
2681 writing. For example, if you are writing a musicological treatise, a
2682 songbook, or (like us) the LilyPond manual. You can make such texts by
2683 hand, simply by importing a PostScript figure into your wordprocessor.
2684 However, there is a also an automated procedure:
2686 If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond
2687 code. A script called @code{lilypond-book} will extract the music
2688 fragments, run LilyPond on them, and put back the resulting notation.
2689 This utility program is described fully in the chapter @ref{Insert
2690 music snippets into your texts using lilypond-book}. Here we show a
2691 small example. Since the example also contains explanatory text, we
2692 won't comment on the contents.
2695 \documentclass[a4paper]@{article@}
2698 In a lilypond-book document, you can freely mix music and text. For
2701 \score @{ \notes \relative c' @{
2702 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2705 Notice that the music line length matches the margin settings of the
2708 If you have no \verb+\score+ block in the fragment,
2709 \texttt@{lilypond-book@} will supply one:
2715 In the example you see here, a number of things happened: a
2716 \verb+\score+ block was added, and the line width was set to natural
2717 length. You can specify many more options using \LaTeX style options
2720 \begin[verbatim,11pt,singleline,
2721 fragment,relative,intertext="hi there!"]@{lilypond@}
2725 \texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
2726 the default music size, \texttt@{fragment@} adds a score block,
2727 \texttt@{relative@} uses relative mode for the fragment, and
2728 \texttt@{intertext@} specifies what to print between the
2729 \texttt@{verbatim@} code and the music.
2731 If you include large examples into the text, it may be more convenient
2732 to put the example in a separate file:
2734 \lilypondfile[printfilename]@{sammartini.ly@}
2736 The \texttt@{printfilename@} option adds the file name to the output.
2741 Under Unix, you can view the results as follows.
2744 $ lilypond-book --outdir=out/ lilbook.tex
2745 lilypond-book (GNU LilyPond) 1.3.146
2746 Reading `input/tutorial/lilbook.tex'
2747 Reading `input/tutorial/sammartini.ly'
2748 @var{lots of stuff deleted}
2749 Writing `out/lilbook.latex'
2751 $ latex lilbook.latex
2752 @var{lots of stuff deleted}
2756 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2757 and running latex creates a lot of temporary files, and you wouldn't want
2758 those to clutter up your working directory. Hence, we have them created
2759 in a separate subdirectory.
2761 The result more or less looks like this:
2765 In a lilypond-book document, you can freely mix music and text. For
2768 \score { \notes \relative c' {
2769 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2772 Notice that the music line length matches the margin settings of the
2775 If you have no @code{\score} block in the fragment,
2776 @code{lilypond-book} will supply one:
2782 In the example you see here, a number of things happened: a
2783 @code{\score} block was added, and the line width was set to natural
2784 length. You can specify many more options using La@TeX{} style options
2787 @lilypond[verbatim,11pt,singleline,
2788 fragment,relative,intertext="hi there!"]
2792 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2793 the default music size, @code{fragment} adds a score block,
2794 @code{relative} uses relative mode for the fragment, and
2795 @code{intertext} specifies what to print between the
2796 @code{verbatim} code and the music.
2798 If you include large examples into the text, it may be more convenient
2799 to put the example in a separate file:
2801 @lilypondfile[printfilename]{sammartini.ly}
2803 The @code{printfilename} option adds the file name to the output.
2804 @node End of tutorial
2805 @section End of tutorial
2807 This is the end of the tutorial. If you came up till here, and
2808 have understood everything, then you're now an accomplished lilypond
2809 hacker. From here, you can try fiddling with input
2810 files, coming back to the reference manual for information.
2811 Also don't forget to check out the
2813 @uref{../../templates/out-www/templates.html,templates},
2814 @uref{../../test/out-www/test.html,example} and
2815 @uref{../../regression/out-www/regression.html,feature test}
2819 templates, example and feature test snippets.
2821 If you want to see real action lilypond, then head over to
2822 @uref{http://www.mutopiaproject.org}, which has many examples of
2823 classical music typeset by LilyPond.