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. If you give them the same name,
756 LilyPond will assume that you only want one staff, and will but both
757 pieces of music on the same staff.
762 We can now typeset a melody with two staves:
765 @lilypond[verbatim,singleline]
768 < \context Staff = staffA {
771 \relative c'' { e2-( d4 c2 b4 a8-[ a-] b-[ b-] g-[ g-] a2.-) }
773 \context Staff = staffB {
784 Notice that the time signature is specified in one melody staff only
785 (the top staff), but is printed on both. LilyPond knows that the time
786 signature should be the same for all staves.
790 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
792 @lilypond[verbatim,relative 1]
798 Dynamic signs are made by adding the markings to the note:
800 @lilypond[verbatim,relative 1]
806 Crescendi and decrescendi are started with the commands @code{\<} and
807 @code{\>}. The command @code{\!} finishes a crescendo on the note it
810 @lilypond[verbatim,relative 1]
811 c2-\< c2-\!-\ff c2-\> c2-\!
816 Chords can be made by surrounding notes with @code{<<} and @code{>>}:
818 @lilypond[relative 0, fragment,verbatim]
819 r4 <<c e g>>4 <<c f a>>8
825 You can combine beams and ties with chords. Beam and tie markings
826 must be placed outside the chord markers:
828 @lilypond[relative 0, fragment,verbatim]
829 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
834 When you want to combine chords with slurs and dynamics, technical
835 detail crops up: you have type these commands next to the notes, which
836 means that they have to be inside the @code{< >}. Don't get confused
837 by the chord @code{< >} and the dynamic @code{\< \>}!
842 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
844 @lilypond[relative 0, fragment]
846 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
854 @multitable @columnfractions .3 .3 .4
864 @lilypond[fragment, relative 1]
865 \property Score.timing = ##f
866 \property Staff.TimeSignature = \turnOff
867 \property Staff.autoBeaming = ##f
868 \property Staff.Clef = \turnOff
876 @lilypond[fragment, relative 1]
877 \property Score.timing = ##f
878 \property Staff.TimeSignature = \turnOff
879 \property Staff.autoBeaming = ##f
880 \property Staff.Clef = \turnOff
888 @lilypond[fragment, relative 1]
889 \property Score.timing = ##f
890 \property Staff.TimeSignature = \turnOff
891 \property Staff.autoBeaming = ##f
892 \property Staff.Clef = \turnOff
897 @item @code{< \context Staff ... >}
901 < \context Staff = SA { c'1 }
902 \context Staff = SB { c'1 } >
909 @lilypond[fragment, relative 1]
910 \property Staff.TimeSignature = \turnOff
911 \property Staff.Clef = \turnOff
916 @item @code{-\mf -\sfz}
919 @lilypond[fragment, relative 1]
920 \property Staff.TimeSignature = \turnOff
921 \property Staff.Clef = \turnOff
929 @lilypond[fragment, relative 1]
930 \property Score.timing = ##f
931 \property Staff.TimeSignature = \turnOff
932 \property Staff.autoBeaming = ##f
933 \property Staff.Clef = \turnOff
940 @lilypond[fragment, relative 1]
941 \property Score.timing = ##f
942 \property Staff.TimeSignature = \turnOff
943 \property Staff.autoBeaming = ##f
944 \property Staff.Clef = \turnOff
952 @lilypond[fragment, relative 1]
958 Now you know the basic ingredients of a music file, so this is the right
959 moment to try your at hand at doing it yourself: try typing some
960 simple examples, and experiment a little.
962 When you're comfortable with the basics, you might want to read
963 the rest of this chapter. It continues in tutorial-style, but it
964 is much more in-depth, dealing with more advanced topics such as
965 lyrics, chords, orchestral scores and parts, fine tuning of output,
966 polyphonic music, and integrating text and music.
972 @node Printing lyrics
973 @section Printing lyrics
976 In this section we shall explain how to typeset the following
977 fragment of The Free Software Song:
979 @lilypond[singleline]
980 \score { \notes { \addlyrics
981 \notes \relative c' {
983 d'2 c4 b16-( a g a b a b c-) a2
984 b2 c4 b8-( a16 g a4-) g2 }
985 \context Lyrics \lyrics {
987 share the soft -- ware; }
989 \paper { linewidth = -1. }
995 @cindex @code{\lyrics}
998 To print lyrics, you must enter them and then instruct lilypond to
1000 You can enter lyrics in a special input mode of LilyPond. This mode is
1001 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1002 The purpose of this mode is that you can enter lyrics as plain text,
1003 punctuation, and accents without any hassle.
1005 Syllables are entered like notes, but with pitches replaced by text. For
1006 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1007 the hyphen has no special meaning for lyrics, and does not introduce
1010 Spaces can be introduced into a lyric either by using quotes:
1011 @code{"He could" not} or by using an underscore without quotes:
1012 @code{He_could not}. All unquoted underscores are converted to
1015 These are the lyrics for the free software song:
1020 share the soft -- ware; @}
1023 As you can see, extender lines are entered as @code{__}. This will
1024 create an extender, which is a line that extends over the entire
1025 duration of the lyric. This line will run all the way to the start
1026 of the next lyric, so you may want to shorten it by using a blank
1027 lyric (using @code{_}).
1030 You can use ordinary hyphens at the end of a syllable, i.e.
1034 but then the hyphen will be attached to the end of the first syllable.
1036 If you want them centered between syllables you can use the special
1037 `@code{-}@code{-}' lyric as a separate word between syllables. The
1038 hyphen will have variable length depending on the space between
1039 the syllables and it will be centered between the syllables.
1041 Normally the notes that you enter are transformed into note heads.
1042 Note heads alone make no sense, so they need surrounding information: a
1043 key signature, a clef, staff lines, etc. They need @emph{context}. In
1044 LilyPond, these symbols are created by objects called `interpretation
1045 contexts'. Interpretation contexts exist for generating notation
1046 (`notation context') and for generating sound (`performance
1047 context'). These objects only exist while LilyPond is executing.
1049 When LilyPond interprets music, it will create a Staff context.
1050 We don't want that default here, because we want lyric. The
1055 explicitly creates an interpretation context of
1056 @code{Lyrics} type to interpret the song text that we entered.
1058 The melody of the song doesn't offer anything new:
1060 \notes \relative c' @{
1062 d'2 c4 b16-( a g a b a b c-) a2
1063 b2 c4 b8-( a16 g a4-) g2 @}
1066 Both can be combined with the @code{\addlyrics}:
1069 \notes \relative c' @dots{}
1070 \context Lyrics \lyrics @dots{}
1073 The lyrics are also music expressions, similar to notes. Each syllable
1074 of the lyrics is put under a note of the melody.
1075 The complete file is listed here:
1078 \score @{ \notes @{ \addlyrics
1079 \notes \relative c' @{
1081 d'2 c4 b16 ( a g a b a b ) c a2
1082 b2 c4 b8 ( a16 g ) a4 g2 @}
1083 \context Lyrics \lyrics @{
1085 share the soft -- ware; @}
1087 \paper @{ linewidth = -1. @}
1093 @node A melody with chords
1094 @section A melody with chords
1096 In this section we show how to typeset a melody with chord
1097 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1100 \include "paper16.ly"
1101 melody = \notes \relative c' @{
1105 c4 c8 d es-[ -( d-]-) c4 | f4 f8 g es-[-( d-)-] c g |
1106 c4 c8 d es-[ -( d-]-) c4 | d4 es8 d c4.
1110 accompaniment =\chords @{
1112 c2:3- f:3-.7 d:min es4 c8:min r8
1113 c2:min f:min7 g:7^3.5 c:min @}
1118 \context ChordNames \accompaniment
1119 \context Staff = mel @{
1124 \midi @{ \tempo 4=72 @}
1125 \paper @{ linewidth = 10.0\cm @}
1130 The result would look this.
1133 \include "paper16.ly"
1134 melody = \notes \relative c' {
1138 c4 c8 d es-[ -( d-)-] c4 | f4 f8 g es-(-[ d-)-] c g |
1139 c4 c8 d es-(-[ d-]-) c4 | d4 es8 d c4.
1143 accompaniment =\chords {
1145 c2:3- f:3-.7 d:min es4 c8:min r8
1146 c2:min f:min7 g:7^3.5 c:min }
1151 \context ChordNames \accompaniment
1153 \context Staff = mel {
1154 \property Staff.autoBeaming = ##f
1158 \midi { \tempo 4=72 }
1159 \paper { linewidth = 10.0\cm }
1163 We will dissect this file line by line.
1168 \include "paper16.ly"
1171 Smaller size (suitable for inclusion in a book).
1175 melody = \notes \relative c' @{
1178 The structure of the file will be the same as the previous one: a
1179 @code{\score} block with music in it. To keep things readable, we will
1180 give different names to the different parts of music, and use the names
1181 to construct the music within the score block.
1188 @cindex @code{\partial}
1190 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1196 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1197 c4 c8 d [es () d] c4 | d4 es8 d c4.
1202 @cindex manual beaming
1203 @cindex automatic beaming, turning off
1204 We use explicit beaming. Since this is a song, we turn automatic
1205 beams off and use explicit beaming where needed.
1212 This ends the definition of @code{melody}.
1221 @cindex identifier assignment
1222 @cindex syllables, entering
1223 This defines the lyrics, similar to what we have seen before.
1228 accompaniment =\chords @{
1232 @cindex mode, chords
1233 We'll put chords over the music. To enter them, we use a special mode
1234 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1235 the names of the chords you want instead of listing the notes
1236 comprising the chord.
1243 There is no accompaniment during the anacrusis.
1252 @cindex chord modifier
1253 @cindex modifier, chord
1254 This is a c minor chord, lasting for a half note. Chords are entered using
1255 the tonic. Notes can be changed to create different chords. In this case,
1256 a lowered third is used (making a C major chord into a C minor chord).
1257 The code for this is @code{3-}.
1263 Similarly, @code{7} modifies (adds) a seventh, which is small by
1264 default to create the @code{f a c es} chord. Multiple modifiers must be
1272 Some modifiers have predefined names, e.g. @code{min} is the same as
1273 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1277 c2:min f:min7 g:7^3.5 c:min @}
1280 @cindex named modifier
1282 A named modifier @code{min} and a normal modifier @code{7} do not have
1283 to be separated by a dot. Tones from a chord are removed with chord
1284 subtractions. Subtractions are started with a caret, and they are
1285 also separated by dots. In this example, @code{g:7^3.5} produces a
1286 minor seventh (a G7 chord without the third or the fifth). The
1287 brace ends the sequential music.
1295 We assemble the music in the @code{\score} block. Melody, lyrics and
1296 accompaniment have to sound at the same time, so they should be
1297 @code{\simultaneous}.
1298 @cindex @code{\simultaneous}
1305 Chord mode generates notes grouped in @code{\simultaneous} music. If
1306 you remove the comment sign, you can see the chords in normal
1307 notation: they will be printed as note heads on a separate
1308 staff. To print them as chords names, they have to be interpreted as
1309 being chords, not notes. This is done with the following command:
1313 \context ChordNames \accompaniment
1317 @cindex interpretation context
1318 @cindex notation context
1321 Normally the notes that you enter are transformed into note heads.
1322 Note heads alone make no sense, so they need surrounding information: a key
1323 signature, a clef, staff lines, etc. They need @emph{context}. In
1324 LilyPond, these symbols are created by objects called `interpretation
1325 contexts'. Interpretation contexts exist for generating notation
1326 (`notation context') and for generating sound (`performance
1327 context'). These objects only exist while LilyPond is executing.
1329 When LilyPond interprets music, it will create a Staff context. If
1330 the @code{%} sign in the previous line were removed, you could see
1331 that mechanism in action.
1333 We don't want that default here, because we want chord names. The
1334 command above explicitly creates an interpretation context of
1335 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1340 \context Staff = mel @{
1344 We place the melody on a staff called @code{mel}. We give it a name to
1345 differentiate it from the one that would contain note heads for the
1346 chords, if you would remove the comment before the ``note heads''
1347 version of the accompaniment. By giving this staff a name, it is
1348 forced to be different.
1352 \property Staff.autoBeaming = ##f
1356 @cindex context variables
1357 @cindex setting context variables
1358 An interpretation context has variables, called properties, that tune
1359 its behavior. One of the variables is @code{autoBeaming}. Setting
1360 this @code{Staff}'s property to @code{##f}, which is the boolean value
1361 @var{false}, turns the automatic beaming mechanism off for the current
1372 Finally, we put the melody on the current staff. Note that the
1373 @code{\property} directives and @code{\melody} are grouped in sequential
1374 music, so the property settings are done before the melody is
1380 \midi @{ \tempo 4=72@}
1383 MIDI (Musical Instrument Digital Interface) is a standard for
1384 connecting and recording digital instruments. So a MIDI file is like a
1385 tape recording of an instrument. The @code{\midi} block makes the
1386 music go to a MIDI file, so you can listen to the music you entered. It
1387 is great for checking the music. Whenever you hear something weird, you
1388 probably hear a typing error.
1390 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1391 also specifies an output method. You can specify the tempo using the
1392 @code{\tempo} command, in this case the tempo of quarter notes is set to
1393 72 beats per minute.
1397 \paper @{ linewidth = 10.0\cm @}
1400 We also want notation output. The linewidth is short so that the piece
1401 will be set in two lines.
1404 @section More stanzas
1409 If you have multiple stanzas printed underneath each other, the vertical
1410 groups of syllables should be aligned around punctuation. LilyPond can
1411 do this if you tell it which lyric lines belong to which melody.
1412 We show how you can do this by showing how you could print a frivolous
1413 fragment of a fictional Sesame Street duet.
1415 @lilypond[singleline,verbatim]
1418 \notes \relative c'' \context Voice = duet { \time 3/4
1420 \lyrics \context Lyrics <
1421 \context LyricsVoice = "duet-1" {
1422 \property LyricsVoice . stanza = "Bert"
1423 Hi, my name is bert. }
1424 \context LyricsVoice = "duet-2" {
1425 \property LyricsVoice . stanza = "Ernie"
1426 Ooooo, ch\'e -- ri, je t'aime. }
1431 To this end, give the Voice context an identity, and set the
1432 LyricsVoice to a name starting with that identity followed by a dash.
1433 In the following example, the Voice identity is @code{duet},
1435 \context Voice = duet @{
1440 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1442 \context LyricsVoice = "duet-1" @{
1443 Hi, my name is bert. @}
1444 \context LyricsVoice = "duet-2" @{
1445 Ooooo, ch\'e -- ri, je t'aime. @}
1448 We add the names of the singers. This can be done by setting
1449 @code{LyricsVoice.Stanza} (for the first system) and
1450 @code{LyricsVoice.stz} for the following systems. Note that you must
1451 surround dots with spaces in @code{\lyrics} mode.
1454 \property LyricsVoice . stanza = "Bert"
1456 \property LyricsVoice . stanza = "Ernie"
1459 The convention for naming @code{LyricsVoice} and @code{Voice} must
1460 also be used to get melismata on rests correct.
1463 @node More movements
1464 @section More movements
1466 The program @code{lilypond} only produces sheet music and does not
1467 create titles, subtitles, or print the composer's name. To do that,
1468 you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi}
1469 creates the title, then calls @code{lilypond} to format the sheet music.
1470 In this section, we show you how to create titles like this:
1472 @center @strong{Two miniatures}
1482 \paper { linewidth = -1.0 }
1494 \paper { linewidth = -1.0 }
1498 For example, consider the following file (@file{miniatures.ly})
1503 title = "Two miniatures"
1504 composer = "F. Bar Baz"
1505 tagline = "small is beautiful" @}
1507 \paper @{ linewidth = -1.0 @}
1511 Mental note: discuss Schenkerian analysis of these key pieces.
1516 \notes @{ c'4 d'4 @}
1522 \notes @{ d'4 c'4 @}
1530 The information for the global titling is in a so-called header block.
1531 The information in this block is not used by LilyPond, but it is
1532 passed into @code{ly2dvi}, which uses this information to print titles
1535 @cindex identifier assignment
1536 the @code{\header} block contains assignments. In each assignment, a
1537 variable is set to a value. The header block for this file looks like
1539 @cindex @code{\header}
1542 title = "Two miniatures"
1543 composer = "F. Bar Baz"
1544 tagline = "small is beautiful"
1548 When you process a file with ly2dvi, a signature line is printed at
1549 the bottom of the last page. This signature is produced from the
1550 @code{tagline} field of @code{\header}. The default "Lily was here,
1551 @var{version number}" is convenient for programmers: archiving the
1552 layouts of different versions allows programmers to compare the
1553 versions using old print-outs.
1555 @cindex Lily was here
1556 @cindex signature line
1559 Many people find the default tagline (``Lily was here'') too droll.
1560 If that is the case, you can change @code{tagline} to something else,
1569 A paper block at top level (i.e. not in a @code{\score} block) sets the
1570 default page layout. The following @code{\score} blocks don't have
1571 @code{\paper} sections, so the settings of this block are used.
1573 The variable @code{linewidth} normally sets the length of the systems
1574 on the page. However, a negative value has a special meaning. If
1575 @code{linewidth} is less than 0, no line breaks are inserted into the
1576 score, and the spacing is set to natural length: a short phrase takes
1577 up little space, a longer phrase takes more space, all on the same line.
1582 Mental note: discuss Schenkerian analysis of these key pieces.
1587 Mental notes to yourself can be put into comments. There are two types
1588 of comments. Line comments are introduced by @code{%}, and block
1589 comments are delimited by @code{%@{} and @code{%@}}.
1594 \notes @{ c'4 d'4 @}
1597 In previous examples, most notes were specified in relative octaves
1598 (i.e. each note was put in the octave that is closest to its
1599 predecessor). Besides relative, there is also absolute octave
1600 specification, which you get when you don't include @code{\relative} in
1601 your input file. In this input mode, the middle C is denoted by
1602 @code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
1603 Going up, you get @code{c''} @code{c'''} etc.
1605 When you're copying music from existing sheet music, relative octaves
1606 are probably the easiest to use: you have to do less typing, and errors are
1607 easily spotted. However, if you write LilyPond input directly, either by
1608 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1616 The @code{\header} is normally at the top of the file, where it sets
1617 values for the rest of the file. If you want to typeset different pieces
1618 from one file (for example, if there are multiple movements, or if
1619 you're making an exercise book), you can put different @code{\score}
1620 blocks into the input file. @code{ly2dvi} will assemble all LilyPond
1621 output files into a big document. The contents of @code{\header} blocks
1622 specified within each score is used for the title of that movement.
1628 For example, the Opus number is put at the right, and the "piece" string
1629 will be at the left.
1636 title = "Two miniatures"
1637 composer = "F. Bar Baz"
1638 tagline = "small is beautiful" @}
1640 \paper @{ linewidth = -1.0 @}
1643 \notes @{ c'4 d'4 @}
1649 \notes @{ d'4 c'4 @}
1659 scoreA = \score @{ \deelA @}
1660 scoreB = \score @{ \deelA @}
1662 % \score @{ \scoreA @}
1663 \score @{ \scoreB @}
1671 Lilypond and its language are still under development, and
1672 occasionally details of the syntax are changed. The @code{version}
1673 fragment indicates which version of lilypond the input file was written
1674 for. When you compile this file, the version number will be checked
1675 and you will get a warning when the file is too old. This version
1676 number is also used by the @code{convert-ly} program (See
1677 @ref{Invoking convert-ly}), which can used to update the file to the
1678 latest lily version.
1681 @node A piano excerpt
1682 @section A piano excerpt
1684 Our eighth subject is a piece of piano music. The fragment in the
1685 input file is a piano reduction of the G major Sinfonia by Giovanni
1686 Battista Sammartini, composed around 1740. It's in the source
1687 package under the name @file{input/tutorial/sammartini.ly}.
1689 @lilypondfile[smallverbatim,noquote]{sammartini.ly}
1691 As you can see, this example features multiple voices on one staff. To
1692 make room for those voices, their notes should be stemmed in opposite
1695 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1696 with some other commonly used formatting instructions, but to explain how
1697 it works, we wrote our own here. Of course, you should use predefined
1698 identifiers like these if possible: you will be less affected by changes
1699 between different versions of LilyPond.
1703 viola = \notes \relative c' \context Voice = viola @{
1705 In this example you can see multiple parts on a staff. Each part is
1706 associated with one notation context. This notation context handles
1707 stems and dynamics (among other things). The type name of this context
1708 is @code{Voice}. For each part we have to make sure that there is
1709 precisely one @code{Voice} context, so we give it a unique name
1714 <<c g' c>>4-\arpeggio
1716 The delimiters @code{<<} and @code{>>} enclose the pitches of a chord.
1717 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line)
1728 We want the viola to have stems down, and have all the other
1729 characteristics of a second voice. This is enforced using the
1730 @code{\voiceTwo} command: it inserts instructions that makes stem,
1731 ties, slurs, etc. go down.
1739 Relative octaves work a little differently with chords. The starting
1740 point for the note following a chord is the first note of the chord. So
1741 the @code{g} gets an octave up quote: it is a fifth above the starting
1742 note of the previous chord (the central C).
1748 @code{s} is a spacer rest. It does not print anything, but it does have
1749 the duration of a rest. It is useful for filling up voices that
1750 temporarily don't play. In this case, the viola doesn't come until one
1751 and a half measure later.
1755 oboes = \notes \relative c'' \context Voice = oboe @{
1757 Now comes a part for two oboes. They play homophonically, so we
1758 print the notes as one voice that makes chords. Again, we insure that
1759 these notes are indeed processed by precisely one context with
1763 \voiceOne s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16
1766 The oboes should have stems up to keep them from interfering with
1767 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1771 \grace <<e g>>-( <<d f>>4-) <<c e>>2
1773 @cindex @code{\grace}
1776 @code{\grace} introduces grace notes. It takes one argument, in this
1777 case a chord. A slur is introduced starting from the @code{\grace}
1778 ending on the following chord.
1786 Tuplets are made with the @code{\times} keyword. It takes two
1787 arguments: a fraction and a piece of music. The duration of the piece
1788 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1789 of their notated duration, so in this case the fraction is 2/3.
1792 @{ <<d f>>8 <<e g>> <<f a>> @}
1794 The piece of music to be `tripletted' is sequential music containing
1801 At this point, the homophonic music splits into two rhythmically
1802 different parts. We can't use a sequence of chords to enter this, so
1803 we make a "chord of sequences" to do it. We start with the upper
1804 voice, which continues with upward stems:
1807 @{ \times 2/3 @{ a8 g c @} c2 @}
1814 The easiest way to enter multiple voices is demonstrated
1815 here. Separate the components of the voice (single notes or entire
1816 sequences) with @code{\\} in a simultaneous music expression. The
1817 @code{\\} separators split first voice, second voice, third voice, and
1820 As far as relative mode is concerned, the previous note is the
1821 @code{c'''2} of the upper voice, so we have to go an octave down for
1829 This ends the two-part section.
1833 \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |
1838 @code{\stemBoth} ends the forced stem directions. From here, stems are
1839 positioned as if it were single part music.
1841 The bass has a little hoom-pah melody to demonstrate parts switching
1842 between staves. Since it is repetitive, we use repeats:
1845 hoomPah = \repeat unfold 8
1847 @cindex unfolded @code{\repeat}
1848 The unfolded repeat prints the notes in its argument as if they were
1849 written out in full eight times.
1852 \notes \transpose c' @{
1855 @cindex relative mode and transposing
1857 Transposing can be done with @code{\transpose}, which takes two arguments.
1858 The first specifies what central C should be transposed to. The second
1859 is the to-be-transposed music. As you can see, in this case, the
1860 transposition has no effect, as central C stays at central C.
1862 The purpose of this no-op is to protect it from being interpreted as
1863 relative notes. Relative mode can not be used together with
1864 transposition, so @code{\relative} will leave the contents of
1865 @code{\hoomPah} alone. We can use it without having to worry about
1866 getting the motive in a wrong octave. Conversely, if you want to
1867 transpose a fragment of music entered with @code{\relative}, then you
1868 should make sure that @code{\transpose} comes before @code{\relative}.
1871 @cindex staff switch, manual
1872 @cindex cross staff voice, manual
1873 @cindex @code{\translator}
1876 \translator Staff = down
1879 \translator Staff = up
1883 Voices can switch between staves. Here you see two staff switching
1884 commands. The first one moves to the lower staff, the second one to
1885 the lower one. If you set the stem directions explicitly
1886 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1887 can be beamed together (despite jumping between staffs).
1891 bassvoices = \notes \relative c' @{
1893 \autochange Staff \hoomPah \context Voice
1898 \translator Staff = down
1900 @cindex staff switch
1901 @cindex cross staff voice
1902 We want the remaining part of this melody on the lower staff, so we do a
1903 manual staff switch here.
1908 \context Voice = reallyLow @{\stemDown g2-~ | g4 c8 @} >
1912 After skipping some lines, we see @code{~}. This mark makes ties. Note
1913 that ties and slurs are different things. A tie can only connect two
1914 note heads of the same pitch, whereas a slur can connect many notes
1921 A special context is needed to get cross staff beaming right. This
1922 context is called @code{PianoStaff}.
1925 \context Staff = bottom < \time 2/2 \clef bass
1927 The bottom staff must have a different clef.
1932 To make some more room on the line, the first (in this case the only)
1933 line is not indented. The line still looks very cramped, but that is due
1934 to the page layout of this document.
1940 * font-size, multi-stanza.
1942 * Simple part combining in a Hymn
1946 @node Fine tuning a piece
1947 @section Fine tuning a piece
1949 In this section we show some ways to fine tune the final output of a
1950 piece. We do so using a single measure of a moderately complex piano
1951 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
1952 tuned and the untuned versions) are in @file{input/tutorial/}.
1954 The code for the untuned example shows us some new things.
1956 @lilypondfile[verbatim]{brahms-original.ly}
1966 Hairpin dynamics can be easily added to Lilypond scores. Beginning a
1967 crescendo is indicated with @code{\<} and ending a crescendo is indicated
1968 with @code{\!}. A decrescendo can be indicated with @code{\>} and
1969 @code{\!}. Absolute dynamics (sometimes called ``Letter dynamics'') can
1970 be entered using @code{\p}, @code{\mf}, etc. All these dynamics will
1971 apply to the whole chord where they are entered, but for syntactical
1972 reasons they must be attached to one of the notes of the chord.
1974 @cindex fingering instructions
1976 Fingering indications are entered with @code{-@var{N}}, where
1979 Now that we have the basic piece of music entered, we want to fine
1980 tune it so that we get something that resembles the original printed
1981 edition by Schott/Universal Edition:
1983 @lilypondfile{brahms-tweaked.ly}
1985 @cindex tuning graphical objects
1987 Fine tuning involves overriding the defaults of the printing system.
1988 We do this by setting variables which control how Lilypond prints
1989 symbols. Printed symbols are called graphical objects (often
1990 abbreviated to @emph{grob}). Each object is described by a bunch of
1991 settings. Every setting is a variable: it has a name and a value
1992 which you can change. These values determine the fonts, offsets,
1993 sub-routines to be called on the object, etc. The initial values of
1994 these settings are set in the Scheme file
1995 @file{scm/grob-description.scm}.
1997 @cindex slur attachments
1999 We start with the slur in the upper part, running from F sharp to A. In
2000 the printed edition, this slur runs from stem to stem; in our version,
2001 the slur begins at the note head of the F sharp. The following property
2002 setting forces all slurs to run from stem to stem (not from or to note
2006 \property Voice.Slur \set #'attachment = #'(stem . stem)
2009 More precisely, this command modifies the definition of the @code{Slur}
2010 object in the current @code{Voice}. The variable @code{attachment} is
2011 set to the pair of symbols @code{'(stem . stem)}.
2013 Although this fixes the slur, it isn't very helpful for fine tuning in
2014 general: the lilypond back-end supports approximately 240 variables
2015 like @code{attachment}, each with their own meaning and own type
2016 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2017 different types of graphical objects, that may be created in 14
2018 different context types besides Voice.
2020 @cindex internal documentation
2021 @cindex finding graphical objects
2022 @cindex graphical object descriptions
2024 The interesting information is how you can figure out which properties
2025 to tune for your own scores. To discover this, you must have a copy of
2026 the internals document. This is a set of HTML pages which should be
2027 included if you installed a binary distribution@footnote{You can also
2028 compile them by executing @code{make -C Documentation/user/
2029 out/lilypond-internals.html} in the source package.}. These HTML pages
2030 are also available on the web: go to the lilypond website, click
2031 ``Documentation: Index'' on the side bar, look in the ``Information for
2032 uses'' section, and click on ``Documentation of internals''.
2034 You might want to bookmark either the HTML files on your disk, or the one
2035 on the web (the HTML on your hard drive will load much faster than the
2036 ones on the web!). One word of caution: the internals documentation is
2037 generated from the definitions that lily uses. For that reason, it is
2038 strongly tied to the version of LilyPond that you use. Before you
2039 proceed, please make sure that you are using the documentation that
2040 corresponds to the version of LilyPond that you are using.
2042 @c TODO: the quote is incorrect, although that shouldn't be a big
2043 @c problem for the reader.
2044 Suppose that you wanted to tune the behavior of the slur. The first
2045 step is to get some general information on slurs in lilypond. Turn to
2046 the index, and look up ``slur''. The section on slurs says
2048 The grob for this object is @internalsref{Slur}, generally in
2049 @internalsref{Voice} context.
2052 So the graphical object for this object is called @code{Slur}, and
2053 slurs are created in the @code{Voice} context. If you are reading
2054 this tutorial in the HTML version, then you can simply click Slur,
2055 otherwise, you should look it up the internal documentation: click
2056 ``grob overview'' and select ``slur'' (the list is alphabetical).
2058 Now you get a list of all the properties that the slur object
2059 supports, along with their default values. Among the properties we
2060 find the @code{attachment} property with its default setting.
2061 The property documentation explains that the following setting will
2062 produce the desired effect:
2064 \property Voice.Slur \set #'attachment = #'(stem . stem)
2067 If you ran the previous example, you have unknowingly already used
2068 this kind of command. The @file{ly/property-init.ly} contains the
2069 definition of @code{\stemUp}:
2071 stemUp = \property Voice.Stem \set #'direction = #1
2074 @c this is a long section, and adding an extra space here helps to
2075 @c break it into smaller subsections and thus is easier to understand.
2078 Next we want to move the fingering `3'. In the printed edition it is
2079 not above the stem, but a little lower and slightly left of the stem.
2080 From the user manual we find that the associated graphical object is
2081 called @code{Fingering}, but how do we know if we should use
2082 @code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
2083 bet, but you can also deduce this information from the internals
2084 documentation: if you visit the documentation of @code{Fingering}, you
2087 Fingering grobs are created by: Fingering_engraver
2090 Clicking @code{Fingering_engraver} will show you the documentation of
2091 the module responsible for interpreting the fingering instructions and
2092 translating them to a @code{Fingering} object. Such a module is called
2093 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2096 Fingering_engraver is part of contexts: Voice and TabVoice
2098 so tuning the settings for Fingering should be done using either
2100 \property Voice.Fingering \set @dots{}
2104 \property TabVoice.Fingering \set @dots{}
2107 Since the @code{TabVoice} is only used for tab notation, we see that
2108 the first guess @code{Voice} was indeed correct.
2110 @cindex setting object properties
2111 @cindex @code{extra-offset}
2113 For shifting the fingering, we use the property @code{extra-offset}.
2114 The following command manually adds an offset to the object. We move
2115 it a little to the left, and 1.8 staff space downwards.
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. The
2122 first number controls left-right movement; a positive number will move
2123 the object to the right. The second number controls up-down movement;
2124 a positive number will move it higher.
2126 @cindex reverting object properties
2127 @cindex undoing object properties
2129 We only want to offset a single object, so after the F-sharp we must
2130 undo the setting. The technical term is to revert the property.
2132 \property Voice.Fingering \revert #'extra-offset
2135 @cindex property types
2136 @cindex translator properties
2137 @cindex grob properties
2138 @cindex music properties
2141 There are three different types of variables in LilyPond, something
2142 which can be confusing at first (and for some people it stays confusing
2143 :). Variables such as @code{extra-offset} and @code{attachment} are
2144 called grob properties. They are not the same as translator properties,
2145 like @code{autoBeaming}. Finally, music expressions are internally
2146 stored using properties (so-called music properties). You will encounter
2147 music properties if you run Scheme functions on music using @code{\apply}.
2149 The second fingering instruction should be moved up a little to avoid
2150 a collision with the slur. This could be achieved with
2151 @code{extra-offset}, but in this case, a simpler mechanism also
2152 works. We insert an empty text between the 5 and the note. The empty
2153 text pushes the fingering instruction away:
2155 a^" "^#'(finger "5")
2158 Lilypond tries to put fingering instructions as close to the notes as
2159 possible. To make sure that Lilypond doesn't do that, we disguise the
2160 fingering as text: @code{(finger "5")}.
2164 Normally one would specify all dynamics in the same voice, so that
2165 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2166 in this case, we don't want the decrescendo to be aligned with the
2167 piano sign. We achieve this by putting the dynamic markings in different
2168 voices. The crescendo should be above the upper staff. This can be
2169 forced by using the precooked command
2174 However, if you do that the decrescendo will be too close to the
2175 upper voice and collide with the stems. Looking at the manual for
2176 dynamics, we notice that ``Vertical positioning of these symbols is
2177 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2178 to the documentation of @code{DynamicLineSpanner}, we find that
2179 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2180 object not only puts dynamic objects next to the staff
2181 (@code{side-position-interface}), but it also groups dynamic objects
2182 (@code{axis-group-interface}), is considered a dynamic sign
2183 itself (@code{dynamic-interface}), and is an object. It has the standard
2184 @code{grob-interface} with all the variables that come with it.
2186 For the moment we are interested in side positioning:
2188 side-position-interface
2190 Position a victim object (this one) next to other objects (the
2191 support). In this case, the direction signifies where to put the
2192 victim object relative to the support (left or right, up or down?)
2194 Between the object and its support (in this case the notes in the voice
2195 going down), there should be more space. This space is controlled by
2196 @code{padding}, so we increase it.
2198 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2201 This command is almost like the command for setting slur attachments,
2202 but subtly different in its details. Grob properties can be
2203 manipulated with two commands: @code{\override} extends the
2204 variables with a setting, and @code{\revert} releases this
2205 setting. This has a certain theoretical appeal: the operations are
2206 simple and symmetric. But for practical use, it can be cumbersome. The
2207 commands act like parentheses: you should carefully balance the use of
2208 @code{\override} and @code{\revert}. The @code{\set} command is more
2209 friendly: it first does a @code{\revert} followed by @code{\override}.
2213 Brahms uses music notation is a slightly unorthodox way. Ties
2214 usually happen only within one voice. In this piece, the composer
2215 gladly produces ties that jump voices. We deal with this by faking
2216 these ties: whenever we need such a tie, we insert a notehead in a
2217 different voice, and blank the stem. This is done in the following
2221 \property Voice.Stem \set #'transparent = ##t
2224 Blanking the stem should be done for only one object. One of the ways
2225 to achieve that, is by setting the property before a note. Reverting
2226 it afterwards is tedious, so for setting a property only once, we have
2227 the syntax @code{\once}: it reverts the property directly before
2228 proceeding to the next step in time.
2230 The @code{\once} keyword is added to @code{\property}.
2233 Finally, the last tie is forced up using @code{\tieUp}.
2237 Here's the complete ``fine tuned'' version, which includes all the
2238 modifications we discussed in this section:
2240 @lilypondfile[verbatim]{brahms-tweaked.ly}
2243 @node An orchestral score
2244 @section An orchestral score
2248 * Extracting an individual part::
2252 Our next two examples demonstrate one way to create an orchestral score
2253 in LilyPond. When typesetting a piece for several instruments, you'll
2254 want to create a full score (for the conductor) along with several
2255 individual parts (for the players).
2257 LilyPond is well suited for this task. We will declare the music for
2258 each instrument individually, giving the music of each instrument its
2259 own name. These pieces of music are then combined in different
2260 @code{\score} blocks to produce different combinations of instruments
2261 (for example, one @code{\score} block may only include the cello part;
2262 another @code{\score} block may be for all the strings, and yet another
2263 @code{\score} block may be for all parts together).
2265 This orchestral score example consists of three input files. In the
2266 first file, @file{os-music.ly}, we define the music for all
2267 instruments. This file will be used for producing the score and
2268 the separate parts, but the file doesn't produce any sheet music
2269 itself. Other files reference this file by doing @code{\include
2275 title = "Zo, goed lieverd?"
2276 subtitle = "How's, this babe?"
2285 Key = \notes \key as \major
2286 flautoI = \notes\relative c'' @{
2288 bes as bes as bes as bes as
2290 flautoII = \notes\relative c'' @{
2291 as8 bes as bes R1 d4 ~ d
2293 tromboI = \notes\relative c'' @{
2294 c4. c8 c8 c4. es4 r as, r
2296 tromboII = \notes\relative c'' @{
2297 as4. as8 as8 as4. R1*1/2 as4 es'
2299 timpani = \notes\relative c, @{
2300 \times 2/3 @{ f4 f f @}
2301 \times 4/5 @{ as8 as as as as @}
2304 corno = \notes\relative c' @{
2305 bes4 d f, bes d f, bes d
2309 We will not examine this example line by line, since you already know
2310 most of it. We'll examine a few lines which contain new elements.
2321 Declare setting to be used globally. The @code{\skip} command produces
2322 no output, but moves forward in time: in this case, the duration of a
2323 half note (@code{2}), and that four times (@code{*4}). This brings us
2324 to the end of the piece, and we can set the end bar. You can use @code{s}
2325 as a shortcut for @code{\skip} (the last line of this section would
2326 be @code{s2*4 \bar"|."}).
2330 Key = \notes \key as \major
2332 Declare the key signature of the piece and assign it to the identifier
2333 @var{Key}. Later on we'll use @code{\Key} for all staves except those
2334 for transposing instruments.
2336 @node The full score
2337 @subsection The full score
2340 The second file, @file{input/tutorial/os-score.ly}, reads the
2341 definitions of the first (@file{input/tutorial/os-music.ly}), and
2342 defines the @code{\score} block for the full conductor's score.
2347 \include "os-music.ly"
2348 \include "paper13.ly"
2350 #(ly:set-point-and-click 'line-column)
2351 textFlat = \markup {\smaller \musicglyph #"accidentals--1"}
2355 \property Score.BarNumber \override #'padding = #3
2356 \context StaffGroup = woodwind <
2357 \context Staff = flauti <
2358 \property Staff.midiInstrument = #"flute"
2359 \property Staff.instrument = "2 Flauti"
2360 \property Staff.instr = "Fl."
2362 \context Voice=one { \voiceOne \flautoI }
2363 \context Voice=two { \voiceTwo \flautoII }
2366 \context StaffGroup = timpani <
2367 \context Staff = timpani <
2368 \property Staff.midiInstrument = #"timpani"
2369 \property Staff.instrument = \markup { \column << "Timpani" "(C-G)" >> }
2370 \property Staff.instr = #"Timp."
2376 \context StaffGroup = brass <
2377 \context Staff = trombe <
2378 \property Staff.midiInstrument = #"trumpet"
2379 \property Staff.instrument = \markup { \column << "2 Trombe" "(C)" >> }
2380 \property Staff.instr = \markup{ \column << "Tbe." "(C)">> }
2382 \context Voice=one \partcombine Voice
2383 \context Thread=one \tromboI
2384 \context Thread=two \tromboII
2386 \context Staff = corni <
2387 \property Staff.midiInstrument = #"french horn"
2388 \property Staff.instrument
2389 = \markup { \column << "Corno" { "(E" \textFlat ")" } >> }
2390 \property Staff.instr =
2391 \markup { \column << "Cor." { "(E" \textFlat ")" } >> }
2392 \property Staff.transposing = #3
2393 \notes \key bes \major
2394 \context Voice=one \corno
2399 indent = 15 * \staffspace
2400 linewidth = 60 * \staffspace
2401 textheight = 90 * \staffspace
2404 \consists "Multi_measure_rest_engraver"
2407 \HaraKiriStaffContext
2408 \remove "Multi_measure_rest_engraver"
2420 @center @strong{Zo, goed lieverd?}
2422 @center How's, this babe?
2430 @lilypondfile{os-score.ly}
2434 \include "os-music.ly"
2436 First we need to include the music definitions we made in
2441 #(ly:set-point-and-click 'line-column)
2444 This piece of Scheme code executes the function
2445 @code{ly:set-point-and-click} with the argument
2446 @code{line-column}. Editing input files can be complicated if you're
2447 working with large files: if you're digitizing existing music, you have
2448 to synchronize the .ly file, the sheet music on your lap and the sheet
2449 music on the screen. The point-and-click mechanism makes it easy to
2450 find the origin of an error in the LY file: when you view the file with
2451 Xdvi and click on a note, your editor will jump to the spot where that
2452 note was entered. For more information, see @ref{Point and click}.
2457 #(define text-flat '((font-relative-size . -2)
2458 (music "accidentals--1")))
2461 To name the transposition of the french horn, we will need a piece of
2462 text with a flat sign. LilyPond has a mechanism for font selection and
2463 kerning called Scheme markup text (See @ref{Text markup}). The flat
2464 sign is taken from the music font, and its name is @code{accidentals--1}
2465 (The natural sign is called @code{accidentals-0}). The default font is
2466 too big for text, so we select a relative size of @code{-2}.
2473 All staves are simultaneous and use the same global settings.
2477 \property Score.BarNumber \override #'padding = #3
2479 LilyPond prints bar numbers at the start of each line, but
2480 unfortunately they end up a bit too close to the staff in this
2481 example. In LilyPond, a bar number is called @var{BarNumber}.
2482 BarNumber objects can be manipulated through their
2483 @var{side-position-interface}. One of the properties of a
2484 @var{side-position-interface} that can be tweaked is @var{padding}:
2485 the amount of extra space that is put between this and other objects.
2486 We set the padding to three staff spaces.
2488 You can find information on all these kind of properties in LilyPond's
2489 automatically generated documentation in
2491 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2492 or in @ref{Fine tuning a piece}.
2495 the online documentation or in the previous section of the tutorial.
2502 \context StaffGroup = woodwind <
2503 \context Staff = flauti <
2505 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2506 hold one or more @code{Staff}'s, and will print a big bracket at the
2507 left of the score. This starts a new staff group for the woodwind
2508 section (just the flutes in this case). Immediately after that, we
2509 start the staff for the two flutes, who also play simultaneously.
2513 \property Staff.midiInstrument = #"flute"
2515 Specify the instrument for MIDI output (see @ref{MIDI instrument
2520 \property Staff.instrument = "2 Flauti"
2521 \property Staff.instr = "Fl."
2523 This defines the instrument names to be printed in the
2524 margin. @code{instrument} specifies the name for the first line
2525 of the score, @code{instr} is used for the rest of the score.
2531 The flutes play in the default key.
2535 \context Voice=one @{ \voiceOne \flautoI @}
2536 \context Voice=two @{ \voiceTwo \flautoII @}
2538 Last come the actual flute parts. Remember that we're still in
2539 simultaneous mode. We name both voices differently, so that LilyPond
2540 will create two Voice contexts. The flute parts are simple, so
2541 we specify manually which voice is which: @code{\voiceOne} forces the
2542 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2550 Close the flutes staff and woodwind staff group.
2554 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2556 The timpani staff demonstrates a new piece of scheme markup, it sets two
2561 \context Voice=one \partcombine Voice
2562 \context Thread=one \tromboI
2563 \context Thread=two \tromboII
2565 You have seen the notation contexts Staff and Voice, but here's a new
2566 one: Thread. One or more Threads can be part of a Voice. Thread
2567 takes care of note heads and rests; Voice combine note heads onto a
2570 For the trumpets we use the automatic part combiner (see @ref{Automatic
2571 part combining}) to combine the two simultaneous trumpet parts onto the
2572 trumpet staff. Each trumpet gets its own Thread context, which must be
2573 named @code{one} and @code{two}). The part combiner makes these two
2574 threads share a Voice when they're similar, and splits the threads up
2575 when they're different.
2579 \property Staff.instrument = #`(lines "Corno"
2580 (columns "(E" ,text-flat ")"))
2582 The french horn (``Corno'') has the most complex scheme markup name, made
2583 up of two lines of text. The second line has three elements (columns) --
2584 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2585 and a final @code{")"}. Note that we use a backquote instead of an
2586 ordinary quote at the beginning of the Scheme expression to be able to
2587 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2591 \property Staff.transposing = #3
2593 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2594 transpose this staff by three steps.
2596 Note how we can choose different tunings for the text input, sheet music
2597 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2598 property @var{transposing}.
2602 \notes \key bes \major
2604 Since the horn is transposing, it's in a different key.
2608 indent = 15 * \staffspace
2609 linewidth = 55 * \staffspace
2611 We specify a big indent for the first line and a small linewidth for this
2616 Usually LilyPond's default setup of notation contexts (Thread,
2617 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2618 want a different type of Staff context.
2622 \HaraKiriStaffContext
2626 In orchestral scores it often happens that one instrument only has
2627 rests during one line of the score. @code{HaraKiriStaffContext} can
2628 be used as a regular @code{StaffContext} drop-in and will take care of
2629 the automatic removing of empty staves -- so if the strings are the
2630 only instruments playing for a line, LilyPond will only print the string
2631 parts for that line of the score. This reduces the number of page turns
2632 (and the number of dead trees!) required in a score.
2634 @node Extracting an individual part
2635 @subsection Extracting an individual part
2637 The third file, @file{os-flute-2.ly} also reads the definitions of the
2638 first (@file{os-music.ly}), and defines the @code{\score} block for the
2642 \include "os-music.ly"
2643 \include "paper16.ly"
2647 \property Score.skipBars = ##t
2648 \property Staff.midiInstrument = #"flute"
2654 instrument = "Flauto II"
2657 linewidth = 80 * \staffspace
2658 textheight = 200 * \staffspace
2666 @center @strong{Zo, goed lieverd?}
2668 @center How's, this babe?
2669 @center @emph{Flauto II}
2676 @lilypondfile{os-flute-2.ly}
2679 Because we separated the music definitions from the @code{\score}
2680 instantiations, we can easily define a second score with the music of
2681 the second flute. This is the part for the second flute player. Of
2682 course, we would make separate parts for all individual instruments if
2683 we were preparing the score for an orchestra.
2689 In this individual part the second flute has a whole staff for itself,
2690 so we don't want to force stem or tie directions.
2695 instrument = "Flauto II"
2698 The @code{\header} definitions were also read from @file{os-music.ly},
2699 but we need to set the instrument for this particular score.
2703 \property Score.skipBars = ##t
2705 In the conductor's full score, all bars with rests are printed, but for
2706 the individual parts, we want to print one multimeasure rest instead of
2707 many consecutive empty bars. LilyPond will do this if
2708 @code{Score.skipBars} is set to true (@code{##t}).
2711 @node Integrating text and music
2712 @section Integrating text and music
2715 @cindex La@TeX{}, music in
2716 @cindex HTML, music in
2717 @cindex Texinfo, music in
2719 Sometimes you might want to use music examples in a text that you are
2720 writing (for example a musicological treatise, a songbook, or (like us)
2721 the LilyPond manual). You can make such texts by hand, simply by
2722 importing a PostScript figure into your word processor. However,
2723 there is an automated procedure to reduce the amount of work.
2725 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2726 code. A script called @code{lilypond-book} will extract the music
2727 fragments, run LilyPond on them, and put back the resulting
2728 notation. This program is fully described in the chapter
2729 @ref{Integrating text and music with lilypond-book}. Here we show a
2730 small example. Since the example also contains explanatory text, we
2731 won't comment on the contents.
2734 \documentclass[a4paper]@{article@}
2737 In a lilypond-book document, you can freely mix music and text. For
2740 \score @{ \notes \relative c' @{
2741 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2744 Notice that the music line length matches the margin settings of the
2747 If you have no \verb+\score+ block in the fragment,
2748 \texttt@{lilypond-book@} will supply one:
2754 In the example you see here, two things happened: a
2755 \verb+\score+ block was added, and the line width was set to natural
2756 length. You can specify many more options using \LaTeX style options
2759 \begin[verbatim,11pt,singleline,
2760 fragment,relative,intertext="hi there!"]@{lilypond@}
2764 \texttt@{verbatim@} prints the LilyPond code in addition to the
2766 \texttt@{11pt@} selects the default music size,
2767 \texttt@{fragment@} adds a score block,
2768 \texttt@{relative@} uses relative mode for the fragment, and
2769 \texttt@{intertext@} specifies what to print between the
2770 \texttt@{verbatim@} code and the music.
2772 If you want to include large examples into the text, it may be more
2773 convenient to put the example in a separate file:
2775 \lilypondfile[printfilename]@{sammartini.ly@}
2777 The \texttt@{printfilename@} option adds the file name to the output.
2782 Under Unix, you can view the results as follows.
2786 $ lilypond-book --outdir=out/ lilbook.tex
2787 lilypond-book (GNU LilyPond) 1.6.1
2788 Reading `input/tutorial/lilbook.tex'
2789 Reading `input/tutorial/sammartini.ly'
2790 @var{lots of stuff deleted}
2791 Writing `out/lilbook.latex'
2793 $ latex lilbook.latex
2794 @var{lots of stuff deleted}
2798 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2799 and running latex creates a lot of temporary files, and you wouldn't want
2800 those to clutter up your working directory. Hence, we have them created
2801 in a separate subdirectory.
2803 The result looks more or less like this:
2807 In a lilypond-book document, you can freely mix music and text. For
2811 \notes \relative c' {
2812 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2819 Notice that the music line length matches the margin settings of the
2822 If you have no @code{\score} block in the fragment,
2823 @code{lilypond-book} will supply one:
2829 In the example you see here, a number of things happened: a
2830 @code{\score} block was added, and the line width was set to natural
2831 length. You can specify many more options using La@TeX{} style options
2834 @lilypond[verbatim,11pt,singleline,
2835 fragment,relative,intertext="hi there!"]
2839 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2840 the default music size, @code{fragment} adds a score block,
2841 @code{relative} uses relative mode for the fragment, and
2842 @code{intertext} specifies what to print between the
2843 @code{verbatim} code and the music.
2845 If you include large examples into the text, it may be more convenient
2846 to put the example in a separate file:
2848 @lilypondfile[printfilename,noquote]{sammartini.ly}
2850 The @code{printfilename} option adds the file name to the output.
2851 @node End of tutorial
2852 @section End of tutorial
2854 This is the end of the tutorial. If you read everything until this point
2855 (and understood everything!) then you're now an accomplished lilypond
2856 hacker. From here you should try fiddling with input files or making your
2857 own input files. Come back to the reference manual for more information
2860 Don't forget to check out the
2862 @uref{../../../../input/template/out-www/template.html,templates},
2863 @uref{../../../../input/test/out-www/test.html,examples} and
2864 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2867 templates, examples and feature tests.
2869 If you want to see real action LilyPond, head over to
2870 @uref{http://www.mutopiaproject.org}, which has many examples of
2871 classical music typeset with LilyPond.