1 @c -*- coding: utf-8; 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
9 @chapter Basic notation
11 This chapter explains how to use basic notation features.
16 * Multiple notes at once::
28 This section discusses how to specify the pitch of notes.
33 * Cautionary accidentals::
35 * Notes names in other languages::
45 @subsection Normal pitches
50 A pitch name is specified using lowercase letters @code{a} through @code{g}.
51 An ascending C-major scale is engraved with
53 @lilypond[quote,fragment,verbatim,ragged-right]
58 The note name @code{c} is engraved one octave below middle C.
60 @lilypond[quote,fragment,verbatim,ragged-right]
70 The optional octave specification takes the form of a series of
71 single quote (`@code{'}') characters or a series of comma
72 (`@code{,}') characters. Each @code{'} raises the pitch by one
73 octave; each @code{,} lowers the pitch by an octave.
75 @lilypond[quote,ragged-right,fragment,verbatim]
77 c' c'' e' g d'' d' d c
79 c, c,, e, g d,, d, d c
82 An alternate method may be used to declare which octave to
83 engrave a pitch; this method does not require as many
84 octave specifications (@code{'} and @code{,}). See
85 @ref{Relative octaves}.
89 @subsection Accidentals
91 @cindex note names, Dutch
92 @cindex note names, default
94 A sharp is formed by adding @code{-is} to the end of a pitch name and
95 a flat is formed by adding @code{-es}
97 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
101 Double sharps and double flats
102 are obtained by adding @code{-isis} or @code{-eses} to a note name. These
103 are the Dutch note names. In Dutch, @code{aes} is contracted to
104 @code{as}, but both forms are accepted. Similarly, both
105 @code{es} and @code{ees} are accepted
107 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
111 A natural will cancel the effect of an accidental or key signature.
112 However, naturals are not encoded into the note name syntax with a
113 suffix; a natural pitch is shown as a simple note name
115 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
119 The input @code{d e f} is interpreted as ``print a D-natural,
120 E-natural, and an F-natural,'' regardless of the key
121 signature. For more information about the distinction between
122 musical content and the presentation of that content, see
123 @ref{More about pitches}.
125 @lilypond[fragment,quote,ragged-right,verbatim,relative]
134 In accordance with standard typesetting rules, a natural sign is printed
135 before a sharp or flat if a previous accidental needs to be
136 cancelled. To change this behavior, use
137 @code{\set Staff.extraNatural = ##f}
139 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
141 \set Staff.extraNatural = ##f
148 Program reference: @internalsref{LedgerLineSpanner},
149 @internalsref{NoteHead}.
152 @node Cautionary accidentals
153 @subsection Cautionary accidentals
155 @cindex accidental, reminder
156 @cindex accidental, cautionary
157 @cindex accidental, parenthesized
158 @cindex reminder accidental
160 @cindex cautionary accidental
161 @cindex parenthesized accidental
164 Normally accidentals are printed automatically, but you may also
165 print them manually. A reminder accidental
166 can be forced by adding an exclamation mark @code{!}
167 after the pitch. A cautionary accidental
168 (i.e., an accidental within parentheses) can be obtained by adding the
169 question mark `@code{?}' after the pitch. These extra accidentals
170 can be used to produce natural signs, too.
172 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
173 cis cis cis! cis? c c? c! c
179 The automatic production of accidentals can be tuned in many
180 ways. For more information, see @ref{Automatic accidentals}.
184 @subsection Micro tones
186 @cindex quarter tones
187 @cindex semi-flats, semi-sharps
189 Half-flats and half-sharps are formed by adding @code{-eh} and
190 @code{-ih}; the following is a series of Cs with increasing pitches
192 @lilypond[verbatim,ragged-right,quote,relative=2,fragment]
193 \set Staff.extraNatural = ##f
197 Micro tones are also exported to the MIDI file.
202 There are no generally accepted standards for denoting
203 three-quarter flats, so LilyPond's symbol does not conform to any
207 @node Notes names in other languages
208 @subsection Notes names in other languages
210 There are predefined sets of note names for various other languages.
211 To use them, include the language specific init file. For
212 example, add @code{\include "english.ly"} to the top of the input
213 file. The available language files
214 and the note names they define are
216 @c what about micro-tunes, double-sharps, and double-flats? add
217 @c more columns to the table?
218 @c Oh, and should this be made into a multitable?
219 @cindex note names, other languages
221 Note Names sharp flat
222 nederlands.ly c d e f g a bes b -is -es
223 english.ly c d e f g a bf b -s/-sharp -f/-flat
225 deutsch.ly c d e f g a b h -is -es
226 norsk.ly c d e f g a b h -iss/-is -ess/-es
227 svenska.ly c d e f g a b h -iss -ess
228 italiano.ly do re mi fa sol la sib si -d -b
229 catalan.ly do re mi fa sol la sib si -d/-s -b
230 espanol.ly do re mi fa sol la sib si -s -b
234 @node Relative octaves
235 @subsection Relative octaves
238 @cindex Relative octave specification
241 Octaves are specified by adding @code{'} and @code{,} to pitch names.
242 When you copy existing music, it is easy to accidentally put a pitch
243 in the wrong octave and hard to find such an error. The relative
244 octave mode prevents these errors by making the mistakes much
245 larger: a single error puts the rest of the piece off by one octave
248 \relative @var{startpitch} @var{musicexpr}
255 \relative @var{musicexpr}
259 @code{c'} is used as the default if no starting pitch is defined.
261 The octave of notes that appear in @var{musicexpr} are calculated as
262 follows: if no octave changing marks are used, the basic interval
263 between this and the last note is always taken to be a fourth or
264 less. This distance is determined without regarding alterations; a
265 @code{fisis} following a @code{ceses} will be put above the
266 @code{ceses}. In other words, a doubly-augmented fourth is considered
267 a smaller interval than a diminished fifth, even though the
268 doubly-augmented fourth spans seven semitones while the diminished
269 fifth only spans six semitones.
271 The octave changing marks @code{'} and @code{,} can be added to raise
272 or lower the pitch by an extra octave. Upon entering relative mode,
273 an absolute starting pitch can be specified that will act as the
274 predecessor of the first note of @var{musicexpr}. If no starting pitch
275 is specified, then middle C is used as a start.
277 Here is the relative mode shown in action
278 @lilypond[quote,fragment,ragged-right,verbatim]
284 Octave changing marks are used for intervals greater than a fourth
285 @lilypond[quote,ragged-right,fragment,verbatim]
291 If the preceding item is a chord, the first note of the chord is used
292 to determine the first note of the next chord
294 @lilypond[quote,ragged-right,fragment,verbatim]
302 The pitch after the @code{\relative} contains a note name.
304 The relative conversion will not affect @code{\transpose},
305 @code{\chordmode} or @code{\relative} sections in its argument. To use
306 relative within transposed music, an additional @code{\relative} must
307 be placed inside @code{\transpose}.
311 @subsection Octave check
315 Octave checks make octave errors easier to correct: a note may be
316 followed by @code{=}@var{quotes} which indicates what its absolute
317 octave should be. In the following example,
320 \relative c'' @{ c='' b=' d,='' @}
324 the @code{d} will generate a warning, because a @code{d''} is expected
325 (because @code{b'} to @code{d''} is only a third), but a @code{d'} is
326 found. In the output, the octave is corrected to be a @code{d''} and
327 the next note is calculated relative to @code{d''} instead of @code{d'}.
329 There is also an octave check that produces no visible output. The syntax
335 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
336 quotes) in @code{\relative} mode. If not, a warning is printed, and the
337 octave is corrected. The @var{pitch} is not printed as a note.
339 In the example below, the first check passes without incident, since
340 the @code{e} (in relative mode) is within a fifth of @code{a'}. However,
341 the second check produces a warning, since the @code{e} is not within
342 a fifth of @code{b'}. The warning message is printed, and the octave
343 is adjusted so that the following notes are in the correct octave
355 The octave of a note following an octave check is determined with
356 respect to the note preceding it. In the next fragment, the last note
357 is an @code{a'}, above middle C. That means that the @code{\octave}
358 check passes successfully, so the check could be deleted without changing
359 the output of the piece.
361 @lilypond[quote,ragged-right,verbatim,fragment]
371 @subsection Transpose
374 @cindex Transposition of pitches
377 A music expression can be transposed with @code{\transpose}. The
380 \transpose @var{from} @var{to} @var{musicexpr}
383 This means that @var{musicexpr} is transposed by the interval between
384 the pitches @var{from} and @var{to}: any note with pitch @code{from}
385 is changed to @code{to}.
387 For example, consider a piece written in the key of D-major. If
388 this piece is a little too low for its performer, it can be
389 transposed up to E-major with
391 \transpose d e @dots{}
394 Consider a part written for violin (a C instrument). If
395 this part is to be played on the A clarinet (for which an
396 A is notated as a C, and which sounds a minor third lower
397 than notated), the following
398 transposition will produce the appropriate part
401 \transpose a c @dots{}
404 @code{\transpose} distinguishes between enharmonic pitches: both
405 @code{\transpose c cis} or @code{\transpose c des} will transpose up
406 half a tone. The first version will print sharps and the second
407 version will print flats
409 @lilypond[quote,ragged-right,verbatim]
410 mus = { \key d \major cis d fis g }
419 @code{\transpose} may also be used to input written notes for a
420 transposing instrument. Pitches are normally entered into LilyPond
421 in C (or ``concert pitch''), but they may be entered in another
422 key. For example, when entering music for a B-flat trumpet which
423 begins on concert D, one would write
426 \transpose c bes @{ e4 @dots{} @}
429 To print this music in B-flat again (i.e., producing a trumpet part,
430 instead of a concert pitch conductor's score) you would wrap the
431 existing music with another @code{transpose}
434 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
440 Program reference: @internalsref{TransposedMusic}.
445 If you want to use both @code{\transpose} and @code{\relative},
446 you must put @code{\transpose} outside of @code{\relative}, since
447 @code{\relative} will have no effect music that appears inside a
458 Rests are entered like notes with the note name @code{r}
460 @lilypond[fragment,quote,ragged-right,verbatim]
464 Whole bar rests, centered in middle of the bar,
465 must be done with multi-measure rests. They can be used for a
466 single bar as well as many bars, and are discussed in
467 @ref{Multi measure rests}.
469 To explicitly specify a rest's vertical position, write a note
470 followed by @code{\rest}. A rest will be placed in the position
471 where the note would appear,
473 @lilypond[fragment,quote,ragged-right,verbatim]
478 This makes manual formatting of
479 polyphonic music much easier, since the automatic rest collision
480 formatter will leave these rests alone.
484 Program reference: @internalsref{Rest}.
491 @cindex Invisible rest
496 An invisible rest (also called a `skip') can be entered like a note
497 with note name `@code{s}' or with @code{\skip @var{duration}}
499 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
500 a4 a4 s4 a4 \skip 1 a4
503 The @code{s} syntax is only available in note mode and chord mode. In
504 other situations, for example, when entering lyrics, you should use
505 the @code{\skip} command
507 @lilypond[quote,ragged-right,verbatim]
510 \new Lyrics \lyricmode { \skip 2 bla2 }
514 The skip command is merely an empty musical placeholder. It does not
515 produce any output, not even transparent output.
517 The @code{s} skip command does create @internalsref{Staff} and
518 @internalsref{Voice} when necessary, similar to note and rest
519 commands. For example, the following results in an empty staff.
521 @lilypond[quote,ragged-right,verbatim]
525 The fragment @code{@{ \skip 4 @} } would produce an empty page.
529 Program reference: @internalsref{SkipMusic}.
536 This section discusses rhythms, durations, and bars.
540 * Augmentation dots::
542 * Scaling durations::
545 * Automatic note splitting::
550 @subsection Durations
557 In Note, Chord, and Lyrics mode, durations are designated by numbers and
558 dots: durations are entered as their reciprocal values. For example, a
559 quarter note is entered using a @code{4} (since it is a 1/4 note), while
560 a half note is entered using a @code{2} (since it is a 1/2 note). For
561 notes longer than a whole you must use the variables @code{\longa} and
566 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
568 r1 r2 r4 r8 r16 r32 r64 r64
574 a\breve*1/2 \autoBeamOff
575 a1 a2 a4 a8 a16 a32 a64 a64
578 r\longa*1/4 r\breve *1/2
579 r1 r2 r4 r8 r16 r32 r64 r64
585 \remove "Clef_engraver"
586 \override StaffSymbol #'transparent = ##t
587 \override TimeSignature #'transparent = ##t
588 \override BarLine #'transparent = ##t
589 \consists "Pitch_squash_engraver"
595 If the duration is omitted then it is set to the previously entered
596 duration. The default for the first note is a quarter note.
598 @lilypond[quote,ragged-right,verbatim,fragment]
599 { a a a2 a a4 a a1 a }
603 @node Augmentation dots
604 @subsection Augmentation dots
608 To obtain dotted note lengths, simply add a dot (`@code{.}') to
609 the number. Double-dotted notes are produced in a similar way.
611 @lilypond[quote,ragged-right,fragment,verbatim]
612 a'4 b' c''4. b'8 a'4. b'4.. c''8.
617 Dots are normally moved up to avoid staff lines, except in polyphonic
618 situations. The following commands may be used to force a particular
625 @funindex \dotsNeutral
630 Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
640 Tuplets are made out of a music expression by multiplying all durations
644 \times @var{fraction} @var{musicexpr}
648 The duration of @var{musicexpr} will be multiplied by the fraction.
649 The fraction's denominator will be printed over the notes, optionally
650 with a bracket. The most common tuplet is the triplet in which 3
651 notes have the length of 2, so the notes are 2/3 of their written
654 @lilypond[quote,ragged-right,fragment,verbatim]
655 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
658 Tuplets may be nested, for example,
660 @lilypond[fragment,ragged-right,verbatim,relative=2]
661 \set tupletNumberFormatFunction = #fraction-tuplet-formatter
664 \times 3/5 { a a a a a }
672 @funindex \tupletDown
674 @funindex \tupletNeutral
675 @code{\tupletNeutral}.
680 @funindex tupletNumberFormatFunction
681 @cindex tuplet formatting
683 The property @code{tupletSpannerDuration} specifies how long each
684 bracket should last. With this, you can make lots of tuplets while
685 typing @code{\times} only once, thus saving lots of typing. In the next
686 example, there are two triplets shown, while @code{\times} was only
689 @lilypond[quote,fragment,relative=2,ragged-right,verbatim]
690 \set tupletSpannerDuration = #(ly:make-moment 1 4)
691 \times 2/3 { c8 c c c c c }
695 For more information about @code{make-moment}, see
696 @ref{Time administration}.
698 The format of the number is determined by the property
699 @code{tupletNumberFormatFunction}. The default prints only the
700 denominator, but if it is set to the Scheme function
701 @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
704 To avoid printing tuplet numbers, use
706 @lilypond[quote,fragment,relative=2,ragged-right,verbatim]
707 \times 2/3 { c8 c c } \times 2/3 { c8 c c }
708 \override TupletNumber #'transparent = ##t
709 \times 2/3 { c8 c c } \times 2/3 { c8 c c }
715 Program reference: @internalsref{TupletBracket},
716 @internalsref{TupletNumber}, and @internalsref{TimeScaledMusic}.
718 Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
722 @node Scaling durations
723 @subsection Scaling durations
725 You can alter the length of duration by a fraction @var{N/M}
726 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
727 will not affect the appearance of the notes or rests produced.
729 In the following example, the first three notes take up exactly two
730 beats, but no triplet bracket is printed.
731 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
733 a4*2/3 gis4*2/3 a4*2/3
741 This manual: @ref{Tuplets}
745 @subsection Bar check
748 @funindex barCheckSynchronize
751 Bar checks help detect errors in the durations. A bar check is
752 entered using the bar symbol, `@code{|}'. Whenever it is encountered
753 during interpretation, it should fall on a measure boundary. If it
754 does not, a warning is printed. In the next example, the second bar
755 check will signal an error
757 \time 3/4 c2 e4 | g2 |
760 Bar checks can also be used in lyrics, for example
765 Twin -- kle | Twin -- kle
769 Failed bar checks are caused by entering incorrect
770 durations. Incorrect durations often completely garble up the score,
771 especially if the score is polyphonic, so a good place to start correcting
772 input is by scanning for failed bar checks and incorrect durations.
777 It is also possible to redefine the meaning of @code{|}. This is done
778 by assigning a music expression to @code{pipeSymbol},
780 @lilypond[quote,ragged-right,verbatim]
781 pipeSymbol = \bar "||"
787 @node Barnumber check
788 @subsection Barnumber check
790 When copying large pieces of music, it can be helpful to check that
791 the LilyPond bar number corresponds to the original that you are
792 entering from. This can be checked with @code{\barNumberCheck}, for
800 will print a warning if the @code{currentBarNumber} is not 123 when it
804 @node Automatic note splitting
805 @subsection Automatic note splitting
807 Long notes can be converted automatically to tied notes. This is done
808 by replacing the @internalsref{Note_heads_engraver} by the
809 @internalsref{Completion_heads_engraver}.
810 In the following examples, notes crossing the bar line are split and tied.
812 @lilypond[quote,fragment,verbatim,relative=1,line-width=12\cm]
814 \remove "Note_heads_engraver"
815 \consists "Completion_heads_engraver"
817 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
821 This engraver splits all running notes at the bar line, and inserts
822 ties. One of its uses is to debug complex scores: if the measures are
823 not entirely filled, then the ties exactly show how much each measure
829 Not all durations (especially those containing tuplets) can be
830 represented exactly with normal notes and dots, but the engraver will
833 @code{Completion_heads_engraver} only affects notes; it does not split
839 Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
843 Program reference: @internalsref{Completion_heads_engraver}.
846 @node Multiple notes at once
847 @section Multiple notes at once
849 Polyphony in music refers to having more than one voice occurring in
850 a piece of music. Polyphony in LilyPond refers to having more than
851 one voice on the same staff.
857 * Explicitly instantiating voices::
858 * Collision Resolution::
867 A chord is formed by a enclosing a set of pitches in @code{<} and
868 @code{>}. A chord may be followed by a duration, and a set of
869 articulations, just like simple notes
871 @lilypond[verbatim,ragged-right,fragment,quote,relative=1]
875 For more information about chords, see @ref{Chord names}.
881 Whenever a note is found, a @internalsref{Stem} object is created
882 automatically. For whole notes and rests, they are also created but
891 @funindex \stemNeutral
897 To change the direction of stems in the middle of the staff, use
899 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
901 \override Stem #'neutral-direction = #up
903 \override Stem #'neutral-direction = #down
908 @node Basic polyphony
909 @subsection Basic polyphony
913 The easiest way to enter fragments with more than one voice on a staff
914 is to enter each voice as a sequence (with @code{@{...@}}), and combine
915 them simultaneously, separating the voices with @code{\\}
919 @lilypond[quote,verbatim,fragment]
920 \new Staff \relative c' {
923 { g4 f e | d2 e2 } \\
924 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
930 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
931 voices are sometimes called ``layers'' in other notation packages}
933 to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
934 each of these contexts, vertical direction of slurs, stems, etc., is set
937 These voices are all separate from the voice that contains the notes just
938 outside the @code{<< \\ >>} construct. This should be noted when making
939 changes at the voice level. This also means that slurs and ties cannot go
940 into or out of a @code{<< \\ >>} construct. Conversely, parallel voices
941 from separate @code{<< \\ >>} constructs on the same staff are the the
942 same voice. Here is the same example, with different noteheads for each
943 voice. Note that the change to the note-head style in the main voice does
945 the inside of the @code{<< \\ >>} constructs. Also, the change to the
947 voice in the first @code{<< \\ >>} construct is effective in the second
948 @code{<< \\ >>}, and the voice is tied across the two constructs.
950 @cindex note heads, styles
952 @lilypond[quote,verbatim,fragment]
953 \new Staff \relative c' {
954 \override NoteHead #'style = #'cross
958 { \override NoteHead #'style = #'triangle
963 { c8 b16 a b8 g ~ g2 } \\
964 { \override NoteHead #'style = #'slash s4 b4 c2 }
969 Polyphony does not change the relationship of notes within a
970 @code{\relative @{ @}} block. Each note is calculated relative
971 to the note immediately preceding it.
974 \relative @{ noteA << noteB \\ noteC >> noteD @}
977 @code{noteC} is relative to @code{noteB}, not @code{noteA};
978 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
981 @node Explicitly instantiating voices
982 @subsection Explicitly instantiating voices
984 @internalsref{Voice} contexts can also be instantiated manually
985 inside a @code{<< >>} block to create polyphonic music, using
986 @code{\voiceOne}, up to @code{\voiceFour} to assign stem directions
987 and a horizontal shift for each part.
991 << \upper \\ \lower >>
999 \new Voice = "1" @{ \voiceOne \upper @}
1000 \new Voice = "2" @{ \voiceTwo \lower @}
1004 The @code{\voiceXXX} commands set the direction of stems, slurs, ties,
1005 articulations, text annotations, augmentation dots of dotted
1006 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make
1007 these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour}
1008 make them point downwards.
1009 The command @code{\oneVoice} will revert back to the normal setting.
1011 An expression that appears directly inside a @code{<< >>} belongs to
1012 the main voice. This is useful when extra voices appear while the main
1013 voice is playing. Here is a more correct rendition of the example from
1014 the previous section. The crossed noteheads demonstrate that the main
1015 melody is now in a single voice context.
1017 @lilypond[quote,ragged-right,verbatim]
1018 \new Staff \relative c' {
1019 \override NoteHead #'style = #'cross
1024 \new Voice="1" { \voiceTwo
1025 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1028 \new Voice { \voiceThree
1037 The correct definition of the voices allows the melody to be slurred.
1038 @lilypond[quote,ragged-right,verbatim]
1039 \new Staff \relative c' {
1044 \context Voice="1" { \voiceTwo
1045 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1048 \new Voice { \voiceThree
1057 Avoiding the @code{\\} separator also allows nesting polyphony
1058 constructs, which in some case might be a more natural way to typeset
1061 @lilypond[quote,ragged-right,verbatim]
1062 \new Staff \relative c' {
1067 \context Voice="1" { \voiceTwo
1070 {c8 b16 a b8 g ~ g2}
1071 \new Voice { \voiceThree
1084 @node Collision Resolution
1085 @subsection Collision Resolution
1087 Normally, note heads with a different number of dots are not merged, but
1088 when the object property @code{merge-differently-dotted} is set in
1089 the @internalsref{NoteCollision} object, they are merged
1090 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
1093 \override Staff.NoteCollision
1094 #'merge-differently-dotted = ##t
1096 } \\ { g8.[ f16] g8.[ f16] } >>
1099 Similarly, you can merge half note heads with eighth notes, by setting
1100 @code{merge-differently-headed}
1101 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1104 \override Staff.NoteCollision
1105 #'merge-differently-headed = ##t
1106 c8 c4. } \\ { c2 c2 } >>
1109 LilyPond also vertically shifts rests that are opposite of a stem,
1112 @lilypond[quote,ragged-right,fragment,verbatim]
1113 \new Voice << c''4 \\ r4 >>
1125 @funindex \voiceThree
1127 @funindex \voiceFour
1134 @funindex \shiftOnnn
1137 @code{\shiftOff}: these commands specify in what chords of the current
1138 voice should be shifted. The outer voices (normally: voice one and
1139 two) have @code{\shiftOff}, while the inner voices (three and four)
1140 have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define
1141 further shift levels.
1143 When LilyPond cannot cope, the @code{force-hshift}
1144 property of the @internalsref{NoteColumn} object and pitched rests can
1145 be used to override typesetting decisions.
1147 @lilypond[quote,verbatim,ragged-right]
1154 \once \override NoteColumn #'force-hshift = #1.7
1162 Program reference: the objects responsible for resolving collisions are
1163 @internalsref{NoteCollision} and @internalsref{RestCollision}.
1166 @inputfileref{input/@/regression,collision@/-dots@/.ly},
1167 @inputfileref{input/@/regression,collision@/-head-chords@/.ly},
1168 @inputfileref{input/@/regression,collision@/-heads@/.ly},
1169 @inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
1170 @inputfileref{input/@/regression,collisions@/.ly}.
1175 When using @code{merge-differently-headed} with an upstem eighth or a
1176 shorter note, and a downstem half note, the eighth note gets the wrong
1179 There is no support for clusters where the same note occurs with
1180 different accidentals in the same chord. In this case, it is
1181 recommended to use enharmonic transcription, or to use special cluster
1182 notation (see @ref{Clusters}).
1186 @node Staff notation
1187 @section Staff notation
1189 @cindex Staff notation
1191 This section describes music notation that occurs on staff level,
1192 such as key signatures, clefs and time signatures.
1198 * Partial measures::
1201 * System start delimiters::
1203 * Writing music in parallel::
1212 The clef indicates which lines of the staff correspond to which
1213 pitches. The clef is set with the @code{\clef} command
1215 @lilypond[quote,ragged-right,fragment,verbatim]
1216 { c''2 \clef alto g'2 }
1225 @cindex soprano clef
1226 @cindex mezzosoprano clef
1227 @cindex baritone clef
1228 @cindex varbaritone clef
1229 @cindex subbass clef
1231 Supported clefs include
1233 @multitable @columnfractions .33 .66
1234 @headitem Clef @tab Position
1235 @item @code{treble}, violin, G, G2 @tab
1237 @item @code{alto, C} @tab
1239 @item @code{tenor} @tab
1241 @item @code{bass, F} @tab
1243 @item @code{french} @tab
1244 G clef on 1st line, so-called French violin clef
1245 @item @code{soprano} @tab
1247 @item @code{mezzosoprano} @tab
1249 @item @code{baritone} @tab
1251 @item @code{varbaritone} @tab
1253 @item @code{subbass} @tab
1255 @item @code{percussion} @tab
1257 @item @code{tab} @tab
1261 By adding @code{_8} or @code{^8} to the clef name, the clef is
1262 transposed one octave down or up, respectively, and @code{_15} and
1263 @code{^15} transposes by two octaves. The argument @var{clefname}
1264 must be enclosed in quotes when it contains underscores or digits. For
1267 @cindex choral tenor clef
1268 @lilypond[quote,ragged-right,verbatim,fragment,relative=1]
1275 The command @code{\clef "treble_8"} is equivalent to setting
1277 @code{clefPosition} (which controls the Y position of the clef),
1278 @code{middleCPosition} and @code{clefOctavation}. A clef is printed
1279 when any of these properties are changed. The following example shows
1280 possibilities when setting properties manually.
1282 @lilypond[quote,ragged-right,verbatim]
1284 \set Staff.clefGlyph = #"clefs.F"
1285 \set Staff.clefPosition = #2
1287 \set Staff.clefGlyph = #"clefs.G"
1289 \set Staff.clefGlyph = #"clefs.C"
1291 \set Staff.clefOctavation = #7
1293 \set Staff.clefOctavation = #0
1294 \set Staff.clefPosition = #0
1298 \set Staff.middleCPosition = #4
1306 Program reference: @internalsref{Clef}.
1310 @subsection Key signature
1312 @cindex Key signature
1315 The key signature indicates the tonality in which a piece is played. It
1316 is denoted by a set of alterations (flats or sharps) at the start of the
1319 Setting or changing the key signature is done with the @code{\key}
1323 @code{\key} @var{pitch} @var{type}
1332 @funindex \mixolydian
1336 @cindex church modes
1338 Here, @var{type} should be @code{\major} or @code{\minor} to get
1339 @var{pitch}-major or @var{pitch}-minor, respectively. You may also
1340 use the standard mode names (also called ``church modes''): @code{\ionian},
1341 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
1342 @code{\phrygian}, and @code{\dorian}.
1344 This command sets the context property
1345 @code{Staff.keySignature}. Non-standard key signatures
1346 can be specified by setting this property directly.
1348 Accidentals and key signatures often confuse new users, because
1349 unaltered notes get natural signs depending on the key signature. For
1350 more information, see @ref{Accidentals} or @ref{More about pitches}.
1352 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
1361 A natural sign is printed to cancel any previous accidentals. This
1362 can be suppressed by setting the @code{Staff.printKeyCancellation}
1365 @lilypond[quote,fragment,ragged-right,fragment,verbatim,relative=2]
1370 \set Staff.printKeyCancellation = ##f
1380 Program reference: @internalsref{KeyCancellation},
1381 @internalsref{KeySignature}.
1384 @node Time signature
1385 @subsection Time signature
1387 @cindex Time signature
1391 Time signature indicates the metrum of a piece: a regular pattern of
1392 strong and weak beats. It is denoted by a fraction at the start of the
1395 The time signature is set with the @code{\time} command
1397 @lilypond[quote,ragged-right,fragment,verbatim]
1398 \time 2/4 c'2 \time 3/4 c'2.
1403 The symbol that is printed can be customized with the @code{style}
1404 property. Setting it to @code{#'()} uses fraction style for 4/4 and
1407 @lilypond[fragment,quote,ragged-right,verbatim]
1410 \override Staff.TimeSignature #'style = #'()
1415 There are many more options for its layout. See @ref{Ancient time
1416 signatures} for more examples.
1418 @code{\time} sets the property @code{timeSignatureFraction},
1419 @code{beatLength} and @code{measureLength} in the @code{Timing}
1420 context, which is normally aliased to @internalsref{Score}. The
1421 property @code{measureLength} determines where bar lines should be
1422 inserted, and how automatic beams should be generated. Changing the
1423 value of @code{timeSignatureFraction} also causes the symbol to be
1426 More options are available through the Scheme function
1427 @code{set-time-signature}. In combination with the
1428 @internalsref{Measure_grouping_engraver}, it will create
1429 @internalsref{MeasureGrouping} signs. Such signs ease reading
1430 rhythmically complex modern music. In the following example, the 9/8
1431 measure is subdivided in 2, 2, 2 and 3. This is passed to
1432 @code{set-time-signature} as the third argument @code{(2 2 2 3)}
1434 @lilypond[quote,ragged-right,verbatim]
1437 #(set-time-signature 9 8 '(2 2 2 3))
1438 g8[ g] d[ d] g[ g] a8[( bes g]) |
1439 #(set-time-signature 5 8 '(3 2))
1445 \consists "Measure_grouping_engraver"
1454 Program reference: @internalsref{TimeSignature}, and
1455 @internalsref{Timing_translator}.
1457 Examples: @inputfileref{input/@/test,compound@/-time@/.ly}.
1462 Automatic beaming does not use the measure grouping specified with
1463 @code{set-time-signature}.
1466 @node Partial measures
1467 @subsection Partial measures
1471 @cindex partial measure
1472 @cindex measure, partial
1473 @cindex shorten measures
1476 Partial measures, such as an anacrusis or upbeat, are entered using the
1478 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
1479 \partial 16*5 c16 cis d dis e | a2. c,4 | b2
1482 The syntax for this command is
1485 \partial @var{duration}
1488 This is internally translated into
1491 \set Timing.measurePosition = -@var{length of duration}
1494 The property @code{measurePosition} contains a rational number
1495 indicating how much of the measure has passed at this point. Note
1496 that this is a negative number; @code{\partial 4} is internally
1497 translated to mean ``there is a quarter note left in the bar''.
1502 This command does not take into account grace notes at the start of
1503 the music. When a piece starts with graces notes in the pickup, then
1504 the @code{\partial} should follow the grace notes
1506 @lilypond[verbatim,quote,ragged-right,relative,fragment]
1515 @subsection Bar lines
1519 @cindex measure lines
1522 Bar lines delimit measures, but are also used to indicate
1523 repeats. Normally they are inserted automatically. Line
1524 breaks may only happen on bar lines.
1526 Special types of bar lines can be forced with the @code{\bar} command
1528 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1532 The following bar types are available
1534 @lilypondfile[ragged-right,quote]{bar-lines.ly}
1536 In addition, you can specify @code{"||:"}, which is equivalent to
1537 @code{"|:"} except at line breaks, where it gives a double bar line at
1538 the end of the line and a start repeat at the beginning of the next
1541 To allow a line break where there is no visible bar line, use
1548 This will insert an invisible bar line and allow line breaks at this
1551 In scores with many staves, a @code{\bar} command in one staff is
1552 automatically applied to all staves. The resulting bar lines are
1553 connected between different staves of a StaffGroup
1555 @lilypond[quote,ragged-right,fragment,verbatim]
1563 \new Staff { \clef bass c4 g e g }
1565 \new Staff { \clef bass c2 c2 }
1573 @funindex repeatCommands
1574 @funindex defaultBarType
1576 The command @code{\bar }@var{bartype} is a short cut for doing
1577 @code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
1578 is set to a string, a bar line of that type is created.
1580 A bar line is created whenever the @code{whichBar} property is set.
1581 At the start of a measure it is set to the contents of
1582 @code{Timing.defaultBarType}. The contents of @code{repeatCommands} are
1584 to override default measure bars.
1586 You are encouraged to use @code{\repeat} for repetitions. See
1592 In this manual: @ref{Repeats}, @ref{System start delimiters}.
1594 Program reference: @internalsref{BarLine} (created at
1595 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1597 Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
1600 @node Unmetered music
1601 @subsection Unmetered music
1604 @funindex \cadenzaOn
1605 @funindex \cadenzaOff
1607 Bar lines and bar numbers are calculated automatically. For unmetered
1608 music (cadenzas, for example), this is not desirable. To turn off
1609 automatic bar lines and bar numbers, use the commands @code{\cadenzaOn}
1610 and @code{\cadenzaOff}.
1612 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1624 LilyPond will only insert page breaks at a barline. Unless the unmetered
1625 music ends before the end of the staff line, you will need to insert
1633 to indicate where line breaks can occur.
1636 @node System start delimiters
1637 @subsection System start delimiters
1639 @cindex start of system
1640 @cindex Staff, multiple
1641 @cindex bracket, vertical
1642 @cindex brace, vertical
1645 @cindex staff, choir
1647 Many scores consist of more than one staff. These staves can be
1648 joined in four different ways
1651 @item The group is started with a brace at the left, and bar lines are
1652 connected. This is done with the @internalsref{GrandStaff} context.
1654 @lilypond[verbatim,ragged-right,quote]
1662 @item The group is started with a bracket, and bar lines are connected.
1663 This is done with the
1664 @internalsref{StaffGroup} context
1666 @lilypond[verbatim,ragged-right,quote]
1674 @item The group is started with a bracket, but bar lines are not
1675 connected. This is done with the @internalsref{ChoirStaff} context.
1677 @lilypond[verbatim,ragged-right,quote]
1685 @item The group is started with a vertical line. Bar lines are not
1686 connected. This is the default for the score.
1688 @lilypond[verbatim,ragged-right,quote]
1699 The bar lines at the start of each system are
1700 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
1701 @internalsref{SystemStartBracket}. Only one of these types is created
1702 in every context, and that type is determined by the property
1703 @code{systemStartDelimiter}.
1707 @subsection Staff symbol
1709 @cindex adjusting staff symbol
1711 Notes, dynamic signs, etc., are grouped
1712 with a set of horizontal lines, called a staff (plural `staves'). In
1713 LilyPond, these lines are drawn using a separate layout object called
1716 The staff symbol may be tuned in the number, thickness and distance
1717 of lines, using properties. This is demonstrated in the example files
1718 @inputfileref{input/@/test,staff@/-lines@/.ly},
1719 @inputfileref{input/@/test,staff@/-size@/.ly}.
1721 In addition, staves may be started and stopped at will. This is done
1722 with @code{\startStaff} and @code{\stopStaff}.
1724 @lilypond[verbatim,relative=2,fragment]
1726 \override Staff.StaffSymbol #'line-count = 2
1727 \stopStaff \startStaff
1729 \revert Staff.StaffSymbol #'line-count
1730 \stopStaff \startStaff
1734 In combination with Frenched staves, this may be used to typeset ossia
1735 sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
1740 @lilypondfile{ossia.ly}
1742 @cindex staff lines, setting number of
1743 @cindex staff lines, setting thickness of
1744 @cindex thickness of staff lines, setting
1745 @cindex number of staff lines, setting
1749 Program reference: @internalsref{StaffSymbol}.
1751 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
1752 @inputfileref{input/@/test@/,ossia.ly},
1753 @inputfileref{input/@/test,staff@/-size@/.ly},
1754 @inputfileref{input/@/regression,staff@/-line@/-positions@/.ly}.
1757 @node Writing music in parallel
1758 @subsection Writing music in parallel
1760 @cindex Writing music in parallel
1761 @cindex Interleaved music
1763 Music for multiple parts can be interleaved
1765 @lilypond[quote,fragment,verbatim]
1766 \parallelMusic #'(voiceA voiceB) {
1767 r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] |
1769 r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] |
1773 \new Staff \new Voice \voiceA
1774 \new Staff \new Voice \voiceB
1780 @node Connecting notes
1781 @section Connecting notes
1783 This section deals with notation that affects groups of notes.
1789 * Laissez vibrer ties::
1802 A tie connects two adjacent note heads of the same pitch. The tie in
1803 effect extends the length of a note. Ties should not be confused with
1804 slurs, which indicate articulation, or phrasing slurs, which indicate
1805 musical phrasing. A tie is entered using the tilde symbol `@code{~}'
1807 @lilypond[quote,ragged-right,fragment,verbatim]
1808 e' ~ e' <c' e' g'> ~ <c' e' g'>
1811 When a tie is applied to a chord, all note heads whose pitches match
1812 are connected. When no note heads match, no ties will be created.
1814 A tie is just a way of extending a note duration, similar to the
1815 augmentation dot. The following example shows two ways of notating
1816 exactly the same concept
1818 @lilypond[quote,fragment,ragged-right]
1819 \time 3/4 c'2. c'2 ~ c'4
1823 Ties are used either when the note crosses a bar line, or when dots
1824 cannot be used to denote the rhythm. When using ties, larger note
1825 values should be aligned to subdivisions of the measure, such as
1827 @lilypond[fragment,quote,ragged-right]
1829 r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
1833 If you need to tie a lot of notes over bars, it may be easier to use
1834 automatic note splitting (see @ref{Automatic note splitting}). This
1835 mechanism automatically splits long notes, and ties them across bar
1838 When a second alternative of a repeat starts with a tied note, you
1839 have to repeat the tie. This can be achieved with @code{\repeatTie},
1841 @lilypond[fragment,quote,ragged-right,relative=2]
1845 @cindex repeating ties
1846 @cindex volta brackets and ties
1850 Ties are sometimes used to write out arpeggios. In this case, two tied
1851 notes need not be consecutive. This can be achieved by setting the
1852 @code{tieWaitForNote} property to true. The same feature is also useful,
1853 for example, to tie a tremolo to a chord. For example,
1855 @lilypond[fragment,verbatim,relative=1,ragged-right]
1856 \set tieWaitForNote = ##t
1857 \grace { c16[~ e~ g]~ } <c, e g>2
1858 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
1869 @funindex \tieNeutral
1871 @funindex \tieDotted
1873 @funindex \tieDashed
1881 In this manual: @ref{Automatic note splitting}.
1883 Program reference: @internalsref{Tie}.
1886 @inputfileref{input/@/regression,tie-arpeggio.ly}
1887 @inputfileref{input/@/regression,tie-manual.ly}
1894 Switching staves when a tie is active will not produce a slanted tie.
1902 A slur indicates that notes are to be played bound or
1903 @emph{legato}. They are entered using parentheses
1905 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1906 f( g a) a8 b( a4 g2 f4)
1910 The direction of a slur can be specified with
1911 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is
1912 either @code{Up}, @code{Down}, or @code{Neutral} (automatically
1915 However, there is a convenient shorthand for forcing slur
1916 directions. By adding @code{_} or @code{^} before the opening
1917 parentheses, the direction is also set. For example,
1919 @lilypond[relative=2,ragged-right,quote,verbatim,fragment]
1923 Only one slur can be printed at once. If you need to print a long
1924 slur over a few small slurs, please see @ref{Phrasing slurs}.
1929 Some composers write two slurs when they want legato chords. This can
1930 be achieved in LilyPond by setting @code{doubleSlurs},
1932 @lilypond[verbatim,ragged-right,relative,fragment,quote]
1933 \set doubleSlurs = ##t
1934 <c e>4 ( <d f> <c e> <d f> )
1944 @funindex \slurNeutral
1945 @code{\slurNeutral},
1946 @funindex \slurDashed
1948 @funindex \slurDotted
1950 @funindex \slurSolid
1955 Program reference: @seeinternals{Slur}.
1958 @node Phrasing slurs
1959 @subsection Phrasing slurs
1961 @cindex phrasing slurs
1962 @cindex phrasing marks
1964 A phrasing slur (or phrasing mark) connects notes and is used to
1965 indicate a musical sentence. It is written using @code{\(} and @code{\)}
1968 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
1969 \time 6/4 c'\( d( e) f( e) d\)
1972 Typographically, the phrasing slur behaves almost exactly like a
1973 normal slur. However, they are treated as different objects. A
1974 @code{\slurUp} will have no effect on a phrasing slur; instead, use
1975 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1976 @code{\phrasingSlurNeutral}.
1978 You cannot have simultaneous phrasing slurs.
1983 @funindex \phrasingSlurUp
1984 @code{\phrasingSlurUp},
1985 @funindex \phrasingSlurDown
1986 @code{\phrasingSlurDown},
1987 @funindex \phrasingSlurNeutral
1988 @code{\phrasingSlurNeutral}.
1993 Program reference: @internalsref{PhrasingSlur}.
1996 @node Laissez vibrer ties
1997 @subsection Laissez vibrer ties
1998 @cindex Laissez vibrer
1999 @cindex Ties, laissez vibrer
2001 L.v. ties (laissez vibrer) indicate that notes must not be damped at the
2002 end. It is used in notation for piano, harp and other string and
2003 percussion instruments. They can be entered using @code{\laissezVibrer},
2005 @lilypond[fragment,ragged-right,verbatim,relative=1]
2006 <c f g>\laissezVibrer
2012 @internalsref{LaissezVibrerTie}
2013 @internalsref{LaissezVibrerTieColumn}
2016 @inputfileref{input/regression,laissez-vibrer-tie.ly}
2019 @node Automatic beams
2020 @subsection Automatic beams
2022 LilyPond inserts beams automatically
2024 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2025 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
2028 When these automatic decisions are not good enough, beaming can be
2029 entered explicitly. It is also possible to define beaming patterns
2030 that differ from the defaults. See @ref{Setting automatic beam behavior}
2033 Individual notes may be marked with @code{\noBeam} to prevent them
2036 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2037 \time 2/4 c8 c\noBeam c c
2043 Program reference: @internalsref{Beam}.
2047 @subsection Manual beams
2049 @cindex beams, manual
2053 In some cases it may be necessary to override the automatic beaming
2054 algorithm. For example, the autobeamer will not put beams over rests
2055 or bar lines. Such beams are specified manually by marking the begin
2056 and end point with @code{[} and @code{]}
2058 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2060 r4 r8[ g' a r8] r8 g[ | a] r8
2067 @funindex stemLeftBeamCount
2068 @funindex stemRightBeamCount
2070 Normally, beaming patterns within a beam are determined automatically.
2071 If necessary, the properties @code{stemLeftBeamCount} and
2072 @code{stemRightBeamCount} can be used to override the defaults. If
2073 either property is set, its value will be used only once, and then it
2076 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2081 \set stemLeftBeamCount = #1
2086 The property @code{subdivideBeams} can be set in order to subdivide
2087 all 16th or shorter beams at beat positions, as defined by the
2088 @code{beatLength} property.
2090 @lilypond[fragment,quote,relative=2,verbatim]
2092 \set subdivideBeams = ##t
2094 \set Score.beatLength = #(ly:make-moment 1 8)
2097 @funindex subdivideBeams
2100 For more information about @code{make-moment}, see
2101 @ref{Time administration}.
2103 Line breaks are normally forbidden when beams cross bar lines. This
2104 behavior can be changed by setting @code{allowBeamBreak}.
2106 @funindex allowBeamBreak
2107 @cindex beams and line breaks
2108 @cindex beams, kneed
2110 @cindex auto-knee-gap
2115 Kneed beams are inserted automatically when a large gap is detected
2116 between the note heads. This behavior can be tuned through the object.
2118 Automatically kneed cross-staff beams cannot be used together with
2119 hidden staves. See @ref{Hiding staves}.
2121 Beams do not avoid collisions with symbols around the notes, such as
2122 texts and accidentals.
2126 @subsection Grace notes
2131 @cindex appoggiatura
2132 @cindex acciaccatura
2134 Grace notes are ornaments that are written out. The most common ones
2135 are acciaccatura, which should be played as very short. It is denoted
2136 by a slurred small note with a slashed stem. The appoggiatura is a
2137 grace note that takes a fixed fraction of the main note, and is
2138 denoted as a slurred note in small print without a slash. They
2139 are entered with the commands @code{\acciaccatura} and
2140 @code{\appoggiatura}, as demonstrated in the following example
2142 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2143 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
2144 \acciaccatura { g16[ f] } e4
2147 Both are special forms of the @code{\grace} command. By prefixing this
2148 keyword to a music expression, a new one is formed, which will be
2149 printed in a smaller font and takes up no logical time in a measure.
2151 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2153 \grace { c16[ d16] } c2 c4
2157 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
2158 @code{\grace} command does not start a slur.
2160 Internally, timing for grace notes is done using a second, `grace'
2161 timing. Every point in time consists of two rational numbers: one
2162 denotes the logical time, one denotes the grace timing. The above
2163 example is shown here with timing tuples
2165 @lilypond[quote,ragged-right]
2168 c4 \grace c16 c4 \grace {
2171 \new Lyrics \lyricmode {
2172 \override LyricText #'font-family = #'typewriter
2176 ( \fraction 1 4 , \fraction -1 16 ) } 16 }
2177 \markup { (\fraction 1 4 , 0 ) } 4
2179 \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
2180 \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
2182 \markup { ( \fraction 2 4 , 0 ) }
2187 The placement of grace notes is synchronized between different staves.
2188 In the following example, there are two sixteenth grace notes for
2189 every eighth grace note
2191 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2192 << \new Staff { e4 \grace { c16[ d e f] } e4 }
2193 \new Staff { c4 \grace { g8[ b] } c4 } >>
2196 @funindex \afterGrace
2198 If you want to end a note with a grace, use the @code{\afterGrace}
2199 command. It takes two arguments: the main note, and the grace notes
2200 following the main note.
2202 @lilypond[ragged-right, verbatim,relative=2,fragment]
2203 c1 \afterGrace d1 { c16[ d] } c4
2206 This will put the grace notes after a ``space'' lasting 3/4 of the
2207 length of the main note. The fraction 3/4 can be changed by setting
2208 @code{afterGraceFraction}, ie.
2211 afterGraceFraction = #(cons 7 8)
2215 will put the grace note at 7/8 of the main note.
2217 The same effect can be achieved manually by doing
2219 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2222 { s2 \grace { c16[ d] } } >>
2228 By adjusting the duration of the skip note (here it is a half-note),
2229 the space between the main-note and the grace is adjusted.
2231 A @code{\grace} section will introduce special typesetting settings,
2232 for example, to produce smaller type, and set directions. Hence, when
2233 introducing layout tweaks, they should be inside the grace section,
2235 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2247 The overrides should also be reverted inside the grace section.
2249 The layout of grace sections can be changed throughout the music using
2250 the function @code{add-grace-property}. The following example
2251 undefines the Stem direction for this grace, so stems do not always
2256 #(add-grace-property 'Voice 'Stem 'direction '())
2262 Another option is to change the variables @code{startGraceMusic},
2263 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
2264 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
2265 @code{stopAppoggiaturaMusic}. More information is in the file
2266 @file{ly/@/grace@/-init@/.ly}.
2269 The slash through the stem in acciaccaturas can be obtained
2270 in other situations by @code{\override Stem #'stroke-style = #"grace"}.
2274 Program reference: @internalsref{GraceMusic}.
2279 A score that starts with a @code{\grace} section needs an explicit
2280 @code{\new Voice} declaration, otherwise the main note and the grace
2281 note end up on different staves.
2283 Grace note synchronization can also lead to surprises. Staff notation,
2284 such as key signatures, bar lines, etc., are also synchronized. Take
2285 care when you mix staves with grace notes and staves without, for example,
2287 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2288 << \new Staff { e4 \bar "|:" \grace c16 d4 }
2289 \new Staff { c4 \bar "|:" d4 } >>
2293 This can be remedied by inserting grace skips of the corresponding
2294 durations in the other staves. For the above example
2297 \new Staff @{ c4 \bar "|:" \grace s16 d4 @}
2300 Grace sections should only be used within sequential music
2301 expressions. Nesting or juxtaposing grace sections is not supported,
2302 and might produce crashes or other errors.
2306 @node Expressive marks
2307 @section Expressive marks
2309 Expressive marks help musicians to bring more to the music than simple
2314 * Fingering instructions::
2324 @subsection Articulations
2326 @cindex Articulations
2330 A variety of symbols can appear above and below notes to indicate
2331 different characteristics of the performance. They are added to a note
2332 by adding a dash and the character signifying the
2333 articulation. They are demonstrated here
2335 @lilypondfile[quote,ragged-right]{script-abbreviations.ly}
2337 The meanings of these shorthands can be changed. See
2338 @file{ly/@/script@/-init@/.ly} for examples.
2340 The script is automatically placed, but the direction can be forced as
2341 well. Like other pieces of LilyPond code, @code{_} will place them
2342 below the staff, and @code{^} will place them above.
2344 @lilypond[quote,ragged-right,fragment,verbatim]
2348 Other symbols can be added using the syntax
2349 @var{note}@code{\}@var{name}. Again, they
2350 can be forced up or down using @code{^} and @code{_},
2353 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
2354 c\fermata c^\fermata c_\fermata
2359 @cindex staccatissimo
2369 @cindex organ pedal marks
2378 @cindex prallmordent
2382 @cindex thumb marking
2387 Here is a chart showing all scripts available,
2389 @lilypondfile[ragged-right,quote]{script-chart.ly}
2394 The vertical ordering of scripts is controlled with the
2395 @code{script-priority} property. The lower this number, the closer it
2396 will be put to the note. In this example, the
2397 @internalsref{TextScript} (the sharp symbol) first has the lowest
2398 priority, so it is put lowest in the first example. In the second, the
2399 prall trill (the @internalsref{Script}) has the lowest, so it is on the
2400 inside. When two objects have the same priority, the order in which
2401 they are entered decides which one comes first.
2403 @lilypond[verbatim,relative=3,ragged-right,fragment,quote]
2404 \once \override TextScript #'script-priority = #-100
2405 a4^\prall^\markup { \sharp }
2407 \once \override Script #'script-priority = #-100
2408 a4^\prall^\markup { \sharp }
2414 Program reference: @internalsref{Script}.
2419 These signs appear in the printed output but have no effect on the
2420 MIDI rendering of the music.
2423 @node Fingering instructions
2424 @subsection Fingering instructions
2427 @cindex finger change
2429 Fingering instructions can be entered using
2431 @var{note}-@var{digit}
2433 For finger changes, use markup texts
2435 @lilypond[quote,verbatim,ragged-right,fragment,relative=1]
2437 c^\markup { \finger "2 - 3" }
2440 You can use the thumb-script to indicate that a note should be
2441 played with the thumb (e.g., in cello music)
2442 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2443 <a_\thumb a'-3>8 <b_\thumb b'-3>
2446 Fingerings for chords can also be added to individual notes
2447 of the chord by adding them after the pitches
2448 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2449 < c-1 e-2 g-3 b-5 >4
2455 You may exercise greater control over fingering chords by
2456 setting @code{fingeringOrientations}
2458 @lilypond[quote,verbatim,ragged-right,fragment,relative=1]
2459 \set fingeringOrientations = #'(left down)
2460 <c-1 es-2 g-4 bes-5 > 4
2461 \set fingeringOrientations = #'(up right down)
2462 <c-1 es-2 g-4 bes-5 > 4
2465 Using this feature, it is also possible to put fingering instructions
2466 very close to note heads in monophonic music,
2468 @lilypond[verbatim,ragged-right,quote,fragment]
2469 \set fingeringOrientations = #'(right)
2476 Program reference: @internalsref{Fingering}.
2478 Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
2482 @subsection Dynamics
2503 Absolute dynamic marks are specified using a command after a note
2504 @code{c4\ff}. The available dynamic marks are @code{\ppppp},
2505 @code{\pppp}, @code{\ppp},
2506 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2507 @code{\fff}, @code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff},
2508 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
2510 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2511 c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2512 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
2519 A crescendo mark is started with @code{\<} and terminated with
2520 @code{\!} or an absolute dynamic. A decrescendo is started with
2521 @code{\>} and is also terminated with @code{\!} or an absolute
2522 dynamic. @code{\cr} and @code{\decr} may be used instead of
2523 @code{\<} and @code{\>}. Because these marks are bound to notes, you must
2524 use spacer notes if multiple marks are needed during one note
2526 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2528 << f1 { s4 s4\< s4\! \> s4\! } >>
2532 A hairpin starts at the left edge of the beginning note and ends on the
2533 right edge of the ending note.
2535 In some situations the @code{\espressivo} articulation mark may
2536 be suitable to indicate a crescendo and decrescendo on the one note,
2538 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2539 c2 b4 a g1\espressivo
2542 This may give rise to very short hairpins. Use @code{minimum-length}
2543 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2547 \override Staff.Hairpin #'minimum-length = #5
2554 You can also use a text saying @emph{cresc.} instead of hairpins
2556 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2567 You can also supply your own texts
2568 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2569 \set crescendoText = \markup { \italic "cresc. poco" }
2570 \set crescendoSpanner = #'dashed-line
2574 To create new dynamic marks or text that should be aligned
2575 with dynamics, see @ref{New dynamic marks}.
2580 Dynamics that occur at, begin on, or end on, the same note
2581 will be vertically aligned. If you want to ensure that dynamics
2582 are aligned when they do not occur on the same note, you can
2583 increase the @code{staff-padding} property.
2586 \override DynamicLineSpanner #'staff-padding = #4
2589 You may also use this property if the dynamics are colliding
2590 with other notation.
2592 Crescendi and decrescendi that end on the first note of a
2593 new line are not printed. To change this behavior, use
2596 \override Score.Hairpin #'after-line-breaking = ##t
2599 Text style dynamic changes (such as cresc. and dim.) are printed with a
2600 dashed line showing their extent. To surpress printing this line, use
2603 \override DynamicTextSpanner #'dash-period = #-1.0
2609 @funindex \dynamicUp
2611 @funindex \dynamicDown
2612 @code{\dynamicDown},
2613 @funindex \dynamicNeutral
2614 @code{\dynamicNeutral}.
2619 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
2620 Vertical positioning of these symbols is handled by
2621 @internalsref{DynamicLineSpanner}.
2625 @subsection Breath marks
2627 Breath marks are entered using @code{\breathe}
2629 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2636 The glyph of the breath mark can be tuned by overriding the
2637 @code{text} property of the @code{BreathingSign} layout object with
2638 any markup text. For example,
2639 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
2641 \override BreathingSign #'text
2642 = #(make-musicglyph-markup "scripts.rvarcomma")
2649 Program reference: @internalsref{BreathingSign}.
2651 Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
2657 Short trills are printed like normal articulation; see @ref{Articulations}.
2659 Long running trills are made with @code{\startTrillSpan} and
2660 @code{\stopTrillSpan},
2662 @lilypond[verbatim,ragged-right,relative=2,quote,fragment]
2664 << { c1 \startTrillSpan }
2665 { s2. \grace { d16[\stopTrillSpan e] } } >>
2669 @cindex Pitched trills
2671 Trills that should be executed on an explicitly specified pitch can be
2672 typeset with the command @code{pitchedTrill},
2674 @lilypond[ragged-right,verbatim,fragment,relative=1]
2675 \pitchedTrill c4\startTrillSpan fis
2679 The first argument is the main note. The pitch of the second
2680 is printed as a stemless note head in parentheses.
2685 @code{\startTrillSpan},
2686 @funindex \startTrillSpan
2687 @code{\stopTrillSpan}.
2688 @funindex \stopTrillSpan
2693 Program reference: @internalsref{TrillSpanner}.
2697 @subsection Glissando
2700 @funindex \glissando
2702 A glissando is a smooth change in pitch. It is denoted by a line or a
2703 wavy line between two notes. It is requested by attaching
2704 @code{\glissando} to a note
2706 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2708 \override Glissando #'style = #'zigzag
2715 Program reference: @internalsref{Glissando}.
2717 Example files: @file{input/@/regression/@/glissando@/.ly}.
2722 Printing text over the line (such as @emph{gliss.}) is not supported.
2726 @subsection Arpeggio
2729 @cindex broken chord
2732 You can specify an arpeggio sign (also known as broken chord) on a
2733 chord by attaching an @code{\arpeggio} to a chord
2735 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2739 A square bracket on the left indicates that the player should not
2740 arpeggiate the chord
2742 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2747 The direction of the arpeggio is sometimes denoted by adding an
2748 arrowhead to the wiggly line
2750 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2762 When an arpeggio crosses staves, you may attach an arpeggio to the chords
2763 in both staves and set
2764 @internalsref{PianoStaff}.@code{connectArpeggios}
2766 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2768 \set PianoStaff.connectArpeggios = ##t
2769 \new Staff { <c' e g c>\arpeggio }
2770 \new Staff { \clef bass <c,, e g>\arpeggio }
2778 @funindex \arpeggioUp
2780 @funindex \arpeggioDown
2781 @code{\arpeggioDown},
2782 @funindex \arpeggioNeutral
2783 @code{\arpeggioNeutral},
2784 @funindex \arpeggioBracket
2785 @code{\arpeggioBracket}.
2790 Notation manual: @ref{Ties}, for writing out arpeggios.
2792 Program reference: @internalsref{Arpeggio}.
2797 It is not possible to mix connected arpeggios and unconnected
2798 arpeggios in one @internalsref{PianoStaff} at the same point in time.
2807 Repetition is a central concept in music, and multiple notations exist
2813 * Repeats and MIDI::
2814 * Manual repeat commands::
2816 * Tremolo subdivisions::
2822 @subsection Repeat types
2827 The following types of repetition are supported
2831 Repeated music is fully written (played) out. This is useful when
2832 entering repetitious music. This is the only kind of repeat that
2833 is included in MIDI output.
2836 Repeats are not written out, but alternative endings (volte) are
2837 printed, left to right with brackets. This is the standard notation
2838 for repeats with alternatives. These are not played in MIDI output by
2843 Alternative endings are written stacked. This has limited use but may be
2844 used to typeset two lines of lyrics in songs with repeats, see
2845 @inputfileref{input,star-spangled-banner@/.ly}.
2849 Make tremolo beams. These are not played in MIDI output by default.
2852 Make beat or measure repeats. These look like percent signs. These
2853 are not played in MIDI output by default. Percent repeats must be
2854 declared within a Voice context.
2860 @subsection Repeat syntax
2862 LilyPond has one syntactic construct for specifying different types of
2863 repeats. The syntax is
2866 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2869 If you have alternative endings, you may add
2870 @funindex \alternative
2881 where each @var{alternative} is a music expression. If you do not
2882 give enough alternatives for all of the repeats, the first alternative
2883 is assumed to be played more than once.
2885 Standard repeats are used like this
2886 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2888 \repeat volta 2 { c4 d e f }
2889 \repeat volta 2 { f e d c }
2892 With alternative endings
2893 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2895 \repeat volta 2 {c4 d e f}
2896 \alternative { {d2 d} {f f,} }
2899 In this example, the first ending is not a complete bar (it
2900 only had 3 beats). The beginning of the second ending
2901 contains the 4th beat from the first ending. This ``extra''
2902 beat in the second ending is due to the first time ending,
2903 and has nothing to do with the @code{\partial} at the
2904 beginning of the example.
2906 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2909 \repeat volta 4 { e | c2 d2 | e2 f2 | }
2910 \alternative { { g4 g g } { a | a a a a | b2. } }
2914 It is possible to shorten volta brackets
2915 by setting @code{voltaSpannerDuration}. In the next example, the
2916 bracket only lasts one measure, which is a duration of 3/4.
2918 @lilypond[verbatim,ragged-right,quote]
2922 \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2923 \repeat "volta" 5 { d d d }
2924 \alternative { { e e e f f f }
2934 Brackets for the repeat are normally only printed over the topmost
2935 staff. This can be adjusted by setting the @code{voltaOnThisStaff}
2936 property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
2941 @cindex repeat, ambiguous
2943 A nested repeat like
2952 is ambiguous, since it is is not clear to which @code{\repeat} the
2953 @code{\alternative} belongs. This ambiguity is resolved by always
2954 having the @code{\alternative} belong to the inner @code{\repeat}.
2955 For clarity, it is advisable to use braces in such situations.
2957 Timing information is not remembered at the start of an alternative,
2958 so after a repeat timing information must be reset by hand, for
2959 example by setting @code{Score.measurePosition} or entering
2960 @code{\partial}. Similarly, slurs or ties are also not repeated.
2963 @node Repeats and MIDI
2964 @subsection Repeats and MIDI
2966 @cindex expanding repeats
2967 @funindex \unfoldRepeats
2969 With a little bit of tweaking, all types of repeats can be present
2970 in the MIDI output. This is achieved by applying the
2971 @code{\unfoldRepeats} music function. This functions changes all
2972 repeats to unfold repeats.
2974 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
2976 \repeat tremolo 8 {c'32 e' }
2977 \repeat percent 2 { c''8 d'' }
2978 \repeat volta 2 {c'4 d' e' f'}
2987 When creating a score file using @code{\unfoldRepeats} for midi, then
2988 it is necessary to make two @code{\score} blocks. One for MIDI (with
2989 unfolded repeats) and one for notation (with volta, tremolo, and
2990 percent repeats). For example,
2998 \unfoldRepeats @var{..music..}
3004 @node Manual repeat commands
3005 @subsection Manual repeat commands
3007 @funindex repeatCommands
3009 The property @code{repeatCommands} can be used to control the layout of
3010 repeats. Its value is a Scheme list of repeat commands.
3013 @item @code{start-repeat}
3014 Print a @code{|:} bar line.
3016 @item @code{end-repeat}
3017 Print a @code{:|} bar line.
3019 @item @code{(volta @var{text})}
3020 Print a volta bracket saying @var{text}: The text can be specified as
3021 a text string or as a markup text, see @ref{Text markup}. Do not
3022 forget to change the font, as the default number font does not contain
3023 alphabetic characters;
3025 @item @code{(volta #f)}
3026 Stop a running volta bracket.
3029 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
3031 \set Score.repeatCommands = #'((volta "93") end-repeat)
3033 \set Score.repeatCommands = #'((volta #f))
3040 Program reference: @internalsref{VoltaBracket},
3041 @internalsref{RepeatedMusic},
3042 @internalsref{VoltaRepeatedMusic},
3043 @internalsref{UnfoldedRepeatedMusic}, and
3044 @internalsref{FoldedRepeatedMusic}.
3047 @node Tremolo repeats
3048 @subsection Tremolo repeats
3050 @cindex tremolo beams
3052 To place tremolo marks between notes, use @code{\repeat} with tremolo
3054 @lilypond[quote,verbatim,ragged-right]
3055 \new Voice \relative c' {
3056 \repeat "tremolo" 8 { c16 d16 }
3057 \repeat "tremolo" 4 { c16 d16 }
3058 \repeat "tremolo" 2 { c16 d16 }
3062 Tremolo marks can also be put on a single note. In this case, the
3063 note should not be surrounded by braces.
3064 @lilypond[quote,verbatim,ragged-right]
3065 \repeat "tremolo" 4 c'16
3068 Similar output is obtained using the tremolo subdivision, described in
3069 @ref{Tremolo subdivisions}.
3074 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
3076 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
3078 Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
3079 @inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
3082 @node Tremolo subdivisions
3083 @subsection Tremolo subdivisions
3085 @cindex tremolo marks
3086 @funindex tremoloFlags
3088 Tremolo marks can be printed on a single note by adding
3089 `@code{:}[@var{number}]' after the note. The number indicates the
3090 duration of the subdivision, and it must be at least 8. A
3091 @var{length} value of 8 gives one line across the note stem. If the
3092 length is omitted, the last value (stored in @code{tremoloFlags}) is
3095 @lilypond[quote,ragged-right,verbatim,fragment]
3096 c'2:8 c':32 | c': c': |
3102 Tremolos entered in this way do not carry over into the MIDI output.
3107 In this manual: @ref{Tremolo repeats}.
3109 Elsewhere: @internalsref{StemTremolo}.
3112 @node Measure repeats
3113 @subsection Measure repeats
3115 @cindex percent repeats
3116 @cindex measure repeats
3118 In the @code{percent} style, a note pattern can be repeated. It is
3119 printed once, and then the pattern is replaced with a special sign.
3120 Patterns of one and two measures are replaced by percent-like signs,
3121 patterns that divide the measure length are replaced by slashes.
3122 Percent repeats must be declared within a @code{Voice} context.
3124 @lilypond[quote,verbatim,ragged-right]
3125 \new Voice \relative c' {
3126 \repeat "percent" 4 { c4 }
3127 \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
3131 Measure repeats of more than 2 measures get a counter, if you switch
3132 on the @code{countPercentRepeats} property,
3134 @lilypond[relative=2,fragment,quote,verbatim,ragged-right]
3136 \set countPercentRepeats = ##t
3137 \repeat "percent" 4 { c1 }
3143 Isolated percents can also be printed. This is done by putting a multi
3144 measure rest with a different print function,
3146 @lilypond[fragment,verbatim]
3147 \override MultiMeasureRest #'stencil
3148 = #ly:multi-measure-rest::percent
3157 Program reference: @internalsref{RepeatSlash},
3158 @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
3159 @internalsref{DoublePercentRepeatCounter},
3160 @internalsref{PercentRepeatCounter},
3161 @internalsref{PercentRepeatedMusic}.