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 where @code{duration} is the rhythmic length to be added before
1491 This is internally translated into
1494 \set Timing.measurePosition = -@var{length of duration}
1497 The property @code{measurePosition} contains a rational number
1498 indicating how much of the measure has passed at this point. Note
1499 that this is a negative number; @code{\partial 4} is internally
1500 translated to mean ``there is a quarter note left in the bar''.
1505 This command does not take into account grace notes at the start of
1506 the music. When a piece starts with graces notes in the pickup, then
1507 the @code{\partial} should follow the grace notes
1509 @lilypond[verbatim,quote,ragged-right,relative,fragment]
1518 @subsection Bar lines
1522 @cindex measure lines
1525 Bar lines delimit measures, but are also used to indicate
1526 repeats. Normally they are inserted automatically. Line
1527 breaks may only happen on bar lines.
1529 Special types of bar lines can be forced with the @code{\bar} command
1531 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1535 The following bar types are available
1537 @lilypondfile[ragged-right,quote]{bar-lines.ly}
1539 In addition, you can specify @code{"||:"}, which is equivalent to
1540 @code{"|:"} except at line breaks, where it gives a double bar line at
1541 the end of the line and a start repeat at the beginning of the next
1544 To allow a line break where there is no visible bar line, use
1551 This will insert an invisible bar line and allow line breaks at this
1554 In scores with many staves, a @code{\bar} command in one staff is
1555 automatically applied to all staves. The resulting bar lines are
1556 connected between different staves of a StaffGroup
1558 @lilypond[quote,ragged-right,fragment,verbatim]
1566 \new Staff { \clef bass c4 g e g }
1568 \new Staff { \clef bass c2 c2 }
1576 @funindex repeatCommands
1577 @funindex defaultBarType
1579 The command @code{\bar }@var{bartype} is a short cut for doing
1580 @code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
1581 is set to a string, a bar line of that type is created.
1583 A bar line is created whenever the @code{whichBar} property is set.
1584 At the start of a measure it is set to the contents of
1585 @code{Timing.defaultBarType}. The contents of @code{repeatCommands} are
1587 to override default measure bars.
1589 You are encouraged to use @code{\repeat} for repetitions. See
1595 In this manual: @ref{Repeats}, @ref{System start delimiters}.
1597 Program reference: @internalsref{BarLine} (created at
1598 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1600 Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
1603 @node Unmetered music
1604 @subsection Unmetered music
1607 @funindex \cadenzaOn
1608 @funindex \cadenzaOff
1610 Bar lines and bar numbers are calculated automatically. For unmetered
1611 music (cadenzas, for example), this is not desirable. To turn off
1612 automatic bar lines and bar numbers, use the commands @code{\cadenzaOn}
1613 and @code{\cadenzaOff}.
1615 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1627 LilyPond will only insert line breaks and page breaks at a
1628 barline. Unless the unmetered music ends before the end of
1629 the staff line, you will need to insert
1637 to indicate where breaks can occur.
1640 @node System start delimiters
1641 @subsection System start delimiters
1643 @cindex start of system
1644 @cindex Staff, multiple
1645 @cindex bracket, vertical
1646 @cindex brace, vertical
1649 @cindex staff, choir
1651 Many scores consist of more than one staff. These staves can be
1652 joined in four different ways
1655 @item The group is started with a brace at the left, and bar lines are
1656 connected. This is done with the @internalsref{GrandStaff} context.
1658 @lilypond[verbatim,ragged-right,quote]
1666 @item The group is started with a bracket, and bar lines are connected.
1667 This is done with the
1668 @internalsref{StaffGroup} context
1670 @lilypond[verbatim,ragged-right,quote]
1678 @item The group is started with a bracket, but bar lines are not
1679 connected. This is done with the @internalsref{ChoirStaff} context.
1681 @lilypond[verbatim,ragged-right,quote]
1689 @item The group is started with a vertical line. Bar lines are not
1690 connected. This is the default for the score.
1692 @lilypond[verbatim,ragged-right,quote]
1703 The bar lines at the start of each system are
1704 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
1705 @internalsref{SystemStartBracket}. Only one of these types is created
1706 in every context, and that type is determined by the property
1707 @code{systemStartDelimiter}.
1711 @subsection Staff symbol
1713 @cindex adjusting staff symbol
1715 Notes, dynamic signs, etc., are grouped
1716 with a set of horizontal lines, called a staff (plural `staves'). In
1717 LilyPond, these lines are drawn using a separate layout object called
1720 The staff symbol may be tuned in the number, thickness and distance
1721 of lines, using properties. This is demonstrated in the example files
1722 @inputfileref{input/@/test,staff@/-lines@/.ly},
1723 @inputfileref{input/@/test,staff@/-size@/.ly}.
1725 In addition, staves may be started and stopped at will. This is done
1726 with @code{\startStaff} and @code{\stopStaff}.
1728 @lilypond[verbatim,relative=2,fragment]
1730 \override Staff.StaffSymbol #'line-count = 2
1731 \stopStaff \startStaff
1733 \revert Staff.StaffSymbol #'line-count
1734 \stopStaff \startStaff
1738 In combination with Frenched staves, this may be used to typeset ossia
1739 sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
1744 @lilypondfile{ossia.ly}
1746 @cindex staff lines, setting number of
1747 @cindex staff lines, setting thickness of
1748 @cindex thickness of staff lines, setting
1749 @cindex number of staff lines, setting
1753 Program reference: @internalsref{StaffSymbol}.
1755 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
1756 @inputfileref{input/@/test@/,ossia.ly},
1757 @inputfileref{input/@/test,staff@/-size@/.ly},
1758 @inputfileref{input/@/regression,staff@/-line@/-positions@/.ly}.
1761 @node Writing music in parallel
1762 @subsection Writing music in parallel
1764 @cindex Writing music in parallel
1765 @cindex Interleaved music
1767 Music for multiple parts can be interleaved
1769 @lilypond[quote,fragment,verbatim]
1770 \parallelMusic #'(voiceA voiceB) {
1771 r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] |
1773 r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] |
1777 \new Staff \new Voice \voiceA
1778 \new Staff \new Voice \voiceB
1784 @node Connecting notes
1785 @section Connecting notes
1787 This section deals with notation that affects groups of notes.
1793 * Laissez vibrer ties::
1806 A tie connects two adjacent note heads of the same pitch. The tie in
1807 effect extends the length of a note. Ties should not be confused with
1808 slurs, which indicate articulation, or phrasing slurs, which indicate
1809 musical phrasing. A tie is entered using the tilde symbol `@code{~}'
1811 @lilypond[quote,ragged-right,fragment,verbatim]
1812 e' ~ e' <c' e' g'> ~ <c' e' g'>
1815 When a tie is applied to a chord, all note heads whose pitches match
1816 are connected. When no note heads match, no ties will be created.
1818 A tie is just a way of extending a note duration, similar to the
1819 augmentation dot. The following example shows two ways of notating
1820 exactly the same concept
1822 @lilypond[quote,fragment,ragged-right]
1823 \time 3/4 c'2. c'2 ~ c'4
1827 Ties are used either when the note crosses a bar line, or when dots
1828 cannot be used to denote the rhythm. When using ties, larger note
1829 values should be aligned to subdivisions of the measure, such as
1831 @lilypond[fragment,quote,ragged-right]
1833 r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
1837 If you need to tie a lot of notes over bars, it may be easier to use
1838 automatic note splitting (see @ref{Automatic note splitting}). This
1839 mechanism automatically splits long notes, and ties them across bar
1842 When a second alternative of a repeat starts with a tied note, you
1843 have to repeat the tie. This can be achieved with @code{\repeatTie},
1845 @lilypond[fragment,quote,ragged-right,relative=2]
1849 @cindex repeating ties
1850 @cindex volta brackets and ties
1854 Ties are sometimes used to write out arpeggios. In this case, two tied
1855 notes need not be consecutive. This can be achieved by setting the
1856 @code{tieWaitForNote} property to true. The same feature is also useful,
1857 for example, to tie a tremolo to a chord. For example,
1859 @lilypond[fragment,verbatim,relative=1,ragged-right]
1860 \set tieWaitForNote = ##t
1861 \grace { c16[~ e~ g]~ } <c, e g>2
1862 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
1873 @funindex \tieNeutral
1875 @funindex \tieDotted
1877 @funindex \tieDashed
1885 In this manual: @ref{Automatic note splitting}.
1887 Program reference: @internalsref{Tie}.
1890 @inputfileref{input/@/regression,tie-arpeggio.ly}
1891 @inputfileref{input/@/regression,tie-manual.ly}
1898 Switching staves when a tie is active will not produce a slanted tie.
1906 A slur indicates that notes are to be played bound or
1907 @emph{legato}. They are entered using parentheses
1909 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1910 f( g a) a8 b( a4 g2 f4)
1914 The direction of a slur can be specified with
1915 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is
1916 either @code{Up}, @code{Down}, or @code{Neutral} (automatically
1919 However, there is a convenient shorthand for forcing slur
1920 directions. By adding @code{_} or @code{^} before the opening
1921 parentheses, the direction is also set. For example,
1923 @lilypond[relative=2,ragged-right,quote,verbatim,fragment]
1927 Only one slur can be printed at once. If you need to print a long
1928 slur over a few small slurs, please see @ref{Phrasing slurs}.
1933 Some composers write two slurs when they want legato chords. This can
1934 be achieved in LilyPond by setting @code{doubleSlurs},
1936 @lilypond[verbatim,ragged-right,relative,fragment,quote]
1937 \set doubleSlurs = ##t
1938 <c e>4 ( <d f> <c e> <d f> )
1948 @funindex \slurNeutral
1949 @code{\slurNeutral},
1950 @funindex \slurDashed
1952 @funindex \slurDotted
1954 @funindex \slurSolid
1959 Program reference: @seeinternals{Slur}.
1962 @node Phrasing slurs
1963 @subsection Phrasing slurs
1965 @cindex phrasing slurs
1966 @cindex phrasing marks
1968 A phrasing slur (or phrasing mark) connects notes and is used to
1969 indicate a musical sentence. It is written using @code{\(} and @code{\)}
1972 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
1973 \time 6/4 c'\( d( e) f( e) d\)
1976 Typographically, the phrasing slur behaves almost exactly like a
1977 normal slur. However, they are treated as different objects. A
1978 @code{\slurUp} will have no effect on a phrasing slur; instead, use
1979 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1980 @code{\phrasingSlurNeutral}.
1982 You cannot have simultaneous phrasing slurs.
1987 @funindex \phrasingSlurUp
1988 @code{\phrasingSlurUp},
1989 @funindex \phrasingSlurDown
1990 @code{\phrasingSlurDown},
1991 @funindex \phrasingSlurNeutral
1992 @code{\phrasingSlurNeutral}.
1997 Program reference: @internalsref{PhrasingSlur}.
2000 @node Laissez vibrer ties
2001 @subsection Laissez vibrer ties
2002 @cindex Laissez vibrer
2003 @cindex Ties, laissez vibrer
2005 L.v. ties (laissez vibrer) indicate that notes must not be damped at the
2006 end. It is used in notation for piano, harp and other string and
2007 percussion instruments. They can be entered using @code{\laissezVibrer},
2009 @lilypond[fragment,ragged-right,verbatim,relative=1]
2010 <c f g>\laissezVibrer
2016 @internalsref{LaissezVibrerTie}
2017 @internalsref{LaissezVibrerTieColumn}
2020 @inputfileref{input/regression,laissez-vibrer-tie.ly}
2023 @node Automatic beams
2024 @subsection Automatic beams
2026 LilyPond inserts beams automatically
2028 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2029 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
2032 When these automatic decisions are not good enough, beaming can be
2033 entered explicitly. It is also possible to define beaming patterns
2034 that differ from the defaults. See @ref{Setting automatic beam behavior}
2037 Individual notes may be marked with @code{\noBeam} to prevent them
2040 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2041 \time 2/4 c8 c\noBeam c c
2047 Program reference: @internalsref{Beam}.
2051 @subsection Manual beams
2053 @cindex beams, manual
2057 In some cases it may be necessary to override the automatic beaming
2058 algorithm. For example, the autobeamer will not put beams over rests
2059 or bar lines. Such beams are specified manually by marking the begin
2060 and end point with @code{[} and @code{]}
2062 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2064 r4 r8[ g' a r8] r8 g[ | a] r8
2071 @funindex stemLeftBeamCount
2072 @funindex stemRightBeamCount
2074 Normally, beaming patterns within a beam are determined automatically.
2075 If necessary, the properties @code{stemLeftBeamCount} and
2076 @code{stemRightBeamCount} can be used to override the defaults. If
2077 either property is set, its value will be used only once, and then it
2080 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2085 \set stemLeftBeamCount = #1
2090 The property @code{subdivideBeams} can be set in order to subdivide
2091 all 16th or shorter beams at beat positions, as defined by the
2092 @code{beatLength} property.
2094 @lilypond[fragment,quote,relative=2,verbatim]
2096 \set subdivideBeams = ##t
2098 \set Score.beatLength = #(ly:make-moment 1 8)
2101 @funindex subdivideBeams
2104 For more information about @code{make-moment}, see
2105 @ref{Time administration}.
2107 Line breaks are normally forbidden when beams cross bar lines. This
2108 behavior can be changed by setting @code{allowBeamBreak}.
2110 @funindex allowBeamBreak
2111 @cindex beams and line breaks
2112 @cindex beams, kneed
2114 @cindex auto-knee-gap
2119 Kneed beams are inserted automatically when a large gap is detected
2120 between the note heads. This behavior can be tuned through the object.
2122 Automatically kneed cross-staff beams cannot be used together with
2123 hidden staves. See @ref{Hiding staves}.
2125 Beams do not avoid collisions with symbols around the notes, such as
2126 texts and accidentals.
2130 @subsection Grace notes
2135 @cindex appoggiatura
2136 @cindex acciaccatura
2138 Grace notes are ornaments that are written out. The most common ones
2139 are acciaccatura, which should be played as very short. It is denoted
2140 by a slurred small note with a slashed stem. The appoggiatura is a
2141 grace note that takes a fixed fraction of the main note, and is
2142 denoted as a slurred note in small print without a slash. They
2143 are entered with the commands @code{\acciaccatura} and
2144 @code{\appoggiatura}, as demonstrated in the following example
2146 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2147 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
2148 \acciaccatura { g16[ f] } e4
2151 Both are special forms of the @code{\grace} command. By prefixing this
2152 keyword to a music expression, a new one is formed, which will be
2153 printed in a smaller font and takes up no logical time in a measure.
2155 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2157 \grace { c16[ d16] } c2 c4
2161 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
2162 @code{\grace} command does not start a slur.
2164 Internally, timing for grace notes is done using a second, `grace'
2165 timing. Every point in time consists of two rational numbers: one
2166 denotes the logical time, one denotes the grace timing. The above
2167 example is shown here with timing tuples
2169 @lilypond[quote,ragged-right]
2172 c4 \grace c16 c4 \grace {
2175 \new Lyrics \lyricmode {
2176 \override LyricText #'font-family = #'typewriter
2180 ( \fraction 1 4 , \fraction -1 16 ) } 16 }
2181 \markup { (\fraction 1 4 , 0 ) } 4
2183 \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
2184 \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
2186 \markup { ( \fraction 2 4 , 0 ) }
2191 The placement of grace notes is synchronized between different staves.
2192 In the following example, there are two sixteenth grace notes for
2193 every eighth grace note
2195 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2196 << \new Staff { e4 \grace { c16[ d e f] } e4 }
2197 \new Staff { c4 \grace { g8[ b] } c4 } >>
2200 @funindex \afterGrace
2202 If you want to end a note with a grace, use the @code{\afterGrace}
2203 command. It takes two arguments: the main note, and the grace notes
2204 following the main note.
2206 @lilypond[ragged-right, verbatim,relative=2,fragment]
2207 c1 \afterGrace d1 { c16[ d] } c4
2210 This will put the grace notes after a ``space'' lasting 3/4 of the
2211 length of the main note. The fraction 3/4 can be changed by setting
2212 @code{afterGraceFraction}, ie.
2215 afterGraceFraction = #(cons 7 8)
2219 will put the grace note at 7/8 of the main note.
2221 The same effect can be achieved manually by doing
2223 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2226 { s2 \grace { c16[ d] } } >>
2232 By adjusting the duration of the skip note (here it is a half-note),
2233 the space between the main-note and the grace is adjusted.
2235 A @code{\grace} section will introduce special typesetting settings,
2236 for example, to produce smaller type, and set directions. Hence, when
2237 introducing layout tweaks, they should be inside the grace section,
2239 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2251 The overrides should also be reverted inside the grace section.
2253 The layout of grace sections can be changed throughout the music using
2254 the function @code{add-grace-property}. The following example
2255 undefines the Stem direction for this grace, so stems do not always
2260 #(add-grace-property 'Voice 'Stem 'direction '())
2266 Another option is to change the variables @code{startGraceMusic},
2267 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
2268 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
2269 @code{stopAppoggiaturaMusic}. More information is in the file
2270 @file{ly/@/grace@/-init@/.ly}.
2273 The slash through the stem in acciaccaturas can be obtained
2274 in other situations by @code{\override Stem #'stroke-style = #"grace"}.
2278 Program reference: @internalsref{GraceMusic}.
2283 A score that starts with a @code{\grace} section needs an explicit
2284 @code{\new Voice} declaration, otherwise the main note and the grace
2285 note end up on different staves.
2287 Grace note synchronization can also lead to surprises. Staff notation,
2288 such as key signatures, bar lines, etc., are also synchronized. Take
2289 care when you mix staves with grace notes and staves without, for example,
2291 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
2292 << \new Staff { e4 \bar "|:" \grace c16 d4 }
2293 \new Staff { c4 \bar "|:" d4 } >>
2297 This can be remedied by inserting grace skips of the corresponding
2298 durations in the other staves. For the above example
2301 \new Staff @{ c4 \bar "|:" \grace s16 d4 @}
2304 Grace sections should only be used within sequential music
2305 expressions. Nesting or juxtaposing grace sections is not supported,
2306 and might produce crashes or other errors.
2310 @node Expressive marks
2311 @section Expressive marks
2313 Expressive marks help musicians to bring more to the music than simple
2318 * Fingering instructions::
2328 @subsection Articulations
2330 @cindex Articulations
2334 A variety of symbols can appear above and below notes to indicate
2335 different characteristics of the performance. They are added to a note
2336 by adding a dash and the character signifying the
2337 articulation. They are demonstrated here
2339 @lilypondfile[quote,ragged-right]{script-abbreviations.ly}
2341 The meanings of these shorthands can be changed. See
2342 @file{ly/@/script@/-init@/.ly} for examples.
2344 The script is automatically placed, but the direction can be forced as
2345 well. Like other pieces of LilyPond code, @code{_} will place them
2346 below the staff, and @code{^} will place them above.
2348 @lilypond[quote,ragged-right,fragment,verbatim]
2352 Other symbols can be added using the syntax
2353 @var{note}@code{\}@var{name}. Again, they
2354 can be forced up or down using @code{^} and @code{_},
2357 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
2358 c\fermata c^\fermata c_\fermata
2363 @cindex staccatissimo
2373 @cindex organ pedal marks
2382 @cindex prallmordent
2386 @cindex thumb marking
2391 Here is a chart showing all scripts available,
2393 @lilypondfile[ragged-right,quote]{script-chart.ly}
2398 The vertical ordering of scripts is controlled with the
2399 @code{script-priority} property. The lower this number, the closer it
2400 will be put to the note. In this example, the
2401 @internalsref{TextScript} (the sharp symbol) first has the lowest
2402 priority, so it is put lowest in the first example. In the second, the
2403 prall trill (the @internalsref{Script}) has the lowest, so it is on the
2404 inside. When two objects have the same priority, the order in which
2405 they are entered decides which one comes first.
2407 @lilypond[verbatim,relative=3,ragged-right,fragment,quote]
2408 \once \override TextScript #'script-priority = #-100
2409 a4^\prall^\markup { \sharp }
2411 \once \override Script #'script-priority = #-100
2412 a4^\prall^\markup { \sharp }
2418 Program reference: @internalsref{Script}.
2423 These signs appear in the printed output but have no effect on the
2424 MIDI rendering of the music.
2427 @node Fingering instructions
2428 @subsection Fingering instructions
2431 @cindex finger change
2433 Fingering instructions can be entered using
2435 @var{note}-@var{digit}
2437 For finger changes, use markup texts
2439 @lilypond[quote,verbatim,ragged-right,fragment,relative=1]
2441 c^\markup { \finger "2 - 3" }
2444 You can use the thumb-script to indicate that a note should be
2445 played with the thumb (e.g., in cello music)
2446 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2447 <a_\thumb a'-3>8 <b_\thumb b'-3>
2450 Fingerings for chords can also be added to individual notes
2451 of the chord by adding them after the pitches
2452 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2453 < c-1 e-2 g-3 b-5 >4
2459 You may exercise greater control over fingering chords by
2460 setting @code{fingeringOrientations}
2462 @lilypond[quote,verbatim,ragged-right,fragment,relative=1]
2463 \set fingeringOrientations = #'(left down)
2464 <c-1 es-2 g-4 bes-5 > 4
2465 \set fingeringOrientations = #'(up right down)
2466 <c-1 es-2 g-4 bes-5 > 4
2469 Using this feature, it is also possible to put fingering instructions
2470 very close to note heads in monophonic music,
2472 @lilypond[verbatim,ragged-right,quote,fragment]
2473 \set fingeringOrientations = #'(right)
2480 Program reference: @internalsref{Fingering}.
2482 Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
2486 @subsection Dynamics
2507 Absolute dynamic marks are specified using a command after a note
2508 @code{c4\ff}. The available dynamic marks are @code{\ppppp},
2509 @code{\pppp}, @code{\ppp},
2510 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2511 @code{\fff}, @code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff},
2512 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
2514 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
2515 c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2516 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
2523 A crescendo mark is started with @code{\<} and terminated with
2524 @code{\!} or an absolute dynamic. A decrescendo is started with
2525 @code{\>} and is also terminated with @code{\!} or an absolute
2526 dynamic. @code{\cr} and @code{\decr} may be used instead of
2527 @code{\<} and @code{\>}. Because these marks are bound to notes, you must
2528 use spacer notes if multiple marks are needed during one note
2530 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2532 << f1 { s4 s4\< s4\! \> s4\! } >>
2536 A hairpin starts at the left edge of the beginning note and ends on the
2537 right edge of the ending note.
2539 In some situations the @code{\espressivo} articulation mark may
2540 be suitable to indicate a crescendo and decrescendo on the one note,
2542 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2543 c2 b4 a g1\espressivo
2546 This may give rise to very short hairpins. Use @code{minimum-length}
2547 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2551 \override Staff.Hairpin #'minimum-length = #5
2558 You can also use a text saying @emph{cresc.} instead of hairpins
2560 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2571 You can also supply your own texts
2572 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2573 \set crescendoText = \markup { \italic "cresc. poco" }
2574 \set crescendoSpanner = #'dashed-line
2578 To create new dynamic marks or text that should be aligned
2579 with dynamics, see @ref{New dynamic marks}.
2584 Dynamics that occur at, begin on, or end on, the same note
2585 will be vertically aligned. If you want to ensure that dynamics
2586 are aligned when they do not occur on the same note, you can
2587 increase the @code{staff-padding} property.
2590 \override DynamicLineSpanner #'staff-padding = #4
2593 You may also use this property if the dynamics are colliding
2594 with other notation.
2596 Crescendi and decrescendi that end on the first note of a
2597 new line are not printed. To change this behavior, use
2600 \override Score.Hairpin #'after-line-breaking = ##t
2603 Text style dynamic changes (such as cresc. and dim.) are printed with a
2604 dashed line showing their extent. To surpress printing this line, use
2607 \override DynamicTextSpanner #'dash-period = #-1.0
2613 @funindex \dynamicUp
2615 @funindex \dynamicDown
2616 @code{\dynamicDown},
2617 @funindex \dynamicNeutral
2618 @code{\dynamicNeutral}.
2623 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
2624 Vertical positioning of these symbols is handled by
2625 @internalsref{DynamicLineSpanner}.
2629 @subsection Breath marks
2631 Breath marks are entered using @code{\breathe}
2633 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2640 The glyph of the breath mark can be tuned by overriding the
2641 @code{text} property of the @code{BreathingSign} layout object with
2642 any markup text. For example,
2643 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
2645 \override BreathingSign #'text
2646 = #(make-musicglyph-markup "scripts.rvarcomma")
2653 Program reference: @internalsref{BreathingSign}.
2655 Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
2661 Short trills are printed like normal articulation; see @ref{Articulations}.
2663 Long running trills are made with @code{\startTrillSpan} and
2664 @code{\stopTrillSpan},
2666 @lilypond[verbatim,ragged-right,relative=2,quote,fragment]
2668 << { c1 \startTrillSpan }
2669 { s2. \grace { d16[\stopTrillSpan e] } } >>
2673 @cindex Pitched trills
2675 Trills that should be executed on an explicitly specified pitch can be
2676 typeset with the command @code{pitchedTrill},
2678 @lilypond[ragged-right,verbatim,fragment,relative=1]
2679 \pitchedTrill c4\startTrillSpan fis
2683 The first argument is the main note. The pitch of the second
2684 is printed as a stemless note head in parentheses.
2689 @code{\startTrillSpan},
2690 @funindex \startTrillSpan
2691 @code{\stopTrillSpan}.
2692 @funindex \stopTrillSpan
2697 Program reference: @internalsref{TrillSpanner}.
2701 @subsection Glissando
2704 @funindex \glissando
2706 A glissando is a smooth change in pitch. It is denoted by a line or a
2707 wavy line between two notes. It is requested by attaching
2708 @code{\glissando} to a note
2710 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2712 \override Glissando #'style = #'zigzag
2719 Program reference: @internalsref{Glissando}.
2721 Example files: @file{input/@/regression/@/glissando@/.ly}.
2726 Printing text over the line (such as @emph{gliss.}) is not supported.
2730 @subsection Arpeggio
2733 @cindex broken chord
2736 You can specify an arpeggio sign (also known as broken chord) on a
2737 chord by attaching an @code{\arpeggio} to a chord
2739 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2743 A square bracket on the left indicates that the player should not
2744 arpeggiate the chord
2746 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2751 The direction of the arpeggio is sometimes denoted by adding an
2752 arrowhead to the wiggly line
2754 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2766 When an arpeggio crosses staves, you may attach an arpeggio to the chords
2767 in both staves and set
2768 @internalsref{PianoStaff}.@code{connectArpeggios}
2770 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
2772 \set PianoStaff.connectArpeggios = ##t
2773 \new Staff { <c' e g c>\arpeggio }
2774 \new Staff { \clef bass <c,, e g>\arpeggio }
2782 @funindex \arpeggioUp
2784 @funindex \arpeggioDown
2785 @code{\arpeggioDown},
2786 @funindex \arpeggioNeutral
2787 @code{\arpeggioNeutral},
2788 @funindex \arpeggioBracket
2789 @code{\arpeggioBracket}.
2794 Notation manual: @ref{Ties}, for writing out arpeggios.
2796 Program reference: @internalsref{Arpeggio}.
2801 It is not possible to mix connected arpeggios and unconnected
2802 arpeggios in one @internalsref{PianoStaff} at the same point in time.
2811 Repetition is a central concept in music, and multiple notations exist
2817 * Repeats and MIDI::
2818 * Manual repeat commands::
2820 * Tremolo subdivisions::
2826 @subsection Repeat types
2831 The following types of repetition are supported
2835 Repeated music is fully written (played) out. This is useful when
2836 entering repetitious music. This is the only kind of repeat that
2837 is included in MIDI output.
2840 Repeats are not written out, but alternative endings (volte) are
2841 printed, left to right with brackets. This is the standard notation
2842 for repeats with alternatives. These are not played in MIDI output by
2847 Alternative endings are written stacked. This has limited use but may be
2848 used to typeset two lines of lyrics in songs with repeats, see
2849 @inputfileref{input,star-spangled-banner@/.ly}.
2853 Make tremolo beams. These are not played in MIDI output by default.
2856 Make beat or measure repeats. These look like percent signs. These
2857 are not played in MIDI output by default. Percent repeats must be
2858 declared within a Voice context.
2864 @subsection Repeat syntax
2866 LilyPond has one syntactic construct for specifying different types of
2867 repeats. The syntax is
2870 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2873 If you have alternative endings, you may add
2874 @funindex \alternative
2885 where each @var{alternative} is a music expression. If you do not
2886 give enough alternatives for all of the repeats, the first alternative
2887 is assumed to be played more than once.
2889 Standard repeats are used like this
2890 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2892 \repeat volta 2 { c4 d e f }
2893 \repeat volta 2 { f e d c }
2896 With alternative endings
2897 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2899 \repeat volta 2 {c4 d e f}
2900 \alternative { {d2 d} {f f,} }
2903 In this example, the first ending is not a complete bar (it
2904 only had 3 beats). The beginning of the second ending
2905 contains the 4th beat from the first ending. This ``extra''
2906 beat in the second ending is due to the first time ending,
2907 and has nothing to do with the @code{\partial} at the
2908 beginning of the example.
2910 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
2913 \repeat volta 4 { e | c2 d2 | e2 f2 | }
2914 \alternative { { g4 g g } { a | a a a a | b2. } }
2918 It is possible to shorten volta brackets
2919 by setting @code{voltaSpannerDuration}. In the next example, the
2920 bracket only lasts one measure, which is a duration of 3/4.
2922 @lilypond[verbatim,ragged-right,quote]
2926 \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2927 \repeat "volta" 5 { d d d }
2928 \alternative { { e e e f f f }
2938 Brackets for the repeat are normally only printed over the topmost
2939 staff. This can be adjusted by setting the @code{voltaOnThisStaff}
2940 property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
2945 @cindex repeat, ambiguous
2947 A nested repeat like
2956 is ambiguous, since it is is not clear to which @code{\repeat} the
2957 @code{\alternative} belongs. This ambiguity is resolved by always
2958 having the @code{\alternative} belong to the inner @code{\repeat}.
2959 For clarity, it is advisable to use braces in such situations.
2961 Timing information is not remembered at the start of an alternative,
2962 so after a repeat timing information must be reset by hand, for
2963 example by setting @code{Score.measurePosition} or entering
2964 @code{\partial}. Similarly, slurs or ties are also not repeated.
2967 @node Repeats and MIDI
2968 @subsection Repeats and MIDI
2970 @cindex expanding repeats
2971 @funindex \unfoldRepeats
2973 With a little bit of tweaking, all types of repeats can be present
2974 in the MIDI output. This is achieved by applying the
2975 @code{\unfoldRepeats} music function. This functions changes all
2976 repeats to unfold repeats.
2978 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
2980 \repeat tremolo 8 {c'32 e' }
2981 \repeat percent 2 { c''8 d'' }
2982 \repeat volta 2 {c'4 d' e' f'}
2991 When creating a score file using @code{\unfoldRepeats} for midi, then
2992 it is necessary to make two @code{\score} blocks. One for MIDI (with
2993 unfolded repeats) and one for notation (with volta, tremolo, and
2994 percent repeats). For example,
3002 \unfoldRepeats @var{..music..}
3008 @node Manual repeat commands
3009 @subsection Manual repeat commands
3011 @funindex repeatCommands
3013 The property @code{repeatCommands} can be used to control the layout of
3014 repeats. Its value is a Scheme list of repeat commands.
3017 @item @code{start-repeat}
3018 Print a @code{|:} bar line.
3020 @item @code{end-repeat}
3021 Print a @code{:|} bar line.
3023 @item @code{(volta @var{text})}
3024 Print a volta bracket saying @var{text}: The text can be specified as
3025 a text string or as a markup text, see @ref{Text markup}. Do not
3026 forget to change the font, as the default number font does not contain
3027 alphabetic characters;
3029 @item @code{(volta #f)}
3030 Stop a running volta bracket.
3033 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
3035 \set Score.repeatCommands = #'((volta "93") end-repeat)
3037 \set Score.repeatCommands = #'((volta #f))
3044 Program reference: @internalsref{VoltaBracket},
3045 @internalsref{RepeatedMusic},
3046 @internalsref{VoltaRepeatedMusic},
3047 @internalsref{UnfoldedRepeatedMusic}, and
3048 @internalsref{FoldedRepeatedMusic}.
3051 @node Tremolo repeats
3052 @subsection Tremolo repeats
3054 @cindex tremolo beams
3056 To place tremolo marks between notes, use @code{\repeat} with tremolo
3058 @lilypond[quote,verbatim,ragged-right]
3059 \new Voice \relative c' {
3060 \repeat "tremolo" 8 { c16 d16 }
3061 \repeat "tremolo" 4 { c16 d16 }
3062 \repeat "tremolo" 2 { c16 d16 }
3066 Tremolo marks can also be put on a single note. In this case, the
3067 note should not be surrounded by braces.
3068 @lilypond[quote,verbatim,ragged-right]
3069 \repeat "tremolo" 4 c'16
3072 Similar output is obtained using the tremolo subdivision, described in
3073 @ref{Tremolo subdivisions}.
3078 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
3080 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
3082 Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
3083 @inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
3086 @node Tremolo subdivisions
3087 @subsection Tremolo subdivisions
3089 @cindex tremolo marks
3090 @funindex tremoloFlags
3092 Tremolo marks can be printed on a single note by adding
3093 `@code{:}[@var{number}]' after the note. The number indicates the
3094 duration of the subdivision, and it must be at least 8. A
3095 @var{length} value of 8 gives one line across the note stem. If the
3096 length is omitted, the last value (stored in @code{tremoloFlags}) is
3099 @lilypond[quote,ragged-right,verbatim,fragment]
3100 c'2:8 c':32 | c': c': |
3106 Tremolos entered in this way do not carry over into the MIDI output.
3111 In this manual: @ref{Tremolo repeats}.
3113 Elsewhere: @internalsref{StemTremolo}.
3116 @node Measure repeats
3117 @subsection Measure repeats
3119 @cindex percent repeats
3120 @cindex measure repeats
3122 In the @code{percent} style, a note pattern can be repeated. It is
3123 printed once, and then the pattern is replaced with a special sign.
3124 Patterns of one and two measures are replaced by percent-like signs,
3125 patterns that divide the measure length are replaced by slashes.
3126 Percent repeats must be declared within a @code{Voice} context.
3128 @lilypond[quote,verbatim,ragged-right]
3129 \new Voice \relative c' {
3130 \repeat "percent" 4 { c4 }
3131 \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
3135 Measure repeats of more than 2 measures get a counter, if you switch
3136 on the @code{countPercentRepeats} property,
3138 @lilypond[relative=2,fragment,quote,verbatim,ragged-right]
3140 \set countPercentRepeats = ##t
3141 \repeat "percent" 4 { c1 }
3147 Isolated percents can also be printed. This is done by putting a multi
3148 measure rest with a different print function,
3150 @lilypond[fragment,verbatim]
3151 \override MultiMeasureRest #'stencil
3152 = #ly:multi-measure-rest::percent
3161 Program reference: @internalsref{RepeatSlash},
3162 @internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
3163 @internalsref{DoublePercentRepeatCounter},
3164 @internalsref{PercentRepeatCounter},
3165 @internalsref{PercentRepeatedMusic}.