7 * Introduction:: Introduction
8 * Running LilyPond:: Getting started
9 * The first tune:: The first tune
10 * Lyrics and chords:: Lyrics and chords
11 * More movements:: More than one movement in a file
12 * A piano excerpt:: Piano music
13 * end of tutorial:: The end
20 LilyPond prints music from a specification that you, the user, supply.
21 You have to give that specification using a @emph{language}. This
22 chapter is a gentle introduction to that language.
24 This tutorial will demonstrate how to use Lilypond by presenting
25 examples of input along with resulting output. We will use English
26 terms for notation. In case you are not familiar with those, you may
27 consult the glossary that is distributed with LilyPond.
29 @cindex examples, tutorial
31 The examples discussed are included in the distribution, in the
32 subdirectory @file{input/tutorial/}.@footnote{When we refer
33 to filenames, they are relative to the top directory of the source
36 }. We recommend that you experiment with writing Lilypond input
37 yourself, to get a feel for how the program behaves.
40 @node Running LilyPond
41 @section Running LilyPond
43 Before we dive into describing the input language of LilyPond, we first
44 show you through the procedure for getting notes on your screen and out
47 The first step is creating an input file. Using your favorite
48 text-editor, create @file{test.ly} containing
56 \notes @{ c'4 e'4 g'4 @}
61 @unnumberedsubsec Unix
63 @cindex Unix, Running lilypond on
65 If you run Unix, proceed as follows: run lilypond on the file, i.e.,
69 You will see the following on your screen:
72 Now processing: `input/tutorial/test.ly'
74 Interpreting music...[1]
75 Preprocessing elements...
76 Calculating column positions... [2]
77 paper output to test.tex...
80 Now, run @TeX{}@footnote{@TeX{} is a text-typesetting system that is
81 especially suited for typesetting mathematics.}. The result should
84 This is TeX, Version 3.14159 (Web2C 7.3.1)
85 (test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
86 (/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
87 LilyPond Plain TeX settings) (/home/hanwen/usr/src/ ...
88 (/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
89 (/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
90 Output written on test.dvi (1 page, 3716 bytes).
91 Transcript written on test.log.
93 The result of the @TeX{} run is a @TeX{} ``DeVice Independent'' file
100 To view the output, run Xdvi, i.e.
104 You should see the following in a window next to some buttons.
111 \notes { c'4 e'4 g'4 }
116 @cindex postscript, converting to
117 When you're satisfied with the result, you can print it. For printing,
118 you have to generate a postscript file:
120 dvips -o test.ps test.dvi
122 which looks like this:
124 This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
125 ' TeX output 2001.01.27:1806' -> test.ps
126 <texc.pro><special.pro>. [1]
130 @cindex Printing output
133 PostScript is a page description language, similar to PDF. Some printers
134 can understand a postscript file directly, but the cheaper ones need the
135 intervention of GhostScript, an emulator that runs PostScript on your
136 computer instead of your printer. Most Linux distributions nowadays have
137 GhostScript running ``in the background'', so any configured printer
138 will act as a PostScript printer. Assuming this, the following command
143 If this does not make your printer produce a page of music, then you
144 should look into installing and configuring ghostscript. Refer to
145 GhostScript's website at @uref{http://www.ghostscript.com}.
147 There are three other routes: firstly, you can add titling to the
148 output. This is done by a separate program called @file{ly2dvi}: this
149 program first calls LilyPond to process the @file{.ly} file, and then
150 runs @TeX{} on it to produce a @file{.dvi} file with proper margin
151 settings and titling.
153 @cindex titles, adding
159 After some disk-activity, you should end up with a @file{.dvi} file.
160 Ly2dvi is further described in the Chapter @ref{ly2dvi}.
162 Secondly, you can generate PostScript directly. This is useful if you
163 can not or do not want to run @TeX{} on your system.
164 To obtain PS output, invoke LilyPond as follows:
165 @cindex PostScript output
167 lilypond -f ps test.ly
170 You have to set some environment variables to view or print this
171 output. More information can be found in the Section @ref{Invoking
174 Finally, there is a script called lilypond-book, that allows you to
175 freely mix LilyPond input with Texinfo or LaTeX input. For example, this
176 manual was written using lilypond-book.
178 @unnumberedsubsec Windows
184 @section The first tune
187 To demonstrate what LilyPond input looks like, we start off with a
188 full-fledged, yet simple example. It is a convoluted version
189 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
190 is included in the distribution as @file{menuet.ly}.
191 @cindex Bach, Johann Sebastian
194 % lines preceded by a percent are comments which
195 % are ignored by Lilypond.
196 \include "paper16.ly"
199 \relative c'' \sequential{
204 d4 g,8 a b c d4 g, g |
205 e'4 c8 d e fis g4 g, g |
206 c4 d8()c b a( )b4 c8 b a g |
207 a4 [b8 a] [g fis] g2. |
212 g4 e8 fis g d cis4 b8 cis a4 |
213 a8-. b-. cis-. d-. e-. fis-.
220 % standard settings are too wide for a book
221 linewidth = 14.0 \cm;
226 We will analyse the input, line by line.
228 % lines preceded by a percent are comments which
229 % are ignored by Lilypond.
231 The percent sign, @code{%}, introduces a line comment. If you want to
232 make larger comments, you can use block comments. These are delimited
233 by @code{%@{} and @code{%@}}
235 @cindex block comment
240 \include "paper16.ly"
243 @cindex @code{\include}
244 @cindex point, printer's
245 @cindex staff size setting
246 By default, LilyPond will use definitions for a staff that is 20
247 point@footnote {A point is the standard measure of length for printing;
248 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
249 output (16 point staff height), so we must import the settings for that
250 size, which is done here.
256 A lilypond file combines music with directions for outputting that
257 music. The music is combined with the output directions by putting
258 them into a @code{\score} block.
264 This makes LilyPond ready for accepting notes.
271 @cindex octaves, choosing
273 As we will see, pitches are combinations of octave, note name and
274 chromatic alteration. In this scheme, the octave is indicated by
275 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
276 @code{,}). The central C is denoted by @code{c'}. The C one octave
277 higher is @code{c''}. One and two octaves below the central C is
278 denoted by @code{c} and @code{c,} respectively.
281 For pitches in a long piece you might have to type many quotes. To
282 remedy this, LilyPond has a ``relative'' octave entry mode. In this
283 mode, octaves of notes without quotes are chosen such that a note is
284 as close as possible (graphically, on the staff) to the the preceding
285 note. If you add a high-quote an extra octave is added. The lowered
286 quote (a comma) will subtract an extra octave. Because the first note
287 has no predecessor, you have to give the (absolute) pitch of the note
294 What follows is sequential music, i.e.,
295 @cindex sequential music
296 notes that are to be played and printed after each other.
302 @cindex time signature, setting
304 This command changes the time signature of the current piece: a 3/4
305 sign is printed. This command is also used to generate bar lines in
312 @cindex key signature, setting
314 This command changes the current key signature to G-major. Although this
315 command comes after the @code{\time} command, in the output, the key
316 signature comes before the time signature: LilyPond knows about music
317 typesetting conventions.
323 This command tells LilyPond that the following piece of music must be
324 played twice. The first argument indicates the type of repeat. In this
325 case, @code{"volta"} means that volta brackets are be used for
326 alternatives---if there were any.
332 The subject of the repeat is again sequential music. Since
333 @code{\sequential} is such a common construct, a shorthand is provided:
334 just leave off @code{\sequential}, and the result is the same.
340 This is a note with pitch @code{d} (determined up to octaves). The
341 relative music was started with a @code{c''}, so the real pitch of this
342 note is @code{d''}. The @code{4} designates the duration of the note
343 (it is a quarter note).
349 These are notes with pitch @code{a} and @code{b}. Because their
350 duration is the same as the @code{g}, there is no need to enter the
351 duration (You may enter it anyway, e.g. @code{a4 b4})
359 @cindex errors, finding
360 Three more notes. The @code{|} character is a `bar check'. When
361 processing the music, LilyPond will verify that bar checks are found at
362 the start of a measure. This can help you track down errors.
364 @cindex alteration, chromatic
365 @cindex chromatic alteration
366 So far, no notes were chromatically altered. Here is the first one
367 that is: @code{fis}. Lilypond by default uses Dutch note names, and
368 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
369 sharp sign in the output. The program keeps track of key signatures,
370 and will only print accidentals if they are needed.
376 LilyPond guesses were beams can be added to eighth and shorter notes.
377 In this case, a beam over 4 eighths is added.
380 c4 d8( )c b a( )b4 c8 b a g |
383 The next line shows how to make a slur: the beginning and ending note
384 of the slur is marked with an opening and closing parenthesis
385 respectively. In the line shown above, this is done for two slurs.
386 Slur markers (parentheses) are put between the slurred notes.
392 Automatic beaming can be overridden by inserting beam marks
393 (brackets). Brackets are put around the notes you want beamed.
399 @cindex augmentation dot
401 A duration with augmentation dot is notated
402 with the duration number followed by a period.
408 This ends the sequential music to be repeated. LilyPond will typeset
415 This line shows that Lily will print an accidental if that is
416 needed: the first C sharp of the bar will be printed with an accidental,
417 the second one without.
420 a8-. b-. cis-. d-. e-. fis-.
424 You can enter articulation signs either in a verbose form using a
425 shorthand. Here we demonstrate the shorthand: it is formed by a dash
426 and the character for the articulation to use, e.g. @code{-.} for
427 staccato as shown above.
434 Rests are denoted by the special notename @code{r}.
440 All articulations have a verbose form, like @code{\fermata}. The
441 command @code{\fermata} is not part of the core of the language (most
442 of the other discussed elements are), but it is a shorthand for a more
443 complicated description of a fermata. @code{\fermata} names that
444 description and is therefore called an identifier.
446 @cindex @code{\fermata}
461 This specifies a conversion from music to notation output. Most of
462 the details of this conversions (font sizes, dimensions, etc.) have
463 been taken care of, but to fit the output in this document, it has
464 to be smaller. We do this by setting the line width to 14 centimeters
465 (approximately 5.5 inches).
471 The last brace ends the @code{\score} block.
476 @node Lyrics and chords
477 @section Lyrics and chords
479 In this section we show how to typeset a song.@footnote{The author would
480 welcome information about the origin of this song.}. This file is
481 included as @file{flowing.ly}.
485 title = "The river is flowing";
486 composer = "Traditional (?)";
488 \include "paper16.ly"
489 melody = \notes \relative c' @{
493 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
494 c4 c8 d [es () d] c4 | d4 es8 d c4.
499 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
500 ri -- ver is flo -- wing down to the sea.
503 accompaniment =\chords @{
505 c2:3- f:3-.7 d:min es4 c8:min r8
506 c2:min f:min7 g:7^3.5 c:min @}
511 \context ChordNames \accompaniment
514 \context Staff = mel @{
515 \property Staff.noAutoBeaming = ##t
516 \property Staff.automaticMelismata = ##t
519 \context Lyrics \text
521 \midi @{ \tempo 4=72;@}
522 \paper @{ linewidth = 10.0\cm; @}
527 The result would look this@footnote{The titling and font size shown
528 may differ, since the titling in this document is not generated by
531 @center @strong{The river is flowing}
536 title = "The river is flowing";
537 composer = "Traditional (?)";
539 \include "paper16.ly"
540 melody = \notes \relative c' {
544 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
545 c4 c8 d [es () d] c4 | d4 es8 d c4.
550 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
551 ri -- ver is flo -- wing down to the sea.
554 accompaniment =\chords {
556 c2:3- f:3-.7 d:min es4 c8:min r8
557 c2:min f:min7 g:7^3.5 c:min }
562 \context ChordNames \accompaniment
565 \context Staff = mel {
566 \property Staff.noAutoBeaming = ##t
567 \property Staff.automaticMelismata = ##t
570 \context Lyrics \text
572 \midi { \tempo 4=72;}
573 \paper { linewidth = 10.0\cm; }
577 Again, we will dissect the file line by line.
583 @cindex @code{\header}
584 Information about the music you are about to typeset goes into a
585 @code{\header} block. The information in this block is not used by
586 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
587 information to print titles above the music.
590 title = "The river is flowing";
591 composer = "Traditional (?)";
594 @cindex identifier assignment
595 the @code{\header} block contains assignments. An assignment starts
596 with a string. (which is unquoted, in this case). Then comes the
597 equal sign. After the equal sign comes the expression you
598 want to store. In this case, you want to put in strings. The
599 information has to be quoted here, because it contains spaces. Each
600 assignment is finished with a semicolon.
603 \include "paper16.ly"
606 Smaller size for inclusion in a book.
609 melody = \notes \relative c' @{
612 The structure of the file will be the same as the previous one, a
613 @code{\score} block with music in it. To keep things readable, we will
614 give names to the different parts of music, and use the names to
615 construct the music within the score block.
621 @cindex @code{\partial}
623 The piece starts with an anacrusis of one eighth.
627 The key is C minor: we have three flats.
631 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
632 c4 c8 d [es () d] c4 | d4 es8 d c4.
637 @cindex manual beaming
638 @cindex automatic beaming, turning off
639 We use explicit beaming. Since this is a song, we will turn automatic
640 beams off, and use explicit beaming where needed.
646 This ends the definition of @code{melody}. Note that there are no
647 semicolons after assignments at top level.
654 @cindex identifier assignment
655 @cindex syllables, entering
656 Another identifier assignment. This one is for the lyrics.
657 Lyrics are formed by syllables that have duration, and not by
658 notes. To make LilyPond parse words as syllables, switch it into
659 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
660 is a shorthand for @code{\sequential @{}.
663 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
664 ri- ver is flo- __ wing down to the sea.
668 @cindex extenders, lyric
669 @cindex hyphens, lyric
670 The syllables themselves are separated by spaces. You can get syllable
671 extenders by entering @code{__}, and centered hyphens with
672 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
673 in length (hence the @code{4}), and use a feature to align the
674 syllables to the music (which obviously isn't all quarter notes.)
677 accompaniment =\chords @{
682 We'll put chords over the music, to enter them, there is a special mode,
683 called @code{\chords}. There is a special mode (analogous
684 to @code{\lyrics} and @code{\notes} mode) where you can give the names
685 of the chords you want, instead of the notes comprising the chord.
691 There is no accompaniment during the anacrusis.
699 @cindex chord modifier
700 @cindex modifier, chord
701 A chord is started by the tonic of the chord. The
702 first one lasts a half note. An unadorned note creates a major
703 triad, while a minor triad is wanted. @code{3-} modifies the third to
704 be small. @code{7} modifies (adds) a seventh, which is small by default
705 to create the @code{f a c es} chord. Multiple modifiers must be
713 Some modifiers have predefined names, eg. @code{min} is the same as
714 @code{3-}, so @code{d-min} is a minor @code{d} chord.
717 c2:min f:min7 g:7^3.5 c:min @}
720 @cindex named modifier
722 A named modifier @code{min} and a normal modifier @code{7} do not have
723 to be separated by a dot. Tones from a chord are removed with chord
724 subtractions. Subtractions are started with a caret, and they are
725 also separated by dots. In this example, @code{g:7^3.5} produces a
726 minor seventh. The brace ends the sequential music.
733 We assemble the music in the @code{\score} block. Melody, lyrics and
734 accompaniment have to sound at the same time, so they should be
735 @code{\simultaneous}.
736 @cindex @code{\simultaneous}
742 Chord mode generates notes grouped in @code{\simultaneous} music. If
743 you remove the comment sign, you can see the chords in normal
744 notation: they will be printed as note heads on a separate
748 \context ChordNames \accompaniment
752 @cindex interpretation context
753 @cindex notation context
754 Normally, the notes that you enter are transformed into note heads.
755 The note heads alone make no sense, they need surrounding information:
756 a key signature, a clef, staff lines, etc. They need @emph{context}. In
757 LilyPond, these symbols are created by objects called `interpretation
758 contexts'. Interpretation contexts only exist during a run of
759 LilyPond. Interpretation contexts that are for printing music (as
760 opposed to playing music) are called `notation contexts'.
762 By default, LilyPond will create a Staff context for you. If you
763 removed the @code{%} sign in the previous line, you would see that
766 We don't want that default here, because we want chord names, not note heads.
767 An interpretation context can also created upon explicit request. The
768 keyword for such a request is @code{\context}. It takes two arguments.
769 The first is the name of an interpretation context. The name is a
770 string, it can be quoted with double quotes). The second argument is
771 the music that should be interpreted in this context. For the previous
772 line, we could have written @code{\context Staff \accompaniment}, and
779 @cindex @code{\addlyrics}
780 @cindex lyrics and melody, combining
781 @cindex combining lyrics and melody
783 The lyrics need to be aligned with the melody. This is done by
784 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
785 pieces of music (usually a melody and lyrics, in that order) and
786 aligns the syllables of the second piece under the notes of the
787 first piece. If you would reverse the order, the notes would be
788 aligned on the lyrics, which is not very useful. (Besides, it looks
792 \context Staff = mel @{
796 This is the argument of @code{\addlyrics}. We instantiate a
797 @code{Staff} context explicitly: should you chose to remove the comment
798 before the ``note heads'' version of the accompaniment, the
799 accompaniment will be on a nameless staff. The melody has to be on a
800 different staff as the accompaniment. This is accomplished by giving
801 the melody staff a different name.
804 \property Staff.noAutoBeaming = ##t
808 @cindex context variables
809 @cindex setting context variables
810 An interpretation context has variables that tune its behaviour. One of
811 the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
812 the boolean value @var{true}, LilyPond will not try to put automatic beaming
813 on the current staff.
817 @cindex accessinng Scheme
818 @cindex evaluating Scheme
821 LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
822 a language from the LISP family. You can learn more about Scheme at
823 @uref{http://www.scheme.org}.} to represent data throughout the whole
824 program. The hash-sign (@code{#}) accesses GUILE directly: the code
825 following the hash-sign is evaluated as Scheme. The boolean value
826 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
831 \property Staff.automaticMelismata = ##t
834 @cindex automaticMelismata
836 @cindex @code{\addlyrics} and slurs
837 Similarly, we don't want to print a syllable when there is
838 a slur. This sets up @code{\addlyrics} to not put lyrics under notes
839 while there is a slur.
846 Finally, we put the melody on the current staff. Note that the
847 @code{\property} directives and @code{\melody} are grouped in sequential
848 music, so the property settings are done before the melody is
852 \context Lyrics \text
855 The second argument of @code{\addlyrics} is the text. The text also
856 should not land on a Staff, but on a interpretation context for
857 syllables, extenders, hyphens etc. This context is called
864 This ends @code{\simultaneous}.
867 \midi @{ \tempo 4=72;@}
870 This makes the music go to a MIDI file. MIDI is great for checking
871 music you enter. You listen to the MIDI file: if you hear something
872 unexpected, it's probably a typing error. @code{\midi} starts an output
873 definition, a declaration that specifies how to output music analogous
874 to @code{\paper @{ @}}. You can specify the tempo using the
875 @code{\tempo} command, in this case the tempo of quarter notes is set to
879 \paper @{ linewidth = 10.0\cm; @}
882 We also want notation output. The linewidth is short so the piece
883 will be set in two lines.
892 @section More movements
894 You probably ran @file{ly2dvi} on the last example, and ended up with a
895 viewable @file{.dvi} file. However, between there are a few steps of
896 which LilyPond is only one. To enhance your understanding of what's
897 happening under the hood when you run @code{ly2dvi}, we explain what
900 @code{ly2dvi} is a program that calls a number of programs in sequence.
901 The first thing it does, is running LilyPond on the input file. After
902 some calculations, a @file{.tex} is produced. The contents
903 of this file are very low-level instructions.
905 For example, the following file (@file{layout.ly})
909 \header @{ title = "Two miniatures"; @}
911 #(set! point-and-click #t)
929 results in something like this@footnote{The titling in this manual was
930 not generated by ly2dvi, so details will differ.}
932 @center @strong{Two miniatures}
960 This file is produced by ly2dvi in a few stages, with the help of text
961 formatting tools. LilyPond produces two output files, @file{layout.tex}
962 and @file{layout-1.tex}. They both look like this:
966 \placebox@{-5 \outputscale @}%
967 @{ 8.7229 \outputscale @}%
968 @{\magfontWXGEomMMBo\char90 @}%
970 \placebox@{-4 \outputscale @}%
971 @{ 81.0647 \outputscale @}%
975 @file{ly2dvi} analyses the progress indication that LilyPond spews out,
976 and generates a file called @file{layout_ly1.tex}. This file contains
977 formatting instructions for the title and page layout. A fragment might
981 \geometry@{width=540.602362pt,headheight=2mm, ...
982 \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@} ...
984 \lilypondtitle@{foo@}%
990 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
991 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
992 is successful, this will produce a @file{.dvi} file, containing both the
993 titling and notes. @code{ly2dvi} completes its task by deleting the two
994 temporary files, leaving only @file{layout.dvi}.
996 Next, now we'll look at the examples line by line to explain new things.
1001 Lilypond and its language are still under development, and occasionally,
1002 details of the syntax are changed. This fragment indicates for which
1003 version the input file was written. When you compile this file, the
1004 version number will be checked, and you will get a warning when the file
1007 This version number is also used by the @code{convert-ly} program (See
1008 @ref{convert-ly}), which uses it update the file to the latest lily
1012 \header @{ title = "Two miniatures"; @}
1014 This sets the titling information for the entire file.
1017 #(set! point-and-click #t)
1020 This is Scheme code. It sets the variable @code{point-and-click} to the
1023 Editing input files can be quite complicated if you're working with
1024 large files: if you're digitizing existing music, you have to
1025 synchronize the .ly file, the sheet music on your lap and the sheet
1026 music on the screen. The point-and-click mechanism makes it easy to
1027 find the origin of an error in the .ly file: @footnote{This feature is
1028 presently only available on X-windows using patched versions of Xdvi and
1029 emacs} when you view the file with Xdvi and click on a note using
1030 control-mousebutton 1@footnote{If you're using a patched xdvik, the
1031 command is control-mousebutton-2}, your editor will jump to the spot
1032 where that note was entered.
1034 More information is in in @ref{Point and click}
1040 The @code{\score} blocks that follow in the file don't have
1041 @code{\paper} sections, so the settings of this block are substituted: A
1042 paper block, at top-level, i.e. not in a @code{\score} block sets the
1043 default page layout.
1046 linewidth = -1.0; @}
1051 The variable @code{linewidth} normally sets the length of the systems on
1052 the page. However, a negative value has a special meaning. If
1053 @code{linewidth} is less than 0, no line breaks are inserted into the
1054 score, and the spacing is set to natural length: a short phrase takes up
1055 little space, a longer phrase more space.
1059 \notes @{ c'4 d'4 @}
1062 In previous examples, notes were specified in relative octaves,
1063 i.e. each note was put in the octave that would put it closest to its
1064 predecessor. Besides relative, there is also absolute octave
1065 specification, and it is turned on by default. In this input mode, the
1066 central C is denoted by @code{c'}. Going down, you get @code{c}
1067 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} etc.
1069 When you're copying music from existing sheet music, relative octaves
1070 are probably the easiest to use: it's less typing work and errors are
1071 easily spotted. However, if you write LilyPond input, either by hand
1072 (ie. composing) or by computer, absolute octaves are probably less work.
1079 The @code{\header} is normally at the top of the file, where it sets
1080 values for the rest of the file. If you want to typeset different pieces
1081 from one file (for example, if there are multiple movements, or if
1082 you're making a etude-book), you can put different @code{\score} blocks
1083 into the input file. ly2dvi will assemble all LilyPond output files into
1084 a big document. The contents of \header blocks specified within each
1085 score, are used for the titling of each movement.
1090 For example, the Opus number is put at the right, and the piece string
1091 will be at the left.
1095 @node A piano excerpt
1096 @section A piano excerpt
1098 Our third subject is a piece of piano music. The fragment in the input
1099 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1100 Sammartini. It was composed around 1740. It's in the source package
1101 under the name @file{sammartini.ly}.
1104 \include "paper16.ly";
1106 stemdown = \property Voice.Stem \override #'direction = #-1
1107 stemup = \property Voice.Stem \override #'direction = #1
1108 stemboth = \property Voice.Stem \revert #'direction
1110 viola = \notes \relative c' \context Voice = viola {
1111 <c4-\f-\arpeggio g' c>
1117 oboes = \notes \relative c'' \context Voice = oboe {
1118 \stemup s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1119 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
1121 { \times 2/3 { a8 g c } \! c2 }
1122 \context Voice = oboeTwo {
1125 \property Grace.Stem \override #'direction = #-1
1130 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1131 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1132 [<c16( e> < )e8. g>] <c8 e,>
1135 hoomPah = \repeat unfold 8
1136 \notes \transpose c' { c8 \stemdown c'8 \stemup }
1138 bassvoices = \notes \relative c' {
1140 \autochange Staff \hoomPah
1141 \translator Staff = down
1142 \stemdown [c8 c'8] r4
1144 < {\stemup r2 <e4 c'> <c8 g'> }
1145 \context Voice = reallyLow {\stemdown g2 ~ | g4 c8 } >
1149 \context PianoStaff \notes <
1150 \context Staff = up < \time 2/2;
1154 \context Staff = down < \time 2/2; \clef bass;
1161 linewidth = 15.0 \cm; }
1165 If it looks like incomprehensible gibberish to you, then you are right.
1166 This example has been doctored to have as many quirks as possible.
1169 stemdown = \property Voice.Stem \override #'direction = #-1
1172 As you can see, this example features more voices on one staff. To make
1173 room for those voices, their notes have to be stemmed in opposite
1174 directions. These are the commands to make that happen.
1176 The symbols that are printed, are internally represented by so-called
1177 Graphical Objects (or more colloquially: Grobs). These statements
1178 concern the grob called `Stem'. Each grob is described by a bunch of
1179 settings. These setting determine the fonts, offsets, sub-routines to be
1180 called on the grob, etc. The initial values of these settings are set
1181 in the Scheme file @file{scm/grob-description.scm}.
1183 This statement adds a the setting for all Stem grobs in the current
1184 Voice: @code{direction} is set to @code{-1}, which encodes down. The
1185 setting remains in effect until it is reverted.
1188 \property Voice.Stem \revert #'direction
1191 This statement reverts the old setting. If you do this, the effect of a
1192 @code{\stemdown} or @code{\stemup} is neutralised.
1194 @code{\override} and @code{\revert} function like a stack: you can push
1195 values onto the grob-setting-stack with @code{\override} and you pop
1196 them with @code{\revert}.
1198 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1199 with some more often used formatting instructions, but to explain how it
1200 works, we wrote our own here. Of course, you should use predefined
1201 identifiers like these if possible: then you will be affected less by
1202 the implementation changes we occasionally make.
1205 viola = \notes \relative c' \context Voice = viola @{
1207 In this example, you can see multiple parts on a staff. Each part is
1208 associated with one notation context. This notation context handles
1209 stems and dynamics (among others). The name of this context is
1210 @code{Voice}. For each part we have to make sure that there is
1211 precisely one @code{Voice} context, so we give it an unique name
1215 <c4-\f-\arpeggio g' c>
1217 The delimiters @code{<} and @code{>} are shorthands for
1218 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1219 @code{<} and @code{>} is a chord.
1226 @code{\f} places a forte symbol under the chord. The forte applies to
1227 the whole chord, but the syntax requires that commands like forte and
1228 arpeggio are attached to a note, so here we attach them to the first
1231 @code{\arpeggio} draws an vertical wavy line before the chord,
1232 signifying an arpeggio.
1242 Relative octaves work a little differently with chords. The starting
1243 point for the note following a chord is the first note of the chord. So
1244 the @code{g} gets an octave up quote: it is a fifth above the starting
1245 note of the previous chord (the central C).
1250 @code{s} is a spacer rest. It does not print anything, but it does have
1251 the duration of a rest. It is useful for filling up voices that
1252 temporarily don't play. In this case, the viola doesn't come until one
1253 and a half measure later.
1256 oboes = \notes \relative c'' \context Voice = oboe @{
1258 Now comes a part for two oboes. They play homophonically, so we
1259 print the notes as one voice that makes chords. Again, we insure that
1260 these notes are indeed processed by precisely one context with
1263 \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1265 @code{\stemup} is a reference to the @code{\property \override} command
1268 \grace <e8 g> < d4 f> <c2 e>
1270 @cindex @code{\grace}
1274 @code{\grace} introduces grace notes. It takes one argument, in this
1278 The slur started on the @code{e} of the chord
1279 will be attached to the next note.@footnote{LilyPond will squirm
1280 about unended Slurs. In this case, you can ignore the warning}.
1287 Tuplets are made with the @code{\times} keyword. It takes two
1288 arguments: a fraction and a piece of music. The duration of the piece
1289 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1290 of their notated duration, so in this case the fraction is 2/3.
1292 @{ <d8 \< f> <e g> <f a> @}
1294 The piece of music to be `tripletted' is sequential music containing
1295 three notes. On the first chord, a crescendo is started with
1296 @code{\<}. To be precise, the crescendo start is syntactically attached
1297 to the preceding note, the @code{d}.
1306 At this point, the homophonic music splits into two rhythmically
1307 different parts. We can't use a sequence of chords to enter this, so
1308 we make a `chord' of sequences to do it. We start with the upper
1309 voice, which continues with upward stems:
1311 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1316 The crescendo is ended at the half note by the escaped exclamation
1319 \context Voice = oboeTwo @{
1322 We can't share stems with the other voice, so we have to create a new
1323 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1324 it from the other context. Stems go down in this voice.
1328 @cindex Grace context
1329 When a grace section is processed, a @code{Grace} context is
1330 created. This context acts like a miniature score of its own. It has
1331 its own time bookkeeping, and you can make notes, beams, slurs
1332 etc. Here we fiddle with a property and make a beam. The argument of
1333 @code{\grace} is sequential music.
1336 \property Grace.Stem \override #'direction = #-1
1340 Normally, grace notes are always stem up, but in this case, the upper
1341 voice interferes. We set the stems down here.
1343 As far as relative mode is concerned, the previous note is the
1344 @code{c'''2} of the upper voice, so we have to go an octave down for
1351 This ends the two-part section.
1354 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1359 @code{\stemBoth} ends the forced stem directions. From here, stems are
1360 positioned as if it were single part music.
1362 The bass has a little hoom-pah melody to demonstrate parts switching
1363 between staffs. Since it is repetitive, we use repeats:
1365 hoomPah = \repeat unfold 8
1367 @cindex unfolded @code{\repeat}
1368 This repeat print the following sequence notes eight times.
1370 \notes \transpose c' @{
1373 @cindex relative mode and transposing
1375 Transposing can be done with @code{\transpose}. It takes two arguments;
1376 the first specifies what central C should be transposed to. The second
1377 is the to-be-transposed music. As you can see, in this case, the
1378 transposition is a no-op, as central C stay at central C.
1380 The purpose of this no-op is circumventing relative mode. Relative mode
1381 can not be used together with transposition, so @code{\relative} will
1382 leave the contents of @code{\hoomPah} alone. We can use it without
1383 having to worry about getting the motive in a wrong octave.
1385 bassvoices = \notes \relative c' @{
1387 \autochange Staff \hoomPah
1389 @cindex staff switch, automatic
1390 @cindex cross staff voice, automatic
1391 @cindex @code{\autochange}
1393 Voices can switch between staffs. The easiest way to get this, is to use
1394 @code{\autochange}. This command looks at the pitch of each note, and if
1395 necessary, will cross to the other staff. For this to work, the two
1396 staffs must be called @code{"up"} and @code{"down"}.
1398 \translator Staff = down
1400 @cindex staff switch
1401 @cindex cross staff voice
1402 The rest of this melody must be in the lower staff, so we do a manual
1407 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1411 After skipping some lines, we see @code{~}. This mark makes ties.
1415 A special context is needed to get cross staff beaming right. This
1416 context is called @code{PianoStaff}.
1418 \context Staff = bottom < \time 2/2; \clef bass;
1420 The bottom staff must have a different clef.
1424 To make some more room on the line, the first (in this case the only)
1425 line is not indented. The line still looks very cramped, but that is due
1426 to the page layout of this document.
1431 * arpeggio, glissando,
1433 * \apply, \outputproperty, \translator @{@}, \molecule hacking.
1435 * font-size, cadenza. rhythmic staff, multi-stanza.
1438 * Orchestral: demonstrate Hara-Kiri, part combining, part extraction,
1439 scores, transposition, instrument names,
1443 @node end of tutorial
1446 That's all folks. From here, you can either try fiddling with input
1447 files, or you can read the reference manual.