3 @c TODO: LilyPond LilyPond LilyPond
9 <!--- @@WEB-TITLE@@=Tutorial --->
13 * First steps:: Music language of LilyPond
14 * Running LilyPond:: Printing music
16 * A melody with chords ::
18 * More movements :: Joining separate pieces of music
19 * A piano excerpt:: Piano music
20 * Fine tuning a piece::
21 * An orchestral score:: Conductor's score and individual parts
22 * Integrating text and music:: Integrating text and music
23 * End of tutorial:: The end
26 Operating lilypond is done through text files: to print a piece of
27 music, you enter the music in a file. When you run lilypond, that
28 file is read, and after some computations, the program produces a file
29 containing the sheet music that you can print or view.
31 This tutorial starts with a small introduction to the LilyPond music
32 language. After this first contact, we will show you how to run
33 LilyPond to produce printed output; you should then be able to create
34 your first sheets of music. The tutorial continues with more and more
37 Some of the examples discussed are included as separate files in the
38 distribution, in the subdirectory @file{input/tutorial/} of the source
44 In this section, we show how to make small, very simple pieces of
45 music in LilyPond. If you have not seen LilyPond input files before,
46 this section is for you.
48 You get a simple note by typing its note name, from @code{a} through
49 @code{g}. So if you enter
55 then the result looks like this:
58 \property Score.timing = ##f
59 \property Staff.TimeSignature = \turnOff
60 \transpose c'' { c d e f g a b }
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, ``@code{1}'' for a
69 whole note, ``@code{2}'' for a half note, and so on:
76 @c missing clef seems to raise more questions than actual pitch of notes,
77 @c as these are snippets anyway
79 \property Score.timing = ##f
80 \property Staff.TimeSignature = \turnOff
81 \property Staff.autoBeaming = ##f
82 %\property Staff.Clef = \turnOff
83 \transpose c'' { a1 a2 a4 a16 a32 }
89 If you don't specify a duration, the previous one is used:
95 @c missing clef seems to raise more questions than actual pitch of notes,
96 @c as these are snippets anyway
98 \property Score.timing = ##f
99 \property Staff.TimeSignature = \turnOff
100 %\property Staff.Clef = \turnOff
101 \transpose c'' { a a a2 a }
107 A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
108 (@texiflat{}) by adding ``@code{es}'':
116 \property Score.timing = ##f
117 \property Staff.TimeSignature = \turnOff
118 \transpose c'' { cis1 ees fisis aeses }
124 Add a dot ``@code{.}'' after the duration to get a dotted note:
130 @c missing clef seems to raise more questions than actual pitch of notes,
131 @c as these are snippets anyway
133 \property Score.timing = ##f
134 \property Staff.TimeSignature \set #'transparent = ##t
135 %\property Staff.Clef = \turnOff
136 \transpose c'' { a2. a4 a8. a16 }
142 The meter (or time signature) can be set with the @code{\time} command:
151 @c a clef here may lead to confusion
153 \property Staff.Clef \set #'transparent = ##t
164 The clef can be set using the ``@code{\clef}'' command:
166 @c what is more common name treble or violin?
167 @c in Dutch, its violin.
177 \property Score.timing = ##f
178 \property Staff.TimeSignature = \turnOff
191 From these commands and notes, a piece of music can be formed. A piece
192 of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
193 LilyPond then knows that music follows (and not lyrics, for example):
207 At this point, the piece of music is ready to be printed. This is done
208 by combining the music with a printing command.
210 The printing command is the so-called ``@code{\paper}'' block. You
211 will see later that the @code{\paper} block is necessary 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 }
246 @multitable @columnfractions .3 .3 .4
252 @item @code{1 2 8 16}
255 @lilypond[fragment, relative 1]
256 \property Staff.TimeSignature = \turnOff
257 \property Staff.autoBeaming = ##f
258 \property Staff.Clef = \turnOff
263 @tab augmentation dots
265 @lilypond[fragment, relative 1]
266 \property Staff.TimeSignature = \turnOff
267 \property Staff.Clef = \turnOff
271 @item @code{c d e f g a b }
274 @lilypond[fragment, relative 1]
275 \property Staff.TimeSignature = \turnOff
276 \property Staff.Clef = \turnOff
280 @item @code{\clef treble \clef bass }
284 \property Staff.TimeSignature \set #'transparent = ##t
291 @item @code{\time 3/4 \time 4/4 }
295 \property Staff.Clef \set #'transparent = ##t
305 @c maybe legend here?
308 We continue with the introduction of the remaining musical constructs.
310 Normal rests are entered just like notes with the name ``@code{r}'':
318 \property Score.timing = ##f
319 \property Staff.Clef = \turnOff
320 \property Staff.TimeSignature = \turnOff
327 @c Tim wants to move this quotes example just before the: quotes-don't-work
328 @c score, but we'd need to remove quotes from the other two (key and
331 @c better to have this just before the `octaves are bad' snipped
332 @c but we'd need to remove the ', from \key and tie
333 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
334 the note name, to lower a note one octave, add a ``low quote'' @code{,}
335 (a comma). The central C is @code{c'}:
339 c'4 c'' c''' \clef bass c c,
343 \property Score.timing = ##f
344 \property Staff.TimeSignature = \turnOff
345 c'4 c'' c''' \clef bass c c,
350 A tie is created by entering a tilde ``@code{~}'' between the notes to
351 be tied. A tie between two notes means that the second note must not be
352 played separately, but just makes the first note sound longer:
355 @lilypond[fragment,verbatim]
361 The key signature is set with the command ``@code{\key}'':
371 \property Staff.TimeSignature = \turnOff
380 @c bit on the long/complex/scary taste
381 @c cheating a bit: two lines makes for a friendlier look
382 This example shows notes, ties, octave marks, and rests in action.
391 r4 r8 d''8 cis''4 e''
393 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
406 r4 r8 d''8 cis''4 e''
408 cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
411 \paper { linewidth = 50*\staffspace }
417 There are some interesting points to note in this example.
418 Accidentals (sharps and flats) don't have to be marked explicitly: you
419 just enter the note name, and LilyPond determines whether or not to
420 print an accidental. Bar lines and beams are drawn automatically.
421 LilyPond calculates line breaks for you; it doesn't matter where you
422 make new lines in the source file. Finally, the order of time, key and
423 clef changes is not relevant: lilypond will use standard notation
424 conventions for ordering these items.
426 The example also indicates that a piece of music written in a high
427 register needs lots of quotes. This makes the input less readable,
428 and is therefore also a potential source of errors.
430 The solution is to use ``relative octave'' mode. In practice, this is
431 the most convenient way to copy existing music. To use relative mode,
432 add @code{\relative} before the piece of music. You must also give a
433 note from which relative starts, in this case @code{c''}. If you type
434 no octavation quotes, relative mode chooses the note that is closest
435 to the previous one, which is often just the one you need.
436 @c don't use commas or quotes in this sentence
437 For example: @code{c f} goes up; @code{c g} goes down:
447 \property Score.timing = ##f
448 \property Staff.TimeSignature = \turnOff
456 @c needed better, maybe even redundant explanation
457 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
458 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
459 You can make a large interval by adding octavation quotes. Note that
460 quotes or commas do not determine the absolute height of a note;
461 the height of a note is relative to the previous one.
462 @c don't use commas or quotes in this sentence
463 For example: @code{c f,} goes down; @code{f, f} are both the same;
464 @code{c c'} are the same; and @code{c g'} goes up:
474 \property Score.timing = ##f
475 \property Staff.TimeSignature = \turnOff
486 @multitable @columnfractions .3 .3 .4
495 @lilypond[fragment, relative 1]
496 \property Staff.TimeSignature = \turnOff
497 \property Staff.Clef = \turnOff
505 @lilypond[fragment, relative 1]
506 \property Score.timing = ##f
507 \property Staff.TimeSignature = \turnOff
508 \property Staff.autoBeaming = ##f
509 \property Staff.Clef = \turnOff
514 @item @code{\key es \major }
518 \property Staff.TimeSignature \set #'transparent = ##t
527 @lilypond[fragment, relative 1]
528 \property Score.timing = ##f
529 \property Staff.TimeSignature = \turnOff
530 \property Staff.autoBeaming = ##f
531 \property Staff.Clef = \turnOff
538 @lilypond[fragment, relative 1]
539 \property Score.timing = ##f
540 \property Staff.TimeSignature = \turnOff
541 \property Staff.autoBeaming = ##f
542 \property Staff.Clef = \turnOff
548 A slur is drawn across many notes, and indicates bound articulation
549 (legato). The starting note and ending note are marked with a
550 ``@code{(}'' and a ``@code{)}'' respectively:
553 @lilypond[fragment,relative 1, verbatim]
554 d4( )c16( cis d e c cis d )e( )d4
559 If you need two slurs at the same time (one for articulation, one for
560 phrasing), you can also make a phrasing slur with @code{\(} and
565 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
566 @c chromatic thing pasted in front. (admittedly the original doesn't
567 @c have a phrasing slur. The problem is that we don't want the slur
568 @c and the Phrasing slur to collide. We're trying to make a good
572 @lilypond[fragment,relative 1, verbatim]
573 a8(\( ais b ) c cis2 b'2 a4 cis, \) c
578 Beams are drawn automatically, but if you don't like the choices, you
579 can enter beams by hand. Surround the notes to be grouped with @code{[}
582 @lilypond[fragment,relative 1, verbatim]
588 To print more than one staff, each piece of music that makes up a staff
589 is marked by adding @code{\context Staff} before it. These
590 @code{Staff}'s can be grouped inside @code{<} and @code{>}, as is
594 @lilypond[fragment,verbatim]
596 \context Staff = staffA { \clef violin c'' }
597 \context Staff = staffB { \clef bass c }
602 In this example, @code{staffA} and @code{staffB} are names that are
603 given to the staves. It doesn't matter what names you give, as long
604 as each staff has a unique name.
608 We can typeset a melody with two staves now:
611 @lilypond[verbatim,singleline]
614 < \context Staff = staffA {
617 \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
619 \context Staff = staffB {
630 Notice that the time signature is specified in one melody staff only
631 (the top staff), but is printed on both. LilyPond knows that the time
632 signature should be the same for all staves.
636 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
638 @lilypond[verbatim,relative 1]
644 Dynamic signs are made by adding the markings to the note:
646 @lilypond[verbatim,relative 1]
652 Crescendi are started with the commands @code{\<} and @code{\>}. The
653 command @code{\!} finishes a crescendo on the following note.
655 @lilypond[verbatim,relative 1]
656 c2\< \!c2-\ff \>c2 \!c2
661 Chords can be made by surrounding notes with @code{<} and @code{>}:
663 @lilypond[relative 0, fragment,verbatim]
671 @c hmm, te losjes, iig
672 In general, @code{ < @var{stuff} > } is used when @var{stuff} all
673 happens at the same time, like in chords, or (like in the two-staff
674 example above) in a bunch of stacked staves.
677 Of course, you can combine beams and ties with chords. Notice that
678 beam and tie markings must be placed outside the chord markers:
680 @lilypond[relative 0, fragment,verbatim]
681 r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
685 When you want to combine chords with slurs and dynamics, technical
686 detail crops up: you have type these commands next to the notes, which
687 means that they have to be inside the @code{< >}:
692 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
694 @lilypond[relative 0, fragment]
696 r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
701 There is one golden rule that you should keep in mind when writing
704 @strong{DO NOT START A PIECE WITH A CHORD}
706 Of course, it is a allowed, but the result might not be what you expect:
708 @lilypond[verbatim,singleline]
709 \score { \notes <c'2 e'2> }
714 If you have a piece that starts with a chord, then you must explicitly
715 state that the notes of the chord are to be put on the same staff, in
716 the same voice. This is done by specifying @code{\context Staff} for
720 @lilypond[verbatim,singleline]
721 \score { \notes \context Voice <c'2 e'2> }
730 @multitable @columnfractions .3 .3 .4
740 @lilypond[fragment, relative 1]
741 \property Score.timing = ##f
742 \property Staff.TimeSignature = \turnOff
743 \property Staff.autoBeaming = ##f
744 \property Staff.Clef = \turnOff
752 @lilypond[fragment, relative 1]
753 \property Score.timing = ##f
754 \property Staff.TimeSignature = \turnOff
755 \property Staff.autoBeaming = ##f
756 \property Staff.Clef = \turnOff
764 @lilypond[fragment, relative 1]
765 \property Score.timing = ##f
766 \property Staff.TimeSignature = \turnOff
767 \property Staff.autoBeaming = ##f
768 \property Staff.Clef = \turnOff
773 @item @code{< \context Staff ... >}
777 < \context Staff = SA { c'1 }
778 \context Staff = SB { c'1 } >
785 @lilypond[fragment, relative 1]
786 \property Staff.TimeSignature = \turnOff
787 \property Staff.Clef = \turnOff
792 @item @code{-\mf -\sfz}
795 @lilypond[fragment, relative 1]
796 \property Staff.TimeSignature = \turnOff
797 \property Staff.Clef = \turnOff
805 @lilypond[fragment, relative 1]
806 \property Score.timing = ##f
807 \property Staff.TimeSignature = \turnOff
808 \property Staff.autoBeaming = ##f
809 \property Staff.Clef = \turnOff
816 @lilypond[fragment, relative 1]
817 \property Score.timing = ##f
818 \property Staff.TimeSignature = \turnOff
819 \property Staff.autoBeaming = ##f
820 \property Staff.Clef = \turnOff
828 @lilypond[fragment, relative 1]
834 You know the basic ingredients of a music file, so this is the right
835 moment to try your at hand at doing it yourself: try to type some
836 simple examples, and experiment a little.
838 When you're comfortable with the basics, then you might want to read
839 the rest of this chapter. It also a manual in tutorial-style, but it
840 is much more in-depth, dealing with more advanced topics such as
841 lyrics, chords, orchestral scores and parts, fine tuning output,
842 polyphonic music, and integrating text and music.
845 @node Running LilyPond
846 @section Running LilyPond
848 In the last section, we explained what kind of things you could enter
849 in a lilypond file. In this section we explain how to run LilyPond,
850 and how view or print the output. If you have not used LilyPond
851 before, want to test your setup of LilyPond, or try to run an example
852 file yourself, then read this section. The instructions that follow
853 are for running LilyPond on Unix-like systems. Some additional
854 instructions for running LilyPond on Windows are given at the end of
857 You begin with opening a terminal window, and start up a text editor.
858 For example, open an xterm and execute @code{joe}. In your text editor,
859 enter the following input, and save the file as @file{test.ly}:
864 \notes @{ c'4 e' g' @}
871 @c now this is weird, running ly2dvi to run LilyPond
872 @c (therefore name change proposal)
874 LilyPond is the program that computes the sheet music. All other
875 things, such as adding titles, page breaking and other page layout,
876 are done by a small wrapper program called
877 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
878 then adds the titling and page layout instructions. To process
879 @file{test.ly} with ly2dvi, proceed as follows:
887 You will see the following on your screen:
892 Now processing: `/home/fred/ly/test.ly'
894 Interpreting music...[1]
895 @emph{ ... more interesting stuff ... }
896 PS output to `test.ps'...
897 DVI output to `test.dvi'...
901 @cindex Viewing music
904 The results of the ly2dvi run are two files, @file{test.dvi} and
905 @file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
906 You can view the PS file using the program ghostview. If a version of
907 ghostview is installed on your system, one of these commands will
908 produce a window with some music notation on your screen:
918 If you are satisfied with the looks of the music displayed on your
919 screen, you can print the PS file by clicking File/Print inside
922 The DVI file (@file{test.dvi}) contains the same sheet music in a
923 different format. DVI files are more easily processed by the computer,
924 so viewing them usually is quicker. Execute @code{xdvi test.dvi}
925 to view the DVI file.
927 If your DVI viewer does not have a "Print" button, you can print the
928 file by executing @code{lpr test.ps}.
930 @c volgende alinea schrappen?
932 If you can't get the examples to print, then you should look into
933 installing and configuring ghostscript. Refer to GhostScript's website
934 at @uref{http://www.ghostscript.com}.
938 @cindex Printing output
941 @unnumberedsubsec Windows users
942 Windows users start the terminal by clicking on the LilyPond or Cygwin
943 icon. Notepad is sufficient for editing the LilyPond file. Viewing
944 the PS file can be done with:
947 @code{gsview32 test.ps}
950 You can also print from the command line by executing:
953 @code{gsview32 /s test.ps}
959 @node Printing lyrics
960 @section Printing lyrics
963 In this section we shall explain how to typeset the following
964 fragment of The Free Software Song:
966 @lilypond[singleline]
967 \score { \notes { \addlyrics
968 \notes \relative c' {
970 d'2 c4 b16 ( a g a b a b ) c a2
971 b2 c4 b8 ( a16 g ) a4 g2 }
972 \context Lyrics \lyrics {
974 share the soft -- ware; }
976 \paper { linewidth = -1. }
982 @cindex @code{\lyrics}
985 To print lyrics, you must enter them, and then instruct lilypond to
986 handle the lyrics by printing them.
987 You can enter lyrics in a special input mode of LilyPond. This mode is
988 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
989 The purpose of this mode is that you can enter lyrics as plain text,
990 punctuation and accents without any hassle.
992 Syllables are entered like notes, with pitches replaced by text. For
993 example, @code{Twin- kle twin- kle} enters four syllables. Note that
994 the hyphen has no special meaning for lyrics, and does not introduce
997 Spaces can be introduced into a lyric either by using quotes:
998 @code{"He could"4 not4} or by using an underscore without quotes:
999 @code{He_could4 not4}. All unquoted underscores are converted to
1002 These are the lyrics for the free software song:
1007 share the soft -- ware; @}
1010 As you can see, extender lines are entered as @code{__}. This will
1011 create an extender, a line that extends over the entire duration of
1012 the lyric. This line will run all the way to the start of the next
1013 lyric, so you may want to shorten it by using a blank lyric (using
1017 If you can use have hyphens at the end of a syllable, i.e.
1021 but then the hyphen will be attached to the to the end of the first
1024 If you want them centered between syllables you can use the special
1025 `@code{-}@code{-}' lyric as a separate word between syllables. The
1026 hyphen will have variable length depending on the space between
1027 syllables. It will be centered between the syllables.
1029 Normally, the notes that you enter are transformed into note heads.
1030 Note heads alone make no sense, they need surrounding information: a key
1031 signature, a clef, staff lines, etc. They need @emph{context}. In
1032 LilyPond, these symbols are created by objects called `interpretation
1033 contexts'. Interpretation contexts exist for generating notation
1034 (`notation context') and for generating sound (`performance
1035 context'). These objects only exist during a run of LilyPond.
1037 When LilyPond interprets music, it will create a Staff context.
1038 We don't want that default here, because we want lyric. The
1043 explicitly creates an interpretation context of
1044 @code{Lyrics} type to interpret the song text that we entered.
1046 The melody of the song doesn't offer anything new:
1048 \notes \relative c' @{
1050 d'2 c4 b16 ( a g a b a b ) c a2
1051 b2 c4 b8 ( a16 g ) a4 g2 @}
1054 Both can be combined with the @code{\addlyrics}:
1057 \notes \relative c' @dots{}
1058 \context Lyrics \lyrics @dots{}
1061 The lyrics are also music expressions, similar to notes. What happens
1062 here, is that each syllable of the lyrics is put under the a note of
1064 The complete file is listed here:
1067 \score @{ \notes @{ \addlyrics
1068 \notes \relative c' @{
1070 d'2 c4 b16 ( a g a b a b ) c a2
1071 b2 c4 b8 ( a16 g ) a4 g2 @}
1072 \context Lyrics \lyrics @{
1074 share the soft -- ware; @}
1076 \paper @{ linewidth = -1. @}
1082 @node A melody with chords
1083 @section A melody with chords
1085 In this section we show how to typeset a melody with chord
1086 accompaniment. This file is included as @file{flowing.ly}.
1089 \include "paper16.ly"
1090 melody = \notes \relative c' @{
1094 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1095 c4 c8 d [es () d] c4 | d4 es8 d c4.
1099 accompaniment =\chords @{
1101 c2:3- f:3-.7 d:min es4 c8:min r8
1102 c2:min f:min7 g:7^3.5 c:min @}
1107 \context ChordNames \accompaniment
1108 \context Staff = mel @{
1113 \midi @{ \tempo 4=72 @}
1114 \paper @{ linewidth = 10.0\cm @}
1119 The result would look this.
1122 \include "paper16.ly"
1123 melody = \notes \relative c' {
1127 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1128 c4 c8 d [es () d] c4 | d4 es8 d c4.
1132 accompaniment =\chords {
1134 c2:3- f:3-.7 d:min es4 c8:min r8
1135 c2:min f:min7 g:7^3.5 c:min }
1140 \context ChordNames \accompaniment
1142 \context Staff = mel {
1143 \property Staff.autoBeaming = ##f
1147 \midi { \tempo 4=72 }
1148 \paper { linewidth = 10.0\cm }
1152 Again, we will dissect the file line by line.
1157 \include "paper16.ly"
1160 Smaller size for inclusion in a book.
1164 melody = \notes \relative c' @{
1167 The structure of the file will be the same as the previous one, a
1168 @code{\score} block with music in it. To keep things readable, we will
1169 give names to the different parts of music, and use the names to
1170 construct the music within the score block.
1177 @cindex @code{\partial}
1179 The piece starts with an anacrusis of one eighth.
1184 The key is C minor: we have three flats.
1189 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1190 c4 c8 d [es () d] c4 | d4 es8 d c4.
1195 @cindex manual beaming
1196 @cindex automatic beaming, turning off
1197 We use explicit beaming. Since this is a song, we turn automatic
1198 beams off, and use explicit beaming where needed.
1205 This ends the definition of @code{melody}.
1214 @cindex identifier assignment
1215 @cindex syllables, entering
1220 accompaniment =\chords @{
1224 @cindex mode, chords
1225 We'll put chords over the music. To enter them, there is a special mode
1226 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1227 the names of the chords you want, instead of listing the notes
1228 comprising the chord.
1235 There is no accompaniment during the anacrusis.
1244 @cindex chord modifier
1245 @cindex modifier, chord
1246 This is a c minor chord, lasting half a note. Chord are entered by
1247 entering the tonic. Then notes can be changed. In this case, a small third
1248 is used. The cod for this is @code{3-}.
1254 Similarly, @code{7} modifies (adds) a seventh, which is small by
1255 default to create the @code{f a c es} chord. Multiple modifiers must be
1263 Some modifiers have predefined names, e.g. @code{min} is the same as
1264 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1268 c2:min f:min7 g:7^3.5 c:min @}
1271 @cindex named modifier
1273 A named modifier @code{min} and a normal modifier @code{7} do not have
1274 to be separated by a dot. Tones from a chord are removed with chord
1275 subtractions. Subtractions are started with a caret, and they are
1276 also separated by dots. In this example, @code{g:7^3.5} produces a
1277 minor seventh. The brace ends the sequential music.
1285 We assemble the music in the @code{\score} block. Melody, lyrics and
1286 accompaniment have to sound at the same time, so they should be
1287 @code{\simultaneous}.
1288 @cindex @code{\simultaneous}
1295 Chord mode generates notes grouped in @code{\simultaneous} music. If
1296 you remove the comment sign, you can see the chords in normal
1297 notation: they will be printed as note heads on a separate
1298 staff. To print them as chords names, they have to be interpreted as
1299 being chords, not notes. This is done with the following command:
1303 \context ChordNames \accompaniment
1307 @cindex interpretation context
1308 @cindex notation context
1311 Normally, the notes that you enter are transformed into note heads.
1312 Note heads alone make no sense, they need surrounding information: a key
1313 signature, a clef, staff lines, etc. They need @emph{context}. In
1314 LilyPond, these symbols are created by objects called `interpretation
1315 contexts'. Interpretation contexts exist for generating notation
1316 (`notation context') and for generating sound (`performance
1317 context'). These objects only exist during a run of LilyPond.
1319 When LilyPond interprets music, it will create a Staff context. If
1320 the @code{%} sign in the previous line were removed, you could see
1321 that mechanism in action.
1323 We don't want that default here, because we want chord names. The
1324 command above explicitly creates an interpretation context of
1325 @code{ChordNames} type to interpret the music @code{\accompaniment}.
1330 \context Staff = mel @{
1334 We place the melody on a staff called @code{mel}. We give it a name to
1335 differentiate it from the one that would contain note heads for the
1336 chords, if you would remove the comment before the ``note heads''
1337 version of the accompaniment. By giving this staff a name, it is
1338 forced to be different.
1342 \property Staff.autoBeaming = ##f
1346 @cindex context variables
1347 @cindex setting context variables
1348 An interpretation context has variables, called properties, that tune
1349 its behavior. One of the variables is @code{autoBeaming}. Setting
1350 this @code{Staff}'s property to @code{##f}, which is the boolean value
1351 @var{false}, turns the automatic beaming mechanism off for the current
1362 Finally, we put the melody on the current staff. Note that the
1363 @code{\property} directives and @code{\melody} are grouped in sequential
1364 music, so the property settings are done before the melody is
1370 \midi @{ \tempo 4=72@}
1373 MIDI (Musical Instrument Digital Interface) is a standard for
1374 connecting and recording digital instruments. So a MIDI file is like a
1375 tape recording of an instrument. The @code{\midi} block makes the
1376 music go to a MIDI file, so you can listen to the music you entered. It
1377 is great for checking the music. Whenever you hear something weird, you
1378 probably hear a typing error.
1380 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
1381 also specifies an output method. You can specify the tempo using the
1382 @code{\tempo} command, in this case the tempo of quarter notes is set to
1383 72 beats per minute.
1387 \paper @{ linewidth = 10.0\cm @}
1390 We also want notation output. The linewidth is short so the piece
1391 will be set in two lines.
1394 @section More stanzas
1399 If you have multiple stanzas printed underneath each other, the vertical
1400 groups of syllables should be aligned around punctuation. LilyPond can
1401 do this if you tell it which lyric lines belong to which melody.
1402 We show how you can do this by showing how you could print a frivolous
1403 fragment of a fictional Sesame Street duet.
1405 @lilypond[singleline,verbatim]
1408 \notes \relative c'' \context Voice = duet { \time 3/4
1410 \lyrics \context Lyrics <
1411 \context LyricsVoice = "duet-1" {
1412 \property LyricsVoice . stanza = "Bert"
1413 Hi, my name is bert. }
1414 \context LyricsVoice = "duet-2" {
1415 \property LyricsVoice . stanza = "Ernie"
1416 Ooooo, ch\'e -- ri, je t'aime. }
1421 To this end, give the Voice context an identity, and set the
1422 LyricsVoice to a name starting with that identity followed by a dash.
1423 In the following example, the Voice identity is @code{duet},
1425 \context Voice = duet @{
1430 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1432 \context LyricsVoice = "duet-1" @{
1433 Hi, my name is bert. @}
1434 \context LyricsVoice = "duet-2" @{
1435 Ooooo, ch\'e -- ri, je t'aime. @}
1438 We add the names of the singers. This can be done by setting
1439 @code{LyricsVoice.Stanza} (for the first system) and
1440 @code{LyricsVoice.stz} for the following systems. Notice how you must
1441 surround dots with spaces in @code{\lyrics} mode.
1444 \property LyricsVoice . stanza = "Bert"
1446 \property LyricsVoice . stanza = "Ernie"
1450 @node More movements
1451 @section More movements
1453 LilyPond only handles formatting sheet music. It doesn't concern
1454 itself with producing titles. This is the jobs of a simple wrapper
1455 program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
1456 sheet music formatting. Then it produces titles, and ties together all
1457 inputs into a single @file{dvi} file. In this section, we show some of
1458 the options for titling. We will show how you can produce a file
1459 that looks like this:
1461 @center @strong{Two miniatures}
1471 \paper { linewidth = -1.0 }
1483 \paper { linewidth = -1.0 }
1487 For example, consider the following file (@file{miniatures.ly})
1492 title = "Two miniatures"
1493 composer = "F. Bar Baz"
1494 tagline = "small is beautiful" @}
1496 \paper @{ linewidth = -1.0 @}
1500 Mental note: discuss Schenkerian analysis of these key pieces.
1506 \notes @{ c'4 d'4 @}
1512 \notes @{ d'4 c'4 @}
1519 The information for the global titling is in a so-called header block.
1520 The information in this block is not used by
1521 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
1522 information to print titles above the music.
1524 @cindex identifier assignment
1525 the @code{\header} block contains assignments. In each assignment, a
1526 variable is set to a value. The header block for this file looks like
1528 @cindex @code{\header}
1531 title = "Two miniatures"
1532 composer = "F. Bar Baz"
1533 tagline = "small is beautiful"
1537 When you process a file with ly2dvi, a signature line is printed at
1538 the bottom of the last page. This signature is produced from the
1539 @code{tagline} field of @code{\header}. The default "Lily was here,
1540 @var{version number}" is convenient for us programmers. Archived
1541 the layout of different versions can be compared using archived
1542 print-outs (that include a version number).
1544 Many people find the default tagline too droll. If that is the case,
1545 assign something else to @code{tagline}, as shown above.
1553 A paper block at top level, i.e. not in a @code{\score} block sets the
1554 default page layout. The following @code{\score} blocks don't have
1555 @code{\paper} sections, so the settings of this block are substituted:
1557 The variable @code{linewidth} normally sets the length of the systems
1558 on the page. However, a negative value has a special meaning. If
1559 @code{linewidth} is less than 0, no line breaks are inserted into the
1560 score, and the spacing is set to natural length: a short phrase takes
1561 up little space, a longer phrase more space.
1566 Mental note: discuss Schenkerian analysis of these key pieces.
1571 Mental notes to yourself can be put into comments. There are two types
1572 of comments. Line comments are introduced by @code{%}, and block
1573 comments are delimited by @code{%@{} and @code{%@}}.
1578 \notes @{ c'4 d'4 @}
1581 In previous examples, notes were specified in relative octaves,
1582 i.e. each note was put in the octave that is closest to its
1583 predecessor. Besides relative, there is also absolute octave
1584 specification, which you get when you don't specify @code{\relative}. In
1585 this input mode, the central C is denoted by @code{c'}. Going down, you
1586 get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
1589 When you're copying music from existing sheet music, relative octaves
1590 are probably the easiest to use: it's less typing work and errors are
1591 easily spotted. However, if you write LilyPond input directly, either by
1592 hand (i.e. composing) or by computer, absolute octaves may be easier to use.
1600 The @code{\header} is normally at the top of the file, where it sets
1601 values for the rest of the file. If you want to typeset different pieces
1602 from one file (for example, if there are multiple movements, or if
1603 you're making an exercise book), you can put different @code{\score}
1604 blocks into the input file. ly2dvi will assemble all LilyPond output
1605 files into a big document. The contents of \header blocks specified
1606 within each score, are used for the titling of each movement.
1612 For example, the Opus number is put at the right, and the piece string
1613 will be at the left.
1620 title = "Two miniatures"
1621 composer = "F. Bar Baz"
1622 tagline = "small is beautiful" @}
1624 \paper @{ linewidth = -1.0 @}
1627 \notes @{ c'4 d'4 @}
1633 \notes @{ d'4 c'4 @}
1645 Lilypond and its language are still under development, and
1646 occasionally, details of the syntax are changed. This fragment
1647 indicates for which version the input file was written. When you
1648 compile this file, the version number will be checked, and you will
1649 get a warning when the file is too old. This version number is also
1650 used by the @code{convert-ly} program (See @ref{Older
1651 LilyPond versions}), which is used to update the file to the latest
1655 @node A piano excerpt
1656 @section A piano excerpt
1658 Our fourth subject is a piece of piano music. The fragment in the
1659 input file is a piano reduction of the G major Sinfonia by Giovanni
1660 Battista Sammartini. It was composed around 1740. It's in the source
1661 package under the name @file{sammartini.ly}.
1663 @lilypondfile[verbatim]{sammartini.ly}
1665 As you can see, this example features multiple voices on one staff. To
1666 make room for those voices, their notes have to be stemmed in opposite
1669 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1670 with some other commonly used formatting instructions, but to explain how
1671 it works, we wrote our own here. Of course, you should use predefined
1672 identifiers like these if possible: then you will be affected less by
1673 the implementation changes we occasionally make.
1677 viola = \notes \relative c' \context Voice = viola @{
1679 In this example, you can see multiple parts on a staff. Each part is
1680 associated with one notation context. This notation context handles
1681 stems and dynamics (among others). The type name of this context is
1682 @code{Voice}. For each part we have to make sure that there is
1683 precisely one @code{Voice} context, so we give it a unique name
1690 The delimiters @code{<} and @code{>} are shorthands for
1691 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1692 @code{<} and @code{>} is a chord.
1696 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1704 We want the viola to have stems down, and have all the other
1705 characteristics of a second voice. This is enforced using the
1706 @code{\voiceTwo} command: it inserts instructions that makes stem,
1707 ties, slurs, etc. go down.
1715 Relative octaves work a little differently with chords. The starting
1716 point for the note following a chord is the first note of the chord. So
1717 the @code{g} gets an octave up quote: it is a fifth above the starting
1718 note of the previous chord (the central C).
1724 @code{s} is a spacer rest. It does not print anything, but it does have
1725 the duration of a rest. It is useful for filling up voices that
1726 temporarily don't play. In this case, the viola doesn't come until one
1727 and a half measure later.
1731 oboes = \notes \relative c'' \context Voice = oboe @{
1733 Now comes a part for two oboes. They play homophonically, so we
1734 print the notes as one voice that makes chords. Again, we insure that
1735 these notes are indeed processed by precisely one context with
1739 \voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
1742 The oboes should have stems up, so they should have stems up, to keep
1743 them from interfering with the staff-jumping bass figure.
1747 \grace <e8( g> < d4 )f> <c2 e>
1749 @cindex @code{\grace}
1752 @code{\grace} introduces grace notes. It takes one argument, in this
1753 case a chord. A slur is introduced starting from the @code{\grace}
1754 ending on the following chord.
1762 Tuplets are made with the @code{\times} keyword. It takes two
1763 arguments: a fraction and a piece of music. The duration of the piece
1764 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1765 of their notated duration, so in this case the fraction is 2/3.
1768 @{ <d8 f> <e g> <f a> @}
1770 The piece of music to be `tripletted' is sequential music containing
1777 At this point, the homophonic music splits into two rhythmically
1778 different parts. We can't use a sequence of chords to enter this, so
1779 we make a `chord' of sequences to do it. We start with the upper
1780 voice, which continues with upward stems:
1783 @{ \times 2/3 @{ a8 g c @} c2 @}
1790 The easiest way to enter multiple voices is demonstrated
1791 here. Separate the components of the voice (single notes or entire
1792 sequences) with @code{\\} in a simultaneous music expression. The
1793 @code{\\} separators split first voice, second voice, third voice, and
1796 As far as relative mode is concerned, the previous note is the
1797 @code{c'''2} of the upper voice, so we have to go an octave down for
1805 This ends the two-part section.
1809 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1814 @code{\stemBoth} ends the forced stem directions. From here, stems are
1815 positioned as if it were single part music.
1817 The bass has a little hoom-pah melody to demonstrate parts switching
1818 between staves. Since it is repetitive, we use repeats:
1821 hoomPah = \repeat unfold 8
1823 @cindex unfolded @code{\repeat}
1824 The unfolded repeat prints the notes in its argument as if they were
1825 written out in full eight times.
1828 \notes \transpose c' @{
1831 @cindex relative mode and transposing
1833 Transposing can be done with @code{\transpose}, which takes two arguments.
1834 The first specifies what central C should be transposed to. The second
1835 is the to-be-transposed music. As you can see, in this case, the
1836 transposition has no effect, as central C stays at central C.
1838 The purpose of this no-op is to protect it from being interpreted as
1839 relative notes. Relative mode can not be used together with
1840 transposition, so @code{\relative} will leave the contents of
1841 @code{\hoomPah} alone. We can use it without having to worry about
1842 getting the motive in a wrong octave.
1844 @cindex staff switch, manual
1845 @cindex cross staff voice, manual
1846 @cindex @code{\translator}
1849 \translator Staff = down
1852 \translator Staff = up
1856 Voices can switch between staves. Here you see two staff switching
1857 commands. The first one moves to the lower staff, the second one to
1858 the lower one. If you set stem directions explicitly (using the
1859 identifiers @code{\stemUp} and @code{\stemDown}.
1863 bassvoices = \notes \relative c' @{
1865 \autochange Staff \hoomPah \context Voice
1870 \translator Staff = down
1872 @cindex staff switch
1873 @cindex cross staff voice
1874 We want the remaining part of this melody on the lower staff, so we do a
1875 manual staff switch here.
1880 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1884 After skipping some lines, we see @code{~}. This mark makes ties. Note
1885 that ties and slurs are different things. A tie can only connect two
1886 note heads of the same pitch, whereas a slur can connect many chords
1893 A special context is needed to get cross staff beaming right. This
1894 context is called @code{PianoStaff}.
1897 \context Staff = bottom < \time 2/2 \clef bass
1899 The bottom staff must have a different clef.
1904 To make some more room on the line, the first (in this case the only)
1905 line is not indented. The line still looks very cramped, but that is due
1906 to the page layout of this document.
1912 * font-size, multi-stanza.
1914 * Simple part combining in a Hymn
1918 @node Fine tuning a piece
1919 @section Fine tuning a piece
1921 In this section, we show some ways to fine tune the final output of a
1922 piece. We do so using a single measure of a moderately complex piano
1923 piece: a Brahms intermezzo (opus 119, no. 1).
1924 @cindex Brahms, Johannes
1926 The code for the untuned example shows us some new things.
1928 @lilypondfile[verbatim]{brahms-original.ly}
1938 The crescendo is ended at the half note by the escaped exclamation
1941 Hairpin dynamics can be indicated using @code{\>} to start a
1942 decrescendo, and @code{\!} to end one. The crescendo is started using
1943 @code{\<} and also ended using @code{\!}. Absolute dynamics can be
1944 entered using @code{\p}, @code{\mf}, etc. All these commands apply to
1945 the complete chord where they are entered, but for syntactical
1946 reasons, they must be attached to one of the notes of the chord.
1948 @cindex fingering instructions
1950 Fingering indications are entered simply using @code{-@var{N}}, where
1953 Now that we have the basic piece of music entered, we want to fine
1954 tune it, so we get something that resembles the original printed
1955 edition by Schott/Universal Edition:
1957 @lilypondfile{brahms-tweaked.ly}
1959 @cindex tuning grob behavior
1961 The basic process that we follow is that we override defaults in the
1962 printing system. We do this by setting variables in so-called grobs.
1963 Printed symbols are internally represented by Graphical Objects
1964 (Grobs). Each grob is described by a bunch of settings. Every
1965 setting is a variable: it has a name, and you can assign a value to
1966 the variable. These setting determine the fonts, offsets, sub-routines
1967 to be called on the grob, etc. The initial values of these settings
1968 are set in the Scheme file @file{scm/grob-description.scm}.
1970 @cindex slur attachments
1972 We start with the slur: the slur in the upper part, running from the F
1973 sharp to the A, runs from stem to stem in the printed edition, while
1974 ours starts from the note head at the left. The following property
1975 setting forces all slurs to run from stem to stem (and not from or to
1979 \property Voice.Slur \set #'attachment = #'(stem . stem)
1982 More precisely, this command extends the definition of the @code{Slur}
1983 object in the current @code{Voice}. The variable @code{attachment} is
1984 set to the pair of symbols @code{'(stem . stem)}.
1986 Although this is useful information, it is not very helpful: the
1987 lilypond backend supports approximately 240 variables like
1988 @code{attachment}, each with their own meaning and own type
1989 (eg. number, symbol, list, etc). Besides slur, LilyPond has 80
1990 different types of Grobs, that may be created in 14 different context
1991 types besides Voice.
1993 @cindex internal documentation
1994 @cindex finding grobs
1995 @cindex grob descriptiosn
1997 The interesting information is how you can figure out which properties
1998 to tune for your own scores. To discover this, you must have a copy of
1999 the internals document. This is a set of HTML pages, which should be
2000 included if you run a binary distribution@footnote{You can also
2001 compile them by executing @code{make -C Documentation/user/
2002 out/lilypond-internals.html} in the source package.}. This document is
2003 also available on the web: go to the lilypond website, click
2004 ``Documentation: other'' on the side bar, click
2005 ``lilypond-internals'', under information for users.
2007 You might want to bookmark either the HTML files on disk, or the one
2008 on the web. One word of caution is in place here: the internals
2009 documentation is generated from the definitions that lily uses. For
2010 that reason, it is strongly tied to the version of LilyPond that you
2011 use. Before you proceed, please make sure that you are using the
2012 documentation that corresponds to the LilyPond version that you use.
2014 Suppose that you wanted to tune the behavior of the slur. The first
2015 step is to get some general information on slurs in lilypond. Turn to
2016 the index, and look up ``slur''. The section on slurs says
2018 The grob for this object is @internalsref{Slur}, generally in
2019 @internalsref{Voice} context.
2022 So the grob for this object is called @code{Slur}, and slurs are
2023 created in the @code{Voice} context. If you are reading this tutorial
2024 in the HTML version, then you can simply click Slur, otherwise, you
2025 must look it up the internal documentation: click ``grob overview'' ,
2026 and select ``slur'' (the list is alphabetical.)
2028 Now you get a list of all the properties that the slur object
2029 supports, along with their default values. Among the properties we
2030 find the @code{attachment} property with its default setting.
2031 The property documentation explains that the following setting will
2032 produce the desired effect:
2034 \property Voice.Slur \set #'attachment = #'(stem . stem)
2037 If you ran the previous example, you have unknowingly already used
2038 this kind of command. The @file{ly/property-init.ly} contains the
2039 definition of @code{\stemUp}
2041 stemUp = \property Voice.Stem \set #'direction = #1
2045 We also want to move around the fingering `3'. In the printed edition
2046 it is not above the stem, but a little lower, slightly left of the
2047 stem. From the user manual, we find that the associated grob is called
2048 @code{Fingering}, but how do we know if we should use @code{Voice} or
2049 @code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
2050 also deduce this information from the internals documentation: if you
2051 visit the documentation of @code{Fingering}, you will notice
2053 Fingering grobs are created by: Fingering_engraver
2058 Clicking @code{Fingering_engraver} will show you the documentation of
2059 the module responsible for interpreting the fingering instructions and
2060 translating them to a @code{Fingering} grob. Such a module is called
2061 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
2064 Fingering_engraver is part of contexts: Voice and TabVoice
2066 so tuning the settings for Fingering should be done using either
2068 \property Voice.Fingering \set @dots{}
2072 \property TabVoice.Fingering \set @dots{}
2075 Since the @code{TabVoice} is only used for tab notation, we see that
2076 the first guess @code{Voice} was indeed correct.
2078 @cindex setting grob properties
2079 @cindex @code{extra-offset}
2081 For shifting the fingering, we use the grob property
2082 @code{extra-offset}. The following command manually adds an offset to
2083 the object. We move it a little to the left, and 1.8 staff space
2086 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
2088 The @code{extra-offset} is a low-level feature: it moves around
2089 objects in the printout; the formatting engine is completely oblivious
2090 to these offsets. The unit of these offsets are staff-spaces.
2092 @cindex reverting grob properties
2093 @cindex undoing grob properties
2095 We only want to offset a single grob, so after the F-sharp, we must
2096 undo the setting. The technical term is to revert the grob property.
2098 \property Voice.Fingering \revert #'extra-offset
2101 @cindex property types
2102 @cindex translator properties
2103 @cindex grob properties
2104 @cindex music properties
2107 There is three different types of variables in LilyPond, something
2108 which is confusing at first (and for some, it stays like that).
2109 Variables such as @code{extra-offset} and @code{attachment} are called
2110 grob properties. They are something different from the translator
2111 properties, like @code{autoBeaming}. Finally, music expressions are
2112 internally also stored using properties, so-called music
2113 properties. You will encounter the latter type if you run Scheme
2114 functions on music using @code{\apply}.
2116 The second fingering instruction should be moved up a little, to avoid
2117 a collision with the slur. This could be achieved with
2118 @code{extra-offset}, but in this case, a simpler mechanism also
2119 works. We insert an empty text between the 5 and the note. The empty
2120 text pushes the fingering instruction away:
2122 a^" "^#'(finger "5")
2125 Lilypond tries to put fingering instructions closer to the notes as
2126 text instructions. To insert an empty text (@code{^" "}) between the
2127 finger and the note, we have disguised the fingering instruction as a
2128 text: @code{(finger "5")}.
2130 Normally, one would specify dynamics in a single voice, and start and
2131 end dynamics (such as @b{f} and @b{p}) will be aligned with
2132 hairpins. In this case, we want the decrescendo to be in a different
2133 place from the piano sign. We achieve this by putting the dynamic
2134 markings in different voices. The crescendo should be above the upper
2135 staff. This can be forced by the precooked command
2140 However, if you do that, the decrescendo will be too close to the
2141 upper voice, and collide with the stems. Looking at the manual for
2142 dynamics, we notice that ``Vertical positioning of these symbols is
2143 handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
2144 to the documentation of @code{DynamicLineSpanner}, we find that the
2145 @code{DynamicLineSpanner} supports several so-called
2146 `interfaces'. This grob not only puts dynamic objects next to the
2147 staff (@code{side-position-interface}), but it also groups dynamic
2148 objects (@code{axis-group-interface}), is considered a dynamic sign
2149 itself (@code{dynamic-interface}) and is a grob: it has the
2150 @code{grob-interface}, with all the variables that come with it.
2152 For the moment, we are interested in the side positioning:
2154 side-position-interface
2156 Position a victim object (this one) next to other objects (the
2157 support). In this case, the direction signifies where to put the
2158 victim object relative to the support (left or right, up or down?)
2160 Between the grob and its support (in this case: the notes in the voice
2161 going down), there should be more space. This space is controlled by
2162 @code{padding}, so we increase it.
2164 \property Voice.DynamicLineSpanner \override #'padding = #5.0
2167 This command is almost like the command for setting slur attachments,
2168 but subtly different in its details. Grob properties can be
2169 manipulated with two commands: @code{\override} extends the grob
2170 variables with a setting, and @code{\revert} releases this
2171 setting. This has a certain theoretical appeal: the operations are
2172 simple and symmetric. For practical use, it can be cumbersome. Both
2173 commands act like parentheses: you should carefully balance the use of
2174 @code{\override} and @code{\revert}. The @code{\set} command is more
2175 friendly: it first does a @code{\revert} followed by @code{\override}.
2177 Finally, Brahms uses music notation is a slightly unorthodox way. Ties
2178 usually happen only within one voice. In this piece, the composer
2179 gladly produces ties that jump voices. We deal with this by faking
2180 these ties: whenever we need such a tie, we insert a notehead in a
2181 different voice, and blank the stem. This is done in the following
2185 \property Voice.Stem \set #'transparent = ##t
2187 \property Voice.Stem \revert #'transparent
2190 Finally, the last tie is forced up using @code{\tieUp}.
2193 @node An orchestral score
2194 @section An orchestral score
2198 * Extracting an individual part::
2202 Our last two examples show a way to setup the music for an orchestral
2203 score. When typesetting a piece for several instruments, you'll want to
2204 create a conductor's full score, alongside several individual parts.
2206 LilyPond is well suited for this task. We will declare the music for
2207 each instrument individually, giving the music of each instrument its
2208 own name. These pieces of music are then combined in different
2209 @code{\score} blocks to produce different combinations of the score.
2211 This orchestral score example consists of three input files. In the
2212 first file, @file{os-music.ly}, we define the music for all
2213 instruments. This file will be used both for producing the score and
2214 the separate parts. Other files reference this file by doing
2215 @code{\include "os-music.ly"}.
2217 If you were to run LilyPond on this file, no printable output would be
2223 title = "Zo, goed lieverd?"
2224 subtitle = "How's, this babe?"
2233 Key = \notes \key as \major
2234 flautoI = \notes\relative c'' @{
2236 bes as bes as bes as bes as
2238 flautoII = \notes\relative c'' @{
2239 as8 bes as bes R1 d4 ~ d
2241 tromboI = \notes\relative c'' @{
2242 c4. c8 c8 c4. es4 r as, r
2244 tromboII = \notes\relative c'' @{
2245 as4. as8 as8 as4. R1*1/2 as4 es'
2247 timpani = \notes\relative c, @{
2248 \times 2/3 @{ f4 f f @}
2249 \times 4/5 @{ as8 as as as as @}
2252 corno = \notes\relative c' @{
2253 bes4 d f, bes d f, bes d
2257 We will not go through the input line by line, but only indicate and
2258 explain the new elements.
2265 \skip 2*4 \bar "|.";
2269 Declare setting to be used globally. The @code{\skip} command produces
2270 no output, but moves forward in time: in this case, the duration of a
2271 half note (@code{2}), and that four times (@code{*4}). This brings us
2272 to the end of the piece, and we can set the end bar.
2276 Key = \notes \key as \major
2278 Declare the key signature of the piece and assign it to the identifier
2279 @var{Key}. Later on, we'll use @code{\Key} for all staves except those
2280 for transposing instruments.
2282 @node The full score
2283 @subsection The full score
2286 The second file, @file{os-score.ly} reads the definitions of the first
2287 (@file{os-music.ly}), and defines the @code{\score} block for the full
2293 \include "os-music.ly"
2294 \include "paper13.ly"
2296 #(set! point-and-click line-column-location)
2297 #(define text-flat '((font-relative-size . -2)
2298 (music "accidentals--1")))
2303 \property Score.BarNumber \override #'padding = #3
2304 \context StaffGroup = woodwind <
2305 \context Staff = flauti <
2306 \property Staff.midiInstrument = #"flute"
2307 \property Staff.instrument = "2 Flauti"
2308 \property Staff.instr = "Fl."
2310 \context Voice=one @{ \voiceOne \flautoI @}
2311 \context Voice=two @{ \voiceTwo \flautoII @}
2314 \context StaffGroup = timpani <
2315 \context Staff = timpani <
2316 \property Staff.midiInstrument = #"timpani"
2317 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2318 \property Staff.instr = #"Timp."
2324 \context StaffGroup = brass <
2325 \context Staff = trombe <
2326 \property Staff.midiInstrument = #"trumpet"
2327 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
2328 \property Staff.instr = #`(lines "Tbe." "(C)")
2330 \context Voice=one \partcombine Voice
2331 \context Thread=one \tromboI
2332 \context Thread=two \tromboII
2334 \context Staff = corni <
2335 \property Staff.midiInstrument = #"french horn"
2336 \property Staff.instrument = #`(lines "Corno"
2337 (columns "(E" ,text-flat ")"))
2338 \property Staff.instr = #`(lines "Cor."
2339 (columns "(E" ,text-flat ")"))
2340 \property Staff.transposing = #3
2341 \notes \key bes \major
2342 \context Voice=one \corno
2347 indent = 15 * \staffspace
2348 linewidth = 60 * \staffspace
2349 textheight = 90 * \staffspace
2351 \HaraKiriStaffContext
2360 @center @strong{Zo, goed lieverd?}
2362 @center How's, this babe?
2370 @lilypondfile{os-score.ly}
2374 \include "os-music.ly"
2376 First, we need to include the music definitions we made in
2381 #(set! point-and-click line-column-location)
2384 This piece of Scheme code sets the Scheme variable
2385 @code{point-and-click} to the value @var{line-column-location} (which
2386 itself is a Scheme procedure).
2388 Editing input files can be complicated if you're working with large
2389 files: if you're digitizing existing music, you have to synchronize
2390 the .ly file, the sheet music on your lap and the sheet music on the
2391 screen. The point-and-click mechanism makes it easy to find the
2392 origin of an error in the LY file: when you view the file with Xdvi
2393 and click on a note, your editor will jump to the spot where that note
2394 was entered. For more information, see @ref{Point and click}.
2399 #(define text-flat '((font-relative-size . -2)
2400 (music "accidentals--1")))
2403 When naming the tuning of the french horn, we'll need a piece of text
2404 with a flat sign. LilyPond has a mechanism for font selection and
2405 kerning called Scheme markup text (See @ref{Text markup}). The flat
2406 sign is taken from the music font, and its name is @code{accidentals--1}
2407 (The natural sign is called @code{accidentals-0}). The default font is
2408 too big for text, so we select a relative size of @code{-2}.
2415 Of course, all staves are simultaneous and use the same global settings.
2419 \property Score.BarNumber \override #'padding = #3
2421 LilyPond prints bar numbers at the start of each line, but
2422 unfortunately, they end up a bit too close to the staff in this
2423 example. A bar number internally is a Grob called @var{BarNumber}.
2424 BarNumber Grobs can be manipulated through their
2425 @var{side-position-interface}. One of the properties of a
2426 @var{side-position-interface} that can be tweaked is the
2427 @var{padding}: the amount of extra space that is put between this Grob
2428 and other Grobs. We set the padding to three staff spaces.
2430 You can find information on all these kind of properties in LilyPond's
2431 automatically generated documentation in
2433 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
2436 the online documentation.
2441 \context StaffGroup = woodwind <
2442 \context Staff = flauti <
2444 A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
2445 hold one or more @code{Staff}'s, and will print a big bracket at the
2446 left of the score. Start a new staff group for the woodwind section
2447 (just the flutes in this case). Immediately after that, we start the
2448 staff for the two flutes, that also play simultaneously.
2452 \property Staff.midiInstrument = #"flute"
2454 Specify the instrument for MIDI output (see @ref{MIDI instrument
2459 \property Staff.instrument = "2 Flauti"
2460 \property Staff.instr = "Fl."
2462 And define the instrument names to be printed in the margin,
2463 @code{instrument} for the first line of the score, @code{instr} for the
2470 The flutes play in the default key.
2474 \context Voice=one @{ \voiceOne \flautoI @}
2475 \context Voice=two @{ \voiceTwo \flautoII @}
2477 Last come the actual flute parts. Remember that we're still in
2478 simultaneous mode. We name both voices differently, so that LilyPond
2479 will actually create two Voice contexts. The flute parts are simple, so
2480 we specify manually which voice is which: @code{\voiceOne} forces the
2481 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2489 Close the flutes staff and woodwind staff group.
2493 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2495 The timpani staff only shows a new piece of scheme markup, it sets two
2500 \context Voice=one \partcombine Voice
2501 \context Thread=one \tromboI
2502 \context Thread=two \tromboII
2504 You have seen the notation contexts Staff and Voice, but here's a new
2505 one: Thread. One or more Threads can be part of a Voice. The Thread
2506 takes care of note heads and rests, the Voice combine note heads onto a
2509 For the trumpets we use the automatic part combiner (see @ref{Automatic
2510 part combining}) to combine the two simultaneous trumpet parts onto the
2511 trumpet staff. Each trumpet gets its own Thread context, which must be
2512 named @code{one} and @code{two}). The part combiner makes these two
2513 threads share a Voice when they're similar, and splits the threads up
2514 when they're different.
2518 \property Staff.instrument = #`(lines "Corno"
2519 (columns "(E" ,text-flat ")"))
2521 The french horn has the most complex scheme markup name, made up of two
2522 lines of text. The second line has three elements (columns), the @code{(E},
2523 the flat sign @code{text-flat} that we defined before and a final @code{")"}.
2524 Note that we use a backquote instead of an ordinary quote at the
2525 beginning of the Scheme expression to be able to access the
2526 @code{text-flat} identifier, `unquoting' it with a @code{,}.
2530 \property Staff.transposing = #3
2532 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
2533 transpose this staff by three steps.
2535 Note how we can choose different tuning for entering, printing and
2536 playing, using @code{\transpose} and the MIDI Staff property
2541 \notes \key bes \major
2543 Therefore, it has a different key.
2547 indent = 15 * \staffspace
2548 linewidth = 60 * \staffspace
2550 We specify a big indent for the first line and a small linewidth for this
2555 Usually, LilyPond's predefined setup of notation contexts (Thread,
2556 Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
2557 want a different type of Staff context.
2561 \HaraKiriStaffContext
2565 In orchestral scores, it often happens that one instrument has only
2566 rests during one line of the score. The @code{HaraKiriStaffContext} can
2567 be used as a regular @code{StaffContext} drop-in and will take care of
2568 the automatic removing of empty staves.
2570 @node Extracting an individual part
2571 @subsection Extracting an individual part
2573 The third file, @file{os-flute-2.ly} also reads the definitions of the
2574 first (@file{os-music.ly}), and defines the @code{\score} block for the
2578 \include "os-music.ly"
2579 \include "paper16.ly"
2583 \property Score.skipBars = ##t
2584 \property Staff.midiInstrument = #"flute"
2590 instrument = "Flauto II"
2593 linewidth = 80 * \staffspace
2594 textheight = 200 * \staffspace
2602 @center @strong{Zo, goed lieverd?}
2604 @center How's, this babe?
2605 @center @emph{Flauto II}
2612 @lilypondfile{os-flute-2.ly}
2615 Because we separated the music definitions from the @code{\score}
2616 instantiations, we can easily define a second score with the music of
2617 the second flute. This then is the part for the second flute player.
2618 Of course, we make separate parts for all individual instruments.
2624 In this individual part the second flute has a whole staff for itself,
2625 so we don't want to force stem or tie directions.
2630 instrument = "Flauto II"
2633 The @code{\header} definitions were also read from @file{os-music.ly},
2634 but we need to set the instrument for this particular score.
2638 \property Score.skipBars = ##t
2640 In the conductor's full score, all bars with rests are printed, but for
2641 the individual parts, we want to contract pieces of consecutive empty
2642 bars. LilyPond will do this if Score's @var{skipBars} property to
2646 @node Integrating text and music
2647 @section Integrating text and music
2649 Sometimes, you might want to use music examples in a text that you are
2650 writing. For example, if you are writing a musicological treatise, a
2651 songbook, or (like us) the LilyPond manual. You can make such texts by
2652 hand, simply by importing a PostScript figure into your wordprocessor.
2653 However, there is a also an automated procedure:
2655 If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond
2656 code. A script called @code{lilypond-book} will extract the music
2657 fragments, run LilyPond on them, and put back the resulting notation.
2658 This utility program is described fully in the chapter @ref{Merging text
2659 and music with lilypond-book}. Here we show a small example. Since the
2660 example also contains explanatory text, we won't comment on the
2664 \documentclass[a4paper]@{article@}
2667 In a lilypond-book document, you can freely mix music and text. For
2670 \score @{ \notes \relative c' @{
2671 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2674 Notice that the music line length matches the margin settings of the
2677 If you have no \verb+\score+ block in the fragment,
2678 \texttt@{lilypond-book@} will supply one:
2684 In the example you see here, a number of things happened: a
2685 \verb+\score+ block was added, and the line width was set to natural
2686 length. You can specify many more options using \LaTeX style options
2689 \begin[verbatim,11pt,singleline,
2690 fragment,relative,intertext="hi there!"]@{lilypond@}
2694 \texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
2695 the default music size, \texttt@{fragment@} adds a score block,
2696 \texttt@{relative@} uses relative mode for the fragment, and
2697 \texttt@{intertext@} specifies what to print between the
2698 \texttt@{verbatim@} code and the music.
2700 If you include large examples into the text, it may be more convenient
2701 to put the example in a separate file:
2703 \lilypondfile[printfilename]@{sammartini.ly@}
2705 The \texttt@{printfilename@} option adds the file name to the output.
2710 Under Unix, you can view the results as follows.
2713 $ lilypond-book --outdir=out/ lilbook.tex
2714 lilypond-book (GNU LilyPond) 1.3.146
2715 Reading `input/tutorial/lilbook.tex'
2716 Reading `input/tutorial/sammartini.ly'
2717 @var{lots of stuff deleted}
2718 Writing `out/lilbook.latex'
2720 $ latex lilbook.latex
2721 @var{lots of stuff deleted}
2725 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2726 and running latex creates a lot of temporary files, and you wouldn't want
2727 those to clutter up your working directory. Hence, we have them created
2728 in a separate subdirectory.
2730 The result more or less looks like this:
2734 In a lilypond-book document, you can freely mix music and text. For
2737 \score { \notes \relative c' {
2738 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2741 Notice that the music line length matches the margin settings of the
2744 If you have no @code{\score} block in the fragment,
2745 @code{lilypond-book} will supply one:
2751 In the example you see here, a number of things happened: a
2752 @code{\score} block was added, and the line width was set to natural
2753 length. You can specify many more options using La@TeX{} style options
2756 @lilypond[verbatim,11pt,singleline,
2757 fragment,relative,intertext="hi there!"]
2761 @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2762 the default music size, @code{fragment} adds a score block,
2763 @code{relative} uses relative mode for the fragment, and
2764 @code{intertext} specifies what to print between the
2765 @code{verbatim} code and the music.
2767 If you include large examples into the text, it may be more convenient
2768 to put the example in a separate file:
2770 @lilypondfile[printfilename]{sammartini.ly}
2772 The @code{printfilename} option adds the file name to the output.
2773 @node End of tutorial
2774 @section End of tutorial
2776 That's all folks. From here, you can either try fiddling with input
2777 files, or you can read the reference manual. You can find more example
2778 files in @file{input} and @file{input/test}. You can also look at some
2779 real music. The website @uref{http://www.mutopiaproject.org} has many
2780 examples of real music typeset by LilyPond.
2788 this should be on mutopia website.
2793 @c waar deze info? is uiteindelijk wel handig, schat ik.
2796 If you have a big music project, or just a lot of LilyPond input files,
2797 all generated output from LilyPond, @TeX{} and metafont will clutter
2798 your working directory. LilyPond comes with a one-size-fits-all
2799 pre-cooked makefile that helps you manage producing output. It will
2800 produce all output in the directory @file{out} , generate and track
2801 dependencies. Also, it helps in preparing your submission to @ref{Mutopia
2808 cp /usr/share/lilypond/make/ly.make GNUmakefile
2809 cp /usr/share/doc/lilypond/examples/input/tutorial/minuet.ly .
2812 Generated out/minuet.ps for target minuet.
2815 Type @samp{make help} to see possible targets.
2818 @file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
2824 [TODO: rewrite completely.]
2827 * Songs with additional verses::