3 @c TODO: LilyPond LilyPond LilyPond
9 <!--- @@WEB-TITLE@@=Tutorial --->
13 * First steps:: Music language of LilyPond
14 * Running LilyPond:: Printing music
17 * A melody with chords ::
19 * More movements :: Joining separate pieces of music
20 * A piano excerpt:: Piano music
21 * Fine tuning a piece::
22 * An orchestral score:: Conductor's score and individual parts
23 * Integrating text and music:: Integrating text and music
24 * End of tutorial:: The end
27 Operating lilypond is done through text files: to print a piece of
28 music, you enter the music in a file. When you run lilypond (normally
29 using the program @code{ly2dvi}) on that file, the program produces
30 another file which contains sheet music that you can print or view.
32 This tutorial starts with a small introduction to the LilyPond music
33 language. After this first contact, we will show you how to run
34 LilyPond to produce printed output; you should then be able to create
35 your first sheets of music. The tutorial continues with more and more
41 We start off by showing how very simple music is entered in
42 LilyPond: you get a note simply by typing its note name, from
43 @code{a} through @code{g}. So if you enter
49 then the result looks like this:
52 \property Score.timing = ##f
53 \property Staff.TimeSignature = \turnOff
54 \transpose c'' { c d e f g a b }
59 We will continue with this format: first we show a snippet of input,
60 then the resulting output.
62 The length of a note is specified by adding a number, ``@code{1}'' for a
63 whole note, ``@code{2}'' for a half note, and so on:
70 @c missing clef seems to raise more questions than actual pitch of notes,
71 @c as these are snippets anyway
73 \property Score.timing = ##f
74 \property Staff.TimeSignature = \turnOff
75 \property Staff.autoBeaming = ##f
76 %\property Staff.Clef = \turnOff
77 \transpose c'' { a1 a2 a4 a16 a32 }
83 If you don't specify a duration, the previous one is used:
89 @c missing clef seems to raise more questions than actual pitch of notes,
90 @c as these are snippets anyway
92 \property Score.timing = ##f
93 \property Staff.TimeSignature = \turnOff
94 %\property Staff.Clef = \turnOff
95 \transpose c'' { a a a2 a }
101 A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
102 (@texiflat{}) by adding ``@code{es}''. As you would expect, a
103 double-sharp or double-flat is made by adding ``@code{isis}'' or
112 \property Score.timing = ##f
113 \property Staff.TimeSignature = \turnOff
114 \transpose c'' { cis1 ees fisis aeses }
120 Add a dot ``@code{.}'' after the duration to get a dotted note:
126 @c missing clef seems to raise more questions than actual pitch of notes,
127 @c as these are snippets anyway
129 \property Score.timing = ##f
130 \property Staff.TimeSignature \set #'transparent = ##t
131 %\property Staff.Clef = \turnOff
132 \transpose c'' { a2. a4 a8. a16 }
138 The meter (or time signature) can be set with the @code{\time} command:
147 @c a clef here may lead to confusion
149 \property Staff.Clef \set #'transparent = ##t
160 The clef can be set using the ``@code{\clef}'' command:
162 @c what is more common name treble or violin?
163 @c in Dutch, its violin.
164 @c in English its definitely treble.
174 \property Score.timing = ##f
175 \property Staff.TimeSignature = \turnOff
188 @c From these commands and notes, a piece of music can be formed. A piece
189 @c of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
191 When you enter these commands in a file, you must to enclose them in
192 ``@code{\notes @{ .. @}}''. This lets LilyPond know that music (and
193 not lyrics, for example) follows:
207 Now the piece of music is almost ready to be printed. The final step is to
208 combine the music with a printing command.
210 The printing command is the so-called ``@code{\paper}'' block. Later on
211 you will see that the @code{\paper} block is used to customize
212 printing specifics. The music and the @code{\paper} block are combined by
213 enclosing them in ``@code{\score @{ ... @}}''. This is what a full
214 LilyPond source file looks like:
237 \paper { linewidth = 60 * \staffspace }
244 @node Running LilyPond
245 @section Running LilyPond
247 In the last section we explained what kind of things you could enter
248 in a lilypond file. In this section we explain how to run LilyPond
249 and how to view or print the output. If you have not used LilyPond
250 before, want to test your setup of LilyPond, or want to run an example
251 file yourself, read this section. The instructions that follow
252 are for running LilyPond on Unix-like systems. Some additional
253 instructions for running LilyPond on Windows are given at the end of
256 Begin by opening a terminal window and starting a text editor.
257 For example, you could open an xterm and execute @code{joe}. In your
258 text editor, enter the following input and save the file as
264 \notes @{ c'4 e' g' @}
271 @c now this is weird, running ly2dvi to run LilyPond
272 @c (therefore name change proposal)
274 LilyPond is the program that computes the sheet music. All other
275 things, such as adding titles, page breaking and other page layout,
276 are done by a small wrapper program called
277 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
278 then adds the titling and page layout instructions. To process
279 @file{test.ly} with @code{ly2dvi}, proceed as follows:
287 You will see the following on your screen:
292 Now processing: `/home/fred/ly/test.ly'
294 Interpreting music...[1]
295 @emph{ ... more interesting stuff ... }
296 PS output to `test.ps'...
297 DVI output to `test.dvi'...
301 @cindex Viewing music
304 The results of the ly2dvi run are two files, @file{test.dvi} and
305 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
306 You can view the PS file using the program ghostview. If a version of
307 ghostview is installed on your system, one of these commands will
308 produce a window with some music notation on your screen:
318 If the music on your screen looks good, you can print it by clicking
319 File/Print inside ghostview.
321 The DVI file (@file{test.dvi}) contains the same sheet music in a
322 different format. DVI files are more easily processed by the computer,
323 so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
324 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse buttons
325 activate magnifying glasses. Unfortunately, variable symbols (such as
326 beams and slurs) are not displayed in the magnifying glasses.
328 If your DVI viewer does not have a "Print" button, you can print the
329 file by executing @code{lpr test.ps}.
331 @c volgende alinea schrappen?
333 If your system does not support printing PostScript files, then you
334 can install Ghostscript, a PostScript emulator. Refer to
335 Ghostscript's website at @uref{http://www.ghostscript.com}.
339 @cindex Printing output
343 A final option is to use the popular PDF format. You can get a PDF
344 file by running @code{ly2dvi --pdf test.ly}. With @code{--pdf}
345 you will get DVI, PS and PDF files. Viewers for PS files also
346 accept PDF files, but there are also many other applications for
349 If you are familiar with @TeX{}, be warned: do not use other
350 DVI drivers like @code{dvilj}. The @TeX{} coming out of LilyPond
351 uses embedded PostScript code and will not render correctly if
352 you use anything other than @code{dvips}.
358 @unnumberedsubsec Windows users
359 Windows users can start the terminal by clicking on the LilyPond or
360 Cygwin icon. You can use any text editor (such as NotePad, Emacs or
361 Vim) to edit the LilyPond file. If you install the Cygwin's
362 @code{XFree86} X11 window system, @code{tetex-x11} and
363 @code{ghostscript-x11} packages too, you can view the @code{dvi}
364 output doing @code{xdvi test.dvi} as described above. If you have
365 installed a PostScript/PDF viewer, such as @code{GSView} from
366 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PS file can be done
370 @code{gsview32 test.ps}
373 You can also print from the command line by executing:
376 @code{gsview32 /s test.ps}
383 To run LilyPond, input a text file, then run the command @code{ly2dvi} on
384 that file. The resulting files are either DVI or PostScript, and can
385 be viewed with @code{xdvi} (unix) and ghostview (unix and windows)
386 respectively. The following table summarizes the constructs that were
387 discussed in the previous two sections.
389 @multitable @columnfractions .3 .3 .4
395 @item @code{1 2 8 16}
398 @lilypond[fragment, relative 1]
399 \property Staff.TimeSignature = \turnOff
400 \property Staff.autoBeaming = ##f
401 \property Staff.Clef = \turnOff
406 @tab augmentation dots
408 @lilypond[fragment, relative 1]
409 \property Staff.TimeSignature = \turnOff
410 \property Staff.Clef = \turnOff
414 @item @code{c d e f g a b }
417 @lilypond[fragment, relative 1]
418 \property Staff.TimeSignature = \turnOff
419 \property Staff.Clef = \turnOff
423 @item @code{\clef treble \clef bass }
427 \property Staff.TimeSignature \set #'transparent = ##t
434 @item @code{\time 3/4 \time 4/4 }
438 \property Staff.Clef \set #'transparent = ##t
451 We continue with the introduction of the remaining musical constructs.
452 Normal rests are entered just like notes with the name ``@code{r}'':
460 \property Score.timing = ##f
461 \property Staff.Clef = \turnOff
462 \property Staff.TimeSignature = \turnOff
469 @c Tim wants to move this quotes example just before the: quotes-don't-work
470 @c score, but we'd need to remove quotes from the other two (key and
473 @c better to have this just before the `octaves are bad' snipped
474 @c but we'd need to remove the ', from \key and tie
475 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
476 the note name, to lower a note one octave, add a ``low quote'' @code{,}
477 (a comma). Middle C is @code{c'}:
481 c'4 c'' c''' \clef bass c c,
485 \property Score.timing = ##f
486 \property Staff.TimeSignature = \turnOff
487 c'4 c'' c''' \clef bass c c,
492 A tie is created by entering a tilde ``@code{~}'' between the notes to
493 be tied. A tie between two notes means that the second note must not be
494 played separately; it just makes the first note sound longer:
497 @lilypond[fragment,verbatim]
503 The key signature is set with the command ``@code{\key}''. One caution:
504 you need to specify whether the key is @code{\major} or @code{\minor}.
514 \property Staff.TimeSignature = \turnOff
523 @c bit on the long/complex/scary taste
524 @c cheating a bit: two lines makes for a friendlier look
525 This example shows notes, ties, octave marks, and rests in action.
534 r4 r8 d''8 cis''4 e''
536 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
549 r4 r8 d''8 cis''4 e''
551 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
554 \paper { linewidth = 50*\staffspace }
560 There are some interesting points to note in this example.
561 Accidentals (sharps and flats) don't have to be marked explicitly: you
562 just enter the note name, and LilyPond determines whether or not to
563 print an accidental. Bar lines and beams are drawn automatically.
564 LilyPond calculates line breaks for you; it doesn't matter where you
565 make new lines in the source file. Finally, the order of time, key and
566 clef changes is not relevant: lilypond will use standard notation
567 conventions for ordering these items.
569 The example also indicates that a piece of music written in a high
570 register needs lots of quotes. This makes the input less readable,
571 and is also a potential source of errors.
573 The solution is to use ``relative octave'' mode. In practice, this is
574 the most convenient way to copy existing music. To use relative mode,
575 add @code{\relative} before the piece of music. You must also give a
576 note from which relative starts, in this case @code{c''}. If you don't
577 use octavation quotes (ie don't add ' or , after a note), relative mode
578 chooses the note that is closest to the previous one. Since most music
579 has small intervals, you can write quite a lot in relative mode without
580 using octavation quotes.
581 @c don't use commas or quotes in this sentence
582 For example: @code{c f} goes up; @code{c g} goes down:
592 \property Score.timing = ##f
593 \property Staff.TimeSignature = \turnOff
602 @c needed better, maybe even redundant explanation
603 @c added another example below.
604 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
605 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
606 You can make larger intervals by adding octavation quotes. Note that
607 quotes or commas do not determine the absolute height of a note;
608 the height of a note is relative to the previous one.
609 @c don't use commas or quotes in this sentence
610 For example: @code{c f,} goes down; @code{f, f} are both the same;
611 @code{c' c} are the same; and @code{c g'} goes up:
621 \property Score.timing = ##f
622 \property Staff.TimeSignature = \turnOff
631 Here's an example of the difference between relative mode and
632 ``normal'' (non-relative) mode:
643 \property Score.timing = ##f
644 \property Staff.TimeSignature = \turnOff
660 \property Score.timing = ##f
661 \property Staff.TimeSignature = \turnOff
670 The following table summarizes the syntax learned so far in this section.
672 @c Is it possible to avoid page breaks directly after the
675 @multitable @columnfractions .3 .3 .4
684 @lilypond[fragment, relative 1]
685 \property Staff.TimeSignature = \turnOff
686 \property Staff.Clef = \turnOff
694 @lilypond[fragment, relative 1]
695 \property Score.timing = ##f
696 \property Staff.TimeSignature = \turnOff
697 \property Staff.autoBeaming = ##f
698 \property Staff.Clef = \turnOff
703 @item @code{\key es \major }
707 \property Staff.TimeSignature \set #'transparent = ##t
713 @item @var{note}@code{'}
716 @lilypond[fragment, relative 1]
717 \property Score.timing = ##f
718 \property Staff.TimeSignature = \turnOff
719 \property Staff.autoBeaming = ##f
720 \property Staff.Clef = \turnOff
724 @item @var{note}@code{,}
727 @lilypond[fragment, relative 1]
728 \property Score.timing = ##f
729 \property Staff.TimeSignature = \turnOff
730 \property Staff.autoBeaming = ##f
731 \property Staff.Clef = \turnOff
737 A slur is drawn across many notes, and indicates bound articulation
738 (legato). The starting note and ending note are marked with a
739 ``@code{(}'' and a ``@code{)}'' respectively:
742 @lilypond[fragment,relative 1, verbatim]
743 d4( )c16( cis d e c cis d )e( )d4
748 If you need two slurs at the same time (one for articulation, one for
749 phrasing), you can also make a phrasing slur with @code{\(} and
754 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
755 @c chromatic thing pasted in front. (admittedly the original doesn't
756 @c have a phrasing slur. The problem is that we don't want the slur
757 @c and the Phrasing slur to collide. We're trying to make a good
761 @lilypond[fragment,relative 1, verbatim]
762 a8(\( ais b ) c cis2 b'2 a4 cis, \) c
767 Beams are drawn automatically, but if you don't like the choices, you
768 can enter beams by hand. Surround the notes to be grouped with @code{[}
771 @lilypond[fragment,relative 1, verbatim]
777 To print more than one staff, each piece of music that makes up a staff
778 is marked by adding @code{\context Staff} before it. These
779 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
783 @lilypond[fragment,verbatim]
785 \context Staff = staffA { \clef violin c'' }
786 \context Staff = staffB { \clef bass c }
791 In this example, @code{staffA} and @code{staffB} are names that are
792 given to the staves. It doesn't matter what names you give, as long
793 as each staff has a different name.
797 We can now typeset a melody with two staves:
800 @lilypond[verbatim,singleline]
803 < \context Staff = staffA {
806 \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
808 \context Staff = staffB {
819 Notice that the time signature is specified in one melody staff only
820 (the top staff), but is printed on both. LilyPond knows that the time
821 signature should be the same for all staves.
825 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
827 @lilypond[verbatim,relative 1]
833 Dynamic signs are made by adding the markings to the note:
835 @lilypond[verbatim,relative 1]
841 Crescendi and decrescendi are started with the commands @code{\<} and
842 @code{\>}. The command @code{\!} finishes a crescendo on the following
845 @lilypond[verbatim,relative 1]
846 c2\< \!c2-\ff \>c2 \!c2
851 Chords can be made by surrounding notes with @code{<} and @code{>}:
853 @lilypond[relative 0, fragment,verbatim]
861 @c hmm, te losjes, iig
862 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
863 happens at the same time, like in chords, or (like in the two-staff
864 example above) in a bunch of stacked staves.
867 You can combine beams and ties with chords. Beam and tie markings
868 must be placed outside the chord markers:
870 @lilypond[relative 0, fragment,verbatim]
871 r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
875 When you want to combine chords with slurs and dynamics, technical
876 detail crops up: you have type these commands next to the notes, which
877 means that they have to be inside the @code{< >}. Don't get confused
878 by the chord @code{< >} and the dynamic @code{\< \>}!
883 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
885 @lilypond[relative 0, fragment]
887 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
892 @c this example is a bit too strongly worded -- there's nothing wrong
893 @c with starting a piece with a chord; you just have to be careful when
894 @c you do so. I've rephrased this example below.
895 @c There is one golden rule that you should keep in mind when writing
898 @c @strong{DO NOT START A PIECE WITH A CHORD}
900 @c Of course, it is a allowed, but the result might not be what you expect:
902 @c rephrased "don't start with a chord"
903 There is one caution when using chords: if you use a chord at the very
904 beginning of the piece, LilyPond might not understand what you want:
907 @lilypond[verbatim,singleline]
908 \score { \notes <c'2 e'2> }
913 If you have a piece that begins with a chord, you must explicitly
914 state that the notes of the chord are to be put on the same staff, in
915 the same voice. This is done by specifying @code{\context Staff} or
916 @code{\context Voice} for the notes:
919 @lilypond[verbatim,singleline]
920 \score { \notes \context Voice <c'2 e'2> }
928 @multitable @columnfractions .3 .3 .4
938 @lilypond[fragment, relative 1]
939 \property Score.timing = ##f
940 \property Staff.TimeSignature = \turnOff
941 \property Staff.autoBeaming = ##f
942 \property Staff.Clef = \turnOff
950 @lilypond[fragment, relative 1]
951 \property Score.timing = ##f
952 \property Staff.TimeSignature = \turnOff
953 \property Staff.autoBeaming = ##f
954 \property Staff.Clef = \turnOff
962 @lilypond[fragment, relative 1]
963 \property Score.timing = ##f
964 \property Staff.TimeSignature = \turnOff
965 \property Staff.autoBeaming = ##f
966 \property Staff.Clef = \turnOff
971 @item @code{< \context Staff ... >}
975 < \context Staff = SA { c'1 }
976 \context Staff = SB { c'1 } >
983 @lilypond[fragment, relative 1]
984 \property Staff.TimeSignature = \turnOff
985 \property Staff.Clef = \turnOff
990 @item @code{-\mf -\sfz}
993 @lilypond[fragment, relative 1]
994 \property Staff.TimeSignature = \turnOff
995 \property Staff.Clef = \turnOff
1003 @lilypond[fragment, relative 1]
1004 \property Score.timing = ##f
1005 \property Staff.TimeSignature = \turnOff
1006 \property Staff.autoBeaming = ##f
1007 \property Staff.Clef = \turnOff
1014 @lilypond[fragment, relative 1]
1015 \property Score.timing = ##f
1016 \property Staff.TimeSignature = \turnOff
1017 \property Staff.autoBeaming = ##f
1018 \property Staff.Clef = \turnOff
1026 @lilypond[fragment, relative 1]
1027 \context Voice <c e>
1032 Now you know the basic ingredients of a music file, so this is the right
1033 moment to try your at hand at doing it yourself: try typing some
1034 simple examples, and experiment a little.
1036 When you're comfortable with the basics, you might want to read
1037 the rest of this chapter. It continues in tutorial-style, but it
1038 is much more in-depth, dealing with more advanced topics such as
1039 lyrics, chords, orchestral scores and parts, fine tuning of output,
1040 polyphonic music, and integrating text and music.
1046 @node Printing lyrics
1047 @section Printing lyrics
1050 In this section we shall explain how to typeset the following
1051 fragment of The Free Software Song:
1053 @lilypond[singleline]
1054 \score { \notes { \addlyrics
1055 \notes \relative c' {
1057 d'2 c4 b16 ( a g a b a b ) c a2
1058 b2 c4 b8 ( a16 g ) a4 g2 }
1059 \context Lyrics \lyrics {
1061 share the soft -- ware; }
1063 \paper { linewidth = -1. }
1069 @cindex @code{\lyrics}
1072 To print lyrics, you must enter them and then instruct lilypond to
1074 You can enter lyrics in a special input mode of LilyPond. This mode is
1075 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1076 The purpose of this mode is that you can enter lyrics as plain text,
1077 punctuation, and accents without any hassle.
1079 Syllables are entered like notes, but with pitches replaced by text. For
1080 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1081 the hyphen has no special meaning for lyrics, and does not introduce
1084 Spaces can be introduced into a lyric either by using quotes:
1085 @code{"He could" not} or by using an underscore without quotes:
1086 @code{He_could not}. All unquoted underscores are converted to
1089 These are the lyrics for the free software song:
1094 share the soft -- ware; @}
1097 As you can see, extender lines are entered as @code{__}. This will
1098 create an extender, which is a line that extends over the entire
1099 duration of the lyric. This line will run all the way to the start
1100 of the next lyric, so you may want to shorten it by using a blank
1101 lyric (using @code{_}).
1104 You can use ordinary hyphens at the end of a syllable, i.e.
1108 but then the hyphen will be attached to the end of the first syllable.
1110 If you want them centered between syllables you can use the special
1111 `@code{-}@code{-}' lyric as a separate word between syllables. The
1112 hyphen will have variable length depending on the space between
1113 the syllables and it will be centered between the syllables.
1115 Normally the notes that you enter are transformed into note heads.
1116 Note heads alone make no sense, so they need surrounding information: a
1117 key signature, a clef, staff lines, etc. They need @emph{context}. In
1118 LilyPond, these symbols are created by objects called `interpretation
1119 contexts'. Interpretation contexts exist for generating notation
1120 (`notation context') and for generating sound (`performance
1121 context'). These objects only exist while LilyPond is executing.
1123 When LilyPond interprets music, it will create a Staff context.
1124 We don't want that default here, because we want lyric. The
1129 explicitly creates an interpretation context of
1130 @code{Lyrics} type to interpret the song text that we entered.
1132 The melody of the song doesn't offer anything new:
1134 \notes \relative c' @{
1136 d'2 c4 b16 ( a g a b a b ) c a2
1137 b2 c4 b8 ( a16 g ) a4 g2 @}
1140 Both can be combined with the @code{\addlyrics}:
1143 \notes \relative c' @dots{}
1144 \context Lyrics \lyrics @dots{}
1147 The lyrics are also music expressions, similar to notes. Each syllable
1148 of the lyrics is put under a note of the melody.
1149 The complete file is listed here:
1152 \score @{ \notes @{ \addlyrics
1153 \notes \relative c' @{
1155 d'2 c4 b16 ( a g a b a b ) c a2
1156 b2 c4 b8 ( a16 g ) a4 g2 @}
1157 \context Lyrics \lyrics @{
1159 share the soft -- ware; @}
1161 \paper @{ linewidth = -1. @}
1167 @node A melody with chords
1168 @section A melody with chords
1170 In this section we show how to typeset a melody with chord
1171 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1174 \include "paper16.ly"
1175 melody = \notes \relative c' @{
1179 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1180 c4 c8 d [es () d] c4 | d4 es8 d c4.
1184 accompaniment =\chords @{
1186 c2:3- f:3-.7 d:min es4 c8:min r8
1187 c2:min f:min7 g:7^3.5 c:min @}
1192 \context ChordNames \accompaniment
1193 \context Staff = mel @{
1198 \midi @{ \tempo 4=72 @}
1199 \paper @{ linewidth = 10.0\cm @}
1204 The result would look this.
1207 \include "paper16.ly"
1208 melody = \notes \relative c' {
1212 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1213 c4 c8 d [es () d] c4 | d4 es8 d c4.
1217 accompaniment =\chords {
1219 c2:3- f:3-.7 d:min es4 c8:min r8
1220 c2:min f:min7 g:7^3.5 c:min }
1225 \context ChordNames \accompaniment
1227 \context Staff = mel {
1228 \property Staff.autoBeaming = ##f
1232 \midi { \tempo 4=72 }
1233 \paper { linewidth = 10.0\cm }
1237 We will dissect this file line by line.
1242 \include "paper16.ly"
1245 Smaller size (suitable for inclusion in a book).
1249 melody = \notes \relative c' @{
1252 The structure of the file will be the same as the previous one: a
1253 @code{\score} block with music in it. To keep things readable, we will
1254 give different names to the different parts of music, and use the names
1255 to construct the music within the score block.
1262 @cindex @code{\partial}
1264 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1270 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1271 c4 c8 d [es () d] c4 | d4 es8 d c4.
1276 @cindex manual beaming
1277 @cindex automatic beaming, turning off
1278 We use explicit beaming. Since this is a song, we turn automatic
1279 beams off and use explicit beaming where needed.
1286 This ends the definition of @code{melody}.
1295 @cindex identifier assignment
1296 @cindex syllables, entering
1297 This defines the lyrics, similar to what we have seen before.
1302 accompaniment =\chords @{
1306 @cindex mode, chords
1307 We'll put chords over the music. To enter them, we use a special mode
1308 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1309 the names of the chords you want instead of listing the notes
1310 comprising the chord.
1317 There is no accompaniment during the anacrusis.
1326 @cindex chord modifier
1327 @cindex modifier, chord
1328 This is a c minor chord, lasting for a half note. Chords are entered using
1329 the tonic. Notes can be changed to create different chords. In this case,
1330 a lowered third is used (making a C major chord into a C minor chord).
1331 The code for this is @code{3-}.
1337 Similarly, @code{7} modifies (adds) a seventh, which is small by
1338 default to create the @code{f a c es} chord. Multiple modifiers must be
1346 Some modifiers have predefined names, e.g. @code{min} is the same as
1347 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1351 c2:min f:min7 g:7^3.5 c:min @}
1354 @cindex named modifier
1356 A named modifier @code{min} and a normal modifier @code{7} do not have
1357 to be separated by a dot. Tones from a chord are removed with chord
1358 subtractions. Subtractions are started with a caret, and they are
1359 also separated by dots. In this example, @code{g:7^3.5} produces a
1360 minor seventh (a G7 chord without the third or the fifth). The
1361 brace ends the sequential music.
1369 We assemble the music in the @code{\score} block. Melody, lyrics and
1370 accompaniment have to sound at the same time, so they should be
1371 @code{\simultaneous}.
1372 @cindex @code{\simultaneous}
1379 Chord mode generates notes grouped in @code{\simultaneous} music. If
1380 you remove the comment sign, you can see the chords in normal
1381 notation: they will be printed as note heads on a separate
1382 staff. To print them as chords names, they have to be interpreted as
1383 being chords, not notes. This is done with the following command:
1387 \context ChordNames \accompaniment
1391 @cindex interpretation context
1392 @cindex notation context
1395 Normally the notes that you enter are transformed into note heads.
1396 Note heads alone make no sense, so they need surrounding information: a key
1397 signature, a clef, staff lines, etc. They need @emph{context}. In
1398 LilyPond, these symbols are created by objects called `interpretation
1399 contexts'. Interpretation contexts exist for generating notation
1400 (`notation context') and for generating sound (`performance
1401 context'). These objects only exist while LilyPond is executing.
1403 When LilyPond interprets music, it will create a Staff context. If
1404 the @code{%} sign in the previous line were removed, you could see
1405 that mechanism in action.
1407 We don't want that default here, because we want chord names. The
1408 command above explicitly creates an interpretation context of
1409 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1414 \context Staff = mel @{
1418 We place the melody on a staff called @code{mel}. We give it a name to
1419 differentiate it from the one that would contain note heads for the
1420 chords, if you would remove the comment before the ``note heads''
1421 version of the accompaniment. By giving this staff a name, it is
1422 forced to be different.
1426 \property Staff.autoBeaming = ##f
1430 @cindex context variables
1431 @cindex setting context variables
1432 An interpretation context has variables, called properties, that tune
1433 its behavior. One of the variables is @code{autoBeaming}. Setting
1434 this @code{Staff}'s property to @code{##f}, which is the boolean value
1435 @var{false}, turns the automatic beaming mechanism off for the current
1446 Finally, we put the melody on the current staff. Note that the
1447 @code{\property} directives and @code{\melody} are grouped in sequential
1448 music, so the property settings are done before the melody is
1454 \midi @{ \tempo 4=72@}
1457 MIDI (Musical Instrument Digital Interface) is a standard for
1458 connecting and recording digital instruments. So a MIDI file is like a
1459 tape recording of an instrument. The @code{\midi} block makes the
1460 music go to a MIDI file, so you can listen to the music you entered. It
1461 is great for checking the music. Whenever you hear something weird, you
1462 probably hear a typing error.
1464 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1465 also specifies an output method. You can specify the tempo using the
1466 @code{\tempo} command, in this case the tempo of quarter notes is set to
1467 72 beats per minute.
1471 \paper @{ linewidth = 10.0\cm @}
1474 We also want notation output. The linewidth is short so that the piece
1475 will be set in two lines.
1478 @section More stanzas
1483 If you have multiple stanzas printed underneath each other, the vertical
1484 groups of syllables should be aligned around punctuation. LilyPond can
1485 do this if you tell it which lyric lines belong to which melody.
1486 We show how you can do this by showing how you could print a frivolous
1487 fragment of a fictional Sesame Street duet.
1489 @lilypond[singleline,verbatim]
1492 \notes \relative c'' \context Voice = duet { \time 3/4
1494 \lyrics \context Lyrics <
1495 \context LyricsVoice = "duet-1" {
1496 \property LyricsVoice . stanza = "Bert"
1497 Hi, my name is bert. }
1498 \context LyricsVoice = "duet-2" {
1499 \property LyricsVoice . stanza = "Ernie"
1500 Ooooo, ch\'e -- ri, je t'aime. }
1505 To this end, give the Voice context an identity, and set the
1506 LyricsVoice to a name starting with that identity followed by a dash.
1507 In the following example, the Voice identity is @code{duet},
1509 \context Voice = duet @{
1514 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1516 \context LyricsVoice = "duet-1" @{
1517 Hi, my name is bert. @}
1518 \context LyricsVoice = "duet-2" @{
1519 Ooooo, ch\'e -- ri, je t'aime. @}
1522 We add the names of the singers. This can be done by setting
1523 @code{LyricsVoice.Stanza} (for the first system) and
1524 @code{LyricsVoice.stz} for the following systems. Note that you must
1525 surround dots with spaces in @code{\lyrics} mode.
1528 \property LyricsVoice . stanza = "Bert"
1530 \property LyricsVoice . stanza = "Ernie"
1533 The convention for naming @code{LyricsVoice} and @code{Voice} must
1534 also be used to get melismata on rests correct.
1537 @c I think we need to change the name of this section, but that
1538 @c would probably involve a lot of changes in other places too.
1539 @node More movements
1540 @section More movements
1542 The program @code{lilypond} only produces sheet music and does not
1543 create titles, subtitles, or print the composer's name. To do that,
1544 you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi}
1545 creates the title, then calls @code{lilypond} to format the sheet music.
1546 In this section, we show you how to create titles like this:
1548 @c Old version of the above paragraph.
1549 @c LilyPond only produces sheet music; it doesn't concern itself with
1550 @c producing titles. Titles are produced using a simply wrapper program
1551 @c This is the jobs of a simple wrapper
1552 @c program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
1553 @c sheet music formatting. Then it produces titles, and ties together all
1554 @c inputs into a single @file{dvi} file. In this section, we show some of
1555 @c the options for titling. We will show how you can produce a file
1556 @c that looks like this:
1558 @center @strong{Two miniatures}
1568 \paper { linewidth = -1.0 }
1580 \paper { linewidth = -1.0 }
1584 For example, consider the following file (@file{miniatures.ly})
1589 title = "Two miniatures"
1590 composer = "F. Bar Baz"
1591 tagline = "small is beautiful" @}
1593 \paper @{ linewidth = -1.0 @}
1597 Mental note: discuss Schenkerian analysis of these key pieces.
1602 \notes @{ c'4 d'4 @}
1608 \notes @{ d'4 c'4 @}
1616 The information for the global titling is in a so-called header block.
1617 The information in this block is not used by LilyPond, but it is
1618 passed into @code{ly2dvi}, which uses this information to print titles
1621 @cindex identifier assignment
1622 the @code{\header} block contains assignments. In each assignment, a
1623 variable is set to a value. The header block for this file looks like
1625 @cindex @code{\header}
1628 title = "Two miniatures"
1629 composer = "F. Bar Baz"
1630 tagline = "small is beautiful"
1634 When you process a file with ly2dvi, a signature line is printed at
1635 the bottom of the last page. This signature is produced from the
1636 @code{tagline} field of @code{\header}. The default "Lily was here,
1637 @var{version number}" is convenient for programmers: archiving the
1638 layouts of different versions allows programmers to compare the
1639 versions using old print-outs.
1641 @cindex Lily was here
1642 @cindex signature line
1645 Many people find the default tagline (``Lily was here'') too droll.
1646 If that is the case, you can change @code{tagline} to somethign else,
1655 A paper block at top level (i.e. not in a @code{\score} block) sets the
1656 default page layout. The following @code{\score} blocks don't have
1657 @code{\paper} sections, so the settings of this block are used.
1659 The variable @code{linewidth} normally sets the length of the systems
1660 on the page. However, a negative value has a special meaning. If
1661 @code{linewidth} is less than 0, no line breaks are inserted into the
1662 score, and the spacing is set to natural length: a short phrase takes
1663 up little space, a longer phrase takes more space, all on the same line.
1668 Mental note: discuss Schenkerian analysis of these key pieces.
1673 Mental notes to yourself can be put into comments. There are two types
1674 of comments. Line comments are introduced by @code{%}, and block
1675 comments are delimited by @code{%@{} and @code{%@}}.
1680 \notes @{ c'4 d'4 @}
1683 In previous examples, most notes were specified in relative octaves
1684 (i.e. each note was put in the octave that is closest to its
1685 predecessor). Besides relative, there is also absolute octave
1686 specification, which you get when you don't include @code{\relative} in
1687 your input file. In this input mode, the middle C is denoted by
1688 @code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
1689 Going up, you get @code{c''} @code{c'''} etc.
1691 When you're copying music from existing sheet music, relative octaves
1692 are probably the easiest to use: you have to do less typing, and errors are
1693 easily spotted. However, if you write LilyPond input directly, either by
1694 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1702 The @code{\header} is normally at the top of the file, where it sets
1703 values for the rest of the file. If you want to typeset different pieces
1704 from one file (for example, if there are multiple movements, or if
1705 you're making an exercise book), you can put different @code{\score}
1706 blocks into the input file. @code{ly2dvi} will assemble all LilyPond
1707 output files into a big document. The contents of @code{\header} blocks
1708 specified within each score is used for the title of that movement.
1714 For example, the Opus number is put at the right, and the "piece" string
1715 will be at the left.
1722 title = "Two miniatures"
1723 composer = "F. Bar Baz"
1724 tagline = "small is beautiful" @}
1726 \paper @{ linewidth = -1.0 @}
1729 \notes @{ c'4 d'4 @}
1735 \notes @{ d'4 c'4 @}
1747 Lilypond and its language are still under development, and
1748 occasionally details of the syntax are changed. The @code{version}
1749 fragment indicates which version of lilypond the input file was written
1750 for. When you compile this file, the version number will be checked
1751 and you will get a warning when the file is too old. This version
1752 number is also used by the @code{convert-ly} program (See
1753 @ref{Invoking convert-ly}), which can used to update the file to the
1754 latest lily version.
1757 @node A piano excerpt
1758 @section A piano excerpt
1760 Our eighth subject is a piece of piano music. The fragment in the
1761 input file is a piano reduction of the G major Sinfonia by Giovanni
1762 Battista Sammartini, composed around 1740. It's in the source
1763 package under the name @file{input/tutorial/sammartini.ly}.
1765 @lilypondfile[smallverbatim]{sammartini.ly}
1767 As you can see, this example features multiple voices on one staff. To
1768 make room for those voices, their notes should be stemmed in opposite
1771 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1772 with some other commonly used formatting instructions, but to explain how
1773 it works, we wrote our own here. Of course, you should use predefined
1774 identifiers like these if possible: you will be less affected by changes
1775 between different versions of LilyPond.
1779 viola = \notes \relative c' \context Voice = viola @{
1781 In this example you can see multiple parts on a staff. Each part is
1782 associated with one notation context. This notation context handles
1783 stems and dynamics (among other things). The type name of this context
1784 is @code{Voice}. For each part we have to make sure that there is
1785 precisely one @code{Voice} context, so we give it a unique name
1792 The delimiters @code{<} and @code{>} are shorthands for
1793 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1794 @code{<} and @code{>} is a chord.
1798 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1806 We want the viola to have stems down, and have all the other
1807 characteristics of a second voice. This is enforced using the
1808 @code{\voiceTwo} command: it inserts instructions that makes stem,
1809 ties, slurs, etc. go down.
1817 Relative octaves work a little differently with chords. The starting
1818 point for the note following a chord is the first note of the chord. So
1819 the @code{g} gets an octave up quote: it is a fifth above the starting
1820 note of the previous chord (the central C).
1826 @code{s} is a spacer rest. It does not print anything, but it does have
1827 the duration of a rest. It is useful for filling up voices that
1828 temporarily don't play. In this case, the viola doesn't come until one
1829 and a half measure later.
1833 oboes = \notes \relative c'' \context Voice = oboe @{
1835 Now comes a part for two oboes. They play homophonically, so we
1836 print the notes as one voice that makes chords. Again, we insure that
1837 these notes are indeed processed by precisely one context with
1841 \voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
1844 The oboes should have stems up to keep them from interfering with
1845 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1849 \grace <e8( g> < d4 )f> <c2 e>
1851 @cindex @code{\grace}
1854 @code{\grace} introduces grace notes. It takes one argument, in this
1855 case a chord. A slur is introduced starting from the @code{\grace}
1856 ending on the following chord.
1864 Tuplets are made with the @code{\times} keyword. It takes two
1865 arguments: a fraction and a piece of music. The duration of the piece
1866 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1867 of their notated duration, so in this case the fraction is 2/3.
1870 @{ <d8 f> <e g> <f a> @}
1872 The piece of music to be `tripletted' is sequential music containing
1879 At this point, the homophonic music splits into two rhythmically
1880 different parts. We can't use a sequence of chords to enter this, so
1881 we make a "chord of sequences" to do it. We start with the upper
1882 voice, which continues with upward stems:
1885 @{ \times 2/3 @{ a8 g c @} c2 @}
1892 The easiest way to enter multiple voices is demonstrated
1893 here. Separate the components of the voice (single notes or entire
1894 sequences) with @code{\\} in a simultaneous music expression. The
1895 @code{\\} separators split first voice, second voice, third voice, and
1898 As far as relative mode is concerned, the previous note is the
1899 @code{c'''2} of the upper voice, so we have to go an octave down for
1907 This ends the two-part section.
1911 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1916 @code{\stemBoth} ends the forced stem directions. From here, stems are
1917 positioned as if it were single part music.
1919 The bass has a little hoom-pah melody to demonstrate parts switching
1920 between staves. Since it is repetitive, we use repeats:
1923 hoomPah = \repeat unfold 8
1925 @cindex unfolded @code{\repeat}
1926 The unfolded repeat prints the notes in its argument as if they were
1927 written out in full eight times.
1930 \notes \transpose c' @{
1933 @cindex relative mode and transposing
1935 Transposing can be done with @code{\transpose}, which takes two arguments.
1936 The first specifies what central C should be transposed to. The second
1937 is the to-be-transposed music. As you can see, in this case, the
1938 transposition has no effect, as central C stays at central C.
1940 The purpose of this no-op is to protect it from being interpreted as
1941 relative notes. Relative mode can not be used together with
1942 transposition, so @code{\relative} will leave the contents of
1943 @code{\hoomPah} alone. We can use it without having to worry about
1944 getting the motive in a wrong octave.
1946 @cindex staff switch, manual
1947 @cindex cross staff voice, manual
1948 @cindex @code{\translator}
1951 \translator Staff = down
1954 \translator Staff = up
1958 Voices can switch between staves. Here you see two staff switching
1959 commands. The first one moves to the lower staff, the second one to
1960 the lower one. If you set the stem directions explicitly
1961 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1962 can be beamed together (despite jumping between staffs).
1966 bassvoices = \notes \relative c' @{
1968 \autochange Staff \hoomPah \context Voice
1973 \translator Staff = down
1975 @cindex staff switch
1976 @cindex cross staff voice
1977 We want the remaining part of this melody on the lower staff, so we do a
1978 manual staff switch here.
1983 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1987 After skipping some lines, we see @code{~}. This mark makes ties. Note
1988 that ties and slurs are different things. A tie can only connect two
1989 note heads of the same pitch, whereas a slur can connect many notes
1996 A special context is needed to get cross staff beaming right. This
1997 context is called @code{PianoStaff}.
2000 \context Staff = bottom < \time 2/2 \clef bass
2002 The bottom staff must have a different clef.
2007 To make some more room on the line, the first (in this case the only)
2008 line is not indented. The line still looks very cramped, but that is due
2009 to the page layout of this document.
2015 * font-size, multi-stanza.
2017 * Simple part combining in a Hymn
2021 @node Fine tuning a piece
2022 @section Fine tuning a piece
2024 In this section we show some ways to fine tune the final output of a
2025 piece. We do so using a single measure of a moderately complex piano
2026 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
2027 tuned and the untuned versions) are in @file{input/tutorial/}.
2029 The code for the untuned example shows us some new things.
2031 @lilypondfile[verbatim]{brahms-original.ly}
2041 Hairpin dynamics can be easily added to Lilypond scores. Beginning a
2042 crescendo is indicated with @code{\<} and ending a crescendo is indicated
2043 with @code{\!}. A decrescendo can be indicated with @code{\>} and
2044 @code{\!}. Absolute dynamics (sometimes called ``Letter dynamics'') can
2045 be entered using @code{\p}, @code{\mf}, etc. All these dynamics will
2046 apply to the whole chord where they are entered, but for syntactical
2047 reasons they must be attached to one of the notes of the chord.
2049 @cindex fingering instructions
2051 Fingering indications are entered with @code{-@var{N}}, where
2054 Now that we have the basic piece of music entered, we want to fine
2055 tune it so that we get something that resembles the original printed
2056 edition by Schott/Universal Edition:
2058 @lilypondfile{brahms-tweaked.ly}
2060 @cindex tuning graphical objects
2062 Fine tuning involves overriding the defaults of the printing system.
2063 We do this by setting variables which control how Lilypond prints
2064 symbols. Printed symbols are called graphical objects (often
2065 abbreviated to @emph{grob}). Each object is described by a bunch of
2066 settings. Every setting is a variable: it has a name and a value
2067 which you can change. These values determine the fonts, offsets,
2068 sub-routines to be called on the object, etc. The initial values of
2069 these settings are set in the Scheme file
2070 @file{scm/grob-description.scm}.
2072 @cindex slur attachments
2074 We start with the slur in the upper part, running from F sharp to A. In
2075 the printed edition, this slur runs from stem to stem; in our version,
2076 the slur begins at the note head of the F sharp. The following property
2077 setting forces all slurs to run from stem to stem (not from or to note
2081 \property Voice.Slur \set #'attachment = #'(stem . stem)
2084 More precisely, this command modifies the definition of the @code{Slur}
2085 object in the current @code{Voice}. The variable @code{attachment} is
2086 set to the pair of symbols @code{'(stem . stem)}.
2088 Although this fixes the slur, it isn't very helpful for fine tuning in
2089 general: the lilypond back-end supports approximately 240 variables
2090 like @code{attachment}, each with their own meaning and own type
2091 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2092 different types of graphical objects, that may be created in 14
2093 different context types besides Voice.
2095 @cindex internal documentation
2096 @cindex finding graphical objects
2097 @cindex graphical object descriptions
2099 The interesting information is how you can figure out which properties
2100 to tune for your own scores. To discover this, you must have a copy of
2101 the internals document. This is a set of HTML pages which should be
2102 included if you installed a binary distribution@footnote{You can also
2103 compile them by executing @code{make -C Documentation/user/
2104 out/lilypond-internals.html} in the source package.}. These HTML pages
2105 are also available on the web: go to the lilypond website, click
2106 ``Documentation: Index'' on the side bar, look in the ``Information for
2107 uses'' section, and click on ``Documentation of internals''.
2109 You might want to bookmark either the HTML files on your disk, or the one
2110 on the web (the HTML on your hard drive will load much faster than the
2111 ones on the web!). One word of caution: the internals documentation is
2112 generated from the definitions that lily uses. For that reason, it is
2113 strongly tied to the version of LilyPond that you use. Before you
2114 proceed, please make sure that you are using the documentation that
2115 corresponds to the version of LilyPond that you are using.
2117 @c TODO: the quote is incorrect, although that shouldn't be a big
2118 @c problem for the reader.
2119 Suppose that you wanted to tune the behavior of the slur. The first
2120 step is to get some general information on slurs in lilypond. Turn to
2121 the index, and look up ``slur''. The section on slurs says
2123 The grob for this object is @internalsref{Slur}, generally in
2124 @internalsref{Voice} context.
2127 So the graphical object for this object is called @code{Slur}, and
2128 slurs are created in the @code{Voice} context. If you are reading
2129 this tutorial in the HTML version, then you can simply click Slur,
2130 otherwise, you should look it up the internal documentation: click
2131 ``grob overview'' and select ``slur'' (the list is alphabetical).
2133 Now you get a list of all the properties that the slur object
2134 supports, along with their default values. Among the properties we
2135 find the @code{attachment} property with its default setting.
2136 The property documentation explains that the following setting will
2137 produce the desired effect:
2139 \property Voice.Slur \set #'attachment = #'(stem . stem)
2142 If you ran the previous example, you have unknowingly already used
2143 this kind of command. The @file{ly/property-init.ly} contains the
2144 definition of @code{\stemUp}:
2146 stemUp = \property Voice.Stem \set #'direction = #1
2149 @c this is a long section, and adding an extra space here helps to
2150 @c break it into smaller subsections and thus is easier to understand.
2153 Next we want to move the fingering `3'. In the printed edition it is
2154 not above the stem, but a little lower and slightly left of the stem.
2155 From the user manual we find that the associated graphical object is
2156 called @code{Fingering}, but how do we know if we should use
2157 @code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
2158 bet, but you can also deduce this information from the internals
2159 documentation: if you visit the documentation of @code{Fingering}, you
2162 Fingering grobs are created by: Fingering_engraver
2165 Clicking @code{Fingering_engraver} will show you the documentation of
2166 the module responsible for interpreting the fingering instructions and
2167 translating them to a @code{Fingering} object. Such a module is called
2168 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2171 Fingering_engraver is part of contexts: Voice and TabVoice
2173 so tuning the settings for Fingering should be done using either
2175 \property Voice.Fingering \set @dots{}
2179 \property TabVoice.Fingering \set @dots{}
2182 Since the @code{TabVoice} is only used for tab notation, we see that
2183 the first guess @code{Voice} was indeed correct.
2185 @cindex setting object properties
2186 @cindex @code{extra-offset}
2188 For shifting the fingering, we use the property @code{extra-offset}.
2189 The following command manually adds an offset to the object. We move
2190 it a little to the left, and 1.8 staff space downwards.
2192 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2194 The @code{extra-offset} is a low-level feature: it moves around
2195 objects in the printout; the formatting engine is completely oblivious
2196 to these offsets. The unit of these offsets are staff-spaces. The
2197 first number controls left-right movement; a positive number will move
2198 the object to the right. The second number controls up-down movement;
2199 a positive number will move it higher.
2201 @cindex reverting object properties
2202 @cindex undoing object properties
2204 We only want to offset a single object, so after the F-sharp we must
2205 undo the setting. The technical term is to revert the property.
2207 \property Voice.Fingering \revert #'extra-offset
2210 @cindex property types
2211 @cindex translator properties
2212 @cindex grob properties
2213 @cindex music properties
2216 There are three different types of variables in LilyPond, something
2217 which can be confusing at first (and for some people it stays confusing
2218 :). Variables such as @code{extra-offset} and @code{attachment} are
2219 called grob properties. They are not the same as translator properties,
2220 like @code{autoBeaming}. Finally, music expressions are internally
2221 stored using properties (so-called music properties). You will encounter
2222 music properties if you run Scheme functions on music using @code{\apply}.
2224 The second fingering instruction should be moved up a little to avoid
2225 a collision with the slur. This could be achieved with
2226 @code{extra-offset}, but in this case, a simpler mechanism also
2227 works. We insert an empty text between the 5 and the note. The empty
2228 text pushes the fingering instruction away:
2230 a^" "^#'(finger "5")
2233 Lilypond tries to put fingering instructions as close to the notes as
2234 possible. To make sure that Lilypond doesn't do that, we disguise the
2235 fingering as text: @code{(finger "5")}.
2239 Normally one would specify all dynamics in the same voice, so that
2240 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2241 in this case, we don't want the decrescendo to be aligned with the
2242 piano sign. We achieve this by putting the dynamic markings in different
2243 voices. The crescendo should be above the upper staff. This can be
2244 forced by using the precooked command
2249 However, if you do that the decrescendo will be too close to the
2250 upper voice and collide with the stems. Looking at the manual for
2251 dynamics, we notice that ``Vertical positioning of these symbols is
2252 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2253 to the documentation of @code{DynamicLineSpanner}, we find that
2254 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2255 object not only puts dynamic objects next to the staff
2256 (@code{side-position-interface}), but it also groups dynamic objects
2257 (@code{axis-group-interface}), is considered a dynamic sign
2258 itself (@code{dynamic-interface}), and is an object. It has the standard
2259 @code{grob-interface} with all the variables that come with it.
2261 For the moment we are interested in side positioning:
2263 side-position-interface
2265 Position a victim object (this one) next to other objects (the
2266 support). In this case, the direction signifies where to put the
2267 victim object relative to the support (left or right, up or down?)
2269 Between the object and its support (in this case the notes in the voice
2270 going down), there should be more space. This space is controlled by
2271 @code{padding}, so we increase it.
2273 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2276 This command is almost like the command for setting slur attachments,
2277 but subtly different in its details. Grob properties can be
2278 manipulated with two commands: @code{\override} extends the
2279 variables with a setting, and @code{\revert} releases this
2280 setting. This has a certain theoretical appeal: the operations are
2281 simple and symmetric. But for practical use, it can be cumbersome. The
2282 commands act like parentheses: you should carefully balance the use of
2283 @code{\override} and @code{\revert}. The @code{\set} command is more
2284 friendly: it first does a @code{\revert} followed by @code{\override}.
2288 Brahms uses music notation is a slightly unorthodox way. Ties
2289 usually happen only within one voice. In this piece, the composer
2290 gladly produces ties that jump voices. We deal with this by faking
2291 these ties: whenever we need such a tie, we insert a notehead in a
2292 different voice, and blank the stem. This is done in the following
2296 \property Voice.Stem \set #'transparent = ##t
2299 Blanking the stem should be done for only one object. One of the ways
2300 to achieve that, is by setting the property before a note. Reverting
2301 it afterwards is tedious, so for setting a property only once, we have
2302 the syntax @code{\once}: it reverts the property directly before
2303 proceeding to the next step in time.
2305 The @code{\once} keyword is added to @code{\property}.
2308 Finally, the last tie is forced up using @code{\tieUp}.
2312 Here's the complete ``fine tuned'' version, which includes all the
2313 modifications we discussed in this section:
2315 @lilypondfile[verbatim]{brahms-tweaked.ly}
2318 @node An orchestral score
2319 @section An orchestral score
2323 * Extracting an individual part::
2327 Our next two examples demonstrate one way to create an orchestral score
2328 in LilyPond. When typesetting a piece for several instruments, you'll
2329 want to create a full score (for the conductor) along with several
2330 individual parts (for the players).
2332 LilyPond is well suited for this task. We will declare the music for
2333 each instrument individually, giving the music of each instrument its
2334 own name. These pieces of music are then combined in different
2335 @code{\score} blocks to produce different combinations of instruments
2336 (for example, one @code{\score} block may only include the cello part;
2337 another @code{\score} block may be for all the strings, and yet another
2338 @code{\score} block may be for all parts together).
2340 This orchestral score example consists of three input files. In the
2341 first file, @file{os-music.ly}, we define the music for all
2342 instruments. This file will be used for producing the score and
2343 the separate parts, but the file doesn't produce any sheet music
2344 itself. Other files reference this file by doing @code{\include
2350 title = "Zo, goed lieverd?"
2351 subtitle = "How's, this babe?"
2360 Key = \notes \key as \major
2361 flautoI = \notes\relative c'' @{
2363 bes as bes as bes as bes as
2365 flautoII = \notes\relative c'' @{
2366 as8 bes as bes R1 d4 ~ d
2368 tromboI = \notes\relative c'' @{
2369 c4. c8 c8 c4. es4 r as, r
2371 tromboII = \notes\relative c'' @{
2372 as4. as8 as8 as4. R1*1/2 as4 es'
2374 timpani = \notes\relative c, @{
2375 \times 2/3 @{ f4 f f @}
2376 \times 4/5 @{ as8 as as as as @}
2379 corno = \notes\relative c' @{
2380 bes4 d f, bes d f, bes d
2384 We will not examine this example line by line, since you already know
2385 most of it. We'll examine a few lines which contain new elements.
2396 Declare setting to be used globally. The @code{\skip} command produces
2397 no output, but moves forward in time: in this case, the duration of a
2398 half note (@code{2}), and that four times (@code{*4}). This brings us
2399 to the end of the piece, and we can set the end bar. You can use @code{s}
2400 as a shortcut for @code{\skip} (the last line of this section would
2401 be @code{s2*4 \bar"|."}).
2405 Key = \notes \key as \major
2407 Declare the key signature of the piece and assign it to the identifier
2408 @var{Key}. Later on we'll use @code{\Key} for all staves except those
2409 for transposing instruments.
2411 @node The full score
2412 @subsection The full score
2415 The second file, @file{input/tutorial/os-score.ly}, reads the definitions of the first
2416 (@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
2422 \include "os-music.ly"
2423 \include "paper13.ly"
2425 #(set-point-and-click! 'line-column)
2426 #(define text-flat '((font-relative-size . -2)
2427 (music "accidentals--1")))
2432 \property Score.BarNumber \override #'padding = #3
2433 \context StaffGroup = woodwind <
2434 \context Staff = flauti <
2435 \property Staff.midiInstrument = #"flute"
2436 \property Staff.instrument = "2 Flauti"
2437 \property Staff.instr = "Fl."
2439 \context Voice=one @{ \voiceOne \flautoI @}
2440 \context Voice=two @{ \voiceTwo \flautoII @}
2443 \context StaffGroup = timpani <
2444 \context Staff = timpani <
2445 \property Staff.midiInstrument = #"timpani"
2446 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2447 \property Staff.instr = #"Timp."
2453 \context StaffGroup = brass <
2454 \context Staff = trombe <
2455 \property Staff.midiInstrument = #"trumpet"
2456 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2457 \property Staff.instr = #`(lines "Tbe." "(C)")
2459 \context Voice=one \partcombine Voice
2460 \context Thread=one \tromboI
2461 \context Thread=two \tromboII
2463 \context Staff = corni <
2464 \property Staff.midiInstrument = #"french horn"
2465 \property Staff.instrument = #`(lines "Corno"
2466 (columns "(E" ,text-flat ")"))
2467 \property Staff.instr = #`(lines "Cor."
2468 (columns "(E" ,text-flat ")"))
2469 \property Staff.transposing = #3
2470 \notes \key bes \major
2471 \context Voice=one \corno
2476 indent = 15 * \staffspace
2477 linewidth = 60 * \staffspace
2478 textheight = 90 * \staffspace
2480 \HaraKiriStaffContext
2489 @center @strong{Zo, goed lieverd?}
2491 @center How's, this babe?
2499 @lilypondfile{os-score.ly}
2503 \include "os-music.ly"
2505 First we need to include the music definitions we made in
2510 #(set-point-and-click! 'line-column)
2513 This piece of Scheme code executes the function
2514 @code{set-point-and-click!} with the argument
2515 @code{line-column}. Editing input files can be complicated if you're
2516 working with large files: if you're digitizing existing music, you have
2517 to synchronize the .ly file, the sheet music on your lap and the sheet
2518 music on the screen. The point-and-click mechanism makes it easy to
2519 find the origin of an error in the LY file: when you view the file with
2520 Xdvi and click on a note, your editor will jump to the spot where that
2521 note was entered. For more information, see @ref{Point and click}.
2526 #(define text-flat '((font-relative-size . -2)
2527 (music "accidentals--1")))
2530 To name the transposition of the french horn, we will need a piece of
2531 text with a flat sign. LilyPond has a mechanism for font selection and
2532 kerning called Scheme markup text (See @ref{Text markup}). The flat
2533 sign is taken from the music font, and its name is @code{accidentals--1}
2534 (The natural sign is called @code{accidentals-0}). The default font is
2535 too big for text, so we select a relative size of @code{-2}.
2542 All staves are simultaneous and use the same global settings.
2546 \property Score.BarNumber \override #'padding = #3
2548 LilyPond prints bar numbers at the start of each line, but
2549 unfortunately they end up a bit too close to the staff in this
2550 example. In LilyPond, a bar number is called @var{BarNumber}.
2551 BarNumber objects can be manipulated through their
2552 @var{side-position-interface}. One of the properties of a
2553 @var{side-position-interface} that can be tweaked is @var{padding}:
2554 the amount of extra space that is put between this and other objects.
2555 We set the padding to three staff spaces.
2557 You can find information on all these kind of properties in LilyPond's
2558 automatically generated documentation in
2560 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2561 or in @ref{Fine tuning a piece}.
2564 the online documentation or in the previous section of the tutorial.
2571 \context StaffGroup = woodwind <
2572 \context Staff = flauti <
2574 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2575 hold one or more @code{Staff}'s, and will print a big bracket at the
2576 left of the score. This starts a new staff group for the woodwind
2577 section (just the flutes in this case). Immediately after that, we
2578 start the staff for the two flutes, who also play simultaneously.
2582 \property Staff.midiInstrument = #"flute"
2584 Specify the instrument for MIDI output (see @ref{MIDI instrument
2589 \property Staff.instrument = "2 Flauti"
2590 \property Staff.instr = "Fl."
2592 This defines the instrument names to be printed in the
2593 margin. @code{instrument} specifies the name for the first line
2594 of the score, @code{instr} is used for the rest of the score.
2600 The flutes play in the default key.
2604 \context Voice=one @{ \voiceOne \flautoI @}
2605 \context Voice=two @{ \voiceTwo \flautoII @}
2607 Last come the actual flute parts. Remember that we're still in
2608 simultaneous mode. We name both voices differently, so that LilyPond
2609 will create two Voice contexts. The flute parts are simple, so
2610 we specify manually which voice is which: @code{\voiceOne} forces the
2611 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2619 Close the flutes staff and woodwind staff group.
2623 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2625 The timpani staff demonstrates a new piece of scheme markup, it sets two
2630 \context Voice=one \partcombine Voice
2631 \context Thread=one \tromboI
2632 \context Thread=two \tromboII
2634 You have seen the notation contexts Staff and Voice, but here's a new
2635 one: Thread. One or more Threads can be part of a Voice. Thread
2636 takes care of note heads and rests; Voice combine note heads onto a
2639 For the trumpets we use the automatic part combiner (see @ref{Automatic
2640 part combining}) to combine the two simultaneous trumpet parts onto the
2641 trumpet staff. Each trumpet gets its own Thread context, which must be
2642 named @code{one} and @code{two}). The part combiner makes these two
2643 threads share a Voice when they're similar, and splits the threads up
2644 when they're different.
2648 \property Staff.instrument = #`(lines "Corno"
2649 (columns "(E" ,text-flat ")"))
2651 The french horn (``Corno'') has the most complex scheme markup name, made
2652 up of two lines of text. The second line has three elements (columns) --
2653 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2654 and a final @code{")"}. Note that we use a backquote instead of an
2655 ordinary quote at the beginning of the Scheme expression to be able to
2656 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2660 \property Staff.transposing = #3
2662 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2663 transpose this staff by three steps.
2665 Note how we can choose different tunings for the text input, sheet music
2666 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2667 property @var{transposing}.
2671 \notes \key bes \major
2673 Since the horn is transposing, it's in a different key.
2677 indent = 15 * \staffspace
2678 linewidth = 60 * \staffspace
2680 We specify a big indent for the first line and a small linewidth for this
2685 Usually LilyPond's default setup of notation contexts (Thread,
2686 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2687 want a different type of Staff context.
2691 \HaraKiriStaffContext
2695 In orchestral scores it often happens that one instrument only has
2696 rests during one line of the score. @code{HaraKiriStaffContext} can
2697 be used as a regular @code{StaffContext} drop-in and will take care of
2698 the automatic removing of empty staves -- so if the strings are the
2699 only instruments playing for a line, LilyPond will only print the string
2700 parts for that line of the score. This reduces the number of page turns
2701 (and the number of dead trees!) required in a score.
2703 @node Extracting an individual part
2704 @subsection Extracting an individual part
2706 The third file, @file{os-flute-2.ly} also reads the definitions of the
2707 first (@file{os-music.ly}), and defines the @code{\score} block for the
2711 \include "os-music.ly"
2712 \include "paper16.ly"
2716 \property Score.skipBars = ##t
2717 \property Staff.midiInstrument = #"flute"
2723 instrument = "Flauto II"
2726 linewidth = 80 * \staffspace
2727 textheight = 200 * \staffspace
2735 @center @strong{Zo, goed lieverd?}
2737 @center How's, this babe?
2738 @center @emph{Flauto II}
2745 @lilypondfile{os-flute-2.ly}
2748 Because we separated the music definitions from the @code{\score}
2749 instantiations, we can easily define a second score with the music of
2750 the second flute. This is the part for the second flute player. Of
2751 course, we would make separate parts for all individual instruments if
2752 we were preparing the score for an orchestra.
2758 In this individual part the second flute has a whole staff for itself,
2759 so we don't want to force stem or tie directions.
2764 instrument = "Flauto II"
2767 The @code{\header} definitions were also read from @file{os-music.ly},
2768 but we need to set the instrument for this particular score.
2772 \property Score.skipBars = ##t
2774 In the conductor's full score, all bars with rests are printed, but for
2775 the individual parts, we want to print one multimeasure rest instead of
2776 many consecutive empty bars. LilyPond will do this if
2777 @code{Score.skipBars} is set to true (@code{##t}).
2780 @node Integrating text and music
2781 @section Integrating text and music
2784 @cindex La@TeX{}, music in
2785 @cindex HTML, music in
2786 @cindex Texinfo, music in
2788 Sometimes you might want to use music examples in a text that you are
2789 writing (for example a musicological treatise, a songbook, or (like us)
2790 the LilyPond manual). You can make such texts by hand, simply by
2791 importing a PostScript figure into your word processor. However,
2792 there is an automated procedure to reduce the amount of work.
2794 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2795 code. A script called @code{lilypond-book} will extract the music
2796 fragments, run LilyPond on them, and put back the resulting
2797 notation. This program is fully described in the chapter
2798 @ref{Integrating text and music with lilypond-book}. Here we show a
2799 small example. Since the example also contains explanatory text, we
2800 won't comment on the contents.
2803 \documentclass[a4paper]@{article@}
2806 In a lilypond-book document, you can freely mix music and text. For
2809 \score @{ \notes \relative c' @{
2810 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2813 Notice that the music line length matches the margin settings of the
2816 If you have no \verb+\score+ block in the fragment,
2817 \texttt@{lilypond-book@} will supply one:
2823 In the example you see here, two things happened: a
2824 \verb+\score+ block was added, and the line width was set to natural
2825 length. You can specify many more options using \LaTeX style options
2828 \begin[verbatim,11pt,singleline,
2829 fragment,relative,intertext="hi there!"]@{lilypond@}
2833 \texttt@{verbatim@} prints the LilyPond code in addition to the
2835 \texttt@{11pt@} selects the default music size,
2836 \texttt@{fragment@} adds a score block,
2837 \texttt@{relative@} uses relative mode for the fragment, and
2838 \texttt@{intertext@} specifies what to print between the
2839 \texttt@{verbatim@} code and the music.
2841 If you want to include large examples into the text, it may be more
2842 convenient to put the example in a separate file:
2844 \lilypondfile[printfilename]@{sammartini.ly@}
2846 The \texttt@{printfilename@} option adds the file name to the output.
2851 Under Unix, you can view the results as follows.
2855 $ lilypond-book --outdir=out/ lilbook.tex
2856 lilypond-book (GNU LilyPond) 1.6.1
2857 Reading `input/tutorial/lilbook.tex'
2858 Reading `input/tutorial/sammartini.ly'
2859 @var{lots of stuff deleted}
2860 Writing `out/lilbook.latex'
2862 $ latex lilbook.latex
2863 @var{lots of stuff deleted}
2867 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2868 and running latex creates a lot of temporary files, and you wouldn't want
2869 those to clutter up your working directory. Hence, we have them created
2870 in a separate subdirectory.
2872 The result looks more or less like this:
2876 In a lilypond-book document, you can freely mix music and text. For
2879 \score { \notes \relative c' {
2880 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2883 Notice that the music line length matches the margin settings of the
2886 If you have no @code{\score} block in the fragment,
2887 @code{lilypond-book} will supply one:
2893 In the example you see here, a number of things happened: a
2894 @code{\score} block was added, and the line width was set to natural
2895 length. You can specify many more options using La@TeX{} style options
2898 @lilypond[verbatim,11pt,singleline,
2899 fragment,relative,intertext="hi there!"]
2903 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2904 the default music size, @code{fragment} adds a score block,
2905 @code{relative} uses relative mode for the fragment, and
2906 @code{intertext} specifies what to print between the
2907 @code{verbatim} code and the music.
2909 If you include large examples into the text, it may be more convenient
2910 to put the example in a separate file:
2912 @lilypondfile[printfilename]{sammartini.ly}
2914 The @code{printfilename} option adds the file name to the output.
2915 @node End of tutorial
2916 @section End of tutorial
2918 This is the end of the tutorial. If you read everything until this point
2919 (and understood everything!) then you're now an accomplished lilypond
2920 hacker. From here you should try fiddling with input files or making your
2921 own input files. Come back to the reference manual for more information
2924 Don't forget to check out the
2926 @uref{../../../../input/template/out-www/template.html,templates},
2927 @uref{../../../../input/test/out-www/test.html,examples} and
2928 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2931 templates, examples and feature tests.
2933 If you want to see real action LilyPond, head over to
2934 @uref{http://www.mutopiaproject.org}, which has many examples of
2935 classical music typeset with LilyPond.