8 * Running LilyPond:: Getting started
9 * The first tune:: The first tune
10 * Lyrics and chords:: Lyrics and chords
12 * A piano excerpt:: Piano music
13 * An orchestral score::
15 * end of tutorial:: The end
22 LilyPond prints music from a specification that you, the user, supply.
23 You have to give that specification using a @emph{language}. This
24 chapter is a gentle introduction to that language.
26 This tutorial will demonstrate how to use Lilypond by presenting
27 examples of input along with resulting output. We will use English
28 terms for notation. In case you are not familiar with those, you may
29 consult the glossary that is distributed with LilyPond.
31 @cindex examples, tutorial
33 The examples discussed are included in the distribution, in the
34 subdirectory @file{input/tutorial/}.@footnote{When we refer
35 to filenames, they are relative to the top directory of the source
38 }. We recommend that you experiment with writing Lilypond input
39 yourself, to get a feel for how the program behaves.
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
58 \notes @{ c'4 e'4 g'4 @}
63 @unnumberedsubsec Unix
65 @cindex Unix, Running lilypond on
67 If you run Unix, proceed as follows: run lilypond on the file, i.e.,
71 You will see the following on your screen:
74 Now processing: `input/tutorial/test.ly'
76 Interpreting music...[1]
77 Preprocessing elements...
78 Calculating column positions... [2]
79 paper output to test.tex...
82 Now, run @TeX{}@footnote{@TeX{} is a text-typesetting system that is
83 especially suited for typesetting mathematics.}. The result should
86 This is TeX, Version 3.14159 (Web2C 7.3.1)
87 (test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
88 (/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
89 LilyPond Plain TeX settings) (/home/hanwen/usr/src/ ...
90 (/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
91 (/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
92 Output written on test.dvi (1 page, 3716 bytes).
93 Transcript written on test.log.
95 The result of the @TeX{} run is a @TeX{} ``DeVice Independent'' file
100 @cindex Viewing music
102 To view the output, run Xdvi, i.e.
106 You should see the following in a window next to some buttons.
113 \notes { c'4 e'4 g'4 }
118 @cindex postscript, converting to
119 When you're satisfied with the result, you can print it. For printing,
120 you have to generate a postscript file:
122 dvips -o test.ps test.dvi
124 which looks like this:
126 This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
127 ' TeX output 2001.01.27:1806' -> test.ps
128 <texc.pro><special.pro>. [1]
132 @cindex Printing output
135 PostScript is a page description language, similar to PDF. Some printers
136 can understand a postscript file directly, but the cheaper ones need the
137 intervention of GhostScript, an emulator that runs PostScript on your
138 computer instead of your printer. Most Linux distributions nowadays have
139 GhostScript running ``in the background'', so any configured printer
140 will act as a PostScript printer. Assuming this, the following command
145 If this does not make your printer produce a page of music, then you
146 should look into installing and configuring ghostscript. Refer to
147 GhostScript's website at @uref{http://www.ghostscript.com}.
149 There are three other routes: firstly, you can add titling to the
150 output. This is done by a separate program called @file{ly2dvi}: this
151 program first calls LilyPond to process the @file{.ly} file, and then
152 runs @TeX{} on it to produce a @file{.dvi} file with proper margin
153 settings and titling.
155 @cindex titles, adding
161 After some disk-activity, you should end up with a @file{.dvi} file.
162 Ly2dvi is further described in the @ref{ly2dvi}.
164 Secondly, you can generate PostScript directly. This is useful if you
165 can not or do not want to run @TeX{} on your system.
166 To obtain PS output, invoke LilyPond as follows:
167 @cindex PostScript output
169 lilypond -f ps test.ly
172 You have to set some environment variables to view or print this
173 output. More information can be found in the @ref{Invoking
176 Finally, there is a script called lilypond-book, that allows you to
177 freely mix LilyPond input with Texinfo or LaTeX input. For example, this
178 manual was written using lilypond-book. lilypond-book is discussed in
181 @unnumberedsubsec Windows
185 * setting of env vars (TFMINPUTS,MFINPUTS,TEXINPUTS)
186 * dvi viewer doesn't display postscript
190 @section The first tune
193 To demonstrate what LilyPond input looks like, we start off with a
194 full-fledged, yet simple example. It is a convoluted version
195 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
196 is included in the distribution as @file{menuet.ly}.
197 @cindex Bach, Johann Sebastian
200 % lines preceded by a percent are comments which
201 % are ignored by Lilypond.
202 \include "paper16.ly"
205 \relative c'' \sequential{
210 d4 g,8 a b c d4 g, g |
211 e'4 c8 d e fis g4 g, g |
212 c4 d8()c b a( )b4 c8 b a g |
213 a4 [b8 a] [g fis] g2. |
218 g4 e8 fis g d cis4 b8 cis a4 |
219 a8-. b-. cis-. d-. e-. fis-.
226 % standard settings are too wide for a book
227 linewidth = 14.0 \cm;
232 We will analyse the input, line by line.
234 % lines preceded by a percent are comments which
235 % are ignored by Lilypond.
237 The percent sign, @code{%}, introduces a line comment. If you want to
238 make larger comments, you can use block comments. These are delimited
239 by @code{%@{} and @code{%@}}
241 @cindex block comment
246 \include "paper16.ly"
249 @cindex @code{\include}
250 @cindex point, printer's
251 @cindex staff size setting
252 By default, LilyPond will use definitions for a staff that is 20
253 point@footnote {A point is the standard measure of length for printing;
254 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
255 output (16 point staff height), so we must import the settings for that
256 size, which is done here.
262 A lilypond file combines music with directions for outputting that
263 music. The music is combined with the output directions by putting
264 them into a @code{\score} block.
270 This makes LilyPond ready for accepting notes.
277 @cindex octaves, choosing
279 As we will see, pitches are combinations of octave, note name and
280 chromatic alteration. In this scheme, the octave is indicated by
281 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
282 @code{,}). The central C is denoted by @code{c'}. The C one octave
283 higher is @code{c''}. One and two octaves below the central C is
284 denoted by @code{c} and @code{c,} respectively.
287 For pitches in a long piece you might have to type many quotes. It is
288 easy to make typing errors with this, so LilyPond has a special entry
289 mode to remedy this. In this ``relative'' octave mode, octaves of notes
290 without quotes are chosen such that a note is as close as possible
291 (graphically, on the staff) to the the preceding note. If you add a
292 high-quote an extra octave is added. The lowered quote (a comma) will
293 subtract an extra octave. Because the first note has no predecessor,
294 you have to give the (absolute) pitch of the note to start with.
300 What follows is sequential music, i.e.,
301 @cindex sequential music
302 notes that are to be played and printed after each other.
308 @cindex time signature, setting
310 This command changes the time signature of the current piece: a 3/4
311 sign is printed. This command is also used to generate bar lines in
318 @cindex key signature, setting
320 This command changes the current key signature to G-major. Although this
321 command comes after the @code{\time} command, in the output, the key
322 signature comes before the time signature: LilyPond knows about music
323 typesetting conventions.
329 This command tells LilyPond that the following piece of music must be
330 played twice. The first argument indicates the type of repeat. In this
331 case, @code{"volta"} means that volta brackets are be used for
332 alternatives---if there were any.
338 The subject of the repeat is again sequential music. Since
339 @code{\sequential} is such a common construct, a shorthand is provided:
340 just leave off @code{\sequential}, and the result is the same.
346 This is a note with pitch @code{d} (determined up to octaves). The
347 relative music was started with a @code{c''}, so the real pitch of this
348 note is @code{d''}. The @code{4} designates the duration of the note
349 (it is a quarter note).
355 These are notes with pitch @code{a} and @code{b}. Because their
356 duration is the same as the @code{g}, there is no need to enter the
357 duration (You may enter it anyway, e.g. @code{a4 b4})
365 @cindex errors, finding
366 Three more notes. The @code{|} character is a `bar check'. When
367 processing the music, LilyPond will verify that bar checks are found at
368 the start of a measure. This can help you track down errors.
370 @cindex alteration, chromatic
371 @cindex chromatic alteration
372 So far, no notes were chromatically altered. Here is the first one
373 that is: @code{fis}. Lilypond by default uses Dutch note names, and
374 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
375 sharp sign in the output. The program keeps track of key signatures,
376 and will only print accidentals if they are needed.
382 LilyPond guesses were beams can be added to eighth and shorter notes.
383 In this case, a beam over 4 eighths is added.
386 c4 d8( )c b a( )b4 c8 b a g |
389 The next line shows how to make a slur: the beginning and ending note
390 of the slur is marked with an opening and closing parenthesis
391 respectively. In the line shown above, this is done for two slurs.
392 Slur markers (parentheses) are put between the slurred notes.
398 Automatic beaming can be overridden by inserting beam marks
399 (brackets). Brackets are put around the notes you want beamed.
405 @cindex augmentation dot
407 A duration with augmentation dot is notated
408 with the duration number followed by a period.
414 This ends the sequential music to be repeated. LilyPond will typeset
421 This line shows that Lily will print an accidental if that is
422 needed: the first C sharp of the bar will be printed with an accidental,
423 the second one without.
426 a8-. b-. cis-. d-. e-. fis-.
430 You can enter articulation signs either in a verbose form using a
431 shorthand. Here we demonstrate the shorthand: it is formed by a dash
432 and the character for the articulation to use, e.g. @code{-.} for
433 staccato as shown above.
440 Rests are denoted by the special notename @code{r}.
446 All articulations have a verbose form, like @code{\fermata}. The
447 command @code{\fermata} is not part of the core of the language (most
448 of the other discussed elements are), but it is a shorthand for a more
449 complicated description of a fermata. @code{\fermata} names that
450 description and is therefore called an identifier.
452 @cindex @code{\fermata}
467 This specifies a conversion from music to notation output. Most of
468 the details of this conversions (font sizes, dimensions, etc.) have
469 been taken care of, but to fit the output in this document, it has
470 to be smaller. We do this by setting the line width to 14 centimeters
471 (approximately 5.5 inches).
477 The last brace ends the @code{\score} block.
482 @node Lyrics and chords
483 @section Lyrics and chords
485 In this section we show how to typeset a song. This file is
486 included as @file{flowing.ly}.
490 title = "The river is flowing";
491 composer = "Traditional (?)";
493 \include "paper16.ly"
494 melody = \notes \relative c' @{
498 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
499 c4 c8 d [es () d] c4 | d4 es8 d c4.
504 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
505 ri -- ver is flo -- wing down to the sea.
508 accompaniment =\chords @{
510 c2:3- f:3-.7 d:min es4 c8:min r8
511 c2:min f:min7 g:7^3.5 c:min @}
516 \context ChordNames \accompaniment
519 \context Staff = mel @{
520 \property Staff.noAutoBeaming = ##t
521 \property Staff.automaticMelismata = ##t
524 \context Lyrics \text
526 \midi @{ \tempo 4=72;@}
527 \paper @{ linewidth = 10.0\cm; @}
532 The result would look this.@footnote{The titling and font size shown
533 may differ, since the titling in this document is not generated by
536 @center @strong{The river is flowing}
541 title = "The river is flowing";
542 composer = "Traditional (?)";
544 \include "paper16.ly"
545 melody = \notes \relative c' {
549 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
550 c4 c8 d [es () d] c4 | d4 es8 d c4.
555 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
556 ri -- ver is flo -- wing down to the sea.
559 accompaniment =\chords {
561 c2:3- f:3-.7 d:min es4 c8:min r8
562 c2:min f:min7 g:7^3.5 c:min }
567 \context ChordNames \accompaniment
570 \context Staff = mel {
571 \property Staff.noAutoBeaming = ##t
572 \property Staff.automaticMelismata = ##t
575 \context Lyrics \text
577 \midi { \tempo 4=72;}
578 \paper { linewidth = 10.0\cm; }
582 Again, we will dissect the file line by line.
588 @cindex @code{\header}
589 Information about the music you are about to typeset goes into a
590 @code{\header} block. The information in this block is not used by
591 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
592 information to print titles above the music.
595 title = "The river is flowing";
596 composer = "Traditional (?)";
599 @cindex identifier assignment
600 the @code{\header} block contains assignments. An assignment starts
601 with a string. (which is unquoted, in this case). Then comes the
602 equal sign. After the equal sign comes the expression you
603 want to store. In this case, you want to put in strings. The
604 information has to be quoted here, because it contains spaces. Each
605 assignment is finished with a semicolon.
608 \include "paper16.ly"
611 Smaller size for inclusion in a book.
614 melody = \notes \relative c' @{
617 The structure of the file will be the same as the previous one, a
618 @code{\score} block with music in it. To keep things readable, we will
619 give names to the different parts of music, and use the names to
620 construct the music within the score block.
626 @cindex @code{\partial}
628 The piece starts with an anacrusis of one eighth.
632 The key is C minor: we have three flats.
636 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
637 c4 c8 d [es () d] c4 | d4 es8 d c4.
642 @cindex manual beaming
643 @cindex automatic beaming, turning off
644 We use explicit beaming. Since this is a song, we will turn automatic
645 beams off, and use explicit beaming where needed.
651 This ends the definition of @code{melody}. Note that there are no
652 semicolons after assignments at top level.
659 @cindex identifier assignment
660 @cindex syllables, entering
661 Another identifier assignment. This one is for the lyrics.
662 Lyrics are formed by syllables that have duration, and not by
663 notes. To make LilyPond parse words as syllables, switch it into
664 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
665 is a shorthand for @code{\sequential @{}.
668 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
669 ri- ver is flo- __ wing down to the sea.
673 @cindex extenders, lyric
674 @cindex hyphens, lyric
675 The syllables themselves are separated by spaces. You can get syllable
676 extenders by entering @code{__}, and centered hyphens with
677 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
678 in length (hence the @code{4}), and use a feature to align the
679 syllables to the music (which obviously isn't all quarter notes.)
682 accompaniment =\chords @{
687 We'll put chords over the music, to enter them, there is a special mode,
688 called @code{\chords}. There is a special mode (analogous
689 to @code{\lyrics} and @code{\notes} mode) where you can give the names
690 of the chords you want, instead of the notes comprising the chord.
696 There is no accompaniment during the anacrusis.
704 @cindex chord modifier
705 @cindex modifier, chord
706 A chord is started by the tonic of the chord. The
707 first one lasts a half note. An unadorned note creates a major
708 triad, while a minor triad is wanted. @code{3-} modifies the third to
709 be small. @code{7} modifies (adds) a seventh, which is small by default
710 to create the @code{f a c es} chord. Multiple modifiers must be
718 Some modifiers have predefined names, eg. @code{min} is the same as
719 @code{3-}, so @code{d-min} is a minor @code{d} chord.
722 c2:min f:min7 g:7^3.5 c:min @}
725 @cindex named modifier
727 A named modifier @code{min} and a normal modifier @code{7} do not have
728 to be separated by a dot. Tones from a chord are removed with chord
729 subtractions. Subtractions are started with a caret, and they are
730 also separated by dots. In this example, @code{g:7^3.5} produces a
731 minor seventh. The brace ends the sequential music.
738 We assemble the music in the @code{\score} block. Melody, lyrics and
739 accompaniment have to sound at the same time, so they should be
740 @code{\simultaneous}.
741 @cindex @code{\simultaneous}
747 Chord mode generates notes grouped in @code{\simultaneous} music. If
748 you remove the comment sign, you can see the chords in normal
749 notation: they will be printed as note heads on a separate
753 \context ChordNames \accompaniment
757 @cindex interpretation context
758 @cindex notation context
759 Normally, the notes that you enter are transformed into note heads.
760 The note heads alone make no sense, they need surrounding information:
761 a key signature, a clef, staff lines, etc. They need @emph{context}. In
762 LilyPond, these symbols are created by objects called `interpretation
763 contexts'. Interpretation contexts only exist during a run of
764 LilyPond. Interpretation contexts that are for printing music (as
765 opposed to playing music) are called `notation contexts'.
767 By default, LilyPond will create a Staff context for you. If you
768 removed the @code{%} sign in the previous line, you would see that
771 We don't want that default here, because we want chord names, not note heads.
772 An interpretation context can also created upon explicit request. The
773 keyword for such a request is @code{\context}. It takes two arguments.
774 The first is the name of an interpretation context. The name is a
775 string, it can be quoted with double quotes). The second argument is
776 the music that should be interpreted in this context. For the previous
777 line, we could have written @code{\context Staff \accompaniment}, and
784 @cindex @code{\addlyrics}
785 @cindex lyrics and melody, combining
786 @cindex combining lyrics and melody
788 The lyrics need to be aligned with the melody. This is done by
789 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
790 pieces of music (usually a melody and lyrics, in that order) and
791 aligns the syllables of the second piece under the notes of the
792 first piece. If you would reverse the order, the notes would be
793 aligned on the lyrics, which is not very useful. (Besides, it looks
797 \context Staff = mel @{
801 This is the argument of @code{\addlyrics}. We instantiate a
802 @code{Staff} context explicitly: should you chose to remove the comment
803 before the ``note heads'' version of the accompaniment, the
804 accompaniment will be on a nameless staff. The melody has to be on a
805 different staff as the accompaniment. This is accomplished by giving
806 the melody staff a different name.
809 \property Staff.noAutoBeaming = ##t
813 @cindex context variables
814 @cindex setting context variables
815 An interpretation context has variables that tune its behaviour. One of
816 the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
817 the boolean value @var{true}, LilyPond will not try to put automatic beaming
818 on the current staff.
822 @cindex accessinng Scheme
823 @cindex evaluating Scheme
826 LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
827 a language from the LISP family. You can learn more about Scheme at
828 @uref{http://www.scheme.org}.} to represent data throughout the whole
829 program. The hash-sign (@code{#}) accesses GUILE directly: the code
830 following the hash-sign is evaluated as Scheme. The boolean value
831 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
836 \property Staff.automaticMelismata = ##t
839 @cindex automaticMelismata
841 @cindex @code{\addlyrics} and slurs
842 Similarly, we don't want to print a syllable when there is
843 a slur. This sets up @code{\addlyrics} to not put lyrics under notes
844 while there is a slur.
851 Finally, we put the melody on the current staff. Note that the
852 @code{\property} directives and @code{\melody} are grouped in sequential
853 music, so the property settings are done before the melody is
857 \context Lyrics \text
860 The second argument of @code{\addlyrics} is the text. The text also
861 should not land on a Staff, but on a interpretation context for
862 syllables, extenders, hyphens etc. This context is called
869 This ends @code{\simultaneous}.
872 \midi @{ \tempo 4=72;@}
875 This makes the music go to a MIDI file. MIDI is great for checking
876 music you enter. You listen to the MIDI file: if you hear something
877 unexpected, it's probably a typing error. @code{\midi} starts an output
878 definition, a declaration that specifies how to output music analogous
879 to @code{\paper @{ @}}. You can specify the tempo using the
880 @code{\tempo} command, in this case the tempo of quarter notes is set to
884 \paper @{ linewidth = 10.0\cm; @}
887 We also want notation output. The linewidth is short so the piece
888 will be set in two lines.
897 @section More movements
899 You probably ran @file{ly2dvi} on the last example, and ended up with a
900 viewable @file{.dvi} file. However, between there are a few steps of
901 which LilyPond is only one. To enhance your understanding of what's
902 happening under the hood when you run @code{ly2dvi}, we explain what
905 @code{ly2dvi} is a program that calls a number of programs in sequence.
906 The first thing it does, is running LilyPond on the input file. After
907 some calculations, a @file{.tex} is produced. The contents
908 of this file are very low-level instructions.
910 For example, the following file (@file{layout.ly})
914 \header @{ title = "Two miniatures"; @}
916 #(set! point-and-click line-column-location)
934 results in something like this@footnote{The titling in this manual was
935 not generated by ly2dvi, so details will differ.}
937 @center @strong{Two miniatures}
965 This file is produced by ly2dvi in a few stages, with the help of text
966 formatting tools. LilyPond produces two output files, @file{layout.tex}
967 and @file{layout-1.tex}. They both look like this:
971 \placebox@{-5 \outputscale @}%
972 @{ 8.7229 \outputscale @}%
973 @{\magfontWXGEomMMBo\char90 @}%
975 \placebox@{-4 \outputscale @}%
976 @{ 81.0647 \outputscale @}%
980 @file{ly2dvi} analyses the progress indication that LilyPond spews out,
981 and generates a file called @file{layout_ly1.tex}. This file contains
982 formatting instructions for the title and page layout. A fragment might
986 \geometry@{width=540.602362pt,headheight=2mm, ...
987 \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@} ...
989 \lilypondtitle@{foo@}%
995 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
996 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
997 is successful, this will produce a @file{.dvi} file, containing both the
998 titling and notes. @code{ly2dvi} completes its task by deleting the two
999 temporary files, leaving only @file{layout.dvi}.
1001 Next, now we'll look at the examples line by line to explain new things.
1006 Lilypond and its language are still under development, and occasionally,
1007 details of the syntax are changed. This fragment indicates for which
1008 version the input file was written. When you compile this file, the
1009 version number will be checked, and you will get a warning when the file
1012 This version number is also used by the @code{convert-ly} program (See
1013 @ref{convert-ly}), which uses it update the file to the latest lily
1017 \header @{ title = "Two miniatures"; @}
1019 This sets the titling information for the entire file.
1022 #(set! point-and-click line-column-location)
1025 This is Scheme code. It sets the variable @code{point-and-click} to the
1028 Editing input files can be quite complicated if you're working with
1029 large files: if you're digitizing existing music, you have to
1030 synchronize the .ly file, the sheet music on your lap and the sheet
1031 music on the screen. The point-and-click mechanism makes it easy to
1032 find the origin of an error in the .ly file: @footnote{This feature is
1033 presently only available on X-windows using patched versions of Xdvi and
1034 emacs} when you view the file with Xdvi and click on a note using
1035 control-mousebutton 1@footnote{If you're using a patched xdvik, the
1036 command is control-mousebutton-2}, your editor will jump to the spot
1037 where that note was entered.
1039 More information is in in @ref{Point and click}
1045 The @code{\score} blocks that follow in the file don't have
1046 @code{\paper} sections, so the settings of this block are substituted: A
1047 paper block, at top-level, i.e. not in a @code{\score} block sets the
1048 default page layout.
1051 linewidth = -1.0; @}
1056 The variable @code{linewidth} normally sets the length of the systems on
1057 the page. However, a negative value has a special meaning. If
1058 @code{linewidth} is less than 0, no line breaks are inserted into the
1059 score, and the spacing is set to natural length: a short phrase takes up
1060 little space, a longer phrase more space.
1064 \notes @{ c'4 d'4 @}
1067 In previous examples, notes were specified in relative octaves,
1068 i.e. each note was put in the octave that would put it closest to its
1069 predecessor. Besides relative, there is also absolute octave
1070 specification, and it is turned on by default. In this input mode, the
1071 central C is denoted by @code{c'}. Going down, you get @code{c}
1072 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} etc.
1074 When you're copying music from existing sheet music, relative octaves
1075 are probably the easiest to use: it's less typing work and errors are
1076 easily spotted. However, if you write LilyPond input, either by hand
1077 (ie. composing) or by computer, absolute octaves are probably less work.
1084 The @code{\header} is normally at the top of the file, where it sets
1085 values for the rest of the file. If you want to typeset different pieces
1086 from one file (for example, if there are multiple movements, or if
1087 you're making a etude-book), you can put different @code{\score} blocks
1088 into the input file. ly2dvi will assemble all LilyPond output files into
1089 a big document. The contents of \header blocks specified within each
1090 score, are used for the titling of each movement.
1095 For example, the Opus number is put at the right, and the piece string
1096 will be at the left.
1100 @node A piano excerpt
1101 @section A piano excerpt
1103 Our third subject is a piece of piano music. The fragment in the input
1104 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1105 Sammartini. It was composed around 1740. It's in the source package
1106 under the name @file{sammartini.ly}.
1109 \include "paper16.ly";
1111 stemDown = \property Voice.Stem \override #'direction = #-1
1112 stemUp = \property Voice.Stem \override #'direction = #1
1113 stemBoth = \property Voice.Stem \revert #'direction
1115 viola = \notes \relative c' \context Voice = viola {
1116 <c4-\f-\arpeggio g' c>
1122 oboes = \notes \relative c'' \context Voice = oboe {
1123 \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1124 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
1126 { \times 2/3 { a8 g c } \! c2 }
1127 \context Voice = oboeTwo {
1130 \property Grace.Stem \override #'direction = #-1
1135 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1136 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1137 [<c16( e> < )e8. g>] <c8 e,>
1140 hoomPah = \repeat unfold 8
1141 \notes \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }
1143 bassvoices = \notes \relative c' {
1145 \autochange Staff \hoomPah
1146 \translator Staff = down
1147 \stemDown [c8 c'8] r4
1149 < {\stemUp r2 <e4 c'> <c8 g'> }
1150 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
1154 \context PianoStaff \notes <
1155 \context Staff = up < \time 2/2;
1159 \context Staff = down < \time 2/2; \clef bass;
1166 linewidth = 15.0 \cm; }
1170 If it looks like incomprehensible gibberish to you, then you are right.
1171 This example has been doctored to have as many quirks as possible.
1174 stemDown = \property Voice.Stem \override #'direction = #-1
1177 As you can see, this example features more voices on one staff. To make
1178 room for those voices, their notes have to be stemmed in opposite
1179 directions. These are the commands to make that happen.
1181 The symbols that are printed, are internally represented by so-called
1182 Graphical Objects (or more colloquially: Grobs). These statements
1183 concern the grob called `Stem'. Each grob is described by a bunch of
1184 settings. These setting determine the fonts, offsets, sub-routines to be
1185 called on the grob, etc. The initial values of these settings are set
1186 in the Scheme file @file{scm/grob-description.scm}.
1188 This statement adds a the setting for all Stem grobs in the current
1189 Voice: @code{direction} is set to @code{-1}, which encodes down. The
1190 setting remains in effect until it is reverted.
1193 \property Voice.Stem \revert #'direction
1196 This statement reverts the old setting. If you do this, the effect of a
1197 @code{\stemDown} or @code{\stemUp} is neutralised.
1199 @code{\override} and @code{\revert} function like a stack: you can push
1200 values onto the grob-setting-stack with @code{\override} and you pop
1201 them with @code{\revert}.
1203 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1204 with some more often used formatting instructions, but to explain how it
1205 works, we wrote our own here. Of course, you should use predefined
1206 identifiers like these if possible: then you will be affected less by
1207 the implementation changes we occasionally make.
1210 viola = \notes \relative c' \context Voice = viola @{
1212 In this example, you can see multiple parts on a staff. Each part is
1213 associated with one notation context. This notation context handles
1214 stems and dynamics (among others). The name of this context is
1215 @code{Voice}. For each part we have to make sure that there is
1216 precisely one @code{Voice} context, so we give it an unique name
1220 <c4-\f-\arpeggio g' c>
1222 The delimiters @code{<} and @code{>} are shorthands for
1223 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1224 @code{<} and @code{>} is a chord.
1231 @code{\f} places a forte symbol under the chord. The forte applies to
1232 the whole chord, but the syntax requires that commands like forte and
1233 arpeggio are attached to a note, so here we attach them to the first
1236 @code{\arpeggio} draws an vertical wavy line before the chord,
1237 signifying an arpeggio.
1247 Relative octaves work a little differently with chords. The starting
1248 point for the note following a chord is the first note of the chord. So
1249 the @code{g} gets an octave up quote: it is a fifth above the starting
1250 note of the previous chord (the central C).
1255 @code{s} is a spacer rest. It does not print anything, but it does have
1256 the duration of a rest. It is useful for filling up voices that
1257 temporarily don't play. In this case, the viola doesn't come until one
1258 and a half measure later.
1261 oboes = \notes \relative c'' \context Voice = oboe @{
1263 Now comes a part for two oboes. They play homophonically, so we
1264 print the notes as one voice that makes chords. Again, we insure that
1265 these notes are indeed processed by precisely one context with
1268 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1270 @code{\stemUp} is a reference to the @code{\property \override} command
1273 \grace <e8 g> < d4 f> <c2 e>
1275 @cindex @code{\grace}
1279 @code{\grace} introduces grace notes. It takes one argument, in this
1283 The slur started on the @code{e} of the chord
1284 will be attached to the next note.@footnote{LilyPond will squirm
1285 about unended Slurs. In this case, you can ignore the warning}.
1292 Tuplets are made with the @code{\times} keyword. It takes two
1293 arguments: a fraction and a piece of music. The duration of the piece
1294 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1295 of their notated duration, so in this case the fraction is 2/3.
1297 @{ <d8 \< f> <e g> <f a> @}
1299 The piece of music to be `tripletted' is sequential music containing
1300 three notes. On the first chord, a crescendo is started with
1301 @code{\<}. To be precise, the crescendo start is syntactically attached
1302 to the preceding note, the @code{d}.
1311 At this point, the homophonic music splits into two rhythmically
1312 different parts. We can't use a sequence of chords to enter this, so
1313 we make a `chord' of sequences to do it. We start with the upper
1314 voice, which continues with upward stems:
1316 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1321 The crescendo is ended at the half note by the escaped exclamation
1324 \context Voice = oboeTwo @{
1327 We can't share stems with the other voice, so we have to create a new
1328 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1329 it from the other context. Stems go down in this voice.
1333 @cindex Grace context
1334 When a grace section is processed, a @code{Grace} context is
1335 created. This context acts like a miniature score of its own. It has
1336 its own time bookkeeping, and you can make notes, beams, slurs
1337 etc. Here we fiddle with a property and make a beam. The argument of
1338 @code{\grace} is sequential music.
1341 \property Grace.Stem \override #'direction = #-1
1345 Normally, grace notes are always stem up, but in this case, the upper
1346 voice interferes. We set the stems down here.
1348 As far as relative mode is concerned, the previous note is the
1349 @code{c'''2} of the upper voice, so we have to go an octave down for
1356 This ends the two-part section.
1359 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1364 @code{\stemBoth} ends the forced stem directions. From here, stems are
1365 positioned as if it were single part music.
1367 The bass has a little hoom-pah melody to demonstrate parts switching
1368 between staffs. Since it is repetitive, we use repeats:
1370 hoomPah = \repeat unfold 8
1372 @cindex unfolded @code{\repeat}
1373 This repeat print the following sequence notes eight times.
1375 \notes \transpose c' @{
1378 @cindex relative mode and transposing
1380 Transposing can be done with @code{\transpose}. It takes two arguments;
1381 the first specifies what central C should be transposed to. The second
1382 is the to-be-transposed music. As you can see, in this case, the
1383 transposition is a no-op, as central C stay at central C.
1385 The purpose of this no-op is circumventing relative mode. Relative mode
1386 can not be used together with transposition, so @code{\relative} will
1387 leave the contents of @code{\hoomPah} alone. We can use it without
1388 having to worry about getting the motive in a wrong octave.
1390 bassvoices = \notes \relative c' @{
1392 \autochange Staff \hoomPah
1394 @cindex staff switch, automatic
1395 @cindex cross staff voice, automatic
1396 @cindex @code{\autochange}
1398 Voices can switch between staffs. The easiest way to get this, is to use
1399 @code{\autochange}. This command looks at the pitch of each note, and if
1400 necessary, will cross to the other staff. For this to work, the two
1401 staffs must be called @code{"up"} and @code{"down"}.
1403 \translator Staff = down
1405 @cindex staff switch
1406 @cindex cross staff voice
1407 The rest of this melody must be in the lower staff, so we do a manual
1412 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1416 After skipping some lines, we see @code{~}. This mark makes ties.
1420 A special context is needed to get cross staff beaming right. This
1421 context is called @code{PianoStaff}.
1423 \context Staff = bottom < \time 2/2; \clef bass;
1425 The bottom staff must have a different clef.
1429 To make some more room on the line, the first (in this case the only)
1430 line is not indented. The line still looks very cramped, but that is due
1431 to the page layout of this document.
1437 * font-size, multi-stanza.
1439 * Simple part combining in a Hymn
1442 @node An orchestral score
1443 @section An orchestral score
1445 If you've come this far, you should have seen enough LilyPond source to
1446 feel comfortable with an orchestral score. We will not go through the
1447 input line by line, but only indicate and explain the new elements.
1449 This orchestral score example consists of three input files. In the
1450 first file, @file{os-music.ly}, we define the music for all instruments.
1451 This file is to be used by the other two files, as you will see below.
1452 If you run lilypond on this file, no output will be produced.
1458 title = "Zo, goed lieverd?";
1459 subtitle = "How's, this babe?";
1462 piece = "Laid back";
1466 \skip 2*4; \bar "|.";
1468 Key = \notes \key as \major;
1469 flautoI = \notes\relative c'' @{
1471 bes as bes as bes as bes as
1473 flautoII = \notes\relative c'' @{
1474 as8 bes as bes R1 d4 ~ d
1476 tromboI = \notes\relative c'' @{
1477 c4. c8 c8 c4. es4 R1*1/2 es4
1479 tromboII = \notes\relative c'' @{
1480 as4. as8 as8 as4. R1*1/2 as4 es'
1482 timpani = \notes\relative c, @{
1483 \times 2/3 @{ f4 f f @}
1484 \times 4/5 @{ as8 as as as as @}
1487 corno = \notes\relative c' @{
1488 bes4 d f, bes d f, bes d
1492 Things to note here are the definition of @code{\global} where we define
1493 meter, and set the end bar. And the separate definition of @code{\Key}
1494 that we will use all staffs except staffs for transposing instruments.
1496 The second file, @file{os-score.ly} reads the definitions of the first
1497 (@file{os-music.ly}), and defines the @code{\score} block for the full
1502 \include "os-music.ly";
1503 \include "paper13.ly";
1505 #(set! point-and-click line-column-location)
1506 #(define text-flat '((font-relative-size . -2)
1507 (music "accidentals--1")))
1512 \context StaffGroup = woodwind <
1513 \context Staff = flauti <
1514 \property Staff.midiInstrument = #"flute"
1515 \property Staff.instrument = "2 Flauti"
1516 \property Staff.instr = "Fl."
1518 \context Voice=one @{ \voiceOne \flautoI @}
1519 \context Voice=two @{ \voiceTwo \flautoII @}
1522 \context StaffGroup = timpani <
1523 \context Staff = timpani <
1524 \property Staff.midiInstrument = #"timpani"
1525 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1526 \property Staff.instr = #"Timp."
1532 \context StaffGroup = brass <
1533 \context Staff = trombe <
1534 \property Staff.midiInstrument = #"trumpet"
1535 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
1536 \property Staff.instr = #`(lines "Tbe." "(C)")
1538 \context Voice=one \partcombine Voice
1539 \context Thread=one \tromboI
1540 \context Thread=two \tromboII
1542 \context Staff = corni <
1543 \property Staff.midiInstrument = #"french horn"
1544 \property Staff.instrument = #`(lines "Corno"
1545 (rows "(E" ,text-flat ")"))
1546 \property Staff.instr = #`(lines "Cor."
1547 (rows "(E" ,text-flat ")"))
1548 \property Staff.transposing = #3
1549 \notes \key bes \major;
1550 \context Voice=one \corno
1555 indent = 15 * \staffspace;
1556 linewidth = 60 * \staffspace;
1557 textheight = 90 * \staffspace;
1560 \consists "Rest_engraver";
1564 \remove "Rest_engraver";
1565 \consists "Multi_measure_rest_engraver";
1566 \consists "Bar_engraver";
1569 \HaraKiriStaffContext
1570 \remove "Multi_measure_rest_engraver";
1571 \remove "Bar_engraver";
1574 \OrchestralScoreContext
1575 BarNumber \override #'padding = #3
1584 @center @strong{Zo, goed lieverd?}
1586 @center How's, this babe?
1594 @lilypondfile{os-score.ly}
1596 First, we need to include the music definitions we made in
1599 \include "os-music.ly";
1602 In a large orchestral score like this you're bound to make some small
1603 mistakes, so we enable point and click (See @ref{Point and click})
1606 #(set! point-and-click line-column-location)
1609 We need a flat sign in text to name the tuning of the french horn, so we
1610 predefine it with bit of scheme markup text (See @ref{Text markup}).
1612 #(define text-flat '((font-relative-size . -2)
1613 (music "accidentals--1")))
1616 Of course, all staffs are simultaneous and use the same global settings.
1622 Then, we start a new staff group for the woodwind section (just the
1623 flutes in this case). Immediately after that, we start the staff for
1624 the two flutes, that also play simultaneously.
1626 \context StaffGroup = woodwind <
1627 \context Staff = flauti <
1630 We specify the intrument for MIDI output (see @ref{MIDI instrument
1633 \property Staff.midiInstrument = #"flute"
1636 And define the intrument names to be printed in the margin,
1637 @code{instrument} for the first line of the score, @code{instr} for the
1640 \property Staff.instrument = "2 Flauti"
1641 \property Staff.instr = "Fl."
1644 The flutes play in the default key.
1649 Last come the actual flute parts. Remember that we're still in
1650 simultaneous mode. We name both voices differently, so that LilyPond
1651 will actually create two Voice contexts. The flute parts are simple, so
1652 we specify manually which voice is which: @code{\voiceOne} forces the
1653 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
1656 \context Voice=one @{ \voiceOne \flautoI @}
1657 \context Voice=two @{ \voiceTwo \flautoII @}
1660 We close the flutes staff and woodwind staff group.
1666 The timpani staff only shows a new piece of scheme markup, it sets two
1669 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1672 For the trumpets we use the automatic part combiner (see @ref{Automatic
1673 part combining}) to combine the two simultaneous trumpet parts onto the
1674 trumpet staff. Each trumpet gets its own Thread context, which must be
1675 named @code{one} and @code{two}). The part combiner makes these two
1676 threads share a Voice when they're similar, and splits the threads up
1677 when they're different.
1679 \context Voice=one \partcombine Voice
1680 \context Thread=one \tromboI
1681 \context Thread=two \tromboII
1684 The french horn has the most complex scheme markup name, made up of two
1685 lines of text. The second line has two elements (rows), the @code{E}
1686 and the flat sign @code{text-flat} that we defined before.
1688 \property Staff.instrument = #`(lines "Corno"
1689 (rows "(E" ,text-flat ")"))
1692 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
1693 transpose this staff by three steps.
1695 \property Staff.transposing = #3
1698 Therefore, it has a different key.
1700 \notes \key bes \major;
1703 We specify a big indent for the first line and a small linewith for this
1706 indent = 15 * \staffspace;
1707 linewidth = 60 * \staffspace;
1710 Because we have a Thread representing one instrument, we need to move
1711 the @code{Rest_engraver} from Voice to Thread level. Similarly, we need
1712 to move the @code{Multi_measure_rest_engraver} from Staff to Voice level.
1716 \consists "Rest_engraver";
1720 \remove "Rest_engraver";
1721 \consists "Multi_measure_rest_engraver";
1722 \consists "Bar_engraver";
1726 In orchestral scores, it often happens that one instrument has only
1727 rests during one line of the score. The @code{HaraKiriStaffContext} can
1728 be used as a regular @code{StaffContext} drop-in and will take care of
1729 the automatic removing of empty staffs.
1732 \HaraKiriStaffContext
1733 \remove "Multi_measure_rest_engraver";
1734 \remove "Bar_engraver";
1738 We want bar numbering at score level and want to move the bar number a
1739 few staff spaces up.
1742 \OrchestralScoreContext
1743 BarNumber \override #'padding = #3
1747 @node Part extraction
1748 @section Part extraction
1750 The third file, @file{os-flute-2.ly} also reads the definitions of the
1751 first (@file{os-music.ly}), and defines the @code{\score} block for the
1755 \include "os-music.ly";
1756 \include "paper16.ly";
1760 \property Staff.midiInstrument = #"flute"
1766 instrument = "Flauto II";
1769 linewidth = 80 * \staffspace;
1770 textheight = 200 * \staffspace;
1772 \OrchestralScoreContext
1782 @center @strong{Zo, goed lieverd?}
1784 @center How's, this babe?
1785 @center @emph{Flauto II}
1792 @lilypondfile{os-flute-2.ly}
1795 Because we separated the music definitions from the @code{\score}
1796 instantiations, we can easily define a second score from the music of
1797 the second flute. This then is the part for the second flute player.
1798 Of course, we make separate parts for all individual instruments.
1800 In this individual part the second flute has a whole staff for itself,
1801 so we don't want to force stem or tie directions.
1806 The @code{\header} definitions were also read from @file{os-music.ly},
1807 but we need to set the instrument for this particular score.
1810 instrument = "Flauto II";
1814 In the conductor's full score, all bars with rests are printed, but for
1815 the individual parts, we want to contract pieces of consecutive empty
1821 @node end of tutorial
1824 That's all folks. From here, you can either try fiddling with input
1825 files, or you can read the reference manual. You can find more example
1826 files in @file{input} and @file{input/test}. You can also look at Real
1827 Music (TM), have a look at the @ref{Mutopia project}.
1831 [TODO figure out what to do with this: ]
1834 * Pre-cooked makefile::
1837 @node Pre-cooked makefile
1838 @subsection Pre-cooked makefile
1840 @c waar deze info? is uiteindelijk wel handig, schat ik.
1843 If you have a big music project, or just a lot of LilyPond input files,
1844 all generated output from LilyPond, @TeX{} and metafont will clutter
1845 your working directory. LilyPond comes with a one-size-fits-all
1846 pre-cooked makefile that helps you manage producing ouptut. It will
1847 produce all output in @file{out}, generate and track dependencies.
1848 Also, it helps in preparing your submission to the @ref{Mutopia
1855 cp /usr/share/lilypond/make/ly.make GNUmakefile
1856 cp /usr/share/doc/lilypond/examples/input/tutorial/menuet.ly .
1859 Generated out/menuet.ps for target menuet.
1862 Type @samp{make help} to see possible targets.
1865 @file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}