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
16 * Pre-cooked makefile::
23 LilyPond prints music from a specification that you, the user, supply.
24 You have to give that specification using a @emph{language}. This
25 chapter is a gentle introduction to that language.
27 This tutorial will demonstrate how to use Lilypond by presenting
28 examples of input along with resulting output. We will use English
29 terms for notation. In case you are not familiar with those, you may
30 consult the glossary that is distributed with LilyPond.
32 @cindex examples, tutorial
34 The examples discussed are included in the distribution, in the
35 subdirectory @file{input/tutorial/}.@footnote{When we refer
36 to filenames, they are relative to the top directory of the source
39 }. We recommend that you experiment with writing Lilypond input
40 yourself, to get a feel for how the program behaves.
43 @node Running LilyPond
44 @section Running LilyPond
46 Before we dive into describing the input language of LilyPond, we first
47 show you through the procedure for getting notes on your screen and out
50 The first step is creating an input file. Using your favorite
51 text-editor, create @file{test.ly} containing
59 \notes @{ c'4 e'4 g'4 @}
64 @unnumberedsubsec Unix
66 @cindex Unix, Running lilypond on
68 If you run Unix, proceed as follows: run lilypond on the file, i.e.,
72 You will see the following on your screen:
75 Now processing: `input/tutorial/test.ly'
77 Interpreting music...[1]
78 Preprocessing elements...
79 Calculating column positions... [2]
80 paper output to test.tex...
83 Now, run @TeX{}@footnote{@TeX{} is a text-typesetting system that is
84 especially suited for typesetting mathematics.}. The result should
87 This is TeX, Version 3.14159 (Web2C 7.3.1)
88 (test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
89 (/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
90 LilyPond Plain TeX settings) (/home/hanwen/usr/src/ ...
91 (/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
92 (/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
93 Output written on test.dvi (1 page, 3716 bytes).
94 Transcript written on test.log.
96 The result of the @TeX{} run is a @TeX{} ``DeVice Independent'' file
101 @cindex Viewing music
103 To view the output, run Xdvi, i.e.
107 You should see the following in a window next to some buttons.
114 \notes { c'4 e'4 g'4 }
119 @cindex postscript, converting to
120 When you're satisfied with the result, you can print it. For printing,
121 you have to generate a postscript file:
123 dvips -o test.ps test.dvi
125 which looks like this:
127 This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
128 ' TeX output 2001.01.27:1806' -> test.ps
129 <texc.pro><special.pro>. [1]
133 @cindex Printing output
136 PostScript is a page description language, similar to PDF. Some printers
137 can understand a postscript file directly, but the cheaper ones need the
138 intervention of GhostScript, an emulator that runs PostScript on your
139 computer instead of your printer. Most Linux distributions nowadays have
140 GhostScript running ``in the background'', so any configured printer
141 will act as a PostScript printer. Assuming this, the following command
146 If this does not make your printer produce a page of music, then you
147 should look into installing and configuring ghostscript. Refer to
148 GhostScript's website at @uref{http://www.ghostscript.com}.
150 There are three other routes: firstly, you can add titling to the
151 output. This is done by a separate program called @file{ly2dvi}: this
152 program first calls LilyPond to process the @file{.ly} file, and then
153 runs @TeX{} on it to produce a @file{.dvi} file with proper margin
154 settings and titling.
156 @cindex titles, adding
162 After some disk-activity, you should end up with a @file{.dvi} file.
163 Ly2dvi is further described in the @ref{ly2dvi}.
165 Secondly, you can generate PostScript directly. This is useful if you
166 can not or do not want to run @TeX{} on your system.
167 To obtain PS output, invoke LilyPond as follows:
168 @cindex PostScript output
170 lilypond -f ps test.ly
173 You have to set some environment variables to view or print this
174 output. More information can be found in the @ref{Invoking
177 Finally, there is a script called lilypond-book, that allows you to
178 freely mix LilyPond input with Texinfo or LaTeX input. For example, this
179 manual was written using lilypond-book. lilypond-book is discussed in
182 @unnumberedsubsec Windows
186 * setting of env vars (TFMINPUTS,MFINPUTS,TEXINPUTS)
187 * dvi viewer doesn't display postscript
191 @section The first tune
194 To demonstrate what LilyPond input looks like, we start off with a
195 full-fledged, yet simple example. It is a convoluted version
196 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
197 is included in the distribution as @file{menuet.ly}.
198 @cindex Bach, Johann Sebastian
201 % lines preceded by a percent are comments which
202 % are ignored by Lilypond.
203 \include "paper16.ly"
206 \relative c'' \sequential{
211 d4 g,8 a b c d4 g, g |
212 e'4 c8 d e fis g4 g, g |
213 c4 d8()c b a( )b4 c8 b a g |
214 a4 [b8 a] [g fis] g2. |
219 g4 e8 fis g d cis4 b8 cis a4 |
220 a8-. b-. cis-. d-. e-. fis-.
227 % standard settings are too wide for a book
228 linewidth = 14.0 \cm;
233 We will analyse the input, line by line.
235 % lines preceded by a percent are comments which
236 % are ignored by Lilypond.
238 The percent sign, @code{%}, introduces a line comment. If you want to
239 make larger comments, you can use block comments. These are delimited
240 by @code{%@{} and @code{%@}}
242 @cindex block comment
247 \include "paper16.ly"
250 @cindex @code{\include}
251 @cindex point, printer's
252 @cindex staff size setting
253 By default, LilyPond will use definitions for a staff that is 20
254 point@footnote {A point is the standard measure of length for printing;
255 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
256 output (16 point staff height), so we must import the settings for that
257 size, which is done here.
263 A lilypond file combines music with directions for outputting that
264 music. The music is combined with the output directions by putting
265 them into a @code{\score} block.
271 This makes LilyPond ready for accepting notes.
278 @cindex octaves, choosing
280 As we will see, pitches are combinations of octave, note name and
281 chromatic alteration. In this scheme, the octave is indicated by
282 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
283 @code{,}). The central C is denoted by @code{c'}. The C one octave
284 higher is @code{c''}. One and two octaves below the central C is
285 denoted by @code{c} and @code{c,} respectively.
288 For pitches in a long piece you might have to type many quotes. It is
289 easy to make typing errors with this, so LilyPond has a special entry
290 mode to remedy this. In this ``relative'' octave mode, octaves of notes
291 without quotes are chosen such that a note is as close as possible
292 (graphically, on the staff) to the the preceding note. If you add a
293 high-quote an extra octave is added. The lowered quote (a comma) will
294 subtract an extra octave. Because the first note has no predecessor,
295 you have to give the (absolute) pitch of the note to start with.
301 What follows is sequential music, i.e.,
302 @cindex sequential music
303 notes that are to be played and printed after each other.
309 @cindex time signature, setting
311 This command changes the time signature of the current piece: a 3/4
312 sign is printed. This command is also used to generate bar lines in
319 @cindex key signature, setting
321 This command changes the current key signature to G-major. Although this
322 command comes after the @code{\time} command, in the output, the key
323 signature comes before the time signature: LilyPond knows about music
324 typesetting conventions.
330 This command tells LilyPond that the following piece of music must be
331 played twice. The first argument indicates the type of repeat. In this
332 case, @code{"volta"} means that volta brackets are be used for
333 alternatives---if there were any.
339 The subject of the repeat is again sequential music. Since
340 @code{\sequential} is such a common construct, a shorthand is provided:
341 just leave off @code{\sequential}, and the result is the same.
347 This is a note with pitch @code{d} (determined up to octaves). The
348 relative music was started with a @code{c''}, so the real pitch of this
349 note is @code{d''}. The @code{4} designates the duration of the note
350 (it is a quarter note).
356 These are notes with pitch @code{a} and @code{b}. Because their
357 duration is the same as the @code{g}, there is no need to enter the
358 duration (You may enter it anyway, e.g. @code{a4 b4})
366 @cindex errors, finding
367 Three more notes. The @code{|} character is a `bar check'. When
368 processing the music, LilyPond will verify that bar checks are found at
369 the start of a measure. This can help you track down errors.
371 @cindex alteration, chromatic
372 @cindex chromatic alteration
373 So far, no notes were chromatically altered. Here is the first one
374 that is: @code{fis}. Lilypond by default uses Dutch note names, and
375 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
376 sharp sign in the output. The program keeps track of key signatures,
377 and will only print accidentals if they are needed.
383 LilyPond guesses were beams can be added to eighth and shorter notes.
384 In this case, a beam over 4 eighths is added.
387 c4 d8( )c b a( )b4 c8 b a g |
390 The next line shows how to make a slur: the beginning and ending note
391 of the slur is marked with an opening and closing parenthesis
392 respectively. In the line shown above, this is done for two slurs.
393 Slur markers (parentheses) are put between the slurred notes.
399 Automatic beaming can be overridden by inserting beam marks
400 (brackets). Brackets are put around the notes you want beamed.
406 @cindex augmentation dot
408 A duration with augmentation dot is notated
409 with the duration number followed by a period.
415 This ends the sequential music to be repeated. LilyPond will typeset
422 This line shows that Lily will print an accidental if that is
423 needed: the first C sharp of the bar will be printed with an accidental,
424 the second one without.
427 a8-. b-. cis-. d-. e-. fis-.
431 You can enter articulation signs either in a verbose form using a
432 shorthand. Here we demonstrate the shorthand: it is formed by a dash
433 and the character for the articulation to use, e.g. @code{-.} for
434 staccato as shown above.
441 Rests are denoted by the special notename @code{r}.
447 All articulations have a verbose form, like @code{\fermata}. The
448 command @code{\fermata} is not part of the core of the language (most
449 of the other discussed elements are), but it is a shorthand for a more
450 complicated description of a fermata. @code{\fermata} names that
451 description and is therefore called an identifier.
453 @cindex @code{\fermata}
468 This specifies a conversion from music to notation output. Most of
469 the details of this conversions (font sizes, dimensions, etc.) have
470 been taken care of, but to fit the output in this document, it has
471 to be smaller. We do this by setting the line width to 14 centimeters
472 (approximately 5.5 inches).
478 The last brace ends the @code{\score} block.
483 @node Lyrics and chords
484 @section Lyrics and chords
486 In this section we show how to typeset a song. This file is
487 included as @file{flowing.ly}.
491 title = "The river is flowing";
492 composer = "Traditional (?)";
494 \include "paper16.ly"
495 melody = \notes \relative c' @{
499 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
500 c4 c8 d [es () d] c4 | d4 es8 d c4.
505 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
506 ri -- ver is flo -- wing down to the sea.
509 accompaniment =\chords @{
511 c2:3- f:3-.7 d:min es4 c8:min r8
512 c2:min f:min7 g:7^3.5 c:min @}
517 \context ChordNames \accompaniment
520 \context Staff = mel @{
521 \property Staff.noAutoBeaming = ##t
522 \property Staff.automaticMelismata = ##t
525 \context Lyrics \text
527 \midi @{ \tempo 4=72;@}
528 \paper @{ linewidth = 10.0\cm; @}
533 The result would look this.@footnote{The titling and font size shown
534 may differ, since the titling in this document is not generated by
537 @center @strong{The river is flowing}
542 title = "The river is flowing";
543 composer = "Traditional (?)";
545 \include "paper16.ly"
546 melody = \notes \relative c' {
550 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
551 c4 c8 d [es () d] c4 | d4 es8 d c4.
556 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
557 ri -- ver is flo -- wing down to the sea.
560 accompaniment =\chords {
562 c2:3- f:3-.7 d:min es4 c8:min r8
563 c2:min f:min7 g:7^3.5 c:min }
568 \context ChordNames \accompaniment
571 \context Staff = mel {
572 \property Staff.noAutoBeaming = ##t
573 \property Staff.automaticMelismata = ##t
576 \context Lyrics \text
578 \midi { \tempo 4=72;}
579 \paper { linewidth = 10.0\cm; }
583 Again, we will dissect the file line by line.
589 @cindex @code{\header}
590 Information about the music you are about to typeset goes into a
591 @code{\header} block. The information in this block is not used by
592 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
593 information to print titles above the music.
596 title = "The river is flowing";
597 composer = "Traditional (?)";
600 @cindex identifier assignment
601 the @code{\header} block contains assignments. An assignment starts
602 with a string. (which is unquoted, in this case). Then comes the
603 equal sign. After the equal sign comes the expression you
604 want to store. In this case, you want to put in strings. The
605 information has to be quoted here, because it contains spaces. Each
606 assignment is finished with a semicolon.
609 \include "paper16.ly"
612 Smaller size for inclusion in a book.
615 melody = \notes \relative c' @{
618 The structure of the file will be the same as the previous one, a
619 @code{\score} block with music in it. To keep things readable, we will
620 give names to the different parts of music, and use the names to
621 construct the music within the score block.
627 @cindex @code{\partial}
629 The piece starts with an anacrusis of one eighth.
633 The key is C minor: we have three flats.
637 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
638 c4 c8 d [es () d] c4 | d4 es8 d c4.
643 @cindex manual beaming
644 @cindex automatic beaming, turning off
645 We use explicit beaming. Since this is a song, we will turn automatic
646 beams off, and use explicit beaming where needed.
652 This ends the definition of @code{melody}. Note that there are no
653 semicolons after assignments at top level.
660 @cindex identifier assignment
661 @cindex syllables, entering
662 Another identifier assignment. This one is for the lyrics.
663 Lyrics are formed by syllables that have duration, and not by
664 notes. To make LilyPond parse words as syllables, switch it into
665 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
666 is a shorthand for @code{\sequential @{}.
669 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
670 ri- ver is flo- __ wing down to the sea.
674 @cindex extenders, lyric
675 @cindex hyphens, lyric
676 The syllables themselves are separated by spaces. You can get syllable
677 extenders by entering @code{__}, and centered hyphens with
678 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
679 in length (hence the @code{4}), and use a feature to align the
680 syllables to the music (which obviously isn't all quarter notes.)
683 accompaniment =\chords @{
688 We'll put chords over the music, to enter them, there is a special mode,
689 called @code{\chords}. There is a special mode (analogous
690 to @code{\lyrics} and @code{\notes} mode) where you can give the names
691 of the chords you want, instead of the notes comprising the chord.
697 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, while a minor triad is wanted. @code{3-} modifies the third to
710 be small. @code{7} modifies (adds) a seventh, which is small by default
711 to create the @code{f a c es} chord. Multiple modifiers must be
719 Some modifiers have predefined names, eg. @code{min} is the same as
720 @code{3-}, so @code{d-min} is a minor @code{d} chord.
723 c2:min f:min7 g:7^3.5 c:min @}
726 @cindex named modifier
728 A named modifier @code{min} and a normal modifier @code{7} do not have
729 to be separated by a dot. Tones from a chord are removed with chord
730 subtractions. Subtractions are started with a caret, and they are
731 also separated by dots. In this example, @code{g:7^3.5} produces a
732 minor seventh. The brace ends the sequential music.
739 We assemble the music in the @code{\score} block. Melody, lyrics and
740 accompaniment have to sound at the same time, so they should be
741 @code{\simultaneous}.
742 @cindex @code{\simultaneous}
748 Chord mode generates notes grouped in @code{\simultaneous} music. If
749 you remove the comment sign, you can see the chords in normal
750 notation: they will be printed as note heads on a separate
754 \context ChordNames \accompaniment
758 @cindex interpretation context
759 @cindex notation context
760 Normally, the notes that you enter are transformed into note heads.
761 The note heads alone make no sense, they need surrounding information:
762 a key signature, a clef, staff lines, etc. They need @emph{context}. In
763 LilyPond, these symbols are created by objects called `interpretation
764 contexts'. Interpretation contexts only exist during a run of
765 LilyPond. Interpretation contexts that are for printing music (as
766 opposed to playing music) are called `notation contexts'.
768 By default, LilyPond will create a Staff context for you. If you
769 removed the @code{%} sign in the previous line, you would see that
772 We don't want that default here, because we want chord names, not note heads.
773 An interpretation context can also created upon explicit request. The
774 keyword for such a request is @code{\context}. It takes two arguments.
775 The first is the name of an interpretation context. The name is a
776 string, it can be quoted with double quotes). The second argument is
777 the music that should be interpreted in this context. For the previous
778 line, we could have written @code{\context Staff \accompaniment}, and
785 @cindex @code{\addlyrics}
786 @cindex lyrics and melody, combining
787 @cindex combining lyrics and melody
789 The lyrics need to be aligned with the melody. This is done by
790 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
791 pieces of music (usually a melody and lyrics, in that order) and
792 aligns the syllables of the second piece under the notes of the
793 first piece. If you would reverse the order, the notes would be
794 aligned on the lyrics, which is not very useful. (Besides, it looks
798 \context Staff = mel @{
802 This is the argument of @code{\addlyrics}. We instantiate a
803 @code{Staff} context explicitly: should you chose to remove the comment
804 before the ``note heads'' version of the accompaniment, the
805 accompaniment will be on a nameless staff. The melody has to be on a
806 different staff as the accompaniment. This is accomplished by giving
807 the melody staff a different name.
810 \property Staff.noAutoBeaming = ##t
814 @cindex context variables
815 @cindex setting context variables
816 An interpretation context has variables that tune its behaviour. One of
817 the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
818 the boolean value @var{true}, LilyPond will not try to put automatic beaming
819 on the current staff.
823 @cindex accessinng Scheme
824 @cindex evaluating Scheme
827 LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
828 a language from the LISP family. You can learn more about Scheme at
829 @uref{http://www.scheme.org}.} to represent data throughout the whole
830 program. The hash-sign (@code{#}) accesses GUILE directly: the code
831 following the hash-sign is evaluated as Scheme. The boolean value
832 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
837 \property Staff.automaticMelismata = ##t
840 @cindex automaticMelismata
842 @cindex @code{\addlyrics} and slurs
843 Similarly, we don't want to print a syllable when there is
844 a slur. This sets up @code{\addlyrics} to not put lyrics under notes
845 while there is a slur.
852 Finally, we put the melody on the current staff. Note that the
853 @code{\property} directives and @code{\melody} are grouped in sequential
854 music, so the property settings are done before the melody is
858 \context Lyrics \text
861 The second argument of @code{\addlyrics} is the text. The text also
862 should not land on a Staff, but on a interpretation context for
863 syllables, extenders, hyphens etc. This context is called
870 This ends @code{\simultaneous}.
873 \midi @{ \tempo 4=72;@}
876 This makes the music go to a MIDI file. MIDI is great for checking
877 music you enter. You listen to the MIDI file: if you hear something
878 unexpected, it's probably a typing error. @code{\midi} starts an output
879 definition, a declaration that specifies how to output music analogous
880 to @code{\paper @{ @}}. You can specify the tempo using the
881 @code{\tempo} command, in this case the tempo of quarter notes is set to
885 \paper @{ linewidth = 10.0\cm; @}
888 We also want notation output. The linewidth is short so the piece
889 will be set in two lines.
898 @section More movements
900 You probably ran @file{ly2dvi} on the last example, and ended up with a
901 viewable @file{.dvi} file. However, between there are a few steps of
902 which LilyPond is only one. To enhance your understanding of what's
903 happening under the hood when you run @code{ly2dvi}, we explain what
906 @code{ly2dvi} is a program that calls a number of programs in sequence.
907 The first thing it does, is running LilyPond on the input file. After
908 some calculations, a @file{.tex} is produced. The contents
909 of this file are very low-level instructions.
911 For example, the following file (@file{layout.ly})
915 \header @{ title = "Two miniatures"; @}
917 #(set! point-and-click line-column-location)
935 results in something like this@footnote{The titling in this manual was
936 not generated by ly2dvi, so details will differ.}
938 @center @strong{Two miniatures}
966 This file is produced by ly2dvi in a few stages, with the help of text
967 formatting tools. LilyPond produces two output files, @file{layout.tex}
968 and @file{layout-1.tex}. They both look like this:
972 \placebox@{-5 \outputscale @}%
973 @{ 8.7229 \outputscale @}%
974 @{\magfontWXGEomMMBo\char90 @}%
976 \placebox@{-4 \outputscale @}%
977 @{ 81.0647 \outputscale @}%
981 @file{ly2dvi} analyses the progress indication that LilyPond spews out,
982 and generates a file called @file{layout_ly1.tex}. This file contains
983 formatting instructions for the title and page layout. A fragment might
987 \geometry@{width=540.602362pt,headheight=2mm, ...
988 \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@} ...
990 \lilypondtitle@{foo@}%
996 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
997 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
998 is successful, this will produce a @file{.dvi} file, containing both the
999 titling and notes. @code{ly2dvi} completes its task by deleting the two
1000 temporary files, leaving only @file{layout.dvi}.
1002 Next, now we'll look at the examples line by line to explain new things.
1007 Lilypond and its language are still under development, and occasionally,
1008 details of the syntax are changed. This fragment indicates for which
1009 version the input file was written. When you compile this file, the
1010 version number will be checked, and you will get a warning when the file
1013 This version number is also used by the @code{convert-ly} program (See
1014 @ref{convert-ly}), which uses it update the file to the latest lily
1018 \header @{ title = "Two miniatures"; @}
1020 This sets the titling information for the entire file.
1023 #(set! point-and-click line-column-location)
1026 This is Scheme code. It sets the variable @code{point-and-click} to the
1029 Editing input files can be quite complicated if you're working with
1030 large files: if you're digitizing existing music, you have to
1031 synchronize the .ly file, the sheet music on your lap and the sheet
1032 music on the screen. The point-and-click mechanism makes it easy to
1033 find the origin of an error in the .ly file: @footnote{This feature is
1034 presently only available on X-windows using patched versions of Xdvi and
1035 emacs} when you view the file with Xdvi and click on a note using
1036 control-mousebutton 1@footnote{If you're using a patched xdvik, the
1037 command is control-mousebutton-2}, your editor will jump to the spot
1038 where that note was entered.
1040 More information is in in @ref{Point and click}
1046 The @code{\score} blocks that follow in the file don't have
1047 @code{\paper} sections, so the settings of this block are substituted: A
1048 paper block, at top-level, i.e. not in a @code{\score} block sets the
1049 default page layout.
1052 linewidth = -1.0; @}
1057 The variable @code{linewidth} normally sets the length of the systems on
1058 the page. However, a negative value has a special meaning. If
1059 @code{linewidth} is less than 0, no line breaks are inserted into the
1060 score, and the spacing is set to natural length: a short phrase takes up
1061 little space, a longer phrase more space.
1065 \notes @{ c'4 d'4 @}
1068 In previous examples, notes were specified in relative octaves,
1069 i.e. each note was put in the octave that would put it closest to its
1070 predecessor. Besides relative, there is also absolute octave
1071 specification, and it is turned on by default. In this input mode, the
1072 central C is denoted by @code{c'}. Going down, you get @code{c}
1073 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} etc.
1075 When you're copying music from existing sheet music, relative octaves
1076 are probably the easiest to use: it's less typing work and errors are
1077 easily spotted. However, if you write LilyPond input, either by hand
1078 (ie. composing) or by computer, absolute octaves are probably less work.
1085 The @code{\header} is normally at the top of the file, where it sets
1086 values for the rest of the file. If you want to typeset different pieces
1087 from one file (for example, if there are multiple movements, or if
1088 you're making a etude-book), you can put different @code{\score} blocks
1089 into the input file. ly2dvi will assemble all LilyPond output files into
1090 a big document. The contents of \header blocks specified within each
1091 score, are used for the titling of each movement.
1096 For example, the Opus number is put at the right, and the piece string
1097 will be at the left.
1101 @node A piano excerpt
1102 @section A piano excerpt
1104 Our third subject is a piece of piano music. The fragment in the input
1105 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1106 Sammartini. It was composed around 1740. It's in the source package
1107 under the name @file{sammartini.ly}.
1110 \include "paper16.ly";
1112 stemDown = \property Voice.Stem \override #'direction = #-1
1113 stemUp = \property Voice.Stem \override #'direction = #1
1114 stemBoth = \property Voice.Stem \revert #'direction
1116 viola = \notes \relative c' \context Voice = viola {
1117 <c4-\f-\arpeggio g' c>
1123 oboes = \notes \relative c'' \context Voice = oboe {
1124 \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1125 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
1127 { \times 2/3 { a8 g c } \! c2 }
1128 \context Voice = oboeTwo {
1131 \property Grace.Stem \override #'direction = #-1
1136 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1137 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1138 [<c16( e> < )e8. g>] <c8 e,>
1141 hoomPah = \repeat unfold 8
1142 \notes \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }
1144 bassvoices = \notes \relative c' {
1146 \autochange Staff \hoomPah
1147 \translator Staff = down
1148 \stemDown [c8 c'8] r4
1150 < {\stemUp r2 <e4 c'> <c8 g'> }
1151 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
1155 \context PianoStaff \notes <
1156 \context Staff = up < \time 2/2;
1160 \context Staff = down < \time 2/2; \clef bass;
1167 linewidth = 15.0 \cm; }
1171 If it looks like incomprehensible gibberish to you, then you are right.
1172 This example has been doctored to have as many quirks as possible.
1175 stemDown = \property Voice.Stem \override #'direction = #-1
1178 As you can see, this example features more voices on one staff. To make
1179 room for those voices, their notes have to be stemmed in opposite
1180 directions. These are the commands to make that happen.
1182 The symbols that are printed, are internally represented by so-called
1183 Graphical Objects (or more colloquially: Grobs). These statements
1184 concern the grob called `Stem'. Each grob is described by a bunch of
1185 settings. These setting determine the fonts, offsets, sub-routines to be
1186 called on the grob, etc. The initial values of these settings are set
1187 in the Scheme file @file{scm/grob-description.scm}.
1189 This statement adds a the setting for all Stem grobs in the current
1190 Voice: @code{direction} is set to @code{-1}, which encodes down. The
1191 setting remains in effect until it is reverted.
1194 \property Voice.Stem \revert #'direction
1197 This statement reverts the old setting. If you do this, the effect of a
1198 @code{\stemDown} or @code{\stemUp} is neutralised.
1200 @code{\override} and @code{\revert} function like a stack: you can push
1201 values onto the grob-setting-stack with @code{\override} and you pop
1202 them with @code{\revert}.
1204 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1205 with some more often used formatting instructions, but to explain how it
1206 works, we wrote our own here. Of course, you should use predefined
1207 identifiers like these if possible: then you will be affected less by
1208 the implementation changes we occasionally make.
1211 viola = \notes \relative c' \context Voice = viola @{
1213 In this example, you can see multiple parts on a staff. Each part is
1214 associated with one notation context. This notation context handles
1215 stems and dynamics (among others). The name of this context is
1216 @code{Voice}. For each part we have to make sure that there is
1217 precisely one @code{Voice} context, so we give it an unique name
1221 <c4-\f-\arpeggio g' c>
1223 The delimiters @code{<} and @code{>} are shorthands for
1224 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1225 @code{<} and @code{>} is a chord.
1232 @code{\f} places a forte symbol under the chord. The forte applies to
1233 the whole chord, but the syntax requires that commands like forte and
1234 arpeggio are attached to a note, so here we attach them to the first
1237 @code{\arpeggio} draws an vertical wavy line before the chord,
1238 signifying an arpeggio.
1248 Relative octaves work a little differently with chords. The starting
1249 point for the note following a chord is the first note of the chord. So
1250 the @code{g} gets an octave up quote: it is a fifth above the starting
1251 note of the previous chord (the central C).
1256 @code{s} is a spacer rest. It does not print anything, but it does have
1257 the duration of a rest. It is useful for filling up voices that
1258 temporarily don't play. In this case, the viola doesn't come until one
1259 and a half measure later.
1262 oboes = \notes \relative c'' \context Voice = oboe @{
1264 Now comes a part for two oboes. They play homophonically, so we
1265 print the notes as one voice that makes chords. Again, we insure that
1266 these notes are indeed processed by precisely one context with
1269 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1271 @code{\stemUp} is a reference to the @code{\property \override} command
1274 \grace <e8 g> < d4 f> <c2 e>
1276 @cindex @code{\grace}
1280 @code{\grace} introduces grace notes. It takes one argument, in this
1284 The slur started on the @code{e} of the chord
1285 will be attached to the next note.@footnote{LilyPond will squirm
1286 about unended Slurs. In this case, you can ignore the warning}.
1293 Tuplets are made with the @code{\times} keyword. It takes two
1294 arguments: a fraction and a piece of music. The duration of the piece
1295 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1296 of their notated duration, so in this case the fraction is 2/3.
1298 @{ <d8 \< f> <e g> <f a> @}
1300 The piece of music to be `tripletted' is sequential music containing
1301 three notes. On the first chord, a crescendo is started with
1302 @code{\<}. To be precise, the crescendo start is syntactically attached
1303 to the preceding note, the @code{d}.
1312 At this point, the homophonic music splits into two rhythmically
1313 different parts. We can't use a sequence of chords to enter this, so
1314 we make a `chord' of sequences to do it. We start with the upper
1315 voice, which continues with upward stems:
1317 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1322 The crescendo is ended at the half note by the escaped exclamation
1325 \context Voice = oboeTwo @{
1328 We can't share stems with the other voice, so we have to create a new
1329 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1330 it from the other context. Stems go down in this voice.
1334 @cindex Grace context
1335 When a grace section is processed, a @code{Grace} context is
1336 created. This context acts like a miniature score of its own. It has
1337 its own time bookkeeping, and you can make notes, beams, slurs
1338 etc. Here we fiddle with a property and make a beam. The argument of
1339 @code{\grace} is sequential music.
1342 \property Grace.Stem \override #'direction = #-1
1346 Normally, grace notes are always stem up, but in this case, the upper
1347 voice interferes. We set the stems down here.
1349 As far as relative mode is concerned, the previous note is the
1350 @code{c'''2} of the upper voice, so we have to go an octave down for
1357 This ends the two-part section.
1360 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1365 @code{\stemBoth} ends the forced stem directions. From here, stems are
1366 positioned as if it were single part music.
1368 The bass has a little hoom-pah melody to demonstrate parts switching
1369 between staffs. Since it is repetitive, we use repeats:
1371 hoomPah = \repeat unfold 8
1373 @cindex unfolded @code{\repeat}
1374 This repeat print the following sequence notes eight times.
1376 \notes \transpose c' @{
1379 @cindex relative mode and transposing
1381 Transposing can be done with @code{\transpose}. It takes two arguments;
1382 the first specifies what central C should be transposed to. The second
1383 is the to-be-transposed music. As you can see, in this case, the
1384 transposition is a no-op, as central C stay at central C.
1386 The purpose of this no-op is circumventing relative mode. Relative mode
1387 can not be used together with transposition, so @code{\relative} will
1388 leave the contents of @code{\hoomPah} alone. We can use it without
1389 having to worry about getting the motive in a wrong octave.
1391 bassvoices = \notes \relative c' @{
1393 \autochange Staff \hoomPah
1395 @cindex staff switch, automatic
1396 @cindex cross staff voice, automatic
1397 @cindex @code{\autochange}
1399 Voices can switch between staffs. The easiest way to get this, is to use
1400 @code{\autochange}. This command looks at the pitch of each note, and if
1401 necessary, will cross to the other staff. For this to work, the two
1402 staffs must be called @code{"up"} and @code{"down"}.
1404 \translator Staff = down
1406 @cindex staff switch
1407 @cindex cross staff voice
1408 The rest of this melody must be in the lower staff, so we do a manual
1413 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1417 After skipping some lines, we see @code{~}. This mark makes ties.
1421 A special context is needed to get cross staff beaming right. This
1422 context is called @code{PianoStaff}.
1424 \context Staff = bottom < \time 2/2; \clef bass;
1426 The bottom staff must have a different clef.
1430 To make some more room on the line, the first (in this case the only)
1431 line is not indented. The line still looks very cramped, but that is due
1432 to the page layout of this document.
1438 * font-size, multi-stanza.
1440 * Simple part combining in a Hymn
1443 @node An orchestral score
1444 @section An orchestral score
1446 If you've come this far, you should have seen enough LilyPond source to
1447 feel comfortable with an orchestral score. We will not go through the
1448 input line by line, but only indicate and explain the new elements.
1450 This orchestral score example consists of three input files. In the
1451 first file, @file{os-music.ly}, we define the music for all instruments.
1452 This file is to be used by the other two files, as you will see below.
1453 If you run lilypond on this file, no output will be produced.
1459 title = "Zo, goed lieverd?";
1460 subtitle = "How's, this babe?";
1463 piece = "Laid back";
1467 \skip 2*4; \bar "|.";
1469 Key = \notes \key as \major;
1470 flautoI = \notes\relative c'' @{
1472 bes as bes as bes as bes as
1474 flautoII = \notes\relative c'' @{
1475 as8 bes as bes R1 d4 ~ d
1477 tromboI = \notes\relative c'' @{
1478 c4. c8 c8 c4. es4 R1*1/2 es4
1480 tromboII = \notes\relative c'' @{
1481 as4. as8 as8 as4. R1*1/2 as4 es'
1483 timpani = \notes\relative c, @{
1484 \times 2/3 @{ f4 f f @}
1485 \times 4/5 @{ as8 as as as as @}
1488 corno = \notes\relative c' @{
1489 bes4 d f, bes d f, bes d
1493 Things to note here are the definition of @code{\global} where we define
1494 meter, and set the end bar. And the separate definition of @code{\Key}
1495 that we will use all staffs except staffs for transposing instruments.
1497 The second file, @file{os-score.ly} reads the definitions of the first
1498 (@file{os-music.ly}), and defines the @code{\score} block for the full
1503 \include "os-music.ly";
1504 \include "paper13.ly";
1506 #(set! point-and-click line-column-location)
1507 #(define text-flat '((font-relative-size . -2)
1508 (music "accidentals--1")))
1513 \context StaffGroup = woodwind <
1514 \context Staff = flauti <
1515 \property Staff.midiInstrument = #"flute"
1516 \property Staff.instrument = "2 Flauti"
1517 \property Staff.instr = "Fl."
1519 \context Voice=one @{ \voiceOne \flautoI @}
1520 \context Voice=two @{ \voiceTwo \flautoII @}
1523 \context StaffGroup = timpani <
1524 \context Staff = timpani <
1525 \property Staff.midiInstrument = #"timpani"
1526 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1527 \property Staff.instr = #"Timp."
1533 \context StaffGroup = brass <
1534 \context Staff = trombe <
1535 \property Staff.midiInstrument = #"trumpet"
1536 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
1537 \property Staff.instr = #`(lines "Tbe." "(C)")
1539 \context Voice=one \partcombine Voice
1540 \context Thread=one \tromboI
1541 \context Thread=two \tromboII
1543 \context Staff = corni <
1544 \property Staff.midiInstrument = #"french horn"
1545 \property Staff.instrument = #`(lines "Corno"
1546 (rows "(E" ,text-flat ")"))
1547 \property Staff.instr = #`(lines "Cor."
1548 (rows "(E" ,text-flat ")"))
1549 \property Staff.transposing = #3
1550 \notes \key bes \major;
1551 \context Voice=one \corno
1556 indent = 15 * \staffspace;
1557 linewidth = 60 * \staffspace;
1558 textheight = 90 * \staffspace;
1561 \consists "Rest_engraver";
1565 \remove "Rest_engraver";
1566 \consists "Multi_measure_rest_engraver";
1567 \consists "Bar_engraver";
1570 \HaraKiriStaffContext
1571 \remove "Multi_measure_rest_engraver";
1572 \remove "Bar_engraver";
1575 \OrchestralScoreContext
1576 BarNumber \override #'padding = #3
1585 @center @strong{Zo, goed lieverd?}
1587 @center How's, this babe?
1595 @lilypondfile{os-score.ly}
1597 First, we need to include the music definitions we made in
1600 \include "os-music.ly";
1603 In a large orchestral score like this you're bound to make some small
1604 mistakes, so we enable point and click (See @ref{Point and click})
1607 #(set! point-and-click line-column-location)
1610 We need a flat sign in text to name the tuning of the french horn, so we
1611 predefine it with bit of scheme markup text (See @ref{Text markup}).
1613 #(define text-flat '((font-relative-size . -2)
1614 (music "accidentals--1")))
1617 Of course, all staffs are simultaneous and use the same global settings.
1623 Then, we start a new staff group for the woodwind section (just the
1624 flutes in this case). Immediately after that, we start the staff for
1625 the two flutes, that also play simultaneously.
1627 \context StaffGroup = woodwind <
1628 \context Staff = flauti <
1631 We specify the intrument for MIDI output (see @ref{MIDI instrument
1634 \property Staff.midiInstrument = #"flute"
1637 And define the intrument names to be printed in the margin,
1638 @code{instrument} for the first line of the score, @code{instr} for the
1641 \property Staff.instrument = "2 Flauti"
1642 \property Staff.instr = "Fl."
1645 The flutes play in the default key.
1650 Last come the actual flute parts. Remember that we're still in
1651 simultaneous mode. We name both voices differently, so that LilyPond
1652 will actually create two Voice contexts. The flute parts are simple, so
1653 we specify manually which voice is which: @code{\voiceOne} forces the
1654 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
1657 \context Voice=one @{ \voiceOne \flautoI @}
1658 \context Voice=two @{ \voiceTwo \flautoII @}
1661 We close the flutes staff and woodwind staff group.
1667 The timpani staff only shows a new piece of scheme markup, it sets two
1670 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1673 For the trumpets we use the automatic part combiner (see @ref{Automatic
1674 part combining}) to combine the two simultaneous trumpet parts onto the
1675 trumpet staff. Each trumpet gets its own Thread context, which must be
1676 named @code{one} and @code{two}). The part combiner makes these two
1677 threads share a Voice when they're similar, and splits the threads up
1678 when they're different.
1680 \context Voice=one \partcombine Voice
1681 \context Thread=one \tromboI
1682 \context Thread=two \tromboII
1685 The french horn has the most complex scheme markup name, made up of two
1686 lines of text. The second line has two elements (rows), the @code{E}
1687 and the flat sign @code{text-flat} that we defined before.
1689 \property Staff.instrument = #`(lines "Corno"
1690 (rows "(E" ,text-flat ")"))
1693 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
1694 transpose this staff by three steps.
1696 \property Staff.transposing = #3
1699 Therefore, it has a different key.
1701 \notes \key bes \major;
1704 We specify a big indent for the first line and a small linewith for this
1707 indent = 15 * \staffspace;
1708 linewidth = 60 * \staffspace;
1711 Because we have a Thread representing one instrument, we need to move
1712 the @code{Rest_engraver} from Voice to Thread level. Similarly, we need
1713 to move the @code{Multi_measure_rest_engraver} from Staff to Voice level.
1717 \consists "Rest_engraver";
1721 \remove "Rest_engraver";
1722 \consists "Multi_measure_rest_engraver";
1723 \consists "Bar_engraver";
1727 In orchestral scores, it often happens that one instrument has only
1728 rests during one line of the score. The @code{HaraKiriStaffContext} can
1729 be used as a regular @code{StaffContext} drop-in and will take care of
1730 the automatic removing of empty staffs.
1733 \HaraKiriStaffContext
1734 \remove "Multi_measure_rest_engraver";
1735 \remove "Bar_engraver";
1739 We want bar numbering at score level and want to move the bar number a
1740 few staff spaces up.
1743 \OrchestralScoreContext
1744 BarNumber \override #'padding = #3
1748 @node Part extraction
1749 @section Part extraction
1751 The third file, @file{os-flute-2.ly} also reads the definitions of the
1752 first (@file{os-music.ly}), and defines the @code{\score} block for the
1756 \include "os-music.ly";
1757 \include "paper16.ly";
1761 \property Staff.midiInstrument = #"flute"
1767 instrument = "Flauto II";
1770 linewidth = 80 * \staffspace;
1771 textheight = 200 * \staffspace;
1773 \OrchestralScoreContext
1783 @center @strong{Zo, goed lieverd?}
1785 @center How's, this babe?
1786 @center @emph{Flauto II}
1793 @lilypondfile{os-flute-2.ly}
1796 Because we separated the music definitions from the @code{\score}
1797 instantiations, we can easily define a second score from the music of
1798 the second flute. This then is the part for the second flute player.
1799 Of course, we make separate parts for all individual instruments.
1801 In this individual part the second flute has a whole staff for itself,
1802 so we don't want to force stem or tie directions.
1807 The @code{\header} definitions were also read from @file{os-music.ly},
1808 but we need to set the instrument for this particular score.
1811 instrument = "Flauto II";
1815 In the conductor's full score, all bars with rests are printed, but for
1816 the individual parts, we want to contract pieces of consecutive empty
1822 @node end of tutorial
1825 That's all folks. From here, you can either try fiddling with input
1826 files, or you can read the reference manual. You can find more example
1827 files in @file{input} and @file{input/test}. You can also look at Real
1828 Music (TM), have a look at the @ref{Mutopia project}.
1832 [TODO figure out what to do with this: ]
1835 @node Pre-cooked makefile
1836 @section Pre-cooked makefile
1838 @c waar deze info? is uiteindelijk wel handig, schat ik.
1841 If you have a big music project, or just a lot of LilyPond input files,
1842 all generated output from LilyPond, @TeX{} and metafont will clutter
1843 your working directory. LilyPond comes with a one-size-fits-all
1844 pre-cooked makefile that helps you manage producing ouptut. It will
1845 produce all output in @file{out}, generate and track dependencies.
1846 Also, it helps in preparing your submission to the @ref{Mutopia
1853 cp /usr/share/lilypond/make/ly.make GNUmakefile
1854 cp /usr/share/doc/lilypond/examples/input/tutorial/menuet.ly .
1857 Generated out/menuet.ps for target menuet.
1860 Type @samp{make help} to see possible targets.
1863 @file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}