3 @c TODO: LilyPond Lilypond lilypond
9 LilyPond prints music from a specification that you, the user, supply.
10 You have to give that specification using a textual @emph{language}.
11 This chapter is a gentle introduction to that language.
13 This tutorial will demonstrate how to use Lilypond by presenting
14 examples of input along with resulting output. We will use English
15 terms for notation. In case you are not familiar with those, you may
16 consult the glossary that is distributed with LilyPond.
18 @cindex examples, tutorial
20 The examples discussed are included in the distribution, in the
21 subdirectory @file{input/tutorial/}@footnote{When we refer
22 to filenames, they are relative to the top directory of the source
23 package. In binary installations you should look in your doc section,
24 eg, @code{/usr/share/doc/lilypond1.3/examples/input/tutorial}
26 }. We recommend that you experiment with writing Lilypond input
27 yourself, to get a feel for how the program behaves.
30 * Running LilyPond:: Getting started
31 * The first tune:: The first tune
32 * Lyrics and chords:: Lyrics and chords
34 * A piano excerpt:: Piano music
35 * An orchestral score::
36 * Other ways to run LilyPond::
37 * Integrating text and music::
38 * end of tutorial:: The end
42 @node Running LilyPond
43 @section Running LilyPond
45 Before we dive into describing the input language of LilyPond, we first
46 show you through the procedure for getting notes on your screen and out
49 The first step is creating an input file. Using your favorite
50 text-editor, create @file{test.ly} containing
54 NOTE: if you're reading this, ie, the Texinfo source itself, test.ly
55 should of course contain:
65 \notes @{ c'4 e' g' @}
69 @unnumberedsubsec Unix
70 @cindex Unix, Running lilypond on
73 On unix, you invoke ly2dvi to compile your lilypond source file (you can
80 You will see the following on your screen:
84 Now processing: `/home/fred/ly/test.ly'
86 Interpreting music...[1]
87 Preprocessing elements...
88 Calculating column positions... [2]
89 paper output to test.tex...
94 PS output to test.ps...
95 DVI output to test.dvi...
98 The results of the ly2dvi run are a ``DeVice Independent'' file
99 (@file{test.dvi}) and a PostScript file (@file{test.ps}).
103 @cindex Viewing music
107 To view the @code{test.dvi} output, run Xdvi (you may omit the
114 You should see the following in a window next to some buttons.
121 When you're satisfied with the result, you can print the
127 If this does not make your printer produce a page of music, you should
128 look into installing and configuring ghostscript. Refer to
129 GhostScript's website at @uref{http://www.ghostscript.com}.
132 @cindex Printing output
137 @unnumberedsubsec Windows
141 * setting of env vars (TFMFONTS,MFINPUTS,TEXINPUTS)
143 * dvi viewer doesn't display postscript
147 @section The first tune
150 To demonstrate what LilyPond input looks like, we start off with a
151 full-fledged, yet simple example. It is a convoluted version
152 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
153 is included in the distribution as @file{menuet.ly}.
154 @cindex Bach, Johann Sebastian
157 % all text after a percent sign is a comment
158 % and is ignored by Lilypond
159 \include "paper16.ly"
162 \relative c'' \sequential {
167 d4 g,8 a b c d4 g, g |
168 e'4 c8 d e fis g4 g, g |
169 c4 d8( )c b a( )b4 c8 b a g |
170 a4 [b8 a] [g fis] g2. |
175 g4 e8 fis g d cis4 b8 cis a4 |
176 a8-. b-. cis-. d-. e-. fis-.
183 % standard settings are too wide for a book
189 We will analyse the input, line by line.
192 % all text after a percent sign is a comment
193 % and is ignored by Lilypond
195 The percent sign, @code{%}, introduces a line comment. You can also
196 comment out a block of several lines, by enclosing them in
197 @code{%@{} and @code{%@}}.
199 @cindex block comment
204 \include "paper16.ly"
207 @cindex @code{\include}
208 @cindex point, printer's
209 @cindex staff size setting
210 By default, LilyPond will typeset the music in a size such that each
211 staff is 20 point@footnote{A point is the standard measure of length for
212 printing; one point is 1/72.27 inch.} high. We want smaller
213 output (16 point staff height), so we must import the settings for that
214 size, which is done here.
221 Music is printed by combining a piece of music with directions for
222 outputting it. This combination is formed in the @code{\score} block.
229 Prepare LilyPond for accepting notes.
230 @cindex octaves, choosing
239 As we will see, each note is described by its note name, duration,
240 octave and possibly a chromatic alteration. In this setup, the octave
241 is indicated by using high quotes (@code{'}) and ``lowered quotes''
242 (commas: @code{,}). The central C is denoted by @code{c'}. The C one
243 octave higher is @code{c''}. One and two octaves below the central C is
244 denoted by @code{c} and @code{c,} respectively.
246 Even though a piece of music often spans a range of several octaves, it
247 mostly moves in small intervals. LilyPond has a special entry mode to
248 save typing in this situation. In this ``relative'' octave mode,
249 octaves of notes without quotes are chosen such that a note is as close
250 as possible (graphically, on the staff) to the preceding note. If you
251 add a high-quote an extra octave is added. A lowered quote (a comma)
252 will subtract an extra octave.
254 Because the first note has no predecessor,
255 you have to give the (absolute) pitch of the note to start with.
262 What follows is sequential music, i.e.,
263 @cindex sequential music
264 notes that are to be played and printed after each other.
271 @cindex time signature, setting
273 Set (or change) the time signature of the current piece: a 3/4 sign is
274 printed. The time signature setting is also used to generate bar lines
282 @cindex key signature, setting
284 Set (or change) the current key signature to G-major. Although in this
285 example, the @code{\key} command happened to be entered after the
286 @code{\time} command, in the output the time signature will be printed
287 after the key signature; LilyPond knows about music typesetting
295 The following piece of music is played twice. The first argument
296 indicates the type of repeat. In this case, @code{"volta"} means that
297 prima volta/secunda volta brackets are used for the alternative
298 endings---if there were any.
305 The subject of the repeat is again sequential music. Since
306 @code{\sequential} is such a common construct, a shorthand is provided:
307 just leave off @code{\sequential}, and the result is the same.
314 Two notes. The first note is a quarter note with relative pitch
315 @code{d}. The relative music was started with a @code{c''}, so the real
316 pitch of this note is @code{d''}. The duration of a note is designated
317 by a number; the @code{4} here represents a quarter note.
319 The second note is an eight note with relative pitch @code{g,}. The
320 pitch is taken relative to the previous @code{d''}, making this
321 note have real pitch @code{g'}. The @code{8} represents an eight note.
328 Two more notes, with pitch @code{a} and @code{b}. Because their
329 duration is the same as the @code{g,8}, there is no need to enter the
330 duration, but you may enter it anyway, i.e., @code{a4 b4}
339 @cindex errors, finding
340 Three more notes. The @code{|} character is a ``bar check''. LilyPond
341 will verify that bar checks are found at the start of a measure. This can
342 help you track down typing errors.
344 @cindex alteration, chromatic
345 @cindex chromatic alteration
352 So far, no notes were chromatically altered. Here is the first one that
353 is: @code{fis}. Lilypond by default uses Dutch@footnote{Note names are
354 available in several languages, but we find the Dutch names quite
355 convenient.} note names, and ``Fis'' is the Dutch note name for ``F
356 sharp''. However, there is no sharp sign in the output. The program
357 keeps track of key signatures, and will only print accidentals if they
360 For groups of eighth notes and shorter, LilyPond can determine how the
361 notes should form a beam. In this case, the 4 eights are automatically
366 c4 d8( )c b a( )b4 c8 b a g |
369 The beginning and ending notes of a slur are marked with parentheses,
370 @code{(} and @code{)} for start and end respectively. The line above
371 indicates two slurs. These slur markers (parentheses) are entered
372 between the slurred notes.
379 Automatic beaming can be overridden by inserting beam marks, @code{[}
380 and @code{]}. These beam markers (brackets) are put around the notes
388 @cindex augmentation dot
390 A period adds an augmentation dot to the note.
397 The end of the sequential music to be repeated. LilyPond will typeset a
405 Accidentals are printed whenever necessary: the first C sharp of the bar
406 will be printed with an accidental, the second one without.
410 a8-. b-. cis-. d-. e-. fis-.
414 You can enter articulation signs either in a verbose form or using a
415 shorthand. Here we demonstrate the shorthand: it is formed by a dash
416 and the character for the articulation to use, e.g. @code{-.} for
417 staccato as shown above.
425 Rests are denoted by the special notename @code{r}.
432 All articulations have a verbose form, like @code{\fermata}. The
433 command @code{\fermata} is not part of the core of the language, but it
434 is a shorthand for a more complicated description of a fermata symbol.
435 @code{\fermata} names that description and is therefore called an
438 @cindex @code{\fermata}
444 Here the music ends. LilyPond does not automatically typeset and end
445 bar, we must explicitely request one, using @code{"|."}.
455 The @code{\paper} block specifies how entered music should be converted
456 to notation output. Most of the details of the conversion (font sizes,
457 dimensions, etc.) have been taken care of, but to fit the output in this
458 document, it has to be narrower. We do this by setting the line width
459 to 14 centimeters (approximately 5.5 inches).
466 The last brace ends the @code{\score} block.
471 @node Lyrics and chords
472 @section Lyrics and chords
474 In this section we show how to typeset a song. This file is
475 included as @file{flowing.ly}.
479 title = "The river is flowing"
480 composer = "Traditional"
482 \include "paper16.ly"
483 melody = \notes \relative c' @{
487 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
488 c4 c8 d [es () d] c4 | d4 es8 d c4.
493 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
494 ri -- ver is flo -- wing down to the sea.
497 accompaniment =\chords @{
499 c2:3- f:3-.7 d:min es4 c8:min r8
500 c2:min f:min7 g:7^3.5 c:min @}
505 \context ChordNames \accompaniment
508 \context Staff = mel @{
509 \property Staff.noAutoBeaming = ##t
510 \property Staff.automaticMelismata = ##t
513 \context Lyrics \text
515 \midi @{ \tempo 4=72 @}
516 \paper @{ linewidth = 10.0\cm @}
521 The result would look this.@footnote{The titling and font size shown
522 may differ, since the titling in this document is not generated by
525 @center @strong{The river is flowing}
530 title = "The river is flowing"
531 composer = "Traditional"
533 \include "paper16.ly"
534 melody = \notes \relative c' {
538 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
539 c4 c8 d [es () d] c4 | d4 es8 d c4.
544 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
545 ri -- ver is flo -- wing down to the sea.
548 accompaniment =\chords {
550 c2:3- f:3-.7 d:min es4 c8:min r8
551 c2:min f:min7 g:7^3.5 c:min }
556 \context ChordNames \accompaniment
559 \context Staff = mel {
560 \property Staff.noAutoBeaming = ##t
561 \property Staff.automaticMelismata = ##t
564 \context Lyrics \text
566 \midi { \tempo 4=72 }
567 \paper { linewidth = 10.0\cm }
571 Again, we will dissect the file line by line.
578 @cindex @code{\header}
579 Information about the music you are about to typeset goes into a
580 @code{\header} block. The information in this block is not used by
581 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
582 information to print titles above the music.
586 title = "The river is flowing"
587 composer = "Traditional (?)"
590 @cindex identifier assignment
591 the @code{\header} block contains assignments. In each assignment, a
592 variable is set to a value. Lexically, both the variable name and the
593 assigned value are strings. The values have to be quoted here, because
594 they contain spaces, the variable names could also be put within quotes
595 but it is not necessary.
599 \include "paper16.ly"
602 Smaller size for inclusion in a book.
606 melody = \notes \relative c' @{
609 The structure of the file will be the same as the previous one, a
610 @code{\score} block with music in it. To keep things readable, we will
611 give names to the different parts of music, and use the names to
612 construct the music within the score block.
619 @cindex @code{\partial}
621 The piece starts with an anacrusis of one eighth.
626 The key is C minor: we have three flats.
631 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
632 c4 c8 d [es () d] c4 | d4 es8 d c4.
637 @cindex manual beaming
638 @cindex automatic beaming, turning off
639 We use explicit beaming. Since this is a song, we turn automatic
640 beams off, and use explicit beaming where needed.
647 This ends the definition of @code{melody}.
656 @cindex identifier assignment
657 @cindex syllables, entering
658 Another identifier assignment. This one is for the lyrics.
659 Lyrics are formed by syllables that have duration, and not by
660 notes. To make LilyPond parse words as syllables, switch it into
661 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
662 is a shorthand for @code{\sequential @{}.
666 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
667 ri- ver is flo- __ wing down to the sea.
671 @cindex extenders, lyric
672 @cindex hyphens, lyric
673 The syllables themselves are separated by spaces. You can get syllable
674 extenders by entering @code{__}, and centered hyphens with
675 @code{-}@code{-}. We enter the syllables as if they are all quarter notes
676 in length (hence the @code{4}), and use a feature to align the
677 syllables to the music, which obviously isn't all quarter notes.
681 accompaniment =\chords @{
686 We'll put chords over the music. To enter them, there is a special mode
687 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
688 the names of the chords you want, instead of listing the notes
689 comprising the chord.
696 There is no accompaniment during the anacrusis.
705 @cindex chord modifier
706 @cindex modifier, chord
707 A chord is started by the tonic of the chord. The
708 first one lasts a half note. An unadorned note creates a major
709 triad. Since a minor triad is wanted, @code{3-} is added to modify the
710 third to be small. @code{7} modifies (adds) a seventh, which is small by
711 default to create the @code{f a c es} chord. Multiple modifiers must be
720 Some modifiers have predefined names, eg. @code{min} is the same as
721 @code{3-}, so @code{d-min} is a minor @code{d} chord.
725 c2:min f:min7 g:7^3.5 c:min @}
728 @cindex named modifier
730 A named modifier @code{min} and a normal modifier @code{7} do not have
731 to be separated by a dot. Tones from a chord are removed with chord
732 subtractions. Subtractions are started with a caret, and they are
733 also separated by dots. In this example, @code{g:7^3.5} produces a
734 minor seventh. The brace ends the sequential music.
742 We assemble the music in the @code{\score} block. Melody, lyrics and
743 accompaniment have to sound at the same time, so they should be
744 @code{\simultaneous}.
745 @cindex @code{\simultaneous}
752 Chord mode generates notes grouped in @code{\simultaneous} music. If
753 you remove the comment sign, you can see the chords in normal
754 notation: they will be printed as note heads on a separate
755 staff. To print them as chords names, they have to be interpreted as
756 being chords, not notes. This is done with the following command:
760 \context ChordNames \accompaniment
764 @cindex interpretation context
765 @cindex notation context
768 Normally, the notes that you enter are transformed into note heads.
769 Note heads alone make no sense, they need surrounding information: a key
770 signature, a clef, staff lines, etc. They need @emph{context}. In
771 LilyPond, these symbols are created by objects called `interpretation
772 contexts'. Interpretation contexts exist for generating notation
773 (`notation context') and for generating sound (`performance
774 context'). These objects only exist during a run of LilyPond.
776 By default, LilyPond will create a Staff context for you. If you would
777 remove the @code{%} sign in the previous line, you would see that
780 We don't want that default here, because we want chord names. The
781 command above explicitly creates an interpretation context of
782 @code{ChordNames} type to interpret the music @code{\accompaniment}.
789 @cindex @code{\addlyrics}
790 @cindex lyrics and melody, combining
791 @cindex combining lyrics and melody
793 The lyrics should be aligned with the melody. This is done by
794 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
795 pieces of music (usually a melody and lyrics, in that order) and
796 aligns the syllables of the second piece under the notes of the
797 first piece. If you would reverse the order, the notes would be
798 aligned on the lyrics, which is not very useful, and looks
803 \context Staff = mel @{
807 The second argument of @code{\addlyrics} is the melody. We instantiate
808 a @code{Staff} context explicitly: should you choose to remove the
809 comment before the ``note heads'' version of the accompaniment, the
810 accompaniment will be on a nameless staff. The melody has to be on
811 staff different from the accompaniment. This is accomplished by giving
812 the melody and accompaniment staffs different names.
816 \property Staff.noAutoBeaming = ##t
820 @cindex context variables
821 @cindex setting context variables
822 An interpretation context has variables, called properties, that tune
823 its behaviour. One of the variables is @code{noAutoBeaming}. Setting
824 this Staff's property to @code{##t}, which is the boolean value @var{true},
825 turns the automatic beaming mechanism off for the current staff.
828 @cindex accessing Scheme
829 @cindex evaluating Scheme
832 LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
833 language from the LISP family. You can learn more about Scheme at
834 @uref{http://www.scheme.org}. It is used to represent data throughout
835 the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
836 code following the hash-sign is evaluated as Scheme. The boolean value
837 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
840 If Scheme scares you, don't worry. You don't need to know Scheme to
841 create beautiful sheet music.
848 \property Staff.automaticMelismata = ##t
851 @cindex automaticMelismata
853 @cindex @code{\addlyrics} and slurs
854 Similarly, we don't want to print a syllable when there is
855 a slur. This sets up @code{\addlyrics} to not put lyrics under each
856 separate note while there is a slur.
864 Finally, we put the melody on the current staff. Note that the
865 @code{\property} directives and @code{\melody} are grouped in sequential
866 music, so the property settings are done before the melody is
871 \context Lyrics \text
874 The second argument of @code{\addlyrics} is the text. The text also
875 should not land on a Staff, but on a interpretation context for
876 syllables, extenders, hyphens etc. This context is called
881 \midi @{ \tempo 4=72@}
884 MIDI (Musical Instrument Digital Interface) is a standard for
885 connecting and recording digital instruments. So a MIDI file is like a
886 tape recording of an instrument. The @code{\midi} block causes makes the
887 music go to a MIDI file, so you can listen to the music you entered. It
888 is great for checking the music. Whenever you hear something weird, you
889 probably hear a typing error.
891 Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
892 also specifies an output method. You can specify the tempo using the
893 @code{\tempo} command, in this case the tempo of quarter notes is set to
898 \paper @{ linewidth = 10.0\cm @}
901 We also want notation output. The linewidth is short so the piece
902 will be set in two lines.
905 @section More movements
907 [FIXME: merge here with, or move this to: Other ways to run LilyPond]
909 You probably ran @file{ly2dvi} on the last example, and ended up with a
910 viewable @file{.dvi} file. However, between there are a few steps of
911 which LilyPond is only one. To enhance your understanding of what's
912 happening under the hood when you run @code{ly2dvi}, we explain what
915 @code{ly2dvi} is a program that calls a number of programs in sequence.
916 The first thing it does, is running LilyPond on the input file. After
917 some calculations, a @file{.tex} is produced. The contents
918 of this file are very low-level instructions.
920 For example, the following file (@file{miniatures.ly})
924 \header @{ title = "Two miniatures" @}
926 #(set! point-and-click line-column-location)
928 \paper @{ linewidth = -1.0 @}
944 The titling in this manual was not generated by ly2dvi, so we can't
945 exactly show it would look, but the result should resemble this:
947 @center @strong{Two miniatures}
957 \paper { linewidth = -1.0 }
969 \paper { linewidth = -1.0 }
973 This file is produced by ly2dvi in a few stages, with the help of text
974 formatting tools. LilyPond produces two output files, @file{miniatures.tex}
975 and @file{miniatures-1.tex}. They both look like this:
979 \placebox@{-5 \outputscale @}%
980 @{ 8.7229 \outputscale @}%
981 @{\magfontWXGEomMMBo\char90 @}%
983 \placebox@{-4 \outputscale @}%
984 @{ 81.0647 \outputscale @}%
988 @file{ly2dvi} looks at what output LilyPond produces, and generates a
989 file called @file{ly2dvi.out.tex}. This file contains formatting
990 instructions for the title and page layout. A fragment might look like
994 \def\lilypondopus@{Opus 1.@}
995 \def\lilypondpiece@{Up@}
996 \def\mustmakelilypondtitle@{@}
997 \input miniatures.tex
998 \def\lilypondtitle@{Two miniatures@}
1002 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
1003 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
1004 is successful, this will produce a @file{.dvi} file, containing both the
1005 titling and the actual music. @code{ly2dvi} completes its task by
1006 deleting the two temporary files, leaving only @file{miniatures.dvi}.
1008 Next, now we'll look at the example line by line to explain new things.
1014 Lilypond and its language are still under development, and occasionally,
1015 details of the syntax are changed. This fragment indicates for which
1016 version the input file was written. When you compile this file, the
1017 version number will be checked, and you will get a warning when the file
1020 This version number is also used by the @code{convert-ly} program (See
1021 @ref{convert-ly}), which uses it to update the file to the latest lily
1026 \header @{ title = "Two miniatures" @}
1028 This sets the titling information for the entire file.
1032 #(set! point-and-click line-column-location)
1035 This piece of Scheme code sets the Scheme variable
1036 @code{point-and-click} to the value @var{line-column-location} (which
1037 itself is a Scheme procedure).
1039 Editing input files can be quite complicated if you're working with
1040 large files: if you're digitizing existing music, you have to
1041 synchronize the .ly file, the sheet music on your lap and the sheet
1042 music on the screen. The point-and-click mechanism makes it easy to
1043 find the origin of an error in the .ly file: when you view the file with
1044 Xdvi and click on a note, your editor will jump to the spot where that
1045 note was entered. For more information, see @ref{Point and click}.
1052 The @code{\score} blocks that follow in the file don't have
1053 @code{\paper} sections, so the settings of this block are substituted: A
1054 paper block, at top-level, i.e. not in a @code{\score} block sets the
1055 default page layout.
1064 The variable @code{linewidth} normally sets the length of the systems on
1065 the page. However, a negative value has a special meaning. If
1066 @code{linewidth} is less than 0, no line breaks are inserted into the
1067 score, and the spacing is set to natural length: a short phrase takes up
1068 little space, a longer phrase more space.
1073 \notes @{ c'4 d'4 @}
1076 In previous examples, notes were specified in relative octaves,
1077 i.e. each note was put in the octave that would put it closest to its
1078 predecessor. Besides relative, there is also absolute octave
1079 specification, which you get when you don't specify @code{\relative}. In
1080 this input mode, the central C is denoted by @code{c'}. Going down, you
1081 get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
1084 When you're copying music from existing sheet music, relative octaves
1085 are probably the easiest to use: it's less typing work and errors are
1086 easily spotted. However, if you write LilyPond input, either by hand
1087 (ie. composing) or by computer, absolute octaves are probably less work.
1095 The @code{\header} is normally at the top of the file, where it sets
1096 values for the rest of the file. If you want to typeset different pieces
1097 from one file (for example, if there are multiple movements, or if
1098 you're making an exercise book), you can put different @code{\score}
1099 blocks into the input file. ly2dvi will assemble all LilyPond output
1100 files into a big document. The contents of \header blocks specified
1101 within each score, are used for the titling of each movement.
1107 For example, the Opus number is put at the right, and the piece string
1108 will be at the left.
1112 @node A piano excerpt
1113 @section A piano excerpt
1115 Our fourth subject is a piece of piano music. The fragment in the input
1116 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1117 Sammartini. It was composed around 1740. It's in the source package
1118 under the name @file{sammartini.ly}.
1121 \include "paper16.ly"
1123 stemDown = \property Voice.Stem \override #'direction = #-1
1124 stemUp = \property Voice.Stem \override #'direction = #1
1125 stemBoth = \property Voice.Stem \revert #'direction
1127 viola = \notes \relative c' \context Voice = viola {
1128 <c4-\f-\arpeggio g' c>
1134 oboes = \notes \relative c'' \context Voice = oboe {
1135 \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1136 \grace <e8( g> <d4 )f> <c2 e>
1137 \times 2/3 { <d8 \< f> <e g> <f a> }
1139 { \times 2/3 { a8 g c } \! c2 }
1140 \context Voice = oboeTwo {
1143 \property Grace.Stem \override #'direction = #-1
1149 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1150 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1151 [<c16( e> < )e8. g>] <c8 e,>
1154 hoomPah = \repeat unfold 8 \notes
1155 \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }
1157 bassvoices = \notes \relative c' {
1159 \autochange Staff \hoomPah
1160 \translator Staff = down
1161 \stemDown [c8 c'8] r4
1163 < {\stemUp r2 <e4 c'> <c8 g'> }
1164 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
1168 \context PianoStaff \notes <
1169 \context Staff = up < \time 2/2
1173 \context Staff = down < \time 2/2 \clef bass
1180 linewidth = 15.0 \cm }
1184 If this looks like incomprehensible gibberish to you, you are right.
1185 This example has been doctored to have as many quirks as possible.
1187 As you can see, this example features multiple voices on one staff. To
1188 make room for those voices, their notes have to be stemmed in opposite
1191 Printed symbols are internally represented by so-called Graphical
1192 Objects (more colloquially: Grobs). These statements concern the
1193 grob called `Stem'. Each grob is described by a bunch of settings. These
1194 setting determine the fonts, offsets, sub-routines to be called on the
1195 grob, etc. The initial values of these settings are set in the Scheme
1196 file @file{scm/grob-description.scm}.
1200 stemDown = \property Voice.Stem \override #'direction = #-1
1203 Set a proprerty for all Stem grobs in the current Voice:
1204 @code{direction} is set to @code{-1}, which encodes down. The setting
1205 remains in effect until it is reverted.
1209 \property Voice.Stem \revert #'direction
1212 Revert the to the previous setting. The effect of precisely one
1213 @code{\stemDown} or @code{\stemUp} is neutralised.
1216 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1217 with some other commonly used formatting instructions, but to explain how
1218 it works, we wrote our own here. Of course, you should use predefined
1219 identifiers like these if possible: then you will be affected less by
1220 the implementation changes we occasionally make.
1224 viola = \notes \relative c' \context Voice = viola @{
1226 In this example, you can see multiple parts on a staff. Each part is
1227 associated with one notation context. This notation context handles
1228 stems and dynamics (among others). The name of this context is
1229 @code{Voice}. For each part we have to make sure that there is
1230 precisely one @code{Voice} context, so we give it an unique name
1235 <c4-\f-\arpeggio g' c>
1237 The delimiters @code{<} and @code{>} are shorthands for
1238 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1239 @code{<} and @code{>} is a chord.
1246 @code{\f} places a forte symbol under the chord. The forte applies to
1247 the whole chord, but the syntax requires that commands like forte and
1248 arpeggio are attached to a note, so here we attach them to the first
1251 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
1264 Relative octaves work a little differently with chords. The starting
1265 point for the note following a chord is the first note of the chord. So
1266 the @code{g} gets an octave up quote: it is a fifth above the starting
1267 note of the previous chord (the central C).
1273 @code{s} is a spacer rest. It does not print anything, but it does have
1274 the duration of a rest. It is useful for filling up voices that
1275 temporarily don't play. In this case, the viola doesn't come until one
1276 and a half measure later.
1280 oboes = \notes \relative c'' \context Voice = oboe @{
1282 Now comes a part for two oboes. They play homophonically, so we
1283 print the notes as one voice that makes chords. Again, we insure that
1284 these notes are indeed processed by precisely one context with
1288 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1290 @code{\stemUp} is a reference to the @code{\property \override} command
1294 \grace <e8 g> < d4 f> <c2 e>
1296 @cindex @code{\grace}
1300 @code{\grace} introduces grace notes. It takes one argument, in this
1304 The slur started on the @code{e} of the chord
1305 will be attached to the next note.@footnote{LilyPond will squirm
1306 about unended Slurs. In this case, you can ignore the warning}.
1314 Tuplets are made with the @code{\times} keyword. It takes two
1315 arguments: a fraction and a piece of music. The duration of the piece
1316 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1317 of their notated duration, so in this case the fraction is 2/3.
1320 @{ <d8 \< f> <e g> <f a> @}
1322 The piece of music to be `tripletted' is sequential music containing
1323 three notes. On the first chord, a crescendo is started with
1324 @code{\<}. To be precise, the crescendo start is syntactically attached
1325 to the preceding note, the @code{d}.
1335 At this point, the homophonic music splits into two rhythmically
1336 different parts. We can't use a sequence of chords to enter this, so
1337 we make a `chord' of sequences to do it. We start with the upper
1338 voice, which continues with upward stems:
1341 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1346 The crescendo is ended at the half note by the escaped exclamation
1350 \context Voice = oboeTwo @{
1353 We can't share stems with the other voice, so we have to create a new
1354 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1355 it from the other context. Stems go down in this voice.
1360 @cindex Grace context
1361 When a grace section is processed, a @code{Grace} context is
1362 created. This context acts like a miniature score of its own. It has
1363 its own time bookkeeping, and you can make notes, beams, slurs
1364 etc. Here we fiddle with a property and make a beam. The argument of
1365 @code{\grace} is sequential music.
1369 \property Grace.Stem \override #'direction = #-1
1373 Normally, grace notes are always stem up, but in this case, the upper
1374 voice interferes. We set the stems down here.
1376 As far as relative mode is concerned, the previous note is the
1377 @code{c'''2} of the upper voice, so we have to go an octave down for
1385 This ends the two-part section.
1389 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1394 @code{\stemBoth} ends the forced stem directions. From here, stems are
1395 positioned as if it were single part music.
1397 The bass has a little hoom-pah melody to demonstrate parts switching
1398 between staffs. Since it is repetitive, we use repeats:
1401 hoomPah = \repeat unfold 8
1403 @cindex unfolded @code{\repeat}
1404 The unfolded repeat prints the notes in its argument as if they were
1405 written out in full eight times.
1408 \notes \transpose c' @{
1411 @cindex relative mode and transposing
1413 Transposing can be done with @code{\transpose}. It takes two arguments
1414 the first specifies what central C should be transposed to. The second
1415 is the to-be-transposed music. As you can see, in this case, the
1416 transposition has no effect, as central C stays at central C.
1418 The purpose of this no-op is circumventing relative mode. Relative mode
1419 can not be used together with transposition, so @code{\relative} will
1420 leave the contents of @code{\hoomPah} alone. We can use it without
1421 having to worry about getting the motive in a wrong octave.
1424 bassvoices = \notes \relative c' @{
1426 \autochange Staff \hoomPah
1428 @cindex staff switch, automatic
1429 @cindex cross staff voice, automatic
1430 @cindex @code{\autochange}
1432 Voices can switch between staffs. The easiest way to get this, is to use
1433 @code{\autochange}. This command looks at the pitch of each note, and if
1434 necessary, will cross to the other staff. For this to work, the two
1435 staffs must be called @code{"up"} and @code{"down"}.
1438 \translator Staff = down
1440 @cindex staff switch
1441 @cindex cross staff voice
1442 We want the remaining part of this melody on the lower staff, so we do a
1443 manual staff switch here.
1448 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1452 After skipping some lines, we see @code{~}. This mark makes ties. Note
1453 that ties and slurs are different things. A tie can only connect two
1454 note heads of the same pitch, whereas a slur can connect many chords
1461 A special context is needed to get cross staff beaming right. This
1462 context is called @code{PianoStaff}.
1465 \context Staff = bottom < \time 2/2 \clef bass
1467 The bottom staff must have a different clef.
1472 To make some more room on the line, the first (in this case the only)
1473 line is not indented. The line still looks very cramped, but that is due
1474 to the page layout of this document.
1480 * font-size, multi-stanza.
1482 * Simple part combining in a Hymn
1486 @node An orchestral score
1487 @section An orchestral score
1491 * Extracting an individual part::
1495 Our last two examples show a way to setup the music for an orchestral
1496 score. When typesetting a piece for several instruments, you'll want to
1497 create a conductor's full score, alongside several individual parts.
1499 LilyPond is well suited for this task. We will declare the music for
1500 each instrument individually, giving the music of each instrument its
1501 own name. These pieces of music are then combined in different
1502 @code{\score} blocks to produce different combinations of the score.
1504 This orchestral score example consists of three input files. In the
1505 first file, @file{os-music.ly}, we define the music for all instruments.
1506 This file will be used both for producing the score and the separate
1509 If you were to run lilypond on this file, no printable output would be
1515 title = "Zo, goed lieverd?"
1516 subtitle = "How's, this babe?"
1525 Key = \notes \key as \major
1526 flautoI = \notes\relative c'' @{
1528 bes as bes as bes as bes as
1530 flautoII = \notes\relative c'' @{
1531 as8 bes as bes R1 d4 ~ d
1533 tromboI = \notes\relative c'' @{
1534 c4. c8 c8 c4. es4 r as, r
1536 tromboII = \notes\relative c'' @{
1537 as4. as8 as8 as4. R1*1/2 as4 es'
1539 timpani = \notes\relative c, @{
1540 \times 2/3 @{ f4 f f @}
1541 \times 4/5 @{ as8 as as as as @}
1544 corno = \notes\relative c' @{
1545 bes4 d f, bes d f, bes d
1549 We will not go through the input line by line, but only indicate and
1550 explain the new elements.
1557 \skip 2*4 \bar "|.";
1561 Declare setting to be used globally. The @code{\skip} command produces
1562 no output, but moves forward in time: in this case, the duration of a
1563 half note (@code{2}), and that four times (@code{*4}). This brings us
1564 to the end of the piece, and we can set the end bar.
1568 Key = \notes \key as \major
1570 Declare the key signature of the piece and assign it to the identifier
1571 @var{Key}. Lateron, we'll use @code{\Key} for all staffs except those
1572 for transposing instruments.
1574 @node The full score
1575 @subsection The full score
1578 The second file, @file{os-score.ly} reads the definitions of the first
1579 (@file{os-music.ly}), and defines the @code{\score} block for the full
1585 \include "os-music.ly"
1586 \include "paper13.ly"
1588 #(set! point-and-click line-column-location)
1589 #(define text-flat '((font-relative-size . -2)
1590 (music "accidentals--1")))
1595 \property Score.BarNumber \override #'padding = #3
1596 \context StaffGroup = woodwind <
1597 \context Staff = flauti <
1598 \property Staff.midiInstrument = #"flute"
1599 \property Staff.instrument = "2 Flauti"
1600 \property Staff.instr = "Fl."
1602 \context Voice=one @{ \voiceOne \flautoI @}
1603 \context Voice=two @{ \voiceTwo \flautoII @}
1606 \context StaffGroup = timpani <
1607 \context Staff = timpani <
1608 \property Staff.midiInstrument = #"timpani"
1609 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1610 \property Staff.instr = #"Timp."
1616 \context StaffGroup = brass <
1617 \context Staff = trombe <
1618 \property Staff.midiInstrument = #"trumpet"
1619 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
1620 \property Staff.instr = #`(lines "Tbe." "(C)")
1622 \context Voice=one \partcombine Voice
1623 \context Thread=one \tromboI
1624 \context Thread=two \tromboII
1626 \context Staff = corni <
1627 \property Staff.midiInstrument = #"french horn"
1628 \property Staff.instrument = #`(lines "Corno"
1629 (rows "(E" ,text-flat ")"))
1630 \property Staff.instr = #`(lines "Cor."
1631 (rows "(E" ,text-flat ")"))
1632 \property Staff.transposing = #3
1633 \notes \key bes \major
1634 \context Voice=one \corno
1639 indent = 15 * \staffspace
1640 linewidth = 60 * \staffspace
1641 textheight = 90 * \staffspace
1644 \consists "Multi_measure_rest_engraver"
1647 \HaraKiriStaffContext
1648 \remove "Multi_measure_rest_engraver"
1657 @center @strong{Zo, goed lieverd?}
1659 @center How's, this babe?
1667 @lilypondfile{os-score.ly}
1671 \include "os-music.ly"
1673 First, we need to include the music definitions we made in
1678 #(set! point-and-click line-column-location)
1680 In a large orchestral score like this you're bound to make some small
1681 mistakes, so we enable point and click (See @ref{Point and click})
1686 #(define text-flat '((font-relative-size . -2)
1687 (music "accidentals--1")))
1690 When naming the tuning of the french horn, we'll need a piece of text
1691 with a flat sign. LilyPond has a mechanism for font selection and
1692 kerning called Scheme markup text (See @ref{Text markup}). The flat
1693 sign is taken from the music font, and its name is @code{accidentals--1}
1694 (The sharp sign is called @code{accidentals-+1}). The default font is
1695 too big for text, so we select a relative size of @code{-2}.
1702 Of course, all staffs are simultaneous and use the same global settings.
1706 \property Score.BarNumber \override #'padding = #3
1708 LilyPond prints bar numbers at the start of each line, but
1709 unfortunately, they end up a bit too close to the staff in this example.
1710 A bar number internally is a Grob called @var{BarNumber}. BarNumber
1711 Grobs can be manipulated through their @var{side-position-interface}. One
1712 of the properties of a @var{side-position-interface} that can be tweaked
1713 is the @var{padding}: the amount of extra space that is put between this
1714 Grob and other Grobs. We set the padding to three staff spaces.
1716 You can find all this kind of information in LilyPond's automatically
1717 generated documentation in
1719 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
1722 the online documentation.
1727 \context StaffGroup = woodwind <
1728 \context Staff = flauti <
1730 A new notation context: the StaffGroup. StaffGroup can hold one or more
1731 Staffs, and will print a big bracket at the left of the score. Start a
1732 new staff group for the woodwind section (just the flutes in this case).
1733 Immediately after that, we start the staff for the two flutes, that also
1734 play simultaneously.
1738 \property Staff.midiInstrument = #"flute"
1740 Specify the instrument for MIDI output (see @ref{MIDI instrument
1745 \property Staff.instrument = "2 Flauti"
1746 \property Staff.instr = "Fl."
1748 And define the instrument names to be printed in the margin,
1749 @code{instrument} for the first line of the score, @code{instr} for the
1756 The flutes play in the default key.
1760 \context Voice=one @{ \voiceOne \flautoI @}
1761 \context Voice=two @{ \voiceTwo \flautoII @}
1763 Last come the actual flute parts. Remember that we're still in
1764 simultaneous mode. We name both voices differently, so that LilyPond
1765 will actually create two Voice contexts. The flute parts are simple, so
1766 we specify manually which voice is which: @code{\voiceOne} forces the
1767 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
1775 Close the flutes staff and woodwind staff group.
1779 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1781 The timpani staff only shows a new piece of scheme markup, it sets two
1786 \context Voice=one \partcombine Voice
1787 \context Thread=one \tromboI
1788 \context Thread=two \tromboII
1790 You have seen the notation contexts Staff and Voice, but here's a new
1791 one: Thread. One or more Threads can be part of a Voice. The Thread
1792 takes care of note heads and rests, the Voice combine note heads onto a
1795 For the trumpets we use the automatic part combiner (see @ref{Automatic
1796 part combining}) to combine the two simultaneous trumpet parts onto the
1797 trumpet staff. Each trumpet gets its own Thread context, which must be
1798 named @code{one} and @code{two}). The part combiner makes these two
1799 threads share a Voice when they're similar, and splits the threads up
1800 when they're different.
1804 \property Staff.instrument = #`(lines "Corno"
1805 (rows "(E" ,text-flat ")"))
1807 The french horn has the most complex scheme markup name, made up of two
1808 lines of text. The second line has two elements (rows), the @code{E}
1809 and the flat sign @code{text-flat} that we defined before.
1813 \property Staff.transposing = #3
1815 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
1816 transpose this staff by three steps.
1818 Note how we can choose different tuning for entering, printing and
1819 playing, using @code{\transpose} and the MIDI Staff proprerty
1824 \notes \key bes \major
1826 Therefore, it has a different key.
1830 indent = 15 * \staffspace
1831 linewidth = 60 * \staffspace
1833 We specify a big indent for the first line and a small linewidth for this
1838 Usually, LilyPond's predefined setup of notation contexts (Thread,
1839 Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
1840 want a different type of Staff context.
1842 In orchestral scores, it often happens that one instrument has only
1843 rests during one line of the score. The @code{HaraKiriStaffContext} can
1844 be used as a regular @code{StaffContext} drop-in and will take care of
1845 the automatic removing of empty staffs.
1847 @node Extracting an individual part
1848 @subsection Extracting an individual part
1850 The third file, @file{os-flute-2.ly} also reads the definitions of the
1851 first (@file{os-music.ly}), and defines the @code{\score} block for the
1855 \include "os-music.ly"
1856 \include "paper16.ly"
1860 \property Score.skipBars = ##t
1861 \property Staff.midiInstrument = #"flute"
1867 instrument = "Flauto II"
1870 linewidth = 80 * \staffspace
1871 textheight = 200 * \staffspace
1879 @center @strong{Zo, goed lieverd?}
1881 @center How's, this babe?
1882 @center @emph{Flauto II}
1889 @lilypondfile{os-flute-2.ly}
1892 Because we separated the music definitions from the @code{\score}
1893 instantiations, we can easily define a second score from the music of
1894 the second flute. This then is the part for the second flute player.
1895 Of course, we make separate parts for all individual instruments.
1901 In this individual part the second flute has a whole staff for itself,
1902 so we don't want to force stem or tie directions.
1907 instrument = "Flauto II"
1910 The @code{\header} definitions were also read from @file{os-music.ly},
1911 but we need to set the instrument for this particular score.
1915 \property Score.skipBars = ##t
1917 In the conductor's full score, all bars with rests are printed, but for
1918 the individual parts, we want to contract pieces of consecutive empty
1919 bars. LilyPond will do this if Score's @var{skipBars} property to
1923 @node Other ways to run LilyPond
1924 @section Other ways to run LilyPond
1926 Until now, you have been using @file{ly2dvi} to invoke LilyPond.
1927 There are three other routes. Firstly, there is a script called
1928 @code{lilypond-book}, that allows you to freely mix LilyPond input with
1929 Texinfo or LaTeX input. For example, this manual was written using
1930 @code{lilypond-book}. It is discussed in @ref{lilypond-book}.
1933 Secondly, you can generate PostScript directly. This is useful if you
1934 can not or do not want to run @TeX{} on your system. To obtain direct
1935 PostScript output, invoke LilyPond as follows:
1936 @cindex PostScript output
1938 lilypond -f ps test.ly
1940 You have to set some environment variables to view or print this
1941 output. More information can be found in @ref{Invoking
1945 Thirdly, if you want to do special things with your output, you can run
1946 invoke lilypond directly:
1950 to produce plain @TeX{} output. Note that La@TeX{} will not work on the
1951 resulting @file{test.tex}. You must run plain @TeX{} on it.
1959 @node Integrating text and music
1960 @section Integrating text and music
1962 Sometimes, you might want to use music examples in a text that you are
1963 writing. For example, if you are writing a musicological treatise, a
1964 songbook, or (like us) the LilyPond manual. You can make such texts by
1965 hand, simply by importing a PostScript figure into your wordprocessor.
1966 However, there is a also an automated procedure:
1968 If you use La@TeX{} or texinfo, you can mix text and lilypond code. A
1969 script called @code{lilypond-book} will extract the music fragments, run
1970 lilypond on them, and put back the resulting notation. lilypond-book is
1971 described fully in @ref{lilypond-book}, but here we show a small
1972 example. Since the example also contains explanatory text, we won't
1973 comment on the contents.
1976 \documentclass[a4paper]@{article@}
1979 In a lilypond-book document, you can freely mix music and text. For
1982 \score @{ \notes \relative c' @{
1983 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1986 Notice that the music line length matches the margin settings of the
1989 If you have no \verb+\score+ block in the fragment,
1990 \texttt@{lilypond-book@} will supply one:
1996 In the example you see here, a number of things happened: a
1997 \verb+\score+ block was added, and the line width was set to natural
1998 length. You can specify many more options using \LaTeX style options
2001 \begin[verbatim,11pt,singleline,
2002 fragment,relative,intertext="hi there!"]@{lilypond@}
2006 \texttt@{verbatim@} also shows the lilypond code, \texttt@{11pt@} selects
2007 the default music size, \texttt@{fragment@} adds a score block,
2008 \texttt@{relative@} uses relative mode for the fragment, and
2009 \texttt@{intertext@} specifies what to print between the
2010 \texttt@{verbatim@} code and the music.
2012 If you include large examples into the text, it may be more convenient
2013 to put the example in a separate file:
2015 \lilypondfile[printfilename]@{sammartini.ly@}
2017 The \texttt@{printfilename@} option adds the file name to the output.
2022 Under Unix, you can view the results as follows.
2025 $ lilypond-book --outdir=out/ lilbook.tex
2026 lilypond-book (GNU LilyPond) 1.3.146
2027 Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex'
2029 `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly'
2030 @var{lots of stuff deleted}
2031 Writing `out/lilbook.latex'
2033 $ latex lilbook.latex
2034 @var{lots of stuff deleted}
2038 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2039 and running latex creates a lot of temporary files, and you wouldn't
2040 those to clutter up your working directory. Hence, we have them created
2041 in a separate subdirectory.
2043 The result more or less looks like this:
2047 In a lilypond-book document, you can freely mix music and text. For
2050 \score { \notes \relative c' {
2051 c2 g'2 \times 2/3 { f8 e d } c'2 g4
2054 Notice that the music line length matches the margin settings of the
2057 If you have no @code{\score} block in the fragment,
2058 @code{lilypond-book} will supply one:
2064 In the example you see here, a number of things happened: a
2065 @code{\score} block was added, and the line width was set to natural
2066 length. You can specify many more options using La@TeX{} style options
2069 @lilypond[verbatim,11pt,singleline,
2070 fragment,relative,intertext="hi there!"]
2074 @code{verbatim} also shows the lilypond code, @code{11pt} selects
2075 the default music size, @code{fragment} adds a score block,
2076 @code{relative} uses relative mode for the fragment, and
2077 @code{intertext} specifies what to print between the
2078 @code{verbatim} code and the music.
2080 If you include large examples into the text, it may be more convenient
2081 to put the example in a separate file:
2083 @lilypondfile[printfilename]{sammartini.ly}
2085 The @code{printfilename} option adds the file name to the output.
2086 @node end of tutorial
2089 That's all folks. From here, you can either try fiddling with input
2090 files, or you can read the reference manual. You can find more example
2091 files in @file{input} and @file{input/test}. You can also look at some
2092 real music. Have a look at the @uref{Mutopia project,
2093 http://www.mutopiaproject.org}.
2101 this should be on mutopia website.
2106 @c waar deze info? is uiteindelijk wel handig, schat ik.
2109 If you have a big music project, or just a lot of LilyPond input files,
2110 all generated output from LilyPond, @TeX{} and metafont will clutter
2111 your working directory. LilyPond comes with a one-size-fits-all
2112 pre-cooked makefile that helps you manage producing output. It will
2113 produce all output in the directory @file{out} , generate and track
2114 dependencies. Also, it helps in preparing your submission to @ref{Mutopia
2121 cp /usr/share/lilypond/make/ly.make GNUmakefile
2122 cp /usr/share/doc/lilypond/examples/input/tutorial/menuet.ly .
2125 Generated out/menuet.ps for target menuet.
2128 Type @samp{make help} to see possible targets.
2131 @file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
2137 [TODO: rewrite completely.]
2140 * Songs with additional verses::
2144 So what does this look like? Well, here is an example:
2145 @li lypond[veryverbatim, intertext="produces this music:"]
2149 [e16( g b c a g][e a b d] | )e2 d,8 |
2150 [e16( g b c a g][e a b d] | )b2 [a16( f] |
2151 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
2152 [f( a b d b a][f a b d] | )e2
2156 If you are lucky, the above example show a nice feature of LilyPond
2157 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
2158 La@TeX{} can insert pagebreaks between the lines of music.
2160 Notice that there is no @code{\paper} statement in the example
2161 above. Lilypond-book will insert some code for you that defines the
2162 linewidth and the font to use. If you don't want to change the default,
2163 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
2164 In the example above, something like this might be inserted before your code:
2166 \include "paper16.ly"
2167 \paper@{ \paper_sixteen
2171 The actual values for linewidth will differ depending on papersize and
2172 number of columns. Also, if you use a different fontsize for the
2173 music, another file than @code{paper16.ly} should be included.
2175 If you want to make the music not so wide, you can insert a
2176 @code{\paper} statement to set the linewidth:
2178 @li lypond[veryverbatim, intertext="produces this music:"]
2182 [e16( g b c a g][e a b d] | )e2 d,8 |
2183 [e16( g b c a g][e a b d] | )b2 [a16( f] |
2184 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
2185 [f( a b d b a][f a b d] | )e2
2187 \paper{linewidth = 10.\cm }
2191 Very often, if you mix music and text, the music is often only a
2192 few notes or at most a few bars. This music should be as short as
2193 possible and not stretched to be aligned to the right margin.
2195 If you only write voice-contents in the lilypond block, @command{lilypond-book}
2196 will set the @code{linewidth} variable to -1, so Lilypond
2197 will make the music as short as possible but without breaking the
2198 line. Here is a well know harmonic progression:
2199 @li lypond[veryverbatim, intertext="produce a well known harmonic progression:"]
2200 \context Voice { <c' e g> <b d g> <c2 e g> }
2203 If you want to place music examples in the text,
2205 \context Voice { <c' e g> <b d g> <c2 e g> }
2207 , you can use the @code{eps} option. This will create the music as
2208 eps graphics and include it into the document with the
2209 @code{\includegraphics} command.
2211 The code used look like this:
2214 \context Voice @{ <c' e g> <b d g> <c2 e g> @}
2218 You can also use the @code{eps} option if the block is a complete
2219 lilypond source. This 5 cm long empty line,
2223 \paper{ linewidth = 5.\cm }
2226 was created with this code:
2231 \paper@{ linewidth = 5.\cm@}
2236 To avoid that La@TeX{} places the music on a line of its one, there should
2237 be no empty lines between the normal text and the lilypond
2240 You can also use @code{lilypondfile}, to include another file:
2242 @@li lypondfile[printfilename]@{foo.ly@}
2245 @subsection Fontsize options
2247 You can use all lilypond fontsizes in @command{lilypond-book}. The
2248 default 16pt fontsize is probably to big to be included in the middle of
2249 the text, 11pt or 13pt is probably better.
2251 The code can look like this:
2253 @@li lypond[13pt, eps]
2258 The following options set the fontsize:
2261 @li lypond[11pt, eps]
2263 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
2264 [d16 g, a b][c a b g][d'8 g f-\prall g]
2268 @li lypond[13pt, eps]
2270 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
2271 [d16 g, a b][c a b g][d'8 g f-\prall g]
2275 @li lypond[16pt, eps]
2277 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
2278 [d16 g, a b][c a b g][d'8 g f-\prall g]
2282 @li lypond[20pt, eps]
2284 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
2285 [d16 g, a b][c a b g][d'8 g f-\prall g]
2289 @li lypond[26pt, eps]
2291 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
2297 @subsection More options
2300 @item The @code{singleline} option sets @code{linewidth} to -1.0.
2301 @item The @code{multiline} option sets @code{linewidth} to a value letting
2302 the music be aligned to the right margin. The music can span several
2306 @subsection Just in case...
2307 The options @code{fragment} and @code{nofragment} will override
2308 @command{lilypond-book} when it scans the lilypond code to see if it is voice
2309 contents or complete code. This might be useful if @command{lilypond-book} choose
2312 Since there is no finder's fee which doubles every year, there is no
2313 need to wait for the price money to grow. So send a bug report today
2314 if you need this one of these options.
2316 @subsection Examples
2318 This was all options to @code{\begin}. The rest of the lilypond
2319 document will show some ways you can use lilypond in
2320 La@TeX{} documents. It will also act as a simple test-suite for
2321 lilypond-book. You can place @code{eps} lilypond in and marginspars just
2322 as any other included eps graphics.
2328 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
2329 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
2331 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
2333 \paper{linewidth = 7.\cm}
2338 To the right you can see some bars from the trumpet fanfara from the
2339 beginning of the fantastic street opera ``Houdini the Great'', by the
2340 Danish composer Andy Pape. The music is put inside a
2341 @code{floatingfigure} environment, and the music will be aligned by
2342 the right margin if you set floatingfigure width and lilypond linewidth
2343 to the same value. The code looks like this:
2345 @li lypond[verbatim]
2349 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
2350 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
2352 r4.-\fermata [cis,16 cis g'8 f16 f b8]
2353 [g16 g f8 b16 b] dis4.-\fermata
2355 \paper{linewidth = 7.\cm }
2359 If you have a lot of small music examples like this in the middle of
2360 your text, you might get a nicer look by using ``double'' line
2361 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
2362 your document. Then the line spacing will not be increased between the
2363 lines where you have music printed with the smallest font size.
2365 Lilypond-book does know about @code{\onecolumn} and @code{\twocolumn}.
2366 So the music will be adjusted to the new linewidth:
2368 Verbatim environments will also ignore the page margins. That is
2369 a feature of La@TeX{}. (But you usually put things inside a verbatim
2370 environment when you don't want La@TeX{} to do any linebreaking)