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.
2906 \consists Ambitus_engraver
2911 The result will look like this.
2912 @lilypond[singleline]
2913 upper = \notes \relative c {
2916 as'' c e2 bes f cis d4 e f2 g
2918 lower = \notes \relative c {
2921 e'4 b g a c es fis a cis b a g f e d2
2924 \context ChoirStaff {
2926 \context Staff = one { \upper }
2927 \context Staff = three { \lower }
2933 \consists Ambitus_engraver
2942 @internalsref{Ambitus}, @inputfileref{input/regression/,ambitus.ly}.
2947 Tablature notation is used for notating music for plucked string
2948 instruments. It notates pitches not by using note heads, but by
2949 indicating on which string and fret a note must be played. LilyPond
2950 offers limited support for tablature.
2953 * Tablatures basic::
2954 * Non-guitar tablatures::
2957 @node Tablatures basic
2958 @subsection Tablatures basic
2959 @cindex Tablatures basic
2961 The string number associated to a note is given as a backslash
2962 followed by a number, e.g. @code{c4\3} for a C quarter on the third
2963 string. By default, string 1 is the highest one, and the tuning
2964 defaults to the standard guitar tuning (with 6 strings). The notes
2965 are printed as tablature, by using @internalsref{TabStaff} and
2966 @internalsref{TabVoice} contexts.
2968 @lilypond[fragment,verbatim]
2969 \notes \context TabStaff {
2975 If you do not specify a string number then one is selected
2976 automatically: the first string that does not give a fret number less
2977 than @code{minimumFret} is selected. The default value for
2978 @code{minimumFret} is 0.
2982 e8 fis gis a b cis' dis' e'
2983 \property TabStaff.minimumFret = #8
2984 e8 fis gis a b cis' dis' e'
2989 e8 fis gis a b cis' dis' e'
2990 \property TabStaff.minimumFret = #8
2991 e8 fis gis a b cis' dis' e'
2994 \context StaffGroup <
2995 \context Staff { \clef "G_8" \frag }
2996 \context TabStaff { \frag }
3003 @internalsref{TabStaff}, @internalsref{TabVoice}
3007 Chords are not handled in a special way, and hence the automatic
3008 string selector may easily select the same string to two notes in a
3012 @node Non-guitar tablatures
3013 @subsection Non-guitar tablatures
3014 @cindex Non-guitar tablatures
3016 You can change the number of strings, by setting the number of lines
3017 in the @internalsref{TabStaff} (the @code{line-count} property of
3018 @internalsref{TabStaff} can only be changed using
3019 @code{\outputproperty}, for more information, see @ref{Tuning per
3022 You can change the tuning of the strings. A string tuning is given as
3023 a Scheme list with one integer number for each string, the number
3024 being the pitch (measured in semitones relative to central C) of an
3025 open string. The numbers specified for @code{stringTuning} are the
3026 numbers of semitones to subtract or add, starting the specified pitch
3027 by default middle C, in string order: thus the notes are e, a, d, and
3030 @lilypond[fragment,verbatim]
3033 \outputproperty #(make-type-checker 'staff-symbol-interface)
3035 \property TabStaff.stringTunings = #'(-5 -10 -15 -20)
3038 a,4 c' a e' e c' a e'
3043 Finally, it is possible to change the Scheme function to format the
3044 tablature note text. The default is
3045 @var{fret-number-tablature-format}, which uses the fret number. For
3046 some instruments that do not use this notation, you can create a
3047 special tablature formatting function. This function takes three
3048 argument: the string number, the string tuning and the note pitch.
3052 As tablature is a recent feature, most of the guitar special effects
3053 such as bend are not yet supported.
3060 LilyPond has support for both entering and printing chords.
3061 @lilypond[verbatim,singleline]
3062 twoWays = \notes \transpose c c' {
3072 < \context ChordNames \twoWays
3073 \context Voice \twoWays > }
3076 This example also shows that the chord printing routines do not try to
3077 be intelligent. If you enter @code{f bes d}, it does not interpret
3078 this as an inversion.
3080 Chords are represented as a set of pitches. They are internally
3081 stored as simultaneous music expressions. This means you can enter
3082 chords by name and print them as notes, enter them as notes and print
3083 them as chord names, or (the most common case) enter them by name, and
3088 * Printing chord names::
3093 @subsection Chords mode
3096 Chord mode is a mode where you can input sets of pitches using common
3097 names. It is introduced by the keyword @code{\chords}.
3098 In chords mode, a chord is entered by the root, which is entered
3099 like a common pitch, for example,
3100 @lilypond[fragment,verbatim,quote, relative=1]
3101 \chords { es4. d8 c2 }
3103 is the notation for three chords: an E-flat major chord, a D major and
3109 Other chords may be entered
3110 by suffixing a colon, and introducing a modifier, and optionally, a
3112 @lilypond[fragment,verbatim,quote]
3113 \chords { e1:m e1:7 e1:m7 }
3115 The first number following the root is taken to be the `type' of the
3116 chord, thirds are added to the root until it reaches the specified
3117 number, for example.
3118 @lilypond[fragment,verbatim]
3119 \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }
3122 @cindex root of chord
3123 @cindex additions, in chords
3124 @cindex removals, in chords
3126 More complex chords may also be constructed adding separate steps
3127 to a chord. Additions are added after the number following
3128 the colon, and are separated by dots. For example
3130 @lilypond[verbatim,fragment,quote]
3131 \chords { c:5.6 c:3.7.8 c:3.6.13 }
3133 Chord steps can be altered by suffixing a @code{-} or @code{+} sign
3134 to the number, for example:
3135 @lilypond[verbatim,fragment,quote]
3136 \chords { c:7+ c:5+.3- c:3-.5-.7- }
3138 Removals are specified similarly, and are introduced by a caret. They
3139 must come after the additions.
3140 @lilypond[verbatim,fragment]
3141 \chords { c^3 c:7^5 c:9^3.5 }
3144 Modifiers can be used to change pitches. The following modifiers are
3148 is the minor chord. This modifier lowers the 3rd and (if present) the 7th step.
3150 is the diminished chord. This modifier lowers the 3rd, 5th and (if present)
3153 is augmented chord. This modifier raises the 5th step.
3155 is the major 7th chord. This modifier raises the 7th step if present.
3157 is the suspended 4th or 2nd. This modifier removes the 3rd
3158 step. Append either @code{2} or @code{4} to add the 2nd or 4th step to
3161 Modifiers can be mixed with additions.
3162 @lilypond[verbatim,fragment]
3163 \chords { c:sus4 c:7sus4 c:dim7 c:m6 }
3166 @cindex modifiers, in chords.
3173 Since the unaltered 11 does sound well when combined with the
3174 unaltered 3, the 11 is removed in this case, unless it is added
3175 explicitly). For example,
3176 @lilypond[fragment,verbatim]
3177 \chords { c:13 c:13.11 c:m13 }
3182 An inversion (putting one pitch of the chord on the bottom), as well
3183 as bass notes, can be specified by appending
3184 @code{/}@var{pitch} to the chord.
3185 @lilypond[fragment,verbatim,center]
3186 \chords { c1 c/g c/f }
3189 If you do not want to remove the bass note from the chord, but rather
3190 add the note, then you can use @code{/+}@var{pitch}.
3192 @lilypond[fragment,verbatim,center]
3193 \chords { c1 c/+g c/+f }
3196 Chords is a mode similar to @code{\lyrics}, @code{\notes} etc. Most
3197 of the commands continue to work, for example, @code{r} and
3198 @code{\skip} can be used to insert rests and spaces, and
3199 @code{\property} may be used to change various settings.
3205 Each step can only be present in a chord once. The following
3206 simply produces the augmented chord, since @code{5+} is interpreted
3209 @lilypond[verbatim,fragment]
3210 \chords { c:5.5-.5+ }
3213 In chord mode, dashes and carets are used to indicate chord additions
3214 and subtractions, so articulation scripts can not be entered.
3217 @node Printing chord names
3218 @subsection Printing chord names
3220 @cindex printing chord names
3224 For displaying printed chord names, use the @internalsref{ChordNames} context.
3225 The chords may be entered either using the notation described above, or
3226 directly using simultaneous music.
3228 @lilypond[verbatim,singleline]
3230 \chords {a1 b c} <<d f g>> <<e g b>>
3234 \context ChordNames \scheme
3235 \context Staff \transpose c c' \scheme
3240 You can make the chord changes stand out by setting
3241 @internalsref{ChordNames}.@code{chordChanges} to true. This will only
3242 display chord names when there is a change in the chords scheme and at
3243 the start of a new line.
3247 c1:m c:m \break c:m c:m d
3251 \context ChordNames {
3252 \property ChordNames.chordChanges = ##t
3254 \context Staff \transpose c c' \scheme
3256 \paper{linewidth= 9.\cm}
3260 The default chord name layout is a system for Jazz music, proposed by
3261 Klaus Ignatzek (See @ref{Literature}).
3263 [TODO: add description for banter other jazz.]
3265 The Ignatzek chord name formatting can be tuned in a number of ways
3266 through the following properties:
3268 @item chordNameExceptions
3269 This is a list that contains the chords that have special formatting.
3271 @lilypond[verbatim,singleline]
3272 chExceptionMusic = \notes { <<c f g bes>>1-\markup { \super "7" "wahh" }}
3273 chExceptions = #(append
3274 (sequential-music-to-chord-exceptions chExceptionMusic)
3277 \score { \context ChordNames
3280 \property ChordNames.chordNameExceptions = #chExceptions
3284 Putting the exceptions list encoded as
3286 \notes @{ <<c f g bes>>1-\markup @{ \super "7" "wahh" @} @}
3288 into @code{chordNameExceptions} takes a little manoeuvring. The
3289 following code transforms @code{chExceptionMusic} (which is a
3290 sequential music) into a list of exceptions.
3292 (sequential-music-to-chord-exceptions chExceptionMusic)
3297 ... ignatzekExceptions)
3299 adds the new exceptions to the default ones, which are defined in
3300 @file{ly/chord-modifier-init.ly}.
3302 @item majorSevenSymbol
3303 This property contains the markup object used for the 7th step, when
3304 it is major. Predefined options are @code{whiteTriangleMarkup},
3305 @code{blackTriangleMarkup}.
3307 @item chordNameSeparator
3308 Different parts of a chord name are normally separated by a
3309 slash. By setting @code{chordNameSeparator}, you can specify other
3311 @lilypond[fragment,verbatim]
3312 \context ChordNames \chords {
3314 \property ChordNames.chordNameSeparator = \markup { "|" }
3322 @inputfileref{input/regression/,chord-name-major7.ly},
3323 @file{scm/chords-ignatzek.scm}, @file{scm/chord-entry.scm}.
3328 Chord names are determined solely from the list of pitches. Chord
3329 inversions are not identified, and neither are added bass notes. This
3330 may result in strange chord names when chords are entered with the
3331 @code{<< .. >>} syntax.
3337 @section Writing parts
3339 Orchestral music involves some special notation, both in the full score,
3340 as in the individual parts. This section explains how to tackle common
3341 problems in orchestral music.
3348 * Instrument names::
3350 * Multi measure rests::
3351 * Automatic part combining::
3352 * Hara kiri staves::
3353 * Sound output for transposing instruments::
3357 @node Rehearsal marks
3358 @subsection Rehearsal marks
3359 @cindex Rehearsal marks
3361 @cindex @code{\mark}
3363 To print a rehearsal mark, use the @code{\mark} command.
3364 @lilypond[fragment,verbatim]
3375 As you can see, the mark is incremented automatically if you use
3376 @code{\mark \default}. The value to use is stored in the property
3377 @code{rehearsalMark} is used and automatically incremented. The object
3378 is @internalsref{RehearsalMark} in @internalsref{Score} context. See
3379 @inputfileref{input/test,boxed-molecule.ly} if you need boxes around the
3382 The @code{\mark} command can also be used to put signs like coda,
3383 segno and fermatas on a barline. The trick is to use the text markup
3384 mechanism to access the fermata symbol.
3385 @lilypond[fragment,verbatim,relative=1]
3386 c1 \mark \markup { \musicglyph #"scripts-ufermata" }
3391 The problem is that marks that occur at a line break are typeset only
3392 at the beginning of the next line, opposite to what you want for the
3393 fermata. This can be corrected by the following property setting
3395 \property Score.RehearsalMark \override
3396 #'break-visibility = #begin-of-line-invisible
3402 @cindex barlines, putting symbols on
3406 @subsection Bar numbers
3410 @cindex measure numbers
3411 @cindex currentBarNumber
3413 Bar numbers are printed by default at the start of the line. The
3414 number itself is a property that can be set by modifying the
3415 @code{currentBarNumber} property, although that is usually not
3418 \property Score.currentBarNumber = #217
3421 To typeset Bar Numbers at regular intervals instead of at the beginning of each line,
3422 you need to change the grob property @code{break-visibility} as well as the translator
3423 property @code{barNumberVisibility}, as illustrated in the following example which also
3424 adds a box around the bar numbers:
3426 \property Score.BarNumber \override #'break-visibility =
3427 #end-of-line-invisible
3428 \property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
3429 \property Score.BarNumber \override #'molecule-callback =
3430 #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule)
3431 \property Score.BarNumber \override #'font-relative-size = #0
3435 \context Staff \notes \transpose c c'' {
3436 \property Score.BarNumber \override #'break-visibility = #end-of-line-invisible
3437 \property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
3438 \property Score.BarNumber \override #'molecule-callback =
3439 #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule)
3440 \property Score.BarNumber \override #'font-relative-size = #0
3442 \repeat unfold 16 c1 \bar "|."
3447 If you would like the bar numbers to appear at regular intervals, but
3448 not starting from measure zero, you can use the context function,
3449 @code{set-bar-number-visibility}, to automatically set
3450 @code{barNumberVisibility} so that the bar numbers appear at regular
3451 intervals, starting from the @code{\applycontext}:
3454 resetBarnum = \context Score \applycontext
3455 #(set-bar-number-visibility 4)
3457 \property Score.BarNumber \override #'break-visibility =
3458 #end-of-line-invisible
3459 \mark "A" \resetBarnum
3460 \repeat unfold 10 c1
3461 \mark \default \resetBarnum
3465 resetBarnum = \context Score \applycontext
3466 #(set-bar-number-visibility 4)
3469 \notes \transpose c c'' {
3470 \property Score.BarNumber \override #'break-visibility =#end-of-line-invisible
3471 \property Score.RehearsalMark \override #'padding = #2.5
3472 \mark "A" \resetBarnum
3473 \repeat unfold 10 c1
3474 \mark \default \resetBarnum
3482 See also @seeinternals{BarNumber}.
3486 Barnumbers can collide with the StaffGroup, if there is one at the
3487 top. To solve this, You have to twiddle with the
3488 @internalsref{padding} property of @internalsref{BarNumber} if your
3489 score starts with a @internalsref{StaffGroup}.
3491 @node Instrument names
3492 @subsection Instrument names
3494 In scores, the instrument name is printed before the staff. This can
3495 be done by setting @code{Staff.instrument} and
3496 @code{Staff.instr}. This will print a string before the start of the
3497 staff. For the first start, @code{instrument} is used, for the next
3498 ones @code{instr} is used.
3500 @lilypond[verbatim,singleline]
3501 \property Staff.instrument = "ploink " { c''4 }
3504 You can also use markup texts to construct more complicated instrument
3508 @lilypond[verbatim,singleline]
3510 \notes \context Staff = treble {
3511 \property Staff.instrument
3512 = \markup { \column << "Clarinetti" { "in B" \smaller \musicglyph #"accidentals--1" } >> }
3515 \paper { linewidth= 8.0\cm }
3522 When you put a name on a grand staff or piano staff the width of the
3523 brace is not taken into account. You must add extra spaces to the end of
3524 the name to avoid a collision.
3527 @subsection Transpose
3529 @cindex transposition of pitches
3530 @cindex @code{\transpose}
3532 A music expression can be transposed with @code{\transpose}. The syntax
3535 \transpose @var{from} @var{to} @var{musicexpr}
3538 This means that @var{musicexpr} is transposed to by the interval
3539 between @var{from} is @var{to}.
3541 @code{\transpose} distinguishes between enharmonic pitches: both
3542 @code{\transpose c cis} or @code{\transpose c des} will transpose up
3543 half a tone. The first version will print sharps and the second
3544 version will print flats.
3546 @lilypond[singleline, verbatim]
3547 mus =\notes { \key d \major cis d fis g }
3548 \score { \notes \context Staff {
3551 \transpose c g' \mus
3552 \transpose c f' \mus
3556 If you want to use both @code{\transpose} and @code{\relative}, then
3557 you must use @code{\transpose} first. @code{\relative} will have no
3558 effect music that appears inside a @code{\transpose}.
3561 @node Multi measure rests
3562 @subsection Multi measure rests
3563 @cindex Multi measure rests
3567 Multi measure rests are entered using `@code{R}'. It is specifically
3568 meant for full bar rests and for entering parts: the rest can expand to
3569 fill a score with rests, or it can be printed as a single multimeasure
3570 rest. This expansion is controlled by the property
3571 @code{Score.skipBars}. If this is set to true, Lily will not expand
3572 empty measures, and the appropriate number is added automatically.
3574 @lilypond[fragment,verbatim]
3575 \time 4/4 r1 | R1 | R1*2
3576 \property Score.skipBars = ##t R1*17 R1*4
3579 The @code{1} in @code{R1} is similar to the duration notation used for
3580 notes. Hence, for time signatures other than 4/4, you must enter other
3581 durations. This can be done with augmentation dots, or with
3584 @lilypond[fragment,verbatim]
3585 \property Score.skipBars = ##t
3593 A @code{R} spanning a single measure is printed as a whole rest
3594 centered in the measure, regardless of the time signature.
3596 [ add note about breves.]
3599 @cindex text on multi-measure rest
3600 @cindex script on multi-measure rest
3601 @cindex fermata on multi-measure rest
3603 Texts can be added to multi-measure rests by using the
3604 @var{note}-@code{markup} syntax. In this case, the number is
3605 replaced. If you need both texts and the number, you must add the
3606 number by hand. An identifier (@code{fermataMarkup}) is provided for
3610 @lilypond[verbatim,fragment]
3612 R2._\markup { "Ad lib" }
3617 @cindex whole rests for a full measure
3619 The object for this object is @internalsref{MultiMeasureRest},
3620 @internalsref{MultiMeasureRestNumber} (for the default number), and
3621 @internalsref{MultiMeasureRestText} (for user specified texts).
3625 It is not possible to use fingerings (e.g. @code{R1-4}) to put numbers
3626 over multi-measure rests.
3628 @cindex condensing rests
3630 There is no way to automatically condense multiple rests
3631 into a single multimeasure rest. Multi measure rests do not take part
3634 Be careful when entering multimeasure rests followed by whole notes,
3638 will enter two notes lasting four measures each. The result will look
3639 ok, but the bar numbering will be off.
3641 @node Automatic part combining
3642 @subsection Automatic part combining
3643 @cindex automatic part combining
3644 @cindex part combiner
3647 Automatic part combining is used to merge two parts of music onto a
3648 staff in an intelligent way. It is aimed primarily at typesetting
3649 orchestral scores. When the two parts are identical for a period of
3650 time, only one is shown. In places where the two parts differ, they
3651 are typeset as separate voices, and stem directions are set
3652 automatically. Also, solo and @emph{a due} parts can be identified
3655 The syntax for part combining is
3658 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
3660 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
3661 combined into one context of type @var{context}. The music expressions
3662 must be interpreted by contexts whose names should start with @code{one}
3665 The most useful function of the part combiner is to combine parts into
3666 one voice, as common for wind parts in orchestral scores:
3668 @lilypond[verbatim,singleline,fragment]
3670 \context Voice=one \partcombine Voice
3671 \context Thread=one \relative c'' {
3674 \context Thread=two \relative c'' {
3680 The first @code{g} appears only once, although it was
3681 specified twice (once in each part). Stem, slur and tie directions are
3682 set automatically, depending whether there is a solo or unisono. The
3683 first part (with context called @code{one}) always gets up stems, and
3684 `solo', while the second (called @code{two}) always gets down stems and
3687 If you just want the merging parts, and not the textual markings, you
3688 may set the property @var{soloADue} to false.
3690 @lilypond[verbatim,singleline,fragment]
3692 \property Staff.soloADue = ##f
3693 \context Voice=one \partcombine Voice
3694 \context Thread=one \relative c'' {
3697 \context Thread=two \relative c'' {
3703 There are a number of other properties that you can use to tweak the
3704 behavior of part combining, refer to the automatically generated
3705 documentation of @internalsref{Thread_devnull_engraver} and
3706 @internalsref{Voice_devnull_engraver}. Look at the documentation of the
3707 responsible engravers, @code{Thread_devnull_engraver},
3708 @code{Voice_devnull_engraver} and @code{A2_engraver}.
3712 In @code{soloADue} mode, when the two voices play the same notes on and
3713 off, the part combiner may typeset @code{a2} more than once in a
3716 @lilypond[fragment,singleline]
3718 \context Voice=one \partcombine Voice
3719 \context Thread=one \relative c'' {
3722 \context Thread=two \relative c'' {
3728 @cindex @code{Thread_devnull_engraver}
3729 @cindex @code{Voice_engraver}
3730 @cindex @code{A2_engraver}
3732 @node Hara kiri staves
3733 @subsection Hara kiri staves
3735 In orchestral scores, staff lines that only have rests are usually removed.
3736 This saves some space. LilyPond also supports this through the hara
3737 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
3738 the Japanese Samourai warriors.} staff. This staff commits suicide when
3739 it finds itself to be empty after the line-breaking process. It will
3740 not disappear when it contains normal rests, you must use multi measure
3743 The hara kiri staff is specialized version of the @internalsref{Staff}
3744 context. It is available as the context identifier
3745 @code{\HaraKiriStaffContext}. Observe how the second staff in this
3746 example disappears in the second line.
3750 \notes \relative c' <
3751 \context Staff = SA { e4 f g a \break c1 }
3752 \context Staff = SB { c4 d e f \break R1 }
3756 \translator { \HaraKiriStaffContext }
3761 For @internalsref{Lyrics}, @internalsref{LyricsVoice},
3762 @internalsref{ChordNames} and @internalsref{FiguredBass}, hara-kiri is
3763 switched on by default.
3766 @node Sound output for transposing instruments
3767 @subsection Sound output for transposing instruments
3769 When you want to make a MIDI file from a score containing transposed
3770 and untransposed instruments, you have to instruct LilyPond the pitch
3771 offset (in semitones) for the transposed instruments. This is done
3772 using the @code{transposing} property. It does not affect printed
3775 @cindex @code{transposing}
3778 \property Staff.instrument = #"Cl. in B-flat"
3779 \property Staff.transposing = #-2
3783 @node Ancient notation
3784 @section Ancient notation
3786 @cindex Vaticana, Editio
3787 @cindex Medicaea, Editio
3793 * Ancient note heads::
3802 @node Ancient note heads
3803 @subsection Ancient note heads
3805 To get a longa note head, you have to use mensural note heads. This
3806 is accomplished by setting the @code{style} property of the
3807 NoteHead object to @code{mensural}. There is also a note head style
3808 @code{baroque} which gives mensural note heads for @code{\longa} and
3809 @code{\breve} but standard note heads for shorter notes.
3811 @lilypond[fragment,singleline,verbatim]
3812 \property Voice.NoteHead \set #'style = #'mensural
3817 @subsection Ancient clefs
3819 LilyPond supports a variety of clefs, many of them ancient.
3821 For modern clefs, see section @ref{Clef}. For the percussion clef, see
3822 section @ref{Percussion staves}. For the @code{TAB} clef, see section
3825 The following table shows all ancient clefs that are supported via the
3826 @code{\clef} command. Some of the clefs use the same glyph, but differ
3827 only with respect to the line they are printed on. In such cases, a
3828 trailing number in the name is used to enumerate these clefs. Still,
3829 you can manually force a clef glyph to be typeset on an arbitrary line,
3830 as described in section @ref{Clef}. The note printed to the right side
3831 of each clef denotes the @code{c'} with respect to the clef.
3835 @c --- This should go somewhere else: ---
3836 @c @item modern style G clef (glyph: @code{clefs-G})
3839 @c @code{treble}, @code{violin}, @code{G}, @code{G2}, @code{french}
3841 @c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "G" c'}
3843 @c @item modern style F clef (glyph: @code{clefs-F})
3846 @c @code{varbaritone}, @code{bass}, @code{F}, @code{subbass}
3848 @c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "F" c'}
3850 @c @item modern style C clef (glyph: @code{clefs-C})
3853 @c @code{soprano}, @code{mezzosoprano}, @code{alto}, @code{C},
3854 @c @code{tenor}, @code{baritone}
3856 @c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "C" c'}
3858 @item modern style mensural C clef (glyph: @code{clefs-neo_mensural_c'})
3861 @code{neo_mensural_c1}, @code{neo_mensural_c2},
3862 @code{neo_mensural_c3}, @code{neo_mensural_c4}
3864 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "neo_mensural_c2" c'}
3866 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c1})
3872 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c1" c'}
3874 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c2})
3880 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c2" c'}
3882 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c3})
3888 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c3" c'}
3890 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c4})
3896 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c4" c'}
3898 @item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c5})
3904 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c5" c'}
3906 @item petrucci style mensural F clef (glyph: @code{clefs-petrucci_f})
3911 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_f" c'}
3913 @item petrucci style mensural G clef (glyph: @code{clefs-petrucci_g})
3918 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_g" c'}
3920 @item historic style mensural C clef (glyph: @code{clefs-mensural_c'})
3923 @code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3},
3926 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_c2" c'}
3928 @item historic style mensural F clef (glyph: @code{clefs-mensural_f})
3933 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_f" c'}
3935 @item historic style mensural G clef (glyph: @code{clefs-mensural_g})
3940 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_g" c'}
3942 @item Editio Vaticana style do clef (glyph: @code{clefs-vaticana_do})
3945 @code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3}
3947 @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_do2" c'}
3949 @item Editio Vaticana style fa clef (glyph: @code{clefs-vaticana_fa})
3952 @code{vaticana_fa1}, @code{vaticana_fa2}
3954 @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_fa2" c'}
3956 @item Editio Medicaea style do clef (glyph: @code{clefs-medicaea_do})
3959 @code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3}
3961 @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_do2" c'}
3963 @item Editio Medicaea style fa clef (glyph: @code{clefs-medicaea_fa})
3966 @code{medicaea_fa1}, @code{medicaea_fa2}
3968 @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_fa2" c'}
3970 @item historic style hufnagel do clef (glyph: @code{clefs-hufnagel_do})
3973 @code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3}
3975 @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do2" c'}
3977 @item historic style hufnagel fa clef (glyph: @code{clefs-hufnagel_fa})
3980 @code{hufnagel_fa1}, @code{hufnagel_fa2}
3982 @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_fa2" c'}
3984 @item historic style hufnagel combined do/fa clef (glyph: @code{clefs-hufnagel_do_fa})
3987 @code{hufnagel_do_fa}
3989 @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do_fa" c'}
3991 @c --- This should go somewhere else: ---
3992 @c @item modern style percussion clef (glyph: @code{clefs-percussion})
3995 @c @code{percussion}
3997 @c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "percussion" c'}
3999 @c @item modern style tab clef (glyph: @code{clefs-tab})
4004 @c @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #6 \property Staff.TimeSignature \set #'transparent = ##t \clef "tab" c'}
4008 @emph{Modern style} means ``as is typeset in current editions of
4009 transcribed mensural music''.
4011 @emph{Petrucci style} means ``inspired by printings published by the
4012 famous engraver Petrucci (1466-1539)''.
4014 @emph{Historic style} means ``as was typeset or written in contemporary
4015 historic editions (other than those of Petrucci)''.
4017 @emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
4019 Petrucci used C clefs with differently balanced left-side vertical
4020 beams, depending on which staffline it was printed.
4024 @subsection Custodes
4029 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
4030 staff context symbol that appears at the end of a staff line. It
4031 anticipates the pitch of the first note(s) of the following line and
4032 thus helps the player or singer to manage line breaks during
4033 performance, thus enhancing readability of a score.
4038 \property Staff.Custos \set #'style = #'mensural
4043 \consists Custos_engraver
4049 Custodes were frequently used in music notation until the 17th century.
4050 There were different appearances for different notation styles.
4051 Nowadays, they have survived only in special forms of musical notation
4052 such as via the @emph{editio vaticana} dating back to the beginning of
4055 For typesetting custodes, just put a @code{Custos_engraver} into the
4056 Staff context when declaring the @code{\paper} block, as shown in the
4057 following example. In the @code{\paper} block, you can also globally
4058 control the appearance of the custos symbol by setting the custos
4059 @code{style} property.
4065 \consists Custos_engraver
4066 Custos \override #'style = #'mensural
4071 The property can also be set locally, for example in a @code{\notes}
4076 \property Staff.Custos \override #'style = #'vaticana
4077 c'1 d' e' d' \break c' d' e' d'
4081 Currently, the following styles are supported:
4088 ^\markup { "vaticana" }
4089 ^\markup { \musicglyph #"custodes-vaticana-u0" }
4091 ^\markup { "medicaea" }
4092 ^\markup { \musicglyph #"custodes-medicaea-u0" }
4094 ^\markup { "hufnagel" }
4095 ^\markup { \musicglyph #"custodes-hufnagel-u0" }
4097 ^\markup { "mensural" }
4098 ^\markup { \musicglyph #"custodes-mensural-u0" }
4105 \remove "Bar_number_engraver"
4106 TextScript \override #'extra-X-extent = #'(-1 . 1)
4110 \remove "Clef_engraver"
4111 \remove "Key_engraver"
4112 \remove "Time_signature_engraver"
4113 \remove "Staff_symbol_engraver"
4114 minimumVerticalExtent = ##f
4120 If the boolean property @code{adjust-if-on-staffline} is set to
4121 @code{#t} (which it is by default), lily typesets slightly different
4122 variants of the custos glyph, depending on the pitch of the custos,
4123 i.e. depending on the glyph being typeset either on a staffline or
4124 between two stafflines. The idea is that the glyph will optically fit
4125 well into the staff, with the appendage on the right of the custos
4126 always ending at the same vertical position between two stafflines
4127 regardless of the pitch. If you set @code{adjust-if-on-staffline} to
4128 @code{#f}, then lily takes regardless of the pitch always a glyph that
4129 is a compromise of the former two variants.
4131 Just like stems can be attached to noteheads in two directions
4132 @emph{up} and @emph{down}, each custos glyph is available with its
4133 appendage pointing either up or down. If the pitch of a custos is
4134 above a selectable position, the appendage will point downwards; if
4135 the pitch is below this position, the appendage will point upwards.
4136 Use property @code{neutral-position} to select this position. By
4137 default, it is set to @code{0}, such that the neutral position is the
4138 center of the staff. Use property @code{neutral-direction} to control
4139 what happens if a custos is typeset on the neutral position itself.
4140 By default, this property is set to @code{-1}, such that the appendage
4141 will point downwards. If set to @code{1}, the appendage will point
4142 upwards. Other values such as @code{0} are reserved for future
4143 extensions and should not be used.
4149 \property Staff.Custos \set #'neutral-position = #4
4150 \property Staff.Custos \set #'neutral-direction = #-1
4151 \property Staff.Custos \set #'adjust-if-on-staffline = ##t
4159 @subsection Divisiones
4165 A @emph{divisio} (plural: @emph{divisiones}; latin word for
4166 `division') is a staff context symbol that is used to structure
4167 Gregorian music into phrases and sections. The musical meaning of
4168 @emph{divisio minima}, @emph{divisio maior} and @emph{divisio maxima}
4169 can be characterized as short, medium and long pause, somewhat like
4170 @ref{Breath marks}. The @emph{finalis} sign not only marks the end of
4171 a chant, but is also frequently used within a single
4172 antiphonal/responsorial chant to mark the end of each section.
4174 To use divisiones, just include the file @code{gregorian-init.ly}. It
4175 contains definitions that you can apply by just inserting
4176 @code{\divisiominima}, @code{\divisiomaior}, @code{\divisiomaxima},
4177 and @code{\finalis} at proper places into your lilypond files.
4180 \include "gregorian-init.ly"
4183 \context Staff = staff \addlyrics \notes \transpose c c' {
4184 \property Score.timing = ##f
4185 \property Score.barAlways = ##t
4186 \property Staff.BarLine \override #'transparent = ##t
4187 \property Voice.Stem \override #'transparent = ##t
4189 ^\markup { "divisio minima" }
4192 ^\markup { "divisio maior" }
4195 ^\markup { "divisio maxima" }
4198 ^\markup { "finalis" }
4202 \context Lyrics = lyrics \lyrics {
4203 Blah blub, blah blam.
4204 Blah blub, blah blam.
4205 Blah blub, blah blam.
4206 Blah blub, blah blam.
4207 Blah blub, blah blam.
4213 Some editions use @emph{virgula} or @emph{caesura} instead of divisio
4214 minima. Therefore, @code{gregorian-init.ly} also defines
4215 @code{\virgula} and @code{\caesura}.
4218 \include "gregorian-init.ly"
4221 \context Staff = staff \addlyrics \notes \transpose c c' {
4222 \property Score.timing = ##f
4223 \property Score.barAlways = ##t
4224 \property Staff.BarLine \override #'transparent = ##t
4225 \property Voice.Stem \override #'transparent = ##t
4227 ^\markup { "virgula" }
4230 ^\markup { "caesura" }
4234 \context Lyrics = lyrics \lyrics {
4235 Blah blub, blah blam.
4236 Blah blub, blah blam.
4237 Blah blub, blah blam.
4244 @subsection Ligatures
4248 @c TODO: Should double check if I recalled things correctly when I wrote
4249 @c down the following paragraph by heart.
4250 In musical terminology, a ligature is a coherent graphical symbol that
4251 represents at least two different notes. Ligatures originally appeared
4252 in the manuscripts of Gregorian chant notation roughly since the 9th
4253 century as an allusion to the accent symbols of greek lyric poetry to
4254 denote ascending or descending sequences of notes. Both, the shape and
4255 the exact meaning of ligatures changed tremendously during the following
4256 centuries: In early notation, ligatures where used for monophonic tunes
4257 (Gregorian chant) and very soon denoted also the way of performance in
4258 the sense of articulation. With upcoming multiphony, the need for a
4259 metric system arised, since multiple voices of a piece have to be
4260 synchronized some way. New notation systems were invented, that used
4261 the manifold shapes of ligatures to now denote rhythmical patterns
4262 (e.g. black mensural notation, mannered notation, ars nova). With the
4263 invention of the metric system of the white mensural notation, the need
4264 for ligatures to denote such patterns disappeared. Nevertheless,
4265 ligatures were still in use in the mensural system for a couple of
4266 decades until they finally disappeared during the late 16th / early 17th
4267 century. Still, ligatures have survived in contemporary editions of
4268 Gregorian chant such as the Editio Vaticana from 1905/08.
4270 Syntactically, ligatures are simply enclosed by @code{\[} and @code{\]}.
4271 Some ligature styles (such as Editio Vaticana) may need additional input
4272 syntax specific for this particular type of ligature. By default, the
4273 @internalsref{LigatureBracket} engraver just marks the start and end of
4274 a ligature by small square angles:
4276 @lilypond[singleline,verbatim]
4278 \notes \transpose c c' {
4286 To select a specific style of ligatures, a proper ligature engraver has
4287 to be added to the @internalsref{Voice} context, as explained in the
4288 following subsections. Currently, Lilypond only supports white mensural
4289 ligatures with certain limitations. Support for Editio Vaticana will be
4290 added in the future.
4293 * White mensural ligatures::
4296 @node White mensural ligatures
4297 @subsubsection White mensural ligatures
4299 @cindex Mensural ligatures
4300 @cindex White mensural ligatures
4302 Lilypond has limited support for white mensural ligatures. The
4303 implementation is still experimental; it currently may output strange
4304 warnings or even crash in some cases or produce weird results on more
4305 complex ligatures. To engrave white mensural ligatures, in the paper
4306 block the @internalsref{MensuralLigature} engraver has to be put into
4307 the @internalsref{Voice} context (and you probably want to remove the
4308 @internalsref{LigatureBracket} engraver). There is no additional input
4309 language to describe the shape of a white mensural ligature. The shape
4310 is rather determined solely from the pitch and duration of the enclosed
4311 notes. While this approach may take a new user quite a while to get
4312 accustomed, it has a great advantage: this way, lily has full musical
4313 information about the ligature. This is not only required for correct
4314 MIDI output, but also allows for automatic transcription of the
4319 @lilypond[singleline,verbatim]
4321 \notes \transpose c c' {
4322 \property Score.timing = ##f
4323 \property Score.defaultBarType = "empty"
4324 \property Voice.NoteHead \set #'style = #'neo_mensural
4325 \property Staff.TimeSignature \set #'style = #'neo_mensural
4327 \[ g\longa c\breve a\breve f\breve d'\longa \]
4329 \[ e1 f1 a\breve g\longa \]
4334 \remove Ligature_bracket_engraver
4335 \consists Mensural_ligature_engraver
4341 Without replacing @code{Ligature_bracket_engraver} with
4342 @code{Mensural_ligature_engraver}, the same music transcribes to the
4345 @lilypond[singleline,verbatim]
4347 \notes \transpose c c' {
4348 \property Score.timing = ##f
4349 \property Score.defaultBarType = "empty"
4350 \property Voice.NoteHead \set #'style = #'neo_mensural
4351 \property Staff.TimeSignature \set #'style = #'neo_mensural
4353 \[ g\longa c\breve a\breve f\breve d'\longa \]
4355 \[ e1 f1 a\breve g\longa \]
4361 @subsection Figured bass
4363 @cindex Basso continuo
4365 LilyPond has limited support for figured bass:
4367 @lilypond[verbatim,fragment]
4369 \context Voice \notes { \clef bass dis4 c d ais}
4370 \context FiguredBass
4372 < 6 >4 < 7 >8 < 6+ [_!] >
4378 The support for figured bass consists of two parts: there is an input
4379 mode, introduced by @code{\figures}, where you can enter bass figures
4380 as numbers, and there is a context called @internalsref{FiguredBass}
4381 that takes care of making @internalsref{BassFigure} objects.
4383 In figures input mode, a group of bass figures is delimited by
4384 @code{<} and @code{>}. The duration is entered after the @code{>}.
4389 \context FiguredBass
4393 Accidentals are added to the numbers if you alterate them by
4394 appending @code{-}, @code{!} and @code{+}.
4400 \context FiguredBass
4401 \figures { <4- 6+ 7!> }
4404 Spaces or dashes may be inserted by using @code{_}. Brackets are
4405 introduced with @code{[} and @code{]}.
4411 \context FiguredBass
4412 \figures { < [4 6] 8 [_ 12]> }
4415 Although the support for figured bass may superficially resemble chord
4416 support, it works much simpler: in figured bass simply stores the
4417 numbers, and then prints the numbers you entered. There is no
4418 conversion to pitches, and no realizations of the bass are played in
4421 Internally, the code produces markup texts internally. You can use any
4422 of the markup text properties to override formatting. For example, the
4423 vertical spacing of the figures may be set with @code{baseline-skip}.
4426 @node Contemporary notation
4427 @section Contemporary notation
4435 @subsection Clusters
4439 In musical terminology, a @emph{cluster} denotes a range of
4440 simultaneously sounding pitches that may change over time. The set of
4441 available pitches to apply usually depends on the accoustic source.
4442 Thus, in piano music, a cluster typically consists of a continous range
4443 of the semitones as provided by the piano's fixed set of a chromatic
4444 scale. In choral music, each singer of the choir typically may sing an
4445 arbitrary pitch within the cluster's range that is not bound to any
4446 diatonic, chromatic or other scale. In electronic music, a cluster
4447 (theoretically) may even cover a continuous range of pitches, thus
4448 resulting in coloured noise, such as pink noise.
4450 Clusters can be notated in the context of ordinary staff notation by
4451 engraving simple geometrical shapes that replace ordinary notation of
4452 notes. Ordinary notes as musical events specify starting time and
4453 duration of pitches; however, the duration of a note is expressed by the
4454 shape of the note head rather than by the horizontal graphical extent of
4455 the note symbol. In contrast, the shape of a cluster geometrically
4456 describes the development of a range of pitches (vertical extent) over
4457 time (horizontal extent). Still, the geometrical shape of a cluster
4458 covers the area in wich any single pitch contained in the cluster would
4459 be notated as an ordinary note. From this point of view, it is
4460 reasonable to specify a cluster as the envelope of a set of notes. This
4461 is exactly how to construct a cluster with lilypond.
4463 @lilypond[singleline,verbatim]
4465 \context PianoStaff <
4466 \context Voice = voiceI { % same as voiceII, but with ordinary notes
4467 \notes \relative c' {
4469 a4 <e4 d'4> | \break
4470 < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 |
4474 \context Voice = voiceII { % same as voiceI, but with cluster notation
4475 \notes \relative c' {
4477 % hide notes, accidentals, etc.
4478 \property Thread.NoteHead \set #'transparent = ##t
4479 \property Voice.Stem \set #'transparent = ##t
4480 \property Voice.Beam \set #'transparent = ##t
4481 \property Staff.Accidental \set #'transparent = ##t
4483 \property Voice.Cluster \set #'padding = #0.01
4484 \property Voice.Cluster \set #'shape = #'ramp
4488 a4 <e4 d'4> | \break
4489 < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 |
4490 c4 \stopCluster a4 f4 g4 a4
4497 Note that the second voice differs from the first one only by the
4498 additional keywords @code{\startCluster} and @code{\stopCluster} and the
4499 fact that notes, accidentals, etc. are hidden. A future version of
4500 lilypond may automatically hide notes, accidentals, etc. within the
4503 Also note that a music expression like @code{< @{ g8 e8 @} a4 >} is
4504 illegal; in such a case, you can instead use the expression @code{< g8
4507 By default, cluster engraver is in the voice context. This allows
4508 putting ordinary notes and clusters together in the same staff, even
4509 simultaneously. However, in such a case no attempt is made to
4510 automatically avoid collisions between ordinary notes and clusters.
4512 The geometrical shape can be further controlled with grob properties
4513 @code{padding} and @code{shape}. @code{padding} adds to the vertical
4514 extent of the shape (top and bottom) and is expressed in units of
4515 staffspace. Since the pitch range of a single pitch is infinitely
4516 small, if padding is set to @code{0.0}, this possibly results in an
4517 invisible shape, if you,for example, say @code{ \startCluster c d e
4518 \endCluster}. The default value for @code{padding} therefore is
4519 @code{0.25}, such that a single pitch roughly shows the same height as a
4520 note head. Property @code{shape} controls how the overall shape of the
4521 cluster is constructed from the set of notes. Currently supported
4522 values are @code{leftsided-stairs}, @code{rightsided-stairs},
4523 @code{centered-stairs}, and @code{ramp}.
4526 @subsection Fermatas
4530 Currently, lilypond supports the following fermata symbols that are
4531 frequently used in contemporary music notation:
4533 @lilypond[singleline,verbatim]
4540 ^\markup { short fermata }
4545 ^\markup { fermata }
4550 ^\markup { long fermata }
4555 ^\markup { very long fermata }
4561 See @ref{Articulations} for general instructions how to apply scripts
4562 such as fermatas to a @code{\notes@{@}} block.
4566 @section Tuning output
4568 LilyPond tries to take as much formatting as possible out of your
4569 hands. Nevertheless, there are situations where it needs some help, or
4570 where you want to override its decisions. In this section we discuss
4571 ways to do just that.
4573 Formatting is internally done by manipulating so called objects (graphic
4574 objects). Each object carries with it a set of properties (object
4575 properties) specific to that object. For example, a stem object has
4576 properties that specify its direction, length and thickness.
4578 The most direct way of tuning the output is by altering the values of
4579 these properties. There are two ways of doing that: first, you can
4580 temporarily change the definition of a certain type of object, thus
4581 affecting a whole set of objects. Second, you can select one specific
4582 object, and set a object property in that object.
4585 * Tuning groups of objects ::
4586 * Tuning per object ::
4591 @node Tuning groups of objects
4592 @subsection Tuning groups of objects
4594 @cindex object description
4596 A object definition is a Scheme association list, that is stored in a
4597 context property. By assigning to that property (using plain
4598 @code{\property}), you can change the resulting objects.
4600 @lilypond[verbatim, fragment,quote]
4601 c'4 \property Voice.NoteHead = #'() c'4
4603 This mechanism is fairly crude, since you can only set, but not modify,
4604 the definition of an object. Also, it will thoroughly confuse LilyPond.
4606 The definition of an object is actually a list of default object
4607 properties. For example, the definition of the Stem object (available
4608 in @file{scm/grob-description.scm}), includes the following definitions for
4613 (beamed-lengths . (0.0 2.5 2.0 1.5))
4614 (Y-extent-callback . ,Stem::height)
4618 You can add a property on top of the existing definition, or remove a
4619 property, thus overriding the system defaults:
4620 @lilypond[verbatim,quote]
4621 c'4 \property Voice.Stem \override #'thickness = #4.0
4622 c'4 \property Voice.Stem \revert #'thickness
4625 You should balance @code{\override} and @code{\revert}. If that is too
4626 much work, you can use the @code{\set} shorthand. It performs a revert
4627 followed by an override. The following example gives exactly the same
4628 result as the previous one.
4629 @lilypond[verbatim,quote]
4630 c'4 \property Voice.Stem \set #'thickness = #4.0
4631 c'4 \property Voice.Stem \set #'thickness = #0.8
4634 If you use @code{\set}, you must explicitly restore the default.
4637 Formally the syntax for these constructions is
4639 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
4640 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
4641 \property @var{context}.@var{grobname} \revert @var{symbol}
4643 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
4644 and @var{grobname} are strings and @var{value} is a Scheme expression.
4647 If you revert a setting which was not set in the first place, then it
4648 has no effect. However, if the setting was set as a system default, it
4649 may remove the default value, and this may give surprising results,
4650 including crashes. In other words, @code{\override} and @code{\revert},
4651 must be carefully balanced.
4653 These are examples of correct nesting of @code{\override}, @code{\set},
4656 A clumsy but correct form:
4658 \override \revert \override \revert \override \revert
4661 Shorter version of the same:
4663 \override \set \set \revert
4666 A short form, using only @code{\set}. This requires you to know the
4669 \set \set \set \set @var{to default value}
4672 If there is no default (i.e. by default, the object property is unset),
4675 \set \set \set \revert
4678 For the digirati, the object description is an Scheme association
4679 list. Since a Scheme list is a singly linked list, we can treat it as a
4680 stack, and @code{\override} and @code{\revert} are just push and pop
4681 operations. This pushing and popping is also used for overriding
4682 automatic beaming settings.
4686 LilyPond will hang or crash if @var{value} contains cyclic references.
4687 The backend is not very strict in type-checking object properties. If you
4688 @code{\revert} properties that are expected to be set by default,
4694 @node Tuning per object
4695 @subsection Tuning per object
4698 Tuning a single object is most often done with @code{\property}. The
4701 \once \property @dots{}
4704 applies a setting only during one moment in the score: the
4705 original setting for stem thickness is restored automatically in the
4708 @lilypond[verbatim, fragment, relative=1]
4710 \once \property Voice.Stem \set #'thickness = #4
4716 @cindex \outputproperty
4718 A second way of tuning objects is the more arcane @code{\outputproperty}
4719 feature. The syntax is as follows:
4721 \outputproperty @var{predicate} @var{symbol} = @var{value}
4723 Here @code{predicate} is a Scheme function taking a object argument, and
4724 returning a boolean. This statement is processed by the
4725 @code{Output_property_engraver}. It instructs the engraver to feed all
4726 objects that it sees to @var{predicate}. Whenever the predicate returns
4727 true, the object property @var{symbol} will be set to @var{value}.
4729 This command is only single shot, in contrast to @code{\override} and
4732 You will need to combine this statement with @code{\context} to select
4733 the appropriate context to apply this to.
4735 In the following example, all note heads occurring at current staff
4736 level, are shifted up and right by setting their @code{extra-offset}
4739 @lilypond[fragment,verbatim,singleline]
4741 \context Staff \outputproperty
4742 #(make-type-checker 'note-head-interface)
4743 #'extra-offset = #'(0.5 . 0.75)
4747 @cindex @code{extra-offset}
4749 In this example, the predicate checks the @code{text} object property, to
4750 shift only the `m.d.' text, but not the fingering instruction "2".
4751 @lilypond[verbatim,singleline]
4752 #(define (make-text-checker text)
4753 (lambda (grob) (equal? text (ly:get-grob-property grob 'text))))
4756 \notes\relative c''' {
4757 \property Voice.Stem \set #'direction = #1
4758 \outputproperty #(make-text-checker "m.d.")
4759 #'extra-offset = #'(-3.5 . -4.5)
4767 If possible, avoid this feature: the semantics are not very clean, and
4768 the syntax and semantics are up for rewrite.
4773 @node Font selection
4774 @subsection Font selection
4776 The most common thing to change about the appearance of fonts is
4777 their size. The font size of a @internalsref{Voice},
4778 @internalsref{Staff} or @internalsref{Thread} context, can be easily
4779 changed by setting the @code{fontSize} property for that context:
4780 @lilypond[fragment,relative=1,verbatim,quote]
4781 c4 c4 \property Voice.fontSize = #-1
4784 This command will not change the size of variable symbols, such as
4785 beams or slurs. You can use this command to get smaller symbol for
4786 cue notes, but that involves some more subtleties. An elaborate
4787 example of those is in @inputfileref{input/test,cue-notes.ly}.
4795 The font used for printing a object can be selected by setting
4796 @code{font-name}, e.g.
4798 \property Staff.TimeSignature
4799 \set #'font-name = #"cmr17"
4801 You may use any font which is available to @TeX{}, such as foreign
4802 fonts or fonts that do not belong to the Computer Modern font family.
4803 Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
4804 can also be adjusted with a more fine-grained mechanism. By setting
4805 the object properties described below, you can select a different font.
4806 All three mechanisms work for every object that supports
4807 @code{font-interface}.
4811 A symbol indicating the general class of the typeface. Supported are
4812 @code{roman} (Computer Modern), @code{braces} (for piano staff
4813 braces), @code{music} (the standard music font), @code{ancient} (the
4814 ancient notation font) @code{dynamic} (font for dynamic signs) and
4818 A symbol indicating the shape of the font, there are typically several
4819 font shapes available for each font family. Choices are @code{italic},
4820 @code{caps} and @code{upright}
4823 A symbol indicating the series of the font. There are typically several
4824 font series for each font family and shape. Choices are @code{medium}
4827 @item font-relative-size
4828 A number indicating the size relative the standard size. For example,
4829 with 20pt staff height, relative size -1 corresponds to 16pt staff
4830 height, and relative size +1 corresponds to 23 pt staff height.
4832 @item font-design-size
4833 A number indicating the design size of the font.
4835 This is a feature of the Computer Modern Font: each point size has a
4836 slightly different design. Smaller design sizes are relatively wider,
4837 which enhances readability.
4840 For any of these properties, the value @code{*} (i.e. the @emph{symbol},
4841 @code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
4842 to override default setting, which are always present. For example:
4844 \property Lyrics.LyricText \override #'font-series = #'bold
4845 \property Lyrics.LyricText \override #'font-family = #'typewriter
4846 \property Lyrics.LyricText \override #'font-shape = #'*
4849 @cindex @code{font-style}
4851 There are also pre-cooked font selection qualifiers. These are
4852 selected through the object property @code{font-style}. For example,
4853 the style @code{finger} selects family @code{number} and relative size
4854 @code{-3}. Styles available include @code{volta}, @code{finger},
4855 @code{tuplet}, @code{timesig}, @code{mmrest}, @code{script},
4856 @code{large}, @code{Large} and @code{dynamic}. The style sheets and
4857 tables for selecting fonts are located in @file{scm/font.scm}. Refer
4858 to this file for more information.
4860 @cindex magnification
4862 The size of the font may be scaled with the object property
4863 @code{font-magnification}. For example, @code{2.0} blows up all
4864 letters by a factor 2 in both directions.
4868 Relative size is not linked to any real size.
4870 There is no style sheet provided for other fonts besides the @TeX{}
4871 family, and the style sheet can not be modified easily.
4873 @cindex font selection
4874 @cindex font magnification
4875 @cindex @code{font-interface}
4879 @subsection Text markup
4884 @cindex typeset text
4886 LilyPond has an internal mechanism to typeset texts. You can access it
4887 with the keyword @code{\markup}. Within markup mode, you can enter texts
4888 similar to lyrics: simply enter them, surrounded by spaces.
4891 @lilypond[verbatim,fragment,relative=1]
4892 c1^\markup { hello }
4893 c1_\markup { hi there }
4894 c1^\markup { hi \bold there, is \italic anyone home? }
4897 @cindex font switching
4899 The line of the example demonstrates font switching commands. The
4900 command only apply to the first following word; enclose a set of texts
4901 with braces to apply a command to more words.
4903 \markup @{ \bold @{ hi there @} @}
4905 For clarity, you can also do this for single arguments, e.g.
4907 \markup @{ is \italic @{ anyone @} home @}
4910 @cindex font size, texts
4912 The following size commands set abolute sizes
4928 You can also make letter larger or smaller relative to their neighbors,
4929 with the commands @code{\larger} and @code{\smaller}.
4933 @cindex font style, for texts
4939 The following font change commands are defined:
4942 This changes to the font used for dynamic signs. Note that this font
4943 does not contain all characters of the alphabet.
4945 This changes to the font used for time signatures. It only contains
4946 numbers and a few punctuation marks.
4951 @cindex raising text
4952 @cindex lowering text
4954 @cindex translating text
4959 Raising and lowering texts can be done with @code{\super} and
4962 @lilypond[verbatim,fragment,relative=1]
4963 c1^\markup { E "=" mc \super "2" }
4968 If you want to give an explicit amount for lowering or raising, use
4969 @code{\raise}. This command takes a Scheme valued argument,
4970 @lilypond[verbatim,fragment,relative=1,quote]
4971 c1^\markup { C \small \raise #1.0 { "9/7+" }}
4973 The argument to @code{\raise} is the vertical displacement amount,
4974 measured in (global) staff spaces.
4976 Other commands taking single arguments include
4979 @item \bracket, \hbracket
4980 Bracket the argument markup.
4984 This is converted to a musical symbol, e.g. @code{\musicglyph
4985 #"accidentals-0"} will select the natural sign from the music font.
4986 See @ref{The Feta font} for a complete listing of the possible glyphs.
4988 This produces a single character, e.g. @code{\char #65} produces the
4991 @item \hspace #@var{amount}
4993 This produces a invisible object taking horizontal space.
4995 \markup @{ A \hspace #2.0 B @}
4997 will put extra space between A and B. Note that lilypond
4998 inserts space before and after @code{\hspace}.
5000 @item \fontsize #@var{size}
5002 This sets the relative font size, eg.
5004 A \fontsize #2 @{ B C @} D
5008 This will enlarge the B and the C by two steps.
5009 @item \translate #(cons @var{x} @var{y})
5011 This translates an object. Its first argument is a cons of numbers
5013 A \translate #(cons 2 -3) @{ B C @} D
5015 This moves `B C' 2 spaces to the right, and 3 down.
5017 @item \magnify #@var{mag}
5019 This sets the font magnification for the its argument. In the following
5020 example, the middle A will be 10% larger.
5022 A \magnify #1.1 @{ A @} A
5026 @item \override #(@var{key} . @var{value})
5028 This overrides a formatting property for its argument. The argument
5029 should be a key/value pair, e.g.
5031 m \override #'(font-family . math) m m
5035 In markup mode you can compose expressions, similar to mathematical
5036 expressions, XML documents and music expressions. The braces group
5037 notes into horizontal lines. Other types of lists also exist: you can
5038 stack expressions grouped with @code{<<}, and @code{>>} vertically with
5039 the command @code{\column}. Similarly, @code{\center} aligns texts by
5042 @lilypond[verbatim,fragment,relative=1]
5043 c1^\markup { \column << a bbbb c >> }
5044 c1^\markup { \center << a bbbb c >> }
5045 c1^\markup { \line << a b c >> }
5050 The markup mechanism is very flexible and extensible. Refer to
5051 @file{scm/new-markup.scm} for more information on extending the markup
5055 @cindex metronome mark
5057 One practical application of complicated markup is to fake a metronome
5061 eighthStem = \markup \combine
5062 \musicglyph #"flags-stem"
5063 \translate #'(0.0 . 3.5) \musicglyph #"flags-u3"
5064 eighthNote = \markup
5065 \override #'(word-space . 0.0)
5066 { \musicglyph #"noteheads-2"
5067 \translate #'(-0.05 . 0.1) \eighthStem }
5070 \notes\relative c'' {
5071 a1^\markup { \magnify #0.9 \eighthNote " = 64" }
5080 LilyPond does not account for kerning in its text formatting, so it
5081 spaces texts slightly too wide.
5083 Syntax errors for markup mode are confusing.
5087 @section Global layout
5089 The global layout determined by three factors: the page layout, the
5090 line breaks and the spacing. These all influence each other: The
5091 choice of spacing determines how densely each system of music is set,
5092 where line breaks breaks are chosen, and thus ultimately how many
5093 pages a piece of music takes. In this section we will explain how the
5094 lilypond spacing engine works, and how you can tune its results.
5096 Globally spoken, this procedure happens in three steps: first,
5097 flexible distances (``springs'') are chosen, based on durations. All
5098 possible line breaking combination are tried, and the one with the
5099 best results---a layout that has uniform density and requires as
5100 little stretching or cramping as possible---is chosen. When the score
5101 is processed by @TeX{}, page are filled with systems, and page breaks
5102 are chosen whenever the page gets full.
5105 * Vertical spacing::
5106 * Horizontal spacing::
5113 @node Vertical spacing
5114 @subsection Vertical spacing
5116 @cindex vertical spacing
5117 @cindex distance between staves
5118 @cindex staff distance
5119 @cindex between staves, distance
5120 @cindex staffs per page
5123 The height of each system is determined automatically by lilypond, to
5124 keep systems from bumping into each other, some minimum distances are
5125 set. By changing these, you can put staves closer together, and thus
5126 put more systems onto one page.
5128 Normally staves are stacked vertically. To make
5129 staves maintain a distance, their vertical size is padded. This is
5130 done with the property @code{minimumVerticalExtent}. It takes a pair
5131 of numbers, so if you want to make it smaller from its, then you could
5134 \property Staff.minimumVerticalExtent = #'(-4 . 4)
5136 This sets the vertical size of the current staff to 4 staff-space on
5137 either side of the center staff line. The argument of
5138 @code{minimumVerticalExtent} is interpreted as an interval, where the
5139 center line is the 0, so the first number is generally negative. you
5140 could also make the staff larger at the bottom by setting it to
5141 @code{(-6 . 4)}. The default value is @code{(-6 . 6)}.
5143 Vertical aligment of staves is handled by the
5144 @internalsref{VerticalAlignment} object, which lives at
5145 @internalsref{Score} level.
5147 The piano staves are handled a little differently: to make cross-staff
5148 beaming work correctly, it necessary that the distance between staves
5149 is fixed. This is also done with a @internalsref{VerticalAlignment}
5150 object, created in @internalsref{PianoStaff}, but a forced distance is
5151 set. This is done with the object property #'forced-distance. If you
5152 want to override this, use a @code{\translator} block as follows:
5156 VerticalAlignment \override #'forced-distance = #9
5159 This would bring the staves together at a distance of 9 staff spaces,
5160 and again this is measured from the center line of each staff.
5164 @node Horizontal spacing
5165 @subsection Horizontal Spacing
5167 The spacing engine translates differences in durations into
5168 stretchable distances (``springs'') of differing lengths. Longer
5169 durations get more space, shorter durations get less. The basis for
5170 assigning spaces to durations, is that the shortest durations get a
5171 fixed amount of space, and the longer durations get more: doubling a
5172 duration adds a fixed amount of space to the note.
5174 For example, the following piece contains lots of half, quarter and
5175 8th notes, the eighth note is followed by 1 note head width. The The
5176 quarter note is followed by 2 NHW, the half by 3 NHW, etc.
5177 @lilypond[fragment, verbatim, relative=1]
5178 c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4
5181 These two amounts of space are @code{shortest-duration-space}
5182 @code{spacing-increment}, object properties of
5183 @internalsref{SpacingSpanner}. Normally @code{spacing-increment} is
5184 set to 1.2, which is the width of a note head, and
5185 @code{shortest-duration-space} is set to 2.0, meaning that the
5186 shortest note gets 2 noteheads of space. For normal notes, this space
5187 is always counted from the left edge of the symbol, so the short notes
5188 in a score is generally followed by one note head width of space.
5190 If one would follow the above procedure exactly, then adding a single
5191 32th note to a score that uses 8th and 16th notes, would widen up the
5192 entire score a lot. The shortest note is no longer a 16th, but a 64th,
5193 thus adding 2 noteheads of space to every note. To prevent this, the
5194 shortest duration for spacing is not the shortest note in the score,
5195 but the most commonly found shortest note. Notes that are even
5196 shorter this are followed by a space that is proportonial to their
5197 duration relative to the common shortest note. So if we were to add
5198 only a few 16th notes to the example above, they would be followed by
5201 @lilypond[fragment, verbatim, relative=1]
5202 c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4
5205 The most common shortest duration is determined as follows: in every
5206 measure, the shortest duration is determined. The most common short
5207 duration, is taken as the basis for the spacing, with the stipulation
5208 that this shortest duration should always be equal to or shorter than
5209 1/8th note. The shortest duration is printed when you run lilypond
5210 with @code{--verbose}. These durations may also be customized. If you
5211 set the @code{common-shortest-duration} in
5212 @internalsref{SpacingSpanner}, then this sets the base duration for
5213 spacing. The maximum duration for this base (normally 1/8th), is set
5214 through @code{base-shortest-duration}.
5216 @cindex @code{common-shortest-duration}
5217 @cindex @code{base-shortest-duration}
5218 @cindex @code{stem-spacing-correction}
5219 @cindex @code{spacing}
5221 In the introduction it was explained that stem directions influence
5222 spacing. This is controlled with @code{stem-spacing-correction} in
5223 @internalsref{NoteSpacing}. The @code{StaffSpacing} object contains the
5224 same property for controlling the stem/barline spacing. In the
5225 following example shows these corrections, once with default settings,
5226 and once with exaggerated corrections.
5232 \property Staff.NoteSpacing \override #'stem-spacing-correction
5234 \property Staff.StaffSpacing \override #'stem-spacing-correction
5239 \paper { linewidth = -1. } }
5242 @cindex SpacingSpanner, overriding properties
5244 The @internalsref{SpacingSpanner}, is score wide, so its properties
5245 must be overriden from the @code{\paper} block, e.g.
5247 \paper @{ \translator @{
5249 SpacingSpanner \override #'spacing-increment = #3.0
5256 Spacing is determined on a score wide basis. If you have a score that
5257 changes its character (measured in durations) halfway during the
5258 score, the part containing the longer durations will be spaced too
5261 Generating optically pleasing spacing is black magic. LilyPond tries
5262 to deal with a number of frequent cases. Here is an example that is
5263 not handled correctly, due to the combination of chord collisions and
5268 \context PianoStaff \notes \transpose c c'' <
5269 \context Staff = up { s1 }
5270 \context Staff = down { [c8 c \translator Staff=up <<c d>> c
5271 \translator Staff=down c c c] }
5273 \paper { linewidth = -1 }
5280 @subsection Font size
5281 @cindex font size, setting
5282 @cindex staff size, setting
5283 @cindex @code{paper} file
5285 The Feta font provides musical symbols at seven different sizes.
5286 These fonts are 11 point, 13 point, 16 point, 19 pt, 20 point, 23
5287 point, and 26 point. The point size of a font is the height of the
5288 five lines in a staff when displayed in the font.
5290 Definitions for these sizes are the files @file{paperSZ.ly}, where
5291 @code{SZ} is one of 11, 13, 16, 19, 20, 23 and 26. If you include any
5292 of these files, the identifiers @code{paperEleven},
5293 @code{paperThirteen}, @code{paperSixteen}, @code{paperNineteen},
5294 @code{paperTwenty}, @code{paperTwentythree}, and @code{paperTwentysix}
5295 are defined respectively. The default @code{\paper} block is also
5296 set. These files should be imported at toplevel, i.e.
5298 \include "paper26.ly"
5302 The font definitions are generated using a Scheme function. For more
5303 details, see the file @file{scm/font.scm}.
5308 @subsection Line breaking
5311 @cindex breaking lines
5313 Line breaks are normally computed automatically. They are chosen such
5314 that it looks neither cramped nor loose, and that consecutive lines have
5317 Occasionally you might want to override the automatic breaks; you can
5318 do this by specifying @code{\break}. This will force a line break at
5319 this point. Line breaks can only occur at places where there are bar
5320 lines. If you want to have a line break where there is no bar line,
5321 you can force an invisible bar line by entering @code{\bar
5322 ""}. Similarly, @code{\noBreak} forbids a line break at a certain
5326 @cindex regular line breaks
5327 @cindex four bar music.
5329 If you want linebreaks at regular intervals, you can use the following:
5331 < \repeat 7 unfold @{ s1 * 4 \break @}
5335 This makes the following 28 measures (assuming 4/4 time) be broken every
5339 @subsection Page layout
5342 @cindex breaking pages
5344 @cindex @code{indent}
5345 @cindex @code{linewidth}
5347 The most basic settings influencing the spacing are @code{indent} and
5348 @code{linewidth}. They are set in the @code{\paper} block. They
5349 control the indentation of the first line of music, and the lengths of
5350 the lines. If @code{linewidth} set to a negative value, a single
5351 unjustified line is produced. A similar effect for scores that are
5352 longer than one line, can be produced by setting @code{raggedright} to
5353 true in the @code{\paper} block.
5356 @cindex vertical spacing
5358 The page layout process happens outside lilypond. Ly2dvi sets page
5359 layout instructions. Ly2dvi responds to the following variables in the
5360 @code{\paper} block. The variable @code{textheight} sets the total
5361 height of the music on each page. The spacing between systems is
5362 controlled with @code{interscoreline}, its default is 16pt.
5363 The distance between the score lines will stretch in order to fill the
5364 full page @code{interscorelinefill} is set to a positive number. In
5365 that case @code{interscoreline} specifies the minimum spacing.
5367 @cindex @code{textheight}
5368 @cindex @code{interscoreline}
5369 @cindex @code{interscorelinefill}
5371 If the variable @code{lastpagefill} is defined (that is, it gets any
5372 value assigned in the @code{\paper} block), systems are evenly
5373 distributed vertically on the last page. This might produce ugly
5374 results in case there are not enough systems on the last page. Note
5375 that @command{lilypond-book} ignores @code{lastpagefill}. See
5376 @ref{Integrating text and music with lilypond-book} for
5379 @cindex @code{lastpagefill}
5381 Page breaks are normally computed by @TeX{}, so they are not under
5382 direct control of LilyPond. However, you can insert a commands into
5383 the @file{.tex} output to instruct @TeX{} where to break pages. You
5384 can insert a @code{\newpage} from within lilypond. This is done by
5385 setting the @code{between-systems-strings} on the
5386 @internalsref{NonMusicalPaperColumn} where the system is broken.
5390 @cindex @code{papersize}
5392 To change the paper size, you must first set the
5393 @code{papersize} paper variable variable. Set it to
5394 the strings @code{a4}, @code{letter}, or @code{legal}. After this
5395 specification, you must set the font as described above. If you want
5396 the default font, then use the 20 point font.
5399 \paper@{ papersize = "a4" @}
5400 \include "paper16.ly"
5403 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
5404 will set the paper variables @code{hsize} and @code{vsize} (used by
5405 Lilypond and @code{ly2dvi})
5415 LilyPond can produce MIDI output. The performance lacks lots of
5416 interesting effects, such as swing, articulation, slurring, etc., but it
5417 is good enough for proof-hearing the music you have entered. Ties,
5418 dynamics and tempo changes are interpreted.
5420 Dynamic marks, crescendi and decrescendi translate into MIDI volume
5421 levels. Dynamic marks translate to a fixed fraction of the available
5422 MIDI volume range, crescendi and decrescendi make the the volume vary
5423 linearly between their two extremities. The fractions be adjusted by
5424 overriding the @code{absolute-volume-alist} defined in
5425 @file{scm/midi.scm}.
5427 For each type of musical instrument (that MIDI supports), a volume range
5428 can be defined. This gives you basic equalizer control, which can
5429 enhance the quality of the MIDI output remarkably. You can add
5430 instruments and ranges or change the default settings by overriding the
5431 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
5433 Both loudness controls are combined to produce the final MIDI volume.
5437 * MIDI instrument names::
5442 @subsection MIDI block
5446 The MIDI block is analogous to the paper block, but it is somewhat
5447 simpler. The @code{\midi} block can contain:
5451 @item a @code{\tempo} definition
5452 @item context definitions
5455 Assignments in the @code{\midi} block are not allowed.
5459 @cindex context definition
5461 Context definitions follow precisely the same syntax as within the
5462 \paper block. Translation modules for sound are called performers.
5463 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
5466 @node MIDI instrument names
5467 @subsection MIDI instrument names
5469 @cindex instrument names
5470 @cindex @code{Staff.midiInstrument}
5471 @cindex @code{Staff.instrument}
5473 The MIDI instrument name is set by the @code{Staff.midiInstrument}
5474 property or, if that property is not set, the @code{Staff.instrument}
5475 property. The instrument name should be chosen from the list in
5476 @ref{MIDI instruments}.
5480 If the selected string does not exactly match, then LilyPond uses the
5481 default (Grand Piano). It is not possible to select an instrument by