7 * Introduction:: Introduction
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
187 @section The first tune
190 To demonstrate what LilyPond input looks like, we start off with a
191 full-fledged, yet simple example. It is a convoluted version
192 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
193 is included in the distribution as @file{menuet.ly}.
194 @cindex Bach, Johann Sebastian
197 % lines preceded by a percent are comments which
198 % are ignored by Lilypond.
199 \include "paper16.ly"
202 \relative c'' \sequential{
207 d4 g,8 a b c d4 g, g |
208 e'4 c8 d e fis g4 g, g |
209 c4 d8()c b a( )b4 c8 b a g |
210 a4 [b8 a] [g fis] g2. |
215 g4 e8 fis g d cis4 b8 cis a4 |
216 a8-. b-. cis-. d-. e-. fis-.
223 % standard settings are too wide for a book
224 linewidth = 14.0 \cm;
229 We will analyse the input, line by line.
231 % lines preceded by a percent are comments which
232 % are ignored by Lilypond.
234 The percent sign, @code{%}, introduces a line comment. If you want to
235 make larger comments, you can use block comments. These are delimited
236 by @code{%@{} and @code{%@}}
238 @cindex block comment
243 \include "paper16.ly"
246 @cindex @code{\include}
247 @cindex point, printer's
248 @cindex staff size setting
249 By default, LilyPond will use definitions for a staff that is 20
250 point@footnote {A point is the standard measure of length for printing;
251 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
252 output (16 point staff height), so we must import the settings for that
253 size, which is done here.
259 A lilypond file combines music with directions for outputting that
260 music. The music is combined with the output directions by putting
261 them into a @code{\score} block.
267 This makes LilyPond ready for accepting notes.
274 @cindex octaves, choosing
276 As we will see, pitches are combinations of octave, note name and
277 chromatic alteration. In this scheme, the octave is indicated by
278 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
279 @code{,}). The central C is denoted by @code{c'}. The C one octave
280 higher is @code{c''}. One and two octaves below the central C is
281 denoted by @code{c} and @code{c,} respectively.
284 For pitches in a long piece you might have to type many quotes. It is
285 easy to make typing errors with this, so LilyPond has a special entry
286 mode to remedy this. In this ``relative'' octave mode, octaves of notes
287 without quotes are chosen such that a note is as close as possible
288 (graphically, on the staff) to the the preceding note. If you add a
289 high-quote an extra octave is added. The lowered quote (a comma) will
290 subtract an extra octave. Because the first note has no predecessor,
291 you have to give the (absolute) pitch of the note to start with.
297 What follows is sequential music, i.e.,
298 @cindex sequential music
299 notes that are to be played and printed after each other.
305 @cindex time signature, setting
307 This command changes the time signature of the current piece: a 3/4
308 sign is printed. This command is also used to generate bar lines in
315 @cindex key signature, setting
317 This command changes the current key signature to G-major. Although this
318 command comes after the @code{\time} command, in the output, the key
319 signature comes before the time signature: LilyPond knows about music
320 typesetting conventions.
326 This command tells LilyPond that the following piece of music must be
327 played twice. The first argument indicates the type of repeat. In this
328 case, @code{"volta"} means that volta brackets are be used for
329 alternatives---if there were any.
335 The subject of the repeat is again sequential music. Since
336 @code{\sequential} is such a common construct, a shorthand is provided:
337 just leave off @code{\sequential}, and the result is the same.
343 This is a note with pitch @code{d} (determined up to octaves). The
344 relative music was started with a @code{c''}, so the real pitch of this
345 note is @code{d''}. The @code{4} designates the duration of the note
346 (it is a quarter note).
352 These are notes with pitch @code{a} and @code{b}. Because their
353 duration is the same as the @code{g}, there is no need to enter the
354 duration (You may enter it anyway, e.g. @code{a4 b4})
362 @cindex errors, finding
363 Three more notes. The @code{|} character is a `bar check'. When
364 processing the music, LilyPond will verify that bar checks are found at
365 the start of a measure. This can help you track down errors.
367 @cindex alteration, chromatic
368 @cindex chromatic alteration
369 So far, no notes were chromatically altered. Here is the first one
370 that is: @code{fis}. Lilypond by default uses Dutch note names, and
371 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
372 sharp sign in the output. The program keeps track of key signatures,
373 and will only print accidentals if they are needed.
379 LilyPond guesses were beams can be added to eighth and shorter notes.
380 In this case, a beam over 4 eighths is added.
383 c4 d8( )c b a( )b4 c8 b a g |
386 The next line shows how to make a slur: the beginning and ending note
387 of the slur is marked with an opening and closing parenthesis
388 respectively. In the line shown above, this is done for two slurs.
389 Slur markers (parentheses) are put between the slurred notes.
395 Automatic beaming can be overridden by inserting beam marks
396 (brackets). Brackets are put around the notes you want beamed.
402 @cindex augmentation dot
404 A duration with augmentation dot is notated
405 with the duration number followed by a period.
411 This ends the sequential music to be repeated. LilyPond will typeset
418 This line shows that Lily will print an accidental if that is
419 needed: the first C sharp of the bar will be printed with an accidental,
420 the second one without.
423 a8-. b-. cis-. d-. e-. fis-.
427 You can enter articulation signs either in a verbose form using a
428 shorthand. Here we demonstrate the shorthand: it is formed by a dash
429 and the character for the articulation to use, e.g. @code{-.} for
430 staccato as shown above.
437 Rests are denoted by the special notename @code{r}.
443 All articulations have a verbose form, like @code{\fermata}. The
444 command @code{\fermata} is not part of the core of the language (most
445 of the other discussed elements are), but it is a shorthand for a more
446 complicated description of a fermata. @code{\fermata} names that
447 description and is therefore called an identifier.
449 @cindex @code{\fermata}
464 This specifies a conversion from music to notation output. Most of
465 the details of this conversions (font sizes, dimensions, etc.) have
466 been taken care of, but to fit the output in this document, it has
467 to be smaller. We do this by setting the line width to 14 centimeters
468 (approximately 5.5 inches).
474 The last brace ends the @code{\score} block.
479 @node Lyrics and chords
480 @section Lyrics and chords
482 In this section we show how to typeset a song. This file is
483 included as @file{flowing.ly}.
487 title = "The river is flowing";
488 composer = "Traditional (?)";
490 \include "paper16.ly"
491 melody = \notes \relative c' @{
495 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
496 c4 c8 d [es () d] c4 | d4 es8 d c4.
501 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
502 ri -- ver is flo -- wing down to the sea.
505 accompaniment =\chords @{
507 c2:3- f:3-.7 d:min es4 c8:min r8
508 c2:min f:min7 g:7^3.5 c:min @}
513 \context ChordNames \accompaniment
516 \context Staff = mel @{
517 \property Staff.noAutoBeaming = ##t
518 \property Staff.automaticMelismata = ##t
521 \context Lyrics \text
523 \midi @{ \tempo 4=72;@}
524 \paper @{ linewidth = 10.0\cm; @}
529 The result would look this.@footnote{The titling and font size shown
530 may differ, since the titling in this document is not generated by
533 @center @strong{The river is flowing}
538 title = "The river is flowing";
539 composer = "Traditional (?)";
541 \include "paper16.ly"
542 melody = \notes \relative c' {
546 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
547 c4 c8 d [es () d] c4 | d4 es8 d c4.
552 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
553 ri -- ver is flo -- wing down to the sea.
556 accompaniment =\chords {
558 c2:3- f:3-.7 d:min es4 c8:min r8
559 c2:min f:min7 g:7^3.5 c:min }
564 \context ChordNames \accompaniment
567 \context Staff = mel {
568 \property Staff.noAutoBeaming = ##t
569 \property Staff.automaticMelismata = ##t
572 \context Lyrics \text
574 \midi { \tempo 4=72;}
575 \paper { linewidth = 10.0\cm; }
579 Again, we will dissect the file line by line.
585 @cindex @code{\header}
586 Information about the music you are about to typeset goes into a
587 @code{\header} block. The information in this block is not used by
588 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
589 information to print titles above the music.
592 title = "The river is flowing";
593 composer = "Traditional (?)";
596 @cindex identifier assignment
597 the @code{\header} block contains assignments. An assignment starts
598 with a string. (which is unquoted, in this case). Then comes the
599 equal sign. After the equal sign comes the expression you
600 want to store. In this case, you want to put in strings. The
601 information has to be quoted here, because it contains spaces. Each
602 assignment is finished with a semicolon.
605 \include "paper16.ly"
608 Smaller size for inclusion in a book.
611 melody = \notes \relative c' @{
614 The structure of the file will be the same as the previous one, a
615 @code{\score} block with music in it. To keep things readable, we will
616 give names to the different parts of music, and use the names to
617 construct the music within the score block.
623 @cindex @code{\partial}
625 The piece starts with an anacrusis of one eighth.
629 The key is C minor: we have three flats.
633 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
634 c4 c8 d [es () d] c4 | d4 es8 d c4.
639 @cindex manual beaming
640 @cindex automatic beaming, turning off
641 We use explicit beaming. Since this is a song, we will turn automatic
642 beams off, and use explicit beaming where needed.
648 This ends the definition of @code{melody}. Note that there are no
649 semicolons after assignments at top level.
656 @cindex identifier assignment
657 @cindex syllables, entering
658 Another identifier assignment. This one is for the lyrics.
659 Lyrics are formed by syllables that have duration, and not by
660 notes. To make LilyPond parse words as syllables, switch it into
661 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
662 is a shorthand for @code{\sequential @{}.
665 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
666 ri- ver is flo- __ wing down to the sea.
670 @cindex extenders, lyric
671 @cindex hyphens, lyric
672 The syllables themselves are separated by spaces. You can get syllable
673 extenders by entering @code{__}, and centered hyphens with
674 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
675 in length (hence the @code{4}), and use a feature to align the
676 syllables to the music (which obviously isn't all quarter notes.)
679 accompaniment =\chords @{
684 We'll put chords over the music, to enter them, there is a special mode,
685 called @code{\chords}. There is a special mode (analogous
686 to @code{\lyrics} and @code{\notes} mode) where you can give the names
687 of the chords you want, instead of the notes comprising the chord.
693 There is no accompaniment during the anacrusis.
701 @cindex chord modifier
702 @cindex modifier, chord
703 A chord is started by the tonic of the chord. The
704 first one lasts a half note. An unadorned note creates a major
705 triad, while a minor triad is wanted. @code{3-} modifies the third to
706 be small. @code{7} modifies (adds) a seventh, which is small by default
707 to create the @code{f a c es} chord. Multiple modifiers must be
715 Some modifiers have predefined names, eg. @code{min} is the same as
716 @code{3-}, so @code{d-min} is a minor @code{d} chord.
719 c2:min f:min7 g:7^3.5 c:min @}
722 @cindex named modifier
724 A named modifier @code{min} and a normal modifier @code{7} do not have
725 to be separated by a dot. Tones from a chord are removed with chord
726 subtractions. Subtractions are started with a caret, and they are
727 also separated by dots. In this example, @code{g:7^3.5} produces a
728 minor seventh. The brace ends the sequential music.
735 We assemble the music in the @code{\score} block. Melody, lyrics and
736 accompaniment have to sound at the same time, so they should be
737 @code{\simultaneous}.
738 @cindex @code{\simultaneous}
744 Chord mode generates notes grouped in @code{\simultaneous} music. If
745 you remove the comment sign, you can see the chords in normal
746 notation: they will be printed as note heads on a separate
750 \context ChordNames \accompaniment
754 @cindex interpretation context
755 @cindex notation context
756 Normally, the notes that you enter are transformed into note heads.
757 The note heads alone make no sense, they need surrounding information:
758 a key signature, a clef, staff lines, etc. They need @emph{context}. In
759 LilyPond, these symbols are created by objects called `interpretation
760 contexts'. Interpretation contexts only exist during a run of
761 LilyPond. Interpretation contexts that are for printing music (as
762 opposed to playing music) are called `notation contexts'.
764 By default, LilyPond will create a Staff context for you. If you
765 removed the @code{%} sign in the previous line, you would see that
768 We don't want that default here, because we want chord names, not note heads.
769 An interpretation context can also created upon explicit request. The
770 keyword for such a request is @code{\context}. It takes two arguments.
771 The first is the name of an interpretation context. The name is a
772 string, it can be quoted with double quotes). The second argument is
773 the music that should be interpreted in this context. For the previous
774 line, we could have written @code{\context Staff \accompaniment}, and
781 @cindex @code{\addlyrics}
782 @cindex lyrics and melody, combining
783 @cindex combining lyrics and melody
785 The lyrics need to be aligned with the melody. This is done by
786 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
787 pieces of music (usually a melody and lyrics, in that order) and
788 aligns the syllables of the second piece under the notes of the
789 first piece. If you would reverse the order, the notes would be
790 aligned on the lyrics, which is not very useful. (Besides, it looks
794 \context Staff = mel @{
798 This is the argument of @code{\addlyrics}. We instantiate a
799 @code{Staff} context explicitly: should you chose to remove the comment
800 before the ``note heads'' version of the accompaniment, the
801 accompaniment will be on a nameless staff. The melody has to be on a
802 different staff as the accompaniment. This is accomplished by giving
803 the melody staff a different name.
806 \property Staff.noAutoBeaming = ##t
810 @cindex context variables
811 @cindex setting context variables
812 An interpretation context has variables that tune its behaviour. One of
813 the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
814 the boolean value @var{true}, LilyPond will not try to put automatic beaming
815 on the current staff.
819 @cindex accessinng Scheme
820 @cindex evaluating Scheme
823 LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
824 a language from the LISP family. You can learn more about Scheme at
825 @uref{http://www.scheme.org}.} to represent data throughout the whole
826 program. The hash-sign (@code{#}) accesses GUILE directly: the code
827 following the hash-sign is evaluated as Scheme. The boolean value
828 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
833 \property Staff.automaticMelismata = ##t
836 @cindex automaticMelismata
838 @cindex @code{\addlyrics} and slurs
839 Similarly, we don't want to print a syllable when there is
840 a slur. This sets up @code{\addlyrics} to not put lyrics under notes
841 while there is a slur.
848 Finally, we put the melody on the current staff. Note that the
849 @code{\property} directives and @code{\melody} are grouped in sequential
850 music, so the property settings are done before the melody is
854 \context Lyrics \text
857 The second argument of @code{\addlyrics} is the text. The text also
858 should not land on a Staff, but on a interpretation context for
859 syllables, extenders, hyphens etc. This context is called
866 This ends @code{\simultaneous}.
869 \midi @{ \tempo 4=72;@}
872 This makes the music go to a MIDI file. MIDI is great for checking
873 music you enter. You listen to the MIDI file: if you hear something
874 unexpected, it's probably a typing error. @code{\midi} starts an output
875 definition, a declaration that specifies how to output music analogous
876 to @code{\paper @{ @}}. You can specify the tempo using the
877 @code{\tempo} command, in this case the tempo of quarter notes is set to
881 \paper @{ linewidth = 10.0\cm; @}
884 We also want notation output. The linewidth is short so the piece
885 will be set in two lines.
894 @section More movements
896 You probably ran @file{ly2dvi} on the last example, and ended up with a
897 viewable @file{.dvi} file. However, between there are a few steps of
898 which LilyPond is only one. To enhance your understanding of what's
899 happening under the hood when you run @code{ly2dvi}, we explain what
902 @code{ly2dvi} is a program that calls a number of programs in sequence.
903 The first thing it does, is running LilyPond on the input file. After
904 some calculations, a @file{.tex} is produced. The contents
905 of this file are very low-level instructions.
907 For example, the following file (@file{layout.ly})
911 \header @{ title = "Two miniatures"; @}
913 #(set! point-and-click #t)
931 results in something like this@footnote{The titling in this manual was
932 not generated by ly2dvi, so details will differ.}
934 @center @strong{Two miniatures}
962 This file is produced by ly2dvi in a few stages, with the help of text
963 formatting tools. LilyPond produces two output files, @file{layout.tex}
964 and @file{layout-1.tex}. They both look like this:
968 \placebox@{-5 \outputscale @}%
969 @{ 8.7229 \outputscale @}%
970 @{\magfontWXGEomMMBo\char90 @}%
972 \placebox@{-4 \outputscale @}%
973 @{ 81.0647 \outputscale @}%
977 @file{ly2dvi} analyses the progress indication that LilyPond spews out,
978 and generates a file called @file{layout_ly1.tex}. This file contains
979 formatting instructions for the title and page layout. A fragment might
983 \geometry@{width=540.602362pt,headheight=2mm, ...
984 \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@} ...
986 \lilypondtitle@{foo@}%
992 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
993 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
994 is successful, this will produce a @file{.dvi} file, containing both the
995 titling and notes. @code{ly2dvi} completes its task by deleting the two
996 temporary files, leaving only @file{layout.dvi}.
998 Next, now we'll look at the examples line by line to explain new things.
1003 Lilypond and its language are still under development, and occasionally,
1004 details of the syntax are changed. This fragment indicates for which
1005 version the input file was written. When you compile this file, the
1006 version number will be checked, and you will get a warning when the file
1009 This version number is also used by the @code{convert-ly} program (See
1010 @ref{convert-ly}), which uses it update the file to the latest lily
1014 \header @{ title = "Two miniatures"; @}
1016 This sets the titling information for the entire file.
1019 #(set! point-and-click #t)
1022 This is Scheme code. It sets the variable @code{point-and-click} to the
1025 Editing input files can be quite complicated if you're working with
1026 large files: if you're digitizing existing music, you have to
1027 synchronize the .ly file, the sheet music on your lap and the sheet
1028 music on the screen. The point-and-click mechanism makes it easy to
1029 find the origin of an error in the .ly file: @footnote{This feature is
1030 presently only available on X-windows using patched versions of Xdvi and
1031 emacs} when you view the file with Xdvi and click on a note using
1032 control-mousebutton 1@footnote{If you're using a patched xdvik, the
1033 command is control-mousebutton-2}, your editor will jump to the spot
1034 where that note was entered.
1036 More information is in in @ref{Point and click}
1042 The @code{\score} blocks that follow in the file don't have
1043 @code{\paper} sections, so the settings of this block are substituted: A
1044 paper block, at top-level, i.e. not in a @code{\score} block sets the
1045 default page layout.
1048 linewidth = -1.0; @}
1053 The variable @code{linewidth} normally sets the length of the systems on
1054 the page. However, a negative value has a special meaning. If
1055 @code{linewidth} is less than 0, no line breaks are inserted into the
1056 score, and the spacing is set to natural length: a short phrase takes up
1057 little space, a longer phrase more space.
1061 \notes @{ c'4 d'4 @}
1064 In previous examples, notes were specified in relative octaves,
1065 i.e. each note was put in the octave that would put it closest to its
1066 predecessor. Besides relative, there is also absolute octave
1067 specification, and it is turned on by default. In this input mode, the
1068 central C is denoted by @code{c'}. Going down, you get @code{c}
1069 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} etc.
1071 When you're copying music from existing sheet music, relative octaves
1072 are probably the easiest to use: it's less typing work and errors are
1073 easily spotted. However, if you write LilyPond input, either by hand
1074 (ie. composing) or by computer, absolute octaves are probably less work.
1081 The @code{\header} is normally at the top of the file, where it sets
1082 values for the rest of the file. If you want to typeset different pieces
1083 from one file (for example, if there are multiple movements, or if
1084 you're making a etude-book), you can put different @code{\score} blocks
1085 into the input file. ly2dvi will assemble all LilyPond output files into
1086 a big document. The contents of \header blocks specified within each
1087 score, are used for the titling of each movement.
1092 For example, the Opus number is put at the right, and the piece string
1093 will be at the left.
1097 @node A piano excerpt
1098 @section A piano excerpt
1100 Our third subject is a piece of piano music. The fragment in the input
1101 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1102 Sammartini. It was composed around 1740. It's in the source package
1103 under the name @file{sammartini.ly}.
1106 \include "paper16.ly";
1108 stemDown = \property Voice.Stem \override #'direction = #-1
1109 stemUp = \property Voice.Stem \override #'direction = #1
1110 stemBoth = \property Voice.Stem \revert #'direction
1112 viola = \notes \relative c' \context Voice = viola {
1113 <c4-\f-\arpeggio g' c>
1119 oboes = \notes \relative c'' \context Voice = oboe {
1120 \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1121 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
1123 { \times 2/3 { a8 g c } \! c2 }
1124 \context Voice = oboeTwo {
1127 \property Grace.Stem \override #'direction = #-1
1132 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1133 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1134 [<c16( e> < )e8. g>] <c8 e,>
1137 hoomPah = \repeat unfold 8
1138 \notes \transpose c' { c8 \stemDown c'8 \stemUp }
1140 bassvoices = \notes \relative c' {
1142 \autochange Staff \hoomPah
1143 \translator Staff = down
1144 \stemDown [c8 c'8] r4
1146 < {\stemUp r2 <e4 c'> <c8 g'> }
1147 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
1151 \context PianoStaff \notes <
1152 \context Staff = up < \time 2/2;
1156 \context Staff = down < \time 2/2; \clef bass;
1163 linewidth = 15.0 \cm; }
1167 If it looks like incomprehensible gibberish to you, then you are right.
1168 This example has been doctored to have as many quirks as possible.
1171 stemDown = \property Voice.Stem \override #'direction = #-1
1174 As you can see, this example features more voices on one staff. To make
1175 room for those voices, their notes have to be stemmed in opposite
1176 directions. These are the commands to make that happen.
1178 The symbols that are printed, are internally represented by so-called
1179 Graphical Objects (or more colloquially: Grobs). These statements
1180 concern the grob called `Stem'. Each grob is described by a bunch of
1181 settings. These setting determine the fonts, offsets, sub-routines to be
1182 called on the grob, etc. The initial values of these settings are set
1183 in the Scheme file @file{scm/grob-description.scm}.
1185 This statement adds a the setting for all Stem grobs in the current
1186 Voice: @code{direction} is set to @code{-1}, which encodes down. The
1187 setting remains in effect until it is reverted.
1190 \property Voice.Stem \revert #'direction
1193 This statement reverts the old setting. If you do this, the effect of a
1194 @code{\stemDown} or @code{\stemUp} is neutralised.
1196 @code{\override} and @code{\revert} function like a stack: you can push
1197 values onto the grob-setting-stack with @code{\override} and you pop
1198 them with @code{\revert}.
1200 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1201 with some more often used formatting instructions, but to explain how it
1202 works, we wrote our own here. Of course, you should use predefined
1203 identifiers like these if possible: then you will be affected less by
1204 the implementation changes we occasionally make.
1207 viola = \notes \relative c' \context Voice = viola @{
1209 In this example, you can see multiple parts on a staff. Each part is
1210 associated with one notation context. This notation context handles
1211 stems and dynamics (among others). The name of this context is
1212 @code{Voice}. For each part we have to make sure that there is
1213 precisely one @code{Voice} context, so we give it an unique name
1217 <c4-\f-\arpeggio g' c>
1219 The delimiters @code{<} and @code{>} are shorthands for
1220 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1221 @code{<} and @code{>} is a chord.
1228 @code{\f} places a forte symbol under the chord. The forte applies to
1229 the whole chord, but the syntax requires that commands like forte and
1230 arpeggio are attached to a note, so here we attach them to the first
1233 @code{\arpeggio} draws an vertical wavy line before the chord,
1234 signifying an arpeggio.
1244 Relative octaves work a little differently with chords. The starting
1245 point for the note following a chord is the first note of the chord. So
1246 the @code{g} gets an octave up quote: it is a fifth above the starting
1247 note of the previous chord (the central C).
1252 @code{s} is a spacer rest. It does not print anything, but it does have
1253 the duration of a rest. It is useful for filling up voices that
1254 temporarily don't play. In this case, the viola doesn't come until one
1255 and a half measure later.
1258 oboes = \notes \relative c'' \context Voice = oboe @{
1260 Now comes a part for two oboes. They play homophonically, so we
1261 print the notes as one voice that makes chords. Again, we insure that
1262 these notes are indeed processed by precisely one context with
1265 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1267 @code{\stemUp} is a reference to the @code{\property \override} command
1270 \grace <e8 g> < d4 f> <c2 e>
1272 @cindex @code{\grace}
1276 @code{\grace} introduces grace notes. It takes one argument, in this
1280 The slur started on the @code{e} of the chord
1281 will be attached to the next note.@footnote{LilyPond will squirm
1282 about unended Slurs. In this case, you can ignore the warning}.
1289 Tuplets are made with the @code{\times} keyword. It takes two
1290 arguments: a fraction and a piece of music. The duration of the piece
1291 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1292 of their notated duration, so in this case the fraction is 2/3.
1294 @{ <d8 \< f> <e g> <f a> @}
1296 The piece of music to be `tripletted' is sequential music containing
1297 three notes. On the first chord, a crescendo is started with
1298 @code{\<}. To be precise, the crescendo start is syntactically attached
1299 to the preceding note, the @code{d}.
1308 At this point, the homophonic music splits into two rhythmically
1309 different parts. We can't use a sequence of chords to enter this, so
1310 we make a `chord' of sequences to do it. We start with the upper
1311 voice, which continues with upward stems:
1313 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1318 The crescendo is ended at the half note by the escaped exclamation
1321 \context Voice = oboeTwo @{
1324 We can't share stems with the other voice, so we have to create a new
1325 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1326 it from the other context. Stems go down in this voice.
1330 @cindex Grace context
1331 When a grace section is processed, a @code{Grace} context is
1332 created. This context acts like a miniature score of its own. It has
1333 its own time bookkeeping, and you can make notes, beams, slurs
1334 etc. Here we fiddle with a property and make a beam. The argument of
1335 @code{\grace} is sequential music.
1338 \property Grace.Stem \override #'direction = #-1
1342 Normally, grace notes are always stem up, but in this case, the upper
1343 voice interferes. We set the stems down here.
1345 As far as relative mode is concerned, the previous note is the
1346 @code{c'''2} of the upper voice, so we have to go an octave down for
1353 This ends the two-part section.
1356 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1361 @code{\stemBoth} ends the forced stem directions. From here, stems are
1362 positioned as if it were single part music.
1364 The bass has a little hoom-pah melody to demonstrate parts switching
1365 between staffs. Since it is repetitive, we use repeats:
1367 hoomPah = \repeat unfold 8
1369 @cindex unfolded @code{\repeat}
1370 This repeat print the following sequence notes eight times.
1372 \notes \transpose c' @{
1375 @cindex relative mode and transposing
1377 Transposing can be done with @code{\transpose}. It takes two arguments;
1378 the first specifies what central C should be transposed to. The second
1379 is the to-be-transposed music. As you can see, in this case, the
1380 transposition is a no-op, as central C stay at central C.
1382 The purpose of this no-op is circumventing relative mode. Relative mode
1383 can not be used together with transposition, so @code{\relative} will
1384 leave the contents of @code{\hoomPah} alone. We can use it without
1385 having to worry about getting the motive in a wrong octave.
1387 bassvoices = \notes \relative c' @{
1389 \autochange Staff \hoomPah
1391 @cindex staff switch, automatic
1392 @cindex cross staff voice, automatic
1393 @cindex @code{\autochange}
1395 Voices can switch between staffs. The easiest way to get this, is to use
1396 @code{\autochange}. This command looks at the pitch of each note, and if
1397 necessary, will cross to the other staff. For this to work, the two
1398 staffs must be called @code{"up"} and @code{"down"}.
1400 \translator Staff = down
1402 @cindex staff switch
1403 @cindex cross staff voice
1404 The rest of this melody must be in the lower staff, so we do a manual
1409 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1413 After skipping some lines, we see @code{~}. This mark makes ties.
1417 A special context is needed to get cross staff beaming right. This
1418 context is called @code{PianoStaff}.
1420 \context Staff = bottom < \time 2/2; \clef bass;
1422 The bottom staff must have a different clef.
1426 To make some more room on the line, the first (in this case the only)
1427 line is not indented. The line still looks very cramped, but that is due
1428 to the page layout of this document.
1433 * arpeggio, glissando,
1435 * \apply, \outputproperty, \translator @{@}, \molecule hacking.
1437 * font-size, cadenza. rhythmic staff, 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 @}
1486 corno = \notes\relative c' @{
1487 bes4 d f, bes d f, bes d
1491 Things to note here are the definition of @code{\global} where we define
1492 meter, and set the end bar. And the separate definition of @code{\Key}
1493 that we will use all staffs except staffs for transposing instruments.
1495 The second file, @file{os-score.ly} reads the definitions of the first
1496 (@file{os-music.ly}), and defines the @code{\score} block for the full
1501 \include "os-music.ly";
1502 \include "paper13.ly";
1504 #(set! point-and-click #t)
1505 #(define text-flat '((font-relative-size . -2)
1506 (music "accidentals--1")))
1511 \context StaffGroup = woodwind <
1512 \context Staff = flauti <
1513 \property Staff.midiInstrument = #"flute"
1514 \property Staff.instrument = "2 Flauti"
1515 \property Staff.instr = "Fl."
1517 \context Voice=one @{ \voiceOne \flautoI @}
1518 \context Voice=two @{ \voiceTwo \flautoII @}
1521 \context StaffGroup = timpani <
1522 \context Staff = timpani <
1523 \property Staff.midiInstrument = #"timpani"
1524 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1525 \property Staff.instr = #"Timp."
1531 \context StaffGroup = brass <
1532 \context Staff = trombe <
1533 \property Staff.midiInstrument = #"trumpet"
1534 \property Staff.instrument = #`(lines "2 Trombe" "(C)")
1535 \property Staff.instr = #`(lines "Tbe." "(C)")
1537 \context Voice=one \partcombine Voice
1538 \context Thread=one \tromboI
1539 \context Thread=two \tromboII
1541 \context Staff = corni <
1542 \property Staff.midiInstrument = #"french horn"
1543 \property Staff.instrument = #`(lines "Corno"
1544 (rows "(E" ,text-flat ")"))
1545 \property Staff.instr = #`(lines "Cor."
1546 (rows "(E" ,text-flat ")"))
1547 \property Staff.transposing = #3
1548 \notes \key bes \major;
1549 \context Voice=one \corno
1554 indent = 15 * \staffspace;
1555 linewidth = 60 * \staffspace;
1556 textheight = 90 * \staffspace;
1559 \consists "Rest_engraver";
1563 \remove "Rest_engraver";
1566 \HaraKiriStaffContext
1569 \OrchestralScoreContext
1570 BarNumber \override #'padding = #3
1579 % geen echte titels, wat jammer :-(
1580 @center @strong{Zo, goed lieverd?}
1582 @center How's, this babe?
1590 @lilypondfile{os-score.ly}
1592 First, we need to include the music definitions we made in
1595 \include "os-music.ly";
1598 In a large orchestral score like this you're bound to make some small
1599 mistakes, so we enable point and click (See @ref{Point and click})
1602 #(set! point-and-click #t)
1605 We need a flat to specify the tuning of the french horn, so we predefine
1606 it with bit of scheme markup text (See @ref{Text markup}).
1608 #(define text-flat '((font-relative-size . -2)
1609 (music "accidentals--1")))
1612 Of course, all staffs are simultaneous and use the same global settings.
1618 Then, we start a new staff group for the woodwind section (just the
1619 flutes in this case). Immediately after that, we start the staff for
1620 the two flutes, that also play simultaneously.
1622 \context StaffGroup = woodwind <
1623 \context Staff = flauti <
1626 We specify the intrument for MIDI output (see @ref{MIDI instrument
1629 \property Staff.midiInstrument = #"flute"
1632 And define the intrument names to be printed in the margin,
1633 @code{instrument} for the first line of the score, @code{instr} for the
1636 \property Staff.instrument = "2 Flauti"
1637 \property Staff.instr = "Fl."
1640 The flutes play in the default key.
1645 Last come the actual flute parts. Remember that we're still in
1646 simultaneous mode. We name both voices differently, so that LilyPond
1647 will actually create two Voice contexts. The flute parts are simple, so
1648 we specify manually which voice is which: @code{\voiceOne} forces the
1649 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
1652 \context Voice=one @{ \voiceOne \flautoI @}
1653 \context Voice=two @{ \voiceTwo \flautoII @}
1656 We close the flutes staff and woodwind staff group.
1662 The timpani staff only shows a new piece of scheme markup, it sets two
1665 \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1668 For the trumpets we use the automatic part combiner (see @ref{Automatic
1669 part combining}) to combine the two simultaneous trumpet parts onto the
1670 trumpet staff. Each trumpet gets its own Thread context, which must be
1671 named @code{one} and @code{two}). The part combiner makes these two
1672 threads share a Voice when they're similar, and splits the threads up
1673 when they're different.
1675 \context Voice=one \partcombine Voice
1676 \context Thread=one \tromboI
1677 \context Thread=two \tromboII
1680 The french horn has the most complex scheme markup name, made up of two
1681 lines of text. The second line has two elements (rows), the @code{E}
1682 and the flat sign @code{text-flat} that we defined before.
1684 \property Staff.instrument = #`(lines "Corno"
1685 (rows "(E" ,text-flat ")"))
1688 The french horn is to be tuned in E-flat, so we tell the MIDI backend to
1689 transpose this staff by three steps.
1691 \property Staff.transposing = #3
1694 Therefore, it has a different key.
1696 \notes \key bes \major;
1699 We specify a big indent for the first line and a small linewith for this
1702 indent = 15 * \staffspace;
1703 linewidth = 60 * \staffspace;
1706 Because we have a Thread representing one instument, we move the
1707 need the @code{Rest_engraver} from Voice to Thread level.
1711 \consists "Rest_engraver";
1715 \remove "Rest_engraver";
1719 In orchestral scores, it often happens that one instrument has only
1720 rests during one line of the score. The @code{HaraKiriStaffContext} can
1721 be used as a regular @code{StaffContext} drop-in and will take care of
1722 the automatic removing of empty staffs.
1725 \HaraKiriStaffContext
1729 Lastly, we want bar numbering at score level and want to move the bar
1730 number a few staff-spaces up.
1733 \OrchestralScoreContext
1734 BarNumber \override #'padding = #3
1738 @node Part extraction
1739 @section Part extraction
1741 The third file, @file{os-flute-2.ly} also reads the definitions of the
1742 first (@file{os-music.ly}), and defines the @code{\score} block for the
1746 \include "os-music.ly";
1747 \include "paper16.ly";
1751 \property Staff.midiInstrument = #"flute"
1757 instrument = "Flauto II";
1760 linewidth = 80 * \staffspace;
1761 textheight = 200 * \staffspace;
1763 \OrchestralScoreContext
1773 @center @strong{Zo, goed lieverd?}
1775 @center How's, this babe?
1776 @center @emph{Flauto II}
1783 @lilypondfile{os-flute-2.ly}
1786 Because we separated the music definitions from the @code{\score}
1787 instantiations, we can easily define a second score from the music of
1788 the second flute. This then is the part for the second flute player.
1789 Of course, we make separate parts for all individual instruments.
1791 In this individual part the second flute has a whole staff for itself,
1792 so we don't want to force stem or tie directions.
1797 The @code{\header} definitions were also read from @file{os-music.ly},
1798 but we need to set the instrument for this particular score.
1801 instrument = "Flauto II";
1805 In the conductor's full score, all bars with rests are printed, but for
1806 the individual parts, we want to contract pieces of consecutive empty
1812 @node end of tutorial
1815 That's all folks. From here, you can either try fiddling with input
1816 files, or you can read the reference manual.