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
16 @macro internalsref{NAME}
17 @uref{../lilypond-internals/\NAME\.html,\NAME\}
20 @macro seeinternals{NAME}
21 See @internalsref{\NAME\}
27 @macro seeinternals{NAME}
29 @macro internalsref{NAME}
35 @c .{Reference Manual}
37 @node Reference Manual
38 @chapter Reference Manual
41 <!--- @@WEB-TITLE@@=Reference Manual --->
44 This document describes GNU LilyPond and its input format. The last
45 revision of this document was made for LilyPond 1.4.1. It supposes a
46 passing familiarity with how LilyPond input works. New users are
47 encouraged to study the tutorial first.
72 * Skipping corrected music::
73 * Interpretation context::
78 @c FIXME: Note entry vs Music entry at top level menu is confusing.
84 The most basic forms of music are notes. Notes on their own don't
85 form valid input, but for the sake of brevity we omit @code{\score}
86 blocks and @code{\paper} declarations.
92 * Chromatic alterations::
97 * Automatic note splitting ::
99 * Defining pitch names::
100 * Easy Notation note heads ::
108 A note is printed by specifying its pitch, and then its duration.
109 @lilypond[fragment,verbatim]
112 The grob for a note head is called @internalsref{NoteHead}.
119 @cindex Note specification
121 @cindex entering notes
123 The verbose syntax for pitch specification is
125 @cindex @code{\pitch}
127 \pitch @var{scmpitch}
130 @var{scmpitch} is a pitch scheme object.
132 In Note and Chord mode, pitches may be designated by names. The default
133 names are the Dutch note names. The notes are specified by the letters
134 @code{a} through @code{g} (where the octave is formed by notes ranging
135 from @code{c} to @code{b}). The pitch @code{c} is an octave below
136 middle C and the letters span the octave above that C.
138 @cindex note names, Dutch
140 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
141 name and a flat is formed by adding @code{-es}. Double sharps and double
142 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
143 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
144 both forms are accepted.
146 LilyPond has predefined sets of note names for various other languages.
147 To use them, simply include the language specific init file. For
148 example: @code{\include "english.ly"}. The available language files and
149 the names they define are:
152 Note Names sharp flat
153 nederlands.ly c d e f g a bes b -is -es
154 english.ly c d e f g a bf b -s/-sharp -f/-flat
155 deutsch.ly c d e f g a b h -is -es
156 norsk.ly c d e f g a b h -iss/-is -ess/-es
157 svenska.ly c d e f g a b h -iss -ess
158 italiano.ly do re mi fa sol la sib si -d -b
159 catalan.ly do re mi fa sol la sib si -d/-s -b
160 espanol.ly do re mi fa sol la sib si -s -b
169 The optional octave specification takes the form of a series of
170 single quote (`@code{'}') characters or a series of comma
171 (`@code{,}') characters. Each @code{'} raises the pitch by one
172 octave; each @code{,} lowers the pitch by an octave.
174 @lilypond[fragment,verbatim,center]
175 c' c'' es' g' as' gisis' ais'
178 @node Chromatic alterations
179 @subsection Chromatic alterations
181 Normally Accidentals signify that the pitch of a note differs from the
182 key signature. Normally, they are printed automatically depending, but
183 you may force accidentals in the following ways:
184 A reminder accidental
185 @cindex reminder accidental
187 can be forced by adding an exclamation mark @code{!} after the pitch. A
188 cautionary accidental,
189 @cindex cautionary accidental
190 @cindex parenthesized accidental
191 i.e., an accidental within parentheses can be obtained by adding the
192 question mark `@code{?}' after the pitch.
194 Each accidental symbol is an @internalsref{Accidental} grob. The
195 placement of accidentals is handled by
196 @internalsref{AccidentalPlacement}.
204 A rest is entered like a note, with note name `@code{r}':
206 @lilypond[singleline,verbatim]
210 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
211 specified using @code{R}, see @ref{Multi measure rests}.
213 For polyphonic music, it can be convenient to specify the rest position
214 directly. You can do that by entering a note, with the keyword
215 @code{\rest} appended, e.g. Rest collisions will leave these rests alone.
217 @lilypond[singleline,verbatim]
227 @cindex Invisible rest
230 An invisible rest, or skip, can be entered like a note with note name
231 @code{s}, or with @code{\skip @var{duration}}:
233 @lilypond[singleline,verbatim]
237 The @code{s} syntax is only available in Note mode and Chord mode.
238 In other situations, you should use the @code{\skip} command, and it is
239 only available in Note mode and Chord mode.
241 @c FIXME: in lyrics mode, we have " " and _
243 In Lyrics mode, you can use `@code{" "}' and `@code{_}':
244 @lilypond[singleline,verbatim]
246 \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
247 \notes\relative c'' { a2 a4 a a2 a4 a }
251 The unabbreviated `@code{\skip} @var{duration}' also works outside of
254 @lilypond[singleline,verbatim]
257 { \time 4/8 \skip 2 \time 4/4 }
258 \notes\relative c'' { a2 a1 }
263 The skip command is merely a empty musical placeholder. It does not
264 produce any output, not even transparent output.
269 @subsection Durations
273 @cindex @code{\duration}
275 The syntax for a verbose duration specification is
277 \duration @var{scmduration}
279 Here, @var{scmduration} is a Scheme object of type @code{Duration}.
282 In Note, Chord, and Lyrics mode, durations may be designated by numbers
283 and dots: durations are entered as their reciprocal values. For notes
284 longer than a whole you must use identifiers.
288 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
290 r1 r2 r4 r8 r16 r32 r64 r64
296 \notes \relative c'' {
298 a1 a2 a4 a8 a16 a32 a64 a64
300 r1 r2 r4 r8 r16 r32 r64 r64
305 \remove "Clef_engraver"
306 \remove "Staff_symbol_engraver"
307 \remove "Time_signature_engraver"
308 \consists "Pitch_squash_engraver"
315 If the duration is omitted then it is set to the previous duration
316 entered. At the start of parsing a quarter note is assumed. The
317 duration can be followed by dots (`@code{.}') to obtain dotted note
321 @lilypond[fragment,verbatim,center]
327 You can alter the length of duration by a fraction @var{N/M} by
328 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
329 will not affect the appearance of the notes or rests produced.
341 A tie connects two adjacent note heads of the same pitch. The tie in
342 effect extends the length of a note. A tie is entered with @code{~}.
344 @lilypond[fragment,verbatim,center]
345 e' ~ e' <c' e' g'> ~ <c' e' g'>
348 When ties are used with chords, all note heads whose pitches match are
349 connected. Ties are indicated using the tilde symbol `@code{~}'. If
350 you try to tie together chords which have no common pitches then no
351 ties will be created.
353 If you want less ties created for a chord, you can set
354 @code{Voice.sparseTies} to true. In this case, a single tie is used
355 for every tied chord.
356 @lilypond[fragment,verbatim,center]
357 \property Voice.sparseTies = ##t
358 <c' e' g'> ~ <c' e' g'>
361 In its meaning a tie is just a way of extending a note duration, similar
362 to the augmentation dot: the following example are two ways of notating
363 exactly the same concept.
365 @lilypond[fragment, singleline]
366 \time 3/4 c'2. c'2 ~ c'4
368 Ties should not be confused with slurs, which indicate articulation,
369 and phrasing slurs, which indicate musical phrasing.
371 The name of the tie grob is @internalsref{Tie}, and it is created in the
372 @internalsref{Voice} context.
376 At present, the tie is implemented as a separate thing, temporally
377 located in between the notes.
378 Tieing only a subset of the note heads of a chord is not supported in a
379 simple way. It can be achieved by moving the tie-engraver into the Thread
380 context and turning on and off ties per Thread.
382 @node Automatic note splitting
383 @subsection Automatic note splitting
385 There is a facility for automatically converting long notes to tied
386 notes. This is done by replacing the @code{Note_heads_engraver} by the
387 @code{Completion_heads_engraver}.
389 @lilypond[verbatim,center]
391 \notes\relative c'{ \time 2/4
392 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
396 \remove "Note_heads_engraver"
397 \consists "Completion_heads_engraver"
401 This engraver splits all running notes at the bar line, and inserts
402 ties. One of the uses of this is, is to debug complex scores: if the
403 measures are not entirely filled, then the ties exactly show how much
408 Not all durations (especially those containing tuplets) can be
409 represented exactly; the engraver will not insert tuplets.
416 @cindex @code{\times}
418 Tuplets are made out of a music expression by multiplying all duration
421 @cindex @code{\times}
423 \times @var{fraction} @var{musicexpr}
426 The duration of @var{musicexpr} will be multiplied by the fraction.
427 In print, the fraction's denominator will be printed over the notes,
428 optionally with a bracket. The most common tuplet is the triplet in
429 which 3 notes have the length of 2, so the notes are 2/3 of
430 their written length:
432 @lilypond[fragment,verbatim,center]
433 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
436 The property @code{tupletSpannerDuration} specifies how long each bracket
437 should last. With this, you can make lots of tuplets while typing
438 @code{\times} only once, thus saving typing work.
440 @lilypond[fragment, relative, singleline, verbatim]
441 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
442 \times 2/3 { c'8 c c c c c }
445 The format of the number is determined by the property
446 @code{tupletNumberFormatFunction}. The default prints only the
447 denominator, but if you set it to the Scheme function
448 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
453 The typesetting of brackets and numbers is controlled by the properties
454 @code{bracket-visibility} and @code{number-visibility}. These
455 properties can either be @code{#f}, @code{#t} or @code{'if-no-beam},
456 meaning respectively off, on, and on if there is no beam.
458 @lilypond[fragment, relative, singleline, verbatim]
459 \property Voice.TupletBracket \set #'bracket-visibility = ##t
460 \times 2/3{c'8 d e} \times 2/3{d4 e8}
461 \property Voice.TupletBracket \set #'bracket-visibility = #'if-no-beam
462 \times 2/3{c d e} \times 2/3{d4 e8}
463 \property Voice.TupletBracket \set #'bracket-visibility = ##f
464 \times 2/3{c d e} \times 2/3{d4 e8}
465 \property Voice.TupletBracket \set #'number-visibility = ##f
466 \times 2/3{c d e} \times 2/3{d4 e8}
467 \property Voice.TupletBracket \set #'number-visibility = #'if-no-beam
468 \times 2/3{c d e} \times 2/3{d4 e8}
471 @cindex @code{tupletNumberFormatFunction}
472 @cindex tuplet formatting
474 Tuplet brackets are printed as @internalsref{TupletBracket} grobs in
475 the @internalsref{Voice} context.
477 @c . {Defining pitch names}
478 @node Defining pitch names
479 @subsection Defining pitch names
481 @cindex defining pitch names
482 @cindex pitch names, defining
484 Note names and chord modifiers can be customized for nationalities. The
485 syntax is as follows.
487 @cindex @code{\pitchnames}
488 @cindex @code{\chordmodifiers}
490 \pitchnames @var{scheme-alist}
491 \chordmodifiers @var{scheme-alist}
494 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers-init.ly} for
495 specific examples on how to do this.
498 @node Easy Notation note heads
499 @subsection Easy Notation note heads
501 @cindex easy notation
504 A entirely different type of note head is the "easyplay" note head: a
505 note head that includes a note name. It is used in some publications by
506 Hal-Leonard Inc. music publishers.
508 @lilypond[singleline,verbatim]
509 \include "paper23.ly"
511 \notes { c'2 e'4 f' | g'1 }
512 \paper { \translator { \EasyNotation } }
516 Note that @internalsref{EasyNotation} overrides a @internalsref{Score} context. You
517 probably will want to print it with magnification to make it more
518 readable, see @ref{Output scaling}.
524 If you view the result with Xdvi, then staff lines will show through the
525 letters. Printing the postscript file obtained either by using dvips or
526 the @code{-f ps} option of lilypond produces the correct result.
531 @section Staff notation
533 @cindex Staff notation
545 @subsection Key signature
550 Setting or changing the key signature is done with the @code{\key}
553 @code{\key} @var{pitch} @var{type}
556 @cindex @code{\minor}
557 @cindex @code{\major}
558 @cindex @code{\minor}
559 @cindex @code{\ionian}
560 @cindex @code{\locrian}
561 @cindex @code{\aeolian}
562 @cindex @code{\mixolydian}
563 @cindex @code{\lydian}
564 @cindex @code{\phrygian}
565 @cindex @code{\dorian}
567 Here, @var{type} should be @code{\major} or @code{\minor} to get
568 @var{pitch}-major or @var{pitch}-minor, respectively.
569 The standard mode names @code{\ionian},
570 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
571 @code{\phrygian}, and @code{\dorian} are also defined.
573 This command sets the context property @code{Staff.keySignature}.
574 Non-standard key signatures can be specified by setting this property
577 The printed signature is a @internalsref{KeySignature} grob, typically
578 created in @internalsref{Staff} context.
580 @cindex @code{keySignature}
587 The clef can be set or changed with the @code{\clef} command:
588 @lilypond[fragment,verbatim]
589 \key f\major c''2 \clef alto g'2
592 Supported clef-names include
593 @c Moved standard clefs to the top /MB
595 @item treble, violin, G, G2
604 G clef on 1st line, so-called French violin clef
619 By adding @code{_8} or @code{^8} to the clef name, the clef is
620 transposed one octave down or up, respectively. Note that you have to
621 enclose @var{clefname} in quotes if you use underscores or digits in the
627 The grob for this symbol is @internalsref{Clef}.
630 The full syntax for this command is
634 where @var{clefname} is a string. This command is a shortcut for
636 \property Staff.clefGlyph = @var{glyph associated with clefname}
637 \property Staff.clefPosition = @var{clef Y-position for clefname}
638 \property Staff.centralCPosition = @var{position for central C}
639 \property Staff.clefOctavation = @var{extra transposition of clefname}
641 Upon any change in these properties lilypond creates a clef
642 symbol. The mapping from @var{clefname} to the property values can be
643 found in @file{scm/clef.scm}
649 @c . {Time signature}
651 @subsection Time signature
652 @cindex Time signature
656 The time signature is set or changed by the @code{\time}
658 @lilypond[fragment,verbatim]
659 \time 2/4 c'2 \time 3/4 c'2.
662 The actual symbol that's printed can be customized with the style
664 @lilypond[fragment, verbatim, singleline]
666 \property Staff.TimeSignature \override #'style = #'C
668 \property Staff.TimeSignature \override #'style = #'()
670 \property Staff.TimeSignature \override #'style = #'C
674 The grob for this symbol is @internalsref{TimeSignature}. There are
675 many more options for its layout. They are selected through the
676 @code{style} grob property. See @file{input/test/time.ly} for more
680 The full syntax for this command is
682 \time @var{n}@code{/}@var{d}
684 where @var{n} and @var{d} are integers. This command is internally
685 translated, to the following:
687 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
688 \property Score.beatLength = #(make-moment 1 @var{d})
689 \property Score.measureLength = #(make-moment @var{n} @var{d})
692 The property @code{timeSignatureFraction} determine where bar lines
693 should be inserted, and how automatic beams should be generated.
694 Changing the value of @code{timeSignatureFraction} also causes a
695 fraction to be printed.
702 @cindex partial measure
703 @cindex measure, partial
704 @cindex shorten measures
705 @cindex @code{\partial}
707 Partial measures, for example in upbeats, are entered using the
708 @code{\partial} command:
709 @lilypond[fragment,verbatim]
710 \partial 4* 5/16 c'16 c8. f16 a'2. ~ a'8. a'16 | g'1
713 The syntax for this command is
715 \partial @var{duration}
717 This is internally translated into
719 \property Score.measurePosition = -@var{length of duration}
722 The property @code{measurePosition} contains a rational number
723 indicating how much of the measure has passed at this point.
726 @node Unmetered music
727 @subsection Unmetered music
729 Bar lines and bar numbers are calculated automatically. For unmetered
730 music (e.g. cadenzas), this is not desirable. The property
731 @code{Score.timing} can be used to switch off this automatic timing
733 @lilypond[fragment,relative,singleline,verbatim]
735 \property Score.timing = ##f
737 \property Score.timing = ##t
741 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
748 @subsection Bar lines
752 @cindex measure lines
755 Bar lines are inserted automatically by, but if you need a special
756 types of barline, you can force one using the @code{\bar} command:
757 @lilypond[fragment,verbatim]
761 The following bar types are available
762 @lilypond[fragment, relative, singleline, verbatim]
774 You are encouraged to use @code{\repeat} for repetitions. See
777 In scores with many staffs, the barlines are automatically placed at
778 top level, and they are connected between different staffs of a
779 @internalsref{StaffGroup}:
780 @lilypond[fragment, verbatim]
781 < \context StaffGroup <
782 \context Staff = up { e'4 d'
785 \context Staff = down { \clef bass c4 g e g } >
786 \context Staff = pedal { \clef bass c2 c2 } >
789 The grobs that are created at @internalsref{Staff} level. The name is
790 @internalsref{BarLine}.
792 The full syntax for this command is
796 where @var{bartype} is a string. This is a shortcut for doing
798 \property Score.whichBar = @var{bartype}
802 @cindex Bar_line_engraver
804 @cindex repeatCommands
805 @cindex defaultBarType
807 Whenever @code{whichBar} is set to a string, a bar line of that type is
808 created. @code{whichBar} is usually set automatically: at the start of
809 a measure it is set to @code{defaultBarType}. The contents of
810 @code{repeatCommands} is used to override default measure bars.
812 @code{whichBar} can also be set directly, using @code{\property} or
813 @code{\bar }. These settings take precedence over the automatic
814 @code{whichBar} settings.
821 Polyphonic parts, i.e. parts with more than one voice on a staff can be
822 typeset with LilyPond.
824 The easiest way to enter such fragments, is the Scheme function
825 @code{voicify-music}. It will split chords using the separator
826 @code{\\}, to make multiple voices. You can use it for small,
827 short-lived voices (make a chord of voices) or for single chords:
829 @lilypond[verbatim,fragment]
830 \context Voice = VA \apply #voicify-music \relative c'' {
831 c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
835 The function @code{voicify-music} instantiates @internalsref{Voice}
836 contexts, bearing the names @code{"1"}, @code{"2"}, etc.
838 To explicity typeset polyphonic music, instantiate a separate Voice
839 context for each part, and use @code{\voiceOne}, up to
840 @code{\voiceFour} to assign a stem directions and horizontal shift for
844 @lilypond[singleline, verbatim]
846 \context Staff < \context Voice = VA { \voiceOne cis2 b }
847 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
848 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
851 The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
852 ties, slurs and stems, and set shift directions.
854 If you want more than four voices, you can also manually set
855 horizontal shifts and stem directions, as is shown in the following example:
856 @lilypond[fragment, verbatim]
857 \context Staff \notes\relative c''<
864 \context Voice=three {
865 \shiftOnn \stemUp ais
867 \context Voice=four {
868 \shiftOnnn \stemUp fis
874 Normally, note heads with a different number of dots are not merged, but
875 if you set the grob property @code{merge-differently-dotted}, they are:
876 @lilypond[verbatim,fragment,singleline]
877 \apply #voicify-music < {
879 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
881 } \\ { [g'8. f16] [g'8. f'16] }
885 Similarly, you can merge half note heads with eighth notes, by setting
886 @code{merge-differently-headed}:
887 @lilypond[fragment, relative=2,verbatim]
888 \apply #voicify-music < {
890 \property Staff.NoteCollision
891 \override #'merge-differently-headed = ##t
892 c8 c4. } \\ { c2 c2 } >
895 LilyPond also vertically shifts rests that are opposite of a stem.
897 @lilypond[singleline,fragment,verbatim]
898 \apply #voicify-music <
903 Note head collisions (horizontal shifting of note heads) are handled by
904 the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
905 handles vertical shifting of rests.
911 Resolving collisions is a very intricate subject, and LilyPond only
912 handles a few situations. When it can not cope, you are advised to use
913 @code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
914 rests to override typesetting decisions.
919 Beams are used to group short notes into chunks that are aligned with
920 the metrum. They are inserted automatically in most cases.
922 @lilypond[fragment,verbatim, relative=2]
923 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
926 If you're not satisfied with the automatic beaming, you can enter the
927 beams explicitly. If you have beaming patterns that differ from the
928 defaults, you can also set the patterns for automatic beamer.
930 The beam symbol is @internalsref{Beam} in @internalsref{Voice}
931 context, both for automatically created and manual beams.
934 @cindex Automatic beams
935 @subsection Manual beams
936 @cindex beams, manual
940 In some cases it may be necessary to override LilyPond's automatic
941 beaming algorithm. For example, the auto beamer will not beam over
942 rests or bar lines, If you want that, specify the begin and end point
943 manually using a @code{[} before the first beamed note and a @code{]}
946 @lilypond[fragment,relative,verbatim]
948 r4 [r8 g' a r8] r8 [g | a] r8
952 @cindex @code{stemLeftBeamCount}
954 Normally, beaming patterns within a beam are determined automatically.
955 When this mechanism fouls up, the properties
956 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
957 be used to control the beam subdivision on a stem. If you set either
958 property, it's value will be used only once, and then it is erased.
960 @lilypond[fragment,relative,verbatim]
963 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
966 @cindex @code{stemRightBeamCount}
969 TODO: FIXME, we don't want this doc here.
971 can be tweaked through
972 grob-property @code{positions}. The value is a pair.
973 specify vertical location of the left and right end point. Both are
974 measured in half staff-spaces, and the middle staff line is the value
977 @li lypond[fragment,relative,verbatim]
978 \property Voice.Beam \set #'position = #
979 \property Voice.Beam \set #'height = #0
983 Here's how you'd specify a weird looking beam that instead of being
984 horizontal, falls two staff spaces:
990 @li lypond[fragment,relative,verbatim]
991 \property Voice.Beam \set #'staff-position = #4
992 \property Voice.Beam \set #'height = #-4
999 Kneed beams are inserted automatically, when a large gap between two
1000 adjacent beamed notes is detected. This behavior can be tuned through
1001 the grob property @code{auto-knee-gap}.
1003 @cindex beams, kneed
1005 @cindex auto-knee-gap
1009 @c TODO -> why this ref? Document?
1010 @cindex @code{neutral-direction}
1014 Auto knee beams can not be used together with hara kiri staffs.
1018 * Setting automatic beam behavior ::
1021 @node Beam typography
1022 @subsection Beam typography
1024 One of the strong points of LilyPond is how beams are formatted. Beams
1025 are quantized, meaning that the left and right endpoints beams start
1026 exactly on staff lines. Without quantization, small wedges of white
1027 space appear between the beam and staff line, and this looks untidy.
1029 Beams are also slope-damped: melodies that go up or down should also
1030 have beams that go up or down, but the slope of the beams should be
1031 less than the slope of the notes themselves.
1033 Some beams should be horizontal. These are so-called concave beams.
1035 [TODO: some pictures.]
1038 @c . {Automatic beams}
1039 @node Setting automatic beam behavior
1040 @subsection Setting automatic beam behavior
1042 @cindex @code{autoBeamSettings}
1043 @cindex @code{(end * * * *)}
1044 @cindex @code{(begin * * * *)}
1045 @cindex automatic beams, tuning
1046 @cindex tuning automatic beaming
1048 In normal time signatures, automatic beams can start on any note but can
1049 only end in a few positions within the measure: beams can end on a beat,
1050 or at durations specified by the properties in
1051 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
1052 are defined in @file{scm/auto-beam.scm}.
1054 The value of @code{autoBeamSettings} is changed using
1055 @code{\override} and unset using @code{\revert}:
1057 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
1058 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
1060 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
1061 whether the rule applies to begin or end-points. The quantity
1062 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
1063 *}' designates notes of any length), @var{N}/@var{M} refers to a time
1064 signature (wildcards, `@code{* *}' may be entered to designate all time
1067 For example, if you want automatic beams to end on every quarter note,
1068 you can use the following:
1070 \property Voice.autoBeamSettings \override
1071 #'(end * * * *) = #(make-moment 1 4)
1073 Since the duration of a quarter note is 1/4 of a whole note, it is
1074 entered as @code{(make-moment 1 4)}.
1076 The same syntax can be used to specify beam starting points. In this
1077 example, automatic beams can only end on a dotted quarter note.
1079 \property Voice.autoBeamSettings \override
1080 #'(end * * * *) = #(make-moment 3 8)
1082 In 4/4 time signature, this means that automatic beams could end only on
1083 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1084 3/8 has passed within the measure).
1086 You can also restrict rules to specific time signatures. A rule that
1087 should only be applied in @var{N}/@var{M} time signature is formed by
1088 replacing the second asterisks by @var{N} and @var{M}. For example, a
1089 rule for 6/8 time exclusively looks like
1091 \property Voice.autoBeamSettings \override
1092 #'(begin * * 6 8) = ...
1095 If you want a rule to apply to certain types of beams, you can use the
1096 first pair of asterisks. Beams are classified according to the shortest
1097 note they contain. For a beam ending rule that only applies to beams
1098 with 32nd notes (and no shorter notes), you would use @code{(end 1
1102 @c Automatic beams can not be put on the last note in a score.
1104 If a score ends while an automatic beam has not been ended and is still
1105 accepting notes, this last beam will not be typeset at all.
1107 @cindex automatic beam generation
1109 @cindex @code{Voice.autoBeaming}
1112 For melodies that have lyrics, you may want to switch off
1113 automatic beaming. This is done by setting @code{Voice.autoBeaming} to
1119 It is not possible to specify beaming parameters for beams with mixed
1120 durations, that differ from the beaming parameters of all separate
1121 durations, i.e., you'll have to specify manual beams to get:
1122 @lilypond[fragment,singleline,relative]
1123 \property Voice.autoBeamSettings
1124 \override #'(end * * * *) = #(make-moment 3 8)
1125 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
1128 It is not possible to specify beaming parameters that act differently in
1129 different parts of a measure. This means that it is not possible to use
1130 automatic beaming in irregular meters such as @code{5/8}.
1133 @node Expressive marks
1134 @section Expressive marks
1149 A slur indicates that notes are to be played bound or @emph{legato}.
1150 They are entered using parentheses:
1152 @lilypond[fragment,verbatim,center]
1153 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1157 Slurs avoid crossing stems, and are generally attached to note heads.
1158 However, in some situations with beams, slurs may be attached to stem
1159 ends. If you want to override this layout you can do this through the
1160 grob-property @code{attachment} of @internalsref{Slur} in
1161 @internalsref{Voice} context It's value is a pair of symbols, specifying
1162 the attachment type of the left and right end points.
1164 @lilypond[fragment,relative,verbatim]
1166 \property Voice.Stem \set #'length = #5.5
1168 \property Voice.Slur \set #'attachment = #'(stem . stem)
1172 If a slur would strike through a stem or beam, the slur will be moved
1173 away upward or downward. If this happens, attaching the slur to the
1174 stems might look better:
1176 @lilypond[fragment,relative,verbatim]
1179 \property Voice.Slur \set #'attachment = #'(stem . stem)
1184 Similarly, the curvature of a slur is adjusted to stay clear of note
1185 heads and stems. When that would increase the curvature too much, the
1186 slur is reverted to its default shape. The threshold for this decision
1187 is in @internalsref{Slur}'s grob-property @code{beautiful}. It is loosely
1188 related to the enclosed area between the slur and the notes. Usually,
1189 the default setting works well, but in some cases you may prefer a
1190 curved slur when LilyPond decides for a vertically moved one. You can
1191 indicate this preference by increasing the @code{beautiful} value:
1193 @lilypond[verbatim,singleline,relative]
1195 c16( a' f' a a f a, )c,
1196 c( a' f' a a f d, )c
1197 \property Voice.Slur \override #'beautiful = #5.0
1198 c( a' f' a a f d, )c
1203 Producing nice slurs is a difficult problem, and LilyPond currently
1204 uses a simple, empiric method to produce slurs. In some cases, the
1205 results of this method don't look too good. This is reflected by the
1206 @code{beautiful} property, which it is an arbitrary parameter in the
1207 slur formatter. Useful values can only be determined by trial and
1210 @cindex Adjusting slurs
1212 @node Phrasing slurs
1213 @subsection Phrasing slurs
1215 @cindex phrasing slurs
1216 @cindex phrasing marks
1218 A phrasing slur (or phrasing mark) connects chords and is used to
1219 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1222 @lilypond[fragment,verbatim,center,relative]
1223 \time 6/4 c' \( ( d ) e f ( e ) \) d
1226 Typographically, the phrasing slur behaves almost exactly like a normal
1227 slur. The grob associated with it is @internalsref{PhrasingSlur}, in
1228 @internalsref{Voice} context.
1231 @subsection Breath marks
1233 Breath marks are entered using @code{\breathe}. The result is a
1234 @internalsref{BreathingSign} grob in @internalsref{Voice} context.
1236 @lilypond[fragment,relative]
1245 @cindex beats per minute
1246 @cindex metronome marking
1248 Metronome settings can be entered as follows:
1250 @cindex @code{\tempo}
1252 \tempo @var{duration} = @var{perminute}
1255 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1260 The tempo setting is not printed, but is only used in the MIDI
1261 output. You can trick lily into producing a metronome mark,
1262 though. Details are in @ref{Text markup}.
1267 @subsection Text spanners
1268 @cindex Text spanners
1270 Some textual indications, e.g. rallentando or accelerando, often extend
1271 over many measures. This is indicated by following the text with a
1272 dotted line. You can create such texts using text spanners. The syntax
1275 \spanrequest \start "text"
1276 \spanrequest \stop "text"
1278 LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
1279 in @internalsref{Voice} context). The string to be printed, as well as the
1280 style is set through grob properties.
1282 An application---or rather, a hack---is to fake octavation indications.
1283 @lilypond[fragment,relative,verbatim]
1284 \relative c' { a''' b c a
1285 \property Voice.TextSpanner \set #'type = #'dotted-line
1286 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1287 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1288 \property Staff.centralCPosition = #-13
1289 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1308 @subsection Articulations
1309 @cindex Articulations
1311 @cindex articulations
1315 A variety of symbols can appear above and below notes to indicate
1316 different characteristics of the performance. They are added to a note
1317 by adding @code{-}@var{script}
1318 @lilypond[singleline]
1320 \notes \context Voice {
1321 \property Voice.TextScript \set #'font-family = #'typewriter
1322 \property Voice.TextScript \set #'font-shape = #'upright
1328 c''4-^_"c-\\^{ }" s4
1333 The script is automatically placed, but if you need to force
1334 directions, you can use @code{_} to force them down, or @code{^} to
1336 @lilypond[fragment, verbatim]
1341 Other symbols can be added using the syntax
1342 @var{note}@code{-\}@var{name}. Again, they can be forced up or down
1343 using @code{^} and @code{_}.
1347 \property Score.LyricSyllable \override #'font-family =#'typewriter
1348 \property Score.LyricSyllable \override #'font-shape = #'upright
1349 \context Staff \notes {
1350 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1351 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1352 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1353 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1354 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1355 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1356 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1357 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1359 \context Lyrics \lyrics {
1360 accent__ marcato__ staccatissimo__ fermata
1361 stopped__ staccato__ tenuto__ upbow
1362 downbow__ lheel__ rheel__ ltoe
1363 rtoe__ turn__ open__ flageolet
1364 reverseturn__ trill__ prall__ mordent
1365 prallprall__ prallmordent__ uprall__ downprall
1366 upmordent__ downmordent__ pralldown__ prallup__
1367 lineprall__ thumb__ segno__ coda
1371 linewidth = 5.875\in
1380 Fingering instructions can also be entered in this shorthand. For
1381 finger changes, use markup texts:
1383 @lilypond[verbatim, singleline, fragment]
1384 c'4-1 c'4-2 c'4-3 c'4-4
1389 @cindex @code{\script}
1394 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
1398 All of these note ornaments appear in the printed output but have no
1399 effect on the MIDI rendering of the music.
1401 Unfortunately, there is no support for adding fingering instructions or
1402 ornaments to individual note heads. Some hacks exist, though. See
1403 @file{input/test/script-horizontal.ly}.
1408 @subsection Text scripts
1409 @cindex Text scripts
1411 In addition, it is possible to place arbitrary strings of text or markup
1412 text (see @ref{Text markup}) above or below notes by using a string:
1415 By default, these indications do not influence the note spacing, but
1416 by using the command @code{\fatText}, the widths will be taken into
1419 @lilypond[fragment,singleline,verbatim] \relative c' {
1420 c4^"longtext" \fatText c4_"longlongtext" c4 }
1423 Text scripts are created in form of @internalsref{TextScript} grobs, in
1424 @internalsref{Voice} context.
1426 @ref{Text markup} describes how to change the font or access
1427 special symbols in text scripts.
1430 @node Adding scripts
1431 @subsection Adding scripts
1433 TODO: should junk this subsect?
1435 You can add scripts by editing @file{scm/script.scm} and
1436 @file{ly/script-init.ly}. This file contains a table, listing script
1437 definitions and aliases. The following syntax accesses a script
1438 definition from the table:
1444 Usually the @code{\script} keyword is not used directly. Various
1445 helpful identifier definitions appear in @file{script.ly}.
1450 @subsection Grace notes
1454 @cindex @code{\grace}
1458 Grace notes are ornaments are written out ornaments
1459 @lilypond[relative=2,fragment]
1460 c4 \grace c16 c4 \grace { [c16 d16] } c4
1463 In normal notation, grace notes are supposed to take up no logical
1464 time in a measure. Such an idea is practical for normal notation, but
1465 is not strict enough to put it into a program. The model that LilyPond
1466 uses for grace notes internally is that all timing is done in two
1469 Every point in musical time consists of two rational numbers: one
1470 denotes the logical time, one denotes the grace timing. The above
1471 example is shown here with timing tuples.
1473 @lilypond[relative=2,fragment]
1474 c4^"(0,0)" \grace c16^"(1/4,-1/16)" c4^"(1/4,0)" \grace {
1475 [c16^"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4^"(2/4,0)"
1478 The advantage of this approach is that you can use almost any lilypond
1479 construction together with grace notes, for example slurs and clef
1480 changes may appear halfway in between grace notes:
1482 @lilypond[relative=2,fragment]
1483 c4 \grace { [ c16 c, \clef bass c, b(] } )c4
1486 The placement of these grace notes is synchronized between different
1487 staffs, using this grace timing.
1489 @lilypond[relative=2,fragment]
1490 \context Staff = SA { e4 \grace { c16 d e f } e4 }
1491 \context Staff = SB { c4 \grace { g8 b } c4 }
1495 The syntax is as follows.
1497 \grace @var{musicexpr}
1500 Unbeamed eighth notes and shorter by default have a slash through the
1503 @lilypond[fragment,verbatim]
1504 \relative c'' \context Voice {
1505 \grace c8 c4 \grace { [c16 c16] } c4
1507 \property Voice.Stem \override #'flag-style = #'()
1509 \property Voice.Stem \revert #'flag-style
1514 A grace note expression has duration 0; the next real note is assumed to
1515 be the main note. If you want the note to appear after the main note,
1516 set @code{Voice.graceAlignPosition} to @code{1}.
1521 Grace note synchronization can also lead to surprises. Staff notation,
1522 such as key signatures, barlines, etc. are also synchronized. Take
1523 care when you mix staffs with grace notes and staffs without.
1525 @lilypond[relative=2,fragment]
1526 \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
1527 \context Staff = SB { c4 \bar "|:" d4 }
1530 Nesting @code{\grace} notes is not supported. The following may cause
1534 @code{\grace @{ \grace c32 c16 @} c4}
1536 Since the meaning of such a construct is unclear, we don't consider this
1537 a loss. Similarly, juxtaposing two @code{\grace} sections is
1538 syntactically valid, but makes no sense and may cause runtime errors.
1539 Ending a staff or score with grace notes may also generate a run-time
1540 error, since there will be no main note to attach the grace notes to.
1551 @subsection Glissando
1554 @cindex @code{\glissando}
1556 A glissando line (grob @internalsref{Glissando}) can be requested by
1557 attaching a @code{\glissando} to a notte:
1559 @lilypond[fragment,relative,verbatim]
1565 Printing of an additional text (such as @emph{gliss.}) must be done
1572 @subsection Dynamics
1585 @cindex @code{\ffff}
1595 Absolute dynamic marks are specified using an identifier after a
1596 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1597 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1598 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1599 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1601 @lilypond[verbatim,singleline,fragment,relative]
1602 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1608 @cindex @code{\decr}
1609 @cindex @code{\rced}
1615 A crescendo mark is started with @code{\cr} and terminated with
1616 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1617 started with @code{\decr} and terminated with @code{\rced}. There are
1618 also shorthands for these marks. A crescendo can be started with
1619 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1620 can be terminated with @code{\!}. Note that @code{\!} must go before
1621 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1622 after the last note. Because these marks are bound to notes, if you
1623 want several marks during one note, you have to use spacer notes.
1625 @lilypond[fragment,verbatim,center]
1626 c'' \< \! c'' d'' \decr e'' \rced
1627 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1630 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1631 is an example how to do it:
1636 @lilypond[fragment,relative,verbatim]
1638 \property Voice.crescendoText = "cresc."
1639 \property Voice.crescendoSpanner = #'dashed-line
1644 For everyday use, we recommend the identifiers @code{\cresc},
1645 @code{endcresc}, @code{\dim} and @code{\enddim}.
1649 Dynamics are grobs of @internalsref{DynamicText} and
1650 @internalsref{Hairpin}. Vertical positioning of these symbols is handled
1651 by the @internalsref{DynamicLineSpanner} grob. If you want to adjust
1652 padding or vertical direction of the dynamics, you must set properties
1653 for the @internalsref{DynamicLineSpanner} grob. Predefined identifiers
1654 to set the vertical direction are \dynamicUp and \dynamicDown.
1656 @cindex direction, of dynamics
1657 @cindex @code{\dynamicDown}
1658 @cindex @code{\dynamicUp}
1666 @cindex @code{\repeat}
1668 To specify repeats, use the @code{\repeat} keyword. Since repeats
1669 should work differently when played or printed, there are a few
1670 different variants of repeats.
1674 Repeated music is fully written (played) out. Useful for MIDI
1675 output, and entering repetitive music.
1678 This is the normal notation: Repeats are not written out, but
1679 alternative endings (voltas) are printed, left to right.
1682 Alternative endings are written stacked. This has limited use but may be
1683 used to typeset two lines of lyrics in songs with repeats, see
1684 @file{input/star-spangled-banner.ly}.
1690 Make beat or measure repeats. These look like percent signs.
1696 * Repeats and MIDI::
1697 * Manual repeat commands::
1699 * Tremolo subdivisions::
1704 @subsection Repeat syntax
1706 The syntax for repeats is
1709 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1712 If you have alternative endings, you may add
1713 @cindex @code{\alternative}
1715 \alternative @code{@{} @var{alternative1}
1717 @var{alternative3} @dots{} @code{@}}
1719 where each @var{alternative} is a music expression.
1721 Normal notation repeats are used like this:
1722 @lilypond[fragment,verbatim]
1724 \repeat volta 2 { c'4 d' e' f' }
1725 \repeat volta 2 { f' e' d' c' }
1728 With alternative endings:
1729 @lilypond[fragment,verbatim]
1731 \repeat volta 2 {c'4 d' e' f'}
1732 \alternative { {d'2 d'} {f' f} }
1735 Folded repeats look like this:
1738 @lilypond[fragment,verbatim]
1740 \repeat fold 2 {c'4 d' e' f'}
1741 \alternative { {d'2 d'} {f' f} }
1745 If you don't give enough alternatives for all of the repeats, then
1746 the first alternative is assumed to be repeated often enough to equal
1747 the specified number of repeats.
1749 @lilypond[fragment,verbatim]
1753 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1754 \alternative { { g4 g g } { a | a a a a | b2. } }
1759 @node Repeats and MIDI
1760 @subsection Repeats and MIDI
1762 @cindex expanding repeats
1764 For instructions on how to unfoldi repeats for MIDI output, see
1765 the example file @file{input/test/unfold-all-repeats.ly}.
1770 Notice that timing information is not remembered at the start of an
1771 alternative, so you have to reset timing information after a repeat,
1772 e.g. using a bar-check (See @ref{Bar check}), setting
1773 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1774 are also not repeated.
1776 It is possible to nest @code{\repeat}s, although this probably is only
1777 meaningful for unfolded repeats.
1779 Folded repeats offer little more over simultaneous music. However, it
1780 is to be expected that more functionality -- especially for the MIDI
1781 backend -- will be implemented at some point in the future.
1783 Volta repeats are printed over all staves in a score. You must turn them
1784 off explicitly, for example by doing
1786 \property Staff.VoltaBracket = \turnOff
1788 in all but the top staff.
1790 @node Manual repeat commands
1791 @subsection Manual repeat commands
1793 @cindex @code{repeatCommands}
1795 The property @code{repeatCommands} can be used to control the layout of
1796 repeats. Its value is a Scheme list of repeat commands, where each repeat
1804 @item (volta . @var{text})
1805 Print a volta bracket saying @var{text}.
1807 Stop a running volta bracket
1810 @lilypond[verbatim, fragment]
1812 \property Score.repeatCommands = #'((volta "93") end-repeat)
1814 \property Score.repeatCommands = #'((volta #f))
1819 Repeats brackets are @internalsref{VoltaBracket} grobs.
1821 @node Tremolo repeats
1822 @subsection Tremolo repeats
1823 @cindex tremolo beams
1825 To place tremolo marks between notes, use @code{\repeat} with tremolo
1827 @lilypond[verbatim,center,singleline]
1829 \context Voice \notes\relative c' {
1830 \repeat "tremolo" 8 { c16 d16 }
1831 \repeat "tremolo" 4 { c16 d16 }
1832 \repeat "tremolo" 2 { c16 d16 }
1833 \repeat "tremolo" 4 c16
1838 Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
1839 @internalsref{StemTremolo}.
1844 At present, the spacing between tremolo beams is not regular, since the
1845 spacing engine does not notice that not all notes are printed.
1847 @node Tremolo subdivisions
1848 @subsection Tremolo subdivisions
1849 @cindex tremolo marks
1850 @cindex @code{tremoloFlags}
1852 Tremolo marks can be printed on a single note by adding
1853 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1854 A @var{length} value of 8 gives one line across the note stem. If the
1855 length is omitted, then then the last value (stored in
1856 @code{Voice.tremoloFlags}) is used.
1858 @lilypond[verbatim,fragment,center]
1859 c'2:8 c':32 | c': c': |
1865 Tremolos in this style do not carry over into the MIDI output.
1868 @node Measure repeats
1869 @subsection Measure repeats
1871 @cindex percent repeats
1872 @cindex measure repeats
1874 In the @code{percent} style, a note pattern can be repeated. It is
1875 printed once, and then the pattern is replaced with a special sign.
1876 Patterns of a one and two measures are replaced by percent-like signs,
1877 patterns that divide the measure length are replaced by slashes.
1879 @lilypond[verbatim,singleline]
1880 \context Voice { \repeat "percent" 4 { c'4 }
1881 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1885 The signs are represented by these grobs: @internalsref{RepeatSlash} and
1886 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
1890 You can not nest percent repeats, e.g. by filling in the first measure
1891 with slashes, and repeating that measure with percents.
1893 @node Rhythmic music
1894 @section Rhythmic music
1901 @node Rhythmic staves
1902 @subsection Rhythmic staves
1904 Sometimes you might want to show only the rhythm of a melody. This can
1905 be done with the rhythmic staff. All pitches of notes on such a staff
1906 are squashed, and the staff itself looks has a single staff line:
1908 @lilypond[fragment,relative,verbatim]
1909 \context RhythmicStaff {
1911 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1918 @section Piano music
1920 Piano music is an odd type of notation. Piano staves are two normal
1921 staves coupled with a brace. The staves are largely independent, but
1922 sometimes voices can cross between the two staves. The
1923 @internalsref{PianoStaff} is especially built to handle this cross-staffing
1924 behavior. In this section we discuss the @internalsref{PianoStaff} and some
1925 other pianistic peculiarities.
1928 * Automatic staff changes::
1929 * Manual staff switches::
1932 * Voice follower lines::
1936 @c . {Automatic staff changes}
1937 @node Automatic staff changes
1938 @subsection Automatic staff changes
1939 @cindex Automatic staff changes
1941 Voices can switch automatically between the top and the bottom
1942 staff. The syntax for this is
1944 \autochange @var{contexttype} \context @var{childcontexttype}
1948 This will switch the interpretation context of @var{musicexp} between
1949 a @var{contexttype} named @code{up} and @code{down}. Typically, you
1950 use @internalsref{Staff} for @var{contexttype}, and
1951 @internalsref{Voice} for @var{childcontexttype}. The autochanger
1952 switches on basis of pitch (central C is the turning point), and it
1953 looks ahead skipping over rests to switch rests in advance.
1955 @lilypond[verbatim,singleline]
1956 \score { \notes \context PianoStaff <
1957 \context Staff = "up" {
1958 \autochange Staff \context Voice = VA < \relative c' {
1959 g4 a b c d r4 a g } > }
1960 \context Staff = "down" {
1966 Note how spacer rests are used to prevent the bottom staff from
1967 terminating too soon.
1970 @node Manual staff switches
1971 @subsection Manual staff switches
1973 @cindex manual staff switches
1974 @cindex staff switch, manual
1976 Voices can be switched between staves manually, using the following command:
1978 \translator Staff = @var{staffname} @var{music}
1980 The string @var{staffname} is the name of the staff. It switches the
1981 current voice from its current staff to the Staff called
1982 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1985 The formal definition of this construct is obtuse, but for the sake of
1986 completeness we give it here.
1987 @cindex @code{\translator}
1989 \translator @var{contexttype} = @var{name}
1991 Formally, this construct is a music expression indicating
1992 that the context which is a direct child of the context of type
1993 @var{contexttype} should be shifted to a context of type
1994 @var{contexttype} and the specified name.
2002 Piano pedal instruction can be expressed using
2003 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
2004 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
2006 These identifiers are shorthands for spanner commands of the types
2007 @internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
2009 @lilypond[fragment,verbatim]
2010 c''4 \spanrequest \start "Sustain" c''4
2011 c''4 \spanrequest \stop "Sustain"
2014 The symbols that are printed can be modified by setting
2015 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
2016 Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
2017 @rgrob{SustainPedal}, for example, for more information.
2019 Pedals can also be indicated by a sequence of brackets, by setting the
2020 @code{pedal-type} property of SustainPedal grobs:
2022 @lilypond[fragment,verbatim]
2023 \property Staff.SustainPedal \override #'pedal-type = #'bracket
2024 c''4 \sustainDown d''4 e''4 a'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
2027 A third style of pedal notation is a mixture of text and brackets,
2028 obtained by setting @code{pedal-type} to @code{mixed}:
2030 @lilypond[fragment,verbatim]
2031 \property Staff.SustainPedal \override #'pedal-type = #'mixed
2032 c''4 \sustainDown d''4 e''4 c'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
2035 The default '*Ped' style for sustain and damper pedals corresponds to
2036 @code{\pedal-type = #'text}. However, @code{mixed} is the default style
2037 for a sostenuto pedal:
2039 @lilypond[fragment,verbatim]
2040 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2043 For fine-tuning of the appearance of a pedal bracket, the properties
2044 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
2045 @code{PianoPedalBracket} grobs (see the detailed documentation of
2046 @rgrob{PianoPedalBracket}) can be modified. For example, the bracket
2047 may be extended to the end of the note head.
2049 @lilypond[fragment,verbatim]
2050 \property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0)
2051 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2058 @subsection Arpeggio
2061 @cindex broken arpeggio
2062 @cindex @code{\arpeggio}
2064 You can specify an arpeggio sign on a chord by attaching an
2065 @code{\arpeggio} to a note of the chord.
2068 @lilypond[fragment,relative,verbatim]
2069 \context Voice <c\arpeggio e g c>
2072 When an arpeggio crosses staves in piano music, you attach an arpeggio
2073 to the chords in both staves, and set
2074 @code{PianoStaff.connectArpeggios}.
2076 @lilypond[fragment,relative,verbatim]
2077 \context PianoStaff <
2078 \property PianoStaff.connectArpeggios = ##t
2079 \context Voice = one { <c'\arpeggio e g c> }
2080 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2084 This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
2085 are @code{PianoStaff.Arpeggio}.
2087 To add an arrow head to explicitly specify the direction of the
2088 arpeggio, you should set the arpeggio grob property
2089 @code{arpeggio-type}.
2091 @lilypond[fragment,relative,verbatim]
2093 \property Voice.Arpeggio \override #'arpeggio-direction = #1
2095 \property Voice.Arpeggio \override #'arpeggio-direction = #-1
2100 A square bracket on the left indicates that the player should not
2101 arpeggiate the chord. To draw these brackets, set the
2102 @code{molecule-callback} property of @code{Arpeggio} or
2103 @code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
2104 @code{\arpeggio} statements within the chords as before.
2106 @lilypond[fragment,relative,verbatim]
2107 \context PianoStaff <
2108 \property PianoStaff.connectArpeggios = ##t
2109 \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket
2110 \context Voice = one { <c'\arpeggio e g c> }
2111 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2118 It is not possible to mix connected arpeggios and unconnected arpeggios
2123 @node Voice follower lines
2124 @subsection Voice follower lines
2126 @cindex follow voice
2127 @cindex staff switching
2130 @cindex @code{followVoice}
2132 Whenever a voice switches to another staff a line connecting the notes
2133 can be printed automatically. This is enabled if the property
2134 @code{PianoStaff.followVoice} is set to true:
2136 @lilypond[fragment,relative,verbatim]
2137 \context PianoStaff <
2138 \property PianoStaff.followVoice = ##t
2139 \context Staff \context Voice {
2141 \translator Staff=two
2144 \context Staff=two {\clef bass \skip 1*2 }
2148 The associated grob is @internalsref{VoiceFollower}.
2155 * Tablatures basic::
2156 * Non-guitar tablatures::
2157 * Tablature in addition to normal staff::
2160 @node Tablatures basic
2161 @subsection Tablatures basic
2162 @cindex Tablatures basic
2164 Tablature can be typeset with Lilypond by using the
2165 @internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
2166 tablatures is a recent feature in Lilypond, most of the guitar special
2167 effects (hammer, pull, bend, ...) are not yet supported.
2169 With the @internalsref{TabStaff}, the string number associated to a note
2170 is given though the fingering mechanism, e.g. @code{c4-3} for a C
2171 quarter on the third string. The string 1 is the lowest one, and the
2172 tuning defaults to the standard guitar tuning (with 6 strings).
2174 @lilypond[fragment,verbatim]
2177 \property Staff.Stem \override #'direction = #1
2186 @node Non-guitar tablatures
2187 @subsection Non-guitar tablatures
2188 @cindex Non-guitar tablatures
2190 There are many ways to customize Lilypond tablatures.
2192 First you can change the number of string, e.g.
2193 @code{StaffSymbol \override #'line-count = #5} to have only 5 strings.
2194 Because of a kind of bug in Lilypond, you MUST create a new type of
2195 context if you want different tablatures with diiferent number of
2198 Then you can change the strings tuning. String tuning is given as a
2199 Scheme list with one integer number for each string, the number being
2200 the string note pitch if not fretted (open note).
2202 Finally, it is possible to change the Scheme function to format the
2203 tablature note text. The default is @var{fret-number-tablature-format},
2204 which uses the fret number, but for some instruments that may not use
2205 this notation, just create your own tablature-format function. This
2206 function takes three argument: the string number, the string tuning and
2210 @node Tablature in addition to normal staff
2211 @subsection Tablature in addition to normal staff
2212 @cindex Tablature in addition to normal staff
2214 It is possible to typeset both tablature and a "normal" staff, as
2215 commonly done in many parts.
2217 A common trick for that is to put the notes in a variables, and to hide
2218 the fingering information (which correspond to the string number) for
2227 \context StaffGroup <
2229 % Hide fingering number (used for string number) for the "normal" staff
2230 \property Staff.Fingering \override #'transparent = ##t
2235 \property Staff.Stem \override #'direction = #1
2252 * Automatic syllable durations::
2258 @subsection Lyrics mode
2261 To print lyrics, you must first make a music expression from the lyric
2262 text. That music expression can be printed by selecting an appropriate
2266 @cindex @code{\lyrics}
2268 You can enter lyrics in a special input mode of LilyPond. This mode is
2269 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
2270 The purpose of this mode is that you can enter lyrics as plain text,
2271 punctuation and accents without any hassle.
2273 Syllables are entered like notes, with pitches replaced by text. For
2274 example, @code{Twin- kle twin- kle} enters four syllables. Note that
2275 the hyphen has no special meaning for lyrics, and does not introduce
2278 Spaces can be introduced into a lyric either by using quotes:
2279 @code{"He could"4 not4} or by using an underscore without quotes:
2280 @code{He_could4 not4}. All unquoted underscores are converted to
2283 The precise definition of this mode can be found in @ref{Lyrics mode
2286 @c . {Printing lyrics}
2287 @node Printing lyrics
2288 @subsection Printing lyrics
2291 Lyrics are printed by interpreting them in the @internalsref{Lyrics} context.
2293 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
2294 @c Add tied and beamed melismata too.
2295 @lilypond[verbatim,singleline]
2297 \notes \relative c' {
2299 \property Staff.automaticMelismata = ##t
2300 d'2 c4 b16 ( a g a b a b ) c a2
2301 b2 c4 b8 ( a16 g ) a4 g2 }
2302 \context Lyrics \lyrics {
2304 share the soft -- ware; }
2308 Notes and syllable durations are matched automatically. This is
2309 accomplished using @code{\addlyrics}, which is documented in
2310 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
2311 the melody staff will cause tied, slurred or beamed notes to be
2312 interpreted as melismata.
2314 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
2317 @cindex lyric extender
2320 As you can see, extender lines are entered as @code{__}. This will
2321 create an extender, a line that extends over the entire duration of the
2322 lyric. This line will run all the way to the start of the next lyric,
2323 so you may want to shorten it by using a blank lyric (using @code{_}).
2324 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2329 If you want to have hyphens centered between syllables (rather than
2330 attached to the end of the first syllable) you can use the special
2331 `@code{-}@code{-}' lyric as a separate word between syllables. This
2332 will result in a hyphen whose length varies depending on the space
2333 between syllables. It will be centered between the syllables. The grob
2334 for this symbol is @code{LyricsVoice.LyricHyphen}.
2336 @cindex Lyric hyphen
2338 @node Automatic syllable durations
2339 @subsection Automatic syllable durations
2340 @cindex Automatic syllable durations
2342 @cindex automatic lyric durations
2343 @cindex @code{\addlyrics}
2345 If you have lyrics that are set to a melody, you can copy the rhythm
2346 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2349 \addlyrics @var{musicexpr1 musicexpr2}
2352 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2353 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2354 when there are events in @var{musicexpr1}.
2356 @cindex @code{automaticMelismata}
2358 If the property @code{automaticMelismata} is set in the
2359 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2362 @lilypond[verbatim,fragment]
2365 \property Voice.automaticMelismata = ##t
2366 c8 () cis d8. e16 f2
2368 \context Lyrics \lyrics {
2372 If you want the lyric lines to be above the melody staff, or in some
2373 other, more complex configuration, then build that configuration first
2374 using simultaneous music, and use @code{\addlyrics} after that.
2376 @lilypond[verbatim, singleline]
2378 \context Lyrics = LA { s1 }
2379 \context Staff = SA { s1 }
2381 \context Staff = SA \relative c' { c4 e g g }
2382 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2385 For @code{\addlyrics} you should use a single rhythm melody, and single
2386 rhythm lyrics (a constant duration is the obvious choice). If you do
2387 not, you can get undesired effects when using multiple stanzas:
2389 @lilypond[verbatim,fragment]
2392 c8 () cis d8. e16 f2
2394 \context Lyrics \lyrics
2399 It is valid (but probably not very useful) to use notes instead of
2400 lyrics for @var{musicexpr2}.
2403 @subsection More stanzas
2407 If you have multiple stanzas printed underneath each other, the vertical
2408 groups of syllables should be aligned around punctuation. LilyPond can
2409 do this if you tell it which lyric lines belong to which melody.
2411 To this end, give the Voice context an identity, and set the LyricsVoice
2412 to a name starting with that identity followed by a dash.
2413 In the following example, the Voice
2414 identity is @code{duet}, and the identities of the LyricsVoices are
2415 @code{duet-1} and @code{duet-2}.
2418 @lilypond[singleline,verbatim]
2421 \notes \relative c'' \context Voice = duet { \time 3/4
2423 \lyrics \context Lyrics <
2424 \context LyricsVoice = "duet-1" {
2425 \property LyricsVoice . stanza = "Bert"
2426 Hi, my name is bert. }
2427 \context LyricsVoice = "duet-2" {
2428 \property LyricsVoice . stanza = "Ernie"
2429 Ooooo, ch\'e -- ri, je t'aime. }
2434 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2435 first system) and @code{LyricsVoice.stz} for the following
2436 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2442 @cindex stanza numbering
2450 LilyPond has support for both entering and printing chords. Chords are
2451 characterized by a set of pitches. They are
2452 internally stored as simultaneous music expressions. This means you can
2453 enter chords by name and print them as note head, enter them as notes
2454 and print them as chord names, or (the most common case) enter them by
2455 name, and print them as name.
2458 @lilypond[verbatim,singleline]
2459 twoWays = \notes \transpose c'' {
2469 < \context ChordNames \twoWays
2470 \context Voice \twoWays > }
2473 Note that this example also shows that the chord printing routines do
2474 not attempt to be intelligent. If you enter @code{f bes d}, it does not
2475 interpret this as an inversion.
2479 * Printing named chords::
2484 @subsection Chords mode
2487 Chord mode is a mode where you can input sets of pitches using common
2488 names. It is introduced by the keyword @code{\chords}. It is similar
2489 to note mode, but words are also looked up in a chord modifier table
2490 (containing @code{maj}, @code{dim}, etc).
2492 Dashes and carets are used to indicate chord additions and subtractions,
2493 so articulation scripts can not be entered in Chord mode.
2495 The syntax for named chords is as follows:
2497 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2500 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2501 the chord duration in the usual notation. There are two kinds of
2502 modifiers. One type is formed by @emph{chord additions}. Additions are
2503 obtained by listing intervals separated by dots. An interval is written
2504 by its number with an optional @code{+} or @code{-} to indicate raising
2505 or lowering by half a step. Chord additions have two effects: they adds
2506 the specified interval and all lower odd numbered intervals to the
2507 chord, and they may lower or raise the specified interval.
2509 Throughout these examples, chords have been shifted around the staff
2510 using @code{\transpose}.
2512 @lilypond[fragment,verbatim]
2516 c:9 c:9-.5+.7+ c:3-.5-
2526 The second type of modifier that may appear after the @code{:} is a
2527 named modifier. Named modifiers are listed in the file
2528 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2529 @code{min} which lower the 3rd half a step, `@code{aug}' which
2530 raises the 5th, `@code{dim}' which lowers the 5th,
2531 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2532 which replaces the 5th with a 4th.
2534 @lilypond[fragment,verbatim]
2537 c1:m c:min7 c:maj c:aug c:dim c:sus
2543 Chord subtractions are used to eliminate notes from a chord. The
2544 notes to be subtracted are listed after a @code{^} character,
2547 @lilypond[fragment,verbatim,center]
2556 Chord inversions can be specified by appending `@code{/}' and the name
2557 of a single note to a chord. In a chord inversion, the inverted note is
2558 transposed down until it is the lowest note in the chord. If the note
2559 is not in the chord, a warning will be printed.
2561 @lilypond[fragment,verbatim,center]
2571 Bass notes can be added by `@code{/+}' and
2572 the name of a single note to a chord. This has the effect of
2573 adding the specified note to the chord, lowered by an octave,
2574 so it becomes the lowest note in the chord.
2576 @lilypond[fragment,verbatim,center]
2587 Implementation details are quite gory. For example @code{c:4} not only
2588 adds a fourth, but also removes the third.
2591 @c . {Printing named chords}
2592 @node Printing named chords
2593 @subsection Printing named chords
2595 @cindex printing chord names
2599 For displaying printed chord names, use the @internalsref{ChordNames} context.
2600 The chords may be entered either using the notation described above, or
2601 directly using simultaneous music.
2603 @lilypond[verbatim,singleline]
2605 \chords {a1 b c} <d f g> <e g b>
2609 \context ChordNames \scheme
2610 \context Staff \transpose c'' \scheme
2615 You can make the chord changes stand out by setting
2616 @code{ChordNames.chordChanges} to true. This will only display chord
2617 names when there's a change in the chords scheme and at the start of a
2622 c1:m c:m \break c:m c:m d
2626 \context ChordNames {
2627 \property ChordNames.chordChanges = ##t
2629 \context Staff \transpose c'' \scheme
2633 LilyPond examines chords specified as lists of notes to determine a name
2634 to give the chord. LilyPond will not try to identify chord inversions or
2635 an added bass note, which may result in strange chord names when chords
2636 are entered as a list of pitches:
2638 @lilypond[verbatim,center,singleline]
2647 \context ChordNames \scheme
2648 \context Staff \scheme
2654 By default, a chord name system proposed by Harald Banter (See
2655 @ref{Literature}) is used. The system is very regular and predictable.
2656 Typical American style chord names may be selected by setting the
2657 @code{style} property of the @code{ChordNames.ChordName} grob to
2658 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2660 Routines that determine the names to be printed are written in Scheme,
2661 and may be customized by the user. The code can be found in
2662 @file{scm/chord-name.scm}. Here's an example showing the differences in
2666 @c maybe just junk verbatim option?
2667 @lilypond[verbatim,singleline]
2677 \context ChordNames = banter \scheme
2678 \context ChordNames = american {
2679 \property ChordNames.ChordName \override
2680 #'style = #'american \scheme }
2681 \context ChordNames = jazz {
2682 \property ChordNames.ChordName \override
2683 #'style = #'jazz \scheme }
2684 \context Staff \transpose c'' \scheme
2691 @section Writing parts
2693 Orchestral music involves some special notation, both in the full score,
2694 as in the individual parts. This section explains how to tackle common
2695 problems in orchestral music.
2702 * Instrument names::
2704 * Sound output for transposing instruments::
2705 * Multi measure rests::
2706 * Automatic part combining::
2707 * Hara kiri staves::
2710 @c . {Rehearsal marks}
2711 @node Rehearsal marks
2712 @subsection Rehearsal marks
2713 @cindex Rehearsal marks
2715 @cindex @code{\mark}
2719 \mark @var{unsigned}
2724 This command prints a rehearsal mark above the system. You can provide
2725 a number, a string or a markup text as argument. If you use
2726 @code{\default}, the value of property @code{rehearsalMark} is used and
2727 automatically incremented.
2729 @lilypond[fragment,verbatim]
2735 c1 \mark #'(music "scripts-segno")
2740 The grob is @internalsref{RehearsalMark} in @internalsref{Score} context. See
2741 @code{input/test/boxed-molecule.ly} if you need boxes around the marks.
2744 @subsection Bar numbers
2748 @cindex measure numbers
2749 @cindex currentBarNumber
2751 Bar numbers are @internalsref{BarNumber} grobs. They are printed at the
2752 start of the line. The number itself is a property that can be set by
2753 modifying the @code{currentBarNumber} property, i.e.
2755 \property Score.currentBarNumber = #217
2758 If you want boxed bar numbers, see the example file
2759 @code{input/test/boxed-molecule.ly}.
2763 It is not possible to have bar numbers printed at regular intervals
2766 Barnumbers can collide with the StaffGroup, if there is one at the
2767 top. To solve this, You have to twiddle with the padding-property of
2768 the bar-number if your score starts with a staff-group.
2770 @node Instrument names
2771 @subsection Instrument names
2773 You can specify an instrument name for a staff by setting
2774 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2775 before the start of the staff. For the first start, @code{instrument} is
2776 used, for the next ones @code{instr} is used.
2778 @lilypond[verbatim,singleline]
2779 \property Staff.instrument = "ploink " { c''4 }
2782 You can also use markup texts to construct more complicated instrument
2786 @lilypond[verbatim,singleline]
2788 '((font-relative-size . -2 ) (music "accidentals--1")))
2791 \property Staff.instrument = #`((kern . 0.5) (lines
2792 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2800 When you put a name on a grand staff or piano staff the width of the
2801 brace is not taken into account. You must add extra spaces to the end of
2802 the name to avoid a collision.
2805 @subsection Transpose
2807 @cindex transposition of pitches
2808 @cindex @code{\transpose}
2810 A music expression can be transposed with @code{\transpose}. The syntax
2813 \transpose @var{pitch} @var{musicexpr}
2816 This means that middle C in @var{musicexpr} is transposed to
2819 @code{\transpose} distinguishes between enharmonic pitches: both
2820 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2821 a tone. The first version will print sharps and the second version
2824 @lilypond[fragment,verbatim]
2827 { \key e \major c d e f }
2829 \transpose des'' { \key e \major c d e f }
2830 \transpose cis'' { \key e \major c d e f }
2834 If you want to use both @code{\transpose} and @code{\relative}, then
2835 you must use @code{\transpose} first. @code{\relative} will have no
2836 effect music that appears inside a @code{\transpose}.
2838 @node Sound output for transposing instruments
2839 @subsection Sound output transposing instruments
2841 When you want to make a MIDI file from a score containing transposed and
2843 instruments, you have to instruct LilyPond the pitch offset (in
2844 semitones) for the transposed instruments. This is done using the
2845 @code{transposing} property. It does not affect printed output.
2847 @cindex @code{transposing}
2850 \property Staff.instrument = #"Cl. in B-flat"
2851 \property Staff.transposing = #-2
2854 @c . {Multi measure rests}
2855 @node Multi measure rests
2856 @subsection Multi measure rests
2857 @cindex Multi measure rests
2861 Multi measure rests are entered using `@code{R}'. It is specifically
2862 meant for full bar rests and for entering parts: the rest can expand to
2864 rests, or it can be printed as a single multimeasure rest This expansion
2865 is controlled by the property @code{Score.skipBars}. If this is set to true,
2866 Lily will not expand empty measures, and the appropriate number is added
2869 @lilypond[fragment,verbatim]
2870 \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2873 Notice that the @code{R2.} is printed as a whole rest, centered in the
2876 @cindex whole rests for a full measure
2878 The grob for this object is @internalsref{MultiMeasureRest}.
2882 Currently, there is no way to automatically condense multiple rests into
2883 a single multimeasure rest.
2885 @cindex condensing rests
2887 @node Automatic part combining
2888 @subsection Automatic part combining
2889 @cindex automatic part combining
2890 @cindex part combiner
2893 Automatic part combining is used to merge two parts of music onto a
2894 staff in an intelligent way. It is aimed primarily at typesetting
2895 orchestral scores. When the two parts are identical for a period of
2896 time, only one is shown. In places where the two parts differ, they are
2897 typeset as separate voices, and stem directions are set automatically.
2898 Also, solo and @emph{a due} parts can be identified and marked.
2900 The syntax for part combining is
2903 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2905 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2906 combined into one context of type @var{context}. The music expressions
2907 must be interpreted by contexts whose names should start with @code{one}
2910 The most useful function of the part combiner is to combine parts into
2911 one voice, as common for wind parts in orchestral scores:
2913 @lilypond[verbatim,singleline,fragment]
2915 \context Voice=one \partcombine Voice
2916 \context Thread=one \relative c'' {
2919 \context Thread=two \relative c'' {
2925 Notice that the first @code{g} appears only once, although it was
2926 specified twice (once in each part). Stem, slur and tie directions are
2927 set automatically, depending whether there is a solo or unisono. The
2928 first part (with context called @code{one}) always gets up stems, and
2929 `solo', while the second (called @code{two}) always gets down stems and
2932 If you just want the merging parts, and not the textual markings, you
2933 may set the property @var{soloADue} to false.
2935 @lilypond[verbatim,singleline,fragment]
2937 \property Staff.soloADue = ##f
2938 \context Voice=one \partcombine Voice
2939 \context Thread=one \relative c'' {
2942 \context Thread=two \relative c'' {
2948 There are a number of other properties that you can use to tweak the
2949 behavior of part combining, refer to the automatically generated
2950 documentation of @reng{Thread_devnull_engraver} and
2951 @reng{Voice_devnull_engraver}. Look at the documentation of the
2952 responsible engravers, @code{Thread_devnull_engraver},
2953 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2957 In @code{soloADue} mode, when the two voices play the same notes on and
2958 off, the part combiner may typeset @code{a2} more than once in a
2961 @lilypond[fragment,singleline]
2963 \context Voice=one \partcombine Voice
2964 \context Thread=one \relative c'' {
2967 \context Thread=two \relative c'' {
2973 @cindex @code{Thread_devnull_engraver}
2974 @cindex @code{Voice_engraver}
2975 @cindex @code{A2_engraver}
2977 @node Hara kiri staves
2978 @subsection Hara kiri staves
2980 In orchestral scores, staff lines that only have rests are usually removed.
2981 This saves some space. LilyPond also supports this through the hara
2982 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2983 the Japanese Samourai warriors.} staff. This staff commits suicide when
2984 it finds itself to be empty after the line-breaking process. It will
2985 not disappear when it contains normal rests, you must use multi measure
2988 The hara kiri staff is specialized version of the @internalsref{Staff}
2989 context. It is available as the context identifier
2990 @code{\HaraKiriStaffContext}. Observe how the second staff in this
2991 example disappears in the second line.
2995 \notes \relative c' <
2996 \context Staff = SA { e4 f g a \break c1 }
2997 \context Staff = SB { c4 d e f \break R1 }
3001 \translator { \HaraKiriStaffContext }
3009 @node Ancient notation
3010 @section Ancient notation
3013 * Ancient note heads::
3018 @node Ancient note heads
3019 @subsection Ancient note heads
3021 To get a longa note head, you have to use mensural note heads. This
3022 is accomplished by setting the @code{style} property of the
3023 NoteHead grob to @code{mensural}. There is also a note head style
3024 @code{baroque} which gives mensural note heads for @code{\longa} and
3025 @code{\breve} but standard note heads for shorter notes.
3027 @lilypond[fragment,singleline,verbatim]
3028 \property Voice.NoteHead \set #'style = #'mensural
3029 \property Voice.NoteHead \set #'font-family = #'ancient
3034 @subsection Custodes
3039 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
3040 staff context symbol that appears at the end of a staff line. It
3041 anticipates the pitch of the first note(s) of the following line and
3042 thus helps the player or singer to manage line breaks during
3043 performance, thus enhancing readability of a score.
3048 \property Staff.Custos \set #'style = #'mensural
3053 \consists Custos_engraver
3059 Custodes were frequently used in music notation until the 17th century.
3060 There were different appearances for different notation styles.
3061 Nowadays, they have survived only in special forms of musical notation
3062 such as via the @emph{editio vaticana} dating back to the beginning of
3065 For typesetting custodes, just put a @code{Custos_engraver} into the
3066 @internalsref{Staff} context when declaring the @code{\paper} block. In this
3067 block, you can also globally control the appearance of the custos symbol
3068 by setting the custos @code{style} property. Currently supported styles
3069 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
3076 \consists Custos_engraver
3077 Custos \override #'style = #'mensural
3082 The property can also be set locally, for example in a @code{\notes}
3087 \property Staff.Custos \override #'style = #'vaticana
3088 c'1 d' e' d' \break c' d' e' d'
3093 @section Ancient clefs
3095 LilyPond supports a variety of clefs, many of them ancient. These can
3096 be selected from the @code{ancient} font family, by setting
3097 @code{Staff.clefGlyph}) to the following values
3106 @item clefs-vaticana_do
3107 Editio Vaticana style do clef
3108 @item clefs-vaticana_fa
3109 Editio Vaticana style fa clef
3110 @item clefs-medicaea_do
3111 Editio Medicaea style do clef
3112 @item clefs-medicaea_fa
3113 Editio Medicaea style fa clef
3114 @item clefs-mensural1_c
3115 modern style mensural C clef
3116 @item clefs-mensural2_c
3117 historic style small mensural C clef
3118 @item clefs-mensural3_c
3119 historic style big mensural C clef
3120 @item clefs-mensural1_f
3121 historic style traditional mensural F clef
3122 @item clefs-mensural2_f
3123 historic style new mensural F clef
3124 @item clefs-mensural_g
3125 historic style mensural G clef
3126 @item clefs-hufnagel_do
3127 historic style hufnagel do clef
3128 @item clefs-hufnagel_fa
3129 historic style hufnagel fa clef
3130 @item clefs-hufnagel_do_fa
3131 historic style hufnagel combined do/fa clef
3132 @item clefs-percussion
3133 modern style percussion clef
3136 @emph{Modern style} means ``as is typeset in current editions.''
3137 @emph{Historic style} means ``as was typeset or written in contemporary
3138 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
3141 @cindex Vaticana, Editio
3142 @cindex Medicaea, Editio
3143 @cindex hufnagel clefs
3149 @section Figured bass
3151 @cindex Basso continuo
3153 TODO. see figured-bass.ly
3155 @c . {Tuning output}
3157 @section Tuning output
3159 LilyPond tries to take as much formatting as possible out of your
3160 hands. Nevertheless, there are situations where it needs some help, or
3161 where you want to override its decisions. In this section we discuss
3162 ways to do just that.
3164 Formatting is internally done by manipulating so called grobs (graphic
3165 objects). Each grob carries with it a set of properties (grob
3166 properties) specific to that object. For example, a stem grob has
3167 properties that specify its direction, length and thickness.
3169 The most direct way of tuning the output is by altering the values of
3170 these properties. There are two ways of doing that: first, you can
3171 temporarily change the definition of a certain type of grob, thus
3172 affecting a whole set of objects. Second, you can select one specific
3173 object, and set a grob property in that object.
3176 * Tuning groups of grobs ::
3177 * Tuning per grob ::
3186 @node Tuning groups of grobs
3187 @subsection Tuning groups of grobs
3189 @cindex grob description
3193 A grob definition is a Scheme association list, that is stored in a
3194 context property. By assigning to that property (using plain
3195 @code{\property}), you can change the resulting grobs.
3197 @lilypond[verbatim, fragment]
3198 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
3201 The @code{\property} assignment effectively empties the definition of
3202 the Stem object. One of the effects is that the recipe of how it should be
3203 printed is erased, with the effect of rendering it invisible. The above
3204 assignment is available as a standard identifier, for the case that you
3208 \property Voice.Stem = \turnOff
3215 This mechanism is fairly crude, since you can only set, but not modify,
3216 the definition of a grob. For this reason, there is a more advanced
3219 The definition of a grob is actually a list of default grob
3220 properties. For example, the definition of the Stem grob (available in
3221 @file{scm/grob-description.scm}), defines the following values for
3226 (beamed-lengths . (0.0 2.5 2.0 1.5))
3227 (Y-extent-callback . ,Stem::height)
3231 You can add a property on top of the existing definition, or remove a
3232 property, thus overriding the system defaults:
3234 c'4 \property Voice.Stem \override #'thickness = #4.0
3235 c'4 \property Voice.Stem \revert #'thickness
3238 You should balance @code{\override} and @code{\revert}. If that's too
3239 much work, you can use the @code{\set} shorthand. It performs a revert
3240 followed by an override. The following example gives exactly the same
3241 result as the previous one.
3243 c'4 \property Voice.Stem \set #'thickness = #4.0
3244 c'4 \property Voice.Stem \set #'thickness = #0.8
3247 If you use @code{\set}, you must explicitly restore the default.
3250 Formally the syntax for these constructions is
3252 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
3253 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
3254 \property @var{context}.@var{grobname} \revert @var{symbol}
3256 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
3257 and @var{grobname} are strings and @var{value} is a Scheme expression.
3260 If you revert a setting which was not set in the first place, then it
3261 has no effect. However, if the setting was set as a system default, it
3262 may remove the default value, and this may give surprising results,
3263 including crashes. In other words, @code{\override} and @code{\revert},
3264 must be carefully balanced.
3266 These are examples of correct nesting of @code{\override}, @code{\set},
3269 A clumsy but correct form:
3271 \override \revert \override \revert \override \revert
3274 Shorter version of the same:
3276 \override \set \set \revert
3279 A short form, using only @code{\set}. This requires you to know the
3282 \set \set \set \set @var{to default value}
3285 If there is no default (i.e. by default, the grob property is unset),
3288 \set \set \set \revert
3291 For the digirati, the grob description is an Scheme association
3292 list. Since a Scheme list is a singly linked list, we can treat it as a
3293 stack, and @code{\override} and @code{\revert} are just push and pop
3294 operations. This pushing and popping is also used for overriding
3295 automatic beaming settings.
3299 LilyPond will hang or crash if @var{value} contains cyclic references.
3300 The backend is not very strict in type-checking grob properties. If you
3301 @code{\revert} properties that are expected to be set by default,
3305 @cindex adjusting staff symbol
3306 @cindex StaffSymbol, using \property
3307 @cindex staff lines, setting number of
3309 Some grobs are created at the moment that their context is created. An
3310 example of such a grob is the staff itself (i.e. the horizontal lines).
3311 You can not change the appearance of the staff symbol by manipulating
3312 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3313 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3314 created before any @code{\override} is effective. You can deal with this
3315 either overriding properties in a @code{\translator} definition, or by
3316 using @code{\outputproperty}.
3321 @node Tuning per grob
3322 @subsection Tuning per grob
3324 @cindex \outputproperty
3326 A second way of tuning grobs is the more arcane @code{\outputproperty}
3327 feature. The syntax is as follows:
3329 \outputproperty @var{predicate} @var{symbol} = @var{value}
3331 Here @code{predicate} is a Scheme function taking a grob argument, and
3332 returning a boolean. This statement is processed by the
3333 @code{Output_property_engraver}. It instructs the engraver to feed all
3334 grobs that it sees to @var{predicate}. Whenever the predicate returns
3335 true, the grob property @var{symbol} will be set to @var{value}.
3337 You will need to combine this statement with @code{\context} to select
3338 the appropriate context to apply this to.
3340 Here are some random examples.
3343 In the following example, all note heads occurring at current staff
3344 level, are shifted up and right by setting their @code{extra-offset}
3347 @lilypond[fragment,verbatim,singleline]
3349 \context Staff \outputproperty
3350 #(make-type-checker 'note-head-interface)
3351 #'extra-offset = #'(0.5 . 0.75)
3355 @cindex @code{extra-offset}
3357 In this example, the predicate checks the @code{text} grob property, to
3358 shift only the `m.d.' text, but not the fingering instruction "2".
3359 @lilypond[verbatim,singleline]
3360 #(define (make-text-checker text)
3361 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3364 \notes\relative c''' {
3365 \property Voice.Stem \set #'direction = #1
3366 \outputproperty #(make-text-checker "m.d.")
3367 #'extra-offset = #'(-3.5 . -4.5)
3375 If possible, avoid this feature: the semantics are not very clean, and
3376 the syntax and semantics are up for rewrite.
3382 @subsection What to tune?
3384 This all tells you how to tune grobs, but you don't know what variables
3385 to set? The question is not answered in this part of the manual
3386 (although you may encounter some examples.).
3388 Grob properties are tied directly to the implementation of LilyPond, and
3389 they are thus a moving target. Documentation of such variables is in the
3390 automatically generated documentation. Description of properties are
3391 generated from the source code for each version. This documentation is
3392 therefore more up to date. It should be available from the same place
3393 where you got this manual.
3395 To decide how to tune a grob, you need to find the following information
3398 which grob to modify
3400 which property to modify
3402 which context the grob comes from.
3405 Included with the automatically generated documentation is a master list
3406 of grobs. Selecting a grob will take you to an overview of the
3407 properties available for that grob.
3409 There is also a master list of contexts. Selecting one takes you to an
3410 overview of that context which lists which grob types are created there.
3413 @node Font selection
3414 @subsection Font selection
3416 Most graphics in LilyPond are composed of characters of fonts. You can
3417 alter the characteristics of the font by setting certain grob
3418 properties. The mechanism that is used for this resembles La@TeX{}'s New
3419 Font Selection Scheme. Within this scheme, a font is entirely
3420 characterized by its font name.
3422 For each grob that uses fonts (in other words, each grob that supports
3423 @code{font-interface}) a font-name must be selected before it can be
3424 printed. The font name is selected by looking at a number of grob
3429 A symbol indicating the general class of the typeface. Supported are
3430 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3431 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3432 signs) and @code{typewriter}
3435 A symbol indicating the shape of the font, there are typically several
3436 font shapes available for each font family. Choices are @code{italic},
3437 @code{caps} and @code{upright}
3440 A symbol indicating the series of the font. There are typically several
3441 font series for each font family and shape. Choices are @code{medium}
3444 @item font-relative-size
3445 A number indicating the size relative the standard size. For example,
3446 with 20pt staff height, relative size -1 corresponds to 16pt staff
3447 height, and relative size +1 corresponds to 23 pt staff height.
3449 @item font-design-size
3450 A number indicating the design size of the font.
3452 This is a feature of the Computer Modern Font: each point size has a
3453 slightly different design. Smaller design sizes are relatively wider,
3454 which enhances readability. Scalable type faces such TrueType and Adobe
3455 Type1 usually come as ``one design fits all sizes''.
3458 The name of the font, without the design size, e.g. @code{cmr},
3459 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3466 The font is selected by taking the first font that satisfies all
3467 qualifiers specified. You can override any of these fields through
3468 @code{\override} and @code{\revert}. The special value @code{*} matches
3469 any value for that qualifier.
3472 \property Lyrics.LyricText \override #'font-series = #'bold
3473 \property Lyrics.LyricText \override #'font-shape = #'*
3476 @cindex @code{font-style}
3478 There are also pre-cooked font selection qualifiers. These are selected
3479 through the grob property @code{font-style}. For example, the style
3480 @code{finger} selects family @code{number} and relative size @code{-3}.
3481 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3482 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3485 The style sheets and tables for selecting fonts are located in
3486 @file{scm/font.scm}. Refer to this file for more information.
3489 Setting @code{font-name} overrides all other qualifiers. The value for
3490 this property should be a string, the file name of the font. You may use
3491 this to use special fonts, which are not a part of the style sheet, or
3492 which have special encodings.
3494 The size of the font may be set with the grob property
3495 @code{font-magnification}. It is the size of font, relative to its
3496 standard size. For example, @code{1.0} is normal size.
3500 Relative size is not linked to any real size.
3502 There is no style sheet provided for other fonts besides the @TeX{}
3505 @cindex font selection
3506 @cindex font magnification
3507 @cindex @code{font-interface}
3511 @subsection Text markup
3515 LilyPond has an internal mechanism to typeset texts. You can
3516 form text markup expressions by composing scheme expressions
3517 in the following way.
3519 @lilypond[verbatim, singleline]
3524 c^#'(italic "italic")
3525 d_#'((bold italic) "ff")
3527 f_#'(lines "one" (bold "two"))
3528 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3532 Normally, the Scheme markup text is stored in the @code{text} property
3533 of a grob. Formally, it is defined as follows:
3536 text: string | (head? text+)
3537 head: markup | (markup+)
3538 markup-item: property | abbrev
3539 property: (@var{key} . @var{value})
3540 abbrev: @code{columns lines roman music bold italic named super sub}
3541 @code{overstrike text finger volta timesig mmrest mark script}
3542 @code{large Large dynamic}
3545 The markup is broken down and converted into a list of grob properties,
3546 which are prepended to the property list. The @var{key}-@var{value}
3547 pair is a grob property. A list of properties available is included in
3548 the generated documentation for @rint{Text_interface}.
3550 The following abbreviations are currently defined:
3553 horizontal mode: set all text on one line (default)
3555 vertical mode: set every text on a new line
3559 selects the Feta font (the standard font for music notation glyphs),
3560 and uses named lookup
3567 lookup by character name
3569 plain text lookup (by character value)
3575 the next text or character overstrikes this one
3577 select fingering number fontstyle
3579 select volta number fontstyle
3581 select time signature number fontstyle
3583 select multi measure rest number fontstyle
3585 select mark number fontstyle
3587 select scriptsize roman fontstyle
3589 select large roman fontstyle
3591 select Large roman fontstyle
3593 select dynamics fontstyle
3597 @cindex metronome mark
3599 One practical application of complicated markup is to fake a metronome
3603 #(define note '(columns
3604 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3605 #(define eight-note `(columns ,note ((kern . -0.1)
3606 (music ((raise . 3.5) "flags-u3")))))
3607 #(define dotted-eight-note
3608 `(columns ,eight-note (music "dots-dot")))
3611 \notes\relative c'' {
3612 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3618 TextScript \override #'font-shape = #'upright
3624 @node Invisible grobs
3625 @subsection Invisible grobs
3626 @cindex invisible grobs
3630 ben nog steeds niet kapot van de informatiedichtheid hier.
3636 You can imagine a number of situations where you would want to make
3637 certain grobs not show up in the output. There may be aesthetic
3638 reasons, to make the output resemble an (old) manuscript as close as
3639 possible, or to make lessons or exercises for students.
3641 Grobs can be made invisible in a number of ways:
3643 Here's an example with blanked-out notes and stems:
3644 @lilypond[singleline,verbatim]
3646 \property Voice.NoteHead \override
3648 \property Voice.Stem \override
3649 #'transparent = ##t }
3652 \property Voice.NoteHead \revert #'transparent
3653 \property Voice.Stem \revert #'transparent }
3656 \notes\relative c'' {
3658 a b c b \blanknotes c \unblanknotes d
3662 This method makes the grobs invisible but they still take the normal space.
3663 To remove all traces of the grob, you can redefine the function
3667 \notes\relative c'' {
3670 as bes c bes c d \break
3671 \property Staff.KeySignature \override #'molecule-callback = #'()
3674 \paper{linewidth=5.0\cm indent=0}
3678 A very rigorous way of removing grobs from the whole score is to remove
3679 the engraver that creates them. For example,
3681 @lilypond[singleline,verbatim]
3682 \score {\notes { c'4 d'8 e'8 g2 }
3683 \paper { \translator {
3685 \remove Stem_engraver
3691 @subsection Dirty tricks
3692 @cindex embedded tex
3694 It is possible to use @TeX{} commands in the strings, but this should be
3695 avoided because it makes it impossible for LilyPond to compute the
3696 exact length of the string, which may lead to collisions. Also, @TeX{}
3697 commands won't work with direct PostScript output (see @ref{PostScript
3700 @lilypond[fragment,relative,verbatim]
3701 a'^"3 $\\times$ \\`a deux"
3704 You can also use raw PostScript commands embedded in text scripts. This
3705 offers ultimate flexibility, but requires you to learn PostScript.
3706 Currently, embedded PostScript will @strong{not} work with direct
3707 PostScript output. Note that all dimensions that you use are in staff
3712 \notes \relative c'' {
3713 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3714 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3715 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3719 \paper { linewidth = 70*\staffspace }
3726 TODO: Move this section.
3732 Generating optically pleasing spacing is black magic. LilyPond tries
3733 to deal with a number of frequent cases. Here is an example that is
3734 not handled correctly, due to the combination of chord collisions and
3739 \context PianoStaff \notes \transpose c''' <
3740 \context Staff = up { s1 }
3741 \context Staff = down { [c8 c \translator Staff=up <c d> c
3742 \translator Staff=down c c c] }
3744 \paper { linewidth = -1 }
3752 @section Page layout
3755 The page layout is the combined product of LilyPond formatting notation,
3756 and (La)@TeX{} putting the notation on a page, including page breaks.
3757 The part of LilyPond is documented here.
3771 @subsection Paper block
3774 The most important output definition is the @code{\paper} block, for
3775 music notation. The syntax is
3778 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3781 where each of the items is one of
3784 @item An assignment.
3786 @item A context definition. See @ref{Interpretation context} for
3787 more information on context definitions.
3789 @item \stylesheet declaration. Its syntax is
3791 \stylesheet @var{alist}
3794 See @file{scm/font.scm} for details of @var{alist}.
3795 @item an @code{\elementdescriptions} declaration.
3797 \elementdescriptions @var{alist}
3799 See @file{scm/grob-description.scm} for details of
3800 @var{alist}. This command is not user-serviceable.
3804 @c . {Paper variables}
3805 @node Paper variables
3806 @subsection Paper variables
3807 @cindex Paper variables
3809 The paper block has some variables you may want to use or change:
3812 @cindex @code{indent}
3814 The indentation of the first line of music.
3815 @cindex @code{staffspace}
3817 @item @code{staffspace}
3818 The distance between two staff lines, calculated from the center
3821 @cindex @code{linewidth}
3822 @item @code{linewidth}
3823 Sets the width of the lines.
3825 If set to a negative value, a single unjustified line is produced.
3826 @c rename to singleLinePaper ?
3827 The shorthand @code{\singleLine} defines a default paper block that
3828 produces a single line.
3830 @cindex @code{textheight}
3832 @item @code{textheight}
3833 Sets the total height of the music on each page. Only used by
3836 @cindex @code{interscoreline}
3838 @item @code{interscoreline}
3839 Sets the spacing between systems. The default is 16pt.
3841 @cindex @code{interscorelinefill}
3843 @item @code{interscorelinefill}
3844 If set to a positive number, the distance between the score
3845 lines will stretch in order to fill the full page. In that
3846 case @code{interscoreline} specifies the minimum spacing.
3851 @cindex @code{stafflinethickness}
3853 @item @code{stafflinethickness}
3854 Determines the thickness of staff lines, and also acts as a scaling
3855 parameter for other line thicknesses.
3858 You may enter these dimension using units (@code{cm}, @code{in},
3859 @code{mm}, @code{pt}), or relative to another dimension
3861 linewidth = 20.0 * \staffspace
3868 @subsection Font size
3869 @cindex font size, setting
3870 @cindex staff size, setting
3871 @cindex @code{paper} file
3873 The Feta font provides musical symbols at six different sizes. These
3874 fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
3875 point. The point size of a font is the height of the five lines in a
3876 staff when displayed in the font.
3878 Definitions for these sizes are the files @file{paperSZ.ly}, where
3879 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3880 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3881 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3882 @code{paperTwentysix} are defined respectively. The default
3883 @code{\paper} block is also set. These files should be imported at toplevel, i.e.
3885 \include "paper26.ly"
3889 The font definitions are generated using a Scheme function. For more
3890 details, see the file @file{scm/font.scm}.
3896 @subsection Paper size
3901 @cindex @code{papersize}
3903 To change the paper size, you must first set the
3904 @code{papersize} paper variable variable. Set it to
3905 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3906 specification, you must set the font as described above. If you want
3907 the default font, then use the 20 point font.
3910 \paper@{ papersize = "a4" @}
3911 \include "paper16.ly"
3914 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3915 will set the paper variables @code{hsize} and @code{vsize} (used by
3916 Lilypond and @code{ly2dvi})
3920 @subsection Line break
3923 @cindex breaking lines
3925 Line breaks are normally computed automatically. They are chosen such
3926 that it looks neither cramped nor loose, and that consecutive lines have
3929 Occasionally you might want to override the automatic breaks; you can do
3930 this by specifying @code{\break}. This will force a line break at this
3931 point. Do remember that line breaks can only occur at places where there
3932 are bar lines. If you want to have a line break where there is no
3933 bar line, you can force an invisible bar line by entering @code{\bar
3934 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3936 If you want linebreaks at regular intervals, you can use the following:
3939 < \repeat 7 unfold @{ s1 * 4 \break @}
3943 This makes the following 28 measures (assuming 4/4 time) be broken every
3947 @cindex @code{\penalty}
3949 The @code{\break} and @code{\noBreak} commands are defined in terms of
3950 the penalty command:
3955 This encourages or discourages LilyPond to make a line break at this
3960 The scaling of the @code{\penalty} argument is not well-defined. The
3961 command is rather kludgey, and slated for rewriting.
3965 @subsection Page break
3968 @cindex breaking pages
3970 Page breaks are normally computed by @TeX{}, so they are not under
3971 direct control of LilyPond. However, you can insert a commands into the
3972 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3973 the command @code{\newpage}
3974 @cindex @code{\newpage}
3980 @c why do so difficult?
3981 @c maybe should explain contents of between-system.ly,
3982 @c but not now, we're talking about page breaks here.
3984 @c details, see the example file @file{input/test/between-systems.ly}
3987 @c . {Output scaling}
3988 @node Output scaling
3989 @subsection Output scaling
4004 There is no mechanism to select magnification of particular fonts,
4005 meaning that you don't have access to continuously scaled fonts.
4009 @c . {Output formats}
4010 @node Output formats
4011 @section Output formats
4013 LilyPond can output processed music in different output formats.
4017 * PostScript output::
4019 * ASCIIScript output::
4023 @subsection TeX output
4026 LilyPond will use @TeX{} by default. Even if you want to produce
4027 PostScript output for viewing or printing, you should normally have
4028 LilyPond produce @TeX{} first. The .tex output must be processed by
4029 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
4030 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
4031 used to generate the .dvi for you.
4035 Titling is not generated unless you use @file{ly2dvi}.
4038 @node PostScript output
4039 @subsection PostScript output
4040 @cindex PostScript output
4041 @cindex direct PostScript output
4043 LilyPond can produce PostScript directly, without going through @TeX{}.
4044 Currently, this is mainly useful if you cannot use TeX, because direct
4045 PostScript output has some problems; see Bugs below.
4048 $ lilypond -fps foo.ly
4049 GNU LilyPond 1.3.144
4050 Now processing: `foo.ly'
4052 Interpreting music...[3]
4053 Preprocessing elements...
4054 Calculating column positions...
4055 paper output to foo.ps...
4057 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
4063 Text font selection is broken.
4065 The .ps file does not contain the .pfa font files. To print a .ps
4066 created through direct postscript output, you should prepend the
4067 necessary .pfa files to LilyPond's .ps output, or upload them to the
4068 printer before printing.
4070 The line height calculation is broken, you must set @var{lineheight} in
4071 the paperblock if you have more than one staff in your score, e.g.
4076 % Set line height to 40 staff spaces
4082 @subsection Scheme output
4083 @cindex Scheme output
4085 In the typesetting stage, LilyPond builds a page description, which is
4086 then written to disk in postscript, @TeX{} or ASCII art. Before it is
4087 written, the page description is represented as Scheme expressions. You
4088 can also dump these Scheme expressions to a file, which may be
4089 convenient for debugging output routines. This is done with the Scheme
4093 $ lilypond -fscm foo.ly
4094 GNU LilyPond 1.3.144
4095 Now processing: `foo.ly'
4097 Interpreting music...[3]
4098 Preprocessing elements...
4099 Calculating column positions...
4100 paper output to foo.scm...
4103 ;;; Usage: guile -s x.scm > x.tex
4104 (primitive-load-path 'standalone.scm)
4108 $ guile -s foo.scm > foo.tex
4112 @node ASCIIScript output
4113 @subsection ASCIIScript output
4114 @cindex ASCIIScript output
4115 @cindex ascii script
4118 LilyPond can output ASCII Art. This is a two step process, LilyPond
4119 produces an ASCII description file, dubbed ASCIIScript (extension
4120 @file{.as}). ASCIIScript has a small and simple command set that
4121 includes font selection, character and string printing and line drawing
4122 commands. The program @file{as2text} is used to translate an .as file
4125 To produce ASCII Art, you must include an ASCII Art paper definition
4126 file in your .ly, one of:
4128 \include "paper-as5.ly"
4129 \include "paper-as9.ly"
4132 Here's an example use for ASCII Art output (the example file
4133 @file{as-email.ly} is included in the LilyPond distribution), the staff
4134 symbol has been made invisible:
4137 $ lilypond -fas as-email.ly
4138 GNU LilyPond 1.3.144
4139 Now processing: `as-email.ly'
4141 Interpreting music...[3]
4142 Preprocessing elements...
4143 Calculating column positions... [2]
4144 paper output to as-email.as...
4146 $ as2text as-email.as 2>/dev/null
4148 |/ |##|##| | | | | |
4149 /| | | | | |\ |\ |\ |\ |\ |
4150 / |_ 3 | | | | 5 | )| )| )| )| )|
4151 | /| \ 8 * * * | 8 * * * * * |
4161 The ASCII Art fonts are far from complete and not very well designed.
4162 It's easy to change the glyphs, though; if you think you can do better,
4163 have a look at @file{mf/*.af}.
4165 Lots of resizable symbols such as slurs, ties and tuplets are missing.
4167 The poor looks of most ASCII Art output and its limited general
4168 usefulness gives ASCII Art output a low priority; it may be
4169 dropped in future versions.
4176 LilyPond can produce MIDI output. The performance lacks lots of
4177 interesting effects, such as swing, articulation, slurring, etc., but it
4178 is good enough for proof-hearing the music you have entered. Ties,
4179 dynamics and tempo changes are interpreted.
4181 Dynamic marks, crescendi and decrescendi translate into MIDI volume
4182 levels. Dynamic marks translate to a fixed fraction of the available
4183 MIDI volume range, crescendi and decrescendi make the the volume vary
4184 linearly between their two extremities. The fractions be adjusted by
4185 overriding the @code{absolute-volume-alist} defined in
4186 @file{scm/midi.scm}.
4188 For each type of musical instrument (that MIDI supports), a volume range
4189 can be defined. This gives you basic equalizer control, which can
4190 enhance the quality of the MIDI output remarkably. You can add
4191 instruments and ranges or change the default settings by overriding the
4192 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
4194 Both loudness controls are combined to produce the final MIDI volume.
4199 It is currently not possible to use the percussion channel (generally
4200 channel 10 of a MIDI file).
4204 * MIDI instrument names::
4209 @subsection MIDI block
4213 The MIDI block is analogous to the paper block, but it is somewhat
4214 simpler. The @code{\midi} block can contain:
4218 @item a @code{\tempo} definition
4219 @item context definitions
4222 Assignments in the @code{\midi} block are not allowed.
4226 @cindex context definition
4228 Context definitions follow precisely the same syntax as within the
4229 \paper block. Translation modules for sound are called performers.
4230 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
4233 @node MIDI instrument names
4234 @subsection MIDI instrument names
4236 @cindex instrument names
4237 @cindex @code{Staff.midiInstrument}
4238 @cindex @code{Staff.instrument}
4240 The MIDI instrument name is set by the @code{Staff.midiInstrument}
4241 property or, if that property is not set, the @code{Staff.instrument}
4242 property. The instrument name should be chosen from the list in
4243 @ref{MIDI instruments}.
4247 If the selected string does not exactly match, then LilyPond uses the
4248 default (Grand Piano). It is not possible to select an instrument by
4258 @c FIXME: Note entry vs Music entry at top level menu is confusing.
4261 @section Music entry
4269 When entering music with LilyPond, it is easy to introduce errors. This
4270 section deals with tricks and features that help you enter music, and
4271 find and correct mistakes.
4275 @subsection Relative
4277 @cindex relative octave specification
4279 Octaves are specified by adding @code{'} and @code{,} to pitch names.
4280 When you copy existing music, it is easy to accidentally put a pitch in
4281 the wrong octave and hard to find such an error. To prevent these
4282 errors, LilyPond features octave entry.
4284 @cindex @code{\relative}
4286 \relative @var{startpitch} @var{musicexpr}
4289 The octave of notes that appear in @var{musicexpr} are calculated as
4290 follows: If no octave changing marks are used, the basic interval
4291 between this and the last note is always taken to be a fourth or less
4292 (This distance is determined without regarding alterations; a
4293 @code{fisis} following a @code{ceses} will be put above the
4296 The octave changing marks @code{'} and @code{,} can be added to raise or
4297 lower the pitch by an extra octave. Upon entering relative mode, an
4298 absolute starting pitch must be specified that will act as the
4299 predecessor of the first note of @var{musicexpr}.
4301 Entering music that changes octave frequently is easy in relative mode.
4302 @lilypond[fragment,singleline,verbatim,center]
4308 And octave changing marks are used for intervals greater than a fourth.
4309 @lilypond[fragment,verbatim,center]
4311 c g c f, c' a, e'' }
4314 If the preceding item is a chord, the first note of the chord is used
4315 to determine the first note of the next chord. However, other notes
4316 within the second chord are determined by looking at the immediately
4319 @lilypond[fragment,verbatim,center]
4326 @cindex @code{\notes}
4328 The pitch after the @code{\relative} contains a note name. To parse
4329 the pitch as a note name, you have to be in note mode, so there must
4330 be a surrounding @code{\notes} keyword (which is not
4333 The relative conversion will not affect @code{\transpose},
4334 @code{\chords} or @code{\relative} sections in its argument. If you
4335 want to use relative within transposed music, you must place an
4336 additional @code{\relative} inside the @code{\transpose}.
4341 @subsection Bar check
4345 @cindex @code{barCheckNoSynchronize}
4349 Whenever a bar check is encountered during interpretation, a warning
4350 message is issued if it doesn't fall at a measure boundary. This can
4351 help you find errors in the input. Depending on the value of
4352 @code{barCheckNoSynchronize}, the beginning of the measure will be
4353 relocated, so this can also be used to shorten measures.
4355 A bar check is entered using the bar symbol, @code{|}:
4357 \time 3/4 c2 e4 | g2.
4362 @cindex skipTypesetting
4364 Failed bar checks are most often caused by entering incorrect
4365 durations. Incorrect durations often completely garble up the score,
4366 especially if it is polyphonic, so you should start correcting the score
4367 by scanning for failed bar checks and incorrect durations. To speed up
4368 this process, you can use @code{skipTypesetting} (See @ref{Skipping
4369 corrected music})). Bar
4372 @c . {Point and click}
4373 @node Point and click
4374 @subsection Point and click
4376 Point and click lets you find notes in the input by clicking on them in
4377 the Xdvi window. This makes it very easy to find input that causes some
4378 error in the sheet music.
4380 To use it, you need the following software
4382 @unnumberedsubsec Installation
4386 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
4387 Xdvi} version 22.36 or newer.
4389 Note that most @TeX{} distributions ship with xdvik, which is a
4390 different and less well maintained program. To find out which xdvi you
4391 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
4395 Xdvi must be configured to find the TeX fonts and music
4396 fonts. Refer to the Xdvi documentation for more information.
4399 @unnumberedsubsec Using it
4401 Add one of these lines to the top of your .ly file. The first one is for
4402 line location only. The second one is more convenient, but requires
4403 patching @code{emacsclient} and @code{server.el}.
4406 #(set! point-and-click line-location)
4409 In the emacs startup file (usually @file{~/.emacs}), add the following
4414 Make sure that the environment variable @code{XEDITOR} is set
4417 emacsclient --no-wait +%l %f
4419 The second one, that also specifies the column, only works if you have
4420 patched your emacsclient and server, and have compiled your @code{.ly}
4421 file using the @code{line-column-location} setting.
4423 When viewing, control-mousebutton 1 will take you to the originating
4424 spot in the @file{.ly} file. Control-mousebutton 2 will show all
4428 @unnumberedsubsec Column location
4430 If you want emacs to jump to the exact spot (and not just the line) on a
4431 click, you must enable column positioning. To do so, you need to patch
4432 emacsclient. Apply @file{emacsclient.patch} (included with the source
4433 package) to @file{emacsclient.c} and @file{server.el} from the emacs
4434 source code. Recompile and stick the recompiled emacsclient into a bin
4435 directory, and put @file{server.el} into a elisp directory
4436 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
4437 init file, before invoking server-start.
4440 (setq load-path (cons "~/usr/share/emacs" load-path))
4443 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
4445 At the top of the @code{ly} file, replace the @code{set!} line with the
4448 #(set! point-and-click line-column-location)
4451 One final hint: if you correct large files with point-and-click, then
4452 start correcting at the end of the file. When you start at the top, and
4453 insert one line, all subsequent locations will be off by a line.
4458 When you convert the @TeX{} file to PostScript using @code{dvips}, it
4459 will complain about not finding @code{src:X:Y} files. Those complaints
4460 are harmless, and can be ignored.
4462 @node Skipping corrected music
4463 @section Skipping corrected music
4465 The property @code{Score.skipTypesetting} can be used to switch on and
4466 off typesetting completely during the interpretation phase. When
4467 typesetting is switched off, the music is processed much more quickly.
4468 You can use this to skip over the parts of a score that you have already
4471 @lilypond[fragment,singleline,verbatim]
4472 \relative c'' { c8 d
4473 \property Score.skipTypesetting = ##t
4475 \property Score.skipTypesetting = ##f
4480 @node Interpretation context
4481 @section Interpretation context
4484 * Creating contexts::
4485 * Default contexts::
4486 * Context properties::
4487 * Engravers and performers::
4488 * Changing context definitions::
4489 * Defining new contexts::
4493 Interpretation contexts are objects that only exist during a run of
4494 LilyPond. During the interpretation phase of LilyPond (when it prints
4495 "interpreting music"), the music expression in a @code{\score} block is
4496 interpreted in time order. This is the same order that humans hear and
4499 During this interpretation, the interpretation context holds the
4500 state for the current point within the music. It contains information
4504 @item What notes are playing at this point?
4505 @item What symbols will be printed at this point?
4506 @item What is the current key signature, time signature, point within
4510 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4511 contained in a @internalsref{Staff} context (because a staff can contain
4512 multiple voices at any point), a @internalsref{Staff} context is contained in
4513 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4515 Contexts associated with sheet music output are called @emph{notation
4516 contexts}, those for sound output are called @emph{performance
4517 contexts}. The default definitions of the standard notation and
4518 performance contexts can be found in @file{ly/engraver-init.ly} and
4519 @file{ly/performer-init.ly}, respectively.
4521 @node Creating contexts
4522 @subsection Creating contexts
4524 @cindex @code{\context}
4525 @cindex context selection
4527 Contexts for a music expression can be selected manually, using the
4528 following music expression.
4531 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4534 This instructs lilypond to interpret @var{musicexpr} within the context
4535 of type @var{contexttype} and with name @var{contextname}. If this
4536 context does not exist, it will be created.
4538 @lilypond[verbatim,singleline]
4540 \notes \relative c'' {
4541 c4 <d4 \context Staff = "another" e4> f
4547 In this example, the @code{c} and @code{d} are printed on the
4548 default staff. For the @code{e}, a context Staff called
4549 @code{another} is specified; since that does not exist, a new
4550 context is created. Within @code{another}, a (default) Voice context
4551 is created for the @code{e4}. When all music referring to a
4552 context is finished, the context is ended as well. So after the
4553 third quarter, @code{another} is removed.
4557 @node Default contexts
4558 @subsection Default contexts
4560 Most music expressions don't need an explicit @code{\context}
4561 declaration: they inherit the
4562 notation context from their parent. Each note is a music expression, and
4563 as you can see in the following example, only the sequential music
4564 enclosing the three notes has an explicit context.
4566 @lilypond[verbatim,singleline]
4567 \score { \notes \context Voice = goUp { c'4 d' e' } }
4570 There are some quirks that you must keep in mind when dealing with
4573 First, every top level music is interpreted by the Score context, in other
4574 words, you may think of @code{\score} working like
4577 \context Score @var{music}
4581 Second, contexts are created automatically to be able to interpret the
4582 music expressions. Consider the following example.
4584 @lilypond[verbatim, singleline]
4585 \score { \context Score \notes { c'4 ( d' )e' } }
4588 The sequential music is interpreted by the Score context initially
4589 (notice that the @code{\context} specification is redundant), but when a
4590 note is encountered, contexts are setup to accept that note. In this
4591 case, a Thread, Voice and Staff are created. The rest of the sequential
4592 music is also interpreted with the same Thread, Voice and Staff context,
4593 putting the notes on the same staff, in the same voice.
4595 This is a convenient mechanism, but do not expect opening chords to work
4596 without @code{\context}. For every note, a separate staff is
4599 @cindex explicit context
4600 @cindex starting with chords
4601 @cindex chords, starting with
4603 @lilypond[verbatim, singleline]
4604 \score { \notes <c'4 es'> }
4607 Of course, if the chord is preceded by a normal note in sequential
4608 music, the chord will be interpreted by the Thread of the preceding
4610 @lilypond[verbatim,singleline]
4611 \score { \notes { c'4 <c'4 es'> } }
4616 @node Context properties
4617 @subsection Context properties
4619 Notation contexts have properties. These properties are from
4620 the @file{.ly} file using the following expression:
4621 @cindex @code{\property}
4623 \property @var{contextname}.@var{propname} = @var{value}
4626 Sets the @var{propname} property of the context @var{contextname} to the
4627 specified Scheme expression @var{value}. All @var{propname} and
4628 @var{contextname} are strings, which are typically unquoted.
4630 Properties that are set in one context are inherited by all of the
4631 contained contexts. This means that a property valid for the
4632 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4633 example) and thus take effect in all @internalsref{Voice} contexts.
4635 Properties can be unset using the following expression:
4637 \property @var{contextname}.@var{propname} \unset
4640 @cindex properties, unsetting
4641 @cindex @code{\unset}
4643 This removes the definition of @var{propname} in @var{contextname}. If
4644 @var{propname} was not defined in @var{contextname} (but was inherited
4645 from a higher context), then this has no effect.
4650 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4651 the inverse of @code{\property \set}.
4653 @node Engravers and performers
4654 @subsection Engravers and performers
4658 Basic building blocks of translation are called engravers; they are
4659 special C++ classes.
4663 @c . {Context definitions}
4664 @node Changing context definitions
4665 @subsection Changing context definitions
4667 @cindex context definition
4668 @cindex translator definition
4670 The most common way to define a context is by extending an existing
4671 context. You can change an existing context from the paper block, by
4672 first initializing a translator with an existing context identifier:
4676 @var{context-identifier}
4679 Then you can add and remove engravers using the following syntax:
4681 \remove @var{engravername}
4682 \consists @var{engravername}
4686 Here @var{engravername} is a string, the name of an engraver in the
4690 @lilypond[verbatim,singleline]
4694 \translator { \StaffContext
4695 \remove Clef_engraver
4701 You can also set properties in a translator definition. The syntax is as
4704 @var{propname} = @var{value}
4705 @var{propname} \set @var{grob-propname} = @var{pvalue}
4706 @var{propname} \override @var{grob-propname} = @var{pvalue}
4707 @var{propname} \revert @var{grob-propname}
4709 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4710 and @code{pvalue} are Scheme expressions. These type of property
4711 assignments happen before interpretation starts, so a @code{\property}
4712 command will override any predefined settings.
4715 To simplify editing translators, all standard contexts have standard
4716 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4717 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
4719 @node Defining new contexts
4720 @subsection Defining new contexts
4722 If you want to build a context from scratch, you must also supply the
4723 following extra information:
4725 @item A name, specified by @code{\name @var{contextname}}.
4727 @item A cooperation module. This is specified by @code{\type
4734 \type "Engraver_group_engraver"
4737 \consists "Staff_symbol_engraver"
4738 \consists "Note_head_engraver"
4739 \consistsend "Axis_group_engraver"
4743 The argument of @code{\type} is the name for a special engraver that
4744 handles cooperation between simple engravers such as
4745 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4746 for this engraver are the following:
4748 @cindex @code{Engraver_group_engraver}
4749 @item @code{Engraver_group_engraver}
4750 The standard cooperation engraver.
4752 @cindex @code{Score_engraver}
4754 @item @code{Score_engraver}
4755 This is cooperation module that should be in the top level context,
4756 and only the top level context.
4758 @cindex @code{Grace_engraver_group}
4760 @item @code{Grace_engraver_group}
4761 This is a special cooperation module (resembling
4762 @code{Score_engraver}) that is used to create an embedded
4769 @item @code{\alias} @var{alternate-name}
4770 This specifies a different name. In the above example,
4771 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4773 @item @code{\consistsend} @var{engravername}
4774 Analogous to @code{\consists}, but makes sure that
4775 @var{engravername} is always added to the end of the list of
4778 Some engraver types need to be at the end of the list; this
4779 insures they stay there even if a user adds or removes engravers.
4780 End-users generally don't need this command.
4782 @item @code{\accepts} @var{contextname}
4783 Add @var{contextname} to the list of contexts this context can
4784 contain in the context hierarchy. The first listed context is the
4785 context to create by default.
4787 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4788 completeness, but is never used in practice.
4791 @item @code{\name} @var{contextname}
4792 This sets the type name of the context, e.g. @internalsref{Staff},
4793 @internalsref{Voice}. If the name is not specified, the translator won't do
4797 In the @code{\paper} block, it is also possible to define translator
4798 identifiers. Like other block identifiers, the identifier can only
4799 be used as the very first item of a translator. In order to define
4800 such an identifier outside of @code{\score}, you must do
4805 foo = \translator @{ @dots{} @}
4812 \translator @{ \foo @dots{} @}
4820 @cindex paper types, engravers, and pre-defined translators
4827 @c . {Syntactic details}
4828 @node Syntactic details
4829 @section Syntactic details
4830 @cindex Syntactic details
4832 This section describes details that were too boring to be put elsewhere.
4837 * Music expressions::
4838 * Manipulating music expressions::
4846 @subsection Top level
4849 This section describes what you may enter at top level.
4853 @subsubsection Score
4856 @cindex score definition
4858 The output is generated combining a music expression with an output
4859 definition. A score block has the following syntax:
4862 \score @{ @var{musicexpr} @var{outputdefs} @}
4865 @var{outputdefs} are zero or more output definitions. If none is
4866 supplied, the default @code{\paper} block will be added.
4870 @c . {Default output}
4871 @subsubsection Default output
4873 Default values for the @code{\paper} and @code{\midi} block are set by
4874 entering such a block at the top level.
4877 @subsubsection Header
4879 @cindex @code{\header}
4882 A header describes bibliographic information of the file's contents. It
4883 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4884 use this information for generating titles. Key values that are used by
4885 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4886 meter, arranger, piece and tagline.
4888 @cindex @code{ly2dvi}
4892 \header @{ @var{key1} = @var{val1}
4893 @var{key2} = @var{val2} @dots{} @}
4896 It is customary to put the @code{\header} at the top of the file.
4898 @subsubsection Default output
4900 A @code{\midi} or @code{\paper} block at top level sets the default
4901 paper block for all scores that lack an explicit paper block.
4905 @subsection Identifiers
4909 What has this section got to do with identifiers?
4910 It seems more appropriate in the introduction to Chapter 4,
4916 All of the information in a LilyPond input file, is internally
4917 represented as a Scheme value. In addition to normal Scheme data types
4918 (such as pair, number, boolean, etc.), LilyPond has a number of
4919 specialized data types,
4926 @item Translator_def
4930 @item Music_output_def
4931 @item Moment (rational number)
4934 LilyPond also includes some transient object types. Objects of these
4935 types are built during a LilyPond run, and do not `exist' per se within
4936 your input file. These objects are created as a result of your input
4937 file, so you can include commands in the input to manipulate them,
4938 during a lilypond run.
4941 @item Grob: short for Graphical object. See @ref{Grobs}.
4942 @item Molecule: device-independent page output object,
4943 including dimensions. Produced by some Grob functions
4945 @item Translator: object that produces audio objects or Grobs. This is
4946 not yet user accessible.
4947 @item Font_metric: object representing a font.
4951 @node Music expressions
4952 @subsection Music expressions
4954 @cindex music expressions
4956 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4957 syllables are music expressions, and you can combine music expressions
4958 to form new ones, for example by enclosing a list of expressions in
4959 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4960 compound expression is formed out of the quarter note @code{c} and a
4961 quarter note @code{d}:
4964 \sequential @{ c4 d4 @}
4967 @cindex Sequential music
4968 @cindex @code{\sequential}
4969 @cindex sequential music
4972 @cindex Simultaneous music
4973 @cindex @code{\simultaneous}
4975 The two basic compound music expressions are simultaneous and
4979 \sequential @code{@{} @var{musicexprlist} @code{@}}
4980 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4982 For both, there is a shorthand:
4984 @code{@{} @var{musicexprlist} @code{@}}
4988 @code{<} @var{musicexprlist} @code{>}
4990 for simultaneous music.
4991 In principle, the way in which you nest sequential and simultaneous to
4992 produce music is not relevant. In the following example, three chords
4993 are expressed in two different ways:
4995 @lilypond[fragment,verbatim,center]
4996 \notes \context Voice {
4997 <a c'> <b d' > <c' e'>
4998 < { a b c' } { c' d' e' } >
5003 Other compound music expressions include
5006 \transpose @var{pitch} @var{expr}
5007 \apply @var{func} @var{expr}
5008 \context @var{type} = @var{id} @var{expr}
5009 \times @var{fraction} @var{expr}
5013 @c . {Manipulating music expressions}
5014 @node Manipulating music expressions
5015 @subsection Manipulating music expressions
5017 The @code{\apply} mechanism gives you access to the internal
5018 representation of music. You can write Scheme-functions that operate
5019 directly on it. The syntax is
5021 \apply #@var{func} @var{music}
5023 This means that @var{func} is applied to @var{music}. The function
5024 @var{func} should return a music expression.
5026 This example replaces the text string of a script. It also shows a dump
5027 of the music it processes, which is useful if you want to know more
5028 about how music is stored.
5030 @lilypond[verbatim,singleline]
5031 #(define (testfunc x)
5032 (if (equal? (ly-get-mus-property x 'text) "foo")
5033 (ly-set-mus-property x 'text "bar"))
5035 (ly-set-mus-property x 'elements
5036 (map testfunc (ly-get-mus-property x 'elements)))
5041 \apply #testfunc { c'4_"foo" }
5045 For more information on what is possible, see the automatically
5046 generated documentation.
5049 Directly accessing internal representations is dangerous: the
5050 implementation is subject to changes, so you should avoid this feature
5053 A final example is a function that reverses a piece of music in time:
5055 @lilypond[verbatim,singleline]
5056 #(define (reverse-music music)
5057 (let* ((elements (ly-get-mus-property music 'elements))
5058 (reversed (reverse elements))
5059 (span-dir (ly-get-mus-property music 'span-direction)))
5060 (ly-set-mus-property music 'elements reversed)
5062 (ly-set-mus-property music 'span-direction (- span-dir)))
5063 (map reverse-music reversed)
5066 music = \notes { c'4 d'4( e'4 f'4 }
5068 \score { \context Voice {
5070 \apply #reverse-music \music
5075 More examples are given in the distributed example files in
5078 @c . {Span requests}
5084 @subsubsection Span requests
5085 @cindex Span requests
5087 Notational constructs that start and end on different notes can be
5088 entered using span requests. The syntax is as follows:
5092 \spanrequest @var{startstop} @var{type}
5096 @cindex @code{\start}
5097 @cindex @code{\stop}
5099 This defines a spanning request. The @var{startstop} parameter is either
5100 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
5101 describes what should be started. Much of the syntactic sugar is a
5102 shorthand for @code{\spanrequest}, for example,
5104 @lilypond[fragment,verbatim,center]
5105 c'4-\spanrequest \start "slur"
5106 c'4-\spanrequest \stop "slur"
5109 Among the supported types are @code{crescendo}, @code{decrescendo},
5110 @code{beam}, @code{slur}. This is an internal command. Users are
5111 encouraged to use the shorthands which are defined in the initialization
5112 file @file{spanners.ly}.
5117 @subsection Assignments
5120 Identifiers allow objects to be assigned to names during the parse
5121 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
5122 and to refer to an identifier, you precede its name with a backslash:
5123 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
5124 the input-types listed above. Identifier assignments can appear at top
5125 level in the LilyPond file, but also in @code{\paper} blocks.
5127 An identifier can be created with any string for its name, but you will
5128 only be able to refer to identifiers whose names begin with a letter,
5129 being entirely alphabetical. It is impossible to refer to an identifier
5130 whose name is the same as the name of a keyword.
5132 The right hand side of an identifier assignment is parsed completely
5133 before the assignment is done, so it is allowed to redefine an
5134 identifier in terms of its old value, e.g.
5140 When an identifier is referenced, the information it points to is
5141 copied. For this reason, an identifier reference must always be the
5142 first item in a block.
5146 \paperIdent % wrong and invalid
5150 \paperIdent % correct
5155 @c . {Lexical modes}
5157 @subsection Lexical modes
5158 @cindex Lexical modes
5161 @cindex @code{\notes}
5162 @cindex @code{\chords}
5163 @cindex @code{\lyrics}
5165 To simplify entering notes, lyrics, and chords, LilyPond has three
5166 special input modes in addition to the default mode: note, lyrics and
5167 chords mode. These input modes change the way that normal, unquoted
5168 words are interpreted: for example, the word @code{cis} may be
5169 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
5170 major triad respectively.
5172 A mode switch is entered as a compound music expression
5174 @code{\notes} @var{musicexpr}
5175 @code{\chords} @var{musicexpr}
5176 @code{\lyrics} @var{musicexpr}.
5179 In each of these cases, these expressions do not add anything to the
5180 meaning of their arguments. They just instruct the parser in what mode
5181 to parse their arguments. The modes are treated in more detail in
5182 @ref{Lyrics} and @ref{Chords}.
5184 Different input modes may be nested.
5188 @subsection Ambiguities
5193 The grammar contains a number of ambiguities. We hope to resolve them at
5197 @item The assignment
5202 is interpreted as the string identifier assignment. However,
5203 it can also be interpreted as making a string identifier @code{\foo}
5204 containing @code{"bar"}, or a music identifier @code{\foo}
5205 containing the syllable `bar'.
5207 @item If you do a nested repeat like
5219 then it is ambiguous to which @code{\repeat} the
5220 @code{\alternative} belongs. This is the classic if-then-else
5221 dilemma. It may be solved by using braces.
5223 @item The parser is not sophisticated enough to distinguish at the
5225 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
5232 @c . {Lexical details}
5233 @node Lexical details
5234 @section Lexical details
5236 Even more boring details, now on lexical side of the input parser.
5247 * Version information::
5252 @subsection Comments
5255 @cindex block comment
5256 @cindex line comment
5260 A one line comment is introduced by a @code{%} character.
5261 Block comments are started by @code{%@{} and ended by @code{%@}}.
5262 They cannot be nested.
5265 @subsection Direct Scheme
5269 @cindex Scheme, in-line code
5272 LilyPond contains a Scheme interpreter (the GUILE library) for
5273 internal use. In some places, Scheme expressions also form valid syntax:
5274 wherever it is allowed,
5278 evaluates the specified Scheme code. Example:
5280 \property Staff.TestObject \override #'foobar = #(+ 1 2)
5282 @code{\override} expects two Scheme expressions, so there are two Scheme
5283 expressions. The first one is a symbol (@code{foobar}), the second one
5284 an integer (namely, 3).
5286 In-line scheme may be used at the top level. In this case the result is
5289 Scheme is a full-blown programming language, and a full discussion is
5290 outside the scope of this document. Interested readers are referred to
5291 the website @uref{http://www.schemers.org/} for more information on
5296 @subsection Keywords
5300 Keywords start with a backslash, followed by a number of lower case
5301 alphabetic characters. These are all the keywords.
5304 apply arpeggio autochange spanrequest commandspanrequest
5305 simultaneous sequential accepts alternative bar breathe
5306 char chordmodifiers chords clef cm consists consistsend
5307 context denies duration dynamicscript elementdescriptions
5308 font grace header in lyrics key mark pitch
5309 time times midi mm name pitchnames notes outputproperty
5310 override set revert partial paper penalty property pt
5311 relative remove repeat addlyrics partcombine score
5312 script stylesheet skip textscript tempo translator
5317 @subsection Integers
5325 Formed from an optional minus sign followed by digits. Arithmetic
5326 operations cannot be done with integers, and integers cannot be mixed
5331 @cindex real numbers
5337 Formed from an optional minus sign and a sequence of digits followed
5338 by a @emph{required} decimal point and an optional exponent such as
5339 @code{-1.2e3}. Reals can be built up using the usual operations:
5340 `@code{+}', `@code{-}', `@code{*}', and
5341 `@code{/}', with parentheses for grouping.
5349 A real constant can be followed by one of the dimension keywords:
5350 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5351 points, inches and centimeters, respectively. This converts the number
5352 a number that is the internal representation of that dimension.
5360 Begins and ends with the @code{"} character. To include a @code{"}
5361 character in a string write @code{\"}. Various other backslash
5362 sequences have special interpretations as in the C language. A string
5363 that contains no spaces can be written without the quotes. Strings can
5364 be concatenated with the @code{+} operator.
5368 @subsection Main input
5371 @cindex @code{\maininput}
5373 The @code{\maininput} command is used in init files to signal that the
5374 user file must be read. This command cannot be used in a user file.
5376 @node File inclusion
5377 @subsection File inclusion
5378 @cindex @code{\include}
5380 \include @var{filename}
5383 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5384 unquoted string will not work here!) or a string identifier. The full
5385 filename including the @file{.ly} extension must be given,
5388 @node Version information
5389 @subsection Version information
5390 @cindex @code{\version}
5392 \version @var{string}
5395 Specify the version of LilyPond that a file was written for. The
5396 argument is a version string in quotes, for example @code{"1.2.0"}.
5397 This is used to detect invalid input, and to aid
5398 @code{convert-ly} a tool that automatically upgrades input files. See
5399 See @ref{convert-ly} for more information on @code{convert-ly}.
5407 @c broken with emacs-21
5408 @c {Local emac s vars}
5409 @c Local varia bles:
5411 @c minor-mod e: font-lock
5412 @c minor-mo de: outline
5413 @c outline -layout: (-1 : 0)
5414 @c outlin e-use-mode-specific-leader: "@c \."
5415 @c outli ne-primary-bullet: "{"
5416 @c outli ne-stylish-prefixes: nil
5417 @c outli ne-override-protect: t