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 text 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 text file
66 in LilyPond format to produce a file which can be printed and
67 (optionally) a MIDI file which can be played. The first example
68 shows what a simple input text file looks like.
70 To create sheet music, we write a text file that specifies the
71 notation. For example, if we write:
80 the result looks like this:
82 @c in this case we don't want verbatim
83 @lilypond[quote,ragged-right]
89 @warning{Notes and lyrics in LilyPond input must always be
90 surrounded by @strong{@{ curly braces @}}. The braces
91 should also be surrounded by a space unless they are at the
92 beginning or end of a line to avoid ambiguities. The braces may
93 be omitted in some examples in this manual, but don't forget them
94 in your own music! For more information about the display of
95 examples in the manual, see @ref{How to read the manual}.}
97 @cindex case sensitive
98 In addition, LilyPond input is @strong{case sensitive}. @code{
99 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
104 @subheading Entering music and viewing output
107 @cindex viewing music
109 In this section we will explain what commands to run and how to
110 view or print the output.
112 Note that there are several other text editors available with
113 better support for LilyPond. For more information, see
114 @rprogram{Text editor support}.
116 @warning{The first time you ever run LilyPond, it may take a
117 minute or two because all of the system fonts have to be analyzed
118 first. After this, LilyPond will be much faster!}
120 @subsubheading MacOS X
122 If you double click @code{LilyPond.app}, it will open with an
123 example file. Save it, for example, to @file{test.ly} on your
124 Desktop, and then process it with the menu command @code{Compile >
125 Typeset File}. The resulting PDF file will be displayed on your
128 For future use of LilyPond, you should begin by selecting @q{New}
129 or @q{Open}. You must save your file before typesetting it. If
130 any errors occur in processing, please see the log window.
133 @subsubheading Windows
135 On Windows, if you double-click in the LilyPond icon on the
136 Desktop, it will open a simple text editor with an example file.
137 Save it, for example, to @file{test.ly} on your Desktop and then
138 double-click on the file to process it (the file icon looks like a
139 note). After some seconds, you will get a file @file{test.pdf} on
140 your desktop. Double-click on this PDF file to view the typeset
141 score. An alternative method to process the @file{test.ly} file
142 is to drag and drop it onto the LilyPond icon using your mouse
145 To edit an existing @file{.ly} file, right-click on it and
146 select @qq{Edit source}. To get an empty file to start from, run
147 the editor as described above and use @qq{New} in
148 the @qq{File} menu, or right-click on the desktop and select
149 @qq{New..Text Document}, change its name to a name of your choice
150 and change the file extension to @code{.ly}. Double-click the
151 icon to type in your LilyPond source code as before.
153 Double-clicking the file does not only result in a PDF file, but
154 also produces a @file{.log} file that contains some information on
155 what LilyPond has done to the file. If any errors occur, please
160 Create a text file called @file{test.ly} and enter:
168 To process @file{test.ly}, proceed as follows:
175 You will see something resembling:
182 Interpreting music...
183 Preprocessing graphical objects...
184 Finding the ideal number of pages...
185 Fitting music on 1 page...
187 Layout output to `test.ps'...
188 Converting to `test.pdf'...
192 @node Simple notation
193 @subsection Simple notation
195 LilyPond will add some notation elements automatically. In the
196 next example, we have only specified four pitches, but LilyPond
197 has added a clef, time signature, and rhythms.
199 @lilypond[verbatim,quote,ragged-right]
206 This behavior may be altered, but in most cases these automatic
212 Music Glossary: @rglos{pitch}, @rglos{interval},
213 @rglos{scale}, @rglos{middle C}, @rglos{octave},
216 The easiest way to enter notes is by using @code{\relative} mode.
217 In this mode, the octave is chosen automatically by assuming the
218 following note is always to be placed closest to the previous
219 note, i.e., it is to be placed in the octave which is within three
220 staff spaces of the previous note. We begin by entering the most
221 elementary piece of music, a @notation{scale}, in which every note
222 is within just one staff space of the previous note.
224 @lilypond[verbatim,quote,ragged-right]
225 \relative c' { % set the starting point to middle C
231 The initial note is @notation{middle C}. Each successive note is
232 placed closest to the previous note -- in other words, the first
233 @code{c} is the closest C to middle C. This is followed by the
234 closest D to the previous note. We can create melodies which have
235 larger intervals, still using only @code{\relative} mode:
237 @lilypond[verbatim,quote,ragged-right]
245 It is not necessary for the first note of the melody to start on
246 the note which specifies the starting pitch. In the previous
247 example, the first note -- the @code{d} -- is the closest D to
250 By adding (or removing) quotes @code{'} or commas @code{,} from
251 the @code{\relative c' @{} command, we can change the starting
254 @lilypond[verbatim,quote,ragged-right]
255 \relative c'' { % one octave above middle C
260 Relative mode can be confusing initially, but is the easiest way
261 to enter most melodies. Let us see how this relative calculation
262 works in practice. Starting from a B, which is on the middle line
263 in a treble clef, you can reach a C, D and E within 3 staff spaces
264 going up, and an A, G and F within 3 staff spaces going down. So
265 if the note following a B is a C, D or E it will be assumed to be
266 above the B, and an A, G or F will be assumed to be below.
268 @lilypond[verbatim,quote,ragged-right]
270 b c % c is 1 staff space up, so is the c above
271 b d % d is 2 up or 5 down, so is the d above
272 b e % e is 3 up or 4 down, so is the e above
273 b a % a is 6 up or 1 down, so is the a below
274 b g % g is 5 up or 2 down, so is the g below
275 b f % f is 4 up or 3 down, so is the f below
279 Exactly the same happens even when any of these notes are
280 sharpened or flattened. @notation{Accidentals} are
281 @strong{totally ignored} in the calculation of relative position.
282 Precisely the same staff space counting is done from a note at any
283 other position on the staff.
285 To add intervals that are larger than three staff spaces, we can
286 raise the @notation{octave} by adding a single quote @code{'} (or
287 apostrophe) to the note name. We can lower the octave by adding a
288 comma @code{,} to the note name.
290 @lilypond[verbatim,quote,ragged-right]
298 To change a note by two (or more!) octaves, we use multiple
299 @code{''} or @code{,,} -- but be careful that you use two single
300 quotes @code{''} and not one double quote @code{"}@tie{}! The
301 initial value in @code{\relative c'} may also be modified like
303 @c " - keeps quotes in order for context-sensitive editor -td
305 @subheading Durations (rhythms)
307 Music Glossary: @rglos{beam}, @rglos{duration},
308 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
311 The @notation{duration} of a note is specified by a number after
312 the note name. @code{1} for a @notation{whole note}, @code{2} for
313 a @notation{half note}, @code{4} for a @notation{quarter note} and
314 so on. @notation{Beams} are added automatically.
316 If you do not specify a duration, the previous duration is used
317 for the next note. The duration of the first note defaults to a
320 @lilypond[verbatim,quote,ragged-right]
324 a16 a a a a32 a a a a64 a a a a a a a a2
328 To create @notation{dotted notes}, add a dot @code{.} to the
329 duration number. The duration of a dotted note must be stated
330 explicitly (i.e., with a number).
332 @lilypond[verbatim,quote,ragged-right]
342 Music Glossary: @rglos{rest}.
344 A @notation{rest} is entered just like a note with the name
347 @lilypond[verbatim,quote,ragged-right]
355 @subheading Time signature
357 Music Glossary: @rglos{time signature}.
359 The @notation{time signature} can be set with the @code{\time}
362 @lilypond[verbatim,quote,ragged-right]
376 Music Glossary: @rglos{clef}.
378 The @notation{clef} can be set using the @code{\clef} command:
380 @lilypond[verbatim,quote,ragged-right]
394 @subheading All together
396 Here is a small example showing all these elements together:
398 @lilypond[verbatim,quote,ragged-right]
410 Notation Reference: @ruser{Writing pitches},
411 @ruser{Writing rhythms}, @ruser{Writing rests},
412 @ruser{Time signature}, @ruser{Clef}.
415 @node Working on text files
416 @subsection Working on text files
418 LilyPond input files are similar to source files in many common
419 programming languages. They are case sensitive, and white-space
420 is generally ignored. Expressions are formed with curly braces
421 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
424 If the previous sentences sound like nonsense, don't worry! We'll
425 explain what all these terms mean:
429 @cindex case sensitive
431 @strong{Case sensitive}:
432 it matters whether you enter a letter in lower case (e.g. @code{a,
433 b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
434 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
435 will produce an error message.
438 @strong{Whitespace insensitive}:
439 it does not matter how many spaces (or new lines) you add.
440 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
441 @tie{} @tie{} d e @}} and:
449 Of course, the previous example is hard to read. A good rule of
450 thumb is to indent code blocks with either a tab or two spaces:
459 @strong{Expressions}:
460 every piece of LilyPond input needs to have @strong{@{ curly
461 braces @}} placed around the input. These braces tell LilyPond
462 that the input is a single music expression, just like parentheses
463 @code{()} in mathematics. The braces should be surrounded by a
464 space unless they are at the beginning or end of a line to avoid
467 A LilyPond command followed by a simple expression in braces (such
468 as @code{\relative @{ @}}) also counts as a single music
473 @cindex block comment
476 a comment is a remark for the human reader of the music input; it
477 is ignored while parsing, so it has no effect on the printed
478 output. There are two types of comments. The percent symbol
479 @code{%} introduces a line comment; anything after @code{%} on
480 that line is ignored. By convention, a line comment is placed
481 @emph{above} the code it refers to.
485 % this comment refers to the Bs
489 A block comment marks a whole section of music input as a comment.
490 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
491 However, block comments do not @q{nest}. This means that you
492 cannot place a block comment inside another block comment. If you
493 try, the first @code{%@}} will terminate @emph{both} block
494 comments. The following fragment shows possible uses for
498 % notes for twinkle twinkle follow
502 This line, and the notes below
503 are ignored, since they are in a
513 @node How to read the manual
514 @subsection How to read the manual
516 LilyPond input must be surrounded by @{ @} marks or a
517 @code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
518 files}. For the rest of this manual, most examples will omit
519 this. To replicate the examples, you may copy and paste the
520 displayed input but you @strong{must} add the @code{\relative c''
525 ... example goes here...
529 Why omit the braces? Most examples in this manual can be inserted
530 into the middle of a longer piece of music. For these examples,
531 it does not make sense to add @code{\relative c'' @{ @}} -- you
532 should not place a @code{\relative} inside another
533 @code{\relative}! If we included @code{\relative c'' @{ @}}
534 around every example, you would not be able to copy a small
535 documentation example and paste it inside a longer piece of your
536 own. Most people want to add material to an existing piece, so we
537 format the manual this way.
540 @subheading Clickable examples
542 Many people learn programs by trying and fiddling around with the
543 program. This is also possible with LilyPond. If you click on a
544 picture in the HTML version of this manual, you will see the exact
545 LilyPond input that was used to generate that image. Try it on
549 @lilypond[quote,ragged-right]
551 c-\markup { \bold \huge { Click here. } }
555 By cutting and pasting everything in the @qq{ly snippet} section,
556 you have a starting template for experiments. To see exactly the
557 same output (line-width and all), copy everything from @qq{Start
558 cut-&-pastable section} to the bottom of the file.
563 There are more tips for constructing input files in
564 @ref{Suggestions for writing LilyPond files}. But it might be
565 best to read through the rest of the tutorial first.
569 @node Single staff notation
570 @section Single staff notation
572 This section introduces common notation that is used for one voice
576 * Accidentals and key signatures::
578 * Articulation and dynamics::
580 * Automatic and manual beams::
581 * Advanced rhythmic commands::
585 @node Accidentals and key signatures
586 @subsection Accidentals and key signatures
588 @subheading Accidentals
590 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
591 @rglos{double flat}, @rglos{accidental}.
593 A @notation{sharp} pitch is made by adding @code{is} to the name,
594 and a @notation{flat} pitch by adding @code{es}. As you might
595 expect, a @notation{double sharp} or @notation{double flat} is
596 made by adding @code{isis} or @code{eses}. This syntax is derived
597 from note naming conventions in Nordic and Germanic languages,
598 like German and Dutch. To use other names for
599 @notation{accidentals}, see @ruser{Note names in other languages}.
601 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
602 cis1 ees fisis, aeses
605 @cindex key signature, setting
606 @subheading Key signatures
608 Music Glossary: @rglos{key signature}, @rglos{major},
611 The @notation{key signature} is set with the command @code{\key}
612 followed by a pitch and @code{\major} or @code{\minor}.
614 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
623 @subheading Warning: key signatures and pitches
625 Music Glossary: @rglos{accidental}, @rglos{key signature},
626 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
627 @rglos{transposition}.
629 To determine whether to print an @notation{accidental}, LilyPond
630 examines the pitches and the @notation{key signature}. The key
631 signature only affects the @emph{printed} accidentals, not the
632 note's @notation{pitch}! This is a feature that often causes
633 confusion to newcomers, so let us explain it in more detail.
635 LilyPond makes a sharp distinction between musical content and
636 layout. The alteration (@notation{flat}, @notation{natural sign} or
637 @notation{sharp}) of a note is part of the pitch, and is therefore
638 musical content. Whether an accidental (a @emph{printed} flat,
639 natural or sharp sign) is printed in front of the corresponding
640 note is a question of layout. Layout is something that follows
641 rules, so accidentals are printed automatically according to those
642 rules. The pitches in your music are works of art, so they will
643 not be added automatically, and you must enter what you want to
648 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
654 No note has a printed accidental, but you must still add
655 @code{is} and type @code{cis} and @code{fis} in the input file.
657 The code @code{e} does not mean @qq{print a black dot just below
658 the first line of the staff.} Rather, it means @qq{there is a
659 note with pitch E-natural.} In the key of A-flat major, it
660 @emph{does} get an accidental:
662 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
667 Adding all alterations explicitly might require a little more
668 effort when typing, but the advantage is that
669 @notation{transposing} is easier, and accidentals can be printed
670 according to different conventions. For some examples how
671 accidentals can be printed according to different rules, see
672 @ruser{Automatic accidentals}.
676 Notation Reference: @ruser{Note names in other languages},
677 @ruser{Accidentals}, @ruser{Automatic accidentals},
678 @ruser{Key signature}.
680 Music Glossary: @rglos{Pitch names}.
684 @subsection Ties and slurs
689 Music Glossary: @rglos{tie}.
691 A @notation{tie} is created by appending a tilde @code{~} to the
692 first note being tied.
694 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
702 Music Glossary: @rglos{slur}.
704 A @notation{slur} is a curve drawn across many notes. The
705 starting note and ending note are marked with @code{(} and
706 @code{)} respectively.
708 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
709 d4( c16) cis( d e c cis d) e( d4)
712 @cindex slurs, phrasing
713 @cindex phrasing slurs
714 @subheading Phrasing slurs
716 Music Glossary: @rglos{slurs}, @rglos{phrasing}.
718 Slurs to indicate longer @notation{phrasing} can be entered with
719 @code{\(} and @code{\)}. You can have both @notation{slurs}
720 and phrasing slurs at the same time, but you cannot have
721 simultaneous slurs or simultaneous phrasing slurs.
723 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
724 a8(\( ais b c) cis2 b'2 a4 cis,\)
729 @cindex slurs versus ties
730 @subheading Warnings: slurs vs. ties
732 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
734 A @notation{slur} looks like a @notation{tie}, but it has a
735 different meaning. A tie simply makes the first note longer, and
736 can only be used on pairs of notes with the same pitch. Slurs
737 indicate the @notation{articulation} of notes, and can be used on
738 larger groups of notes. Slurs and ties can be nested.
740 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
741 c2~( c8 fis fis4 ~ fis2 g2)
746 Notation Reference: @ruser{Ties}, @ruser{Slurs},
747 @ruser{Phrasing slurs}.
750 @node Articulation and dynamics
751 @subsection Articulation and dynamics
756 @subheading Articulations
758 Music Glossary: @rglos{articulation}.
760 Common @notation{articulations} can be added to a note using a
761 dash @code{-} and a single character:
763 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
764 c-. c-- c-> c-^ c-+ c-_
768 @subheading Fingerings
770 Music Glossary: @rglos{fingering}.
773 Similarly, @notation{fingering} indications can be added to a note
774 using a dash (@code{-}) and the digit to be printed:
776 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
780 Articulations and fingerings are usually placed automatically, but
781 you can specify a direction by replacing the dash (@code{-}) with
782 @code{^} (up) or @code{_} (down). You can also use multiple
783 articulations on the same note. However, in most cases it is best
784 to let LilyPond determine the articulation directions.
786 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
787 c_-^1 d^. f^4_2-> e^-_+
792 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
795 @notation{Dynamic} signs are made by adding the markings (with a
796 backslash) to the note:
798 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
806 @notation{Crescendi} and @notation{decrescendi} are started with
807 the commands @code{\<} and @code{\>}. The next dynamics sign, for
808 example @code{\f}, will end the (de)crescendo, or the command
809 @code{\!} can be used:
811 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
817 Notation Reference: @ruser{Articulations and ornamentations},
818 @ruser{Fingering instructions}, @ruser{Dynamics}.
822 @subsection Adding text
824 Text may be added to your scores:
826 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
830 Extra formatting may be added with the @code{\markup} command:
832 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
833 c1^\markup{ \bold espr}
835 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
842 Notation Reference: @ruser{Writing text}.
845 @node Automatic and manual beams
846 @subsection Automatic and manual beams
848 Music Glossary: @rglos{beam}.
850 @cindex beams, by hand
851 All @notation{beams} are drawn automatically:
853 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
854 a8 ais d ees r d c16 b a8
858 If you do not like the automatic beams, they may be overridden
859 manually. Mark the first note to be beamed with @code{[} and the
860 last one with @code{]}.
862 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
863 a8[ ais] d[ ees r d] a b
868 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
871 @node Advanced rhythmic commands
872 @subsection Advanced rhythmic commands
876 @cindex partial measure
877 @subheading Partial measure
879 Music Glossary: @rglos{anacrusis}.
881 A pickup (or @notation{anacrusis}) is entered with the keyword
882 @code{\partial}. It is followed by a duration: @code{\partial 4}
883 is a quarter note pickup and @code{\partial 8} an eighth note.
885 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
894 Music Glossary: @rglos{note value}, @rglos{triplet}.
896 @notation{Tuplets} are made with the @code{\times} keyword. It
897 takes two arguments: a fraction and a piece of music. The
898 duration of the piece of music is multiplied by the fraction.
899 Triplets make notes occupy 2/3 of their notated duration, so a
900 @notation{triplet} has 2/3 as its fraction
902 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
903 \times 2/3 { f8 g a }
905 \times 2/3 { f,8 g16[ a g a] }
912 @subheading Grace notes
914 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
915 @rglos{appoggiatura}.
917 @notation{Grace notes} are created with the @code{\grace} command,
918 although they can also be created by prefixing a music expression
919 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
921 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
922 c2 \grace { a32[ b] } c2
923 c2 \appoggiatura b16 c2
924 c2 \acciaccatura b16 c2
929 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
933 @node Multiple notes at once
934 @section Multiple notes at once
936 This section introduces having more than one note at the same
937 time: multiple instruments, multiple staves for a single
938 instrument (i.e. piano), and chords.
940 Polyphony in music refers to having more than one voice occurring
941 in a piece of music. Polyphony in LilyPond refers to having more
942 than one voice on the same staff.
945 * Music expressions explained::
948 * Combining notes into chords::
949 * Single staff polyphony::
953 @node Music expressions explained
954 @subsection Music expressions explained
956 In LilyPond input files, music is represented by @emph{music
957 expressions}. A single note is a music expression:
959 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
963 Enclosing a note in braces creates a @emph{compound music
964 expression}. Here we have created a compound music expression
967 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
971 Putting a group of music expressions (e.g. notes) in braces means
972 that they are in sequence (i.e. each one follows the previous
973 one). The result is another music expression:
975 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
980 @cindex music expression
981 @subheading Analogy: mathematical expressions
983 This mechanism is similar to mathematical formulas: a big formula
984 is created by composing small formulas. Such formulas are called
985 expressions, and they can contain other expressions, so you can
986 make arbitrarily complex and large expressions. For example,
995 ((1 + 2) * 3) / (4 * 5)
998 This is a sequence of expressions, where each expression is
999 contained in the next (larger) one. The simplest expressions are
1000 numbers, and larger ones are made by combining expressions with
1001 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
1002 Like mathematical expressions, music expressions can be nested
1003 arbitrarily deep, which is necessary for complex music like
1007 @subheading Simultaneous music expressions: multiple staves
1009 Music Glossary: @rglos{polyphony}.
1011 This technique is useful for @notation{polyphonic} music. To
1012 enter music with more voices or more staves, we combine
1013 expressions in parallel. To indicate that two voices should play
1014 at the same time, simply enter a simultaneous combination of music
1015 expressions. A @q{simultaneous} music expression is formed by
1016 enclosing expressions inside @code{<<} and @code{>>}. In the
1017 following example, three sequences (all containing two separate
1018 notes) are combined simultaneously:
1020 @lilypond[verbatim,quote,ragged-right]
1030 Note that we have indented each level of the input with a
1031 different amount of space. LilyPond does not care how much (or
1032 little) space there is at the beginning of a line, but indenting
1033 LilyPond code like this makes it much easier for humans to read.
1035 @warning{each note is relative to the previous note in
1036 the input, not relative to the @code{c''} in the initial
1037 @code{@bs{}relative} command.}
1040 @subheading Simultaneous music expressions: single staff
1042 To determine the number of staves in a piece, LilyPond looks at
1043 the beginning of the first expression. If is a single note, there
1044 is one staff; if there is a simultaneous expression, there is more
1047 @lilypond[verbatim,quote,ragged-right]
1050 << { e f } { c <<b d>> } >>
1054 @node Multiple staves
1055 @subsection Multiple staves
1057 LilyPond input files are constructed out of music expressions, as
1058 we saw in @ref{Music expressions explained}. If the score begins
1059 with simultaneous music expressions, LilyPond creates multiples
1060 staves. However, it is easier to see what happens if we create
1061 each staff explicitly.
1063 To print more than one staff, each piece of music that makes up a
1064 staff is marked by adding @code{\new Staff} before it. These
1065 @code{Staff} elements are then combined in parallel with @code{<<}
1068 @lilypond[verbatim,quote,ragged-right]
1071 \new Staff { \clef treble c }
1072 \new Staff { \clef bass c,, }
1077 The command @code{\new} introduces a @q{notation context.} A
1078 notation context is an environment in which musical events (like
1079 notes or @code{\clef} commands) are interpreted. For simple
1080 pieces, such notation contexts are created automatically. For
1081 more complex pieces, it is best to mark contexts explicitly.
1083 There are several types of contexts. @code{Score}, @code{Staff},
1084 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1085 lyric texts and @code{ChordNames} prints chord names.
1087 In terms of syntax, prepending @code{\new} to a music expression
1088 creates a bigger music expression. In this way it resembles the
1089 minus sign in mathematics. The formula @math{(4+5)} is an
1090 expression, so @math{-(4+5)} is a bigger expression.
1092 Time signatures entered in one staff affects all other staves by
1093 default. On the other hand, the key signature of one staff does
1094 @emph{not} affect other staves. This different default behavior
1095 is because scores with transposing instruments are more common
1096 than polyrhythmic scores.
1098 @lilypond[verbatim,quote,ragged-right]
1101 \new Staff { \clef treble \key d \major \time 3/4 c }
1102 \new Staff { \clef bass c,, }
1111 @subsection Staff groups
1117 Music Glossary: @rglos{brace}.
1119 Piano music is typeset in two staves connected by a
1121 Printing such a staff is similar to the polyphonic example in
1122 @ref{Multiple staves}. However, now this entire expression is
1123 inserted inside a @code{PianoStaff}:
1132 Here is a small example:
1134 @lilypond[verbatim,quote,ragged-right]
1137 \new Staff { \time 2/4 c4 e g g, }
1138 \new Staff { \clef bass c,, c' e c }
1143 Other staff groupings are introduced with
1144 @code{\new GrandStaff,} suitable for orchestral
1145 scores, and @code{\new ChoirStaff,} suitable for
1146 vocal scores. These staff groups each form another
1147 type of context, one that generates the brace at the
1148 left end of every system and also controls the extent
1153 Notation Reference: @ruser{Piano music},
1154 @ruser{Displaying staves}.
1157 @node Combining notes into chords
1158 @subsection Combining notes into chords
1162 Music Glossary: @rglos{chord}.
1164 We saw earlier how notes can be combined into @notation{chords} by
1165 indicating they are simultaneous by enclosing them in double angle
1166 brackets. However, the normal way of indicating a chord is to
1167 surround the pitches with @emph{single} angle brackets. Note that
1168 all the notes in a chord must have the same duration, and that the
1169 duration is placed after the closing bracket.
1171 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1172 r4 <c e g>4 <c f a>2
1175 Think of chords as almost equivalent to single notes:
1176 almost everything you can attach to a single note can be attached
1177 to a chord, and everything must go @emph{outside} the angle
1178 brackets. For example, you can combine markings like beams and
1179 ties with chords. They must be placed outside the angle brackets.
1181 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1182 r4 <c e g>8[ <c f a>]~ <c f a>2
1183 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
1187 @node Single staff polyphony
1188 @subsection Single staff polyphony
1191 @cindex multiple voices
1192 @cindex voices, more -- on a staff
1193 When different melodic lines are combined on a single staff they
1194 are printed as polyphonic voices; each voice has its own stems,
1195 slurs and beams, and the top voice has the stems up, while the
1196 bottom voice has them down.
1198 Entering such parts is done by entering each voice as a sequence
1199 (with @code{@{...@}}) and combining these simultaneously,
1200 separating the voices with @code{\\}
1202 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1209 For polyphonic music typesetting, spacer rests can also be
1210 convenient; these are rests that do not print. They are useful
1211 for filling up voices that temporarily do not play. Here is the
1212 same example with a spacer rest (@code{s}) instead of a normal
1215 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1223 Again, these expressions can be nested arbitrarily.
1225 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1233 { <c g>1 ~ <c g>4 } \\
1241 Notation Reference: @ruser{Simultaneous notes}.
1247 This section introduces vocal music and simple song sheets.
1250 * Setting simple songs::
1251 * Aligning lyrics to a melody::
1252 * Lyrics to multiple staves::
1256 @node Setting simple songs
1257 @subsection Setting simple songs
1262 Music Glossary: @rglos{lyrics}.
1264 Here is the start of the melody to a nursery
1265 rhyme, @qq{Girls and boys come out to play}:
1267 @lilypond[verbatim,quote,ragged-right]
1271 d4 b8 c4 a8 d4 b8 g4
1275 The @notation{lyrics} can be set to these notes, combining both
1276 with the @code{\addlyrics} keyword. Lyrics are entered by
1277 separating each syllable with a space.
1279 @lilypond[verbatim,quote,ragged-right]
1284 d4 b8 c4 a8 d4 b8 g4
1287 Girls and boys come out to play,
1292 Note the curly brackets delimiting both the music and the lyrics,
1293 and the double angle brackets @code{<< ... >>} around the whole
1294 piece to show that the music and lyrics are to occur at the same
1297 @node Aligning lyrics to a melody
1298 @subsection Aligning lyrics to a melody
1300 Music Glossary: @rglos{melisma}, @rglos{extender line}.
1303 @cindex extender line
1307 The next line in the nursery rhyme is @q{The moon doth shine as
1308 bright as day}. Let's extend it:
1310 @lilypond[verbatim,quote,ragged-right]
1315 d4 b8 c4 a8 d4 b8 g4
1316 g8 a4 b8 c b a d4 b8 g4.
1319 Girls and boys come out to play,
1320 The moon doth shine as bright as day;
1325 We see the extra lyrics do not align properly with the notes. The
1326 word @q{shine} should be sung on two notes, not one. This is
1327 called a @notation{melisma}, a single syllable sung to more than
1328 one note. There are several ways to spread a syllable over
1329 multiple notes, the simplest being to add a slur across them (see
1330 @ref{Ties and slurs}):
1332 @lilypond[verbatim,quote,ragged-right]
1337 d4 b8 c4 a8 d4 b8 g4
1338 g8 a4 b8 c([ b)] a d4 b8 g4.
1341 Girls and boys come out to play,
1342 The moon doth shine as bright as day;
1347 Here we have also used manual beaming (the square brackets @code{[
1348 ]} ) to generate the beaming which is customarily used with lyrics
1349 (see @ref{Automatic and manual beams}).
1351 As an alternative to using slurs, the melismata may be indicated
1352 in just the lyrics by using an underscore, @code{_}, for each
1353 note that should be included in the melisma:
1355 @lilypond[verbatim,quote,ragged-right]
1360 d4 b8 c4 a8 d4 b8 g4
1361 g8 a4 b8 c[ b] a d4 b8 g4.
1364 Girls and boys come out to play,
1365 The moon doth shine _ as bright as day;
1370 If a syllable extends over several notes or a single very long
1371 note an @notation{extender line} is usually drawn from the
1372 syllable extending under all the notes for that syllable. It is
1373 entered as two underscores @code{__}. Here is an example from the
1374 first three bars of Dido's Lament, from Purcell's Dido and Æneas:
1376 @lilypond[verbatim,quote,ragged-right]
1382 b c4.( bes8 a4. g8 fis4.) g8 fis1
1386 am laid __ in earth,
1391 None of the examples so far have involved words containing more
1392 than one syllable. Such words are usually split one syllable to a
1393 note, with hyphens between syllables. Such hyphens are entered as
1394 two dashes, resulting in a centered hyphen between the syllables.
1395 Here is an example showing this and everything we have learned so
1396 far about aligning lyrics to notes.
1398 @c no ragged-right here because otherwise the hyphens get lost,
1399 @c but the example is long enough to avoid looking strange.
1400 @lilypond[verbatim,quote]
1406 d4 g4 g a8( b) g4 g4
1410 A -- way in a __ man -- ger,
1411 no __ crib for a bed, __
1416 Some lyrics, especially those in Italian, require the opposite:
1417 setting more than one syllable to a single note. This is
1418 achieved by linking the syllables together with a single
1419 underscore @code{_} (with no spaces), or enclosing them in
1420 quotes. Here's an example from Rossini's Figaro, where
1421 @q{al} has to be sung on the same note as the @q{go} of
1422 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1424 @c no ragged-right here because otherwise the hyphens get lost,
1425 @c but the example is long enough to avoid looking strange.
1426 @lilypond[verbatim,quote]
1432 c4.~ c8 d b c([ d)] b c d b c
1435 Lar -- go_al fac -- to -- tum del -- la cit -- tà
1443 Notation Reference: @ruser{Vocal music}.
1446 @node Lyrics to multiple staves
1447 @subsection Lyrics to multiple staves
1449 The simple approach using @code{\addlyrics} can be used for
1450 placing lyrics under more than one staff. Here is an
1451 example from Handel's Judas Maccabæus:
1453 @lilypond[verbatim,quote,ragged-right]
1461 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1464 Let flee -- cy flocks the hills a -- dorn, __
1468 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1471 Let flee -- cy flocks the hills a -- dorn,
1477 but scores any more complex than this simple example are
1478 better produced by separating out the staff structure
1479 from the notes and lyrics with variables. These are
1480 discussed in @ref{Organizing pieces with variables}.
1484 Notation Reference: @ruser{Vocal music}.
1489 @section Final touches
1491 This is the final section of the tutorial; it demonstrates how to
1492 add the final touches to simple pieces, and provides an
1493 introduction to the rest of the manual.
1496 * Organizing pieces with variables::
1499 * Absolute note names::
1500 * After the tutorial::
1504 @node Organizing pieces with variables
1505 @subsection Organizing pieces with variables
1507 When all of the elements discussed earlier are combined to produce
1508 larger files, the music expressions get a lot bigger. In
1509 polyphonic music with many staves, the input files can become very
1510 confusing. We can reduce this confusion by using
1513 With variables (also known as identifiers or macros), we can break
1514 up complex music expressions. A variable is assigned as
1518 namedMusic = @{ @dots{} @}
1521 The contents of the music expression @code{namedMusic} can be used
1522 later by placing a backslash in front of the name
1523 (@code{\namedMusic}, just like a normal LilyPond command).
1525 @lilypond[verbatim,quote,ragged-right]
1526 violin = \new Staff { \relative c'' {
1529 cello = \new Staff { \relative c {
1542 The name of a variable must have alphabetic characters only, no
1543 numbers, underscores, or dashes.
1545 Variables must be defined @emph{before} the main music
1546 expression, but may be used as many times as required anywhere after
1547 they have been defined. They may even be used in a later definition
1548 of another variable, giving a way of shortening the input if a
1549 section of music is repeated many times.
1551 @lilypond[verbatim,quote,ragged-right]
1552 tripletA = \times 2/3 { c,8 e g }
1553 barA = { \tripletA \tripletA \tripletA \tripletA }
1560 Variables may be used for many other types of objects in
1561 the input. For example,
1566 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1569 Depending on its contents, the variable can be used in different
1570 places. The following example uses the above variables:
1581 @node Version number
1582 @subsection Version number
1585 The @code{\version} statement records the version of LilyPond that
1586 was used to write the file:
1589 \version @w{"@version{}"}
1593 By convention, this is placed at the top of your LilyPond file.
1595 These annotations make future upgrades of LilyPond go more
1596 smoothly. Changes in the syntax are handled with a special
1597 program, @file{convert-ly}, and it uses @code{\version} to
1598 determine what rules to apply. For details, see
1599 @rprogram{Updating files with convert-ly}.
1603 @subsection Adding titles
1605 The title, composer, opus number, and similar information are
1606 entered in the @code{\header} block. This exists outside of the
1607 main music expression; the @code{\header} block is usually placed
1608 underneath the @ref{Version number}.
1611 \version @w{"@version{}"}
1619 @dots{} music @dots{}
1623 When the file is processed, the title and composer are printed
1624 above the music. More information on titling can be found in
1625 @ruser{Creating titles}.
1628 @node Absolute note names
1629 @subsection Absolute note names
1631 So far we have always used @code{\relative} to define pitches.
1632 This is the easiest way to enter most music, but another way of
1633 defining pitches exists: absolute mode.
1635 If you omit the @code{\relative}, LilyPond treats all pitches as
1636 absolute values. A @code{c'} will always mean middle C, a
1637 @code{b} will always mean the note one step below middle C, and a
1638 @code{g,} will always mean the note on the bottom staff of the
1641 @lilypond[verbatim,quote,ragged-right]
1649 Here is a four-octave scale:
1651 @lilypond[verbatim,quote,ragged-right]
1666 As you can see, writing a melody in the treble clef involves a lot
1667 of quote @code{'} marks. Consider this fragment from Mozart:
1669 @lilypond[verbatim,quote,ragged-right]
1673 cis''8. d''16 cis''8 e''4 e''8
1674 b'8. cis''16 b'8 d''4 d''8
1678 All these quotes makes the input less readable and they are a source
1679 of errors. With @code{\relative}, the previous example is much
1680 easier to read and type:
1682 @lilypond[verbatim,quote,ragged-right]
1686 cis8. d16 cis8 e4 e8
1691 If you make a mistake with an octave mark (@code{'} or @code{,})
1692 while working in @code{\relative} mode, it is very obvious -- many
1693 notes will be in the wrong octave. When working in absolute mode,
1694 a single mistake will not be as visible, and will not be as easy
1697 However, absolute mode is useful for music which has large
1698 intervals, and is extremely useful for computer-generated LilyPond
1703 @node After the tutorial
1704 @subsection After the tutorial
1706 FIXME: rewrite slightly after the rest of the LM has been
1707 stabilized. Translators, ignore this section for now.
1709 After finishing the tutorial, you should probably try writing a
1710 piece or two. Start by adding notes to one of the
1711 @ref{Templates}. If you need any notation that was not covered in
1712 the tutorial, look at the Notation Reference, starting with
1713 @ruser{Musical notation}. If you want to write for an instrument
1714 ensemble that is not covered in the templates, take a look at
1715 @ref{Extending the templates}.
1717 Once you have written a few short pieces, read the rest of the
1718 Learning Manual (chapters 3-5). There's nothing wrong with
1719 reading it now, of course! However, the rest of the Learning
1720 Manual assumes that you are familiar with LilyPond input. You may
1721 wish to skim these chapters right now, and come back to them after
1722 you have more experience.