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.
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 don't 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 doesn't 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 In this section we show how to typeset a melody with chord
1095 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1098 \include "paper16.ly"
1099 melody = \notes \relative c' @{
1103 c4 c8 d es-[ -( d-]-) c4 | f4 f8 g es-[-( d-)-] c g |
1104 c4 c8 d es-[ -( d-]-) c4 | d4 es8 d c4.
1108 accompaniment =\chords @{
1110 c2:3- f:3-.7 d:min es4 c8:min r8
1111 c2:min f:min7 g:7^3.5 c:min @}
1116 \context ChordNames \accompaniment
1117 \context Staff = mel @{
1122 \midi @{ \tempo 4=72 @}
1123 \paper @{ linewidth = 10.0\cm @}
1128 The result would look this.
1131 \include "paper16.ly"
1132 melody = \notes \relative c' {
1136 c4 c8 d es-[ -( d-)-] c4 | f4 f8 g es-(-[ d-)-] c g |
1137 c4 c8 d es-(-[ d-]-) c4 | d4 es8 d c4.
1141 accompaniment =\chords {
1143 c2:3- f:3-.7 d:min es4 c8:min r8
1144 c2:min f:min7 g:7^3.5 c:min }
1149 \context ChordNames \accompaniment
1151 \context Staff = mel {
1152 \property Staff.autoBeaming = ##f
1156 \midi { \tempo 4=72 }
1157 \paper { linewidth = 10.0\cm }
1161 We will dissect this file line by line.
1166 \include "paper16.ly"
1169 Smaller size (suitable for inclusion in a book).
1173 melody = \notes \relative c' @{
1176 The structure of the file will be the same as the previous one: a
1177 @code{\score} block with music in it. To keep things readable, we will
1178 give different names to the different parts of music, and use the names
1179 to construct the music within the score block.
1186 @cindex @code{\partial}
1188 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1194 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1195 c4 c8 d [es () d] c4 | d4 es8 d c4.
1200 @cindex manual beaming
1201 @cindex automatic beaming, turning off
1202 We use explicit beaming. Since this is a song, we turn automatic
1203 beams off and use explicit beaming where needed.
1210 This ends the definition of @code{melody}.
1219 @cindex identifier assignment
1220 @cindex syllables, entering
1221 This defines the lyrics, similar to what we have seen before.
1226 accompaniment =\chords @{
1230 @cindex mode, chords
1231 We'll put chords over the music. To enter them, we use a special mode
1232 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1233 the names of the chords you want instead of listing the notes
1234 comprising the chord.
1241 There is no accompaniment during the anacrusis.
1250 @cindex chord modifier
1251 @cindex modifier, chord
1252 This is a c minor chord, lasting for a half note. Chords are entered using
1253 the tonic. Notes can be changed to create different chords. In this case,
1254 a lowered third is used (making a C major chord into a C minor chord).
1255 The code for this is @code{3-}.
1261 Similarly, @code{7} modifies (adds) a seventh, which is small by
1262 default to create the @code{f a c es} chord. Multiple modifiers must be
1270 Some modifiers have predefined names, e.g. @code{min} is the same as
1271 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1275 c2:min f:min7 g:7^3.5 c:min @}
1278 @cindex named modifier
1280 A named modifier @code{min} and a normal modifier @code{7} do not have
1281 to be separated by a dot. Tones from a chord are removed with chord
1282 subtractions. Subtractions are started with a caret, and they are
1283 also separated by dots. In this example, @code{g:7^3.5} produces a
1284 minor seventh (a G7 chord without the third or the fifth). The
1285 brace ends the sequential music.
1293 We assemble the music in the @code{\score} block. Melody, lyrics and
1294 accompaniment have to sound at the same time, so they should be
1295 @code{\simultaneous}.
1296 @cindex @code{\simultaneous}
1303 Chord mode generates notes grouped in @code{\simultaneous} music. If
1304 you remove the comment sign, you can see the chords in normal
1305 notation: they will be printed as note heads on a separate
1306 staff. To print them as chords names, they have to be interpreted as
1307 being chords, not notes. This is done with the following command:
1311 \context ChordNames \accompaniment
1315 @cindex interpretation context
1316 @cindex notation context
1319 Normally the notes that you enter are transformed into note heads.
1320 Note heads alone make no sense, so they need surrounding information: a key
1321 signature, a clef, staff lines, etc. They need @emph{context}. In
1322 LilyPond, these symbols are created by objects called `interpretation
1323 contexts'. Interpretation contexts exist for generating notation
1324 (`notation context') and for generating sound (`performance
1325 context'). These objects only exist while LilyPond is executing.
1327 When LilyPond interprets music, it will create a Staff context. If
1328 the @code{%} sign in the previous line were removed, you could see
1329 that mechanism in action.
1331 We don't want that default here, because we want chord names. The
1332 command above explicitly creates an interpretation context of
1333 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1338 \context Staff = mel @{
1342 We place the melody on a staff called @code{mel}. We give it a name to
1343 differentiate it from the one that would contain note heads for the
1344 chords, if you would remove the comment before the ``note heads''
1345 version of the accompaniment. By giving this staff a name, it is
1346 forced to be different.
1350 \property Staff.autoBeaming = ##f
1354 @cindex context variables
1355 @cindex setting context variables
1356 An interpretation context has variables, called properties, that tune
1357 its behavior. One of the variables is @code{autoBeaming}. Setting
1358 this @code{Staff}'s property to @code{##f}, which is the boolean value
1359 @var{false}, turns the automatic beaming mechanism off for the current
1370 Finally, we put the melody on the current staff. Note that the
1371 @code{\property} directives and @code{\melody} are grouped in sequential
1372 music, so the property settings are done before the melody is
1378 \midi @{ \tempo 4=72@}
1381 MIDI (Musical Instrument Digital Interface) is a standard for
1382 connecting and recording digital instruments. So a MIDI file is like a
1383 tape recording of an instrument. The @code{\midi} block makes the
1384 music go to a MIDI file, so you can listen to the music you entered. It
1385 is great for checking the music. Whenever you hear something weird, you
1386 probably hear a typing error.
1388 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1389 also specifies an output method. You can specify the tempo using the
1390 @code{\tempo} command, in this case the tempo of quarter notes is set to
1391 72 beats per minute.
1395 \paper @{ linewidth = 10.0\cm @}
1398 We also want notation output. The linewidth is short so that the piece
1399 will be set in two lines.
1402 @section More stanzas
1407 If you have multiple stanzas printed underneath each other, the vertical
1408 groups of syllables should be aligned around punctuation. LilyPond can
1409 do this if you tell it which lyric lines belong to which melody.
1410 We show how you can do this by showing how you could print a frivolous
1411 fragment of a fictional Sesame Street duet.
1413 @lilypond[singleline,verbatim]
1416 \notes \relative c'' \context Voice = duet { \time 3/4
1418 \lyrics \context Lyrics <
1419 \context LyricsVoice = "duet-1" {
1420 \property LyricsVoice . stanza = "Bert"
1421 Hi, my name is bert. }
1422 \context LyricsVoice = "duet-2" {
1423 \property LyricsVoice . stanza = "Ernie"
1424 Ooooo, ch\'e -- ri, je t'aime. }
1429 To this end, give the Voice context an identity, and set the
1430 LyricsVoice to a name starting with that identity followed by a dash.
1431 In the following example, the Voice identity is @code{duet},
1433 \context Voice = duet @{
1438 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1440 \context LyricsVoice = "duet-1" @{
1441 Hi, my name is bert. @}
1442 \context LyricsVoice = "duet-2" @{
1443 Ooooo, ch\'e -- ri, je t'aime. @}
1446 We add the names of the singers. This can be done by setting
1447 @code{LyricsVoice.Stanza} (for the first system) and
1448 @code{LyricsVoice.stz} for the following systems. Note that you must
1449 surround dots with spaces in @code{\lyrics} mode.
1452 \property LyricsVoice . stanza = "Bert"
1454 \property LyricsVoice . stanza = "Ernie"
1457 The convention for naming @code{LyricsVoice} and @code{Voice} must
1458 also be used to get melismata on rests correct.
1461 @node More movements
1462 @section More movements
1464 The program @code{lilypond} only produces sheet music and does not
1465 create titles, subtitles, or print the composer's name. To do that,
1466 you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi}
1467 creates the title, then calls @code{lilypond} to format the sheet music.
1468 In this section, we show you how to create titles like this:
1470 @center @strong{Two miniatures}
1480 \paper { linewidth = -1.0 }
1492 \paper { linewidth = -1.0 }
1496 For example, consider the following file (@file{miniatures.ly})
1501 title = "Two miniatures"
1502 composer = "F. Bar Baz"
1503 tagline = "small is beautiful" @}
1505 \paper @{ linewidth = -1.0 @}
1509 Mental note: discuss Schenkerian analysis of these key pieces.
1514 \notes @{ c'4 d'4 @}
1520 \notes @{ d'4 c'4 @}
1528 The information for the global titling is in a so-called header block.
1529 The information in this block is not used by LilyPond, but it is
1530 passed into @code{ly2dvi}, which uses this information to print titles
1533 @cindex identifier assignment
1534 the @code{\header} block contains assignments. In each assignment, a
1535 variable is set to a value. The header block for this file looks like
1537 @cindex @code{\header}
1540 title = "Two miniatures"
1541 composer = "F. Bar Baz"
1542 tagline = "small is beautiful"
1546 When you process a file with ly2dvi, a signature line is printed at
1547 the bottom of the last page. This signature is produced from the
1548 @code{tagline} field of @code{\header}. The default "Lily was here,
1549 @var{version number}" is convenient for programmers: archiving the
1550 layouts of different versions allows programmers to compare the
1551 versions using old print-outs.
1553 @cindex Lily was here
1554 @cindex signature line
1557 Many people find the default tagline (``Lily was here'') too droll.
1558 If that is the case, you can change @code{tagline} to something else,
1567 A paper block at top level (i.e. not in a @code{\score} block) sets the
1568 default page layout. The following @code{\score} blocks don't have
1569 @code{\paper} sections, so the settings of this block are used.
1571 The variable @code{linewidth} normally sets the length of the systems
1572 on the page. However, a negative value has a special meaning. If
1573 @code{linewidth} is less than 0, no line breaks are inserted into the
1574 score, and the spacing is set to natural length: a short phrase takes
1575 up little space, a longer phrase takes more space, all on the same line.
1580 Mental note: discuss Schenkerian analysis of these key pieces.
1585 Mental notes to yourself can be put into comments. There are two types
1586 of comments. Line comments are introduced by @code{%}, and block
1587 comments are delimited by @code{%@{} and @code{%@}}.
1592 \notes @{ c'4 d'4 @}
1595 In previous examples, most notes were specified in relative octaves
1596 (i.e. each note was put in the octave that is closest to its
1597 predecessor). Besides relative, there is also absolute octave
1598 specification, which you get when you don't include @code{\relative} in
1599 your input file. In this input mode, the middle C is denoted by
1600 @code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
1601 Going up, you get @code{c''} @code{c'''} etc.
1603 When you're copying music from existing sheet music, relative octaves
1604 are probably the easiest to use: you have to do less typing, and errors are
1605 easily spotted. However, if you write LilyPond input directly, either by
1606 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1614 The @code{\header} is normally at the top of the file, where it sets
1615 values for the rest of the file. If you want to typeset different pieces
1616 from one file (for example, if there are multiple movements, or if
1617 you're making an exercise book), you can put different @code{\score}
1618 blocks into the input file. @code{ly2dvi} will assemble all LilyPond
1619 output files into a big document. The contents of @code{\header} blocks
1620 specified within each score is used for the title of that movement.
1626 For example, the Opus number is put at the right, and the "piece" string
1627 will be at the left.
1634 title = "Two miniatures"
1635 composer = "F. Bar Baz"
1636 tagline = "small is beautiful" @}
1638 \paper @{ linewidth = -1.0 @}
1641 \notes @{ c'4 d'4 @}
1647 \notes @{ d'4 c'4 @}
1657 scoreA = \score @{ \deelA @}
1658 scoreB = \score @{ \deelA @}
1660 % \score @{ \scoreA @}
1661 \score @{ \scoreB @}
1669 Lilypond and its language are still under development, and
1670 occasionally details of the syntax are changed. The @code{version}
1671 fragment indicates which version of lilypond the input file was written
1672 for. When you compile this file, the version number will be checked
1673 and you will get a warning when the file is too old. This version
1674 number is also used by the @code{convert-ly} program (See
1675 @ref{Invoking convert-ly}), which can used to update the file to the
1676 latest lily version.
1679 @node A piano excerpt
1680 @section A piano excerpt
1682 Our eighth subject is a piece of piano music. The fragment in the
1683 input file is a piano reduction of the G major Sinfonia by Giovanni
1684 Battista Sammartini, composed around 1740. It's in the source
1685 package under the name @file{input/tutorial/sammartini.ly}.
1687 @lilypondfile[smallverbatim,noquote]{sammartini.ly}
1689 As you can see, this example features multiple voices on one staff. To
1690 make room for those voices, their notes should be stemmed in opposite
1693 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1694 with some other commonly used formatting instructions, but to explain how
1695 it works, we wrote our own here. Of course, you should use predefined
1696 identifiers like these if possible: you will be less affected by changes
1697 between different versions of LilyPond.
1701 viola = \notes \relative c' \context Voice = viola @{
1703 In this example you can see multiple parts on a staff. Each part is
1704 associated with one notation context. This notation context handles
1705 stems and dynamics (among other things). The type name of this context
1706 is @code{Voice}. For each part we have to make sure that there is
1707 precisely one @code{Voice} context, so we give it a unique name
1712 <<c g' c>>4-\arpeggio
1714 The delimiters @code{<<} and @code{>>} enclose the pitches of a chord.
1715 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line)
1726 We want the viola to have stems down, and have all the other
1727 characteristics of a second voice. This is enforced using the
1728 @code{\voiceTwo} command: it inserts instructions that makes stem,
1729 ties, slurs, etc. go down.
1737 Relative octaves work a little differently with chords. The starting
1738 point for the note following a chord is the first note of the chord. So
1739 the @code{g} gets an octave up quote: it is a fifth above the starting
1740 note of the previous chord (the central C).
1746 @code{s} is a spacer rest. It does not print anything, but it does have
1747 the duration of a rest. It is useful for filling up voices that
1748 temporarily don't play. In this case, the viola doesn't come until one
1749 and a half measure later.
1753 oboes = \notes \relative c'' \context Voice = oboe @{
1755 Now comes a part for two oboes. They play homophonically, so we
1756 print the notes as one voice that makes chords. Again, we insure that
1757 these notes are indeed processed by precisely one context with
1761 \voiceOne s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16
1764 The oboes should have stems up to keep them from interfering with
1765 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1769 \grace <<e g>>-( <<d f>>4-) <<c e>>2
1771 @cindex @code{\grace}
1774 @code{\grace} introduces grace notes. It takes one argument, in this
1775 case a chord. A slur is introduced starting from the @code{\grace}
1776 ending on the following chord.
1784 Tuplets are made with the @code{\times} keyword. It takes two
1785 arguments: a fraction and a piece of music. The duration of the piece
1786 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1787 of their notated duration, so in this case the fraction is 2/3.
1790 @{ <<d f>>8 <<e g>> <<f a>> @}
1792 The piece of music to be `tripletted' is sequential music containing
1799 At this point, the homophonic music splits into two rhythmically
1800 different parts. We can't use a sequence of chords to enter this, so
1801 we make a "chord of sequences" to do it. We start with the upper
1802 voice, which continues with upward stems:
1805 @{ \times 2/3 @{ a8 g c @} c2 @}
1812 The easiest way to enter multiple voices is demonstrated
1813 here. Separate the components of the voice (single notes or entire
1814 sequences) with @code{\\} in a simultaneous music expression. The
1815 @code{\\} separators split first voice, second voice, third voice, and
1818 As far as relative mode is concerned, the previous note is the
1819 @code{c'''2} of the upper voice, so we have to go an octave down for
1827 This ends the two-part section.
1831 \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |
1836 @code{\stemBoth} ends the forced stem directions. From here, stems are
1837 positioned as if it were single part music.
1839 The bass has a little hoom-pah melody to demonstrate parts switching
1840 between staves. Since it is repetitive, we use repeats:
1843 hoomPah = \repeat unfold 8
1845 @cindex unfolded @code{\repeat}
1846 The unfolded repeat prints the notes in its argument as if they were
1847 written out in full eight times.
1850 \notes \transpose c' @{
1853 @cindex relative mode and transposing
1855 Transposing can be done with @code{\transpose}, which takes two arguments.
1856 The first specifies what central C should be transposed to. The second
1857 is the to-be-transposed music. As you can see, in this case, the
1858 transposition has no effect, as central C stays at central C.
1860 The purpose of this no-op is to protect it from being interpreted as
1861 relative notes. Relative mode can not be used together with
1862 transposition, so @code{\relative} will leave the contents of
1863 @code{\hoomPah} alone. We can use it without having to worry about
1864 getting the motive in a wrong octave. Conversely, if you want to
1865 transpose a fragment of music entered with @code{\relative}, then you
1866 should make sure that @code{\transpose} comes before @code{\relative}.
1869 @cindex staff switch, manual
1870 @cindex cross staff voice, manual
1871 @cindex @code{\translator}
1874 \translator Staff = down
1877 \translator Staff = up
1881 Voices can switch between staves. Here you see two staff switching
1882 commands. The first one moves to the lower staff, the second one to
1883 the lower one. If you set the stem directions explicitly
1884 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1885 can be beamed together (despite jumping between staffs).
1889 bassvoices = \notes \relative c' @{
1891 \autochange Staff \hoomPah \context Voice
1896 \translator Staff = down
1898 @cindex staff switch
1899 @cindex cross staff voice
1900 We want the remaining part of this melody on the lower staff, so we do a
1901 manual staff switch here.
1906 \context Voice = reallyLow @{\stemDown g2-~ | g4 c8 @} >
1910 After skipping some lines, we see @code{~}. This mark makes ties. Note
1911 that ties and slurs are different things. A tie can only connect two
1912 note heads of the same pitch, whereas a slur can connect many notes
1919 A special context is needed to get cross staff beaming right. This
1920 context is called @code{PianoStaff}.
1923 \context Staff = bottom < \time 2/2 \clef bass
1925 The bottom staff must have a different clef.
1930 To make some more room on the line, the first (in this case the only)
1931 line is not indented. The line still looks very cramped, but that is due
1932 to the page layout of this document.
1938 * font-size, multi-stanza.
1940 * Simple part combining in a Hymn
1944 @node Fine tuning a piece
1945 @section Fine tuning a piece
1947 In this section we show some ways to fine tune the final output of a
1948 piece. We do so using a single measure of a moderately complex piano
1949 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
1950 tuned and the untuned versions) are in @file{input/tutorial/}.
1952 The code for the untuned example shows us some new things.
1954 @lilypondfile[verbatim]{brahms-original.ly}
1964 Hairpin dynamics can be easily added to Lilypond scores. Beginning a
1965 crescendo is indicated with @code{\<} and ending a crescendo is indicated
1966 with @code{\!}. A decrescendo can be indicated with @code{\>} and
1967 @code{\!}. Absolute dynamics (sometimes called ``Letter dynamics'') can
1968 be entered using @code{\p}, @code{\mf}, etc. All these dynamics will
1969 apply to the whole chord where they are entered, but for syntactical
1970 reasons they must be attached to one of the notes of the chord.
1972 @cindex fingering instructions
1974 Fingering indications are entered with @code{-@var{N}}, where
1977 Now that we have the basic piece of music entered, we want to fine
1978 tune it so that we get something that resembles the original printed
1979 edition by Schott/Universal Edition:
1981 @lilypondfile{brahms-tweaked.ly}
1983 @cindex tuning graphical objects
1985 Fine tuning involves overriding the defaults of the printing system.
1986 We do this by setting variables which control how Lilypond prints
1987 symbols. Printed symbols are called graphical objects (often
1988 abbreviated to @emph{grob}). Each object is described by a bunch of
1989 settings. Every setting is a variable: it has a name and a value
1990 which you can change. These values determine the fonts, offsets,
1991 sub-routines to be called on the object, etc. The initial values of
1992 these settings are set in the Scheme file
1993 @file{scm/grob-description.scm}.
1995 @cindex slur attachments
1997 We start with the slur in the upper part, running from F sharp to A. In
1998 the printed edition, this slur runs from stem to stem; in our version,
1999 the slur begins at the note head of the F sharp. The following property
2000 setting forces all slurs to run from stem to stem (not from or to note
2004 \property Voice.Slur \set #'attachment = #'(stem . stem)
2007 More precisely, this command modifies the definition of the @code{Slur}
2008 object in the current @code{Voice}. The variable @code{attachment} is
2009 set to the pair of symbols @code{'(stem . stem)}.
2011 Although this fixes the slur, it isn't very helpful for fine tuning in
2012 general: the lilypond back-end supports approximately 240 variables
2013 like @code{attachment}, each with their own meaning and own type
2014 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2015 different types of graphical objects, that may be created in 14
2016 different context types besides Voice.
2018 @cindex internal documentation
2019 @cindex finding graphical objects
2020 @cindex graphical object descriptions
2022 The interesting information is how you can figure out which properties
2023 to tune for your own scores. To discover this, you must have a copy of
2024 the internals document. This is a set of HTML pages which should be
2025 included if you installed a binary distribution@footnote{You can also
2026 compile them by executing @code{make -C Documentation/user/
2027 out/lilypond-internals.html} in the source package.}. These HTML pages
2028 are also available on the web: go to the lilypond website, click
2029 ``Documentation: Index'' on the side bar, look in the ``Information for
2030 uses'' section, and click on ``Documentation of internals''.
2032 You might want to bookmark either the HTML files on your disk, or the one
2033 on the web (the HTML on your hard drive will load much faster than the
2034 ones on the web!). One word of caution: the internals documentation is
2035 generated from the definitions that lily uses. For that reason, it is
2036 strongly tied to the version of LilyPond that you use. Before you
2037 proceed, please make sure that you are using the documentation that
2038 corresponds to the version of LilyPond that you are using.
2040 @c TODO: the quote is incorrect, although that shouldn't be a big
2041 @c problem for the reader.
2042 Suppose that you wanted to tune the behavior of the slur. The first
2043 step is to get some general information on slurs in lilypond. Turn to
2044 the index, and look up ``slur''. The section on slurs says
2046 The grob for this object is @internalsref{Slur}, generally in
2047 @internalsref{Voice} context.
2050 So the graphical object for this object is called @code{Slur}, and
2051 slurs are created in the @code{Voice} context. If you are reading
2052 this tutorial in the HTML version, then you can simply click Slur,
2053 otherwise, you should look it up the internal documentation: click
2054 ``grob overview'' and select ``slur'' (the list is alphabetical).
2056 Now you get a list of all the properties that the slur object
2057 supports, along with their default values. Among the properties we
2058 find the @code{attachment} property with its default setting.
2059 The property documentation explains that the following setting will
2060 produce the desired effect:
2062 \property Voice.Slur \set #'attachment = #'(stem . stem)
2065 If you ran the previous example, you have unknowingly already used
2066 this kind of command. The @file{ly/property-init.ly} contains the
2067 definition of @code{\stemUp}:
2069 stemUp = \property Voice.Stem \set #'direction = #1
2072 @c this is a long section, and adding an extra space here helps to
2073 @c break it into smaller subsections and thus is easier to understand.
2076 Next we want to move the fingering `3'. In the printed edition it is
2077 not above the stem, but a little lower and slightly left of the stem.
2078 From the user manual we find that the associated graphical object is
2079 called @code{Fingering}, but how do we know if we should use
2080 @code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
2081 bet, but you can also deduce this information from the internals
2082 documentation: if you visit the documentation of @code{Fingering}, you
2085 Fingering grobs are created by: Fingering_engraver
2088 Clicking @code{Fingering_engraver} will show you the documentation of
2089 the module responsible for interpreting the fingering instructions and
2090 translating them to a @code{Fingering} object. Such a module is called
2091 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2094 Fingering_engraver is part of contexts: Voice and TabVoice
2096 so tuning the settings for Fingering should be done using either
2098 \property Voice.Fingering \set @dots{}
2102 \property TabVoice.Fingering \set @dots{}
2105 Since the @code{TabVoice} is only used for tab notation, we see that
2106 the first guess @code{Voice} was indeed correct.
2108 @cindex setting object properties
2109 @cindex @code{extra-offset}
2111 For shifting the fingering, we use the property @code{extra-offset}.
2112 The following command manually adds an offset to the object. We move
2113 it a little to the left, and 1.8 staff space downwards.
2115 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2117 The @code{extra-offset} is a low-level feature: it moves around
2118 objects in the printout; the formatting engine is completely oblivious
2119 to these offsets. The unit of these offsets are staff-spaces. The
2120 first number controls left-right movement; a positive number will move
2121 the object to the right. The second number controls up-down movement;
2122 a positive number will move it higher.
2124 @cindex reverting object properties
2125 @cindex undoing object properties
2127 We only want to offset a single object, so after the F-sharp we must
2128 undo the setting. The technical term is to revert the property.
2130 \property Voice.Fingering \revert #'extra-offset
2133 @cindex property types
2134 @cindex translator properties
2135 @cindex grob properties
2136 @cindex music properties
2139 There are three different types of variables in LilyPond, something
2140 which can be confusing at first (and for some people it stays confusing
2141 :). Variables such as @code{extra-offset} and @code{attachment} are
2142 called grob properties. They are not the same as translator properties,
2143 like @code{autoBeaming}. Finally, music expressions are internally
2144 stored using properties (so-called music properties). You will encounter
2145 music properties if you run Scheme functions on music using @code{\apply}.
2147 The second fingering instruction should be moved up a little to avoid
2148 a collision with the slur. This could be achieved with
2149 @code{extra-offset}, but in this case, a simpler mechanism also
2150 works. We insert an empty text between the 5 and the note. The empty
2151 text pushes the fingering instruction away:
2153 a-)^" "^\markup @{ \finger "5" @}
2156 A fingering instruction, which would be entered as @code{^5}, is put
2157 as close to the notes as possible, closer than the space entered to
2158 push away the 5. Hence, the 5 is entered as a normal text, formatting
2159 of fingering instructions.
2163 Normally one would specify all dynamics in the same voice, so that
2164 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2165 in this case, we don't want the decrescendo to be aligned with the
2166 piano sign. We achieve this by putting the dynamic markings in different
2167 voices. The crescendo should be above the upper staff. This can be
2168 forced by using the precooked command
2173 However, if you do that the decrescendo will be too close to the
2174 upper voice and collide with the stems. Looking at the manual for
2175 dynamics, we notice that ``Vertical positioning of these symbols is
2176 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2177 to the documentation of @code{DynamicLineSpanner}, we find that
2178 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2179 object not only puts dynamic objects next to the staff
2180 (@code{side-position-interface}), but it also groups dynamic objects
2181 (@code{axis-group-interface}), is considered a dynamic sign
2182 itself (@code{dynamic-interface}), and is an object. It has the standard
2183 @code{grob-interface} with all the variables that come with it.
2185 For the moment we are interested in side positioning:
2187 side-position-interface
2189 Position a victim object (this one) next to other objects (the
2190 support). In this case, the direction signifies where to put the
2191 victim object relative to the support (left or right, up or down?)
2193 Between the object and its support (in this case the notes in the voice
2194 going down), there should be more space. This space is controlled by
2195 @code{padding}, so we increase it.
2197 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2200 This command is almost like the command for setting slur attachments,
2201 but subtly different in its details. Grob properties can be
2202 manipulated with two commands: @code{\override} extends the
2203 variables with a setting, and @code{\revert} releases this
2204 setting. This has a certain theoretical appeal: the operations are
2205 simple and symmetric. But for practical use, it can be cumbersome. The
2206 commands act like parentheses: you should carefully balance the use of
2207 @code{\override} and @code{\revert}. The @code{\set} command is more
2208 friendly: it first does a @code{\revert} followed by @code{\override}.
2212 Brahms uses music notation is a slightly unorthodox way. Ties
2213 usually happen only within one voice. In this piece, the composer
2214 gladly produces ties that jump voices. We deal with this by faking
2215 these ties: whenever we need such a tie, we insert a notehead in a
2216 different voice, and blank the stem. This is done in the following
2219 @cindex transparent objects
2220 @cindex removing objects
2221 @cindex invisible objects
2223 \property Voice.Stem \set #'transparent = ##t
2226 Blanking the stem should be done for only one object. One of the ways
2227 to achieve that, is by setting the property before a note. Reverting
2228 it afterwards is tedious, so for setting a property only once, we have
2229 the syntax @code{\once}: it reverts the property directly before
2230 proceeding to the next step in time.
2232 The @code{\once} keyword is added to @code{\property}.
2235 Finally, the last tie is forced up using @code{\tieUp}.
2239 Here's the complete ``fine tuned'' version, which includes all the
2240 modifications we discussed in this section:
2242 @lilypondfile[verbatim]{brahms-tweaked.ly}
2245 @node An orchestral score
2246 @section An orchestral score
2250 * Extracting an individual part::
2254 Our next two examples demonstrate one way to create an orchestral score
2255 in LilyPond. When typesetting a piece for several instruments, you'll
2256 want to create a full score (for the conductor) along with several
2257 individual parts (for the players).
2259 LilyPond is well suited for this task. We will declare the music for
2260 each instrument individually, giving the music of each instrument its
2261 own name. These pieces of music are then combined in different
2262 @code{\score} blocks to produce different combinations of instruments
2263 (for example, one @code{\score} block may only include the cello part;
2264 another @code{\score} block may be for all the strings, and yet another
2265 @code{\score} block may be for all parts together).
2267 This orchestral score example consists of three input files. In the
2268 first file, @file{os-music.ly}, we define the music for all
2269 instruments. This file will be used for producing the score and
2270 the separate parts, but the file doesn't produce any sheet music
2271 itself. Other files reference this file by doing @code{\include
2277 title = "Zo, goed lieverd?"
2278 subtitle = "How's, this babe?"
2287 Key = \notes \key as \major
2288 flautoI = \notes\relative c'' @{
2290 bes as bes as bes as bes as
2292 flautoII = \notes\relative c'' @{
2293 as8 bes as bes R1 d4 ~ d
2295 tromboI = \notes\relative c'' @{
2296 c4. c8 c8 c4. es4 r as, r
2298 tromboII = \notes\relative c'' @{
2299 as4. as8 as8 as4. R1*1/2 as4 es'
2301 timpani = \notes\relative c, @{
2302 \times 2/3 @{ f4 f f @}
2303 \times 4/5 @{ as8 as as as as @}
2306 corno = \notes\relative c' @{
2307 bes4 d f, bes d f, bes d
2311 We will not examine this example line by line, since you already know
2312 most of it. We'll examine a few lines which contain new elements.
2323 Declare setting to be used globally. The @code{\skip} command produces
2324 no output, but moves forward in time: in this case, the duration of a
2325 half note (@code{2}), and that four times (@code{*4}). This brings us
2326 to the end of the piece, and we can set the end bar. You can use @code{s}
2327 as a shortcut for @code{\skip} (the last line of this section would
2328 be @code{s2*4 \bar"|."}).
2332 Key = \notes \key as \major
2334 Declare the key signature of the piece and assign it to the identifier
2335 @var{Key}. Later on we'll use @code{\Key} for all staves except those
2336 for transposing instruments.
2338 @node The full score
2339 @subsection The full score
2342 The second file, @file{input/tutorial/os-score.ly}, reads the
2343 definitions of the first (@file{input/tutorial/os-music.ly}), and
2344 defines the @code{\score} block for the full conductor's score.
2349 \include "os-music.ly"
2350 \include "paper13.ly"
2352 #(ly:set-point-and-click 'line-column)
2353 textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
2357 \property Score.BarNumber \override #'padding = #3
2358 \context StaffGroup = woodwind <
2359 \context Staff = flauti <
2360 \property Staff.midiInstrument = #"flute"
2361 \property Staff.instrument = "2 Flauti"
2362 \property Staff.instr = "Fl."
2364 \context Voice=one @{ \voiceOne \flautoI @}
2365 \context Voice=two @{ \voiceTwo \flautoII @}
2368 \context StaffGroup = timpani <
2369 \context Staff = timpani <
2370 \property Staff.midiInstrument = #"timpani"
2371 \property Staff.instrument = \markup @{ \column << "Timpani" "(C-G)" >> @}
2372 \property Staff.instr = #"Timp."
2378 \context StaffGroup = brass <
2379 \context Staff = trombe <
2380 \property Staff.midiInstrument = #"trumpet"
2381 \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
2382 \property Staff.instr = \markup@{ \column << "Tbe." "(C)">> @}
2384 \context Voice=one \partcombine Voice
2385 \context Thread=one \tromboI
2386 \context Thread=two \tromboII
2388 \context Staff = corni <
2389 \property Staff.midiInstrument = #"french horn"
2390 \property Staff.instrument
2391 = \markup @{ \column << "Corno" @{ "(E" \textFlat ")" @} >> @}
2392 \property Staff.instr =
2393 \markup @{ \column << "Cor." @{ "(E" \textFlat ")" @} >> @}
2394 \property Staff.transposing = #3
2395 \notes \key bes \major
2396 \context Voice=one \corno
2401 indent = 15 * \staffspace
2402 linewidth = 60 * \staffspace
2403 textheight = 90 * \staffspace
2406 \consists "Multi_measure_rest_engraver"
2409 \HaraKiriStaffContext
2410 \remove "Multi_measure_rest_engraver"
2419 @center @strong{Zo, goed lieverd?}
2421 @center How's, this babe?
2429 @lilypondfile{os-score.ly}
2433 \include "os-music.ly"
2435 First we need to include the music definitions we made in
2440 #(ly:set-point-and-click 'line-column)
2443 This piece of Scheme code executes the function
2444 @code{ly:set-point-and-click} with the argument
2445 @code{line-column}. Editing input files can be complicated if you're
2446 working with large files: if you're digitizing existing music, you have
2447 to synchronize the .ly file, the sheet music on your lap and the sheet
2448 music on the screen. The point-and-click mechanism makes it easy to
2449 find the origin of an error in the LY file: when you view the file with
2450 Xdvi and click on a note, your editor will jump to the spot where that
2451 note was entered. For more information, see @ref{Point and click}.
2456 #(define text-flat '((font-relative-size . -2)
2457 (music "accidentals--1")))
2460 To name the transposition of the french horn, we will need a piece of
2461 text with a flat sign. LilyPond has a mechanism for font selection and
2462 kerning called Scheme markup text (See @ref{Text markup}). The flat
2463 sign is taken from the music font, and its name is @code{accidentals--1}
2464 (The natural sign is called @code{accidentals-0}). The default font is
2465 too big for text, so we select a relative size of @code{-2}.
2472 All staves are simultaneous and use the same global settings.
2476 \property Score.BarNumber \override #'padding = #3
2478 LilyPond prints bar numbers at the start of each line, but
2479 unfortunately they end up a bit too close to the staff in this
2480 example. In LilyPond, a bar number is called @var{BarNumber}.
2481 BarNumber objects can be manipulated through their
2482 @var{side-position-interface}. One of the properties of a
2483 @var{side-position-interface} that can be tweaked is @var{padding}:
2484 the amount of extra space that is put between this and other objects.
2485 We set the padding to three staff spaces.
2487 You can find information on all these kind of properties in LilyPond's
2488 automatically generated documentation in
2490 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2491 or in @ref{Fine tuning a piece}.
2494 the online documentation or in the previous section of the tutorial.
2501 \context StaffGroup = woodwind <
2502 \context Staff = flauti <
2504 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2505 hold one or more @code{Staff}'s, and will print a big bracket at the
2506 left of the score. This starts a new staff group for the woodwind
2507 section (just the flutes in this case). Immediately after that, we
2508 start the staff for the two flutes, who also play simultaneously.
2512 \property Staff.midiInstrument = #"flute"
2514 Specify the instrument for MIDI output (see @ref{MIDI instrument
2519 \property Staff.instrument = "2 Flauti"
2520 \property Staff.instr = "Fl."
2522 This defines the instrument names to be printed in the
2523 margin. @code{instrument} specifies the name for the first line
2524 of the score, @code{instr} is used for the rest of the score.
2530 The flutes play in the default key.
2534 \context Voice=one @{ \voiceOne \flautoI @}
2535 \context Voice=two @{ \voiceTwo \flautoII @}
2537 Last come the actual flute parts. Remember that we're still in
2538 simultaneous mode. We name both voices differently, so that LilyPond
2539 will create two Voice contexts. The flute parts are simple, so
2540 we specify manually which voice is which: @code{\voiceOne} forces the
2541 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2549 Close the flutes staff and woodwind staff group.
2553 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2555 The timpani staff demonstrates a new piece of scheme markup, it sets two
2560 \context Voice=one \partcombine Voice
2561 \context Thread=one \tromboI
2562 \context Thread=two \tromboII
2564 You have seen the notation contexts Staff and Voice, but here's a new
2565 one: Thread. One or more Threads can be part of a Voice. Thread
2566 takes care of note heads and rests; Voice combine note heads onto a
2569 For the trumpets we use the automatic part combiner (see @ref{Automatic
2570 part combining}) to combine the two simultaneous trumpet parts onto the
2571 trumpet staff. Each trumpet gets its own Thread context, which must be
2572 named @code{one} and @code{two}). The part combiner makes these two
2573 threads share a Voice when they're similar, and splits the threads up
2574 when they're different.
2578 \property Staff.instrument = #`(lines "Corno"
2579 (columns "(E" ,text-flat ")"))
2581 The french horn (``Corno'') has the most complex scheme markup name, made
2582 up of two lines of text. The second line has three elements (columns) --
2583 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2584 and a final @code{")"}. Note that we use a backquote instead of an
2585 ordinary quote at the beginning of the Scheme expression to be able to
2586 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2590 \property Staff.transposing = #3
2592 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2593 transpose this staff by three steps.
2595 Note how we can choose different tunings for the text input, sheet music
2596 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2597 property @var{transposing}.
2601 \notes \key bes \major
2603 Since the horn is transposing, it's in a different key.
2607 indent = 15 * \staffspace
2608 linewidth = 55 * \staffspace
2610 We specify a big indent for the first line and a small linewidth for this
2615 Usually LilyPond's default setup of notation contexts (Thread,
2616 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2617 want a different type of Staff context.
2621 \HaraKiriStaffContext
2625 In orchestral scores it often happens that one instrument only has
2626 rests during one line of the score. @code{HaraKiriStaffContext} can
2627 be used as a regular @code{StaffContext} drop-in and will take care of
2628 the automatic removing of empty staves -- so if the strings are the
2629 only instruments playing for a line, LilyPond will only print the string
2630 parts for that line of the score. This reduces the number of page turns
2631 (and the number of dead trees!) required in a score.
2633 @node Extracting an individual part
2634 @subsection Extracting an individual part
2636 The third file, @file{os-flute-2.ly} also reads the definitions of the
2637 first (@file{os-music.ly}), and defines the @code{\score} block for the
2641 \include "os-music.ly"
2642 \include "paper16.ly"
2646 \property Score.skipBars = ##t
2647 \property Staff.midiInstrument = #"flute"
2653 instrument = "Flauto II"
2656 linewidth = 80 * \staffspace
2657 textheight = 200 * \staffspace
2665 @center @strong{Zo, goed lieverd?}
2667 @center How's, this babe?
2668 @center @emph{Flauto II}
2675 @lilypondfile{os-flute-2.ly}
2678 Because we separated the music definitions from the @code{\score}
2679 instantiations, we can easily define a second score with the music of
2680 the second flute. This is the part for the second flute player. Of
2681 course, we would make separate parts for all individual instruments if
2682 we were preparing the score for an orchestra.
2688 In this individual part the second flute has a whole staff for itself,
2689 so we don't want to force stem or tie directions.
2694 instrument = "Flauto II"
2697 The @code{\header} definitions were also read from @file{os-music.ly},
2698 but we need to set the instrument for this particular score.
2702 \property Score.skipBars = ##t
2704 In the conductor's full score, all bars with rests are printed, but for
2705 the individual parts, we want to print one multimeasure rest instead of
2706 many consecutive empty bars. LilyPond will do this if
2707 @code{Score.skipBars} is set to true (@code{##t}).
2710 @node Integrating text and music
2711 @section Integrating text and music
2714 @cindex La@TeX{}, music in
2715 @cindex HTML, music in
2716 @cindex Texinfo, music in
2718 Sometimes you might want to use music examples in a text that you are
2719 writing (for example a musicological treatise, a songbook, or (like us)
2720 the LilyPond manual). You can make such texts by hand, simply by
2721 importing a PostScript figure into your word processor. However,
2722 there is an automated procedure to reduce the amount of work.
2724 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2725 code. A script called @code{lilypond-book} will extract the music
2726 fragments, run LilyPond on them, and put back the resulting
2727 notation. This program is fully described in the chapter
2728 @ref{Integrating text and music with lilypond-book}. Here we show a
2729 small example. Since the example also contains explanatory text, we
2730 won't comment on the contents.
2733 \documentclass[a4paper]@{article@}
2736 In a lilypond-book document, you can freely mix music and text. For
2739 \score @{ \notes \relative c' @{
2740 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2743 Notice that the music line length matches the margin settings of the
2746 If you have no \verb+\score+ block in the fragment,
2747 \texttt@{lilypond-book@} will supply one:
2753 In the example you see here, two things happened: a
2754 \verb+\score+ block was added, and the line width was set to natural
2755 length. You can specify many more options using \LaTeX style options
2758 \begin[verbatim,11pt,singleline,
2759 fragment,relative,intertext="hi there!"]@{lilypond@}
2763 \texttt@{verbatim@} prints the LilyPond code in addition to the
2765 \texttt@{11pt@} selects the default music size,
2766 \texttt@{fragment@} adds a score block,
2767 \texttt@{relative@} uses relative mode for the fragment, and
2768 \texttt@{intertext@} specifies what to print between the
2769 \texttt@{verbatim@} code and the music.
2771 If you want to include large examples into the text, it may be more
2772 convenient to put the example in a separate file:
2774 \lilypondfile[printfilename]@{sammartini.ly@}
2776 The \texttt@{printfilename@} option adds the file name to the output.
2781 Under Unix, you can view the results as follows.
2785 $ lilypond-book --outdir=out/ lilbook.tex
2786 lilypond-book (GNU LilyPond) 1.6.1
2787 Reading `input/tutorial/lilbook.tex'
2788 Reading `input/tutorial/sammartini.ly'
2789 @var{lots of stuff deleted}
2790 Writing `out/lilbook.latex'
2792 $ latex lilbook.latex
2793 @var{lots of stuff deleted}
2797 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2798 and running latex creates a lot of temporary files, and you wouldn't want
2799 those to clutter up your working directory. Hence, we have them created
2800 in a separate subdirectory.
2802 The result looks more or less like this:
2806 In a lilypond-book document, you can freely mix music and text. For
2810 \notes \relative c' {
2811 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2818 Notice that the music line length matches the margin settings of the
2821 If you have no @code{\score} block in the fragment,
2822 @code{lilypond-book} will supply one:
2828 In the example you see here, a number of things happened: a
2829 @code{\score} block was added, and the line width was set to natural
2830 length. You can specify many more options using La@TeX{} style options
2833 @lilypond[verbatim,11pt,singleline,
2834 fragment,relative,intertext="hi there!"]
2838 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2839 the default music size, @code{fragment} adds a score block,
2840 @code{relative} uses relative mode for the fragment, and
2841 @code{intertext} specifies what to print between the
2842 @code{verbatim} code and the music.
2844 If you include large examples into the text, it may be more convenient
2845 to put the example in a separate file:
2847 @lilypondfile[printfilename,noquote]{sammartini.ly}
2849 The @code{printfilename} option adds the file name to the output.
2850 @node End of tutorial
2851 @section End of tutorial
2853 This is the end of the tutorial. If you read everything until this point
2854 (and understood everything!) then you're now an accomplished lilypond
2855 hacker. From here you should try fiddling with input files or making your
2856 own input files. Come back to the reference manual for more information
2859 Don't forget to check out the
2861 @uref{../../../../input/template/out-www/template.html,templates},
2862 @uref{../../../../input/test/out-www/test.html,examples} and
2863 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2866 templates, examples and feature tests.
2868 If you want to see real action LilyPond, head over to
2869 @uref{http://www.mutopiaproject.org}, which has many examples of
2870 classical music typeset with LilyPond.