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.
11 Tutorial guidelines: (different from policy.txt!)
12 - unless you have a really good reason, use either
13 @lilypond[verbatim,quote,ragged-right]
15 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
17 Don't use any other relative=X commands (make it a non-fragment
18 example), and don't use fragment without relative=2.
20 - use "aes" and "ees" instead of "as" and "es". I know it's not
21 correct Dutch naming, but let's not confuse people with this
22 until we get to the Basic notation chapter.
24 - Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
25 portions of the tutorial.
33 This tutorial starts with an introduction to the LilyPond music
34 language and explains how to produce printed music. After this first
35 contact we will explain how to create beautiful printed music
36 containing common musical notation.
40 * Single staff notation::
41 * Multiple notes at once::
50 This section gives a basic introduction to working with LilyPond.
55 * Working on text files::
56 * How to read the manual::
60 @node Compiling a file
61 @subsection Compiling a file
63 @qq{Compiling} is the term used for processing an input text file
64 in LilyPond format to produce a file which can be printed and
65 (optionally) a MIDI file which can be played. The first example
66 shows what a simple input text file looks like.
75 the result looks like this:
77 @c in this case we don't want verbatim
78 @lilypond[quote,ragged-right]
84 @warning{Every piece of LilyPond input needs to have
85 @strong{@{ curly braces @}} placed around the input. The braces
86 should also be surrounded by a space unless they are at the
87 beginning or end of a line to avoid ambiguities. The braces may
88 be omitted in some examples in this manual, but don't forget them
89 in your own music! For more information about the display of
90 examples in the manual, see @ref{How to read the manual}.}
92 @cindex case sensitive
93 In addition, LilyPond input is @strong{case sensitive}. @code{
94 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
99 @subheading Entering music and viewing output
102 @cindex viewing music
104 In this section we will explain what commands to run and how to
105 view or print the output.
107 Note that there are several other text editors available with
108 better support for LilyPond. For more information, see
109 @rprogram{Text editor support}.
111 @warning{The first time you ever run LilyPond, it may take a
112 minute or two because all of the system fonts have to be analyzed
113 first. After this, LilyPond will be much faster!}
115 @subsubheading MacOS X
117 If you double click @code{LilyPond.app}, it will open with an
118 example file. Save it, for example, to @file{test.ly} on your
119 Desktop, and then process it with the menu command @code{Compile >
120 Typeset File}. The resulting PDF file will be displayed on your
123 For future use of LilyPond, you should begin by selecting @q{New}
124 or @q{Open}. You must save your file before typesetting it. If
125 any errors occur in processing, please see the log window.
128 @subsubheading Windows
130 On Windows, if you double-click in the LilyPond icon on the
131 Desktop, it will open a simple text editor with an example file.
132 Save it, for example, to @file{test.ly} on your Desktop and then
133 double-click on the file to process it (the file icon looks like a
134 note). After some seconds, you will get a file @file{test.pdf} on
135 your desktop. Double-click on this PDF file to view the typeset
136 score. An alternative method to process the @file{test.ly} file
137 is to drag and drop it onto the LilyPond icon using your mouse
140 To edit an existing @file{.ly} file, right-click on it and
141 select @qq{Edit source}. To get an empty file to start from, run
142 the editor as described above and use @qq{New} in
143 the @qq{File} menu, or right-click on the desktop and select
144 @qq{New..Text Document}, change its name to a name of your choice
145 and change the file extension to @code{.ly}. Double-click the
146 icon to type in your LilyPond source code as before.
148 Double-clicking the file does not only result in a PDF file, but
149 also produces a @file{.log} file that contains some information on
150 what LilyPond has done to the file. If any errors occur, please
155 Create a text file called @file{test.ly} and enter:
163 To process @file{test.ly}, proceed as follows:
170 You will see something resembling:
177 Interpreting music...
178 Preprocessing graphical objects...
179 Finding the ideal number of pages...
180 Fitting music on 1 page...
182 Layout output to `test.ps'...
183 Converting to `test.pdf'...
187 @node Simple notation
188 @subsection Simple notation
190 LilyPond will add some notation elements automatically. In the
191 next example, we have only specified four pitches, but LilyPond
192 has added a clef, time signature, and rhythms.
194 @lilypond[verbatim,quote,ragged-right]
201 This behavior may be altered, but in most cases these automatic
207 Music Glossary: @rglos{pitch}, @rglos{interval},
208 @rglos{scale}, @rglos{middle C}, @rglos{octave},
211 The easiest way to enter notes is by using @code{\relative} mode.
212 In this mode, the octave is chosen automatically by assuming the
213 following note is always to be placed closest to the previous
214 note, i.e., it is to be placed in the octave which is within three
215 staff spaces of the previous note. We begin by entering the most
216 elementary piece of music, a @notation{scale}, in which every note
217 is within just one staff space of the previous note.
219 @lilypond[verbatim,quote,ragged-right]
220 \relative c' { % set the starting point to middle C
226 The initial note is @notation{middle C}. Each successive note is
227 placed closest to the previous note -- in other words, the first
228 @code{c} is the closest C to middle C. This is followed by the
229 closest D to the previous note. We can create melodies which have
230 larger intervals, still using only @code{\relative} mode:
232 @lilypond[verbatim,quote,ragged-right]
240 It is not necessary for the first note of the melody to start on
241 the note which specifies the starting pitch. In the previous
242 example, the first note -- the @code{d} -- is the closest D to
245 By adding (or removing) quotes @code{'} or commas @code{,} from
246 the @code{\relative c' @{} command, we can change the starting
249 @lilypond[verbatim,quote,ragged-right]
250 \relative c'' { % one octave above middle C
255 Relative mode can be confusing initially, but is the easiest way
256 to enter most melodies. Let us see how this relative calculation
257 works in practice. Starting from a B, which is on the middle line
258 in a treble clef, you can reach a C, D and E within 3 staff spaces
259 going up, and an A, G and F within 3 staff spaces going down. So
260 if the note following a B is a C, D or F it will be assumed to be
261 above the B, and an A, G or F will be assumed to be below.
263 @lilypond[verbatim,quote,ragged-right]
265 b c % c is 1 staff space up, so is the c above
266 b d % d is 2 up or 5 down, so is the d above
267 b e % e is 3 up or 4 down, so is the e above
268 b a % a is 6 up or 1 down, so is the a below
269 b g % g is 5 up or 2 down, so is the g below
270 b f % f is 4 up or 3 down, so is the f below
274 Exactly the same happens even when any of these notes are
275 sharpened or flattened. @notation{Accidentals} are
276 @strong{totally ignored} in the calculation of relative position.
277 Precisely the same staff space counting is done from a note at any
278 other position on the staff.
280 To add intervals that are larger than three staff spaces, we can
281 raise the @notation{octave} by adding a single quote @code{'} (or
282 apostrophe) to the note name. We can lower the octave by adding a
283 comma @code{,} to the note name.
285 @lilypond[verbatim,quote,ragged-right]
293 To change a note by two (or more!) octaves, we use multiple
294 @code{''} or @code{,,} -- but be careful that you use two single
295 quotes @code{''} and not one double quote @code{"}@tie{}! The
296 initial value in @code{\relative c'} may also be modified like
298 @c " - keeps quotes in order for context-sensitive editor -td
300 @subheading Durations (rhythms)
302 Music Glossary: @rglos{beam}, @rglos{duration},
303 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
306 The @notation{duration} of a note is specified by a number after
307 the note name. @code{1} for a @notation{whole note}, @code{2} for
308 a @notation{half note}, @code{4} for a @notation{quarter note} and
309 so on. @notation{Beams} are added automatically.
311 If you do not specify a duration, the previous duration is used
312 for the next note. The duration of the first note defaults to a
315 @lilypond[verbatim,quote,ragged-right]
319 a16 a a a a32 a a a a64 a a a a a a a a2
323 To create @notation{dotted notes}, add a dot @code{.} to the
324 duration number. The duration of a dotted note must be stated
325 explicitly (i.e., with a number).
327 @lilypond[verbatim,quote,ragged-right]
337 Music Glossary: @rglos{rest}.
339 A @notation{rest} is entered just like a note with the name
342 @lilypond[verbatim,quote,ragged-right]
350 @subheading Time signature
352 Music Glossary: @rglos{time signature}.
354 The @notation{time signature} can be set with the @code{\time}
357 @lilypond[verbatim,quote,ragged-right]
371 Music Glossary: @rglos{clef}.
373 The @notation{clef} can be set using the @code{\clef} command:
375 @lilypond[verbatim,quote,ragged-right]
389 @subheading All together
391 Here is a small example showing all these elements together:
393 @lilypond[verbatim,quote,ragged-right]
405 Notation Reference: @ruser{Writing pitches},
406 @ruser{Writing rhythms}, @ruser{Writing rests},
407 @ruser{Time signature}, @ruser{Clef}.
410 @node Working on text files
411 @subsection Working on text files
413 LilyPond input files are similar to source files in many common
414 programming languages. They are case sensitive, and white-space
415 is generally ignored. Expressions are formed with curly braces
416 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
419 If the previous sentences sound like nonsense, don't worry! We'll
420 explain what all these terms mean:
424 @cindex case sensitive
426 @strong{Case sensitive}:
427 it matters whether you enter a letter in lower case (e.g. @code{a,
428 b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
429 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
430 will produce an error message.
433 @strong{Whitespace insensitive}:
434 it does not matter how many spaces (or new lines) you add.
435 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
436 @tie{} @tie{} d e @}} and:
444 Of course, the previous example is hard to read. A good rule of
445 thumb is to indent code blocks with either a tab or two spaces:
454 @strong{Expressions}:
455 every piece of LilyPond input needs to have @strong{@{ curly
456 braces @}} placed around the input. These braces tell LilyPond
457 that the input is a single music expression, just like parentheses
458 @code{()} in mathematics. The braces should be surrounded by a
459 space unless they are at the beginning or end of a line to avoid
462 A LilyPond command followed by a simple expression in braces (such
463 as @code{\relative @{ @}}) also counts as a single music
468 @cindex block comment
471 a comment is a remark for the human reader of the music input; it
472 is ignored while parsing, so it has no effect on the printed
473 output. There are two types of comments. The percent symbol
474 @code{%} introduces a line comment; anything after @code{%} on
475 that line is ignored. By convention, a line comment is placed
476 @emph{above} the code it refers to.
480 % this comment refers to the Bs
484 A block comment marks a whole section of music input as a comment.
485 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
486 However, block comments do not @q{nest}. This means that you
487 cannot place a block comment inside another block comment. If you
488 try, the first @code{%@}} will terminate @emph{both} block
489 comments. The following fragment shows possible uses for
493 % notes for twinkle twinkle follow
497 This line, and the notes below
498 are ignored, since they are in a
508 @node How to read the manual
509 @subsection How to read the manual
511 LilyPond input must be surrounded by @{ @} marks or a
512 @code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
513 files}. For the rest of this manual, most examples will omit
514 this. To replicate the examples, you may copy and paste the
515 displayed input but you @strong{must} add the @code{\relative c''
520 ... example goes here...
524 Why omit the braces? Most examples in this manual can be inserted
525 into the middle of a longer piece of music. For these examples,
526 it does not make sense to add @code{\relative c'' @{ @}} -- you
527 should not place a @code{\relative} inside another
528 @code{\relative}! If we included @code{\relative c'' @{ @}}
529 around every example, you would not be able to copy a small
530 documentation example and paste it inside a longer piece of your
531 own. Most people want to add material to an existing piece, so we
532 format the manual this way.
535 @subheading Clickable examples
537 Many people learn programs by trying and fiddling around with the
538 program. This is also possible with LilyPond. If you click on a
539 picture in the HTML version of this manual, you will see the exact
540 LilyPond input that was used to generate that image. Try it on
544 @lilypond[quote,ragged-right]
546 c-\markup { \bold \huge { Click here. } }
550 By cutting and pasting everything in the @qq{ly snippet} section,
551 you have a starting template for experiments. To see exactly the
552 same output (line-width and all), copy everything from @qq{Start
553 cut-&-pastable section} to the bottom of the file.
558 There are more tips for constructing input files in
559 @ref{Suggestions for writing LilyPond files}. But it might be
560 best to read through the rest of the tutorial first.
564 @node Single staff notation
565 @section Single staff notation
567 This section introduces common notation that is used for one voice
571 * Accidentals and key signatures::
573 * Articulation and dynamics::
575 * Automatic and manual beams::
576 * Advanced rhythmic commands::
580 @node Accidentals and key signatures
581 @subsection Accidentals and key signatures
583 @subheading Accidentals
585 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
586 @rglos{double flat}, @rglos{accidental}.
588 A @notation{sharp} pitch is made by adding @code{is} to the name,
589 and a @notation{flat} pitch by adding @code{es}. As you might
590 expect, a @notation{double sharp} or @notation{double flat} is
591 made by adding @code{isis} or @code{eses}. This syntax is derived
592 from note naming conventions in Nordic and Germanic languages,
593 like German and Dutch. To use other names for
594 @notation{accidentals}, see @ruser{Note names in other languages}.
596 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
597 cis1 ees fisis, aeses
600 @cindex key signature, setting
601 @subheading Key signatures
603 Music Glossary: @rglos{key signature}, @rglos{major},
606 The @notation{key signature} is set with the command @code{\key}
607 followed by a pitch and @code{\major} or @code{\minor}.
609 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
618 @subheading Warning: key signatures and pitches
620 Music Glossary: @rglos{accidental}, @rglos{key signature},
621 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
622 @rglos{transposition}.
624 To determine whether to print an @notation{accidental}, LilyPond
625 examines the pitches and the @notation{key signature}. The key
626 signature only affects the @emph{printed} accidentals, not the
627 note's @notation{pitch}! This is a feature that often causes
628 confusion to newcomers, so let us explain it in more detail.
630 LilyPond makes a sharp distinction between musical content and
631 layout. The alteration (@notation{flat}, @notation{natural} or
632 @notation{sharp}) of a note is part of the pitch, and is therefore
633 musical content. Whether an accidental (a @emph{printed} flat,
634 natural or sharp sign) is printed in front of the corresponding
635 note is a question of layout. Layout is something that follows
636 rules, so accidentals are printed automatically according to those
637 rules. The pitches in your music are works of art, so they will
638 not be added automatically, and you must enter what you want to
643 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
649 No note has a printed accidental, but you must still add
650 @code{is} and type @code{cis} and @code{fis} in the input file.
652 The code @code{e} does not mean @qq{print a black dot just below
653 the first line of the staff.} Rather, it means @qq{there is a
654 note with pitch E-natural.} In the key of A-flat major, it
655 @emph{does} get an accidental:
657 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
662 Adding all alterations explicitly might require a little more
663 effort when typing, but the advantage is that
664 @notation{transposing} is easier, and accidentals can be printed
665 according to different conventions. For some examples how
666 accidentals can be printed according to different rules, see
667 @ruser{Automatic accidentals}.
671 Notation Reference: @ruser{Note names in other languages},
672 @ruser{Accidentals}, @ruser{Automatic accidentals},
673 @ruser{Key signature}.
675 Music Glossary: @rglos{Pitch names}.
679 @subsection Ties and slurs
684 Music Glossary: @rglos{tie}.
686 A @notation{tie} is created by appending a tilde @code{~} to the
687 first note being tied.
689 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
697 Music Glossary: @rglos{slur}.
699 A @notation{slur} is a curve drawn across many notes. The
700 starting note and ending note are marked with @code{(} and
701 @code{)} respectively.
703 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
704 d4( c16) cis( d e c cis d) e( d4)
707 @cindex slurs, phrasing
708 @cindex phrasing slurs
709 @subheading Phrasing slurs
711 Music Glossary: @rglos{slurs}, @rglos{phrasing}.
713 Slurs to indicate longer @notation{phrasing} can be entered with
714 @code{\(} and @code{\)}. You can have both @notation{slurs}
715 and phrasing slurs at the same time, but you cannot have
716 simultaneous slurs or simultaneous phrasing slurs.
718 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
719 a8(\( ais b c) cis2 b'2 a4 cis,\)
724 @cindex slurs versus ties
725 @subheading Warnings: slurs vs. ties
727 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
729 A @notation{slur} looks like a @notation{tie}, but it has a
730 different meaning. A tie simply makes the first note longer, and
731 can only be used on pairs of notes with the same pitch. Slurs
732 indicate the @notation{articulation} of notes, and can be used on
733 larger groups of notes. Slurs and ties can be nested.
735 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
736 c2~( c8 fis fis4 ~ fis2 g2)
741 Notation Reference: @ruser{Ties}, @ruser{Slurs},
742 @ruser{Phrasing slurs}.
745 @node Articulation and dynamics
746 @subsection Articulation and dynamics
751 @subheading Articulations
753 Music Glossary: @rglos{articulation}.
755 Common @notation{articulations} can be added to a note using a
756 dash @code{-} and a single character:
758 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
759 c-. c-- c-> c-^ c-+ c-_
763 @subheading Fingerings
765 Music Glossary: @rglos{fingering}.
768 Similarly, @notation{fingering} indications can be added to a note
769 using a dash (@code{-}) and the digit to be printed:
771 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
775 Articulations and fingerings are usually placed automatically, but
776 you can specify a direction by replacing the dash (@code{-}) with
777 @code{^} (up) or @code{_} (down). You can also use multiple
778 articulations on the same note. However, in most cases it is best
779 to let LilyPond determine the articulation directions.
781 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
782 c_-^1 d^. f^4_2-> e^-_+
787 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
790 @notation{Dynamic} signs are made by adding the markings (with a
791 backslash) to the note:
793 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
801 @notation{Crescendi} and @notation{decrescendi} are started with
802 the commands @code{\<} and @code{\>}. The next dynamics sign, for
803 example @code{\f}, will end the (de)crescendo, or the command
804 @code{\!} can be used:
806 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
812 Notation Reference: @ruser{Articulations and ornamentations},
813 @ruser{Fingering instructions}, @ruser{Dynamics}.
817 @subsection Adding text
819 Text may be added to your scores:
821 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
825 Extra formatting may be added with the @code{\markup} command:
827 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
828 c1^\markup{ \bold espr}
830 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
837 Notation Reference: @ruser{Writing text}.
840 @node Automatic and manual beams
841 @subsection Automatic and manual beams
843 Music Glossary: @rglos{beam}.
845 @cindex beams, by hand
846 All @notation{beams} are drawn automatically:
848 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
849 a8 ais d ees r d c16 b a8
853 If you do not like the automatic beams, they may be overridden
854 manually. Mark the first note to be beamed with @code{[} and the
855 last one with @code{]}.
857 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
858 a8[ ais] d[ ees r d] a b
863 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
866 @node Advanced rhythmic commands
867 @subsection Advanced rhythmic commands
871 @cindex partial measure
872 @subheading Partial measure
874 Music Glossary: @rglos{anacrusis}.
876 A pickup (or @notation{anacrusis}) is entered with the keyword
877 @code{\partial}. It is followed by a duration: @code{\partial 4}
878 is a quarter note pickup and @code{\partial 8} an eighth note.
880 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
889 Music Glossary: @rglos{note value}, @rglos{triplet}.
891 @notation{Tuplets} are made with the @code{\times} keyword. It
892 takes two arguments: a fraction and a piece of music. The
893 duration of the piece of music is multiplied by the fraction.
894 Triplets make notes occupy 2/3 of their notated duration, so a
895 @notation{triplet} has 2/3 as its fraction
897 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
898 \times 2/3 { f8 g a }
900 \times 2/3 { f,8 g16[ a g a] }
907 @subheading Grace notes
909 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
910 @rglos{appoggiatura}.
912 @notation{Grace notes} are created with the @code{\grace} command,
913 although they can also be created by prefixing a music expression
914 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
916 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
917 c2 \grace { a32[ b] } c2
918 c2 \appoggiatura b16 c2
919 c2 \acciaccatura b16 c2
924 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
928 @node Multiple notes at once
929 @section Multiple notes at once
931 This section introduces having more than one note at the same
932 time: multiple instruments, multiple staves for a single
933 instrument (i.e. piano), and chords.
935 Polyphony in music refers to having more than one voice occurring
936 in a piece of music. Polyphony in LilyPond refers to having more
937 than one voice on the same staff.
940 * Music expressions explained::
943 * Combining notes into chords::
944 * Single staff polyphony::
948 @node Music expressions explained
949 @subsection Music expressions explained
951 In LilyPond input files, music is represented by @emph{music
952 expressions}. A single note is a music expression:
954 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
958 Enclosing a note in braces creates a @emph{compound music
959 expression}. Here we have created a compound music expression
962 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
966 Putting a group of music expressions (e.g. notes) in braces means
967 that they are in sequence (i.e. each one follows the previous
968 one). The result is another music expression:
970 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
975 @cindex music expression
976 @subheading Analogy: mathematical expressions
978 This mechanism is similar to mathematical formulas: a big formula
979 is created by composing small formulas. Such formulas are called
980 expressions, and they can contain other expressions, so you can
981 make arbitrarily complex and large expressions. For example,
990 ((1 + 2) * 3) / (4 * 5)
993 This is a sequence of expressions, where each expression is
994 contained in the next (larger) one. The simplest expressions are
995 numbers, and larger ones are made by combining expressions with
996 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
997 Like mathematical expressions, music expressions can be nested
998 arbitrarily deep, which is necessary for complex music like
1002 @subheading Simultaneous music expressions: multiple staves
1004 Music Glossary: @rglos{polyphony}.
1006 This technique is useful for @notation{polyphonic} music. To
1007 enter music with more voices or more staves, we combine
1008 expressions in parallel. To indicate that two voices should play
1009 at the same time, simply enter a simultaneous combination of music
1010 expressions. A @q{simultaneous} music expression is formed by
1011 enclosing expressions inside @code{<<} and @code{>>}. In the
1012 following example, three sequences (all containing two separate
1013 notes) are combined simultaneously:
1015 @lilypond[verbatim,quote,ragged-right]
1025 Note that we have indented each level of the input with a
1026 different amount of space. LilyPond does not care how much (or
1027 little) space there is at the beginning of a line, but indenting
1028 LilyPond code like this makes it much easier for humans to read.
1030 @c FIXME: number of backslashes?! works in html but not pdf.
1031 @warning{each note is relative to the previous note in
1032 the input, not relative to the @code{c''} in the initial
1033 @code{\\relative} command.}
1036 @subheading Simultaneous music expressions: single staff
1038 To determine the number of staves in a piece, LilyPond looks at
1039 the first expression. If it is a single note, there is one staff;
1040 if there is a simultaneous expression, there is more than one
1043 @lilypond[verbatim,quote,ragged-right]
1046 << { e f } { c <<b d>> } >>
1050 @node Multiple staves
1051 @subsection Multiple staves
1053 LilyPond input files are constructed out of music expressions, as
1054 we saw in @ref{Music expressions explained}. If the score begins
1055 with simultaneous music expressions, LilyPond creates multiples
1056 staves. However, it is easier to see what happens if we create
1057 each staff explicitly.
1059 To print more than one staff, each piece of music that makes up a
1060 staff is marked by adding @code{\new Staff} before it. These
1061 @code{Staff} elements are then combined in parallel with @code{<<}
1064 @lilypond[verbatim,quote,ragged-right]
1067 \new Staff { \clef treble c }
1068 \new Staff { \clef bass c,, }
1073 The command @code{\new} introduces a @q{notation context.} A
1074 notation context is an environment in which musical events (like
1075 notes or @code{\clef} commands) are interpreted. For simple
1076 pieces, such notation contexts are created automatically. For
1077 more complex pieces, it is best to mark contexts explicitly.
1079 There are several types of contexts. @code{Score}, @code{Staff},
1080 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1081 lyric texts and @code{ChordNames} prints chord names.
1083 In terms of syntax, prepending @code{\new} to a music expression
1084 creates a bigger music expression. In this way it resembles the
1085 minus sign in mathematics. The formula @math{(4+5)} is an
1086 expression, so @math{-(4+5)} is a bigger expression.
1088 Time signatures entered in one staff affects all other staves by
1089 default. On the other hand, the key signature of one staff does
1090 @emph{not} affect other staves. This different default behaviour
1091 is because scores with transposing instruments are more common
1092 than polyrhythmic scores.
1094 @lilypond[verbatim,quote,ragged-right]
1097 \new Staff { \clef treble \key d \major \time 3/4 c }
1098 \new Staff { \clef bass c,, }
1107 @subsection Staff groups
1113 Music Glossary: @rglos{brace}.
1115 Piano music is typeset in two staves connected by a
1117 Printing such a staff is similar to the polyphonic example in
1118 @ref{Multiple staves}. However, now this entire expression is
1119 inserted inside a @code{PianoStaff}:
1128 Here is a small example:
1130 @lilypond[verbatim,quote,ragged-right]
1133 \new Staff { \time 2/4 c4 e g g, }
1134 \new Staff { \clef bass c,, c' e c }
1139 Other staff groupings are introduced with
1140 @code{\new GrandStaff,} suitable for orchestral
1141 scores, and @code{\new ChoirStaff,} suitable for
1142 vocal scores. These staff groups each form another
1143 type of context, one that generates the brace at the
1144 left end of every system and also controls the extent
1149 Notation Reference: @ruser{Piano music},
1150 @ruser{Displaying staves}.
1153 @node Combining notes into chords
1154 @subsection Combining notes into chords
1158 Music Glossary: @rglos{chord}.
1160 @notation{Chords} can be made by surrounding pitches with single
1161 angle brackets. Note that all the notes in a chord must have the
1162 same duration, and that duration is placed after the closing
1165 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1166 r4 <c e g>4 <c f a>2
1169 Think of chords as almost equivalent to single notes:
1170 almost everything you can attach to a single note can be attached
1171 to a chord, and everything must go @emph{outside} the angle
1172 brackets. For example, you can combine markings like beams and
1173 ties with chords. They must be placed outside the angle brackets.
1175 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1176 r4 <c e g>8[ <c f a>]~ <c f a>2
1177 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
1181 @node Single staff polyphony
1182 @subsection Single staff polyphony
1185 @cindex multiple voices
1186 @cindex voices, more -- on a staff
1187 When different melodic lines are combined on a single staff they
1188 are printed as polyphonic voices; each voice has its own stems,
1189 slurs and beams, and the top voice has the stems up, while the
1190 bottom voice has them down.
1192 Entering such parts is done by entering each voice as a sequence
1193 (with @code{@{...@}}) and combining these simultaneously,
1194 separating the voices with @code{\\}
1196 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1203 For polyphonic music typesetting, spacer rests can also be
1204 convenient; these are rests that do not print. They are useful
1205 for filling up voices that temporarily do not play. Here is the
1206 same example with a spacer rest (@code{s}) instead of a normal
1209 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1217 Again, these expressions can be nested arbitrarily.
1219 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1227 { <c g>1 ~ <c g>4 } \\
1235 Notation Reference: @ruser{Simultaneous notes}.
1241 This section introduces vocal music and simple song sheets.
1244 * Setting simple songs::
1245 * Aligning lyrics to a melody::
1246 * Lyrics to multiple staves::
1250 @node Setting simple songs
1251 @subsection Setting simple songs
1256 Music Glossary: @rglos{lyrics}.
1258 Here is the start of the melody to a nursery
1259 rhyme, @qq{Girls and boys come out to play}:
1261 @lilypond[verbatim,quote,ragged-right]
1265 d4 b8 c4 a8 d4 b8 g4
1269 The @notation{lyrics} can be set to these notes, combining both
1270 with the @code{\addlyrics} keyword. Lyrics are entered by
1271 separating each syllable with a space.
1273 @lilypond[verbatim,quote,ragged-right]
1278 d4 b8 c4 a8 d4 b8 g4
1281 Girls and boys come out to play,
1286 Note the curly brackets delimiting both the music and the lyrics,
1287 and the double angle brackets @code{<< ... >>} around the whole
1288 piece to show that the music and lyrics are to occur at the same
1291 @node Aligning lyrics to a melody
1292 @subsection Aligning lyrics to a melody
1294 Music Glossary: @rglos{melisma}, @rglos{extender line}.
1297 @cindex extender line
1301 The next line in the nursery rhyme is @q{The moon doth shine as
1302 bright as day}. Let's extend it:
1304 @lilypond[verbatim,quote,ragged-right]
1309 d4 b8 c4 a8 d4 b8 g4
1310 g8 a4 b8 c b a d4 b8 g4.
1313 Girls and boys come out to play,
1314 The moon doth shine as bright as day;
1319 We see the extra lyrics do not align properly with the notes. The
1320 word @q{shine} should be sung on two notes, not one. This is
1321 called a @notation{melisma}, a single syllable sung to more than
1322 one note. There are several ways to spread a syllable over
1323 multiple notes, the simplest being to add a slur across them (see
1324 @ref{Ties and slurs}):
1326 @lilypond[verbatim,quote,ragged-right]
1331 d4 b8 c4 a8 d4 b8 g4
1332 g8 a4 b8 c([ b)] a d4 b8 g4.
1335 Girls and boys come out to play,
1336 The moon doth shine as bright as day;
1341 Here we have also used manual beaming (the square brackets @code{[
1342 ]} ) to generate the beaming which is customarily used with lyrics
1343 (see @ref{Automatic and manual beams}).
1345 As an alternative to using slurs, the melismata may be indicated
1346 in just the lyrics by using an underscore, @code{_}, for each
1347 note that should be included in the melisma:
1349 @lilypond[verbatim,quote,ragged-right]
1354 d4 b8 c4 a8 d4 b8 g4
1355 g8 a4 b8 c[ b] a d4 b8 g4.
1358 Girls and boys come out to play,
1359 The moon doth shine _ as bright as day;
1364 If a syllable extends over several notes or a single very long
1365 note an @notation{extender line} is usually drawn from the
1366 syllable extending under all the notes for that syllable. It is
1367 entered as two underscores @code{__}. Here is an example from the
1368 first three bars of Dido's Lament, from Purcell's Dido and Æneas:
1370 @lilypond[verbatim,quote,ragged-right]
1376 b c4.( bes8 a4. g8 fis4.) g8 fis1
1380 am laid __ in earth,
1385 None of the examples so far have involved words containing more
1386 than one syllable. Such words are usually split one syllable to a
1387 note, with hyphens between syllables. Such hyphens are entered as
1388 two dashes, resulting in a centered hyphen between the syllables.
1389 Here is an example showing this and everything we have learned so
1390 far about aligning lyrics to notes.
1392 @c no ragged-right here because otherwise the hyphens get lost,
1393 @c but the example is long enough to avoid looking strange.
1394 @lilypond[verbatim,quote]
1400 d4 g4 g a8( b) g4 g4
1404 A -- way in a __ man -- ger,
1405 no __ crib for a bed, __
1410 Some lyrics, especially those in Italian, require the opposite:
1411 setting more than one syllable to a single note. This is
1412 achieved by linking the syllables together with a single
1413 underscore @code{_} (with no spaces), or enclosing them in
1414 quotes. Here's an example from Rossini's Figaro, where
1415 @q{al} has to be sung on the same note as the @q{go} of
1416 @q{Largo} in Figaro's aria @q{Largo al factotum}:
1418 @c no ragged-right here because otherwise the hyphens get lost,
1419 @c but the example is long enough to avoid looking strange.
1420 @lilypond[verbatim,quote]
1426 c4.~ c8 d b c([ d)] b c d b c
1429 Lar -- go_al fac -- to -- tum del -- la cit -- tÃ
1437 Notation Reference: @ruser{Vocal music}.
1440 @node Lyrics to multiple staves
1441 @subsection Lyrics to multiple staves
1443 The simple approach using @code{\addlyrics} can be used for
1444 placing lyrics under more than one staff. Here is an
1445 example from Handel's Judas Maccabæus:
1447 @lilypond[verbatim,quote,ragged-right]
1455 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1458 Let flee -- cy flocks the hills a -- dorn, __
1462 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1465 Let flee -- cy flocks the hills a -- dorn,
1471 but scores any more complex than this simple example are
1472 better produced by separating out the staff structure
1473 from the notes and lyrics with variables. These are
1474 discussed in @ref{Organizing pieces with variables}.
1478 Notation Reference: @ruser{Vocal music}.
1483 @section Final touches
1485 This is the final section of the tutorial; it demonstrates how to
1486 add the final touches to simple pieces, and provides an
1487 introduction to the rest of the manual.
1490 * Organizing pieces with variables::
1493 * Absolute note names::
1494 * After the tutorial::
1498 @node Organizing pieces with variables
1499 @subsection Organizing pieces with variables
1501 When all of the elements discussed earlier are combined to produce
1502 larger files, the music expressions get a lot bigger. In
1503 polyphonic music with many staves, the input files can become very
1504 confusing. We can reduce this confusion by using
1507 With variables (also known as identifiers or macros), we can break
1508 up complex music expressions. A variable is assigned as
1512 namedMusic = @{ @dots{} @}
1515 The contents of the music expression @code{namedMusic} can be used
1516 later by placing a backslash in front of the name
1517 (@code{\namedMusic}, just like a normal LilyPond command).
1519 @lilypond[verbatim,quote,ragged-right]
1520 violin = \new Staff { \relative c'' {
1523 cello = \new Staff { \relative c {
1536 The name of a variable must have alphabetic characters only, no
1537 numbers, underscores, or dashes.
1539 Variables must be defined @emph{before} the main music
1540 expression, but may be used as many times as required anywhere after
1541 they have been defined. They may even be used in a later definition
1542 of another variable, giving a way of shortening the input if a
1543 section of music is repeated many times.
1545 @lilypond[verbatim,quote,ragged-right]
1546 tripletA = \times 2/3 { c,8 e g }
1547 barA = { \tripletA \tripletA \tripletA \tripletA }
1554 Variables may be used for many other types of objects in
1555 the input. For example,
1560 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1563 Depending on its contents, the variable can be used in different
1564 places. The following example uses the above variables:
1575 @node Version number
1576 @subsection Version number
1579 The @code{\version} statement records the version of LilyPond that
1580 was used to write the file:
1587 By convention, this is placed at the top of your LilyPond file.
1589 These annotations make future upgrades of LilyPond go more
1590 smoothly. Changes in the syntax are handled with a special
1591 program, @file{convert-ly}, and it uses @code{\version} to
1592 determine what rules to apply. For details, see
1593 @rprogram{Updating files with convert-ly}.
1597 @subsection Adding titles
1599 The title, composer, opus number, and similar information are
1600 entered in the @code{\header} block. This exists outside of the
1601 main music expression; the @code{\header} block is usually placed
1602 underneath the @ref{Version number}.
1613 @dots{} music @dots{}
1617 When the file is processed, the title and composer are printed
1618 above the music. More information on titling can be found in
1619 @ruser{Creating titles}.
1622 @node Absolute note names
1623 @subsection Absolute note names
1625 So far we have always used @code{\relative} to define pitches.
1626 This is the easiest way to enter most music, but another way of
1627 defining pitches exists: absolute mode.
1629 If you omit the @code{\relative}, LilyPond treats all pitches as
1630 absolute values. A @code{c'} will always mean middle C, a
1631 @code{b} will always mean the note one step below middle C, and a
1632 @code{g,} will always mean the note on the bottom staff of the
1635 @lilypond[verbatim,quote,ragged-right]
1643 Here is a four-octave scale:
1645 @lilypond[verbatim,quote,ragged-right]
1660 As you can see, writing a melody in the treble clef involves a lot
1661 of quote @code{'} marks. Consider this fragment from Mozart:
1663 @lilypond[verbatim,quote,ragged-right]
1667 cis''8. d''16 cis''8 e''4 e''8
1668 b'8. cis''16 b'8 d''4 d''8
1672 All these quotes makes the input less readable and they are a source
1673 of errors. With @code{\relative}, the previous example is much
1674 easier to read and type:
1676 @lilypond[verbatim,quote,ragged-right]
1680 cis8. d16 cis8 e4 e8
1685 If you make a mistake with an octave mark (@code{'} or @code{,})
1686 while working in @code{\relative} mode, it is very obvious -- many
1687 notes will be in the wrong octave. When working in absolute mode,
1688 a single mistake will not be as visible, and will not be as easy
1691 However, absolute mode is useful for music which has large
1692 intervals, and is extremely useful for computer-generated LilyPond
1697 @node After the tutorial
1698 @subsection After the tutorial
1700 FIXME: rewrite slightly after the rest of the LM has been
1701 stabilized. Translators, ignore this section for now.
1703 After finishing the tutorial, you should probably try writing a
1704 piece or two. Start by adding notes to one of the
1705 @ref{Templates}. If you need any notation that was not covered in
1706 the tutorial, look at the Notation Reference, starting with
1707 @ruser{Musical notation}. If you want to write for an instrument
1708 ensemble that is not covered in the templates, take a look at
1709 @ref{Extending the templates}.
1711 Once you have written a few short pieces, read the rest of the
1712 Learning Manual (chapters 3-5). There's nothing wrong with
1713 reading it now, of course! However, the rest of the Learning
1714 Manual assumes that you are familiar with LilyPond input. You may
1715 wish to skim these chapters right now, and come back to them after
1716 you have more experience.