1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
13 Tutorial guidelines: (different from policy.txt!)
14 - unless you have a really good reason, use either
15 @lilypond[verbatim,quote,ragged-right]
17 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
19 Don't use any other relative=X commands (make it a non-fragment
20 example), and don't use fragment without relative=2.
22 - use "aes" and "ees" instead of "as" and "es". I know it's not
23 correct Dutch naming, but let's not confuse people with this
24 until we get to the Basic notation chapter.
26 - Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
27 portions of the tutorial.
35 This tutorial starts with an introduction to the LilyPond music
36 language and explains how to produce printed music. After this first
37 contact we will explain how to create beautiful printed music
38 containing common musical notation.
42 * Single staff notation::
43 * Multiple notes at once::
52 This section gives a basic introduction to working with LilyPond.
57 * Working on input files::
58 * How to read the manual::
62 @node Compiling a file
63 @subsection Compiling a file
65 @qq{Compiling} is the term used for processing an input file
66 in LilyPond format to produce a file which can be printed and
67 (optionally) a MIDI file which can be played. LilyPond input
68 files are simple text files. The first example
69 shows what a simple input file looks like.
71 To create sheet music, we write an input file that specifies the
72 notation. For example, if we write:
81 the result looks like this:
83 @c in this case we don't want verbatim
84 @lilypond[quote,ragged-right]
90 @warning{Notes and lyrics in LilyPond input must always be
91 surrounded by @strong{@{ curly braces @}}. The braces
92 should also be surrounded by a space unless they are at the
93 beginning or end of a line to avoid ambiguities. The braces may
94 be omitted in some examples in this manual, but don't forget them
95 in your own music! For more information about the display of
96 examples in the manual, see @ref{How to read the manual}.}
98 @cindex case sensitive
99 In addition, LilyPond input is @strong{case sensitive}.
100 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
101 produce an error message.
105 @subheading Entering music and viewing output
108 @cindex viewing music
110 In this section we will explain what commands to run and how to
111 view or print the output.
113 Note that there are several other text editors available with
114 better support for LilyPond. For more information, see
115 @rprogram{Text editor support}.
117 @warning{The first time you ever run LilyPond, it may take a
118 minute or two because all of the system fonts have to be analyzed
119 first. After this, LilyPond will be much faster!}
121 @subsubheading MacOS X
123 If you double click @command{LilyPond.app}, it will open with an
124 example file. Save it, for example, to @file{test.ly} on your
125 Desktop, and then process it with the menu command
126 @w{@code{Compile > Typeset File}}. The resulting PDF file will be
127 displayed on your screen.
129 For future use of LilyPond, you should begin by selecting @q{New}
130 or @q{Open}. You must save your file before typesetting it. If
131 any errors occur in processing, please see the log window.
134 @subsubheading Windows
136 On Windows, if you double-click in the LilyPond icon on the
137 Desktop, it will open a simple text editor with an example file.
138 Save it, for example, to @file{test.ly} on your Desktop and then
139 double-click on the file to process it (the file icon looks like a
140 note). After some seconds, you will get a file @file{test.pdf} on
141 your desktop. Double-click on this PDF file to view the typeset
142 score. An alternative method to process the @file{test.ly} file
143 is to drag and drop it onto the LilyPond icon using your mouse
146 To edit an existing @file{.ly} file, right-click on it and
147 select @qq{Edit source}. To get an empty file to start from, run
148 the editor as described above and use @qq{New} in
149 the @qq{File} menu, or right-click on the desktop and select
150 @qq{New..Text Document}, change its name to a name of your choice
151 and change the file extension to @code{.ly}. Double-click the
152 icon to type in your LilyPond source code as before.
154 Double-clicking the file does not only result in a PDF file, but
155 also produces a @file{.log} file that contains some information on
156 what LilyPond has done to the file. If any errors occur, please
161 Create a text file called @file{test.ly} and enter:
169 To process @file{test.ly}, proceed as follows:
176 You will see something resembling:
183 Interpreting music...
184 Preprocessing graphical objects...
185 Finding the ideal number of pages...
186 Fitting music on 1 page...
188 Layout output to `test.ps'...
189 Converting to `test.pdf'...
193 @node Simple notation
194 @subsection Simple notation
196 LilyPond will add some notation elements automatically. In the
197 next example, we have only specified four pitches, but LilyPond
198 has added a clef, time signature, and rhythms.
200 @lilypond[verbatim,quote,ragged-right]
207 This behavior may be altered, but in most cases these automatic
213 Music Glossary: @rglos{pitch}, @rglos{interval},
214 @rglos{scale}, @rglos{middle C}, @rglos{octave},
217 The easiest way to enter notes is by using @code{\relative} mode.
218 In this mode, the octave is chosen automatically by assuming the
219 following note is always to be placed closest to the previous
220 note, i.e., it is to be placed in the octave which is within three
221 staff spaces of the previous note. We begin by entering the most
222 elementary piece of music, a @notation{scale}, in which every note
223 is within just one staff space of the previous note.
225 @lilypond[verbatim,quote,ragged-right]
226 \relative c' { % set the starting point to middle C
232 The initial note is @notation{middle C}. Each successive note is
233 placed closest to the previous note -- in other words, the first
234 @code{c} is the closest C to middle C. This is followed by the
235 closest D to the previous note. We can create melodies which have
236 larger intervals, still using only @code{\relative} mode:
238 @lilypond[verbatim,quote,ragged-right]
246 It is not necessary for the first note of the melody to start on
247 the note which specifies the starting pitch. In the previous
248 example, the first note -- the @code{d} -- is the closest D to
251 By adding (or removing) quotes @code{'} or commas @code{,} from
252 the @w{@code{\relative c' @{}} command, we can change the starting
255 @lilypond[verbatim,quote,ragged-right]
256 \relative c'' { % one octave above middle C
261 Relative mode can be confusing initially, but is the easiest way
262 to enter most melodies. Let us see how this relative calculation
263 works in practice. Starting from a B, which is on the middle line
264 in a treble clef, you can reach a C, D and E within 3 staff spaces
265 going up, and an A, G and F within 3 staff spaces going down. So
266 if the note following a B is a C, D or E it will be assumed to be
267 above the B, and an A, G or F will be assumed to be below.
269 @lilypond[verbatim,quote,ragged-right]
271 b c % c is 1 staff space up, so is the c above
272 b d % d is 2 up or 5 down, so is the d above
273 b e % e is 3 up or 4 down, so is the e above
274 b a % a is 6 up or 1 down, so is the a below
275 b g % g is 5 up or 2 down, so is the g below
276 b f % f is 4 up or 3 down, so is the f below
280 Exactly the same happens even when any of these notes are
281 sharpened or flattened. @notation{Accidentals} are
282 @strong{totally ignored} in the calculation of relative position.
283 Precisely the same staff space counting is done from a note at any
284 other position on the staff.
286 To add intervals that are larger than three staff spaces, we can
287 raise the @notation{octave} by adding a single quote @code{'} (or
288 apostrophe) to the note name. We can lower the octave by adding a
289 comma @code{,} to the note name.
291 @lilypond[verbatim,quote,ragged-right]
299 To change a note by two (or more!) octaves, we use multiple
300 @code{''} or @code{,,} -- but be careful that you use two single
301 quotes @code{''} and not one double quote @code{"}@tie{}! The
302 initial value in @w{@code{\relative c'}} may also be modified like
304 @c " - keeps quotes in order for context-sensitive editor -td
306 @subheading Durations (rhythms)
308 Music Glossary: @rglos{beam}, @rglos{duration},
309 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
312 The @notation{duration} of a note is specified by a number after
313 the note name. @code{1} for a @notation{whole note}, @code{2} for
314 a @notation{half note}, @code{4} for a @notation{quarter note} and
315 so on. @notation{Beams} are added automatically.
317 If you do not specify a duration, the previous duration is used
318 for the next note. The duration of the first note defaults to a
321 @lilypond[verbatim,quote,ragged-right]
325 a16 a a a a32 a a a a64 a a a a a a a a2
329 To create @notation{dotted notes}, add a dot @code{.} to the
330 duration number. The duration of a dotted note must be stated
331 explicitly (i.e., with a number).
333 @lilypond[verbatim,quote,ragged-right]
343 Music Glossary: @rglos{rest}.
345 A @notation{rest} is entered just like a note with the name
348 @lilypond[verbatim,quote,ragged-right]
356 @subheading Time signature
358 Music Glossary: @rglos{time signature}.
360 The @notation{time signature} can be set with the @code{\time}
363 @lilypond[verbatim,quote,ragged-right]
377 Music Glossary: @rglos{clef}.
379 The @notation{clef} can be set using the @code{\clef} command:
381 @lilypond[verbatim,quote,ragged-right]
395 @subheading All together
397 Here is a small example showing all these elements together:
399 @lilypond[verbatim,quote,ragged-right]
411 Notation Reference: @ruser{Writing pitches},
412 @ruser{Writing rhythms}, @ruser{Writing rests},
413 @ruser{Time signature}, @ruser{Clef}.
416 @node Working on input files
417 @subsection Working on input files
419 LilyPond input files are similar to source files in many common
420 programming languages. They are case sensitive, and white-space
421 is generally ignored. Expressions are formed with curly braces
422 @{ @}, and comments are denoted with @code{%} or
423 @w{@code{%@{ ... %@}}}.
425 If the previous sentences sound like nonsense, don't worry! We'll
426 explain what all these terms mean:
430 @cindex case sensitive
432 @strong{Case sensitive}:
433 it matters whether you enter a letter in lower case (e.g.
434 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
435 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
436 @w{@code{@{ C D E @}}} will produce an error message.
439 @strong{Whitespace insensitive}:
440 it does not matter how many spaces (or new lines) you add.
441 @w{@code{@{ c d e @}}} means the same thing as
442 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
450 Of course, the previous example is hard to read. A good rule of
451 thumb is to indent code blocks with either a tab or two spaces:
460 @strong{Expressions}:
461 every piece of LilyPond input needs to have @strong{@{ curly
462 braces @}} placed around the input. These braces tell LilyPond
463 that the input is a single music expression, just like parentheses
464 @code{()} in mathematics. The braces should be surrounded by a
465 space unless they are at the beginning or end of a line to avoid
468 A LilyPond command followed by a simple expression in braces (such
469 as @w{@code{\relative @{ @}}}) also counts as a single music
474 @cindex block comment
477 a comment is a remark for the human reader of the music input; it
478 is ignored while parsing, so it has no effect on the printed
479 output. There are two types of comments. The percent symbol
480 @code{%} introduces a line comment; anything after @code{%} on
481 that line is ignored. By convention, a line comment is placed
482 @emph{above} the code it refers to.
486 % this comment refers to the Bs
490 A block comment marks a whole section of music input as a comment.
491 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
492 However, block comments do not @q{nest}. This means that you
493 cannot place a block comment inside another block comment. If you
494 try, the first @code{%@}} will terminate @emph{both} block
495 comments. The following fragment shows possible uses for
499 % notes for twinkle twinkle follow
503 This line, and the notes below
504 are ignored, since they are in a
514 @node How to read the manual
515 @subsection How to read the manual
517 LilyPond input must be surrounded by @{ @} marks or a
518 @w{@code{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
519 input files}. For the rest of this manual, most examples will
520 omit this. To replicate the examples, you may copy and paste the
521 displayed input but you @strong{must} add the
522 @w{@code{\relative c'' @{ @}}} like this:
526 ... example goes here...
530 Why omit the braces? Most examples in this manual can be inserted
531 into the middle of a longer piece of music. For these examples,
532 it does not make sense to add @w{@code{\relative c'' @{ @}}} --
533 you should not place a @code{\relative} inside another
534 @code{\relative}! If we included @w{@code{\relative c'' @{ @}}}
535 around every example, you would not be able to copy a small
536 documentation example and paste it inside a longer piece of your
537 own. Most people want to add material to an existing piece, so we
538 format the manual this way.
541 @subheading Clickable examples
543 Many people learn programs by trying and fiddling around with the
544 program. This is also possible with LilyPond. If you click on a
545 picture in the HTML version of this manual, you will see the exact
546 LilyPond input that was used to generate that image. Try it on
550 @lilypond[quote,ragged-right]
552 c-\markup { \bold \huge { Click here. } }
556 By cutting and pasting everything in the @qq{ly snippet} section,
557 you have a starting template for experiments. To see exactly the
558 same output (line-width and all), copy everything from @qq{Start
559 cut-&-pastable section} to the bottom of the file.
564 There are more tips for constructing input files in
565 @ref{Suggestions for writing LilyPond input files}. But it might be
566 best to read through the rest of the tutorial first.
570 @node Single staff notation
571 @section Single staff notation
573 This section introduces common notation that is used for one voice
577 * Accidentals and key signatures::
579 * Articulation and dynamics::
581 * Automatic and manual beams::
582 * Advanced rhythmic commands::
586 @node Accidentals and key signatures
587 @subsection Accidentals and key signatures
589 @subheading Accidentals
591 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
592 @rglos{double flat}, @rglos{accidental}.
594 A @notation{sharp} pitch is made by adding @code{is} to the name,
595 and a @notation{flat} pitch by adding @code{es}. As you might
596 expect, a @notation{double sharp} or @notation{double flat} is
597 made by adding @code{isis} or @code{eses}. This syntax is derived
598 from note naming conventions in Nordic and Germanic languages,
599 like German and Dutch. To use other names for
600 @notation{accidentals}, see @ruser{Note names in other languages}.
602 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
603 cis1 ees fisis, aeses
606 @cindex key signature, setting
607 @subheading Key signatures
609 Music Glossary: @rglos{key signature}, @rglos{major},
612 The @notation{key signature} is set with the command @code{\key}
613 followed by a pitch and @code{\major} or @code{\minor}.
615 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
624 @subheading Warning: key signatures and pitches
626 Music Glossary: @rglos{accidental}, @rglos{key signature},
627 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
628 @rglos{transposition}.
630 To determine whether to print an @notation{accidental}, LilyPond
631 examines the pitches and the @notation{key signature}. The key
632 signature only affects the @emph{printed} accidentals, not the
633 note's @notation{pitch}! This is a feature that often causes
634 confusion to newcomers, so let us explain it in more detail.
636 LilyPond makes a sharp distinction between musical content and
637 layout. The alteration (@notation{flat}, @notation{natural sign} or
638 @notation{sharp}) of a note is part of the pitch, and is therefore
639 musical content. Whether an accidental (a @emph{printed} flat,
640 natural or sharp sign) is printed in front of the corresponding
641 note is a question of layout. Layout is something that follows
642 rules, so accidentals are printed automatically according to those
643 rules. The pitches in your music are works of art, so they will
644 not be added automatically, and you must enter what you want to
649 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
655 No note has a printed accidental, but you must still add
656 @code{is} and type @code{cis} and @code{fis} in the input file.
658 The code @code{e} does not mean @qq{print a black dot just below
659 the first line of the staff.} Rather, it means @qq{there is a
660 note with pitch E-natural.} In the key of A-flat major, it
661 @emph{does} get an accidental:
663 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
668 Adding all alterations explicitly might require a little more
669 effort when typing, but the advantage is that
670 @notation{transposing} is easier, and accidentals can be printed
671 according to different conventions. For some examples how
672 accidentals can be printed according to different rules, see
673 @ruser{Automatic accidentals}.
677 Notation Reference: @ruser{Note names in other languages},
678 @ruser{Accidentals}, @ruser{Automatic accidentals},
679 @ruser{Key signature}.
681 Music Glossary: @rglos{Pitch names}.
685 @subsection Ties and slurs
690 Music Glossary: @rglos{tie}.
692 A @notation{tie} is created by appending a tilde @code{~} to the
693 first note being tied.
695 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
703 Music Glossary: @rglos{slur}.
705 A @notation{slur} is a curve drawn across many notes. The
706 starting note and ending note are marked with @code{(} and
707 @code{)} respectively.
709 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
710 d4( c16) cis( d e c cis d) e( d4)
713 @cindex slurs, phrasing
714 @cindex phrasing slurs
715 @subheading Phrasing slurs
717 Music Glossary: @rglos{slur}, @rglos{phrasing}.
719 Slurs to indicate longer @notation{phrasing} can be entered with
720 @code{\(} and @code{\)}. You can have both @notation{slurs}
721 and phrasing slurs at the same time, but you cannot have
722 simultaneous slurs or simultaneous phrasing slurs.
724 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
725 a8(\( ais b c) cis2 b'2 a4 cis,\)
730 @cindex slurs versus ties
731 @subheading Warnings: slurs vs. ties
733 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
735 A @notation{slur} looks like a @notation{tie}, but it has a
736 different meaning. A tie simply makes the first note longer, and
737 can only be used on pairs of notes with the same pitch. Slurs
738 indicate the @notation{articulation} of notes, and can be used on
739 larger groups of notes. Slurs and ties can be nested.
741 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
742 c2~( c8 fis fis4 ~ fis2 g2)
747 Notation Reference: @ruser{Ties}, @ruser{Slurs},
748 @ruser{Phrasing slurs}.
751 @node Articulation and dynamics
752 @subsection Articulation and dynamics
757 @subheading Articulations
759 Music Glossary: @rglos{articulation}.
761 Common @notation{articulations} can be added to a note using a
762 dash @code{-} and a single character:
764 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
765 c-. c-- c-> c-^ c-+ c-_
769 @subheading Fingerings
771 Music Glossary: @rglos{fingering}.
774 Similarly, @notation{fingering} indications can be added to a note
775 using a dash (@code{-}) and the digit to be printed:
777 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
781 Articulations and fingerings are usually placed automatically, but
782 you can specify a direction by replacing the dash (@code{-}) with
783 @code{^} (up) or @code{_} (down). You can also use multiple
784 articulations on the same note. However, in most cases it is best
785 to let LilyPond determine the articulation directions.
787 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
788 c_-^1 d^. f^4_2-> e^-_+
793 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
796 @notation{Dynamic} signs are made by adding the markings (with a
797 backslash) to the note:
799 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
807 @notation{Crescendi} and @notation{decrescendi} are started with
808 the commands @code{\<} and @code{\>}. The next dynamics sign, for
809 example @code{\f}, will end the (de)crescendo, or the command
810 @code{\!} can be used:
812 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
818 Notation Reference: @ruser{Articulations and ornamentations},
819 @ruser{Fingering instructions}, @ruser{Dynamics}.
823 @subsection Adding text
825 Text may be added to your scores:
827 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
831 Extra formatting may be added with the @code{\markup} command:
833 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
834 c1^\markup{ \bold espr}
836 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
843 Notation Reference: @ruser{Writing text}.
846 @node Automatic and manual beams
847 @subsection Automatic and manual beams
849 Music Glossary: @rglos{beam}.
851 @cindex beams, by hand
852 All @notation{beams} are drawn automatically:
854 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
855 a8 ais d ees r d c16 b a8
859 If you do not like the automatic beams, they may be overridden
860 manually. Mark the first note to be beamed with @code{[} and the
861 last one with @code{]}.
863 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
864 a8[ ais] d[ ees r d] a b
869 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
872 @node Advanced rhythmic commands
873 @subsection Advanced rhythmic commands
877 @cindex partial measure
878 @subheading Partial measure
880 Music Glossary: @rglos{anacrusis}.
882 A pickup (or @notation{anacrusis}) is entered with the keyword
883 @code{\partial}. It is followed by a duration: @code{\partial 4}
884 is a quarter note pickup and @code{\partial 8} an eighth note.
886 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
895 Music Glossary: @rglos{note value}, @rglos{triplet}.
897 @notation{Tuplets} are made with the @code{\times} keyword. It
898 takes two arguments: a fraction and a piece of music. The
899 duration of the piece of music is multiplied by the fraction.
900 Triplets make notes occupy 2/3 of their notated duration, so a
901 @notation{triplet} has 2/3 as its fraction
903 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
904 \times 2/3 { f8 g a }
906 \times 2/3 { f,8 g16[ a g a] }
913 @subheading Grace notes
915 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
916 @rglos{appoggiatura}.
918 @notation{Grace notes} are created with the @code{\grace} command,
919 although they can also be created by prefixing a music expression
920 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
922 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
923 c2 \grace { a32[ b] } c2
924 c2 \appoggiatura b16 c2
925 c2 \acciaccatura b16 c2
930 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
934 @node Multiple notes at once
935 @section Multiple notes at once
937 This section introduces having more than one note at the same
938 time: multiple instruments, multiple staves for a single
939 instrument (i.e. piano), and chords.
941 Polyphony in music refers to having more than one voice occurring
942 in a piece of music. Polyphony in LilyPond refers to having more
943 than one voice on the same staff.
946 * Music expressions explained::
949 * Combining notes into chords::
950 * Single staff polyphony::
954 @node Music expressions explained
955 @subsection Music expressions explained
957 In LilyPond input files, music is represented by @emph{music
958 expressions}. A single note is a music expression:
960 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
964 Enclosing a note in braces creates a @emph{compound music
965 expression}. Here we have created a compound music expression
968 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
972 Putting a group of music expressions (e.g. notes) in braces means
973 that they are in sequence (i.e. each one follows the previous
974 one). The result is another music expression:
976 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
981 @cindex music expression
982 @subheading Analogy: mathematical expressions
984 This mechanism is similar to mathematical formulas: a big formula
985 is created by composing small formulas. Such formulas are called
986 expressions, and they can contain other expressions, so you can
987 make arbitrarily complex and large expressions. For example,
996 ((1 + 2) * 3) / (4 * 5)
999 This is a sequence of expressions, where each expression is
1000 contained in the next (larger) one. The simplest expressions are
1001 numbers, and larger ones are made by combining expressions with
1002 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
1003 Like mathematical expressions, music expressions can be nested
1004 arbitrarily deep, which is necessary for complex music like
1008 @subheading Simultaneous music expressions: multiple staves
1010 Music Glossary: @rglos{polyphony}.
1012 This technique is useful for @notation{polyphonic} music. To
1013 enter music with more voices or more staves, we combine
1014 expressions in parallel. To indicate that two voices should play
1015 at the same time, simply enter a simultaneous combination of music
1016 expressions. A @q{simultaneous} music expression is formed by
1017 enclosing expressions inside @code{<<} and @code{>>}. In the
1018 following example, three sequences (all containing two separate
1019 notes) are combined simultaneously:
1021 @lilypond[verbatim,quote,ragged-right]
1031 Note that we have indented each level of the input with a
1032 different amount of space. LilyPond does not care how much (or
1033 little) space there is at the beginning of a line, but indenting
1034 LilyPond code like this makes it much easier for humans to read.
1036 @warning{each note is relative to the previous note in
1037 the input, not relative to the @code{c''} in the initial
1038 @code{@bs{}relative} command.}
1041 @subheading Simultaneous music expressions: single staff
1043 To determine the number of staves in a piece, LilyPond looks at
1044 the beginning of the first expression. If is a single note, there
1045 is one staff; if there is a simultaneous expression, there is more
1048 @lilypond[verbatim,quote,ragged-right]
1051 << { e f } { c <<b d>> } >>
1055 @node Multiple staves
1056 @subsection Multiple staves
1058 LilyPond input files are constructed out of music expressions, as
1059 we saw in @ref{Music expressions explained}. If the score begins
1060 with simultaneous music expressions, LilyPond creates multiples
1061 staves. However, it is easier to see what happens if we create
1062 each staff explicitly.
1064 To print more than one staff, each piece of music that makes up a
1065 staff is marked by adding @code{\new Staff} before it. These
1066 @code{Staff} elements are then combined in parallel with @code{<<}
1069 @lilypond[verbatim,quote,ragged-right]
1072 \new Staff { \clef treble c }
1073 \new Staff { \clef bass c,, }
1078 The command @code{\new} introduces a @q{notation context.} A
1079 notation context is an environment in which musical events (like
1080 notes or @code{\clef} commands) are interpreted. For simple
1081 pieces, such notation contexts are created automatically. For
1082 more complex pieces, it is best to mark contexts explicitly.
1084 There are several types of contexts. @code{Score}, @code{Staff},
1085 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1086 lyric texts and @code{ChordNames} prints chord names.
1088 In terms of syntax, prepending @code{\new} to a music expression
1089 creates a bigger music expression. In this way it resembles the
1090 minus sign in mathematics. The formula @math{(4+5)} is an
1091 expression, so @math{-(4+5)} is a bigger expression.
1093 Time signatures entered in one staff affects all other staves by
1094 default. On the other hand, the key signature of one staff does
1095 @emph{not} affect other staves. This different default behavior
1096 is because scores with transposing instruments are more common
1097 than polyrhythmic scores.
1099 @lilypond[verbatim,quote,ragged-right]
1102 \new Staff { \clef treble \key d \major \time 3/4 c }
1103 \new Staff { \clef bass c,, }
1112 @subsection Staff groups
1118 Music Glossary: @rglos{brace}.
1120 Piano music is typeset in two staves connected by a
1122 Printing such a staff is similar to the polyphonic example in
1123 @ref{Multiple staves}. However, now this entire expression is
1124 inserted inside a @code{PianoStaff}:
1133 Here is a small example:
1135 @lilypond[verbatim,quote,ragged-right]
1138 \new Staff { \time 2/4 c4 e g g, }
1139 \new Staff { \clef bass c,, c' e c }
1144 Other staff groupings are introduced with @code{\new GrandStaff},
1145 suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
1146 suitable for vocal scores. These staff groups each form another
1147 type of context, one that generates the brace at the left end of
1148 every system and also controls the extent of bar lines.
1152 Notation Reference: @ruser{Keyboard instruments},
1153 @ruser{Displaying staves}.
1156 @node Combining notes into chords
1157 @subsection Combining notes into chords
1161 Music Glossary: @rglos{chord}.
1163 We saw earlier how notes can be combined into @notation{chords} by
1164 indicating they are simultaneous by enclosing them in double angle
1165 brackets. However, the normal way of indicating a chord is to
1166 surround the pitches with @emph{single} angle brackets. Note that
1167 all the notes in a chord must have the same duration, and that the
1168 duration is placed after the closing bracket.
1170 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1171 r4 <c e g>4 <c f a>2
1174 Think of chords as almost equivalent to single notes:
1175 almost everything you can attach to a single note can be attached
1176 to a chord, and everything must go @emph{outside} the angle
1177 brackets. For example, you can combine markings like beams and
1178 ties with chords. They must be placed outside the angle brackets.
1180 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1181 r4 <c e g>8[ <c f a>]~ <c f a>2
1182 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
1186 @node Single staff polyphony
1187 @subsection Single staff polyphony
1190 @cindex multiple voices
1191 @cindex voices, more -- on a staff
1192 When different melodic lines are combined on a single staff they
1193 are printed as polyphonic voices; each voice has its own stems,
1194 slurs and beams, and the top voice has the stems up, while the
1195 bottom voice has them down.
1197 Entering such parts is done by entering each voice as a sequence
1198 (with @w{@code{@{...@}}}) and combining these simultaneously,
1199 separating the voices with @code{\\}:
1201 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1208 For polyphonic music typesetting, spacer rests can also be
1209 convenient; these are rests that do not print. They are useful
1210 for filling up voices that temporarily do not play. Here is the
1211 same example with a spacer rest (@code{s}) instead of a normal
1214 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1222 Again, these expressions can be nested arbitrarily.
1224 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1232 { <c g>1 ~ <c g>4 } \\
1240 Notation Reference: @ruser{Simultaneous notes}.
1246 This section introduces vocal music and simple song sheets.
1249 * Setting simple songs::
1250 * Aligning lyrics to a melody::
1251 * Lyrics to multiple staves::
1255 @node Setting simple songs
1256 @subsection Setting simple songs
1261 Music Glossary: @rglos{lyrics}.
1263 Here is the start of the melody to a nursery
1264 rhyme, @qq{Girls and boys come out to play}:
1266 @lilypond[verbatim,quote,ragged-right]
1270 d4 b8 c4 a8 d4 b8 g4
1274 The @notation{lyrics} can be set to these notes, combining both
1275 with the @code{\addlyrics} keyword. Lyrics are entered by
1276 separating each syllable with a space.
1278 @lilypond[verbatim,quote,ragged-right]
1283 d4 b8 c4 a8 d4 b8 g4
1286 Girls and boys come out to play,
1291 Note the curly brackets delimiting both the music and the lyrics,
1292 and the double angle brackets @w{@code{<< ... >>}} around the
1293 whole piece to show that the music and lyrics are to occur at the
1296 @node Aligning lyrics to a melody
1297 @subsection Aligning lyrics to a melody
1299 Music Glossary: @rglos{melisma}, @rglos{extender line}.
1302 @cindex extender line
1306 The next line in the nursery rhyme is @q{The moon doth shine as
1307 bright as day}. Let's extend it:
1309 @lilypond[verbatim,quote,ragged-right]
1314 d4 b8 c4 a8 d4 b8 g4
1315 g8 a4 b8 c b a d4 b8 g4.
1318 Girls and boys come out to play,
1319 The moon doth shine as bright as day;
1324 We see the extra lyrics do not align properly with the notes. The
1325 word @q{shine} should be sung on two notes, not one. This is
1326 called a @notation{melisma}, a single syllable sung to more than
1327 one note. There are several ways to spread a syllable over
1328 multiple notes, the simplest being to add a slur across them (see
1329 @ref{Ties and slurs}):
1331 @lilypond[verbatim,quote,ragged-right]
1336 d4 b8 c4 a8 d4 b8 g4
1337 g8 a4 b8 c([ b)] a d4 b8 g4.
1340 Girls and boys come out to play,
1341 The moon doth shine as bright as day;
1346 Here we have also used manual beaming (the square brackets
1347 @code{[]} ) to generate the beaming which is customarily used with lyrics
1348 (see @ref{Automatic and manual beams}).
1350 As an alternative to using slurs, the melismata may be indicated
1351 in just the lyrics by using an underscore, @code{_}, for each
1352 note that should be included in the melisma:
1354 @lilypond[verbatim,quote,ragged-right]
1359 d4 b8 c4 a8 d4 b8 g4
1360 g8 a4 b8 c[ b] a d4 b8 g4.
1363 Girls and boys come out to play,
1364 The moon doth shine _ as bright as day;
1369 If a syllable extends over several notes or a single very long
1370 note an @notation{extender line} is usually drawn from the
1371 syllable extending under all the notes for that syllable. It is
1372 entered as two underscores @code{__}. Here is an example from the
1373 first three bars of Dido's Lament, from Purcell's Dido and Æneas:
1375 @lilypond[verbatim,quote,ragged-right]
1381 b c4.( bes8 a4. g8 fis4.) g8 fis1
1385 am laid __ in earth,
1390 None of the examples so far have involved words containing more
1391 than one syllable. Such words are usually split one syllable to a
1392 note, with hyphens between syllables. Such hyphens are entered as
1393 two dashes, resulting in a centered hyphen between the syllables.
1394 Here is an example showing this and everything we have learned so
1395 far about aligning lyrics to notes.
1397 @c no ragged-right here because otherwise the hyphens get lost,
1398 @c but the example is long enough to avoid looking strange.
1399 @lilypond[verbatim,quote]
1405 d4 g4 g a8( b) g4 g4
1409 A -- way in a __ man -- ger,
1410 no __ crib for a bed, __
1415 Some lyrics, especially those in Italian, require the opposite:
1416 setting more than one syllable to a single note. This is
1417 achieved by linking the syllables together with a single
1418 underscore @code{_} (with no spaces), or enclosing them in
1419 quotes. Here's an example from Rossini's Figaro, where
1420 @q{al} has to be sung on the same note as the @q{go} of
1421 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1423 @c no ragged-right here because otherwise the hyphens get lost,
1424 @c but the example is long enough to avoid looking strange.
1425 @lilypond[verbatim,quote]
1431 c4.~ c8 d b c([ d)] b c d b c
1434 Lar -- go_al fac -- to -- tum del -- la cit -- tà
1442 Notation Reference: @ruser{Vocal music}.
1445 @node Lyrics to multiple staves
1446 @subsection Lyrics to multiple staves
1448 The simple approach using @code{\addlyrics} can be used for
1449 placing lyrics under more than one staff. Here is an
1450 example from Handel's Judas Maccabæus:
1452 @lilypond[verbatim,quote,ragged-right]
1460 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1463 Let flee -- cy flocks the hills a -- dorn, __
1467 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1470 Let flee -- cy flocks the hills a -- dorn,
1476 but scores any more complex than this simple example are
1477 better produced by separating out the staff structure
1478 from the notes and lyrics with variables. These are
1479 discussed in @ref{Organizing pieces with variables}.
1483 Notation Reference: @ruser{Vocal music}.
1488 @section Final touches
1490 This is the final section of the tutorial; it demonstrates how to
1491 add the final touches to simple pieces, and provides an
1492 introduction to the rest of the manual.
1495 * Organizing pieces with variables::
1498 * Absolute note names::
1499 * After the tutorial::
1503 @node Organizing pieces with variables
1504 @subsection Organizing pieces with variables
1506 When all of the elements discussed earlier are combined to produce
1507 larger files, the music expressions get a lot bigger. In
1508 polyphonic music with many staves, the input files can become very
1509 confusing. We can reduce this confusion by using
1512 With variables (also known as identifiers or macros), we can break
1513 up complex music expressions. A variable is assigned as
1517 namedMusic = @{ @dots{} @}
1520 The contents of the music expression @code{namedMusic} can be used
1521 later by placing a backslash in front of the name
1522 (@code{\namedMusic}, just like a normal LilyPond command).
1524 @lilypond[verbatim,quote,ragged-right]
1525 violin = \new Staff { \relative c'' {
1528 cello = \new Staff { \relative c {
1541 The name of a variable must have alphabetic characters only, no
1542 numbers, underscores, or dashes.
1544 Variables must be defined @emph{before} the main music
1545 expression, but may be used as many times as required anywhere after
1546 they have been defined. They may even be used in a later definition
1547 of another variable, giving a way of shortening the input if a
1548 section of music is repeated many times.
1550 @lilypond[verbatim,quote,ragged-right]
1551 tripletA = \times 2/3 { c,8 e g }
1552 barA = { \tripletA \tripletA \tripletA \tripletA }
1559 Variables may be used for many other types of objects in
1560 the input. For example,
1565 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1568 Depending on its contents, the variable can be used in different
1569 places. The following example uses the above variables:
1580 @node Version number
1581 @subsection Version number
1584 The @code{\version} statement records the version of LilyPond that
1585 was used to write the file:
1588 \version @w{"@version{}"}
1592 By convention, this is placed at the top of your LilyPond file.
1594 These annotations make future upgrades of LilyPond go more
1595 smoothly. Changes in the syntax are handled with a special
1596 program, @file{convert-ly}, and it uses @code{\version} to
1597 determine what rules to apply. For details, see
1598 @rprogram{Updating files with convert-ly}.
1602 @subsection Adding titles
1604 The title, composer, opus number, and similar information are
1605 entered in the @code{\header} block. This exists outside of the
1606 main music expression; the @code{\header} block is usually placed
1607 underneath the @ref{Version number}.
1610 \version @w{"@version{}"}
1618 @dots{} music @dots{}
1622 When the file is processed, the title and composer are printed
1623 above the music. More information on titling can be found in
1624 @ruser{Creating titles}.
1627 @node Absolute note names
1628 @subsection Absolute note names
1630 So far we have always used @code{\relative} to define pitches.
1631 This is the easiest way to enter most music, but another way of
1632 defining pitches exists: absolute mode.
1634 If you omit the @code{\relative}, LilyPond treats all pitches as
1635 absolute values. A @code{c'} will always mean middle C, a
1636 @code{b} will always mean the note one step below middle C, and a
1637 @code{g,} will always mean the note on the bottom staff of the
1640 @lilypond[verbatim,quote,ragged-right]
1648 Here is a four-octave scale:
1650 @lilypond[verbatim,quote,ragged-right]
1665 As you can see, writing a melody in the treble clef involves a lot
1666 of quote @code{'} marks. Consider this fragment from Mozart:
1668 @lilypond[verbatim,quote,ragged-right]
1672 cis''8. d''16 cis''8 e''4 e''8
1673 b'8. cis''16 b'8 d''4 d''8
1677 All these quotes makes the input less readable and they are a source
1678 of errors. With @code{\relative}, the previous example is much
1679 easier to read and type:
1681 @lilypond[verbatim,quote,ragged-right]
1685 cis8. d16 cis8 e4 e8
1690 If you make a mistake with an octave mark (@code{'} or @code{,})
1691 while working in @code{\relative} mode, it is very obvious -- many
1692 notes will be in the wrong octave. When working in absolute mode,
1693 a single mistake will not be as visible, and will not be as easy
1696 However, absolute mode is useful for music which has large
1697 intervals, and is extremely useful for computer-generated LilyPond
1702 @node After the tutorial
1703 @subsection After the tutorial
1705 FIXME: rewrite slightly after the rest of the LM has been
1706 stabilized. Translators, ignore this section for now.
1708 After finishing the tutorial, you should probably try writing a
1709 piece or two. Start by adding notes to one of the
1710 @ref{Templates}. If you need any notation that was not covered in
1711 the tutorial, look at the Notation Reference, starting with
1712 @ruser{Musical notation}. If you want to write for an instrument
1713 ensemble that is not covered in the templates, take a look at
1714 @ref{Extending the templates}.
1716 Once you have written a few short pieces, read the rest of the
1717 Learning Manual (chapters 3-5). There's nothing wrong with
1718 reading it now, of course! However, the rest of the Learning
1719 Manual assumes that you are familiar with LilyPond input. You may
1720 wish to skim these chapters right now, and come back to them after
1721 you have more experience.