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 are discussed in
235 @ref{Multi measure rests}.
238 A rest's vertical position may be explicitly specified by entering a
239 note with the @code{\rest} keyword appended, the rest will be placed at
240 the note's place. This makes manual formatting in polyphonic music
241 easier. Automatic rest collision formatting will leave these rests
244 @lilypond[fragment,quote,raggedright,verbatim]
250 Program reference: @internalsref{Rest}.
257 @cindex Invisible rest
262 An invisible rest (also called a `skip') can be entered like a note
263 with note name `@code{s}' or with @code{\skip @var{duration}}
265 @lilypond[fragment,quote,raggedright,verbatim,relative=2]
266 a4 a4 s4 a4 \skip 1 a4
269 The @code{s} syntax is only available in note mode and chord mode. In
270 other situations, for example, when entering lyrics, you should use
271 the @code{\skip} command
273 @lilypond[quote,raggedright,verbatim]
276 \new Lyrics \lyricmode { \skip 2 bla2 }
280 The skip command is merely an empty musical placeholder. It does not
281 produce any output, not even transparent output.
283 The @code{s} skip command does create @internalsref{Staff} and
284 @internalsref{Voice} when necessary, similar to note and rest
285 commands. For example, the following results in an empty staff.
287 @lilypond[quote,raggedright,verbatim]
291 The fragment @code{@{ \skip 4 @} } would produce an empty page.
295 Program reference: @internalsref{SkipMusic}.
299 @subsection Durations
302 @cindex @code{\longa}
303 @cindex @code{\breve}
304 @cindex @code{\maxima}
306 In Note, Chord, and Lyrics mode, durations are designated by numbers and
307 dots: durations are entered as their reciprocal values. For example, a
308 quarter note is entered using a @code{4} (since it is a 1/4 note), while
309 a half note is entered using a @code{2} (since it is a 1/2 note). For
310 notes longer than a whole you must use the variables @code{\longa} and
315 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
317 r1 r2 r4 r8 r16 r32 r64 r64
323 a\breve*1/2 \autoBeamOff
324 a1 a2 a4 a8 a16 a32 a64 a64
327 r\longa*1/4 r\breve *1/2
328 r1 r2 r4 r8 r16 r32 r64 r64
334 \remove "Clef_engraver"
335 \override StaffSymbol #'transparent = ##t
336 \override TimeSignature #'transparent = ##t
337 \override BarLine #'transparent = ##t
338 \consists "Pitch_squash_engraver"
344 If the duration is omitted then it is set to the previously entered
345 duration. The default for the first note is a quarter note.
347 @lilypond[quote,raggedright,verbatim,fragment]
348 { a a a2 a a4 a a1 a }
352 @node Augmentation dots
353 @subsection Augmentation dots
357 To obtain dotted note lenghts, simply add a dot (`@code{.}') to
358 the number. Double-dotted notes are produced in a similar way.
360 @lilypond[quote,raggedright,fragment,verbatim]
361 a'4 b' c''4. b'8 a'4. b'4.. c''8.
366 Dots are normally moved up to avoid staff lines, except in polyphonic
367 situations. The following commands may be used to force a particular
370 @cindex @code{\dotsUp}
372 @cindex @code{\dotsDown}
374 @cindex @code{\dotsNeutral}
379 Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
387 @cindex @code{\times}
389 Tuplets are made out of a music expression by multiplying all durations
393 \times @var{fraction} @var{musicexpr}
397 The duration of @var{musicexpr} will be multiplied by the fraction.
398 The fraction's denominator will be printed over the notes, optionally
399 with a bracket. The most common tuplet is the triplet in which 3
400 notes have the length of 2, so the notes are 2/3 of their written
403 @lilypond[quote,raggedright,fragment,verbatim]
404 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
407 Tuplets may be nested, for example,
409 @lilypond[fragment,raggedright,verbatim,relative=2]
410 \set tupletNumberFormatFunction = #fraction-tuplet-formatter
413 \times 3/5 { a a a a a }
419 @cindex @code{\tupletUp}
421 @cindex @code{\tupletDown}
423 @cindex @code{\tupletNeutral}
424 @code{\tupletNeutral}.
429 @cindex @code{tupletNumberFormatFunction}
430 @cindex tuplet formatting
432 The property @code{tupletSpannerDuration} specifies how long each
433 bracket should last. With this, you can make lots of tuplets while
434 typing @code{\times} only once, thus saving lots of typing. In the next
435 example, there are two triplets shown, while @code{\times} was only
438 @lilypond[quote,fragment,relative=1,raggedright,verbatim]
439 \set tupletSpannerDuration = #(ly:make-moment 1 4)
440 \times 2/3 { c'8 c c c c c }
443 The format of the number is determined by the property
444 @code{tupletNumberFormatFunction}. The default prints only the
445 denominator, but if it is set to the Scheme function
446 @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
455 Program reference: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}.
457 Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
461 @node Scaling durations
462 @subsection Scaling durations
464 You can alter the length of duration by a fraction @var{N/M}
465 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
466 will not affect the appearance of the notes or rests produced.
468 In the following example, the first three notes take up exactly two
469 beats, but no triplet bracket is printed.
470 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
472 a4*2/3 gis4*2/3 a4*2/3
480 This manual: @ref{Tuplets}
484 @node Alternate music entry
485 @section Alternate music entry
488 This section deals with tricks and features of the input language that
489 were added solely to help entering music and finding and correcting
490 mistakes. There are also external tools that make debugging easier.
491 See @ref{Point and click} for more information.
493 It is also possible to enter and edit music using other programs, such as
494 GUI interfaces or MIDI sequencers. Refer to the LilyPond
495 website for more information.
503 * Skipping corrected music::
504 * Automatic note splitting::
508 @node Relative octaves
509 @subsection Relative octaves
512 @cindex Relative octave specification
513 @cindex @code{\relative}
515 Octaves are specified by adding @code{'} and @code{,} to pitch names.
516 When you copy existing music, it is easy to accidentally put a pitch
517 in the wrong octave and hard to find such an error. The relative
518 octave mode prevents these errors by making the mistakes much
519 larger: a single error puts the rest of the piece off by one octave
522 \relative @var{startpitch} @var{musicexpr}
529 \relative @var{musicexpr}
532 The octave of notes that appear in @var{musicexpr} are calculated as
533 follows: if no octave changing marks are used, the basic interval
534 between this and the last note is always taken to be a fourth or
535 less. This distance is determined without regarding alterations; a
536 @code{fisis} following a @code{ceses} will be put above the
537 @code{ceses}. In other words, a doubly-augmented fourth is considered
538 a smaller interval than a diminshed fifth, even though the fourth is
539 seven semitones while the fifth is only six semitones.
541 The octave changing marks @code{'} and @code{,} can be added to raise
542 or lower the pitch by an extra octave. Upon entering relative mode,
543 an absolute starting pitch can be specified that will act as the
544 predecessor of the first note of @var{musicexpr}. If no starting pitch
545 is specified, then middle C is used as a start.
547 Here is the relative mode shown in action
548 @lilypond[quote,fragment,raggedright,verbatim]
554 Octave changing marks are used for intervals greater than a fourth
555 @lilypond[quote,raggedright,fragment,verbatim]
561 If the preceding item is a chord, the first note of the chord is used
562 to determine the first note of the next chord
564 @lilypond[quote,raggedright,fragment,verbatim]
572 The pitch after the @code{\relative} contains a note name.
574 The relative conversion will not affect @code{\transpose},
575 @code{\chordmode} or @code{\relative} sections in its argument. To use
576 relative within transposed music, an additional @code{\relative} must
577 be placed inside @code{\transpose}.
581 @subsection Octave check
585 Octave checks make octave errors easier to correct: a note may be
586 followed by @code{=}@var{quotes} which indicates what its absolute
587 octave should be. In the following example,
590 \relative c'' @{ c='' b=' d,='' @}
594 the @code{d} will generate a warning, because a @code{d''} is expected
595 (because @code{b'} to @code{d''} is only a third), but a @code{d'} is
596 found. In the output, the octave is corrected to be a @code{d''} and
597 the next note is calculated relative to @code{d''} instead of @code{d'}.
599 There is also a syntax that is separate from the notes. The syntax
605 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
606 quotes) in \relative mode. If not, a warning is printed, and the
609 In the example below, the first check passes without incident, since
610 the @code{e} (in relative mode) is within a fifth of @code{a'}. However,
611 the second check produces a warning, since the @code{e} is not within
612 a fifth of @code{b'}. The warning message is printed, and the octave
613 is adjusted so that the following notes are in the correct octave
625 The octave of a note following an octave check is determined with
626 respect to the note preceding it. In the next fragment, the last note
627 is an @code{a'}, above middle C. That means that the @code{\octave}
628 check passes successfully, so the check could be deleted without changing
629 the output of the piece.
631 @lilypond[quote,raggedright,verbatim,fragment]
641 @subsection Transpose
644 @cindex transposition of pitches
645 @cindex @code{\transpose}
647 A music expression can be transposed with @code{\transpose}. The
650 \transpose @var{from} @var{to} @var{musicexpr}
653 This means that @var{musicexpr} is transposed by the interval between
654 the pitches @var{from} and @var{to}: any note with pitch @code{from}
655 is changed to @code{to}.
657 For example, consider a piece written in the key of D-major. If
658 this piece is a little too low for its performer, it can be
659 transposed up to E-major with
661 \transpose d e @dots{}
664 Consider a part written for violin (a C instrument). If
665 this part is to be played on the A clarinet, the following
666 transposition will produce the appropriate part
669 \transpose a c @dots{}
672 @code{\transpose} distinguishes between enharmonic pitches: both
673 @code{\transpose c cis} or @code{\transpose c des} will transpose up
674 half a tone. The first version will print sharps and the second
675 version will print flats
677 @lilypond[quote,raggedright,verbatim]
678 mus = { \key d \major cis d fis g }
687 @code{\transpose} may also be used to input written notes for a
688 transposing instrument. Pitches are normally entered into LilyPond
689 in C (or ``concert pitch''), but they may be entered in another
690 key. For example, when entering music for a B-flat trumpet which
691 begins on concert D, one would write
694 \transpose c bes @{ e4 @dots{} @}
697 To print this music in B-flat again (ie producing a trumpet part,
698 instead of a concert pitch conductor's score) you would wrap the
699 existing music with another @code{transpose}
702 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
708 Program reference: @internalsref{TransposedMusic}.
713 If you want to use both @code{\transpose} and @code{\relative},
714 you must put @code{\transpose} outside of @code{\relative}, since
715 @code{\relative} will have no effect music that appears inside a
720 @subsection Bar check
723 @cindex @code{barCheckSynchronize}
726 Bar checks help detect errors in the durations. A bar check is
727 entered using the bar symbol, `@code{|}'. Whenever it is encountered
728 during interpretation, it should fall on a measure boundary. If it
729 does not, a warning is printed. In the next example, the second bar
730 check will signal an error
732 \time 3/4 c2 e4 | g2 |
735 Bar checks can also be used in lyrics, for example
740 Twin -- kle | Twin -- kle
744 Failed bar checks are caused by entering incorrect
745 durations. Incorrect durations often completely garble up the score,
746 especially if the score is polyphonic, so a good place to start correcting
747 input is by scanning for failed bar checks and incorrect durations.
750 @cindex @code{pipeSymbol}
752 It is also possible to redefine the meaning of @code{|}. This is done
753 by assigning a music expression to @code{pipeSymbol},
755 @lilypond[quote,raggedright,verbatim]
756 pipeSymbol = \bar "||"
762 @node Barnumber check
763 @subsection Barnumber check
765 When copying large pieces of music, it can be helpful to check that
766 the LilyPond bar number corresponds to the original that you are
767 entering from. This can be checked with @code{\barNumberCheck}, for
775 will print a warning if the @code{currentBarNumber} is not 123 when it
779 @node Skipping corrected music
780 @subsection Skipping corrected music
783 @cindex @code{skipTypesetting}
784 @cindex @code{showLastLength}
786 When entering or copying music, only the music near the end (where you
787 are adding notes) is interesting to view and correct. To speed up
788 this correction process, it is possible to skip typesetting of all but
789 the last few measures. This is achieved by putting
792 showLastLength = R1*5
797 in your source file. This will render only the last 5 measures
798 (assuming 4/4 time signature) of every @code{\score} in the input
799 file. For longer pieces, rendering only a small part is often an order
800 of magnitude quicker than rendering it completely
802 Skipping parts of a score can be controlled in a more fine-grained
803 fashing with the property @code{Score.skipTypesetting}. When it is
804 set, no typesetting is performed at all.
806 @lilypond[quote,fragment,raggedright,verbatim]
809 \set Score.skipTypesetting = ##t
811 \set Score.skipTypesetting = ##f
815 In polyphonic music, @code{Score.skipTypesetting} will affect all
816 voices and staves, saving even more time.
819 @node Automatic note splitting
820 @subsection Automatic note splitting
822 Long notes can be converted automatically to tied notes. This is done
823 by replacing the @internalsref{Note_heads_engraver} by the
824 @internalsref{Completion_heads_engraver}.
825 In the following examples, notes crossing the bar line are split and tied.
827 @lilypond[quote,fragment,verbatim,relative=1,linewidth=12\cm]
829 \remove "Note_heads_engraver"
830 \consists "Completion_heads_engraver"
832 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
836 This engraver splits all running notes at the bar line, and inserts
837 ties. One of its uses is to debug complex scores: if the measures are
838 not entirely filled, then the ties exactly show how much each measure
844 Not all durations (especially those containing tuplets) can be
845 represented exactly with normal notes and dots, but the engraver will
848 @code{Completion_heads_engraver} only affects notes; it does not split
854 Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
858 Program reference: @internalsref{Completion_heads_engraver}.
863 @section Staff notation
865 @cindex Staff notation
867 This section describes music notation that occurs on staff level,
868 such as key signatures, clefs and time signatures.
877 * System start delimiters::
887 The clef indicates which lines of the staff correspond to which
888 pitches. The clef is set with the @code{\clef} command
890 @lilypond[quote,raggedright,fragment,verbatim]
891 { c''2 \clef alto g'2 }
901 @cindex mezzosoprano clef
902 @cindex baritone clef
903 @cindex varbaritone clef
906 Supported clefs finclude
908 @item treble, violin, G, G2
917 G clef on 1st line, so-called French violin clef
934 By adding @code{_8} or @code{^8} to the clef name, the clef is
935 transposed one octave down or up, respectively, and @code{_15} and
936 @code{^15} transposes by two octaves. The argument @var{clefname}
937 must be enclosed in quotes when it contains underscores or digits. For
940 @cindex choral tenor clef
941 @lilypond[quote,raggedright,verbatim,fragment,relative=1]
948 The command @code{\clef "treble_8"} is equivalent to setting @code{clefGlyph},
949 @code{clefPosition} (which controls the Y position of the clef),
950 @code{middleCPosition} and @code{clefOctavation}. A clef is printed
951 when any of these properties are changed. The following example shows
952 possibilities when setting properties manually.
954 @lilypond[quote,raggedright,verbatim]
956 \set Staff.clefGlyph = #"clefs.F"
957 \set Staff.clefPosition = #2
959 \set Staff.clefGlyph = #"clefs.G"
961 \set Staff.clefGlyph = #"clefs.C"
963 \set Staff.clefOctavation = #7
965 \set Staff.clefOctavation = #0
966 \set Staff.clefPosition = #0
970 \set Staff.middleCPosition = #4
978 Program reference: @internalsref{Clef}.
982 @subsection Key signature
984 @cindex Key signature
987 The key signature indicates the tonality in which a piece is played. It
988 is denoted by a set of alterations (flats or sharps) at the start of the
991 Setting or changing the key signature is done with the @code{\key}
995 @code{\key} @var{pitch} @var{type}
998 @cindex @code{\minor}
999 @cindex @code{\major}
1000 @cindex @code{\minor}
1001 @cindex @code{\ionian}
1002 @cindex @code{\locrian}
1003 @cindex @code{\aeolian}
1004 @cindex @code{\mixolydian}
1005 @cindex @code{\lydian}
1006 @cindex @code{\phrygian}
1007 @cindex @code{\dorian}
1008 @cindex church modes
1010 Here, @var{type} should be @code{\major} or @code{\minor} to get
1011 @var{pitch}-major or @var{pitch}-minor, respectively. You may also
1012 use the standard mode names (also called ``church modes''): @code{\ionian},
1013 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
1014 @code{\phrygian}, and @code{\dorian}.
1016 This command sets the context property
1017 @code{Staff.keySignature}. Non-standard key signatures
1018 can be specified by setting this property directly.
1020 Accidentals and key signatures often confuse new users, because
1021 unaltered notes get natural signs depending on the key signature. For
1022 more information, see @ref{More about pitches}.
1027 A natural sign is printed to cancel any previous accidentals. This
1028 can be suppressed by setting the @code{Staff.printKeyCancellation}
1031 @lilypond[quote,fragment,raggedright,fragment,verbatim,relative=2]
1036 \set Staff.printKeyCancellation = ##f
1046 Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}.
1049 @node Time signature
1050 @subsection Time signature
1052 @cindex Time signature
1054 @cindex @code{\time}
1056 Time signature indicates the metrum of a piece: a regular pattern of
1057 strong and weak beats. It is denoted by a fraction at the start of the
1060 The time signature is set with the @code{\time} command
1062 @lilypond[quote,raggedright,fragment,verbatim]
1063 \time 2/4 c'2 \time 3/4 c'2.
1068 The symbol that is printed can be customized with the @code{style}
1069 property. Setting it to @code{#'()} uses fraction style for 4/4 and
1072 @lilypond[fragment,quote,raggedright,verbatim]
1075 \override Staff.TimeSignature #'style = #'()
1080 There are many more options for its layout. See @ref{Ancient time
1081 signatures} for more examples.
1083 @code{\time} sets the property @code{timeSignatureFraction},
1084 @code{beatLength} and @code{measureLength} in the @code{Timing}
1085 context, which is normally aliased to @internalsref{Score}. The
1086 property @code{measureLength} determines where bar lines should be
1087 inserted, and how automatic beams should be generated. Changing the
1088 value of @code{timeSignatureFraction} also causes the symbol to be
1091 More options are available through the Scheme function
1092 @code{set-time-signature}. In combination with the
1093 @internalsref{Measure_grouping_engraver}, it will create
1094 @internalsref{MeasureGrouping} signs. Such signs ease reading
1095 rhythmically complex modern music. In the following example, the 9/8
1096 measure is subdivided in 2, 2, 2 and 3. This is passed to
1097 @code{set-time-signature} as the third argument @code{(2 2 2 3)}
1099 @lilypond[quote,raggedright,verbatim]
1102 #(set-time-signature 9 8 '(2 2 2 3))
1103 g8[ g] d[ d] g[ g] a8[( bes g]) |
1104 #(set-time-signature 5 8 '(3 2))
1110 \consists "Measure_grouping_engraver"
1118 Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_translator}.
1123 Automatic beaming does not use the measure grouping specified with
1124 @code{set-time-signature}.
1127 @node Partial measures
1128 @subsection Partial measures
1132 @cindex partial measure
1133 @cindex measure, partial
1134 @cindex shorten measures
1135 @cindex @code{\partial}
1137 Partial measures, such as an anacrusis or upbeat, are entered using the
1139 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1140 \partial 16*5 c16 cis d dis e | a2. c,4 | b2
1143 The syntax for this command is
1146 \partial @var{duration}
1149 This is internally translated into
1152 \set Timing.measurePosition = -@var{length of duration}
1155 The property @code{measurePosition} contains a rational number
1156 indicating how much of the measure has passed at this point.
1161 This command does not take into account grace notes at the start of
1162 the music. When a piece starts with graces notes in the pickup, then
1163 the @code{\partial} should follow the grace notes
1165 @lilypond[verbatim,quote,raggedright,relative,fragment]
1174 @subsection Bar lines
1178 @cindex measure lines
1181 Bar lines delimit measures, but are also used to indicate
1182 repeats. Normally they are inserted automatically. Line
1183 breaks may only happen on bar lines.
1185 Special types of bar lines can be forced with the @code{\bar} command
1187 @lilypond[quote,raggedright,relative=2,fragment,verbatim]
1191 The following bar types are available
1193 @lilypondfile[raggedright,quote]{bar-lines.ly}
1195 To allow a line break where there is no visible bar line, use
1202 This will insert an invisible bar line and allow line breaks at this
1205 In scores with many staves, a @code{\bar} command in one staff is
1206 automatically applied to all staves. The resulting bar lines are
1207 connected between different staves of a StaffGroup
1209 @lilypond[quote,raggedright,fragment,verbatim]
1211 \context StaffGroup <<
1217 \new Staff { \clef bass c4 g e g }
1219 \new Staff { \clef bass c2 c2 }
1226 @cindex @code{whichBar}
1227 @cindex @code{repeatCommands}
1228 @cindex @code{defaultBarType}
1230 The command @code{\bar }@var{bartype} is a short cut for doing
1231 @code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
1232 is set to a string, a bar line of that type is created.
1234 A bar line is created whenever the @code{whichBar} property is set.
1235 At the start of a measure it is set to the contents of
1236 @code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used
1237 to override default measure bars.
1239 You are encouraged to use @code{\repeat} for repetitions. See
1245 In this manual: @ref{Repeats}, @ref{System start delimiters}.
1247 Program reference: @internalsref{BarLine} (created at
1248 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1250 Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
1253 @node Unmetered music
1254 @subsection Unmetered music
1257 @cindex @code{\cadenzaOn}
1258 @cindex @code{\cadenzaOff}
1260 Bar lines and bar numbers are calculated automatically. For unmetered
1261 music (cadenzas, for example), this is not desirable. To turn off
1262 automatic bar lines and bar numbers, use the commands @code{\cadenzaOn}
1263 and @code{\cadenzaOff}.
1265 @lilypond[verbatim,quote,raggedright,relative=2,fragment]
1277 LilyPond will only insert page breaks at a barline. Unless the unmetered
1278 music ends before the end of the staff line, you will need to insert
1286 to indicate where line breaks can occur.
1289 @node System start delimiters
1290 @subsection System start delimiters
1292 @cindex start of system
1293 @cindex Staff, multiple
1294 @cindex bracket, vertical
1295 @cindex brace, vertical
1298 @cindex staff, choir
1300 Many scores consist of more than one staff. These staves can be
1301 joined in four different ways
1304 @item The group is started with a brace at the left, and bar lines are
1305 connected. This is done with the @internalsref{GrandStaff} context.
1307 @lilypond[verbatim,raggedright,quote]
1315 @item The group is started with a bracket, and bar lines are connected.
1316 This is done with the
1317 @internalsref{StaffGroup} context
1319 @lilypond[verbatim,raggedright,quote]
1327 @item The group is started with a bracket, but bar lines are not
1328 connected. This is done with the @internalsref{ChoirStaff} context.
1330 @lilypond[verbatim,raggedright,quote]
1338 @item The group is started with a vertical line. Bar lines are not
1339 connected. This is the default for the score.
1341 @lilypond[verbatim,raggedright,quote]
1352 The bar lines at the start of each system are
1353 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
1354 @internalsref{SystemStartBracket}. Only one of these types is created
1355 in every context, and that type is determined by the property
1356 @code{systemStartDelimiter}.
1360 @subsection Staff symbol
1362 @cindex adjusting staff symbol
1364 Notes, dynamic signs, etc., are grouped
1365 with a set of horizontal lines, called a staff (plural `staves'). In
1366 LilyPond, these lines are drawn using a separate layout object called
1369 The staff symbol may be tuned in the number, thickness and distance
1370 of lines, using properties. This is demonstrated in the example files
1371 @inputfileref{input/@/test,staff@/-lines@/.ly},
1372 @inputfileref{input/@/test,staff@/-size@/.ly}.
1374 In addition, staves may be started and stopped at will. This is done
1375 with @code{\startStaff} and @code{\stopStaff}.
1377 @lilypond[verbatim,relative=2,fragment]
1379 \override Staff.StaffSymbol #'line-count = 2
1380 \stopStaff \startStaff
1382 \revert Staff.StaffSymbol #'line-count
1383 \stopStaff \startStaff
1387 In combination with Frenched staves, this may be used to typeset ossia
1388 sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
1393 @lilypondfile{ossia.ly}
1395 @cindex staff lines, setting number of
1396 @cindex staff lines, setting thickness of
1397 @cindex thickness of staff lines, setting
1398 @cindex number of staff lines, setting
1402 Program reference: @internalsref{StaffSymbol}.
1404 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
1405 @inputfileref{input/@/test@/,ossia.ly},
1406 @inputfileref{input/@/test,staff@/-size@/.ly}.
1410 @node Connecting notes
1411 @section Connecting notes
1413 This section deals with notation that affects groups of notes.
1431 A tie connects two adjacent note heads of the same pitch. The tie in
1432 effect extends the length of a note. Ties should not be confused with
1433 slurs, which indicate articulation, or phrasing slurs, which indicate
1434 musical phrasing. A tie is entered using the tilde symbol `@code{~}'
1436 @lilypond[quote,raggedright,fragment,verbatim]
1437 e' ~ e' <c' e' g'> ~ <c' e' g'>
1440 When a tie is applied to a chord, all note heads whose pitches match
1441 are connected. When no note heads match, no ties will be created.
1443 A tie is just a way of extending a note duration, similar to the
1444 augmentation dot. The following example shows two ways of notating
1445 exactly the same concept
1447 @lilypond[quote,fragment,raggedright]
1448 \time 3/4 c'2. c'2 ~ c'4
1452 Ties are used either when the note crosses a bar line, or when dots
1453 cannot be used to denote the rhythm. When using ties, larger note
1454 values should be aligned to subdivisions of the measure, eg.
1456 @lilypond[fragment,quote,raggedright]
1458 r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
1462 If you need to tie a lot of notes over bars, it may be easier to use
1463 automatic note splitting (see @ref{Automatic note splitting}). This
1464 mechanism automatically splits long notes, and ties them across bar
1470 Ties are sometimes used to write out arpeggios. In this case, two tied
1471 notes need not be consecutive. This can be achieved by setting the
1472 @code{tieWaitForNote} property to true. For example,
1474 @lilypond[fragment,verbatim,relative=1,raggedright]
1475 \set tieWaitForNote = ##t
1476 \grace { c16[~ e~ g]~ } <c, e g>4
1483 @cindex @code{\tieUp}
1485 @cindex @code{\tieDown}
1487 @cindex @code{\tieNeutral}
1489 @cindex @code{\tieDotted}
1491 @cindex @code{\tieDashed}
1493 @cindex @code{\tieSolid}
1499 In this manual: @ref{Automatic note splitting}.
1501 Program reference: @internalsref{Tie}.
1506 Switching staves when a tie is active will not produce a slanted tie.
1508 Formatting of ties is a difficult subject. The results are often not
1517 A slur indicates that notes are to be played bound or
1518 @emph{legato}. They are entered using parentheses
1520 @lilypond[quote,raggedright,relative=2,fragment,verbatim]
1521 f( g a) a8 b( a4 g2 f4)
1525 The direction of a slur can be specified with
1526 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is
1527 either @code{Up}, @code{Down}, or @code{Neutral} (automatically
1530 However, there is a convenient shorthand for forcing slur
1531 directions. By adding @code{_} or @code{^} before the opening
1532 parentheses, the direction is also set. For example,
1534 @lilypond[relative=2,raggedright,quote,verbatim,fragment]
1538 Only one slur can be printed at once. If you need to print a long
1539 slur over a few small slurs, please see @ref{Phrasing slurs}.
1544 Some composers write two slurs when they want legato chords. This can
1545 be achieved in LilyPond by setting @code{doubleSlurs},
1547 @lilypond[verbatim,raggedright,relative,fragment,quote]
1548 \set doubleSlurs = ##t
1549 <c e>4 ( <d f> <c e> <d f> )
1555 @cindex @code{\slurUp}
1557 @cindex @code{\slurDown}
1559 @cindex @code{\slurNeutral}
1560 @code{\slurNeutral},
1561 @cindex @code{\slurDashed}
1563 @cindex @code{\slurDotted}
1565 @cindex @code{\slurSolid}
1570 Program reference: @seeinternals{Slur}.
1573 @node Phrasing slurs
1574 @subsection Phrasing slurs
1576 @cindex phrasing slurs
1577 @cindex phrasing marks
1579 A phrasing slur (or phrasing mark) connects notes and is used to
1580 indicate a musical sentence. It is written using @code{\(} and @code{\)}
1583 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
1584 \time 6/4 c'\( d( e) f( e) d\)
1587 Typographically, the phrasing slur behaves almost exactly like a
1588 normal slur. However, they are treated as different objects. A
1589 @code{\slurUp} will have no effect on a phrasing slur; instead, use
1590 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1591 @code{\phrasingSlurNeutral}.
1593 You cannot have simultaneous phrasing slurs.
1598 @cindex @code{\phrasingSlurUp}
1599 @code{\phrasingSlurUp},
1600 @cindex @code{\phrasingSlurDown}
1601 @code{\phrasingSlurDown},
1602 @cindex @code{\phrasingSlurNeutral}
1603 @code{\phrasingSlurNeutral}.
1608 Program reference: @internalsref{PhrasingSlur}.
1611 @node Automatic beams
1612 @subsection Automatic beams
1614 LilyPond inserts beams automatically
1616 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1617 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
1620 When these automatic decisions are not good enough, beaming can be
1621 entered explicitly. It is also possible to define beaming patterns
1622 that differ from the defaults. See @ref{Setting automatic beam behavior}
1625 Individual notes may be marked with @code{\noBeam} to prevent them
1628 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1629 \time 2/4 c8 c\noBeam c c
1635 Program reference: @internalsref{Beam}.
1639 @subsection Manual beams
1641 @cindex beams, manual
1645 In some cases it may be necessary to override the automatic beaming
1646 algorithm. For example, the autobeamer will not put beams over rests
1647 or bar lines. Such beams are specified manually by marking the begin
1648 and end point with @code{[} and @code{]}
1650 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
1652 r4 r8[ g' a r8] r8 g[ | a] r8
1659 @cindex @code{stemLeftBeamCount}
1660 @cindex @code{stemRightBeamCount}
1662 Normally, beaming patterns within a beam are determined automatically.
1663 If necessary, the properties @code{stemLeftBeamCount} and
1664 @code{stemRightBeamCount} can be used to override the defaults. If
1665 either property is set, its value will be used only once, and then it
1668 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
1673 \set stemLeftBeamCount = #1
1678 The property @code{subdivideBeams} can be set in order to subdivide
1679 all 16th or shorter beams at beat positions, as defined by the
1680 @code{beatLength} property.
1682 @lilypond[fragment,quote,relative=2,verbatim]
1684 \set subdivideBeams = ##t
1686 \set Score.beatLength = #(ly:make-moment 1 8)
1689 @cindex @code{subdivideBeams}
1691 Line breaks are normally forbidden when beams cross bar lines. This
1692 behavior can be changed by setting @code{allowBeamBreak}.
1694 @cindex @code{allowBeamBreak}
1695 @cindex beams and line breaks
1696 @cindex beams, kneed
1698 @cindex auto-knee-gap
1703 Kneed beams are inserted automatically when a large gap is detected
1704 between the note heads. This behavior can be tuned through the object.
1706 Automatically kneed cross-staff beams cannot be used together with
1707 hidden staves. See @ref{Hiding staves}.
1709 Beams do not avoid collisions with symbols around the notes, such as
1710 texts and accidentals.
1714 @subsection Grace notes
1716 @cindex @code{\grace}
1719 @cindex appoggiatura
1720 @cindex acciaccatura
1722 Grace notes are ornaments that are written out. The most common ones
1723 are acciaccatura, which should be played as very short. It is denoted
1724 by a slurred small note with a slashed stem. The appoggiatura is a
1725 grace note that takes a fixed fraction of the main note, and is
1726 denoted as a slurred note in small print without a slash. They
1727 are entered with the commands @code{\acciaccatura} and
1728 @code{\appoggiatura}, as demonstrated in the following example
1730 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1731 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
1732 \acciaccatura { g16[ f] } e4
1735 Both are special forms of the @code{\grace} command. By prefixing this
1736 keyword to a music expression, a new one is formed, which will be
1737 printed in a smaller font and takes up no logical time in a measure.
1739 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1741 \grace { c16[ d16] } c2 c4
1745 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
1746 @code{\grace} command does not start a slur.
1748 Internally, timing for grace notes is done using a second, `grace'
1749 timing. Every point in time consists of two rational numbers: one
1750 denotes the logical time, one denotes the grace timing. The above
1751 example is shown here with timing tuples
1753 @lilypond[quote,raggedright]
1756 c4 \grace c16 c4 \grace {
1759 \new Lyrics \lyricmode {
1760 \override LyricText #'font-family = #'typewriter
1764 ( \fraction 1 4 , \fraction -1 16 ) } 16 }
1765 \markup { (\fraction 1 4 , 0 ) } 4
1767 \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
1768 \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
1770 \markup { ( \fraction 2 4 , 0 ) }
1775 The placement of grace notes is synchronized between different staves.
1776 In the following example, there are two sixteenth grace notes for
1777 every eighth grace note
1779 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1780 << \new Staff { e4 \grace { c16[ d e f] } e4 }
1781 \new Staff { c4 \grace { g8[ b] } c4 } >>
1784 If you want to end a note with a grace, use the @code{\afterGrace}
1785 command. It takes two arguments: the main note, and the grace notes
1786 following the main note.
1788 @lilypond[raggedright, verbatim,relative=2,fragment]
1789 c1 \afterGrace d1 { c16[ d] } c4
1792 This will put the grace notes after a ``space'' lasting 3/4 of the
1793 length of the main note. The fraction 3/4 can be changed by setting
1794 @code{afterGraceFraction}, ie.
1797 afterGraceFraction = #(cons 7 8)
1801 will put the grace note at 7/8 of the main note.
1803 The same effect can be achieved manually by doing
1805 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1808 { s2 \grace { c16[ d] } } >>
1814 By adjusting the duration of the skip note (here it is a half-note),
1815 the space between the main-note and the grace is adjusted.
1817 A @code{\grace} section will introduce special typesetting settings,
1818 for example, to produce smaller type, and set directions. Hence, when
1819 introducing layout tweaks, they should be inside the grace section,
1821 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
1833 The overrides should also be reverted inside the grace section.
1835 The layout of grace sections can be changed throughout the music using
1836 the function @code{add-grace-property}. The following example
1837 undefines the Stem direction for this grace, so stems do not always
1842 #(add-grace-property 'Voice 'Stem 'direction '())
1848 Another option is to change the variables @code{startGraceMusic},
1849 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
1850 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
1851 @code{stopAppoggiaturaMusic}. More information is in the file
1852 @file{ly/@/grace@/-init@/.ly}.
1857 Program reference: @internalsref{GraceMusic}.
1862 A score that starts with a @code{\grace} section needs an explicit
1863 @code{\context Voice} declaration, otherwise the main note and the grace
1864 note end up on different staves.
1866 Grace note synchronization can also lead to surprises. Staff notation,
1867 such as key signatures, bar lines, etc., are also synchronized. Take
1868 care when you mix staves with grace notes and staves without, for example,
1870 @lilypond[quote,raggedright,relative=2,verbatim,fragment]
1871 << \new Staff { e4 \bar "|:" \grace c16 d4 }
1872 \new Staff { c4 \bar "|:" d4 } >>
1876 This can be remedied by inserting grace skips, for the above example
1879 \new Staff @{ c4 \bar "|:" \grace s16 d4 @}
1882 Grace sections should only be used within sequential music
1883 expressions. Nesting or juxtaposing grace sections is not supported,
1884 and might produce crashes or other errors.
1888 @node Expressive marks
1889 @section Expressive marks
1891 Expressive marks help musicians to bring more to the music than simple
1896 * Fingering instructions::
1906 @subsection Articulations
1908 @cindex Articulations
1912 A variety of symbols can appear above and below notes to indicate
1913 different characteristics of the performance. They are added to a note
1914 by adding a dash and the character signifying the
1915 articulation. They are demonstrated here
1917 @lilypondfile[quote,raggedright]{script-abbreviations.ly}
1919 The meanings of these shorthands can be changed. See
1920 @file{ly/@/script@/-init@/.ly} for examples.
1922 The script is automatically placed, but the direction can be forced as
1923 well. Like other pieces of LilyPond code, @code{_} will place them
1924 below the staff, and @code{^} will place them above.
1926 @lilypond[quote,raggedright,fragment,verbatim]
1930 Other symbols can be added using the syntax
1931 @var{note}@code{\}@var{name}. Again, they
1932 can be forced up or down using @code{^} and @code{_},
1935 @lilypond[quote,raggedright,verbatim,fragment,relative=2]
1936 c\fermata c^\fermata c_\fermata
1941 @cindex staccatissimo
1951 @cindex organ pedal marks
1960 @cindex prallmordent
1964 @cindex thumb marking
1969 Here is a chart showing all scripts available,
1971 @lilypondfile[raggedright,quote]{script-chart.ly}
1976 The vertical ordering of scripts is controlled with the
1977 @code{script-priority} property. The lower this number, the closer it
1978 will be put to the note. In this example, the
1979 @internalsref{TextScript} (the sharp symbol) first has the lowest
1980 priority, so it is put lowest in the first example. In the second, the
1981 prall trill (the @internalsref{Script}) has the lowest, so it is on the
1982 inside. When two objects have the same priority, the order in which
1983 they are entered decides which one comes first.
1985 @lilypond[verbatim,relative=3,raggedright,fragment,quote]
1986 \once \override TextScript #'script-priority = #-100
1987 a4^\prall^\markup { \sharp }
1989 \once \override Script #'script-priority = #-100
1990 a4^\prall^\markup { \sharp }
1996 Program reference: @internalsref{Script}.
2001 These signs appear in the printed output but have no effect on the
2002 MIDI rendering of the music.
2005 @node Fingering instructions
2006 @subsection Fingering instructions
2009 @cindex finger change
2011 Fingering instructions can be entered using
2013 @var{note}-@var{digit}
2015 For finger changes, use markup texts
2017 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2019 c^\markup { \finger "2 - 3" }
2022 You can use the thumb-script to indicate that a note should be
2023 played with the thumb (e.g., in cello music)
2024 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2025 <a_\thumb a'-3>8 <b_\thumb b'-3>
2028 Fingerings for chords can also be added to individual notes
2029 of the chord by adding them after the pitches
2030 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2031 < c-1 e-2 g-3 b-5 >4
2037 You may exercise greater control over fingering chords by
2038 setting @code{fingeringOrientations}
2040 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2041 \set fingeringOrientations = #'(left down)
2042 <c-1 es-2 g-4 bes-5 > 4
2043 \set fingeringOrientations = #'(up right down)
2044 <c-1 es-2 g-4 bes-5 > 4
2047 Using this feature, it is also possible to put fingering instructions
2048 very close to note heads in monophonic music,
2050 @lilypond[verbatim,raggedright,quote,fragment]
2051 \set fingeringOrientations = #'(right)
2058 Program reference: @internalsref{Fingering}.
2060 Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
2064 @subsection Dynamics
2075 @cindex @code{\ffff}
2084 Absolute dynamic marks are specified using a command after a note
2085 @code{c4\ff}. The available dynamic marks are @code{\ppp},
2086 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2087 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
2088 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
2090 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2091 c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2092 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
2099 A crescendo mark is started with @code{\<} and terminated with
2100 @code{\!} or an absolute dynamic. A decrescendo is started with
2101 @code{\>} and is also terminated with @code{\!} or an absolute
2102 dynamic. Because these marks are bound to notes, you must
2103 use spacer notes if multiple marks are needed during one note
2105 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2107 << f1 { s4 s4\< s4\! \> s4\! } >>
2109 This may give rise to very short hairpins. Use @code{minimum-length}
2110 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2114 \override Staff.Hairpin #'minimum-length = #5
2121 You can also use a text saying @emph{cresc.} instead of hairpins
2123 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2134 You can also supply your own texts
2135 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2136 \set crescendoText = \markup { \italic "cresc. poco" }
2137 \set crescendoSpanner = #'dashed-line
2141 To create new dynamic marks or text that should be aligned
2142 with dynamics, see @ref{New dynamic marks}.
2147 @cindex @code{\dynamicUp}
2149 @cindex @code{\dynamicDown}
2150 @code{\dynamicDown},
2151 @cindex @code{\dynamicNeutral}
2152 @code{\dynamicNeutral}.
2157 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
2158 Vertical positioning of these symbols is handled by
2159 @internalsref{DynamicLineSpanner}.
2163 @subsection Breath marks
2165 Breath marks are entered using @code{\breathe}
2167 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2174 The glyph of the breath mark can be tuned by overriding the
2175 @code{text} property of the @code{BreathingSign} layout object with
2176 any markup text. For example,
2177 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
2179 \override BreathingSign #'text
2180 = #(make-musicglyph-markup "scripts.rvarcomma")
2187 Program reference: @internalsref{BreathingSign}.
2189 Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
2192 @node Running trills
2193 @subsection Running trills
2195 Long running trills are made with @code{\startTrillSpan} and
2196 @code{\stopTrillSpan},
2198 @lilypond[verbatim,raggedright,relative=2,quote,fragment]
2200 << { c1 \startTrillSpan }
2201 { s2. \grace { d16[\stopTrillSpan e] } } >>
2208 @code{\startTrillSpan},
2209 @cindex @code{\startTrillSpan}
2210 @code{\stopTrillSpan}.
2211 @cindex @code{\stopTrillSpan}
2216 This manual: @ref{Pitched trills}.
2218 Program reference: @internalsref{TrillSpanner}.
2222 @subsection Glissando
2225 @cindex @code{\glissando}
2227 A glissando is a smooth change in pitch. It is denoted by a line or a
2228 wavy line between two notes. It is requested by attaching
2229 @code{\glissando} to a note
2231 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2233 \override Glissando #'style = #'zigzag
2240 Program reference: @internalsref{Glissando}.
2242 Example files: @file{input/@/regression/@/glissando@/.ly}.
2247 Printing text over the line (such as @emph{gliss.}) is not supported.
2251 @subsection Arpeggio
2254 @cindex broken chord
2255 @cindex @code{\arpeggio}
2257 You can specify an arpeggio sign (also known as broken chord) on a
2258 chord by attaching an @code{\arpeggio} to a chord
2260 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2264 A square bracket on the left indicates that the player should not
2265 arpeggiate the chord
2267 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2272 The direction of the arpeggio is sometimes denoted by adding an
2273 arrowhead to the wiggly line
2275 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2287 When an arpeggio crosses staves, you may attach an arpeggio to the chords
2288 in both staves and set
2289 @internalsref{PianoStaff}.@code{connectArpeggios}
2291 @lilypond[quote,raggedright,fragment,relative=1,verbatim]
2292 \context PianoStaff <<
2293 \set PianoStaff.connectArpeggios = ##t
2294 \new Staff { <c' e g c>\arpeggio }
2295 \new Staff { \clef bass <c,, e g>\arpeggio }
2303 @cindex @code{\arpeggioUp}
2305 @cindex @code{\arpeggioDown}
2306 @code{\arpeggioDown},
2307 @cindex @code{\arpeggioNeutral}
2308 @code{\arpeggioNeutral},
2309 @cindex @code{\arpeggioBracket}
2310 @code{\arpeggioBracket}.
2315 Notation manual: @ref{Ties}, for writing out arpeggios.
2317 Program reference: @internalsref{Arpeggio}.
2322 It is not possible to mix connected arpeggios and unconnected
2323 arpeggios in one @internalsref{PianoStaff} at the same point in time.
2330 Polyphony in music refers to having more than one voice occuring in
2331 a piece of music. Polyphony in LilyPond refers to having more than
2332 one voice on the same staff.
2336 * Explicitly instantiating voices::
2337 * Collision Resolution::
2341 @node Basic polyphony
2342 @subsection Basic polyphony
2346 The easiest way to enter fragments with more than one voice on a staff
2347 is to enter each voice as a sequence (with @code{@{...@}}), and combine
2348 them simultaneously, separating the voices with @code{\\}
2352 @lilypond[quote,verbatim,fragment]
2353 \new Staff \relative c' {
2356 { g4 f e | d2 e2 } \\
2357 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
2363 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
2364 voices are sometimes called ``layers'' in other notation packages}
2366 to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
2367 each of these contexts, vertical direction of slurs, stems, etc., is set
2370 These voices are all seperate from the voice that contains the notes just
2371 outside the @code{<< \\ >>} construct. This should be noted when making
2372 changes at the voice level. This also means that slurs and ties cannot go
2373 into or out of a @code{<< \\ >>} construct. Conversely, parallel voices
2374 from separate @code{<< \\ >>} constructs on the same staff are the the
2375 same voice. Here is the same example, with different noteheads for each
2376 voice. Note that the change to the note-head style in the main voice does not affect
2377 the inside of the @code{<< \\ >>} constructs. Also, the change to the second
2378 voice in the first @code{<< \\ >>} construct is effective in the second
2379 @code{<< \\ >>}, and the voice is tied accross the two constructs.
2381 @lilypond[quote,verbatim,fragment]
2382 \new Staff \relative c' {
2383 \override NoteHead #'style = #'cross
2387 { \override NoteHead #'style = #'triangle
2392 { c8 b16 a b8 g ~ g2 } \\
2393 { \override NoteHead #'style = #'slash s4 b4 c2 }
2398 Polyphony does not change the relationship of notes within a
2399 @code{\relative @{ @}} block. Each note is calculated relative
2400 to the note immediately preceding it.
2403 \relative @{ noteA << noteB \\ noteC >> noteD @}
2406 @code{noteC} is relative to @code{noteB}, not @code{noteA};
2407 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
2410 @node Explicitly instantiating voices
2411 @subsection Explicitly instantiating voices
2413 @internalsref{Voice} contexts can also also be instantiated manually
2414 inside a @code{<< >>} block to create polyphonic music, using
2415 @code{\voiceOne}, up to @code{\voiceFour} to assign stem directions
2416 and a horizontal shift for each part.
2420 << \upper \\ \lower >>
2428 \context Voice = "1" @{ \voiceOne \upper @}
2429 \context Voice = "2" @{ \voiceTwo \lower @}
2433 The @code{\voiceXXX} commands set the direction of stems, slurs, ties,
2434 articulations, text annotations, augmentation dots of dotted
2435 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make
2436 these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour}
2437 make them point downwards.
2438 The command @code{\oneVoice} will revert back to the normal setting.
2440 An expression that appears directly inside a @code{<< >>} belongs to
2441 the main voice. This is useful when extra voices appear while the main
2442 voice is playing. Here is a more correct rendition of the example from
2443 the previous section. The crossed noteheads demonstrate that the main
2444 melody is now in a single voice context.
2446 @lilypond[quote,raggedright,verbatim]
2447 \new Staff \relative c' {
2448 \override NoteHead #'style = #'cross
2453 \context Voice="1" { \voiceTwo
2454 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
2457 \new Voice { \voiceThree
2466 The correct definition of the voices allows the melody to be slurred.
2467 @lilypond[quote,raggedright,verbatim]
2468 \new Staff \relative c' {
2473 \context Voice="1" { \voiceTwo
2474 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
2477 \new Voice { \voiceThree
2486 Avoiding the @code{\\} seperator also allows nesting polyphony
2487 constructs, which in some case might be a more natural way to typeset
2490 @lilypond[quote,raggedright,verbatim]
2491 \new Staff \relative c' {
2496 \context Voice="1" { \voiceTwo
2499 {c8 b16 a b8 g ~ g2}
2500 \new Voice { \voiceThree
2513 @node Collision Resolution
2514 @subsection Collision Resolution
2516 Normally, note heads with a different number of dots are not merged, but
2517 when the object property @code{merge-differently-dotted} is set in
2518 the @internalsref{NoteCollision} object, they are merged
2519 @lilypond[quote,verbatim,fragment,raggedright,relative=2]
2522 \override Staff.NoteCollision
2523 #'merge-differently-dotted = ##t
2525 } \\ { g8.[ f16] g8.[ f16] } >>
2528 Similarly, you can merge half note heads with eighth notes, by setting
2529 @code{merge-differently-headed}
2530 @lilypond[quote,raggedright,fragment,relative=2,verbatim]
2533 \override Staff.NoteCollision
2534 #'merge-differently-headed = ##t
2535 c8 c4. } \\ { c2 c2 } >>
2538 LilyPond also vertically shifts rests that are opposite of a stem,
2541 @lilypond[quote,raggedright,fragment,verbatim]
2542 \context Voice << c''4 \\ r4 >>
2548 @cindex @code{\oneVoice}
2550 @cindex @code{\voiceOne}
2552 @cindex @code{\voiceTwo}
2554 @cindex @code{\voiceThree}
2556 @cindex @code{\voiceFour}
2559 @cindex @code{\shiftOn}
2561 @cindex @code{\shiftOnn}
2563 @cindex @code{\shiftOnnn}
2565 @cindex @code{\shiftOff}
2566 @code{\shiftOff}: these commands specify in what chords of the current
2567 voice should be shifted. The outer voices (normally: voice one and
2568 two) have @code{\shiftOff}, while the inner voices (three and four)
2569 have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define
2570 further shift levels.
2572 When LilyPond cannot cope, the @code{force-hshift}
2573 property of the @internalsref{NoteColumn} object and pitched rests can
2574 be used to override typesetting decisions.
2576 @lilypond[quote,verbatim,raggedright]
2583 \once \override NoteColumn #'force-hshift = #1.7
2591 Program reference: the objects responsible for resolving collisions are
2592 @internalsref{NoteCollision} and @internalsref{RestCollision}.
2595 @inputfileref{input/@/regression,collision@/-dots@/.ly},
2596 @inputfileref{input/@/regression,collision@/-head-chords@/.ly},
2597 @inputfileref{input/@/regression,collision@/-heads@/.ly},
2598 @inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
2599 @inputfileref{input/@/regression,collisions@/.ly}.
2604 When using @code{merge-differently-headed} with an upstem eighth or a
2605 shorter note, and a downstem half note, the eighth note gets the wrong
2608 There is no support for clusters where the same note occurs with
2609 different accidentals in the same chord. In this case, it is
2610 recommended to use enharmonic transcription, or to use special cluster
2611 notation (see @ref{Clusters}).
2618 Repetition is a central concept in music, and multiple notations exist
2624 * Repeats and MIDI::
2625 * Manual repeat commands::
2627 * Tremolo subdivisions::
2633 @subsection Repeat types
2636 @cindex @code{\repeat}
2638 The following types of repetition are supported
2642 Repeated music is fully written (played) out. This is useful when
2643 entering repetitious music. This is the only kind of repeat that
2644 is included in MIDI output.
2647 Repeats are not written out, but alternative endings (volte) are
2648 printed, left to right with brackets. This is the standard notation
2649 for repeats with alternatives. These are not played in MIDI output by default.
2653 Alternative endings are written stacked. This has limited use but may be
2654 used to typeset two lines of lyrics in songs with repeats, see
2655 @inputfileref{input,star-spangled-banner@/.ly}.
2659 Make tremolo beams. These are not played in MIDI output by default.
2662 Make beat or measure repeats. These look like percent signs. These
2663 are not played in MIDI output by default. Percent repeats must be
2664 declared within a Voice context.
2670 @subsection Repeat syntax
2672 LilyPond has one syntactic construct for specifying different types of
2673 repeats. The syntax is
2676 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2679 If you have alternative endings, you may add
2680 @cindex @code{\alternative}
2691 where each @var{alternative} is a music expression. If you do not
2692 give enough alternatives for all of the repeats, the first alternative
2693 is assumed to be played more than once.
2695 Standard repeats are used like this
2696 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2698 \repeat volta 2 { c4 d e f }
2699 \repeat volta 2 { f e d c }
2702 With alternative endings
2703 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2705 \repeat volta 2 {c4 d e f}
2706 \alternative { {d2 d} {f f,} }
2709 @lilypond[quote,raggedright,fragment,verbatim,relative=2]
2712 \repeat volta 4 { e | c2 d2 | e2 f2 | }
2713 \alternative { { g4 g g } { a | a a a a | b2. } }
2717 It is possible to shorten volta brackets
2718 by setting @code{voltaSpannerDuration}. In the next example, the
2719 bracket only lasts one measure, which is a duration of 3/4.
2721 @lilypond[verbatim,raggedright,quote]
2725 \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2726 \repeat "volta" 5 { d d d }
2727 \alternative { { e e e f f f }
2737 Brackets for the repeat are normally only printed over the topmost
2738 staff. This can be adjusted by setting the @code{voltaOnThisStaff}
2739 property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
2744 @cindex repeat, ambiguous
2746 A nested repeat like
2755 is ambiguous, since it is is not clear to which @code{\repeat} the
2756 @code{\alternative} belongs. This ambiguity is resolved by always
2757 having the @code{\alternative} belong to the inner @code{\repeat}.
2758 For clarity, it is advisable to use braces in such situations.
2760 Timing information is not remembered at the start of an alternative,
2761 so after a repeat timing information must be reset by hand, for
2762 example by setting @code{Score.measurePosition} or entering
2763 @code{\partial}. Similarly, slurs or ties are also not repeated.
2766 @node Repeats and MIDI
2767 @subsection Repeats and MIDI
2769 @cindex expanding repeats
2770 @cindex @code{\unfoldRepeats}
2772 With a little bit of tweaking, all types of repeats can be present
2773 in the MIDI output. This is achieved by applying the
2774 @code{\unfoldRepeats} music function. This functions changes all
2775 repeats to unfold repeats.
2777 @lilypond[quote,verbatim,fragment,linewidth=8.0\cm]
2779 \repeat tremolo 8 {c'32 e' }
2780 \repeat percent 2 { c''8 d'' }
2781 \repeat volta 2 {c'4 d' e' f'}
2790 When creating a score file using @code{\unfoldRepeats} for midi, then
2791 it is necessary to make two @code{\score} blocks. One for MIDI (with
2792 unfolded repeats) and one for notation (with volta, tremolo, and
2793 percent repeats). For example,
2801 \unfoldRepeats @var{..music..}
2807 @node Manual repeat commands
2808 @subsection Manual repeat commands
2810 @cindex @code{repeatCommands}
2812 The property @code{repeatCommands} can be used to control the layout of
2813 repeats. Its value is a Scheme list of repeat commands.
2816 @item @code{start-repeat}
2817 Print a @code{|:} bar line.
2819 @item @code{end-repeat}
2820 Print a @code{:|} bar line.
2822 @item @code{(volta @var{text})}
2823 Print a volta bracket saying @var{text}: The text can be specified as
2824 a text string or as a markup text, see @ref{Text markup}. Do not
2825 forget to change the font, as the default number font does not contain
2826 alphabetic characters;
2828 @item @code{(volta #f)}
2829 Stop a running volta bracket.
2832 @lilypond[quote,raggedright,verbatim,fragment,relative=2]
2834 \set Score.repeatCommands = #'((volta "93") end-repeat)
2836 \set Score.repeatCommands = #'((volta #f))
2843 Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
2844 @internalsref{VoltaRepeatedMusic},
2845 @internalsref{UnfoldedRepeatedMusic}, and
2846 @internalsref{FoldedRepeatedMusic}.
2849 @node Tremolo repeats
2850 @subsection Tremolo repeats
2852 @cindex tremolo beams
2854 To place tremolo marks between notes, use @code{\repeat} with tremolo
2856 @lilypond[quote,verbatim,raggedright]
2857 \new Voice \relative c' {
2858 \repeat "tremolo" 8 { c16 d16 }
2859 \repeat "tremolo" 4 { c16 d16 }
2860 \repeat "tremolo" 2 { c16 d16 }
2864 Tremolo marks can also be put on a single note. In this case, the
2865 note should not be surrounded by braces.
2866 @lilypond[quote,verbatim,raggedright]
2867 \repeat "tremolo" 4 c'16
2870 Similar output is obtained using the tremolo subdivision, described in
2871 @ref{Tremolo subdivisions}.
2876 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
2878 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
2880 Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
2881 @inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
2884 @node Tremolo subdivisions
2885 @subsection Tremolo subdivisions
2887 @cindex tremolo marks
2888 @cindex @code{tremoloFlags}
2890 Tremolo marks can be printed on a single note by adding
2891 `@code{:}[@var{number}]' after the note. The number indicates the
2892 duration of the subdivision, and it must be at least 8. A
2893 @var{length} value of 8 gives one line across the note stem. If the
2894 length is omitted, the last value (stored in @code{tremoloFlags}) is
2897 @lilypond[quote,raggedright,verbatim,fragment]
2898 c'2:8 c':32 | c': c': |
2904 Tremolos entered in this way do not carry over into the MIDI output.
2909 In this manual: @ref{Tremolo repeats}.
2911 Elsewhere: @internalsref{StemTremolo}.
2914 @node Measure repeats
2915 @subsection Measure repeats
2917 @cindex percent repeats
2918 @cindex measure repeats
2920 In the @code{percent} style, a note pattern can be repeated. It is
2921 printed once, and then the pattern is replaced with a special sign.
2922 Patterns of one and two measures are replaced by percent-like signs,
2923 patterns that divide the measure length are replaced by slashes.
2924 Percent repeats must be declared within a @code{Voice} context.
2926 @lilypond[quote,verbatim,raggedright]
2927 \new Voice \relative c' {
2928 \repeat "percent" 4 { c4 }
2929 \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
2936 Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat},
2937 @internalsref{PercentRepeatedMusic}, and
2938 @internalsref{DoublePercentRepeat}.