3 @c A menu is needed before every deeper *section nesting of @node's; run
4 @c M-x texinfo-all-menus-update
5 @c to automagically fill in these menus before saving changes
7 @c FIXME: singular vs. plural: Beams/Beam
10 @node Reference Manual
11 @chapter Reference Manual
14 <!--- @@WEB-TITLE@@=Reference Manual --->
18 This document describes GNU LilyPond and its input format. The last
19 revision of this document was made for LilyPond 1.7.10. It assumes
20 that you already know a little bit about LilyPond input (how to
21 make an input file, how to create sheet music from that input file,
22 etc). New users are encouraged to study the tutorial before reading
27 * Easier music entry::
42 * Contemporary notation::
48 @c FIXME: Note entry vs Music entry at top level menu is confusing.
54 Notes constitute the most basic elements of LilyPond input, but they do
55 not form valid input on their own without a @code{\score} block. However,
56 for the sake of brevity and simplicity we will generally omit
57 @code{\score} blocks and @code{\paper} declarations in this manual.
63 * Chromatic alterations::
68 * Automatic note splitting ::
70 * Easy Notation note heads ::
78 A note is printed by specifying its pitch and then its duration.
79 @lilypond[fragment,verbatim]
88 @cindex Note specification
90 @cindex entering notes
92 The verbose syntax for pitch specification is
99 where @var{scmpitch} is a pitch scheme object.
101 In Note and Chord mode, pitches may be designated by names. The
102 default names are the Dutch note names. The notes are specified by
103 the letters @code{a} through @code{g}, while the octave is formed with
104 notes ranging from @code{c} to @code{b}. The pitch @code{c} is an
105 octave below middle C and the letters span the octave above that C.
107 @lilypond[fragment,verbatim]
109 a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c''
112 @cindex note names, Dutch
114 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
115 name and a flat is formed by adding @code{-es}. Double sharps and
116 double flats are obtained by adding @code{-isis} or @code{-eses}.
117 @code{aes} is contracted to @code{as} in Dutch, but both forms are
118 accepted. Similarly, both @code{es} and @code{ees} are accepted.
120 There are predefined sets of note names for various other languages.
121 To use them, include the language specific init file. For
122 example: @code{\include "english.ly"}. The available language files
123 and the note names they define are:
128 Note Names sharp flat
129 nederlands.ly c d e f g a bes b -is -es
130 english.ly c d e f g a bf b -s/-sharp -f/-flat
131 deutsch.ly c d e f g a b h -is -es
132 norsk.ly c d e f g a b h -iss/-is -ess/-es
133 svenska.ly c d e f g a b h -iss -ess
134 italiano.ly do re mi fa sol la sib si -d -b
135 catalan.ly do re mi fa sol la sib si -d/-s -b
136 espanol.ly do re mi fa sol la sib si -s -b
145 The optional octave specification takes the form of a series of
146 single quote (`@code{'}') characters or a series of comma
147 (`@code{,}') characters. Each @code{'} raises the pitch by one
148 octave; each @code{,} lowers the pitch by an octave.
150 @lilypond[fragment,verbatim,center]
151 c' c'' es' g' as' gisis' ais'
154 @node Chromatic alterations
155 @subsection Chromatic alterations
157 Normally accidentals are printed automatically, but you may also
158 print them manually. A reminder accidental
159 @cindex reminder accidental
161 can be forced by adding an exclamation mark @code{!}
162 after the pitch. A cautionary accidental
163 @cindex cautionary accidental
164 @cindex parenthesized accidental
165 (an accidental within parentheses) can be obtained by adding the
166 question mark `@code{?}' after the pitch.
168 @lilypond[fragment,verbatim]
169 cis' cis' cis'! cis'?
173 The automatic production of accidentals can be tuned in many
174 ways. For more information, refer to @ref{Accidentals}.
181 Rests are entered like notes, with the note name @code{r}.
183 @lilypond[singleline,verbatim]
187 Whole bar rests, centered in middle of the bar, are specified using
188 @code{R} (capital R); see @ref{Multi measure rests}. See also
191 For some music, you may wish to explicitly specify the rest's vertical
192 position. This can be achieved by entering a note with the @code{\rest}
193 keyword appended. Rest collision testing will leave these rests alone.
195 @lilypond[singleline,verbatim]
205 @cindex Invisible rest
208 An invisible rest (also called a `skip') can be entered like a note
209 with note name `@code{s}' or with @code{\skip @var{duration}}:
211 @lilypond[singleline,verbatim]
215 The @code{s} syntax is only available in Note mode and Chord
216 mode. In other situations, you should use the @code{\skip} command,
217 which will work outside of those two modes:
219 @lilypond[singleline,verbatim]
222 { \time 4/8 \skip 2 \time 4/4 }
223 \notes\relative c'' { a2 a1 }
228 The skip command is merely an empty musical placeholder. It does not
229 produce any output, not even transparent output.
235 @subsection Durations
239 @cindex @code{\duration}
242 In Note, Chord, and Lyrics mode, durations are designated by numbers
243 and dots: durations are entered as their reciprocal values. For example,
244 a quarter note is entered using a @code{4} (since it is a 1/4 note), while
245 a half note is entered using a @code{2} (since it is a 1/2 note). For notes
246 longer than a whole you must use identifiers.
247 @c FIXME: what is an identifier? I do not think it's been introduced yet.
248 @c and if it has, I obviously skipped that part. - Graham
252 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
254 r1 r2 r4 r8 r16 r32 r64 r64
259 \notes \relative c'' {
261 a1 a2 a4 a8 a16 a32 a64 a64
263 r1 r2 r4 r8 r16 r32 r64 r64
268 \remove "Clef_engraver"
269 \remove "Staff_symbol_engraver"
270 \remove "Time_signature_engraver"
271 \consists "Pitch_squash_engraver"
278 If the duration is omitted then it is set to the previously entered
279 duration. Default for the first note is a quarter note. The duration
280 can be followed by dots (`@code{.}') in order to obtain dotted note
284 @lilypond[fragment,verbatim,center]
285 a' b' c''8 b' a'4 a'4. b'4.. c'8.
290 You can alter the length of duration by a fraction @var{N/M}
291 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
292 will not affect the appearance of the notes or rests produced.
294 @lilypond[fragment,verbatim]
295 a'2*2 b'4*2 a'8*4 a'4*3/2 gis'4*3/2 a'4*3/2 a'4
298 Durations can also be produced through GUILE extension mechanism.
299 @lilypond[verbatim,fragment]
300 c'\duration #(ly:make-duration 2 1)
306 Dot placement for chords is not perfect. In some cases, dots overlap:
319 A tie connects two adjacent note heads of the same pitch. The tie in
320 effect extends the length of a note. Ties should not be confused with
321 slurs, which indicate articulation, or phrasing slurs, which indicate
322 musical phrasing. A tie is entered using the tilde symbol `@code{~}'.
324 @lilypond[fragment,verbatim,center]
325 e' ~ e' <<c' e' g'>> ~ <<c' e' g'>>
328 When a tie is applied to a chord, all note heads (whose pitches match) are
329 connected. If you try to tie together chords that have no common pitches,
330 no ties will be created.
332 In its meaning a tie is just a way of extending a note duration, similar
333 to the augmentation dot: the following example are two ways of notating
334 exactly the same concept.
336 @lilypond[fragment, singleline,quote]
337 \time 3/4 c'2. c'2 ~ c'4
339 If you need to tie notes over bars, it may be easier to use automatic
340 note splitting (See @ref{Automatic note splitting}).
345 @seeinternals{Tie}, @ref{Automatic note splitting}. If you want less
346 ties created for a chord, see @inputfileref{input/test/,tie-sparse.ly}.
350 Tieing only a subset of the note heads of a pair of chords is not
351 supported in a simple way. It can be achieved by moving the
352 tie-engraver into the @internalsref{Thread} context and turning on and
353 off ties per @internalsref{Thread}.
355 Switching staves when a tie is active, will produce a horizontal tie
359 Formatting of ties is a difficult subject. LilyPond often does not
360 give optimal results.
364 @node Automatic note splitting
365 @subsection Automatic note splitting
366 @c FIXME: This subsection does not belong in @ref{Note entry}.
368 LilyPond can automatically converting long notes to tied notes. This
369 is done by replacing the @code{Note_heads_engraver} by the
370 @code{Completion_heads_engraver}.
372 @lilypond[verbatim,noindent]
374 \notes\relative c'{ \time 2/4
375 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
379 \remove "Note_heads_engraver"
380 \consists "Completion_heads_engraver"
384 This engraver splits all running notes at the bar line, and inserts
385 ties. One of its uses is to debug complex scores: if the measures are
386 not entirely filled, then the ties exactly show how much each measure
391 Not all durations (especially those containing tuplets) can be
392 represented exactly; the engraver will not insert tuplets.
399 @cindex @code{\times}
401 Tuplets are made out of a music expression by multiplying all durations
404 @cindex @code{\times}
406 \times @var{fraction} @var{musicexpr}
409 The duration of @var{musicexpr} will be multiplied by the fraction.
410 In the sheet music, the fraction's denominator will be printed over
411 the notes, optionally with a bracket. The most common tuplet is the
412 triplet in which 3 notes have the length of 2, so the notes are 2/3
413 of their written length:
415 @lilypond[fragment,verbatim,center]
416 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
419 The property @code{tupletSpannerDuration} specifies how long each bracket
420 should last. With this, you can make lots of tuplets while typing
421 @code{\times} only once, saving you lots of typing.
423 @lilypond[fragment, relative, singleline, verbatim]
424 \property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
425 \times 2/3 { c'8 c c c c c }
428 The format of the number is determined by the property
429 @code{tupletNumberFormatFunction}. The default prints only the
430 denominator, but if you set it to the Scheme function
431 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
435 @cindex @code{tupletNumberFormatFunction}
436 @cindex tuplet formatting
438 See also @seeinternals{TupletBracket}.
442 Nested tuplets are not formatted automatically. In this case, outer
443 tuplet brackets should be moved manually.
445 @node Easy Notation note heads
446 @subsection Easy Notation note heads
448 @cindex easy notation
451 The "easyplay" note head includes a note name inside the head. It is
452 used in music aimed at beginners.
454 @lilypond[singleline,verbatim,26pt]
456 \notes { c'2 e'4 f' | g'1 }
457 \paper { \translator { \EasyNotation } }
461 The @code{EasyNotation} identifier overrides a @internalsref{Score}
462 context. You probably will want to print it with magnification or a
463 large font size to make it more readable. To print with
464 magnification, you must create a DVI file (with @file{ly2dvi}) and
465 then enlarge it with something like @file{dvips -x 2000 file.dvi}.
466 See @file{man dvips} for details. To print with a larger font, see
473 If you view the result with Xdvi, then staff lines will show through
474 the letters. Printing the PostScript file obtained with ly2dvi does
475 produce the correct result.
478 @node Easier music entry
479 @section Easier music entry
484 * Skipping corrected music::
487 When entering music with LilyPond, it is easy to introduce
488 errors. This section deals with tricks and features that help you
489 enter music, and find and correct mistakes. It is also possible to
490 use external programs to enter or edit music. Refer to the website for
495 @node Relative octaves
496 @subsection Relative octaves
498 @cindex relative octave specification
500 Octaves are specified by adding @code{'} and @code{,} to pitch names.
501 When you copy existing music, it is easy to accidentally put a pitch in
502 the wrong octave and hard to find such an error. To prevent these
503 errors, LilyPond features octave entry.
505 @cindex @code{\relative}
507 \relative @var{startpitch} @var{musicexpr}
510 The octave of notes that appear in @var{musicexpr} are calculated as
511 follows: If no octave changing marks are used, the basic interval
512 between this and the last note is always taken to be a fourth or less
513 (This distance is determined without regarding alterations; a
514 @code{fisis} following a @code{ceses} will be put above the
517 The octave changing marks @code{'} and @code{,} can be added to raise or
518 lower the pitch by an extra octave. Upon entering relative mode, an
519 absolute starting pitch must be specified that will act as the
520 predecessor of the first note of @var{musicexpr}.
522 Entering music that changes octave frequently is easy in relative mode.
523 @lilypond[fragment,singleline,verbatim,center]
529 And octave changing marks are used for intervals greater than a fourth.
530 @lilypond[fragment,verbatim,center]
535 If the preceding item is a chord, the first note of the chord is used
536 to determine the first note of the next chord. However, other notes
537 within the second chord are determined by looking at the immediately
540 @lilypond[fragment,verbatim,center]
547 @cindex @code{\notes}
549 The pitch after the @code{\relative} contains a note name. To parse
550 the pitch as a note name, you have to be in note mode, so there must
551 be a surrounding @code{\notes} keyword (which is not
554 The relative conversion will not affect @code{\transpose},
555 @code{\chords} or @code{\relative} sections in its argument. If you
556 want to use relative within transposed music, you must place an
557 additional @code{\relative} inside the @code{\transpose}.
561 @subsection Bar check
565 @cindex @code{barCheckSynchronize}
569 Whenever a bar check is encountered during interpretation, a warning
570 message is issued if it does not fall at a measure boundary. This can
571 help you find errors in the input. Depending on the value of
572 @code{barCheckSynchronize}, the beginning of the measure will be
573 relocated, so this can also be used to shorten measures.
575 A bar check is entered using the bar symbol, `@code{|}'.
577 \time 3/4 c2 e4 | g2.
582 @cindex skipTypesetting
584 Failed bar checks are caused by entering incorrect
585 durations. Incorrect durations often completely garble up the score,
586 especially if it is polyphonic, so you should start correcting the
587 score by scanning for failed bar checks and incorrect durations. To
588 speed up this process, you can use @code{skipTypesetting}, described
591 @node Skipping corrected music
592 @subsection Skipping corrected music
594 The property @code{Score.skipTypesetting} can be used to switch on and
595 off typesetting completely during the interpretation phase. When
596 typesetting is switched off, the music is processed much more quickly.
597 You can use this to skip over the parts of a score that you have already
600 @lilypond[fragment,singleline,verbatim]
602 \property Score.skipTypesetting = ##t
604 \property Score.skipTypesetting = ##f
612 @section Staff notation
614 This section deals with music notation that occurs on staff level,
615 such as keys, clefs and time signatures.
617 @cindex Staff notation
629 @subsection Staff symbol
631 @cindex adjusting staff symbol
632 @cindex StaffSymbol, using \property
633 @cindex staff lines, setting number of
635 Staff is a the general name for Notes, dynamic signs, etc. are grouped
636 with a set of horizontal lines, into a staff (plural `staves'). In our
637 system, these lines are drawn using a separate graphical object called
640 This object is created whenever a @internalsref{Staff} context is
641 created. You can not change the appearance of the staff symbol by
642 using @code{\override} or @code{\set}. At the moment that
643 @code{\property Staff} is interpreted, a Staff context is made, and
644 the @internalsref{StaffSymbol} is created before any @code{\override} is
645 effective. You can deal with this either overriding properties in a
646 @code{\translator} definition, or by using @code{\outputproperty}.
650 If you end a staff halfway a piece, the staff symbol may not end
651 exactly on the barline.
655 @subsection Key signature
660 The key signature indicates the scale in which a piece is played. It
661 is denoted by a set of alterations (flats or sharps) at the start of
666 Setting or changing the key signature is done with the @code{\key}
669 @code{\key} @var{pitch} @var{type}
672 @cindex @code{\minor}
673 @cindex @code{\major}
674 @cindex @code{\minor}
675 @cindex @code{\ionian}
676 @cindex @code{\locrian}
677 @cindex @code{\aeolian}
678 @cindex @code{\mixolydian}
679 @cindex @code{\lydian}
680 @cindex @code{\phrygian}
681 @cindex @code{\dorian}
683 Here, @var{type} should be @code{\major} or @code{\minor} to get
684 @var{pitch}-major or @var{pitch}-minor, respectively.
685 The standard mode names @code{\ionian},
686 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
687 @code{\phrygian}, and @code{\dorian} are also defined.
691 This command sets the context property
692 @internalsref{Staff}.@code{keySignature}. Non-standard key signatures
693 can be specified by setting this property directly.
695 The printed signature is a @internalsref{KeySignature} object, typically
696 created in @internalsref{Staff} context.
698 @cindex @code{keySignature}
705 The clef indicates which lines of the staff correspond to which
710 The clef can be set or changed with the @code{\clef} command:
711 @lilypond[fragment,verbatim]
712 \key f\major c''2 \clef alto g'2
715 Supported clef-names include
716 @c Moved standard clefs to the top /MB
718 @item treble, violin, G, G2
727 G clef on 1st line, so-called French violin clef
742 By adding @code{_8} or @code{^8} to the clef name, the clef is
743 transposed one octave down or up, respectively. You have to
744 enclose @var{clefname} in quotes if you use underscores or digits in the
750 This command is equivalent to setting @code{clefGlyph},
751 @code{clefPosition} (which controls the Y position of the clef),
752 @code{centralCPosition} and @code{clefOctavation}. A clef is printed
753 when any of these properties are changed.
757 The object for this symbol is @internalsref{Clef}.
763 @subsection Time signature
764 @cindex Time signature
768 Time signature indicates the metrum of a piece: a regular pattern of
769 strong and weak beats. It is denoted by a fraction at the start of the
774 The time signature is set or changed by the @code{\time}
776 @lilypond[fragment,verbatim]
777 \time 2/4 c'2 \time 3/4 c'2.
780 The actual symbol that is printed can be customized with the @code{style}
781 property. Setting it to @code{#'()} uses fraction style for 4/4 and
784 This command sets the property @code{timeSignatureFraction},
785 @code{beatLength} and @code{measureLength} in the @code{Timing}
786 context, which is normally aliased to @internalsref{Score}. The property
787 @code{timeSignatureFraction} determine where bar lines should be
788 inserted, and how automatic beams should be generated. Changing the
789 value of @code{timeSignatureFraction} also causes a time signature
790 symbol to be printed.
792 More options are available through the Scheme function
793 @code{set-time-signature}. In combination with the
794 @internalsref{Measure_grouping_engraver}, it will create
795 @internalsref{MeasureGrouping} signs. Such signs ease reading
796 rhythmically complex modern music. In the following example, the 9/8
797 measure is subdivided in 2, 2, 2 and 3. This is passed to
798 @code{set-time-signature} as the third argument @code{(2 2 2 3)}.
801 \score { \notes \relative c'' {
802 #(set-time-signature 9 8 '(2 2 2 3))
803 g8-[ g-] d-[ d-] g-[ g-] a8-[-( bes g-]-) |
804 #(set-time-signature 5 8 '(3 2))
809 \translator { \StaffContext
810 \consists "Measure_grouping_engraver"
816 The object for this symbol is @internalsref{TimeSignature}. There are
817 many more options for its layout. See
818 @inputfileref{input/test,time.ly} for more examples.
822 Automatic beaming does not use measure grouping specified with
823 @code{set-time-signature}.
830 @cindex partial measure
831 @cindex measure, partial
832 @cindex shorten measures
833 @cindex @code{\partial}
835 Partial measures, for example in upbeats, are entered using the
836 @code{\partial} command:
837 @lilypond[fragment,verbatim]
838 \partial 16*5 c'16 c4 f16 a'2. ~ a'8. a'16 | g'1
841 The syntax for this command is
843 \partial @var{duration}
845 This is internally translated into
847 \property Timing.measurePosition = -@var{length of duration}
850 The property @code{measurePosition} contains a rational number
851 indicating how much of the measure has passed at this point.
853 @node Unmetered music
854 @subsection Unmetered music
856 Bar lines and bar numbers are calculated automatically. For unmetered
857 music (e.g. cadenzas), this is not desirable. By setting
858 @code{Score.timing} to false, this automatic timing can be switched
862 @subsection Bar lines
866 @cindex measure lines
870 Bar lines delimit measures, but are also used to indicate
871 repeats. Line breaks may only happen on barlines.
875 Bar lines are inserted automatically, but if you need a special type
876 of barline, you can force one using the @code{\bar} command:
877 @lilypond[relative=1,fragment,verbatim]
881 The following bar types are available
882 @lilypond[fragment, relative, singleline, verbatim]
894 In scores with many staves, the barlines are automatically placed at
895 top level, and they are connected between different staves of a
896 @internalsref{StaffGroup}:
897 @lilypond[fragment, verbatim]
898 < \context StaffGroup <
899 \context Staff = up { e'4 d'
902 \context Staff = down { \clef bass c4 g e g } >
903 \context Staff = pedal { \clef bass c2 c2 } >
907 The command @code{\bar @var{bartype}} is a short cut for
908 doing @code{\property Score.whichBar = @var{bartype}}
909 Whenever @code{whichBar} is set to a string, a bar line of that type is
910 created. @code{whichBar} is usually set automatically: at the start of
911 a measure it is set to @code{defaultBarType}. The contents of
912 @code{repeatCommands} is used to override default measure bars.
914 @code{whichBar} can also be set directly, using @code{\property} or
915 @code{\bar }. These settings take precedence over the automatic
916 @code{whichBar} settings.
919 @cindex repeatCommands
920 @cindex defaultBarType
925 You are encouraged to use @code{\repeat} for repetitions. See
928 The bar line objects that are created at @internalsref{Staff} are
929 called @internalsref{BarLine}, the bar lines that span staffs are
930 @internalsref{SpanBar}s.
937 The easiest way to enter fragments with more than one voice on a staff
938 is to split chords using the separator @code{\\}. You can use it for
939 small, short-lived voices (make a chord of voices) or for single
942 @lilypond[verbatim,fragment]
943 \context Voice = VA \relative c'' {
944 c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f' \\ d' >
948 The separator causes @internalsref{Voice} contexts to be instantiated,
949 bearing the names @code{"1"}, @code{"2"}, etc. In each of these
950 contexts, vertical direction of slurs, stems, etc. are set
953 This can also be done by instantiating @internalsref{Voice} contexts
954 by hand, and using @code{\voiceOne}, up to @code{\voiceFour} to assign
955 a stem directions and horizontal shift for each part.
958 @lilypond[singleline, verbatim]
960 \context Staff < \context Voice = VA { \voiceOne cis2 b }
961 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
962 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
965 Normally, note heads with a different number of dots are not merged, but
966 if you set the object property @code{merge-differently-dotted}, they are:
967 @lilypond[verbatim,fragment,singleline]
968 \relative c' \context Voice < {
970 \property Staff.NoteCollision \override
971 #'merge-differently-dotted = ##t
973 } \\ { [g8. f16] [g8. f16] }
977 Similarly, you can merge half note heads with eighth notes, by setting
978 @code{merge-differently-headed}:
979 @lilypond[fragment, relative=2,verbatim]
982 \property Staff.NoteCollision
983 \override #'merge-differently-headed = ##t
984 c8 c4. } \\ { c2 c2 } >
987 LilyPond also vertically shifts rests that are opposite of a stem.
989 @lilypond[singleline,fragment,verbatim]
990 \context Voice < c''4 \\ r4 >
995 The objects responsible for resolving collisions are
996 @internalsref{NoteCollision} and @internalsref{RestCollision}. See
997 also example files @inputfileref{input/regression/,collision-dots.ly},
998 @inputfileref{input/regression/,collision-head-chords.ly},
999 @inputfileref{input/regression/,collision-heads.ly},
1000 @inputfileref{input/regression/,collision-mesh.ly}, and
1001 @inputfileref{input/regression/,collisions.ly}.
1006 Resolving collisions is a very intricate subject, and LilyPond only
1007 handles a few situations. When it can not cope, you are advised to use
1008 @code{force-hshift} of the @internalsref{NoteColumn} object and pitched
1009 rests to override typesetting decisions.
1014 Beams are used to group short notes into chunks that are aligned with
1015 the metrum. They are inserted automatically in most cases.
1017 @lilypond[fragment,verbatim, relative=2]
1018 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
1021 If you are not satisfied with the automatic beaming, you can enter the
1022 beams explicitly. If you have beaming patterns that differ from the
1023 defaults, you can also set your own.
1025 See also @internalsref{Beam}.
1028 @cindex Automatic beams
1029 @subsection Manual beams
1030 @cindex beams, manual
1034 In some cases it may be necessary to override the automatic beaming
1035 algorithm. For example, the auto beamer will not beam over rests or
1036 bar lines, If you want that, specify the begin and end point manually
1037 using @code{[} and @code{]}.
1039 @lilypond[fragment,relative,verbatim]
1041 r4 r8-[ g' a r8-] r8 g-[ | a-] r8
1045 @cindex @code{stemLeftBeamCount}
1047 Normally, beaming patterns within a beam are determined automatically.
1048 When this mechanism fouls up, the properties
1049 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
1050 be used to control the beam subdivision on a stem. If you set either
1051 property, its value will be used only once, and then it is erased.
1053 @lilypond[fragment,relative,verbatim]
1056 f8-[ r16 \property Voice.stemLeftBeamCount = #1 f g a-]
1059 @cindex @code{stemRightBeamCount}
1062 The property @code{subdivideBeams} can be set in order to subdivide
1063 all 16th or shorter beams at beat positions. This accomplishes the
1064 same effect as twiddling with @code{stemLeftBeamCount} and
1065 @code{stemRightBeamCount}, but it take less typing.
1068 @lilypond[relative=1,verbatim,noindent]
1069 c16-[ c c c c c c c-]
1070 \property Voice.subdivideBeams = ##t
1071 c16-[ c c c c c c c-]
1072 c32-[ c c c c c c c c c c c c c c c-]
1073 \property Score.beatLength = #(ly:make-moment 1 8)
1074 c32-[ c c c c c c c c c c c c c c c-]
1076 @cindex subdivideBeams
1078 Kneed beams are inserted automatically, when a large gap is detected
1079 between the note heads. This behavior can be tuned through the object
1080 property @code{auto-knee-gap}.
1082 @cindex beams, kneed
1084 @cindex auto-knee-gap
1092 Automatically kneed beams can not be used together with Hara Kiri
1097 The Automatic beamer does not put @strong{unfinished} beams on the
1098 last notes of a score.
1101 * Setting automatic beam behavior ::
1105 @no de Beam typography
1106 @sub section Beam typography
1108 One of the strong points of LilyPond is how beams are formatted. Beams
1109 are quantized, meaning that the left and right endpoints beams start
1110 exactly on staff lines. Without quantization, small wedges of white
1111 space appear between the beam and staff line, and this looks untidy.
1113 Beams are also slope-damped: melodies that go up or down should also
1114 have beams that go up or down, but the slope of the beams should be
1115 less than the slope of the notes themselves.
1117 Some beams should be horizontal. These are so-called concave beams.
1119 [TODO: some pictures.]
1123 @node Setting automatic beam behavior
1124 @subsection Setting automatic beam behavior
1126 @cindex @code{autoBeamSettings}
1127 @cindex @code{(end * * * *)}
1128 @cindex @code{(begin * * * *)}
1129 @cindex automatic beams, tuning
1130 @cindex tuning automatic beaming
1132 [TODO: use \applycontext]
1134 In normal time signatures, automatic beams can start on any note but can
1135 only end in a few positions within the measure: beams can end on a beat,
1136 or at durations specified by the properties in
1137 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
1138 are defined in @file{scm/auto-beam.scm}.
1140 The value of @code{autoBeamSettings} is changed using
1141 @code{\override} and unset using @code{\revert}:
1143 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
1144 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
1146 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
1147 whether the rule applies to begin or end-points. The quantity
1148 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
1149 *}' designates notes of any length), @var{N}/@var{M} refers to a time
1150 signature (wildcards, `@code{* *}' may be entered to designate all time
1153 For example, if you want automatic beams to end on every quarter note,
1154 you can use the following:
1156 \property Voice.autoBeamSettings \override
1157 #'(end * * * *) = #(ly:make-moment 1 4)
1159 Since the duration of a quarter note is 1/4 of a whole note, it is
1160 entered as @code{(ly:make-moment 1 4)}.
1162 The same syntax can be used to specify beam starting points. In this
1163 example, automatic beams can only end on a dotted quarter note.
1165 \property Voice.autoBeamSettings \override
1166 #'(end * * * *) = #(ly:make-moment 3 8)
1168 In 4/4 time signature, this means that automatic beams could end only on
1169 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1170 3/8 has passed within the measure).
1172 You can also restrict rules to specific time signatures. A rule that
1173 should only be applied in @var{N}/@var{M} time signature is formed by
1174 replacing the second asterisks by @var{N} and @var{M}. For example, a
1175 rule for 6/8 time exclusively looks like
1177 \property Voice.autoBeamSettings \override
1178 #'(begin * * 6 8) = ...
1181 If you want a rule to apply to certain types of beams, you can use the
1182 first pair of asterisks. Beams are classified according to the shortest
1183 note they contain. For a beam ending rule that only applies to beams
1184 with 32nd notes (and no shorter notes), you would use @code{(end 1
1188 @c Automatic beams can not be put on the last note in a score.
1190 If a score ends while an automatic beam has not been ended and is still
1191 accepting notes, this last beam will not be typeset at all.
1193 @cindex automatic beam generation
1195 @cindex @code{Voice.autoBeaming}
1198 For melodies that have lyrics, you may want to switch off
1199 automatic beaming. This is done by setting @code{Voice.autoBeaming} to
1205 It is not possible to specify beaming parameters for beams with mixed
1206 durations, that differ from the beaming parameters of all separate
1207 durations, i.e., you'll have to specify manual beams to get:
1209 @lilypond[singleline,fragment,relative,noverbatim,quote]
1210 \property Voice.autoBeamSettings
1211 \override #'(end * * * *) = #(ly:make-moment 3 8)
1212 \time 12/8 c'8 c c c16 c c c c c c-[ c c c-] c8 c c4
1214 It is not possible to specify beaming parameters that act differently in
1215 different parts of a measure. This means that it is not possible to use
1216 automatic beaming in irregular meters such as @code{5/8}.
1219 @section Accidentals
1222 This section describes how to change the way that LilyPond automatically
1223 inserts accidentals before the running notes.
1225 [TODO: identifier vs. macro]
1228 * Using the predefined accidental macros::
1229 * Defining your own accidental typesettings::
1232 @node Using the predefined accidental macros
1233 @subsection Using the predefined accidental macros
1234 The constructs for describing the accidental typesetting rules are
1235 quite hairy, so non-experts should stick to the macros defined in
1236 @file{ly/property-init.ly}.
1237 @cindex @file{property-init.ly}
1239 The macros operate on the ``Current'' context (see @ref{Context properties}). This
1240 means that the macros shuold normally be invoked right after the
1241 creation of the context in which the accidental typesetting described
1242 by the macro is to take effect. I.e. if you want to use
1243 piano-accidentals in a pianostaff then you issue
1244 @code{\pianoAccidentals} first thing after the creation of the piano
1248 \notes \relative c'' <
1249 \context Staff = sa @{ cis4 d e2 @}
1250 \context GrandStaff <
1252 \context Staff = sb @{ cis4 d e2 @}
1253 \context Staff = sc @{ es2 c @}
1255 \context Staff = sd @{ es2 c @}
1259 @lilypond[singleline]
1261 \notes \relative c'' <
1262 \context Staff = sa { cis4 d e2 }
1263 \context GrandStaff <
1265 \context Staff = sb { cis4 d e2 }
1266 \context Staff = sc { es2 c }
1268 \context Staff = sd { es2 c }
1273 minimumVerticalExtent = #'(-4.0 . 4.0)
1281 @item \defaultAccidentals
1282 @cindex @code{\defaultAccidentals}
1283 This is the default typesetting behaviour. It should correspond
1284 to 18th century common practice: Accidentals are
1285 remembered to the end of the measure in which they occur and
1286 only on their own octave.
1288 @item \voiceAccidentals
1289 @cindex @code{\voiceAccidentals}
1290 The normal behaviour is to remember the accidentals on
1292 This macro, however, typesets accidentals individually for each
1294 Apart from that the rule is similar to
1295 @code{\defaultAccidentals}.
1297 This leads to some weird and often unwanted results
1298 because accidentals from one voice do not get cancelled in other
1300 @lilypond[singleline,relative,fragment,verbatim,quote]
1308 Hence you should only use @code{\voiceAccidentals} if the voices
1309 are to be read solely by individual musicians. If the staff is to be
1310 used by one musician (e.g., a conductor) then you use
1311 @code{\modernVoiceAccidentals} or @code{\modernVoiceCautionaries}
1314 @item \modernAccidentals
1315 @cindex @code{\modernAccidentals}
1316 This rule corresponds to the common practice in the 20th
1318 The rule is more complex than @code{\defaultAccidentals}.
1319 You get all the same accidentals, but temporary
1320 accidentals also get cancelled in other octaves. Further more,
1321 in the same octave, they also get cancelled in the following measure:
1322 @lilypond[singleline,fragment,verbatim]
1324 cis' c'' cis'2 | c'' c'
1327 @item \modernCautionaries
1328 @cindex @code{\modernCautionaries}
1329 This rule is similar to @code{\modernAccidentals}, but the
1330 ``extra'' accidentals (the ones not typeset by
1331 @code{\defaultAccidentals}) are typeset as cautionary accidentals
1332 (i.e. in reduced size):
1333 @lilypond[singleline,fragment,verbatim]
1335 cis' c'' cis'2 | c'' c'
1338 @cindex @code{\modernVoiceAccidentals}
1339 @item \modernVoiceAccidentals
1340 is used for multivoice accidentals to be read both by musicians
1341 playing one voice and musicians playing all voices. Accidentals are
1342 typeset for each voice, but they @emph{are} cancelled across voices in
1343 the same @internalsref{Staff}.
1345 @cindex @code{\modernVoiceCautionaries}
1346 @item \modernVoiceCautionaries
1348 @code{\modernVoiceAccidentals}, but with the extra accidentals (the
1349 ones not typeset by @code{\voiceAccidentals}) typeset as cautionaries.
1350 Even though all accidentals typeset by @code{\defaultAccidentals}
1351 @emph{are} typeset by this macro then some of them are typeset as
1354 @item \pianoAccidentals
1355 @cindex @code{\pianoAccidentals}
1356 20th century practice for piano notation. Very similar to
1357 @code{\modernAccidentals} but accidentals also get cancelled
1358 across the staves in the same @internalsref{GrandStaff} or
1359 @internalsref{PianoStaff}.
1361 @item \pianoCautionaries
1362 @cindex @code{\pianoCautionaries}
1363 As @code{\pianoAccidentals} but with the extra accidentals
1364 typeset as cautionaries.
1367 @cindex @code{\noResetKey}
1368 Same as @code{\defaultAccidentals} but with accidentals lasting
1369 ``forever'' and not only until the next measure:
1370 @lilypond[singleline,fragment,verbatim,relative]
1375 @item \forgetAccidentals
1376 @cindex @code{\forgetAccidentals}
1377 This is sort of the opposite of @code{\noResetKey}: Accidentals
1378 are not remembered at all - and hence all accidentals are
1379 typeset relative to the key signature, regardless of what was
1380 before in the music:
1381 @lilypond[singleline,fragment,verbatim,relative]
1383 \key d\major c4 c cis cis d d dis dis
1387 @node Defining your own accidental typesettings
1388 @subsection Defining your own accidental typesettings
1390 This section must be considered gurus-only, and hence it must be
1391 sufficient with a short description of the system and a reference to
1392 the internal documentation.
1394 The algorithm tries several different rules, and uses the rule
1395 that gives the highest number of accidentals. Each rule consists of
1398 In which context is the rule applied. For example, if
1399 @var{context} is @internalsref{Score} then all staves share
1400 accidentals, and if @var{context} is @internalsref{Staff} then all
1401 voices in the same staff share accidentals, but staves do not.
1403 Whether the accidental changes all octaves or only the current
1406 Over how many barlines the accidental lasts.
1407 If @var{lazyness} is @code{-1} then the accidental is forget
1408 immediately, and if @var{lazyness} is @code{#t} then the accidental
1411 [TODO: should use +infinity for this case?]
1417 @internalsref{Accidental_engraver},
1422 Currently the simultaneous notes are considered to be entered in
1423 sequential mode. This means that in a chord the accidentals are
1424 typeset as if the notes in the chord happened one at a time - in the
1425 order in which they appear in the input file.
1427 This is only a problem when there are simultaneous notes whose
1428 accidentals depend on each other. The problem only occurs when using
1429 non-default accidentals. In the default scheme, accidentals only
1430 depend on other accidentals with the same pitch on the same staff, so
1431 no conflicts possible.
1433 This example shows two examples of the same music giving different
1434 accidentals depending on the order in which the notes occur in the
1437 @lilypond[singleline,fragment,verbatim]
1438 \property Staff.autoAccidentals = #'( Staff (any-octave . 0) )
1439 cis'4 <<c'' c'>> r2 | cis'4 <<c' c''>> r2
1440 | <<cis' c''>> r | <<c'' cis'>> r |
1443 This problem can be solved by manually inserting @code{!} and @code{?}
1444 for the problematic notes.
1446 @node Expressive marks
1447 @section Expressive marks
1456 * Analysis brackets::
1463 A slur indicates that notes are to be played bound or @emph{legato}.
1467 They are entered using parentheses:
1468 @lilypond[fragment,verbatim,center]
1469 f'-( g'-)-( a'-) [a'8 b'-(-] a'4 g'2 f'4-)
1470 <<c' e'>>2-( <<b d'>>2-)
1474 @c TODO: should explain that ^( and _( set directions
1475 @c should set attachments with ^ and _ ?
1477 Slurs avoid crossing stems, and are generally attached to note heads.
1478 However, in some situations with beams, slurs may be attached to stem
1479 ends. If you want to override this layout you can do this through the
1480 object property @code{attachment} of @internalsref{Slur} in
1481 @internalsref{Voice} context. Its value is a pair of symbols, specifying
1482 the attachment type of the left and right end points.
1484 @lilypond[fragment,relative,verbatim]
1486 \property Voice.Stem \set #'length = #5.5
1488 \property Voice.Slur \set #'attachment = #'(stem . stem)
1492 If a slur would strike through a stem or beam, the slur will be moved
1493 away upward or downward. If this happens, attaching the slur to the
1494 stems might look better:
1496 @lilypond[fragment,relative,verbatim]
1499 \property Voice.Slur \set #'attachment = #'(stem . stem)
1505 @seeinternals{Slur}.
1510 Producing nice slurs is a difficult problem, and LilyPond currently
1511 uses a simple, empiric method to produce slurs. In some cases, the
1512 results of this method are ugly.
1515 @cindex Adjusting slurs
1517 @node Phrasing slurs
1518 @subsection Phrasing slurs
1520 @cindex phrasing slurs
1521 @cindex phrasing marks
1523 A phrasing slur (or phrasing mark) connects chords and is used to
1524 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1527 @lilypond[fragment,verbatim,center,relative]
1528 \time 6/4 c'-\( d-( e-) f-( e-) d-\)
1531 Typographically, the phrasing slur behaves almost exactly like a
1532 normal slur. Although they behave similar to normal slurs, phrasing
1533 slurs count as different objects. A @code{\slurUp} will have no
1534 effect on a phrasing slur; instead, you should use
1535 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
1536 @code{\phrasingSlurBoth}.
1538 The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurBoth}
1539 will only affect normal slurs and not phrasing slurs.
1543 See also @seeinternals{PhrasingSlur}. Phrasing slurs have the same
1544 limitations in their formatting.
1547 @subsection Breath marks
1549 Breath marks are entered using @code{\breathe}.
1552 @lilypond[fragment,relative]
1556 The glyph of the breath mark can be tweaked by overriding the
1557 @code{text} property of the @code{BreathingSign} grob with the name of
1558 any glyph of @ref{The Feta font}. For example,
1559 @lilypond[fragment,verbatim,relative]
1561 \property Voice.BreathingSign \override #'text = #"scripts-rvarcomma"
1568 @seeinternals{BreathingSign},
1569 @inputfileref{input/regression/,breathing-sign.ly}.
1575 @cindex beats per minute
1576 @cindex metronome marking
1578 Metronome settings can be entered as follows:
1580 @cindex @code{\tempo}
1582 \tempo @var{duration} = @var{perminute}
1585 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1590 The tempo setting is not printed, but is only used in the MIDI
1591 output. You can trick lily into producing a metronome mark,
1592 though. Details are in @ref{Text markup}.
1594 [TODO: make note markup.]
1598 @subsection Text spanners
1599 @cindex Text spanners
1601 Some textual indications, e.g. @i{rallentando} or @i{accelerando}, are
1602 often extended over many measures. This is indicated by following the
1603 text with a dotted line. You can create such texts using text
1604 spanners. The syntax is as follows:
1609 The string to be printed, as well as the style, is set through object
1612 An application is to fake octavation indications.
1614 @lilypond[fragment,relative,verbatim]
1615 \relative c' { a''' b c a
1616 \property Voice.TextSpanner \set #'type = #'dotted-line
1617 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1618 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1619 \property Staff.centralCPosition = #-13
1620 a-\startTextSpan b c a-\stopTextSpan }
1626 @internalsref{TextSpanner}, @inputfileref{input/regression/,text-spanner.ly}.
1629 @node Analysis brackets
1630 @subsection Analysis brackets
1632 @cindex phrasing brackets
1633 @cindex musicological analysis
1634 @cindex note grouping bracket
1636 Brackets are used in musical analysis to indicate structure in musical
1637 pieces. LilyPond supports a simple form of nested horizontal brackets.
1638 To use this, add the @internalsref{Horizontal_bracket_engraver} to
1639 @internalsref{Staff} context. A bracket is started with
1640 @code{\groupOpen} and closed with @code{\groupClose}. This produces
1641 @internalsref{HorizontalBracket} objects.
1643 @lilypond[singleline,verbatim]
1644 \score { \notes \relative c'' {
1645 c4-\groupOpen-\groupOpen
1648 c4-\groupClose-\groupClose
1650 \paper { \translator {
1651 \StaffContext \consists "Horizontal_bracket_engraver"
1657 Bracket endings should be angled/slanted. (TODO)
1665 [TODO: ornaments vs. expressive marks]
1677 @subsection Articulations
1678 @cindex Articulations
1680 @cindex articulations
1684 A variety of symbols can appear above and below notes to indicate
1685 different characteristics of the performance. They are added to a note
1686 by adding a dash and the the character signifying the
1687 articulation. They are demonstrated here.
1689 @lilypondfile[notexidoc]{script-abbreviations.ly}
1691 The script is automatically placed, but if you need to force
1692 directions, you can use @code{_} to force them down, or @code{^} to
1694 @lilypond[fragment, verbatim]
1699 Other symbols can be added using the syntax
1700 @var{note}@code{-\}@var{name}. Again, they can be forced up or down
1701 using @code{^} and @code{_}.
1705 @cindex staccatissimo
1714 @cindex organ pedal marks
1723 @cindex prallmordent
1727 @cindex thumb marking
1732 @lilypondfile[notexidoc]{script-chart.ly}
1737 Fingering instructions can also be entered in this shorthand. For
1738 finger changes, use markup texts:
1740 @lilypond[verbatim, singleline, fragment]
1741 c'4-1 c'4-2 c'4-3 c'4-4
1742 c'^\markup { \fontsize #-3 \number "2-3" }
1745 @cindex finger change
1750 @lilypond[verbatim,singleline,fragment,relative=1]
1751 << c-1 e-2 g-3 b-5 >> 4
1752 \property Voice.fingerHorizontalDirection = #LEFT
1753 << c-1 es-3 g-5 >> 4
1754 \property Voice.fingerHorizontalDirection = #RIGHT
1755 << c-1 e-2 g-3 b-5 >> 4-\arpeggio
1756 \property Voice.fingerHorizontalDirection = #LEFT
1757 << c_1 e-2 g-3 b^5 >> 4
1762 @internalsref{Script} and @internalsref{Fingering}.
1766 All of these note ornaments appear in the printed output but have no
1767 effect on the MIDI rendering of the music.
1771 @subsection Text scripts
1772 @cindex Text scripts
1774 It is possible to place arbitrary strings of text or markup text (see
1775 @ref{Text markup}) above or below notes by using a string:
1776 @code{c^"text"}. By default, these indications do not influence the
1777 note spacing, but by using the command @code{\fatText}, the widths
1778 will be taken into account.
1780 @lilypond[fragment,singleline,verbatim] \relative c' {
1781 c4^"longtext" \fatText c4_"longlongtext" c4 }
1784 It is possible to use @TeX{} commands in the strings, but this should be
1785 avoided because it makes it impossible for LilyPond to compute the
1786 exact length of the string, which may lead to collisions. Also, @TeX{}
1787 commands will not work with direct PostScript output.
1791 @internalsref{TextScript} objects.
1793 @ref{Text markup} describes how to change the font or access
1794 special symbols in text scripts.
1799 @subsection Grace notes
1803 @cindex @code{\grace}
1807 Grace notes are ornaments that are written out
1809 @lilypond[relative=2,verbatim,ifragment] c4 \grace c16 c4 \grace {
1813 In normal notation, grace notes take up no logical
1814 time in a measure. Such an idea is practical for normal notation, but
1815 is not strict enough to put it into a program. The model that LilyPond
1816 uses for grace notes internally is that all timing is done in two
1819 Every point in musical time consists of two rational numbers: one
1820 denotes the logical time, one denotes the grace timing. The above
1821 example is shown here with timing tuples.
1824 \score { \notes \relative c''{
1825 c4^"(0,0)" \grace c16_" "_"(1/4,-1/16)" c4^"(1/4,0)" \grace {
1826 [c16_"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4_" "_"(2/4,0)"
1828 \paper { linewidth = 8.\cm }
1833 The placement of these grace notes is synchronized between different
1836 @lilypond[relative=2,verbatim,fragment]
1837 < \context Staff = SA { e4 \grace { c16-[ d e f-] } e4 }
1838 \context Staff = SB { c'4 \grace { g8 b } c4 } >
1842 Unbeamed eighth notes and shorter by default have a slash through the
1843 stem. This can be controlled with object property @code{stroke-style} of
1844 @internalsref{Stem}. The change in formatting is accomplished by
1845 inserting @code{\startGraceMusic} before handling the grace notes, and
1846 @code{\stopGraceMusic} after finishing the grace notes.
1847 You can add to these definitions to globally change grace note
1848 formatting. The standard definitions are in @file{ly/grace-init.ly}.
1850 [TODO discuss Scheme functionality.]
1853 The @code{\override} is carefully matched with a @code{\revert}.
1858 @lilypond[fragment,verbatim]
1859 \relative c'' \context Voice {
1860 \grace c8 c4 \grace { [c16 c16] } c4
1862 \property Voice.Stem \override #'stroke-style = #'()
1864 \property Voice.Stem \revert #'stroke-style
1871 If you want to end a note with a grace note, then the standard trick
1872 is to put the grace notes before a phantom ``space note'', e.g.
1873 @lilypond[fragment,verbatim, relative=2]
1876 { s2 \grace { [c16 d] } } >
1881 A @code{\grace} section has some default values, and LilyPond will
1882 use those default values unless you specify otherwise inside the
1883 @code{\grace} section. For example, if you specify \slurUp
1884 @emph{before} your @code{\grace} section, a slur which starts inside
1885 the @code{\grace} will not be forced up, even if the slur ends outside
1886 of the @code{\grace}. Note the difference between the first and
1887 second bars in this example:
1889 @lilypond[fragment,verbatim]
1890 \relative c'' \context Voice {
1909 Grace notes can not be used in the smallest size (@file{paper11.ly}).
1911 Grace note synchronization can also lead to surprises. Staff notation,
1912 such as key signatures, barlines, etc. are also synchronized. Take
1913 care when you mix staves with grace notes and staves without.
1915 @lilypond[relative=2,verbatim,fragment]
1916 < \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
1917 \context Staff = SB { c4 \bar "|:" d4 } >
1920 Grace sections should only be used within sequential music
1921 expressions. Nesting, juxtaposing, or ending sequential music with a
1922 grace section is not supported, and might produce crashes or other
1927 @subsection Glissando
1930 @cindex @code{\glissando}
1932 A glissando is a smooth change in pitch. It is denoted by a line or a
1933 wavy line between two notes.
1937 A glissando line can be requested by attaching a @code{\glissando} to
1940 @lilypond[fragment,relative,verbatim]
1946 @seeinternals{Glissando}.
1951 Printing of an additional text (such as @emph{gliss.}) must be done
1956 @subsection Dynamics
1969 @cindex @code{\ffff}
1979 Absolute dynamic marks are specified using an identifier after a
1980 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1981 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1982 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1983 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1985 @lilypond[verbatim,singleline,fragment,relative]
1986 c'-\ppp c-\pp c -\p c-\mp c-\mf c-\f c-\ff c-\fff
1992 @cindex @code{\decr}
1993 @cindex @code{\rced}
2000 A crescendo mark is started with @code{\cr} and terminated with
2001 @code{\endcr}, and decrescendi similarly with @code{\decr} and
2002 @code{\enddecr}. There are also shorthands for these marks. A
2003 crescendo can be started with @code{\<} and a decrescendo can be
2004 started with @code{\>}. Either one can be terminated with @code{\!}.
2005 Because these marks are bound to notes, if you must use spacer notes
2006 if marks during one note are needed.
2008 @lilypond[fragment,verbatim,center,quote]
2009 c''-\< c''-\! d''-\decr e''-\rced
2010 < f''1 { s4 s4-\< s4-\! \> s4-\! } >
2012 This may give rise to very short hairpins. Use @code{minimum-length}
2013 in @internalsref{Voice}.@internalsref{HairPin} to lengthen these, e.g.
2016 \property Staff.Hairpin \override #'minimum-length = #5
2019 You can also use a text saying @emph{cresc.} instead of hairpins. Here
2020 is an example how to do it:
2022 @lilypond[fragment,relative=2,verbatim]
2023 c4 \cresc c4 \endcresc c4
2030 You can also supply your own texts:
2031 @lilypond[fragment,relative,verbatim]
2033 \property Voice.crescendoText = "cresc. poco"
2034 \property Voice.crescendoSpanner = #'dashed-line
2043 Dynamics are objects of @internalsref{DynamicText} and
2044 @internalsref{Hairpin}. Vertical positioning of these symbols is
2045 handled by the @internalsref{DynamicLineSpanner} object.
2047 If you want to adjust padding or vertical direction of the dynamics,
2048 you must set properties for the @internalsref{DynamicLineSpanner}
2049 object. Predefined identifiers to set the vertical direction are
2050 \dynamicUp and \dynamicDown.
2052 @cindex direction, of dynamics
2053 @cindex @code{\dynamicDown}
2054 @cindex @code{\dynamicUp}
2062 @cindex @code{\repeat}
2064 To specify repeats, use the @code{\repeat} keyword. Since repeats
2065 should work differently when played or printed, there are a few
2066 different variants of repeats.
2070 Repeated music is fully written (played) out. Useful for MIDI
2071 output, and entering repetitive music.
2074 This is the normal notation: Repeats are not written out, but
2075 alternative endings (voltas) are printed, left to right.
2079 Alternative endings are written stacked. This has limited use but may be
2080 used to typeset two lines of lyrics in songs with repeats, see
2081 @inputfileref{input,star-spangled-banner.ly}.
2088 Make beat or measure repeats. These look like percent signs.
2094 * Repeats and MIDI::
2095 * Manual repeat commands::
2097 * Tremolo subdivisions::
2102 @subsection Repeat syntax
2105 Repetition is a central concept in music, and multiple notations exist
2110 LilyPond has one syntactic construct for specifying different types of
2111 repeats. The syntax is
2114 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2117 If you have alternative endings, you may add
2118 @cindex @code{\alternative}
2120 \alternative @code{@{} @var{alternative1}
2122 @var{alternative3} @dots{} @code{@}}
2124 where each @var{alternative} is a music expression. If you do not
2125 give enough alternatives for all of the repeats, then the first
2126 alternative is assumed to be played more than once.
2128 Normal notation repeats are used like this:
2129 @lilypond[fragment,verbatim]
2131 \repeat volta 2 { c'4 d' e' f' }
2132 \repeat volta 2 { f' e' d' c' }
2135 With alternative endings:
2136 @lilypond[fragment,verbatim]
2138 \repeat volta 2 {c'4 d' e' f'}
2139 \alternative { {d'2 d'} {f' f} }
2143 Folded repeats look like this:
2146 @li lypond[fragment,verbatim]
2148 \repeat fold 2 {c'4 d' e' f'}
2149 \alternative { {d'2 d'} {f' f} }
2155 @lilypond[fragment,verbatim]
2159 \repeat volta 4 { e | c2 d2 | e2 f2 | }
2160 \alternative { { g4 g g } { a | a a a a | b2. } }
2165 @node Repeats and MIDI
2166 @subsection Repeats and MIDI
2168 @cindex expanding repeats
2170 For instructions on how to unfold repeats for MIDI output, see the
2171 example file @inputfileref{input/test,unfold-all-repeats.ly}.
2176 Timing information is not remembered at the start of an alternative,
2177 so you have to reset timing information after a repeat, e.g. using a
2178 bar-check (See @ref{Bar check}), setting @code{Score.measurePosition}
2179 or entering @code{\partial}. Slurs or ties are also not repeated.
2182 @node Manual repeat commands
2183 @subsection Manual repeat commands
2185 @cindex @code{repeatCommands}
2187 The property @code{repeatCommands} can be used to control the layout of
2188 repeats. Its value is a Scheme list of repeat commands, where each repeat
2196 @item (volta . @var{text})
2197 Print a volta bracket saying @var{text}. The text can be specified as
2198 a text string or as a markup text, see @ref{Text markup}. Do not
2199 forget to change the font, as the default number font does not contain
2200 alphabetic characters.
2202 Stop a running volta bracket
2205 @lilypond[verbatim, fragment]
2207 \property Score.repeatCommands = #'((volta "93") end-repeat)
2209 \property Score.repeatCommands = #'((volta #f))
2216 Repeat brackets are @internalsref{VoltaBracket} objects.
2218 @node Tremolo repeats
2219 @subsection Tremolo repeats
2220 @cindex tremolo beams
2222 To place tremolo marks between notes, use @code{\repeat} with tremolo
2224 @lilypond[verbatim,center,singleline]
2226 \context Voice \notes\relative c' {
2227 \repeat "tremolo" 8 { c16 d16 }
2228 \repeat "tremolo" 4 { c16 d16 }
2229 \repeat "tremolo" 2 { c16 d16 }
2230 \repeat "tremolo" 4 c16
2237 Tremolo beams are @internalsref{Beam} objects. Single stem tremolos are
2238 @internalsref{StemTremolo}.
2242 The single stem tremolo @emph{must} be entered without @code{@{} and
2245 @node Tremolo subdivisions
2246 @subsection Tremolo subdivisions
2247 @cindex tremolo marks
2248 @cindex @code{tremoloFlags}
2250 Tremolo marks can be printed on a single note by adding
2251 `@code{:}[@var{length}]' after the note. The length must be at least 8.
2252 A @var{length} value of 8 gives one line across the note stem. If the
2253 length is omitted, then then the last value (stored in
2254 @code{Voice.tremoloFlags}) is used.
2256 @lilypond[verbatim,fragment,center]
2257 c'2:8 c':32 | c': c': |
2260 [TODO : stok is te kort bij 32en]
2264 Tremolos in this style do not carry over into the MIDI output.
2267 @node Measure repeats
2268 @subsection Measure repeats
2270 @cindex percent repeats
2271 @cindex measure repeats
2273 In the @code{percent} style, a note pattern can be repeated. It is
2274 printed once, and then the pattern is replaced with a special sign.
2275 Patterns of a one and two measures are replaced by percent-like signs,
2276 patterns that divide the measure length are replaced by slashes.
2278 @lilypond[verbatim,singleline]
2279 \context Voice { \repeat "percent" 4 { c'4 }
2280 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
2286 @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, and
2287 @internalsref{DoublePercentRepeat}.
2291 You can not nest percent repeats, e.g. by filling in the first measure
2292 with slashes, and repeating that measure with percents.
2294 @node Rhythmic music
2295 @section Rhythmic music
2297 Sometimes you might want to show only the rhythm of a melody. This can
2298 be done with the rhythmic staff. All pitches of notes on such a staff
2299 are squashed, and the staff itself looks has a single staff line:
2301 @lilypond[fragment,relative,verbatim]
2302 \context RhythmicStaff {
2304 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
2309 * Percussion staves::
2310 * Percussion midi output::
2313 @node Percussion staves
2314 @subsection Percussion staves
2318 To typeset more than one piece of percussion to be played by the same
2319 musician one typically uses a multiline staff where each staff
2320 position refers to a specific piece of percussion.
2324 LilyPond is has a set of Scheme functions that can be used to typeset
2325 percussion staves. The system is based on the general MIDI
2326 drum-pitches. Include @file{ly/drumpitch-init.ly} to use drum
2327 pitches. This file defines the pitches from the Scheme variable
2328 @code{drum-pitch-names}, the definition of which can be read in
2329 @file{scm/drums.scm}. Each piece of percussion has a full name and an
2330 abbreviated name, and both the full name or the abbreviation may be
2331 used in input files.
2333 To typeset the music on a staff apply the function @code{drums->paper}
2334 to the percussion music. This function takes a list of percussion
2335 instrument names, notehead scripts and staff positions (that is:
2336 pitches relative to the C-clef) and transforms the input
2337 music by moving the pitch, changing the notehead and (optionally)
2340 @lilypond[singleline,verbatim,quote]
2341 \include "drumpitch-init.ly"
2342 up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
2343 down = \notes { bassdrum4 snare8 bd r bd sn4 }
2345 \apply #(drums->paper 'drums) \context Staff <
2347 \context Voice = up { \voiceOne \up }
2348 \context Voice = down { \voiceTwo \down }
2353 In the above example the music was transformed using the list @code{'drums}.
2354 Currently the following lists are defined in @file{scm/drums.scm}:
2357 To typeset a typical drum kit on a five-line staff.
2360 \include "drumpitch-init.ly"
2361 nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc
2362 bd sn ss tomh tommh tomml toml tomfh tomfl }
2363 mus = \notes { cymc cyms cymr hh hhc hho hhho hhp cb hc
2364 bd sn ss tomh tommh tomml toml tomfh tomfl s16 }
2367 \apply #(drums->paper 'drums) \context Staff <
2371 \context Lyrics \nam
2374 linewidth = 100.0\mm
2377 \remove Bar_engraver
2378 \remove Time_signature_engraver
2379 minimumVerticalExtent = #'(-4.0 . 5.0)
2383 \remove Stem_engraver
2389 Scheme supports six different toms. When there fewer toms, simply
2390 select the toms that produce the desired result, i.e., to get toms on
2391 the three middle lines you use @code{tommh}, @code{tomml} and
2394 Because general MIDI does not contain rimshots the sidestick is used
2395 for this purpose instead.
2397 To typeset timbales on a two line staff.
2398 @lilypond[singleline]
2399 \include "drumpitch-init.ly"
2400 nam = \lyrics { timh ssh timl ssl cb }
2401 mus = \notes { timh ssh timl ssl cb s16 }
2404 \apply #(drums->paper 'timbales) \context Staff <
2408 \context Lyrics \nam
2413 \remove Bar_engraver
2414 \remove Time_signature_engraver
2415 StaffSymbol \override #'line-count = #2
2416 StaffSymbol \override #'staff-space = #2
2417 minimumVerticalExtent = #'(-3.0 . 4.0)
2421 \remove Stem_engraver
2428 To typeset congas on a two line staff.
2429 @lilypond[singleline]
2430 \include "drumpitch-init.ly"
2431 nam = \lyrics { cgh cgho cghm ssh cgl cglo cglm ssl }
2432 mus = \notes { cgh cgho cghm ssh cgl cglo cglm ssl s16 }
2435 \apply #(drums->paper 'congas) \context Staff <
2439 \context Lyrics \nam
2444 \remove Bar_engraver
2445 \remove Time_signature_engraver
2446 StaffSymbol \override #'line-count = #2
2447 StaffSymbol \override #'staff-space = #2
2448 minimumVerticalExtent = #'(-3.0 . 4.0)
2452 \remove Stem_engraver
2458 To typeset bongos on a two line staff.
2459 @lilypond[singleline]
2460 \include "drumpitch-init.ly"
2461 nam = \lyrics { boh boho bohm ssh bol bolo bolm ssl }
2462 mus = \notes { boh boho bohm ssh bol bolo bolm ssl s16 }
2465 \apply #(drums->paper 'bongos) \context Staff <
2469 \context Lyrics \nam
2474 \remove Bar_engraver
2475 \remove Time_signature_engraver
2476 StaffSymbol \override #'line-count = #2
2477 StaffSymbol \override #'staff-space = #2
2478 minimumVerticalExtent = #'(-3.0 . 4.0)
2482 \remove Stem_engraver
2488 To typeset all kinds of simple percussion on one line staves.
2489 @lilypond[singleline]
2490 \include "drumpitch-init.ly"
2491 nam = \lyrics { tri trio trim gui guis guil cb cl tamb cab mar hc }
2492 mus = \notes { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }
2495 \apply #(drums->paper 'percussion) \context Staff <
2499 \context Lyrics \nam
2504 \remove Bar_engraver
2505 \remove Time_signature_engraver
2506 StaffSymbol \override #'line-count = #1
2507 minimumVerticalExtent = #'(-2.0 . 3.0)
2511 \remove Stem_engraver
2518 If you do not like any of the predefined lists you can define your own
2519 list at the top of your file:
2521 @lilypond[singleline, verbatim]
2523 (bassdrum default #f ,(ly:make-pitch -1 2 0))
2524 (snare default #f ,(ly:make-pitch 0 1 0))
2525 (hihat cross #f ,(ly:make-pitch 0 5 0))
2526 (pedalhihat xcircle "stopped" ,(ly:make-pitch 0 5 0))
2527 (lowtom diamond #f ,(ly:make-pitch -1 6 0))
2529 \include "drumpitch-init.ly"
2530 up = \notes { hh8 hh hh hh hhp4 hhp }
2531 down = \notes { bd4 sn bd toml8 toml }
2533 \apply #(drums->paper 'mydrums) \context Staff <
2535 \context Voice = up { \voiceOne \up }
2536 \context Voice = down { \voiceTwo \down }
2541 To use a modified existing list, one can prepend modifications to the
2545 #(define mydrums (append `(
2546 (bassdrum default #f ,(ly:make-pitch -1 2 0))
2547 (lowtom diamond #f ,(ly:make-pitch -1 6 0))
2551 The file @file{drumpitch-init.ly} replaces the normal pitch names, so
2552 you have to reinclude @file{nederlands.ly} after the
2553 drum-pattern-definitions to enter normal notes.
2555 @lilypond[singleline,verbatim]
2556 \include "drumpitch-init.ly"
2557 up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
2558 down = \notes { bassdrum4 snare8 bd r bd sn4 }
2559 \include "nederlands.ly"
2560 bass = \notes \transpose c c,, { a4. e8 r e g e }
2563 \apply #(drums->paper 'drums) \context Staff = drums <
2565 \context Voice = up { \voiceOne \up }
2566 \context Voice = down { \voiceTwo \down }
2568 \context Staff = bass { \clef "F_8" \bass }
2573 @node Percussion midi output
2574 @subsection Percussion midi output
2576 In order to produce correct midi output you need to produce two score
2577 blocks---one for the paper and one for the midi output. To use the
2578 percussion channel you set the property @code{instrument} to
2579 @code{'drums}. Because the drum-pitches themself are similar to the
2580 general midi pitches all you have to do is to insert the voices with
2581 none of the scheme functions to get the correct midi output:
2585 \apply #(drums->paper 'mydrums) \context Staff <
2594 \property Staff.instrument = #'drums
2603 This scheme is to be considered a temporary implementation.
2607 @section Piano music
2609 Piano staves are two normal staves coupled with a brace. The staves
2610 are largely independent, but sometimes voices can cross between the
2611 two staves. The same notation is also used for harps and other key
2612 instruments. The @internalsref{PianoStaff} is especially built to
2613 handle this cross-staffing behavior. In this section we discuss the
2614 @internalsref{PianoStaff} and some other pianistic peculiarities.
2618 * Automatic staff changes::
2619 * Manual staff switches::
2622 * Voice follower lines::
2627 There is no support for putting chords across staves. You can get
2628 this result by increasing the length of the stem in the lower stave so
2629 it reaches the stem in the upper stave, or vice versa. An example is
2630 included with the distribution as @inputfileref{input/test,stem-cross-staff.ly}.
2632 Dynamics are not centered, but kludges do exist. See
2633 @inputfileref{input/templates,piano-dynamics.ly}.
2635 @cindex cross staff stem
2636 @cindex stem, cross staff
2639 @c fixme: should have hyperlinks as well.
2645 @node Automatic staff changes
2646 @subsection Automatic staff changes
2647 @cindex Automatic staff changes
2649 Voices can switch automatically between the top and the bottom
2650 staff. The syntax for this is
2652 \autochange Staff \context Voice @{ @dots{}@var{music}@dots{} @}
2654 The autochanger switches on basis of pitch (central C is the turning
2655 point), and it looks ahead skipping over rests to switch rests in
2656 advance. Here is a practical example:
2658 @lilypond[verbatim,singleline,quote]
2659 \score { \notes \context PianoStaff <
2660 \context Staff = "up" {
2661 \autochange Staff \context Voice = VA < \relative c' {
2662 g4 a b c d r4 a g } > }
2663 \context Staff = "down" {
2668 Spacer rests are used to prevent the bottom staff from
2669 terminating too soon.
2674 The staff switches often do not end up in optimal places. For high
2675 quality output staff switches should be specified manually.
2679 @node Manual staff switches
2680 @subsection Manual staff switches
2682 @cindex manual staff switches
2683 @cindex staff switch, manual
2685 Voices can be switched between staves manually, using the following command:
2687 \translator Staff = @var{staffname} @var{music}
2689 The string @var{staffname} is the name of the staff. It switches the
2690 current voice from its current staff to the Staff called
2691 @var{staffname}. Typically @var{staffname} is @code{"up"} or
2699 Pianos have pedals that alter the way sound are produced. Generally, a
2700 piano has three pedals, sustain, una corda, and sostenuto.
2704 Piano pedal instruction can be expressed by attaching
2705 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
2706 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
2709 The symbols that are printed can be modified by setting
2710 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
2711 Sustain, Sostenuto or UnaCorda. Refer to the generated documentation
2712 of @internalsref{SustainPedal} for more information.
2714 Pedals can also be indicated by a sequence of brackets, by setting the
2715 @code{pedal-type} property of @internalsref{SustainPedal} objects:
2717 @lilypond[fragment,verbatim]
2718 \property Staff.SustainPedal \override #'pedal-type = #'bracket
2719 c''4-\sustainDown d''4 e''4
2720 a'4-\sustainUp-\sustainDown
2721 f'4 g'4 a'4-\sustainUp
2724 A third style of pedal notation is a mixture of text and brackets,
2725 obtained by setting @code{pedal-type} to @code{mixed}:
2727 @lilypond[fragment,verbatim]
2728 \property Staff.SustainPedal \override #'pedal-type = #'mixed
2729 c''4-\sustainDown d''4 e''4
2730 c'4-\sustainUp-\sustainDown
2731 f'4 g'4 a'4-\sustainUp
2734 The default '*Ped' style for sustain and damper pedals corresponds to
2735 @code{\pedal-type = #'text}. However, @code{mixed} is the default style
2736 for a sostenuto pedal:
2738 @lilypond[fragment,verbatim]
2739 c''4-\sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4-\sostenutoUp
2742 For fine-tuning of the appearance of a pedal bracket, the properties
2743 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
2744 @code{PianoPedalBracket} objects (see the detailed documentation of
2745 @internalsref{PianoPedalBracket}) can be modified. For example, the bracket
2746 may be extended to the end of the note head.
2748 @lilypond[fragment,verbatim]
2749 \property Staff.PianoPedalBracket \override
2750 #'shorten-pair = #'(0 . -1.0)
2751 c''4-\sostenutoDown d''4 e''4 c'4
2752 f'4 g'4 a'4-\sostenutoUp
2756 @subsection Arpeggio
2759 @cindex broken arpeggio
2760 @cindex @code{\arpeggio}
2762 You can specify an arpeggio sign on a chord by attaching an
2763 @code{\arpeggio} to a chord.
2766 @lilypond[fragment,relative,verbatim]
2767 <<c e g c>>-\arpeggio
2770 When an arpeggio crosses staves in piano music, you attach an arpeggio
2771 to the chords in both staves, and set
2772 @internalsref{PianoStaff}.@code{connectArpeggios}.
2774 @lilypond[fragment,relative,verbatim]
2775 \context PianoStaff <
2776 \property PianoStaff.connectArpeggios = ##t
2777 \context Voice = one { <<c' e g c>>-\arpeggio }
2778 \context Voice = other { \clef bass <<c,, e g>>-\arpeggio }
2782 This command creates @internalsref{Arpeggio} objects. Cross staff
2783 arpeggios are @internalsref{PianoStaff}.@internalsref{Arpeggio}.
2785 The direction of the arpeggio is sometimes denoted by adding an
2786 arrowhead to the wiggly line. This can be typeset by setting
2787 @code{arpeggio-direction}.
2789 @lilypond[fragment,relative,verbatim]
2791 \property Voice.Arpeggio \set #'arpeggio-direction = #1
2792 <<c e g c>>-\arpeggio
2793 \property Voice.Arpeggio \set #'arpeggio-direction = #-1
2794 <<c e g c>>-\arpeggio
2798 A square bracket on the left indicates that the player should not
2799 arpeggiate the chord. To draw these brackets, set the
2800 @code{molecule-callback} property of @code{Arpeggio} or
2801 @code{PianoStaff.Arpeggio} objects to @code{\arpeggioBracket}, and use
2802 @code{\arpeggio} statements within the chords as before.
2804 @lilypond[fragment,relative,verbatim]
2805 \property PianoStaff.Arpeggio \override
2806 #'molecule-callback = \arpeggioBracket
2807 <<c' e g c>>-\arpeggio
2813 It is not possible to mix connected arpeggios and unconnected
2814 arpeggios in one @internalsref{PianoStaff} at the same time.
2816 @node Voice follower lines
2817 @subsection Voice follower lines
2820 [TODO: invent better name]
2822 @cindex follow voice
2823 @cindex staff switching
2826 @cindex @code{followVoice}
2828 Whenever a voice switches to another staff a line connecting the notes
2829 can be printed automatically. This is enabled if the property
2830 @code{PianoStaff.followVoice} is set to true:
2832 @lilypond[fragment,relative,verbatim]
2833 \context PianoStaff <
2834 \property PianoStaff.followVoice = ##t
2835 \context Staff \context Voice {
2837 \translator Staff=two
2840 \context Staff=two { \clef bass \skip 1*2 }
2844 The associated object is @internalsref{VoiceFollower}.
2848 @section Vocal music
2850 For a discussion of how to put lyrics into a score, see section
2851 @code{Printing lyrics} in the tutorial.
2853 [TODO: Move lyrics section from tutorial to here?]
2855 See also the sections on @ref{Slurs} and @ref{Breath marks}.
2857 [TODO: Move slurs / breath marks section to here?]
2859 [TODO: Write subsection upon usage of ChoirStaff.]
2861 For entering quotes in Lyrics mode, use the following
2863 "\"God\"" is "`King'"
2866 You can use empty syllables, e.g. @code{_4} or @code{" "4} to enter
2867 lyrics. This can confuse the LilyPond -- for example, this might put
2868 (empty) lyrics under rests. To remedy this, use @code{\skip}.
2879 The term @emph{ambitus} denotes a range of pitches for a given voice in
2880 a part of music. It also may denote the pitch range that a musical
2881 instrument is capable of playing. Most musical instruments have their
2882 ambitus standardized (or at least there is agreement upon the minimal
2883 ambitus of a particular type of instrument), such that a composer or
2884 arranger of a piece of music can easily meet the ambitus constraints of
2885 the targeted instrument. However, the ambitus of the human voice
2886 depends on individual physiological state, including education and
2887 training of the voice. Therefore, a singer potentially has to check for
2888 each piece of music if the ambitus of that piece meets his individual
2889 capabilities. This is why the ambitus of a piece may be of particular
2890 value to vocal performers.
2892 The ambitus is typically notated on a per-voice basis at the very
2893 beginning of a piece, e.g. nearby the initial clef or time signature of
2894 each staff. The range is graphically specified by two noteheads, that
2895 represent the minimum and maximum pitch. Some publishers use a textual
2896 notation: they put the range in words in front of the corresponding
2897 staff. Lilypond currently only supports the graphical ambitus notation.
2899 To apply, add the @internalsref{Ambitus_engraver} to the
2900 @internalsref{Voice} context, i.e.
2903 \paper @{ \translator @{
2905 \consists Ambitus_engraver
2911 @lilypond[singleline]
2912 upper = \notes \relative c {
2915 as'' c e2 bes f cis d4 e f2 g
2917 lower = \notes \relative c {
2920 e'4 b g a c es fis a cis b a g f e d2
2923 \context ChoirStaff {
2925 \context Staff = one { \upper }
2926 \context Staff = three { \lower }
2932 \consists Ambitus_engraver
2941 @internalsref{Ambitus}, @inputfileref{input/regression/,ambitus.ly}.
2946 Tablature notation is used for notating music for plucked string
2947 instruments. It notates pitches not by using note heads, but by
2948 indicating on which string and fret a note must be played. LilyPond
2949 offers limited support for tablature.
2952 * Tablatures basic::
2953 * Non-guitar tablatures::
2956 @node Tablatures basic
2957 @subsection Tablatures basic
2958 @cindex Tablatures basic
2960 The string number associated to a note is given as a backslash
2961 followed by a number, e.g. @code{c4\3} for a C quarter on the third
2962 string. By default, string 1 is the highest one, and the tuning
2963 defaults to the standard guitar tuning (with 6 strings). The notes
2964 are printed as tablature, by using @internalsref{TabStaff} and
2965 @internalsref{TabVoice} contexts.
2967 @lilypond[fragment,verbatim]
2968 \notes \context TabStaff {
2974 If you do not specify a string number then one is selected
2975 automatically: the first string that does not give a fret number less
2976 than @code{minimumFret} is selected. The default value for
2977 @code{minimumFret} is 0.
2981 e8 fis gis a b cis' dis' e'
2982 \property TabStaff.minimumFret = #8
2983 e8 fis gis a b cis' dis' e'
2988 e8 fis gis a b cis' dis' e'
2989 \property TabStaff.minimumFret = #8
2990 e8 fis gis a b cis' dis' e'
2993 \context StaffGroup <
2994 \context Staff { \clef "G_8" \frag }
2995 \context TabStaff { \frag }
3002 @internalsref{TabStaff}, @internalsref{TabVoice}
3006 Chords are not handled in a special way, and hence the automatic
3007 string selector may easily select the same string to two notes in a
3011 @node Non-guitar tablatures
3012 @subsection Non-guitar tablatures
3013 @cindex Non-guitar tablatures
3015 You can change the number of strings, by setting the number of lines
3016 in the @internalsref{TabStaff} (the @code{line-count} property of
3017 @internalsref{TabStaff} can only be changed using
3018 @code{\outputproperty}, for more information, see @ref{Tuning per
3021 You can change the tuning of the strings. A string tuning is given as
3022 a Scheme list with one integer number for each string, the number
3023 being the pitch (measured in semitones relative to central C) of an
3024 open string. The numbers specified for @code{stringTuning} are the
3025 numbers of semitones to subtract or add, starting the specified pitch
3026 by default middle C, in string order: thus the notes are e, a, d, and
3029 @lilypond[fragment,verbatim]
3032 \outputproperty #(make-type-checker 'staff-symbol-interface)
3034 \property TabStaff.stringTunings = #'(-5 -10 -15 -20)
3037 a,4 c' a e' e c' a e'
3042 Finally, it is possible to change the Scheme function to format the
3043 tablature note text. The default is
3044 @var{fret-number-tablature-format}, which uses the fret number. For
3045 some instruments that do not use this notation, you can create a
3046 special tablature formatting function. This function takes three
3047 argument: the string number, the string tuning and the note pitch.
3051 As tablature is a recent feature, most of the guitar special effects
3052 such as bend are not yet supported.
3059 LilyPond has support for both entering and printing chords.
3060 @lilypond[verbatim,singleline]
3061 twoWays = \notes \transpose c c' {
3071 < \context ChordNames \twoWays
3072 \context Voice \twoWays > }
3075 This example also shows that the chord printing routines do not try to
3076 be intelligent. If you enter @code{f bes d}, it does not interpret
3077 this as an inversion.
3079 Chords are represented as a set of pitches. They are internally
3080 stored as simultaneous music expressions. This means you can enter
3081 chords by name and print them as notes, enter them as notes and print
3082 them as chord names, or (the most common case) enter them by name, and
3087 * Printing chord names::
3092 @subsection Chords mode
3095 Chord mode is a mode where you can input sets of pitches using common
3096 names. It is introduced by the keyword @code{\chords}.
3097 In chords mode, a chord is entered by the root, which is entered
3098 like a common pitch, for example,
3099 @lilypond[fragment,verbatim,quote, relative=1]
3100 \chords { es4. d8 c2 }
3105 Other chords may be entered by suffixing a colon, and introducing a
3106 modifier, and optionally, a number, for example
3108 @lilypond[fragment,verbatim,quote]
3109 \chords { e1:m e1:7 e1:m7 }
3111 The first number following the root is taken to be the `type' of the
3112 chord, thirds are added to the root until it reaches the specified
3113 number, for example.
3114 @lilypond[fragment,verbatim]
3115 \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }
3118 @cindex root of chord
3119 @cindex additions, in chords
3120 @cindex removals, in chords
3122 More complex chords may also be constructed adding separate steps
3123 to a chord. Additions are added after the number following
3124 the colon, and are separated by dots. For example
3126 @lilypond[verbatim,fragment,quote]
3127 \chords { c:5.6 c:3.7.8 c:3.6.13 }
3129 Chord steps can be altered by suffixing a @code{-} or @code{+} sign
3130 to the number, for example:
3131 @lilypond[verbatim,fragment,quote]
3132 \chords { c:7+ c:5+.3- c:3-.5-.7- }
3134 Removals are specified similarly, and are introduced by a caret. They
3135 must come after the additions.
3136 @lilypond[verbatim,fragment]
3137 \chords { c^3 c:7^5 c:9^3.5 }
3140 Modifiers can be used to change pitches. The following modifiers are
3144 is the minor chord. This modifier lowers the 3rd and (if present) the 7th step.
3146 is the diminished chord. This modifier lowers the 3rd, 5th and (if present)
3149 is the augmented chord. This modifier raises the 5th step.
3151 is the major 7th chord. This modifier raises the 7th step if present.
3153 is the suspended 4th or 2nd. This modifier removes the 3rd
3154 step. Append either @code{2} or @code{4} to add the 2nd or 4th step to
3157 Modifiers can be mixed with additions.
3158 @lilypond[verbatim,fragment]
3159 \chords { c:sus4 c:7sus4 c:dim7 c:m6 }
3162 @cindex modifiers, in chords.
3169 Since the unaltered 11 does sound well when combined with the
3170 unaltered 3, the 11 is removed in this case, unless it is added
3171 explicitly). For example,
3172 @lilypond[fragment,verbatim]
3173 \chords { c:13 c:13.11 c:m13 }
3178 An inversion (putting one pitch of the chord on the bottom), as well
3179 as bass notes, can be specified by appending
3180 @code{/}@var{pitch} to the chord.
3181 @lilypond[fragment,verbatim,center]
3182 \chords { c1 c/g c/f }
3185 If you do not want to remove the bass note from the chord, but rather
3186 add the note, then you can use @code{/+}@var{pitch}.
3188 @lilypond[fragment,verbatim,center]
3189 \chords { c1 c/+g c/+f }
3192 Chords is a mode similar to @code{\lyrics}, @code{\notes} etc. Most
3193 of the commands continue to work, for example, @code{r} and
3194 @code{\skip} can be used to insert rests and spaces, and
3195 @code{\property} may be used to change various settings.
3201 Each step can only be present in a chord once. The following
3202 simply produces the augmented chord, since @code{5+} is interpreted
3205 @lilypond[verbatim,fragment]
3206 \chords { c:5.5-.5+ }
3209 In chord mode, dashes and carets are used to indicate chord additions
3210 and subtractions, so articulation scripts can not be entered.
3213 @node Printing chord names
3214 @subsection Printing chord names
3216 @cindex printing chord names
3220 For displaying printed chord names, use the @internalsref{ChordNames} context.
3221 The chords may be entered either using the notation described above, or
3222 directly using simultaneous music.
3224 @lilypond[verbatim,singleline]
3226 \chords {a1 b c} <<d f g>> <<e g b>>
3230 \context ChordNames \scheme
3231 \context Staff \transpose c c' \scheme
3236 You can make the chord changes stand out by setting
3237 @internalsref{ChordNames}.@code{chordChanges} to true. This will only
3238 display chord names when there is a change in the chords scheme and at
3239 the start of a new line.
3243 c1:m c:m \break c:m c:m d
3247 \context ChordNames {
3248 \property ChordNames.chordChanges = ##t
3250 \context Staff \transpose c c' \scheme
3252 \paper{linewidth= 9.\cm}
3256 The default chord name layout is a system for Jazz music, proposed by
3257 Klaus Ignatzek (See @ref{Literature}).
3259 [TODO: add description for banter other jazz.]
3261 The Ignatzek chord name formatting can be tuned in a number of ways
3262 through the following properties:
3264 @item chordNameExceptions
3265 This is a list that contains the chords that have special formatting.
3267 @inputfileref{input/regression/,chord-name-exceptions.ly}.
3269 @item majorSevenSymbol
3270 This property contains the markup object used for the 7th step, when
3271 it is major. Predefined options are @code{whiteTriangleMarkup},
3272 @code{blackTriangleMarkup}. See
3273 @inputfileref{input/regression/,chord-name-major7.ly} for an example.
3275 @item chordNameSeparator
3276 Different parts of a chord name are normally separated by a
3277 slash. By setting @code{chordNameSeparator}, you can specify other
3279 @lilypond[fragment,verbatim]
3280 \context ChordNames \chords {
3282 \property ChordNames.chordNameSeparator
3287 @item chordRootNamer
3288 The root of a chord is usually printed as a letter with an optional
3289 alteration. The transformation from pitch to letter is done by this
3290 function. An application of setting this function, is providing chord
3291 names with german notation for the root.
3293 @item chordNoteNamer
3294 The default is to print single notes (as for instance the bass note)
3295 using the chordRootNamer. However, by setting this function to a non-null
3296 value you can specify a different function. I.e. you could use letters
3297 in lower case for the base note.
3303 @inputfileref{input/regression/,chord-name-major7.ly},
3304 @inputfileref{input/regression/,chord-name-exceptions.ly},
3305 @file{scm/chords-ignatzek.scm}, @file{scm/chord-entry.scm}
3310 Chord names are determined solely from the list of pitches. Chord
3311 inversions are not identified, and neither are added bass notes. This
3312 may result in strange chord names when chords are entered with the
3313 @code{<< .. >>} syntax.
3319 @section Writing parts
3321 Orchestral music involves some special notation, both in the full score,
3322 as in the individual parts. This section explains how to tackle common
3323 problems in orchestral music.
3330 * Instrument names::
3332 * Multi measure rests::
3333 * Automatic part combining::
3334 * Hara kiri staves::
3335 * Sound output for transposing instruments::
3339 @node Rehearsal marks
3340 @subsection Rehearsal marks
3341 @cindex Rehearsal marks
3343 @cindex @code{\mark}
3345 To print a rehearsal mark, use the @code{\mark} command.
3346 @lilypond[fragment,verbatim]
3356 The mark is incremented automatically if you use @code{\mark
3357 \default}. The value to use is stored in the property
3358 @code{rehearsalMark} is used and automatically incremented.
3360 The @code{\mark} command can also be used to put signs like coda,
3361 segno and fermatas on a barline. Use @code{\markup} to
3362 to access the appropriate symbol.
3364 @lilypond[fragment,verbatim,relative=1]
3365 c1 \mark \markup { \musicglyph #"scripts-ufermata" }
3369 In this case, during line breaks,
3370 marks must also be printed at the end of the line, and not at the
3371 beginning. Use the following to force that behavior
3373 \property Score.RehearsalMark \override
3374 #'break-visibility = #begin-of-line-invisible
3380 @cindex barlines, putting symbols on
3384 The object is @internalsref{RehearsalMark} in @internalsref{Score}
3385 context. See @inputfileref{input/test,boxed-molecule.ly} for putting
3386 boxes around the marks.
3390 @subsection Bar numbers
3394 @cindex measure numbers
3395 @cindex currentBarNumber
3397 Bar numbers are printed by default at the start of the line. The
3398 number itself is stored in the
3399 @code{currentBarNumber} property,
3400 which is normally updated automatically for every measure.
3402 Bar numbers can be typeset at regular intervals instead of at the
3403 beginning of each line. This is illustrated in the following example,
3404 whose source is available as
3405 @inputfileref{input/test/,bar-number-every-fifth.ly}
3407 @lilypondfile[notexidoc]{bar-number-every-fifth.ly}
3409 The start of that numbering can also be reset, as demonstrated in
3410 @inputfileref{input/test/,bar-number-every-5-reset.ly}.
3412 @lilypondfile[notexidoc]{bar-number-every-5-reset.ly}
3417 @internalsref{BarNumber}.
3418 @inputfileref{input/test/,bar-number-every-5-reset.ly}.
3419 @inputfileref{input/test/,bar-number-every-fifth.ly}
3423 Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
3424 there is one at the top. To solve this, You have to twiddle with the
3425 @internalsref{padding} property of @internalsref{BarNumber} if your
3426 score starts with a @internalsref{StaffGroup}.
3428 @node Instrument names
3429 @subsection Instrument names
3431 In an orchestral score, instrument names are printed left of the
3434 This can be achieved by setting @internalsref{Staff}.@code{instrument}
3435 and @internalsref{Staff}.@code{instr}. This will print a string before
3436 the start of the staff. For the first start, @code{instrument} is
3437 used, for the next ones @code{instr} is used.
3439 @lilypond[verbatim,singleline]
3440 \property Staff.instrument = "ploink " { c''4 }
3443 You can also use markup texts to construct more complicated instrument
3446 @lilypond[fragment,verbatim,singleline]
3447 \notes \context Staff = treble {
3448 \property Staff.instrument = \markup {
3449 \column << "Clarinetti"
3451 \smaller \musicglyph #"accidentals--1"
3462 When you put a name on a grand staff or piano staff the width of the
3463 brace is not taken into account. You must add extra spaces to the end of
3464 the name to avoid a collision.
3467 @subsection Transpose
3469 @cindex transposition of pitches
3470 @cindex @code{\transpose}
3472 A music expression can be transposed with @code{\transpose}. The syntax
3475 \transpose @var{from} @var{to} @var{musicexpr}
3478 This means that @var{musicexpr} is transposed by the interval
3479 between @var{from} and @var{to}.
3481 @code{\transpose} distinguishes between enharmonic pitches: both
3482 @code{\transpose c cis} or @code{\transpose c des} will transpose up
3483 half a tone. The first version will print sharps and the second
3484 version will print flats.
3486 @lilypond[singleline, verbatim]
3487 mus =\notes { \key d \major cis d fis g }
3488 \score { \notes \context Staff {
3491 \transpose c g' \mus
3492 \transpose c f' \mus
3498 If you want to use both @code{\transpose} and @code{\relative}, then
3499 you must put @code{\transpose} outside of @code{\relative}, since
3500 @code{\relative} will have no effect music that appears inside a
3504 @node Multi measure rests
3505 @subsection Multi measure rests
3506 @cindex Multi measure rests
3510 Multi measure rests are entered using `@code{R}'. It is specifically
3511 meant for full bar rests and for entering parts: the rest can expand to
3512 fill a score with rests, or it can be printed as a single multimeasure
3513 rest. This expansion is controlled by the property
3514 @code{Score.skipBars}. If this is set to true, Lily will not expand
3515 empty measures, and the appropriate number is added automatically.
3517 @lilypond[fragment,verbatim]
3518 \time 4/4 r1 | R1 | R1*2
3519 \property Score.skipBars = ##t R1*17 R1*4
3522 The @code{1} in @code{R1} is similar to the duration notation used for
3523 notes. Hence, for time signatures other than 4/4, you must enter other
3524 durations. This can be done with augmentation dots or fractions:
3526 @lilypond[fragment,verbatim]
3527 \property Score.skipBars = ##t
3535 A @code{R} spanning a single measure is printed as a whole rest
3536 centered in the measure (or a breve when the measure lasts longer than
3537 two whole notes), regardless of the time signature.
3541 @cindex text on multi-measure rest
3542 @cindex script on multi-measure rest
3543 @cindex fermata on multi-measure rest
3545 Texts can be added to multi-measure rests by using the
3546 @var{note}-@code{markup} syntax. In this case, the number is
3547 replaced. If you need both texts and the number, you must add the
3548 number by hand. An identifier (@code{fermataMarkup}) is provided for
3552 @lilypond[verbatim,fragment]
3554 R2._\markup { "Ad lib" }
3559 @cindex whole rests for a full measure
3563 The object for this object is @internalsref{MultiMeasureRest},
3564 @internalsref{MultiMeasureRestNumber} (for the default number), and
3565 @internalsref{MultiMeasureRestText} (for user specified texts).
3569 It is not possible to use fingerings (e.g. @code{R1-4}) to put numbers
3570 over multi-measure rests.
3572 @cindex condensing rests
3574 There is no way to automatically condense multiple rests into a single
3575 multimeasure rest. Multi measure rests do not take part in rest
3578 Be careful when entering multimeasure rests followed by whole notes,
3582 will enter two notes lasting four measures each. The result will look
3583 ok, but the bar numbering will be off.
3585 @node Automatic part combining
3586 @subsection Automatic part combining
3587 @cindex automatic part combining
3588 @cindex part combiner
3591 Automatic part combining is used to merge two parts of music onto a
3592 staff. It is aimed at typesetting orchestral scores. When the two
3593 parts are identical for a period of time, only one is shown. In
3594 places where the two parts differ, they are typeset as separate
3595 voices, and stem directions are set automatically. Also, solo and
3596 @emph{a due} parts are identified and can be marked.
3600 The syntax for part combining is
3603 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
3605 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
3606 combined into one context of type @var{context}. The music expressions
3607 must be interpreted by contexts whose names should start with @code{one}
3610 The following example demonstrates the basic functionality of the part
3611 combiner: putting parts on one staff, and setting stem directions and
3614 @lilypond[verbatim,singleline,fragment]
3616 \context Voice=one \partcombine Voice
3617 \context Thread=one \relative c'' {
3620 \context Thread=two \relative c'' {
3626 The first @code{g} appears only once, although it was
3627 specified twice (once in each part). Stem, slur and tie directions are
3628 set automatically, depending whether there is a solo or unisono. The
3629 first part (with context called @code{one}) always gets up stems, and
3630 `solo', while the second (called @code{two}) always gets down stems and
3633 If you just want the merging parts, and not the textual markings, you
3634 may set the property @var{soloADue} to false.
3636 @lilypond[verbatim,singleline,fragment]
3638 \property Staff.soloADue = ##f
3639 \context Voice=one \partcombine Voice
3640 \context Thread=one \relative c'' {
3643 \context Thread=two \relative c'' {
3651 Look at the documentation of the responsible engravers,
3652 @code{Thread_devnull_engraver}, @code{Voice_devnull_engraver} and
3657 The syntax for naming contexts in inconsistent with the syntax for
3660 In @code{soloADue} mode, when the two voices play the same notes on and
3661 off, the part combiner may typeset @code{a2} more than once in a
3664 @lilypond[fragment,singleline]
3666 \context Voice=one \partcombine Voice
3667 \context Thread=one \relative c'' {
3670 \context Thread=two \relative c'' {
3676 The part combiner is slated to be rewritten [TODO: explain why] .
3678 @cindex @code{Thread_devnull_engraver}
3679 @cindex @code{Voice_engraver}
3680 @cindex @code{A2_engraver}
3682 @node Hara kiri staves
3683 @subsection Hara kiri staves
3685 In orchestral scores, staff lines that only have rests are usually removed.
3686 This saves some space. This style is called `French Score'.
3690 This is supported through the hara kiri@footnote{Hara kiri is the
3691 vulgar name for Seppuku, is the ritual suicide of the Japanese
3692 Samourai warriors.} staff. This staff commits suicide when it finds
3693 itself to be empty after the line-breaking process. It will not
3694 disappear when it contains normal rests, you must use multi measure
3697 For @internalsref{Lyrics}, @internalsref{LyricsVoice},
3698 @internalsref{ChordNames} and @internalsref{FiguredBass}, hara-kiri is
3699 switched on by default. For normal staffs, hara kiri is available as a
3700 specialized @internalsref{Staff} context, with the name identifier
3701 @code{\HaraKiriStaffContext}. Observe how the second staff in this
3702 example disappears in the second line.
3706 \notes \relative c' <
3707 \context Staff = SA { e4 f g a \break c1 }
3708 \context Staff = SB { c4 d e f \break R1 }
3712 \translator { \HaraKiriStaffContext }
3718 @node Sound output for transposing instruments
3719 @subsection Sound output for transposing instruments
3721 When you want to make a MIDI file from a score containing transposed
3722 and untransposed instruments, you have to instruct LilyPond the pitch
3723 offset (in semitones) for the transposed instruments. This is done
3724 using the @code{transposing} property. It does not affect printed
3727 @cindex @code{transposing}
3730 \property Staff.instrument = #"Cl. in B-flat"
3731 \property Staff.transposing = #-2
3735 @node Ancient notation
3736 @section Ancient notation
3738 @cindex Vaticana, Editio
3739 @cindex Medicaea, Editio
3744 [TODO: write introduction on ancient notation]
3747 * Ancient note heads::
3756 @node Ancient note heads
3757 @subsection Ancient note heads
3759 To get a longa note head, you have to use mensural note heads. This
3760 is accomplished by setting the @code{style} property of the
3761 NoteHead object to @code{mensural}. There is also a note head style
3762 @code{baroque} which gives mensural note heads for @code{\longa} and
3763 @code{\breve} but standard note heads for shorter notes.
3765 @lilypond[fragment,singleline,verbatim]
3766 \property Voice.NoteHead \set #'style = #'mensural
3771 @subsection Ancient clefs
3773 LilyPond supports a variety of clefs, many of them ancient.
3775 For modern clefs, see section @ref{Clef}. For the percussion clef, see
3776 section @ref{Percussion staves}. For the @code{TAB} clef, see section
3779 The following table shows all ancient clefs that are supported via the
3780 @code{\clef} command. Some of the clefs use the same glyph, but differ
3781 only with respect to the line they are printed on. In such cases, a
3782 trailing number in the name is used to enumerate these clefs. Still,
3783 you can manually force a clef glyph to be typeset on an arbitrary line,
3784 as described in section @ref{Clef}. The note printed to the right side
3785 of each clef denotes the @code{c'} with respect to the clef.
3789 @c --- This should go somewhere else: ---
3790 @c @item modern style G clef (glyph: @code{clefs-G})
3793 @c @code{treble}, @code{violin}, @code{G}, @code{G2}, @code{french}
3795 @c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "G" c'}
3797 @c @item modern style F clef (glyph: @code{clefs-F})
3800 @c @code{varbaritone}, @code{bass}, @code{F}, @code{subbass}
3802 @c @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "F" c'}
3804 @c @item modern style C clef (glyph: @code{clefs-C})
3807 @c @code{soprano}, @code{mezzosoprano}, @code{alto}, @code{C},
3808 @c @code{tenor}, @code{baritone}
3810 @c @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "C" c'}
3812 @item modern style mensural C clef (glyph: @code{clefs-neo_mensural_c'})
3815 @code{neo_mensural_c1}, @code{neo_mensural_c2},
3816 @code{neo_mensural_c3}, @code{neo_mensural_c4}
3818 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "neo_mensural_c2" c'}
3820 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c1})
3826 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c1" c'}
3828 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c2})
3834 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c2" c'}
3836 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c3})
3842 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c3" c'}
3844 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c4})
3850 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c4" c'}
3852 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c5})
3858 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c5" c'}
3860 @item petrucci style mensural F clef (glyph: @code{clefs-petrucci_f})
3865 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_f" c'}
3867 @item petrucci style mensural G clef (glyph: @code{clefs-petrucci_g})
3872 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_g" c'}
3874 @item historic style mensural C clef (glyph: @code{clefs-mensural_c'})
3877 @code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3},
3880 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_c2" c'}
3882 @item historic style mensural F clef (glyph: @code{clefs-mensural_f})
3887 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_f" c'}
3889 @item historic style mensural G clef (glyph: @code{clefs-mensural_g})
3894 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_g" c'}
3896 @item Editio Vaticana style do clef (glyph: @code{clefs-vaticana_do})
3899 @code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3}
3901 @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_do2" c'}
3903 @item Editio Vaticana style fa clef (glyph: @code{clefs-vaticana_fa})
3906 @code{vaticana_fa1}, @code{vaticana_fa2}
3908 @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_fa2" c'}
3910 @item Editio Medicaea style do clef (glyph: @code{clefs-medicaea_do})
3913 @code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3}
3915 @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_do2" c'}
3917 @item Editio Medicaea style fa clef (glyph: @code{clefs-medicaea_fa})
3920 @code{medicaea_fa1}, @code{medicaea_fa2}
3922 @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_fa2" c'}
3924 @item historic style hufnagel do clef (glyph: @code{clefs-hufnagel_do})
3927 @code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3}
3929 @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do2" c'}
3931 @item historic style hufnagel fa clef (glyph: @code{clefs-hufnagel_fa})
3934 @code{hufnagel_fa1}, @code{hufnagel_fa2}
3936 @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_fa2" c'}
3938 @item historic style hufnagel combined do/fa clef (glyph: @code{clefs-hufnagel_do_fa})
3941 @code{hufnagel_do_fa}
3943 @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do_fa" c'}
3945 @c --- This should go somewhere else: ---
3946 @c @item modern style percussion clef (glyph: @code{clefs-percussion})
3949 @c @code{percussion}
3951 @c @lilypond{\property Staff.TimeSignature \set #'transparent = ##t \clef "percussion" c'}
3953 @c @item modern style tab clef (glyph: @code{clefs-tab})
3958 @c @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #6 \property Staff.TimeSignature \set #'transparent = ##t \clef "tab" c'}
3962 @emph{Modern style} means ``as is typeset in current editions of
3963 transcribed mensural music''.
3965 @emph{Petrucci style} means ``inspired by printings published by the
3966 famous engraver Petrucci (1466-1539)''.
3968 @emph{Historic style} means ``as was typeset or written in contemporary
3969 historic editions (other than those of Petrucci)''.
3971 @emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
3973 Petrucci used C clefs with differently balanced left-side vertical
3974 beams, depending on which staffline it was printed.
3978 @subsection Custodes
3983 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
3984 staff context symbol that appears at the end of a staff line. It
3985 anticipates the pitch of the first note(s) of the following line and
3986 thus helps the player or singer to manage line breaks during
3987 performance, thus enhancing readability of a score.
3992 \property Staff.Custos \set #'style = #'mensural
3997 \consists Custos_engraver
4003 Custodes were frequently used in music notation until the 17th century.
4004 There were different appearances for different notation styles.
4005 Nowadays, they have survived only in special forms of musical notation
4006 such as via the @emph{editio vaticana} dating back to the beginning of
4009 For typesetting custodes, just put a @code{Custos_engraver} into the
4010 Staff context when declaring the @code{\paper} block, as shown in the
4011 following example. In the @code{\paper} block, you can also globally
4012 control the appearance of the custos symbol by setting the custos
4013 @code{style} property.
4019 \consists Custos_engraver
4020 Custos \override #'style = #'mensural
4025 The property can also be set locally, for example in a @code{\notes}
4030 \property Staff.Custos \override #'style = #'vaticana
4031 c'1 d' e' d' \break c' d' e' d'
4035 Currently, the following styles are supported:
4042 ^\markup { "vaticana" }
4043 ^\markup { \musicglyph #"custodes-vaticana-u0" }
4045 ^\markup { "medicaea" }
4046 ^\markup { \musicglyph #"custodes-medicaea-u0" }
4048 ^\markup { "hufnagel" }
4049 ^\markup { \musicglyph #"custodes-hufnagel-u0" }
4051 ^\markup { "mensural" }
4052 ^\markup { \musicglyph #"custodes-mensural-u0" }
4059 \remove "Bar_number_engraver"
4060 TextScript \override #'extra-X-extent = #'(-1 . 1)
4064 \remove "Clef_engraver"
4065 \remove "Key_engraver"
4066 \remove "Time_signature_engraver"
4067 \remove "Staff_symbol_engraver"
4068 minimumVerticalExtent = ##f
4074 If the boolean property @code{adjust-if-on-staffline} is set to
4075 @code{#t} (which it is by default), lily typesets slightly different
4076 variants of the custos glyph, depending on the pitch of the custos,
4077 i.e. depending on the glyph being typeset either on a staffline or
4078 between two stafflines. The idea is that the glyph will optically fit
4079 well into the staff, with the appendage on the right of the custos
4080 always ending at the same vertical position between two stafflines
4081 regardless of the pitch. If you set @code{adjust-if-on-staffline} to
4082 @code{#f}, then lily takes regardless of the pitch always a glyph that
4083 is a compromise of the former two variants.
4085 Just like stems can be attached to noteheads in two directions
4086 @emph{up} and @emph{down}, each custos glyph is available with its
4087 appendage pointing either up or down. If the pitch of a custos is
4088 above a selectable position, the appendage will point downwards; if
4089 the pitch is below this position, the appendage will point upwards.
4090 Use property @code{neutral-position} to select this position. By
4091 default, it is set to @code{0}, such that the neutral position is the
4092 center of the staff. Use property @code{neutral-direction} to control
4093 what happens if a custos is typeset on the neutral position itself.
4094 By default, this property is set to @code{-1}, such that the appendage
4095 will point downwards. If set to @code{1}, the appendage will point
4096 upwards. Other values such as @code{0} are reserved for future
4097 extensions and should not be used.
4103 \property Staff.Custos \set #'neutral-position = #4
4104 \property Staff.Custos \set #'neutral-direction = #-1
4105 \property Staff.Custos \set #'adjust-if-on-staffline = ##t
4113 @subsection Divisiones
4119 A @emph{divisio} (plural: @emph{divisiones}; latin word for
4120 `division') is a staff context symbol that is used to structure
4121 Gregorian music into phrases and sections. The musical meaning of
4122 @emph{divisio minima}, @emph{divisio maior} and @emph{divisio maxima}
4123 can be characterized as short, medium and long pause, somewhat like
4124 @ref{Breath marks}. The @emph{finalis} sign not only marks the end of
4125 a chant, but is also frequently used within a single
4126 antiphonal/responsorial chant to mark the end of each section.
4128 To use divisiones, just include the file @code{gregorian-init.ly}. It
4129 contains definitions that you can apply by just inserting
4130 @code{\divisiominima}, @code{\divisiomaior}, @code{\divisiomaxima},
4131 and @code{\finalis} at proper places into your lilypond files.
4134 \include "gregorian-init.ly"
4137 \context Staff = staff \addlyrics \notes \transpose c c' {
4138 \property Score.timing = ##f
4139 \property Score.barAlways = ##t
4140 \property Staff.BarLine \override #'transparent = ##t
4141 \property Voice.Stem \override #'transparent = ##t
4143 ^\markup { "divisio minima" }
4146 ^\markup { "divisio maior" }
4149 ^\markup { "divisio maxima" }
4152 ^\markup { "finalis" }
4156 \context Lyrics = lyrics \lyrics {
4157 Blah blub, blah blam.
4158 Blah blub, blah blam.
4159 Blah blub, blah blam.
4160 Blah blub, blah blam.
4161 Blah blub, blah blam.
4167 Some editions use @emph{virgula} or @emph{caesura} instead of divisio
4168 minima. Therefore, @code{gregorian-init.ly} also defines
4169 @code{\virgula} and @code{\caesura}.
4172 \include "gregorian-init.ly"
4175 \context Staff = staff \addlyrics \notes \transpose c c' {
4176 \property Score.timing = ##f
4177 \property Score.barAlways = ##t
4178 \property Staff.BarLine \override #'transparent = ##t
4179 \property Voice.Stem \override #'transparent = ##t
4181 ^\markup { "virgula" }
4184 ^\markup { "caesura" }
4188 \context Lyrics = lyrics \lyrics {
4189 Blah blub, blah blam.
4190 Blah blub, blah blam.
4191 Blah blub, blah blam.
4198 @subsection Ligatures
4202 @c TODO: Should double check if I recalled things correctly when I wrote
4203 @c down the following paragraph by heart.
4204 In musical terminology, a ligature is a coherent graphical symbol that
4205 represents at least two different notes. Ligatures originally appeared
4206 in the manuscripts of Gregorian chant notation roughly since the 9th
4207 century as an allusion to the accent symbols of greek lyric poetry to
4208 denote ascending or descending sequences of notes. Both, the shape and
4209 the exact meaning of ligatures changed tremendously during the following
4210 centuries: In early notation, ligatures where used for monophonic tunes
4211 (Gregorian chant) and very soon denoted also the way of performance in
4212 the sense of articulation. With upcoming multiphony, the need for a
4213 metric system arised, since multiple voices of a piece have to be
4214 synchronized some way. New notation systems were invented, that used
4215 the manifold shapes of ligatures to now denote rhythmical patterns
4216 (e.g. black mensural notation, mannered notation, ars nova). With the
4217 invention of the metric system of the white mensural notation, the need
4218 for ligatures to denote such patterns disappeared. Nevertheless,
4219 ligatures were still in use in the mensural system for a couple of
4220 decades until they finally disappeared during the late 16th / early 17th
4221 century. Still, ligatures have survived in contemporary editions of
4222 Gregorian chant such as the Editio Vaticana from 1905/08.
4224 Syntactically, ligatures are simply enclosed by @code{\[} and @code{\]}.
4225 Some ligature styles (such as Editio Vaticana) may need additional input
4226 syntax specific for this particular type of ligature. By default, the
4227 @internalsref{LigatureBracket} engraver just marks the start and end of
4228 a ligature by small square angles:
4230 @lilypond[singleline,verbatim]
4232 \notes \transpose c c' {
4240 To select a specific style of ligatures, a proper ligature engraver has
4241 to be added to the @internalsref{Voice} context, as explained in the
4242 following subsections. Currently, Lilypond only supports white mensural
4243 ligatures with certain limitations. Support for Editio Vaticana will be
4244 added in the future.
4247 * White mensural ligatures::
4250 @node White mensural ligatures
4251 @subsubsection White mensural ligatures
4253 @cindex Mensural ligatures
4254 @cindex White mensural ligatures
4256 Lilypond has limited support for white mensural ligatures. The
4257 implementation is still experimental; it currently may output strange
4258 warnings or even crash in some cases or produce weird results on more
4259 complex ligatures. To engrave white mensural ligatures, in the paper
4260 block the @internalsref{MensuralLigature} engraver has to be put into
4261 the @internalsref{Voice} context (and you probably want to remove the
4262 @internalsref{LigatureBracket} engraver). There is no additional input
4263 language to describe the shape of a white mensural ligature. The shape
4264 is rather determined solely from the pitch and duration of the enclosed
4265 notes. While this approach may take a new user quite a while to get
4266 accustomed, it has a great advantage: this way, lily has full musical
4267 information about the ligature. This is not only required for correct
4268 MIDI output, but also allows for automatic transcription of the
4273 @lilypond[singleline,verbatim]
4275 \notes \transpose c c' {
4276 \property Score.timing = ##f
4277 \property Score.defaultBarType = "empty"
4278 \property Voice.NoteHead \set #'style = #'neo_mensural
4279 \property Staff.TimeSignature \set #'style = #'neo_mensural
4281 \[ g\longa c\breve a\breve f\breve d'\longa \]
4283 \[ e1 f1 a\breve g\longa \]
4288 \remove Ligature_bracket_engraver
4289 \consists Mensural_ligature_engraver
4295 Without replacing @code{Ligature_bracket_engraver} with
4296 @code{Mensural_ligature_engraver}, the same music transcribes to the
4299 @lilypond[singleline,verbatim]
4301 \notes \transpose c c' {
4302 \property Score.timing = ##f
4303 \property Score.defaultBarType = "empty"
4304 \property Voice.NoteHead \set #'style = #'neo_mensural
4305 \property Staff.TimeSignature \set #'style = #'neo_mensural
4307 \[ g\longa c\breve a\breve f\breve d'\longa \]
4309 \[ e1 f1 a\breve g\longa \]
4315 @subsection Figured bass
4317 @cindex Basso continuo
4319 LilyPond has limited support for figured bass:
4321 @lilypond[verbatim,fragment]
4323 \context Voice \notes { \clef bass dis4 c d ais}
4324 \context FiguredBass
4326 < 6 >4 < 7 >8 < 6+ [_!] >
4332 The support for figured bass consists of two parts: there is an input
4333 mode, introduced by @code{\figures}, where you can enter bass figures
4334 as numbers, and there is a context called @internalsref{FiguredBass}
4335 that takes care of making @internalsref{BassFigure} objects.
4337 In figures input mode, a group of bass figures is delimited by
4338 @code{<} and @code{>}. The duration is entered after the @code{>}.
4343 \context FiguredBass
4347 Accidentals are added to the numbers if you alterate them by
4348 appending @code{-}, @code{!} and @code{+}.
4354 \context FiguredBass
4355 \figures { <4- 6+ 7!> }
4358 Spaces or dashes may be inserted by using @code{_}. Brackets are
4359 introduced with @code{[} and @code{]}.
4365 \context FiguredBass
4366 \figures { < [4 6] 8 [_ 12]> }
4369 Although the support for figured bass may superficially resemble chord
4370 support, it works much simpler: in figured bass simply stores the
4371 numbers, and then prints the numbers you entered. There is no
4372 conversion to pitches, and no realizations of the bass are played in
4375 Internally, the code produces markup texts internally. You can use any
4376 of the markup text properties to override formatting. For example, the
4377 vertical spacing of the figures may be set with @code{baseline-skip}.
4380 @node Contemporary notation
4381 @section Contemporary notation
4389 @subsection Clusters
4393 In musical terminology, a @emph{cluster} denotes a range of
4394 simultaneously sounding pitches that may change over time. The set of
4395 available pitches to apply usually depends on the accoustic source.
4396 Thus, in piano music, a cluster typically consists of a continous range
4397 of the semitones as provided by the piano's fixed set of a chromatic
4398 scale. In choral music, each singer of the choir typically may sing an
4399 arbitrary pitch within the cluster's range that is not bound to any
4400 diatonic, chromatic or other scale. In electronic music, a cluster
4401 (theoretically) may even cover a continuous range of pitches, thus
4402 resulting in coloured noise, such as pink noise.
4404 Clusters can be notated in the context of ordinary staff notation by
4405 engraving simple geometrical shapes that replace ordinary notation of
4406 notes. Ordinary notes as musical events specify starting time and
4407 duration of pitches; however, the duration of a note is expressed by the
4408 shape of the note head rather than by the horizontal graphical extent of
4409 the note symbol. In contrast, the shape of a cluster geometrically
4410 describes the development of a range of pitches (vertical extent) over
4411 time (horizontal extent). Still, the geometrical shape of a cluster
4412 covers the area in wich any single pitch contained in the cluster would
4413 be notated as an ordinary note. From this point of view, it is
4414 reasonable to specify a cluster as the envelope of a set of notes. This
4415 is exactly how to construct a cluster with lilypond.
4417 @lilypond[singleline,verbatim]
4419 \context PianoStaff <
4420 \context Voice = voiceI { % same as voiceII, but with ordinary notes
4421 \notes \relative c' {
4423 a4 <e4 d'4> | \break
4424 < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 |
4428 \context Voice = voiceII { % same as voiceI, but with cluster notation
4429 \notes \relative c' {
4431 % hide notes, accidentals, etc.
4432 \property Thread.NoteHead \set #'transparent = ##t
4433 \property Voice.Stem \set #'transparent = ##t
4434 \property Voice.Beam \set #'transparent = ##t
4435 \property Staff.Accidental \set #'transparent = ##t
4437 \property Voice.Cluster \set #'padding = #0.01
4438 \property Voice.Cluster \set #'shape = #'ramp
4442 a4 <e4 d'4> | \break
4443 < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 |
4444 c4 \stopCluster a4 f4 g4 a4
4451 Note that the second voice differs from the first one only by the
4452 additional keywords @code{\startCluster} and @code{\stopCluster} and the
4453 fact that notes, accidentals, etc. are hidden. A future version of
4454 lilypond may automatically hide notes, accidentals, etc. within the
4457 Also note that a music expression like @code{< @{ g8 e8 @} a4 >} is
4458 illegal; in such a case, you can instead use the expression @code{< g8
4461 By default, cluster engraver is in the voice context. This allows
4462 putting ordinary notes and clusters together in the same staff, even
4463 simultaneously. However, in such a case no attempt is made to
4464 automatically avoid collisions between ordinary notes and clusters.
4466 The geometrical shape can be further controlled with grob properties
4467 @code{padding} and @code{shape}. @code{padding} adds to the vertical
4468 extent of the shape (top and bottom) and is expressed in units of
4469 staffspace. Since the pitch range of a single pitch is infinitely
4470 small, if padding is set to @code{0.0}, this possibly results in an
4471 invisible shape, if you,for example, say @code{ \startCluster c d e
4472 \endCluster}. The default value for @code{padding} therefore is
4473 @code{0.25}, such that a single pitch roughly shows the same height as a
4474 note head. Property @code{shape} controls how the overall shape of the
4475 cluster is constructed from the set of notes. Currently supported
4476 values are @code{leftsided-stairs}, @code{rightsided-stairs},
4477 @code{centered-stairs}, and @code{ramp}.
4480 @subsection Fermatas
4484 Currently, lilypond supports the following fermata symbols that are
4485 frequently used in contemporary music notation:
4487 @lilypond[singleline,verbatim]
4494 ^\markup { short fermata }
4499 ^\markup { fermata }
4504 ^\markup { long fermata }
4509 ^\markup { very long fermata }
4515 See @ref{Articulations} for general instructions how to apply scripts
4516 such as fermatas to a @code{\notes@{@}} block.
4520 @section Tuning output
4522 LilyPond tries to take as much formatting as possible out of your
4523 hands. Nevertheless, there are situations where it needs some help, or
4524 where you want to override its decisions. In this section we discuss
4525 ways to do just that.
4527 Formatting is internally done by manipulating so called objects (graphic
4528 objects). Each object carries with it a set of properties (object
4529 properties) specific to that object. For example, a stem object has
4530 properties that specify its direction, length and thickness.
4532 The most direct way of tuning the output is by altering the values of
4533 these properties. There are two ways of doing that: first, you can
4534 temporarily change the definition of a certain type of object, thus
4535 affecting a whole set of objects. Second, you can select one specific
4536 object, and set a object property in that object.
4539 * Tuning groups of objects ::
4540 * Tuning per object ::
4545 @node Tuning groups of objects
4546 @subsection Tuning groups of objects
4548 @cindex object description
4550 A object definition is a Scheme association list, that is stored in a
4551 context property. By assigning to that property (using plain
4552 @code{\property}), you can change the resulting objects.
4554 @lilypond[verbatim, fragment,quote]
4555 c'4 \property Voice.NoteHead = #'() c'4
4557 This mechanism is fairly crude, since you can only set, but not modify,
4558 the definition of an object. Also, it will thoroughly confuse LilyPond.
4560 The definition of an object is actually a list of default object
4561 properties. For example, the definition of the Stem object (available
4562 in @file{scm/grob-description.scm}), includes the following definitions for
4567 (beamed-lengths . (0.0 2.5 2.0 1.5))
4568 (Y-extent-callback . ,Stem::height)
4572 You can add a property on top of the existing definition, or remove a
4573 property, thus overriding the system defaults:
4574 @lilypond[verbatim,quote]
4575 c'4 \property Voice.Stem \override #'thickness = #4.0
4576 c'4 \property Voice.Stem \revert #'thickness
4579 You should balance @code{\override} and @code{\revert}. If that is too
4580 much work, you can use the @code{\set} shorthand. It performs a revert
4581 followed by an override. The following example gives exactly the same
4582 result as the previous one.
4583 @lilypond[verbatim,quote]
4584 c'4 \property Voice.Stem \set #'thickness = #4.0
4585 c'4 \property Voice.Stem \set #'thickness = #0.8
4588 If you use @code{\set}, you must explicitly restore the default.
4591 Formally the syntax for these constructions is
4593 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
4594 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
4595 \property @var{context}.@var{grobname} \revert @var{symbol}
4597 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
4598 and @var{grobname} are strings and @var{value} is a Scheme expression.
4601 If you revert a setting which was not set in the first place, then it
4602 has no effect. However, if the setting was set as a system default, it
4603 may remove the default value, and this may give surprising results,
4604 including crashes. In other words, @code{\override} and @code{\revert},
4605 must be carefully balanced.
4607 These are examples of correct nesting of @code{\override}, @code{\set},
4610 A clumsy but correct form:
4612 \override \revert \override \revert \override \revert
4615 Shorter version of the same:
4617 \override \set \set \revert
4620 A short form, using only @code{\set}. This requires you to know the
4623 \set \set \set \set @var{to default value}
4626 If there is no default (i.e. by default, the object property is unset),
4629 \set \set \set \revert
4632 For the digirati, the object description is an Scheme association
4633 list. Since a Scheme list is a singly linked list, we can treat it as a
4634 stack, and @code{\override} and @code{\revert} are just push and pop
4635 operations. This pushing and popping is also used for overriding
4636 automatic beaming settings.
4640 LilyPond will hang or crash if @var{value} contains cyclic references.
4641 The backend is not very strict in type-checking object properties. If you
4642 @code{\revert} properties that are expected to be set by default,
4648 @node Tuning per object
4649 @subsection Tuning per object
4652 Tuning a single object is most often done with @code{\property}. The
4655 \once \property @dots{}
4658 applies a setting only during one moment in the score: the
4659 original setting for stem thickness is restored automatically in the
4662 @lilypond[verbatim, fragment, relative=1]
4664 \once \property Voice.Stem \set #'thickness = #4
4670 @cindex \outputproperty
4672 A second way of tuning objects is the more arcane @code{\outputproperty}
4673 feature. The syntax is as follows:
4675 \outputproperty @var{predicate} @var{symbol} = @var{value}
4677 Here @code{predicate} is a Scheme function taking a object argument, and
4678 returning a boolean. This statement is processed by the
4679 @code{Output_property_engraver}. It instructs the engraver to feed all
4680 objects that it sees to @var{predicate}. Whenever the predicate returns
4681 true, the object property @var{symbol} will be set to @var{value}.
4683 This command is only single shot, in contrast to @code{\override} and
4686 You will need to combine this statement with @code{\context} to select
4687 the appropriate context to apply this to.
4689 In the following example, all note heads occurring at current staff
4690 level, are shifted up and right by setting their @code{extra-offset}
4693 @lilypond[fragment,verbatim,singleline]
4695 \context Staff \outputproperty
4696 #(make-type-checker 'note-head-interface)
4697 #'extra-offset = #'(0.5 . 0.75)
4701 @cindex @code{extra-offset}
4703 In this example, the predicate checks the @code{text} object property, to
4704 shift only the `m.d.' text, but not the fingering instruction "2".
4705 @lilypond[verbatim,singleline]
4706 #(define (make-text-checker text)
4707 (lambda (grob) (equal? text (ly:get-grob-property grob 'text))))
4710 \notes\relative c''' {
4711 \property Voice.Stem \set #'direction = #1
4712 \outputproperty #(make-text-checker "m.d.")
4713 #'extra-offset = #'(-3.5 . -4.5)
4721 If possible, avoid this feature: the semantics are not very clean, and
4722 the syntax and semantics are up for rewrite.
4727 @node Font selection
4728 @subsection Font selection
4730 The most common thing to change about the appearance of fonts is
4731 their size. The font size of a @internalsref{Voice},
4732 @internalsref{Staff} or @internalsref{Thread} context, can be easily
4733 changed by setting the @code{fontSize} property for that context:
4734 @lilypond[fragment,relative=1,verbatim,quote]
4735 c4 c4 \property Voice.fontSize = #-1
4738 This command will not change the size of variable symbols, such as
4739 beams or slurs. You can use this command to get smaller symbol for
4740 cue notes, but that involves some more subtleties. An elaborate
4741 example of those is in @inputfileref{input/test,cue-notes.ly}.
4749 The font used for printing a object can be selected by setting
4750 @code{font-name}, e.g.
4752 \property Staff.TimeSignature
4753 \set #'font-name = #"cmr17"
4755 You may use any font which is available to @TeX{}, such as foreign
4756 fonts or fonts that do not belong to the Computer Modern font family.
4757 Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
4758 can also be adjusted with a more fine-grained mechanism. By setting
4759 the object properties described below, you can select a different font.
4760 All three mechanisms work for every object that supports
4761 @code{font-interface}.
4765 A symbol indicating the general class of the typeface. Supported are
4766 @code{roman} (Computer Modern), @code{braces} (for piano staff
4767 braces), @code{music} (the standard music font), @code{ancient} (the
4768 ancient notation font) @code{dynamic} (font for dynamic signs) and
4772 A symbol indicating the shape of the font, there are typically several
4773 font shapes available for each font family. Choices are @code{italic},
4774 @code{caps} and @code{upright}
4777 A symbol indicating the series of the font. There are typically several
4778 font series for each font family and shape. Choices are @code{medium}
4781 @item font-relative-size
4782 A number indicating the size relative the standard size. For example,
4783 with 20pt staff height, relative size -1 corresponds to 16pt staff
4784 height, and relative size +1 corresponds to 23 pt staff height.
4786 @item font-design-size
4787 A number indicating the design size of the font.
4789 This is a feature of the Computer Modern Font: each point size has a
4790 slightly different design. Smaller design sizes are relatively wider,
4791 which enhances readability.
4794 For any of these properties, the value @code{*} (i.e. the @emph{symbol},
4795 @code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
4796 to override default setting, which are always present. For example:
4798 \property Lyrics.LyricText \override #'font-series = #'bold
4799 \property Lyrics.LyricText \override #'font-family = #'typewriter
4800 \property Lyrics.LyricText \override #'font-shape = #'*
4803 @cindex @code{font-style}
4805 There are also pre-cooked font selection qualifiers. These are
4806 selected through the object property @code{font-style}. For example,
4807 the style @code{finger} selects family @code{number} and relative size
4808 @code{-3}. Styles available include @code{volta}, @code{finger},
4809 @code{tuplet}, @code{timesig}, @code{mmrest}, @code{script},
4810 @code{large}, @code{Large} and @code{dynamic}. The style sheets and
4811 tables for selecting fonts are located in @file{scm/font.scm}. Refer
4812 to this file for more information.
4814 @cindex magnification
4816 The size of the font may be scaled with the object property
4817 @code{font-magnification}. For example, @code{2.0} blows up all
4818 letters by a factor 2 in both directions.
4822 Relative size is not linked to any real size.
4824 There is no style sheet provided for other fonts besides the @TeX{}
4825 family, and the style sheet can not be modified easily.
4827 @cindex font selection
4828 @cindex font magnification
4829 @cindex @code{font-interface}
4833 @subsection Text markup
4838 @cindex typeset text
4840 LilyPond has an internal mechanism to typeset texts. You can access it
4841 with the keyword @code{\markup}. Within markup mode, you can enter texts
4842 similar to lyrics: simply enter them, surrounded by spaces.
4845 @lilypond[verbatim,fragment,relative=1]
4846 c1^\markup { hello }
4847 c1_\markup { hi there }
4848 c1^\markup { hi \bold there, is \italic anyone home? }
4851 @cindex font switching
4853 The line of the example demonstrates font switching commands. The
4854 command only apply to the first following word; enclose a set of texts
4855 with braces to apply a command to more words.
4857 \markup @{ \bold @{ hi there @} @}
4859 For clarity, you can also do this for single arguments, e.g.
4861 \markup @{ is \italic @{ anyone @} home @}
4864 @cindex font size, texts
4866 The following size commands set abolute sizes
4882 You can also make letter larger or smaller relative to their neighbors,
4883 with the commands @code{\larger} and @code{\smaller}.
4887 @cindex font style, for texts
4893 The following font change commands are defined:
4896 This changes to the font used for dynamic signs. Note that this font
4897 does not contain all characters of the alphabet.
4899 This changes to the font used for time signatures. It only contains
4900 numbers and a few punctuation marks.
4905 @cindex raising text
4906 @cindex lowering text
4908 @cindex translating text
4913 Raising and lowering texts can be done with @code{\super} and
4916 @lilypond[verbatim,fragment,relative=1]
4917 c1^\markup { E "=" mc \super "2" }
4922 If you want to give an explicit amount for lowering or raising, use
4923 @code{\raise}. This command takes a Scheme valued argument,
4924 @lilypond[verbatim,fragment,relative=1,quote]
4925 c1^\markup { C \small \raise #1.0 { "9/7+" }}
4927 The argument to @code{\raise} is the vertical displacement amount,
4928 measured in (global) staff spaces.
4930 Other commands taking single arguments include
4933 @item \bracket, \hbracket
4934 Bracket the argument markup.
4938 This is converted to a musical symbol, e.g. @code{\musicglyph
4939 #"accidentals-0"} will select the natural sign from the music font.
4940 See @ref{The Feta font} for a complete listing of the possible glyphs.
4942 This produces a single character, e.g. @code{\char #65} produces the
4945 @item \hspace #@var{amount}
4947 This produces a invisible object taking horizontal space.
4949 \markup @{ A \hspace #2.0 B @}
4951 will put extra space between A and B. Note that lilypond
4952 inserts space before and after @code{\hspace}.
4954 @item \fontsize #@var{size}
4956 This sets the relative font size, eg.
4958 A \fontsize #2 @{ B C @} D
4962 This will enlarge the B and the C by two steps.
4963 @item \translate #(cons @var{x} @var{y})
4965 This translates an object. Its first argument is a cons of numbers
4967 A \translate #(cons 2 -3) @{ B C @} D
4969 This moves `B C' 2 spaces to the right, and 3 down.
4971 @item \magnify #@var{mag}
4973 This sets the font magnification for the its argument. In the following
4974 example, the middle A will be 10% larger.
4976 A \magnify #1.1 @{ A @} A
4980 @item \override #(@var{key} . @var{value})
4982 This overrides a formatting property for its argument. The argument
4983 should be a key/value pair, e.g.
4985 m \override #'(font-family . math) m m
4989 In markup mode you can compose expressions, similar to mathematical
4990 expressions, XML documents and music expressions. The braces group
4991 notes into horizontal lines. Other types of lists also exist: you can
4992 stack expressions grouped with @code{<<}, and @code{>>} vertically with
4993 the command @code{\column}. Similarly, @code{\center} aligns texts by
4996 @lilypond[verbatim,fragment,relative=1]
4997 c1^\markup { \column << a bbbb c >> }
4998 c1^\markup { \center << a bbbb c >> }
4999 c1^\markup { \line << a b c >> }
5004 The markup mechanism is very flexible and extensible. Refer to
5005 @file{scm/new-markup.scm} for more information on extending the markup
5009 @cindex metronome mark
5011 One practical application of complicated markup is to fake a metronome
5015 eighthStem = \markup \combine
5016 \musicglyph #"flags-stem"
5017 \translate #'(0.0 . 3.5) \musicglyph #"flags-u3"
5018 eighthNote = \markup
5019 \override #'(word-space . 0.0)
5020 { \musicglyph #"noteheads-2"
5021 \translate #'(-0.05 . 0.1) \eighthStem }
5024 \notes\relative c'' {
5025 a1^\markup { \magnify #0.9 \eighthNote " = 64" }
5034 LilyPond does not account for kerning in its text formatting, so it
5035 spaces texts slightly too wide.
5037 Syntax errors for markup mode are confusing.
5041 @section Global layout
5043 The global layout determined by three factors: the page layout, the
5044 line breaks and the spacing. These all influence each other: The
5045 choice of spacing determines how densely each system of music is set,
5046 where line breaks breaks are chosen, and thus ultimately how many
5047 pages a piece of music takes. In this section we will explain how the
5048 lilypond spacing engine works, and how you can tune its results.
5050 Globally spoken, this procedure happens in three steps: first,
5051 flexible distances (``springs'') are chosen, based on durations. All
5052 possible line breaking combination are tried, and the one with the
5053 best results---a layout that has uniform density and requires as
5054 little stretching or cramping as possible---is chosen. When the score
5055 is processed by @TeX{}, page are filled with systems, and page breaks
5056 are chosen whenever the page gets full.
5059 * Vertical spacing::
5060 * Horizontal spacing::
5067 @node Vertical spacing
5068 @subsection Vertical spacing
5070 @cindex vertical spacing
5071 @cindex distance between staves
5072 @cindex staff distance
5073 @cindex between staves, distance
5074 @cindex staffs per page
5077 The height of each system is determined automatically by lilypond, to
5078 keep systems from bumping into each other, some minimum distances are
5079 set. By changing these, you can put staves closer together, and thus
5080 put more systems onto one page.
5082 Normally staves are stacked vertically. To make
5083 staves maintain a distance, their vertical size is padded. This is
5084 done with the property @code{minimumVerticalExtent}. It takes a pair
5085 of numbers, so if you want to make it smaller from its, then you could
5088 \property Staff.minimumVerticalExtent = #'(-4 . 4)
5090 This sets the vertical size of the current staff to 4 staff-space on
5091 either side of the center staff line. The argument of
5092 @code{minimumVerticalExtent} is interpreted as an interval, where the
5093 center line is the 0, so the first number is generally negative. you
5094 could also make the staff larger at the bottom by setting it to
5095 @code{(-6 . 4)}. The default value is @code{(-6 . 6)}.
5097 Vertical aligment of staves is handled by the
5098 @internalsref{VerticalAlignment} object, which lives at
5099 @internalsref{Score} level.
5101 The piano staves are handled a little differently: to make cross-staff
5102 beaming work correctly, it necessary that the distance between staves
5103 is fixed. This is also done with a @internalsref{VerticalAlignment}
5104 object, created in @internalsref{PianoStaff}, but a forced distance is
5105 set. This is done with the object property #'forced-distance. If you
5106 want to override this, use a @code{\translator} block as follows:
5110 VerticalAlignment \override #'forced-distance = #9
5113 This would bring the staves together at a distance of 9 staff spaces,
5114 and again this is measured from the center line of each staff.
5118 @node Horizontal spacing
5119 @subsection Horizontal Spacing
5121 The spacing engine translates differences in durations into
5122 stretchable distances (``springs'') of differing lengths. Longer
5123 durations get more space, shorter durations get less. The basis for
5124 assigning spaces to durations, is that the shortest durations get a
5125 fixed amount of space, and the longer durations get more: doubling a
5126 duration adds a fixed amount of space to the note.
5128 For example, the following piece contains lots of half, quarter and
5129 8th notes, the eighth note is followed by 1 note head width. The The
5130 quarter note is followed by 2 NHW, the half by 3 NHW, etc.
5131 @lilypond[fragment, verbatim, relative=1]
5132 c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4
5135 These two amounts of space are @code{shortest-duration-space}
5136 @code{spacing-increment}, object properties of
5137 @internalsref{SpacingSpanner}. Normally @code{spacing-increment} is
5138 set to 1.2, which is the width of a note head, and
5139 @code{shortest-duration-space} is set to 2.0, meaning that the
5140 shortest note gets 2 noteheads of space. For normal notes, this space
5141 is always counted from the left edge of the symbol, so the short notes
5142 in a score is generally followed by one note head width of space.
5144 If one would follow the above procedure exactly, then adding a single
5145 32th note to a score that uses 8th and 16th notes, would widen up the
5146 entire score a lot. The shortest note is no longer a 16th, but a 64th,
5147 thus adding 2 noteheads of space to every note. To prevent this, the
5148 shortest duration for spacing is not the shortest note in the score,
5149 but the most commonly found shortest note. Notes that are even
5150 shorter this are followed by a space that is proportonial to their
5151 duration relative to the common shortest note. So if we were to add
5152 only a few 16th notes to the example above, they would be followed by
5155 @lilypond[fragment, verbatim, relative=1]
5156 c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4
5159 The most common shortest duration is determined as follows: in every
5160 measure, the shortest duration is determined. The most common short
5161 duration, is taken as the basis for the spacing, with the stipulation
5162 that this shortest duration should always be equal to or shorter than
5163 1/8th note. The shortest duration is printed when you run lilypond
5164 with @code{--verbose}. These durations may also be customized. If you
5165 set the @code{common-shortest-duration} in
5166 @internalsref{SpacingSpanner}, then this sets the base duration for
5167 spacing. The maximum duration for this base (normally 1/8th), is set
5168 through @code{base-shortest-duration}.
5170 @cindex @code{common-shortest-duration}
5171 @cindex @code{base-shortest-duration}
5172 @cindex @code{stem-spacing-correction}
5173 @cindex @code{spacing}
5175 In the introduction it was explained that stem directions influence
5176 spacing. This is controlled with @code{stem-spacing-correction} in
5177 @internalsref{NoteSpacing}. The @code{StaffSpacing} object contains the
5178 same property for controlling the stem/barline spacing. In the
5179 following example shows these corrections, once with default settings,
5180 and once with exaggerated corrections.
5186 \property Staff.NoteSpacing \override #'stem-spacing-correction
5188 \property Staff.StaffSpacing \override #'stem-spacing-correction
5193 \paper { raggedright = ##t } }
5196 @cindex SpacingSpanner, overriding properties
5198 The @internalsref{SpacingSpanner}, is score wide, so its properties
5199 must be overriden from the @code{\paper} block, e.g.
5201 \paper @{ \translator @{
5203 SpacingSpanner \override #'spacing-increment = #3.0
5210 Spacing is determined on a score wide basis. If you have a score that
5211 changes its character (measured in durations) halfway during the
5212 score, the part containing the longer durations will be spaced too
5215 Generating optically pleasing spacing is black magic. LilyPond tries
5216 to deal with a number of frequent cases. Here is an example that is
5217 not handled correctly, due to the combination of chord collisions and
5222 \context PianoStaff \notes \transpose c c'' <
5223 \context Staff = up { s1 }
5224 \context Staff = down { [c8 c \translator Staff=up <<c d>> c
5225 \translator Staff=down c c c] }
5227 \paper { raggedright = ##t }
5234 @subsection Font size
5235 @cindex font size, setting
5236 @cindex staff size, setting
5237 @cindex @code{paper} file
5239 The Feta font provides musical symbols at seven different sizes.
5240 These fonts are 11 point, 13 point, 16 point, 19 pt, 20 point, 23
5241 point, and 26 point. The point size of a font is the height of the
5242 five lines in a staff when displayed in the font.
5244 Definitions for these sizes are the files @file{paperSZ.ly}, where
5245 @code{SZ} is one of 11, 13, 16, 19, 20, 23 and 26. If you include any
5246 of these files, the identifiers @code{paperEleven},
5247 @code{paperThirteen}, @code{paperSixteen}, @code{paperNineteen},
5248 @code{paperTwenty}, @code{paperTwentythree}, and @code{paperTwentysix}
5249 are defined respectively. The default @code{\paper} block is also
5250 set. These files should be imported at toplevel, i.e.
5252 \include "paper26.ly"
5256 The font definitions are generated using a Scheme function. For more
5257 details, see the file @file{scm/font.scm}.
5262 @subsection Line breaking
5265 @cindex breaking lines
5267 Line breaks are normally computed automatically. They are chosen such
5268 that it looks neither cramped nor loose, and that consecutive lines have
5271 Occasionally you might want to override the automatic breaks; you can
5272 do this by specifying @code{\break}. This will force a line break at
5273 this point. Line breaks can only occur at places where there are bar
5274 lines. If you want to have a line break where there is no bar line,
5275 you can force an invisible bar line by entering @code{\bar
5276 ""}. Similarly, @code{\noBreak} forbids a line break at a certain
5280 @cindex regular line breaks
5281 @cindex four bar music.
5283 If you want linebreaks at regular intervals, you can use the following:
5285 < \repeat 7 unfold @{ s1 * 4 \break @}
5289 This makes the following 28 measures (assuming 4/4 time) be broken every
5293 @subsection Page layout
5296 @cindex breaking pages
5298 @cindex @code{indent}
5299 @cindex @code{linewidth}
5301 The most basic settings influencing the spacing are @code{indent} and
5302 @code{linewidth}. They are set in the @code{\paper} block. They
5303 control the indentation of the first line of music, and the lengths of
5306 If @code{raggedright} is set to true in the @code{\paper}
5307 block, then the lines are justified at their natural length. This
5308 useful for short fragments, and for checking how tight the natural
5312 @cindex vertical spacing
5314 The page layout process happens outside lilypond. Ly2dvi sets page
5315 layout instructions. Ly2dvi responds to the following variables in the
5316 @code{\paper} block. The variable @code{textheight} sets the total
5317 height of the music on each page. The spacing between systems is
5318 controlled with @code{interscoreline}, its default is 16pt.
5319 The distance between the score lines will stretch in order to fill the
5320 full page @code{interscorelinefill} is set to a positive number. In
5321 that case @code{interscoreline} specifies the minimum spacing.
5323 @cindex @code{textheight}
5324 @cindex @code{interscoreline}
5325 @cindex @code{interscorelinefill}
5327 If the variable @code{lastpagefill} is defined (that is, it gets any
5328 value assigned in the @code{\paper} block), systems are evenly
5329 distributed vertically on the last page. This might produce ugly
5330 results in case there are not enough systems on the last page. Note
5331 that @command{lilypond-book} ignores @code{lastpagefill}. See
5332 @ref{Integrating text and music with lilypond-book} for
5335 @cindex @code{lastpagefill}
5337 Page breaks are normally computed by @TeX{}, so they are not under
5338 direct control of LilyPond. However, you can insert a commands into
5339 the @file{.tex} output to instruct @TeX{} where to break pages. You
5340 can insert a @code{\newpage} from within lilypond. This is done by
5341 setting the @code{between-systems-strings} on the
5342 @internalsref{NonMusicalPaperColumn} where the system is broken.
5346 @cindex @code{papersize}
5348 To change the paper size, you must first set the
5349 @code{papersize} paper variable variable. Set it to
5350 the strings @code{a4}, @code{letter}, or @code{legal}. After this
5351 specification, you must set the font as described above. If you want
5352 the default font, then use the 20 point font.
5355 \paper@{ papersize = "a4" @}
5356 \include "paper16.ly"
5359 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
5360 will set the paper variables @code{hsize} and @code{vsize} (used by
5361 Lilypond and @code{ly2dvi})
5371 LilyPond can produce MIDI output. The performance lacks lots of
5372 interesting effects, such as swing, articulation, slurring, etc., but it
5373 is good enough for proof-hearing the music you have entered. Ties,
5374 dynamics and tempo changes are interpreted.
5376 Dynamic marks, crescendi and decrescendi translate into MIDI volume
5377 levels. Dynamic marks translate to a fixed fraction of the available
5378 MIDI volume range, crescendi and decrescendi make the the volume vary
5379 linearly between their two extremities. The fractions be adjusted by
5380 overriding the @code{absolute-volume-alist} defined in
5381 @file{scm/midi.scm}.
5383 For each type of musical instrument (that MIDI supports), a volume range
5384 can be defined. This gives you basic equalizer control, which can
5385 enhance the quality of the MIDI output remarkably. You can add
5386 instruments and ranges or change the default settings by overriding the
5387 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
5389 Both loudness controls are combined to produce the final MIDI volume.
5393 * MIDI instrument names::
5398 @subsection MIDI block
5402 The MIDI block is analogous to the paper block, but it is somewhat
5403 simpler. The @code{\midi} block can contain:
5407 @item a @code{\tempo} definition
5408 @item context definitions
5411 Assignments in the @code{\midi} block are not allowed.
5415 @cindex context definition
5417 Context definitions follow precisely the same syntax as within the
5418 \paper block. Translation modules for sound are called performers.
5419 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
5422 @node MIDI instrument names
5423 @subsection MIDI instrument names
5425 @cindex instrument names
5426 @cindex @code{Staff.midiInstrument}
5427 @cindex @code{Staff.instrument}
5429 The MIDI instrument name is set by the @code{Staff.midiInstrument}
5430 property or, if that property is not set, the @code{Staff.instrument}
5431 property. The instrument name should be chosen from the list in
5432 @ref{MIDI instruments}.
5436 If the selected string does not exactly match, then LilyPond uses the
5437 default (Grand Piano). It is not possible to select an instrument by