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
17 @c .{Reference Manual}
19 @node Reference Manual
20 @chapter Reference Manual
23 <!--- @@WEB-TITLE@@=Reference Manual --->
26 This document describes GNU LilyPond and its input format. The last
27 revision of this document was made for LilyPond 1.4.1. It supposes a
28 passing familiarity with how LilyPond input works. New users are
29 encouraged to study the tutorial first.
54 * Skipping corrected music::
55 * Interpretation context::
60 @c FIXME: Note entry vs Music entry at top level menu is confusing.
66 The most basic forms of music are notes. Notes on their own don't
67 form valid input, but for the sake of brevity we omit @code{\score}
68 blocks and @code{\paper} declarations.
74 * Chromatic alterations::
79 * Automatic note splitting ::
81 * Defining pitch names::
82 * Easy Notation note heads ::
90 A note is printed by specifying its pitch, and then its duration.
91 @lilypond[fragment,verbatim]
94 The grob for a note head is called @internalsref{NoteHead}.
101 @cindex Note specification
103 @cindex entering notes
105 The verbose syntax for pitch specification is
107 @cindex @code{\pitch}
109 \pitch @var{scmpitch}
112 @var{scmpitch} is a pitch scheme object.
114 In Note and Chord mode, pitches may be designated by names. The default
115 names are the Dutch note names. The notes are specified by the letters
116 @code{a} through @code{g} (where the octave is formed by notes ranging
117 from @code{c} to @code{b}). The pitch @code{c} is an octave below
118 middle C and the letters span the octave above that C.
120 @cindex note names, Dutch
122 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
123 name and a flat is formed by adding @code{-es}. Double sharps and double
124 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
125 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
126 both forms are accepted.
128 LilyPond has predefined sets of note names for various other languages.
129 To use them, simply include the language specific init file. For
130 example: @code{\include "english.ly"}. The available language files and
131 the names they define are:
134 Note Names sharp flat
135 nederlands.ly c d e f g a bes b -is -es
136 english.ly c d e f g a bf b -s/-sharp -f/-flat
137 deutsch.ly c d e f g a b h -is -es
138 norsk.ly c d e f g a b h -iss/-is -ess/-es
139 svenska.ly c d e f g a b h -iss -ess
140 italiano.ly do re mi fa sol la sib si -d -b
141 catalan.ly do re mi fa sol la sib si -d/-s -b
142 espanol.ly do re mi fa sol la sib si -s -b
151 The optional octave specification takes the form of a series of
152 single quote (`@code{'}') characters or a series of comma
153 (`@code{,}') characters. Each @code{'} raises the pitch by one
154 octave; each @code{,} lowers the pitch by an octave.
156 @lilypond[fragment,verbatim,center]
157 c' c'' es' g' as' gisis' ais'
160 @node Chromatic alterations
161 @subsection Chromatic alterations
163 Normally Accidentals signify that the pitch of a note differs from the
164 key signature. Normally, they are printed automatically depending, but
165 you may force accidentals in the following ways:
166 A reminder accidental
167 @cindex reminder accidental
169 can be forced by adding an exclamation mark @code{!} after the pitch. A
170 cautionary accidental,
171 @cindex cautionary accidental
172 @cindex parenthesized accidental
173 i.e., an accidental within parentheses can be obtained by adding the
174 question mark `@code{?}' after the pitch.
176 Each accidental symbol is an @internalsref{Accidental} grob. The
177 placement of accidentals is handled by
178 @internalsref{AccidentalPlacement}.
186 A rest is entered like a note, with note name `@code{r}':
188 @lilypond[singleline,verbatim]
192 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
193 specified using @code{R}, see @ref{Multi measure rests}.
195 For polyphonic music, it can be convenient to specify the rest position
196 directly. You can do that by entering a note, with the keyword
197 @code{\rest} appended, e.g. Rest collisions will leave these rests alone.
199 @lilypond[singleline,verbatim]
209 @cindex Invisible rest
212 An invisible rest, or skip, can be entered like a note with note name
213 @code{s}, or with @code{\skip @var{duration}}:
215 @lilypond[singleline,verbatim]
219 The @code{s} syntax is only available in Note mode and Chord mode.
220 In other situations, you should use the @code{\skip} command, and it is
221 only available in Note mode and Chord mode.
223 @c FIXME: in lyrics mode, we have " " and _
225 In Lyrics mode, you can use `@code{" "}' and `@code{_}':
226 @lilypond[singleline,verbatim]
228 \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
229 \notes\relative c'' { a2 a4 a a2 a4 a }
233 The unabbreviated `@code{\skip} @var{duration}' also works outside of
236 @lilypond[singleline,verbatim]
239 { \time 4/8 \skip 2 \time 4/4 }
240 \notes\relative c'' { a2 a1 }
245 The skip command is merely a empty musical placeholder. It does not
246 produce any output, not even transparent output.
251 @subsection Durations
255 @cindex @code{\duration}
257 The syntax for a verbose duration specification is
259 \duration @var{scmduration}
261 Here, @var{scmduration} is a Scheme object of type @code{Duration}.
264 In Note, Chord, and Lyrics mode, durations may be designated by numbers
265 and dots: durations are entered as their reciprocal values. For notes
266 longer than a whole you must use identifiers.
270 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
272 r1 r2 r4 r8 r16 r32 r64 r64
278 \notes \relative c'' {
280 a1 a2 a4 a8 a16 a32 a64 a64
282 r1 r2 r4 r8 r16 r32 r64 r64
287 \remove "Clef_engraver"
288 \remove "Staff_symbol_engraver"
289 \remove "Time_signature_engraver"
290 \consists "Pitch_squash_engraver"
297 If the duration is omitted then it is set to the previous duration
298 entered. At the start of parsing a quarter note is assumed. The
299 duration can be followed by dots (`@code{.}') to obtain dotted note
303 @lilypond[fragment,verbatim,center]
309 You can alter the length of duration by a fraction @var{N/M} by
310 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
311 will not affect the appearance of the notes or rests produced.
323 A tie connects two adjacent note heads of the same pitch. The tie in
324 effect extends the length of a note. A tie is entered with @code{~}.
326 @lilypond[fragment,verbatim,center]
327 e' ~ e' <c' e' g'> ~ <c' e' g'>
330 When ties are used with chords, all note heads whose pitches match are
331 connected. Ties are indicated using the tilde symbol `@code{~}'. If
332 you try to tie together chords which have no common pitches then no
333 ties will be created.
335 If you want less ties created for a chord, you can set
336 @code{Voice.sparseTies} to true. In this case, a single tie is used
337 for every tied chord.
338 @lilypond[fragment,verbatim,center]
339 \property Voice.sparseTies = ##t
340 <c' e' g'> ~ <c' e' g'>
343 In its meaning a tie is just a way of extending a note duration, similar
344 to the augmentation dot: the following example are two ways of notating
345 exactly the same concept.
347 @lilypond[fragment, singleline]
348 \time 3/4 c'2. c'2 ~ c'4
350 Ties should not be confused with slurs, which indicate articulation,
351 and phrasing slurs, which indicate musical phrasing.
353 The name of the tie grob is @internalsref{Tie}, and it is created in the
354 @internalsref{Voice} context.
358 At present, the tie is implemented as a separate thing, temporally
359 located in between the notes.
360 Tieing only a subset of the note heads of a chord is not supported in a
361 simple way. It can be achieved by moving the tie-engraver into the Thread
362 context and turning on and off ties per Thread.
364 @node Automatic note splitting
365 @subsection Automatic note splitting
367 There is a facility for automatically converting long notes to tied
368 notes. This is done by replacing the @code{Note_heads_engraver} by the
369 @code{Completion_heads_engraver}.
371 @lilypond[verbatim,center]
373 \notes\relative c'{ \time 2/4
374 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
378 \remove "Note_heads_engraver"
379 \consists "Completion_heads_engraver"
383 This engraver splits all running notes at the bar line, and inserts
384 ties. One of the uses of this is, is to debug complex scores: if the
385 measures are not entirely filled, then the ties exactly show how much
390 Not all durations (especially those containing tuplets) can be
391 represented exactly; the engraver will not insert tuplets.
398 @cindex @code{\times}
400 Tuplets are made out of a music expression by multiplying all duration
403 @cindex @code{\times}
405 \times @var{fraction} @var{musicexpr}
408 The duration of @var{musicexpr} will be multiplied by the fraction.
409 In print, the fraction's denominator will be printed over the notes,
410 optionally with a bracket. The most common tuplet is the triplet in
411 which 3 notes have the length of 2, so the notes are 2/3 of
412 their written length:
414 @lilypond[fragment,verbatim,center]
415 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
418 The property @code{tupletSpannerDuration} specifies how long each bracket
419 should last. With this, you can make lots of tuplets while typing
420 @code{\times} only once, thus saving typing work.
422 @lilypond[fragment, relative, singleline, verbatim]
423 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
424 \times 2/3 { c'8 c c c c c }
427 The format of the number is determined by the property
428 @code{tupletNumberFormatFunction}. The default prints only the
429 denominator, but if you set it to the Scheme function
430 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
435 The typesetting of brackets and numbers is controlled by the properties
436 @code{bracket-visibility} and @code{number-visibility}. These
437 properties can either be @code{#f}, @code{#t} or @code{'if-no-beam},
438 meaning respectively off, on, and on if there is no beam.
440 @lilypond[fragment, relative, singleline, verbatim]
441 \property Voice.TupletBracket \set #'bracket-visibility = ##t
442 \times 2/3{c'8 d e} \times 2/3{d4 e8}
443 \property Voice.TupletBracket \set #'bracket-visibility = #'if-no-beam
444 \times 2/3{c d e} \times 2/3{d4 e8}
445 \property Voice.TupletBracket \set #'bracket-visibility = ##f
446 \times 2/3{c d e} \times 2/3{d4 e8}
447 \property Voice.TupletBracket \set #'number-visibility = ##f
448 \times 2/3{c d e} \times 2/3{d4 e8}
449 \property Voice.TupletBracket \set #'number-visibility = #'if-no-beam
450 \times 2/3{c d e} \times 2/3{d4 e8}
453 @cindex @code{tupletNumberFormatFunction}
454 @cindex tuplet formatting
456 Tuplet brackets are printed as @internalsref{TupletBracket} grobs in
457 the @internalsref{Voice} context.
459 @c . {Defining pitch names}
460 @node Defining pitch names
461 @subsection Defining pitch names
463 @cindex defining pitch names
464 @cindex pitch names, defining
466 Note names and chord modifiers can be customized for nationalities. The
467 syntax is as follows.
469 @cindex @code{\pitchnames}
470 @cindex @code{\chordmodifiers}
472 \pitchnames @var{scheme-alist}
473 \chordmodifiers @var{scheme-alist}
476 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers-init.ly} for
477 specific examples on how to do this.
480 @node Easy Notation note heads
481 @subsection Easy Notation note heads
483 @cindex easy notation
486 A entirely different type of note head is the "easyplay" note head: a
487 note head that includes a note name. It is used in some publications by
488 Hal-Leonard Inc. music publishers.
490 @lilypond[singleline,verbatim]
491 \include "paper23.ly"
493 \notes { c'2 e'4 f' | g'1 }
494 \paper { \translator { \EasyNotation } }
498 Note that @internalsref{EasyNotation} overrides a @internalsref{Score} context. You
499 probably will want to print it with magnification to make it more
500 readable, see @ref{Output scaling}.
506 If you view the result with Xdvi, then staff lines will show through the
507 letters. Printing the postscript file obtained either by using dvips or
508 the @code{-f ps} option of lilypond produces the correct result.
513 @section Staff notation
515 @cindex Staff notation
527 @subsection Key signature
532 Setting or changing the key signature is done with the @code{\key}
535 @code{\key} @var{pitch} @var{type}
538 @cindex @code{\minor}
539 @cindex @code{\major}
540 @cindex @code{\minor}
541 @cindex @code{\ionian}
542 @cindex @code{\locrian}
543 @cindex @code{\aeolian}
544 @cindex @code{\mixolydian}
545 @cindex @code{\lydian}
546 @cindex @code{\phrygian}
547 @cindex @code{\dorian}
549 Here, @var{type} should be @code{\major} or @code{\minor} to get
550 @var{pitch}-major or @var{pitch}-minor, respectively.
551 The standard mode names @code{\ionian},
552 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
553 @code{\phrygian}, and @code{\dorian} are also defined.
555 This command sets the context property @code{Staff.keySignature}.
556 Non-standard key signatures can be specified by setting this property
559 The printed signature is a @internalsref{KeySignature} grob, typically
560 created in @internalsref{Staff} context.
562 @cindex @code{keySignature}
569 The clef can be set or changed with the @code{\clef} command:
570 @lilypond[fragment,verbatim]
571 \key f\major c''2 \clef alto g'2
574 Supported clef-names include
575 @c Moved standard clefs to the top /MB
577 @item treble, violin, G, G2
586 G clef on 1st line, so-called French violin clef
601 By adding @code{_8} or @code{^8} to the clef name, the clef is
602 transposed one octave down or up, respectively. Note that you have to
603 enclose @var{clefname} in quotes if you use underscores or digits in the
609 The grob for this symbol is @internalsref{Clef}.
612 The full syntax for this command is
616 where @var{clefname} is a string. This command is a shortcut for
618 \property Staff.clefGlyph = @var{glyph associated with clefname}
619 \property Staff.clefPosition = @var{clef Y-position for clefname}
620 \property Staff.centralCPosition = @var{position for central C}
621 \property Staff.clefOctavation = @var{extra transposition of clefname}
623 Upon any change in these properties lilypond creates a clef
624 symbol. The mapping from @var{clefname} to the property values can be
625 found in @file{scm/clef.scm}
631 @c . {Time signature}
633 @subsection Time signature
634 @cindex Time signature
638 The time signature is set or changed by the @code{\time}
640 @lilypond[fragment,verbatim]
641 \time 2/4 c'2 \time 3/4 c'2.
644 The actual symbol that's printed can be customized with the style
646 @lilypond[fragment, verbatim, singleline]
648 \property Staff.TimeSignature \override #'style = #'C
650 \property Staff.TimeSignature \override #'style = #'()
652 \property Staff.TimeSignature \override #'style = #'C
656 The grob for this symbol is @internalsref{TimeSignature}. There are
657 many more options for its layout. They are selected through the
658 @code{style} grob property. See @file{input/test/time.ly} for more
662 The full syntax for this command is
664 \time @var{n}@code{/}@var{d}
666 where @var{n} and @var{d} are integers. This command is internally
667 translated, to the following:
669 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
670 \property Score.beatLength = #(make-moment 1 @var{d})
671 \property Score.measureLength = #(make-moment @var{n} @var{d})
674 The property @code{timeSignatureFraction} determine where bar lines
675 should be inserted, and how automatic beams should be generated.
676 Changing the value of @code{timeSignatureFraction} also causes a
677 fraction to be printed.
684 @cindex partial measure
685 @cindex measure, partial
686 @cindex shorten measures
687 @cindex @code{\partial}
689 Partial measures, for example in upbeats, are entered using the
690 @code{\partial} command:
691 @lilypond[fragment,verbatim]
692 \partial 4* 5/16 c'16 c8. f16 a'2. ~ a'8. a'16 | g'1
695 The syntax for this command is
697 \partial @var{duration}
699 This is internally translated into
701 \property Score.measurePosition = -@var{length of duration}
704 The property @code{measurePosition} contains a rational number
705 indicating how much of the measure has passed at this point.
708 @node Unmetered music
709 @subsection Unmetered music
711 Bar lines and bar numbers are calculated automatically. For unmetered
712 music (e.g. cadenzas), this is not desirable. The property
713 @code{Score.timing} can be used to switch off this automatic timing
715 @lilypond[fragment,relative,singleline,verbatim]
717 \property Score.timing = ##f
719 \property Score.timing = ##t
723 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
730 @subsection Bar lines
734 @cindex measure lines
737 Bar lines are inserted automatically by, but if you need a special
738 types of barline, you can force one using the @code{\bar} command:
739 @lilypond[fragment,verbatim]
743 The following bar types are available
744 @lilypond[fragment, relative, singleline, verbatim]
756 You are encouraged to use @code{\repeat} for repetitions. See
759 In scores with many staffs, the barlines are automatically placed at
760 top level, and they are connected between different staffs of a
761 @internalsref{StaffGroup}:
762 @lilypond[fragment, verbatim]
763 < \context StaffGroup <
764 \context Staff = up { e'4 d'
767 \context Staff = down { \clef bass c4 g e g } >
768 \context Staff = pedal { \clef bass c2 c2 } >
771 The grobs that are created at @internalsref{Staff} level. The name is
772 @internalsref{BarLine}.
774 The full syntax for this command is
778 where @var{bartype} is a string. This is a shortcut for doing
780 \property Score.whichBar = @var{bartype}
784 @cindex Bar_line_engraver
786 @cindex repeatCommands
787 @cindex defaultBarType
789 Whenever @code{whichBar} is set to a string, a bar line of that type is
790 created. @code{whichBar} is usually set automatically: at the start of
791 a measure it is set to @code{defaultBarType}. The contents of
792 @code{repeatCommands} is used to override default measure bars.
794 @code{whichBar} can also be set directly, using @code{\property} or
795 @code{\bar }. These settings take precedence over the automatic
796 @code{whichBar} settings.
803 Polyphonic parts, i.e. parts with more than one voice on a staff can be
804 typeset with LilyPond.
806 The easiest way to enter such fragments, is the Scheme function
807 @code{voicify-music}. It will split chords using the separator
808 @code{\\}, to make multiple voices. You can use it for small,
809 short-lived voices (make a chord of voices) or for single chords:
811 @lilypond[verbatim,fragment]
812 \context Voice = VA \apply #voicify-music \relative c'' {
813 c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
817 The function @code{voicify-music} instantiates @internalsref{Voice}
818 contexts, bearing the names @code{"1"}, @code{"2"}, etc.
820 To explicity typeset polyphonic music, instantiate a separate Voice
821 context for each part, and use @code{\voiceOne}, up to
822 @code{\voiceFour} to assign a stem directions and horizontal shift for
826 @lilypond[singleline, verbatim]
828 \context Staff < \context Voice = VA { \voiceOne cis2 b }
829 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
830 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
833 The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
834 ties, slurs and stems, and set shift directions.
836 If you want more than four voices, you can also manually set
837 horizontal shifts and stem directions, as is shown in the following example:
838 @lilypond[fragment, verbatim]
839 \context Staff \notes\relative c''<
846 \context Voice=three {
847 \shiftOnn \stemUp ais
849 \context Voice=four {
850 \shiftOnnn \stemUp fis
856 Normally, note heads with a different number of dots are not merged, but
857 if you set the grob property @code{merge-differently-dotted}, they are:
858 @lilypond[verbatim,fragment,singleline]
859 \apply #voicify-music < {
861 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
863 } \\ { [g'8. f16] [g'8. f'16] }
867 Similarly, you can merge half note heads with eighth notes, by setting
868 @code{merge-differently-headed}:
869 @lilypond[fragment, relative=2,verbatim]
870 \apply #voicify-music < {
872 \property Staff.NoteCollision
873 \override #'merge-differently-headed = ##t
874 c8 c4. } \\ { c2 c2 } >
877 LilyPond also vertically shifts rests that are opposite of a stem.
879 @lilypond[singleline,fragment,verbatim]
880 \apply #voicify-music <
885 Note head collisions (horizontal shifting of note heads) are handled by
886 the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
887 handles vertical shifting of rests.
893 Resolving collisions is a very intricate subject, and LilyPond only
894 handles a few situations. When it can not cope, you are advised to use
895 @code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
896 rests to override typesetting decisions.
901 Beams are used to group short notes into chunks that are aligned with
902 the metrum. They are inserted automatically in most cases.
904 @lilypond[fragment,verbatim, relative=2]
905 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
908 If you're not satisfied with the automatic beaming, you can enter the
909 beams explicitly. If you have beaming patterns that differ from the
910 defaults, you can also set the patterns for automatic beamer.
912 The beam symbol is @internalsref{Beam} in @internalsref{Voice}
913 context, both for automatically created and manual beams.
916 @cindex Automatic beams
917 @subsection Manual beams
918 @cindex beams, manual
922 In some cases it may be necessary to override LilyPond's automatic
923 beaming algorithm. For example, the auto beamer will not beam over
924 rests or bar lines, If you want that, specify the begin and end point
925 manually using a @code{[} before the first beamed note and a @code{]}
928 @lilypond[fragment,relative,verbatim]
930 r4 [r8 g' a r8] r8 [g | a] r8
934 @cindex @code{stemLeftBeamCount}
936 Normally, beaming patterns within a beam are determined automatically.
937 When this mechanism fouls up, the properties
938 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
939 be used to control the beam subdivision on a stem. If you set either
940 property, it's value will be used only once, and then it is erased.
942 @lilypond[fragment,relative,verbatim]
945 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
948 @cindex @code{stemRightBeamCount}
951 TODO: FIXME, we don't want this doc here.
953 can be tweaked through
954 grob-property @code{positions}. The value is a pair.
955 specify vertical location of the left and right end point. Both are
956 measured in half staff-spaces, and the middle staff line is the value
959 @li lypond[fragment,relative,verbatim]
960 \property Voice.Beam \set #'position = #
961 \property Voice.Beam \set #'height = #0
965 Here's how you'd specify a weird looking beam that instead of being
966 horizontal, falls two staff spaces:
972 @li lypond[fragment,relative,verbatim]
973 \property Voice.Beam \set #'staff-position = #4
974 \property Voice.Beam \set #'height = #-4
981 Kneed beams are inserted automatically, when a large gap between two
982 adjacent beamed notes is detected. This behavior can be tuned through
983 the grob property @code{auto-knee-gap}.
987 @cindex auto-knee-gap
991 @c TODO -> why this ref? Document?
992 @cindex @code{neutral-direction}
996 Auto knee beams can not be used together with hara kiri staffs.
1000 * Setting automatic beam behavior ::
1003 @node Beam typography
1004 @subsection Beam typography
1006 One of the strong points of LilyPond is how beams are formatted. Beams
1007 are quantized, meaning that the left and right endpoints beams start
1008 exactly on staff lines. Without quantization, small wedges of white
1009 space appear between the beam and staff line, and this looks untidy.
1011 Beams are also slope-damped: melodies that go up or down should also
1012 have beams that go up or down, but the slope of the beams should be
1013 less than the slope of the notes themselves.
1015 Some beams should be horizontal. These are so-called concave beams.
1017 [TODO: some pictures.]
1020 @c . {Automatic beams}
1021 @node Setting automatic beam behavior
1022 @subsection Setting automatic beam behavior
1024 @cindex @code{autoBeamSettings}
1025 @cindex @code{(end * * * *)}
1026 @cindex @code{(begin * * * *)}
1027 @cindex automatic beams, tuning
1028 @cindex tuning automatic beaming
1030 In normal time signatures, automatic beams can start on any note but can
1031 only end in a few positions within the measure: beams can end on a beat,
1032 or at durations specified by the properties in
1033 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
1034 are defined in @file{scm/auto-beam.scm}.
1036 The value of @code{autoBeamSettings} is changed using
1037 @code{\override} and unset using @code{\revert}:
1039 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
1040 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
1042 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
1043 whether the rule applies to begin or end-points. The quantity
1044 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
1045 *}' designates notes of any length), @var{N}/@var{M} refers to a time
1046 signature (wildcards, `@code{* *}' may be entered to designate all time
1049 For example, if you want automatic beams to end on every quarter note,
1050 you can use the following:
1052 \property Voice.autoBeamSettings \override
1053 #'(end * * * *) = #(make-moment 1 4)
1055 Since the duration of a quarter note is 1/4 of a whole note, it is
1056 entered as @code{(make-moment 1 4)}.
1058 The same syntax can be used to specify beam starting points. In this
1059 example, automatic beams can only end on a dotted quarter note.
1061 \property Voice.autoBeamSettings \override
1062 #'(end * * * *) = #(make-moment 3 8)
1064 In 4/4 time signature, this means that automatic beams could end only on
1065 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1066 3/8 has passed within the measure).
1068 You can also restrict rules to specific time signatures. A rule that
1069 should only be applied in @var{N}/@var{M} time signature is formed by
1070 replacing the second asterisks by @var{N} and @var{M}. For example, a
1071 rule for 6/8 time exclusively looks like
1073 \property Voice.autoBeamSettings \override
1074 #'(begin * * 6 8) = ...
1077 If you want a rule to apply to certain types of beams, you can use the
1078 first pair of asterisks. Beams are classified according to the shortest
1079 note they contain. For a beam ending rule that only applies to beams
1080 with 32nd notes (and no shorter notes), you would use @code{(end 1
1084 @c Automatic beams can not be put on the last note in a score.
1086 If a score ends while an automatic beam has not been ended and is still
1087 accepting notes, this last beam will not be typeset at all.
1089 @cindex automatic beam generation
1091 @cindex @code{Voice.autoBeaming}
1094 For melodies that have lyrics, you may want to switch off
1095 automatic beaming. This is done by setting @code{Voice.autoBeaming} to
1101 It is not possible to specify beaming parameters for beams with mixed
1102 durations, that differ from the beaming parameters of all separate
1103 durations, i.e., you'll have to specify manual beams to get:
1104 @lilypond[fragment,singleline,relative]
1105 \property Voice.autoBeamSettings
1106 \override #'(end * * * *) = #(make-moment 3 8)
1107 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
1110 It is not possible to specify beaming parameters that act differently in
1111 different parts of a measure. This means that it is not possible to use
1112 automatic beaming in irregular meters such as @code{5/8}.
1115 @node Expressive marks
1116 @section Expressive marks
1131 A slur indicates that notes are to be played bound or @emph{legato}.
1132 They are entered using parentheses:
1133 @lilypond[fragment,verbatim,center]
1134 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1137 The grob for this object is @internalsref{Slur}, generally in
1138 @internalsref{Voice} context.
1140 Slurs avoid crossing stems, and are generally attached to note heads.
1141 However, in some situations with beams, slurs may be attached to stem
1142 ends. If you want to override this layout you can do this through the
1143 grob-property @code{attachment} of @internalsref{Slur} in
1144 @internalsref{Voice} context It's value is a pair of symbols, specifying
1145 the attachment type of the left and right end points.
1147 @lilypond[fragment,relative,verbatim]
1149 \property Voice.Stem \set #'length = #5.5
1151 \property Voice.Slur \set #'attachment = #'(stem . stem)
1155 If a slur would strike through a stem or beam, the slur will be moved
1156 away upward or downward. If this happens, attaching the slur to the
1157 stems might look better:
1159 @lilypond[fragment,relative,verbatim]
1162 \property Voice.Slur \set #'attachment = #'(stem . stem)
1167 Similarly, the curvature of a slur is adjusted to stay clear of note
1168 heads and stems. When that would increase the curvature too much, the
1169 slur is reverted to its default shape. The threshold for this decision
1170 is in @internalsref{Slur}'s grob-property @code{beautiful}. It is loosely
1171 related to the enclosed area between the slur and the notes. Usually,
1172 the default setting works well, but in some cases you may prefer a
1173 curved slur when LilyPond decides for a vertically moved one. You can
1174 indicate this preference by increasing the @code{beautiful} value:
1176 @lilypond[verbatim,singleline,relative]
1178 c16( a' f' a a f a, )c,
1179 c( a' f' a a f d, )c
1180 \property Voice.Slur \override #'beautiful = #5.0
1181 c( a' f' a a f d, )c
1186 Producing nice slurs is a difficult problem, and LilyPond currently
1187 uses a simple, empiric method to produce slurs. In some cases, the
1188 results of this method don't look too good. This is reflected by the
1189 @code{beautiful} property, which it is an arbitrary parameter in the
1190 slur formatter. Useful values can only be determined by trial and
1193 @cindex Adjusting slurs
1195 @node Phrasing slurs
1196 @subsection Phrasing slurs
1198 @cindex phrasing slurs
1199 @cindex phrasing marks
1201 A phrasing slur (or phrasing mark) connects chords and is used to
1202 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1205 @lilypond[fragment,verbatim,center,relative]
1206 \time 6/4 c' \( ( d ) e f ( e ) \) d
1209 Typographically, the phrasing slur behaves almost exactly like a normal
1210 slur. The grob associated with it is @internalsref{PhrasingSlur}, in
1211 @internalsref{Voice} context.
1214 @subsection Breath marks
1216 Breath marks are entered using @code{\breathe}. The result is a
1217 @internalsref{BreathingSign} grob in @internalsref{Voice} context.
1219 @lilypond[fragment,relative]
1228 @cindex beats per minute
1229 @cindex metronome marking
1231 Metronome settings can be entered as follows:
1233 @cindex @code{\tempo}
1235 \tempo @var{duration} = @var{perminute}
1238 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1243 The tempo setting is not printed, but is only used in the MIDI
1244 output. You can trick lily into producing a metronome mark,
1245 though. Details are in @ref{Text markup}.
1250 @subsection Text spanners
1251 @cindex Text spanners
1253 Some textual indications, e.g. rallentando or accelerando, often extend
1254 over many measures. This is indicated by following the text with a
1255 dotted line. You can create such texts using text spanners. The syntax
1258 \spanrequest \start "text"
1259 \spanrequest \stop "text"
1261 LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
1262 in @internalsref{Voice} context). The string to be printed, as well as the
1263 style is set through grob properties.
1265 An application---or rather, a hack---is to fake octavation indications.
1266 @lilypond[fragment,relative,verbatim]
1267 \relative c' { a''' b c a
1268 \property Voice.TextSpanner \set #'type = #'dotted-line
1269 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1270 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1271 \property Staff.centralCPosition = #-13
1272 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1291 @subsection Articulations
1292 @cindex Articulations
1294 @cindex articulations
1298 A variety of symbols can appear above and below notes to indicate
1299 different characteristics of the performance. They are added to a note
1300 by adding @code{-}@var{script}
1301 @lilypond[singleline]
1303 \notes \context Voice {
1304 \property Voice.TextScript \set #'font-family = #'typewriter
1305 \property Voice.TextScript \set #'font-shape = #'upright
1311 c''4-^_"c-\\^{ }" s4
1316 The script is automatically placed, but if you need to force
1317 directions, you can use @code{_} to force them down, or @code{^} to
1319 @lilypond[fragment, verbatim]
1324 Other symbols can be added using the syntax
1325 @var{note}@code{-\}@var{name}. Again, they can be forced up or down
1326 using @code{^} and @code{_}.
1330 \property Score.LyricSyllable \override #'font-family =#'typewriter
1331 \property Score.LyricSyllable \override #'font-shape = #'upright
1332 \context Staff \notes {
1333 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1334 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1335 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1336 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1337 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1338 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1339 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1340 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1342 \context Lyrics \lyrics {
1343 accent__ marcato__ staccatissimo__ fermata
1344 stopped__ staccato__ tenuto__ upbow
1345 downbow__ lheel__ rheel__ ltoe
1346 rtoe__ turn__ open__ flageolet
1347 reverseturn__ trill__ prall__ mordent
1348 prallprall__ prallmordent__ uprall__ downprall
1349 upmordent__ downmordent__ pralldown__ prallup__
1350 lineprall__ thumb__ segno__ coda
1354 linewidth = 5.875\in
1363 Fingering instructions can also be entered in this shorthand. For
1364 finger changes, use markup texts:
1366 @lilypond[verbatim, singleline, fragment]
1367 c'4-1 c'4-2 c'4-3 c'4-4
1372 @cindex @code{\script}
1377 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
1381 All of these note ornaments appear in the printed output but have no
1382 effect on the MIDI rendering of the music.
1384 Unfortunately, there is no support for adding fingering instructions or
1385 ornaments to individual note heads. Some hacks exist, though. See
1386 @file{input/test/script-horizontal.ly}.
1391 @subsection Text scripts
1392 @cindex Text scripts
1394 In addition, it is possible to place arbitrary strings of text or markup
1395 text (see @ref{Text markup}) above or below notes by using a string:
1398 By default, these indications do not influence the note spacing, but
1399 by using the command @code{\fatText}, the widths will be taken into
1402 @lilypond[fragment,singleline,verbatim] \relative c' {
1403 c4^"longtext" \fatText c4_"longlongtext" c4 }
1406 Text scripts are created in form of @internalsref{TextScript} grobs, in
1407 @internalsref{Voice} context.
1409 @ref{Text markup} describes how to change the font or access
1410 special symbols in text scripts.
1413 @node Adding scripts
1414 @subsection Adding scripts
1416 TODO: should junk this subsect?
1418 You can add scripts by editing @file{scm/script.scm} and
1419 @file{ly/script-init.ly}. This file contains a table, listing script
1420 definitions and aliases. The following syntax accesses a script
1421 definition from the table:
1427 Usually the @code{\script} keyword is not used directly. Various
1428 helpful identifier definitions appear in @file{script.ly}.
1433 @subsection Grace notes
1437 @cindex @code{\grace}
1441 Grace notes are ornaments are written out ornaments
1442 @lilypond[relative=2,fragment]
1443 c4 \grace c16 c4 \grace { [c16 d16] } c4
1446 In normal notation, grace notes are supposed to take up no logical
1447 time in a measure. Such an idea is practical for normal notation, but
1448 is not strict enough to put it into a program. The model that LilyPond
1449 uses for grace notes internally is that all timing is done in two
1452 Every point in musical time consists of two rational numbers: one
1453 denotes the logical time, one denotes the grace timing. The above
1454 example is shown here with timing tuples.
1456 @lilypond[relative=2,fragment]
1457 c4^"(0,0)" \grace c16^"(1/4,-1/16)" c4^"(1/4,0)" \grace {
1458 [c16^"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4^"(2/4,0)"
1461 The advantage of this approach is that you can use almost any lilypond
1462 construction together with grace notes, for example slurs and clef
1463 changes may appear halfway in between grace notes:
1465 @lilypond[relative=2,fragment]
1466 c4 \grace { [ c16 c, \clef bass c, b(] } )c4
1469 The placement of these grace notes is synchronized between different
1470 staffs, using this grace timing.
1472 @lilypond[relative=2,fragment]
1473 \context Staff = SA { e4 \grace { c16 d e f } e4 }
1474 \context Staff = SB { c4 \grace { g8 b } c4 }
1478 The syntax is as follows.
1480 \grace @var{musicexpr}
1483 Unbeamed eighth notes and shorter by default have a slash through the
1486 @lilypond[fragment,verbatim]
1487 \relative c'' \context Voice {
1488 \grace c8 c4 \grace { [c16 c16] } c4
1490 \property Voice.Stem \override #'flag-style = #'()
1492 \property Voice.Stem \revert #'flag-style
1497 A grace note expression has duration 0; the next real note is assumed to
1498 be the main note. If you want the note to appear after the main note,
1499 set @code{Voice.graceAlignPosition} to @code{1}.
1504 Grace note synchronization can also lead to surprises. Staff notation,
1505 such as key signatures, barlines, etc. are also synchronized. Take
1506 care when you mix staffs with grace notes and staffs without.
1508 @lilypond[relative=2,fragment]
1509 \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
1510 \context Staff = SB { c4 \bar "|:" d4 }
1513 Nesting @code{\grace} notes is not supported. The following may cause
1517 @code{\grace @{ \grace c32 c16 @} c4}
1519 Since the meaning of such a construct is unclear, we don't consider this
1520 a loss. Similarly, juxtaposing two @code{\grace} sections is
1521 syntactically valid, but makes no sense and may cause runtime errors.
1522 Ending a staff or score with grace notes may also generate a run-time
1523 error, since there will be no main note to attach the grace notes to.
1534 @subsection Glissando
1537 @cindex @code{\glissando}
1539 A glissando line (grob @internalsref{Glissando}) can be requested by
1540 attaching a @code{\glissando} to a notte:
1542 @lilypond[fragment,relative,verbatim]
1548 Printing of an additional text (such as @emph{gliss.}) must be done
1555 @subsection Dynamics
1568 @cindex @code{\ffff}
1578 Absolute dynamic marks are specified using an identifier after a
1579 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1580 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1581 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1582 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1584 @lilypond[verbatim,singleline,fragment,relative]
1585 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1591 @cindex @code{\decr}
1592 @cindex @code{\rced}
1598 A crescendo mark is started with @code{\cr} and terminated with
1599 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1600 started with @code{\decr} and terminated with @code{\rced}. There are
1601 also shorthands for these marks. A crescendo can be started with
1602 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1603 can be terminated with @code{\!}. Note that @code{\!} must go before
1604 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1605 after the last note. Because these marks are bound to notes, if you
1606 want several marks during one note, you have to use spacer notes.
1608 @lilypond[fragment,verbatim,center]
1609 c'' \< \! c'' d'' \decr e'' \rced
1610 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1613 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1614 is an example how to do it:
1619 @lilypond[fragment,relative,verbatim]
1621 \property Voice.crescendoText = "cresc."
1622 \property Voice.crescendoSpanner = #'dashed-line
1627 For everyday use, we recommend the identifiers @code{\cresc},
1628 @code{endcresc}, @code{\dim} and @code{\enddim}.
1632 Dynamics are grobs of @internalsref{DynamicText} and
1633 @internalsref{Hairpin}. Vertical positioning of these symbols is
1634 handled by the @internalsref{DynamicLineSpanner} grob. If you want to
1635 adjust padding or vertical direction of the dynamics, you must set
1636 properties for the @internalsref{DynamicLineSpanner} grob. Predefined
1637 identifiers to set the vertical direction are \dynamicUp and
1640 @cindex direction, of dynamics
1641 @cindex @code{\dynamicDown}
1642 @cindex @code{\dynamicUp}
1650 @cindex @code{\repeat}
1652 To specify repeats, use the @code{\repeat} keyword. Since repeats
1653 should work differently when played or printed, there are a few
1654 different variants of repeats.
1658 Repeated music is fully written (played) out. Useful for MIDI
1659 output, and entering repetitive music.
1662 This is the normal notation: Repeats are not written out, but
1663 alternative endings (voltas) are printed, left to right.
1666 Alternative endings are written stacked. This has limited use but may be
1667 used to typeset two lines of lyrics in songs with repeats, see
1668 @file{input/star-spangled-banner.ly}.
1674 Make beat or measure repeats. These look like percent signs.
1680 * Repeats and MIDI::
1681 * Manual repeat commands::
1683 * Tremolo subdivisions::
1688 @subsection Repeat syntax
1690 The syntax for repeats is
1693 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1696 If you have alternative endings, you may add
1697 @cindex @code{\alternative}
1699 \alternative @code{@{} @var{alternative1}
1701 @var{alternative3} @dots{} @code{@}}
1703 where each @var{alternative} is a music expression.
1705 Normal notation repeats are used like this:
1706 @lilypond[fragment,verbatim]
1708 \repeat volta 2 { c'4 d' e' f' }
1709 \repeat volta 2 { f' e' d' c' }
1712 With alternative endings:
1713 @lilypond[fragment,verbatim]
1715 \repeat volta 2 {c'4 d' e' f'}
1716 \alternative { {d'2 d'} {f' f} }
1719 Folded repeats look like this:
1722 @lilypond[fragment,verbatim]
1724 \repeat fold 2 {c'4 d' e' f'}
1725 \alternative { {d'2 d'} {f' f} }
1729 If you don't give enough alternatives for all of the repeats, then
1730 the first alternative is assumed to be repeated often enough to equal
1731 the specified number of repeats.
1733 @lilypond[fragment,verbatim]
1737 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1738 \alternative { { g4 g g } { a | a a a a | b2. } }
1743 @node Repeats and MIDI
1744 @subsection Repeats and MIDI
1746 @cindex expanding repeats
1748 For instructions on how to unfoldi repeats for MIDI output, see
1749 the example file @file{input/test/unfold-all-repeats.ly}.
1754 Notice that timing information is not remembered at the start of an
1755 alternative, so you have to reset timing information after a repeat,
1756 e.g. using a bar-check (See @ref{Bar check}), setting
1757 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1758 are also not repeated.
1760 It is possible to nest @code{\repeat}s, although this probably is only
1761 meaningful for unfolded repeats.
1763 Folded repeats offer little more over simultaneous music. However, it
1764 is to be expected that more functionality -- especially for the MIDI
1765 backend -- will be implemented at some point in the future.
1767 Volta repeats are printed over all staves in a score. You must turn them
1768 off explicitly, for example by doing
1770 \property Staff.VoltaBracket = \turnOff
1772 in all but the top staff.
1774 @node Manual repeat commands
1775 @subsection Manual repeat commands
1777 @cindex @code{repeatCommands}
1779 The property @code{repeatCommands} can be used to control the layout of
1780 repeats. Its value is a Scheme list of repeat commands, where each repeat
1788 @item (volta . @var{text})
1789 Print a volta bracket saying @var{text}.
1791 Stop a running volta bracket
1794 @lilypond[verbatim, fragment]
1796 \property Score.repeatCommands = #'((volta "93") end-repeat)
1798 \property Score.repeatCommands = #'((volta #f))
1803 Repeats brackets are @internalsref{VoltaBracket} grobs.
1805 @node Tremolo repeats
1806 @subsection Tremolo repeats
1807 @cindex tremolo beams
1809 To place tremolo marks between notes, use @code{\repeat} with tremolo
1811 @lilypond[verbatim,center,singleline]
1813 \context Voice \notes\relative c' {
1814 \repeat "tremolo" 8 { c16 d16 }
1815 \repeat "tremolo" 4 { c16 d16 }
1816 \repeat "tremolo" 2 { c16 d16 }
1817 \repeat "tremolo" 4 c16
1822 Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
1823 @internalsref{StemTremolo}.
1828 At present, the spacing between tremolo beams is not regular, since the
1829 spacing engine does not notice that not all notes are printed.
1831 @node Tremolo subdivisions
1832 @subsection Tremolo subdivisions
1833 @cindex tremolo marks
1834 @cindex @code{tremoloFlags}
1836 Tremolo marks can be printed on a single note by adding
1837 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1838 A @var{length} value of 8 gives one line across the note stem. If the
1839 length is omitted, then then the last value (stored in
1840 @code{Voice.tremoloFlags}) is used.
1842 @lilypond[verbatim,fragment,center]
1843 c'2:8 c':32 | c': c': |
1849 Tremolos in this style do not carry over into the MIDI output.
1852 @node Measure repeats
1853 @subsection Measure repeats
1855 @cindex percent repeats
1856 @cindex measure repeats
1858 In the @code{percent} style, a note pattern can be repeated. It is
1859 printed once, and then the pattern is replaced with a special sign.
1860 Patterns of a one and two measures are replaced by percent-like signs,
1861 patterns that divide the measure length are replaced by slashes.
1863 @lilypond[verbatim,singleline]
1864 \context Voice { \repeat "percent" 4 { c'4 }
1865 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1869 The signs are represented by these grobs: @internalsref{RepeatSlash} and
1870 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
1874 You can not nest percent repeats, e.g. by filling in the first measure
1875 with slashes, and repeating that measure with percents.
1877 @node Rhythmic music
1878 @section Rhythmic music
1885 @node Rhythmic staves
1886 @subsection Rhythmic staves
1888 Sometimes you might want to show only the rhythm of a melody. This can
1889 be done with the rhythmic staff. All pitches of notes on such a staff
1890 are squashed, and the staff itself looks has a single staff line:
1892 @lilypond[fragment,relative,verbatim]
1893 \context RhythmicStaff {
1895 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1902 @section Piano music
1904 Piano music is an odd type of notation. Piano staves are two normal
1905 staves coupled with a brace. The staves are largely independent, but
1906 sometimes voices can cross between the two staves. The
1907 @internalsref{PianoStaff} is especially built to handle this cross-staffing
1908 behavior. In this section we discuss the @internalsref{PianoStaff} and some
1909 other pianistic peculiarities.
1912 * Automatic staff changes::
1913 * Manual staff switches::
1916 * Voice follower lines::
1920 @c . {Automatic staff changes}
1921 @node Automatic staff changes
1922 @subsection Automatic staff changes
1923 @cindex Automatic staff changes
1925 Voices can switch automatically between the top and the bottom
1926 staff. The syntax for this is
1928 \autochange @var{contexttype} \context @var{childcontexttype}
1932 This will switch the interpretation context of @var{musicexp} between
1933 a @var{contexttype} named @code{up} and @code{down}. Typically, you
1934 use @internalsref{Staff} for @var{contexttype}, and
1935 @internalsref{Voice} for @var{childcontexttype}. The autochanger
1936 switches on basis of pitch (central C is the turning point), and it
1937 looks ahead skipping over rests to switch rests in advance.
1939 @lilypond[verbatim,singleline]
1940 \score { \notes \context PianoStaff <
1941 \context Staff = "up" {
1942 \autochange Staff \context Voice = VA < \relative c' {
1943 g4 a b c d r4 a g } > }
1944 \context Staff = "down" {
1950 Note how spacer rests are used to prevent the bottom staff from
1951 terminating too soon.
1954 @node Manual staff switches
1955 @subsection Manual staff switches
1957 @cindex manual staff switches
1958 @cindex staff switch, manual
1960 Voices can be switched between staves manually, using the following command:
1962 \translator Staff = @var{staffname} @var{music}
1964 The string @var{staffname} is the name of the staff. It switches the
1965 current voice from its current staff to the Staff called
1966 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1969 The formal definition of this construct is obtuse, but for the sake of
1970 completeness we give it here.
1971 @cindex @code{\translator}
1973 \translator @var{contexttype} = @var{name}
1975 Formally, this construct is a music expression indicating
1976 that the context which is a direct child of the context of type
1977 @var{contexttype} should be shifted to a context of type
1978 @var{contexttype} and the specified name.
1986 Piano pedal instruction can be expressed using
1987 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
1988 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1990 These identifiers are shorthands for spanner commands of the types
1991 @internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
1993 @lilypond[fragment,verbatim]
1994 c''4 \spanrequest \start "Sustain" c''4
1995 c''4 \spanrequest \stop "Sustain"
1998 The symbols that are printed can be modified by setting
1999 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
2000 Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
2001 @rgrob{SustainPedal}, for example, for more information.
2003 Pedals can also be indicated by a sequence of brackets, by setting the
2004 @code{pedal-type} property of SustainPedal grobs:
2006 @lilypond[fragment,verbatim]
2007 \property Staff.SustainPedal \override #'pedal-type = #'bracket
2008 c''4 \sustainDown d''4 e''4 a'4
2009 \sustainUp \sustainDown
2010 f'4 g'4 a'4 \sustainUp
2013 A third style of pedal notation is a mixture of text and brackets,
2014 obtained by setting @code{pedal-type} to @code{mixed}:
2016 @lilypond[fragment,verbatim]
2017 \property Staff.SustainPedal \override #'pedal-type = #'mixed
2018 c''4 \sustainDown d''4 e''4 c'4
2019 \sustainUp \sustainDown
2020 f'4 g'4 a'4 \sustainUp
2023 The default '*Ped' style for sustain and damper pedals corresponds to
2024 @code{\pedal-type = #'text}. However, @code{mixed} is the default style
2025 for a sostenuto pedal:
2027 @lilypond[fragment,verbatim]
2028 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2031 For fine-tuning of the appearance of a pedal bracket, the properties
2032 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
2033 @code{PianoPedalBracket} grobs (see the detailed documentation of
2034 @rgrob{PianoPedalBracket}) can be modified. For example, the bracket
2035 may be extended to the end of the note head.
2037 @lilypond[fragment,verbatim]
2038 \property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0)
2039 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2046 @subsection Arpeggio
2049 @cindex broken arpeggio
2050 @cindex @code{\arpeggio}
2052 You can specify an arpeggio sign on a chord by attaching an
2053 @code{\arpeggio} to a note of the chord.
2056 @lilypond[fragment,relative,verbatim]
2057 \context Voice <c\arpeggio e g c>
2060 When an arpeggio crosses staves in piano music, you attach an arpeggio
2061 to the chords in both staves, and set
2062 @code{PianoStaff.connectArpeggios}.
2064 @lilypond[fragment,relative,verbatim]
2065 \context PianoStaff <
2066 \property PianoStaff.connectArpeggios = ##t
2067 \context Voice = one { <c'\arpeggio e g c> }
2068 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2072 This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
2073 are @code{PianoStaff.Arpeggio}.
2075 To add an arrow head to explicitly specify the direction of the
2076 arpeggio, you should set the arpeggio grob property
2077 @code{arpeggio-type}.
2079 @lilypond[fragment,relative,verbatim]
2081 \property Voice.Arpeggio \override #'arpeggio-direction = #1
2083 \property Voice.Arpeggio \override #'arpeggio-direction = #-1
2088 A square bracket on the left indicates that the player should not
2089 arpeggiate the chord. To draw these brackets, set the
2090 @code{molecule-callback} property of @code{Arpeggio} or
2091 @code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
2092 @code{\arpeggio} statements within the chords as before.
2094 @lilypond[fragment,relative,verbatim]
2095 \context PianoStaff <
2096 \property PianoStaff.connectArpeggios = ##t
2097 \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket
2098 \context Voice = one { <c'\arpeggio e g c> }
2099 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2106 It is not possible to mix connected arpeggios and unconnected arpeggios
2111 @node Voice follower lines
2112 @subsection Voice follower lines
2114 @cindex follow voice
2115 @cindex staff switching
2118 @cindex @code{followVoice}
2120 Whenever a voice switches to another staff a line connecting the notes
2121 can be printed automatically. This is enabled if the property
2122 @code{PianoStaff.followVoice} is set to true:
2124 @lilypond[fragment,relative,verbatim]
2125 \context PianoStaff <
2126 \property PianoStaff.followVoice = ##t
2127 \context Staff \context Voice {
2129 \translator Staff=two
2132 \context Staff=two {\clef bass \skip 1*2 }
2136 The associated grob is @internalsref{VoiceFollower}.
2143 * Tablatures basic::
2144 * Non-guitar tablatures::
2145 * Tablature in addition to normal staff::
2148 @node Tablatures basic
2149 @subsection Tablatures basic
2150 @cindex Tablatures basic
2152 Tablature can be typeset with Lilypond by using the
2153 @internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
2154 tablatures is a recent feature in Lilypond, most of the guitar special
2155 effects (hammer, pull, bend, ...) are not yet supported.
2157 With the @internalsref{TabStaff}, the string number associated to a note
2158 is given though the fingering mechanism, e.g. @code{c4-3} for a C
2159 quarter on the third string. The string 1 is the lowest one, and the
2160 tuning defaults to the standard guitar tuning (with 6 strings).
2162 @lilypond[fragment,verbatim]
2165 \property Staff.Stem \override #'direction = #1
2174 @node Non-guitar tablatures
2175 @subsection Non-guitar tablatures
2176 @cindex Non-guitar tablatures
2178 There are many ways to customize Lilypond tablatures.
2180 First you can change the number of string, e.g.
2181 @code{StaffSymbol \override #'line-count = #5} to have only 5 strings.
2182 Because of a kind of bug in Lilypond, you MUST create a new type of
2183 context if you want different tablatures with diiferent number of
2186 Then you can change the strings tuning. String tuning is given as a
2187 Scheme list with one integer number for each string, the number being
2188 the string note pitch if not fretted (open note).
2190 Finally, it is possible to change the Scheme function to format the
2191 tablature note text. The default is @var{fret-number-tablature-format},
2192 which uses the fret number, but for some instruments that may not use
2193 this notation, just create your own tablature-format function. This
2194 function takes three argument: the string number, the string tuning and
2198 @node Tablature in addition to normal staff
2199 @subsection Tablature in addition to normal staff
2200 @cindex Tablature in addition to normal staff
2202 It is possible to typeset both tablature and a "normal" staff, as
2203 commonly done in many parts.
2205 A common trick for that is to put the notes in a variables, and to hide
2206 the fingering information (which correspond to the string number) for
2215 \context StaffGroup <
2217 % Hide fingering number (used for string number) for the "normal" staff
2218 \property Staff.Fingering \override #'transparent = ##t
2223 \property Staff.Stem \override #'direction = #1
2240 * Automatic syllable durations::
2246 @subsection Lyrics mode
2249 To print lyrics, you must first make a music expression from the lyric
2250 text. That music expression can be printed by selecting an appropriate
2254 @cindex @code{\lyrics}
2256 You can enter lyrics in a special input mode of LilyPond. This mode is
2257 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
2258 The purpose of this mode is that you can enter lyrics as plain text,
2259 punctuation and accents without any hassle.
2261 Syllables are entered like notes, with pitches replaced by text. For
2262 example, @code{Twin- kle twin- kle} enters four syllables. Note that
2263 the hyphen has no special meaning for lyrics, and does not introduce
2266 Spaces can be introduced into a lyric either by using quotes:
2267 @code{"He could"4 not4} or by using an underscore without quotes:
2268 @code{He_could4 not4}. All unquoted underscores are converted to
2271 The precise definition of this mode can be found in @ref{Lyrics mode
2274 @c . {Printing lyrics}
2275 @node Printing lyrics
2276 @subsection Printing lyrics
2279 Lyrics are printed by interpreting them in the @internalsref{Lyrics} context.
2281 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
2282 @c Add tied and beamed melismata too.
2283 @lilypond[verbatim,singleline]
2285 \notes \relative c' {
2287 \property Staff.automaticMelismata = ##t
2288 d'2 c4 b16 ( a g a b a b ) c a2
2289 b2 c4 b8 ( a16 g ) a4 g2 }
2290 \context Lyrics \lyrics {
2292 share the soft -- ware; }
2296 Notes and syllable durations are matched automatically. This is
2297 accomplished using @code{\addlyrics}, which is documented in
2298 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
2299 the melody staff will cause tied, slurred or beamed notes to be
2300 interpreted as melismata.
2302 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
2305 @cindex lyric extender
2308 As you can see, extender lines are entered as @code{__}. This will
2309 create an extender, a line that extends over the entire duration of the
2310 lyric. This line will run all the way to the start of the next lyric,
2311 so you may want to shorten it by using a blank lyric (using @code{_}).
2312 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2317 If you want to have hyphens centered between syllables (rather than
2318 attached to the end of the first syllable) you can use the special
2319 `@code{-}@code{-}' lyric as a separate word between syllables. This
2320 will result in a hyphen whose length varies depending on the space
2321 between syllables. It will be centered between the syllables. The grob
2322 for this symbol is @code{LyricsVoice.LyricHyphen}.
2324 @cindex Lyric hyphen
2326 @node Automatic syllable durations
2327 @subsection Automatic syllable durations
2328 @cindex Automatic syllable durations
2330 @cindex automatic lyric durations
2331 @cindex @code{\addlyrics}
2333 If you have lyrics that are set to a melody, you can copy the rhythm
2334 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2337 \addlyrics @var{musicexpr1 musicexpr2}
2340 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2341 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2342 when there are events in @var{musicexpr1}.
2344 @cindex @code{automaticMelismata}
2346 If the property @code{automaticMelismata} is set in the
2347 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2350 @lilypond[verbatim,fragment]
2353 \property Voice.automaticMelismata = ##t
2354 c8 () cis d8. e16 f2
2356 \context Lyrics \lyrics {
2360 If you want the lyric lines to be above the melody staff, or in some
2361 other, more complex configuration, then build that configuration first
2362 using simultaneous music, and use @code{\addlyrics} after that.
2364 @lilypond[verbatim, singleline]
2366 \context Lyrics = LA { s1 }
2367 \context Staff = SA { s1 }
2369 \context Staff = SA \relative c' { c4 e g g }
2370 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2373 For @code{\addlyrics} you should use a single rhythm melody, and single
2374 rhythm lyrics (a constant duration is the obvious choice). If you do
2375 not, you can get undesired effects when using multiple stanzas:
2377 @lilypond[verbatim,fragment]
2380 c8 () cis d8. e16 f2
2382 \context Lyrics \lyrics
2387 It is valid (but probably not very useful) to use notes instead of
2388 lyrics for @var{musicexpr2}.
2391 @subsection More stanzas
2395 If you have multiple stanzas printed underneath each other, the vertical
2396 groups of syllables should be aligned around punctuation. LilyPond can
2397 do this if you tell it which lyric lines belong to which melody.
2399 To this end, give the Voice context an identity, and set the LyricsVoice
2400 to a name starting with that identity followed by a dash.
2401 In the following example, the Voice
2402 identity is @code{duet}, and the identities of the LyricsVoices are
2403 @code{duet-1} and @code{duet-2}.
2406 @lilypond[singleline,verbatim]
2409 \notes \relative c'' \context Voice = duet { \time 3/4
2411 \lyrics \context Lyrics <
2412 \context LyricsVoice = "duet-1" {
2413 \property LyricsVoice . stanza = "Bert"
2414 Hi, my name is bert. }
2415 \context LyricsVoice = "duet-2" {
2416 \property LyricsVoice . stanza = "Ernie"
2417 Ooooo, ch\'e -- ri, je t'aime. }
2422 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2423 first system) and @code{LyricsVoice.stz} for the following
2424 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2430 @cindex stanza numbering
2438 LilyPond has support for both entering and printing chords.
2439 @lilypond[verbatim,singleline]
2440 twoWays = \notes \transpose c'' {
2450 < \context ChordNames \twoWays
2451 \context Voice \twoWays > }
2454 This example also shows that the chord printing routines do not try to
2455 be intelligent. If you enter @code{f bes d}, it does not interpret
2456 this as an inversion.
2458 As you can see chords really are a set of pitches. They are internally
2459 stored as simultaneous music expressions. This means you can enter
2460 chords by name and print them as notes, enter them as notes and print
2461 them as chord names, or (the most common case) enter them by name, and
2466 * Printing named chords::
2471 @subsection Chords mode
2474 Chord mode is a mode where you can input sets of pitches using common
2475 names. It is introduced by the keyword @code{\chords}. It is similar
2476 to note mode, but words are also looked up in a chord modifier table
2477 (containing @code{maj}, @code{dim}, etc). Dashes and carets are used
2478 to indicate chord additions and subtractions, so articulation scripts
2479 can not be entered in Chord mode.
2481 Throughout these examples, chords have been shifted around the staff
2482 using @code{\transpose}.
2484 @lilypond[fragment,verbatim]
2488 c:9 c:9-.5+.7+ c:3-.5-
2498 The second type of modifier that may appear after the @code{:} is a
2499 named modifier. Named modifiers are listed in the file
2500 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2501 @code{min} which lower the 3rd half a step, `@code{aug}' which
2502 raises the 5th, `@code{dim}' which lowers the 5th,
2503 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2504 which replaces the 5th with a 4th.
2506 @lilypond[fragment,verbatim]
2509 c1:m c:min7 c:maj c:aug c:dim c:sus
2515 Chord subtractions are used to eliminate notes from a chord. The
2516 notes to be subtracted are listed after a @code{^} character,
2519 @lilypond[fragment,verbatim,center]
2528 Chord inversions can be specified by appending `@code{/}' and the name
2529 of a single note to a chord. In a chord inversion, the inverted note is
2530 transposed down until it is the lowest note in the chord. If the note
2531 is not in the chord, a warning will be printed.
2533 @lilypond[fragment,verbatim,center]
2543 Bass notes can be added by `@code{/+}' and
2544 the name of a single note to a chord. This has the effect of
2545 adding the specified note to the chord, lowered by an octave,
2546 so it becomes the lowest note in the chord.
2548 @lilypond[fragment,verbatim,center]
2557 The formal syntax for named chords is as follows:
2559 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2562 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2563 the chord duration in the usual notation. There are two kinds of
2564 modifiers. One type is formed by @emph{chord additions}. Additions are
2565 obtained by listing intervals separated by dots. An interval is written
2566 by its number with an optional @code{+} or @code{-} to indicate raising
2567 or lowering by half a step. Chord additions have two effects: they adds
2568 the specified interval and all lower odd numbered intervals to the
2569 chord, and they may lower or raise the specified interval.
2574 Implementation details are gory. For example @code{c:4} not only adds
2575 a fourth, but also removes the third.
2578 @c . {Printing named chords}
2579 @node Printing named chords
2580 @subsection Printing named chords
2582 @cindex printing chord names
2586 For displaying printed chord names, use the @internalsref{ChordNames} context.
2587 The chords may be entered either using the notation described above, or
2588 directly using simultaneous music.
2590 @lilypond[verbatim,singleline]
2592 \chords {a1 b c} <d f g> <e g b>
2596 \context ChordNames \scheme
2597 \context Staff \transpose c'' \scheme
2602 You can make the chord changes stand out by setting
2603 @code{ChordNames.chordChanges} to true. This will only display chord
2604 names when there's a change in the chords scheme and at the start of a
2609 c1:m c:m \break c:m c:m d
2613 \context ChordNames {
2614 \property ChordNames.chordChanges = ##t
2616 \context Staff \transpose c'' \scheme
2618 \paper{linewidth= 9.\cm}
2622 LilyPond examines chords specified as lists of notes to determine a name
2623 to give the chord. LilyPond will not try to identify chord inversions or
2624 an added bass note, which may result in strange chord names when chords
2625 are entered as a list of pitches:
2627 @lilypond[verbatim,center,singleline]
2636 \context ChordNames \scheme
2637 \context Staff \scheme
2643 By default, a chord name system proposed by Harald Banter (See
2644 @ref{Literature}) is used. The system is very regular and predictable.
2645 Typical American style chord names may be selected by setting the
2646 @code{style} property of the @code{ChordNames.ChordName} grob to
2647 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2649 Routines that determine the names to be printed are written in Scheme,
2650 and may be customized by the user. The code can be found in
2651 @file{scm/chord-name.scm}. Here's an example showing the differences in
2655 @c maybe just junk verbatim option?
2656 @lilypond[verbatim,singleline]
2666 \context ChordNames = banter \scheme
2667 \context ChordNames = american {
2668 \property ChordNames.ChordName \override
2669 #'style = #'american \scheme }
2670 \context ChordNames = jazz {
2671 \property ChordNames.ChordName \override
2672 #'style = #'jazz \scheme }
2673 \context Staff \transpose c'' \scheme
2680 @section Writing parts
2682 Orchestral music involves some special notation, both in the full score,
2683 as in the individual parts. This section explains how to tackle common
2684 problems in orchestral music.
2691 * Instrument names::
2693 * Sound output for transposing instruments::
2694 * Multi measure rests::
2695 * Automatic part combining::
2696 * Hara kiri staves::
2699 @c . {Rehearsal marks}
2700 @node Rehearsal marks
2701 @subsection Rehearsal marks
2702 @cindex Rehearsal marks
2704 @cindex @code{\mark}
2706 To print a rehearsal mark, use the @code{\mark} command.
2707 @lilypond[fragment,verbatim]
2714 c1 \mark #'(music "scripts-segno")
2719 As you can see, the mark is incremented automatically if you use
2720 @code{\mark \default}. The value to use is stored in the property
2721 @code{rehearsalMark} is used and automatically incremented. The grob
2722 is @internalsref{RehearsalMark} in @internalsref{Score} context. See
2723 @code{input/test/boxed-molecule.ly} if you need boxes around the
2727 @subsection Bar numbers
2731 @cindex measure numbers
2732 @cindex currentBarNumber
2734 They are printed at the
2735 start of the line. The number itself is a property that can be set by
2736 modifying the @code{currentBarNumber} property, i.e.
2738 \property Score.currentBarNumber = #217
2741 If you want boxed bar numbers, see the example file
2742 @code{input/test/boxed-molecule.ly}.
2744 Bar numbers are @internalsref{BarNumber} grobs.
2748 It is not possible to have bar numbers printed at regular intervals
2751 Barnumbers can collide with the StaffGroup, if there is one at the
2752 top. To solve this, You have to twiddle with the
2753 @internalsref{padding} property of @internalsref{BarNumber} if your
2754 score starts with a @internalsref{StaffGroup}.
2756 @node Instrument names
2757 @subsection Instrument names
2759 In scores, the instrument name is printed before the staff. This can
2760 be done by setting @code{Staff.instrument} and
2761 @code{Staff.instr}. This will print a string before the start of the
2762 staff. For the first start, @code{instrument} is used, for the next
2763 ones @code{instr} is used.
2765 @lilypond[verbatim,singleline]
2766 \property Staff.instrument = "ploink " { c''4 }
2769 You can also use markup texts to construct more complicated instrument
2773 @lilypond[verbatim,singleline]
2775 '((font-relative-size . -2 ) (music "accidentals--1")))
2778 \property Staff.instrument = #`((kern . 0.5) (lines
2779 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2787 When you put a name on a grand staff or piano staff the width of the
2788 brace is not taken into account. You must add extra spaces to the end of
2789 the name to avoid a collision.
2792 @subsection Transpose
2794 @cindex transposition of pitches
2795 @cindex @code{\transpose}
2797 A music expression can be transposed with @code{\transpose}. The syntax
2800 \transpose @var{pitch} @var{musicexpr}
2803 This means that middle C in @var{musicexpr} is transposed to
2806 @code{\transpose} distinguishes between enharmonic pitches: both
2807 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2808 a tone. The first version will print sharps and the second version
2811 @lilypond[singleline, verbatim]
2812 mus =\notes { \key e \major c d e f }
2813 \score { \notes \context Staff {
2816 \transpose des'' \mus
2817 \transpose cis'' \mus
2821 If you want to use both @code{\transpose} and @code{\relative}, then
2822 you must use @code{\transpose} first. @code{\relative} will have no
2823 effect music that appears inside a @code{\transpose}.
2825 @c . {Multi measure rests}
2826 @node Multi measure rests
2827 @subsection Multi measure rests
2828 @cindex Multi measure rests
2832 Multi measure rests are entered using `@code{R}'. It is specifically
2833 meant for full bar rests and for entering parts: the rest can expand to
2835 rests, or it can be printed as a single multimeasure rest This expansion
2836 is controlled by the property @code{Score.skipBars}. If this is set to true,
2837 Lily will not expand empty measures, and the appropriate number is added
2840 @lilypond[fragment,verbatim]
2841 \time 3/4 r2. | R2. | R2.*2
2842 \property Score.skipBars = ##t R2.*17 R2.*4
2845 Notice that the @code{R2.} is printed as a whole rest, centered in the
2848 @cindex whole rests for a full measure
2850 The grob for this object is @internalsref{MultiMeasureRest}.
2854 Currently, there is no way to automatically condense multiple rests
2855 into a single multimeasure rest. Multi measure rests do not take part
2858 @cindex condensing rests
2860 @node Automatic part combining
2861 @subsection Automatic part combining
2862 @cindex automatic part combining
2863 @cindex part combiner
2866 Automatic part combining is used to merge two parts of music onto a
2867 staff in an intelligent way. It is aimed primarily at typesetting
2868 orchestral scores. When the two parts are identical for a period of
2869 time, only one is shown. In places where the two parts differ, they
2870 are typeset as separate voices, and stem directions are set
2871 automatically. Also, solo and @emph{a due} parts can be identified
2874 The syntax for part combining is
2877 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2879 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2880 combined into one context of type @var{context}. The music expressions
2881 must be interpreted by contexts whose names should start with @code{one}
2884 The most useful function of the part combiner is to combine parts into
2885 one voice, as common for wind parts in orchestral scores:
2887 @lilypond[verbatim,singleline,fragment]
2889 \context Voice=one \partcombine Voice
2890 \context Thread=one \relative c'' {
2893 \context Thread=two \relative c'' {
2899 Notice that the first @code{g} appears only once, although it was
2900 specified twice (once in each part). Stem, slur and tie directions are
2901 set automatically, depending whether there is a solo or unisono. The
2902 first part (with context called @code{one}) always gets up stems, and
2903 `solo', while the second (called @code{two}) always gets down stems and
2906 If you just want the merging parts, and not the textual markings, you
2907 may set the property @var{soloADue} to false.
2909 @lilypond[verbatim,singleline,fragment]
2911 \property Staff.soloADue = ##f
2912 \context Voice=one \partcombine Voice
2913 \context Thread=one \relative c'' {
2916 \context Thread=two \relative c'' {
2922 There are a number of other properties that you can use to tweak the
2923 behavior of part combining, refer to the automatically generated
2924 documentation of @reng{Thread_devnull_engraver} and
2925 @reng{Voice_devnull_engraver}. Look at the documentation of the
2926 responsible engravers, @code{Thread_devnull_engraver},
2927 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2931 In @code{soloADue} mode, when the two voices play the same notes on and
2932 off, the part combiner may typeset @code{a2} more than once in a
2935 @lilypond[fragment,singleline]
2937 \context Voice=one \partcombine Voice
2938 \context Thread=one \relative c'' {
2941 \context Thread=two \relative c'' {
2947 @cindex @code{Thread_devnull_engraver}
2948 @cindex @code{Voice_engraver}
2949 @cindex @code{A2_engraver}
2951 @node Hara kiri staves
2952 @subsection Hara kiri staves
2954 In orchestral scores, staff lines that only have rests are usually removed.
2955 This saves some space. LilyPond also supports this through the hara
2956 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2957 the Japanese Samourai warriors.} staff. This staff commits suicide when
2958 it finds itself to be empty after the line-breaking process. It will
2959 not disappear when it contains normal rests, you must use multi measure
2962 The hara kiri staff is specialized version of the @internalsref{Staff}
2963 context. It is available as the context identifier
2964 @code{\HaraKiriStaffContext}. Observe how the second staff in this
2965 example disappears in the second line.
2969 \notes \relative c' <
2970 \context Staff = SA { e4 f g a \break c1 }
2971 \context Staff = SB { c4 d e f \break R1 }
2975 \translator { \HaraKiriStaffContext }
2981 @node Sound output for transposing instruments
2982 @subsection Sound output for transposing instruments
2984 When you want to make a MIDI file from a score containing transposed
2985 and untransposed instruments, you have to instruct LilyPond the pitch
2986 offset (in semitones) for the transposed instruments. This is done
2987 using the @code{transposing} property. It does not affect printed
2990 @cindex @code{transposing}
2993 \property Staff.instrument = #"Cl. in B-flat"
2994 \property Staff.transposing = #-2
3000 @node Ancient notation
3001 @section Ancient notation
3004 * Ancient note heads::
3009 @node Ancient note heads
3010 @subsection Ancient note heads
3012 To get a longa note head, you have to use mensural note heads. This
3013 is accomplished by setting the @code{style} property of the
3014 NoteHead grob to @code{mensural}. There is also a note head style
3015 @code{baroque} which gives mensural note heads for @code{\longa} and
3016 @code{\breve} but standard note heads for shorter notes.
3018 @lilypond[fragment,singleline,verbatim]
3019 \property Voice.NoteHead \set #'style = #'mensural
3020 \property Voice.NoteHead \set #'font-family = #'ancient
3025 @subsection Custodes
3030 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
3031 staff context symbol that appears at the end of a staff line. It
3032 anticipates the pitch of the first note(s) of the following line and
3033 thus helps the player or singer to manage line breaks during
3034 performance, thus enhancing readability of a score.
3039 \property Staff.Custos \set #'style = #'mensural
3044 \consists Custos_engraver
3050 Custodes were frequently used in music notation until the 17th century.
3051 There were different appearances for different notation styles.
3052 Nowadays, they have survived only in special forms of musical notation
3053 such as via the @emph{editio vaticana} dating back to the beginning of
3056 For typesetting custodes, just put a @code{Custos_engraver} into the
3057 @internalsref{Staff} context when declaring the @code{\paper} block. In this
3058 block, you can also globally control the appearance of the custos symbol
3059 by setting the custos @code{style} property. Currently supported styles
3060 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
3067 \consists Custos_engraver
3068 Custos \override #'style = #'mensural
3073 The property can also be set locally, for example in a @code{\notes}
3078 \property Staff.Custos \override #'style = #'vaticana
3079 c'1 d' e' d' \break c' d' e' d'
3084 @section Ancient clefs
3086 LilyPond supports a variety of clefs, many of them ancient. These can
3087 be selected from the @code{ancient} font family, by setting
3088 @code{Staff.clefGlyph}) to the following values
3097 @item clefs-vaticana_do
3098 Editio Vaticana style do clef
3099 @item clefs-vaticana_fa
3100 Editio Vaticana style fa clef
3101 @item clefs-medicaea_do
3102 Editio Medicaea style do clef
3103 @item clefs-medicaea_fa
3104 Editio Medicaea style fa clef
3105 @item clefs-mensural1_c
3106 modern style mensural C clef
3107 @item clefs-mensural2_c
3108 historic style small mensural C clef
3109 @item clefs-mensural3_c
3110 historic style big mensural C clef
3111 @item clefs-mensural1_f
3112 historic style traditional mensural F clef
3113 @item clefs-mensural2_f
3114 historic style new mensural F clef
3115 @item clefs-mensural_g
3116 historic style mensural G clef
3117 @item clefs-hufnagel_do
3118 historic style hufnagel do clef
3119 @item clefs-hufnagel_fa
3120 historic style hufnagel fa clef
3121 @item clefs-hufnagel_do_fa
3122 historic style hufnagel combined do/fa clef
3123 @item clefs-percussion
3124 modern style percussion clef
3127 @emph{Modern style} means ``as is typeset in current editions.''
3128 @emph{Historic style} means ``as was typeset or written in contemporary
3129 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
3132 @cindex Vaticana, Editio
3133 @cindex Medicaea, Editio
3134 @cindex hufnagel clefs
3140 @section Figured bass
3142 @cindex Basso continuo
3144 LilyPond has limited support for figured bass:
3146 @lilypond[verbatim,fragment]
3148 \context FiguredBass
3153 \context Voice { c4 g8 }
3157 The support for figured bass consists of two parts: there is an input
3158 mode, introduced by @code{\figures}, where you can enter bass figures
3159 as numbers, and there is a context called @internalsref{FiguredBass}
3160 that takes care of making @internalsref{BassFigure} grobs.
3162 In figures input mode, a group of bass figures is delimited by
3163 @code{<} and @code{>}. The duration is entered after the @code{>}.
3165 \context FiguredBass
3172 Accidentals are added to the numbers if you alterate them by
3173 appending @code{-}, @code{!} and @code{+}.
3176 \context FiguredBass
3177 \figures { <4- 6+ 7!> }
3183 Spaces or dashes may be inserted by using @code{_}. Brackets are
3184 introduced with @code{[} and @code{]}.
3187 \context FiguredBass
3188 \figures { < [4 6] 8 [_ 12]> }
3194 Although the support for figured bass may superficially resemble chord
3195 support, it works much simpler: in figured bass simply stores the
3196 numbers, and then prints the numbers you entered. There is no
3197 conversion to pitches, and no realizations of the bass are played in
3201 @c . {Tuning output}
3203 @section Tuning output
3205 LilyPond tries to take as much formatting as possible out of your
3206 hands. Nevertheless, there are situations where it needs some help, or
3207 where you want to override its decisions. In this section we discuss
3208 ways to do just that.
3210 Formatting is internally done by manipulating so called grobs (graphic
3211 objects). Each grob carries with it a set of properties (grob
3212 properties) specific to that object. For example, a stem grob has
3213 properties that specify its direction, length and thickness.
3215 The most direct way of tuning the output is by altering the values of
3216 these properties. There are two ways of doing that: first, you can
3217 temporarily change the definition of a certain type of grob, thus
3218 affecting a whole set of objects. Second, you can select one specific
3219 object, and set a grob property in that object.
3222 * Tuning groups of grobs ::
3223 * Tuning per grob ::
3232 @node Tuning groups of grobs
3233 @subsection Tuning groups of grobs
3235 @cindex grob description
3239 A grob definition is a Scheme association list, that is stored in a
3240 context property. By assigning to that property (using plain
3241 @code{\property}), you can change the resulting grobs.
3243 @lilypond[verbatim, fragment]
3244 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
3247 The @code{\property} assignment effectively empties the definition of
3248 the Stem object. One of the effects is that the recipe of how it should be
3249 printed is erased, with the effect of rendering it invisible. The above
3250 assignment is available as a standard identifier, for the case that you
3254 \property Voice.Stem = \turnOff
3261 This mechanism is fairly crude, since you can only set, but not modify,
3262 the definition of a grob. For this reason, there is a more advanced
3265 The definition of a grob is actually a list of default grob
3266 properties. For example, the definition of the Stem grob (available in
3267 @file{scm/grob-description.scm}), defines the following values for
3272 (beamed-lengths . (0.0 2.5 2.0 1.5))
3273 (Y-extent-callback . ,Stem::height)
3277 You can add a property on top of the existing definition, or remove a
3278 property, thus overriding the system defaults:
3280 c'4 \property Voice.Stem \override #'thickness = #4.0
3281 c'4 \property Voice.Stem \revert #'thickness
3284 You should balance @code{\override} and @code{\revert}. If that's too
3285 much work, you can use the @code{\set} shorthand. It performs a revert
3286 followed by an override. The following example gives exactly the same
3287 result as the previous one.
3289 c'4 \property Voice.Stem \set #'thickness = #4.0
3290 c'4 \property Voice.Stem \set #'thickness = #0.8
3293 If you use @code{\set}, you must explicitly restore the default.
3296 Formally the syntax for these constructions is
3298 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
3299 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
3300 \property @var{context}.@var{grobname} \revert @var{symbol}
3302 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
3303 and @var{grobname} are strings and @var{value} is a Scheme expression.
3306 If you revert a setting which was not set in the first place, then it
3307 has no effect. However, if the setting was set as a system default, it
3308 may remove the default value, and this may give surprising results,
3309 including crashes. In other words, @code{\override} and @code{\revert},
3310 must be carefully balanced.
3312 These are examples of correct nesting of @code{\override}, @code{\set},
3315 A clumsy but correct form:
3317 \override \revert \override \revert \override \revert
3320 Shorter version of the same:
3322 \override \set \set \revert
3325 A short form, using only @code{\set}. This requires you to know the
3328 \set \set \set \set @var{to default value}
3331 If there is no default (i.e. by default, the grob property is unset),
3334 \set \set \set \revert
3337 For the digirati, the grob description is an Scheme association
3338 list. Since a Scheme list is a singly linked list, we can treat it as a
3339 stack, and @code{\override} and @code{\revert} are just push and pop
3340 operations. This pushing and popping is also used for overriding
3341 automatic beaming settings.
3345 LilyPond will hang or crash if @var{value} contains cyclic references.
3346 The backend is not very strict in type-checking grob properties. If you
3347 @code{\revert} properties that are expected to be set by default,
3351 @cindex adjusting staff symbol
3352 @cindex StaffSymbol, using \property
3353 @cindex staff lines, setting number of
3355 Some grobs are created at the moment that their context is created. An
3356 example of such a grob is the staff itself (i.e. the horizontal lines).
3357 You can not change the appearance of the staff symbol by manipulating
3358 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3359 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3360 created before any @code{\override} is effective. You can deal with this
3361 either overriding properties in a @code{\translator} definition, or by
3362 using @code{\outputproperty}.
3367 @node Tuning per grob
3368 @subsection Tuning per grob
3370 @cindex \outputproperty
3372 A second way of tuning grobs is the more arcane @code{\outputproperty}
3373 feature. The syntax is as follows:
3375 \outputproperty @var{predicate} @var{symbol} = @var{value}
3377 Here @code{predicate} is a Scheme function taking a grob argument, and
3378 returning a boolean. This statement is processed by the
3379 @code{Output_property_engraver}. It instructs the engraver to feed all
3380 grobs that it sees to @var{predicate}. Whenever the predicate returns
3381 true, the grob property @var{symbol} will be set to @var{value}.
3383 You will need to combine this statement with @code{\context} to select
3384 the appropriate context to apply this to.
3386 Here are some random examples.
3389 In the following example, all note heads occurring at current staff
3390 level, are shifted up and right by setting their @code{extra-offset}
3393 @lilypond[fragment,verbatim,singleline]
3395 \context Staff \outputproperty
3396 #(make-type-checker 'note-head-interface)
3397 #'extra-offset = #'(0.5 . 0.75)
3401 @cindex @code{extra-offset}
3403 In this example, the predicate checks the @code{text} grob property, to
3404 shift only the `m.d.' text, but not the fingering instruction "2".
3405 @lilypond[verbatim,singleline]
3406 #(define (make-text-checker text)
3407 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3410 \notes\relative c''' {
3411 \property Voice.Stem \set #'direction = #1
3412 \outputproperty #(make-text-checker "m.d.")
3413 #'extra-offset = #'(-3.5 . -4.5)
3421 If possible, avoid this feature: the semantics are not very clean, and
3422 the syntax and semantics are up for rewrite.
3427 @node Font selection
3428 @subsection Font selection
3430 Most graphics in LilyPond are composed of characters of fonts. You can
3431 alter the characteristics of the font by setting certain grob
3432 properties. The mechanism that is used for this resembles La@TeX{}'s New
3433 Font Selection Scheme. Within this scheme, a font is entirely
3434 characterized by its font name.
3436 For each grob that uses fonts (in other words, each grob that supports
3437 @code{font-interface}) a font-name must be selected before it can be
3438 printed. The font name is selected by looking at a number of grob
3443 A symbol indicating the general class of the typeface. Supported are
3444 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3445 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3446 signs) and @code{typewriter}
3449 A symbol indicating the shape of the font, there are typically several
3450 font shapes available for each font family. Choices are @code{italic},
3451 @code{caps} and @code{upright}
3454 A symbol indicating the series of the font. There are typically several
3455 font series for each font family and shape. Choices are @code{medium}
3458 @item font-relative-size
3459 A number indicating the size relative the standard size. For example,
3460 with 20pt staff height, relative size -1 corresponds to 16pt staff
3461 height, and relative size +1 corresponds to 23 pt staff height.
3463 @item font-design-size
3464 A number indicating the design size of the font.
3466 This is a feature of the Computer Modern Font: each point size has a
3467 slightly different design. Smaller design sizes are relatively wider,
3468 which enhances readability. Scalable type faces such TrueType and Adobe
3469 Type1 usually come as ``one design fits all sizes''.
3472 The name of the font, without the design size, e.g. @code{cmr},
3473 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3480 The font is selected by taking the first font that satisfies all
3481 qualifiers specified. You can override any of these fields through
3482 @code{\override} and @code{\revert}. The special value @code{*} matches
3483 any value for that qualifier.
3486 \property Lyrics.LyricText \override #'font-series = #'bold
3487 \property Lyrics.LyricText \override #'font-shape = #'*
3490 @cindex @code{font-style}
3492 There are also pre-cooked font selection qualifiers. These are selected
3493 through the grob property @code{font-style}. For example, the style
3494 @code{finger} selects family @code{number} and relative size @code{-3}.
3495 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3496 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3499 The style sheets and tables for selecting fonts are located in
3500 @file{scm/font.scm}. Refer to this file for more information.
3503 Setting @code{font-name} overrides all other qualifiers. The value for
3504 this property should be a string, the file name of the font. You may use
3505 this to use special fonts, which are not a part of the style sheet, or
3506 which have special encodings.
3508 The size of the font may be set with the grob property
3509 @code{font-magnification}. It is the size of font, relative to its
3510 standard size. For example, @code{1.0} is normal size.
3514 Relative size is not linked to any real size.
3516 There is no style sheet provided for other fonts besides the @TeX{}
3519 @cindex font selection
3520 @cindex font magnification
3521 @cindex @code{font-interface}
3525 @subsection Text markup
3529 LilyPond has an internal mechanism to typeset texts. You can
3530 form text markup expressions by composing scheme expressions
3531 in the following way.
3533 @lilypond[verbatim, singleline]
3538 c^#'(italic "italic")
3539 d_#'((bold italic) "ff")
3541 f_#'(lines "one" (bold "two"))
3542 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3546 Normally, the Scheme markup text is stored in the @code{text} property
3547 of a grob. Formally, it is defined as follows:
3550 text: string | (head? text+)
3551 head: markup | (markup+)
3552 markup-item: property | abbrev
3553 property: (@var{key} . @var{value})
3554 abbrev: @code{columns lines roman music bold italic named super sub}
3555 @code{overstrike text finger volta timesig mmrest mark script}
3556 @code{large Large dynamic}
3559 The markup is broken down and converted into a list of grob properties,
3560 which are prepended to the property list. The @var{key}-@var{value}
3561 pair is a grob property. A list of properties available is included in
3562 the generated documentation for @rint{Text_interface}.
3564 The following abbreviations are currently defined:
3567 horizontal mode: set all text on one line (default)
3569 vertical mode: set every text on a new line
3573 selects the Feta font (the standard font for music notation glyphs),
3574 and uses named lookup
3581 lookup by character name
3583 plain text lookup (by character value)
3589 the next text or character overstrikes this one
3591 select fingering number fontstyle
3593 select volta number fontstyle
3595 select time signature number fontstyle
3597 select multi measure rest number fontstyle
3599 select mark number fontstyle
3601 select scriptsize roman fontstyle
3603 select large roman fontstyle
3605 select Large roman fontstyle
3607 select dynamics fontstyle
3611 @cindex metronome mark
3613 One practical application of complicated markup is to fake a metronome
3617 #(define note '(columns
3618 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3619 #(define eight-note `(columns ,note ((kern . -0.1)
3620 (music ((raise . 3.5) "flags-u3")))))
3621 #(define dotted-eight-note
3622 `(columns ,eight-note (music "dots-dot")))
3625 \notes\relative c'' {
3626 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3632 TextScript \override #'font-shape = #'upright
3638 @node Invisible grobs
3639 @subsection Invisible grobs
3640 @cindex invisible grobs
3644 ben nog steeds niet kapot van de informatiedichtheid hier.
3650 You can imagine a number of situations where you would want to make
3651 certain grobs not show up in the output. There may be aesthetic
3652 reasons, to make the output resemble an (old) manuscript as close as
3653 possible, or to make lessons or exercises for students.
3655 Grobs can be made invisible in a number of ways:
3657 Here's an example with blanked-out notes and stems:
3658 @lilypond[singleline,verbatim]
3660 \property Voice.NoteHead \override
3662 \property Voice.Stem \override
3663 #'transparent = ##t }
3666 \property Voice.NoteHead \revert #'transparent
3667 \property Voice.Stem \revert #'transparent }
3670 \notes\relative c'' {
3672 a b c b \blanknotes c \unblanknotes d
3676 This method makes the grobs invisible but they still take the normal space.
3677 To remove all traces of the grob, you can redefine the function
3681 \notes\relative c'' {
3684 as bes c bes c d \break
3685 \property Staff.KeySignature \override #'molecule-callback = #'()
3688 \paper{linewidth=5.0\cm indent=0}
3692 A very rigorous way of removing grobs from the whole score is to remove
3693 the engraver that creates them. For example,
3695 @lilypond[singleline,verbatim]
3696 \score {\notes { c'4 d'8 e'8 g2 }
3697 \paper { \translator {
3699 \remove Stem_engraver
3705 @subsection Dirty tricks
3706 @cindex embedded tex
3708 It is possible to use @TeX{} commands in the strings, but this should be
3709 avoided because it makes it impossible for LilyPond to compute the
3710 exact length of the string, which may lead to collisions. Also, @TeX{}
3711 commands won't work with direct PostScript output (see @ref{PostScript
3714 @lilypond[fragment,relative,verbatim]
3715 a'^"3 $\\times$ \\`a deux"
3718 You can also use raw PostScript commands embedded in text scripts. This
3719 offers ultimate flexibility, but requires you to learn PostScript.
3720 Currently, embedded PostScript will @strong{not} work with direct
3721 PostScript output. Note that all dimensions that you use are in staff
3726 \notes \relative c'' {
3727 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3728 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3729 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3733 \paper { linewidth = 70*\staffspace }
3740 TODO: Move this section.
3746 Generating optically pleasing spacing is black magic. LilyPond tries
3747 to deal with a number of frequent cases. Here is an example that is
3748 not handled correctly, due to the combination of chord collisions and
3753 \context PianoStaff \notes \transpose c''' <
3754 \context Staff = up { s1 }
3755 \context Staff = down { [c8 c \translator Staff=up <c d> c
3756 \translator Staff=down c c c] }
3758 \paper { linewidth = -1 }
3766 @section Page layout
3769 The page layout is the combined product of LilyPond formatting notation,
3770 and (La)@TeX{} putting the notation on a page, including page breaks.
3771 The part of LilyPond is documented here.
3785 @subsection Paper block
3788 The most important output definition is the @code{\paper} block, for
3789 music notation. The syntax is
3792 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3795 where each of the items is one of
3798 @item An assignment.
3800 @item A context definition. See @ref{Interpretation context} for
3801 more information on context definitions.
3803 @item \stylesheet declaration. Its syntax is
3805 \stylesheet @var{alist}
3808 See @file{scm/font.scm} for details of @var{alist}.
3809 @item an @code{\elementdescriptions} declaration.
3811 \elementdescriptions @var{alist}
3813 See @file{scm/grob-description.scm} for details of
3814 @var{alist}. This command is not user-serviceable.
3818 @c . {Paper variables}
3819 @node Paper variables
3820 @subsection Paper variables
3821 @cindex Paper variables
3823 The paper block has some variables you may want to use or change:
3826 @cindex @code{indent}
3828 The indentation of the first line of music.
3829 @cindex @code{staffspace}
3831 @item @code{staffspace}
3832 The distance between two staff lines, calculated from the center
3835 @cindex @code{linewidth}
3836 @item @code{linewidth}
3837 Sets the width of the lines.
3839 If set to a negative value, a single unjustified line is produced.
3840 @c rename to singleLinePaper ?
3841 The shorthand @code{\singleLine} defines a default paper block that
3842 produces a single line.
3844 @cindex @code{textheight}
3846 @item @code{textheight}
3847 Sets the total height of the music on each page. Only used by
3850 @cindex @code{interscoreline}
3852 @item @code{interscoreline}
3853 Sets the spacing between systems. The default is 16pt.
3855 @cindex @code{interscorelinefill}
3857 @item @code{interscorelinefill}
3858 If set to a positive number, the distance between the score
3859 lines will stretch in order to fill the full page. In that
3860 case @code{interscoreline} specifies the minimum spacing.
3865 @cindex @code{stafflinethickness}
3867 @item @code{stafflinethickness}
3868 Determines the thickness of staff lines, and also acts as a scaling
3869 parameter for other line thicknesses.
3872 You may enter these dimension using units (@code{cm}, @code{in},
3873 @code{mm}, @code{pt}), or relative to another dimension
3875 linewidth = 20.0 * \staffspace
3882 @subsection Font size
3883 @cindex font size, setting
3884 @cindex staff size, setting
3885 @cindex @code{paper} file
3887 The Feta font provides musical symbols at six different sizes. These
3888 fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
3889 point. The point size of a font is the height of the five lines in a
3890 staff when displayed in the font.
3892 Definitions for these sizes are the files @file{paperSZ.ly}, where
3893 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3894 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3895 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3896 @code{paperTwentysix} are defined respectively. The default
3897 @code{\paper} block is also set. These files should be imported at toplevel, i.e.
3899 \include "paper26.ly"
3903 The font definitions are generated using a Scheme function. For more
3904 details, see the file @file{scm/font.scm}.
3910 @subsection Paper size
3915 @cindex @code{papersize}
3917 To change the paper size, you must first set the
3918 @code{papersize} paper variable variable. Set it to
3919 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3920 specification, you must set the font as described above. If you want
3921 the default font, then use the 20 point font.
3924 \paper@{ papersize = "a4" @}
3925 \include "paper16.ly"
3928 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3929 will set the paper variables @code{hsize} and @code{vsize} (used by
3930 Lilypond and @code{ly2dvi})
3934 @subsection Line break
3937 @cindex breaking lines
3939 Line breaks are normally computed automatically. They are chosen such
3940 that it looks neither cramped nor loose, and that consecutive lines have
3943 Occasionally you might want to override the automatic breaks; you can do
3944 this by specifying @code{\break}. This will force a line break at this
3945 point. Do remember that line breaks can only occur at places where there
3946 are bar lines. If you want to have a line break where there is no
3947 bar line, you can force an invisible bar line by entering @code{\bar
3948 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3950 If you want linebreaks at regular intervals, you can use the following:
3953 < \repeat 7 unfold @{ s1 * 4 \break @}
3957 This makes the following 28 measures (assuming 4/4 time) be broken every
3961 @cindex @code{\penalty}
3963 The @code{\break} and @code{\noBreak} commands are defined in terms of
3964 the penalty command:
3969 This encourages or discourages LilyPond to make a line break at this
3974 The scaling of the @code{\penalty} argument is not well-defined. The
3975 command is rather kludgey, and slated for rewriting.
3979 @subsection Page break
3982 @cindex breaking pages
3984 Page breaks are normally computed by @TeX{}, so they are not under
3985 direct control of LilyPond. However, you can insert a commands into the
3986 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3987 the command @code{\newpage}
3988 @cindex @code{\newpage}
3994 @c why do so difficult?
3995 @c maybe should explain contents of between-system.ly,
3996 @c but not now, we're talking about page breaks here.
3998 @c details, see the example file @file{input/test/between-systems.ly}
4001 @c . {Output scaling}
4002 @node Output scaling
4003 @subsection Output scaling
4018 There is no mechanism to select magnification of particular fonts,
4019 meaning that you don't have access to continuously scaled fonts.
4023 @c . {Output formats}
4024 @node Output formats
4025 @section Output formats
4027 LilyPond can output processed music in different output formats.
4031 * PostScript output::
4033 * ASCIIScript output::
4037 @subsection TeX output
4040 LilyPond will use @TeX{} by default. Even if you want to produce
4041 PostScript output for viewing or printing, you should normally have
4042 LilyPond produce @TeX{} first. The .tex output must be processed by
4043 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
4044 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
4045 used to generate the .dvi for you.
4049 Titling is not generated unless you use @file{ly2dvi}.
4052 @node PostScript output
4053 @subsection PostScript output
4054 @cindex PostScript output
4055 @cindex direct PostScript output
4057 LilyPond can produce PostScript directly, without going through @TeX{}.
4058 Currently, this is mainly useful if you cannot use TeX, because direct
4059 PostScript output has some problems; see Bugs below.
4062 $ lilypond -fps foo.ly
4063 GNU LilyPond 1.3.144
4064 Now processing: `foo.ly'
4066 Interpreting music...[3]
4067 Preprocessing elements...
4068 Calculating column positions...
4069 paper output to foo.ps...
4071 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
4077 Text font selection is broken.
4079 The .ps file does not contain the .pfa font files. To print a .ps
4080 created through direct postscript output, you should prepend the
4081 necessary .pfa files to LilyPond's .ps output, or upload them to the
4082 printer before printing.
4084 The line height calculation is broken, you must set @var{lineheight} in
4085 the paperblock if you have more than one staff in your score, e.g.
4090 % Set line height to 40 staff spaces
4096 @subsection Scheme output
4097 @cindex Scheme output
4099 In the typesetting stage, LilyPond builds a page description, which is
4100 then written to disk in postscript, @TeX{} or ASCII art. Before it is
4101 written, the page description is represented as Scheme expressions. You
4102 can also dump these Scheme expressions to a file, which may be
4103 convenient for debugging output routines. This is done with the Scheme
4107 $ lilypond -fscm foo.ly
4108 GNU LilyPond 1.3.144
4109 Now processing: `foo.ly'
4111 Interpreting music...[3]
4112 Preprocessing elements...
4113 Calculating column positions...
4114 paper output to foo.scm...
4117 ;;; Usage: guile -s x.scm > x.tex
4118 (primitive-load-path 'standalone.scm)
4122 $ guile -s foo.scm > foo.tex
4126 @node ASCIIScript output
4127 @subsection ASCIIScript output
4128 @cindex ASCIIScript output
4129 @cindex ascii script
4132 LilyPond can output ASCII Art. This is a two step process, LilyPond
4133 produces an ASCII description file, dubbed ASCIIScript (extension
4134 @file{.as}). ASCIIScript has a small and simple command set that
4135 includes font selection, character and string printing and line drawing
4136 commands. The program @file{as2text} is used to translate an .as file
4139 To produce ASCII Art, you must include an ASCII Art paper definition
4140 file in your .ly, one of:
4142 \include "paper-as5.ly"
4143 \include "paper-as9.ly"
4146 Here's an example use for ASCII Art output (the example file
4147 @file{as-email.ly} is included in the LilyPond distribution), the staff
4148 symbol has been made invisible:
4151 $ lilypond -fas as-email.ly
4152 GNU LilyPond 1.3.144
4153 Now processing: `as-email.ly'
4155 Interpreting music...[3]
4156 Preprocessing elements...
4157 Calculating column positions... [2]
4158 paper output to as-email.as...
4160 $ as2text as-email.as 2>/dev/null
4162 |/ |##|##| | | | | |
4163 /| | | | | |\ |\ |\ |\ |\ |
4164 / |_ 3 | | | | 5 | )| )| )| )| )|
4165 | /| \ 8 * * * | 8 * * * * * |
4175 The ASCII Art fonts are far from complete and not very well designed.
4176 It's easy to change the glyphs, though; if you think you can do better,
4177 have a look at @file{mf/*.af}.
4179 Lots of resizable symbols such as slurs, ties and tuplets are missing.
4181 The poor looks of most ASCII Art output and its limited general
4182 usefulness gives ASCII Art output a low priority; it may be
4183 dropped in future versions.
4190 LilyPond can produce MIDI output. The performance lacks lots of
4191 interesting effects, such as swing, articulation, slurring, etc., but it
4192 is good enough for proof-hearing the music you have entered. Ties,
4193 dynamics and tempo changes are interpreted.
4195 Dynamic marks, crescendi and decrescendi translate into MIDI volume
4196 levels. Dynamic marks translate to a fixed fraction of the available
4197 MIDI volume range, crescendi and decrescendi make the the volume vary
4198 linearly between their two extremities. The fractions be adjusted by
4199 overriding the @code{absolute-volume-alist} defined in
4200 @file{scm/midi.scm}.
4202 For each type of musical instrument (that MIDI supports), a volume range
4203 can be defined. This gives you basic equalizer control, which can
4204 enhance the quality of the MIDI output remarkably. You can add
4205 instruments and ranges or change the default settings by overriding the
4206 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
4208 Both loudness controls are combined to produce the final MIDI volume.
4213 It is currently not possible to use the percussion channel (generally
4214 channel 10 of a MIDI file).
4218 * MIDI instrument names::
4223 @subsection MIDI block
4227 The MIDI block is analogous to the paper block, but it is somewhat
4228 simpler. The @code{\midi} block can contain:
4232 @item a @code{\tempo} definition
4233 @item context definitions
4236 Assignments in the @code{\midi} block are not allowed.
4240 @cindex context definition
4242 Context definitions follow precisely the same syntax as within the
4243 \paper block. Translation modules for sound are called performers.
4244 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
4247 @node MIDI instrument names
4248 @subsection MIDI instrument names
4250 @cindex instrument names
4251 @cindex @code{Staff.midiInstrument}
4252 @cindex @code{Staff.instrument}
4254 The MIDI instrument name is set by the @code{Staff.midiInstrument}
4255 property or, if that property is not set, the @code{Staff.instrument}
4256 property. The instrument name should be chosen from the list in
4257 @ref{MIDI instruments}.
4261 If the selected string does not exactly match, then LilyPond uses the
4262 default (Grand Piano). It is not possible to select an instrument by
4272 @c FIXME: Note entry vs Music entry at top level menu is confusing.
4275 @section Music entry
4283 When entering music with LilyPond, it is easy to introduce errors. This
4284 section deals with tricks and features that help you enter music, and
4285 find and correct mistakes.
4289 @subsection Relative
4291 @cindex relative octave specification
4293 Octaves are specified by adding @code{'} and @code{,} to pitch names.
4294 When you copy existing music, it is easy to accidentally put a pitch in
4295 the wrong octave and hard to find such an error. To prevent these
4296 errors, LilyPond features octave entry.
4298 @cindex @code{\relative}
4300 \relative @var{startpitch} @var{musicexpr}
4303 The octave of notes that appear in @var{musicexpr} are calculated as
4304 follows: If no octave changing marks are used, the basic interval
4305 between this and the last note is always taken to be a fourth or less
4306 (This distance is determined without regarding alterations; a
4307 @code{fisis} following a @code{ceses} will be put above the
4310 The octave changing marks @code{'} and @code{,} can be added to raise or
4311 lower the pitch by an extra octave. Upon entering relative mode, an
4312 absolute starting pitch must be specified that will act as the
4313 predecessor of the first note of @var{musicexpr}.
4315 Entering music that changes octave frequently is easy in relative mode.
4316 @lilypond[fragment,singleline,verbatim,center]
4322 And octave changing marks are used for intervals greater than a fourth.
4323 @lilypond[fragment,verbatim,center]
4325 c g c f, c' a, e'' }
4328 If the preceding item is a chord, the first note of the chord is used
4329 to determine the first note of the next chord. However, other notes
4330 within the second chord are determined by looking at the immediately
4333 @lilypond[fragment,verbatim,center]
4340 @cindex @code{\notes}
4342 The pitch after the @code{\relative} contains a note name. To parse
4343 the pitch as a note name, you have to be in note mode, so there must
4344 be a surrounding @code{\notes} keyword (which is not
4347 The relative conversion will not affect @code{\transpose},
4348 @code{\chords} or @code{\relative} sections in its argument. If you
4349 want to use relative within transposed music, you must place an
4350 additional @code{\relative} inside the @code{\transpose}.
4355 @subsection Bar check
4359 @cindex @code{barCheckNoSynchronize}
4363 Whenever a bar check is encountered during interpretation, a warning
4364 message is issued if it doesn't fall at a measure boundary. This can
4365 help you find errors in the input. Depending on the value of
4366 @code{barCheckNoSynchronize}, the beginning of the measure will be
4367 relocated, so this can also be used to shorten measures.
4369 A bar check is entered using the bar symbol, @code{|}:
4371 \time 3/4 c2 e4 | g2.
4376 @cindex skipTypesetting
4378 Failed bar checks are most often caused by entering incorrect
4379 durations. Incorrect durations often completely garble up the score,
4380 especially if it is polyphonic, so you should start correcting the score
4381 by scanning for failed bar checks and incorrect durations. To speed up
4382 this process, you can use @code{skipTypesetting} (See @ref{Skipping
4383 corrected music})). Bar
4386 @c . {Point and click}
4387 @node Point and click
4388 @subsection Point and click
4390 Point and click lets you find notes in the input by clicking on them in
4391 the Xdvi window. This makes it very easy to find input that causes some
4392 error in the sheet music.
4394 To use it, you need the following software
4396 @unnumberedsubsec Installation
4400 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
4401 Xdvi} version 22.36 or newer.
4403 Note that most @TeX{} distributions ship with xdvik, which is a
4404 different and less well maintained program. To find out which xdvi you
4405 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
4409 Xdvi must be configured to find the TeX fonts and music
4410 fonts. Refer to the Xdvi documentation for more information.
4413 @unnumberedsubsec Using it
4415 Add one of these lines to the top of your .ly file. The first one is for
4416 line location only. The second one is more convenient, but requires
4417 patching @code{emacsclient} and @code{server.el}.
4420 #(set! point-and-click line-location)
4423 In the emacs startup file (usually @file{~/.emacs}), add the following
4428 Make sure that the environment variable @code{XEDITOR} is set
4431 emacsclient --no-wait +%l %f
4433 The second one, that also specifies the column, only works if you have
4434 patched your emacsclient and server, and have compiled your @code{.ly}
4435 file using the @code{line-column-location} setting.
4437 When viewing, control-mousebutton 1 will take you to the originating
4438 spot in the @file{.ly} file. Control-mousebutton 2 will show all
4442 @unnumberedsubsec Column location
4444 If you want emacs to jump to the exact spot (and not just the line) on a
4445 click, you must enable column positioning. To do so, you need to patch
4446 emacsclient. Apply @file{emacsclient.patch} (included with the source
4447 package) to @file{emacsclient.c} and @file{server.el} from the emacs
4448 source code. Recompile and stick the recompiled emacsclient into a bin
4449 directory, and put @file{server.el} into a elisp directory
4450 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
4451 init file, before invoking server-start.
4454 (setq load-path (cons "~/usr/share/emacs" load-path))
4457 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
4459 At the top of the @code{ly} file, replace the @code{set!} line with the
4462 #(set! point-and-click line-column-location)
4465 One final hint: if you correct large files with point-and-click, then
4466 start correcting at the end of the file. When you start at the top, and
4467 insert one line, all subsequent locations will be off by a line.
4472 When you convert the @TeX{} file to PostScript using @code{dvips}, it
4473 will complain about not finding @code{src:X:Y} files. Those complaints
4474 are harmless, and can be ignored.
4476 @node Skipping corrected music
4477 @section Skipping corrected music
4479 The property @code{Score.skipTypesetting} can be used to switch on and
4480 off typesetting completely during the interpretation phase. When
4481 typesetting is switched off, the music is processed much more quickly.
4482 You can use this to skip over the parts of a score that you have already
4485 @lilypond[fragment,singleline,verbatim]
4486 \relative c'' { c8 d
4487 \property Score.skipTypesetting = ##t
4489 \property Score.skipTypesetting = ##f
4494 @node Interpretation context
4495 @section Interpretation context
4498 * Creating contexts::
4499 * Default contexts::
4500 * Context properties::
4501 * Engravers and performers::
4502 * Changing context definitions::
4503 * Defining new contexts::
4507 Interpretation contexts are objects that only exist during a run of
4508 LilyPond. During the interpretation phase of LilyPond (when it prints
4509 "interpreting music"), the music expression in a @code{\score} block is
4510 interpreted in time order. This is the same order that humans hear and
4513 During this interpretation, the interpretation context holds the
4514 state for the current point within the music. It contains information
4518 @item What notes are playing at this point?
4519 @item What symbols will be printed at this point?
4520 @item What is the current key signature, time signature, point within
4524 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4525 contained in a @internalsref{Staff} context (because a staff can contain
4526 multiple voices at any point), a @internalsref{Staff} context is contained in
4527 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4529 Contexts associated with sheet music output are called @emph{notation
4530 contexts}, those for sound output are called @emph{performance
4531 contexts}. The default definitions of the standard notation and
4532 performance contexts can be found in @file{ly/engraver-init.ly} and
4533 @file{ly/performer-init.ly}, respectively.
4535 @node Creating contexts
4536 @subsection Creating contexts
4538 @cindex @code{\context}
4539 @cindex context selection
4541 Contexts for a music expression can be selected manually, using the
4542 following music expression.
4545 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4548 This instructs lilypond to interpret @var{musicexpr} within the context
4549 of type @var{contexttype} and with name @var{contextname}. If this
4550 context does not exist, it will be created.
4552 @lilypond[verbatim,singleline]
4554 \notes \relative c'' {
4555 c4 <d4 \context Staff = "another" e4> f
4561 In this example, the @code{c} and @code{d} are printed on the
4562 default staff. For the @code{e}, a context Staff called
4563 @code{another} is specified; since that does not exist, a new
4564 context is created. Within @code{another}, a (default) Voice context
4565 is created for the @code{e4}. When all music referring to a
4566 context is finished, the context is ended as well. So after the
4567 third quarter, @code{another} is removed.
4571 @node Default contexts
4572 @subsection Default contexts
4574 Most music expressions don't need an explicit @code{\context}
4575 declaration: they inherit the
4576 notation context from their parent. Each note is a music expression, and
4577 as you can see in the following example, only the sequential music
4578 enclosing the three notes has an explicit context.
4580 @lilypond[verbatim,singleline]
4581 \score { \notes \context Voice = goUp { c'4 d' e' } }
4584 There are some quirks that you must keep in mind when dealing with
4587 First, every top level music is interpreted by the Score context, in other
4588 words, you may think of @code{\score} working like
4591 \context Score @var{music}
4595 Second, contexts are created automatically to be able to interpret the
4596 music expressions. Consider the following example.
4598 @lilypond[verbatim, singleline]
4599 \score { \context Score \notes { c'4 ( d' )e' } }
4602 The sequential music is interpreted by the Score context initially
4603 (notice that the @code{\context} specification is redundant), but when a
4604 note is encountered, contexts are setup to accept that note. In this
4605 case, a Thread, Voice and Staff are created. The rest of the sequential
4606 music is also interpreted with the same Thread, Voice and Staff context,
4607 putting the notes on the same staff, in the same voice.
4609 This is a convenient mechanism, but do not expect opening chords to work
4610 without @code{\context}. For every note, a separate staff is
4613 @cindex explicit context
4614 @cindex starting with chords
4615 @cindex chords, starting with
4617 @lilypond[verbatim, singleline]
4618 \score { \notes <c'4 es'> }
4621 Of course, if the chord is preceded by a normal note in sequential
4622 music, the chord will be interpreted by the Thread of the preceding
4624 @lilypond[verbatim,singleline]
4625 \score { \notes { c'4 <c'4 es'> } }
4630 @node Context properties
4631 @subsection Context properties
4633 Notation contexts have properties. These properties are from
4634 the @file{.ly} file using the following expression:
4635 @cindex @code{\property}
4637 \property @var{contextname}.@var{propname} = @var{value}
4640 Sets the @var{propname} property of the context @var{contextname} to the
4641 specified Scheme expression @var{value}. All @var{propname} and
4642 @var{contextname} are strings, which are typically unquoted.
4644 Properties that are set in one context are inherited by all of the
4645 contained contexts. This means that a property valid for the
4646 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4647 example) and thus take effect in all @internalsref{Voice} contexts.
4649 Properties can be unset using the following expression:
4651 \property @var{contextname}.@var{propname} \unset
4654 @cindex properties, unsetting
4655 @cindex @code{\unset}
4657 This removes the definition of @var{propname} in @var{contextname}. If
4658 @var{propname} was not defined in @var{contextname} (but was inherited
4659 from a higher context), then this has no effect.
4664 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4665 the inverse of @code{\property \set}.
4667 @node Engravers and performers
4668 @subsection Engravers and performers
4672 Basic building blocks of translation are called engravers; they are
4673 special C++ classes.
4677 @c . {Context definitions}
4678 @node Changing context definitions
4679 @subsection Changing context definitions
4681 @cindex context definition
4682 @cindex translator definition
4684 The most common way to define a context is by extending an existing
4685 context. You can change an existing context from the paper block, by
4686 first initializing a translator with an existing context identifier:
4690 @var{context-identifier}
4693 Then you can add and remove engravers using the following syntax:
4695 \remove @var{engravername}
4696 \consists @var{engravername}
4700 Here @var{engravername} is a string, the name of an engraver in the
4704 @lilypond[verbatim,singleline]
4708 \translator { \StaffContext
4709 \remove Clef_engraver
4715 You can also set properties in a translator definition. The syntax is as
4718 @var{propname} = @var{value}
4719 @var{propname} \set @var{grob-propname} = @var{pvalue}
4720 @var{propname} \override @var{grob-propname} = @var{pvalue}
4721 @var{propname} \revert @var{grob-propname}
4723 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4724 and @code{pvalue} are Scheme expressions. These type of property
4725 assignments happen before interpretation starts, so a @code{\property}
4726 command will override any predefined settings.
4729 To simplify editing translators, all standard contexts have standard
4730 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4731 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
4733 @node Defining new contexts
4734 @subsection Defining new contexts
4736 If you want to build a context from scratch, you must also supply the
4737 following extra information:
4739 @item A name, specified by @code{\name @var{contextname}}.
4741 @item A cooperation module. This is specified by @code{\type
4748 \type "Engraver_group_engraver"
4751 \consists "Staff_symbol_engraver"
4752 \consists "Note_head_engraver"
4753 \consistsend "Axis_group_engraver"
4757 The argument of @code{\type} is the name for a special engraver that
4758 handles cooperation between simple engravers such as
4759 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4760 for this engraver are the following:
4762 @cindex @code{Engraver_group_engraver}
4763 @item @code{Engraver_group_engraver}
4764 The standard cooperation engraver.
4766 @cindex @code{Score_engraver}
4768 @item @code{Score_engraver}
4769 This is cooperation module that should be in the top level context,
4770 and only the top level context.
4772 @cindex @code{Grace_engraver_group}
4774 @item @code{Grace_engraver_group}
4775 This is a special cooperation module (resembling
4776 @code{Score_engraver}) that is used to create an embedded
4783 @item @code{\alias} @var{alternate-name}
4784 This specifies a different name. In the above example,
4785 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4787 @item @code{\consistsend} @var{engravername}
4788 Analogous to @code{\consists}, but makes sure that
4789 @var{engravername} is always added to the end of the list of
4792 Some engraver types need to be at the end of the list; this
4793 insures they stay there even if a user adds or removes engravers.
4794 End-users generally don't need this command.
4796 @item @code{\accepts} @var{contextname}
4797 Add @var{contextname} to the list of contexts this context can
4798 contain in the context hierarchy. The first listed context is the
4799 context to create by default.
4801 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4802 completeness, but is never used in practice.
4805 @item @code{\name} @var{contextname}
4806 This sets the type name of the context, e.g. @internalsref{Staff},
4807 @internalsref{Voice}. If the name is not specified, the translator won't do
4811 In the @code{\paper} block, it is also possible to define translator
4812 identifiers. Like other block identifiers, the identifier can only
4813 be used as the very first item of a translator. In order to define
4814 such an identifier outside of @code{\score}, you must do
4819 foo = \translator @{ @dots{} @}
4826 \translator @{ \foo @dots{} @}
4834 @cindex paper types, engravers, and pre-defined translators
4841 @c . {Syntactic details}
4842 @node Syntactic details
4843 @section Syntactic details
4844 @cindex Syntactic details
4846 This section describes details that were too boring to be put elsewhere.
4851 * Music expressions::
4852 * Manipulating music expressions::
4860 @subsection Top level
4863 This section describes what you may enter at top level.
4867 @subsubsection Score
4870 @cindex score definition
4872 The output is generated combining a music expression with an output
4873 definition. A score block has the following syntax:
4876 \score @{ @var{musicexpr} @var{outputdefs} @}
4879 @var{outputdefs} are zero or more output definitions. If none is
4880 supplied, the default @code{\paper} block will be added.
4884 @c . {Default output}
4885 @subsubsection Default output
4887 Default values for the @code{\paper} and @code{\midi} block are set by
4888 entering such a block at the top level.
4891 @subsubsection Header
4893 @cindex @code{\header}
4896 A header describes bibliographic information of the file's contents. It
4897 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4898 use this information for generating titles. Key values that are used by
4899 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4900 meter, arranger, piece and tagline.
4902 @cindex @code{ly2dvi}
4906 \header @{ @var{key1} = @var{val1}
4907 @var{key2} = @var{val2} @dots{} @}
4910 It is customary to put the @code{\header} at the top of the file.
4912 @subsubsection Default output
4914 A @code{\midi} or @code{\paper} block at top level sets the default
4915 paper block for all scores that lack an explicit paper block.
4919 @subsection Identifiers
4923 What has this section got to do with identifiers?
4924 It seems more appropriate in the introduction to Chapter 4,
4930 All of the information in a LilyPond input file, is internally
4931 represented as a Scheme value. In addition to normal Scheme data types
4932 (such as pair, number, boolean, etc.), LilyPond has a number of
4933 specialized data types,
4940 @item Translator_def
4944 @item Music_output_def
4945 @item Moment (rational number)
4948 LilyPond also includes some transient object types. Objects of these
4949 types are built during a LilyPond run, and do not `exist' per se within
4950 your input file. These objects are created as a result of your input
4951 file, so you can include commands in the input to manipulate them,
4952 during a lilypond run.
4955 @item Grob: short for Graphical object. See @ref{Grobs}.
4956 @item Molecule: device-independent page output object,
4957 including dimensions. Produced by some Grob functions
4959 @item Translator: object that produces audio objects or Grobs. This is
4960 not yet user accessible.
4961 @item Font_metric: object representing a font.
4965 @node Music expressions
4966 @subsection Music expressions
4968 @cindex music expressions
4970 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4971 syllables are music expressions, and you can combine music expressions
4972 to form new ones, for example by enclosing a list of expressions in
4973 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4974 compound expression is formed out of the quarter note @code{c} and a
4975 quarter note @code{d}:
4978 \sequential @{ c4 d4 @}
4981 @cindex Sequential music
4982 @cindex @code{\sequential}
4983 @cindex sequential music
4986 @cindex Simultaneous music
4987 @cindex @code{\simultaneous}
4989 The two basic compound music expressions are simultaneous and
4993 \sequential @code{@{} @var{musicexprlist} @code{@}}
4994 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4996 For both, there is a shorthand:
4998 @code{@{} @var{musicexprlist} @code{@}}
5002 @code{<} @var{musicexprlist} @code{>}
5004 for simultaneous music.
5005 In principle, the way in which you nest sequential and simultaneous to
5006 produce music is not relevant. In the following example, three chords
5007 are expressed in two different ways:
5009 @lilypond[fragment,verbatim,center]
5010 \notes \context Voice {
5011 <a c'> <b d' > <c' e'>
5012 < { a b c' } { c' d' e' } >
5017 Other compound music expressions include
5020 \transpose @var{pitch} @var{expr}
5021 \apply @var{func} @var{expr}
5022 \context @var{type} = @var{id} @var{expr}
5023 \times @var{fraction} @var{expr}
5027 @c . {Manipulating music expressions}
5028 @node Manipulating music expressions
5029 @subsection Manipulating music expressions
5031 The @code{\apply} mechanism gives you access to the internal
5032 representation of music. You can write Scheme-functions that operate
5033 directly on it. The syntax is
5035 \apply #@var{func} @var{music}
5037 This means that @var{func} is applied to @var{music}. The function
5038 @var{func} should return a music expression.
5040 This example replaces the text string of a script. It also shows a dump
5041 of the music it processes, which is useful if you want to know more
5042 about how music is stored.
5044 @lilypond[verbatim,singleline]
5045 #(define (testfunc x)
5046 (if (equal? (ly-get-mus-property x 'text) "foo")
5047 (ly-set-mus-property x 'text "bar"))
5049 (ly-set-mus-property x 'elements
5050 (map testfunc (ly-get-mus-property x 'elements)))
5055 \apply #testfunc { c'4_"foo" }
5059 For more information on what is possible, see the automatically
5060 generated documentation.
5063 Directly accessing internal representations is dangerous: the
5064 implementation is subject to changes, so you should avoid this feature
5067 A final example is a function that reverses a piece of music in time:
5069 @lilypond[verbatim,singleline]
5070 #(define (reverse-music music)
5071 (let* ((elements (ly-get-mus-property music 'elements))
5072 (reversed (reverse elements))
5073 (span-dir (ly-get-mus-property music 'span-direction)))
5074 (ly-set-mus-property music 'elements reversed)
5076 (ly-set-mus-property music 'span-direction (- span-dir)))
5077 (map reverse-music reversed)
5080 music = \notes { c'4 d'4( e'4 f'4 }
5082 \score { \context Voice {
5084 \apply #reverse-music \music
5089 More examples are given in the distributed example files in
5092 @c . {Span requests}
5098 @subsubsection Span requests
5099 @cindex Span requests
5101 Notational constructs that start and end on different notes can be
5102 entered using span requests. The syntax is as follows:
5106 \spanrequest @var{startstop} @var{type}
5110 @cindex @code{\start}
5111 @cindex @code{\stop}
5113 This defines a spanning request. The @var{startstop} parameter is either
5114 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
5115 describes what should be started. Much of the syntactic sugar is a
5116 shorthand for @code{\spanrequest}, for example,
5118 @lilypond[fragment,verbatim,center]
5119 c'4-\spanrequest \start "slur"
5120 c'4-\spanrequest \stop "slur"
5123 Among the supported types are @code{crescendo}, @code{decrescendo},
5124 @code{beam}, @code{slur}. This is an internal command. Users are
5125 encouraged to use the shorthands which are defined in the initialization
5126 file @file{spanners.ly}.
5131 @subsection Assignments
5134 Identifiers allow objects to be assigned to names during the parse
5135 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
5136 and to refer to an identifier, you precede its name with a backslash:
5137 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
5138 the input-types listed above. Identifier assignments can appear at top
5139 level in the LilyPond file, but also in @code{\paper} blocks.
5141 An identifier can be created with any string for its name, but you will
5142 only be able to refer to identifiers whose names begin with a letter,
5143 being entirely alphabetical. It is impossible to refer to an identifier
5144 whose name is the same as the name of a keyword.
5146 The right hand side of an identifier assignment is parsed completely
5147 before the assignment is done, so it is allowed to redefine an
5148 identifier in terms of its old value, e.g.
5154 When an identifier is referenced, the information it points to is
5155 copied. For this reason, an identifier reference must always be the
5156 first item in a block.
5160 \paperIdent % wrong and invalid
5164 \paperIdent % correct
5169 @c . {Lexical modes}
5171 @subsection Lexical modes
5172 @cindex Lexical modes
5175 @cindex @code{\notes}
5176 @cindex @code{\chords}
5177 @cindex @code{\lyrics}
5179 To simplify entering notes, lyrics, and chords, LilyPond has three
5180 special input modes in addition to the default mode: note, lyrics and
5181 chords mode. These input modes change the way that normal, unquoted
5182 words are interpreted: for example, the word @code{cis} may be
5183 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
5184 major triad respectively.
5186 A mode switch is entered as a compound music expression
5188 @code{\notes} @var{musicexpr}
5189 @code{\chords} @var{musicexpr}
5190 @code{\lyrics} @var{musicexpr}.
5193 In each of these cases, these expressions do not add anything to the
5194 meaning of their arguments. They just instruct the parser in what mode
5195 to parse their arguments. The modes are treated in more detail in
5196 @ref{Lyrics} and @ref{Chords}.
5198 Different input modes may be nested.
5202 @subsection Ambiguities
5207 The grammar contains a number of ambiguities. We hope to resolve them at
5211 @item The assignment
5216 is interpreted as the string identifier assignment. However,
5217 it can also be interpreted as making a string identifier @code{\foo}
5218 containing @code{"bar"}, or a music identifier @code{\foo}
5219 containing the syllable `bar'.
5221 @item If you do a nested repeat like
5233 then it is ambiguous to which @code{\repeat} the
5234 @code{\alternative} belongs. This is the classic if-then-else
5235 dilemma. It may be solved by using braces.
5237 @item The parser is not sophisticated enough to distinguish at the
5239 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
5246 @c . {Lexical details}
5247 @node Lexical details
5248 @section Lexical details
5250 Even more boring details, now on lexical side of the input parser.
5261 * Version information::
5266 @subsection Comments
5269 @cindex block comment
5270 @cindex line comment
5274 A one line comment is introduced by a @code{%} character.
5275 Block comments are started by @code{%@{} and ended by @code{%@}}.
5276 They cannot be nested.
5279 @subsection Direct Scheme
5283 @cindex Scheme, in-line code
5286 LilyPond contains a Scheme interpreter (the GUILE library) for
5287 internal use. In some places, Scheme expressions also form valid syntax:
5288 wherever it is allowed,
5292 evaluates the specified Scheme code. Example:
5294 \property Staff.TestObject \override #'foobar = #(+ 1 2)
5296 @code{\override} expects two Scheme expressions, so there are two Scheme
5297 expressions. The first one is a symbol (@code{foobar}), the second one
5298 an integer (namely, 3).
5300 In-line scheme may be used at the top level. In this case the result is
5303 Scheme is a full-blown programming language, and a full discussion is
5304 outside the scope of this document. Interested readers are referred to
5305 the website @uref{http://www.schemers.org/} for more information on
5310 @subsection Keywords
5314 Keywords start with a backslash, followed by a number of lower case
5315 alphabetic characters. These are all the keywords.
5318 apply arpeggio autochange spanrequest commandspanrequest
5319 simultaneous sequential accepts alternative bar breathe
5320 char chordmodifiers chords clef cm consists consistsend
5321 context denies duration dynamicscript elementdescriptions
5322 font grace header in lyrics key mark pitch
5323 time times midi mm name pitchnames notes outputproperty
5324 override set revert partial paper penalty property pt
5325 relative remove repeat addlyrics partcombine score
5326 script stylesheet skip textscript tempo translator
5331 @subsection Integers
5339 Formed from an optional minus sign followed by digits. Arithmetic
5340 operations cannot be done with integers, and integers cannot be mixed
5345 @cindex real numbers
5351 Formed from an optional minus sign and a sequence of digits followed
5352 by a @emph{required} decimal point and an optional exponent such as
5353 @code{-1.2e3}. Reals can be built up using the usual operations:
5354 `@code{+}', `@code{-}', `@code{*}', and
5355 `@code{/}', with parentheses for grouping.
5363 A real constant can be followed by one of the dimension keywords:
5364 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5365 points, inches and centimeters, respectively. This converts the number
5366 a number that is the internal representation of that dimension.
5374 Begins and ends with the @code{"} character. To include a @code{"}
5375 character in a string write @code{\"}. Various other backslash
5376 sequences have special interpretations as in the C language. A string
5377 that contains no spaces can be written without the quotes. Strings can
5378 be concatenated with the @code{+} operator.
5382 @subsection Main input
5385 @cindex @code{\maininput}
5387 The @code{\maininput} command is used in init files to signal that the
5388 user file must be read. This command cannot be used in a user file.
5390 @node File inclusion
5391 @subsection File inclusion
5392 @cindex @code{\include}
5394 \include @var{filename}
5397 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5398 unquoted string will not work here!) or a string identifier. The full
5399 filename including the @file{.ly} extension must be given,
5402 @node Version information
5403 @subsection Version information
5404 @cindex @code{\version}
5406 \version @var{string}
5409 Specify the version of LilyPond that a file was written for. The
5410 argument is a version string in quotes, for example @code{"1.2.0"}.
5411 This is used to detect invalid input, and to aid
5412 @code{convert-ly} a tool that automatically upgrades input files. See
5413 See @ref{convert-ly} for more information on @code{convert-ly}.
5421 @c broken with emacs-21
5422 @c {Local emac s vars}
5423 @c Local varia bles:
5425 @c minor-mod e: font-lock
5426 @c minor-mo de: outline
5427 @c outline -layout: (-1 : 0)
5428 @c outlin e-use-mode-specific-leader: "@c \."
5429 @c outli ne-primary-bullet: "{"
5430 @c outli ne-stylish-prefixes: nil
5431 @c outli ne-override-protect: t