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 how to produce printed music. After this first
35 contact we will explain how to create common musical notation.
39 * Single staff notation::
40 * Multiple notes at once::
49 This section gives a basic introduction to working with LilyPond.
54 * Working on text files::
55 * How to read the tutorial::
59 @node Compiling a file
60 @subsection Compiling a file
62 The first example demonstrates how to start working with LilyPond.
63 To create sheet music, we write a text file that specifies the
64 notation. For example, if we write:
73 the result looks like this:
75 @c in this case we don't want verbatim
76 @lilypond[quote,ragged-right]
82 @warning{Every piece of LilyPond input needs to have
83 @strong{@{ curly braces @}} placed around the input. The braces
84 should also be surrounded by a space unless they are at the
85 beginning or end of a line to avoid ambiguities. The braces may
86 be omitted in some examples in this manual, but don't forget them
87 in your own music! For more information about the display of
88 examples in the manual, see @ref{How to read the tutorial}.}
90 @cindex case sensitive
91 In addition, LilyPond input is @strong{case sensitive}. @code{
92 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
97 @subheading Entering music and viewing output
100 @cindex viewing music
102 In this section we will explain what commands to run and how to
103 view or print the output.
105 Note that there are several other text editors available with
106 better support for LilyPond. For more information, see
107 @rprogram{Text editor support}.
109 @warning{the first time you ever run LilyPond, it may take a
110 minute or two because all of the system fonts have to be analyzed
111 first. After this, LilyPond will be much faster!}
113 @subsubheading MacOS X
115 If you double click @code{LilyPond.app}, it will open with an
116 example file. Save it, for example, to @file{test.ly} on your
117 Desktop, and then process it with the menu command @samp{Compile >
118 Typeset File}. The resulting PDF file will be displayed on your
121 For future use of LilyPond, you should begin by selecting @q{New}
122 or @q{Open}. You must save your file before typesetting it. If
123 any errors occur in processing, please see the log window.
126 @subsubheading Windows
128 On Windows, if you double-click in the LilyPond icon on the
129 Desktop, it will open a simple text editor with an example file.
130 Save it, for example, to @file{test.ly} on your Desktop and then
131 double-click on the file to process it (the file icon looks like a
132 note). After some seconds, you will get a file @file{test.pdf} on
133 your desktop. Double-click on this PDF file to view the typeset
134 score. An alternative method to process the @file{test.ly} file
135 is to drag and drop it onto the LilyPond icon using your mouse
138 To edit an existing @file{.ly} file, right-click on it and
139 select @qq{Edit source}. To get an empty file to start from, run
140 the editor as described above and use @qq{New} in
143 Double-clicking the file does not only result in a PDF file, but
144 also produces a @file{.log} file that contains some information on
145 what LilyPond has done to the file. If any errors occur, please
150 Create a file (such as @file{test.ly}) and enter:
158 To process @file{test.ly}, proceed as follows:
165 You will see something resembling:
172 Interpreting music...
173 Preprocessing graphical objects...
174 Finding the ideal number of pages...
175 Fitting music on 1 page...
177 Layout output to `test.ps'...
178 Converting to `test.pdf'...
182 @node Simple notation
183 @subsection Simple notation
185 LilyPond will add some notation elements automatically. In the
186 next example, we have only specified four pitches, but LilyPond
187 has added a clef, time signature, and rhythms.
189 @lilypond[verbatim,quote,ragged-right]
196 This behavior may be altered, but in most cases these automatic
202 Music glossary: @rglos{pitch}, @rglos{interval}, @rglos{fourth},
203 @rglos{scale}, @rglos{middle C}, @rglos{octave}.
205 The easiest way to enter notes is by using @code{\relative} mode.
206 In this mode, the @notation{interval} between the previous note and
207 the current note is assumed to be within a @notation{fourth}. We
208 begin by entering the most elementary piece of music, a
211 @lilypond[verbatim,quote,ragged-right]
218 The initial note is @notation{middle C}. Each successive note is
219 within a fourth of the previous note -- in other words, the first
220 @code{c} is the closest C to middle C. This is followed by the
221 closest D to the previous note. We can create melodies which
222 have larger intervals:
224 @lilypond[verbatim,quote,ragged-right]
232 As you may notice, this example does not start on middle C. The first
233 note -- the @code{d} -- is the closest D to middle C.
235 To add intervals that are larger than a fourth, we can raise
236 the @notation{octave} by adding a single quote @code{'} (or apostrophe)
237 to the note name. We can lower the octave by adding a comma @code{,} to
240 @lilypond[verbatim,quote,ragged-right]
248 To change a note by two (or more!) octaves, we use multiple
249 @code{''} or @code{,,} -- but be careful that you use two single
250 quotes @code{''} and not one double quote @code{"}@tie{}! The
251 initial value in @code{\relative c'} may also be modified like
255 @subheading Durations (rhythms)
257 Music glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note},
258 @rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
260 The @notation{duration} of a note is specified by a number after
261 the note name. @samp{1} for a @notation{whole note}, @samp{2} for
262 a @notation{half note}, @samp{4} for a @notation{quarter note} and
263 so on. @notation{Beams} are added automatically.
265 @lilypond[verbatim,quote,ragged-right]
269 a16 a a a a32 a a a a64 a a a a a a a a2
274 If you do not specify a duration, the previous duration is used
275 for the next note. The duration of the first note defaults to a
278 To create @notation{dotted notes}, add a dot @samp{.} to the duration
281 @lilypond[verbatim,quote,ragged-right]
291 Music glossary: @rglos{rest}.
293 A @notation{rest} is entered just like a note with the name @samp{r}:
295 @lilypond[verbatim,quote,ragged-right]
303 @subheading Time signature
305 Music glossary: @rglos{time signature}.
307 The @notation{time signature} can be set with the @code{\time}
310 @lilypond[verbatim,quote,ragged-right]
324 Music glossary: @rglos{clef}.
326 The @notation{clef} can be set using the @code{\clef} command:
328 @lilypond[verbatim,quote,ragged-right]
342 @subheading All together
344 Here is a small example showing all these elements together:
346 @lilypond[verbatim,quote,ragged-right]
358 Notation reference: @ruser{Writing pitches}, @ruser{Writing rhythms},
359 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
362 @c HERE's where I started
364 @node Working on text files
365 @subsection Working on text files
367 LilyPond input files are similar to source files in many common
368 programming languages. They are case sensitive, and white-space
369 is generally equivalent. Expressions are formed with curly braces
370 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
373 If the previous sentence sounds like nonsense, don't worry! We'll
374 explain what all these terms mean:
378 @cindex case sensitive
380 @strong{Case sensitive}:
381 it matters whether you enter a letter in lower case (e.g. @code{a,
382 b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
383 lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
384 will produce an error message.
387 @strong{Whitespace insensitive}:
388 it does not matter how many spaces (or new lines) you add.
389 @code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
390 @tie{} @tie{} d e @}} and:
398 Of course, the previous example is hard to read. A good rule of
399 thumb is to indent code blocks with either a tab or two spaces:
408 @strong{Expressions:}
409 Every piece of LilyPond input needs to have @strong{@{ curly
410 braces @}} placed around the input. These braces tell LilyPond
411 that the input is a single music expression, just like parentheses
412 @samp{()} in mathematics. The braces should be surrounded by a
413 space unless they are at the beginning or end of a line to avoid
416 A function (such as @code{\relative @{ @}}) also counts as a
417 single music expression.
421 @cindex block comment
424 A comment is a remark for the human reader of the music input; it
425 is ignored while parsing, so it has no effect on the printed
426 output. There are two types of comments. The percent symbol
427 @samp{%} introduces a line comment; anything after @samp{%} on
428 that line is ignored. A block comment marks a whole section of
429 music input as a comment. Anything that is enclosed in @code{%@{}
430 and @code{%@}} is ignored. (Comments do not nest.) The following
431 fragment shows possible uses for comments:
434 % notes for twinkle twinkle follow
438 This line, and the notes below
439 are ignored, since they are in a
448 There are more tips for constructing input files in
449 @ref{Suggestions for writing LilyPond files}.
452 @node How to read the tutorial
453 @subsection How to read the tutorial
455 LilyPond input must be surrounded by @{ @} marks or a
456 @code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
457 files}. For the rest of this manual, most examples will omit
458 this. To replicate the examples, you may copy and paste the
459 displayed input but you @strong{must} add the @code{\relative c''
464 ... example goes here...
468 Why omit the braces? Most examples in this manual can be inserted
469 into the middle of a longer piece of music. For these examples,
470 it does not make sense to add @code{\relative c'' @{ @}} -- you
471 should not place a @code{\relative} inside another
472 @code{\relative}! If we included @code{\relative c'' @{ @}}
473 around every example, you would not be able to copy a small
474 documentation example and paste it inside a longer piece of your
475 own. Most people want to add material to an existing piece, so we
476 format the manual this way.
479 @subheading Clickable examples
481 Many people learn programs by trying and fiddling around with the
482 program. This is also possible with LilyPond. If you click on a
483 picture in the HTML version of this manual, you will see the exact
484 LilyPond input that was used to generate that image. Try it on
488 @lilypond[quote,ragged-right]
490 c-\markup { \bold \huge { Click here. } }
494 By cutting and pasting everything in the @qq{ly snippet} section,
495 you have a starting template for experiments. To see exactly the
496 same output (line-width and all), copy everything from @qq{Start
497 cut-&-pastable section} to the bottom of the file.
500 @node Single staff notation
501 @section Single staff notation
503 This section introduces common notation that is used for one voice
507 * Relative note names::
508 * Accidentals and key signatures::
510 * Articulation and dynamics::
512 * Automatic and manual beams::
513 * Advanced rhythmic commands::
517 @node Relative note names
518 @subsection Relative note names
520 Music glossary: @rglos{octave}, @rglos{fourth}, @rglos{fifth}.
522 LilyPond calculates the pitch of each note relative to the
523 previous one@footnote{There is another mode of entering pitches,
524 @ruser{Absolute octave entry}. However, in practice relative mode is
525 much easier and safer to use.}, as we saw in @ref{Simple
526 notation}. If no extra @notation{octave} marks (@code{'} and
527 @code{,}) are added, it assumes that each pitch is within a
528 @notation{fourth} of the previous note.
530 LilyPond examines pitches based on the note names -- in other
531 words, an augmented fourth is @emph{not} treated the same as a
532 diminished fifth. If we begin at a C, then an F-sharp will be placed a
533 higher than the C, while a G-flat will be placed lower than the C.
534 An F-sharp is written as @code{fis} and a G-flat is written as
535 @code{ges} as we will see in @ref{Accidentals and key signatures}.
537 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
545 @item Relative octaves
546 see @ruser{Relative octave entry}.
548 see @ruser{Octave check}.
553 @node Accidentals and key signatures
554 @subsection Accidentals and key signatures
556 @subheading Accidentals
558 Music glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
559 @rglos{double flat}, @rglos{accidental}.
561 A @notation{sharp} pitch is made by adding @samp{is} to the name, and
562 a @notation{flat} pitch by adding @samp{es}. As you might expect, a
563 @notation{double sharp} or @notation{double flat} is made by adding
564 @samp{isis} or @samp{eses}. This syntax derived from note
565 naming conventions in Nordic and Germanic languages, like German
566 and Dutch. To use other names for @notation{accidentals}, see
567 @ruser{Note names in other languages}.
569 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
570 cis1 ees fisis, aeses
573 @cindex key signature, setting
574 @subheading Key signatures
576 Music glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}.
578 The @notation{key signature} is set with the command @code{\key}
579 followed by a pitch and @code{\major} or @code{\minor}.
581 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
590 @subheading Warning: key signatures and pitches
592 Music glossary: @rglos{accidental}, @rglos{key signature},
593 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
594 @rglos{transposition}.
596 To determine whether to print an @notation{accidental}, LilyPond
597 examines the pitches and the @notation{key signature}. The key
598 signature only affects the @emph{printed} accidentals, not the note's
599 @notation{pitch}! This is a feature that often causes confusion to
600 newcomers, so let us explain it in more detail.
602 LilyPond makes a sharp distinction between musical content and
603 layout. The alteration (@notation{flat}, @notation{natural} or
604 @notation{sharp}) of a note is part of the pitch, and is therefore
605 musical content. Whether an accidental (a @emph{printed} flat, natural
606 or sharp sign) is printed in front of the corresponding note is a
607 question of layout. Layout is something that follows rules, so
608 accidentals are printed automatically according to those rules. The
609 pitches in your music are works of art, so they will not be added
610 automatically, and you must enter what you want to hear.
614 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
620 No note has a printed accidental, but you must still add the
621 @samp{is} to @code{cis} and @code{fis}.
623 The code @samp{e} does not mean @qq{print a black dot just below
624 the first line of the staff.} Rather, it means @qq{there is a
625 note with pitch E-natural.} In the key of A-flat major, it
626 @emph{does} get an accidental:
628 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
633 Adding all alterations explicitly might require a little more
634 effort when typing, but the advantage is that
635 @notation{transposing} is easier, and accidentals can be printed
636 according to different conventions. For some examples how
637 accidentals can be printed according to different rules, see
638 @ruser{Automatic accidentals}.
644 see @ruser{Accidentals}, and @ruser{Automatic accidentals}.
646 see @ruser{Key signature}
648 see @rglos{Pitch names}.
654 @subsection Ties and slurs
659 Music glossary: @rglos{tie}.
661 A @notation{tie} is created by appending a tilde @samp{~} to the
662 first note being tied
664 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
672 Music glossary: @rglos{slur}.
674 A @notation{slur} is a curve drawn across many notes. The starting
675 note and ending note are marked with @samp{(} and @samp{)}
678 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
679 d4( c16) cis( d e c cis d) e( d4)
682 @cindex slurs, phrasing
683 @cindex phrasing slurs
684 @subheading Phrasing slurs
686 Music glossary: @rglos{phrasing}, @rglos{legato}.
688 Slurs to indicate longer @notation{phrasing} can be entered with
689 @code{\(} and @code{\)}. You can have both @notation{legato} slurs and
690 phrasing slurs at the same time, but you cannot have simultaneous legato
691 slurs or simultaneous phrasing slurs.
693 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
694 a8(\( ais b c) cis2 b'2 a4 cis,\)
699 @cindex slurs versus ties
700 @subheading Warnings: slurs vs. ties
702 Music glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
704 A @notation{slur} looks like a @notation{tie}, but it has a different
705 meaning. A tie simply makes the first note longer, and can only be
706 used on pairs of notes with the same pitch. Slurs indicate the
707 @notation{articulation} of notes, and can be used on larger groups of
708 notes. Slurs and ties can be nested.
710 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
711 c2~( c8 fis fis4 ~ fis2 g2)
722 see @ruser{Phrasing slurs}.
727 @node Articulation and dynamics
728 @subsection Articulation and dynamics
733 @subheading Articulations
735 Music glossary: @rglos{articulation}.
737 Common @notation{articulations} can be added to a note using a
738 dash @samp{-} and a single character:
740 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
741 c-. c-- c-> c-^ c-+ c-_
745 @subheading Fingerings
747 Music glossary: @rglos{fingering}.
749 Similarly, @notation{fingering} indications can be added to a note using
750 a dash (@samp{-}) and the digit to be printed:
752 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
756 Articulations and fingerings are usually placed automatically, but
757 you can specify a direction using @samp{^} (up) or @samp{_}
758 (down). You can also use multiple articulations on the same note.
759 However, in most cases it is best to let LilyPond determine the
760 articulation directions.
762 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
763 c_-^1 d^. f^4_2-> e^-_+
768 Music glossary: @rglos{dynamics}, @rglos{crescendo},
771 @notation{Dynamic} signs are made by adding the markings (with a
772 backslash) to the note:
774 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
782 @notation{Crescendi} and @notation{decrescendi} are started with
783 the commands @code{\<} and @code{\>}. An ending dynamic, for
784 example @code{\f}, will finish the (de)crescendo, or the command
785 @code{\!} can be used:
787 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
795 see @ruser{Articulations}.
797 see @ruser{Fingering instructions}.
799 see @ruser{Dynamics} (Notation reference) and @rglos{dynamics}
807 @subsection Adding text
809 Text may be added to your scores:
811 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
815 Extra formatting may be added with the @code{\markup} command:
817 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
818 c1^\markup{ \bold espr}
820 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
825 @c Kurt: leave this alone for now.
829 Notation reference: @ruser{Writing text}.
832 @node Automatic and manual beams
833 @subsection Automatic and manual beams
835 Music glossary: @rglos{beam}.
837 @cindex beams, by hand
838 All @notation{beams} are drawn automatically:
840 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
841 a8 ais d ees r d c16 b a8
845 If you do not like the automatic beams, they may be overridden
846 manually. Mark the first note to be beamed with @samp{[} and the
847 last one with @samp{]}.
849 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
850 a8[ ais] d[ ees r d] a b
856 @item Automatic beams
857 see @ruser{Automatic beams}.
859 see @ruser{Manual beams}.
864 @node Advanced rhythmic commands
865 @subsection Advanced rhythmic commands
869 @cindex partial measure
870 @subheading Partial measure
872 Music glossary: @rglos{anacrusis}.
874 A pickup (or @notation{anacrusis}) is entered with the keyword
875 @code{\partial}. It is followed by a duration: @code{\partial 4}
876 is a quarter note pickup and @code{\partial 8} an eighth note.
878 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
887 Music glossary: @rglos{note value}, @rglos{triplet}.
889 @notation{Tuplets} are made with the @code{\times} keyword. It
890 takes two arguments: a fraction and a piece of music. The
891 duration of the piece of music is multiplied by the fraction.
892 Triplets make notes occupy 2/3 of their notated duration, so a
893 @notation{triplet} has 2/3 as its fraction
895 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
896 \times 2/3 { f8 g a }
898 \times 2/3 { f,8 g16[ a g a] }
905 @subheading Grace notes
907 Music glossary: @rglos{grace notes}, @rglos{appoggiatura}.
909 @notation{Grace notes} are created with the @code{\grace} command,
910 although they can also be created by prefixing a music expression
911 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
913 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
914 c2 \grace { a32[ b] } c2
915 c2 \appoggiatura b16 c2
916 c2 \acciaccatura b16 c2
923 see @ruser{Grace notes},
932 @node Multiple notes at once
933 @section Multiple notes at once
935 This section introduces having more than one note at the same
936 time: multiple instruments, multiple staves for a single
937 instrument (i.e. piano), and chords.
939 Polyphony in music refers to having more than one voice occurring
940 in a piece of music. Polyphony in LilyPond refers to having more
941 than one voice on the same staff.
944 * Music expressions explained::
947 * Combining notes into chords::
948 * Single staff polyphony::
952 @node Music expressions explained
953 @subsection Music expressions explained
955 In LilyPond input files, music is represented by @emph{music
956 expressions}. A single note is a music expression:
958 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
962 Enclosing a note in braces creates a @emph{compound music
963 expression}. Here we have created a compound music expression
966 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
970 Putting a group of music expressions (e.g. notes) in braces means
971 that they are in sequence (i.e. each one follows the previous
972 one). The result is another music expression:
974 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
978 @subheading Simultaneous music expressions: multiple staves
980 Music glossary: @rglos{polyphony}.
982 This technique is useful for @notation{polyphonic} music. To
983 enter music with more voices or more staves, we combine
984 expressions in parallel. To indicate that two voices should play
985 at the same time, simply enter a simultaneous combination of music
986 expressions. A @q{simultaneous} music expression is formed by
987 enclosing expressions inside @code{<<} and @code{>>}. In the
988 following example, three sequences (all containing two separate
989 notes) are combined simultaneously:
991 @lilypond[verbatim,quote,ragged-right]
1001 Note that we have indented each level of the input with a
1002 different amount of space. LilyPond does not care how much (or
1003 little) space there is at the beginning of a line, but indenting
1004 LilyPond code like this makes it much easier for humans to read.
1006 @warning{each note is relative to the previous note in
1007 the input, not relative to the @code{c''} in the initial
1008 @code{\\relative} command.}
1011 @subheading Simultaneous music expressions: single staff
1013 To determine the number of staves in a piece, LilyPond looks at
1014 the first expression. If it is a single note, there is one staff;
1015 if there is a simultaneous expression, there is more than one
1018 @lilypond[verbatim,quote,ragged-right]
1021 << { e f } { c <<b d>> } >>
1026 @cindex music expression
1027 @subheading Analogy: mathematical expressions
1029 This mechanism is similar to mathematical formulas: a big formula
1030 is created by composing small formulas. Such formulas are called
1031 expressions, and their definition is recursive so you can make
1032 arbitrarily complex and large expressions. For example,
1041 ((1 + 2) * 3) / (4 * 5)
1044 This is a sequence of expressions, where each expression is
1045 contained in the next (larger) one. The simplest expressions are
1046 numbers, and larger ones are made by combining expressions with
1047 operators (like @samp{+}, @samp{*} and @samp{/}) and parentheses.
1048 Like mathematical expressions, music expressions can be nested
1049 arbitrarily deep, which is necessary for complex music like
1053 @node Multiple staves
1054 @subsection Multiple staves
1056 LilyPond input files are constructed out of music expressions, as
1057 we saw in @ref{Music expressions explained}. If the score begins
1058 with simultaneous music expressions, LilyPond creates multiples
1059 staves. However, it is easier to see what happens if we create
1060 each staff explicitly.
1062 To print more than one staff, each piece of music that makes up a
1063 staff is marked by adding @code{\new Staff} before it. These
1064 @code{Staff} elements are then combined in parallel with @code{<<}
1067 @lilypond[verbatim,quote,ragged-right]
1070 \new Staff { \clef treble c }
1071 \new Staff { \clef bass c,, }
1076 The command @code{\new} introduces a @q{notation context.} A
1077 notation context is an environment in which musical events (like
1078 notes or @code{\clef} commands) are interpreted. For simple
1079 pieces, such notation contexts are created automatically. For
1080 more complex pieces, it is best to mark contexts explicitly.
1082 There are several types of contexts. @code{Score}, @code{Staff},
1083 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1084 lyric texts and @code{ChordNames} prints chord names.
1086 In terms of syntax, prepending @code{\new} to a music expression
1087 creates a bigger music expression. In this way it resembles the
1088 minus sign in mathematics. The formula @math{(4+5)} is an
1089 expression, so @math{-(4+5)} is a bigger expression.
1091 Time signatures entered in one staff affects all other
1092 staves@footnote{This behavior may be changed if desired; for
1093 details, see @ruser{Polymetric notation}.}. On the other hand,
1094 the key signature of one staff does @emph{not} affect other
1097 @lilypond[verbatim,quote,ragged-right]
1100 \new Staff { \clef treble \time 3/4 c }
1101 \new Staff { \clef bass \key d \major c,, }
1110 @subsection Piano staves
1112 @cindex staff switch, manual
1113 @cindex cross staff voice, manual
1115 Music glossary: @rglos{brace}.
1117 Piano music is typeset in two staves connected by a
1119 Printing such a staff is similar to the polyphonic example in
1120 @ref{Multiple staves}. However, now this entire expression is
1121 inserted inside a @code{PianoStaff}:
1130 Here is a small example:
1132 @lilypond[verbatim,quote,ragged-right]
1135 \new Staff { \time 2/4 c4 e g g, }
1136 \new Staff { \clef bass c,, c' e c }
1143 See @ruser{Piano music}.
1147 @node Combining notes into chords
1148 @subsection Combining notes into chords
1152 Music glossary: @rglos{chord}.
1154 @notation{Chords} can be made by surrounding pitches with single
1155 angle brackets. Angle brackets are the symbols @samp{<} and
1158 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1159 r4 <c e g>4 <c f a>2
1162 You can combine markings like beams and ties with chords. They
1163 must be placed outside the angle brackets
1165 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1166 r4 <c e g>8[ <c f a>]~ <c f a>2
1169 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1170 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
1174 @node Single staff polyphony
1175 @subsection Single staff polyphony
1178 @cindex multiple voices
1179 @cindex voices, more -- on a staff
1180 When different melodic lines are combined on a single staff they
1181 are printed as polyphonic voices; each voice has its own stems,
1182 slurs and beams, and the top voice has the stems up, while the
1183 bottom voice has them down.
1185 Entering such parts is done by entering each voice as a sequence
1186 (with @code{@{...@}}) and combining these simultaneously,
1187 separating the voices with @code{\\}
1189 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1196 For polyphonic music typesetting, spacer rests can also be
1197 convenient; these are rests that do not print. They are useful
1198 for filling up voices that temporarily do not play. Here is the
1199 same example with a spacer rest (@samp{s}) instead of a normal
1202 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1210 Again, these expressions can be nested arbitrarily.
1212 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
1220 { <c g>1 ~ <c g>4 } \\
1228 See @ruser{Simultaneous notes}.
1235 This section introduces vocal music and simple song sheets.
1238 * Setting simple songs::
1239 * Aligning lyrics to a melody::
1240 * Lyrics to multiple staves::
1244 @node Setting simple songs
1245 @subsection Setting simple songs
1250 Music glossary: @rglos{lyrics}.
1252 Here is the start of the melody to a nursery
1253 rhyme, @qq{Girls and boys come out to play}:
1255 @lilypond[verbatim,quote,ragged-right]
1259 d4 b8 c4 a8 d4 b8 g4
1263 The @notation{lyrics} can be set to these notes, combining both
1264 with the @code{\addlyrics} keyword. Lyrics are entered by
1265 separating each syllable with a space.
1267 @lilypond[verbatim,quote,ragged-right]
1272 d4 b8 c4 a8 d4 b8 g4
1275 Girls and boys come out to play,
1280 Note the curly brackets delimiting both the music and the lyrics,
1281 and the angle brackets @code{<< ... >>} around the whole piece to
1282 show that the music and lyrics are to occur at the same time.
1284 @node Aligning lyrics to a melody
1285 @subsection Aligning lyrics to a melody
1287 Music glossary: @rglos{melisma}, @rglos{extender line}.
1290 @cindex extender line
1294 The next line in the nursery rhyme is @q{The moon doth shine as
1295 bright as day}. Let's extend it:
1297 @lilypond[verbatim,quote,ragged-right]
1302 d4 b8 c4 a8 d4 b8 g4
1303 g8 a4 b8 c b a d4 b8 g4.
1306 Girls and boys come out to play,
1307 The moon doth shine as bright as day;
1312 We see the extra lyrics do not align properly with the notes. The
1313 word @q{shine} should be sung on two notes, not one. This is
1314 called a @notation{melisma}, a single syllable sung to more than one
1315 note. There are several ways to spread a syllable over multiple
1316 notes, the simplest being to add a slur across them (see @ref{Ties
1319 @lilypond[verbatim,quote,ragged-right]
1324 d4 b8 c4 a8 d4 b8 g4
1325 g8 a4 b8 c([ b)] a d4 b8 g4.
1328 Girls and boys come out to play,
1329 The moon doth shine as bright as day;
1334 Here we have also used manual beaming (the square brackets @code{[
1335 ]} ) to generate the beaming which is customarily used with lyrics
1336 (see @ref{Automatic and manual beams}).
1338 If a syllable extends over several notes or a single very long
1339 note an @notation{extender line} is usually drawn from the syllable
1340 extending under all the notes for that syllable. It is entered as
1341 two underscores @code{__}. Here is an example from the first
1342 three bars of Dido's Lament, from Purcell's Dido and Æneas:
1344 @lilypond[verbatim,quote,ragged-right]
1350 b c4.( bes8 a4. g8 fis4.) g8 fis1
1354 am laid __ in earth,
1359 None of the examples so far have involved words containing more
1360 than one syllable. Such words are usually split one syllable to a
1361 note, with hyphens between syllables. Such hyphens are entered as
1362 two dashes, resulting in a centered hyphen between the syllables.
1363 Here is an example showing this and everything we have learned so
1364 far about aligning lyrics to notes.
1366 @c no ragged-right here because otherwise the hyphens get lost,
1367 @c but the example is long enough to avoid looking strange.
1368 @lilypond[verbatim,quote]
1374 d4 g4 g a8( b) g4 g4
1378 A -- way in a __ man -- ger,
1379 no __ crib for a bed, __
1384 Some lyrics, especially those in Italian, require the opposite:
1385 setting more than one syllable to a single note. This is
1386 achieved by linking the syllables together with a single
1387 underscore @code{_} (with no spaces), or enclosing them in
1388 quotes. Here's an example from Rossini's Figaro, where
1389 @q{al} has to be sung on the same note as the @q{go} of
1390 @q{Largo} in Figaro's aria @q{Largo al factotum}:
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 c4.~ c8 d b c([ d)] b c d b c
1403 Lar -- go_al fac -- to -- tum del -- la cit -- tĂ
1411 More options, such as inserting explicit rhythms into lyrics,
1412 inserting lyric ties (e.g., between @q{go al}) above,
1413 alternative ways of handling melismata,
1414 and adding extra verses,
1415 are discussed in @ruser{Vocal music}.
1418 @node Lyrics to multiple staves
1419 @subsection Lyrics to multiple staves
1421 The simple approach using @code{\addlyrics} can be used for
1422 placing lyrics under more than one staff. Here is an
1423 example from Handel's Judas Maccabæus:
1425 @lilypond[verbatim,quote,ragged-right]
1433 c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
1436 Let flee -- cy flocks the hills a -- dorn, __
1440 r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
1443 Let flee -- cy flocks the hills a -- dorn,
1448 but scores any more complex than this simple example are
1449 better produced by separating out the staff structure
1450 from the notes and lyrics with variables. These are
1451 discussed later (see @ref{Organizing pieces with variables}).
1455 More options, such as putting multiple stanzas below the score,
1456 setting choral music, and lyrics to divided voices,
1457 are discussed in @ruser{Vocal music}.
1462 @section Final touches
1464 This is the final section of the tutorial; it demonstrates how to
1465 add the final touches to simple pieces, and provides an
1466 introduction to the rest of the manual.
1471 * Absolute note names::
1472 * Organizing pieces with variables::
1473 * After the tutorial::
1474 * How to read the manual::
1478 @node Version number
1479 @subsection Version number
1482 The @code{\version} statement records the version of LilyPond that
1483 was used to write the file:
1490 By convention, this is placed at the top of your LilyPond file.
1492 These annotations make future upgrades of LilyPond go more
1493 smoothly. Changes in the syntax are handled with a special
1494 program, @file{convert-ly}, and it uses @code{\version} to
1495 determine what rules to apply. For details, see
1496 @rprogram{Updating files with convert-ly}.
1500 @subsection Adding titles
1502 The title, composer, opus number, and similar information are
1503 entered in the @code{\header} block. This exists outside of the
1504 main music expression; the @code{\header} block is usually placed
1505 underneath the @ref{Version number}.
1516 @dots{} music @dots{}
1520 When the file is processed, the title and composer are printed
1521 above the music. More information on titling can be found in
1522 @ruser{Creating titles}.
1525 @node Absolute note names
1526 @subsection Absolute note names
1528 So far we have always used @code{\relative} to define pitches.
1529 This is the easiest way to enter most music, but another way of
1530 defining pitches exists: absolute mode.
1532 If you omit the @code{\relative}, LilyPond treats all pitches as
1533 absolute values. A @code{c'} will always mean middle C, a
1534 @code{b} will always mean the note one step below middle C, and a
1535 @code{g,} will always mean the note on the bottom staff of the
1538 @lilypond[verbatim,quote,ragged-right]
1546 Here is a four-octave scale:
1548 @lilypond[verbatim,quote,ragged-right]
1563 As you can see, writing a melody in the treble clef involves a lot
1564 of quote @code{'} marks. Consider this fragment from Mozart:
1566 @lilypond[verbatim,quote,ragged-right]
1570 cis''8. d''16 cis''8 e''4 e''8
1571 b'8. cis''16 b'8 d''4 d''8
1575 All these quotes makes the input less readable and it is a source
1576 of errors. With @code{\relative}, the previous example is much
1579 @lilypond[verbatim,quote,ragged-right]
1583 cis8. d16 cis8 e4 e8
1588 If you make a mistake with an octave mark (@code{'} or @code{,})
1589 while working in @code{\relative} mode, it is very obvious -- many
1590 notes will be in the wrong octave. When working in absolute mode,
1591 a single mistake will not be as visible, and will not be as easy
1594 However, absolute mode is useful for music which has large
1595 intervals, and is extremely useful for computer-generated LilyPond
1599 @node Organizing pieces with variables
1600 @subsection Organizing pieces with variables
1602 When all of the elements discussed earlier are combined to produce
1603 larger files, the music expressions get a lot bigger. In
1604 polyphonic music with many staves, the input files can become very
1605 confusing. We can reduce this confusion by using
1608 With variables (also known as identifiers or macros), we can break
1609 up complex music expressions. An variable is assigned as
1613 namedMusic = @{ @dots{} @}
1616 The contents of the music expression @code{namedMusic} can be used
1617 later by placing a backslash in front of the name
1618 (@code{\namedMusic}, just like a normal LilyPond command).
1619 Variables must be defined @emph{before} the main music
1622 @lilypond[verbatim,quote,ragged-right]
1623 violin = \new Staff { \relative c'' {
1626 cello = \new Staff { \relative c {
1639 The name of an variable must have alphabetic characters only, no
1640 numbers, underscores, or dashes.
1642 It is possible to use variables for many other types of objects in
1643 the input. For example,
1648 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1651 Depending on its contents, the variable can be used in different
1652 places. The following example uses the above variables:
1663 @node After the tutorial
1664 @subsection After the tutorial
1666 After finishing the tutorial, you should probably try writing a
1667 piece or two. Start by adding notes to one of the @ref{Templates}.
1668 If you need any notation that was not covered in the
1669 tutorial, look at the Notation Reference, starting with
1670 @ruser{Musical notation}. If you want to write for an instrument
1671 ensemble that is not covered in the templates, take a look at
1672 @ref{Extending the templates}.
1674 Once you have written a few short pieces, read the rest of the
1675 Learning Manual (chapters 3-5). There's nothing wrong with
1676 reading it now, of course! However, the rest of the Learning
1677 Manual assumes that you are familiar with LilyPond input. You may
1678 wish to skim these chapters right now, and come back to them after
1679 you have more experience.
1682 @node How to read the manual
1683 @subsection How to read the manual
1685 Many examples in the tutorial omitted a @code{\relative c'' @{
1686 ... @}} around the printed example, as we saw in
1687 @ref{How to read the tutorial}.
1689 In the rest of the manual, we are much more lax about the printed
1690 examples: sometimes they may have omitted a @code{\relative c'' @{
1691 ... @}}, but other times a different initial pitch may be used
1692 (such as @code{c'} or @code{c,,}), and in some cases the whole
1693 example is in absolute note mode! However, ambiguities like this
1694 only exist where the pitches are not important. In any example
1695 where the pitch matters, we have explicitly stated
1696 @code{\relative} or absolute-mode @code{@{ @}}.
1698 If you are still confused about the exact LilyPond input that was
1699 used in an example, read the HTML version (if you are not already
1700 doing so) and click on the picture of the music. This will
1701 display the exact input that LilyPond used to generate this
1704 For information about the structure of the rest of the manual, see
1705 @ref{About this manual}.