1 @c -*- coding: latin-1; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c M-x texinfo-all-menus-update
6 @c to automatically fill in these menus before saving changes
10 @chapter Basic notation
12 This chapter explains how to use all basic notation features.
16 * Alternate music entry::
30 This section is about basic notation elements like notes, rests, and
31 related constructs, such as stems, tuplets and ties.
36 * Cautionary accidentals::
51 @cindex Note specification
52 @cindex entering notes
54 A note is printed by specifying its pitch and then its duration,
56 @lilypond[quote,verbatim,raggedright,fragment]
62 This manual: @ref{Pitches}, @ref{Durations}
71 The most common syntax for pitch entry is used for standard notes and
72 @code{\chordmode} modes. In these modes, pitches may be designated by
73 names. The notes are specified by the letters @code{a} through
74 @code{g}. The octave is formed with notes ranging from @code{c}
75 to @code{b}. The pitch @code{c} is an octave below middle C and the
76 letters span the octave above that C
78 @lilypond[quote,fragment,verbatim,raggedright]
80 a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c''
86 The optional octave specification takes the form of a series of
87 single quote (`@code{'}') characters or a series of comma
88 (`@code{,}') characters. Each @code{'} raises the pitch by one
89 octave; each @code{,} lowers the pitch by an octave
91 @lilypond[quote,raggedright,fragment,verbatim]
95 @cindex note names, Dutch
97 A sharp is formed by adding @code{-is} to the end of a pitch name and
98 a flat is formed by adding @code{-es}. Double sharps and double flats
99 are obtained by adding @code{-isis} or @code{-eses}. These
100 names are the Dutch note names. In Dutch, @code{aes} is contracted to
101 @code{as}, but both forms are accepted. Similarly, both
102 @code{es} and @code{ees} are accepted
104 @lilypond[fragment,quote,raggedright,verbatim,relative=2]
112 There are predefined sets of note names for various other languages.
113 To use them, include the language specific init file. For
114 example: @code{\include "english.ly"}. The available language files
115 and the note names they define are
120 Note Names sharp flat
121 nederlands.ly c d e f g a bes b -is -es
122 english.ly c d e f g a bf b -s/-sharp -f/-flat
124 deutsch.ly c d e f g a b h -is -es
125 norsk.ly c d e f g a b h -iss/-is -ess/-es
126 svenska.ly c d e f g a b h -iss -ess
127 italiano.ly do re mi fa sol la sib si -d -b
128 catalan.ly do re mi fa sol la sib si -d/-s -b
129 espanol.ly do re mi fa sol la sib si -s -b
135 In accordance with standard typsetting rules, a natural sign is printed
136 before a sharp or flat if a previous accidental needs to be
137 cancelled. To change this behaviour, use
138 @code{\set Staff.extraNatural = ##f}
140 @lilypond[fragment,quote,raggedright,verbatim,relative=2]
142 \set Staff.extraNatural = ##f
149 Program reference: @internalsref{LedgerLineSpanner}, @internalsref{NoteHead}.
152 @node Cautionary accidentals
153 @subsection Cautionary accidentals
155 @cindex reminder accidental
157 @cindex cautionary accidental
158 @cindex parenthesized accidental
161 Normally accidentals are printed automatically, but you may also
162 print them manually. A reminder accidental
163 can be forced by adding an exclamation mark @code{!}
164 after the pitch. A cautionary accidental
165 (i.e., an accidental within parentheses) can be obtained by adding the
166 question mark `@code{?}' after the pitch. These extra accidentals
167 can be used to produce natural signs, too.
169 @lilypond[quote,raggedright,fragment,verbatim]
170 cis' cis' cis'! cis'? c c? c! c
176 The automatic production of accidentals can be tuned in many
177 ways. For more information, refer to @ref{Automatic accidentals}.
182 @subsection Micro tones
184 @cindex quarter tones
185 @cindex semi-flats, semi-sharps
187 Half-flats and half-sharps are formed by adding @code{-eh} and
188 @code{-ih}; the following is a series of Cs with increasing pitches
190 @lilypond[verbatim,raggedright,quote,relative=2,fragment]
191 \set Staff.extraNatural = ##f
195 Micro tones are also exported to the MIDI file.
200 There are no generally accepted standards for denoting three quarter
201 flats, so LilyPond's symbol does not conform to any standard.
209 A chord is formed by a enclosing a set of pitches in @code{<} and
210 @code{>}. A chord may be followed by a duration, and a set of
211 articulations, just like simple notes
213 @lilypond[verbatim,raggedright,fragment,quote,relative=1]
217 For more information about chords, see @ref{Chord names}.
228 Rests are entered like notes with the note name @code{r}
230 @lilypond[fragment,quote,raggedright,verbatim]
234 Whole bar rests, centered in middle of the bar,
235 must be done with multi-measure rests. They can be used for a
236 single bar as well as many bars, and are discussed in
237 @ref{Multi measure rests}.
240 A rest's vertical position may be explicitly specified by entering a
241 note with the @code{\rest} keyword appended, the rest will be placed at
242 the note's place. This makes manual formatting in polyphonic music
243 easier. Automatic rest collision formatting will leave these rests
246 @lilypond[fragment,quote,raggedright,verbatim]
252 Program reference: @internalsref{Rest}.
259 @cindex Invisible rest
264 An invisible rest (also called a `skip') can be entered like a note
265 with note name `@code{s}' or with @code{\skip @var{duration}}
267 @lilypond[fragment,quote,raggedright,verbatim,relative=2]
268 a4 a4 s4 a4 \skip 1 a4
271 The @code{s} syntax is only available in note mode and chord mode. In
272 other situations, for example, when entering lyrics, you should use
273 the @code{\skip} command
275 @lilypond[quote,raggedright,verbatim]
278 \new Lyrics \lyricmode { \skip 2 bla2 }
282 The skip command is merely an empty musical placeholder. It does not
283 produce any output, not even transparent output.
285 The @code{s} skip command does create @internalsref{Staff} and
286 @internalsref{Voice} when necessary, similar to note and rest
287 commands. For example, the following results in an empty staff.
289 @lilypond[quote,raggedright,verbatim]
293 The fragment @code{@{ \skip 4 @} } would produce an empty page.
297 Program reference: @internalsref{SkipMusic}.
301 @subsection Durations
304 @cindex @code{\longa}
305 @cindex @code{\breve}
306 @cindex @code{\maxima}
308 In Note, Chord, and Lyrics mode, durations are designated by numbers and
309 dots: durations are entered as their reciprocal values. For example, a
310 quarter note is entered using a @code{4} (since it is a 1/4 note), while
311 a half note is entered using a @code{2} (since it is a 1/2 note). For
312 notes longer than a whole you must use the variables @code{\longa} and
317 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
319 r1 r2 r4 r8 r16 r32 r64 r64
325 a\breve*1/2 \autoBeamOff
326 a1 a2 a4 a8 a16 a32 a64 a64
329 r\longa*1/4 r\breve *1/2
330 r1 r2 r4 r8 r16 r32 r64 r64
336 \remove "Clef_engraver"
337 \override StaffSymbol #'transparent = ##t
338 \override TimeSignature #'transparent = ##t
339 \override BarLine #'transparent = ##t
340 \consists "Pitch_squash_engraver"
346 If the duration is omitted then it is set to the previously entered
347 duration. The default for the first note is a quarter note.
349 @lilypond[quote,raggedright,verbatim,fragment]
350 { a a a2 a a4 a a1 a }
354 @node Augmentation dots
355 @subsection Augmentation dots
359 To obtain dotted note lenghts, simply add a dot (`@code{.}') to
360 the number. Double-dotted notes are produced in a similar way.
362 @lilypond[quote,raggedright,fragment,verbatim]
363 a'4 b' c''4. b'8 a'4. b'4.. c''8.
368 Dots are normally moved up to avoid staff lines, except in polyphonic
369 situations. The following commands may be used to force a particular
372 @cindex @code{\dotsUp}
374 @cindex @code{\dotsDown}
376 @cindex @code{\dotsNeutral}
381 Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
389 @cindex @code{\times}
391 Tuplets are made out of a music expression by multiplying all durations
395 \times @var{fraction} @var{musicexpr}
399 The duration of @var{musicexpr} will be multiplied by the fraction.
400 The fraction's denominator will be printed over the notes, optionally
401 with a bracket. The most common tuplet is the triplet in which 3
402 notes have the length of 2, so the notes are 2/3 of their written
405 @lilypond[quote,raggedright,fragment,verbatim]
406 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
409 Tuplets may be nested, for example,
411 @lilypond[fragment,raggedright,verbatim,relative=2]
412 \set tupletNumberFormatFunction = #fraction-tuplet-formatter
415 \times 3/5 { a a a a a }
421 @cindex @code{\tupletUp}
423 @cindex @code{\tupletDown}
425 @cindex @code{\tupletNeutral}
426 @code{\tupletNeutral}.
431 @cindex @code{tupletNumberFormatFunction}
432 @cindex tuplet formatting
434 The property @code{tupletSpannerDuration} specifies how long each
435 bracket should last. With this, you can make lots of tuplets while
436 typing @code{\times} only once, thus saving lots of typing. In the next
437 example, there are two triplets shown, while @code{\times} was only
440 @lilypond[quote,fragment,relative=1,raggedright,verbatim]
441 \set tupletSpannerDuration = #(ly:make-moment 1 4)
442 \times 2/3 { c'8 c c c c c }
445 The format of the number is determined by the property
446 @code{tupletNumberFormatFunction}. The default prints only the
447 denominator, but if it is set to the Scheme function
448 @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
457 Program reference: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}.
459 Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
463 @node Scaling durations
464 @subsection Scaling durations
466 You can alter the length of duration by a fraction @var{N/M}
467 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
468 will not affect the appearance of the notes or rests produced.
470 In the following example, the first three notes take up exactly two
471 beats, but no triplet bracket is printed.
472 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
474 a4*2/3 gis4*2/3 a4*2/3
482 This manual: @ref{Tuplets}
486 @node Alternate music entry
487 @section Alternate music entry
490 This section deals with tricks and features of the input language that
491 were added solely to help entering music and finding and correcting
492 mistakes. There are also external tools that make debugging easier.
493 See @ref{Point and click} for more information.
495 It is also possible to enter and edit music using other programs, such as
496 GUI interfaces or MIDI sequencers. Refer to the LilyPond
497 website for more information.
505 * Skipping corrected music::
506 * Automatic note splitting::
510 @node Relative octaves
511 @subsection Relative octaves
514 @cindex Relative octave specification
515 @cindex @code{\relative}
517 Octaves are specified by adding @code{'} and @code{,} to pitch names.
518 When you copy existing music, it is easy to accidentally put a pitch
519 in the wrong octave and hard to find such an error. The relative
520 octave mode prevents these errors by making the mistakes much
521 larger: a single error puts the rest of the piece off by one octave
524 \relative @var{startpitch} @var{musicexpr}
531 \relative @var{musicexpr}
534 The octave of notes that appear in @var{musicexpr} are calculated as
535 follows: if no octave changing marks are used, the basic interval
536 between this and the last note is always taken to be a fourth or
537 less. This distance is determined without regarding alterations; a
538 @code{fisis} following a @code{ceses} will be put above the
539 @code{ceses}. In other words, a doubly-augmented fourth is considered
540 a smaller interval than a diminished fifth, even though the
541 doubly-augmented fourth spans seven semitones while the diminished
542 fifth only spans six semitones.
544 The octave changing marks @code{'} and @code{,} can be added to raise
545 or lower the pitch by an extra octave. Upon entering relative mode,
546 an absolute starting pitch can be specified that will act as the
547 predecessor of the first note of @var{musicexpr}. If no starting pitch
548 is specified, then middle C is used as a start.
550 Here is the relative mode shown in action
551 @lilypond[quote,fragment,raggedright,verbatim]
557 Octave changing marks are used for intervals greater than a fourth
558 @lilypond[quote,raggedright,fragment,verbatim]
564 If the preceding item is a chord, the first note of the chord is used
565 to determine the first note of the next chord
567 @lilypond[quote,raggedright,fragment,verbatim]
575 The pitch after the @code{\relative} contains a note name.
577 The relative conversion will not affect @code{\transpose},
578 @code{\chordmode} or @code{\relative} sections in its argument. To use
579 relative within transposed music, an additional @code{\relative} must
580 be placed inside @code{\transpose}.
584 @subsection Octave check
588 Octave checks make octave errors easier to correct: a note may be
589 followed by @code{=}@var{quotes} which indicates what its absolute
590 octave should be. In the following example,
593 \relative c'' @{ c='' b=' d,='' @}
597 the @code{d} will generate a warning, because a @code{d''} is expected
598 (because @code{b'} to @code{d''} is only a third), but a @code{d'} is
599 found. In the output, the octave is corrected to be a @code{d''} and
600 the next note is calculated relative to @code{d''} instead of @code{d'}.
602 There is also a syntax that is separate from the notes. The syntax
608 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
609 quotes) in \relative mode. If not, a warning is printed, and the
612 In the example below, the first check passes without incident, since
613 the @code{e} (in relative mode) is within a fifth of @code{a'}. However,
614 the second check produces a warning, since the @code{e} is not within
615 a fifth of @code{b'}. The warning message is printed, and the octave
616 is adjusted so that the following notes are in the correct octave
628 The octave of a note following an octave check is determined with
629 respect to the note preceding it. In the next fragment, the last note
630 is an @code{a'}, above middle C. That means that the @code{\octave}
631 check passes successfully, so the check could be deleted without changing
632 the output of the piece.
634 @lilypond[quote,raggedright,verbatim,fragment]
644 @subsection Transpose
647 @cindex transposition of pitches
648 @cindex @code{\transpose}
650 A music expression can be transposed with @code{\transpose}. The
653 \transpose @var{from} @var{to} @var{musicexpr}
656 This means that @var{musicexpr} is transposed by the interval between
657 the pitches @var{from} and @var{to}: any note with pitch @code{from}
658 is changed to @code{to}.
660 For example, consider a piece written in the key of D-major. If
661 this piece is a little too low for its performer, it can be
662 transposed up to E-major with
664 \transpose d e @dots{}
667 Consider a part written for violin (a C instrument). If
668 this part is to be played on the A clarinet, the following
669 transposition will produce the appropriate part
672 \transpose a c @dots{}
675 @code{\transpose} distinguishes between enharmonic pitches: both
676 @code{\transpose c cis} or @code{\transpose c des} will transpose up
677 half a tone. The first version will print sharps and the second
678 version will print flats
680 @lilypond[quote,raggedright,verbatim]
681 mus = { \key d \major cis d fis g }
690 @code{\transpose} may also be used to input written notes for a
691 transposing instrument. Pitches are normally entered into LilyPond
692 in C (or ``concert pitch''), but they may be entered in another
693 key. For example, when entering music for a B-flat trumpet which
694 begins on concert D, one would write
697 \transpose c bes @{ e4 @dots{} @}
700 To print this music in B-flat again (ie producing a trumpet part,
701 instead of a concert pitch conductor's score) you would wrap the
702 existing music with another @code{transpose}
705 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
711 Program reference: @internalsref{TransposedMusic}.
716 If you want to use both @code{\transpose} and @code{\relative},
717 you must put @code{\transpose} outside of @code{\relative}, since
718 @code{\relative} will have no effect music that appears inside a
723 @subsection Bar check
726 @cindex @code{barCheckSynchronize}
729 Bar checks help detect errors in the durations. A bar check is
730 entered using the bar symbol, `@code{|}'. Whenever it is encountered
731 during interpretation, it should fall on a measure boundary. If it
732 does not, a warning is printed. In the next example, the second bar
733 check will signal an error
735 \time 3/4 c2 e4 | g2 |
738 Bar checks can also be used in lyrics, for example
743 Twin -- kle | Twin -- kle
747 Failed bar checks are caused by entering incorrect
748 durations. Incorrect durations often completely garble up the score,
749 especially if the score is polyphonic, so a good place to start correcting
750 input is by scanning for failed bar checks and incorrect durations.
753 @cindex @code{pipeSymbol}
755 It is also possible to redefine the meaning of @code{|}. This is done
756 by assigning a music expression to @code{pipeSymbol},
758 @lilypond[quote,raggedright,verbatim]
759 pipeSymbol = \bar "||"
765 @node Barnumber check
766 @subsection Barnumber check
768 When copying large pieces of music, it can be helpful to check that
769 the LilyPond bar number corresponds to the original that you are
770 entering from. This can be checked with @code{\barNumberCheck}, for
778 will print a warning if the @code{currentBarNumber} is not 123 when it
782 @node Skipping corrected music
783 @subsection Skipping corrected music
786 @cindex @code{skipTypesetting}
787 @cindex @code{showLastLength}
789 When entering or copying music, only the music near the end (where you
790 are adding notes) is interesting to view and correct. To speed up
791 this correction process, it is possible to skip typesetting of all but
792 the last few measures. This is achieved by putting
795 showLastLength = R1*5
800 in your source file. This will render only the last 5 measures
801 (assuming 4/4 time signature) of every @code{\score} in the input
802 file. For longer pieces, rendering only a small part is often an order
803 of magnitude quicker than rendering it completely
805 Skipping parts of a score can be controlled in a more fine-grained
806 fashing with the property @code{Score.skipTypesetting}. When it is
807 set, no typesetting is performed at all.
809 @lilypond[quote,fragment,raggedright,verbatim]
812 \set Score.skipTypesetting = ##t
814 \set Score.skipTypesetting = ##f
818 In polyphonic music, @code{Score.skipTypesetting} will affect all
819 voices and staves, saving even more time.
822 @node Automatic note splitting
823 @subsection Automatic note splitting
825 Long notes can be converted automatically to tied notes. This is done
826 by replacing the @internalsref{Note_heads_engraver} by the
827 @internalsref{Completion_heads_engraver}.
828 In the following examples, notes crossing the bar line are split and tied.
830 @lilypond[quote,fragment,verbatim,relative=1,linewidth=12\cm]
832 \remove "Note_heads_engraver"
833 \consists "Completion_heads_engraver"
835 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
839 This engraver splits all running notes at the bar line, and inserts
840 ties. One of its uses is to debug complex scores: if the measures are
841 not entirely filled, then the ties exactly show how much each measure
847 Not all durations (especially those containing tuplets) can be
848 represented exactly with normal notes and dots, but the engraver will
851 @code{Completion_heads_engraver} only affects notes; it does not split
857 Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
861 Program reference: @internalsref{Completion_heads_engraver}.
866 @section Staff notation
868 @cindex Staff notation
870 This section describes music notation that occurs on staff level,
871 such as key signatures, clefs and time signatures.
880 * System start delimiters::
890 The clef indicates which lines of the staff correspond to which
891 pitches. The clef is set with the @code{\clef} command
893 @lilypond[quote,raggedright,fragment,verbatim]
894 { c''2 \clef alto g'2 }
904 @cindex mezzosoprano clef
905 @cindex baritone clef
906 @cindex varbaritone clef
909 Supported clefs finclude
911 @item treble, violin, G, G2
920 G clef on 1st line, so-called French violin clef
937 By adding @code{_8} or @code{^8} to the clef name, the clef is
938 transposed one octave down or up, respectively, and @code{_15} and
939 @code{^15} transposes by two octaves. The argument @var{clefname}
940 must be enclosed in quotes when it contains underscores or digits. For
943 @cindex choral tenor clef
944 @lilypond[quote,raggedright,verbatim,fragment,relative=1]
951 The command @code{\clef "treble_8"} is equivalent to setting @code{clefGlyph},
952 @code{clefPosition} (which controls the Y position of the clef),
953 @code{middleCPosition} and @code{clefOctavation}. A clef is printed
954 when any of these properties are changed. The following example shows
955 possibilities when setting properties manually.
957 @lilypond[quote,raggedright,verbatim]
959 \set Staff.clefGlyph = #"clefs.F"
960 \set Staff.clefPosition = #2
962 \set Staff.clefGlyph = #"clefs.G"
964 \set Staff.clefGlyph = #"clefs.C"
966 \set Staff.clefOctavation = #7
968 \set Staff.clefOctavation = #0
969 \set Staff.clefPosition = #0
973 \set Staff.middleCPosition = #4
981 Program reference: @internalsref{Clef}.
985 @subsection Key signature
987 @cindex Key signature
990 The key signature indicates the tonality in which a piece is played. It
991 is denoted by a set of alterations (flats or sharps) at the start of the
994 Setting or changing the key signature is done with the @code{\key}
998 @code{\key} @var{pitch} @var{type}
1001 @cindex @code{\minor}
1002 @cindex @code{\major}
1003 @cindex @code{\minor}
1004 @cindex @code{\ionian}
1005 @cindex @code{\locrian}
1006 @cindex @code{\aeolian}
1007 @cindex @code{\mixolydian}
1008 @cindex @code{\lydian}
1009 @cindex @code{\phrygian}
1010 @cindex @code{\dorian}
1011 @cindex church modes
1013 Here, @var{type} should be @code{\major} or @code{\minor} to get
1014 @var{pitch}-major or @var{pitch}-minor, respectively. You may also
1015 use the standard mode names (also called ``church modes''): @code{\ionian},
1016 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
1017 @code{\phrygian}, and @code{\dorian}.
1019 This command sets the context property
1020 @code{Staff.keySignature}. Non-standard key signatures
1021 can be specified by setting this property directly.
1023 Accidentals and key signatures often confuse new users, because
1024 unaltered notes get natural signs depending on the key signature. For
1025 more information, see @ref{More about pitches}.
1030 A natural sign is printed to cancel any previous accidentals. This
1031 can be suppressed by setting the @code{Staff.printKeyCancellation}
1034 @lilypond[quote,fragment,raggedright,fragment,verbatim,relative=2]
1039 \set Staff.printKeyCancellation = ##f
1049 Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}.
1052 @node Time signature
1053 @subsection Time signature
1055 @cindex Time signature
1057 @cindex @code{\time}
1059 Time signature indicates the metrum of a piece: a regular pattern of
1060 strong and weak beats. It is denoted by a fraction at the start of the
1063 The time signature is set with the @code{\time} command
1065 @lilypond[quote,raggedright,fragment,verbatim]
1066 \time 2/4 c'2 \time 3/4 c'2.
1071 The symbol that is printed can be customized with the @code{style}
1072 property. Setting it to @code{#'()} uses fraction style for 4/4 and
1075 @lilypond[fragment,quote,raggedright,verbatim]
1078 \override Staff.TimeSignature #'style = #'()
1083 There are many more options for its layout. See @ref{Ancient time
1084 signatures} for more examples.
1086 @code{\time} sets the property @code{timeSignatureFraction},
1087 @code{beatLength} and @code{measureLength} in the @code{Timing}
1088 context, which is normally aliased to @internalsref{Score}. The
1089 property @code{measureLength} determines where bar lines should be
1090 inserted, and how automatic beams should be generated. Changing the
1091 value of @code{timeSignatureFraction} also causes the symbol to be
1094 More options are available through the Scheme function
1095 @code{set-time-signature}. In combination with the
1096 @internalsref{Measure_grouping_engraver}, it will create
1097 @internalsref{MeasureGrouping} signs. Such signs ease reading
1098 rhythmically complex modern music. In the following example, the 9/8
1099 measure is subdivided in 2, 2, 2 and 3. This is passed to
1100 @code{set-time-signature} as the third argument @code{(2 2 2 3)}
1102 @lilypond[quote,raggedright,verbatim]
1105 #(set-time-signature 9 8 '(2 2 2 3))
1106 g8[ g] d[ d] g[ g] a8[( bes g]) |
1107 #(set-time-signature 5 8 '(3 2))
1113 \consists "Measure_grouping_engraver"
1121 Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_translator}.
1126 Automatic beaming does not use the measure grouping specified with
1127 @code{set-time-signature}.
1130 @node Partial measures
1131 @subsection Partial measures
1135 @cindex partial measure
1136 @cindex measure, partial
1137 @cindex shorten measures
1138 @cindex @code{\partial}
1140 Partial measures, such as an anacrusis or upbeat, are entered using the
1142 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1143 \partial 16*5 c16 cis d dis e | a2. c,4 | b2
1146 The syntax for this command is
1149 \partial @var{duration}
1152 This is internally translated into
1155 \set Timing.measurePosition = -@var{length of duration}
1158 The property @code{measurePosition} contains a rational number
1159 indicating how much of the measure has passed at this point.
1164 This command does not take into account grace notes at the start of
1165 the music. When a piece starts with graces notes in the pickup, then
1166 the @code{\partial} should follow the grace notes
1168 @lilypond[verbatim,quote,raggedright,relative,fragment]
1177 @subsection Bar lines
1181 @cindex measure lines
1184 Bar lines delimit measures, but are also used to indicate
1185 repeats. Normally they are inserted automatically. Line
1186 breaks may only happen on bar lines.
1188 Special types of bar lines can be forced with the @code{\bar} command
1190 @lilypond[quote,raggedright,relative=2,fragment,verbatim]
1194 The following bar types are available
1196 @lilypondfile[raggedright,quote]{bar-lines.ly}
1198 To allow a line break where there is no visible bar line, use
1205 This will insert an invisible bar line and allow line breaks at this
1208 In scores with many staves, a @code{\bar} command in one staff is
1209 automatically applied to all staves. The resulting bar lines are
1210 connected between different staves of a StaffGroup
1212 @lilypond[quote,raggedright,fragment,verbatim]
1214 \context StaffGroup <<
1220 \new Staff { \clef bass c4 g e g }
1222 \new Staff { \clef bass c2 c2 }
1229 @cindex @code{whichBar}
1230 @cindex @code{repeatCommands}
1231 @cindex @code{defaultBarType}
1233 The command @code{\bar }@var{bartype} is a short cut for doing
1234 @code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
1235 is set to a string, a bar line of that type is created.
1237 A bar line is created whenever the @code{whichBar} property is set.
1238 At the start of a measure it is set to the contents of
1239 @code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used
1240 to override default measure bars.
1242 You are encouraged to use @code{\repeat} for repetitions. See
1248 In this manual: @ref{Repeats}, @ref{System start delimiters}.
1250 Program reference: @internalsref{BarLine} (created at
1251 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1253 Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
1256 @node Unmetered music
1257 @subsection Unmetered music
1260 @cindex @code{\cadenzaOn}
1261 @cindex @code{\cadenzaOff}
1263 Bar lines and bar numbers are calculated automatically. For unmetered
1264 music (cadenzas, for example), this is not desirable. To turn off
1265 automatic bar lines and bar numbers, use the commands @code{\cadenzaOn}
1266 and @code{\cadenzaOff}.
1268 @lilypond[verbatim,quote,raggedright,relative=2,fragment]
1280 LilyPond will only insert page breaks at a barline. Unless the unmetered
1281 music ends before the end of the staff line, you will need to insert
1289 to indicate where line breaks can occur.
1292 @node System start delimiters
1293 @subsection System start delimiters
1295 @cindex start of system
1296 @cindex Staff, multiple
1297 @cindex bracket, vertical
1298 @cindex brace, vertical
1301 @cindex staff, choir
1303 Many scores consist of more than one staff. These staves can be
1304 joined in four different ways
1307 @item The group is started with a brace at the left, and bar lines are
1308 connected. This is done with the @internalsref{GrandStaff} context.
1310 @lilypond[verbatim,raggedright,quote]
1318 @item The group is started with a bracket, and bar lines are connected.
1319 This is done with the
1320 @internalsref{StaffGroup} context
1322 @lilypond[verbatim,raggedright,quote]
1330 @item The group is started with a bracket, but bar lines are not
1331 connected. This is done with the @internalsref{ChoirStaff} context.
1333 @lilypond[verbatim,raggedright,quote]
1341 @item The group is started with a vertical line. Bar lines are not
1342 connected. This is the default for the score.
1344 @lilypond[verbatim,raggedright,quote]
1355 The bar lines at the start of each system are
1356 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
1357 @internalsref{SystemStartBracket}. Only one of these types is created
1358 in every context, and that type is determined by the property
1359 @code{systemStartDelimiter}.
1363 @subsection Staff symbol
1365 @cindex adjusting staff symbol
1367 Notes, dynamic signs, etc., are grouped
1368 with a set of horizontal lines, called a staff (plural `staves'). In
1369 LilyPond, these lines are drawn using a separate layout object called
1372 The staff symbol may be tuned in the number, thickness and distance
1373 of lines, using properties. This is demonstrated in the example files
1374 @inputfileref{input/@/test,staff@/-lines@/.ly},
1375 @inputfileref{input/@/test,staff@/-size@/.ly}.
1377 In addition, staves may be started and stopped at will. This is done
1378 with @code{\startStaff} and @code{\stopStaff}.
1380 @lilypond[verbatim,relative=2,fragment]
1382 \override Staff.StaffSymbol #'line-count = 2
1383 \stopStaff \startStaff
1385 \revert Staff.StaffSymbol #'line-count
1386 \stopStaff \startStaff
1390 In combination with Frenched staves, this may be used to typeset ossia
1391 sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
1396 @lilypondfile{ossia.ly}
1398 @cindex staff lines, setting number of
1399 @cindex staff lines, setting thickness of
1400 @cindex thickness of staff lines, setting
1401 @cindex number of staff lines, setting
1405 Program reference: @internalsref{StaffSymbol}.
1407 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
1408 @inputfileref{input/@/test@/,ossia.ly},
1409 @inputfileref{input/@/test,staff@/-size@/.ly}.
1413 @node Connecting notes
1414 @section Connecting notes
1416 This section deals with notation that affects groups of notes.
1434 A tie connects two adjacent note heads of the same pitch. The tie in
1435 effect extends the length of a note. Ties should not be confused with
1436 slurs, which indicate articulation, or phrasing slurs, which indicate
1437 musical phrasing. A tie is entered using the tilde symbol `@code{~}'
1439 @lilypond[quote,raggedright,fragment,verbatim]
1440 e' ~ e' <c' e' g'> ~ <c' e' g'>
1443 When a tie is applied to a chord, all note heads whose pitches match
1444 are connected. When no note heads match, no ties will be created.
1446 A tie is just a way of extending a note duration, similar to the
1447 augmentation dot. The following example shows two ways of notating
1448 exactly the same concept
1450 @lilypond[quote,fragment,raggedright]
1451 \time 3/4 c'2. c'2 ~ c'4
1455 Ties are used either when the note crosses a bar line, or when dots
1456 cannot be used to denote the rhythm. When using ties, larger note
1457 values should be aligned to subdivisions of the measure, eg.
1459 @lilypond[fragment,quote,raggedright]
1461 r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
1465 If you need to tie a lot of notes over bars, it may be easier to use
1466 automatic note splitting (see @ref{Automatic note splitting}). This
1467 mechanism automatically splits long notes, and ties them across bar
1473 Ties are sometimes used to write out arpeggios. In this case, two tied
1474 notes need not be consecutive. This can be achieved by setting the
1475 @code{tieWaitForNote} property to true. The same feature is also useful,
1476 for example, to tie a tremolo to a chord. For example,
1478 @lilypond[fragment,verbatim,relative=1,raggedright]
1479 \set tieWaitForNote = ##t
1480 \grace { c16[~ e~ g]~ } <c, e g>2
1481 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
1488 @cindex @code{\tieUp}
1490 @cindex @code{\tieDown}
1492 @cindex @code{\tieNeutral}
1494 @cindex @code{\tieDotted}
1496 @cindex @code{\tieDashed}
1498 @cindex @code{\tieSolid}
1504 In this manual: @ref{Automatic note splitting}.
1506 Program reference: @internalsref{Tie}.
1511 Switching staves when a tie is active will not produce a slanted tie.
1519 A slur indicates that notes are to be played bound or
1520 @emph{legato}. They are entered using parentheses
1522 @lilypond[quote,raggedright,relative=2,fragment,verbatim]
1523 f( g a) a8 b( a4 g2 f4)
1527 The direction of a slur can be specified with
1528 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is
1529 either @code{Up}, @code{Down}, or @code{Neutral} (automatically
1532 However, there is a convenient shorthand for forcing slur
1533 directions. By adding @code{_} or @code{^} before the opening
1534 parentheses, the direction is also set. For example,
1536 @lilypond[relative=2,raggedright,quote,verbatim,fragment]
1540 Only one slur can be printed at once. If you need to print a long
1541 slur over a few small slurs, please see @ref{Phrasing slurs}.
1546 Some composers write two slurs when they want legato chords. This can
1547 be achieved in LilyPond by setting @code{doubleSlurs},
1549 @lilypond[verbatim,raggedright,relative,fragment,quote]
1550 \set doubleSlurs = ##t
1551 <c e>4 ( <d f> <c e> <d f> )
1557 @cindex @code{\slurUp}
1559 @cindex @code{\slurDown}
1561 @cindex @code{\slurNeutral}
1562 @code{\slurNeutral},
1563 @cindex @code{\slurDashed}
1565 @cindex @code{\slurDotted}
1567 @cindex @code{\slurSolid}
1572 Program reference: @seeinternals{Slur}.
1575 @node Phrasing slurs
1576 @subsection Phrasing slurs
1578 @cindex phrasing slurs
1579 @cindex phrasing marks
1581 A phrasing slur (or phrasing mark) connects notes and is used to
1582 indicate a musical sentence. It is written using @code{\(} and @code{\)}
1585 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
1586 \time 6/4 c'\( d( e) f( e) d\)
1589 Typographically, the phrasing slur behaves almost exactly like a
1590 normal slur. However, they are treated as different objects. A
1591 @code{\slurUp} will have no effect on a phrasing slur; instead, use
1592 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1593 @code{\phrasingSlurNeutral}.
1595 You cannot have simultaneous phrasing slurs.
1600 @cindex @code{\phrasingSlurUp}
1601 @code{\phrasingSlurUp},
1602 @cindex @code{\phrasingSlurDown}
1603 @code{\phrasingSlurDown},
1604 @cindex @code{\phrasingSlurNeutral}
1605 @code{\phrasingSlurNeutral}.
1610 Program reference: @internalsref{PhrasingSlur}.
1613 @node Automatic beams
1614 @subsection Automatic beams
1616 LilyPond inserts beams automatically
1618 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1619 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
1622 When these automatic decisions are not good enough, beaming can be
1623 entered explicitly. It is also possible to define beaming patterns
1624 that differ from the defaults. See @ref{Setting automatic beam behavior}
1627 Individual notes may be marked with @code{\noBeam} to prevent them
1630 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1631 \time 2/4 c8 c\noBeam c c
1637 Program reference: @internalsref{Beam}.
1641 @subsection Manual beams
1643 @cindex beams, manual
1647 In some cases it may be necessary to override the automatic beaming
1648 algorithm. For example, the autobeamer will not put beams over rests
1649 or bar lines. Such beams are specified manually by marking the begin
1650 and end point with @code{[} and @code{]}
1652 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
1654 r4 r8[ g' a r8] r8 g[ | a] r8
1661 @cindex @code{stemLeftBeamCount}
1662 @cindex @code{stemRightBeamCount}
1664 Normally, beaming patterns within a beam are determined automatically.
1665 If necessary, the properties @code{stemLeftBeamCount} and
1666 @code{stemRightBeamCount} can be used to override the defaults. If
1667 either property is set, its value will be used only once, and then it
1670 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
1675 \set stemLeftBeamCount = #1
1680 The property @code{subdivideBeams} can be set in order to subdivide
1681 all 16th or shorter beams at beat positions, as defined by the
1682 @code{beatLength} property.
1684 @lilypond[fragment,quote,relative=2,verbatim]
1686 \set subdivideBeams = ##t
1688 \set Score.beatLength = #(ly:make-moment 1 8)
1691 @cindex @code{subdivideBeams}
1693 Line breaks are normally forbidden when beams cross bar lines. This
1694 behavior can be changed by setting @code{allowBeamBreak}.
1696 @cindex @code{allowBeamBreak}
1697 @cindex beams and line breaks
1698 @cindex beams, kneed
1700 @cindex auto-knee-gap
1705 Kneed beams are inserted automatically when a large gap is detected
1706 between the note heads. This behavior can be tuned through the object.
1708 Automatically kneed cross-staff beams cannot be used together with
1709 hidden staves. See @ref{Hiding staves}.
1711 Beams do not avoid collisions with symbols around the notes, such as
1712 texts and accidentals.
1716 @subsection Grace notes
1718 @cindex @code{\grace}
1721 @cindex appoggiatura
1722 @cindex acciaccatura
1724 Grace notes are ornaments that are written out. The most common ones
1725 are acciaccatura, which should be played as very short. It is denoted
1726 by a slurred small note with a slashed stem. The appoggiatura is a
1727 grace note that takes a fixed fraction of the main note, and is
1728 denoted as a slurred note in small print without a slash. They
1729 are entered with the commands @code{\acciaccatura} and
1730 @code{\appoggiatura}, as demonstrated in the following example
1732 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1733 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
1734 \acciaccatura { g16[ f] } e4
1737 Both are special forms of the @code{\grace} command. By prefixing this
1738 keyword to a music expression, a new one is formed, which will be
1739 printed in a smaller font and takes up no logical time in a measure.
1741 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1743 \grace { c16[ d16] } c2 c4
1747 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
1748 @code{\grace} command does not start a slur.
1750 Internally, timing for grace notes is done using a second, `grace'
1751 timing. Every point in time consists of two rational numbers: one
1752 denotes the logical time, one denotes the grace timing. The above
1753 example is shown here with timing tuples
1755 @lilypond[quote,raggedright]
1758 c4 \grace c16 c4 \grace {
1761 \new Lyrics \lyricmode {
1762 \override LyricText #'font-family = #'typewriter
1766 ( \fraction 1 4 , \fraction -1 16 ) } 16 }
1767 \markup { (\fraction 1 4 , 0 ) } 4
1769 \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
1770 \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
1772 \markup { ( \fraction 2 4 , 0 ) }
1777 The placement of grace notes is synchronized between different staves.
1778 In the following example, there are two sixteenth grace notes for
1779 every eighth grace note
1781 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1782 << \new Staff { e4 \grace { c16[ d e f] } e4 }
1783 \new Staff { c4 \grace { g8[ b] } c4 } >>
1786 If you want to end a note with a grace, use the @code{\afterGrace}
1787 command. It takes two arguments: the main note, and the grace notes
1788 following the main note.
1790 @lilypond[raggedright, verbatim,relative=2,fragment]
1791 c1 \afterGrace d1 { c16[ d] } c4
1794 This will put the grace notes after a ``space'' lasting 3/4 of the
1795 length of the main note. The fraction 3/4 can be changed by setting
1796 @code{afterGraceFraction}, ie.
1799 afterGraceFraction = #(cons 7 8)
1803 will put the grace note at 7/8 of the main note.
1805 The same effect can be achieved manually by doing
1807 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1810 { s2 \grace { c16[ d] } } >>
1816 By adjusting the duration of the skip note (here it is a half-note),
1817 the space between the main-note and the grace is adjusted.
1819 A @code{\grace} section will introduce special typesetting settings,
1820 for example, to produce smaller type, and set directions. Hence, when
1821 introducing layout tweaks, they should be inside the grace section,
1823 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1835 The overrides should also be reverted inside the grace section.
1837 The layout of grace sections can be changed throughout the music using
1838 the function @code{add-grace-property}. The following example
1839 undefines the Stem direction for this grace, so stems do not always
1844 #(add-grace-property 'Voice 'Stem 'direction '())
1850 Another option is to change the variables @code{startGraceMusic},
1851 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
1852 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
1853 @code{stopAppoggiaturaMusic}. More information is in the file
1854 @file{ly/@/grace@/-init@/.ly}.
1859 Program reference: @internalsref{GraceMusic}.
1864 A score that starts with a @code{\grace} section needs an explicit
1865 @code{\context Voice} declaration, otherwise the main note and the grace
1866 note end up on different staves.
1868 Grace note synchronization can also lead to surprises. Staff notation,
1869 such as key signatures, bar lines, etc., are also synchronized. Take
1870 care when you mix staves with grace notes and staves without, for example,
1872 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1873 << \new Staff { e4 \bar "|:" \grace c16 d4 }
1874 \new Staff { c4 \bar "|:" d4 } >>
1878 This can be remedied by inserting grace skips, for the above example
1881 \new Staff @{ c4 \bar "|:" \grace s16 d4 @}
1884 Grace sections should only be used within sequential music
1885 expressions. Nesting or juxtaposing grace sections is not supported,
1886 and might produce crashes or other errors.
1890 @node Expressive marks
1891 @section Expressive marks
1893 Expressive marks help musicians to bring more to the music than simple
1898 * Fingering instructions::
1908 @subsection Articulations
1910 @cindex Articulations
1914 A variety of symbols can appear above and below notes to indicate
1915 different characteristics of the performance. They are added to a note
1916 by adding a dash and the character signifying the
1917 articulation. They are demonstrated here
1919 @lilypondfile[quote,raggedright]{script-abbreviations.ly}
1921 The meanings of these shorthands can be changed. See
1922 @file{ly/@/script@/-init@/.ly} for examples.
1924 The script is automatically placed, but the direction can be forced as
1925 well. Like other pieces of LilyPond code, @code{_} will place them
1926 below the staff, and @code{^} will place them above.
1928 @lilypond[quote,raggedright,fragment,verbatim]
1932 Other symbols can be added using the syntax
1933 @var{note}@code{\}@var{name}. Again, they
1934 can be forced up or down using @code{^} and @code{_},
1937 @lilypond[quote,raggedright,verbatim,fragment,relative=2]
1938 c\fermata c^\fermata c_\fermata
1943 @cindex staccatissimo
1953 @cindex organ pedal marks
1962 @cindex prallmordent
1966 @cindex thumb marking
1971 Here is a chart showing all scripts available,
1973 @lilypondfile[raggedright,quote]{script-chart.ly}
1978 The vertical ordering of scripts is controlled with the
1979 @code{script-priority} property. The lower this number, the closer it
1980 will be put to the note. In this example, the
1981 @internalsref{TextScript} (the sharp symbol) first has the lowest
1982 priority, so it is put lowest in the first example. In the second, the
1983 prall trill (the @internalsref{Script}) has the lowest, so it is on the
1984 inside. When two objects have the same priority, the order in which
1985 they are entered decides which one comes first.
1987 @lilypond[verbatim,relative=3,raggedright,fragment,quote]
1988 \once \override TextScript #'script-priority = #-100
1989 a4^\prall^\markup { \sharp }
1991 \once \override Script #'script-priority = #-100
1992 a4^\prall^\markup { \sharp }
1998 Program reference: @internalsref{Script}.
2003 These signs appear in the printed output but have no effect on the
2004 MIDI rendering of the music.
2007 @node Fingering instructions
2008 @subsection Fingering instructions
2011 @cindex finger change
2013 Fingering instructions can be entered using
2015 @var{note}-@var{digit}
2017 For finger changes, use markup texts
2019 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2021 c^\markup { \finger "2 - 3" }
2024 You can use the thumb-script to indicate that a note should be
2025 played with the thumb (e.g., in cello music)
2026 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2027 <a_\thumb a'-3>8 <b_\thumb b'-3>
2030 Fingerings for chords can also be added to individual notes
2031 of the chord by adding them after the pitches
2032 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2033 < c-1 e-2 g-3 b-5 >4
2039 You may exercise greater control over fingering chords by
2040 setting @code{fingeringOrientations}
2042 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2043 \set fingeringOrientations = #'(left down)
2044 <c-1 es-2 g-4 bes-5 > 4
2045 \set fingeringOrientations = #'(up right down)
2046 <c-1 es-2 g-4 bes-5 > 4
2049 Using this feature, it is also possible to put fingering instructions
2050 very close to note heads in monophonic music,
2052 @lilypond[verbatim,raggedright,quote,fragment]
2053 \set fingeringOrientations = #'(right)
2060 Program reference: @internalsref{Fingering}.
2062 Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
2066 @subsection Dynamics
2077 @cindex @code{\ffff}
2086 Absolute dynamic marks are specified using a command after a note
2087 @code{c4\ff}. The available dynamic marks are @code{\ppp},
2088 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2089 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
2090 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
2092 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2093 c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2094 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
2101 A crescendo mark is started with @code{\<} and terminated with
2102 @code{\!} or an absolute dynamic. A decrescendo is started with
2103 @code{\>} and is also terminated with @code{\!} or an absolute
2104 dynamic. Because these marks are bound to notes, you must
2105 use spacer notes if multiple marks are needed during one note
2107 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2109 << f1 { s4 s4\< s4\! \> s4\! } >>
2111 This may give rise to very short hairpins. Use @code{minimum-length}
2112 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2116 \override Staff.Hairpin #'minimum-length = #5
2123 You can also use a text saying @emph{cresc.} instead of hairpins
2125 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2136 You can also supply your own texts
2137 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2138 \set crescendoText = \markup { \italic "cresc. poco" }
2139 \set crescendoSpanner = #'dashed-line
2143 To create new dynamic marks or text that should be aligned
2144 with dynamics, see @ref{New dynamic marks}.
2149 @cindex @code{\dynamicUp}
2151 @cindex @code{\dynamicDown}
2152 @code{\dynamicDown},
2153 @cindex @code{\dynamicNeutral}
2154 @code{\dynamicNeutral}.
2159 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
2160 Vertical positioning of these symbols is handled by
2161 @internalsref{DynamicLineSpanner}.
2165 @subsection Breath marks
2167 Breath marks are entered using @code{\breathe}
2169 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2176 The glyph of the breath mark can be tuned by overriding the
2177 @code{text} property of the @code{BreathingSign} layout object with
2178 any markup text. For example,
2179 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
2181 \override BreathingSign #'text
2182 = #(make-musicglyph-markup "scripts.rvarcomma")
2189 Program reference: @internalsref{BreathingSign}.
2191 Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
2194 @node Running trills
2195 @subsection Running trills
2197 Long running trills are made with @code{\startTrillSpan} and
2198 @code{\stopTrillSpan},
2200 @lilypond[verbatim,raggedright,relative=2,quote,fragment]
2202 << { c1 \startTrillSpan }
2203 { s2. \grace { d16[\stopTrillSpan e] } } >>
2210 @code{\startTrillSpan},
2211 @cindex @code{\startTrillSpan}
2212 @code{\stopTrillSpan}.
2213 @cindex @code{\stopTrillSpan}
2218 This manual: @ref{Pitched trills}.
2220 Program reference: @internalsref{TrillSpanner}.
2224 @subsection Glissando
2227 @cindex @code{\glissando}
2229 A glissando is a smooth change in pitch. It is denoted by a line or a
2230 wavy line between two notes. It is requested by attaching
2231 @code{\glissando} to a note
2233 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2235 \override Glissando #'style = #'zigzag
2242 Program reference: @internalsref{Glissando}.
2244 Example files: @file{input/@/regression/@/glissando@/.ly}.
2249 Printing text over the line (such as @emph{gliss.}) is not supported.
2253 @subsection Arpeggio
2256 @cindex broken chord
2257 @cindex @code{\arpeggio}
2259 You can specify an arpeggio sign (also known as broken chord) on a
2260 chord by attaching an @code{\arpeggio} to a chord
2262 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2266 A square bracket on the left indicates that the player should not
2267 arpeggiate the chord
2269 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2274 The direction of the arpeggio is sometimes denoted by adding an
2275 arrowhead to the wiggly line
2277 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2289 When an arpeggio crosses staves, you may attach an arpeggio to the chords
2290 in both staves and set
2291 @internalsref{PianoStaff}.@code{connectArpeggios}
2293 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2294 \context PianoStaff <<
2295 \set PianoStaff.connectArpeggios = ##t
2296 \new Staff { <c' e g c>\arpeggio }
2297 \new Staff { \clef bass <c,, e g>\arpeggio }
2305 @cindex @code{\arpeggioUp}
2307 @cindex @code{\arpeggioDown}
2308 @code{\arpeggioDown},
2309 @cindex @code{\arpeggioNeutral}
2310 @code{\arpeggioNeutral},
2311 @cindex @code{\arpeggioBracket}
2312 @code{\arpeggioBracket}.
2317 Notation manual: @ref{Ties}, for writing out arpeggios.
2319 Program reference: @internalsref{Arpeggio}.
2324 It is not possible to mix connected arpeggios and unconnected
2325 arpeggios in one @internalsref{PianoStaff} at the same point in time.
2332 Polyphony in music refers to having more than one voice occuring in
2333 a piece of music. Polyphony in LilyPond refers to having more than
2334 one voice on the same staff.
2338 * Explicitly instantiating voices::
2339 * Collision Resolution::
2343 @node Basic polyphony
2344 @subsection Basic polyphony
2348 The easiest way to enter fragments with more than one voice on a staff
2349 is to enter each voice as a sequence (with @code{@{...@}}), and combine
2350 them simultaneously, separating the voices with @code{\\}
2354 @lilypond[quote,verbatim,fragment]
2355 \new Staff \relative c' {
2358 { g4 f e | d2 e2 } \\
2359 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
2365 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
2366 voices are sometimes called ``layers'' in other notation packages}
2368 to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
2369 each of these contexts, vertical direction of slurs, stems, etc., is set
2372 These voices are all seperate from the voice that contains the notes just
2373 outside the @code{<< \\ >>} construct. This should be noted when making
2374 changes at the voice level. This also means that slurs and ties cannot go
2375 into or out of a @code{<< \\ >>} construct. Conversely, parallel voices
2376 from separate @code{<< \\ >>} constructs on the same staff are the the
2377 same voice. Here is the same example, with different noteheads for each
2378 voice. Note that the change to the note-head style in the main voice does not affect
2379 the inside of the @code{<< \\ >>} constructs. Also, the change to the second
2380 voice in the first @code{<< \\ >>} construct is effective in the second
2381 @code{<< \\ >>}, and the voice is tied accross the two constructs.
2383 @lilypond[quote,verbatim,fragment]
2384 \new Staff \relative c' {
2385 \override NoteHead #'style = #'cross
2389 { \override NoteHead #'style = #'triangle
2394 { c8 b16 a b8 g ~ g2 } \\
2395 { \override NoteHead #'style = #'slash s4 b4 c2 }
2400 Polyphony does not change the relationship of notes within a
2401 @code{\relative @{ @}} block. Each note is calculated relative
2402 to the note immediately preceding it.
2405 \relative @{ noteA << noteB \\ noteC >> noteD @}
2408 @code{noteC} is relative to @code{noteB}, not @code{noteA};
2409 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
2412 @node Explicitly instantiating voices
2413 @subsection Explicitly instantiating voices
2415 @internalsref{Voice} contexts can also also be instantiated manually
2416 inside a @code{<< >>} block to create polyphonic music, using
2417 @code{\voiceOne}, up to @code{\voiceFour} to assign stem directions
2418 and a horizontal shift for each part.
2422 << \upper \\ \lower >>
2430 \context Voice = "1" @{ \voiceOne \upper @}
2431 \context Voice = "2" @{ \voiceTwo \lower @}
2435 The @code{\voiceXXX} commands set the direction of stems, slurs, ties,
2436 articulations, text annotations, augmentation dots of dotted
2437 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make
2438 these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour}
2439 make them point downwards.
2440 The command @code{\oneVoice} will revert back to the normal setting.
2442 An expression that appears directly inside a @code{<< >>} belongs to
2443 the main voice. This is useful when extra voices appear while the main
2444 voice is playing. Here is a more correct rendition of the example from
2445 the previous section. The crossed noteheads demonstrate that the main
2446 melody is now in a single voice context.
2448 @lilypond[quote,raggedright,verbatim]
2449 \new Staff \relative c' {
2450 \override NoteHead #'style = #'cross
2455 \context Voice="1" { \voiceTwo
2456 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
2459 \new Voice { \voiceThree
2468 The correct definition of the voices allows the melody to be slurred.
2469 @lilypond[quote,raggedright,verbatim]
2470 \new Staff \relative c' {
2475 \context Voice="1" { \voiceTwo
2476 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
2479 \new Voice { \voiceThree
2488 Avoiding the @code{\\} seperator also allows nesting polyphony
2489 constructs, which in some case might be a more natural way to typeset
2492 @lilypond[quote,raggedright,verbatim]
2493 \new Staff \relative c' {
2498 \context Voice="1" { \voiceTwo
2501 {c8 b16 a b8 g ~ g2}
2502 \new Voice { \voiceThree
2515 @node Collision Resolution
2516 @subsection Collision Resolution
2518 Normally, note heads with a different number of dots are not merged, but
2519 when the object property @code{merge-differently-dotted} is set in
2520 the @internalsref{NoteCollision} object, they are merged
2521 @lilypond[quote,verbatim,fragment,raggedright,relative=2]
2524 \override Staff.NoteCollision
2525 #'merge-differently-dotted = ##t
2527 } \\ { g8.[ f16] g8.[ f16] } >>
2530 Similarly, you can merge half note heads with eighth notes, by setting
2531 @code{merge-differently-headed}
2532 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2535 \override Staff.NoteCollision
2536 #'merge-differently-headed = ##t
2537 c8 c4. } \\ { c2 c2 } >>
2540 LilyPond also vertically shifts rests that are opposite of a stem,
2543 @lilypond[quote,raggedright,fragment,verbatim]
2544 \context Voice << c''4 \\ r4 >>
2550 @cindex @code{\oneVoice}
2552 @cindex @code{\voiceOne}
2554 @cindex @code{\voiceTwo}
2556 @cindex @code{\voiceThree}
2558 @cindex @code{\voiceFour}
2561 @cindex @code{\shiftOn}
2563 @cindex @code{\shiftOnn}
2565 @cindex @code{\shiftOnnn}
2567 @cindex @code{\shiftOff}
2568 @code{\shiftOff}: these commands specify in what chords of the current
2569 voice should be shifted. The outer voices (normally: voice one and
2570 two) have @code{\shiftOff}, while the inner voices (three and four)
2571 have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define
2572 further shift levels.
2574 When LilyPond cannot cope, the @code{force-hshift}
2575 property of the @internalsref{NoteColumn} object and pitched rests can
2576 be used to override typesetting decisions.
2578 @lilypond[quote,verbatim,raggedright]
2585 \once \override NoteColumn #'force-hshift = #1.7
2593 Program reference: the objects responsible for resolving collisions are
2594 @internalsref{NoteCollision} and @internalsref{RestCollision}.
2597 @inputfileref{input/@/regression,collision@/-dots@/.ly},
2598 @inputfileref{input/@/regression,collision@/-head-chords@/.ly},
2599 @inputfileref{input/@/regression,collision@/-heads@/.ly},
2600 @inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
2601 @inputfileref{input/@/regression,collisions@/.ly}.
2606 When using @code{merge-differently-headed} with an upstem eighth or a
2607 shorter note, and a downstem half note, the eighth note gets the wrong
2610 There is no support for clusters where the same note occurs with
2611 different accidentals in the same chord. In this case, it is
2612 recommended to use enharmonic transcription, or to use special cluster
2613 notation (see @ref{Clusters}).
2620 Repetition is a central concept in music, and multiple notations exist
2626 * Repeats and MIDI::
2627 * Manual repeat commands::
2629 * Tremolo subdivisions::
2635 @subsection Repeat types
2638 @cindex @code{\repeat}
2640 The following types of repetition are supported
2644 Repeated music is fully written (played) out. This is useful when
2645 entering repetitious music. This is the only kind of repeat that
2646 is included in MIDI output.
2649 Repeats are not written out, but alternative endings (volte) are
2650 printed, left to right with brackets. This is the standard notation
2651 for repeats with alternatives. These are not played in MIDI output by default.
2655 Alternative endings are written stacked. This has limited use but may be
2656 used to typeset two lines of lyrics in songs with repeats, see
2657 @inputfileref{input,star-spangled-banner@/.ly}.
2661 Make tremolo beams. These are not played in MIDI output by default.
2664 Make beat or measure repeats. These look like percent signs. These
2665 are not played in MIDI output by default. Percent repeats must be
2666 declared within a Voice context.
2672 @subsection Repeat syntax
2674 LilyPond has one syntactic construct for specifying different types of
2675 repeats. The syntax is
2678 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2681 If you have alternative endings, you may add
2682 @cindex @code{\alternative}
2693 where each @var{alternative} is a music expression. If you do not
2694 give enough alternatives for all of the repeats, the first alternative
2695 is assumed to be played more than once.
2697 Standard repeats are used like this
2698 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2700 \repeat volta 2 { c4 d e f }
2701 \repeat volta 2 { f e d c }
2704 With alternative endings
2705 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2707 \repeat volta 2 {c4 d e f}
2708 \alternative { {d2 d} {f f,} }
2711 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2714 \repeat volta 4 { e | c2 d2 | e2 f2 | }
2715 \alternative { { g4 g g } { a | a a a a | b2. } }
2719 It is possible to shorten volta brackets
2720 by setting @code{voltaSpannerDuration}. In the next example, the
2721 bracket only lasts one measure, which is a duration of 3/4.
2723 @lilypond[verbatim,raggedright,quote]
2727 \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2728 \repeat "volta" 5 { d d d }
2729 \alternative { { e e e f f f }
2739 Brackets for the repeat are normally only printed over the topmost
2740 staff. This can be adjusted by setting the @code{voltaOnThisStaff}
2741 property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
2746 @cindex repeat, ambiguous
2748 A nested repeat like
2757 is ambiguous, since it is is not clear to which @code{\repeat} the
2758 @code{\alternative} belongs. This ambiguity is resolved by always
2759 having the @code{\alternative} belong to the inner @code{\repeat}.
2760 For clarity, it is advisable to use braces in such situations.
2762 Timing information is not remembered at the start of an alternative,
2763 so after a repeat timing information must be reset by hand, for
2764 example by setting @code{Score.measurePosition} or entering
2765 @code{\partial}. Similarly, slurs or ties are also not repeated.
2768 @node Repeats and MIDI
2769 @subsection Repeats and MIDI
2771 @cindex expanding repeats
2772 @cindex @code{\unfoldRepeats}
2774 With a little bit of tweaking, all types of repeats can be present
2775 in the MIDI output. This is achieved by applying the
2776 @code{\unfoldRepeats} music function. This functions changes all
2777 repeats to unfold repeats.
2779 @lilypond[quote,verbatim,fragment,linewidth=8.0\cm]
2781 \repeat tremolo 8 {c'32 e' }
2782 \repeat percent 2 { c''8 d'' }
2783 \repeat volta 2 {c'4 d' e' f'}
2792 When creating a score file using @code{\unfoldRepeats} for midi, then
2793 it is necessary to make two @code{\score} blocks. One for MIDI (with
2794 unfolded repeats) and one for notation (with volta, tremolo, and
2795 percent repeats). For example,
2803 \unfoldRepeats @var{..music..}
2809 @node Manual repeat commands
2810 @subsection Manual repeat commands
2812 @cindex @code{repeatCommands}
2814 The property @code{repeatCommands} can be used to control the layout of
2815 repeats. Its value is a Scheme list of repeat commands.
2818 @item @code{start-repeat}
2819 Print a @code{|:} bar line.
2821 @item @code{end-repeat}
2822 Print a @code{:|} bar line.
2824 @item @code{(volta @var{text})}
2825 Print a volta bracket saying @var{text}: The text can be specified as
2826 a text string or as a markup text, see @ref{Text markup}. Do not
2827 forget to change the font, as the default number font does not contain
2828 alphabetic characters;
2830 @item @code{(volta #f)}
2831 Stop a running volta bracket.
2834 @lilypond[quote,raggedright,verbatim,fragment,relative=2]
2836 \set Score.repeatCommands = #'((volta "93") end-repeat)
2838 \set Score.repeatCommands = #'((volta #f))
2845 Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
2846 @internalsref{VoltaRepeatedMusic},
2847 @internalsref{UnfoldedRepeatedMusic}, and
2848 @internalsref{FoldedRepeatedMusic}.
2851 @node Tremolo repeats
2852 @subsection Tremolo repeats
2854 @cindex tremolo beams
2856 To place tremolo marks between notes, use @code{\repeat} with tremolo
2858 @lilypond[quote,verbatim,raggedright]
2859 \new Voice \relative c' {
2860 \repeat "tremolo" 8 { c16 d16 }
2861 \repeat "tremolo" 4 { c16 d16 }
2862 \repeat "tremolo" 2 { c16 d16 }
2866 Tremolo marks can also be put on a single note. In this case, the
2867 note should not be surrounded by braces.
2868 @lilypond[quote,verbatim,raggedright]
2869 \repeat "tremolo" 4 c'16
2872 Similar output is obtained using the tremolo subdivision, described in
2873 @ref{Tremolo subdivisions}.
2878 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
2880 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
2882 Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
2883 @inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
2886 @node Tremolo subdivisions
2887 @subsection Tremolo subdivisions
2889 @cindex tremolo marks
2890 @cindex @code{tremoloFlags}
2892 Tremolo marks can be printed on a single note by adding
2893 `@code{:}[@var{number}]' after the note. The number indicates the
2894 duration of the subdivision, and it must be at least 8. A
2895 @var{length} value of 8 gives one line across the note stem. If the
2896 length is omitted, the last value (stored in @code{tremoloFlags}) is
2899 @lilypond[quote,raggedright,verbatim,fragment]
2900 c'2:8 c':32 | c': c': |
2906 Tremolos entered in this way do not carry over into the MIDI output.
2911 In this manual: @ref{Tremolo repeats}.
2913 Elsewhere: @internalsref{StemTremolo}.
2916 @node Measure repeats
2917 @subsection Measure repeats
2919 @cindex percent repeats
2920 @cindex measure repeats
2922 In the @code{percent} style, a note pattern can be repeated. It is
2923 printed once, and then the pattern is replaced with a special sign.
2924 Patterns of one and two measures are replaced by percent-like signs,
2925 patterns that divide the measure length are replaced by slashes.
2926 Percent repeats must be declared within a @code{Voice} context.
2928 @lilypond[quote,verbatim,raggedright]
2929 \new Voice \relative c' {
2930 \repeat "percent" 4 { c4 }
2931 \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
2935 Measure repeats of more than 2 measures get a counter, if you switch
2936 on the @code{countPercentRepeats} property,
2938 @lilypond[relative=2,fragment,quote,verbatim,raggedright]
2939 \set countPercentRepeats = ##t
2941 \repeat "percent" 4 { c1 }
2946 Isolated percents can also be printed. This is done by putting a multi
2947 measure rest with a different print function,
2949 @lilypond[fragment,verbatim]
2950 \override MultiMeasureRest #'print-function
2951 = #Multi_measure_rest::percent
2960 Program reference: @internalsref{RepeatSlash},
2961 @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
2962 @internalsref{DoublePercentRepeatCounter},
2963 @internalsref{PercentRepeatCounter},
2964 @internalsref{PercentRepeatedMusic}, and