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]
17 @lilypond[verbatim,quote,relative=2]
19 Don't use any other relative=X commands.
21 - use "aes" and "ees" instead of "as" and "es". I know it's not
22 correct Dutch naming, but let's not confuse people with this
23 until we get to the Basic notation chapter.
25 - Add "Music Glossary: @rglos{foo}" to the *top* of the relevant
26 portions of the tutorial.
34 This tutorial starts with an introduction to the LilyPond music
35 language and explains how to produce printed music. After this first
36 contact we will explain how to create beautiful printed music
37 containing common musical notation.
41 * Single staff notation::
42 * Multiple notes at once::
51 This section gives a basic introduction to working with LilyPond.
56 * Working on input files::
57 * How to read the manual::
61 @node Compiling a file
62 @subsection Compiling a file
66 @cindex example, first
67 @cindex case sensitive
69 @qq{Compiling} is the term used for processing an input file
70 in LilyPond format to produce a file which can be printed and
71 (optionally) a MIDI file which can be played. LilyPond input
72 files are simple text files. The first example
73 shows what a simple input file looks like.
75 To create sheet music, we write an input file that specifies the
76 notation. For example, if we write:
85 the result looks like this:
87 @c in this case we don't want verbatim
94 @warning{Notes and lyrics in LilyPond input must always be
95 surrounded by @strong{@{ curly braces @}}. The braces
96 should also be surrounded by a space unless they are at the
97 beginning or end of a line to avoid ambiguities. The braces may
98 be omitted in some examples in this manual, but don't forget them
99 in your own music! For more information about the display of
100 examples in the manual, see @ref{How to read the manual}.}
102 In addition, LilyPond input is @strong{case sensitive}.
103 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
104 produce an error message.
108 @subheading Entering music and viewing output
111 @cindex viewing music
113 @cindex running LilyPond under MacOS X
114 @cindex MacOS X, running LilyPond
115 @cindex running LilyPond under Windows
116 @cindex Windows, running LilyPond
117 @cindex running LilyPond under Unix
118 @cindex Unix, running LilyPond
120 In this section we will explain what commands to run and how to
121 view or print the output.
123 Note that there are several other text editors available with
124 better support for LilyPond. For more information, see
125 @rprogram{Text editor support}.
127 @warning{The first time you ever run LilyPond, it may take a
128 minute or two because all of the system fonts have to be analyzed
129 first. After this, LilyPond will be much faster!}
131 @subsubheading MacOS X
133 If you double click @command{LilyPond.app}, it will open with an
134 example file. Save it, for example, to @file{test.ly} on your
135 Desktop, and then process it with the menu command
136 @w{@code{Compile > Typeset File}}. The resulting PDF file will be
137 displayed on your screen.
139 For future use of LilyPond, you should begin by selecting @q{New}
140 or @q{Open}. You must save your file before typesetting it. If
141 any errors occur in processing, please see the log window.
144 @subsubheading Windows
146 On Windows, if you double-click in the LilyPond icon on the
147 Desktop, it will open a simple text editor with an example file.
148 Save it, for example, to @file{test.ly} on your Desktop and then
149 double-click on the file to process it (the file icon looks like a
150 note). After some seconds, you will get a file @file{test.pdf} on
151 your desktop. Double-click on this PDF file to view the typeset
152 score. An alternative method to process the @file{test.ly} file
153 is to drag and drop it onto the LilyPond icon using your mouse
156 To edit an existing @file{.ly} file, right-click on it and
157 select @qq{Edit source}. To get an empty file to start from, run
158 the editor as described above and use @qq{New} in
159 the @qq{File} menu, or right-click on the desktop and select
160 @qq{New..Text Document}, change its name to a name of your choice
161 and change the file extension to @code{.ly}. Double-click the
162 icon to type in your LilyPond source code as before.
164 Double-clicking the file does not only result in a PDF file, but
165 also produces a @file{.log} file that contains some information on
166 what LilyPond has done to the file. If any errors occur, please
171 Create a text file called @file{test.ly} and enter:
179 To process @file{test.ly}, proceed as follows:
186 You will see something resembling:
190 GNU LilyPond @version{}
193 Interpreting music...
194 Preprocessing graphical objects...
195 Finding the ideal number of pages...
196 Fitting music on 1 page...
198 Layout output to `test.ps'...
199 Converting to `test.pdf'...
203 @node Simple notation
204 @subsection Simple notation
206 @cindex simple notation
207 @cindex notation, simple
209 LilyPond will add some notation elements automatically. In the
210 next example, we have only specified four pitches, but LilyPond
211 has added a clef, time signature, and rhythms.
213 @lilypond[verbatim,quote]
220 This behavior may be altered, but in most cases these automatic
227 @cindex relative mode
228 @cindex quote, single
230 @cindex accidentals and relative mode
231 @cindex relative mode, and accidentals
238 Music Glossary: @rglos{pitch}, @rglos{interval},
239 @rglos{scale}, @rglos{middle C}, @rglos{octave},
242 The easiest way to enter notes is by using @code{\relative} mode.
243 In this mode, the octave is chosen automatically by assuming the
244 following note is always to be placed closest to the previous
245 note, i.e., it is to be placed in the octave which is within three
246 staff spaces of the previous note. We begin by entering the most
247 elementary piece of music, a @notation{scale}, in which every note
248 is within just one staff space of the previous note.
250 @lilypond[verbatim,quote]
251 % set the starting point to middle C
258 The initial note is @notation{middle C}. Each successive note is
259 placed closest to the previous note -- in other words, the first
260 @code{c} is the closest C to middle C. This is followed by the
261 closest D to the previous note. We can create melodies which have
262 larger intervals, still using only @code{\relative} mode:
264 @lilypond[verbatim,quote]
272 It is not necessary for the first note of the melody to start on
273 the note which specifies the starting pitch. In the previous
274 example, the first note -- the @code{d} -- is the closest D to
277 By adding (or removing) quotes @code{'} or commas @code{,} from
278 the @code{\relative c' @{} command, we can change the starting
281 @lilypond[verbatim,quote]
282 % one octave above middle C
288 Relative mode can be confusing initially, but is the easiest way
289 to enter most melodies. Let us see how this relative calculation
290 works in practice. Starting from a B, which is on the middle line
291 in a treble clef, you can reach a C, D and E within 3 staff spaces
292 going up, and an A, G and F within 3 staff spaces going down. So
293 if the note following a B is a C, D or E it will be assumed to be
294 above the B, and an A, G or F will be assumed to be below.
296 @lilypond[verbatim,quote]
298 b c % c is 1 staff space up, so is the c above
299 b d % d is 2 up or 5 down, so is the d above
300 b e % e is 3 up or 4 down, so is the e above
301 b a % a is 6 up or 1 down, so is the a below
302 b g % g is 5 up or 2 down, so is the g below
303 b f % f is 4 up or 3 down, so is the f below
307 Exactly the same happens even when any of these notes are
308 sharpened or flattened. @notation{Accidentals} are
309 @strong{totally ignored} in the calculation of relative position.
310 Precisely the same staff space counting is done from a note at any
311 other position on the staff.
313 To add intervals that are larger than three staff spaces, we can
314 raise the @notation{octave} by adding a single quote @code{'} (or
315 apostrophe) to the note name. We can lower the octave by adding a
316 comma @code{,} to the note name.
318 @lilypond[verbatim,quote]
326 To change a note by two (or more!) octaves, we use multiple
327 @code{''} or @code{,,} -- but be careful that you use two single
328 quotes @code{''} and not one double quote @code{"}@tie{}! The
329 initial value in @w{@code{\relative c'}} may also be modified like
331 @c " - keeps quotes in order for context-sensitive editor -td
333 @subheading Durations (rhythms)
335 @cindex note durations
342 @cindex notating durations
344 Music Glossary: @rglos{beam}, @rglos{duration},
345 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
348 The @notation{duration} of a note is specified by a number after
349 the note name. @code{1} for a @notation{whole note}, @code{2} for
350 a @notation{half note}, @code{4} for a @notation{quarter note} and
351 so on. @notation{Beams} are added automatically.
353 If you do not specify a duration, the previous duration is used
354 for the next note. The duration of the first note defaults to a
357 @lilypond[verbatim,quote]
361 a16 a a a a32 a a a a64 a a a a a a a a2
365 To create @notation{dotted notes}, add a dot @code{.} to the
366 duration number. The duration of a dotted note must be stated
367 explicitly (i.e., with a number).
369 @lilypond[verbatim,quote]
380 @cindex notating rests
382 Music Glossary: @rglos{rest}.
384 A @notation{rest} is entered just like a note with the name
387 @lilypond[verbatim,quote]
395 @subheading Time signature
397 @cindex time signature
402 Music Glossary: @rglos{time signature}.
404 The @notation{time signature} can be set with the @code{\time}
407 @lilypond[verbatim,quote]
430 Music Glossary: @rglos{clef}.
432 The @notation{clef} can be set using the @code{\clef} command:
434 @lilypond[verbatim,quote]
448 @subheading All together
450 Here is a small example showing all these elements together:
452 @lilypond[verbatim,quote]
464 Notation Reference: @ruser{Writing pitches},
465 @ruser{Writing rhythms}, @ruser{Writing rests},
466 @ruser{Time signature}, @ruser{Clef}.
469 @node Working on input files
470 @subsection Working on input files
473 @cindex braces, curly
476 @cindex comment, line
477 @cindex block comment
478 @cindex comment, line
479 @cindex case sensitive
480 @cindex whitespace insensitive
485 @funindex %@{ ... %@}
487 LilyPond input files are similar to source files in many common
488 programming languages. They are case sensitive, and white-space
489 is generally ignored. Expressions are formed with curly braces
490 @{ @}, and comments are denoted with @code{%} or
491 @w{@code{%@{ ... %@}}}.
493 If the previous sentences sound like nonsense, don't worry! We'll
494 explain what all these terms mean:
499 @strong{Case sensitive}:
500 it matters whether you enter a letter in lower case (e.g.
501 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
502 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
503 @w{@code{@{ C D E @}}} will produce an error message.
506 @strong{Whitespace insensitive}:
507 it does not matter how many spaces (or new lines) you add.
508 @w{@code{@{ c d e @}}} means the same thing as
509 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
517 Of course, the previous example is hard to read. A good rule of
518 thumb is to indent code blocks with either a tab or two spaces:
527 @strong{Expressions}:
528 every piece of LilyPond input needs to have @strong{@{ curly
529 braces @}} placed around the input. These braces tell LilyPond
530 that the input is a single music expression, just like parentheses
531 @code{()} in mathematics. The braces should be surrounded by a
532 space unless they are at the beginning or end of a line to avoid
535 A LilyPond command followed by a simple expression in braces (such
536 as @w{@code{\relative @{ @}}}) also counts as a single music
541 @cindex block comment
544 a comment is a remark for the human reader of the music input; it
545 is ignored while parsing, so it has no effect on the printed
546 output. There are two types of comments. The percent symbol
547 @code{%} introduces a line comment; anything after @code{%} on
548 that line is ignored. By convention, a line comment is placed
549 @emph{above} the code it refers to.
553 % this comment refers to the Bs
557 A block comment marks a whole section of music input as a comment.
558 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
559 However, block comments do not @q{nest}. This means that you
560 cannot place a block comment inside another block comment. If you
561 try, the first @code{%@}} will terminate @emph{both} block
562 comments. The following fragment shows possible uses for
566 % notes for twinkle twinkle follow
570 This line, and the notes below are ignored,
571 since they are in a block comment.
580 @node How to read the manual
581 @subsection How to read the manual
583 @cindex how to read the manual
584 @cindex manual, reading
585 @cindex reading the manual
586 @cindex examples, clickable
587 @cindex clickable examples
588 @cindex tips for constructing files
590 @cindex constructing files, tips
591 @cindex files, tips for constructing
593 LilyPond input must be surrounded by @{ @} marks or a
594 @w{@code{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
595 input files}. For the rest of this manual, most examples will
596 omit this. To replicate the examples, you may copy and paste the
597 displayed input, but you @strong{must} add the
598 @w{@code{\relative c'' @{ @}}} like this:
602 ... example goes here...
606 Why omit the braces? Most examples in this manual can be inserted
607 into the middle of a longer piece of music. For these examples,
608 it does not make sense to add @w{@code{\relative c'' @{ @}}} --
609 you should not place a @code{\relative} inside another
610 @code{\relative}! If we included @w{@code{\relative c'' @{ @}}}
611 around every example, you would not be able to copy a small
612 documentation example and paste it inside a longer piece of your
613 own. Most people want to add material to an existing piece, so we
614 format the manual this way.
617 @subheading Clickable examples
619 Many people learn programs by trying and fiddling around with the
620 program. This is also possible with LilyPond. If you click on a
621 picture in the HTML version of this manual, you will see the exact
622 LilyPond input that was used to generate that image. Try it on
628 c-\markup { \bold \huge { Click here. } }
632 By cutting and pasting everything in the @qq{ly snippet} section,
633 you have a starting template for experiments. To see exactly the
634 same output (line-width and all), copy everything from @qq{Start
635 cut-&-pastable section} to the bottom of the file.
639 There are more tips for constructing input files in
640 @ref{Suggestions for writing LilyPond input files}. But it might be
641 best to read through the rest of the tutorial first.
645 @node Single staff notation
646 @section Single staff notation
648 This section introduces common notation that is used for one voice
652 * Accidentals and key signatures::
654 * Articulation and dynamics::
656 * Automatic and manual beams::
657 * Advanced rhythmic commands::
661 @node Accidentals and key signatures
662 @subsection Accidentals and key signatures
664 @subheading Accidentals
667 @cindex accidentals and key signatures
670 @cindex sharp, double
680 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
681 @rglos{double flat}, @rglos{accidental}.
683 A @notation{sharp} pitch is made by adding @code{is} to the name,
684 and a @notation{flat} pitch by adding @code{es}. As you might
685 expect, a @notation{double sharp} or @notation{double flat} is
686 made by adding @code{isis} or @code{eses}. This syntax is derived
687 from note naming conventions in Nordic and Germanic languages,
688 like German and Dutch. To use other names for
689 @notation{accidentals}, see @ruser{Note names in other languages}.
691 @lilypond[verbatim,quote,relative=2]
692 cis1 ees fisis, aeses
695 @cindex key signature, setting
696 @subheading Key signatures
698 @cindex key signature
701 @cindex accidentals and key signature
702 @cindex content vs. layout
703 @cindex layout vs. content
712 Music Glossary: @rglos{key signature}, @rglos{major},
715 The @notation{key signature} is set with the command @code{\key}
716 followed by a pitch and @code{\major} or @code{\minor}.
718 @lilypond[verbatim,quote,relative=2]
727 @subheading Warning: key signatures and pitches
729 Music Glossary: @rglos{accidental}, @rglos{key signature},
730 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
731 @rglos{transposition}.
733 To determine whether to print an @notation{accidental}, LilyPond
734 examines the pitches and the @notation{key signature}. The key
735 signature only affects the @emph{printed} accidentals, not the
736 note's @notation{pitch}! This is a feature that often causes
737 confusion to newcomers, so let us explain it in more detail.
739 LilyPond makes a sharp distinction between musical content and
740 layout. The alteration (@notation{flat}, @notation{natural sign} or
741 @notation{sharp}) of a note is part of the pitch, and is therefore
742 musical content. Whether an accidental (a @emph{printed} flat,
743 natural or sharp sign) is printed in front of the corresponding
744 note is a question of layout. Layout is something that follows
745 rules, so accidentals are printed automatically according to those
746 rules. The pitches in your music are works of art, so they will
747 not be added automatically, and you must enter what you want to
752 @lilypond[verbatim,quote,relative=2]
758 No note has a printed accidental, but you must still add
759 @code{is} and type @code{cis} and @code{fis} in the input file.
761 The code @code{e} does not mean @qq{print a black dot just on
762 the first line of the staff.} Rather, it means @qq{there is a
763 note with pitch E-natural.} In the key of A-flat major, it
764 @emph{does} get an accidental:
766 @lilypond[verbatim,quote,relative=2]
771 Adding all alterations explicitly might require a little more
772 effort when typing, but the advantage is that
773 @notation{transposing} is easier, and accidentals can be printed
774 according to different conventions. For some examples how
775 accidentals can be printed according to different rules, see
776 @ruser{Automatic accidentals}.
780 Notation Reference: @ruser{Note names in other languages},
781 @ruser{Accidentals}, @ruser{Automatic accidentals},
782 @ruser{Key signature}.
784 Music Glossary: @rglos{Pitch names}.
788 @subsection Ties and slurs
792 @cindex slur, phrasing
793 @cindex phrasing slur
802 Music Glossary: @rglos{tie}.
804 A @notation{tie} is created by appending a tilde @code{~} to the
805 first note being tied.
807 @lilypond[verbatim,quote,relative=2]
815 Music Glossary: @rglos{slur}.
817 A @notation{slur} is a curve drawn across many notes. The
818 starting note and ending note are marked with @code{(} and
819 @code{)} respectively.
821 @lilypond[verbatim,quote,relative=2]
822 d4( c16) cis( d e c cis d) e( d4)
825 @subheading Phrasing slurs
827 Music Glossary: @rglos{slur}, @rglos{phrasing}.
829 Slurs to indicate longer @notation{phrasing} can be entered with
830 @code{\(} and @code{\)}. You can have both @notation{slurs}
831 and phrasing slurs at the same time, but you cannot have
832 simultaneous slurs or simultaneous phrasing slurs.
834 @lilypond[verbatim,quote,relative=2]
835 a8(\( ais b c) cis2 b'2 a4 cis,\)
840 @cindex slurs versus ties
841 @subheading Warnings: slurs vs. ties
843 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
845 A @notation{slur} looks like a @notation{tie}, but it has a
846 different meaning. A tie simply makes the first note longer, and
847 can only be used on pairs of notes with the same pitch. Slurs
848 indicate the @notation{articulation} of notes, and can be used on
849 larger groups of notes. Slurs and ties can be nested.
851 @lilypond[verbatim,quote,relative=2]
852 c2~( c8 fis fis4 ~ fis2 g2)
857 Notation Reference: @ruser{Ties}, @ruser{Slurs},
858 @ruser{Phrasing slurs}.
861 @node Articulation and dynamics
862 @subsection Articulation and dynamics
865 @subheading Articulations
871 Music Glossary: @rglos{articulation}.
873 Common @notation{articulations} can be added to a note using a
874 dash @code{-} and a single character:
876 @lilypond[verbatim,quote,relative=2]
877 c-. c-- c-> c-^ c-+ c-_
880 @subheading Fingerings
887 Music Glossary: @rglos{fingering}.
889 Similarly, @notation{fingering} indications can be added to a note
890 using a dash (@code{-}) and the digit to be printed:
892 @lilypond[verbatim,quote,relative=2]
896 Articulations and fingerings are usually placed automatically, but
897 you can specify a direction by replacing the dash (@code{-}) with
898 @code{^} (up) or @code{_} (down). You can also use multiple
899 articulations on the same note. However, in most cases it is best
900 to let LilyPond determine the articulation directions.
902 @lilypond[verbatim,quote,relative=2]
903 c_-^1 d^. f^4_2-> e^-_+
925 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
928 @notation{Dynamic} signs are made by adding the markings (with a
929 backslash) to the note:
931 @lilypond[verbatim,quote,relative=2]
936 @notation{Crescendi} and @notation{decrescendi} are started with
937 the commands @code{\<} and @code{\>}. The next dynamics sign, for
938 example @code{\f}, will end the (de)crescendo, or the command
939 @code{\!} can be used:
941 @lilypond[verbatim,quote,relative=2]
947 Notation Reference: @ruser{Articulations and ornamentations},
948 @ruser{Fingering instructions}, @ruser{Dynamics}.
952 @subsection Adding text
961 Text may be added to your scores:
963 @lilypond[verbatim,quote,relative=2]
967 Extra formatting may be added with the @code{\markup} command:
969 @lilypond[verbatim,quote,relative=2]
970 c1^\markup{ \bold espr}
972 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
979 Notation Reference: @ruser{Writing text}.
982 @node Automatic and manual beams
983 @subsection Automatic and manual beams
986 @cindex automatic beams
988 @cindex beams, automatic
989 @cindex beams, manual
990 @cindex beams, by hand
995 @funindex \autoBeamOff
996 @funindex autoBeamOff
997 @funindex \autoBeamOn
1000 Music Glossary: @rglos{beam}.
1002 All @notation{beams} are drawn automatically:
1004 @lilypond[verbatim,quote,relative=2]
1005 a8 ais d ees r d c16 b a8
1008 If you do not like the automatic beams, they may be overridden
1009 manually. To correct just an occasional beam mark the first note
1010 to be beamed with @code{[} and the last one with @code{]}.
1012 @lilypond[verbatim,quote,relative=2]
1013 a8[ ais] d[ ees r d] a b
1016 If you want to turn off automatic beaming entirely or for an
1017 extended section of music, use the command @code{\autoBeamOff}
1018 to turn off automatic beaming and @code{\autoBeamOn} to turn it
1021 @lilypond[verbatim,quote,relative=2]
1030 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
1033 @node Advanced rhythmic commands
1034 @subsection Advanced rhythmic commands
1036 @subheading Partial measure
1040 @cindex partial measure
1045 Music Glossary: @rglos{anacrusis}.
1047 A pickup (or @notation{anacrusis}) is entered with the keyword
1048 @code{\partial}. It is followed by a duration: @code{\partial 4}
1049 is a quarter note pickup and @code{\partial 8} an eighth note.
1051 @lilypond[verbatim,quote,relative=2]
1064 Music Glossary: @rglos{note value}, @rglos{triplet}.
1066 @notation{Tuplets} are made with the @code{\times} keyword. It
1067 takes two arguments: a fraction and a piece of music. The
1068 duration of the piece of music is multiplied by the fraction.
1069 Triplets make notes occupy 2/3 of their notated duration, so a
1070 @notation{triplet} has 2/3 as its fraction
1072 @lilypond[verbatim,quote,relative=2]
1073 \times 2/3 { f8 g a }
1074 \times 2/3 { c r c }
1075 \times 2/3 { f,8 g16[ a g a] }
1076 \times 2/3 { d4 a8 }
1079 @subheading Grace notes
1082 @cindex acciaccatura
1083 @cindex appoggiatura
1087 @funindex \acciaccatura
1088 @funindex acciaccatura
1089 @funindex \appoggiatura
1090 @funindex acciaccatura
1092 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
1093 @rglos{appoggiatura}.
1095 @notation{Grace notes} are created with the @code{\grace} command,
1096 although they can also be created by prefixing a music expression
1097 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
1099 @lilypond[verbatim,quote,relative=2]
1100 c2 \grace { a32[ b] } c2
1101 c2 \appoggiatura b16 c2
1102 c2 \acciaccatura b16 c2
1107 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
1111 @node Multiple notes at once
1112 @section Multiple notes at once
1114 This section introduces having more than one note at the same
1115 time: multiple instruments, multiple staves for a single
1116 instrument (i.e. piano), and chords.
1118 Polyphony in music refers to having more than one voice occurring
1119 in a piece of music. Polyphony in LilyPond refers to having more
1120 than one voice on the same staff.
1123 * Music expressions explained::
1126 * Combining notes into chords::
1127 * Single staff polyphony::
1131 @node Music expressions explained
1132 @subsection Music expressions explained
1134 @cindex music expression
1135 @cindex expression, music
1136 @cindex compound music expression
1137 @cindex music expression, compound
1139 In LilyPond input files, music is represented by @emph{music
1140 expressions}. A single note is a music expression:
1142 @lilypond[verbatim,quote,relative=2]
1146 Enclosing a note in braces creates a @emph{compound music
1147 expression}. Here we have created a compound music expression
1150 @lilypond[verbatim,quote,relative=2]
1154 Putting a group of music expressions (e.g. notes) in braces means
1155 that they are in sequence (i.e. each one follows the previous
1156 one). The result is another music expression:
1158 @lilypond[verbatim,quote,relative=2]
1162 @subheading Analogy: mathematical expressions
1164 This mechanism is similar to mathematical formulas: a big formula
1165 is created by composing small formulas. Such formulas are called
1166 expressions, and they can contain other expressions, so you can
1167 make arbitrarily complex and large expressions. For example,
1176 ((1 + 2) * 3) / (4 * 5)
1179 This is a sequence of expressions, where each expression is
1180 contained in the next (larger) one. The simplest expressions are
1181 numbers, and larger ones are made by combining expressions with
1182 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
1183 Like mathematical expressions, music expressions can be nested
1184 arbitrarily deep, which is necessary for complex music like
1188 @subheading Simultaneous music expressions: multiple staves
1190 @cindex multiple staves
1191 @cindex staves, multiple
1193 @cindex combining expressions in parallel
1194 @cindex parallel expressions
1195 @cindex expressions, parallel
1196 @cindex relative notes and simultaneous music
1197 @cindex relative notes and parallel expressions
1198 @cindex simultaneous music and relative notes
1199 @cindex parallel expressions and relative notes
1205 Music Glossary: @rglos{polyphony}.
1207 This technique is useful for @notation{polyphonic} music. To
1208 enter music with more voices or more staves, we combine
1209 expressions in parallel. To indicate that two voices should play
1210 at the same time, simply enter a simultaneous combination of music
1211 expressions. A @q{simultaneous} music expression is formed by
1212 enclosing expressions inside @code{<<} and @code{>>}. In the
1213 following example, three sequences (all containing two separate
1214 notes) are combined simultaneously:
1216 @lilypond[verbatim,quote]
1226 Note that we have indented each level of the input with a
1227 different amount of space. LilyPond does not care how much (or
1228 little) space there is at the beginning of a line, but indenting
1229 LilyPond code like this makes it much easier for humans to read.
1231 @warning{each note is relative to the previous note in
1232 the input, not relative to the @code{c''} in the initial
1233 @code{@bs{}relative} command.}
1236 @subheading Simultaneous music expressions: single staff
1238 To determine the number of staves in a piece, LilyPond looks at
1239 the beginning of the first expression. If is a single note, there
1240 is one staff; if there is a simultaneous expression, there is more
1243 @lilypond[verbatim,quote]
1246 << { e f } { c <<b d>> } >>
1250 @node Multiple staves
1251 @subsection Multiple staves
1253 @cindex multiple staves
1254 @cindex staves, multiple
1256 @cindex context, notation
1257 @cindex notation context
1259 @funindex \new Staff
1267 @funindex ChordNames
1269 LilyPond input files are constructed out of music expressions, as
1270 we saw in @ref{Music expressions explained}. If the score begins
1271 with simultaneous music expressions, LilyPond creates multiples
1272 staves. However, it is easier to see what happens if we create
1273 each staff explicitly.
1275 To print more than one staff, each piece of music that makes up a
1276 staff is marked by adding @code{\new Staff} before it. These
1277 @code{Staff} elements are then combined in parallel with @code{<<}
1280 @lilypond[verbatim,quote]
1283 \new Staff { \clef treble c }
1284 \new Staff { \clef bass c,, }
1289 The command @code{\new} introduces a @q{notation context.} A
1290 notation context is an environment in which musical events (like
1291 notes or @code{\clef} commands) are interpreted. For simple
1292 pieces, such notation contexts are created automatically. For
1293 more complex pieces, it is best to mark contexts explicitly.
1295 There are several types of contexts. @code{Score}, @code{Staff},
1296 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
1297 lyric texts and @code{ChordNames} prints chord names.
1299 In terms of syntax, prepending @code{\new} to a music expression
1300 creates a bigger music expression. In this way it resembles the
1301 minus sign in mathematics. The formula @math{(4+5)} is an
1302 expression, so @math{-(4+5)} is a bigger expression.
1304 Time signatures entered in one staff affects all other staves by
1305 default. On the other hand, the key signature of one staff does
1306 @emph{not} affect other staves. This different default behavior
1307 is because scores with transposing instruments are more common
1308 than polyrhythmic scores.
1310 @lilypond[verbatim,quote]
1313 \new Staff { \clef treble \key d \major \time 3/4 c }
1314 \new Staff { \clef bass c,, }
1323 @subsection Staff groups
1326 @cindex staff, piano
1328 @cindex staff, choir
1330 @cindex staff, grand
1333 @funindex PianoStaff
1334 @funindex GrandStaff
1335 @funindex ChoirStaff
1337 Music Glossary: @rglos{brace}.
1339 Piano music is typeset in two staves connected by a
1341 Printing such a staff is similar to the polyphonic example in
1342 @ref{Multiple staves}. However, now this entire expression is
1343 inserted inside a @code{PianoStaff}:
1352 Here is a small example:
1354 @lilypond[verbatim,quote]
1357 \new Staff { \time 2/4 c4 e g g, }
1358 \new Staff { \clef bass c,, c' e c }
1363 Other staff groupings are introduced with @code{\new GrandStaff},
1364 suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
1365 suitable for vocal scores. These staff groups each form another
1366 type of context, one that generates the brace at the left end of
1367 every system and also controls the extent of bar lines.
1371 Notation Reference: @ruser{Keyboard and other multi-staff
1373 @ruser{Displaying staves}.
1376 @node Combining notes into chords
1377 @subsection Combining notes into chords
1380 @cindex note durations in chords
1386 Music Glossary: @rglos{chord}.
1388 We saw earlier how notes can be combined into @notation{chords} by
1389 indicating they are simultaneous by enclosing them in double angle
1390 brackets. However, the normal way of indicating a chord is to
1391 surround the pitches with @emph{single} angle brackets. Note that
1392 all the notes in a chord must have the same duration, and that the
1393 duration is placed after the closing bracket.
1395 @lilypond[verbatim,quote,relative=2]
1396 r4 <c e g>4 <c f a>2
1399 Think of chords as almost equivalent to single notes:
1400 almost everything you can attach to a single note can be attached
1401 to a chord, and everything must go @emph{outside} the angle
1402 brackets. For example, you can combine markings like beams and
1403 ties with chords. They must be placed outside the angle brackets.
1405 @lilypond[verbatim,quote,relative=2]
1406 r4 <c e g>8[ <c f a>]~ <c f a>2
1407 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
1411 @node Single staff polyphony
1412 @subsection Single staff polyphony
1415 @cindex multiple voices
1416 @cindex voices, more on one staff
1417 @cindex single staff polyphony
1419 @cindex rest, spacer
1421 @funindex << ... \\ ... >>
1426 When different melodic lines are combined on a single staff they
1427 are printed as polyphonic voices; each voice has its own stems,
1428 slurs and beams, and the top voice has the stems up, while the
1429 bottom voice has them down.
1431 Entering such parts is done by entering each voice as a sequence
1432 (with @w{@code{@{...@}}}) and combining these simultaneously,
1433 separating the voices with @code{\\}:
1435 @lilypond[verbatim,quote,relative=2]
1442 For polyphonic music typesetting, spacer rests can also be
1443 convenient; these are rests that do not print. They are useful
1444 for filling up voices that temporarily do not play. Here is the
1445 same example with a spacer rest (@code{s}) instead of a normal
1448 @lilypond[verbatim,quote,relative=2]
1456 Again, these expressions can be nested arbitrarily.
1458 @lilypond[verbatim,quote,relative=2]
1466 { <c g>1 ~ <c g>4 } \\
1474 Notation Reference: @ruser{Simultaneous notes}.
1480 This section introduces vocal music and simple song sheets.
1483 * Setting simple songs::
1484 * Aligning lyrics to a melody::
1485 * Lyrics to multiple staves::
1489 @node Setting simple songs
1490 @subsection Setting simple songs
1495 @funindex \addlyrics
1498 Music Glossary: @rglos{lyrics}.
1500 Here is the start of the melody to a nursery
1501 rhyme, @notation{Girls and boys come out to play}:
1503 @lilypond[verbatim,quote]
1507 d4 b8 c4 a8 d4 b8 g4
1511 The @notation{lyrics} can be set to these notes, combining both
1512 with the @code{\addlyrics} keyword. Lyrics are entered by
1513 separating each syllable with a space.
1515 @lilypond[verbatim,quote]
1520 d4 b8 c4 a8 d4 b8 g4
1523 Girls and boys come out to play,
1528 Note the curly brackets delimiting both the music and the lyrics,
1529 and the double angle brackets @w{@code{<< ... >>}} around the
1530 whole piece to show that the music and lyrics are to occur at the
1533 @node Aligning lyrics to a melody
1534 @subsection Aligning lyrics to a melody
1537 @cindex extender line
1540 @cindex lyrics, aligning
1541 @cindex aligning lyrics
1542 @cindex lyrics, multi-syllable words
1543 @cindex words with multiple syllables in lyrics
1545 Music Glossary: @rglos{melisma}, @rglos{extender line}.
1547 The next line in the nursery rhyme is @notation{The moon doth
1548 shine as bright as day}. Let's extend it:
1550 @lilypond[verbatim,quote]
1555 d4 b8 c4 a8 d4 b8 g4
1556 g8 a4 b8 c b a d4 b8 g4.
1559 Girls and boys come out to play,
1560 The moon doth shine as bright as day;
1565 We see the extra lyrics do not align properly with the notes. The
1566 word @notation{shine} should be sung on two notes, not one. This
1567 is called a @notation{melisma}, a single syllable sung to more
1568 than one note. There are several ways to spread a syllable over
1569 multiple notes, the simplest being to add a slur across them, for
1570 details, see @ref{Ties and slurs}:
1572 @lilypond[verbatim,quote]
1577 d4 b8 c4 a8 d4 b8 g4
1578 g8 a4 b8 c( b) a d4 b8 g4.
1581 Girls and boys come out to play,
1582 The moon doth shine as bright as day;
1587 The words now line up correctly with the notes, but the automatic
1588 beaming for the notes above @notation{shine as} does not look right.
1589 We can correct this by inserting manual beaming commands to override
1590 the automatic beaming here, for details, see @ref{Automatic and
1593 @lilypond[verbatim,quote]
1598 d4 b8 c4 a8 d4 b8 g4
1599 g8 a4 b8 c([ b]) a d4 b8 g4.
1602 Girls and boys come out to play,
1603 The moon doth shine as bright as day;
1608 As an alternative to using slurs, the melismata may be indicated
1609 in just the lyrics by using an underscore @code{_} for each note
1610 that should be included in the melisma:
1612 @lilypond[verbatim,quote]
1617 d4 b8 c4 a8 d4 b8 g4
1618 g8 a4 b8 c[ b] a d4 b8 g4.
1621 Girls and boys come out to play,
1622 The moon doth shine _ as bright as day;
1627 If a syllable extends over several notes or a single very long
1628 note an @notation{extender line} is usually drawn from the
1629 syllable extending under all the notes for that syllable. It is
1630 entered as two underscores @code{__}. Here is an example from the
1631 first three bars of @notation{Dido's Lament}, from Purcell's
1632 @notation{Dido and Æneas}:
1634 @lilypond[verbatim,quote]
1640 b c4.( bes8 a4. g8 fis4.) g8 fis1
1644 am laid __ in earth,
1649 None of the examples so far have involved words containing more
1650 than one syllable. Such words are usually split one syllable to a
1651 note, with hyphens between syllables. Such hyphens are entered as
1652 two dashes, resulting in a centered hyphen between the syllables.
1653 Here is an example showing this and everything we have learned so
1654 far about aligning lyrics to notes.
1656 @c no ragged-right here because otherwise the hyphens get lost,
1657 @c but the example is long enough to avoid looking strange.
1658 @lilypond[verbatim,quote,noragged-right]
1664 d4 g4 g a8( b) g4 g4
1668 A -- way in a __ man -- ger,
1669 no __ crib for a bed, __
1674 Some lyrics, especially those in Italian, require the opposite:
1675 setting more than one syllable to a single note. This is
1676 achieved by linking the syllables together with a single
1677 underscore @code{_} (with no spaces), or enclosing them in quotes.
1678 Here's an example from Rossini's @notation{Figaro}, where
1679 @notation{al} has to be sung on the same note as the @notation{go} of
1680 @notation{Largo} in Figaro's aria @notation{Largo al factotum}:
1682 @c no ragged-right here because otherwise the hyphens get lost,
1683 @c but the example is long enough to avoid looking strange.
1684 @lilypond[verbatim,quote,noragged-right]
1690 c4.~ c8 d b c([ d]) b c d b c
1693 Lar -- go_al fac -- to -- tum del -- la cit -- tÃ
1701 Notation Reference: @ruser{Vocal music}.
1704 @node Lyrics to multiple staves
1705 @subsection Lyrics to multiple staves
1707 @cindex lyrics and multiple staves
1708 @cindex multiple staves and lyrics
1710 The simple approach using @code{\addlyrics} can be used for
1711 placing lyrics under more than one staff. Here is an
1712 example from Handel's @notation{Judas Maccabæus}:
1714 @lilypond[verbatim,quote]
1720 c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
1723 Let flee -- cy flocks the hills a -- dorn, __
1729 r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
1732 Let flee -- cy flocks the hills a -- dorn,
1737 Scores any more complex than this simple example are better
1738 produced by separating out the score structure from the notes and
1739 lyrics with variables. These are discussed in @ref{Organizing
1740 pieces with variables}.
1744 Notation Reference: @ruser{Vocal music}.
1749 @section Final touches
1751 This is the final section of the tutorial; it demonstrates how to
1752 add the final touches to simple pieces, and provides an
1753 introduction to the rest of the manual.
1756 * Organizing pieces with variables::
1759 * Absolute note names::
1760 * After the tutorial::
1764 @node Organizing pieces with variables
1765 @subsection Organizing pieces with variables
1768 @cindex variables, defining
1771 @cindex assigning variables
1772 @cindex using variables
1773 @cindex variables, using
1774 @cindex variables, characters allowed in
1775 @cindex characters allowed in variables
1777 When all of the elements discussed earlier are combined to produce
1778 larger files, the music expressions get a lot bigger. In
1779 polyphonic music with many staves, the input files can become very
1780 confusing. We can reduce this confusion by using
1783 With variables (also known as identifiers or macros), we can break
1784 up complex music expressions. A variable is assigned as
1788 namedMusic = @{ @dots{} @}
1791 The contents of the music expression @code{namedMusic} can be used
1792 later by placing a backslash in front of the name
1793 (@code{\namedMusic}, just like a normal LilyPond command).
1795 @lilypond[verbatim,quote]
1796 violin = \new Staff {
1801 cello = \new Staff {
1816 The name of a variable must have alphabetic characters only, no
1817 numbers, underscores, or dashes.
1819 Variables must be defined @emph{before} the main music
1820 expression, but may be used as many times as required anywhere after
1821 they have been defined. They may even be used in a later definition
1822 of another variable, giving a way of shortening the input if a
1823 section of music is repeated many times.
1825 @lilypond[verbatim,quote]
1826 tripletA = \times 2/3 { c,8 e g }
1827 barA = { \tripletA \tripletA \tripletA \tripletA }
1834 Variables may be used for many other types of objects in
1835 the input. For example,
1840 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1843 Depending on its contents, the variable can be used in different
1844 places. The following example uses the above variables:
1857 @node Version number
1858 @subsection Version number
1862 @cindex version number
1864 @cindex future upgrades
1865 @cindex updating files
1866 @cindex files, updating
1870 @funindex convert-ly
1872 The @code{\version} statement records the version of LilyPond that
1873 was used to write the file:
1876 \version @w{"@version{}"}
1880 By convention, this is placed at the top of your LilyPond file.
1882 These annotations make future upgrades of LilyPond go more
1883 smoothly. Changes in the syntax are handled with a special
1884 program, @command{convert-ly}, and it uses @code{\version} to
1885 determine what rules to apply. For details, see
1886 @rprogram{Updating files with convert-ly}.
1890 @subsection Adding titles
1894 @cindex header block
1899 The title, composer, opus number, and similar information are
1900 entered in the @code{\header} block. This exists outside of the
1901 main music expression; the @code{\header} block is usually placed
1902 underneath the version number.
1905 \version @w{"@version{}"}
1913 @dots{} music @dots{}
1917 When the file is processed, the title and composer are printed
1918 above the music. More information on titling can be found in
1919 @ruser{Creating titles}.
1922 @node Absolute note names
1923 @subsection Absolute note names
1926 @cindex note names, absolute
1927 @cindex absolute mode
1928 @cindex absolute values for pitches
1929 @cindex pitches, absolute values
1930 @cindex absolute note names
1932 So far we have always used @code{\relative} to define pitches.
1933 This is the easiest way to enter most music, but another way of
1934 defining pitches exists: absolute mode.
1936 If you omit the @code{\relative}, LilyPond treats all pitches as
1937 absolute values. A @code{c'} will always mean middle C, a
1938 @code{b} will always mean the note one step below middle C, and a
1939 @code{g,} will always mean the note on the bottom staff of the
1942 @lilypond[verbatim,quote]
1950 Here is a four-octave scale:
1952 @lilypond[verbatim,quote]
1967 As you can see, writing a melody in the treble clef involves a lot
1968 of quote @code{'} marks. Consider this fragment from Mozart:
1970 @lilypond[verbatim,quote]
1974 cis''8. d''16 cis''8 e''4 e''8
1975 b'8. cis''16 b'8 d''4 d''8
1979 All these quotes makes the input less readable and they are a source
1980 of errors. With @code{\relative}, the previous example is much
1981 easier to read and type:
1983 @lilypond[verbatim,quote]
1987 cis8. d16 cis8 e4 e8
1992 If you make a mistake with an octave mark (@code{'} or @code{,})
1993 while working in @code{\relative} mode, it is very obvious -- many
1994 notes will be in the wrong octave. When working in absolute mode,
1995 a single mistake will not be as visible, and will not be as easy
1998 However, absolute mode is useful for music which has large
1999 intervals, and is extremely useful for computer-generated LilyPond
2004 @node After the tutorial
2005 @subsection After the tutorial
2007 After finishing the tutorial, you should probably try writing a
2008 piece or two. Start by adding notes to one of the
2009 @ref{Templates}. If you need any notation that was not covered in
2010 the tutorial, look at the Notation Reference, starting with
2011 @ruser{Musical notation}. If you want to write for an instrument
2012 ensemble that is not covered in the templates, take a look at
2013 @ref{Extending the templates}.
2015 Once you have written a few short pieces, read the rest of the
2016 Learning Manual (chapters 3-5). There's nothing wrong with
2017 reading it now, of course! However, the rest of the Learning
2018 Manual assumes that you are familiar with LilyPond input. You may
2019 wish to skim these chapters right now, and come back to them after
2020 you have more experience.
2022 In this tutorial and in the rest of the Learning Manual, there is a
2023 paragraph @strong{See also} at the end of each section, which contains
2024 cross-references to other sections: you should not follow these
2025 cross-references at first reading; when you have read all of the
2026 Learning Manual, you may want to read some sections again and follow
2027 cross-references for further reading.
2029 If you have not done so already, @emph{please} read @ref{About the
2030 documentation}. There is a lot of information about LilyPond, so
2031 newcomers often do not know where they should look for help. If
2032 you spend five minutes reading that section carefully, you might
2033 save yourself hours of frustration looking in the wrong places!