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 do not 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, notime]
365 \property Staff.autoBeaming = ##f
366 \property Staff.Clef = \turnOff
371 @tab augmentation dots
373 @lilypond[relative 1, notime]
374 \property Staff.Clef = \turnOff
378 @item @code{c d e f g a b }
381 @lilypond[relative 1, notime]
382 \property Staff.Clef = \turnOff
386 @item @code{\clef treble \clef bass }
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-do not-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) do not 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 does not 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 do not
546 use octavation quotes (ie do not 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 do not 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 do not 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, notime]
654 \property Staff.Clef = \turnOff
661 @lilypond[relative 1, notime]
662 \property Score.timing = ##f
663 \property Staff.autoBeaming = ##f
664 \property Staff.Clef = \turnOff
668 @item @code{\key es \major }
677 @item @var{note}@code{'}
680 @lilypond[relative 1, 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, 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 does not
718 @c have a phrasing slur. The problem is that we do not 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 do not 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 does not 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{< >}. Do Not 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.
970 @node Printing lyrics
971 @section Printing lyrics
974 In this section we shall explain how to typeset the following
975 fragment of The Free Software Song:
977 @lilypond[singleline]
978 \score { \notes { \addlyrics
979 \notes \relative c' {
981 d'2 c4 b16-( a g a b a b c-) a2
982 b2 c4 b8-( a16 g a4-) g2 }
983 \context Lyrics \lyrics {
985 share the soft -- ware; }
987 \paper { linewidth = -1. }
993 @cindex @code{\lyrics}
996 To print lyrics, you must enter them and then instruct lilypond to
998 You can enter lyrics in a special input mode of LilyPond. This mode is
999 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1000 The purpose of this mode is that you can enter lyrics as plain text,
1001 punctuation, and accents without any hassle.
1003 Syllables are entered like notes, but with pitches replaced by text. For
1004 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1005 the hyphen has no special meaning for lyrics, and does not introduce
1008 Spaces can be introduced into a lyric either by using quotes:
1009 @code{"He could" not} or by using an underscore without quotes:
1010 @code{He_could not}. All unquoted underscores are converted to
1013 These are the lyrics for the free software song:
1018 share the soft -- ware; @}
1021 As you can see, extender lines are entered as @code{__}. This will
1022 create an extender, which is a line that extends over the entire
1023 duration of the lyric. This line will run all the way to the start
1024 of the next lyric, so you may want to shorten it by using a blank
1025 lyric (using @code{_}).
1028 You can use ordinary hyphens at the end of a syllable, i.e.
1032 but then the hyphen will be attached to the end of the first syllable.
1034 If you want them centered between syllables you can use the special
1035 `@code{-}@code{-}' lyric as a separate word between syllables. The
1036 hyphen will have variable length depending on the space between
1037 the syllables and it will be centered between the syllables.
1039 Normally the notes that you enter are transformed into note heads.
1040 Note heads alone make no sense, so they need surrounding information: a
1041 key signature, a clef, staff lines, etc. They need @emph{context}. In
1042 LilyPond, these symbols are created by objects called `interpretation
1043 contexts'. Interpretation contexts exist for generating notation
1044 (`notation context') and for generating sound (`performance
1045 context'). These objects only exist while LilyPond is executing.
1047 When LilyPond interprets music, it will create a Staff context.
1048 We do not want that default here, because we want lyric. The
1053 explicitly creates an interpretation context of
1054 @code{Lyrics} type to interpret the song text that we entered.
1056 The melody of the song does not offer anything new:
1058 \notes \relative c' @{
1060 d'2 c4 b16-( a g a b a b c-) a2
1061 b2 c4 b8-( a16 g a4-) g2 @}
1064 Both can be combined with the @code{\addlyrics}:
1067 \notes \relative c' @dots{}
1068 \context Lyrics \lyrics @dots{}
1071 The lyrics are also music expressions, similar to notes. Each syllable
1072 of the lyrics is put under a note of the melody.
1073 The complete file is listed here:
1076 \score @{ \notes @{ \addlyrics
1077 \notes \relative c' @{
1079 d'2 c4 b16 ( a g a b a b ) c a2
1080 b2 c4 b8 ( a16 g ) a4 g2 @}
1081 \context Lyrics \lyrics @{
1083 share the soft -- ware; @}
1085 \paper @{ linewidth = -1. @}
1091 @node A melody with chords
1092 @section A melody with chords
1094 [TODO: show how to do fixed 4 measures to the line]
1096 In this section we show how to typeset a melody with chord
1097 accompaniment. This file is included as @inputfileref{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 do not 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 do not 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 do not 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 @inputfileref{input/tutorial,sammartini.ly}.
1689 @lilypondfile[smallverbatim]{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 do not play. In this case, the viola does not 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 cannot 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 is not 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 @inputfileref{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-)^" "^\markup @{ \finger "5" @}
2158 A fingering instruction, which would be entered as @code{^5}, is put
2159 as close to the notes as possible, closer than the space entered to
2160 push away the 5. Hence, the 5 is entered as a normal text, formatting
2161 of fingering instructions.
2165 Normally one would specify all dynamics in the same voice, so that
2166 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2167 in this case, we do not want the decrescendo to be aligned with the
2168 piano sign. We achieve this by putting the dynamic markings in different
2169 voices. The crescendo should be above the upper staff. This can be
2170 forced by using the precooked command
2175 However, if you do that the decrescendo will be too close to the
2176 upper voice and collide with the stems. Looking at the manual for
2177 dynamics, we notice that ``Vertical positioning of these symbols is
2178 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2179 to the documentation of @code{DynamicLineSpanner}, we find that
2180 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2181 object not only puts dynamic objects next to the staff
2182 (@code{side-position-interface}), but it also groups dynamic objects
2183 (@code{axis-group-interface}), is considered a dynamic sign
2184 itself (@code{dynamic-interface}), and is an object. It has the standard
2185 @code{grob-interface} with all the variables that come with it.
2187 For the moment we are interested in side positioning:
2189 side-position-interface
2191 Position a victim object (this one) next to other objects (the
2192 support). In this case, the direction signifies where to put the
2193 victim object relative to the support (left or right, up or down?)
2195 Between the object and its support (in this case the notes in the voice
2196 going down), there should be more space. This space is controlled by
2197 @code{padding}, so we increase it.
2199 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2202 This command is almost like the command for setting slur attachments,
2203 but subtly different in its details. Grob properties can be
2204 manipulated with two commands: @code{\override} extends the
2205 variables with a setting, and @code{\revert} releases this
2206 setting. This has a certain theoretical appeal: the operations are
2207 simple and symmetric. But for practical use, it can be cumbersome. The
2208 commands act like parentheses: you should carefully balance the use of
2209 @code{\override} and @code{\revert}. The @code{\set} command is more
2210 friendly: it first does a @code{\revert} followed by @code{\override}.
2214 Brahms uses music notation is a slightly unorthodox way. Ties
2215 usually happen only within one voice. In this piece, the composer
2216 gladly produces ties that jump voices. We deal with this by faking
2217 these ties: whenever we need such a tie, we insert a notehead in a
2218 different voice, and blank the stem. This is done in the following
2221 @cindex transparent objects
2222 @cindex removing objects
2223 @cindex invisible objects
2225 \property Voice.Stem \set #'transparent = ##t
2228 Blanking the stem should be done for only one object. One of the ways
2229 to achieve that, is by setting the property before a note. Reverting
2230 it afterwards is tedious, so for setting a property only once, we have
2231 the syntax @code{\once}: it reverts the property directly before
2232 proceeding to the next step in time.
2234 The @code{\once} keyword is added to @code{\property}.
2237 Finally, the last tie is forced up using @code{\tieUp}.
2241 Here's the complete ``fine tuned'' version, which includes all the
2242 modifications we discussed in this section:
2244 @lilypondfile[verbatim]{brahms-tweaked.ly}
2247 @node An orchestral score
2248 @section An orchestral score
2252 * Extracting an individual part::
2256 Our next two examples demonstrate one way to create an orchestral score
2257 in LilyPond. When typesetting a piece for several instruments, you'll
2258 want to create a full score (for the conductor) along with several
2259 individual parts (for the players).
2261 LilyPond is well suited for this task. We will declare the music for
2262 each instrument individually, giving the music of each instrument its
2263 own name. These pieces of music are then combined in different
2264 @code{\score} blocks to produce different combinations of instruments
2265 (for example, one @code{\score} block may only include the cello part;
2266 another @code{\score} block may be for all the strings, and yet another
2267 @code{\score} block may be for all parts together).
2269 This orchestral score example consists of three input files. In the
2270 first file, @file{os-music.ly}, we define the music for all
2271 instruments. This file will be used for producing the score and
2272 the separate parts, but the file does not produce any sheet music
2273 itself. Other files reference this file by doing @code{\include
2279 title = "Zo, goed lieverd?"
2280 subtitle = "How's, this babe?"
2289 Key = \notes \key as \major
2290 flautoI = \notes\relative c'' @{
2292 bes as bes as bes as bes as
2294 flautoII = \notes\relative c'' @{
2295 as8 bes as bes R1 d4 ~ d
2297 tromboI = \notes\relative c'' @{
2298 c4. c8 c8 c4. es4 r as, r
2300 tromboII = \notes\relative c'' @{
2301 as4. as8 as8 as4. R1*1/2 as4 es'
2303 timpani = \notes\relative c, @{
2304 \times 2/3 @{ f4 f f @}
2305 \times 4/5 @{ as8 as as as as @}
2308 corno = \notes\relative c' @{
2309 bes4 d f, bes d f, bes d
2313 We will not examine this example line by line, since you already know
2314 most of it. We'll examine a few lines which contain new elements.
2325 Declare setting to be used globally. The @code{\skip} command produces
2326 no output, but moves forward in time: in this case, the duration of a
2327 half note (@code{2}), and that four times (@code{*4}). This brings us
2328 to the end of the piece, and we can set the end bar. You can use @code{s}
2329 as a shortcut for @code{\skip} (the last line of this section would
2330 be @code{s2*4 \bar"|."}).
2334 Key = \notes \key as \major
2336 Declare the key signature of the piece and assign it to the identifier
2337 @var{Key}. Later on we'll use @code{\Key} for all staves except those
2338 for transposing instruments.
2340 @node The full score
2341 @subsection The full score
2344 The second file, @inputfileref{input/tutorial,os-score.ly}, reads the
2345 definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and
2346 defines the @code{\score} block for the full conductor's score.
2351 \include "os-music.ly"
2352 \include "paper13.ly"
2354 #(ly:set-point-and-click 'line-column)
2355 textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
2359 \property Score.BarNumber \override #'padding = #3
2360 \context StaffGroup = woodwind <
2361 \context Staff = flauti <
2362 \property Staff.midiInstrument = #"flute"
2363 \property Staff.instrument = "2 Flauti"
2364 \property Staff.instr = "Fl."
2366 \context Voice=one @{ \voiceOne \flautoI @}
2367 \context Voice=two @{ \voiceTwo \flautoII @}
2370 \context StaffGroup = timpani <
2371 \context Staff = timpani <
2372 \property Staff.midiInstrument = #"timpani"
2373 \property Staff.instrument = \markup @{ \column << "Timpani" "(C-G)" >> @}
2374 \property Staff.instr = #"Timp."
2380 \context StaffGroup = brass <
2381 \context Staff = trombe <
2382 \property Staff.midiInstrument = #"trumpet"
2383 \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
2384 \property Staff.instr = \markup@{ \column << "Tbe." "(C)">> @}
2386 \context Voice=one \partcombine Voice
2387 \context Thread=one \tromboI
2388 \context Thread=two \tromboII
2390 \context Staff = corni <
2391 \property Staff.midiInstrument = #"french horn"
2392 \property Staff.instrument
2393 = \markup @{ \column << "Corno" @{ "(E" \textFlat ")" @} >> @}
2394 \property Staff.instr =
2395 \markup @{ \column << "Cor." @{ "(E" \textFlat ")" @} >> @}
2396 \property Staff.transposing = #3
2397 \notes \key bes \major
2398 \context Voice=one \corno
2403 indent = 15 * \staffspace
2404 linewidth = 60 * \staffspace
2405 textheight = 90 * \staffspace
2408 \consists "Multi_measure_rest_engraver"
2411 \HaraKiriStaffContext
2412 \remove "Multi_measure_rest_engraver"
2421 @center @strong{Zo, goed lieverd?}
2423 @center How's, this babe?
2431 @lilypondfile{os-score.ly}
2435 \include "os-music.ly"
2437 First we need to include the music definitions we made in
2442 #(ly:set-point-and-click 'line-column)
2445 This piece of Scheme code executes the function
2446 @code{ly:set-point-and-click} with the argument
2447 @code{line-column}. Editing input files can be complicated if you're
2448 working with large files: if you're digitizing existing music, you have
2449 to synchronize the .ly file, the sheet music on your lap and the sheet
2450 music on the screen. The point-and-click mechanism makes it easy to
2451 find the origin of an error in the LY file: when you view the file with
2452 Xdvi and click on a note, your editor will jump to the spot where that
2453 note was entered. For more information, see @ref{Point and click}.
2458 #(define text-flat '((font-relative-size . -2)
2459 (music "accidentals--1")))
2462 To name the transposition of the french horn, we will need a piece of
2463 text with a flat sign. LilyPond has a mechanism for font selection and
2464 kerning called Scheme markup text (See @ref{Text markup}). The flat
2465 sign is taken from the music font, and its name is @code{accidentals--1}
2466 (The natural sign is called @code{accidentals-0}). The default font is
2467 too big for text, so we select a relative size of @code{-2}.
2474 All staves are simultaneous and use the same global settings.
2478 \property Score.BarNumber \override #'padding = #3
2480 LilyPond prints bar numbers at the start of each line, but
2481 unfortunately they end up a bit too close to the staff in this
2482 example. In LilyPond, a bar number is called @var{BarNumber}.
2483 BarNumber objects can be manipulated through their
2484 @var{side-position-interface}. One of the properties of a
2485 @var{side-position-interface} that can be tweaked is @var{padding}:
2486 the amount of extra space that is put between this and other objects.
2487 We set the padding to three staff spaces.
2489 You can find information on all these kind of properties in LilyPond's
2490 automatically generated documentation in
2492 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2493 or in @ref{Fine tuning a piece}.
2496 the online documentation or in the previous section of the tutorial.
2503 \context StaffGroup = woodwind <
2504 \context Staff = flauti <
2506 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2507 hold one or more @code{Staff}'s, and will print a big bracket at the
2508 left of the score. This starts a new staff group for the woodwind
2509 section (just the flutes in this case). Immediately after that, we
2510 start the staff for the two flutes, who also play simultaneously.
2514 \property Staff.midiInstrument = #"flute"
2516 Specify the instrument for MIDI output (see @ref{MIDI instrument
2521 \property Staff.instrument = "2 Flauti"
2522 \property Staff.instr = "Fl."
2524 This defines the instrument names to be printed in the
2525 margin. @code{instrument} specifies the name for the first line
2526 of the score, @code{instr} is used for the rest of the score.
2532 The flutes play in the default key.
2536 \context Voice=one @{ \voiceOne \flautoI @}
2537 \context Voice=two @{ \voiceTwo \flautoII @}
2539 Last come the actual flute parts. Remember that we're still in
2540 simultaneous mode. We name both voices differently, so that LilyPond
2541 will create two Voice contexts. The flute parts are simple, so
2542 we specify manually which voice is which: @code{\voiceOne} forces the
2543 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2551 Close the flutes staff and woodwind staff group.
2555 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2557 The timpani staff demonstrates a new piece of scheme markup, it sets two
2562 \context Voice=one \partcombine Voice
2563 \context Thread=one \tromboI
2564 \context Thread=two \tromboII
2566 You have seen the notation contexts Staff and Voice, but here's a new
2567 one: Thread. One or more Threads can be part of a Voice. Thread
2568 takes care of note heads and rests; Voice combine note heads onto a
2571 For the trumpets we use the automatic part combiner (see @ref{Automatic
2572 part combining}) to combine the two simultaneous trumpet parts onto the
2573 trumpet staff. Each trumpet gets its own Thread context, which must be
2574 named @code{one} and @code{two}). The part combiner makes these two
2575 threads share a Voice when they're similar, and splits the threads up
2576 when they're different.
2580 \property Staff.instrument = #`(lines "Corno"
2581 (columns "(E" ,text-flat ")"))
2583 The french horn (``Corno'') has the most complex scheme markup name, made
2584 up of two lines of text. The second line has three elements (columns) --
2585 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2586 and a final @code{")"}. Note that we use a backquote instead of an
2587 ordinary quote at the beginning of the Scheme expression to be able to
2588 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2592 \property Staff.transposing = #3
2594 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2595 transpose this staff by three steps.
2597 Note how we can choose different tunings for the text input, sheet music
2598 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2599 property @var{transposing}.
2603 \notes \key bes \major
2605 Since the horn is transposing, it is in a different key.
2609 indent = 15 * \staffspace
2610 linewidth = 55 * \staffspace
2612 We specify a big indent for the first line and a small linewidth for this
2617 Usually LilyPond's default setup of notation contexts (Thread,
2618 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2619 want a different type of Staff context.
2623 \HaraKiriStaffContext
2627 In orchestral scores it often happens that one instrument only has
2628 rests during one line of the score. @code{HaraKiriStaffContext} can
2629 be used as a regular @code{StaffContext} drop-in and will take care of
2630 the automatic removing of empty staves -- so if the strings are the
2631 only instruments playing for a line, LilyPond will only print the string
2632 parts for that line of the score. This reduces the number of page turns
2633 (and the number of dead trees!) required in a score.
2635 @node Extracting an individual part
2636 @subsection Extracting an individual part
2638 The third file, @file{os-flute-2.ly} also reads the definitions of the
2639 first (@file{os-music.ly}), and defines the @code{\score} block for the
2643 \include "os-music.ly"
2644 \include "paper16.ly"
2648 \property Score.skipBars = ##t
2649 \property Staff.midiInstrument = #"flute"
2655 instrument = "Flauto II"
2658 linewidth = 80 * \staffspace
2659 textheight = 200 * \staffspace
2667 @center @strong{Zo, goed lieverd?}
2669 @center How's, this babe?
2670 @center @emph{Flauto II}
2677 @lilypondfile{os-flute-2.ly}
2680 Because we separated the music definitions from the @code{\score}
2681 instantiations, we can easily define a second score with the music of
2682 the second flute. This is the part for the second flute player. Of
2683 course, we would make separate parts for all individual instruments if
2684 we were preparing the score for an orchestra.
2690 In this individual part the second flute has a whole staff for itself,
2691 so we do not want to force stem or tie directions.
2696 instrument = "Flauto II"
2699 The @code{\header} definitions were also read from @file{os-music.ly},
2700 but we need to set the instrument for this particular score.
2704 \property Score.skipBars = ##t
2706 In the conductor's full score, all bars with rests are printed, but for
2707 the individual parts, we want to print one multimeasure rest instead of
2708 many consecutive empty bars. LilyPond will do this if
2709 @code{Score.skipBars} is set to true (@code{##t}).
2712 @node Integrating text and music
2713 @section Integrating text and music
2716 @cindex La@TeX{}, music in
2717 @cindex HTML, music in
2718 @cindex Texinfo, music in
2720 Sometimes you might want to use music examples in a text that you are
2721 writing (for example a musicological treatise, a songbook, or (like us)
2722 the LilyPond manual). You can make such texts by hand, simply by
2723 importing a PostScript figure into your word processor. However,
2724 there is an automated procedure to reduce the amount of work.
2726 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2727 code. A script called @code{lilypond-book} will extract the music
2728 fragments, run LilyPond on them, and put back the resulting
2729 notation. This program is fully described in the chapter
2730 @ref{Integrating text and music with lilypond-book}. Here we show a
2731 small example. Since the example also contains explanatory text, we
2732 will not comment on the contents.
2735 \documentclass[a4paper]@{article@}
2738 In a lilypond-book document, you can freely mix music and text. For
2741 \score @{ \notes \relative c' @{
2742 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2745 Notice that the music line length matches the margin settings of the
2748 If you have no \verb+\score+ block in the fragment,
2749 \texttt@{lilypond-book@} will supply one:
2755 In the example you see here, two things happened: a
2756 \verb+\score+ block was added, and the line width was set to natural
2757 length. You can specify many more options using \LaTeX style options
2760 \begin[verbatim,11pt,singleline,
2761 fragment,relative,intertext="hi there!"]@{lilypond@}
2765 \texttt@{verbatim@} prints the LilyPond code in addition to the
2767 \texttt@{11pt@} selects the default music size,
2768 \texttt@{fragment@} adds a score block,
2769 \texttt@{relative@} uses relative mode for the fragment, and
2770 \texttt@{intertext@} specifies what to print between the
2771 \texttt@{verbatim@} code and the music.
2773 If you want to include large examples into the text, it may be more
2774 convenient to put the example in a separate file:
2776 \lilypondfile[printfilename]@{sammartini.ly@}
2778 The \texttt@{printfilename@} option adds the file name to the output.
2783 Under Unix, you can view the results as follows.
2787 $ lilypond-book --outdir=out/ lilbook.tex
2788 lilypond-book (GNU LilyPond) 1.6.1
2789 Reading `input/tutorial/lilbook.tex'
2790 Reading `input/tutorial/sammartini.ly'
2791 @var{lots of stuff deleted}
2792 Writing `out/lilbook.latex'
2794 $ latex lilbook.latex
2795 @var{lots of stuff deleted}
2799 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2800 and running latex creates a lot of temporary files, and you would not want
2801 those to clutter up your working directory. Hence, we have them created
2802 in a separate subdirectory.
2804 The result looks more or less like this:
2808 In a lilypond-book document, you can freely mix music and text. For
2812 \notes \relative c' {
2813 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2820 Notice that the music line length matches the margin settings of the
2823 If you have no @code{\score} block in the fragment,
2824 @code{lilypond-book} will supply one:
2830 In the example you see here, a number of things happened: a
2831 @code{\score} block was added, and the line width was set to natural
2832 length. You can specify many more options using La@TeX{} style options
2835 @lilypond[verbatim,11pt,singleline,
2836 fragment,relative,intertext="hi there!"]
2840 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2841 the default music size, @code{fragment} adds a score block,
2842 @code{relative} uses relative mode for the fragment, and
2843 @code{intertext} specifies what to print between the
2844 @code{verbatim} code and the music.
2846 If you include large examples into the text, it may be more convenient
2847 to put the example in a separate file:
2849 @lilypondfile[printfilename]{sammartini.ly}
2851 The @code{printfilename} option adds the file name to the output.
2852 @node End of tutorial
2853 @section End of tutorial
2855 This is the end of the tutorial. If you read everything until this point
2856 (and understood everything!) then you're now an accomplished lilypond
2857 hacker. From here you should try fiddling with input files or making your
2858 own input files. Come back to the reference manual for more information
2861 Do not forget to check out the
2863 @uref{../../../../input/template/out-www/template.html,templates},
2864 @uref{../../../../input/test/out-www/test.html,examples} and
2865 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2868 templates, examples and feature tests.
2870 If you want to see real action LilyPond, head over to
2871 @uref{http://www.mutopiaproject.org}, which has many examples of
2872 classical music typeset with LilyPond.