4 @c * LilyPond Lilypond lilypond (sometimes: the program)
5 @c * more details about running lilypond; error messages,
6 @c compiling/viewing (emacs?)
7 @c * where to go from First steps+More basics?
13 <!--- @@WEB-TITLE@@=Tutorial --->
17 * First steps:: Music language of LilyPond
18 * Running LilyPond:: Printing music
21 * A melody with chords ::
23 * More movements :: Joining separate pieces of music
24 * A piano excerpt:: Piano music
25 * Fine tuning a piece::
26 * An orchestral score:: Conductor's score and individual parts
27 * Integrating text and music:: Integrating text and music
28 * End of tutorial:: The end
31 Operating lilypond is done through text files: To print a piece of
32 music, you enter the music in a file. When you run lilypond (normally
33 using the program @code{ly2dvi}) on that file, the program produces
34 another file which contains sheet music that you can print or view.
36 This tutorial starts with a small introduction to the LilyPond music
37 language. After this first contact, we will show you how to run
38 LilyPond to produce printed output; you should then be able to create
39 your first sheets of music. The tutorial continues with more and more
46 We start off by showing how very simple music is entered in LilyPond:
47 you get a note simply by typing its @htmlref{note name}, from @samp{a}
48 through @samp{g}. So if you enter
55 then the result looks like this:
58 @c \transpose c c' { c d e f g a b }
60 @c \property Score.timing = ##f
61 @lilypond[notime, relative=2]
65 We will continue with this format: First we show a snippet of input,
66 then the resulting output.
68 The length of a note is specified by adding a number, @samp{1} for a
69 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
76 \property Score.timing = ##f
77 \property Staff.autoBeaming = ##f
78 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
81 If you do not specify a @rglos{duration}, the previous one is used:
88 \property Score.timing = ##f
89 \transpose c c' { a a a2 a s16_" " }
92 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
93 @rglos{flat} (@texiflat{}) by adding @samp{es}. As you would expect,
94 a @rglos{double sharp} or @rglos{double flat} is made by adding
95 @samp{isis} or @samp{eses}:
102 \property Score.timing = ##f
103 \transpose c c' { cis1 ees fisis aeses s16_" " }
106 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
113 \property Score.timing = ##f
114 \transpose c c' { a2. a4 a8. a16 s16_" " }
117 The @rglos{meter} (or @rglos{time signature}) can be set with the
118 @code{\time} command:
126 @c a clef here may lead to confusion
128 \property Staff.Clef \set #'transparent = ##t
137 The @rglos{clef} can be set using the @code{\clef} command:
139 @c what is more common name treble or violin?
140 @c in Dutch, its violin.
141 @c in English its definitely treble.
150 \property Score.timing = ##f
161 When you enter these commands in a file, you must to enclose them in
162 @code{\notes @{@dots{}@}}. This lets LilyPond know that music (as
163 opposed to @rglos{lyrics}) follows:
173 Now the piece of music is almost ready to be printed. The final step is to
174 combine the music with a printing command.
176 The printing command is the so-called @code{\paper} block. Later on
177 you will see that the @code{\paper} block is used to customize
178 printing specifics. The music and the @code{\paper} block are combined by
179 enclosing them in @code{\score @{ ... @}}. This is what a full
180 LilyPond source file looks like:
203 linewidth = 55 * \staffspace
209 @node Running LilyPond
210 @section Running LilyPond
212 In the last section we explained what kind of things you could enter
213 in a lilypond file. In this section we explain how to run LilyPond
214 and how to view or print the output. If you have not used LilyPond
215 before, want to test your setup of LilyPond, or want to run an example
216 file yourself, read this section. The instructions that follow
217 are for running LilyPond on Unix-like systems. Some additional
218 instructions for running LilyPond on Windows are given at the end of
221 Begin by opening a terminal window and starting a text editor.
222 For example, you could open an xterm and execute @code{joe}. In your
223 text editor, enter the following input and save the file as
229 \notes @{ c'4 e' g' @}
236 @c now this is weird, running ly2dvi to run LilyPond
237 @c (therefore name change proposal)
239 LilyPond is the program that computes the sheet music. All other
240 things, such as adding titles, page breaking and other page layout,
241 are done by a small wrapper program called
242 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
243 then adds the titling and page layout instructions. To process
244 @file{test.ly} with @code{ly2dvi}, proceed as follows:
252 You will see the following on your screen:
257 Now processing: `/home/fred/ly/test.ly'
259 Interpreting music...[1]
260 @emph{ ... more interesting stuff ... }
261 PDF output to `test.pdf'...
262 DVI output to `test.dvi'...
266 @cindex Viewing music
269 The results of the ly2dvi run are two files, @file{test.dvi} and
270 @file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can
271 print or view. For example, viewing PDF can be done with ghostview.
272 If a version of ghostview is installed on your system, one of these
273 commands will produce a window with some music notation on your
284 If the music on your screen looks good, you can print it by clicking
285 File/Print inside ghostview.
287 The DVI file (@file{test.dvi}) contains the same sheet music in a
288 different format. DVI files are more easily processed by the computer,
289 so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
290 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons
291 activate magnifying glasses. Unfortunately, variable symbols (such as
292 beams and slurs) are not displayed in the magnifying glasses.
297 @cindex Printing output
301 If you are familiar with @TeX{}, be warned: do not use other DVI
302 drivers like @code{dvilj}. The @TeX{} coming out of LilyPond uses
303 embedded PostScript code and will not render correctly if you use
304 anything other than @code{dvips}.
310 @unnumberedsubsec Windows users
311 Windows users can start the terminal by clicking on the LilyPond or
312 Cygwin icon. You can use any text editor (such as NotePad, Emacs or
313 Vim) to edit the LilyPond file. If you install the Cygwin's
314 @code{XFree86} X11 window system, @code{tetex-x11} and
315 @code{ghostscript-x11} packages too, you can view the @code{dvi}
316 output doing @code{xdvi test.dvi} as described above. If you have
317 installed a PostScript/PDF viewer, such as @code{GSView} from
318 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
322 @code{gsview32 test.pdf}
325 You can also print from the command line by executing:
328 @code{gsview32 /s test.pdf}
335 To run LilyPond, input a text file, then run the command @code{ly2dvi} on
336 that file. The resulting files are either DVI or PostScript, and can
337 be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows)
338 respectively. The following table summarizes the constructs that were
339 discussed in the previous two sections.
341 @multitable @columnfractions .3 .3 .4
347 @item @code{1 2 8 16}
350 @lilypond[relative 1, notime]
351 \property Staff.autoBeaming = ##f
352 \property Staff.Clef = \turnOff
357 @tab augmentation dots
359 @lilypond[relative 1, notime]
360 \property Staff.Clef = \turnOff
364 @item @code{c d e f g a b }
367 @lilypond[relative 1, notime]
368 \property Staff.Clef = \turnOff
372 @item @code{\clef treble \clef bass }
382 @item @code{\time 3/4 \time 4/4 }
386 \property Staff.Clef \set #'transparent = ##t
399 We continue with the introduction of the remaining musical constructs.
400 Normal rests are entered just like notes with the name ``@code{r}'':
408 \property Score.timing = ##f
409 \property Staff.Clef = \turnOff
410 \property Staff.TimeSignature = \turnOff
417 @c Tim wants to move this quotes example just before the: quotes-do not-work
418 @c score, but we'd need to remove quotes from the other two (key and
421 @c better to have this just before the `octaves are bad' snipped
422 @c but we'd need to remove the ', from \key and tie
423 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
424 the note name, to lower a note one octave, add a ``low quote'' @code{,}
425 (a comma). Middle C is @code{c'}:
429 c'4 c'' c''' \clef bass c c,
433 \property Score.timing = ##f
434 \property Staff.TimeSignature = \turnOff
435 c'4 c'' c''' \clef bass c c,
440 A tie is created by adding a tilde ``@code{~}'' to the first note
443 @lilypond[fragment,verbatim]
448 A tie is different from a slur. A tie simply makes the first note
449 sound longer, and can only be used on pairs of notes with the same
450 pitch. Slurs indicate the articulations of notes, and can be used on
451 larger groups of notes. Slurs and ties are also nested in practice:
452 @lilypond[fragment, relative=1]
453 c2-~-( c8 fis fis4 ~ fis2 g2-)
457 The key signature is set with the command ``@code{\key}''. One
458 caution word of caution: you need to specify whether the key is
459 @code{\major} or @code{\minor}.
469 \property Staff.TimeSignature = \turnOff
478 @c bit on the long/complex/scary taste
479 @c cheating a bit: two lines makes for a friendlier look
480 This example shows notes, ties, octave marks, and rests in action.
489 r4 r8 d''8 cis''4 e''
491 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
504 r4 r8 d''8 cis''4 e''
506 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
509 \paper { linewidth = 50*\staffspace }
515 There are some interesting points to note in this example.
516 Accidentals (sharps and flats) do not have to be marked explicitly: you
517 just enter the note name, and LilyPond determines whether or not to
518 print an accidental. Bar lines and beams are drawn automatically.
519 LilyPond calculates line breaks for you; it does not matter where you
520 make new lines in the source file. Finally, the order of time, key and
521 clef changes is not relevant: lilypond will use standard notation
522 conventions for ordering these items.
524 The example also indicates that a piece of music written in a high
525 register needs lots of quotes. This makes the input less readable,
526 and is also a potential source of errors.
528 The solution is to use ``relative octave'' mode. In practice, this is
529 the most convenient way to copy existing music. To use relative mode,
530 add @code{\relative} before the piece of music. You must also give a
531 note from which relative starts, in this case @code{c''}. If you do not
532 use octavation quotes (ie do not add ' or , after a note), relative mode
533 chooses the note that is closest to the previous one. Since most music
534 has small intervals, you can write quite a lot in relative mode without
535 using octavation quotes.
536 @c do not use commas or quotes in this sentence
537 For example: @code{c f} goes up; @code{c g} goes down:
547 \property Score.timing = ##f
548 \property Staff.TimeSignature = \turnOff
557 @c needed better, maybe even redundant explanation
558 @c added another example below.
559 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
560 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
561 You can make larger intervals by adding octavation quotes. Note that
562 quotes or commas do not determine the absolute height of a note;
563 the height of a note is relative to the previous one.
564 @c do not use commas or quotes in this sentence
565 For example: @code{c f,} goes down; @code{f, f} are both the same;
566 @code{c' c} are the same; and @code{c g'} goes up:
576 \property Score.timing = ##f
577 \property Staff.TimeSignature = \turnOff
586 Here's an example of the difference between relative mode and
587 ``normal'' (non-relative) mode:
598 \property Score.timing = ##f
599 \property Staff.TimeSignature = \turnOff
615 \property Score.timing = ##f
616 \property Staff.TimeSignature = \turnOff
625 The following table summarizes the syntax in this section.
627 @c Is it possible to avoid page breaks directly after the
630 @multitable @columnfractions .3 .3 .4
639 @lilypond[relative 1, notime]
640 \property Staff.Clef = \turnOff
647 @lilypond[relative 1, notime]
648 \property Score.timing = ##f
649 \property Staff.autoBeaming = ##f
650 \property Staff.Clef = \turnOff
654 @item @code{\key es \major }
663 @item @var{note}@code{'}
666 @lilypond[relative 1, notime]
667 \property Score.timing = ##f
668 \property Staff.autoBeaming = ##f
669 \property Staff.Clef = \turnOff
673 @item @var{note}@code{,}
676 @lilypond[relative 1, notime]
677 \property Score.timing = ##f
678 \property Staff.autoBeaming = ##f
679 \property Staff.Clef = \turnOff
685 A slur is drawn across many notes, and indicates bound articulation
686 (legato). The starting note and ending note are marked with a
687 ``@code{(}'' and a ``@code{)}'' respectively:
690 @lilypond[fragment,relative 1, verbatim]
691 d4-( c16-)-( cis d e c cis d e-)-( d4-)
696 If you need two slurs at the same time (one for articulation, one for
697 phrasing), you can also make a phrasing slur with @code{\(} and
702 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
703 @c chromatic thing pasted in front. (admittedly the original does not
704 @c have a phrasing slur. The problem is that we do not want the slur
705 @c and the Phrasing slur to collide. We are trying to make a good
709 @lilypond[fragment,relative 1, verbatim]
710 a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
715 Beams are drawn automatically, but if you do not like the choices, you
716 can enter beams by hand. Mark the first note to be beamed with
717 @code{[} and the last one with @code{]}:
719 @lilypond[fragment,relative 1, verbatim]
720 a8-[ ais-] d-[ es r d-]
725 To print more than one staff, each piece of music that makes up a staff
726 is marked by adding @code{\context Staff} before it. These
727 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
731 @lilypond[fragment,verbatim]
733 \context Staff = staffA { \clef violin c'' }
734 \context Staff = staffB { \clef bass c }
739 In this example, @code{staffA} and @code{staffB} are names that are
740 given to the staves. It does not matter what names you give, as long
741 as each staff has a different name. If you give them the same name,
742 LilyPond will assume that you only want one staff, and will but both
743 pieces of music on the same staff.
748 We can now typeset a melody with two staves:
751 @lilypond[verbatim,singleline]
754 < \context Staff = staffA {
758 e2-( d4 c2 b4 a8-[ a-]
759 b-[ b-] g-[ g-] a2.-) }
761 \context Staff = staffB {
772 Notice that the time signature is specified in one melody staff only
773 (the top staff), but is printed on both. LilyPond knows that the time
774 signature should be the same for all staves.
778 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
780 @lilypond[verbatim,relative 1]
786 Dynamic signs are made by adding the markings to the note:
788 @lilypond[verbatim,relative 1]
794 Crescendi and decrescendi are started with the commands @code{\<} and
795 @code{\>}. The command @code{\!} finishes a crescendo on the note it
798 @lilypond[verbatim,relative 1]
799 c2-\< c2-\!-\ff c2-\> c2-\!
804 Chords can be made by surrounding notes with @code{<<} and @code{>>}:
806 @lilypond[relative 0, fragment,verbatim]
807 r4 <<c e g>>4 <<c f a>>8
813 You can combine beams and ties with chords. Beam and tie markings
814 must be placed outside the chord markers:
816 @lilypond[relative 0, fragment,verbatim]
817 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
822 When you want to combine chords with slurs and dynamics, technical
823 detail crops up: you have type these commands next to the notes, which
824 means that they have to be inside the @code{< >}. Do Not get confused
825 by the chord @code{< >} and the dynamic @code{\< \>}!
830 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
832 @lilypond[relative 0, fragment]
834 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
842 @multitable @columnfractions .3 .3 .4
852 @lilypond[fragment, relative 1]
853 \property Score.timing = ##f
854 \property Staff.TimeSignature = \turnOff
855 \property Staff.autoBeaming = ##f
856 \property Staff.Clef = \turnOff
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
885 @item @code{< \context Staff ... >}
889 < \context Staff = SA { c'1 }
890 \context Staff = SB { c'1 } >
897 @lilypond[fragment, relative 1]
898 \property Staff.TimeSignature = \turnOff
899 \property Staff.Clef = \turnOff
904 @item @code{-\mf -\sfz}
907 @lilypond[fragment, relative 1]
908 \property Staff.TimeSignature = \turnOff
909 \property Staff.Clef = \turnOff
917 @lilypond[fragment, relative 1]
918 \property Score.timing = ##f
919 \property Staff.TimeSignature = \turnOff
920 \property Staff.autoBeaming = ##f
921 \property Staff.Clef = \turnOff
928 @lilypond[fragment, relative 1]
929 \property Score.timing = ##f
930 \property Staff.TimeSignature = \turnOff
931 \property Staff.autoBeaming = ##f
932 \property Staff.Clef = \turnOff
940 @lilypond[fragment, relative 1]
946 Now you know the basic ingredients of a music file, so this is the
947 right moment to experiment and try your at hand typing some simple
950 When you are comfortable with the basics, you might want to read the
951 rest of this chapter. It continues in tutorial-style, but it is much
952 more in-depth, dealing with more advanced topics such as lyrics,
953 chords, orchestral scores and parts, fine tuning of output, polyphonic
954 music, and integrating text and music.
958 @node Printing lyrics
959 @section Printing lyrics
962 In this section we shall explain how to typeset the following
963 fragment of The Free Software Song:
965 @lilypond[singleline]
966 \score { \notes { \addlyrics
967 \notes \relative c' {
969 d'2 c4 b16-( a g a b a b c-) a2
970 b2 c4 b8-( a16 g a4-) g2 }
971 \context Lyrics \lyrics {
973 share the soft -- ware; }
975 \paper { linewidth = -1. }
981 @cindex @code{\lyrics}
984 Lyrics are a form of music. To get them printed, you must do two
985 things: indicate that lyrics are entered with @code{\lyrics}, and
986 indicate that this type of music must be interpreted as texts (and not
987 notes). This is done with @code{\context Lyrics}.
989 You can enter lyrics in a special input mode of LilyPond. This mode is
990 called Lyrics mode, and it is introduced by the keyword
991 @code{\lyrics}. In this mode you can enter lyrics, with punctuation
992 and accents without any hassle. Syllables are entered like notes, but
993 with pitches replaced by text. For example,
997 enters four syllables. Spaces can be introduced into a lyric either
998 by using quotes: @code{"He could" not} or by using an underscore
999 without quotes: @code{He_could not}.
1001 These are the lyrics for the free software song:
1006 share the soft -- ware; @}
1009 Extender lines are entered as @code{__}. This will create an
1010 extender, which is a line that extends over the entire duration of the
1011 lyric. This line will run all the way to the start of the next lyric,
1012 so you may want to shorten it by using a blank lyric (using @code{_}).
1015 You can use ordinary hyphens at the end of a syllable, i.e.
1019 but then the hyphen will be attached to the end of the first syllable.
1021 If you want them centered between syllables you can use the special
1022 `@code{-}@code{-}' lyric as a separate word between syllables. The
1023 hyphen will have variable length depending on the space between
1024 the syllables and it will be centered between the syllables.
1026 Normally the notes that you enter are transformed into note heads.
1027 Note heads alone make no sense. They need surrounding information: a
1028 key signature, a clef, staff lines, etc. They need @emph{context}.
1029 In LilyPond, these symbols are created by objects called
1030 `interpretation contexts'. Interpretation contexts exist for
1031 generating notation (`notation context') and for generating sound
1032 (`performance context'). These objects only exist while LilyPond is
1033 executing. For lyrics, the command
1037 must be used to interpret a set of syllables as lyrics.
1041 @cindex interpretation context
1042 @cindex notation context
1046 The melody and the lyrics can be combined with the @code{\addlyrics}:
1049 \notes \relative c' @dots{}
1050 \context Lyrics \lyrics @dots{}
1053 The lyrics are also music expressions, similar to notes. Each lyric
1054 syllable is put under a note of the melody. The complete file is
1058 \score @{ \notes @{ \addlyrics
1059 \notes \relative c' @{
1061 d'2 c4 b16 ( a g a b a b ) c a2
1062 b2 c4 b8 ( a16 g ) a4 g2 @}
1063 \context Lyrics \lyrics @{
1065 share the soft -- ware; @}
1067 \paper @{ linewidth = -1. @}
1073 @node A melody with chords
1074 @section A melody with chords
1076 In this section we show how to typeset a melody with chord
1077 accompaniment. This file is included in
1078 @inputfileref{input/tutorial,flowing.ly}.
1080 @lilypondfile[verbatim,intertext="the result looks like"]{flowing.ly}
1086 \include "paper16.ly"
1089 Smaller size (suitable for inclusion in a book).
1093 melody = \notes \relative c' @{
1096 The structure of the file will be the same as the previous one: a
1097 @code{\score} block with music in it. To keep things readable, we will
1098 give different names to the different parts of music, and use the names
1099 to construct the music within the score block.
1106 @cindex @code{\partial}
1108 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1114 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1115 c4 c8 d [es () d] c4 | d4 es8 d c4.
1120 @cindex manual beaming
1121 @cindex automatic beaming, turning off
1122 We use explicit beaming. Since this is a song, we turn automatic
1123 beams off and use explicit beaming where needed.
1130 This ends the definition of @code{melody}.
1139 @cindex identifier assignment
1140 @cindex syllables, entering
1141 This defines the lyrics, similar to what we have seen before.
1146 accompaniment =\chords @{
1150 @cindex mode, chords
1151 We will put chords over the music. To enter them, we use a special mode
1152 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1153 the names of the chords you want instead of listing the notes
1154 comprising the chord.
1161 There is no accompaniment during the anacrusis.
1170 @cindex chord modifier
1171 @cindex modifier, chord
1172 This is a c minor chord, lasting for a half note. Chords are entered using
1173 the tonic. Notes can be changed to create different chords. In this case,
1174 a lowered third is used (making a C major chord into a C minor chord).
1175 The code for this is @code{3-}.
1181 Similarly, @code{7} modifies (adds) a seventh, which is small by
1182 default to create the @code{f a c es} chord. Multiple modifiers must be
1190 Some modifiers have predefined names, e.g. @code{min} is the same as
1191 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1195 c2:min f:min7 g:7^3.5 c:min @}
1198 @cindex named modifier
1200 A named modifier @code{min} and a normal modifier @code{7} do not have
1201 to be separated by a dot. Tones from a chord are removed with chord
1202 subtractions. Subtractions are started with a caret, and they are
1203 also separated by dots. In this example, @code{g:7^3.5} produces a
1204 minor seventh (a G7 chord without the third or the fifth). The
1205 brace ends the sequential music.
1213 We assemble the music in the @code{\score} block. Melody, lyrics and
1214 accompaniment have to sound at the same time, so they should be
1215 @code{\simultaneous}.
1216 @cindex @code{\simultaneous}
1218 To print chords as chords names, they have to be interpreted as
1219 such. This is done with the following command: The following command
1220 explicitly creates an interpretation context of @code{ChordNames} type
1221 to interpret the music @code{\accompaniment}.
1224 \context ChordNames \accompaniment
1235 We place the melody on a staff.
1239 \property Staff.autoBeaming = ##f
1243 @cindex context variables
1244 @cindex setting context variables
1245 An interpretation context has variables that tune its behavior. These
1246 variables are also called @emph{properties}. The @code{autoBeaming}
1247 variable in a @code{Staff} controls whether 8th and shorter notes are
1248 beamed automatically. Setting the variable to @code{##f}, which is the
1249 boolean value @var{false}, turns it off.
1259 Finally, we put the melody on the current staff. Note that the
1260 @code{\property} directives and @code{\melody} are grouped in sequential
1261 music, so the property settings are done before the melody is
1267 \midi @{ \tempo 4=72@}
1270 MIDI (Musical Instrument Digital Interface) is a standard for
1271 connecting and recording digital instruments. A MIDI file is like a
1272 tape recording of a MIDI instrument. The @code{\midi} block makes the
1273 music go to a MIDI file, so you can listen to the music you entered.
1274 It is great for checking the music. Whenever you hear something
1275 weird, you probably hear a typing error.
1277 @code{\midi} is similar to @code{\paper @{ @}}, since it also
1278 specifies an output method. You can specify the tempo using the
1279 @code{\tempo} command, in this case the tempo of quarter notes is set
1280 to 72 beats per minute.
1284 \paper @{ linewidth = 10.0\cm @}
1287 We also want notation output. The linewidth is short so that the piece
1288 will be set in two lines.
1291 @section More stanzas
1296 If you have multiple stanzas printed underneath each other, the vertical
1297 groups of syllables should be aligned around punctuation. LilyPond can
1298 do this if you tell it which lyric lines belong to which melody.
1299 We show how you can do this by showing how you could print a frivolous
1300 fragment of a fictional Sesame Street duet.
1302 @lilypond[singleline,verbatim]
1305 \notes \relative c'' \context Voice = duet { \time 3/4
1307 \lyrics \context Lyrics <
1308 \context LyricsVoice = "duet-1" {
1309 \property LyricsVoice . stanza = "Bert"
1310 Hi, my name is bert. }
1311 \context LyricsVoice = "duet-2" {
1312 \property LyricsVoice . stanza = "Ernie"
1313 Ooooo, ch\'e -- ri, je t'aime. }
1318 To this end, give the Voice context an identity, and set the
1319 LyricsVoice to a name starting with that identity followed by a dash.
1320 In the following example, the Voice identity is @code{duet},
1322 \context Voice = duet @{
1327 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1329 \context LyricsVoice = "duet-1" @{
1330 Hi, my name is bert. @}
1331 \context LyricsVoice = "duet-2" @{
1332 Ooooo, ch\'e -- ri, je t'aime. @}
1334 The convention for naming @code{LyricsVoice} and @code{Voice} must
1335 also be used to get melismata on rests correct.
1338 We add the names of the singers. This can be done by setting
1339 @code{LyricsVoice.Stanza} (for the first system) and
1340 @code{LyricsVoice.stz} for the following systems. Note that you must
1341 surround dots with spaces in @code{\lyrics} mode.
1344 \property LyricsVoice . stanza = "Bert"
1346 \property LyricsVoice . stanza = "Ernie"
1350 @node More movements
1351 @section More movements
1353 The program @code{lilypond} only produces sheet music. Titles,
1354 subtitles, and the composer's name are created by a separate program,
1355 called use @code{ly2dvi}. @code{ly2dvi} creates the titles, then
1356 calls @code{lilypond} to format the sheet music. In this section, we
1357 show you how to create titles like this:
1359 @center @strong{Two miniatures}
1369 \paper { linewidth = -1.0 }
1381 \paper { linewidth = -1.0 }
1385 For example, consider the following file (@file{miniatures.ly})
1390 title = "Two miniatures"
1391 composer = "F. Bar Baz"
1392 tagline = "small is beautiful" @}
1394 \paper @{ linewidth = -1.0 @}
1398 Mental note: discuss Schenkerian analysis of these key pieces.
1403 \notes @{ c'4 d'4 @}
1409 \notes @{ d'4 c'4 @}
1417 The information for the global titling is in a so-called header block.
1418 The information in this block is not used by LilyPond, but it is
1419 passed into @code{ly2dvi}, which uses this information to print titles
1422 @cindex identifier assignment
1423 the @code{\header} block contains assignments. In each assignment, a
1424 variable is set to a value. The header block for this file looks like
1426 @cindex @code{\header}
1429 title = "Two miniatures"
1430 composer = "F. Bar Baz"
1431 tagline = "small is beautiful"
1435 When you process a file with ly2dvi, a signature line is printed at
1436 the bottom of the last page. Many people find the default (``Lily was
1437 here'' with a version number) too droll. If that is the case, you can
1438 change @code{tagline} in the @code{\header}, as shown above.
1440 @cindex Lily was here
1441 @cindex signature line
1450 A paper block at top level (i.e. not in a @code{\score} block) sets
1451 the default page layout. The following @code{\score} blocks do not
1452 have @code{\paper} sections so the settings of this block are used.
1454 The variable @code{linewidth} normally sets the length of the systems
1455 on the page. However, a negative value has a special meaning. If
1456 @code{linewidth} is less than 0, no line breaks are inserted into the
1457 score, and the spacing is set to natural length: a short phrase takes
1458 up little space, a longer phrase takes more space, all on the same line.
1463 Mental note: discuss Schenkerian analysis of these key pieces.
1468 Mental notes to yourself can be put into comments. There are two types
1469 of comments. Line comments are introduced by @code{%}, and block
1470 comments are delimited by @code{%@{} and @code{%@}}.
1475 \notes @{ c'4 d'4 @}
1478 In previous examples, most notes were specified in relative octaves
1479 (i.e. each note was put in the octave that is closest to its preceding
1480 note). This is convenient when copying existing music: you have to do
1481 less typing, and errors are easily spotted.
1483 There is also absolute octave specification, which you get when you do
1484 not include @code{\relative} in your input file. In this input mode,
1485 the middle C is denoted by @code{c'}. Going down, you get @code{c}
1486 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''}
1487 etc. Absolute octaves are convenient when you write LilyPond input
1488 directly, either by hand (i.e. composing) or by computer.
1495 The @code{\header} is normally at the top of the file, where it sets
1496 values for the rest of the file. If you want to typeset different
1497 pieces from one file (for example, if there are multiple movements, or
1498 if you are making an exercise book), you can put different
1499 @code{\score} blocks into the input file. @code{ly2dvi} will assemble
1500 all LilyPond output files into a one document. The contents of
1501 @code{\header} blocks specified within each score is used for the
1502 title of that movement.
1508 For example, the Opus number is put at the right, and the "piece" string
1509 will be at the left.
1516 title = "Two miniatures"
1517 composer = "F. Bar Baz"
1518 tagline = "small is beautiful" @}
1520 \paper @{ linewidth = -1.0 @}
1523 \notes @{ c'4 d'4 @}
1529 \notes @{ d'4 c'4 @}
1539 scoreA = \score @{ \deelA @}
1540 scoreB = \score @{ \deelA @}
1542 % \score @{ \scoreA @}
1543 \score @{ \scoreB @}
1551 Lilypond and its language are still under development, and
1552 occasionally details of the syntax are changed. The @code{version}
1553 fragment indicates which version of lilypond the input file was written
1554 for. When you compile this file, the version number will be checked
1555 and you will get a warning when the file is too old. This version
1556 number is also used by the @code{convert-ly} program (See
1557 @ref{Invoking convert-ly}), which can used to update the file to the
1558 latest lily version.
1561 @node A piano excerpt
1562 @section A piano excerpt
1564 Our eighth subject is a piece of piano music. The fragment in the
1565 input file is a piano reduction of the G major Sinfonia by Giovanni
1566 Battista Sammartini, composed around 1740. It's in the source
1567 package under the name @inputfileref{input/tutorial,sammartini.ly}.
1569 @lilypondfile[smallverbatim]{sammartini.ly}
1571 As you can see, this example features multiple voices on one staff. To
1572 make room for those voices, their notes should be stemmed in opposite
1579 viola = \notes \relative c' \context Voice = viola @{
1581 In this example you see multiple parts on a staff. Each part is
1582 associated with one notation context. This notation context handles
1583 stems and dynamics (among other things). The type name of this
1584 context is @code{Voice}. For each part we have to make sure that
1585 there is precisely one @code{Voice} context, so we give it a unique
1586 name (`@code{viola}').
1590 <<c g' c>>4-\arpeggio
1592 The delimiters @code{<<} and @code{>>} enclose the pitches of a chord.
1593 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line)
1606 Relative octaves work a little differently with chords. The starting
1607 point for the note following a chord is the first note of the chord. So
1608 the @code{g} gets an octave up quote: it is a fifth above the starting
1609 note of the previous chord (the central C).
1615 @code{s} is a spacer rest. It does not print anything, but it does have
1616 the duration of a rest. It is useful for filling up voices that
1617 temporarily do not play. In this case, the viola does not come until one
1618 and a half measure later.
1622 oboes = \notes \relative c'' \context Voice = oboe @{
1624 Now comes a part for two oboes. They play homophonically, so we
1625 print the notes as one voice that makes chords. Again, we insure that
1626 these notes are indeed processed by precisely one context with
1630 s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16
1633 The oboes should have stems up to keep them from interfering with
1634 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1638 \grace <<e g>>-( <<d f>>4-) <<c e>>2
1640 @cindex @code{\grace}
1643 @code{\grace} introduces grace notes. It takes one argument, in this
1644 case a chord. A slur is introduced starting from the @code{\grace}
1645 ending on the following chord.
1653 Tuplets are made with the @code{\times} keyword. It takes two
1654 arguments: a fraction and a piece of music. The duration of the piece
1655 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1656 of their notated duration, so in this case the fraction is 2/3.
1659 @{ <<d f>>8 <<e g>> <<f a>> @}
1661 The piece of music to be `tripletted' is sequential music containing
1668 At this point, the homophonic music splits into two rhythmically
1669 different parts. We cannot use a sequence of chords to enter this, so
1670 we make a "chord of sequences" to do it. We start with the upper
1671 voice, which continues with upward stems:
1674 @{ \times 2/3 @{ a8 g c @} c2 @}
1681 The easiest way to enter multiple voices is demonstrated
1682 here. Separate the components of the voice (single notes or entire
1683 sequences) with @code{\\} in a simultaneous music expression. The
1684 @code{\\} separators split first voice, second voice, third voice, and
1687 As far as relative mode is concerned, the previous note is the
1688 @code{c'''2} of the upper voice, so we have to go an octave down for
1696 This ends the two-part section.
1699 \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |
1704 The bass has a little hoom-pah melody to demonstrate parts switching
1705 between staves. Since it is repetitive, we use repeats:
1708 hoomPah = \repeat unfold 8
1710 @cindex unfolded @code{\repeat}
1711 The unfolded repeat prints the notes in its argument as if they were
1712 written out in full eight times.
1715 \notes \transpose c c' @{
1718 @cindex relative mode and transposing
1720 Transposing can be done with @code{\transpose}, which takes two arguments.
1721 The first specifies what central C should be transposed to. The second
1722 is the to-be-transposed music. As you can see, in this case, the
1723 transposition has no effect, as central C stays at central C.
1725 The purpose of this no-op is to protect it from being interpreted as
1726 relative notes. Relative mode can not be used together with
1727 transposition, so @code{\relative} will leave the contents of
1728 @code{\hoomPah} alone. We can use it without having to worry about
1729 getting the motive in a wrong octave. Conversely, if you want to
1730 transpose a fragment of music entered with @code{\relative}, then you
1731 should make sure that @code{\transpose} comes before @code{\relative}.
1734 @cindex staff switch, manual
1735 @cindex cross staff voice, manual
1736 @cindex @code{\translator}
1739 \translator Staff = down
1742 \translator Staff = up
1746 Voices can switch between staves. Here you see two staff switching
1747 commands. The first one moves to the lower staff, the second one to
1748 the lower one. If you set the stem directions explicitly
1749 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1750 can be beamed together (despite jumping between staffs).
1754 bassvoices = \notes \relative c' @{
1756 \autochange Staff \hoomPah \context Voice
1761 \translator Staff = down
1763 @cindex staff switch
1764 @cindex cross staff voice
1765 We want the remaining part of this melody on the lower staff, so we do a
1766 manual staff switch here.
1775 A special context is needed to get cross staff beaming right. This
1776 context is called @code{PianoStaff}.
1779 \context Staff = bottom < \time 2/2 \clef bass
1781 The bottom staff must have a different clef.
1786 To make some more room on the line, the first (in this case the only)
1787 line is not indented. The line still looks very cramped, but that is due
1788 to the page layout of this document.
1794 * font-size, multi-stanza.
1796 * Simple part combining in a Hymn
1800 @node Fine tuning a piece
1801 @section Fine tuning a piece
1803 In this section we show some ways to fine tune the final output of a
1804 piece. We do so using a single measure of a moderately complex piano
1805 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
1806 tuned and the untuned versions) are in @file{input/tutorial/}.
1808 The code for the untuned example shows us some new things.
1810 @lilypondfile[verbatim]{brahms-original.ly}
1820 Hairpin dynamics can be easily added to Lilypond scores. A crescendo
1821 is started with @code{\<} and ended with @code{\!}. A decrescendo is
1822 started with @code{\>} and ended with @code{\!}. Absolute dynamics
1823 can be entered using @code{\p}, @code{\mf}, etc.
1825 @cindex fingering instructions
1827 Fingering indications are entered with @code{-@var{N}}, where
1830 Now that we have the basic piece of music entered, we want to fine
1831 tune it so that we get something that resembles the original printed
1832 edition by Schott/Universal Edition:
1834 @lilypondfile{brahms-tweaked.ly}
1836 @cindex tuning graphical objects
1838 Fine tuning involves overriding the defaults of the printing system.
1839 We do this by setting variables which control how Lilypond prints
1840 symbols. Printed symbols are called graphical objects (often
1841 abbreviated to @emph{grob}). Each object is described by a bunch of
1842 settings. Every setting is a variable: it has a name and a value
1843 which you can change. These values determine the fonts, offsets,
1844 sub-routines to be called on the object, etc. The initial values of
1845 these settings are set in the Scheme file
1846 @file{scm/grob-description.scm}.
1848 @cindex slur attachments
1850 We start with the slur in the upper part, running from F sharp to A. In
1851 the printed edition, this slur runs from stem to stem; in our version,
1852 the slur begins at the note head of the F sharp. The following property
1853 setting forces all slurs to run from stem to stem (not from or to note
1857 \property Voice.Slur \set #'attachment = #'(stem . stem)
1860 More precisely, this command modifies the definition of the @code{Slur}
1861 object in the current @code{Voice}. The variable @code{attachment} is
1862 set to the pair of symbols @code{'(stem . stem)}.
1864 Although this fixes the slur, it is not very helpful for fine tuning in
1865 general: the lilypond back-end supports approximately 240 variables
1866 like @code{attachment}, each with their own meaning and own type
1867 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
1868 different types of graphical objects, that may be created in 14
1869 different context types besides Voice.
1871 @cindex internal documentation
1872 @cindex finding graphical objects
1873 @cindex graphical object descriptions
1875 The interesting information is how you can figure out which properties
1876 to tune for your own scores. To discover this, you must have a copy of
1877 the internals document. This is a set of HTML pages which should be
1878 included if you installed a binary distribution@footnote{You can also
1879 compile them by executing @code{make -C Documentation/user/
1880 out/lilypond-internals.html} in the source package.}. These HTML pages
1881 are also available on the web: go to the lilypond website, click
1882 ``Documentation: Index'' on the side bar, look in the ``Information for
1883 uses'' section, and click on ``Documentation of internals''.
1885 You might want to bookmark either the HTML files on your disk, or the one
1886 on the web (the HTML on your hard drive will load much faster than the
1887 ones on the web!). One word of caution: the internals documentation is
1888 generated from the definitions that lily uses. For that reason, it is
1889 strongly tied to the version of LilyPond that you use. Before you
1890 proceed, please make sure that you are using the documentation that
1891 corresponds to the version of LilyPond that you are using.
1893 @c TODO: the quote is incorrect, although that shouldn't be a big
1894 @c problem for the reader.
1895 Suppose that you wanted to tune the behavior of the slur. The first
1896 step is to get some general information on slurs in lilypond. Turn to
1897 the index, and look up ``slur''. The section on slurs says
1899 The grob for this object is @internalsref{Slur}, generally in
1900 @internalsref{Voice} context.
1903 So the graphical object for this object is called @code{Slur}, and
1904 slurs are created in the @code{Voice} context. If you are reading
1905 this tutorial in the HTML version, then you can simply click Slur,
1906 otherwise, you should look it up the internal documentation: click
1907 ``grob overview'' and select ``slur'' (the list is alphabetical).
1909 Now you get a list of all the properties that the slur object
1910 supports, along with their default values. Among the properties we
1911 find the @code{attachment} property with its default setting.
1912 The property documentation explains that the following setting will
1913 produce the desired effect:
1915 \property Voice.Slur \set #'attachment = #'(stem . stem)
1918 If you ran the previous example, you have unknowingly already used
1919 this kind of command. The @inputfileref{ly,property-init.ly} contains the
1920 definition of @code{\stemUp}:
1922 stemUp = \property Voice.Stem \set #'direction = #1
1925 @c this is a long section, and adding an extra space here helps to
1926 @c break it into smaller subsections and thus is easier to understand.
1929 Next we want to move the fingering `3'. In the printed edition it is
1930 not above the stem, but a little lower and slightly left of the stem.
1931 From the user manual we find that the associated graphical object is
1932 called @code{Fingering}, but how do we know if we should use
1933 @code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe
1934 bet, but you can also deduce this information from the internals
1935 documentation: if you visit the documentation of @code{Fingering}, you
1938 Fingering grobs are created by: Fingering_engraver
1941 Clicking @code{Fingering_engraver} will show you the documentation of
1942 the module responsible for interpreting the fingering instructions and
1943 translating them to a @code{Fingering} object. Such a module is called
1944 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
1947 Fingering_engraver is part of contexts: Voice and TabVoice
1949 so tuning the settings for Fingering should be done using either
1951 \property Voice.Fingering \set @dots{}
1955 \property TabVoice.Fingering \set @dots{}
1958 Since the @code{TabVoice} is only used for tab notation, we see that
1959 the first guess @code{Voice} was indeed correct.
1961 @cindex setting object properties
1962 @cindex @code{extra-offset}
1964 For shifting the fingering, we use the property @code{extra-offset}.
1965 The following command manually adds an offset to the object. We move
1966 it a little to the left, and 1.8 staff space downwards.
1968 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
1970 The @code{extra-offset} is a low-level feature: it moves around
1971 objects in the printout; the formatting engine is completely oblivious
1972 to these offsets. The unit of these offsets are staff-spaces. The
1973 first number controls left-right movement; a positive number will move
1974 the object to the right. The second number controls up-down movement;
1975 a positive number will move it higher.
1977 @cindex reverting object properties
1978 @cindex undoing object properties
1980 We only want to offset a single object, so after the F-sharp we must
1981 undo the setting. The technical term is to revert the property.
1983 \property Voice.Fingering \revert #'extra-offset
1986 @cindex property types
1987 @cindex translator properties
1988 @cindex grob properties
1989 @cindex music properties
1992 There are three different types of variables in LilyPond, something
1993 which can be confusing at first (and for some people it stays confusing
1994 :). Variables such as @code{extra-offset} and @code{attachment} are
1995 called grob properties. They are not the same as translator properties,
1996 like @code{autoBeaming}. Finally, music expressions are internally
1997 stored using properties (so-called music properties). You will encounter
1998 music properties if you run Scheme functions on music using @code{\apply}.
2000 The second fingering instruction should be moved up a little to avoid
2001 a collision with the slur. This could be achieved with
2002 @code{extra-offset}, but in this case, a simpler mechanism also
2003 works. We insert an empty text between the 5 and the note. The empty
2004 text pushes the fingering instruction away:
2006 a-)^" "^\markup @{ \finger "5" @}
2009 A fingering instruction, which would be entered as @code{^5}, is put
2010 as close to the notes as possible, closer than the space entered to
2011 push away the 5. Hence, the 5 is entered as a normal text, formatting
2012 of fingering instructions.
2016 Normally one would specify all dynamics in the same voice, so that
2017 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
2018 in this case, we do not want the decrescendo to be aligned with the
2019 piano sign. We achieve this by putting the dynamic markings in different
2020 voices. The crescendo should be above the upper staff. This can be
2021 forced by using the precooked command
2026 However, if you do that the decrescendo will be too close to the
2027 upper voice and collide with the stems. Looking at the manual for
2028 dynamics, we notice that ``Vertical positioning of these symbols is
2029 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2030 to the documentation of @code{DynamicLineSpanner}, we find that
2031 @code{DynamicLineSpanner} supports several so-called `interfaces'. This
2032 object not only puts dynamic objects next to the staff
2033 (@code{side-position-interface}), but it also groups dynamic objects
2034 (@code{axis-group-interface}), is considered a dynamic sign
2035 itself (@code{dynamic-interface}), and is an object. It has the standard
2036 @code{grob-interface} with all the variables that come with it.
2038 For the moment we are interested in side positioning:
2040 side-position-interface
2042 Position a victim object (this one) next to other objects (the
2043 support). In this case, the direction signifies where to put the
2044 victim object relative to the support (left or right, up or down?)
2046 Between the object and its support (in this case the notes in the voice
2047 going down), there should be more space. This space is controlled by
2048 @code{padding}, so we increase it.
2050 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2053 This command is almost like the command for setting slur attachments,
2054 but subtly different in its details. Grob properties can be
2055 manipulated with two commands: @code{\override} extends the
2056 variables with a setting, and @code{\revert} releases this
2057 setting. This has a certain theoretical appeal: the operations are
2058 simple and symmetric. But for practical use, it can be cumbersome. The
2059 commands act like parentheses: you should carefully balance the use of
2060 @code{\override} and @code{\revert}. The @code{\set} command is more
2061 friendly: it first does a @code{\revert} followed by @code{\override}.
2065 Brahms uses music notation is a slightly unorthodox way. Ties
2066 usually happen only within one voice. In this piece, the composer
2067 gladly produces ties that jump voices. We deal with this by faking
2068 these ties: whenever we need such a tie, we insert a notehead in a
2069 different voice, and blank the stem. This is done in the following
2072 @cindex transparent objects
2073 @cindex removing objects
2074 @cindex invisible objects
2076 \property Voice.Stem \set #'transparent = ##t
2079 Blanking the stem should be done for only one object. One of the ways
2080 to achieve that, is by setting the property before a note. Reverting
2081 it afterwards is tedious, so for setting a property only once, we have
2082 the syntax @code{\once}: it reverts the property directly before
2083 proceeding to the next step in time.
2085 The @code{\once} keyword is added to @code{\property}.
2088 Finally, the last tie is forced up using @code{\tieUp}.
2092 Here's the complete ``fine tuned'' version, which includes all the
2093 modifications we discussed in this section:
2095 @lilypondfile[verbatim]{brahms-tweaked.ly}
2098 @node An orchestral score
2099 @section An orchestral score
2103 * Extracting an individual part::
2107 Our next two examples demonstrate one way to create an orchestral score
2108 in LilyPond. When typesetting a piece for several instruments, you'll
2109 want to create a full score (for the conductor) along with several
2110 individual parts (for the players).
2112 LilyPond is well suited for this task. We will declare the music for
2113 each instrument individually, giving the music of each instrument its
2114 own name. These pieces of music are then combined in different
2115 @code{\score} blocks to produce different combinations of instruments
2116 (for example, one @code{\score} block may only include the cello part;
2117 another @code{\score} block may be for all the strings, and yet another
2118 @code{\score} block may be for all parts together).
2120 This orchestral score example consists of three input files. In the
2121 first file, @file{os-music.ly}, we define the music for all
2122 instruments. This file will be used for producing the score and
2123 the separate parts, but the file does not produce any sheet music
2124 itself. Other files reference this file by doing @code{\include
2130 title = "Zo, goed lieverd?"
2131 subtitle = "How's, this babe?"
2140 Key = \notes \key as \major
2141 flautoI = \notes\relative c'' @{
2143 bes as bes as bes as bes as
2145 flautoII = \notes\relative c'' @{
2146 as8 bes as bes R1 d4 ~ d
2148 tromboI = \notes\relative c'' @{
2149 c4. c8 c8 c4. es4 r as, r
2151 tromboII = \notes\relative c'' @{
2152 as4. as8 as8 as4. R1*1/2 as4 es'
2154 timpani = \notes\relative c, @{
2155 \times 2/3 @{ f4 f f @}
2156 \times 4/5 @{ as8 as as as as @}
2159 corno = \notes\relative c' @{
2160 bes4 d f, bes d f, bes d
2164 We will not examine this example line by line, since you already know
2165 most of it. We'll examine a few lines which contain new elements.
2176 Declare setting to be used globally. The @code{\skip} command produces
2177 no output, but moves forward in time: in this case, the duration of a
2178 half note (@code{2}), and that four times (@code{*4}). This brings us
2179 to the end of the piece, and we can set the end bar. You can use @code{s}
2180 as a shortcut for @code{\skip} (the last line of this section would
2181 be @code{s2*4 \bar"|."}).
2185 Key = \notes \key as \major
2187 Declare the key signature of the piece and assign it to the identifier
2188 @var{Key}. Later on we will use @code{\Key} for all staves except those
2189 for transposing instruments.
2191 @node The full score
2192 @subsection The full score
2195 The second file, @inputfileref{input/tutorial,os-score.ly}, reads the
2196 definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and
2197 defines the @code{\score} block for the full conductor's score.
2202 \include "os-music.ly"
2203 \include "paper13.ly"
2205 #(ly:set-point-and-click 'line-column)
2206 textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
2210 \property Score.BarNumber \override #'padding = #3
2211 \context StaffGroup = woodwind <
2212 \context Staff = flauti <
2213 \property Staff.midiInstrument = #"flute"
2214 \property Staff.instrument = "2 Flauti"
2215 \property Staff.instr = "Fl."
2217 \context Voice=one @{ \voiceOne \flautoI @}
2218 \context Voice=two @{ \voiceTwo \flautoII @}
2221 \context StaffGroup = timpani <
2222 \context Staff = timpani <
2223 \property Staff.midiInstrument = #"timpani"
2224 \property Staff.instrument = \markup @{ \column << "Timpani" "(C-G)" >> @}
2225 \property Staff.instr = #"Timp."
2231 \context StaffGroup = brass <
2232 \context Staff = trombe <
2233 \property Staff.midiInstrument = #"trumpet"
2234 \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
2235 \property Staff.instr = \markup@{ \column << "Tbe." "(C)">> @}
2237 \context Voice=one \partcombine Voice
2238 \context Thread=one \tromboI
2239 \context Thread=two \tromboII
2241 \context Staff = corni <
2242 \property Staff.midiInstrument = #"french horn"
2243 \property Staff.instrument
2244 = \markup @{ \column << "Corno" @{ "(E" \textFlat ")" @} >> @}
2245 \property Staff.instr =
2246 \markup @{ \column << "Cor." @{ "(E" \textFlat ")" @} >> @}
2247 \property Staff.transposing = #3
2248 \notes \key bes \major
2249 \context Voice=one \corno
2254 indent = 15 * \staffspace
2255 linewidth = 60 * \staffspace
2256 textheight = 90 * \staffspace
2259 \consists "Multi_measure_rest_engraver"
2262 \HaraKiriStaffContext
2263 \remove "Multi_measure_rest_engraver"
2272 @center @strong{Zo, goed lieverd?}
2274 @center How's, this babe?
2282 @lilypondfile{os-score.ly}
2286 \include "os-music.ly"
2288 First we need to include the music definitions we made in
2293 #(ly:set-point-and-click 'line-column)
2296 This piece of Scheme code executes the function
2297 @code{ly:set-point-and-click} with the argument
2298 @code{line-column}. Editing input files can be complicated if you are
2299 working with large files: if you are digitizing existing music, you have
2300 to synchronize the .ly file, the sheet music on your lap and the sheet
2301 music on the screen. The point-and-click mechanism makes it easy to
2302 find the origin of an error in the LY file: when you view the file with
2303 Xdvi and click on a note, your editor will jump to the spot where that
2304 note was entered. For more information, see @ref{Point and click}.
2309 #(define text-flat '((font-relative-size . -2)
2310 (music "accidentals--1")))
2313 To name the transposition of the french horn, we will need a piece of
2314 text with a flat sign. LilyPond has a mechanism for font selection and
2315 kerning called Scheme markup text (See @ref{Text markup}). The flat
2316 sign is taken from the music font, and its name is @code{accidentals--1}
2317 (The natural sign is called @code{accidentals-0}). The default font is
2318 too big for text, so we select a relative size of @code{-2}.
2325 All staves are simultaneous and use the same global settings.
2329 \property Score.BarNumber \override #'padding = #3
2331 LilyPond prints bar numbers at the start of each line, but
2332 unfortunately they end up a bit too close to the staff in this
2333 example. In LilyPond, a bar number is called @var{BarNumber}.
2334 BarNumber objects can be manipulated through their
2335 @var{side-position-interface}. One of the properties of a
2336 @var{side-position-interface} that can be tweaked is @var{padding}:
2337 the amount of extra space that is put between this and other objects.
2338 We set the padding to three staff spaces.
2340 You can find information on all these kind of properties in LilyPond's
2341 automatically generated documentation in
2343 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2344 or in @ref{Fine tuning a piece}.
2347 the online documentation or in the previous section of the tutorial.
2354 \context StaffGroup = woodwind <
2355 \context Staff = flauti <
2357 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2358 hold one or more @code{Staff}'s, and will print a big bracket at the
2359 left of the score. This starts a new staff group for the woodwind
2360 section (just the flutes in this case). Immediately after that, we
2361 start the staff for the two flutes, who also play simultaneously.
2365 \property Staff.midiInstrument = #"flute"
2367 Specify the instrument for MIDI output (see @ref{MIDI instrument
2372 \property Staff.instrument = "2 Flauti"
2373 \property Staff.instr = "Fl."
2375 This defines the instrument names to be printed in the
2376 margin. @code{instrument} specifies the name for the first line
2377 of the score, @code{instr} is used for the rest of the score.
2383 The flutes play in the default key.
2387 \context Voice=one @{ \voiceOne \flautoI @}
2388 \context Voice=two @{ \voiceTwo \flautoII @}
2390 Last come the actual flute parts. Remember that we are still in
2391 simultaneous mode. We name both voices differently, so that LilyPond
2392 will create two Voice contexts. The flute parts are simple, so
2393 we specify manually which voice is which: @code{\voiceOne} forces the
2394 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2402 Close the flutes staff and woodwind staff group.
2406 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2408 The timpani staff demonstrates a new piece of scheme markup, it sets two
2413 \context Voice=one \partcombine Voice
2414 \context Thread=one \tromboI
2415 \context Thread=two \tromboII
2417 You have seen the notation contexts Staff and Voice, but here's a new
2418 one: Thread. One or more Threads can be part of a Voice. Thread
2419 takes care of note heads and rests; Voice combine note heads onto a
2422 For the trumpets we use the automatic part combiner (see @ref{Automatic
2423 part combining}) to combine the two simultaneous trumpet parts onto the
2424 trumpet staff. Each trumpet gets its own Thread context, which must be
2425 named @code{one} and @code{two}). The part combiner makes these two
2426 threads share a Voice when they are similar, and splits the threads up
2427 when they are different.
2431 \property Staff.instrument = #`(lines "Corno"
2432 (columns "(E" ,text-flat ")"))
2434 The french horn (``Corno'') has the most complex scheme markup name, made
2435 up of two lines of text. The second line has three elements (columns) --
2436 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2437 and a final @code{")"}. Note that we use a backquote instead of an
2438 ordinary quote at the beginning of the Scheme expression to be able to
2439 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2443 \property Staff.transposing = #3
2445 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2446 transpose this staff by three steps.
2448 Note how we can choose different tunings for the text input, sheet music
2449 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2450 property @var{transposing}.
2454 \notes \key bes \major
2456 Since the horn is transposing, it is in a different key.
2460 indent = 15 * \staffspace
2461 linewidth = 55 * \staffspace
2463 We specify a big indent for the first line and a small linewidth for this
2468 Usually LilyPond's default setup of notation contexts (Thread,
2469 Voice, Staff, Staffgroup, Score) is just fine. But in this case we
2470 want a different type of Staff context.
2474 \HaraKiriStaffContext
2478 In orchestral scores it often happens that one instrument only has
2479 rests during one line of the score. @code{HaraKiriStaffContext} can
2480 be used as a regular @code{StaffContext} drop-in and will take care of
2481 the automatic removing of empty staves -- so if the strings are the
2482 only instruments playing for a line, LilyPond will only print the string
2483 parts for that line of the score. This reduces the number of page turns
2484 (and the number of dead trees!) required in a score.
2486 @node Extracting an individual part
2487 @subsection Extracting an individual part
2489 The third file, @file{os-flute-2.ly} also reads the definitions of the
2490 first (@file{os-music.ly}), and defines the @code{\score} block for the
2494 \include "os-music.ly"
2495 \include "paper16.ly"
2499 \property Score.skipBars = ##t
2500 \property Staff.midiInstrument = #"flute"
2506 instrument = "Flauto II"
2509 linewidth = 80 * \staffspace
2510 textheight = 200 * \staffspace
2518 @center @strong{Zo, goed lieverd?}
2520 @center How's, this babe?
2521 @center @emph{Flauto II}
2528 @lilypondfile{os-flute-2.ly}
2531 Because we separated the music definitions from the @code{\score}
2532 instantiations, we can easily define a second score with the music of
2533 the second flute. This is the part for the second flute player. Of
2534 course, we would make separate parts for all individual instruments if
2535 we were preparing the score for an orchestra.
2541 In this individual part the second flute has a whole staff for itself,
2542 so we do not want to force stem or tie directions.
2547 instrument = "Flauto II"
2550 The @code{\header} definitions were also read from @file{os-music.ly},
2551 but we need to set the instrument for this particular score.
2555 \property Score.skipBars = ##t
2557 In the conductor's full score, all bars with rests are printed, but for
2558 the individual parts, we want to print one multimeasure rest instead of
2559 many consecutive empty bars. LilyPond will do this if
2560 @code{Score.skipBars} is set to true (@code{##t}).
2563 @node Integrating text and music
2564 @section Integrating text and music
2567 @cindex La@TeX{}, music in
2568 @cindex HTML, music in
2569 @cindex Texinfo, music in
2571 Sometimes you might want to use music examples in a text that you are
2572 writing (for example a musicological treatise, a songbook, or (like us)
2573 the LilyPond manual). You can make such texts by hand, simply by
2574 importing a PostScript figure into your word processor. However,
2575 there is an automated procedure to reduce the amount of work.
2577 If you use HTML, La@TeX{}, or texinfo, you can mix text and LilyPond
2578 code. A script called @code{lilypond-book} will extract the music
2579 fragments, run LilyPond on them, and put back the resulting
2580 notation. This program is fully described in the chapter
2581 @ref{Integrating text and music with lilypond-book}. Here we show a
2582 small example. Since the example also contains explanatory text, we
2583 will not comment on the contents.
2586 \documentclass[a4paper]@{article@}
2589 In a lilypond-book document, you can freely mix music and text. For
2592 \score @{ \notes \relative c' @{
2593 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2596 Notice that the music line length matches the margin settings of the
2599 If you have no \verb+\score+ block in the fragment,
2600 \texttt@{lilypond-book@} will supply one:
2606 In the example you see here, two things happened: a
2607 \verb+\score+ block was added, and the line width was set to natural
2608 length. You can specify many more options using \LaTeX style options
2611 \begin[verbatim,11pt,singleline,
2612 fragment,relative,intertext="hi there!"]@{lilypond@}
2616 \texttt@{verbatim@} prints the LilyPond code in addition to the
2618 \texttt@{11pt@} selects the default music size,
2619 \texttt@{fragment@} adds a score block,
2620 \texttt@{relative@} uses relative mode for the fragment, and
2621 \texttt@{intertext@} specifies what to print between the
2622 \texttt@{verbatim@} code and the music.
2624 If you want to include large examples into the text, it may be more
2625 convenient to put the example in a separate file:
2627 \lilypondfile[printfilename]@{sammartini.ly@}
2629 The \texttt@{printfilename@} option adds the file name to the output.
2634 Under Unix, you can view the results as follows.
2638 $ lilypond-book --outdir=out/ lilbook.tex
2639 lilypond-book (GNU LilyPond) 1.6.1
2640 Reading `input/tutorial/lilbook.tex'
2641 Reading `input/tutorial/sammartini.ly'
2642 @var{lots of stuff deleted}
2643 Writing `out/lilbook.latex'
2645 $ latex lilbook.latex
2646 @var{lots of stuff deleted}
2650 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2651 and running latex creates a lot of temporary files, and you would not want
2652 those to clutter up your working directory. Hence, we have them created
2653 in a separate subdirectory.
2655 The result looks more or less like this:
2659 In a lilypond-book document, you can freely mix music and text. For
2663 \notes \relative c' {
2664 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2671 Notice that the music line length matches the margin settings of the
2674 If you have no @code{\score} block in the fragment,
2675 @code{lilypond-book} will supply one:
2681 In the example you see here, a number of things happened: a
2682 @code{\score} block was added, and the line width was set to natural
2683 length. You can specify many more options using La@TeX{} style options
2686 @lilypond[verbatim,11pt,singleline,
2687 fragment,relative,intertext="hi there!"]
2691 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2692 the default music size, @code{fragment} adds a score block,
2693 @code{relative} uses relative mode for the fragment, and
2694 @code{intertext} specifies what to print between the
2695 @code{verbatim} code and the music.
2697 If you include large examples into the text, it may be more convenient
2698 to put the example in a separate file:
2700 @lilypondfile[printfilename]{sammartini.ly}
2702 The @code{printfilename} option adds the file name to the output.
2703 @node End of tutorial
2704 @section End of tutorial
2706 This is the end of the tutorial. If you read everything until this point
2707 (and understood everything!) then you are now an accomplished lilypond
2708 hacker. From here you should try fiddling with input files or making your
2709 own input files. Come back to the reference manual for more information
2712 Do not forget to check out the
2714 @uref{../../../../input/template/out-www/template.html,templates},
2715 @uref{../../../../input/test/out-www/test.html,examples} and
2716 @uref{../../../../input/regression/out-www/regression.html,feature tests}.
2719 templates, examples and feature tests.
2721 If you want to see real action LilyPond, head over to
2722 @uref{http://www.mutopiaproject.org}, which has many examples of
2723 classical music typeset with LilyPond.