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 yourself,
37 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 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 will see this
111 \notes { c'4 e'4 g'4 }
115 along with some buttons in a window.
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 cheapers need the
136 intervention of GhostScript, a PostScript emulator that runs 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
140 following command will print the file
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 two different routes: firstly, you can add titling to the
149 output. This is done by a separate program called ly2dvi: this program
150 first calls LilyPond to process the @file{.ly} file, and then runs
151 @TeX{} on it to produce a @file{.dvi} file with proper margin settings
154 @cindex titles, adding
160 After some disk-activity, you should end up with a @file{.dvi} file.
162 Secondly, you can generate PostScript directly. This is not very useful
163 currently, but here goes:
164 @cindex PostScript output
166 lilypond -f ps test.ly
169 [treat FAQs here, eg. about env vars.]
172 @unnumberedsubsec Windows
178 @section The first tune
181 To demonstrate what LilyPond input looks like, we start off with a
182 full-fledged, yet simple example. It is a convoluted version
183 of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
184 is included in the distribution as @file{menuet.ly}.
185 @cindex Bach, Johann Sebastian
188 % lines preceded by a percent are comments which
189 % are ignored by Lilypond.
190 \include "paper16.ly"
193 \relative c'' \sequential{
198 d4 g,8 a b c d4 g, g |
199 e'4 c8 d e fis g4 g, g |
200 c4 d8()c b a( )b4 c8 b a g |
201 a4 [b8 a] [g fis] g2. |
206 g4 e8 fis g d cis4 b8 cis a4 |
207 a8-. b-. cis-. d-. e-. fis-.
214 % standard settings are too wide for a book
215 linewidth = 14.0 \cm;
220 We will analyse the input, line by line.
222 % lines preceded by a percent are comments which
223 % are ignored by Lilypond.
225 The percent sign, @code{%}, introduces a line comment. If you want to
226 make larger comments, you can use block comments. These are delimited
227 by @code{%@{} and @code{%@}}
229 @cindex block comment
234 \include "paper16.ly"
237 @cindex @code{\include}
238 @cindex point, printer's
239 @cindex staff size setting
240 By default, LilyPond will use definitions for a staff that is 20
241 point@footnote {A point is the standard measure of length for printing;
242 one point is 1/72.27 inch. [TODO: mm vs. pt]} high. We want smaller
243 output (16 point staff height), so we must import the settings for that
244 size, which is done here.
250 A lilypond file combines music with directions for outputting that
251 music. The music is combined with the output directions by putting
252 them into a @code{\score} block.
258 This makes LilyPond ready for accepting notes.
265 @cindex octaves, choosing
267 As we will see, pitches are combinations of octave, note name and
268 chromatic alteration. In this scheme, the octave is indicated by
269 using raised quotes (@code{'}) and ``lowered'' quotes (commas:
270 @code{,}). The central C is denoted by @code{c'}. The C one octave
271 higher is @code{c''}. One and two octaves below the central C is
272 denoted by @code{c} and @code{c,} respectively.
275 For pitches in a long piece you might have to type many quotes. To
276 remedy this, LilyPond has a ``relative'' octave entry mode. In this
277 mode, octaves of notes without quotes are chosen such that a note is
278 as close as possible (graphically, on the staff) to the the preceding
279 note. If you add a high-quote an extra octave is added. The lowered
280 quote (a comma) will subtract an extra octave. Because the first note
281 has no predecessor, you have to give the (absolute) pitch of the note
288 What follows is sequential music, i.e.,
289 @cindex sequential music
290 notes that are to be played and printed after each other.
296 @cindex time signature, setting
298 This command changes the time signature of the current piece: a 3/4
299 sign is printed. This command is also used to generate bar lines in
306 @cindex key signature, setting
308 This command changes the current key signature to G-major. Although this
309 command comes after the @code{\time} command, in the output, the key
310 signature comes before the time signature: LilyPond knows about music
311 typesetting conventions.
317 This command tells LilyPond that the following piece of music must be
318 played twice. The first argument indicates the type of repeat. In this
319 case, @code{"volta"} means that volta brackets are be used for
320 alternatives---if there were any.
326 The subject of the repeat is again sequential music. Since
327 @code{\sequential} is such a common construct, a shorthand is provided:
328 just leave off @code{\sequential}, and the result is the same.
334 This is a note with pitch @code{d} (determined up to octaves). The
335 relative music was started with a @code{c''}, so the real pitch of this
336 note is @code{d''}. The @code{4} designates the duration of the note
337 (it is a quarter note).
343 These are notes with pitch @code{a} and @code{b}. Because their
344 duration is the same as the @code{g}, there is no need to enter the
345 duration (You may enter it anyway, e.g. @code{a4 b4})
353 @cindex errors, finding
354 Three more notes. The @code{|} character is a `bar check'. When
355 processing the music, LilyPond will verify that bar checks are found at
356 the start of a measure. This can help you track down errors.
358 @cindex alteration, chromatic
359 @cindex chromatic alteration
360 So far, no notes were chromatically altered. Here is the first one
361 that is: @code{fis}. Lilypond by default uses Dutch note names, and
362 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
363 sharp sign in the output. The program keeps track of key signatures,
364 and will only print accidentals if they are needed.
370 LilyPond guesses were beams can be added to eighth and shorter notes.
371 In this case, a beam over 4 eighths is added.
374 c4 d8( )c b a( )b4 c8 b a g |
377 The next line shows how to make a slur: the beginning and ending note
378 of the slur is marked with an opening and closing parenthesis
379 respectively. In the line shown above, this is done for two slurs.
380 Slur markers (parentheses) are put between the slurred notes.
386 Automatic beaming can be overridden by inserting beam marks
387 (brackets). Brackets are put around the notes you want beamed.
393 @cindex augmentation dot
395 A duration with augmentation dot is notated
396 with the duration number followed by a period.
402 This ends the sequential music to be repeated. LilyPond will typeset
409 This line shows that Lily will print an accidental if that is
410 needed: the first C sharp of the bar will be printed with an accidental,
411 the second one without.
414 a8-. b-. cis-. d-. e-. fis-.
418 You can enter articulation signs either in a verbose form using a
419 shorthand. Here we demonstrate the shorthand: it is formed by a dash
420 and the character for the articulation to use, e.g. @code{-.} for
421 staccato as shown above.
428 Rests are denoted by the special notename @code{r}.
434 All articulations have a verbose form, like @code{\fermata}. The
435 command @code{\fermata} is not part of the core of the language (most
436 of the other discussed elements are), but it is a shorthand for a more
437 complicated description of a fermata. @code{\fermata} names that
438 description and is therefore called an identifier.
440 @cindex @code{\fermata}
455 This specifies a conversion from music to notation output. Most of
456 the details of this conversions (font sizes, dimensions, etc.) have
457 been taken care of, but to fit the output in this document, it has
458 to be smaller. We do this by setting the line width to 14 centimeters
459 (approximately 5.5 inches).
465 The last brace ends the @code{\score} block.
470 @node Lyrics and chords
471 @section Lyrics and chords
473 In this section we show how to typeset a song.@footnote{The author would
474 welcome information about the origin of this song.}. This file is
475 included as @file{flowing.ly}.
479 title = "The river is flowing";
480 composer = "Traditional (?)";
482 \include "paper16.ly"
483 melody = \notes \relative c' @{
487 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
488 c4 c8 d [es () d] c4 | d4 es8 d c4.
493 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
494 ri -- ver is flo -- wing down to the sea.
497 accompaniment =\chords @{
499 c2:3- f:3-.7 d:min es4 c8:min r8
500 c2:min f:min7 g:7^3.5 c:min @}
505 \context ChordNames \accompaniment
508 \context Staff = mel @{
509 \property Staff.noAutoBeaming = ##t
510 \property Staff.automaticMelismata = ##t
513 \context Lyrics \text
515 \midi @{ \tempo 4=72;@}
516 \paper @{ linewidth = 10.0\cm; @}
521 The result would look this@footnote{The titling and font size shown
522 may differ, since the titling in this document is not generated by
525 @center @strong{The river is flowing}
530 title = "The river is flowing";
531 composer = "Traditional (?)";
533 \include "paper16.ly"
534 melody = \notes \relative c' {
538 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
539 c4 c8 d [es () d] c4 | d4 es8 d c4.
544 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
545 ri -- ver is flo -- wing down to the sea.
548 accompaniment =\chords {
550 c2:3- f:3-.7 d:min es4 c8:min r8
551 c2:min f:min7 g:7^3.5 c:min }
556 \context ChordNames \accompaniment
559 \context Staff = mel {
560 \property Staff.noAutoBeaming = ##t
561 \property Staff.automaticMelismata = ##t
564 \context Lyrics \text
566 \midi { \tempo 4=72;}
567 \paper { linewidth = 10.0\cm; }
571 Again, we will dissect the file line by line.
577 @cindex @code{\header}
578 Information about the music you are about to typeset goes into a
579 @code{\header} block. The information in this block is not used by
580 LilyPond, but it is passed into the output. @file{ly2dvi} uses this
581 information to print titles above the music.
584 title = "The river is flowing";
585 composer = "Traditional (?)";
588 @cindex identifier assignment
589 the @code{\header} block contains assignments. An assignment starts
590 with a string. (which is unquoted, in this case). Then comes the
591 equal sign. After the equal sign comes the expression you
592 want to store. In this case, you want to put in strings. The
593 information has to be quoted here, because it contains spaces. Each
594 assignment is finished with a semicolon.
597 \include "paper16.ly"
600 Smaller size for inclusion in a book.
603 melody = \notes \relative c' @{
606 The structure of the file will be the same as the previous one, a
607 @code{\score} block with music in it. To keep things readable, we will
608 give names to the different parts of music, and use the names to
609 construct the music within the score block.
615 @cindex @code{\partial}
617 The piece starts with an anacrusis of one eighth.
621 The key is C minor: we have three flats.
625 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
626 c4 c8 d [es () d] c4 | d4 es8 d c4.
631 @cindex manual beaming
632 @cindex automatic beaming, turning off
633 We use explicit beaming. Since this is a song, we will turn automatic
634 beams off, and use explicit beaming where needed.
640 This ends the definition of @code{melody}. Note that there are no
641 semicolons after assignments at top level.
648 @cindex identifier assignment
649 @cindex syllables, entering
650 Another identifier assignment. This one is for the lyrics.
651 Lyrics are formed by syllables that have duration, and not by
652 notes. To make LilyPond parse words as syllables, switch it into
653 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
654 is a shorthand for @code{\sequential @{}.
657 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
658 ri- ver is flo- __ wing down to the sea.
662 @cindex extenders, lyric
663 @cindex hyphens, lyric
664 The syllables themselves are separated by spaces. You can get syllable
665 extenders by entering @code{__}, and centered hyphens with
666 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
667 in length (hence the @code{4}), and use a feature to align the
668 syllables to the music (which obviously isn't all quarter notes.)
671 accompaniment =\chords @{
676 We'll put chords over the music, to enter them, there is a special mode,
677 called @code{\chords}. There is a special mode (analogous
678 to @code{\lyrics} and @code{\notes} mode) where you can give the names
679 of the chords you want, instead of the notes comprising the chord.
685 There is no accompaniment during the anacrusis.
693 @cindex chord modifier
694 @cindex modifier, chord
695 A chord is started by the tonic of the chord. The
696 first one lasts a half note. An unadorned note creates a major
697 triad, while a minor triad is wanted. @code{3-} modifies the third to
698 be small. @code{7} modifies (adds) a seventh, which is small by default
699 to create the @code{f a c es} chord. Multiple modifiers must be
707 Some modifiers have predefined names, eg. @code{min} is the same as
708 @code{3-}, so @code{d-min} is a minor @code{d} chord.
711 c2:min f:min7 g:7^3.5 c:min @}
714 @cindex named modifier
716 A named modifier @code{min} and a normal modifier @code{7} do not have
717 to be separated by a dot. Tones from a chord are removed with chord
718 subtractions. Subtractions are started with a caret, and they are
719 also separated by dots. In this example, @code{g:7^3.5} produces a
720 minor seventh. The brace ends the sequential music.
727 We assemble the music in the @code{\score} block. Melody, lyrics and
728 accompaniment have to sound at the same time, so they should be
729 @code{\simultaneous}.
730 @cindex @code{\simultaneous}
736 Chord mode generates notes grouped in @code{\simultaneous} music. If
737 you remove the comment sign, you can see the chords in normal
738 notation: they will be printed as note heads on a separate
742 \context ChordNames \accompaniment
746 @cindex interpretation context
747 @cindex notation context
748 Normally, the notes that you enter are transformed into note heads.
749 The note heads alone make no sense, they need surrounding information:
750 a key signature, a clef, staff lines, etc. They need @emph{context}. In
751 LilyPond, these symbols are created by objects called `interpretation
752 contexts'. Interpretation contexts only exist during a run of
753 LilyPond. Interpretation contexts that are for printing music (as
754 opposed to playing music) are called `notation contexts'.
756 By default, LilyPond will create a Staff context for you. If you
757 removed the @code{%} sign in the previous line, you would see that
760 We don't want that default here, because we want chord names, not note heads.
761 An interpretation context can also created upon explicit request. The
762 keyword for such a request is @code{\context}. It takes two arguments.
763 The first is the name of an interpretation context. The name is a
764 string, it can be quoted with double quotes). The second argument is
765 the music that should be interpreted in this context. For the previous
766 line, we could have written @code{\context Staff \accompaniment}, and
773 @cindex @code{\addlyrics}
774 @cindex lyrics and melody, combining
775 @cindex combining lyrics and melody
777 The lyrics need to be aligned with the melody. This is done by
778 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
779 pieces of music (usually a melody and lyrics, in that order) and
780 aligns the syllables of the second piece under the notes of the
781 first piece. If you would reverse the order, the notes would be
782 aligned on the lyrics, which is not very useful. (Besides, it looks
786 \context Staff = mel @{
790 This is the argument of @code{\addlyrics}. We instantiate a
791 @code{Staff} context explicitly: should you chose to remove the comment
792 before the ``note heads'' version of the accompaniment, the
793 accompaniment will be on a nameless staff. The melody has to be on a
794 different staff as the accompaniment. This is accomplished by giving
795 the melody staff a different name.
798 \property Staff.noAutoBeaming = ##t
802 @cindex context variables
803 @cindex setting context variables
804 An interpretation context has variables that tune its behaviour. One of
805 the variables is @code{noAutoBeaming}. If set to @code{##t}, which is
806 the boolean value @var{true}, LilyPond will not try to put automatic beaming
807 on the current staff.
811 @cindex accessinng Scheme
812 @cindex evaluating Scheme
815 LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
816 a language from the LISP family. You can learn more about Scheme at
817 @uref{http://www.scheme.org}.} to represent data throughout the whole
818 program. The hash-sign (@code{#}) accesses GUILE directly: the code
819 following the hash-sign is evaluated as Scheme. The boolean value
820 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
825 \property Staff.automaticMelismata = ##t
828 @cindex automaticMelismata
830 @cindex @code{\addlyrics} and slurs
831 Similarly, we don't want to print a syllable when there is
832 a slur. This sets up @code{\addlyrics} to not put lyrics under notes
833 while there is a slur.
840 Finally, we put the melody on the current staff. Note that the
841 @code{\property} directives and @code{\melody} are grouped in sequential
842 music, so the property settings are done before the melody is
846 \context Lyrics \text
849 The second argument of @code{\addlyrics} is the text. The text also
850 should not land on a Staff, but on a interpretation context for
851 syllables, extenders, hyphens etc. This context is called
858 This ends @code{\simultaneous}.
861 \midi @{ \tempo 4=72;@}
864 This makes the music go to a MIDI file. MIDI is great for checking
865 music you enter. You listen to the MIDI file: if you hear something
866 unexpected, it's probably a typing error. @code{\midi} starts an output
867 definition, a declaration that specifies how to output music analogous
868 to @code{\paper @{ @}}. You can specify the tempo using the
869 @code{\tempo} command, in this case the tempo of quarter notes is set to
873 \paper @{ linewidth = 10.0\cm; @}
876 We also want notation output. The linewidth is short so the piece
877 will be set in two lines.
886 @section More movements
888 You probably ran @file{ly2dvi} on the last example, and ended up with a
889 viewable @file{.dvi} file. However, between there are a few steps of
890 which LilyPond is only one. To enhance your understanding of what's
891 happening under the hood when you run @code{ly2dvi}, we explain what
894 @code{ly2dvi} is a program that calls a number of programs in sequence.
895 The first thing it does, is running LilyPond on the input file. After
896 some calculations, a @file{.tex} is produced. The contents
897 of this file are very low-level instructions.
899 For example, the following file (@file{layout.ly})
903 \header @{ title = "Two miniatures"; @}
905 #(set! point-and-click #t)
923 results in something like this@footnote{The titling in this manual was
924 not generated by ly2dvi, so details will differ.}
926 @center @strong{Two miniatures}
954 This file is produced by ly2dvi in a few stages, with the help of text
955 formatting tools. LilyPond produces two output files, @file{layout.tex}
956 and @file{layout-1.tex}. They both look like this:
960 \placebox@{-5 \outputscale @}%
961 @{ 8.7229 \outputscale @}%
962 @{\magfontWXGEomMMBo\char90 @}%
964 \placebox@{-4 \outputscale @}%
965 @{ 81.0647 \outputscale @}%
969 @file{ly2dvi} analyses the progress indication that LilyPond spews out,
970 and generates a file called @file{layout_ly1.tex}. This file contains
971 formatting instructions for the title and page layout. A fragment might
975 \geometry@{width=540.602362pt,headheight=2mm, ...
976 \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@} ...
978 \lilypondtitle@{foo@}%
984 @file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
985 built on top of @TeX{}. It's very popular in the academic world. If LaTeX
986 is successful, this will produce a @file{.dvi} file, containing both the
987 titling and notes. @code{ly2dvi} completes its task by deleting the two
988 temporary files, leaving only @file{layout.dvi}.
990 Next, now we'll look at the examples line by line to explain new things.
995 Lilypond and its language are still under development, and occasionally,
996 details of the syntax are changed. This fragment indicates for which
997 version the input file was written. When you compile this file, the
998 version number will be checked, and you will get a warning when the file
1001 This version number is also used by the @code{convert-ly} program (See
1002 @ref{convert-ly}), which uses it update the file to the latest lily
1006 \header @{ title = "Two miniatures"; @}
1008 This sets the titling information for the entire file.
1011 #(set! point-and-click #t)
1014 This is Scheme code. It sets the variable @code{point-and-click} to the
1017 Editing input files can be quite complicated if you're working with
1018 large files: if you're digitizing existing music, you have to
1019 synchronize the .ly file, the sheet music on your lap and the sheet
1020 music on the screen. The point-and-click mechanism makes it easy to
1021 find the origin of an error in the .ly file: @footnote{This feature is
1022 presently only available on X-windows using patched versions of Xdvi and
1023 emacs} when you view the file with Xdvi and click on a note using
1024 control-mousebutton 1@footnote{If you're using a patched xdvik, the
1025 command is control-mousebutton-2}, your editor will jump to the spot
1026 where that note was entered.
1028 More information is in in @ref{Point and click}
1034 The @code{\score} blocks that follow in the file don't have
1035 @code{\paper} sections, so the settings of this block are substituted: A
1036 paper block, at top-level, i.e. not in a @code{\score} block sets the
1037 default page layout.
1040 linewidth = -1.0; @}
1045 The variable @code{linewidth} normally sets the length of the systems on
1046 the page. However, a negative value has a special meaning. If
1047 @code{linewidth} is less than 0, no line breaks are inserted into the
1048 score, and the spacing is set to natural length: a short phrase takes up
1049 little space, a longer phrase more space.
1053 \notes @{ c'4 d'4 @}
1056 In previous examples, notes were specified in relative octaves,
1057 i.e. each note was put in the octave that would put it closest to its
1058 predecessor. Besides relative, there is also absolute octave
1059 specification, and it is turned on by default. In this input mode, the
1060 central C is denoted by @code{c'}. Going down, you get @code{c}
1061 @code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} etc.
1063 When you're copying music from existing sheet music, relative octaves
1064 are probably the easiest to use: it's less typing work and errors are
1065 easily spotted. However, if you write LilyPond input, either by hand
1066 (ie. composing) or by computer, absolute octaves are probably less work.
1073 The @code{\header} is normally at the top of the file, where it sets
1074 values for the rest of the file. If you want to typeset different pieces
1075 from one file (for example, if there are multiple movements, or if
1076 you're making a etude-book), you can put different @code{\score} blocks
1077 into the input file. ly2dvi will assemble all LilyPond output files into
1078 a big document. The contents of \header blocks specified within each
1079 score, are used for the titling of each movement.
1084 For example, the Opus number is put at the right, and the piece string
1085 will be at the left.
1089 @node A piano excerpt
1090 @section A piano excerpt
1092 Our third subject is a piece of piano music. The fragment in the input
1093 file is a piano reduction of the G major Sinfonia by Giovanni Battista
1094 Sammartini. It was composed around 1740. It's in the source package
1095 under the name @file{sammartini.ly}.
1098 \include "paper16.ly";
1100 stemdown = \property Voice.Stem \override #'direction = #-1
1101 stemup = \property Voice.Stem \override #'direction = #1
1102 stemboth = \property Voice.Stem \revert #'direction
1104 viola = \notes \relative c' \context Voice = viola {
1105 <c4-\f-\arpeggio g' c>
1111 oboes = \notes \relative c'' \context Voice = oboe {
1112 \stemup s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
1113 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
1115 { \times 2/3 { a8 g c } \! c2 }
1116 \context Voice = oboeTwo {
1119 \property Grace.Stem \override #'direction = #-1
1124 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1125 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
1126 [<c16( e> < )e8. g>] <c8 e,>
1129 hoomPah = \repeat unfold 8
1130 \notes \transpose c' { c8 \stemdown c'8 \stemup }
1132 bassvoices = \notes \relative c' {
1134 \autochange Staff \hoomPah
1135 \translator Staff = down
1136 \stemdown [c8 c'8] r4
1138 < {\stemup r2 <e4 c'> <c8 g'> }
1139 \context Voice = reallyLow {\stemdown g2 ~ | g4 c8 } >
1143 \context PianoStaff \notes <
1144 \context Staff = up < \time 2/2;
1148 \context Staff = down < \time 2/2; \clef bass;
1155 linewidth = 15.0 \cm; }
1159 If it looks like incomprehensible gibberish to you, then you are right.
1160 This example has been doctored to have as many quirks as possible.
1163 stemdown = \property Voice.Stem \override #'direction = #-1
1166 As you can see, this example features more voices on one staff. To make
1167 room for those voices, their notes have to be stemmed in opposite
1168 directions. These are the commands to make that happen.
1170 The symbols that are printed, are internally represented by so-called
1171 Graphical Objects (or more colloquially: Grobs). These statements
1172 concern the grob called `Stem'. Each grob is described by a bunch of
1173 settings. These setting determine the fonts, offsets, sub-routines to be
1174 called on the grob, etc. The initial values of these settings are set
1175 in the Scheme file @file{scm/grob-description.scm}.
1177 This statement adds a the setting for all Stem grobs in the current
1178 Voice: @code{direction} is set to @code{-1}, which encodes down. The
1179 setting remains in effect until it is reverted.
1182 \property Voice.Stem \revert #'direction
1185 This statement reverts the old setting. If you do this, the effect of a
1186 @code{\stemdown} or @code{\stemup} is neutralised.
1188 @code{\override} and @code{\revert} function like a stack: you can push
1189 values onto the grob-setting-stack with @code{\override} and you pop
1190 them with @code{\revert}.
1192 LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
1193 with some more often used formatting instructions, but to explain how it
1194 works, we wrote our own here. Of course, you should use predefined
1195 identifiers like these if possible: then you will be affected less by
1196 the implementation changes we occasionally make.
1199 viola = \notes \relative c' \context Voice = viola @{
1201 In this example, you can see multiple parts on a staff. Each part is
1202 associated with one notation context. This notation context handles
1203 stems and dynamics (among others). The name of this context is
1204 @code{Voice}. For each part we have to make sure that there is
1205 precisely one @code{Voice} context, so we give it an unique name
1209 <c4-\f-\arpeggio g' c>
1211 The delimiters @code{<} and @code{>} are shorthands for
1212 @code{\simultaneous @{} and @code{@}}. The expression enclosed in
1213 @code{<} and @code{>} is a chord.
1220 @code{\f} places a forte symbol under the chord. The forte applies to
1221 the whole chord, but the syntax requires that commands like forte and
1222 arpeggio are attached to a note, so here we attach them to the first
1225 @code{\arpeggio} draws an vertical wavy line before the chord,
1226 signifying an arpeggio.
1236 Relative octaves work a little differently with chords. The starting
1237 point for the note following a chord is the first note of the chord. So
1238 the @code{g} gets an octave up quote: it is a fifth above the starting
1239 note of the previous chord (the central C).
1244 @code{s} is a spacer rest. It does not print anything, but it does have
1245 the duration of a rest. It is useful for filling up voices that
1246 temporarily don't play. In this case, the viola doesn't come until one
1247 and a half measure later.
1250 oboes = \notes \relative c'' \context Voice = oboe @{
1252 Now comes a part for two oboes. They play homophonically, so we
1253 print the notes as one voice that makes chords. Again, we insure that
1254 these notes are indeed processed by precisely one context with
1257 \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
1259 @code{\stemup} is a reference to the @code{\property \override} command
1262 \grace <e8 g> < d4 f> <c2 e>
1264 @cindex @code{\grace}
1268 @code{\grace} introduces grace notes. It takes one argument, in this
1272 The slur started on the @code{e} of the chord
1273 will be attached to the next note.@footnote{LilyPond will squirm
1274 about unended Slurs. In this case, you can ignore the warning}.
1281 Tuplets are made with the @code{\times} keyword. It takes two
1282 arguments: a fraction and a piece of music. The duration of the piece
1283 of music is multiplied by the fraction. Triplets make notes occupy 2/3
1284 of their notated duration, so in this case the fraction is 2/3.
1286 @{ <d8 \< f> <e g> <f a> @}
1288 The piece of music to be `tripletted' is sequential music containing
1289 three notes. On the first chord, a crescendo is started with
1290 @code{\<}. To be precise, the crescendo start is syntactically attached
1291 to the preceding note, the @code{d}.
1300 At this point, the homophonic music splits into two rhythmically
1301 different parts. We can't use a sequence of chords to enter this, so
1302 we make a `chord' of sequences to do it. We start with the upper
1303 voice, which continues with upward stems:
1305 @{ \times 2/3 @{ a8 g c @} \! c2 @}
1310 The crescendo is ended at the half note by the escaped exclamation
1313 \context Voice = oboeTwo @{
1316 We can't share stems with the other voice, so we have to create a new
1317 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
1318 it from the other context. Stems go down in this voice.
1322 @cindex Grace context
1323 When a grace section is processed, a @code{Grace} context is
1324 created. This context acts like a miniature score of its own. It has
1325 its own time bookkeeping, and you can make notes, beams, slurs
1326 etc. Here we fiddle with a property and make a beam. The argument of
1327 @code{\grace} is sequential music.
1330 \property Grace.Stem \override #'direction = #-1
1334 Normally, grace notes are always stem up, but in this case, the upper
1335 voice interferes. We set the stems down here.
1337 As far as relative mode is concerned, the previous note is the
1338 @code{c'''2} of the upper voice, so we have to go an octave down for
1345 This ends the two-part section.
1348 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
1353 @code{\stemBoth} ends the forced stem directions. From here, stems are
1354 positioned as if it were single part music.
1356 The bass has a little hoom-pah melody to demonstrate parts switching
1357 between staffs. Since it is repetitive, we use repeats:
1359 hoomPah = \repeat unfold 8
1361 @cindex unfolded @code{\repeat}
1362 This repeat print the following sequence notes eight times.
1364 \notes \transpose c' @{
1367 @cindex relative mode and transposing
1369 Transposing can be done with @code{\transpose}. It takes two arguments;
1370 the first specifies what central C should be transposed to. The second
1371 is the to-be-transposed music. As you can see, in this case, the
1372 transposition is a no-op, as central C stay at central C.
1374 The purpose of this no-op is circumventing relative mode. Relative mode
1375 can not be used together with transposition, so @code{\relative} will
1376 leave the contents of @code{\hoomPah} alone. We can use it without
1377 having to worry about getting the motive in a wrong octave.
1379 bassvoices = \notes \relative c' @{
1381 \autochange Staff \hoomPah
1383 @cindex staff switch, automatic
1384 @cindex cross staff voice, automatic
1385 @cindex @code{\autochange}
1387 Voices can switch between staffs. The easiest way to get this, is to use
1388 @code{\autochange}. This command looks at the pitch of each note, and if
1389 necessary, will cross to the other staff. For this to work, the two
1390 staffs must be called @code{"up"} and @code{"down"}.
1392 \translator Staff = down
1394 @cindex staff switch
1395 @cindex cross staff voice
1396 The rest of this melody must be in the lower staff, so we do a manual
1401 \context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
1405 After skipping some lines, we see @code{~}. This mark makes ties.
1409 A special context is needed to get cross staff beaming right. This
1410 context is called @code{PianoStaff}.
1412 \context Staff = bottom < \time 2/2; \clef bass;
1414 The bottom staff must have a different clef.
1418 To make some more room on the line, the first (in this case the only)
1419 line is not indented. The line still looks very cramped, but that is due
1420 to the page layout of this document.
1425 * arpeggio, glissando,
1427 * \apply, \outputproperty, \translator @{@}, \molecule hacking.
1429 * font-size, cadenza. rhythmic staff, multi-stanza.
1432 * Orchestral: demonstrate Hara-Kiri, part combining, part extraction,
1433 scores, transposition, instrument names,
1437 @node end of tutorial
1440 That's all folks. From here, you can either try fiddling with input
1441 files, or you can read the reference manual.