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 Chapter @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 Section @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.
179 @unnumberedsubsec Windows
185 @section The first tune
188 To demonstrate what LilyPond input looks like, we start off with a
189 full-fledged, yet simple example. It is a convoluted version
190 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
191 is included in the distribution as @file{menuet.ly}.
192 @cindex Bach, Johann Sebastian
195 % lines preceded by a percent are comments which
196 % are ignored by Lilypond.
197 \include "paper16.ly"
200 \relative c'' \sequential{
205 d4 g,8 a b c d4 g, g |
206 e'4 c8 d e fis g4 g, g |
207 c4 d8()c b a( )b4 c8 b a g |
208 a4 [b8 a] [g fis] g2. |
213 g4 e8 fis g d cis4 b8 cis a4 |
214 a8-. b-. cis-. d-. e-. fis-.
221 % standard settings are too wide for a book
222 linewidth = 14.0 \cm;
227 We will analyse the input, line by line.
229 % lines preceded by a percent are comments which
230 % are ignored by Lilypond.
232 The percent sign, @code{%}, introduces a line comment. If you want to
233 make larger comments, you can use block comments. These are delimited
234 by @code{%@{} and @code{%@}}
236 @cindex block comment
241 \include "paper16.ly"
244 @cindex @code{\include}
245 @cindex point, printer's
246 @cindex staff size setting
247 By default, LilyPond will use definitions for a staff that is 20
248 point@footnote {A point is the standard measure of length for printing;
249 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
250 output (16 point staff height), so we must import the settings for that
251 size, which is done here.
257 A lilypond file combines music with directions for outputting that
258 music. The music is combined with the output directions by putting
259 them into a @code{\score} block.
265 This makes LilyPond ready for accepting notes.
272 @cindex octaves, choosing
274 As we will see, pitches are combinations of octave, note name and
275 chromatic alteration. In this scheme, the octave is indicated by
276 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
277 @code{,}). The central C is denoted by @code{c'}. The C one octave
278 higher is @code{c''}. One and two octaves below the central C is
279 denoted by @code{c} and @code{c,} respectively.
282 For pitches in a long piece you might have to type many quotes. To
283 remedy this, LilyPond has a ``relative'' octave entry mode. In this
284 mode, octaves of notes without quotes are chosen such that a note is
285 as close as possible (graphically, on the staff) to the the preceding
286 note. If you add a high-quote an extra octave is added. The lowered
287 quote (a comma) will subtract an extra octave. Because the first note
288 has no predecessor, you have to give the (absolute) pitch of the note
295 What follows is sequential music, i.e.,
296 @cindex sequential music
297 notes that are to be played and printed after each other.
303 @cindex time signature, setting
305 This command changes the time signature of the current piece: a 3/4
306 sign is printed. This command is also used to generate bar lines in
313 @cindex key signature, setting
315 This command changes the current key signature to G-major. Although this
316 command comes after the @code{\time} command, in the output, the key
317 signature comes before the time signature: LilyPond knows about music
318 typesetting conventions.
324 This command tells LilyPond that the following piece of music must be
325 played twice. The first argument indicates the type of repeat. In this
326 case, @code{"volta"} means that volta brackets are be used for
327 alternatives---if there were any.
333 The subject of the repeat is again sequential music. Since
334 @code{\sequential} is such a common construct, a shorthand is provided:
335 just leave off @code{\sequential}, and the result is the same.
341 This is a note with pitch @code{d} (determined up to octaves). The
342 relative music was started with a @code{c''}, so the real pitch of this
343 note is @code{d''}. The @code{4} designates the duration of the note
344 (it is a quarter note).
350 These are notes with pitch @code{a} and @code{b}. Because their
351 duration is the same as the @code{g}, there is no need to enter the
352 duration (You may enter it anyway, e.g. @code{a4 b4})
360 @cindex errors, finding
361 Three more notes. The @code{|} character is a `bar check'. When
362 processing the music, LilyPond will verify that bar checks are found at
363 the start of a measure. This can help you track down errors.
365 @cindex alteration, chromatic
366 @cindex chromatic alteration
367 So far, no notes were chromatically altered. Here is the first one
368 that is: @code{fis}. Lilypond by default uses Dutch note names, and
369 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
370 sharp sign in the output. The program keeps track of key signatures,
371 and will only print accidentals if they are needed.
377 LilyPond guesses were beams can be added to eighth and shorter notes.
378 In this case, a beam over 4 eighths is added.
381 c4 d8( )c b a( )b4 c8 b a g |
384 The next line shows how to make a slur: the beginning and ending note
385 of the slur is marked with an opening and closing parenthesis
386 respectively. In the line shown above, this is done for two slurs.
387 Slur markers (parentheses) are put between the slurred notes.
393 Automatic beaming can be overridden by inserting beam marks
394 (brackets). Brackets are put around the notes you want beamed.
400 @cindex augmentation dot
402 A duration with augmentation dot is notated
403 with the duration number followed by a period.
409 This ends the sequential music to be repeated. LilyPond will typeset
416 This line shows that Lily will print an accidental if that is
417 needed: the first C sharp of the bar will be printed with an accidental,
418 the second one without.
421 a8-. b-. cis-. d-. e-. fis-.
425 You can enter articulation signs either in a verbose form using a
426 shorthand. Here we demonstrate the shorthand: it is formed by a dash
427 and the character for the articulation to use, e.g. @code{-.} for
428 staccato as shown above.
435 Rests are denoted by the special notename @code{r}.
441 All articulations have a verbose form, like @code{\fermata}. The
442 command @code{\fermata} is not part of the core of the language (most
443 of the other discussed elements are), but it is a shorthand for a more
444 complicated description of a fermata. @code{\fermata} names that
445 description and is therefore called an identifier.
447 @cindex @code{\fermata}
462 This specifies a conversion from music to notation output. Most of
463 the details of this conversions (font sizes, dimensions, etc.) have
464 been taken care of, but to fit the output in this document, it has
465 to be smaller. We do this by setting the line width to 14 centimeters
466 (approximately 5.5 inches).
472 The last brace ends the @code{\score} block.
477 @node Lyrics and chords
478 @section Lyrics and chords
480 In this section we show how to typeset a song.@footnote{The author would
481 welcome information about the origin of this 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 * Orchestral: demonstrate Hara-Kiri, part combining, part extraction,
1446 scores, transposition, instrument names,
1449 Hopefully, you have seen enough LilyPond input examples by now to be
1450 able read the input for a full orchestral score. We will not go through
1451 the input line by line, but only indicate and explain the new elements.
1456 \include "paper13.ly";
1458 % #(set! point-and-click #t)
1461 flautoI = \notes\relative c'' {
1462 \property Score.currentBarNumber = #218
1463 des2.()c4|e(f e)f|\break
1464 r2 des4\sf()c|r2 des4\sf()c|
1466 flautoII = \notes\relative c'' {
1467 g2.()as4|bes(as bes)as|
1470 oboeI = \notes\relative c'' {
1474 oboeII = \notes\relative c'' {
1475 g2.()as4|bes(as bes)as|
1478 clarinettoI = \notes\relative c' {
1479 es2.()d4|c(bis c)bes|
1480 % r2 es4\sf()d|r2 es4\sf()d|
1482 clarinettoII = \notes\relative c' {
1483 es2.()d4|c(bes c)bes|
1484 % r2 es'4\sf()d|r2 es4\sf()d|
1486 fagottoI = \notes\relative c' {
1488 r r8 des' des4\sf()es|r r8 des des4\sf()es|
1490 fagottoII = \notes\relative c' {
1491 bes2.()as4 | g(f g)f|
1494 cornoI = \notes\relative c''' {
1496 % r4 r8 f f2|r4 r8 f f2|
1498 cornoII = \notes\relative c''' {
1499 g,2. d'4|g, d' g, d'|
1500 r4 r8 d d4\sf()es|r4 r8 d d4\sf()es|
1502 tromboI = \notes\relative c'' {
1506 tromboII = \notes\relative c' {
1510 timpani = \notes\relative c {
1511 c2:16 c4 c|c c c c |
1514 violinoI = \notes\relative c' {
1515 des'2:16\ff des4: c:|e,: f: e: f:|
1516 r8 as des,4\sf~des()c |r8 as' des,4\sf~des()c|
1518 violinoII = \notes\relative c' {
1519 des2:16\ff des4: c: | bes: as: bes: as:|
1520 % r8 as des,4\sf ~ des()c| r8 as' des,4\sf ~ des()c|
1522 violaI = \notes\relative c' {
1523 e2:16\ff e4: f:|b,: c: b: c:|
1524 r4 r8 as as2\sf|r4 r8 as as2\sf|
1526 violaII = \notes\relative c' {
1527 bes2:16\ff bes4: as:|g: f: g: f: |
1528 r4 r8 f f4\sf()ges|r4 r8 f f4\sf()ges|
1530 violoncello = \notes\relative c {
1531 bes2.\ff()as4|g( f g )f |
1532 r4 r8 f' f4\sf()ges |r4 r8 f f4\sf()ges |
1534 contrabasso = \notes\relative c {
1535 bes2.\ff()as4|g( f g )f|
1539 #(define text-flat '((font-relative-size . -2) (music "accidentals--1")))
1541 staffCombinePianoStaffProperties = {
1542 \property PianoStaff.devNullThread = #'()
1543 \property PianoStaff.soloADue = ##t
1544 \property PianoStaff.soloText = #""
1545 \property PianoStaff.soloIIText = #""
1546 % This is non-conventional, but currently it is
1547 % the only way to tell the difference.
1548 \property PianoStaff.aDueText = #"\\`a2"
1549 \property PianoStaff.splitInterval = #'(1 . 0)
1550 \property PianoStaff.changeMoment = #`(,(make-moment 1 1) . ,(make-moment 1 1))
1551 \property PianoStaff.noDirection = ##t
1555 %% Hmm, can't we move this to a `template.ly'
1559 \context StaffGroup = wood <
1560 \context Staff = flauti <
1561 \property Staff.midiInstrument = #"flute"
1562 \property Staff.instrument = "2 Flauti"
1563 \property Staff.instr = "Fl."
1564 \context Voice=one \partcombine Voice
1565 \context Thread=one \flautoI
1566 \context Thread=two \flautoII
1568 \context Staff = oboes <
1569 \property Staff.midiInstrument = #"oboe"
1570 \property Staff.instrument = "2 Oboi"
1571 \property Staff.instr = "Ob."
1572 \context Voice=one \partcombine Voice
1573 \context Thread=one \oboeI
1574 \context Thread=two \oboeII
1576 \context Staff = clarinets <
1577 \property Staff.midiInstrument = #"clarinet"
1578 \property Staff.instrument = #`(lines
1579 "2 Clarinetti" (rows "(B" ,text-flat ")"))
1580 \property Staff.instr = #`(lines
1581 "Cl." (rows "(B" ,text-flat ")"))
1582 \property Staff.transposing = #-2
1583 \notes \key f \major;
1584 \context Voice=one \partcombine Voice
1585 \context Thread=one \clarinettoI
1586 \context Thread=two \clarinettoII
1588 \context Staff = bassoons <
1589 \property Staff.midiInstrument = #"bassoon"
1590 \property Staff.instrument = "2 Fagotti"
1591 \property Staff.instr = "Fg."
1593 \context Voice=one \partcombine Voice
1594 \context Thread=one \fagottoI
1595 \context Thread=two \fagottoII
1598 \context StaffGroup = brass <
1599 \context Staff = frenchHorns <
1600 \property Staff.midiInstrument = #"french horn"
1601 \property Staff.instrument = #`(lines
1602 "2 Corni" (rows "(E" ,text-flat ")"))
1603 \property Staff.instr = #`(lines
1604 "Cor." (rows "(E" ,text-flat ")"))
1605 \property Staff.transposing = #3
1606 \notes \key c \major;
1607 \context Voice=one \partcombine Voice
1608 \context Thread=one \cornoI
1609 \context Thread=two \cornoII
1611 \context Staff = trumpets <
1612 \property Staff.midiInstrument = #"trumpet"
1613 \property Staff.instrument = #`(lines
1614 "2 Trombe" (rows "(C)"))
1615 \property Staff.instr = #`(lines
1616 "Tbe." (rows "(C)"))
1617 \context Voice=one \partcombine Voice
1618 \context Thread=one \tromboI
1619 \context Thread=two \tromboII
1622 \context StaffGroup = timpani <
1623 \context Staff = timpani <
1624 \property Staff.midiInstrument = #"timpani"
1625 \property Staff.instrument = #'(lines
1626 "2 Timpani" "(C-G)")
1627 \property Staff.instr = #"Timp."
1632 \context StaffGroup = strings <
1633 \context GrandStaff = violins <
1634 \context Staff = viI <
1635 \property Staff.midiInstrument = #"violin"
1636 \property Staff.instrument = "Violino I"
1637 \property Staff.instr = "Vi. I"
1640 \context Staff = viII <
1641 \property Staff.midiInstrument = #"violin"
1642 \property Staff.instrument = "Violino II"
1643 \property Staff.instr = "Vi. II"
1647 \context Staff = vla <
1648 \property Staff.midiInstrument = #"viola"
1649 \property Staff.instrument = "Viola"
1650 \property Staff.instr = "Vla."
1652 \context Voice=one \partcombine Voice
1653 \context Thread=one \violaI
1654 \context Thread=two \violaII
1656 \context PianoStaff=bass <
1657 \staffCombinePianoStaffProperties
1658 \context Staff=one <
1659 \property Staff.midiInstrument = #"cello"
1660 \property Staff.instrument = #'(lines
1661 "Violoncello" " e" "Contrabasso")
1662 \property Staff.instr = "Vc."
1665 \context Staff=two <
1666 \property Staff.midiInstrument = #"contrabass"
1667 \property Staff.instrument = "Contrabasso"
1668 \property Staff.instr = "C.B."
1670 \skip 1*4; % sustain clef
1672 \context Staff=one \partcombine Staff
1673 \context Voice=one \violoncello
1674 \context Voice=two \contrabasso
1680 linewidth = 80 * \staffspace;
1681 textheight = 200 * \staffspace;
1684 \consists "Rest_engraver";
1686 % Set value for engraver at thread level,
1687 % to override the default that is set in ScoreContext
1688 % for added engraver at Voice level
1689 devNullThread = #'()
1693 \remove "Rest_engraver";
1695 % The staff combine (bassi part) needs a
1696 % thread_devnull_engraver here.
1697 % Instead of maintaining two separate hierarchies,
1698 % we switch add it, but switch it off immediately.
1699 % --> move to Score level to be able to override
1700 % The staff combine part switches it on.
1702 %% devNullThread = #'never
1703 \consists "Thread_devnull_engraver";
1706 \HaraKiriStaffContext
1707 \consists "Mark_engraver";
1710 \OrchestralScoreContext
1715 % By default, turn off the Thread_devnull_engraver
1717 devNullThread = #'never
1720 currentBarNumber = #218
1721 BarNumber \override #'padding = #3
1722 RestCollision \override #'maximum-rest-count = #1
1723 TimeSignature \override #'style = #'C
1732 % #(set! point-and-click #t)
1736 #(define text-flat '((font-relative-size . -2) (music "accidentals--1")))
1740 staffCombinePianoStaffProperties = @{
1748 flautoI = \notes\relative c'' @{
1752 \property Score.currentBarNumber = #218
1756 flautoII = \notes\relative c'' @{
1762 The hairyness of Staff combining
1765 \property PianoStaff.devNullThread = #'()
1769 \property PianoStaff.soloADue = ##t
1773 \property PianoStaff.soloText = #""
1774 \property PianoStaff.soloIIText = #""
1778 % This is non-conventional, but currently it is
1779 % the only way to tell the difference.
1780 \property PianoStaff.aDueText = #"\\`a2"
1784 \property PianoStaff.splitInterval = #'(1 . 0)
1785 \property PianoStaff.changeMoment = #`(,(make-moment 1 1) . ,(make-moment 1 1))
1789 \property PianoStaff.noDirection = ##t
1799 \context StaffGroup = wood <
1803 \context Staff = flauti <
1807 \property Staff.midiInstrument = #"flute"
1811 \property Staff.instrument = "2 Flauti"
1812 \property Staff.instr = "Fl."
1816 \context Voice=one \partcombine Voice
1817 \context Thread=one \flautoI
1818 \context Thread=two \flautoII
1825 \property Staff.instrument = #`(lines
1826 "2 Clarinetti" (rows "(B" ,text-flat ")"))
1830 \property Staff.instr = #`(lines
1831 "Cl." (rows "(B" ,text-flat ")"))
1835 \property Staff.transposing = #-2
1839 \notes \key f \major;
1845 [the syntax of staff combining]
1848 @node end of tutorial
1851 That's all folks. From here, you can either try fiddling with input
1852 files, or you can read the reference manual.