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.
168 @lilypond[quote,raggedright,fragment,verbatim]
169 cis' cis' cis'! cis'?
175 The automatic production of accidentals can be tuned in many
176 ways. For more information, refer to @ref{Automatic accidentals}.
181 @subsection Micro tones
183 @cindex quarter tones
184 @cindex semi-flats, semi-sharps
186 Half-flats and half-sharps are formed by adding @code{-eh} and
187 @code{-ih}; the following is a series of Cs with increasing pitches
189 @lilypond[verbatim,raggedright,quote,relative=2,fragment]
190 \set Staff.extraNatural = ##f
194 Micro tones are also exported to the MIDI file.
199 There are no generally accepted standards for denoting three quarter
200 flats, so LilyPond's symbol does not conform to any standard.
208 A chord is formed by a enclosing a set of pitches in @code{<} and
209 @code{>}. A chord may be followed by a duration, and a set of
210 articulations, just like simple notes
212 @lilypond[verbatim,raggedright,fragment,quote,relative=1]
216 For more information about chords, see @ref{Chord names}.
227 Rests are entered like notes with the note name @code{r}
229 @lilypond[fragment,quote,raggedright,verbatim]
233 Whole bar rests, centered in middle of the bar,
234 must be done with multi-measure rests. They can be used for a
235 single bar as well as many bars, and are discussed in
236 @ref{Multi measure rests}.
239 A rest's vertical position may be explicitly specified by entering a
240 note with the @code{\rest} keyword appended, the rest will be placed at
241 the note's place. This makes manual formatting in polyphonic music
242 easier. Automatic rest collision formatting will leave these rests
245 @lilypond[fragment,quote,raggedright,verbatim]
251 Program reference: @internalsref{Rest}.
258 @cindex Invisible rest
263 An invisible rest (also called a `skip') can be entered like a note
264 with note name `@code{s}' or with @code{\skip @var{duration}}
266 @lilypond[fragment,quote,raggedright,verbatim,relative=2]
267 a4 a4 s4 a4 \skip 1 a4
270 The @code{s} syntax is only available in note mode and chord mode. In
271 other situations, for example, when entering lyrics, you should use
272 the @code{\skip} command
274 @lilypond[quote,raggedright,verbatim]
277 \new Lyrics \lyricmode { \skip 2 bla2 }
281 The skip command is merely an empty musical placeholder. It does not
282 produce any output, not even transparent output.
284 The @code{s} skip command does create @internalsref{Staff} and
285 @internalsref{Voice} when necessary, similar to note and rest
286 commands. For example, the following results in an empty staff.
288 @lilypond[quote,raggedright,verbatim]
292 The fragment @code{@{ \skip 4 @} } would produce an empty page.
296 Program reference: @internalsref{SkipMusic}.
300 @subsection Durations
303 @cindex @code{\longa}
304 @cindex @code{\breve}
305 @cindex @code{\maxima}
307 In Note, Chord, and Lyrics mode, durations are designated by numbers and
308 dots: durations are entered as their reciprocal values. For example, a
309 quarter note is entered using a @code{4} (since it is a 1/4 note), while
310 a half note is entered using a @code{2} (since it is a 1/2 note). For
311 notes longer than a whole you must use the variables @code{\longa} and
316 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
318 r1 r2 r4 r8 r16 r32 r64 r64
324 a\breve*1/2 \autoBeamOff
325 a1 a2 a4 a8 a16 a32 a64 a64
328 r\longa*1/4 r\breve *1/2
329 r1 r2 r4 r8 r16 r32 r64 r64
335 \remove "Clef_engraver"
336 \override StaffSymbol #'transparent = ##t
337 \override TimeSignature #'transparent = ##t
338 \override BarLine #'transparent = ##t
339 \consists "Pitch_squash_engraver"
345 If the duration is omitted then it is set to the previously entered
346 duration. The default for the first note is a quarter note.
348 @lilypond[quote,raggedright,verbatim,fragment]
349 { a a a2 a a4 a a1 a }
353 @node Augmentation dots
354 @subsection Augmentation dots
358 To obtain dotted note lenghts, simply add a dot (`@code{.}') to
359 the number. Double-dotted notes are produced in a similar way.
361 @lilypond[quote,raggedright,fragment,verbatim]
362 a'4 b' c''4. b'8 a'4. b'4.. c''8.
367 Dots are normally moved up to avoid staff lines, except in polyphonic
368 situations. The following commands may be used to force a particular
371 @cindex @code{\dotsUp}
373 @cindex @code{\dotsDown}
375 @cindex @code{\dotsNeutral}
380 Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
388 @cindex @code{\times}
390 Tuplets are made out of a music expression by multiplying all durations
394 \times @var{fraction} @var{musicexpr}
398 The duration of @var{musicexpr} will be multiplied by the fraction.
399 The fraction's denominator will be printed over the notes, optionally
400 with a bracket. The most common tuplet is the triplet in which 3
401 notes have the length of 2, so the notes are 2/3 of their written
404 @lilypond[quote,raggedright,fragment,verbatim]
405 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
408 Tuplets may be nested, for example,
410 @lilypond[fragment,raggedright,verbatim,relative=2]
411 \set tupletNumberFormatFunction = #fraction-tuplet-formatter
414 \times 3/5 { a a a a a }
420 @cindex @code{\tupletUp}
422 @cindex @code{\tupletDown}
424 @cindex @code{\tupletNeutral}
425 @code{\tupletNeutral}.
430 @cindex @code{tupletNumberFormatFunction}
431 @cindex tuplet formatting
433 The property @code{tupletSpannerDuration} specifies how long each
434 bracket should last. With this, you can make lots of tuplets while
435 typing @code{\times} only once, thus saving lots of typing. In the next
436 example, there are two triplets shown, while @code{\times} was only
439 @lilypond[quote,fragment,relative=1,raggedright,verbatim]
440 \set tupletSpannerDuration = #(ly:make-moment 1 4)
441 \times 2/3 { c'8 c c c c c }
444 The format of the number is determined by the property
445 @code{tupletNumberFormatFunction}. The default prints only the
446 denominator, but if it is set to the Scheme function
447 @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
456 Program reference: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}.
458 Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
462 @node Scaling durations
463 @subsection Scaling durations
465 You can alter the length of duration by a fraction @var{N/M}
466 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
467 will not affect the appearance of the notes or rests produced.
469 In the following example, the first three notes take up exactly two
470 beats, but no triplet bracket is printed.
471 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
473 a4*2/3 gis4*2/3 a4*2/3
481 This manual: @ref{Tuplets}
485 @node Alternate music entry
486 @section Alternate music entry
489 This section deals with tricks and features of the input language that
490 were added solely to help entering music and finding and correcting
491 mistakes. There are also external tools that make debugging easier.
492 See @ref{Point and click} for more information.
494 It is also possible to enter and edit music using other programs, such as
495 GUI interfaces or MIDI sequencers. Refer to the LilyPond
496 website for more information.
504 * Skipping corrected music::
505 * Automatic note splitting::
509 @node Relative octaves
510 @subsection Relative octaves
513 @cindex Relative octave specification
514 @cindex @code{\relative}
516 Octaves are specified by adding @code{'} and @code{,} to pitch names.
517 When you copy existing music, it is easy to accidentally put a pitch
518 in the wrong octave and hard to find such an error. The relative
519 octave mode prevents these errors by making the mistakes much
520 larger: a single error puts the rest of the piece off by one octave
523 \relative @var{startpitch} @var{musicexpr}
530 \relative @var{musicexpr}
533 The octave of notes that appear in @var{musicexpr} are calculated as
534 follows: if no octave changing marks are used, the basic interval
535 between this and the last note is always taken to be a fourth or
536 less. This distance is determined without regarding alterations; a
537 @code{fisis} following a @code{ceses} will be put above the
538 @code{ceses}. In other words, a doubly-augmented fourth is considered
539 a smaller interval than a diminshed fifth, even though the fourth is
540 seven semitones while the fifth is only six semitones.
542 The octave changing marks @code{'} and @code{,} can be added to raise
543 or lower the pitch by an extra octave. Upon entering relative mode,
544 an absolute starting pitch can be specified that will act as the
545 predecessor of the first note of @var{musicexpr}. If no starting pitch
546 is specified, then middle C is used as a start.
548 Here is the relative mode shown in action
549 @lilypond[quote,fragment,raggedright,verbatim]
555 Octave changing marks are used for intervals greater than a fourth
556 @lilypond[quote,raggedright,fragment,verbatim]
562 If the preceding item is a chord, the first note of the chord is used
563 to determine the first note of the next chord
565 @lilypond[quote,raggedright,fragment,verbatim]
573 The pitch after the @code{\relative} contains a note name.
575 The relative conversion will not affect @code{\transpose},
576 @code{\chordmode} or @code{\relative} sections in its argument. To use
577 relative within transposed music, an additional @code{\relative} must
578 be placed inside @code{\transpose}.
582 @subsection Octave check
586 Octave checks make octave errors easier to correct: a note may be
587 followed by @code{=}@var{quotes} which indicates what its absolute
588 octave should be. In the following example,
591 \relative c'' @{ c='' b=' d,='' @}
595 the @code{d} will generate a warning, because a @code{d''} is expected
596 (because @code{b'} to @code{d''} is only a third), but a @code{d'} is
597 found. In the output, the octave is corrected to be a @code{d''} and
598 the next note is calculated relative to @code{d''} instead of @code{d'}.
600 There is also a syntax that is separate from the notes. The syntax
606 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
607 quotes) in \relative mode. If not, a warning is printed, and the
610 In the example below, the first check passes without incident, since
611 the @code{e} (in relative mode) is within a fifth of @code{a'}. However,
612 the second check produces a warning, since the @code{e} is not within
613 a fifth of @code{b'}. The warning message is printed, and the octave
614 is adjusted so that the following notes are in the correct octave
626 The octave of a note following an octave check is determined with
627 respect to the note preceding it. In the next fragment, the last note
628 is an @code{a'}, above middle C. That means that the @code{\octave}
629 check passes successfully, so the check could be deleted without changing
630 the output of the piece.
632 @lilypond[quote,raggedright,verbatim,fragment]
642 @subsection Transpose
645 @cindex transposition of pitches
646 @cindex @code{\transpose}
648 A music expression can be transposed with @code{\transpose}. The
651 \transpose @var{from} @var{to} @var{musicexpr}
654 This means that @var{musicexpr} is transposed by the interval between
655 the pitches @var{from} and @var{to}: any note with pitch @code{from}
656 is changed to @code{to}.
658 For example, consider a piece written in the key of D-major. If
659 this piece is a little too low for its performer, it can be
660 transposed up to E-major with
662 \transpose d e @dots{}
665 Consider a part written for violin (a C instrument). If
666 this part is to be played on the A clarinet, the following
667 transposition will produce the appropriate part
670 \transpose a c @dots{}
673 @code{\transpose} distinguishes between enharmonic pitches: both
674 @code{\transpose c cis} or @code{\transpose c des} will transpose up
675 half a tone. The first version will print sharps and the second
676 version will print flats
678 @lilypond[quote,raggedright,verbatim]
679 mus = { \key d \major cis d fis g }
688 @code{\transpose} may also be used to input written notes for a
689 transposing instrument. Pitches are normally entered into LilyPond
690 in C (or ``concert pitch''), but they may be entered in another
691 key. For example, when entering music for a B-flat trumpet which
692 begins on concert D, one would write
695 \transpose c bes @{ e4 @dots{} @}
698 To print this music in B-flat again (ie producing a trumpet part,
699 instead of a concert pitch conductor's score) you would wrap the
700 existing music with another @code{transpose}
703 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
709 Program reference: @internalsref{TransposedMusic}.
714 If you want to use both @code{\transpose} and @code{\relative},
715 you must put @code{\transpose} outside of @code{\relative}, since
716 @code{\relative} will have no effect music that appears inside a
721 @subsection Bar check
724 @cindex @code{barCheckSynchronize}
727 Bar checks help detect errors in the durations. A bar check is
728 entered using the bar symbol, `@code{|}'. Whenever it is encountered
729 during interpretation, it should fall on a measure boundary. If it
730 does not, a warning is printed. In the next example, the second bar
731 check will signal an error
733 \time 3/4 c2 e4 | g2 |
736 Bar checks can also be used in lyrics, for example
741 Twin -- kle | Twin -- kle
745 Failed bar checks are caused by entering incorrect
746 durations. Incorrect durations often completely garble up the score,
747 especially if the score is polyphonic, so a good place to start correcting
748 input is by scanning for failed bar checks and incorrect durations.
751 @cindex @code{pipeSymbol}
753 It is also possible to redefine the meaning of @code{|}. This is done
754 by assigning a music expression to @code{pipeSymbol},
756 @lilypond[quote,raggedright,verbatim]
757 pipeSymbol = \bar "||"
763 @node Barnumber check
764 @subsection Barnumber check
766 When copying large pieces of music, it can be helpful to check that
767 the LilyPond bar number corresponds to the original that you are
768 entering from. This can be checked with @code{\barNumberCheck}, for
776 will print a warning if the @code{currentBarNumber} is not 123 when it
780 @node Skipping corrected music
781 @subsection Skipping corrected music
784 @cindex @code{skipTypesetting}
785 @cindex @code{showLastLength}
787 When entering or copying music, only the music near the end (where you
788 are adding notes) is interesting to view and correct. To speed up
789 this correction process, it is possible to skip typesetting of all but
790 the last few measures. This is achieved by putting
793 showLastLength = R1*5
798 in your source file. This will render only the last 5 measures
799 (assuming 4/4 time signature) of every @code{\score} in the input
800 file. For longer pieces, rendering only a small part is often an order
801 of magnitude quicker than rendering it completely
803 Skipping parts of a score can be controlled in a more fine-grained
804 fashing with the property @code{Score.skipTypesetting}. When it is
805 set, no typesetting is performed at all.
807 @lilypond[quote,fragment,raggedright,verbatim]
810 \set Score.skipTypesetting = ##t
812 \set Score.skipTypesetting = ##f
816 In polyphonic music, @code{Score.skipTypesetting} will affect all
817 voices and staves, saving even more time.
820 @node Automatic note splitting
821 @subsection Automatic note splitting
823 Long notes can be converted automatically to tied notes. This is done
824 by replacing the @internalsref{Note_heads_engraver} by the
825 @internalsref{Completion_heads_engraver}.
826 In the following examples, notes crossing the bar line are split and tied.
828 @lilypond[quote,fragment,verbatim,relative=1,linewidth=12\cm]
830 \remove "Note_heads_engraver"
831 \consists "Completion_heads_engraver"
833 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
837 This engraver splits all running notes at the bar line, and inserts
838 ties. One of its uses is to debug complex scores: if the measures are
839 not entirely filled, then the ties exactly show how much each measure
845 Not all durations (especially those containing tuplets) can be
846 represented exactly with normal notes and dots, but the engraver will
849 @code{Completion_heads_engraver} only affects notes; it does not split
855 Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
859 Program reference: @internalsref{Completion_heads_engraver}.
864 @section Staff notation
866 @cindex Staff notation
868 This section describes music notation that occurs on staff level,
869 such as key signatures, clefs and time signatures.
878 * System start delimiters::
888 The clef indicates which lines of the staff correspond to which
889 pitches. The clef is set with the @code{\clef} command
891 @lilypond[quote,raggedright,fragment,verbatim]
892 { c''2 \clef alto g'2 }
902 @cindex mezzosoprano clef
903 @cindex baritone clef
904 @cindex varbaritone clef
907 Supported clefs finclude
909 @item treble, violin, G, G2
918 G clef on 1st line, so-called French violin clef
935 By adding @code{_8} or @code{^8} to the clef name, the clef is
936 transposed one octave down or up, respectively, and @code{_15} and
937 @code{^15} transposes by two octaves. The argument @var{clefname}
938 must be enclosed in quotes when it contains underscores or digits. For
941 @cindex choral tenor clef
942 @lilypond[quote,raggedright,verbatim,fragment,relative=1]
949 The command @code{\clef "treble_8"} is equivalent to setting @code{clefGlyph},
950 @code{clefPosition} (which controls the Y position of the clef),
951 @code{middleCPosition} and @code{clefOctavation}. A clef is printed
952 when any of these properties are changed. The following example shows
953 possibilities when setting properties manually.
955 @lilypond[quote,raggedright,verbatim]
957 \set Staff.clefGlyph = #"clefs.F"
958 \set Staff.clefPosition = #2
960 \set Staff.clefGlyph = #"clefs.G"
962 \set Staff.clefGlyph = #"clefs.C"
964 \set Staff.clefOctavation = #7
966 \set Staff.clefOctavation = #0
967 \set Staff.clefPosition = #0
971 \set Staff.middleCPosition = #4
979 Program reference: @internalsref{Clef}.
983 @subsection Key signature
985 @cindex Key signature
988 The key signature indicates the tonality in which a piece is played. It
989 is denoted by a set of alterations (flats or sharps) at the start of the
992 Setting or changing the key signature is done with the @code{\key}
996 @code{\key} @var{pitch} @var{type}
999 @cindex @code{\minor}
1000 @cindex @code{\major}
1001 @cindex @code{\minor}
1002 @cindex @code{\ionian}
1003 @cindex @code{\locrian}
1004 @cindex @code{\aeolian}
1005 @cindex @code{\mixolydian}
1006 @cindex @code{\lydian}
1007 @cindex @code{\phrygian}
1008 @cindex @code{\dorian}
1009 @cindex church modes
1011 Here, @var{type} should be @code{\major} or @code{\minor} to get
1012 @var{pitch}-major or @var{pitch}-minor, respectively. You may also
1013 use the standard mode names (also called ``church modes''): @code{\ionian},
1014 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
1015 @code{\phrygian}, and @code{\dorian}.
1017 This command sets the context property
1018 @code{Staff.keySignature}. Non-standard key signatures
1019 can be specified by setting this property directly.
1021 Accidentals and key signatures often confuse new users, because
1022 unaltered notes get natural signs depending on the key signature. For
1023 more information, see @ref{More about pitches}.
1028 A natural sign is printed to cancel any previous accidentals. This
1029 can be suppressed by setting the @code{Staff.printKeyCancellation}
1032 @lilypond[quote,fragment,raggedright,fragment,verbatim,relative=2]
1037 \set Staff.printKeyCancellation = ##f
1047 Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}.
1050 @node Time signature
1051 @subsection Time signature
1053 @cindex Time signature
1055 @cindex @code{\time}
1057 Time signature indicates the metrum of a piece: a regular pattern of
1058 strong and weak beats. It is denoted by a fraction at the start of the
1061 The time signature is set with the @code{\time} command
1063 @lilypond[quote,raggedright,fragment,verbatim]
1064 \time 2/4 c'2 \time 3/4 c'2.
1069 The symbol that is printed can be customized with the @code{style}
1070 property. Setting it to @code{#'()} uses fraction style for 4/4 and
1073 @lilypond[fragment,quote,raggedright,verbatim]
1076 \override Staff.TimeSignature #'style = #'()
1081 There are many more options for its layout. See @ref{Ancient time
1082 signatures} for more examples.
1084 @code{\time} sets the property @code{timeSignatureFraction},
1085 @code{beatLength} and @code{measureLength} in the @code{Timing}
1086 context, which is normally aliased to @internalsref{Score}. The
1087 property @code{measureLength} determines where bar lines should be
1088 inserted, and how automatic beams should be generated. Changing the
1089 value of @code{timeSignatureFraction} also causes the symbol to be
1092 More options are available through the Scheme function
1093 @code{set-time-signature}. In combination with the
1094 @internalsref{Measure_grouping_engraver}, it will create
1095 @internalsref{MeasureGrouping} signs. Such signs ease reading
1096 rhythmically complex modern music. In the following example, the 9/8
1097 measure is subdivided in 2, 2, 2 and 3. This is passed to
1098 @code{set-time-signature} as the third argument @code{(2 2 2 3)}
1100 @lilypond[quote,raggedright,verbatim]
1103 #(set-time-signature 9 8 '(2 2 2 3))
1104 g8[ g] d[ d] g[ g] a8[( bes g]) |
1105 #(set-time-signature 5 8 '(3 2))
1111 \consists "Measure_grouping_engraver"
1119 Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_translator}.
1124 Automatic beaming does not use the measure grouping specified with
1125 @code{set-time-signature}.
1128 @node Partial measures
1129 @subsection Partial measures
1133 @cindex partial measure
1134 @cindex measure, partial
1135 @cindex shorten measures
1136 @cindex @code{\partial}
1138 Partial measures, such as an anacrusis or upbeat, are entered using the
1140 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1141 \partial 16*5 c16 cis d dis e | a2. c,4 | b2
1144 The syntax for this command is
1147 \partial @var{duration}
1150 This is internally translated into
1153 \set Timing.measurePosition = -@var{length of duration}
1156 The property @code{measurePosition} contains a rational number
1157 indicating how much of the measure has passed at this point.
1162 This command does not take into account grace notes at the start of
1163 the music. When a piece starts with graces notes in the pickup, then
1164 the @code{\partial} should follow the grace notes
1166 @lilypond[verbatim,quote,raggedright,relative,fragment]
1175 @subsection Bar lines
1179 @cindex measure lines
1182 Bar lines delimit measures, but are also used to indicate
1183 repeats. Normally they are inserted automatically. Line
1184 breaks may only happen on bar lines.
1186 Special types of bar lines can be forced with the @code{\bar} command
1188 @lilypond[quote,raggedright,relative=2,fragment,verbatim]
1192 The following bar types are available
1194 @lilypondfile[raggedright,quote]{bar-lines.ly}
1196 To allow a line break where there is no visible bar line, use
1203 This will insert an invisible bar line and allow line breaks at this
1206 In scores with many staves, a @code{\bar} command in one staff is
1207 automatically applied to all staves. The resulting bar lines are
1208 connected between different staves of a StaffGroup
1210 @lilypond[quote,raggedright,fragment,verbatim]
1212 \context StaffGroup <<
1218 \new Staff { \clef bass c4 g e g }
1220 \new Staff { \clef bass c2 c2 }
1227 @cindex @code{whichBar}
1228 @cindex @code{repeatCommands}
1229 @cindex @code{defaultBarType}
1231 The command @code{\bar }@var{bartype} is a short cut for doing
1232 @code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
1233 is set to a string, a bar line of that type is created.
1235 A bar line is created whenever the @code{whichBar} property is set.
1236 At the start of a measure it is set to the contents of
1237 @code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used
1238 to override default measure bars.
1240 You are encouraged to use @code{\repeat} for repetitions. See
1246 In this manual: @ref{Repeats}, @ref{System start delimiters}.
1248 Program reference: @internalsref{BarLine} (created at
1249 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1251 Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
1254 @node Unmetered music
1255 @subsection Unmetered music
1258 @cindex @code{\cadenzaOn}
1259 @cindex @code{\cadenzaOff}
1261 Bar lines and bar numbers are calculated automatically. For unmetered
1262 music (cadenzas, for example), this is not desirable. To turn off
1263 automatic bar lines and bar numbers, use the commands @code{\cadenzaOn}
1264 and @code{\cadenzaOff}.
1266 @lilypond[verbatim,quote,raggedright,relative=2,fragment]
1278 LilyPond will only insert page breaks at a barline. Unless the unmetered
1279 music ends before the end of the staff line, you will need to insert
1287 to indicate where line breaks can occur.
1290 @node System start delimiters
1291 @subsection System start delimiters
1293 @cindex start of system
1294 @cindex Staff, multiple
1295 @cindex bracket, vertical
1296 @cindex brace, vertical
1299 @cindex staff, choir
1301 Many scores consist of more than one staff. These staves can be
1302 joined in four different ways
1305 @item The group is started with a brace at the left, and bar lines are
1306 connected. This is done with the @internalsref{GrandStaff} context.
1308 @lilypond[verbatim,raggedright,quote]
1316 @item The group is started with a bracket, and bar lines are connected.
1317 This is done with the
1318 @internalsref{StaffGroup} context
1320 @lilypond[verbatim,raggedright,quote]
1328 @item The group is started with a bracket, but bar lines are not
1329 connected. This is done with the @internalsref{ChoirStaff} context.
1331 @lilypond[verbatim,raggedright,quote]
1339 @item The group is started with a vertical line. Bar lines are not
1340 connected. This is the default for the score.
1342 @lilypond[verbatim,raggedright,quote]
1353 The bar lines at the start of each system are
1354 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
1355 @internalsref{SystemStartBracket}. Only one of these types is created
1356 in every context, and that type is determined by the property
1357 @code{systemStartDelimiter}.
1361 @subsection Staff symbol
1363 @cindex adjusting staff symbol
1365 Notes, dynamic signs, etc., are grouped
1366 with a set of horizontal lines, called a staff (plural `staves'). In
1367 LilyPond, these lines are drawn using a separate layout object called
1370 The staff symbol may be tuned in the number, thickness and distance
1371 of lines, using properties. This is demonstrated in the example files
1372 @inputfileref{input/@/test,staff@/-lines@/.ly},
1373 @inputfileref{input/@/test,staff@/-size@/.ly}.
1375 In addition, staves may be started and stopped at will. This is done
1376 with @code{\startStaff} and @code{\stopStaff}.
1378 @lilypond[verbatim,relative=2,fragment]
1380 \override Staff.StaffSymbol #'line-count = 2
1381 \stopStaff \startStaff
1383 \revert Staff.StaffSymbol #'line-count
1384 \stopStaff \startStaff
1388 In combination with Frenched staves, this may be used to typeset ossia
1389 sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
1394 @lilypondfile{ossia.ly}
1396 @cindex staff lines, setting number of
1397 @cindex staff lines, setting thickness of
1398 @cindex thickness of staff lines, setting
1399 @cindex number of staff lines, setting
1403 Program reference: @internalsref{StaffSymbol}.
1405 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
1406 @inputfileref{input/@/test@/,ossia.ly},
1407 @inputfileref{input/@/test,staff@/-size@/.ly}.
1411 @node Connecting notes
1412 @section Connecting notes
1414 This section deals with notation that affects groups of notes.
1432 A tie connects two adjacent note heads of the same pitch. The tie in
1433 effect extends the length of a note. Ties should not be confused with
1434 slurs, which indicate articulation, or phrasing slurs, which indicate
1435 musical phrasing. A tie is entered using the tilde symbol `@code{~}'
1437 @lilypond[quote,raggedright,fragment,verbatim]
1438 e' ~ e' <c' e' g'> ~ <c' e' g'>
1441 When a tie is applied to a chord, all note heads whose pitches match
1442 are connected. When no note heads match, no ties will be created.
1444 A tie is just a way of extending a note duration, similar to the
1445 augmentation dot. The following example shows two ways of notating
1446 exactly the same concept
1448 @lilypond[quote,fragment,raggedright]
1449 \time 3/4 c'2. c'2 ~ c'4
1453 Ties are used either when the note crosses a bar line, or when dots
1454 cannot be used to denote the rhythm. When using ties, larger note
1455 values should be aligned to subdivisions of the measure, eg.
1457 @lilypond[fragment,quote,raggedright]
1459 r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
1463 If you need to tie a lot of notes over bars, it may be easier to use
1464 automatic note splitting (see @ref{Automatic note splitting}). This
1465 mechanism automatically splits long notes, and ties them across bar
1471 Ties are sometimes used to write out arpeggios. In this case, two tied
1472 notes need not be consecutive. This can be achieved by setting the
1473 @code{tieWaitForNote} property to true. The same feature is also useful,
1474 for example, to tie a tremolo to a chord. For example,
1476 @lilypond[fragment,verbatim,relative=1,raggedright]
1477 \set tieWaitForNote = ##t
1478 \grace { c16[~ e~ g]~ } <c, e g>2
1479 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
1486 @cindex @code{\tieUp}
1488 @cindex @code{\tieDown}
1490 @cindex @code{\tieNeutral}
1492 @cindex @code{\tieDotted}
1494 @cindex @code{\tieDashed}
1496 @cindex @code{\tieSolid}
1502 In this manual: @ref{Automatic note splitting}.
1504 Program reference: @internalsref{Tie}.
1509 Switching staves when a tie is active will not produce a slanted tie.
1511 Formatting of ties is a difficult subject. The results are often not
1520 A slur indicates that notes are to be played bound or
1521 @emph{legato}. They are entered using parentheses
1523 @lilypond[quote,raggedright,relative=2,fragment,verbatim]
1524 f( g a) a8 b( a4 g2 f4)
1528 The direction of a slur can be specified with
1529 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is
1530 either @code{Up}, @code{Down}, or @code{Neutral} (automatically
1533 However, there is a convenient shorthand for forcing slur
1534 directions. By adding @code{_} or @code{^} before the opening
1535 parentheses, the direction is also set. For example,
1537 @lilypond[relative=2,raggedright,quote,verbatim,fragment]
1541 Only one slur can be printed at once. If you need to print a long
1542 slur over a few small slurs, please see @ref{Phrasing slurs}.
1547 Some composers write two slurs when they want legato chords. This can
1548 be achieved in LilyPond by setting @code{doubleSlurs},
1550 @lilypond[verbatim,raggedright,relative,fragment,quote]
1551 \set doubleSlurs = ##t
1552 <c e>4 ( <d f> <c e> <d f> )
1558 @cindex @code{\slurUp}
1560 @cindex @code{\slurDown}
1562 @cindex @code{\slurNeutral}
1563 @code{\slurNeutral},
1564 @cindex @code{\slurDashed}
1566 @cindex @code{\slurDotted}
1568 @cindex @code{\slurSolid}
1573 Program reference: @seeinternals{Slur}.
1576 @node Phrasing slurs
1577 @subsection Phrasing slurs
1579 @cindex phrasing slurs
1580 @cindex phrasing marks
1582 A phrasing slur (or phrasing mark) connects notes and is used to
1583 indicate a musical sentence. It is written using @code{\(} and @code{\)}
1586 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
1587 \time 6/4 c'\( d( e) f( e) d\)
1590 Typographically, the phrasing slur behaves almost exactly like a
1591 normal slur. However, they are treated as different objects. A
1592 @code{\slurUp} will have no effect on a phrasing slur; instead, use
1593 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1594 @code{\phrasingSlurNeutral}.
1596 You cannot have simultaneous phrasing slurs.
1601 @cindex @code{\phrasingSlurUp}
1602 @code{\phrasingSlurUp},
1603 @cindex @code{\phrasingSlurDown}
1604 @code{\phrasingSlurDown},
1605 @cindex @code{\phrasingSlurNeutral}
1606 @code{\phrasingSlurNeutral}.
1611 Program reference: @internalsref{PhrasingSlur}.
1614 @node Automatic beams
1615 @subsection Automatic beams
1617 LilyPond inserts beams automatically
1619 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1620 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
1623 When these automatic decisions are not good enough, beaming can be
1624 entered explicitly. It is also possible to define beaming patterns
1625 that differ from the defaults. See @ref{Setting automatic beam behavior}
1628 Individual notes may be marked with @code{\noBeam} to prevent them
1631 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1632 \time 2/4 c8 c\noBeam c c
1638 Program reference: @internalsref{Beam}.
1642 @subsection Manual beams
1644 @cindex beams, manual
1648 In some cases it may be necessary to override the automatic beaming
1649 algorithm. For example, the autobeamer will not put beams over rests
1650 or bar lines. Such beams are specified manually by marking the begin
1651 and end point with @code{[} and @code{]}
1653 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
1655 r4 r8[ g' a r8] r8 g[ | a] r8
1662 @cindex @code{stemLeftBeamCount}
1663 @cindex @code{stemRightBeamCount}
1665 Normally, beaming patterns within a beam are determined automatically.
1666 If necessary, the properties @code{stemLeftBeamCount} and
1667 @code{stemRightBeamCount} can be used to override the defaults. If
1668 either property is set, its value will be used only once, and then it
1671 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
1676 \set stemLeftBeamCount = #1
1681 The property @code{subdivideBeams} can be set in order to subdivide
1682 all 16th or shorter beams at beat positions, as defined by the
1683 @code{beatLength} property.
1685 @lilypond[fragment,quote,relative=2,verbatim]
1687 \set subdivideBeams = ##t
1689 \set Score.beatLength = #(ly:make-moment 1 8)
1692 @cindex @code{subdivideBeams}
1694 Line breaks are normally forbidden when beams cross bar lines. This
1695 behavior can be changed by setting @code{allowBeamBreak}.
1697 @cindex @code{allowBeamBreak}
1698 @cindex beams and line breaks
1699 @cindex beams, kneed
1701 @cindex auto-knee-gap
1706 Kneed beams are inserted automatically when a large gap is detected
1707 between the note heads. This behavior can be tuned through the object.
1709 Automatically kneed cross-staff beams cannot be used together with
1710 hidden staves. See @ref{Hiding staves}.
1712 Beams do not avoid collisions with symbols around the notes, such as
1713 texts and accidentals.
1717 @subsection Grace notes
1719 @cindex @code{\grace}
1722 @cindex appoggiatura
1723 @cindex acciaccatura
1725 Grace notes are ornaments that are written out. The most common ones
1726 are acciaccatura, which should be played as very short. It is denoted
1727 by a slurred small note with a slashed stem. The appoggiatura is a
1728 grace note that takes a fixed fraction of the main note, and is
1729 denoted as a slurred note in small print without a slash. They
1730 are entered with the commands @code{\acciaccatura} and
1731 @code{\appoggiatura}, as demonstrated in the following example
1733 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1734 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
1735 \acciaccatura { g16[ f] } e4
1738 Both are special forms of the @code{\grace} command. By prefixing this
1739 keyword to a music expression, a new one is formed, which will be
1740 printed in a smaller font and takes up no logical time in a measure.
1742 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1744 \grace { c16[ d16] } c2 c4
1748 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
1749 @code{\grace} command does not start a slur.
1751 Internally, timing for grace notes is done using a second, `grace'
1752 timing. Every point in time consists of two rational numbers: one
1753 denotes the logical time, one denotes the grace timing. The above
1754 example is shown here with timing tuples
1756 @lilypond[quote,raggedright]
1759 c4 \grace c16 c4 \grace {
1762 \new Lyrics \lyricmode {
1763 \override LyricText #'font-family = #'typewriter
1767 ( \fraction 1 4 , \fraction -1 16 ) } 16 }
1768 \markup { (\fraction 1 4 , 0 ) } 4
1770 \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
1771 \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
1773 \markup { ( \fraction 2 4 , 0 ) }
1778 The placement of grace notes is synchronized between different staves.
1779 In the following example, there are two sixteenth grace notes for
1780 every eighth grace note
1782 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1783 << \new Staff { e4 \grace { c16[ d e f] } e4 }
1784 \new Staff { c4 \grace { g8[ b] } c4 } >>
1787 If you want to end a note with a grace, use the @code{\afterGrace}
1788 command. It takes two arguments: the main note, and the grace notes
1789 following the main note.
1791 @lilypond[raggedright, verbatim,relative=2,fragment]
1792 c1 \afterGrace d1 { c16[ d] } c4
1795 This will put the grace notes after a ``space'' lasting 3/4 of the
1796 length of the main note. The fraction 3/4 can be changed by setting
1797 @code{afterGraceFraction}, ie.
1800 afterGraceFraction = #(cons 7 8)
1804 will put the grace note at 7/8 of the main note.
1806 The same effect can be achieved manually by doing
1808 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1811 { s2 \grace { c16[ d] } } >>
1817 By adjusting the duration of the skip note (here it is a half-note),
1818 the space between the main-note and the grace is adjusted.
1820 A @code{\grace} section will introduce special typesetting settings,
1821 for example, to produce smaller type, and set directions. Hence, when
1822 introducing layout tweaks, they should be inside the grace section,
1824 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1836 The overrides should also be reverted inside the grace section.
1838 The layout of grace sections can be changed throughout the music using
1839 the function @code{add-grace-property}. The following example
1840 undefines the Stem direction for this grace, so stems do not always
1845 #(add-grace-property 'Voice 'Stem 'direction '())
1851 Another option is to change the variables @code{startGraceMusic},
1852 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
1853 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
1854 @code{stopAppoggiaturaMusic}. More information is in the file
1855 @file{ly/@/grace@/-init@/.ly}.
1860 Program reference: @internalsref{GraceMusic}.
1865 A score that starts with a @code{\grace} section needs an explicit
1866 @code{\context Voice} declaration, otherwise the main note and the grace
1867 note end up on different staves.
1869 Grace note synchronization can also lead to surprises. Staff notation,
1870 such as key signatures, bar lines, etc., are also synchronized. Take
1871 care when you mix staves with grace notes and staves without, for example,
1873 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1874 << \new Staff { e4 \bar "|:" \grace c16 d4 }
1875 \new Staff { c4 \bar "|:" d4 } >>
1879 This can be remedied by inserting grace skips, for the above example
1882 \new Staff @{ c4 \bar "|:" \grace s16 d4 @}
1885 Grace sections should only be used within sequential music
1886 expressions. Nesting or juxtaposing grace sections is not supported,
1887 and might produce crashes or other errors.
1891 @node Expressive marks
1892 @section Expressive marks
1894 Expressive marks help musicians to bring more to the music than simple
1899 * Fingering instructions::
1909 @subsection Articulations
1911 @cindex Articulations
1915 A variety of symbols can appear above and below notes to indicate
1916 different characteristics of the performance. They are added to a note
1917 by adding a dash and the character signifying the
1918 articulation. They are demonstrated here
1920 @lilypondfile[quote,raggedright]{script-abbreviations.ly}
1922 The meanings of these shorthands can be changed. See
1923 @file{ly/@/script@/-init@/.ly} for examples.
1925 The script is automatically placed, but the direction can be forced as
1926 well. Like other pieces of LilyPond code, @code{_} will place them
1927 below the staff, and @code{^} will place them above.
1929 @lilypond[quote,raggedright,fragment,verbatim]
1933 Other symbols can be added using the syntax
1934 @var{note}@code{\}@var{name}. Again, they
1935 can be forced up or down using @code{^} and @code{_},
1938 @lilypond[quote,raggedright,verbatim,fragment,relative=2]
1939 c\fermata c^\fermata c_\fermata
1944 @cindex staccatissimo
1954 @cindex organ pedal marks
1963 @cindex prallmordent
1967 @cindex thumb marking
1972 Here is a chart showing all scripts available,
1974 @lilypondfile[raggedright,quote]{script-chart.ly}
1979 The vertical ordering of scripts is controlled with the
1980 @code{script-priority} property. The lower this number, the closer it
1981 will be put to the note. In this example, the
1982 @internalsref{TextScript} (the sharp symbol) first has the lowest
1983 priority, so it is put lowest in the first example. In the second, the
1984 prall trill (the @internalsref{Script}) has the lowest, so it is on the
1985 inside. When two objects have the same priority, the order in which
1986 they are entered decides which one comes first.
1988 @lilypond[verbatim,relative=3,raggedright,fragment,quote]
1989 \once \override TextScript #'script-priority = #-100
1990 a4^\prall^\markup { \sharp }
1992 \once \override Script #'script-priority = #-100
1993 a4^\prall^\markup { \sharp }
1999 Program reference: @internalsref{Script}.
2004 These signs appear in the printed output but have no effect on the
2005 MIDI rendering of the music.
2008 @node Fingering instructions
2009 @subsection Fingering instructions
2012 @cindex finger change
2014 Fingering instructions can be entered using
2016 @var{note}-@var{digit}
2018 For finger changes, use markup texts
2020 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2022 c^\markup { \finger "2 - 3" }
2025 You can use the thumb-script to indicate that a note should be
2026 played with the thumb (e.g., in cello music)
2027 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2028 <a_\thumb a'-3>8 <b_\thumb b'-3>
2031 Fingerings for chords can also be added to individual notes
2032 of the chord by adding them after the pitches
2033 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2034 < c-1 e-2 g-3 b-5 >4
2040 You may exercise greater control over fingering chords by
2041 setting @code{fingeringOrientations}
2043 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2044 \set fingeringOrientations = #'(left down)
2045 <c-1 es-2 g-4 bes-5 > 4
2046 \set fingeringOrientations = #'(up right down)
2047 <c-1 es-2 g-4 bes-5 > 4
2050 Using this feature, it is also possible to put fingering instructions
2051 very close to note heads in monophonic music,
2053 @lilypond[verbatim,raggedright,quote,fragment]
2054 \set fingeringOrientations = #'(right)
2061 Program reference: @internalsref{Fingering}.
2063 Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
2067 @subsection Dynamics
2078 @cindex @code{\ffff}
2087 Absolute dynamic marks are specified using a command after a note
2088 @code{c4\ff}. The available dynamic marks are @code{\ppp},
2089 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2090 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
2091 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
2093 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2094 c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2095 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
2102 A crescendo mark is started with @code{\<} and terminated with
2103 @code{\!} or an absolute dynamic. A decrescendo is started with
2104 @code{\>} and is also terminated with @code{\!} or an absolute
2105 dynamic. Because these marks are bound to notes, you must
2106 use spacer notes if multiple marks are needed during one note
2108 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2110 << f1 { s4 s4\< s4\! \> s4\! } >>
2112 This may give rise to very short hairpins. Use @code{minimum-length}
2113 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2117 \override Staff.Hairpin #'minimum-length = #5
2124 You can also use a text saying @emph{cresc.} instead of hairpins
2126 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2137 You can also supply your own texts
2138 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2139 \set crescendoText = \markup { \italic "cresc. poco" }
2140 \set crescendoSpanner = #'dashed-line
2144 To create new dynamic marks or text that should be aligned
2145 with dynamics, see @ref{New dynamic marks}.
2150 @cindex @code{\dynamicUp}
2152 @cindex @code{\dynamicDown}
2153 @code{\dynamicDown},
2154 @cindex @code{\dynamicNeutral}
2155 @code{\dynamicNeutral}.
2160 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
2161 Vertical positioning of these symbols is handled by
2162 @internalsref{DynamicLineSpanner}.
2166 @subsection Breath marks
2168 Breath marks are entered using @code{\breathe}
2170 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2177 The glyph of the breath mark can be tuned by overriding the
2178 @code{text} property of the @code{BreathingSign} layout object with
2179 any markup text. For example,
2180 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
2182 \override BreathingSign #'text
2183 = #(make-musicglyph-markup "scripts.rvarcomma")
2190 Program reference: @internalsref{BreathingSign}.
2192 Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
2195 @node Running trills
2196 @subsection Running trills
2198 Long running trills are made with @code{\startTrillSpan} and
2199 @code{\stopTrillSpan},
2201 @lilypond[verbatim,raggedright,relative=2,quote,fragment]
2203 << { c1 \startTrillSpan }
2204 { s2. \grace { d16[\stopTrillSpan e] } } >>
2211 @code{\startTrillSpan},
2212 @cindex @code{\startTrillSpan}
2213 @code{\stopTrillSpan}.
2214 @cindex @code{\stopTrillSpan}
2219 This manual: @ref{Pitched trills}.
2221 Program reference: @internalsref{TrillSpanner}.
2225 @subsection Glissando
2228 @cindex @code{\glissando}
2230 A glissando is a smooth change in pitch. It is denoted by a line or a
2231 wavy line between two notes. It is requested by attaching
2232 @code{\glissando} to a note
2234 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2236 \override Glissando #'style = #'zigzag
2243 Program reference: @internalsref{Glissando}.
2245 Example files: @file{input/@/regression/@/glissando@/.ly}.
2250 Printing text over the line (such as @emph{gliss.}) is not supported.
2254 @subsection Arpeggio
2257 @cindex broken chord
2258 @cindex @code{\arpeggio}
2260 You can specify an arpeggio sign (also known as broken chord) on a
2261 chord by attaching an @code{\arpeggio} to a chord
2263 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2267 A square bracket on the left indicates that the player should not
2268 arpeggiate the chord
2270 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2275 The direction of the arpeggio is sometimes denoted by adding an
2276 arrowhead to the wiggly line
2278 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2290 When an arpeggio crosses staves, you may attach an arpeggio to the chords
2291 in both staves and set
2292 @internalsref{PianoStaff}.@code{connectArpeggios}
2294 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2295 \context PianoStaff <<
2296 \set PianoStaff.connectArpeggios = ##t
2297 \new Staff { <c' e g c>\arpeggio }
2298 \new Staff { \clef bass <c,, e g>\arpeggio }
2306 @cindex @code{\arpeggioUp}
2308 @cindex @code{\arpeggioDown}
2309 @code{\arpeggioDown},
2310 @cindex @code{\arpeggioNeutral}
2311 @code{\arpeggioNeutral},
2312 @cindex @code{\arpeggioBracket}
2313 @code{\arpeggioBracket}.
2318 Notation manual: @ref{Ties}, for writing out arpeggios.
2320 Program reference: @internalsref{Arpeggio}.
2325 It is not possible to mix connected arpeggios and unconnected
2326 arpeggios in one @internalsref{PianoStaff} at the same point in time.
2333 Polyphony in music refers to having more than one voice occuring in
2334 a piece of music. Polyphony in LilyPond refers to having more than
2335 one voice on the same staff.
2339 * Explicitly instantiating voices::
2340 * Collision Resolution::
2344 @node Basic polyphony
2345 @subsection Basic polyphony
2349 The easiest way to enter fragments with more than one voice on a staff
2350 is to enter each voice as a sequence (with @code{@{...@}}), and combine
2351 them simultaneously, separating the voices with @code{\\}
2355 @lilypond[quote,verbatim,fragment]
2356 \new Staff \relative c' {
2359 { g4 f e | d2 e2 } \\
2360 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
2366 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
2367 voices are sometimes called ``layers'' in other notation packages}
2369 to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
2370 each of these contexts, vertical direction of slurs, stems, etc., is set
2373 These voices are all seperate from the voice that contains the notes just
2374 outside the @code{<< \\ >>} construct. This should be noted when making
2375 changes at the voice level. This also means that slurs and ties cannot go
2376 into or out of a @code{<< \\ >>} construct. Conversely, parallel voices
2377 from separate @code{<< \\ >>} constructs on the same staff are the the
2378 same voice. Here is the same example, with different noteheads for each
2379 voice. Note that the change to the note-head style in the main voice does not affect
2380 the inside of the @code{<< \\ >>} constructs. Also, the change to the second
2381 voice in the first @code{<< \\ >>} construct is effective in the second
2382 @code{<< \\ >>}, and the voice is tied accross the two constructs.
2384 @lilypond[quote,verbatim,fragment]
2385 \new Staff \relative c' {
2386 \override NoteHead #'style = #'cross
2390 { \override NoteHead #'style = #'triangle
2395 { c8 b16 a b8 g ~ g2 } \\
2396 { \override NoteHead #'style = #'slash s4 b4 c2 }
2401 Polyphony does not change the relationship of notes within a
2402 @code{\relative @{ @}} block. Each note is calculated relative
2403 to the note immediately preceding it.
2406 \relative @{ noteA << noteB \\ noteC >> noteD @}
2409 @code{noteC} is relative to @code{noteB}, not @code{noteA};
2410 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
2413 @node Explicitly instantiating voices
2414 @subsection Explicitly instantiating voices
2416 @internalsref{Voice} contexts can also also be instantiated manually
2417 inside a @code{<< >>} block to create polyphonic music, using
2418 @code{\voiceOne}, up to @code{\voiceFour} to assign stem directions
2419 and a horizontal shift for each part.
2423 << \upper \\ \lower >>
2431 \context Voice = "1" @{ \voiceOne \upper @}
2432 \context Voice = "2" @{ \voiceTwo \lower @}
2436 The @code{\voiceXXX} commands set the direction of stems, slurs, ties,
2437 articulations, text annotations, augmentation dots of dotted
2438 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make
2439 these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour}
2440 make them point downwards.
2441 The command @code{\oneVoice} will revert back to the normal setting.
2443 An expression that appears directly inside a @code{<< >>} belongs to
2444 the main voice. This is useful when extra voices appear while the main
2445 voice is playing. Here is a more correct rendition of the example from
2446 the previous section. The crossed noteheads demonstrate that the main
2447 melody is now in a single voice context.
2449 @lilypond[quote,raggedright,verbatim]
2450 \new Staff \relative c' {
2451 \override NoteHead #'style = #'cross
2456 \context Voice="1" { \voiceTwo
2457 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
2460 \new Voice { \voiceThree
2469 The correct definition of the voices allows the melody to be slurred.
2470 @lilypond[quote,raggedright,verbatim]
2471 \new Staff \relative c' {
2476 \context Voice="1" { \voiceTwo
2477 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
2480 \new Voice { \voiceThree
2489 Avoiding the @code{\\} seperator also allows nesting polyphony
2490 constructs, which in some case might be a more natural way to typeset
2493 @lilypond[quote,raggedright,verbatim]
2494 \new Staff \relative c' {
2499 \context Voice="1" { \voiceTwo
2502 {c8 b16 a b8 g ~ g2}
2503 \new Voice { \voiceThree
2516 @node Collision Resolution
2517 @subsection Collision Resolution
2519 Normally, note heads with a different number of dots are not merged, but
2520 when the object property @code{merge-differently-dotted} is set in
2521 the @internalsref{NoteCollision} object, they are merged
2522 @lilypond[quote,verbatim,fragment,raggedright,relative=2]
2525 \override Staff.NoteCollision
2526 #'merge-differently-dotted = ##t
2528 } \\ { g8.[ f16] g8.[ f16] } >>
2531 Similarly, you can merge half note heads with eighth notes, by setting
2532 @code{merge-differently-headed}
2533 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2536 \override Staff.NoteCollision
2537 #'merge-differently-headed = ##t
2538 c8 c4. } \\ { c2 c2 } >>
2541 LilyPond also vertically shifts rests that are opposite of a stem,
2544 @lilypond[quote,raggedright,fragment,verbatim]
2545 \context Voice << c''4 \\ r4 >>
2551 @cindex @code{\oneVoice}
2553 @cindex @code{\voiceOne}
2555 @cindex @code{\voiceTwo}
2557 @cindex @code{\voiceThree}
2559 @cindex @code{\voiceFour}
2562 @cindex @code{\shiftOn}
2564 @cindex @code{\shiftOnn}
2566 @cindex @code{\shiftOnnn}
2568 @cindex @code{\shiftOff}
2569 @code{\shiftOff}: these commands specify in what chords of the current
2570 voice should be shifted. The outer voices (normally: voice one and
2571 two) have @code{\shiftOff}, while the inner voices (three and four)
2572 have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define
2573 further shift levels.
2575 When LilyPond cannot cope, the @code{force-hshift}
2576 property of the @internalsref{NoteColumn} object and pitched rests can
2577 be used to override typesetting decisions.
2579 @lilypond[quote,verbatim,raggedright]
2586 \once \override NoteColumn #'force-hshift = #1.7
2594 Program reference: the objects responsible for resolving collisions are
2595 @internalsref{NoteCollision} and @internalsref{RestCollision}.
2598 @inputfileref{input/@/regression,collision@/-dots@/.ly},
2599 @inputfileref{input/@/regression,collision@/-head-chords@/.ly},
2600 @inputfileref{input/@/regression,collision@/-heads@/.ly},
2601 @inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
2602 @inputfileref{input/@/regression,collisions@/.ly}.
2607 When using @code{merge-differently-headed} with an upstem eighth or a
2608 shorter note, and a downstem half note, the eighth note gets the wrong
2611 There is no support for clusters where the same note occurs with
2612 different accidentals in the same chord. In this case, it is
2613 recommended to use enharmonic transcription, or to use special cluster
2614 notation (see @ref{Clusters}).
2621 Repetition is a central concept in music, and multiple notations exist
2627 * Repeats and MIDI::
2628 * Manual repeat commands::
2630 * Tremolo subdivisions::
2636 @subsection Repeat types
2639 @cindex @code{\repeat}
2641 The following types of repetition are supported
2645 Repeated music is fully written (played) out. This is useful when
2646 entering repetitious music. This is the only kind of repeat that
2647 is included in MIDI output.
2650 Repeats are not written out, but alternative endings (volte) are
2651 printed, left to right with brackets. This is the standard notation
2652 for repeats with alternatives. These are not played in MIDI output by default.
2656 Alternative endings are written stacked. This has limited use but may be
2657 used to typeset two lines of lyrics in songs with repeats, see
2658 @inputfileref{input,star-spangled-banner@/.ly}.
2662 Make tremolo beams. These are not played in MIDI output by default.
2665 Make beat or measure repeats. These look like percent signs. These
2666 are not played in MIDI output by default. Percent repeats must be
2667 declared within a Voice context.
2673 @subsection Repeat syntax
2675 LilyPond has one syntactic construct for specifying different types of
2676 repeats. The syntax is
2679 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2682 If you have alternative endings, you may add
2683 @cindex @code{\alternative}
2694 where each @var{alternative} is a music expression. If you do not
2695 give enough alternatives for all of the repeats, the first alternative
2696 is assumed to be played more than once.
2698 Standard repeats are used like this
2699 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2701 \repeat volta 2 { c4 d e f }
2702 \repeat volta 2 { f e d c }
2705 With alternative endings
2706 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2708 \repeat volta 2 {c4 d e f}
2709 \alternative { {d2 d} {f f,} }
2712 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2715 \repeat volta 4 { e | c2 d2 | e2 f2 | }
2716 \alternative { { g4 g g } { a | a a a a | b2. } }
2720 It is possible to shorten volta brackets
2721 by setting @code{voltaSpannerDuration}. In the next example, the
2722 bracket only lasts one measure, which is a duration of 3/4.
2724 @lilypond[verbatim,raggedright,quote]
2728 \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2729 \repeat "volta" 5 { d d d }
2730 \alternative { { e e e f f f }
2740 Brackets for the repeat are normally only printed over the topmost
2741 staff. This can be adjusted by setting the @code{voltaOnThisStaff}
2742 property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
2747 @cindex repeat, ambiguous
2749 A nested repeat like
2758 is ambiguous, since it is is not clear to which @code{\repeat} the
2759 @code{\alternative} belongs. This ambiguity is resolved by always
2760 having the @code{\alternative} belong to the inner @code{\repeat}.
2761 For clarity, it is advisable to use braces in such situations.
2763 Timing information is not remembered at the start of an alternative,
2764 so after a repeat timing information must be reset by hand, for
2765 example by setting @code{Score.measurePosition} or entering
2766 @code{\partial}. Similarly, slurs or ties are also not repeated.
2769 @node Repeats and MIDI
2770 @subsection Repeats and MIDI
2772 @cindex expanding repeats
2773 @cindex @code{\unfoldRepeats}
2775 With a little bit of tweaking, all types of repeats can be present
2776 in the MIDI output. This is achieved by applying the
2777 @code{\unfoldRepeats} music function. This functions changes all
2778 repeats to unfold repeats.
2780 @lilypond[quote,verbatim,fragment,linewidth=8.0\cm]
2782 \repeat tremolo 8 {c'32 e' }
2783 \repeat percent 2 { c''8 d'' }
2784 \repeat volta 2 {c'4 d' e' f'}
2793 When creating a score file using @code{\unfoldRepeats} for midi, then
2794 it is necessary to make two @code{\score} blocks. One for MIDI (with
2795 unfolded repeats) and one for notation (with volta, tremolo, and
2796 percent repeats). For example,
2804 \unfoldRepeats @var{..music..}
2810 @node Manual repeat commands
2811 @subsection Manual repeat commands
2813 @cindex @code{repeatCommands}
2815 The property @code{repeatCommands} can be used to control the layout of
2816 repeats. Its value is a Scheme list of repeat commands.
2819 @item @code{start-repeat}
2820 Print a @code{|:} bar line.
2822 @item @code{end-repeat}
2823 Print a @code{:|} bar line.
2825 @item @code{(volta @var{text})}
2826 Print a volta bracket saying @var{text}: The text can be specified as
2827 a text string or as a markup text, see @ref{Text markup}. Do not
2828 forget to change the font, as the default number font does not contain
2829 alphabetic characters;
2831 @item @code{(volta #f)}
2832 Stop a running volta bracket.
2835 @lilypond[quote,raggedright,verbatim,fragment,relative=2]
2837 \set Score.repeatCommands = #'((volta "93") end-repeat)
2839 \set Score.repeatCommands = #'((volta #f))
2846 Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
2847 @internalsref{VoltaRepeatedMusic},
2848 @internalsref{UnfoldedRepeatedMusic}, and
2849 @internalsref{FoldedRepeatedMusic}.
2852 @node Tremolo repeats
2853 @subsection Tremolo repeats
2855 @cindex tremolo beams
2857 To place tremolo marks between notes, use @code{\repeat} with tremolo
2859 @lilypond[quote,verbatim,raggedright]
2860 \new Voice \relative c' {
2861 \repeat "tremolo" 8 { c16 d16 }
2862 \repeat "tremolo" 4 { c16 d16 }
2863 \repeat "tremolo" 2 { c16 d16 }
2867 Tremolo marks can also be put on a single note. In this case, the
2868 note should not be surrounded by braces.
2869 @lilypond[quote,verbatim,raggedright]
2870 \repeat "tremolo" 4 c'16
2873 Similar output is obtained using the tremolo subdivision, described in
2874 @ref{Tremolo subdivisions}.
2879 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
2881 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
2883 Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
2884 @inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
2887 @node Tremolo subdivisions
2888 @subsection Tremolo subdivisions
2890 @cindex tremolo marks
2891 @cindex @code{tremoloFlags}
2893 Tremolo marks can be printed on a single note by adding
2894 `@code{:}[@var{number}]' after the note. The number indicates the
2895 duration of the subdivision, and it must be at least 8. A
2896 @var{length} value of 8 gives one line across the note stem. If the
2897 length is omitted, the last value (stored in @code{tremoloFlags}) is
2900 @lilypond[quote,raggedright,verbatim,fragment]
2901 c'2:8 c':32 | c': c': |
2907 Tremolos entered in this way do not carry over into the MIDI output.
2912 In this manual: @ref{Tremolo repeats}.
2914 Elsewhere: @internalsref{StemTremolo}.
2917 @node Measure repeats
2918 @subsection Measure repeats
2920 @cindex percent repeats
2921 @cindex measure repeats
2923 In the @code{percent} style, a note pattern can be repeated. It is
2924 printed once, and then the pattern is replaced with a special sign.
2925 Patterns of one and two measures are replaced by percent-like signs,
2926 patterns that divide the measure length are replaced by slashes.
2927 Percent repeats must be declared within a @code{Voice} context.
2929 @lilypond[quote,verbatim,raggedright]
2930 \new Voice \relative c' {
2931 \repeat "percent" 4 { c4 }
2932 \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
2939 Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat},
2940 @internalsref{PercentRepeatedMusic}, and
2941 @internalsref{DoublePercentRepeat}.