3 @c TODO: LilyPond LilyPond LilyPond
9 <!--- @@WEB-TITLE@@=Tutorial --->
13 * First steps:: Music language of LilyPond
14 * Running LilyPond:: Printing music
17 * A melody with chords ::
19 * More movements :: Joining separate pieces of music
20 * A piano excerpt:: Piano music
21 * Fine tuning a piece::
22 * An orchestral score:: Conductor's score and individual parts
23 * Integrating text and music:: Integrating text and music
24 * End of tutorial:: The end
27 Operating lilypond is done through text files: to print a piece of
28 music, you enter the music in a file. When you run lilypond (normally
29 using the program @code{ly2dvi}) on that file, the program produces
30 another file which contains sheet music that you can print or view.
32 This tutorial starts with a small introduction to the LilyPond music
33 language. After this first contact, we will show you how to run
34 LilyPond to produce printed output; you should then be able to create
35 your first sheets of music. The tutorial continues with more and more
41 We start off by showing how very simple music is entered in
42 LilyPond: you get a note simply by typing its note name, from
43 @code{a} through @code{g}. So if you enter
49 then the result looks like this:
52 \property Score.timing = ##f
53 \property Staff.TimeSignature = \turnOff
54 \transpose c'' { c d e f g a b }
59 We will continue with this format: first we show a snippet of input,
60 then the resulting output.
62 The length of a note is specified by adding a number, ``@code{1}'' for a
63 whole note, ``@code{2}'' for a half note, and so on:
70 @c missing clef seems to raise more questions than actual pitch of notes,
71 @c as these are snippets anyway
73 \property Score.timing = ##f
74 \property Staff.TimeSignature = \turnOff
75 \property Staff.autoBeaming = ##f
76 %\property Staff.Clef = \turnOff
77 \transpose c'' { a1 a2 a4 a16 a32 }
83 If you don't specify a duration, the previous one is used:
89 @c missing clef seems to raise more questions than actual pitch of notes,
90 @c as these are snippets anyway
92 \property Score.timing = ##f
93 \property Staff.TimeSignature = \turnOff
94 %\property Staff.Clef = \turnOff
95 \transpose c'' { a a a2 a }
101 A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
102 (@texiflat{}) by adding ``@code{es}''. As you would expect, a
103 double-sharp or double-flat is made by adding ``@code{isis}'' or
112 \property Score.timing = ##f
113 \property Staff.TimeSignature = \turnOff
114 \transpose c'' { cis1 ees fisis aeses }
120 Add a dot ``@code{.}'' after the duration to get a dotted note:
126 @c missing clef seems to raise more questions than actual pitch of notes,
127 @c as these are snippets anyway
129 \property Score.timing = ##f
130 \property Staff.TimeSignature \set #'transparent = ##t
131 %\property Staff.Clef = \turnOff
132 \transpose c'' { a2. a4 a8. a16 }
138 The meter (or time signature) can be set with the @code{\time} command:
147 @c a clef here may lead to confusion
149 \property Staff.Clef \set #'transparent = ##t
160 The clef can be set using the ``@code{\clef}'' command:
162 @c what is more common name treble or violin?
163 @c in Dutch, its violin.
164 @c in English its definitely treble.
174 \property Score.timing = ##f
175 \property Staff.TimeSignature = \turnOff
188 @c From these commands and notes, a piece of music can be formed. A piece
189 @c of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
191 When you enter these commands in a file, you must to enclose them in
192 ``@code{\notes @{ .. @}}''. This lets LilyPond know that music (and
193 not lyrics, for example) follows:
207 Now the piece of music is almost ready to be printed. The final step is to
208 combine the music with a printing command.
210 The printing command is the so-called ``@code{\paper}'' block. Later on
211 you will see that the @code{\paper} block is used to customize
212 printing specifics. The music and the @code{\paper} block are combined by
213 enclosing them in ``@code{\score @{ ... @}}''. This is what a full
214 LilyPond source file looks like:
237 \paper { linewidth = 60 * \staffspace }
244 @node Running LilyPond
245 @section Running LilyPond
247 In the last section we explained what kind of things you could enter
248 in a lilypond file. In this section we explain how to run LilyPond
249 and how view or print the output. If you have not used LilyPond
250 before, want to test your setup of LilyPond, or want to run an example
251 file yourself, read this section. The instructions that follow
252 are for running LilyPond on Unix-like systems. Some additional
253 instructions for running LilyPond on Windows are given at the end of
256 Begin by opening a terminal window and starting a text editor.
257 For example, you could open an xterm and execute @code{joe}. In your
258 text editor, enter the following input and save the file as
264 \notes @{ c'4 e' g' @}
271 @c now this is weird, running ly2dvi to run LilyPond
272 @c (therefore name change proposal)
274 LilyPond is the program that computes the sheet music. All other
275 things, such as adding titles, page breaking and other page layout,
276 are done by a small wrapper program called
277 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
278 then adds the titling and page layout instructions. To process
279 @file{test.ly} with @code{ly2dvi}, proceed as follows:
287 You will see the following on your screen:
292 Now processing: `/home/fred/ly/test.ly'
294 Interpreting music...[1]
295 @emph{ ... more interesting stuff ... }
296 PS output to `test.ps'...
297 DVI output to `test.dvi'...
301 @cindex Viewing music
304 The results of the ly2dvi run are two files, @file{test.dvi} and
305 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
306 You can view the PS file using the program ghostview. If a version of
307 ghostview is installed on your system, one of these commands will
308 produce a window with some music notation on your screen:
318 If the music on your screen looks good, you can print it by clicking
319 File/Print inside ghostview.
321 The DVI file (@file{test.dvi}) contains the same sheet music in a
322 different format. DVI files are more easily processed by the computer,
323 so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
324 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse buttons
325 activate magnifying glasses. Unfortunately, variable symbols (such as
326 beams and slurs) are not displayed in the magnifying glasses.
328 If your DVI viewer does not have a "Print" button, you can print the
329 file by executing @code{lpr test.ps}.
331 @c volgende alinea schrappen?
333 If your system does not support printing PostScript files, then you
334 can install GhostScript, a PostScript emulator. Refer to
335 GhostScript's website at @uref{http://www.ghostscript.com}.
339 @cindex Printing output
343 A final option is to use the popular PDF format. You can get a PDF
344 file by running @code{ly2dvi --pdf test.ly}. With @code{--pdf}
345 you will get DVI, PS and PDF files. Viewers for PS files also
346 accept PDF files, but there are also many other applications for
349 If you are familiar with @TeX{}, be warned: do not use other
350 DVI drivers like @code{dvilj}. The @TeX{} coming out of LilyPond
351 uses embedded PostScript code and will not render correctly if
352 you use anything other than @code{dvips}.
358 @unnumberedsubsec Windows users
359 Windows users can start the terminal by clicking on the LilyPond or
360 Cygwin icon. You can use any text editor (such as NotePad, Emacs or
361 Vim) to edit the LilyPond file. If you install the Cygwin's
362 @code{XFree86} X11 window system, @code{tetex-x11} and
363 @code{ghostscript-x11} packages too, you can view the @code{dvi}
364 output doing @code{xdvi test.dvi} as described above. If you have
365 installed a PostScript/PDF viewer, such as @code{GSView} from
366 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PS file can be done
370 @code{gsview32 test.ps}
373 You can also print from the command line by executing:
376 @code{gsview32 /s test.ps}
383 To run LilyPond, input a text file, then run the command @code{ly2dvi} on
384 that file. The resulting files are either DVI or PostScript, and can
385 be viewed with @code{xdvi} (unix) and ghostview (unix and windows)
386 respectively. The following table summarizes the constructs that were
387 discussed in the previous two sections.
389 @multitable @columnfractions .3 .3 .4
395 @item @code{1 2 8 16}
398 @lilypond[fragment, relative 1]
399 \property Staff.TimeSignature = \turnOff
400 \property Staff.autoBeaming = ##f
401 \property Staff.Clef = \turnOff
406 @tab augmentation dots
408 @lilypond[fragment, relative 1]
409 \property Staff.TimeSignature = \turnOff
410 \property Staff.Clef = \turnOff
414 @item @code{c d e f g a b }
417 @lilypond[fragment, relative 1]
418 \property Staff.TimeSignature = \turnOff
419 \property Staff.Clef = \turnOff
423 @item @code{\clef treble \clef bass }
427 \property Staff.TimeSignature \set #'transparent = ##t
434 @item @code{\time 3/4 \time 4/4 }
438 \property Staff.Clef \set #'transparent = ##t
451 We continue with the introduction of the remaining musical constructs.
452 Normal rests are entered just like notes with the name ``@code{r}'':
460 \property Score.timing = ##f
461 \property Staff.Clef = \turnOff
462 \property Staff.TimeSignature = \turnOff
469 @c Tim wants to move this quotes example just before the: quotes-don't-work
470 @c score, but we'd need to remove quotes from the other two (key and
473 @c better to have this just before the `octaves are bad' snipped
474 @c but we'd need to remove the ', from \key and tie
475 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
476 the note name, to lower a note one octave, add a ``low quote'' @code{,}
477 (a comma). Middle C is @code{c'}:
481 c'4 c'' c''' \clef bass c c,
485 \property Score.timing = ##f
486 \property Staff.TimeSignature = \turnOff
487 c'4 c'' c''' \clef bass c c,
492 A tie is created by entering a tilde ``@code{~}'' between the notes to
493 be tied. A tie between two notes means that the second note must not be
494 played separately; it just makes the first note sound longer:
497 @lilypond[fragment,verbatim]
503 The key signature is set with the command ``@code{\key}'':
513 \property Staff.TimeSignature = \turnOff
522 @c bit on the long/complex/scary taste
523 @c cheating a bit: two lines makes for a friendlier look
524 This example shows notes, ties, octave marks, and rests in action.
533 r4 r8 d''8 cis''4 e''
535 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
548 r4 r8 d''8 cis''4 e''
550 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
553 \paper { linewidth = 50*\staffspace }
559 There are some interesting points to note in this example.
560 Accidentals (sharps and flats) don't have to be marked explicitly: you
561 just enter the note name, and LilyPond determines whether or not to
562 print an accidental. Bar lines and beams are drawn automatically.
563 LilyPond calculates line breaks for you; it doesn't matter where you
564 make new lines in the source file. Finally, the order of time, key and
565 clef changes is not relevant: lilypond will use standard notation
566 conventions for ordering these items.
568 The example also indicates that a piece of music written in a high
569 register needs lots of quotes. This makes the input less readable,
570 and is also a potential source of errors.
572 The solution is to use ``relative octave'' mode. In practice, this is
573 the most convenient way to copy existing music. To use relative mode,
574 add @code{\relative} before the piece of music. You must also give a
575 note from which relative starts, in this case @code{c''}. If you don't
576 use octavation quotes (ie don't add ' or , after a note), relative mode
577 chooses the note that is closest to the previous one. Since most music
578 has small intervals, you can write quite a lot in relative mode without
579 using octavation quotes.
580 @c don't use commas or quotes in this sentence
581 For example: @code{c f} goes up; @code{c g} goes down:
591 \property Score.timing = ##f
592 \property Staff.TimeSignature = \turnOff
601 @c needed better, maybe even redundant explanation
602 @c added another example below.
603 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
604 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
605 You can make larger intervals by adding octavation quotes. Note that
606 quotes or commas do not determine the absolute height of a note;
607 the height of a note is relative to the previous one.
608 @c don't use commas or quotes in this sentence
609 For example: @code{c f,} goes down; @code{f, f} are both the same;
610 @code{c' c} are the same; and @code{c g'} goes up:
620 \property Score.timing = ##f
621 \property Staff.TimeSignature = \turnOff
630 Here's an example of the difference between relative mode and
631 ``normal'' (non-relative) mode:
642 \property Score.timing = ##f
643 \property Staff.TimeSignature = \turnOff
659 \property Score.timing = ##f
660 \property Staff.TimeSignature = \turnOff
669 The following table summarizes the syntax learned so far in this section.
671 @c Is it possible to avoid page breaks directly after the
674 @multitable @columnfractions .3 .3 .4
683 @lilypond[fragment, relative 1]
684 \property Staff.TimeSignature = \turnOff
685 \property Staff.Clef = \turnOff
693 @lilypond[fragment, relative 1]
694 \property Score.timing = ##f
695 \property Staff.TimeSignature = \turnOff
696 \property Staff.autoBeaming = ##f
697 \property Staff.Clef = \turnOff
702 @item @code{\key es \major }
706 \property Staff.TimeSignature \set #'transparent = ##t
712 @item @var{note}@code{'}
715 @lilypond[fragment, relative 1]
716 \property Score.timing = ##f
717 \property Staff.TimeSignature = \turnOff
718 \property Staff.autoBeaming = ##f
719 \property Staff.Clef = \turnOff
723 @item @var{note}@code{,}
726 @lilypond[fragment, relative 1]
727 \property Score.timing = ##f
728 \property Staff.TimeSignature = \turnOff
729 \property Staff.autoBeaming = ##f
730 \property Staff.Clef = \turnOff
736 A slur is drawn across many notes, and indicates bound articulation
737 (legato). The starting note and ending note are marked with a
738 ``@code{(}'' and a ``@code{)}'' respectively:
741 @lilypond[fragment,relative 1, verbatim]
742 d4( )c16( cis d e c cis d )e( )d4
747 If you need two slurs at the same time (one for articulation, one for
748 phrasing), you can also make a phrasing slur with @code{\(} and
753 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
754 @c chromatic thing pasted in front. (admittedly the original doesn't
755 @c have a phrasing slur. The problem is that we don't want the slur
756 @c and the Phrasing slur to collide. We're trying to make a good
760 @lilypond[fragment,relative 1, verbatim]
761 a8(\( ais b ) c cis2 b'2 a4 cis, \) c
766 Beams are drawn automatically, but if you don't like the choices, you
767 can enter beams by hand. Surround the notes to be grouped with @code{[}
770 @lilypond[fragment,relative 1, verbatim]
776 To print more than one staff, each piece of music that makes up a staff
777 is marked by adding @code{\context Staff} before it. These
778 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
782 @lilypond[fragment,verbatim]
784 \context Staff = staffA { \clef violin c'' }
785 \context Staff = staffB { \clef bass c }
790 In this example, @code{staffA} and @code{staffB} are names that are
791 given to the staves. It doesn't matter what names you give, as long
792 as each staff has a different name.
796 We can now typeset a melody with two staves:
799 @lilypond[verbatim,singleline]
802 < \context Staff = staffA {
805 \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
807 \context Staff = staffB {
818 Notice that the time signature is specified in one melody staff only
819 (the top staff), but is printed on both. LilyPond knows that the time
820 signature should be the same for all staves.
824 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
826 @lilypond[verbatim,relative 1]
832 Dynamic signs are made by adding the markings to the note:
834 @lilypond[verbatim,relative 1]
840 Crescendi and decrescendi are started with the commands @code{\<} and
841 @code{\>}. The command @code{\!} finishes a crescendo on the following
844 @lilypond[verbatim,relative 1]
845 c2\< \!c2-\ff \>c2 \!c2
850 Chords can be made by surrounding notes with @code{<} and @code{>}:
852 @lilypond[relative 0, fragment,verbatim]
860 @c hmm, te losjes, iig
861 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
862 happens at the same time, like in chords, or (like in the two-staff
863 example above) in a bunch of stacked staves.
866 You can combine beams and ties with chords. Beam and tie markings
867 must be placed outside the chord markers:
869 @lilypond[relative 0, fragment,verbatim]
870 r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
874 When you want to combine chords with slurs and dynamics, technical
875 detail crops up: you have type these commands next to the notes, which
876 means that they have to be inside the @code{< >}. Don't get confused
877 by the chord @code{< >} and the dynamic @code{\< \>}!
882 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
884 @lilypond[relative 0, fragment]
886 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
891 @c this example is a bit too strongly worded -- there's nothing wrong
892 @c with starting a piece with a chord; you just have to be careful when
893 @c you do so. I've rephrased this example below.
894 @c There is one golden rule that you should keep in mind when writing
897 @c @strong{DO NOT START A PIECE WITH A CHORD}
899 @c Of course, it is a allowed, but the result might not be what you expect:
901 @c rephrased "don't start with a chord"
902 There is one caution when using chords: if you use a chord at the very
903 beginning of the piece, LilyPond might not understand what you want:
906 @lilypond[verbatim,singleline]
907 \score { \notes <c'2 e'2> }
912 If you have a piece that begins with a chord, you must explicitly
913 state that the notes of the chord are to be put on the same staff, in
914 the same voice. This is done by specifying @code{\context Staff} or
915 @code{\context Voice} for the notes:
918 @lilypond[verbatim,singleline]
919 \score { \notes \context Voice <c'2 e'2> }
927 @multitable @columnfractions .3 .3 .4
937 @lilypond[fragment, relative 1]
938 \property Score.timing = ##f
939 \property Staff.TimeSignature = \turnOff
940 \property Staff.autoBeaming = ##f
941 \property Staff.Clef = \turnOff
949 @lilypond[fragment, relative 1]
950 \property Score.timing = ##f
951 \property Staff.TimeSignature = \turnOff
952 \property Staff.autoBeaming = ##f
953 \property Staff.Clef = \turnOff
961 @lilypond[fragment, relative 1]
962 \property Score.timing = ##f
963 \property Staff.TimeSignature = \turnOff
964 \property Staff.autoBeaming = ##f
965 \property Staff.Clef = \turnOff
970 @item @code{< \context Staff ... >}
974 < \context Staff = SA { c'1 }
975 \context Staff = SB { c'1 } >
982 @lilypond[fragment, relative 1]
983 \property Staff.TimeSignature = \turnOff
984 \property Staff.Clef = \turnOff
989 @item @code{-\mf -\sfz}
992 @lilypond[fragment, relative 1]
993 \property Staff.TimeSignature = \turnOff
994 \property Staff.Clef = \turnOff
1002 @lilypond[fragment, relative 1]
1003 \property Score.timing = ##f
1004 \property Staff.TimeSignature = \turnOff
1005 \property Staff.autoBeaming = ##f
1006 \property Staff.Clef = \turnOff
1013 @lilypond[fragment, relative 1]
1014 \property Score.timing = ##f
1015 \property Staff.TimeSignature = \turnOff
1016 \property Staff.autoBeaming = ##f
1017 \property Staff.Clef = \turnOff
1025 @lilypond[fragment, relative 1]
1026 \context Voice <c e>
1031 Now you know the basic ingredients of a music file, so this is the right
1032 moment to try your at hand at doing it yourself: try typing some
1033 simple examples, and experiment a little.
1035 When you're comfortable with the basics, you might want to read
1036 the rest of this chapter. It continues in tutorial-style, but it
1037 is much more in-depth, dealing with more advanced topics such as
1038 lyrics, chords, orchestral scores and parts, fine tuning of output,
1039 polyphonic music, and integrating text and music.
1045 @node Printing lyrics
1046 @section Printing lyrics
1049 In this section we shall explain how to typeset the following
1050 fragment of The Free Software Song:
1052 @lilypond[singleline]
1053 \score { \notes { \addlyrics
1054 \notes \relative c' {
1056 d'2 c4 b16 ( a g a b a b ) c a2
1057 b2 c4 b8 ( a16 g ) a4 g2 }
1058 \context Lyrics \lyrics {
1060 share the soft -- ware; }
1062 \paper { linewidth = -1. }
1068 @cindex @code{\lyrics}
1071 To print lyrics, you must enter them and then instruct lilypond to
1073 You can enter lyrics in a special input mode of LilyPond. This mode is
1074 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1075 The purpose of this mode is that you can enter lyrics as plain text,
1076 punctuation, and accents without any hassle.
1078 Syllables are entered like notes, but with pitches replaced by text. For
1079 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1080 the hyphen has no special meaning for lyrics, and does not introduce
1083 Spaces can be introduced into a lyric either by using quotes:
1084 @code{"He could" not} or by using an underscore without quotes:
1085 @code{He_could not}. All unquoted underscores are converted to
1088 These are the lyrics for the free software song:
1093 share the soft -- ware; @}
1096 As you can see, extender lines are entered as @code{__}. This will
1097 create an extender, which is a line that extends over the entire
1098 duration of the lyric. This line will run all the way to the start
1099 of the next lyric, so you may want to shorten it by using a blank
1100 lyric (using @code{_}).
1103 You can use ordinary hyphens at the end of a syllable, i.e.
1107 but then the hyphen will be attached to the end of the first syllable.
1109 If you want them centered between syllables you can use the special
1110 `@code{-}@code{-}' lyric as a separate word between syllables. The
1111 hyphen will have variable length depending on the space between
1112 the syllables and it will be centered between the syllables.
1114 Normally the notes that you enter are transformed into note heads.
1115 Note heads alone make no sense, so they need surrounding information: a
1116 key signature, a clef, staff lines, etc. They need @emph{context}. In
1117 LilyPond, these symbols are created by objects called `interpretation
1118 contexts'. Interpretation contexts exist for generating notation
1119 (`notation context') and for generating sound (`performance
1120 context'). These objects only exist while LilyPond is executing.
1122 When LilyPond interprets music, it will create a Staff context.
1123 We don't want that default here, because we want lyric. The
1128 explicitly creates an interpretation context of
1129 @code{Lyrics} type to interpret the song text that we entered.
1131 The melody of the song doesn't offer anything new:
1133 \notes \relative c' @{
1135 d'2 c4 b16 ( a g a b a b ) c a2
1136 b2 c4 b8 ( a16 g ) a4 g2 @}
1139 Both can be combined with the @code{\addlyrics}:
1142 \notes \relative c' @dots{}
1143 \context Lyrics \lyrics @dots{}
1146 The lyrics are also music expressions, similar to notes. Each syllable
1147 of the lyrics is put under a note of the melody.
1148 The complete file is listed here:
1151 \score @{ \notes @{ \addlyrics
1152 \notes \relative c' @{
1154 d'2 c4 b16 ( a g a b a b ) c a2
1155 b2 c4 b8 ( a16 g ) a4 g2 @}
1156 \context Lyrics \lyrics @{
1158 share the soft -- ware; @}
1160 \paper @{ linewidth = -1. @}
1166 @node A melody with chords
1167 @section A melody with chords
1169 In this section we show how to typeset a melody with chord
1170 accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
1173 \include "paper16.ly"
1174 melody = \notes \relative c' @{
1178 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1179 c4 c8 d [es () d] c4 | d4 es8 d c4.
1183 accompaniment =\chords @{
1185 c2:3- f:3-.7 d:min es4 c8:min r8
1186 c2:min f:min7 g:7^3.5 c:min @}
1191 \context ChordNames \accompaniment
1192 \context Staff = mel @{
1197 \midi @{ \tempo 4=72 @}
1198 \paper @{ linewidth = 10.0\cm @}
1203 The result would look this.
1206 \include "paper16.ly"
1207 melody = \notes \relative c' {
1211 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1212 c4 c8 d [es () d] c4 | d4 es8 d c4.
1216 accompaniment =\chords {
1218 c2:3- f:3-.7 d:min es4 c8:min r8
1219 c2:min f:min7 g:7^3.5 c:min }
1224 \context ChordNames \accompaniment
1226 \context Staff = mel {
1227 \property Staff.autoBeaming = ##f
1231 \midi { \tempo 4=72 }
1232 \paper { linewidth = 10.0\cm }
1236 We will dissect this file line by line.
1241 \include "paper16.ly"
1244 Smaller size (suitable for inclusion in a book).
1248 melody = \notes \relative c' @{
1251 The structure of the file will be the same as the previous one: a
1252 @code{\score} block with music in it. To keep things readable, we will
1253 give different names to the different parts of music, and use the names
1254 to construct the music within the score block.
1261 @cindex @code{\partial}
1263 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1269 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1270 c4 c8 d [es () d] c4 | d4 es8 d c4.
1275 @cindex manual beaming
1276 @cindex automatic beaming, turning off
1277 We use explicit beaming. Since this is a song, we turn automatic
1278 beams off and use explicit beaming where needed.
1285 This ends the definition of @code{melody}.
1294 @cindex identifier assignment
1295 @cindex syllables, entering
1296 This defines the lyrics, similar to what we have seen before.
1301 accompaniment =\chords @{
1305 @cindex mode, chords
1306 We'll put chords over the music. To enter them, we use a special mode
1307 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1308 the names of the chords you want instead of listing the notes
1309 comprising the chord.
1316 There is no accompaniment during the anacrusis.
1325 @cindex chord modifier
1326 @cindex modifier, chord
1327 This is a c minor chord, lasting for a half note. Chords are entered using
1328 the tonic. Notes can be changed to create different chords. In this case,
1329 a lowered third is used (making a C major chord into a C minor chord).
1330 The code for this is @code{3-}.
1336 Similarly, @code{7} modifies (adds) a seventh, which is small by
1337 default to create the @code{f a c es} chord. Multiple modifiers must be
1345 Some modifiers have predefined names, e.g. @code{min} is the same as
1346 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1350 c2:min f:min7 g:7^3.5 c:min @}
1353 @cindex named modifier
1355 A named modifier @code{min} and a normal modifier @code{7} do not have
1356 to be separated by a dot. Tones from a chord are removed with chord
1357 subtractions. Subtractions are started with a caret, and they are
1358 also separated by dots. In this example, @code{g:7^3.5} produces a
1359 minor seventh (a G7 chord without the third or the fifth). The
1360 brace ends the sequential music.
1368 We assemble the music in the @code{\score} block. Melody, lyrics and
1369 accompaniment have to sound at the same time, so they should be
1370 @code{\simultaneous}.
1371 @cindex @code{\simultaneous}
1378 Chord mode generates notes grouped in @code{\simultaneous} music. If
1379 you remove the comment sign, you can see the chords in normal
1380 notation: they will be printed as note heads on a separate
1381 staff. To print them as chords names, they have to be interpreted as
1382 being chords, not notes. This is done with the following command:
1386 \context ChordNames \accompaniment
1390 @cindex interpretation context
1391 @cindex notation context
1394 Normally the notes that you enter are transformed into note heads.
1395 Note heads alone make no sense, so they need surrounding information: a key
1396 signature, a clef, staff lines, etc. They need @emph{context}. In
1397 LilyPond, these symbols are created by objects called `interpretation
1398 contexts'. Interpretation contexts exist for generating notation
1399 (`notation context') and for generating sound (`performance
1400 context'). These objects only exist while LilyPond is executing.
1402 When LilyPond interprets music, it will create a Staff context. If
1403 the @code{%} sign in the previous line were removed, you could see
1404 that mechanism in action.
1406 We don't want that default here, because we want chord names. The
1407 command above explicitly creates an interpretation context of
1408 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1413 \context Staff = mel @{
1417 We place the melody on a staff called @code{mel}. We give it a name to
1418 differentiate it from the one that would contain note heads for the
1419 chords, if you would remove the comment before the ``note heads''
1420 version of the accompaniment. By giving this staff a name, it is
1421 forced to be different.
1425 \property Staff.autoBeaming = ##f
1429 @cindex context variables
1430 @cindex setting context variables
1431 An interpretation context has variables, called properties, that tune
1432 its behavior. One of the variables is @code{autoBeaming}. Setting
1433 this @code{Staff}'s property to @code{##f}, which is the boolean value
1434 @var{false}, turns the automatic beaming mechanism off for the current
1445 Finally, we put the melody on the current staff. Note that the
1446 @code{\property} directives and @code{\melody} are grouped in sequential
1447 music, so the property settings are done before the melody is
1453 \midi @{ \tempo 4=72@}
1456 MIDI (Musical Instrument Digital Interface) is a standard for
1457 connecting and recording digital instruments. So a MIDI file is like a
1458 tape recording of an instrument. The @code{\midi} block makes the
1459 music go to a MIDI file, so you can listen to the music you entered. It
1460 is great for checking the music. Whenever you hear something weird, you
1461 probably hear a typing error.
1463 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1464 also specifies an output method. You can specify the tempo using the
1465 @code{\tempo} command, in this case the tempo of quarter notes is set to
1466 72 beats per minute.
1470 \paper @{ linewidth = 10.0\cm @}
1473 We also want notation output. The linewidth is short so that the piece
1474 will be set in two lines.
1477 @section More stanzas
1482 If you have multiple stanzas printed underneath each other, the vertical
1483 groups of syllables should be aligned around punctuation. LilyPond can
1484 do this if you tell it which lyric lines belong to which melody.
1485 We show how you can do this by showing how you could print a frivolous
1486 fragment of a fictional Sesame Street duet.
1488 @lilypond[singleline,verbatim]
1491 \notes \relative c'' \context Voice = duet { \time 3/4
1493 \lyrics \context Lyrics <
1494 \context LyricsVoice = "duet-1" {
1495 \property LyricsVoice . stanza = "Bert"
1496 Hi, my name is bert. }
1497 \context LyricsVoice = "duet-2" {
1498 \property LyricsVoice . stanza = "Ernie"
1499 Ooooo, ch\'e -- ri, je t'aime. }
1504 To this end, give the Voice context an identity, and set the
1505 LyricsVoice to a name starting with that identity followed by a dash.
1506 In the following example, the Voice identity is @code{duet},
1508 \context Voice = duet @{
1513 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1515 \context LyricsVoice = "duet-1" @{
1516 Hi, my name is bert. @}
1517 \context LyricsVoice = "duet-2" @{
1518 Ooooo, ch\'e -- ri, je t'aime. @}
1521 We add the names of the singers. This can be done by setting
1522 @code{LyricsVoice.Stanza} (for the first system) and
1523 @code{LyricsVoice.stz} for the following systems. Note that you must
1524 surround dots with spaces in @code{\lyrics} mode.
1527 \property LyricsVoice . stanza = "Bert"
1529 \property LyricsVoice . stanza = "Ernie"
1532 The convention for naming @code{LyricsVoice} and @code{Voice} must
1533 also be used to get melismata on rests correct.
1536 @c I think we need to change the name of this section, but that
1537 @c would probably involve a lot of changes in other places too.
1538 @node More movements
1539 @section More movements
1541 The program @code{lilypond} only produces sheet music and does not
1542 create titles, subtitles, or print the composer's name. To do that,
1543 you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi}
1544 creates the title, then calls @code{lilypond} to format the sheet music.
1545 In this section, we show you how to create titles like this:
1547 @c Old version of the above paragraph.
1548 @c LilyPond only produces sheet music; it doesn't concern itself with
1549 @c producing titles. Titles are produced using a simply wrapper program
1550 @c This is the jobs of a simple wrapper
1551 @c program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
1552 @c sheet music formatting. Then it produces titles, and ties together all
1553 @c inputs into a single @file{dvi} file. In this section, we show some of
1554 @c the options for titling. We will show how you can produce a file
1555 @c that looks like this:
1557 @center @strong{Two miniatures}
1567 \paper { linewidth = -1.0 }
1579 \paper { linewidth = -1.0 }
1583 For example, consider the following file (@file{miniatures.ly})
1588 title = "Two miniatures"
1589 composer = "F. Bar Baz"
1590 tagline = "small is beautiful" @}
1592 \paper @{ linewidth = -1.0 @}
1596 Mental note: discuss Schenkerian analysis of these key pieces.
1601 \notes @{ c'4 d'4 @}
1607 \notes @{ d'4 c'4 @}
1615 The information for the global titling is in a so-called header block.
1616 The information in this block is not used by LilyPond, but it is
1617 passed into @code{ly2dvi}, which uses this information to print titles
1620 @cindex identifier assignment
1621 the @code{\header} block contains assignments. In each assignment, a
1622 variable is set to a value. The header block for this file looks like
1624 @cindex @code{\header}
1627 title = "Two miniatures"
1628 composer = "F. Bar Baz"
1629 tagline = "small is beautiful"
1633 When you process a file with ly2dvi, a signature line is printed at
1634 the bottom of the last page. This signature is produced from the
1635 @code{tagline} field of @code{\header}. The default "Lily was here,
1636 @var{version number}" is convenient for programmers: archiving the
1637 layouts of different versions allows programmers to compare the
1638 versions using old print-outs.
1640 @cindex Lily was here
1641 @cindex signature line
1644 Many people find the default tagline (``Lily was here'') too droll.
1645 If that is the case, you can change @code{tagline} to somethign else,
1654 A paper block at top level (i.e. not in a @code{\score} block) sets the
1655 default page layout. The following @code{\score} blocks don't have
1656 @code{\paper} sections, so the settings of this block are used.
1658 The variable @code{linewidth} normally sets the length of the systems
1659 on the page. However, a negative value has a special meaning. If
1660 @code{linewidth} is less than 0, no line breaks are inserted into the
1661 score, and the spacing is set to natural length: a short phrase takes
1662 up little space, a longer phrase takes more space, all on the same line.
1667 Mental note: discuss Schenkerian analysis of these key pieces.
1672 Mental notes to yourself can be put into comments. There are two types
1673 of comments. Line comments are introduced by @code{%}, and block
1674 comments are delimited by @code{%@{} and @code{%@}}.
1679 \notes @{ c'4 d'4 @}
1682 In previous examples, most notes were specified in relative octaves
1683 (i.e. each note was put in the octave that is closest to its
1684 predecessor). Besides relative, there is also absolute octave
1685 specification, which you get when you don't include @code{\relative} in
1686 your input file. In this input mode, the middle C is denoted by
1687 @code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
1688 Going up, you get @code{c''} @code{c'''} etc.
1690 When you're copying music from existing sheet music, relative octaves
1691 are probably the easiest to use: you have to do less typing, and errors are
1692 easily spotted. However, if you write LilyPond input directly, either by
1693 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1701 The @code{\header} is normally at the top of the file, where it sets
1702 values for the rest of the file. If you want to typeset different pieces
1703 from one file (for example, if there are multiple movements, or if
1704 you're making an exercise book), you can put different @code{\score}
1705 blocks into the input file. @code{ly2dvi} will assemble all LilyPond
1706 output files into a big document. The contents of @code{\header} blocks
1707 specified within each score is used for the title of that movement.
1713 For example, the Opus number is put at the right, and the "piece" string
1714 will be at the left.
1721 title = "Two miniatures"
1722 composer = "F. Bar Baz"
1723 tagline = "small is beautiful" @}
1725 \paper @{ linewidth = -1.0 @}
1728 \notes @{ c'4 d'4 @}
1734 \notes @{ d'4 c'4 @}
1746 Lilypond and its language are still under development, and
1747 occasionally details of the syntax are changed. The @code{version}
1748 fragment indicates which version of lilypond the input file was written
1749 for. When you compile this file, the version number will be checked
1750 and you will get a warning when the file is too old. This version
1751 number is also used by the @code{convert-ly} program (See
1752 @ref{Invoking convert-ly}), which can used to update the file to the
1753 latest lily version.
1756 @node A piano excerpt
1757 @section A piano excerpt
1759 Our eighth subject is a piece of piano music. The fragment in the
1760 input file is a piano reduction of the G major Sinfonia by Giovanni
1761 Battista Sammartini, composed around 1740. It's in the source
1762 package under the name @file{input/tutorial/sammartini.ly}.
1764 @lilypondfile[smallverbatim]{sammartini.ly}
1766 As you can see, this example features multiple voices on one staff. To
1767 make room for those voices, their notes should be stemmed in opposite
1770 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1771 with some other commonly used formatting instructions, but to explain how
1772 it works, we wrote our own here. Of course, you should use predefined
1773 identifiers like these if possible: you will be less affected by changes
1774 between different versions of LilyPond.
1778 viola = \notes \relative c' \context Voice = viola @{
1780 In this example you can see multiple parts on a staff. Each part is
1781 associated with one notation context. This notation context handles
1782 stems and dynamics (among other things). The type name of this context
1783 is @code{Voice}. For each part we have to make sure that there is
1784 precisely one @code{Voice} context, so we give it a unique name
1791 The delimiters @code{<} and @code{>} are shorthands for
1792 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1793 @code{<} and @code{>} is a chord.
1797 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1805 We want the viola to have stems down, and have all the other
1806 characteristics of a second voice. This is enforced using the
1807 @code{\voiceTwo} command: it inserts instructions that makes stem,
1808 ties, slurs, etc. go down.
1816 Relative octaves work a little differently with chords. The starting
1817 point for the note following a chord is the first note of the chord. So
1818 the @code{g} gets an octave up quote: it is a fifth above the starting
1819 note of the previous chord (the central C).
1825 @code{s} is a spacer rest. It does not print anything, but it does have
1826 the duration of a rest. It is useful for filling up voices that
1827 temporarily don't play. In this case, the viola doesn't come until one
1828 and a half measure later.
1832 oboes = \notes \relative c'' \context Voice = oboe @{
1834 Now comes a part for two oboes. They play homophonically, so we
1835 print the notes as one voice that makes chords. Again, we insure that
1836 these notes are indeed processed by precisely one context with
1840 \voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
1843 The oboes should have stems up to keep them from interfering with
1844 the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
1848 \grace <e8( g> < d4 )f> <c2 e>
1850 @cindex @code{\grace}
1853 @code{\grace} introduces grace notes. It takes one argument, in this
1854 case a chord. A slur is introduced starting from the @code{\grace}
1855 ending on the following chord.
1863 Tuplets are made with the @code{\times} keyword. It takes two
1864 arguments: a fraction and a piece of music. The duration of the piece
1865 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1866 of their notated duration, so in this case the fraction is 2/3.
1869 @{ <d8 f> <e g> <f a> @}
1871 The piece of music to be `tripletted' is sequential music containing
1878 At this point, the homophonic music splits into two rhythmically
1879 different parts. We can't use a sequence of chords to enter this, so
1880 we make a "chord of sequences" to do it. We start with the upper
1881 voice, which continues with upward stems:
1884 @{ \times 2/3 @{ a8 g c @} c2 @}
1891 The easiest way to enter multiple voices is demonstrated
1892 here. Separate the components of the voice (single notes or entire
1893 sequences) with @code{\\} in a simultaneous music expression. The
1894 @code{\\} separators split first voice, second voice, third voice, and
1897 As far as relative mode is concerned, the previous note is the
1898 @code{c'''2} of the upper voice, so we have to go an octave down for
1906 This ends the two-part section.
1910 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1915 @code{\stemBoth} ends the forced stem directions. From here, stems are
1916 positioned as if it were single part music.
1918 The bass has a little hoom-pah melody to demonstrate parts switching
1919 between staves. Since it is repetitive, we use repeats:
1922 hoomPah = \repeat unfold 8
1924 @cindex unfolded @code{\repeat}
1925 The unfolded repeat prints the notes in its argument as if they were
1926 written out in full eight times.
1929 \notes \transpose c' @{
1932 @cindex relative mode and transposing
1934 Transposing can be done with @code{\transpose}, which takes two arguments.
1935 The first specifies what central C should be transposed to. The second
1936 is the to-be-transposed music. As you can see, in this case, the
1937 transposition has no effect, as central C stays at central C.
1939 The purpose of this no-op is to protect it from being interpreted as
1940 relative notes. Relative mode can not be used together with
1941 transposition, so @code{\relative} will leave the contents of
1942 @code{\hoomPah} alone. We can use it without having to worry about
1943 getting the motive in a wrong octave.
1945 @cindex staff switch, manual
1946 @cindex cross staff voice, manual
1947 @cindex @code{\translator}
1950 \translator Staff = down
1953 \translator Staff = up
1957 Voices can switch between staves. Here you see two staff switching
1958 commands. The first one moves to the lower staff, the second one to
1959 the lower one. If you set the stem directions explicitly
1960 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1961 can be beamed together (despite jumping between staffs).
1965 bassvoices = \notes \relative c' @{
1967 \autochange Staff \hoomPah \context Voice
1972 \translator Staff = down
1974 @cindex staff switch
1975 @cindex cross staff voice
1976 We want the remaining part of this melody on the lower staff, so we do a
1977 manual staff switch here.
1982 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1986 After skipping some lines, we see @code{~}. This mark makes ties. Note
1987 that ties and slurs are different things. A tie can only connect two
1988 note heads of the same pitch, whereas a slur can connect many notes
1995 A special context is needed to get cross staff beaming right. This
1996 context is called @code{PianoStaff}.
1999 \context Staff = bottom < \time 2/2 \clef bass
2001 The bottom staff must have a different clef.
2006 To make some more room on the line, the first (in this case the only)
2007 line is not indented. The line still looks very cramped, but that is due
2008 to the page layout of this document.
2014 * font-size, multi-stanza.
2016 * Simple part combining in a Hymn
2020 @node Fine tuning a piece
2021 @section Fine tuning a piece
2023 In this section, we show some ways to fine tune the final output of a
2024 piece. We do so using a single measure of a moderately complex piano
2025 piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
2026 tuned and the untuned are in the @file{input/tutorial/}).
2028 The code for the untuned example shows us some new things.
2030 @lilypondfile[verbatim]{brahms-original.ly}
2040 The crescendo is ended at the half note by the escaped exclamation
2043 Hairpin dynamics can be indicated using @code{\>} to start a
2044 decrescendo, and @code{\!} to end one. The crescendo is started using
2045 @code{\<} and also ended using @code{\!}. Absolute dynamics can be
2046 entered using @code{\p}, @code{\mf}, etc. All these commands apply to
2047 the complete chord where they are entered, but for syntactical
2048 reasons, they must be attached to one of the notes of the chord.
2050 @cindex fingering instructions
2052 Fingering indications are entered simply using @code{-@var{N}}, where
2055 Now that we have the basic piece of music entered, we want to fine
2056 tune it, so we get something that resembles the original printed
2057 edition by Schott/Universal Edition:
2059 @lilypondfile{brahms-tweaked.ly}
2061 @cindex tuning grob behavior
2063 The basic process that we follow is that we override defaults in the
2064 printing system. We do this by setting variables in so-called grobs.
2065 Printed symbols are internally represented by Graphical Objects
2066 (Grobs). Each grob is described by a bunch of settings. Every
2067 setting is a variable: it has a name, and you can assign a value to
2068 the variable. These setting determine the fonts, offsets, sub-routines
2069 to be called on the grob, etc. The initial values of these settings
2070 are set in the Scheme file @file{scm/grob-description.scm}.
2072 @cindex slur attachments
2074 We start with the slur: the slur in the upper part, running from the F
2075 sharp to the A, runs from stem to stem in the printed edition, while
2076 ours starts from the note head at the left. The following property
2077 setting forces all slurs to run from stem to stem (and not from or to
2081 \property Voice.Slur \set #'attachment = #'(stem . stem)
2084 More precisely, this command extends the definition of the @code{Slur}
2085 object in the current @code{Voice}. The variable @code{attachment} is
2086 set to the pair of symbols @code{'(stem . stem)}.
2088 Although this is useful information, it is not very helpful: the
2089 lilypond back-end supports approximately 240 variables like
2090 @code{attachment}, each with their own meaning and own type
2091 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
2092 different types of Grobs, that may be created in 14 different context
2093 types besides Voice.
2095 @cindex internal documentation
2096 @cindex finding grobs
2097 @cindex grob descriptions
2099 The interesting information is how you can figure out which properties
2100 to tune for your own scores. To discover this, you must have a copy of
2101 the internals document. This is a set of HTML pages, which should be
2102 included if you run a binary distribution@footnote{You can also
2103 compile them by executing @code{make -C Documentation/user/
2104 out/lilypond-internals.html} in the source package.}. This document is
2105 also available on the web: go to the lilypond website, click
2106 ``Documentation: other'' on the side bar, click
2107 ``lilypond-internals'', under information for users.
2109 You might want to bookmark either the HTML files on disk, or the one
2110 on the web. One word of caution is in place here: the internals
2111 documentation is generated from the definitions that lily uses. For
2112 that reason, it is strongly tied to the version of LilyPond that you
2113 use. Before you proceed, please make sure that you are using the
2114 documentation that corresponds to the LilyPond version that you use.
2116 Suppose that you wanted to tune the behavior of the slur. The first
2117 step is to get some general information on slurs in lilypond. Turn to
2118 the index, and look up ``slur''. The section on slurs says
2120 The grob for this object is @internalsref{Slur}, generally in
2121 @internalsref{Voice} context.
2124 So the grob for this object is called @code{Slur}, and slurs are
2125 created in the @code{Voice} context. If you are reading this tutorial
2126 in the HTML version, then you can simply click Slur, otherwise, you
2127 must look it up the internal documentation: click ``grob overview'' ,
2128 and select ``slur'' (the list is alphabetical.)
2130 Now you get a list of all the properties that the slur object
2131 supports, along with their default values. Among the properties we
2132 find the @code{attachment} property with its default setting.
2133 The property documentation explains that the following setting will
2134 produce the desired effect:
2136 \property Voice.Slur \set #'attachment = #'(stem . stem)
2139 If you ran the previous example, you have unknowingly already used
2140 this kind of command. The @file{ly/property-init.ly} contains the
2141 definition of @code{\stemUp}
2143 stemUp = \property Voice.Stem \set #'direction = #1
2147 We also want to move around the fingering `3'. In the printed edition
2148 it is not above the stem, but a little lower, slightly left of the
2149 stem. From the user manual, we find that the associated grob is called
2150 @code{Fingering}, but how do we know if we should use @code{Voice} or
2151 @code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
2152 also deduce this information from the internals documentation: if you
2153 visit the documentation of @code{Fingering}, you will notice
2155 Fingering grobs are created by: Fingering_engraver
2160 Clicking @code{Fingering_engraver} will show you the documentation of
2161 the module responsible for interpreting the fingering instructions and
2162 translating them to a @code{Fingering} grob. Such a module is called
2163 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2166 Fingering_engraver is part of contexts: Voice and TabVoice
2168 so tuning the settings for Fingering should be done using either
2170 \property Voice.Fingering \set @dots{}
2174 \property TabVoice.Fingering \set @dots{}
2177 Since the @code{TabVoice} is only used for tab notation, we see that
2178 the first guess @code{Voice} was indeed correct.
2180 @cindex setting grob properties
2181 @cindex @code{extra-offset}
2183 For shifting the fingering, we use the grob property
2184 @code{extra-offset}. The following command manually adds an offset to
2185 the object. We move it a little to the left, and 1.8 staff space
2188 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2190 The @code{extra-offset} is a low-level feature: it moves around
2191 objects in the printout; the formatting engine is completely oblivious
2192 to these offsets. The unit of these offsets are staff-spaces.
2194 @cindex reverting grob properties
2195 @cindex undoing grob properties
2197 We only want to offset a single grob, so after the F-sharp, we must
2198 undo the setting. The technical term is to revert the grob property.
2200 \property Voice.Fingering \revert #'extra-offset
2203 @cindex property types
2204 @cindex translator properties
2205 @cindex grob properties
2206 @cindex music properties
2209 There is three different types of variables in LilyPond, something
2210 which is confusing at first (and for some, it stays like that).
2211 Variables such as @code{extra-offset} and @code{attachment} are called
2212 grob properties. They are something different from the translator
2213 properties, like @code{autoBeaming}. Finally, music expressions are
2214 internally also stored using properties, so-called music
2215 properties. You will encounter the latter type if you run Scheme
2216 functions on music using @code{\apply}.
2218 The second fingering instruction should be moved up a little, to avoid
2219 a collision with the slur. This could be achieved with
2220 @code{extra-offset}, but in this case, a simpler mechanism also
2221 works. We insert an empty text between the 5 and the note. The empty
2222 text pushes the fingering instruction away:
2224 a^" "^#'(finger "5")
2227 Lilypond tries to put fingering instructions closer to the notes as
2228 text instructions. To insert an empty text (@code{^" "}) between the
2229 finger and the note, we have disguised the fingering instruction as a
2230 text: @code{(finger "5")}.
2232 Normally, one would specify dynamics in a single voice, and start and
2233 end dynamics (such as @b{f} and @b{p}) will be aligned with
2234 hairpins. In this case, we want the decrescendo to be in a different
2235 place from the piano sign. We achieve this by putting the dynamic
2236 markings in different voices. The crescendo should be above the upper
2237 staff. This can be forced by the precooked command
2242 However, if you do that, the decrescendo will be too close to the
2243 upper voice, and collide with the stems. Looking at the manual for
2244 dynamics, we notice that ``Vertical positioning of these symbols is
2245 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2246 to the documentation of @code{DynamicLineSpanner}, we find that the
2247 @code{DynamicLineSpanner} supports several so-called
2248 `interfaces'. This grob not only puts dynamic objects next to the
2249 staff (@code{side-position-interface}), but it also groups dynamic
2250 objects (@code{axis-group-interface}), is considered a dynamic sign
2251 itself (@code{dynamic-interface}) and is a grob: it has the
2252 @code{grob-interface}, with all the variables that come with it.
2254 For the moment, we are interested in the side positioning:
2256 side-position-interface
2258 Position a victim object (this one) next to other objects (the
2259 support). In this case, the direction signifies where to put the
2260 victim object relative to the support (left or right, up or down?)
2262 Between the grob and its support (in this case: the notes in the voice
2263 going down), there should be more space. This space is controlled by
2264 @code{padding}, so we increase it.
2266 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2269 This command is almost like the command for setting slur attachments,
2270 but subtly different in its details. Grob properties can be
2271 manipulated with two commands: @code{\override} extends the grob
2272 variables with a setting, and @code{\revert} releases this
2273 setting. This has a certain theoretical appeal: the operations are
2274 simple and symmetric. For practical use, it can be cumbersome. Both
2275 commands act like parentheses: you should carefully balance the use of
2276 @code{\override} and @code{\revert}. The @code{\set} command is more
2277 friendly: it first does a @code{\revert} followed by @code{\override}.
2279 Finally, Brahms uses music notation is a slightly unorthodox way. Ties
2280 usually happen only within one voice. In this piece, the composer
2281 gladly produces ties that jump voices. We deal with this by faking
2282 these ties: whenever we need such a tie, we insert a notehead in a
2283 different voice, and blank the stem. This is done in the following
2287 \property Voice.Stem \set #'transparent = ##t
2289 \property Voice.Stem \revert #'transparent
2292 Finally, the last tie is forced up using @code{\tieUp}.
2295 @node An orchestral score
2296 @section An orchestral score
2300 * Extracting an individual part::
2304 Our last two examples show a way to setup the music for an orchestral
2305 score. When typesetting a piece for several instruments, you'll want to
2306 create a conductor's full score, alongside several individual parts.
2308 LilyPond is well suited for this task. We will declare the music for
2309 each instrument individually, giving the music of each instrument its
2310 own name. These pieces of music are then combined in different
2311 @code{\score} blocks to produce different combinations of the score.
2313 This orchestral score example consists of three input files. In the
2314 first file, @file{os-music.ly}, we define the music for all
2315 instruments. This file will be used both for producing the score and
2316 the separate parts. Other files reference this file by doing
2317 @code{\include "os-music.ly"}.
2319 If you were to run LilyPond on this file, no printable output would be
2325 title = "Zo, goed lieverd?"
2326 subtitle = "How's, this babe?"
2335 Key = \notes \key as \major
2336 flautoI = \notes\relative c'' @{
2338 bes as bes as bes as bes as
2340 flautoII = \notes\relative c'' @{
2341 as8 bes as bes R1 d4 ~ d
2343 tromboI = \notes\relative c'' @{
2344 c4. c8 c8 c4. es4 r as, r
2346 tromboII = \notes\relative c'' @{
2347 as4. as8 as8 as4. R1*1/2 as4 es'
2349 timpani = \notes\relative c, @{
2350 \times 2/3 @{ f4 f f @}
2351 \times 4/5 @{ as8 as as as as @}
2354 corno = \notes\relative c' @{
2355 bes4 d f, bes d f, bes d
2359 We will not go through the input line by line, but only indicate and
2360 explain the new elements.
2367 \skip 2*4 \bar "|.";
2371 Declare setting to be used globally. The @code{\skip} command produces
2372 no output, but moves forward in time: in this case, the duration of a
2373 half note (@code{2}), and that four times (@code{*4}). This brings us
2374 to the end of the piece, and we can set the end bar.
2378 Key = \notes \key as \major
2380 Declare the key signature of the piece and assign it to the identifier
2381 @var{Key}. Later on, we'll use @code{\Key} for all staves except those
2382 for transposing instruments.
2384 @node The full score
2385 @subsection The full score
2388 The second file, @file{input/tutorial/os-score.ly} reads the definitions of the first
2389 (@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
2395 \include "os-music.ly"
2396 \include "paper13.ly"
2398 #(set-point-and-click! 'line-column)
2399 #(define text-flat '((font-relative-size . -2)
2400 (music "accidentals--1")))
2405 \property Score.BarNumber \override #'padding = #3
2406 \context StaffGroup = woodwind <
2407 \context Staff = flauti <
2408 \property Staff.midiInstrument = #"flute"
2409 \property Staff.instrument = "2 Flauti"
2410 \property Staff.instr = "Fl."
2412 \context Voice=one @{ \voiceOne \flautoI @}
2413 \context Voice=two @{ \voiceTwo \flautoII @}
2416 \context StaffGroup = timpani <
2417 \context Staff = timpani <
2418 \property Staff.midiInstrument = #"timpani"
2419 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2420 \property Staff.instr = #"Timp."
2426 \context StaffGroup = brass <
2427 \context Staff = trombe <
2428 \property Staff.midiInstrument = #"trumpet"
2429 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2430 \property Staff.instr = #`(lines "Tbe." "(C)")
2432 \context Voice=one \partcombine Voice
2433 \context Thread=one \tromboI
2434 \context Thread=two \tromboII
2436 \context Staff = corni <
2437 \property Staff.midiInstrument = #"french horn"
2438 \property Staff.instrument = #`(lines "Corno"
2439 (columns "(E" ,text-flat ")"))
2440 \property Staff.instr = #`(lines "Cor."
2441 (columns "(E" ,text-flat ")"))
2442 \property Staff.transposing = #3
2443 \notes \key bes \major
2444 \context Voice=one \corno
2449 indent = 15 * \staffspace
2450 linewidth = 60 * \staffspace
2451 textheight = 90 * \staffspace
2453 \HaraKiriStaffContext
2462 @center @strong{Zo, goed lieverd?}
2464 @center How's, this babe?
2472 @lilypondfile{os-score.ly}
2476 \include "os-music.ly"
2478 First, we need to include the music definitions we made in
2483 #(set-point-and-click! 'line-column)
2486 This piece of Scheme code executes the function
2487 @code{set-point-and-click!}, with the argument @code{line-column}, a
2490 Editing input files can be complicated if you're working with large
2491 files: if you're digitizing existing music, you have to synchronize
2492 the .ly file, the sheet music on your lap and the sheet music on the
2493 screen. The point-and-click mechanism makes it easy to find the
2494 origin of an error in the LY file: when you view the file with Xdvi
2495 and click on a note, your editor will jump to the spot where that note
2496 was entered. For more information, see @ref{Point and click}.
2501 #(define text-flat '((font-relative-size . -2)
2502 (music "accidentals--1")))
2505 When naming the tuning of the french horn, we'll need a piece of text
2506 with a flat sign. LilyPond has a mechanism for font selection and
2507 kerning called Scheme markup text (See @ref{Text markup}). The flat
2508 sign is taken from the music font, and its name is @code{accidentals--1}
2509 (The natural sign is called @code{accidentals-0}). The default font is
2510 too big for text, so we select a relative size of @code{-2}.
2517 Of course, all staves are simultaneous and use the same global settings.
2521 \property Score.BarNumber \override #'padding = #3
2523 LilyPond prints bar numbers at the start of each line, but
2524 unfortunately, they end up a bit too close to the staff in this
2525 example. A bar number internally is a Grob called @var{BarNumber}.
2526 BarNumber Grobs can be manipulated through their
2527 @var{side-position-interface}. One of the properties of a
2528 @var{side-position-interface} that can be tweaked is the
2529 @var{padding}: the amount of extra space that is put between this Grob
2530 and other Grobs. We set the padding to three staff spaces.
2532 You can find information on all these kind of properties in LilyPond's
2533 automatically generated documentation in
2535 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
2538 the online documentation.
2543 \context StaffGroup = woodwind <
2544 \context Staff = flauti <
2546 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2547 hold one or more @code{Staff}'s, and will print a big bracket at the
2548 left of the score. Start a new staff group for the woodwind section
2549 (just the flutes in this case). Immediately after that, we start the
2550 staff for the two flutes, that also play simultaneously.
2554 \property Staff.midiInstrument = #"flute"
2556 Specify the instrument for MIDI output (see @ref{MIDI instrument
2561 \property Staff.instrument = "2 Flauti"
2562 \property Staff.instr = "Fl."
2564 And define the instrument names to be printed in the margin,
2565 @code{instrument} for the first line of the score, @code{instr} for the
2572 The flutes play in the default key.
2576 \context Voice=one @{ \voiceOne \flautoI @}
2577 \context Voice=two @{ \voiceTwo \flautoII @}
2579 Last come the actual flute parts. Remember that we're still in
2580 simultaneous mode. We name both voices differently, so that LilyPond
2581 will actually create two Voice contexts. The flute parts are simple, so
2582 we specify manually which voice is which: @code{\voiceOne} forces the
2583 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2591 Close the flutes staff and woodwind staff group.
2595 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2597 The timpani staff only shows a new piece of scheme markup, it sets two
2602 \context Voice=one \partcombine Voice
2603 \context Thread=one \tromboI
2604 \context Thread=two \tromboII
2606 You have seen the notation contexts Staff and Voice, but here's a new
2607 one: Thread. One or more Threads can be part of a Voice. The Thread
2608 takes care of note heads and rests, the Voice combine note heads onto a
2611 For the trumpets we use the automatic part combiner (see @ref{Automatic
2612 part combining}) to combine the two simultaneous trumpet parts onto the
2613 trumpet staff. Each trumpet gets its own Thread context, which must be
2614 named @code{one} and @code{two}). The part combiner makes these two
2615 threads share a Voice when they're similar, and splits the threads up
2616 when they're different.
2620 \property Staff.instrument = #`(lines "Corno"
2621 (columns "(E" ,text-flat ")"))
2623 The french horn has the most complex scheme markup name, made up of two
2624 lines of text. The second line has three elements (columns), the @code{(E},
2625 the flat sign @code{text-flat} that we defined before and a final @code{")"}.
2626 Note that we use a backquote instead of an ordinary quote at the
2627 beginning of the Scheme expression to be able to access the
2628 @code{text-flat} identifier, `unquoting' it with a @code{,}.
2632 \property Staff.transposing = #3
2634 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2635 transpose this staff by three steps.
2637 Note how we can choose different tuning for entering, printing and
2638 playing, using @code{\transpose} and the MIDI Staff property
2643 \notes \key bes \major
2645 Therefore, it has a different key.
2649 indent = 15 * \staffspace
2650 linewidth = 60 * \staffspace
2652 We specify a big indent for the first line and a small linewidth for this
2657 Usually, LilyPond's predefined setup of notation contexts (Thread,
2658 Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
2659 want a different type of Staff context.
2663 \HaraKiriStaffContext
2667 In orchestral scores, it often happens that one instrument has only
2668 rests during one line of the score. The @code{HaraKiriStaffContext} can
2669 be used as a regular @code{StaffContext} drop-in and will take care of
2670 the automatic removing of empty staves.
2672 @node Extracting an individual part
2673 @subsection Extracting an individual part
2675 The third file, @file{os-flute-2.ly} also reads the definitions of the
2676 first (@file{os-music.ly}), and defines the @code{\score} block for the
2680 \include "os-music.ly"
2681 \include "paper16.ly"
2685 \property Score.skipBars = ##t
2686 \property Staff.midiInstrument = #"flute"
2692 instrument = "Flauto II"
2695 linewidth = 80 * \staffspace
2696 textheight = 200 * \staffspace
2704 @center @strong{Zo, goed lieverd?}
2706 @center How's, this babe?
2707 @center @emph{Flauto II}
2714 @lilypondfile{os-flute-2.ly}
2717 Because we separated the music definitions from the @code{\score}
2718 instantiations, we can easily define a second score with the music of
2719 the second flute. This then is the part for the second flute player.
2720 Of course, we make separate parts for all individual instruments.
2726 In this individual part the second flute has a whole staff for itself,
2727 so we don't want to force stem or tie directions.
2732 instrument = "Flauto II"
2735 The @code{\header} definitions were also read from @file{os-music.ly},
2736 but we need to set the instrument for this particular score.
2740 \property Score.skipBars = ##t
2742 In the conductor's full score, all bars with rests are printed, but for
2743 the individual parts, we want to contract pieces of consecutive empty
2744 bars. LilyPond will do this if Score's @var{skipBars} property to
2748 @node Integrating text and music
2749 @section Integrating text and music
2752 @cindex La@TeX{}, music in
2753 @cindex HTML, music in
2754 @cindex Texinfo, music in
2756 Sometimes, you might want to use music examples in a text that you are
2757 writing. For example, if you are writing a musicological treatise, a
2758 songbook, or (like us) the LilyPond manual. You can make such texts by
2759 hand, simply by importing a PostScript figure into your word processor.
2760 However, there is a also an automated procedure:
2762 If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond
2763 code. A script called @code{lilypond-book} will extract the music
2764 fragments, run LilyPond on them, and put back the resulting notation.
2765 This utility program is described fully in the chapter
2766 @ref{Integrating text and music with lilypond-book}. Here we show a
2767 small example. Since the example also contains explanatory text, we
2768 won't comment on the contents.
2771 \documentclass[a4paper]@{article@}
2774 In a lilypond-book document, you can freely mix music and text. For
2777 \score @{ \notes \relative c' @{
2778 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2781 Notice that the music line length matches the margin settings of the
2784 If you have no \verb+\score+ block in the fragment,
2785 \texttt@{lilypond-book@} will supply one:
2791 In the example you see here, a number of things happened: a
2792 \verb+\score+ block was added, and the line width was set to natural
2793 length. You can specify many more options using \LaTeX style options
2796 \begin[verbatim,11pt,singleline,
2797 fragment,relative,intertext="hi there!"]@{lilypond@}
2801 \texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
2802 the default music size, \texttt@{fragment@} adds a score block,
2803 \texttt@{relative@} uses relative mode for the fragment, and
2804 \texttt@{intertext@} specifies what to print between the
2805 \texttt@{verbatim@} code and the music.
2807 If you include large examples into the text, it may be more convenient
2808 to put the example in a separate file:
2810 \lilypondfile[printfilename]@{sammartini.ly@}
2812 The \texttt@{printfilename@} option adds the file name to the output.
2817 Under Unix, you can view the results as follows.
2821 @var{..may complain that @file{out/} already exists..}
2822 $ lilypond-book --outdir=out/ lilbook.tex
2823 lilypond-book (GNU LilyPond) 1.3.146
2824 Reading `input/tutorial/lilbook.tex'
2825 Reading `input/tutorial/sammartini.ly'
2826 @var{lots of stuff deleted}
2827 Writing `out/lilbook.latex'
2829 $ latex lilbook.latex
2830 @var{lots of stuff deleted}
2834 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2835 and running latex creates a lot of temporary files, and you wouldn't want
2836 those to clutter up your working directory. Hence, we have them created
2837 in a separate subdirectory.
2839 The result more or less looks like this:
2843 In a lilypond-book document, you can freely mix music and text. For
2846 \score { \notes \relative c' {
2847 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2850 Notice that the music line length matches the margin settings of the
2853 If you have no @code{\score} block in the fragment,
2854 @code{lilypond-book} will supply one:
2860 In the example you see here, a number of things happened: a
2861 @code{\score} block was added, and the line width was set to natural
2862 length. You can specify many more options using La@TeX{} style options
2865 @lilypond[verbatim,11pt,singleline,
2866 fragment,relative,intertext="hi there!"]
2870 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2871 the default music size, @code{fragment} adds a score block,
2872 @code{relative} uses relative mode for the fragment, and
2873 @code{intertext} specifies what to print between the
2874 @code{verbatim} code and the music.
2876 If you include large examples into the text, it may be more convenient
2877 to put the example in a separate file:
2879 @lilypondfile[printfilename]{sammartini.ly}
2881 The @code{printfilename} option adds the file name to the output.
2882 @node End of tutorial
2883 @section End of tutorial
2885 This is the end of the tutorial. If you came up till here, and
2886 have understood everything, then you're now an accomplished lilypond
2887 hacker. From here, you can try fiddling with input
2888 files, coming back to the reference manual for information.
2889 Also don't forget to check out the
2891 @uref{../../templates/out-www/templates.html,templates},
2892 @uref{../../test/out-www/test.html,example} and
2893 @uref{../../regression/out-www/regression.html,feature test}
2897 templates, example and feature test snippets.
2899 If you want to see real action lilypond, then head over to
2900 @uref{http://www.mutopiaproject.org}, which has many examples of
2901 classical music typeset by LilyPond.