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 \property Score.timing = ##f
59 \transpose c'' { c d e f g a b }
62 We will continue with this format: First we show a snippet of input,
63 then the resulting output.
65 The length of a note is specified by adding a number, @samp{1} for a
66 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
73 \property Score.timing = ##f
74 \property Staff.autoBeaming = ##f
75 \transpose c'' { a1 a2 a4 a16 a32 s16_" " }
78 If you don't specify a @rglos{duration}, the previous one is used:
85 \property Score.timing = ##f
86 \transpose c'' { a a a2 a s16_" " }
89 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
90 @rglos{flat} (@texiflat{}) by adding @samp{es}. As you would expect,
91 a @rglos{double sharp} or @rglos{double flat} is made by adding
92 @samp{isis} or @samp{eses}:
99 \property Score.timing = ##f
100 \transpose c'' { cis1 ees fisis aeses s16_" " }
103 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
110 \property Score.timing = ##f
111 \transpose c'' { a2. a4 a8. a16 s16_" " }
114 The @rglos{meter} (or @rglos{time signature}) can be set with the
115 @code{\time} command:
123 @c a clef here may lead to confusion
125 \property Staff.Clef \set #'transparent = ##t
134 The @rglos{clef} can be set using the @code{\clef} command:
136 @c what is more common name treble or violin?
137 @c in Dutch, its violin.
138 @c in English its definitely treble.
147 \property Score.timing = ##f
158 When you enter these commands in a file, you must to enclose them in
159 @code{\notes @{@dots{}@}}. This lets LilyPond know that music (and
160 not @rglos{lyrics}, for example) follows:
171 Now the piece of music is almost ready to be printed. The final step is to
172 combine the music with a printing command.
174 The printing command is the so-called @code{\paper} block. Later on
175 you will see that the @code{\paper} block is used to customize
176 printing specifics. The music and the @code{\paper} block are combined by
177 enclosing them in @code{\score @{ ... @}}. This is what a full
178 LilyPond source file looks like:
201 linewidth = 55 * \staffspace
207 @node Running LilyPond
208 @section Running LilyPond
210 In the last section we explained what kind of things you could enter
211 in a lilypond file. In this section we explain how to run LilyPond
212 and how to view or print the output. If you have not used LilyPond
213 before, want to test your setup of LilyPond, or want to run an example
214 file yourself, read this section. The instructions that follow
215 are for running LilyPond on Unix-like systems. Some additional
216 instructions for running LilyPond on Windows are given at the end of
219 Begin by opening a terminal window and starting a text editor.
220 For example, you could open an xterm and execute @code{joe}. In your
221 text editor, enter the following input and save the file as
227 \notes @{ c'4 e' g' @}
234 @c now this is weird, running ly2dvi to run LilyPond
235 @c (therefore name change proposal)
237 LilyPond is the program that computes the sheet music. All other
238 things, such as adding titles, page breaking and other page layout,
239 are done by a small wrapper program called
240 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
241 then adds the titling and page layout instructions. To process
242 @file{test.ly} with @code{ly2dvi}, proceed as follows:
250 You will see the following on your screen:
255 Now processing: `/home/fred/ly/test.ly'
257 Interpreting music...[1]
258 @emph{ ... more interesting stuff ... }
259 PS output to `test.ps'...
260 DVI output to `test.dvi'...
264 @cindex Viewing music
267 The results of the ly2dvi run are two files, @file{test.dvi} and
268 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
269 You can view the PS file using the program ghostview. If a version of
270 ghostview is installed on your system, one of these commands will
271 produce a window with some music notation on your screen:
281 If the music on your screen looks good, you can print it by clicking
282 File/Print inside ghostview.
284 The DVI file (@file{test.dvi}) contains the same sheet music in a
285 different format. DVI files are more easily processed by the computer,
286 so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
287 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons
288 activate magnifying glasses. Unfortunately, variable symbols (such as
289 beams and slurs) are not displayed in the magnifying glasses.
291 If your DVI viewer does not have a "Print" button, you can print the
292 file by executing @code{lpr test.ps}.
294 @c volgende alinea schrappen?
296 If your system does not support printing PostScript files, then you
297 can install Ghostscript, a PostScript emulator. Refer to
298 Ghostscript's website at @uref{http://www.ghostscript.com}.
302 @cindex Printing output
306 A final option is to use the popular PDF format. You can get a PDF
307 file by running @code{ly2dvi --pdf test.ly}. With @code{--pdf}
308 you will get DVI, PS and PDF files. Viewers for PS files also
309 accept PDF files, but there are also many other applications for
312 If you are familiar with @TeX{}, be warned: do not use other
313 DVI drivers like @code{dvilj}. The @TeX{} coming out of LilyPond
314 uses embedded PostScript code and will not render correctly if
315 you use anything other than @code{dvips}.
321 @unnumberedsubsec Windows users
322 Windows users can start the terminal by clicking on the LilyPond or
323 Cygwin icon. You can use any text editor (such as NotePad, Emacs or
324 Vim) to edit the LilyPond file. If you install the Cygwin's
325 @code{XFree86} X11 window system, @code{tetex-x11} and
326 @code{ghostscript-x11} packages too, you can view the @code{dvi}
327 output doing @code{xdvi test.dvi} as described above. If you have
328 installed a PostScript/PDF viewer, such as @code{GSView} from
329 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PS file can be done
333 @code{gsview32 test.ps}
336 You can also print from the command line by executing:
339 @code{gsview32 /s test.ps}
346 To run LilyPond, input a text file, then run the command @code{ly2dvi} on
347 that file. The resulting files are either DVI or PostScript, and can
348 be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows)
349 respectively. The following table summarizes the constructs that were
350 discussed in the previous two sections.
352 @multitable @columnfractions .3 .3 .4
358 @item @code{1 2 8 16}
361 @lilypond[relative 1, noquote, notime]
362 \property Staff.autoBeaming = ##f
363 \property Staff.Clef = \turnOff
368 @tab augmentation dots
370 @lilypond[relative 1, noquote, notime]
371 \property Staff.Clef = \turnOff
375 @item @code{c d e f g a b }
378 @lilypond[relative 1, noquote, notime]
379 \property Staff.Clef = \turnOff
383 @item @code{\clef treble \clef bass }
386 @lilypond[noquote, notime]
393 @item @code{\time 3/4 \time 4/4 }
397 \property Staff.Clef \set #'transparent = ##t
410 We continue with the introduction of the remaining musical constructs.
411 Normal rests are entered just like notes with the name ``@code{r}'':
419 \property Score.timing = ##f
420 \property Staff.Clef = \turnOff
421 \property Staff.TimeSignature = \turnOff
428 @c Tim wants to move this quotes example just before the: quotes-don't-work
429 @c score, but we'd need to remove quotes from the other two (key and
432 @c better to have this just before the `octaves are bad' snipped
433 @c but we'd need to remove the ', from \key and tie
434 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
435 the note name, to lower a note one octave, add a ``low quote'' @code{,}
436 (a comma). Middle C is @code{c'}:
440 c'4 c'' c''' \clef bass c c,
444 \property Score.timing = ##f
445 \property Staff.TimeSignature = \turnOff
446 c'4 c'' c''' \clef bass c c,
451 A tie is created by adding a tilde ``@code{~}'' to the first note
454 @lilypond[fragment,verbatim]
459 A tie is different from a slur. A tie simply makes the first note
460 sound longer, and can only be used on pairs of notes with the same
461 pitch. Slurs indicate the articulations of notes, and can be used on
462 larger groups of notes. Slurs and ties are also nested in practice:
463 @lilypond[fragment, relative=1]
464 c2-~-( c8 fis fis4 ~ fis2 g2-)
468 The key signature is set with the command ``@code{\key}''. One
469 caution word of caution: you need to specify whether the key is
470 @code{\major} or @code{\minor}.
480 \property Staff.TimeSignature = \turnOff
489 @c bit on the long/complex/scary taste
490 @c cheating a bit: two lines makes for a friendlier look
491 This example shows notes, ties, octave marks, and rests in action.
500 r4 r8 d''8 cis''4 e''
502 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
515 r4 r8 d''8 cis''4 e''
517 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
520 \paper { linewidth = 50*\staffspace }
526 There are some interesting points to note in this example.
527 Accidentals (sharps and flats) don't have to be marked explicitly: you
528 just enter the note name, and LilyPond determines whether or not to
529 print an accidental. Bar lines and beams are drawn automatically.
530 LilyPond calculates line breaks for you; it doesn't matter where you
531 make new lines in the source file. Finally, the order of time, key and
532 clef changes is not relevant: lilypond will use standard notation
533 conventions for ordering these items.
535 The example also indicates that a piece of music written in a high
536 register needs lots of quotes. This makes the input less readable,
537 and is also a potential source of errors.
539 The solution is to use ``relative octave'' mode. In practice, this is
540 the most convenient way to copy existing music. To use relative mode,
541 add @code{\relative} before the piece of music. You must also give a
542 note from which relative starts, in this case @code{c''}. If you don't
543 use octavation quotes (ie don't add ' or , after a note), relative mode
544 chooses the note that is closest to the previous one. Since most music
545 has small intervals, you can write quite a lot in relative mode without
546 using octavation quotes.
547 @c don't use commas or quotes in this sentence
548 For example: @code{c f} goes up; @code{c g} goes down:
558 \property Score.timing = ##f
559 \property Staff.TimeSignature = \turnOff
568 @c needed better, maybe even redundant explanation
569 @c added another example below.
570 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
571 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
572 You can make larger intervals by adding octavation quotes. Note that
573 quotes or commas do not determine the absolute height of a note;
574 the height of a note is relative to the previous one.
575 @c don't use commas or quotes in this sentence
576 For example: @code{c f,} goes down; @code{f, f} are both the same;
577 @code{c' c} are the same; and @code{c g'} goes up:
587 \property Score.timing = ##f
588 \property Staff.TimeSignature = \turnOff
597 Here's an example of the difference between relative mode and
598 ``normal'' (non-relative) mode:
609 \property Score.timing = ##f
610 \property Staff.TimeSignature = \turnOff
626 \property Score.timing = ##f
627 \property Staff.TimeSignature = \turnOff
636 The following table summarizes the syntax learned so far in this section.
638 @c Is it possible to avoid page breaks directly after the
641 @multitable @columnfractions .3 .3 .4
650 @lilypond[relative 1, noquote, notime]
651 \property Staff.Clef = \turnOff
658 @lilypond[relative 1, noquote, notime]
659 \property Score.timing = ##f
660 \property Staff.autoBeaming = ##f
661 \property Staff.Clef = \turnOff
665 @item @code{\key es \major }
668 @lilypond[noquote, notime]
674 @item @var{note}@code{'}
677 @lilypond[relative 1, noquote, notime]
678 \property Score.timing = ##f
679 \property Staff.autoBeaming = ##f
680 \property Staff.Clef = \turnOff
684 @item @var{note}@code{,}
687 @lilypond[relative 1, noquote, notime]
688 \property Score.timing = ##f
689 \property Staff.autoBeaming = ##f
690 \property Staff.Clef = \turnOff
696 A slur is drawn across many notes, and indicates bound articulation
697 (legato). The starting note and ending note are marked with a
698 ``@code{(}'' and a ``@code{)}'' respectively:
701 @lilypond[fragment,relative 1, verbatim]
702 d4-( c16-)-( cis d e c cis d e-)-( d4-)
707 If you need two slurs at the same time (one for articulation, one for
708 phrasing), you can also make a phrasing slur with @code{\(} and
713 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
714 @c chromatic thing pasted in front. (admittedly the original doesn't
715 @c have a phrasing slur. The problem is that we don't want the slur
716 @c and the Phrasing slur to collide. We're trying to make a good
720 @lilypond[fragment,relative 1, verbatim]
721 a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
726 Beams are drawn automatically, but if you don't like the choices, you
727 can enter beams by hand. Mark the first note to be beamed with
728 @code{[} and the last one with @code{]}:
730 @lilypond[fragment,relative 1, verbatim]
731 a8-[ ais-] d-[ es r d-]
736 To print more than one staff, each piece of music that makes up a staff
737 is marked by adding @code{\context Staff} before it. These
738 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
742 @lilypond[fragment,verbatim]
744 \context Staff = staffA { \clef violin c'' }
745 \context Staff = staffB { \clef bass c }
750 In this example, @code{staffA} and @code{staffB} are names that are
751 given to the staves. It doesn't matter what names you give, as long
752 as each staff has a different name.
756 We can now typeset a melody with two staves:
759 @lilypond[verbatim,singleline]
762 < \context Staff = staffA {
765 \relative c'' { e2-( d4 c2 b4 a8-[ a-] b-[ b-] g-[ g-] a2.-) }
767 \context Staff = staffB {
778 Notice that the time signature is specified in one melody staff only
779 (the top staff), but is printed on both. LilyPond knows that the time
780 signature should be the same for all staves.
784 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
786 @lilypond[verbatim,relative 1]
792 Dynamic signs are made by adding the markings to the note:
794 @lilypond[verbatim,relative 1]
800 Crescendi and decrescendi are started with the commands @code{\<} and
801 @code{\>}. The command @code{\!} finishes a crescendo on the note it
804 @lilypond[verbatim,relative 1]
805 c2-\< c2-\!-\ff c2-\> c2-\!
810 Chords can be made by surrounding notes with @code{<<} and @code{>>}:
812 @lilypond[relative 0, fragment,verbatim]
813 r4 <<c e g>>4 <<c f a>>8
820 @c hmm, te losjes, iig
821 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
822 happens at the same time, like in chords, or (like in the two-staff
823 example above) in a bunch of stacked staves.
826 You can combine beams and ties with chords. Beam and tie markings
827 must be placed outside the chord markers:
829 @lilypond[relative 0, fragment,verbatim]
830 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
834 When you want to combine chords with slurs and dynamics, technical
835 detail crops up: you have type these commands next to the notes, which
836 means that they have to be inside the @code{< >}. Don't get confused
837 by the chord @code{< >} and the dynamic @code{\< \>}!
842 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
844 @lilypond[relative 0, fragment]
846 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
854 @multitable @columnfractions .3 .3 .4
864 @lilypond[fragment, relative 1]
865 \property Score.timing = ##f
866 \property Staff.TimeSignature = \turnOff
867 \property Staff.autoBeaming = ##f
868 \property Staff.Clef = \turnOff
876 @lilypond[fragment, relative 1]
877 \property Score.timing = ##f
878 \property Staff.TimeSignature = \turnOff
879 \property Staff.autoBeaming = ##f
880 \property Staff.Clef = \turnOff
888 @lilypond[fragment, relative 1]
889 \property Score.timing = ##f
890 \property Staff.TimeSignature = \turnOff
891 \property Staff.autoBeaming = ##f
892 \property Staff.Clef = \turnOff
897 @item @code{< \context Staff ... >}
901 < \context Staff = SA { c'1 }
902 \context Staff = SB { c'1 } >
909 @lilypond[fragment, relative 1]
910 \property Staff.TimeSignature = \turnOff
911 \property Staff.Clef = \turnOff
916 @item @code{-\mf -\sfz}
919 @lilypond[fragment, relative 1]
920 \property Staff.TimeSignature = \turnOff
921 \property Staff.Clef = \turnOff
929 @lilypond[fragment, relative 1]
930 \property Score.timing = ##f
931 \property Staff.TimeSignature = \turnOff
932 \property Staff.autoBeaming = ##f
933 \property Staff.Clef = \turnOff
940 @lilypond[fragment, relative 1]
941 \property Score.timing = ##f
942 \property Staff.TimeSignature = \turnOff
943 \property Staff.autoBeaming = ##f
944 \property Staff.Clef = \turnOff
952 @lilypond[fragment, relative 1]
958 Now you know the basic ingredients of a music file, so this is the right
959 moment to try your at hand at doing it yourself: try typing some
960 simple examples, and experiment a little.
962 When you're comfortable with the basics, you might want to read
963 the rest of this chapter. It continues in tutorial-style, but it
964 is much more in-depth, dealing with more advanced topics such as
965 lyrics, chords, orchestral scores and parts, fine tuning of output,
966 polyphonic music, and integrating text and music.
972 @node Printing lyrics
973 @section Printing lyrics
976 In this section we shall explain how to typeset the following
977 fragment of The Free Software Song:
979 @lilypond[singleline]
980 \score { \notes { \addlyrics
981 \notes \relative c' {
983 d'2 c4 b16-( a g a b a b c-) a2
984 b2 c4 b8-( a16 g a4-) g2 }
985 \context Lyrics \lyrics {
987 share the soft -- ware; }
989 \paper { linewidth = -1. }
995 @cindex @code{\lyrics}
998 To print lyrics, you must enter them and then instruct lilypond to
1000 You can enter lyrics in a special input mode of LilyPond. This mode is
1001 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1002 The purpose of this mode is that you can enter lyrics as plain text,
1003 punctuation, and accents without any hassle.
1005 Syllables are entered like notes, but with pitches replaced by text. For
1006 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1007 the hyphen has no special meaning for lyrics, and does not introduce
1010 Spaces can be introduced into a lyric either by using quotes:
1011 @code{"He could" not} or by using an underscore without quotes:
1012 @code{He_could not}. All unquoted underscores are converted to
1015 These are the lyrics for the free software song:
1020 share the soft -- ware; @}
1023 As you can see, extender lines are entered as @code{__}. This will
1024 create an extender, which is a line that extends over the entire
1025 duration of the lyric. This line will run all the way to the start
1026 of the next lyric, so you may want to shorten it by using a blank
1027 lyric (using @code{_}).
1030 You can use ordinary hyphens at the end of a syllable, i.e.
1034 but then the hyphen will be attached to the end of the first syllable.
1036 If you want them centered between syllables you can use the special
1037 `@code{-}@code{-}' lyric as a separate word between syllables. The
1038 hyphen will have variable length depending on the space between
1039 the syllables and it will be centered between the syllables.
1041 Normally the notes that you enter are transformed into note heads.
1042 Note heads alone make no sense, so they need surrounding information: a
1043 key signature, a clef, staff lines, etc. They need @emph{context}. In
1044 LilyPond, these symbols are created by objects called `interpretation
1045 contexts'. Interpretation contexts exist for generating notation
1046 (`notation context') and for generating sound (`performance
1047 context'). These objects only exist while LilyPond is executing.
1049 When LilyPond interprets music, it will create a Staff context.
1050 We don't want that default here, because we want lyric. The
1055 explicitly creates an interpretation context of
1056 @code{Lyrics} type to interpret the song text that we entered.
1058 The melody of the song doesn't offer anything new:
1060 \notes \relative c' @{
1062 d'2 c4 b16-( a g a b a b c-) a2
1063 b2 c4 b8-( a16 g a4-) g2 @}
1066 Both can be combined with the @code{\addlyrics}:
1069 \notes \relative c' @dots{}
1070 \context Lyrics \lyrics @dots{}
1073 The lyrics are also music expressions, similar to notes. Each syllable
1074 of the lyrics is put under a note of the melody.
1075 The complete file is listed here:
1078 \score @{ \notes @{ \addlyrics
1079 \notes \relative c' @{
1081 d'2 c4 b16 ( a g a b a b ) c a2
1082 b2 c4 b8 ( a16 g ) a4 g2 @}
1083 \context Lyrics \lyrics @{
1085 share the soft -- ware; @}
1087 \paper @{ linewidth = -1. @}
1093 @node A melody with chords
1094 @section A melody with chords
1096 In this section we show how to typeset a melody with chord
1097 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1100 \include "paper16.ly"
1101 melody = \notes \relative c' @{
1105 c4 c8 d es-[ -( d-]-) c4 | f4 f8 g es-[-( d-)-] c g |
1106 c4 c8 d es-[ -( d-]-) c4 | d4 es8 d c4.
1110 accompaniment =\chords @{
1112 c2:3- f:3-.7 d:min es4 c8:min r8
1113 c2:min f:min7 g:7^3.5 c:min @}
1118 \context ChordNames \accompaniment
1119 \context Staff = mel @{
1124 \midi @{ \tempo 4=72 @}
1125 \paper @{ linewidth = 10.0\cm @}
1130 The result would look this.
1133 \include "paper16.ly"
1134 melody = \notes \relative c' {
1138 c4 c8 d es-[ -( d-)-] c4 | f4 f8 g es-(-[ d-)-] c g |
1139 c4 c8 d es-(-[ d-]-) c4 | d4 es8 d c4.
1143 accompaniment =\chords {
1145 c2:3- f:3-.7 d:min es4 c8:min r8
1146 c2:min f:min7 g:7^3.5 c:min }
1151 \context ChordNames \accompaniment
1153 \context Staff = mel {
1154 \property Staff.autoBeaming = ##f
1158 \midi { \tempo 4=72 }
1159 \paper { linewidth = 10.0\cm }
1163 We will dissect this file line by line.
1168 \include "paper16.ly"
1171 Smaller size (suitable for inclusion in a book).
1175 melody = \notes \relative c' @{
1178 The structure of the file will be the same as the previous one: a
1179 @code{\score} block with music in it. To keep things readable, we will
1180 give different names to the different parts of music, and use the names
1181 to construct the music within the score block.
1188 @cindex @code{\partial}
1190 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1196 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1197 c4 c8 d [es () d] c4 | d4 es8 d c4.
1202 @cindex manual beaming
1203 @cindex automatic beaming, turning off
1204 We use explicit beaming. Since this is a song, we turn automatic
1205 beams off and use explicit beaming where needed.
1212 This ends the definition of @code{melody}.
1221 @cindex identifier assignment
1222 @cindex syllables, entering
1223 This defines the lyrics, similar to what we have seen before.
1228 accompaniment =\chords @{
1232 @cindex mode, chords
1233 We'll put chords over the music. To enter them, we use a special mode
1234 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1235 the names of the chords you want instead of listing the notes
1236 comprising the chord.
1243 There is no accompaniment during the anacrusis.
1252 @cindex chord modifier
1253 @cindex modifier, chord
1254 This is a c minor chord, lasting for a half note. Chords are entered using
1255 the tonic. Notes can be changed to create different chords. In this case,
1256 a lowered third is used (making a C major chord into a C minor chord).
1257 The code for this is @code{3-}.
1263 Similarly, @code{7} modifies (adds) a seventh, which is small by
1264 default to create the @code{f a c es} chord. Multiple modifiers must be
1272 Some modifiers have predefined names, e.g. @code{min} is the same as
1273 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1277 c2:min f:min7 g:7^3.5 c:min @}
1280 @cindex named modifier
1282 A named modifier @code{min} and a normal modifier @code{7} do not have
1283 to be separated by a dot. Tones from a chord are removed with chord
1284 subtractions. Subtractions are started with a caret, and they are
1285 also separated by dots. In this example, @code{g:7^3.5} produces a
1286 minor seventh (a G7 chord without the third or the fifth). The
1287 brace ends the sequential music.
1295 We assemble the music in the @code{\score} block. Melody, lyrics and
1296 accompaniment have to sound at the same time, so they should be
1297 @code{\simultaneous}.
1298 @cindex @code{\simultaneous}
1305 Chord mode generates notes grouped in @code{\simultaneous} music. If
1306 you remove the comment sign, you can see the chords in normal
1307 notation: they will be printed as note heads on a separate
1308 staff. To print them as chords names, they have to be interpreted as
1309 being chords, not notes. This is done with the following command:
1313 \context ChordNames \accompaniment
1317 @cindex interpretation context
1318 @cindex notation context
1321 Normally the notes that you enter are transformed into note heads.
1322 Note heads alone make no sense, so they need surrounding information: a key
1323 signature, a clef, staff lines, etc. They need @emph{context}. In
1324 LilyPond, these symbols are created by objects called `interpretation
1325 contexts'. Interpretation contexts exist for generating notation
1326 (`notation context') and for generating sound (`performance
1327 context'). These objects only exist while LilyPond is executing.
1329 When LilyPond interprets music, it will create a Staff context. If
1330 the @code{%} sign in the previous line were removed, you could see
1331 that mechanism in action.
1333 We don't want that default here, because we want chord names. The
1334 command above explicitly creates an interpretation context of
1335 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1340 \context Staff = mel @{
1344 We place the melody on a staff called @code{mel}. We give it a name to
1345 differentiate it from the one that would contain note heads for the
1346 chords, if you would remove the comment before the ``note heads''
1347 version of the accompaniment. By giving this staff a name, it is
1348 forced to be different.
1352 \property Staff.autoBeaming = ##f
1356 @cindex context variables
1357 @cindex setting context variables
1358 An interpretation context has variables, called properties, that tune
1359 its behavior. One of the variables is @code{autoBeaming}. Setting
1360 this @code{Staff}'s property to @code{##f}, which is the boolean value
1361 @var{false}, turns the automatic beaming mechanism off for the current
1372 Finally, we put the melody on the current staff. Note that the
1373 @code{\property} directives and @code{\melody} are grouped in sequential
1374 music, so the property settings are done before the melody is
1380 \midi @{ \tempo 4=72@}
1383 MIDI (Musical Instrument Digital Interface) is a standard for
1384 connecting and recording digital instruments. So a MIDI file is like a
1385 tape recording of an instrument. The @code{\midi} block makes the
1386 music go to a MIDI file, so you can listen to the music you entered. It
1387 is great for checking the music. Whenever you hear something weird, you
1388 probably hear a typing error.
1390 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1391 also specifies an output method. You can specify the tempo using the
1392 @code{\tempo} command, in this case the tempo of quarter notes is set to
1393 72 beats per minute.
1397 \paper @{ linewidth = 10.0\cm @}
1400 We also want notation output. The linewidth is short so that the piece
1401 will be set in two lines.
1404 @section More stanzas
1409 If you have multiple stanzas printed underneath each other, the vertical
1410 groups of syllables should be aligned around punctuation. LilyPond can
1411 do this if you tell it which lyric lines belong to which melody.
1412 We show how you can do this by showing how you could print a frivolous
1413 fragment of a fictional Sesame Street duet.
1415 @lilypond[singleline,verbatim]
1418 \notes \relative c'' \context Voice = duet { \time 3/4
1420 \lyrics \context Lyrics <
1421 \context LyricsVoice = "duet-1" {
1422 \property LyricsVoice . stanza = "Bert"
1423 Hi, my name is bert. }
1424 \context LyricsVoice = "duet-2" {
1425 \property LyricsVoice . stanza = "Ernie"
1426 Ooooo, ch\'e -- ri, je t'aime. }
1431 To this end, give the Voice context an identity, and set the
1432 LyricsVoice to a name starting with that identity followed by a dash.
1433 In the following example, the Voice identity is @code{duet},
1435 \context Voice = duet @{
1440 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1442 \context LyricsVoice = "duet-1" @{
1443 Hi, my name is bert. @}
1444 \context LyricsVoice = "duet-2" @{
1445 Ooooo, ch\'e -- ri, je t'aime. @}
1448 We add the names of the singers. This can be done by setting
1449 @code{LyricsVoice.Stanza} (for the first system) and
1450 @code{LyricsVoice.stz} for the following systems. Note that you must
1451 surround dots with spaces in @code{\lyrics} mode.
1454 \property LyricsVoice . stanza = "Bert"
1456 \property LyricsVoice . stanza = "Ernie"
1459 The convention for naming @code{LyricsVoice} and @code{Voice} must
1460 also be used to get melismata on rests correct.
1463 @c I think we need to change the name of this section, but that
1464 @c would probably involve a lot of changes in other places too.
1465 @node More movements
1466 @section More movements
1468 The program @code{lilypond} only produces sheet music and does not
1469 create titles, subtitles, or print the composer's name. To do that,
1470 you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi}
1471 creates the title, then calls @code{lilypond} to format the sheet music.
1472 In this section, we show you how to create titles like this:
1474 @c Old version of the above paragraph.
1475 @c LilyPond only produces sheet music; it doesn't concern itself with
1476 @c producing titles. Titles are produced using a simply wrapper program
1477 @c This is the jobs of a simple wrapper
1478 @c program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
1479 @c sheet music formatting. Then it produces titles, and ties together all
1480 @c inputs into a single @file{dvi} file. In this section, we show some of
1481 @c the options for titling. We will show how you can produce a file
1482 @c that looks like this:
1484 @center @strong{Two miniatures}
1494 \paper { linewidth = -1.0 }
1506 \paper { linewidth = -1.0 }
1510 For example, consider the following file (@file{miniatures.ly})
1515 title = "Two miniatures"
1516 composer = "F. Bar Baz"
1517 tagline = "small is beautiful" @}
1519 \paper @{ linewidth = -1.0 @}
1523 Mental note: discuss Schenkerian analysis of these key pieces.
1528 \notes @{ c'4 d'4 @}
1534 \notes @{ d'4 c'4 @}
1542 The information for the global titling is in a so-called header block.
1543 The information in this block is not used by LilyPond, but it is
1544 passed into @code{ly2dvi}, which uses this information to print titles
1547 @cindex identifier assignment
1548 the @code{\header} block contains assignments. In each assignment, a
1549 variable is set to a value. The header block for this file looks like
1551 @cindex @code{\header}
1554 title = "Two miniatures"
1555 composer = "F. Bar Baz"
1556 tagline = "small is beautiful"
1560 When you process a file with ly2dvi, a signature line is printed at
1561 the bottom of the last page. This signature is produced from the
1562 @code{tagline} field of @code{\header}. The default "Lily was here,
1563 @var{version number}" is convenient for programmers: archiving the
1564 layouts of different versions allows programmers to compare the
1565 versions using old print-outs.
1567 @cindex Lily was here
1568 @cindex signature line
1571 Many people find the default tagline (``Lily was here'') too droll.
1572 If that is the case, you can change @code{tagline} to somethign else,
1581 A paper block at top level (i.e. not in a @code{\score} block) sets the
1582 default page layout. The following @code{\score} blocks don't have
1583 @code{\paper} sections, so the settings of this block are used.
1585 The variable @code{linewidth} normally sets the length of the systems
1586 on the page. However, a negative value has a special meaning. If
1587 @code{linewidth} is less than 0, no line breaks are inserted into the
1588 score, and the spacing is set to natural length: a short phrase takes
1589 up little space, a longer phrase takes more space, all on the same line.
1594 Mental note: discuss Schenkerian analysis of these key pieces.
1599 Mental notes to yourself can be put into comments. There are two types
1600 of comments. Line comments are introduced by @code{%}, and block
1601 comments are delimited by @code{%@{} and @code{%@}}.
1606 \notes @{ c'4 d'4 @}
1609 In previous examples, most notes were specified in relative octaves
1610 (i.e. each note was put in the octave that is closest to its
1611 predecessor). Besides relative, there is also absolute octave
1612 specification, which you get when you don't include @code{\relative} in
1613 your input file. In this input mode, the middle C is denoted by
1614 @code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
1615 Going up, you get @code{c''} @code{c'''} etc.
1617 When you're copying music from existing sheet music, relative octaves
1618 are probably the easiest to use: you have to do less typing, and errors are
1619 easily spotted. However, if you write LilyPond input directly, either by
1620 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1628 The @code{\header} is normally at the top of the file, where it sets
1629 values for the rest of the file. If you want to typeset different pieces
1630 from one file (for example, if there are multiple movements, or if
1631 you're making an exercise book), you can put different @code{\score}
1632 blocks into the input file. @code{ly2dvi} will assemble all LilyPond
1633 output files into a big document. The contents of @code{\header} blocks
1634 specified within each score is used for the title of that movement.
1640 For example, the Opus number is put at the right, and the "piece" string
1641 will be at the left.
1648 title = "Two miniatures"
1649 composer = "F. Bar Baz"
1650 tagline = "small is beautiful" @}
1652 \paper @{ linewidth = -1.0 @}
1655 \notes @{ c'4 d'4 @}
1661 \notes @{ d'4 c'4 @}
1671 scoreA = \score @{ \deelA @}
1672 scoreB = \score @{ \deelA @}
1674 % \score @{ \scoreA @}
1675 \score @{ \scoreB @}
1683 Lilypond and its language are still under development, and
1684 occasionally details of the syntax are changed. The @code{version}
1685 fragment indicates which version of lilypond the input file was written
1686 for. When you compile this file, the version number will be checked
1687 and you will get a warning when the file is too old. This version
1688 number is also used by the @code{convert-ly} program (See
1689 @ref{Invoking convert-ly}), which can used to update the file to the
1690 latest lily version.
1693 @node A piano excerpt
1694 @section A piano excerpt
1696 Our eighth subject is a piece of piano music. The fragment in the
1697 input file is a piano reduction of the G major Sinfonia by Giovanni
1698 Battista Sammartini, composed around 1740. It's in the source
1699 package under the name @file{input/tutorial/sammartini.ly}.
1701 @lilypondfile[smallverbatim,noquote]{sammartini.ly}
1703 As you can see, this example features multiple voices on one staff. To
1704 make room for those voices, their notes should be stemmed in opposite
1707 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1708 with some other commonly used formatting instructions, but to explain how
1709 it works, we wrote our own here. Of course, you should use predefined
1710 identifiers like these if possible: you will be less affected by changes
1711 between different versions of LilyPond.
1715 viola = \notes \relative c' \context Voice = viola @{
1717 In this example you can see multiple parts on a staff. Each part is
1718 associated with one notation context. This notation context handles
1719 stems and dynamics (among other things). The type name of this context
1720 is @code{Voice}. For each part we have to make sure that there is
1721 precisely one @code{Voice} context, so we give it a unique name
1728 The delimiters @code{<} and @code{>} are shorthands for
1729 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1730 @code{<} and @code{>} is a chord.
1734 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1742 We want the viola to have stems down, and have all the other
1743 characteristics of a second voice. This is enforced using the
1744 @code{\voiceTwo} command: it inserts instructions that makes stem,
1745 ties, slurs, etc. go down.
1753 Relative octaves work a little differently with chords. The starting
1754 point for the note following a chord is the first note of the chord. So
1755 the @code{g} gets an octave up quote: it is a fifth above the starting
1756 note of the previous chord (the central C).
1762 @code{s} is a spacer rest. It does not print anything, but it does have
1763 the duration of a rest. It is useful for filling up voices that
1764 temporarily don't play. In this case, the viola doesn't come until one
1765 and a half measure later.
1769 oboes = \notes \relative c'' \context Voice = oboe @{
1771 Now comes a part for two oboes. They play homophonically, so we
1772 print the notes as one voice that makes chords. Again, we insure that
1773 these notes are indeed processed by precisely one context with
1777 \voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
1780 The oboes should have stems up to keep them from interfering with
1781 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1785 \grace <e8( g> < d4 )f> <c2 e>
1787 @cindex @code{\grace}
1790 @code{\grace} introduces grace notes. It takes one argument, in this
1791 case a chord. A slur is introduced starting from the @code{\grace}
1792 ending on the following chord.
1800 Tuplets are made with the @code{\times} keyword. It takes two
1801 arguments: a fraction and a piece of music. The duration of the piece
1802 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1803 of their notated duration, so in this case the fraction is 2/3.
1806 @{ <d8 f> <e g> <f a> @}
1808 The piece of music to be `tripletted' is sequential music containing
1815 At this point, the homophonic music splits into two rhythmically
1816 different parts. We can't use a sequence of chords to enter this, so
1817 we make a "chord of sequences" to do it. We start with the upper
1818 voice, which continues with upward stems:
1821 @{ \times 2/3 @{ a8 g c @} c2 @}
1828 The easiest way to enter multiple voices is demonstrated
1829 here. Separate the components of the voice (single notes or entire
1830 sequences) with @code{\\} in a simultaneous music expression. The
1831 @code{\\} separators split first voice, second voice, third voice, and
1834 As far as relative mode is concerned, the previous note is the
1835 @code{c'''2} of the upper voice, so we have to go an octave down for
1843 This ends the two-part section.
1847 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1852 @code{\stemBoth} ends the forced stem directions. From here, stems are
1853 positioned as if it were single part music.
1855 The bass has a little hoom-pah melody to demonstrate parts switching
1856 between staves. Since it is repetitive, we use repeats:
1859 hoomPah = \repeat unfold 8
1861 @cindex unfolded @code{\repeat}
1862 The unfolded repeat prints the notes in its argument as if they were
1863 written out in full eight times.
1866 \notes \transpose c' @{
1869 @cindex relative mode and transposing
1871 Transposing can be done with @code{\transpose}, which takes two arguments.
1872 The first specifies what central C should be transposed to. The second
1873 is the to-be-transposed music. As you can see, in this case, the
1874 transposition has no effect, as central C stays at central C.
1876 The purpose of this no-op is to protect it from being interpreted as
1877 relative notes. Relative mode can not be used together with
1878 transposition, so @code{\relative} will leave the contents of
1879 @code{\hoomPah} alone. We can use it without having to worry about
1880 getting the motive in a wrong octave. Conversely, if you want to
1881 transpose a fragment of music entered with @code{\relative}, then you
1882 should make sure that @code{\transpose} comes before @code{\relative}.
1885 @cindex staff switch, manual
1886 @cindex cross staff voice, manual
1887 @cindex @code{\translator}
1890 \translator Staff = down
1893 \translator Staff = up
1897 Voices can switch between staves. Here you see two staff switching
1898 commands. The first one moves to the lower staff, the second one to
1899 the lower one. If you set the stem directions explicitly
1900 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1901 can be beamed together (despite jumping between staffs).
1905 bassvoices = \notes \relative c' @{
1907 \autochange Staff \hoomPah \context Voice
1912 \translator Staff = down
1914 @cindex staff switch
1915 @cindex cross staff voice
1916 We want the remaining part of this melody on the lower staff, so we do a
1917 manual staff switch here.
1922 \context Voice = reallyLow @{\stemDown g2-~ | g4 c8 @} >
1926 After skipping some lines, we see @code{~}. This mark makes ties. Note
1927 that ties and slurs are different things. A tie can only connect two
1928 note heads of the same pitch, whereas a slur can connect many notes
1935 A special context is needed to get cross staff beaming right. This
1936 context is called @code{PianoStaff}.
1939 \context Staff = bottom < \time 2/2 \clef bass
1941 The bottom staff must have a different clef.
1946 To make some more room on the line, the first (in this case the only)
1947 line is not indented. The line still looks very cramped, but that is due
1948 to the page layout of this document.
1954 * font-size, multi-stanza.
1956 * Simple part combining in a Hymn
1960 @node Fine tuning a piece
1961 @section Fine tuning a piece
1963 In this section we show some ways to fine tune the final output of a
1964 piece. We do so using a single measure of a moderately complex piano
1965 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
1966 tuned and the untuned versions) are in @file{input/tutorial/}.
1968 The code for the untuned example shows us some new things.
1970 @lilypondfile[verbatim]{brahms-original.ly}
1980 Hairpin dynamics can be easily added to Lilypond scores. Beginning a
1981 crescendo is indicated with @code{\<} and ending a crescendo is indicated
1982 with @code{\!}. A decrescendo can be indicated with @code{\>} and
1983 @code{\!}. Absolute dynamics (sometimes called ``Letter dynamics'') can
1984 be entered using @code{\p}, @code{\mf}, etc. All these dynamics will
1985 apply to the whole chord where they are entered, but for syntactical
1986 reasons they must be attached to one of the notes of the chord.
1988 @cindex fingering instructions
1990 Fingering indications are entered with @code{-@var{N}}, where
1993 Now that we have the basic piece of music entered, we want to fine
1994 tune it so that we get something that resembles the original printed
1995 edition by Schott/Universal Edition:
1997 @lilypondfile{brahms-tweaked.ly}
1999 @cindex tuning graphical objects
2001 Fine tuning involves overriding the defaults of the printing system.
2002 We do this by setting variables which control how Lilypond prints
2003 symbols. Printed symbols are called graphical objects (often
2004 abbreviated to @emph{grob}). Each object is described by a bunch of
2005 settings. Every setting is a variable: it has a name and a value
2006 which you can change. These values determine the fonts, offsets,
2007 sub-routines to be called on the object, etc. The initial values of
2008 these settings are set in the Scheme file
2009 @file{scm/grob-description.scm}.
2011 @cindex slur attachments
2013 We start with the slur in the upper part, running from F sharp to A. In
2014 the printed edition, this slur runs from stem to stem; in our version,
2015 the slur begins at the note head of the F sharp. The following property
2016 setting forces all slurs to run from stem to stem (not from or to note
2020 \property Voice.Slur \set #'attachment = #'(stem . stem)
2023 More precisely, this command modifies the definition of the @code{Slur}
2024 object in the current @code{Voice}. The variable @code{attachment} is
2025 set to the pair of symbols @code{'(stem . stem)}.
2027 Although this fixes the slur, it isn't very helpful for fine tuning in
2028 general: the lilypond back-end supports approximately 240 variables
2029 like @code{attachment}, each with their own meaning and own type
2030 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2031 different types of graphical objects, that may be created in 14
2032 different context types besides Voice.
2034 @cindex internal documentation
2035 @cindex finding graphical objects
2036 @cindex graphical object descriptions
2038 The interesting information is how you can figure out which properties
2039 to tune for your own scores. To discover this, you must have a copy of
2040 the internals document. This is a set of HTML pages which should be
2041 included if you installed a binary distribution@footnote{You can also
2042 compile them by executing @code{make -C Documentation/user/
2043 out/lilypond-internals.html} in the source package.}. These HTML pages
2044 are also available on the web: go to the lilypond website, click
2045 ``Documentation: Index'' on the side bar, look in the ``Information for
2046 uses'' section, and click on ``Documentation of internals''.
2048 You might want to bookmark either the HTML files on your disk, or the one
2049 on the web (the HTML on your hard drive will load much faster than the
2050 ones on the web!). One word of caution: the internals documentation is
2051 generated from the definitions that lily uses. For that reason, it is
2052 strongly tied to the version of LilyPond that you use. Before you
2053 proceed, please make sure that you are using the documentation that
2054 corresponds to the version of LilyPond that you are using.
2056 @c TODO: the quote is incorrect, although that shouldn't be a big
2057 @c problem for the reader.
2058 Suppose that you wanted to tune the behavior of the slur. The first
2059 step is to get some general information on slurs in lilypond. Turn to
2060 the index, and look up ``slur''. The section on slurs says
2062 The grob for this object is @internalsref{Slur}, generally in
2063 @internalsref{Voice} context.
2066 So the graphical object for this object is called @code{Slur}, and
2067 slurs are created in the @code{Voice} context. If you are reading
2068 this tutorial in the HTML version, then you can simply click Slur,
2069 otherwise, you should look it up the internal documentation: click
2070 ``grob overview'' and select ``slur'' (the list is alphabetical).
2072 Now you get a list of all the properties that the slur object
2073 supports, along with their default values. Among the properties we
2074 find the @code{attachment} property with its default setting.
2075 The property documentation explains that the following setting will
2076 produce the desired effect:
2078 \property Voice.Slur \set #'attachment = #'(stem . stem)
2081 If you ran the previous example, you have unknowingly already used
2082 this kind of command. The @file{ly/property-init.ly} contains the
2083 definition of @code{\stemUp}:
2085 stemUp = \property Voice.Stem \set #'direction = #1
2088 @c this is a long section, and adding an extra space here helps to
2089 @c break it into smaller subsections and thus is easier to understand.
2092 Next we want to move the fingering `3'. In the printed edition it is
2093 not above the stem, but a little lower and slightly left of the stem.
2094 From the user manual we find that the associated graphical object is
2095 called @code{Fingering}, but how do we know if we should use
2096 @code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
2097 bet, but you can also deduce this information from the internals
2098 documentation: if you visit the documentation of @code{Fingering}, you
2101 Fingering grobs are created by: Fingering_engraver
2104 Clicking @code{Fingering_engraver} will show you the documentation of
2105 the module responsible for interpreting the fingering instructions and
2106 translating them to a @code{Fingering} object. Such a module is called
2107 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2110 Fingering_engraver is part of contexts: Voice and TabVoice
2112 so tuning the settings for Fingering should be done using either
2114 \property Voice.Fingering \set @dots{}
2118 \property TabVoice.Fingering \set @dots{}
2121 Since the @code{TabVoice} is only used for tab notation, we see that
2122 the first guess @code{Voice} was indeed correct.
2124 @cindex setting object properties
2125 @cindex @code{extra-offset}
2127 For shifting the fingering, we use the property @code{extra-offset}.
2128 The following command manually adds an offset to the object. We move
2129 it a little to the left, and 1.8 staff space downwards.
2131 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2133 The @code{extra-offset} is a low-level feature: it moves around
2134 objects in the printout; the formatting engine is completely oblivious
2135 to these offsets. The unit of these offsets are staff-spaces. The
2136 first number controls left-right movement; a positive number will move
2137 the object to the right. The second number controls up-down movement;
2138 a positive number will move it higher.
2140 @cindex reverting object properties
2141 @cindex undoing object properties
2143 We only want to offset a single object, so after the F-sharp we must
2144 undo the setting. The technical term is to revert the property.
2146 \property Voice.Fingering \revert #'extra-offset
2149 @cindex property types
2150 @cindex translator properties
2151 @cindex grob properties
2152 @cindex music properties
2155 There are three different types of variables in LilyPond, something
2156 which can be confusing at first (and for some people it stays confusing
2157 :). Variables such as @code{extra-offset} and @code{attachment} are
2158 called grob properties. They are not the same as translator properties,
2159 like @code{autoBeaming}. Finally, music expressions are internally
2160 stored using properties (so-called music properties). You will encounter
2161 music properties if you run Scheme functions on music using @code{\apply}.
2163 The second fingering instruction should be moved up a little to avoid
2164 a collision with the slur. This could be achieved with
2165 @code{extra-offset}, but in this case, a simpler mechanism also
2166 works. We insert an empty text between the 5 and the note. The empty
2167 text pushes the fingering instruction away:
2169 a^" "^#'(finger "5")
2172 Lilypond tries to put fingering instructions as close to the notes as
2173 possible. To make sure that Lilypond doesn't do that, we disguise the
2174 fingering as text: @code{(finger "5")}.
2178 Normally one would specify all dynamics in the same voice, so that
2179 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2180 in this case, we don't want the decrescendo to be aligned with the
2181 piano sign. We achieve this by putting the dynamic markings in different
2182 voices. The crescendo should be above the upper staff. This can be
2183 forced by using the precooked command
2188 However, if you do that the decrescendo will be too close to the
2189 upper voice and collide with the stems. Looking at the manual for
2190 dynamics, we notice that ``Vertical positioning of these symbols is
2191 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2192 to the documentation of @code{DynamicLineSpanner}, we find that
2193 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2194 object not only puts dynamic objects next to the staff
2195 (@code{side-position-interface}), but it also groups dynamic objects
2196 (@code{axis-group-interface}), is considered a dynamic sign
2197 itself (@code{dynamic-interface}), and is an object. It has the standard
2198 @code{grob-interface} with all the variables that come with it.
2200 For the moment we are interested in side positioning:
2202 side-position-interface
2204 Position a victim object (this one) next to other objects (the
2205 support). In this case, the direction signifies where to put the
2206 victim object relative to the support (left or right, up or down?)
2208 Between the object and its support (in this case the notes in the voice
2209 going down), there should be more space. This space is controlled by
2210 @code{padding}, so we increase it.
2212 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2215 This command is almost like the command for setting slur attachments,
2216 but subtly different in its details. Grob properties can be
2217 manipulated with two commands: @code{\override} extends the
2218 variables with a setting, and @code{\revert} releases this
2219 setting. This has a certain theoretical appeal: the operations are
2220 simple and symmetric. But for practical use, it can be cumbersome. The
2221 commands act like parentheses: you should carefully balance the use of
2222 @code{\override} and @code{\revert}. The @code{\set} command is more
2223 friendly: it first does a @code{\revert} followed by @code{\override}.
2227 Brahms uses music notation is a slightly unorthodox way. Ties
2228 usually happen only within one voice. In this piece, the composer
2229 gladly produces ties that jump voices. We deal with this by faking
2230 these ties: whenever we need such a tie, we insert a notehead in a
2231 different voice, and blank the stem. This is done in the following
2235 \property Voice.Stem \set #'transparent = ##t
2238 Blanking the stem should be done for only one object. One of the ways
2239 to achieve that, is by setting the property before a note. Reverting
2240 it afterwards is tedious, so for setting a property only once, we have
2241 the syntax @code{\once}: it reverts the property directly before
2242 proceeding to the next step in time.
2244 The @code{\once} keyword is added to @code{\property}.
2247 Finally, the last tie is forced up using @code{\tieUp}.
2251 Here's the complete ``fine tuned'' version, which includes all the
2252 modifications we discussed in this section:
2254 @lilypondfile[verbatim]{brahms-tweaked.ly}
2257 @node An orchestral score
2258 @section An orchestral score
2262 * Extracting an individual part::
2266 Our next two examples demonstrate one way to create an orchestral score
2267 in LilyPond. When typesetting a piece for several instruments, you'll
2268 want to create a full score (for the conductor) along with several
2269 individual parts (for the players).
2271 LilyPond is well suited for this task. We will declare the music for
2272 each instrument individually, giving the music of each instrument its
2273 own name. These pieces of music are then combined in different
2274 @code{\score} blocks to produce different combinations of instruments
2275 (for example, one @code{\score} block may only include the cello part;
2276 another @code{\score} block may be for all the strings, and yet another
2277 @code{\score} block may be for all parts together).
2279 This orchestral score example consists of three input files. In the
2280 first file, @file{os-music.ly}, we define the music for all
2281 instruments. This file will be used for producing the score and
2282 the separate parts, but the file doesn't produce any sheet music
2283 itself. Other files reference this file by doing @code{\include
2289 title = "Zo, goed lieverd?"
2290 subtitle = "How's, this babe?"
2299 Key = \notes \key as \major
2300 flautoI = \notes\relative c'' @{
2302 bes as bes as bes as bes as
2304 flautoII = \notes\relative c'' @{
2305 as8 bes as bes R1 d4 ~ d
2307 tromboI = \notes\relative c'' @{
2308 c4. c8 c8 c4. es4 r as, r
2310 tromboII = \notes\relative c'' @{
2311 as4. as8 as8 as4. R1*1/2 as4 es'
2313 timpani = \notes\relative c, @{
2314 \times 2/3 @{ f4 f f @}
2315 \times 4/5 @{ as8 as as as as @}
2318 corno = \notes\relative c' @{
2319 bes4 d f, bes d f, bes d
2323 We will not examine this example line by line, since you already know
2324 most of it. We'll examine a few lines which contain new elements.
2335 Declare setting to be used globally. The @code{\skip} command produces
2336 no output, but moves forward in time: in this case, the duration of a
2337 half note (@code{2}), and that four times (@code{*4}). This brings us
2338 to the end of the piece, and we can set the end bar. You can use @code{s}
2339 as a shortcut for @code{\skip} (the last line of this section would
2340 be @code{s2*4 \bar"|."}).
2344 Key = \notes \key as \major
2346 Declare the key signature of the piece and assign it to the identifier
2347 @var{Key}. Later on we'll use @code{\Key} for all staves except those
2348 for transposing instruments.
2350 @node The full score
2351 @subsection The full score
2354 The second file, @file{input/tutorial/os-score.ly}, reads the definitions of the first
2355 (@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
2361 \include "os-music.ly"
2362 \include "paper13.ly"
2364 #(ly:set-point-and-click 'line-column)
2365 #(define text-flat '((font-relative-size . -2)
2366 (music "accidentals--1")))
2371 \property Score.BarNumber \override #'padding = #3
2372 \context StaffGroup = woodwind <
2373 \context Staff = flauti <
2374 \property Staff.midiInstrument = #"flute"
2375 \property Staff.instrument = "2 Flauti"
2376 \property Staff.instr = "Fl."
2378 \context Voice=one @{ \voiceOne \flautoI @}
2379 \context Voice=two @{ \voiceTwo \flautoII @}
2382 \context StaffGroup = timpani <
2383 \context Staff = timpani <
2384 \property Staff.midiInstrument = #"timpani"
2385 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2386 \property Staff.instr = #"Timp."
2392 \context StaffGroup = brass <
2393 \context Staff = trombe <
2394 \property Staff.midiInstrument = #"trumpet"
2395 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2396 \property Staff.instr = #`(lines "Tbe." "(C)")
2398 \context Voice=one \partcombine Voice
2399 \context Thread=one \tromboI
2400 \context Thread=two \tromboII
2402 \context Staff = corni <
2403 \property Staff.midiInstrument = #"french horn"
2404 \property Staff.instrument = #`(lines "Corno"
2405 (columns "(E" ,text-flat ")"))
2406 \property Staff.instr = #`(lines "Cor."
2407 (columns "(E" ,text-flat ")"))
2408 \property Staff.transposing = #3
2409 \notes \key bes \major
2410 \context Voice=one \corno
2415 indent = 15 * \staffspace
2416 linewidth = 55 * \staffspace
2417 textheight = 90 * \staffspace
2419 \HaraKiriStaffContext
2428 @center @strong{Zo, goed lieverd?}
2430 @center How's, this babe?
2438 @lilypondfile{os-score.ly}
2442 \include "os-music.ly"
2444 First we need to include the music definitions we made in
2449 #(ly:set-point-and-click 'line-column)
2452 This piece of Scheme code executes the function
2453 @code{ly:set-point-and-click} with the argument
2454 @code{line-column}. Editing input files can be complicated if you're
2455 working with large files: if you're digitizing existing music, you have
2456 to synchronize the .ly file, the sheet music on your lap and the sheet
2457 music on the screen. The point-and-click mechanism makes it easy to
2458 find the origin of an error in the LY file: when you view the file with
2459 Xdvi and click on a note, your editor will jump to the spot where that
2460 note was entered. For more information, see @ref{Point and click}.
2465 #(define text-flat '((font-relative-size . -2)
2466 (music "accidentals--1")))
2469 To name the transposition of the french horn, we will need a piece of
2470 text with a flat sign. LilyPond has a mechanism for font selection and
2471 kerning called Scheme markup text (See @ref{Text markup}). The flat
2472 sign is taken from the music font, and its name is @code{accidentals--1}
2473 (The natural sign is called @code{accidentals-0}). The default font is
2474 too big for text, so we select a relative size of @code{-2}.
2481 All staves are simultaneous and use the same global settings.
2485 \property Score.BarNumber \override #'padding = #3
2487 LilyPond prints bar numbers at the start of each line, but
2488 unfortunately they end up a bit too close to the staff in this
2489 example. In LilyPond, a bar number is called @var{BarNumber}.
2490 BarNumber objects can be manipulated through their
2491 @var{side-position-interface}. One of the properties of a
2492 @var{side-position-interface} that can be tweaked is @var{padding}:
2493 the amount of extra space that is put between this and other objects.
2494 We set the padding to three staff spaces.
2496 You can find information on all these kind of properties in LilyPond's
2497 automatically generated documentation in
2499 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2500 or in @ref{Fine tuning a piece}.
2503 the online documentation or in the previous section of the tutorial.
2510 \context StaffGroup = woodwind <
2511 \context Staff = flauti <
2513 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2514 hold one or more @code{Staff}'s, and will print a big bracket at the
2515 left of the score. This starts a new staff group for the woodwind
2516 section (just the flutes in this case). Immediately after that, we
2517 start the staff for the two flutes, who also play simultaneously.
2521 \property Staff.midiInstrument = #"flute"
2523 Specify the instrument for MIDI output (see @ref{MIDI instrument
2528 \property Staff.instrument = "2 Flauti"
2529 \property Staff.instr = "Fl."
2531 This defines the instrument names to be printed in the
2532 margin. @code{instrument} specifies the name for the first line
2533 of the score, @code{instr} is used for the rest of the score.
2539 The flutes play in the default key.
2543 \context Voice=one @{ \voiceOne \flautoI @}
2544 \context Voice=two @{ \voiceTwo \flautoII @}
2546 Last come the actual flute parts. Remember that we're still in
2547 simultaneous mode. We name both voices differently, so that LilyPond
2548 will create two Voice contexts. The flute parts are simple, so
2549 we specify manually which voice is which: @code{\voiceOne} forces the
2550 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2558 Close the flutes staff and woodwind staff group.
2562 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2564 The timpani staff demonstrates a new piece of scheme markup, it sets two
2569 \context Voice=one \partcombine Voice
2570 \context Thread=one \tromboI
2571 \context Thread=two \tromboII
2573 You have seen the notation contexts Staff and Voice, but here's a new
2574 one: Thread. One or more Threads can be part of a Voice. Thread
2575 takes care of note heads and rests; Voice combine note heads onto a
2578 For the trumpets we use the automatic part combiner (see @ref{Automatic
2579 part combining}) to combine the two simultaneous trumpet parts onto the
2580 trumpet staff. Each trumpet gets its own Thread context, which must be
2581 named @code{one} and @code{two}). The part combiner makes these two
2582 threads share a Voice when they're similar, and splits the threads up
2583 when they're different.
2587 \property Staff.instrument = #`(lines "Corno"
2588 (columns "(E" ,text-flat ")"))
2590 The french horn (``Corno'') has the most complex scheme markup name, made
2591 up of two lines of text. The second line has three elements (columns) --
2592 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2593 and a final @code{")"}. Note that we use a backquote instead of an
2594 ordinary quote at the beginning of the Scheme expression to be able to
2595 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2599 \property Staff.transposing = #3
2601 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2602 transpose this staff by three steps.
2604 Note how we can choose different tunings for the text input, sheet music
2605 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2606 property @var{transposing}.
2610 \notes \key bes \major
2612 Since the horn is transposing, it's in a different key.
2616 indent = 15 * \staffspace
2617 linewidth = 55 * \staffspace
2619 We specify a big indent for the first line and a small linewidth for this
2624 Usually LilyPond's default setup of notation contexts (Thread,
2625 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2626 want a different type of Staff context.
2630 \HaraKiriStaffContext
2634 In orchestral scores it often happens that one instrument only has
2635 rests during one line of the score. @code{HaraKiriStaffContext} can
2636 be used as a regular @code{StaffContext} drop-in and will take care of
2637 the automatic removing of empty staves -- so if the strings are the
2638 only instruments playing for a line, LilyPond will only print the string
2639 parts for that line of the score. This reduces the number of page turns
2640 (and the number of dead trees!) required in a score.
2642 @node Extracting an individual part
2643 @subsection Extracting an individual part
2645 The third file, @file{os-flute-2.ly} also reads the definitions of the
2646 first (@file{os-music.ly}), and defines the @code{\score} block for the
2650 \include "os-music.ly"
2651 \include "paper16.ly"
2655 \property Score.skipBars = ##t
2656 \property Staff.midiInstrument = #"flute"
2662 instrument = "Flauto II"
2665 linewidth = 80 * \staffspace
2666 textheight = 200 * \staffspace
2674 @center @strong{Zo, goed lieverd?}
2676 @center How's, this babe?
2677 @center @emph{Flauto II}
2684 @lilypondfile{os-flute-2.ly}
2687 Because we separated the music definitions from the @code{\score}
2688 instantiations, we can easily define a second score with the music of
2689 the second flute. This is the part for the second flute player. Of
2690 course, we would make separate parts for all individual instruments if
2691 we were preparing the score for an orchestra.
2697 In this individual part the second flute has a whole staff for itself,
2698 so we don't want to force stem or tie directions.
2703 instrument = "Flauto II"
2706 The @code{\header} definitions were also read from @file{os-music.ly},
2707 but we need to set the instrument for this particular score.
2711 \property Score.skipBars = ##t
2713 In the conductor's full score, all bars with rests are printed, but for
2714 the individual parts, we want to print one multimeasure rest instead of
2715 many consecutive empty bars. LilyPond will do this if
2716 @code{Score.skipBars} is set to true (@code{##t}).
2719 @node Integrating text and music
2720 @section Integrating text and music
2723 @cindex La@TeX{}, music in
2724 @cindex HTML, music in
2725 @cindex Texinfo, music in
2727 Sometimes you might want to use music examples in a text that you are
2728 writing (for example a musicological treatise, a songbook, or (like us)
2729 the LilyPond manual). You can make such texts by hand, simply by
2730 importing a PostScript figure into your word processor. However,
2731 there is an automated procedure to reduce the amount of work.
2733 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2734 code. A script called @code{lilypond-book} will extract the music
2735 fragments, run LilyPond on them, and put back the resulting
2736 notation. This program is fully described in the chapter
2737 @ref{Integrating text and music with lilypond-book}. Here we show a
2738 small example. Since the example also contains explanatory text, we
2739 won't comment on the contents.
2742 \documentclass[a4paper]@{article@}
2745 In a lilypond-book document, you can freely mix music and text. For
2748 \score @{ \notes \relative c' @{
2749 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2752 Notice that the music line length matches the margin settings of the
2755 If you have no \verb+\score+ block in the fragment,
2756 \texttt@{lilypond-book@} will supply one:
2762 In the example you see here, two things happened: a
2763 \verb+\score+ block was added, and the line width was set to natural
2764 length. You can specify many more options using \LaTeX style options
2767 \begin[verbatim,11pt,singleline,
2768 fragment,relative,intertext="hi there!"]@{lilypond@}
2772 \texttt@{verbatim@} prints the LilyPond code in addition to the
2774 \texttt@{11pt@} selects the default music size,
2775 \texttt@{fragment@} adds a score block,
2776 \texttt@{relative@} uses relative mode for the fragment, and
2777 \texttt@{intertext@} specifies what to print between the
2778 \texttt@{verbatim@} code and the music.
2780 If you want to include large examples into the text, it may be more
2781 convenient to put the example in a separate file:
2783 \lilypondfile[printfilename]@{sammartini.ly@}
2785 The \texttt@{printfilename@} option adds the file name to the output.
2790 Under Unix, you can view the results as follows.
2794 $ lilypond-book --outdir=out/ lilbook.tex
2795 lilypond-book (GNU LilyPond) 1.6.1
2796 Reading `input/tutorial/lilbook.tex'
2797 Reading `input/tutorial/sammartini.ly'
2798 @var{lots of stuff deleted}
2799 Writing `out/lilbook.latex'
2801 $ latex lilbook.latex
2802 @var{lots of stuff deleted}
2806 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2807 and running latex creates a lot of temporary files, and you wouldn't want
2808 those to clutter up your working directory. Hence, we have them created
2809 in a separate subdirectory.
2811 The result looks more or less like this:
2815 In a lilypond-book document, you can freely mix music and text. For
2819 \notes \relative c' {
2820 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2827 Notice that the music line length matches the margin settings of the
2830 If you have no @code{\score} block in the fragment,
2831 @code{lilypond-book} will supply one:
2837 In the example you see here, a number of things happened: a
2838 @code{\score} block was added, and the line width was set to natural
2839 length. You can specify many more options using La@TeX{} style options
2842 @lilypond[verbatim,11pt,singleline,
2843 fragment,relative,intertext="hi there!"]
2847 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2848 the default music size, @code{fragment} adds a score block,
2849 @code{relative} uses relative mode for the fragment, and
2850 @code{intertext} specifies what to print between the
2851 @code{verbatim} code and the music.
2853 If you include large examples into the text, it may be more convenient
2854 to put the example in a separate file:
2856 @lilypondfile[printfilename,noquote]{sammartini.ly}
2858 The @code{printfilename} option adds the file name to the output.
2859 @node End of tutorial
2860 @section End of tutorial
2862 This is the end of the tutorial. If you read everything until this point
2863 (and understood everything!) then you're now an accomplished lilypond
2864 hacker. From here you should try fiddling with input files or making your
2865 own input files. Come back to the reference manual for more information
2868 Don't forget to check out the
2870 @uref{../../../../input/template/out-www/template.html,templates},
2871 @uref{../../../../input/test/out-www/test.html,examples} and
2872 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2875 templates, examples and feature tests.
2877 If you want to see real action LilyPond, head over to
2878 @uref{http://www.mutopiaproject.org}, which has many examples of
2879 classical music typeset with LilyPond.