4 @c * LilyPond Lilypond lilypond (sometimes: the program)
5 @c * more details about running lilypond; error messages,
6 @c compiling/viewing (emacs?)
7 @c * where to go from First steps+More basics?
13 <!--- @@WEB-TITLE@@=Tutorial --->
17 * First steps:: Music language of LilyPond
18 * Running LilyPond:: Printing music
21 * A melody with chords ::
23 * More movements :: Joining separate pieces of music
24 * A piano excerpt:: Piano music
25 * Fine tuning a piece::
26 * An orchestral score:: Conductor's score and individual parts
27 * Integrating text and music:: Integrating text and music
28 * End of tutorial:: The end
31 Operating lilypond is done through text files: To print a piece of
32 music, you enter the music in a file. When you run lilypond (normally
33 using the program @code{ly2dvi}) on that file, the program produces
34 another file which contains sheet music that you can print or view.
36 This tutorial starts with a small introduction to the LilyPond music
37 language. After this first contact, we will show you how to run
38 LilyPond to produce printed output; you should then be able to create
39 your first sheets of music. The tutorial continues with more and more
46 We start off by showing how very simple music is entered in LilyPond:
47 you get a note simply by typing its @htmlref{note name}, from @samp{a}
48 through @samp{g}. So if you enter
55 then the result looks like this:
58 @c \transpose c c' { c d e f g a b }
60 @c \property Score.timing = ##f
61 @lilypond[notime, relative=2]
65 We will continue with this format: First we show a snippet of input,
66 then the resulting output.
68 The length of a note is specified by adding a number, @samp{1} for a
69 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
76 \property Score.timing = ##f
77 \property Staff.autoBeaming = ##f
78 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
81 If you don't specify a @rglos{duration}, the previous one is used:
88 \property Score.timing = ##f
89 \transpose c c' { a a a2 a s16_" " }
92 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
93 @rglos{flat} (@texiflat{}) by adding @samp{es}. As you would expect,
94 a @rglos{double sharp} or @rglos{double flat} is made by adding
95 @samp{isis} or @samp{eses}:
102 \property Score.timing = ##f
103 \transpose c c' { cis1 ees fisis aeses s16_" " }
106 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
113 \property Score.timing = ##f
114 \transpose c c' { a2. a4 a8. a16 s16_" " }
117 The @rglos{meter} (or @rglos{time signature}) can be set with the
118 @code{\time} command:
126 @c a clef here may lead to confusion
128 \property Staff.Clef \set #'transparent = ##t
137 The @rglos{clef} can be set using the @code{\clef} command:
139 @c what is more common name treble or violin?
140 @c in Dutch, its violin.
141 @c in English its definitely treble.
150 \property Score.timing = ##f
161 When you enter these commands in a file, you must to enclose them in
162 @code{\notes @{@dots{}@}}. This lets LilyPond know that music (and
163 not @rglos{lyrics}, for example) follows:
174 Now the piece of music is almost ready to be printed. The final step is to
175 combine the music with a printing command.
177 The printing command is the so-called @code{\paper} block. Later on
178 you will see that the @code{\paper} block is used to customize
179 printing specifics. The music and the @code{\paper} block are combined by
180 enclosing them in @code{\score @{ ... @}}. This is what a full
181 LilyPond source file looks like:
204 linewidth = 55 * \staffspace
210 @node Running LilyPond
211 @section Running LilyPond
213 In the last section we explained what kind of things you could enter
214 in a lilypond file. In this section we explain how to run LilyPond
215 and how to view or print the output. If you have not used LilyPond
216 before, want to test your setup of LilyPond, or want to run an example
217 file yourself, read this section. The instructions that follow
218 are for running LilyPond on Unix-like systems. Some additional
219 instructions for running LilyPond on Windows are given at the end of
222 Begin by opening a terminal window and starting a text editor.
223 For example, you could open an xterm and execute @code{joe}. In your
224 text editor, enter the following input and save the file as
230 \notes @{ c'4 e' g' @}
237 @c now this is weird, running ly2dvi to run LilyPond
238 @c (therefore name change proposal)
240 LilyPond is the program that computes the sheet music. All other
241 things, such as adding titles, page breaking and other page layout,
242 are done by a small wrapper program called
243 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
244 then adds the titling and page layout instructions. To process
245 @file{test.ly} with @code{ly2dvi}, proceed as follows:
253 You will see the following on your screen:
258 Now processing: `/home/fred/ly/test.ly'
260 Interpreting music...[1]
261 @emph{ ... more interesting stuff ... }
262 PS output to `test.ps'...
263 DVI output to `test.dvi'...
267 @cindex Viewing music
270 The results of the ly2dvi run are two files, @file{test.dvi} and
271 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
272 You can view the PS file using the program ghostview. If a version of
273 ghostview is installed on your system, one of these commands will
274 produce a window with some music notation on your screen:
284 If the music on your screen looks good, you can print it by clicking
285 File/Print inside ghostview.
287 The DVI file (@file{test.dvi}) contains the same sheet music in a
288 different format. DVI files are more easily processed by the computer,
289 so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
290 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons
291 activate magnifying glasses. Unfortunately, variable symbols (such as
292 beams and slurs) are not displayed in the magnifying glasses.
294 If your DVI viewer does not have a "Print" button, you can print the
295 file by executing @code{lpr test.ps}.
297 @c volgende alinea schrappen?
299 If your system does not support printing PostScript files, then you
300 can install Ghostscript, a PostScript emulator. Refer to
301 Ghostscript's website at @uref{http://www.ghostscript.com}.
305 @cindex Printing output
309 A final option is to use the popular PDF format. You can get a PDF
310 file by running @code{ly2dvi --pdf test.ly}. With @code{--pdf}
311 you will get DVI, PS and PDF files. Viewers for PS files also
312 accept PDF files, but there are also many other applications for
315 If you are familiar with @TeX{}, be warned: do not use other
316 DVI drivers like @code{dvilj}. The @TeX{} coming out of LilyPond
317 uses embedded PostScript code and will not render correctly if
318 you use anything other than @code{dvips}.
324 @unnumberedsubsec Windows users
325 Windows users can start the terminal by clicking on the LilyPond or
326 Cygwin icon. You can use any text editor (such as NotePad, Emacs or
327 Vim) to edit the LilyPond file. If you install the Cygwin's
328 @code{XFree86} X11 window system, @code{tetex-x11} and
329 @code{ghostscript-x11} packages too, you can view the @code{dvi}
330 output doing @code{xdvi test.dvi} as described above. If you have
331 installed a PostScript/PDF viewer, such as @code{GSView} from
332 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PS file can be done
336 @code{gsview32 test.ps}
339 You can also print from the command line by executing:
342 @code{gsview32 /s test.ps}
349 To run LilyPond, input a text file, then run the command @code{ly2dvi} on
350 that file. The resulting files are either DVI or PostScript, and can
351 be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows)
352 respectively. The following table summarizes the constructs that were
353 discussed in the previous two sections.
355 @multitable @columnfractions .3 .3 .4
361 @item @code{1 2 8 16}
364 @lilypond[relative 1, noquote, notime]
365 \property Staff.autoBeaming = ##f
366 \property Staff.Clef = \turnOff
371 @tab augmentation dots
373 @lilypond[relative 1, noquote, notime]
374 \property Staff.Clef = \turnOff
378 @item @code{c d e f g a b }
381 @lilypond[relative 1, noquote, notime]
382 \property Staff.Clef = \turnOff
386 @item @code{\clef treble \clef bass }
389 @lilypond[noquote, notime]
396 @item @code{\time 3/4 \time 4/4 }
400 \property Staff.Clef \set #'transparent = ##t
413 We continue with the introduction of the remaining musical constructs.
414 Normal rests are entered just like notes with the name ``@code{r}'':
422 \property Score.timing = ##f
423 \property Staff.Clef = \turnOff
424 \property Staff.TimeSignature = \turnOff
431 @c Tim wants to move this quotes example just before the: quotes-don't-work
432 @c score, but we'd need to remove quotes from the other two (key and
435 @c better to have this just before the `octaves are bad' snipped
436 @c but we'd need to remove the ', from \key and tie
437 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
438 the note name, to lower a note one octave, add a ``low quote'' @code{,}
439 (a comma). Middle C is @code{c'}:
443 c'4 c'' c''' \clef bass c c,
447 \property Score.timing = ##f
448 \property Staff.TimeSignature = \turnOff
449 c'4 c'' c''' \clef bass c c,
454 A tie is created by adding a tilde ``@code{~}'' to the first note
457 @lilypond[fragment,verbatim]
462 A tie is different from a slur. A tie simply makes the first note
463 sound longer, and can only be used on pairs of notes with the same
464 pitch. Slurs indicate the articulations of notes, and can be used on
465 larger groups of notes. Slurs and ties are also nested in practice:
466 @lilypond[fragment, relative=1]
467 c2-~-( c8 fis fis4 ~ fis2 g2-)
471 The key signature is set with the command ``@code{\key}''. One
472 caution word of caution: you need to specify whether the key is
473 @code{\major} or @code{\minor}.
483 \property Staff.TimeSignature = \turnOff
492 @c bit on the long/complex/scary taste
493 @c cheating a bit: two lines makes for a friendlier look
494 This example shows notes, ties, octave marks, and rests in action.
503 r4 r8 d''8 cis''4 e''
505 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
518 r4 r8 d''8 cis''4 e''
520 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
523 \paper { linewidth = 50*\staffspace }
529 There are some interesting points to note in this example.
530 Accidentals (sharps and flats) don't have to be marked explicitly: you
531 just enter the note name, and LilyPond determines whether or not to
532 print an accidental. Bar lines and beams are drawn automatically.
533 LilyPond calculates line breaks for you; it doesn't matter where you
534 make new lines in the source file. Finally, the order of time, key and
535 clef changes is not relevant: lilypond will use standard notation
536 conventions for ordering these items.
538 The example also indicates that a piece of music written in a high
539 register needs lots of quotes. This makes the input less readable,
540 and is also a potential source of errors.
542 The solution is to use ``relative octave'' mode. In practice, this is
543 the most convenient way to copy existing music. To use relative mode,
544 add @code{\relative} before the piece of music. You must also give a
545 note from which relative starts, in this case @code{c''}. If you don't
546 use octavation quotes (ie don't add ' or , after a note), relative mode
547 chooses the note that is closest to the previous one. Since most music
548 has small intervals, you can write quite a lot in relative mode without
549 using octavation quotes.
550 @c don't use commas or quotes in this sentence
551 For example: @code{c f} goes up; @code{c g} goes down:
561 \property Score.timing = ##f
562 \property Staff.TimeSignature = \turnOff
571 @c needed better, maybe even redundant explanation
572 @c added another example below.
573 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
574 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
575 You can make larger intervals by adding octavation quotes. Note that
576 quotes or commas do not determine the absolute height of a note;
577 the height of a note is relative to the previous one.
578 @c don't use commas or quotes in this sentence
579 For example: @code{c f,} goes down; @code{f, f} are both the same;
580 @code{c' c} are the same; and @code{c g'} goes up:
590 \property Score.timing = ##f
591 \property Staff.TimeSignature = \turnOff
600 Here's an example of the difference between relative mode and
601 ``normal'' (non-relative) mode:
612 \property Score.timing = ##f
613 \property Staff.TimeSignature = \turnOff
629 \property Score.timing = ##f
630 \property Staff.TimeSignature = \turnOff
639 The following table summarizes the syntax learned so far in this section.
641 @c Is it possible to avoid page breaks directly after the
644 @multitable @columnfractions .3 .3 .4
653 @lilypond[relative 1, noquote, notime]
654 \property Staff.Clef = \turnOff
661 @lilypond[relative 1, noquote, notime]
662 \property Score.timing = ##f
663 \property Staff.autoBeaming = ##f
664 \property Staff.Clef = \turnOff
668 @item @code{\key es \major }
671 @lilypond[noquote, notime]
677 @item @var{note}@code{'}
680 @lilypond[relative 1, noquote, notime]
681 \property Score.timing = ##f
682 \property Staff.autoBeaming = ##f
683 \property Staff.Clef = \turnOff
687 @item @var{note}@code{,}
690 @lilypond[relative 1, noquote, notime]
691 \property Score.timing = ##f
692 \property Staff.autoBeaming = ##f
693 \property Staff.Clef = \turnOff
699 A slur is drawn across many notes, and indicates bound articulation
700 (legato). The starting note and ending note are marked with a
701 ``@code{(}'' and a ``@code{)}'' respectively:
704 @lilypond[fragment,relative 1, verbatim]
705 d4-( c16-)-( cis d e c cis d e-)-( d4-)
710 If you need two slurs at the same time (one for articulation, one for
711 phrasing), you can also make a phrasing slur with @code{\(} and
716 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
717 @c chromatic thing pasted in front. (admittedly the original doesn't
718 @c have a phrasing slur. The problem is that we don't want the slur
719 @c and the Phrasing slur to collide. We're trying to make a good
723 @lilypond[fragment,relative 1, verbatim]
724 a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
729 Beams are drawn automatically, but if you don't like the choices, you
730 can enter beams by hand. Mark the first note to be beamed with
731 @code{[} and the last one with @code{]}:
733 @lilypond[fragment,relative 1, verbatim]
734 a8-[ ais-] d-[ es r d-]
739 To print more than one staff, each piece of music that makes up a staff
740 is marked by adding @code{\context Staff} before it. These
741 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
745 @lilypond[fragment,verbatim]
747 \context Staff = staffA { \clef violin c'' }
748 \context Staff = staffB { \clef bass c }
753 In this example, @code{staffA} and @code{staffB} are names that are
754 given to the staves. It doesn't matter what names you give, as long
755 as each staff has a different name.
759 We can now typeset a melody with two staves:
762 @lilypond[verbatim,singleline]
765 < \context Staff = staffA {
768 \relative c'' { e2-( d4 c2 b4 a8-[ a-] b-[ b-] g-[ g-] a2.-) }
770 \context Staff = staffB {
781 Notice that the time signature is specified in one melody staff only
782 (the top staff), but is printed on both. LilyPond knows that the time
783 signature should be the same for all staves.
787 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
789 @lilypond[verbatim,relative 1]
795 Dynamic signs are made by adding the markings to the note:
797 @lilypond[verbatim,relative 1]
803 Crescendi and decrescendi are started with the commands @code{\<} and
804 @code{\>}. The command @code{\!} finishes a crescendo on the note it
807 @lilypond[verbatim,relative 1]
808 c2-\< c2-\!-\ff c2-\> c2-\!
813 Chords can be made by surrounding notes with @code{<<} and @code{>>}:
815 @lilypond[relative 0, fragment,verbatim]
816 r4 <<c e g>>4 <<c f a>>8
822 You can combine beams and ties with chords. Beam and tie markings
823 must be placed outside the chord markers:
825 @lilypond[relative 0, fragment,verbatim]
826 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
831 When you want to combine chords with slurs and dynamics, technical
832 detail crops up: you have type these commands next to the notes, which
833 means that they have to be inside the @code{< >}. Don't get confused
834 by the chord @code{< >} and the dynamic @code{\< \>}!
839 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
841 @lilypond[relative 0, fragment]
843 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
851 @multitable @columnfractions .3 .3 .4
861 @lilypond[fragment, relative 1]
862 \property Score.timing = ##f
863 \property Staff.TimeSignature = \turnOff
864 \property Staff.autoBeaming = ##f
865 \property Staff.Clef = \turnOff
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
894 @item @code{< \context Staff ... >}
898 < \context Staff = SA { c'1 }
899 \context Staff = SB { c'1 } >
906 @lilypond[fragment, relative 1]
907 \property Staff.TimeSignature = \turnOff
908 \property Staff.Clef = \turnOff
913 @item @code{-\mf -\sfz}
916 @lilypond[fragment, relative 1]
917 \property Staff.TimeSignature = \turnOff
918 \property Staff.Clef = \turnOff
926 @lilypond[fragment, relative 1]
927 \property Score.timing = ##f
928 \property Staff.TimeSignature = \turnOff
929 \property Staff.autoBeaming = ##f
930 \property Staff.Clef = \turnOff
937 @lilypond[fragment, relative 1]
938 \property Score.timing = ##f
939 \property Staff.TimeSignature = \turnOff
940 \property Staff.autoBeaming = ##f
941 \property Staff.Clef = \turnOff
949 @lilypond[fragment, relative 1]
955 Now you know the basic ingredients of a music file, so this is the right
956 moment to try your at hand at doing it yourself: try typing some
957 simple examples, and experiment a little.
959 When you're comfortable with the basics, you might want to read
960 the rest of this chapter. It continues in tutorial-style, but it
961 is much more in-depth, dealing with more advanced topics such as
962 lyrics, chords, orchestral scores and parts, fine tuning of output,
963 polyphonic music, and integrating text and music.
969 @node Printing lyrics
970 @section Printing lyrics
973 In this section we shall explain how to typeset the following
974 fragment of The Free Software Song:
976 @lilypond[singleline]
977 \score { \notes { \addlyrics
978 \notes \relative c' {
980 d'2 c4 b16-( a g a b a b c-) a2
981 b2 c4 b8-( a16 g a4-) g2 }
982 \context Lyrics \lyrics {
984 share the soft -- ware; }
986 \paper { linewidth = -1. }
992 @cindex @code{\lyrics}
995 To print lyrics, you must enter them and then instruct lilypond to
997 You can enter lyrics in a special input mode of LilyPond. This mode is
998 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
999 The purpose of this mode is that you can enter lyrics as plain text,
1000 punctuation, and accents without any hassle.
1002 Syllables are entered like notes, but with pitches replaced by text. For
1003 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1004 the hyphen has no special meaning for lyrics, and does not introduce
1007 Spaces can be introduced into a lyric either by using quotes:
1008 @code{"He could" not} or by using an underscore without quotes:
1009 @code{He_could not}. All unquoted underscores are converted to
1012 These are the lyrics for the free software song:
1017 share the soft -- ware; @}
1020 As you can see, extender lines are entered as @code{__}. This will
1021 create an extender, which is a line that extends over the entire
1022 duration of the lyric. This line will run all the way to the start
1023 of the next lyric, so you may want to shorten it by using a blank
1024 lyric (using @code{_}).
1027 You can use ordinary hyphens at the end of a syllable, i.e.
1031 but then the hyphen will be attached to the end of the first syllable.
1033 If you want them centered between syllables you can use the special
1034 `@code{-}@code{-}' lyric as a separate word between syllables. The
1035 hyphen will have variable length depending on the space between
1036 the syllables and it will be centered between the syllables.
1038 Normally the notes that you enter are transformed into note heads.
1039 Note heads alone make no sense, so they need surrounding information: a
1040 key signature, a clef, staff lines, etc. They need @emph{context}. In
1041 LilyPond, these symbols are created by objects called `interpretation
1042 contexts'. Interpretation contexts exist for generating notation
1043 (`notation context') and for generating sound (`performance
1044 context'). These objects only exist while LilyPond is executing.
1046 When LilyPond interprets music, it will create a Staff context.
1047 We don't want that default here, because we want lyric. The
1052 explicitly creates an interpretation context of
1053 @code{Lyrics} type to interpret the song text that we entered.
1055 The melody of the song doesn't offer anything new:
1057 \notes \relative c' @{
1059 d'2 c4 b16-( a g a b a b c-) a2
1060 b2 c4 b8-( a16 g a4-) g2 @}
1063 Both can be combined with the @code{\addlyrics}:
1066 \notes \relative c' @dots{}
1067 \context Lyrics \lyrics @dots{}
1070 The lyrics are also music expressions, similar to notes. Each syllable
1071 of the lyrics is put under a note of the melody.
1072 The complete file is listed here:
1075 \score @{ \notes @{ \addlyrics
1076 \notes \relative c' @{
1078 d'2 c4 b16 ( a g a b a b ) c a2
1079 b2 c4 b8 ( a16 g ) a4 g2 @}
1080 \context Lyrics \lyrics @{
1082 share the soft -- ware; @}
1084 \paper @{ linewidth = -1. @}
1090 @node A melody with chords
1091 @section A melody with chords
1093 In this section we show how to typeset a melody with chord
1094 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1097 \include "paper16.ly"
1098 melody = \notes \relative c' @{
1102 c4 c8 d es-[ -( d-]-) c4 | f4 f8 g es-[-( d-)-] c g |
1103 c4 c8 d es-[ -( d-]-) c4 | d4 es8 d c4.
1107 accompaniment =\chords @{
1109 c2:3- f:3-.7 d:min es4 c8:min r8
1110 c2:min f:min7 g:7^3.5 c:min @}
1115 \context ChordNames \accompaniment
1116 \context Staff = mel @{
1121 \midi @{ \tempo 4=72 @}
1122 \paper @{ linewidth = 10.0\cm @}
1127 The result would look this.
1130 \include "paper16.ly"
1131 melody = \notes \relative c' {
1135 c4 c8 d es-[ -( d-)-] c4 | f4 f8 g es-(-[ d-)-] c g |
1136 c4 c8 d es-(-[ d-]-) c4 | d4 es8 d c4.
1140 accompaniment =\chords {
1142 c2:3- f:3-.7 d:min es4 c8:min r8
1143 c2:min f:min7 g:7^3.5 c:min }
1148 \context ChordNames \accompaniment
1150 \context Staff = mel {
1151 \property Staff.autoBeaming = ##f
1155 \midi { \tempo 4=72 }
1156 \paper { linewidth = 10.0\cm }
1160 We will dissect this file line by line.
1165 \include "paper16.ly"
1168 Smaller size (suitable for inclusion in a book).
1172 melody = \notes \relative c' @{
1175 The structure of the file will be the same as the previous one: a
1176 @code{\score} block with music in it. To keep things readable, we will
1177 give different names to the different parts of music, and use the names
1178 to construct the music within the score block.
1185 @cindex @code{\partial}
1187 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1193 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1194 c4 c8 d [es () d] c4 | d4 es8 d c4.
1199 @cindex manual beaming
1200 @cindex automatic beaming, turning off
1201 We use explicit beaming. Since this is a song, we turn automatic
1202 beams off and use explicit beaming where needed.
1209 This ends the definition of @code{melody}.
1218 @cindex identifier assignment
1219 @cindex syllables, entering
1220 This defines the lyrics, similar to what we have seen before.
1225 accompaniment =\chords @{
1229 @cindex mode, chords
1230 We'll put chords over the music. To enter them, we use a special mode
1231 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1232 the names of the chords you want instead of listing the notes
1233 comprising the chord.
1240 There is no accompaniment during the anacrusis.
1249 @cindex chord modifier
1250 @cindex modifier, chord
1251 This is a c minor chord, lasting for a half note. Chords are entered using
1252 the tonic. Notes can be changed to create different chords. In this case,
1253 a lowered third is used (making a C major chord into a C minor chord).
1254 The code for this is @code{3-}.
1260 Similarly, @code{7} modifies (adds) a seventh, which is small by
1261 default to create the @code{f a c es} chord. Multiple modifiers must be
1269 Some modifiers have predefined names, e.g. @code{min} is the same as
1270 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1274 c2:min f:min7 g:7^3.5 c:min @}
1277 @cindex named modifier
1279 A named modifier @code{min} and a normal modifier @code{7} do not have
1280 to be separated by a dot. Tones from a chord are removed with chord
1281 subtractions. Subtractions are started with a caret, and they are
1282 also separated by dots. In this example, @code{g:7^3.5} produces a
1283 minor seventh (a G7 chord without the third or the fifth). The
1284 brace ends the sequential music.
1292 We assemble the music in the @code{\score} block. Melody, lyrics and
1293 accompaniment have to sound at the same time, so they should be
1294 @code{\simultaneous}.
1295 @cindex @code{\simultaneous}
1302 Chord mode generates notes grouped in @code{\simultaneous} music. If
1303 you remove the comment sign, you can see the chords in normal
1304 notation: they will be printed as note heads on a separate
1305 staff. To print them as chords names, they have to be interpreted as
1306 being chords, not notes. This is done with the following command:
1310 \context ChordNames \accompaniment
1314 @cindex interpretation context
1315 @cindex notation context
1318 Normally the notes that you enter are transformed into note heads.
1319 Note heads alone make no sense, so they need surrounding information: a key
1320 signature, a clef, staff lines, etc. They need @emph{context}. In
1321 LilyPond, these symbols are created by objects called `interpretation
1322 contexts'. Interpretation contexts exist for generating notation
1323 (`notation context') and for generating sound (`performance
1324 context'). These objects only exist while LilyPond is executing.
1326 When LilyPond interprets music, it will create a Staff context. If
1327 the @code{%} sign in the previous line were removed, you could see
1328 that mechanism in action.
1330 We don't want that default here, because we want chord names. The
1331 command above explicitly creates an interpretation context of
1332 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1337 \context Staff = mel @{
1341 We place the melody on a staff called @code{mel}. We give it a name to
1342 differentiate it from the one that would contain note heads for the
1343 chords, if you would remove the comment before the ``note heads''
1344 version of the accompaniment. By giving this staff a name, it is
1345 forced to be different.
1349 \property Staff.autoBeaming = ##f
1353 @cindex context variables
1354 @cindex setting context variables
1355 An interpretation context has variables, called properties, that tune
1356 its behavior. One of the variables is @code{autoBeaming}. Setting
1357 this @code{Staff}'s property to @code{##f}, which is the boolean value
1358 @var{false}, turns the automatic beaming mechanism off for the current
1369 Finally, we put the melody on the current staff. Note that the
1370 @code{\property} directives and @code{\melody} are grouped in sequential
1371 music, so the property settings are done before the melody is
1377 \midi @{ \tempo 4=72@}
1380 MIDI (Musical Instrument Digital Interface) is a standard for
1381 connecting and recording digital instruments. So a MIDI file is like a
1382 tape recording of an instrument. The @code{\midi} block makes the
1383 music go to a MIDI file, so you can listen to the music you entered. It
1384 is great for checking the music. Whenever you hear something weird, you
1385 probably hear a typing error.
1387 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1388 also specifies an output method. You can specify the tempo using the
1389 @code{\tempo} command, in this case the tempo of quarter notes is set to
1390 72 beats per minute.
1394 \paper @{ linewidth = 10.0\cm @}
1397 We also want notation output. The linewidth is short so that the piece
1398 will be set in two lines.
1401 @section More stanzas
1406 If you have multiple stanzas printed underneath each other, the vertical
1407 groups of syllables should be aligned around punctuation. LilyPond can
1408 do this if you tell it which lyric lines belong to which melody.
1409 We show how you can do this by showing how you could print a frivolous
1410 fragment of a fictional Sesame Street duet.
1412 @lilypond[singleline,verbatim]
1415 \notes \relative c'' \context Voice = duet { \time 3/4
1417 \lyrics \context Lyrics <
1418 \context LyricsVoice = "duet-1" {
1419 \property LyricsVoice . stanza = "Bert"
1420 Hi, my name is bert. }
1421 \context LyricsVoice = "duet-2" {
1422 \property LyricsVoice . stanza = "Ernie"
1423 Ooooo, ch\'e -- ri, je t'aime. }
1428 To this end, give the Voice context an identity, and set the
1429 LyricsVoice to a name starting with that identity followed by a dash.
1430 In the following example, the Voice identity is @code{duet},
1432 \context Voice = duet @{
1437 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1439 \context LyricsVoice = "duet-1" @{
1440 Hi, my name is bert. @}
1441 \context LyricsVoice = "duet-2" @{
1442 Ooooo, ch\'e -- ri, je t'aime. @}
1445 We add the names of the singers. This can be done by setting
1446 @code{LyricsVoice.Stanza} (for the first system) and
1447 @code{LyricsVoice.stz} for the following systems. Note that you must
1448 surround dots with spaces in @code{\lyrics} mode.
1451 \property LyricsVoice . stanza = "Bert"
1453 \property LyricsVoice . stanza = "Ernie"
1456 The convention for naming @code{LyricsVoice} and @code{Voice} must
1457 also be used to get melismata on rests correct.
1460 @c I think we need to change the name of this section, but that
1461 @c would probably involve a lot of changes in other places too.
1462 @node More movements
1463 @section More movements
1465 The program @code{lilypond} only produces sheet music and does not
1466 create titles, subtitles, or print the composer's name. To do that,
1467 you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi}
1468 creates the title, then calls @code{lilypond} to format the sheet music.
1469 In this section, we show you how to create titles like this:
1471 @c Old version of the above paragraph.
1472 @c LilyPond only produces sheet music; it doesn't concern itself with
1473 @c producing titles. Titles are produced using a simply wrapper program
1474 @c This is the jobs of a simple wrapper
1475 @c program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
1476 @c sheet music formatting. Then it produces titles, and ties together all
1477 @c inputs into a single @file{dvi} file. In this section, we show some of
1478 @c the options for titling. We will show how you can produce a file
1479 @c that looks like this:
1481 @center @strong{Two miniatures}
1491 \paper { linewidth = -1.0 }
1503 \paper { linewidth = -1.0 }
1507 For example, consider the following file (@file{miniatures.ly})
1512 title = "Two miniatures"
1513 composer = "F. Bar Baz"
1514 tagline = "small is beautiful" @}
1516 \paper @{ linewidth = -1.0 @}
1520 Mental note: discuss Schenkerian analysis of these key pieces.
1525 \notes @{ c'4 d'4 @}
1531 \notes @{ d'4 c'4 @}
1539 The information for the global titling is in a so-called header block.
1540 The information in this block is not used by LilyPond, but it is
1541 passed into @code{ly2dvi}, which uses this information to print titles
1544 @cindex identifier assignment
1545 the @code{\header} block contains assignments. In each assignment, a
1546 variable is set to a value. The header block for this file looks like
1548 @cindex @code{\header}
1551 title = "Two miniatures"
1552 composer = "F. Bar Baz"
1553 tagline = "small is beautiful"
1557 When you process a file with ly2dvi, a signature line is printed at
1558 the bottom of the last page. This signature is produced from the
1559 @code{tagline} field of @code{\header}. The default "Lily was here,
1560 @var{version number}" is convenient for programmers: archiving the
1561 layouts of different versions allows programmers to compare the
1562 versions using old print-outs.
1564 @cindex Lily was here
1565 @cindex signature line
1568 Many people find the default tagline (``Lily was here'') too droll.
1569 If that is the case, you can change @code{tagline} to somethign else,
1578 A paper block at top level (i.e. not in a @code{\score} block) sets the
1579 default page layout. The following @code{\score} blocks don't have
1580 @code{\paper} sections, so the settings of this block are used.
1582 The variable @code{linewidth} normally sets the length of the systems
1583 on the page. However, a negative value has a special meaning. If
1584 @code{linewidth} is less than 0, no line breaks are inserted into the
1585 score, and the spacing is set to natural length: a short phrase takes
1586 up little space, a longer phrase takes more space, all on the same line.
1591 Mental note: discuss Schenkerian analysis of these key pieces.
1596 Mental notes to yourself can be put into comments. There are two types
1597 of comments. Line comments are introduced by @code{%}, and block
1598 comments are delimited by @code{%@{} and @code{%@}}.
1603 \notes @{ c'4 d'4 @}
1606 In previous examples, most notes were specified in relative octaves
1607 (i.e. each note was put in the octave that is closest to its
1608 predecessor). Besides relative, there is also absolute octave
1609 specification, which you get when you don't include @code{\relative} in
1610 your input file. In this input mode, the middle C is denoted by
1611 @code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
1612 Going up, you get @code{c''} @code{c'''} etc.
1614 When you're copying music from existing sheet music, relative octaves
1615 are probably the easiest to use: you have to do less typing, and errors are
1616 easily spotted. However, if you write LilyPond input directly, either by
1617 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1625 The @code{\header} is normally at the top of the file, where it sets
1626 values for the rest of the file. If you want to typeset different pieces
1627 from one file (for example, if there are multiple movements, or if
1628 you're making an exercise book), you can put different @code{\score}
1629 blocks into the input file. @code{ly2dvi} will assemble all LilyPond
1630 output files into a big document. The contents of @code{\header} blocks
1631 specified within each score is used for the title of that movement.
1637 For example, the Opus number is put at the right, and the "piece" string
1638 will be at the left.
1645 title = "Two miniatures"
1646 composer = "F. Bar Baz"
1647 tagline = "small is beautiful" @}
1649 \paper @{ linewidth = -1.0 @}
1652 \notes @{ c'4 d'4 @}
1658 \notes @{ d'4 c'4 @}
1668 scoreA = \score @{ \deelA @}
1669 scoreB = \score @{ \deelA @}
1671 % \score @{ \scoreA @}
1672 \score @{ \scoreB @}
1680 Lilypond and its language are still under development, and
1681 occasionally details of the syntax are changed. The @code{version}
1682 fragment indicates which version of lilypond the input file was written
1683 for. When you compile this file, the version number will be checked
1684 and you will get a warning when the file is too old. This version
1685 number is also used by the @code{convert-ly} program (See
1686 @ref{Invoking convert-ly}), which can used to update the file to the
1687 latest lily version.
1690 @node A piano excerpt
1691 @section A piano excerpt
1693 Our eighth subject is a piece of piano music. The fragment in the
1694 input file is a piano reduction of the G major Sinfonia by Giovanni
1695 Battista Sammartini, composed around 1740. It's in the source
1696 package under the name @file{input/tutorial/sammartini.ly}.
1698 @lilypondfile[smallverbatim,noquote]{sammartini.ly}
1700 As you can see, this example features multiple voices on one staff. To
1701 make room for those voices, their notes should be stemmed in opposite
1704 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1705 with some other commonly used formatting instructions, but to explain how
1706 it works, we wrote our own here. Of course, you should use predefined
1707 identifiers like these if possible: you will be less affected by changes
1708 between different versions of LilyPond.
1712 viola = \notes \relative c' \context Voice = viola @{
1714 In this example you can see multiple parts on a staff. Each part is
1715 associated with one notation context. This notation context handles
1716 stems and dynamics (among other things). The type name of this context
1717 is @code{Voice}. For each part we have to make sure that there is
1718 precisely one @code{Voice} context, so we give it a unique name
1723 <<c g' c>>4-\arpeggio
1725 The delimiters @code{<<} and @code{>>} enclose the pitches of a chord.
1726 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line)
1737 We want the viola to have stems down, and have all the other
1738 characteristics of a second voice. This is enforced using the
1739 @code{\voiceTwo} command: it inserts instructions that makes stem,
1740 ties, slurs, etc. go down.
1748 Relative octaves work a little differently with chords. The starting
1749 point for the note following a chord is the first note of the chord. So
1750 the @code{g} gets an octave up quote: it is a fifth above the starting
1751 note of the previous chord (the central C).
1757 @code{s} is a spacer rest. It does not print anything, but it does have
1758 the duration of a rest. It is useful for filling up voices that
1759 temporarily don't play. In this case, the viola doesn't come until one
1760 and a half measure later.
1764 oboes = \notes \relative c'' \context Voice = oboe @{
1766 Now comes a part for two oboes. They play homophonically, so we
1767 print the notes as one voice that makes chords. Again, we insure that
1768 these notes are indeed processed by precisely one context with
1772 \voiceOne s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16
1775 The oboes should have stems up to keep them from interfering with
1776 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1780 \grace <<e g>>-( <<d f>>4-) <<c e>>2
1782 @cindex @code{\grace}
1785 @code{\grace} introduces grace notes. It takes one argument, in this
1786 case a chord. A slur is introduced starting from the @code{\grace}
1787 ending on the following chord.
1795 Tuplets are made with the @code{\times} keyword. It takes two
1796 arguments: a fraction and a piece of music. The duration of the piece
1797 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1798 of their notated duration, so in this case the fraction is 2/3.
1801 @{ <<d f>>8 <<e g>> <<f a>> @}
1803 The piece of music to be `tripletted' is sequential music containing
1810 At this point, the homophonic music splits into two rhythmically
1811 different parts. We can't use a sequence of chords to enter this, so
1812 we make a "chord of sequences" to do it. We start with the upper
1813 voice, which continues with upward stems:
1816 @{ \times 2/3 @{ a8 g c @} c2 @}
1823 The easiest way to enter multiple voices is demonstrated
1824 here. Separate the components of the voice (single notes or entire
1825 sequences) with @code{\\} in a simultaneous music expression. The
1826 @code{\\} separators split first voice, second voice, third voice, and
1829 As far as relative mode is concerned, the previous note is the
1830 @code{c'''2} of the upper voice, so we have to go an octave down for
1838 This ends the two-part section.
1842 \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |
1847 @code{\stemBoth} ends the forced stem directions. From here, stems are
1848 positioned as if it were single part music.
1850 The bass has a little hoom-pah melody to demonstrate parts switching
1851 between staves. Since it is repetitive, we use repeats:
1854 hoomPah = \repeat unfold 8
1856 @cindex unfolded @code{\repeat}
1857 The unfolded repeat prints the notes in its argument as if they were
1858 written out in full eight times.
1861 \notes \transpose c' @{
1864 @cindex relative mode and transposing
1866 Transposing can be done with @code{\transpose}, which takes two arguments.
1867 The first specifies what central C should be transposed to. The second
1868 is the to-be-transposed music. As you can see, in this case, the
1869 transposition has no effect, as central C stays at central C.
1871 The purpose of this no-op is to protect it from being interpreted as
1872 relative notes. Relative mode can not be used together with
1873 transposition, so @code{\relative} will leave the contents of
1874 @code{\hoomPah} alone. We can use it without having to worry about
1875 getting the motive in a wrong octave. Conversely, if you want to
1876 transpose a fragment of music entered with @code{\relative}, then you
1877 should make sure that @code{\transpose} comes before @code{\relative}.
1880 @cindex staff switch, manual
1881 @cindex cross staff voice, manual
1882 @cindex @code{\translator}
1885 \translator Staff = down
1888 \translator Staff = up
1892 Voices can switch between staves. Here you see two staff switching
1893 commands. The first one moves to the lower staff, the second one to
1894 the lower one. If you set the stem directions explicitly
1895 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1896 can be beamed together (despite jumping between staffs).
1900 bassvoices = \notes \relative c' @{
1902 \autochange Staff \hoomPah \context Voice
1907 \translator Staff = down
1909 @cindex staff switch
1910 @cindex cross staff voice
1911 We want the remaining part of this melody on the lower staff, so we do a
1912 manual staff switch here.
1917 \context Voice = reallyLow @{\stemDown g2-~ | g4 c8 @} >
1921 After skipping some lines, we see @code{~}. This mark makes ties. Note
1922 that ties and slurs are different things. A tie can only connect two
1923 note heads of the same pitch, whereas a slur can connect many notes
1930 A special context is needed to get cross staff beaming right. This
1931 context is called @code{PianoStaff}.
1934 \context Staff = bottom < \time 2/2 \clef bass
1936 The bottom staff must have a different clef.
1941 To make some more room on the line, the first (in this case the only)
1942 line is not indented. The line still looks very cramped, but that is due
1943 to the page layout of this document.
1949 * font-size, multi-stanza.
1951 * Simple part combining in a Hymn
1955 @node Fine tuning a piece
1956 @section Fine tuning a piece
1958 In this section we show some ways to fine tune the final output of a
1959 piece. We do so using a single measure of a moderately complex piano
1960 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
1961 tuned and the untuned versions) are in @file{input/tutorial/}.
1963 The code for the untuned example shows us some new things.
1965 @lilypondfile[verbatim]{brahms-original.ly}
1975 Hairpin dynamics can be easily added to Lilypond scores. Beginning a
1976 crescendo is indicated with @code{\<} and ending a crescendo is indicated
1977 with @code{\!}. A decrescendo can be indicated with @code{\>} and
1978 @code{\!}. Absolute dynamics (sometimes called ``Letter dynamics'') can
1979 be entered using @code{\p}, @code{\mf}, etc. All these dynamics will
1980 apply to the whole chord where they are entered, but for syntactical
1981 reasons they must be attached to one of the notes of the chord.
1983 @cindex fingering instructions
1985 Fingering indications are entered with @code{-@var{N}}, where
1988 Now that we have the basic piece of music entered, we want to fine
1989 tune it so that we get something that resembles the original printed
1990 edition by Schott/Universal Edition:
1992 @lilypondfile{brahms-tweaked.ly}
1994 @cindex tuning graphical objects
1996 Fine tuning involves overriding the defaults of the printing system.
1997 We do this by setting variables which control how Lilypond prints
1998 symbols. Printed symbols are called graphical objects (often
1999 abbreviated to @emph{grob}). Each object is described by a bunch of
2000 settings. Every setting is a variable: it has a name and a value
2001 which you can change. These values determine the fonts, offsets,
2002 sub-routines to be called on the object, etc. The initial values of
2003 these settings are set in the Scheme file
2004 @file{scm/grob-description.scm}.
2006 @cindex slur attachments
2008 We start with the slur in the upper part, running from F sharp to A. In
2009 the printed edition, this slur runs from stem to stem; in our version,
2010 the slur begins at the note head of the F sharp. The following property
2011 setting forces all slurs to run from stem to stem (not from or to note
2015 \property Voice.Slur \set #'attachment = #'(stem . stem)
2018 More precisely, this command modifies the definition of the @code{Slur}
2019 object in the current @code{Voice}. The variable @code{attachment} is
2020 set to the pair of symbols @code{'(stem . stem)}.
2022 Although this fixes the slur, it isn't very helpful for fine tuning in
2023 general: the lilypond back-end supports approximately 240 variables
2024 like @code{attachment}, each with their own meaning and own type
2025 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2026 different types of graphical objects, that may be created in 14
2027 different context types besides Voice.
2029 @cindex internal documentation
2030 @cindex finding graphical objects
2031 @cindex graphical object descriptions
2033 The interesting information is how you can figure out which properties
2034 to tune for your own scores. To discover this, you must have a copy of
2035 the internals document. This is a set of HTML pages which should be
2036 included if you installed a binary distribution@footnote{You can also
2037 compile them by executing @code{make -C Documentation/user/
2038 out/lilypond-internals.html} in the source package.}. These HTML pages
2039 are also available on the web: go to the lilypond website, click
2040 ``Documentation: Index'' on the side bar, look in the ``Information for
2041 uses'' section, and click on ``Documentation of internals''.
2043 You might want to bookmark either the HTML files on your disk, or the one
2044 on the web (the HTML on your hard drive will load much faster than the
2045 ones on the web!). One word of caution: the internals documentation is
2046 generated from the definitions that lily uses. For that reason, it is
2047 strongly tied to the version of LilyPond that you use. Before you
2048 proceed, please make sure that you are using the documentation that
2049 corresponds to the version of LilyPond that you are using.
2051 @c TODO: the quote is incorrect, although that shouldn't be a big
2052 @c problem for the reader.
2053 Suppose that you wanted to tune the behavior of the slur. The first
2054 step is to get some general information on slurs in lilypond. Turn to
2055 the index, and look up ``slur''. The section on slurs says
2057 The grob for this object is @internalsref{Slur}, generally in
2058 @internalsref{Voice} context.
2061 So the graphical object for this object is called @code{Slur}, and
2062 slurs are created in the @code{Voice} context. If you are reading
2063 this tutorial in the HTML version, then you can simply click Slur,
2064 otherwise, you should look it up the internal documentation: click
2065 ``grob overview'' and select ``slur'' (the list is alphabetical).
2067 Now you get a list of all the properties that the slur object
2068 supports, along with their default values. Among the properties we
2069 find the @code{attachment} property with its default setting.
2070 The property documentation explains that the following setting will
2071 produce the desired effect:
2073 \property Voice.Slur \set #'attachment = #'(stem . stem)
2076 If you ran the previous example, you have unknowingly already used
2077 this kind of command. The @file{ly/property-init.ly} contains the
2078 definition of @code{\stemUp}:
2080 stemUp = \property Voice.Stem \set #'direction = #1
2083 @c this is a long section, and adding an extra space here helps to
2084 @c break it into smaller subsections and thus is easier to understand.
2087 Next we want to move the fingering `3'. In the printed edition it is
2088 not above the stem, but a little lower and slightly left of the stem.
2089 From the user manual we find that the associated graphical object is
2090 called @code{Fingering}, but how do we know if we should use
2091 @code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
2092 bet, but you can also deduce this information from the internals
2093 documentation: if you visit the documentation of @code{Fingering}, you
2096 Fingering grobs are created by: Fingering_engraver
2099 Clicking @code{Fingering_engraver} will show you the documentation of
2100 the module responsible for interpreting the fingering instructions and
2101 translating them to a @code{Fingering} object. Such a module is called
2102 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2105 Fingering_engraver is part of contexts: Voice and TabVoice
2107 so tuning the settings for Fingering should be done using either
2109 \property Voice.Fingering \set @dots{}
2113 \property TabVoice.Fingering \set @dots{}
2116 Since the @code{TabVoice} is only used for tab notation, we see that
2117 the first guess @code{Voice} was indeed correct.
2119 @cindex setting object properties
2120 @cindex @code{extra-offset}
2122 For shifting the fingering, we use the property @code{extra-offset}.
2123 The following command manually adds an offset to the object. We move
2124 it a little to the left, and 1.8 staff space downwards.
2126 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2128 The @code{extra-offset} is a low-level feature: it moves around
2129 objects in the printout; the formatting engine is completely oblivious
2130 to these offsets. The unit of these offsets are staff-spaces. The
2131 first number controls left-right movement; a positive number will move
2132 the object to the right. The second number controls up-down movement;
2133 a positive number will move it higher.
2135 @cindex reverting object properties
2136 @cindex undoing object properties
2138 We only want to offset a single object, so after the F-sharp we must
2139 undo the setting. The technical term is to revert the property.
2141 \property Voice.Fingering \revert #'extra-offset
2144 @cindex property types
2145 @cindex translator properties
2146 @cindex grob properties
2147 @cindex music properties
2150 There are three different types of variables in LilyPond, something
2151 which can be confusing at first (and for some people it stays confusing
2152 :). Variables such as @code{extra-offset} and @code{attachment} are
2153 called grob properties. They are not the same as translator properties,
2154 like @code{autoBeaming}. Finally, music expressions are internally
2155 stored using properties (so-called music properties). You will encounter
2156 music properties if you run Scheme functions on music using @code{\apply}.
2158 The second fingering instruction should be moved up a little to avoid
2159 a collision with the slur. This could be achieved with
2160 @code{extra-offset}, but in this case, a simpler mechanism also
2161 works. We insert an empty text between the 5 and the note. The empty
2162 text pushes the fingering instruction away:
2164 a^" "^#'(finger "5")
2167 Lilypond tries to put fingering instructions as close to the notes as
2168 possible. To make sure that Lilypond doesn't do that, we disguise the
2169 fingering as text: @code{(finger "5")}.
2173 Normally one would specify all dynamics in the same voice, so that
2174 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2175 in this case, we don't want the decrescendo to be aligned with the
2176 piano sign. We achieve this by putting the dynamic markings in different
2177 voices. The crescendo should be above the upper staff. This can be
2178 forced by using the precooked command
2183 However, if you do that the decrescendo will be too close to the
2184 upper voice and collide with the stems. Looking at the manual for
2185 dynamics, we notice that ``Vertical positioning of these symbols is
2186 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2187 to the documentation of @code{DynamicLineSpanner}, we find that
2188 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2189 object not only puts dynamic objects next to the staff
2190 (@code{side-position-interface}), but it also groups dynamic objects
2191 (@code{axis-group-interface}), is considered a dynamic sign
2192 itself (@code{dynamic-interface}), and is an object. It has the standard
2193 @code{grob-interface} with all the variables that come with it.
2195 For the moment we are interested in side positioning:
2197 side-position-interface
2199 Position a victim object (this one) next to other objects (the
2200 support). In this case, the direction signifies where to put the
2201 victim object relative to the support (left or right, up or down?)
2203 Between the object and its support (in this case the notes in the voice
2204 going down), there should be more space. This space is controlled by
2205 @code{padding}, so we increase it.
2207 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2210 This command is almost like the command for setting slur attachments,
2211 but subtly different in its details. Grob properties can be
2212 manipulated with two commands: @code{\override} extends the
2213 variables with a setting, and @code{\revert} releases this
2214 setting. This has a certain theoretical appeal: the operations are
2215 simple and symmetric. But for practical use, it can be cumbersome. The
2216 commands act like parentheses: you should carefully balance the use of
2217 @code{\override} and @code{\revert}. The @code{\set} command is more
2218 friendly: it first does a @code{\revert} followed by @code{\override}.
2222 Brahms uses music notation is a slightly unorthodox way. Ties
2223 usually happen only within one voice. In this piece, the composer
2224 gladly produces ties that jump voices. We deal with this by faking
2225 these ties: whenever we need such a tie, we insert a notehead in a
2226 different voice, and blank the stem. This is done in the following
2230 \property Voice.Stem \set #'transparent = ##t
2233 Blanking the stem should be done for only one object. One of the ways
2234 to achieve that, is by setting the property before a note. Reverting
2235 it afterwards is tedious, so for setting a property only once, we have
2236 the syntax @code{\once}: it reverts the property directly before
2237 proceeding to the next step in time.
2239 The @code{\once} keyword is added to @code{\property}.
2242 Finally, the last tie is forced up using @code{\tieUp}.
2246 Here's the complete ``fine tuned'' version, which includes all the
2247 modifications we discussed in this section:
2249 @lilypondfile[verbatim]{brahms-tweaked.ly}
2252 @node An orchestral score
2253 @section An orchestral score
2257 * Extracting an individual part::
2261 Our next two examples demonstrate one way to create an orchestral score
2262 in LilyPond. When typesetting a piece for several instruments, you'll
2263 want to create a full score (for the conductor) along with several
2264 individual parts (for the players).
2266 LilyPond is well suited for this task. We will declare the music for
2267 each instrument individually, giving the music of each instrument its
2268 own name. These pieces of music are then combined in different
2269 @code{\score} blocks to produce different combinations of instruments
2270 (for example, one @code{\score} block may only include the cello part;
2271 another @code{\score} block may be for all the strings, and yet another
2272 @code{\score} block may be for all parts together).
2274 This orchestral score example consists of three input files. In the
2275 first file, @file{os-music.ly}, we define the music for all
2276 instruments. This file will be used for producing the score and
2277 the separate parts, but the file doesn't produce any sheet music
2278 itself. Other files reference this file by doing @code{\include
2284 title = "Zo, goed lieverd?"
2285 subtitle = "How's, this babe?"
2294 Key = \notes \key as \major
2295 flautoI = \notes\relative c'' @{
2297 bes as bes as bes as bes as
2299 flautoII = \notes\relative c'' @{
2300 as8 bes as bes R1 d4 ~ d
2302 tromboI = \notes\relative c'' @{
2303 c4. c8 c8 c4. es4 r as, r
2305 tromboII = \notes\relative c'' @{
2306 as4. as8 as8 as4. R1*1/2 as4 es'
2308 timpani = \notes\relative c, @{
2309 \times 2/3 @{ f4 f f @}
2310 \times 4/5 @{ as8 as as as as @}
2313 corno = \notes\relative c' @{
2314 bes4 d f, bes d f, bes d
2318 We will not examine this example line by line, since you already know
2319 most of it. We'll examine a few lines which contain new elements.
2330 Declare setting to be used globally. The @code{\skip} command produces
2331 no output, but moves forward in time: in this case, the duration of a
2332 half note (@code{2}), and that four times (@code{*4}). This brings us
2333 to the end of the piece, and we can set the end bar. You can use @code{s}
2334 as a shortcut for @code{\skip} (the last line of this section would
2335 be @code{s2*4 \bar"|."}).
2339 Key = \notes \key as \major
2341 Declare the key signature of the piece and assign it to the identifier
2342 @var{Key}. Later on we'll use @code{\Key} for all staves except those
2343 for transposing instruments.
2345 @node The full score
2346 @subsection The full score
2349 The second file, @file{input/tutorial/os-score.ly}, reads the definitions of the first
2350 (@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
2356 \include "os-music.ly"
2357 \include "paper13.ly"
2359 #(ly:set-point-and-click 'line-column)
2360 #(define text-flat '((font-relative-size . -2)
2361 (music "accidentals--1")))
2366 \property Score.BarNumber \override #'padding = #3
2367 \context StaffGroup = woodwind <
2368 \context Staff = flauti <
2369 \property Staff.midiInstrument = #"flute"
2370 \property Staff.instrument = "2 Flauti"
2371 \property Staff.instr = "Fl."
2373 \context Voice=one @{ \voiceOne \flautoI @}
2374 \context Voice=two @{ \voiceTwo \flautoII @}
2377 \context StaffGroup = timpani <
2378 \context Staff = timpani <
2379 \property Staff.midiInstrument = #"timpani"
2380 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2381 \property Staff.instr = #"Timp."
2387 \context StaffGroup = brass <
2388 \context Staff = trombe <
2389 \property Staff.midiInstrument = #"trumpet"
2390 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2391 \property Staff.instr = #`(lines "Tbe." "(C)")
2393 \context Voice=one \partcombine Voice
2394 \context Thread=one \tromboI
2395 \context Thread=two \tromboII
2397 \context Staff = corni <
2398 \property Staff.midiInstrument = #"french horn"
2399 \property Staff.instrument = #`(lines "Corno"
2400 (columns "(E" ,text-flat ")"))
2401 \property Staff.instr = #`(lines "Cor."
2402 (columns "(E" ,text-flat ")"))
2403 \property Staff.transposing = #3
2404 \notes \key bes \major
2405 \context Voice=one \corno
2410 indent = 15 * \staffspace
2411 linewidth = 55 * \staffspace
2412 textheight = 90 * \staffspace
2414 \HaraKiriStaffContext
2423 @center @strong{Zo, goed lieverd?}
2425 @center How's, this babe?
2433 @lilypondfile{os-score.ly}
2437 \include "os-music.ly"
2439 First we need to include the music definitions we made in
2444 #(ly:set-point-and-click 'line-column)
2447 This piece of Scheme code executes the function
2448 @code{ly:set-point-and-click} with the argument
2449 @code{line-column}. Editing input files can be complicated if you're
2450 working with large files: if you're digitizing existing music, you have
2451 to synchronize the .ly file, the sheet music on your lap and the sheet
2452 music on the screen. The point-and-click mechanism makes it easy to
2453 find the origin of an error in the LY file: when you view the file with
2454 Xdvi and click on a note, your editor will jump to the spot where that
2455 note was entered. For more information, see @ref{Point and click}.
2460 #(define text-flat '((font-relative-size . -2)
2461 (music "accidentals--1")))
2464 To name the transposition of the french horn, we will need a piece of
2465 text with a flat sign. LilyPond has a mechanism for font selection and
2466 kerning called Scheme markup text (See @ref{Text markup}). The flat
2467 sign is taken from the music font, and its name is @code{accidentals--1}
2468 (The natural sign is called @code{accidentals-0}). The default font is
2469 too big for text, so we select a relative size of @code{-2}.
2476 All staves are simultaneous and use the same global settings.
2480 \property Score.BarNumber \override #'padding = #3
2482 LilyPond prints bar numbers at the start of each line, but
2483 unfortunately they end up a bit too close to the staff in this
2484 example. In LilyPond, a bar number is called @var{BarNumber}.
2485 BarNumber objects can be manipulated through their
2486 @var{side-position-interface}. One of the properties of a
2487 @var{side-position-interface} that can be tweaked is @var{padding}:
2488 the amount of extra space that is put between this and other objects.
2489 We set the padding to three staff spaces.
2491 You can find information on all these kind of properties in LilyPond's
2492 automatically generated documentation in
2494 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2495 or in @ref{Fine tuning a piece}.
2498 the online documentation or in the previous section of the tutorial.
2505 \context StaffGroup = woodwind <
2506 \context Staff = flauti <
2508 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2509 hold one or more @code{Staff}'s, and will print a big bracket at the
2510 left of the score. This starts a new staff group for the woodwind
2511 section (just the flutes in this case). Immediately after that, we
2512 start the staff for the two flutes, who also play simultaneously.
2516 \property Staff.midiInstrument = #"flute"
2518 Specify the instrument for MIDI output (see @ref{MIDI instrument
2523 \property Staff.instrument = "2 Flauti"
2524 \property Staff.instr = "Fl."
2526 This defines the instrument names to be printed in the
2527 margin. @code{instrument} specifies the name for the first line
2528 of the score, @code{instr} is used for the rest of the score.
2534 The flutes play in the default key.
2538 \context Voice=one @{ \voiceOne \flautoI @}
2539 \context Voice=two @{ \voiceTwo \flautoII @}
2541 Last come the actual flute parts. Remember that we're still in
2542 simultaneous mode. We name both voices differently, so that LilyPond
2543 will create two Voice contexts. The flute parts are simple, so
2544 we specify manually which voice is which: @code{\voiceOne} forces the
2545 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2553 Close the flutes staff and woodwind staff group.
2557 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2559 The timpani staff demonstrates a new piece of scheme markup, it sets two
2564 \context Voice=one \partcombine Voice
2565 \context Thread=one \tromboI
2566 \context Thread=two \tromboII
2568 You have seen the notation contexts Staff and Voice, but here's a new
2569 one: Thread. One or more Threads can be part of a Voice. Thread
2570 takes care of note heads and rests; Voice combine note heads onto a
2573 For the trumpets we use the automatic part combiner (see @ref{Automatic
2574 part combining}) to combine the two simultaneous trumpet parts onto the
2575 trumpet staff. Each trumpet gets its own Thread context, which must be
2576 named @code{one} and @code{two}). The part combiner makes these two
2577 threads share a Voice when they're similar, and splits the threads up
2578 when they're different.
2582 \property Staff.instrument = #`(lines "Corno"
2583 (columns "(E" ,text-flat ")"))
2585 The french horn (``Corno'') has the most complex scheme markup name, made
2586 up of two lines of text. The second line has three elements (columns) --
2587 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2588 and a final @code{")"}. Note that we use a backquote instead of an
2589 ordinary quote at the beginning of the Scheme expression to be able to
2590 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2594 \property Staff.transposing = #3
2596 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2597 transpose this staff by three steps.
2599 Note how we can choose different tunings for the text input, sheet music
2600 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2601 property @var{transposing}.
2605 \notes \key bes \major
2607 Since the horn is transposing, it's in a different key.
2611 indent = 15 * \staffspace
2612 linewidth = 55 * \staffspace
2614 We specify a big indent for the first line and a small linewidth for this
2619 Usually LilyPond's default setup of notation contexts (Thread,
2620 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2621 want a different type of Staff context.
2625 \HaraKiriStaffContext
2629 In orchestral scores it often happens that one instrument only has
2630 rests during one line of the score. @code{HaraKiriStaffContext} can
2631 be used as a regular @code{StaffContext} drop-in and will take care of
2632 the automatic removing of empty staves -- so if the strings are the
2633 only instruments playing for a line, LilyPond will only print the string
2634 parts for that line of the score. This reduces the number of page turns
2635 (and the number of dead trees!) required in a score.
2637 @node Extracting an individual part
2638 @subsection Extracting an individual part
2640 The third file, @file{os-flute-2.ly} also reads the definitions of the
2641 first (@file{os-music.ly}), and defines the @code{\score} block for the
2645 \include "os-music.ly"
2646 \include "paper16.ly"
2650 \property Score.skipBars = ##t
2651 \property Staff.midiInstrument = #"flute"
2657 instrument = "Flauto II"
2660 linewidth = 80 * \staffspace
2661 textheight = 200 * \staffspace
2669 @center @strong{Zo, goed lieverd?}
2671 @center How's, this babe?
2672 @center @emph{Flauto II}
2679 @lilypondfile{os-flute-2.ly}
2682 Because we separated the music definitions from the @code{\score}
2683 instantiations, we can easily define a second score with the music of
2684 the second flute. This is the part for the second flute player. Of
2685 course, we would make separate parts for all individual instruments if
2686 we were preparing the score for an orchestra.
2692 In this individual part the second flute has a whole staff for itself,
2693 so we don't want to force stem or tie directions.
2698 instrument = "Flauto II"
2701 The @code{\header} definitions were also read from @file{os-music.ly},
2702 but we need to set the instrument for this particular score.
2706 \property Score.skipBars = ##t
2708 In the conductor's full score, all bars with rests are printed, but for
2709 the individual parts, we want to print one multimeasure rest instead of
2710 many consecutive empty bars. LilyPond will do this if
2711 @code{Score.skipBars} is set to true (@code{##t}).
2714 @node Integrating text and music
2715 @section Integrating text and music
2718 @cindex La@TeX{}, music in
2719 @cindex HTML, music in
2720 @cindex Texinfo, music in
2722 Sometimes you might want to use music examples in a text that you are
2723 writing (for example a musicological treatise, a songbook, or (like us)
2724 the LilyPond manual). You can make such texts by hand, simply by
2725 importing a PostScript figure into your word processor. However,
2726 there is an automated procedure to reduce the amount of work.
2728 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2729 code. A script called @code{lilypond-book} will extract the music
2730 fragments, run LilyPond on them, and put back the resulting
2731 notation. This program is fully described in the chapter
2732 @ref{Integrating text and music with lilypond-book}. Here we show a
2733 small example. Since the example also contains explanatory text, we
2734 won't comment on the contents.
2737 \documentclass[a4paper]@{article@}
2740 In a lilypond-book document, you can freely mix music and text. For
2743 \score @{ \notes \relative c' @{
2744 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2747 Notice that the music line length matches the margin settings of the
2750 If you have no \verb+\score+ block in the fragment,
2751 \texttt@{lilypond-book@} will supply one:
2757 In the example you see here, two things happened: a
2758 \verb+\score+ block was added, and the line width was set to natural
2759 length. You can specify many more options using \LaTeX style options
2762 \begin[verbatim,11pt,singleline,
2763 fragment,relative,intertext="hi there!"]@{lilypond@}
2767 \texttt@{verbatim@} prints the LilyPond code in addition to the
2769 \texttt@{11pt@} selects the default music size,
2770 \texttt@{fragment@} adds a score block,
2771 \texttt@{relative@} uses relative mode for the fragment, and
2772 \texttt@{intertext@} specifies what to print between the
2773 \texttt@{verbatim@} code and the music.
2775 If you want to include large examples into the text, it may be more
2776 convenient to put the example in a separate file:
2778 \lilypondfile[printfilename]@{sammartini.ly@}
2780 The \texttt@{printfilename@} option adds the file name to the output.
2785 Under Unix, you can view the results as follows.
2789 $ lilypond-book --outdir=out/ lilbook.tex
2790 lilypond-book (GNU LilyPond) 1.6.1
2791 Reading `input/tutorial/lilbook.tex'
2792 Reading `input/tutorial/sammartini.ly'
2793 @var{lots of stuff deleted}
2794 Writing `out/lilbook.latex'
2796 $ latex lilbook.latex
2797 @var{lots of stuff deleted}
2801 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2802 and running latex creates a lot of temporary files, and you wouldn't want
2803 those to clutter up your working directory. Hence, we have them created
2804 in a separate subdirectory.
2806 The result looks more or less like this:
2810 In a lilypond-book document, you can freely mix music and text. For
2814 \notes \relative c' {
2815 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2822 Notice that the music line length matches the margin settings of the
2825 If you have no @code{\score} block in the fragment,
2826 @code{lilypond-book} will supply one:
2832 In the example you see here, a number of things happened: a
2833 @code{\score} block was added, and the line width was set to natural
2834 length. You can specify many more options using La@TeX{} style options
2837 @lilypond[verbatim,11pt,singleline,
2838 fragment,relative,intertext="hi there!"]
2842 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2843 the default music size, @code{fragment} adds a score block,
2844 @code{relative} uses relative mode for the fragment, and
2845 @code{intertext} specifies what to print between the
2846 @code{verbatim} code and the music.
2848 If you include large examples into the text, it may be more convenient
2849 to put the example in a separate file:
2851 @lilypondfile[printfilename,noquote]{sammartini.ly}
2853 The @code{printfilename} option adds the file name to the output.
2854 @node End of tutorial
2855 @section End of tutorial
2857 This is the end of the tutorial. If you read everything until this point
2858 (and understood everything!) then you're now an accomplished lilypond
2859 hacker. From here you should try fiddling with input files or making your
2860 own input files. Come back to the reference manual for more information
2863 Don't forget to check out the
2865 @uref{../../../../input/template/out-www/template.html,templates},
2866 @uref{../../../../input/test/out-www/test.html,examples} and
2867 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2870 templates, examples and feature tests.
2872 If you want to see real action LilyPond, head over to
2873 @uref{http://www.mutopiaproject.org}, which has many examples of
2874 classical music typeset with LilyPond.