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::
14 * end of tutorial:: The end
21 LilyPond prints music from a specification that you, the user, supply.
22 You have to give that specification using a @emph{language}. This
23 chapter is a gentle introduction to that language.
25 This tutorial will demonstrate how to use Lilypond by presenting
26 examples of input along with resulting output. We will use English
27 terms for notation. In case you are not familiar with those, you may
28 consult the glossary that is distributed with LilyPond.
30 @cindex examples, tutorial
32 The examples discussed are included in the distribution, in the
33 subdirectory @file{input/tutorial/}.@footnote{When we refer
34 to filenames, they are relative to the top directory of the source
37 }. We recommend that you experiment with writing Lilypond input
38 yourself, to get a feel for how the program behaves.
41 @node Running LilyPond
42 @section Running LilyPond
44 Before we dive into describing the input language of LilyPond, we first
45 show you through the procedure for getting notes on your screen and out
48 The first step is creating an input file. Using your favorite
49 text-editor, create @file{test.ly} containing
57 \notes @{ c'4 e'4 g'4 @}
62 @unnumberedsubsec Unix
64 @cindex Unix, Running lilypond on
66 If you run Unix, proceed as follows: run lilypond on the file, i.e.,
70 You will see the following on your screen:
73 Now processing: `input/tutorial/test.ly'
75 Interpreting music...[1]
76 Preprocessing elements...
77 Calculating column positions... [2]
78 paper output to test.tex...
81 Now, run @TeX{}@footnote{@TeX{} is a text-typesetting system that is
82 especially suited for typesetting mathematics.}. The result should
85 This is TeX, Version 3.14159 (Web2C 7.3.1)
86 (test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
87 (/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
88 LilyPond Plain TeX settings) (/home/hanwen/usr/src/ ...
89 (/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
90 (/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
91 Output written on test.dvi (1 page, 3716 bytes).
92 Transcript written on test.log.
94 The result of the @TeX{} run is a @TeX{} ``DeVice Independent'' file
101 To view the output, run Xdvi, i.e.
105 You should see the following in a window next to some buttons.
112 \notes { c'4 e'4 g'4 }
117 @cindex postscript, converting to
118 When you're satisfied with the result, you can print it. For printing,
119 you have to generate a postscript file:
121 dvips -o test.ps test.dvi
123 which looks like this:
125 This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
126 ' TeX output 2001.01.27:1806' -> test.ps
127 <texc.pro><special.pro>. [1]
131 @cindex Printing output
134 PostScript is a page description language, similar to PDF. Some printers
135 can understand a postscript file directly, but the cheaper ones need the
136 intervention of GhostScript, an emulator that runs PostScript on your
137 computer instead of your printer. Most Linux distributions nowadays have
138 GhostScript running ``in the background'', so any configured printer
139 will act as a PostScript printer. Assuming this, the following command
144 If this does not make your printer produce a page of music, then you
145 should look into installing and configuring ghostscript. Refer to
146 GhostScript's website at @uref{http://www.ghostscript.com}.
148 There are three other routes: firstly, you can add titling to the
149 output. This is done by a separate program called @file{ly2dvi}: this
150 program first calls LilyPond to process the @file{.ly} file, and then
151 runs @TeX{} on it to produce a @file{.dvi} file with proper margin
152 settings and titling.
154 @cindex titles, adding
160 After some disk-activity, you should end up with a @file{.dvi} file.
161 Ly2dvi is further described in the @ref{ly2dvi}.
163 Secondly, you can generate PostScript directly. This is useful if you
164 can not or do not want to run @TeX{} on your system.
165 To obtain PS output, invoke LilyPond as follows:
166 @cindex PostScript output
168 lilypond -f ps test.ly
171 You have to set some environment variables to view or print this
172 output. More information can be found in the @ref{Invoking
175 Finally, there is a script called lilypond-book, that allows you to
176 freely mix LilyPond input with Texinfo or LaTeX input. For example, this
177 manual was written using lilypond-book. lilypond-book is discussed in
180 @unnumberedsubsec Windows
186 @section The first tune
189 To demonstrate what LilyPond input looks like, we start off with a
190 full-fledged, yet simple example. It is a convoluted version
191 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
192 is included in the distribution as @file{menuet.ly}.
193 @cindex Bach, Johann Sebastian
196 % lines preceded by a percent are comments which
197 % are ignored by Lilypond.
198 \include "paper16.ly"
201 \relative c'' \sequential{
206 d4 g,8 a b c d4 g, g |
207 e'4 c8 d e fis g4 g, g |
208 c4 d8()c b a( )b4 c8 b a g |
209 a4 [b8 a] [g fis] g2. |
214 g4 e8 fis g d cis4 b8 cis a4 |
215 a8-. b-. cis-. d-. e-. fis-.
222 % standard settings are too wide for a book
223 linewidth = 14.0 \cm;
228 We will analyse the input, line by line.
230 % lines preceded by a percent are comments which
231 % are ignored by Lilypond.
233 The percent sign, @code{%}, introduces a line comment. If you want to
234 make larger comments, you can use block comments. These are delimited
235 by @code{%@{} and @code{%@}}
237 @cindex block comment
242 \include "paper16.ly"
245 @cindex @code{\include}
246 @cindex point, printer's
247 @cindex staff size setting
248 By default, LilyPond will use definitions for a staff that is 20
249 point@footnote {A point is the standard measure of length for printing;
250 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
251 output (16 point staff height), so we must import the settings for that
252 size, which is done here.
258 A lilypond file combines music with directions for outputting that
259 music. The music is combined with the output directions by putting
260 them into a @code{\score} block.
266 This makes LilyPond ready for accepting notes.
273 @cindex octaves, choosing
275 As we will see, pitches are combinations of octave, note name and
276 chromatic alteration. In this scheme, the octave is indicated by
277 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
278 @code{,}). The central C is denoted by @code{c'}. The C one octave
279 higher is @code{c''}. One and two octaves below the central C is
280 denoted by @code{c} and @code{c,} respectively.
283 For pitches in a long piece you might have to type many quotes. It is
284 easy to make typing errors with this, so LilyPond has a special entry
285 mode to remedy this. In this ``relative'' octave mode, octaves of notes
286 without quotes are chosen such that a note is as close as possible
287 (graphically, on the staff) to the the preceding note. If you add a
288 high-quote an extra octave is added. The lowered quote (a comma) will
289 subtract an extra octave. Because the first note has no predecessor,
290 you have to give the (absolute) pitch of the note to start with.
296 What follows is sequential music, i.e.,
297 @cindex sequential music
298 notes that are to be played and printed after each other.
304 @cindex time signature, setting
306 This command changes the time signature of the current piece: a 3/4
307 sign is printed. This command is also used to generate bar lines in
314 @cindex key signature, setting
316 This command changes the current key signature to G-major. Although this
317 command comes after the @code{\time} command, in the output, the key
318 signature comes before the time signature: LilyPond knows about music
319 typesetting conventions.
325 This command tells LilyPond that the following piece of music must be
326 played twice. The first argument indicates the type of repeat. In this
327 case, @code{"volta"} means that volta brackets are be used for
328 alternatives---if there were any.
334 The subject of the repeat is again sequential music. Since
335 @code{\sequential} is such a common construct, a shorthand is provided:
336 just leave off @code{\sequential}, and the result is the same.
342 This is a note with pitch @code{d} (determined up to octaves). The
343 relative music was started with a @code{c''}, so the real pitch of this
344 note is @code{d''}. The @code{4} designates the duration of the note
345 (it is a quarter note).
351 These are notes with pitch @code{a} and @code{b}. Because their
352 duration is the same as the @code{g}, there is no need to enter the
353 duration (You may enter it anyway, e.g. @code{a4 b4})
361 @cindex errors, finding
362 Three more notes. The @code{|} character is a `bar check'. When
363 processing the music, LilyPond will verify that bar checks are found at
364 the start of a measure. This can help you track down errors.
366 @cindex alteration, chromatic
367 @cindex chromatic alteration
368 So far, no notes were chromatically altered. Here is the first one
369 that is: @code{fis}. Lilypond by default uses Dutch note names, and
370 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
371 sharp sign in the output. The program keeps track of key signatures,
372 and will only print accidentals if they are needed.
378 LilyPond guesses were beams can be added to eighth and shorter notes.
379 In this case, a beam over 4 eighths is added.
382 c4 d8( )c b a( )b4 c8 b a g |
385 The next line shows how to make a slur: the beginning and ending note
386 of the slur is marked with an opening and closing parenthesis
387 respectively. In the line shown above, this is done for two slurs.
388 Slur markers (parentheses) are put between the slurred notes.
394 Automatic beaming can be overridden by inserting beam marks
395 (brackets). Brackets are put around the notes you want beamed.
401 @cindex augmentation dot
403 A duration with augmentation dot is notated
404 with the duration number followed by a period.
410 This ends the sequential music to be repeated. LilyPond will typeset
417 This line shows that Lily will print an accidental if that is
418 needed: the first C sharp of the bar will be printed with an accidental,
419 the second one without.
422 a8-. b-. cis-. d-. e-. fis-.
426 You can enter articulation signs either in a verbose form using a
427 shorthand. Here we demonstrate the shorthand: it is formed by a dash
428 and the character for the articulation to use, e.g. @code{-.} for
429 staccato as shown above.
436 Rests are denoted by the special notename @code{r}.
442 All articulations have a verbose form, like @code{\fermata}. The
443 command @code{\fermata} is not part of the core of the language (most
444 of the other discussed elements are), but it is a shorthand for a more
445 complicated description of a fermata. @code{\fermata} names that
446 description and is therefore called an identifier.
448 @cindex @code{\fermata}
463 This specifies a conversion from music to notation output. Most of
464 the details of this conversions (font sizes, dimensions, etc.) have
465 been taken care of, but to fit the output in this document, it has
466 to be smaller. We do this by setting the line width to 14 centimeters
467 (approximately 5.5 inches).
473 The last brace ends the @code{\score} block.
478 @node Lyrics and chords
479 @section Lyrics and chords
481 In this section we show how to typeset a song. This file is
482 included as @file{flowing.ly}.
486 title = "The river is flowing";
487 composer = "Traditional (?)";
489 \include "paper16.ly"
490 melody = \notes \relative c' @{
494 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
495 c4 c8 d [es () d] c4 | d4 es8 d c4.
500 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
501 ri -- ver is flo -- wing down to the sea.
504 accompaniment =\chords @{
506 c2:3- f:3-.7 d:min es4 c8:min r8
507 c2:min f:min7 g:7^3.5 c:min @}
512 \context ChordNames \accompaniment
515 \context Staff = mel @{
516 \property Staff.noAutoBeaming = ##t
517 \property Staff.automaticMelismata = ##t
520 \context Lyrics \text
522 \midi @{ \tempo 4=72;@}
523 \paper @{ linewidth = 10.0\cm; @}
528 The result would look this.@footnote{The titling and font size shown
529 may differ, since the titling in this document is not generated by
532 @center @strong{The river is flowing}
537 title = "The river is flowing";
538 composer = "Traditional (?)";
540 \include "paper16.ly"
541 melody = \notes \relative c' {
545 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
546 c4 c8 d [es () d] c4 | d4 es8 d c4.
551 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
552 ri -- ver is flo -- wing down to the sea.
555 accompaniment =\chords {
557 c2:3- f:3-.7 d:min es4 c8:min r8
558 c2:min f:min7 g:7^3.5 c:min }
563 \context ChordNames \accompaniment
566 \context Staff = mel {
567 \property Staff.noAutoBeaming = ##t
568 \property Staff.automaticMelismata = ##t
571 \context Lyrics \text
573 \midi { \tempo 4=72;}
574 \paper { linewidth = 10.0\cm; }
578 Again, we will dissect the file line by line.
584 @cindex @code{\header}
585 Information about the music you are about to typeset goes into a
586 @code{\header} block. The information in this block is not used by
587 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
588 information to print titles above the music.
591 title = "The river is flowing";
592 composer = "Traditional (?)";
595 @cindex identifier assignment
596 the @code{\header} block contains assignments. An assignment starts
597 with a string. (which is unquoted, in this case). Then comes the
598 equal sign. After the equal sign comes the expression you
599 want to store. In this case, you want to put in strings. The
600 information has to be quoted here, because it contains spaces. Each
601 assignment is finished with a semicolon.
604 \include "paper16.ly"
607 Smaller size for inclusion in a book.
610 melody = \notes \relative c' @{
613 The structure of the file will be the same as the previous one, a
614 @code{\score} block with music in it. To keep things readable, we will
615 give names to the different parts of music, and use the names to
616 construct the music within the score block.
622 @cindex @code{\partial}
624 The piece starts with an anacrusis of one eighth.
628 The key is C minor: we have three flats.
632 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
633 c4 c8 d [es () d] c4 | d4 es8 d c4.
638 @cindex manual beaming
639 @cindex automatic beaming, turning off
640 We use explicit beaming. Since this is a song, we will turn automatic
641 beams off, and use explicit beaming where needed.
647 This ends the definition of @code{melody}. Note that there are no
648 semicolons after assignments at top level.
655 @cindex identifier assignment
656 @cindex syllables, entering
657 Another identifier assignment. This one is for the lyrics.
658 Lyrics are formed by syllables that have duration, and not by
659 notes. To make LilyPond parse words as syllables, switch it into
660 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
661 is a shorthand for @code{\sequential @{}.
664 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
665 ri- ver is flo- __ wing down to the sea.
669 @cindex extenders, lyric
670 @cindex hyphens, lyric
671 The syllables themselves are separated by spaces. You can get syllable
672 extenders by entering @code{__}, and centered hyphens with
673 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
674 in length (hence the @code{4}), and use a feature to align the
675 syllables to the music (which obviously isn't all quarter notes.)
678 accompaniment =\chords @{
683 We'll put chords over the music, to enter them, there is a special mode,
684 called @code{\chords}. There is a special mode (analogous
685 to @code{\lyrics} and @code{\notes} mode) where you can give the names
686 of the chords you want, instead of the notes comprising the chord.
692 There is no accompaniment during the anacrusis.
700 @cindex chord modifier
701 @cindex modifier, chord
702 A chord is started by the tonic of the chord. The
703 first one lasts a half note. An unadorned note creates a major
704 triad, while a minor triad is wanted. @code{3-} modifies the third to
705 be small. @code{7} modifies (adds) a seventh, which is small by default
706 to create the @code{f a c es} chord. Multiple modifiers must be
714 Some modifiers have predefined names, eg. @code{min} is the same as
715 @code{3-}, so @code{d-min} is a minor @code{d} chord.
718 c2:min f:min7 g:7^3.5 c:min @}
721 @cindex named modifier
723 A named modifier @code{min} and a normal modifier @code{7} do not have
724 to be separated by a dot. Tones from a chord are removed with chord
725 subtractions. Subtractions are started with a caret, and they are
726 also separated by dots. In this example, @code{g:7^3.5} produces a
727 minor seventh. The brace ends the sequential music.
734 We assemble the music in the @code{\score} block. Melody, lyrics and
735 accompaniment have to sound at the same time, so they should be
736 @code{\simultaneous}.
737 @cindex @code{\simultaneous}
743 Chord mode generates notes grouped in @code{\simultaneous} music. If
744 you remove the comment sign, you can see the chords in normal
745 notation: they will be printed as note heads on a separate
749 \context ChordNames \accompaniment
753 @cindex interpretation context
754 @cindex notation context
755 Normally, the notes that you enter are transformed into note heads.
756 The note heads alone make no sense, they need surrounding information:
757 a key signature, a clef, staff lines, etc. They need @emph{context}. In
758 LilyPond, these symbols are created by objects called `interpretation
759 contexts'. Interpretation contexts only exist during a run of
760 LilyPond. Interpretation contexts that are for printing music (as
761 opposed to playing music) are called `notation contexts'.
763 By default, LilyPond will create a Staff context for you. If you
764 removed the @code{%} sign in the previous line, you would see that
767 We don't want that default here, because we want chord names, not note heads.
768 An interpretation context can also created upon explicit request. The
769 keyword for such a request is @code{\context}. It takes two arguments.
770 The first is the name of an interpretation context. The name is a
771 string, it can be quoted with double quotes). The second argument is
772 the music that should be interpreted in this context. For the previous
773 line, we could have written @code{\context Staff \accompaniment}, and
780 @cindex @code{\addlyrics}
781 @cindex lyrics and melody, combining
782 @cindex combining lyrics and melody
784 The lyrics need to be aligned with the melody. This is done by
785 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
786 pieces of music (usually a melody and lyrics, in that order) and
787 aligns the syllables of the second piece under the notes of the
788 first piece. If you would reverse the order, the notes would be
789 aligned on the lyrics, which is not very useful. (Besides, it looks
793 \context Staff = mel @{
797 This is the argument of @code{\addlyrics}. We instantiate a
798 @code{Staff} context explicitly: should you chose to remove the comment
799 before the ``note heads'' version of the accompaniment, the
800 accompaniment will be on a nameless staff. The melody has to be on a
801 different staff as the accompaniment. This is accomplished by giving
802 the melody staff a different name.
805 \property Staff.noAutoBeaming = ##t
809 @cindex context variables
810 @cindex setting context variables
811 An interpretation context has variables that tune its behaviour. One of
812 the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
813 the boolean value @var{true}, LilyPond will not try to put automatic beaming
814 on the current staff.
818 @cindex accessinng Scheme
819 @cindex evaluating Scheme
822 LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
823 a language from the LISP family. You can learn more about Scheme at
824 @uref{http://www.scheme.org}.} to represent data throughout the whole
825 program. The hash-sign (@code{#}) accesses GUILE directly: the code
826 following the hash-sign is evaluated as Scheme. The boolean value
827 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
832 \property Staff.automaticMelismata = ##t
835 @cindex automaticMelismata
837 @cindex @code{\addlyrics} and slurs
838 Similarly, we don't want to print a syllable when there is
839 a slur. This sets up @code{\addlyrics} to not put lyrics under notes
840 while there is a slur.
847 Finally, we put the melody on the current staff. Note that the
848 @code{\property} directives and @code{\melody} are grouped in sequential
849 music, so the property settings are done before the melody is
853 \context Lyrics \text
856 The second argument of @code{\addlyrics} is the text. The text also
857 should not land on a Staff, but on a interpretation context for
858 syllables, extenders, hyphens etc. This context is called
865 This ends @code{\simultaneous}.
868 \midi @{ \tempo 4=72;@}
871 This makes the music go to a MIDI file. MIDI is great for checking
872 music you enter. You listen to the MIDI file: if you hear something
873 unexpected, it's probably a typing error. @code{\midi} starts an output
874 definition, a declaration that specifies how to output music analogous
875 to @code{\paper @{ @}}. You can specify the tempo using the
876 @code{\tempo} command, in this case the tempo of quarter notes is set to
880 \paper @{ linewidth = 10.0\cm; @}
883 We also want notation output. The linewidth is short so the piece
884 will be set in two lines.
893 @section More movements
895 You probably ran @file{ly2dvi} on the last example, and ended up with a
896 viewable @file{.dvi} file. However, between there are a few steps of
897 which LilyPond is only one. To enhance your understanding of what's
898 happening under the hood when you run @code{ly2dvi}, we explain what
901 @code{ly2dvi} is a program that calls a number of programs in sequence.
902 The first thing it does, is running LilyPond on the input file. After
903 some calculations, a @file{.tex} is produced. The contents
904 of this file are very low-level instructions.
906 For example, the following file (@file{layout.ly})
910 \header @{ title = "Two miniatures"; @}
912 #(set! point-and-click #t)
930 results in something like this@footnote{The titling in this manual was
931 not generated by ly2dvi, so details will differ.}
933 @center @strong{Two miniatures}
961 This file is produced by ly2dvi in a few stages, with the help of text
962 formatting tools. LilyPond produces two output files, @file{layout.tex}
963 and @file{layout-1.tex}. They both look like this:
967 \placebox@{-5 \outputscale @}%
968 @{ 8.7229 \outputscale @}%
969 @{\magfontWXGEomMMBo\char90 @}%
971 \placebox@{-4 \outputscale @}%
972 @{ 81.0647 \outputscale @}%
976 @file{ly2dvi} analyses the progress indication that LilyPond spews out,
977 and generates a file called @file{layout_ly1.tex}. This file contains
978 formatting instructions for the title and page layout. A fragment might
982 \geometry@{width=540.602362pt,headheight=2mm, ...
983 \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@} ...
985 \lilypondtitle@{foo@}%
991 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
992 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
993 is successful, this will produce a @file{.dvi} file, containing both the
994 titling and notes. @code{ly2dvi} completes its task by deleting the two
995 temporary files, leaving only @file{layout.dvi}.
997 Next, now we'll look at the examples line by line to explain new things.
1002 Lilypond and its language are still under development, and occasionally,
1003 details of the syntax are changed. This fragment indicates for which
1004 version the input file was written. When you compile this file, the
1005 version number will be checked, and you will get a warning when the file
1008 This version number is also used by the @code{convert-ly} program (See
1009 @ref{convert-ly}), which uses it update the file to the latest lily
1013 \header @{ title = "Two miniatures"; @}
1015 This sets the titling information for the entire file.
1018 #(set! point-and-click #t)
1021 This is Scheme code. It sets the variable @code{point-and-click} to the
1024 Editing input files can be quite complicated if you're working with
1025 large files: if you're digitizing existing music, you have to
1026 synchronize the .ly file, the sheet music on your lap and the sheet
1027 music on the screen. The point-and-click mechanism makes it easy to
1028 find the origin of an error in the .ly file: @footnote{This feature is
1029 presently only available on X-windows using patched versions of Xdvi and
1030 emacs} when you view the file with Xdvi and click on a note using
1031 control-mousebutton 1@footnote{If you're using a patched xdvik, the
1032 command is control-mousebutton-2}, your editor will jump to the spot
1033 where that note was entered.
1035 More information is in in @ref{Point and click}
1041 The @code{\score} blocks that follow in the file don't have
1042 @code{\paper} sections, so the settings of this block are substituted: A
1043 paper block, at top-level, i.e. not in a @code{\score} block sets the
1044 default page layout.
1047 linewidth = -1.0; @}
1052 The variable @code{linewidth} normally sets the length of the systems on
1053 the page. However, a negative value has a special meaning. If
1054 @code{linewidth} is less than 0, no line breaks are inserted into the
1055 score, and the spacing is set to natural length: a short phrase takes up
1056 little space, a longer phrase more space.
1060 \notes @{ c'4 d'4 @}
1063 In previous examples, notes were specified in relative octaves,
1064 i.e. each note was put in the octave that would put it closest to its
1065 predecessor. Besides relative, there is also absolute octave
1066 specification, and it is turned on by default. In this input mode, the
1067 central C is denoted by @code{c'}. Going down, you get @code{c}
1068 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} etc.
1070 When you're copying music from existing sheet music, relative octaves
1071 are probably the easiest to use: it's less typing work and errors are
1072 easily spotted. However, if you write LilyPond input, either by hand
1073 (ie. composing) or by computer, absolute octaves are probably less work.
1080 The @code{\header} is normally at the top of the file, where it sets
1081 values for the rest of the file. If you want to typeset different pieces
1082 from one file (for example, if there are multiple movements, or if
1083 you're making a etude-book), you can put different @code{\score} blocks
1084 into the input file. ly2dvi will assemble all LilyPond output files into
1085 a big document. The contents of \header blocks specified within each
1086 score, are used for the titling of each movement.
1091 For example, the Opus number is put at the right, and the piece string
1092 will be at the left.
1096 @node A piano excerpt
1097 @section A piano excerpt
1099 Our third subject is a piece of piano music. The fragment in the input
1100 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1101 Sammartini. It was composed around 1740. It's in the source package
1102 under the name @file{sammartini.ly}.
1105 \include "paper16.ly";
1107 stemDown = \property Voice.Stem \override #'direction = #-1
1108 stemUp = \property Voice.Stem \override #'direction = #1
1109 stemBoth = \property Voice.Stem \revert #'direction
1111 viola = \notes \relative c' \context Voice = viola {
1112 <c4-\f-\arpeggio g' c>
1118 oboes = \notes \relative c'' \context Voice = oboe {
1119 \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1120 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
1122 { \times 2/3 { a8 g c } \! c2 }
1123 \context Voice = oboeTwo {
1126 \property Grace.Stem \override #'direction = #-1
1131 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1132 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1133 [<c16( e> < )e8. g>] <c8 e,>
1136 hoomPah = \repeat unfold 8
1137 \notes \transpose c' { c8 \stemDown c'8 \stemUp }
1139 bassvoices = \notes \relative c' {
1141 \autochange Staff \hoomPah
1142 \translator Staff = down
1143 \stemDown [c8 c'8] r4
1145 < {\stemUp r2 <e4 c'> <c8 g'> }
1146 \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
1150 \context PianoStaff \notes <
1151 \context Staff = up < \time 2/2;
1155 \context Staff = down < \time 2/2; \clef bass;
1162 linewidth = 15.0 \cm; }
1166 If it looks like incomprehensible gibberish to you, then you are right.
1167 This example has been doctored to have as many quirks as possible.
1170 stemDown = \property Voice.Stem \override #'direction = #-1
1173 As you can see, this example features more voices on one staff. To make
1174 room for those voices, their notes have to be stemmed in opposite
1175 directions. These are the commands to make that happen.
1177 The symbols that are printed, are internally represented by so-called
1178 Graphical Objects (or more colloquially: Grobs). These statements
1179 concern the grob called `Stem'. Each grob is described by a bunch of
1180 settings. These setting determine the fonts, offsets, sub-routines to be
1181 called on the grob, etc. The initial values of these settings are set
1182 in the Scheme file @file{scm/grob-description.scm}.
1184 This statement adds a the setting for all Stem grobs in the current
1185 Voice: @code{direction} is set to @code{-1}, which encodes down. The
1186 setting remains in effect until it is reverted.
1189 \property Voice.Stem \revert #'direction
1192 This statement reverts the old setting. If you do this, the effect of a
1193 @code{\stemDown} or @code{\stemUp} is neutralised.
1195 @code{\override} and @code{\revert} function like a stack: you can push
1196 values onto the grob-setting-stack with @code{\override} and you pop
1197 them with @code{\revert}.
1199 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1200 with some more often used formatting instructions, but to explain how it
1201 works, we wrote our own here. Of course, you should use predefined
1202 identifiers like these if possible: then you will be affected less by
1203 the implementation changes we occasionally make.
1206 viola = \notes \relative c' \context Voice = viola @{
1208 In this example, you can see multiple parts on a staff. Each part is
1209 associated with one notation context. This notation context handles
1210 stems and dynamics (among others). The name of this context is
1211 @code{Voice}. For each part we have to make sure that there is
1212 precisely one @code{Voice} context, so we give it an unique name
1216 <c4-\f-\arpeggio g' c>
1218 The delimiters @code{<} and @code{>} are shorthands for
1219 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1220 @code{<} and @code{>} is a chord.
1227 @code{\f} places a forte symbol under the chord. The forte applies to
1228 the whole chord, but the syntax requires that commands like forte and
1229 arpeggio are attached to a note, so here we attach them to the first
1232 @code{\arpeggio} draws an vertical wavy line before the chord,
1233 signifying an arpeggio.
1243 Relative octaves work a little differently with chords. The starting
1244 point for the note following a chord is the first note of the chord. So
1245 the @code{g} gets an octave up quote: it is a fifth above the starting
1246 note of the previous chord (the central C).
1251 @code{s} is a spacer rest. It does not print anything, but it does have
1252 the duration of a rest. It is useful for filling up voices that
1253 temporarily don't play. In this case, the viola doesn't come until one
1254 and a half measure later.
1257 oboes = \notes \relative c'' \context Voice = oboe @{
1259 Now comes a part for two oboes. They play homophonically, so we
1260 print the notes as one voice that makes chords. Again, we insure that
1261 these notes are indeed processed by precisely one context with
1264 \stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1266 @code{\stemUp} is a reference to the @code{\property \override} command
1269 \grace <e8 g> < d4 f> <c2 e>
1271 @cindex @code{\grace}
1275 @code{\grace} introduces grace notes. It takes one argument, in this
1279 The slur started on the @code{e} of the chord
1280 will be attached to the next note.@footnote{LilyPond will squirm
1281 about unended Slurs. In this case, you can ignore the warning}.
1288 Tuplets are made with the @code{\times} keyword. It takes two
1289 arguments: a fraction and a piece of music. The duration of the piece
1290 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1291 of their notated duration, so in this case the fraction is 2/3.
1293 @{ <d8 \< f> <e g> <f a> @}
1295 The piece of music to be `tripletted' is sequential music containing
1296 three notes. On the first chord, a crescendo is started with
1297 @code{\<}. To be precise, the crescendo start is syntactically attached
1298 to the preceding note, the @code{d}.
1307 At this point, the homophonic music splits into two rhythmically
1308 different parts. We can't use a sequence of chords to enter this, so
1309 we make a `chord' of sequences to do it. We start with the upper
1310 voice, which continues with upward stems:
1312 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1317 The crescendo is ended at the half note by the escaped exclamation
1320 \context Voice = oboeTwo @{
1323 We can't share stems with the other voice, so we have to create a new
1324 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1325 it from the other context. Stems go down in this voice.
1329 @cindex Grace context
1330 When a grace section is processed, a @code{Grace} context is
1331 created. This context acts like a miniature score of its own. It has
1332 its own time bookkeeping, and you can make notes, beams, slurs
1333 etc. Here we fiddle with a property and make a beam. The argument of
1334 @code{\grace} is sequential music.
1337 \property Grace.Stem \override #'direction = #-1
1341 Normally, grace notes are always stem up, but in this case, the upper
1342 voice interferes. We set the stems down here.
1344 As far as relative mode is concerned, the previous note is the
1345 @code{c'''2} of the upper voice, so we have to go an octave down for
1352 This ends the two-part section.
1355 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1360 @code{\stemBoth} ends the forced stem directions. From here, stems are
1361 positioned as if it were single part music.
1363 The bass has a little hoom-pah melody to demonstrate parts switching
1364 between staffs. Since it is repetitive, we use repeats:
1366 hoomPah = \repeat unfold 8
1368 @cindex unfolded @code{\repeat}
1369 This repeat print the following sequence notes eight times.
1371 \notes \transpose c' @{
1374 @cindex relative mode and transposing
1376 Transposing can be done with @code{\transpose}. It takes two arguments;
1377 the first specifies what central C should be transposed to. The second
1378 is the to-be-transposed music. As you can see, in this case, the
1379 transposition is a no-op, as central C stay at central C.
1381 The purpose of this no-op is circumventing relative mode. Relative mode
1382 can not be used together with transposition, so @code{\relative} will
1383 leave the contents of @code{\hoomPah} alone. We can use it without
1384 having to worry about getting the motive in a wrong octave.
1386 bassvoices = \notes \relative c' @{
1388 \autochange Staff \hoomPah
1390 @cindex staff switch, automatic
1391 @cindex cross staff voice, automatic
1392 @cindex @code{\autochange}
1394 Voices can switch between staffs. The easiest way to get this, is to use
1395 @code{\autochange}. This command looks at the pitch of each note, and if
1396 necessary, will cross to the other staff. For this to work, the two
1397 staffs must be called @code{"up"} and @code{"down"}.
1399 \translator Staff = down
1401 @cindex staff switch
1402 @cindex cross staff voice
1403 The rest of this melody must be in the lower staff, so we do a manual
1408 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1412 After skipping some lines, we see @code{~}. This mark makes ties.
1416 A special context is needed to get cross staff beaming right. This
1417 context is called @code{PianoStaff}.
1419 \context Staff = bottom < \time 2/2; \clef bass;
1421 The bottom staff must have a different clef.
1425 To make some more room on the line, the first (in this case the only)
1426 line is not indented. The line still looks very cramped, but that is due
1427 to the page layout of this document.
1432 * arpeggio, glissando,
1434 * \apply, \outputproperty, \translator @{@}, \molecule hacking.
1436 * font-size, cadenza. rhythmic staff, multi-stanza.
1438 * Simple part combining in a Hymn
1441 @node An orchestral score
1442 @section An orchestral score
1445 demonstrate Hara-Kiri, part combining, part extraction,
1446 scores, transposition, instrument names.]
1448 Hopefully, you have seen enough LilyPond input examples by now to be
1449 able read the input for a full orchestral score. We will not go through
1450 the input line by line, but only indicate and explain the new elements.
1455 \include "paper13.ly";
1457 % #(set! point-and-click #t)
1460 flautoI = \notes\relative c'' {
1461 \property Score.currentBarNumber = #218
1462 des2.()c4|e(f e)f|\break
1463 r2 des4\sf()c|r2 des4\sf()c|
1465 flautoII = \notes\relative c'' {
1466 g2.()as4|bes(as bes)as|
1469 oboeI = \notes\relative c'' {
1473 oboeII = \notes\relative c'' {
1474 g2.()as4|bes(as bes)as|
1477 clarinettoI = \notes\relative c' {
1478 es2.()d4|c(bis c)bes|
1479 % r2 es4\sf()d|r2 es4\sf()d|
1481 clarinettoII = \notes\relative c' {
1482 es2.()d4|c(bes c)bes|
1483 % r2 es'4\sf()d|r2 es4\sf()d|
1485 fagottoI = \notes\relative c' {
1487 r r8 des' des4\sf()es|r r8 des des4\sf()es|
1489 fagottoII = \notes\relative c' {
1490 bes2.()as4 | g(f g)f|
1493 cornoI = \notes\relative c''' {
1495 % r4 r8 f f2|r4 r8 f f2|
1497 cornoII = \notes\relative c''' {
1498 g,2. d'4|g, d' g, d'|
1499 r4 r8 d d4\sf()es|r4 r8 d d4\sf()es|
1501 tromboI = \notes\relative c'' {
1505 tromboII = \notes\relative c' {
1509 timpani = \notes\relative c {
1510 c2:16 c4 c|c c c c |
1513 violinoI = \notes\relative c' {
1514 des'2:16\ff des4: c:|e,: f: e: f:|
1515 r8 as des,4\sf~des()c |r8 as' des,4\sf~des()c|
1517 violinoII = \notes\relative c' {
1518 des2:16\ff des4: c: | bes: as: bes: as:|
1519 % r8 as des,4\sf ~ des()c| r8 as' des,4\sf ~ des()c|
1521 violaI = \notes\relative c' {
1522 e2:16\ff e4: f:|b,: c: b: c:|
1523 r4 r8 as as2\sf|r4 r8 as as2\sf|
1525 violaII = \notes\relative c' {
1526 bes2:16\ff bes4: as:|g: f: g: f: |
1527 r4 r8 f f4\sf()ges|r4 r8 f f4\sf()ges|
1529 violoncello = \notes\relative c {
1530 bes2.\ff()as4|g( f g )f |
1531 r4 r8 f' f4\sf()ges |r4 r8 f f4\sf()ges |
1533 contrabasso = \notes\relative c {
1534 bes2.\ff()as4|g( f g )f|
1538 #(define text-flat '((font-relative-size . -2) (music "accidentals--1")))
1540 staffCombinePianoStaffProperties = {
1541 \property PianoStaff.devNullThread = #'()
1542 \property PianoStaff.soloADue = ##t
1543 \property PianoStaff.soloText = #""
1544 \property PianoStaff.soloIIText = #""
1545 % This is non-conventional, but currently it is
1546 % the only way to tell the difference.
1547 \property PianoStaff.aDueText = #"\\`a2"
1548 \property PianoStaff.splitInterval = #'(1 . 0)
1549 \property PianoStaff.changeMoment = #`(,(make-moment 1 1) . ,(make-moment 1 1))
1550 \property PianoStaff.noDirection = ##t
1554 %% Hmm, can't we move this to a `template.ly'
1558 \context StaffGroup = wood <
1559 \context Staff = flauti <
1560 \property Staff.midiInstrument = #"flute"
1561 \property Staff.instrument = "2 Flauti"
1562 \property Staff.instr = "Fl."
1563 \context Voice=one \partcombine Voice
1564 \context Thread=one \flautoI
1565 \context Thread=two \flautoII
1567 \context Staff = oboes <
1568 \property Staff.midiInstrument = #"oboe"
1569 \property Staff.instrument = "2 Oboi"
1570 \property Staff.instr = "Ob."
1571 \context Voice=one \partcombine Voice
1572 \context Thread=one \oboeI
1573 \context Thread=two \oboeII
1575 \context Staff = clarinets <
1576 \property Staff.midiInstrument = #"clarinet"
1577 \property Staff.instrument = #`(lines
1578 "2 Clarinetti" (rows "(B" ,text-flat ")"))
1579 \property Staff.instr = #`(lines
1580 "Cl." (rows "(B" ,text-flat ")"))
1581 \property Staff.transposing = #-2
1582 \notes \key f \major;
1583 \context Voice=one \partcombine Voice
1584 \context Thread=one \clarinettoI
1585 \context Thread=two \clarinettoII
1587 \context Staff = bassoons <
1588 \property Staff.midiInstrument = #"bassoon"
1589 \property Staff.instrument = "2 Fagotti"
1590 \property Staff.instr = "Fg."
1592 \context Voice=one \partcombine Voice
1593 \context Thread=one \fagottoI
1594 \context Thread=two \fagottoII
1597 \context StaffGroup = brass <
1598 \context Staff = frenchHorns <
1599 \property Staff.midiInstrument = #"french horn"
1600 \property Staff.instrument = #`(lines
1601 "2 Corni" (rows "(E" ,text-flat ")"))
1602 \property Staff.instr = #`(lines
1603 "Cor." (rows "(E" ,text-flat ")"))
1604 \property Staff.transposing = #3
1605 \notes \key c \major;
1606 \context Voice=one \partcombine Voice
1607 \context Thread=one \cornoI
1608 \context Thread=two \cornoII
1610 \context Staff = trumpets <
1611 \property Staff.midiInstrument = #"trumpet"
1612 \property Staff.instrument = #`(lines
1613 "2 Trombe" (rows "(C)"))
1614 \property Staff.instr = #`(lines
1615 "Tbe." (rows "(C)"))
1616 \context Voice=one \partcombine Voice
1617 \context Thread=one \tromboI
1618 \context Thread=two \tromboII
1621 \context StaffGroup = timpani <
1622 \context Staff = timpani <
1623 \property Staff.midiInstrument = #"timpani"
1624 \property Staff.instrument = #'(lines
1625 "2 Timpani" "(C-G)")
1626 \property Staff.instr = #"Timp."
1631 \context StaffGroup = strings <
1632 \context GrandStaff = violins <
1633 \context Staff = viI <
1634 \property Staff.midiInstrument = #"violin"
1635 \property Staff.instrument = "Violino I"
1636 \property Staff.instr = "Vi. I"
1639 \context Staff = viII <
1640 \property Staff.midiInstrument = #"violin"
1641 \property Staff.instrument = "Violino II"
1642 \property Staff.instr = "Vi. II"
1646 \context Staff = vla <
1647 \property Staff.midiInstrument = #"viola"
1648 \property Staff.instrument = "Viola"
1649 \property Staff.instr = "Vla."
1651 \context Voice=one \partcombine Voice
1652 \context Thread=one \violaI
1653 \context Thread=two \violaII
1655 \context PianoStaff=bass <
1656 \staffCombinePianoStaffProperties
1657 \context Staff=one <
1658 \property Staff.midiInstrument = #"cello"
1659 \property Staff.instrument = #'(lines
1660 "Violoncello" " e" "Contrabasso")
1661 \property Staff.instr = "Vc."
1664 \context Staff=two <
1665 \property Staff.midiInstrument = #"contrabass"
1666 \property Staff.instrument = "Contrabasso"
1667 \property Staff.instr = "C.B."
1669 \skip 1*4; % sustain clef
1671 \context Staff=one \partcombine Staff
1672 \context Voice=one \violoncello
1673 \context Voice=two \contrabasso
1679 linewidth = 80 * \staffspace;
1680 textheight = 200 * \staffspace;
1683 \consists "Rest_engraver";
1685 % Set value for engraver at thread level,
1686 % to override the default that is set in ScoreContext
1687 % for added engraver at Voice level
1688 devNullThread = #'()
1692 \remove "Rest_engraver";
1694 % The staff combine (bassi part) needs a
1695 % thread_devnull_engraver here.
1696 % Instead of maintaining two separate hierarchies,
1697 % we switch add it, but switch it off immediately.
1698 % --> move to Score level to be able to override
1699 % The staff combine part switches it on.
1701 %% devNullThread = #'never
1702 \consists "Thread_devnull_engraver";
1705 \HaraKiriStaffContext
1706 \consists "Mark_engraver";
1709 \OrchestralScoreContext
1714 % By default, turn off the Thread_devnull_engraver
1716 devNullThread = #'never
1719 currentBarNumber = #218
1720 BarNumber \override #'padding = #3
1721 RestCollision \override #'maximum-rest-count = #1
1722 TimeSignature \override #'style = #'C
1731 % #(set! point-and-click #t)
1735 #(define text-flat '((font-relative-size . -2) (music "accidentals--1")))
1739 staffCombinePianoStaffProperties = @{
1747 flautoI = \notes\relative c'' @{
1751 \property Score.currentBarNumber = #218
1755 flautoII = \notes\relative c'' @{
1761 The hairyness of Staff combining
1764 \property PianoStaff.devNullThread = #'()
1768 \property PianoStaff.soloADue = ##t
1772 \property PianoStaff.soloText = #""
1773 \property PianoStaff.soloIIText = #""
1777 % This is non-conventional, but currently it is
1778 % the only way to tell the difference.
1779 \property PianoStaff.aDueText = #"\\`a2"
1783 \property PianoStaff.splitInterval = #'(1 . 0)
1784 \property PianoStaff.changeMoment = #`(,(make-moment 1 1) . ,(make-moment 1 1))
1788 \property PianoStaff.noDirection = ##t
1798 \context StaffGroup = wood <
1802 \context Staff = flauti <
1806 \property Staff.midiInstrument = #"flute"
1810 \property Staff.instrument = "2 Flauti"
1811 \property Staff.instr = "Fl."
1815 \context Voice=one \partcombine Voice
1816 \context Thread=one \flautoI
1817 \context Thread=two \flautoII
1824 \property Staff.instrument = #`(lines
1825 "2 Clarinetti" (rows "(B" ,text-flat ")"))
1829 \property Staff.instr = #`(lines
1830 "Cl." (rows "(B" ,text-flat ")"))
1834 \property Staff.transposing = #-2
1838 \notes \key f \major;
1844 [the syntax of staff combining]
1847 @node end of tutorial
1850 That's all folks. From here, you can either try fiddling with input
1851 files, or you can read the reference manual.