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 * Multi measure rests::
2694 * Automatic part combining::
2695 * Hara kiri staves::
2696 * Sound output for transposing instruments::
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 ::
3231 @node Tuning groups of grobs
3232 @subsection Tuning groups of grobs
3234 @cindex grob description
3238 A grob definition is a Scheme association list, that is stored in a
3239 context property. By assigning to that property (using plain
3240 @code{\property}), you can change the resulting grobs.
3242 @lilypond[verbatim, fragment]
3243 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
3246 The @code{\property} assignment effectively empties the definition of
3247 the Stem object. One of the effects is that the recipe of how it should be
3248 printed is erased, with the effect of rendering it invisible. The above
3249 assignment is available as a standard identifier, for the case that you
3253 \property Voice.Stem = \turnOff
3260 This mechanism is fairly crude, since you can only set, but not modify,
3261 the definition of a grob. For this reason, there is a more advanced
3264 The definition of a grob is actually a list of default grob
3265 properties. For example, the definition of the Stem grob (available in
3266 @file{scm/grob-description.scm}), defines the following values for
3271 (beamed-lengths . (0.0 2.5 2.0 1.5))
3272 (Y-extent-callback . ,Stem::height)
3276 You can add a property on top of the existing definition, or remove a
3277 property, thus overriding the system defaults:
3279 c'4 \property Voice.Stem \override #'thickness = #4.0
3280 c'4 \property Voice.Stem \revert #'thickness
3283 You should balance @code{\override} and @code{\revert}. If that's too
3284 much work, you can use the @code{\set} shorthand. It performs a revert
3285 followed by an override. The following example gives exactly the same
3286 result as the previous one.
3288 c'4 \property Voice.Stem \set #'thickness = #4.0
3289 c'4 \property Voice.Stem \set #'thickness = #0.8
3292 If you use @code{\set}, you must explicitly restore the default.
3295 Formally the syntax for these constructions is
3297 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
3298 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
3299 \property @var{context}.@var{grobname} \revert @var{symbol}
3301 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
3302 and @var{grobname} are strings and @var{value} is a Scheme expression.
3305 If you revert a setting which was not set in the first place, then it
3306 has no effect. However, if the setting was set as a system default, it
3307 may remove the default value, and this may give surprising results,
3308 including crashes. In other words, @code{\override} and @code{\revert},
3309 must be carefully balanced.
3311 These are examples of correct nesting of @code{\override}, @code{\set},
3314 A clumsy but correct form:
3316 \override \revert \override \revert \override \revert
3319 Shorter version of the same:
3321 \override \set \set \revert
3324 A short form, using only @code{\set}. This requires you to know the
3327 \set \set \set \set @var{to default value}
3330 If there is no default (i.e. by default, the grob property is unset),
3333 \set \set \set \revert
3336 For the digirati, the grob description is an Scheme association
3337 list. Since a Scheme list is a singly linked list, we can treat it as a
3338 stack, and @code{\override} and @code{\revert} are just push and pop
3339 operations. This pushing and popping is also used for overriding
3340 automatic beaming settings.
3344 LilyPond will hang or crash if @var{value} contains cyclic references.
3345 The backend is not very strict in type-checking grob properties. If you
3346 @code{\revert} properties that are expected to be set by default,
3350 @cindex adjusting staff symbol
3351 @cindex StaffSymbol, using \property
3352 @cindex staff lines, setting number of
3354 Some grobs are created at the moment that their context is created. An
3355 example of such a grob is the staff itself (i.e. the horizontal lines).
3356 You can not change the appearance of the staff symbol by manipulating
3357 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3358 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3359 created before any @code{\override} is effective. You can deal with this
3360 either overriding properties in a @code{\translator} definition, or by
3361 using @code{\outputproperty}.
3366 @node Tuning per grob
3367 @subsection Tuning per grob
3369 @cindex \outputproperty
3371 A second way of tuning grobs is the more arcane @code{\outputproperty}
3372 feature. The syntax is as follows:
3374 \outputproperty @var{predicate} @var{symbol} = @var{value}
3376 Here @code{predicate} is a Scheme function taking a grob argument, and
3377 returning a boolean. This statement is processed by the
3378 @code{Output_property_engraver}. It instructs the engraver to feed all
3379 grobs that it sees to @var{predicate}. Whenever the predicate returns
3380 true, the grob property @var{symbol} will be set to @var{value}.
3382 You will need to combine this statement with @code{\context} to select
3383 the appropriate context to apply this to.
3385 Here are some random examples.
3388 In the following example, all note heads occurring at current staff
3389 level, are shifted up and right by setting their @code{extra-offset}
3392 @lilypond[fragment,verbatim,singleline]
3394 \context Staff \outputproperty
3395 #(make-type-checker 'note-head-interface)
3396 #'extra-offset = #'(0.5 . 0.75)
3400 @cindex @code{extra-offset}
3402 In this example, the predicate checks the @code{text} grob property, to
3403 shift only the `m.d.' text, but not the fingering instruction "2".
3404 @lilypond[verbatim,singleline]
3405 #(define (make-text-checker text)
3406 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3409 \notes\relative c''' {
3410 \property Voice.Stem \set #'direction = #1
3411 \outputproperty #(make-text-checker "m.d.")
3412 #'extra-offset = #'(-3.5 . -4.5)
3420 If possible, avoid this feature: the semantics are not very clean, and
3421 the syntax and semantics are up for rewrite.
3426 @node Font selection
3427 @subsection Font selection
3429 Most graphics in LilyPond are composed of characters of fonts. You can
3430 alter the characteristics of the font by setting certain grob
3431 properties. The mechanism that is used for this resembles La@TeX{}'s New
3432 Font Selection Scheme. Within this scheme, a font is entirely
3433 characterized by its font name.
3435 For each grob that uses fonts (in other words, each grob that supports
3436 @code{font-interface}) a font-name must be selected before it can be
3437 printed. The font name is selected by looking at a number of grob
3442 A symbol indicating the general class of the typeface. Supported are
3443 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3444 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3445 signs) and @code{typewriter}
3448 A symbol indicating the shape of the font, there are typically several
3449 font shapes available for each font family. Choices are @code{italic},
3450 @code{caps} and @code{upright}
3453 A symbol indicating the series of the font. There are typically several
3454 font series for each font family and shape. Choices are @code{medium}
3457 @item font-relative-size
3458 A number indicating the size relative the standard size. For example,
3459 with 20pt staff height, relative size -1 corresponds to 16pt staff
3460 height, and relative size +1 corresponds to 23 pt staff height.
3462 @item font-design-size
3463 A number indicating the design size of the font.
3465 This is a feature of the Computer Modern Font: each point size has a
3466 slightly different design. Smaller design sizes are relatively wider,
3467 which enhances readability. Scalable type faces such TrueType and Adobe
3468 Type1 usually come as ``one design fits all sizes''.
3471 The name of the font, without the design size, e.g. @code{cmr},
3472 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3479 The font is selected by taking the first font that satisfies all
3480 qualifiers specified. You can override any of these fields through
3481 @code{\override} and @code{\revert}. The special value @code{*} matches
3482 any value for that qualifier.
3485 \property Lyrics.LyricText \override #'font-series = #'bold
3486 \property Lyrics.LyricText \override #'font-shape = #'*
3489 @cindex @code{font-style}
3491 There are also pre-cooked font selection qualifiers. These are selected
3492 through the grob property @code{font-style}. For example, the style
3493 @code{finger} selects family @code{number} and relative size @code{-3}.
3494 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3495 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3498 The style sheets and tables for selecting fonts are located in
3499 @file{scm/font.scm}. Refer to this file for more information.
3502 Setting @code{font-name} overrides all other qualifiers. The value for
3503 this property should be a string, the file name of the font. You may use
3504 this to use special fonts, which are not a part of the style sheet, or
3505 which have special encodings.
3507 The size of the font may be set with the grob property
3508 @code{font-magnification}. It is the size of font, relative to its
3509 standard size. For example, @code{1.0} is normal size.
3513 Relative size is not linked to any real size.
3515 There is no style sheet provided for other fonts besides the @TeX{}
3518 @cindex font selection
3519 @cindex font magnification
3520 @cindex @code{font-interface}
3524 @subsection Text markup
3528 LilyPond has an internal mechanism to typeset texts. You can
3529 form text markup expressions by composing scheme expressions
3530 in the following way.
3532 @lilypond[verbatim, singleline]
3537 c^#'(italic "italic")
3538 d_#'((bold italic) "ff")
3540 f_#'(lines "one" (bold "two"))
3541 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3545 Normally, the Scheme markup text is stored in the @code{text} property
3546 of a grob. Formally, it is defined as follows:
3549 text: string | (head? text+)
3550 head: markup | (markup+)
3551 markup-item: property | abbrev
3552 property: (@var{key} . @var{value})
3553 abbrev: @code{columns lines roman music bold italic named super sub}
3554 @code{overstrike text finger volta timesig mmrest mark script}
3555 @code{large Large dynamic}
3558 The markup is broken down and converted into a list of grob properties,
3559 which are prepended to the property list. The @var{key}-@var{value}
3560 pair is a grob property. A list of properties available is included in
3561 the generated documentation for @rint{Text_interface}.
3563 The following abbreviations are currently defined:
3566 horizontal mode: set all text on one line (default)
3568 vertical mode: set every text on a new line
3572 selects the Feta font (the standard font for music notation glyphs),
3573 and uses named lookup
3580 lookup by character name
3582 plain text lookup (by character value)
3588 the next text or character overstrikes this one
3590 select fingering number fontstyle
3592 select volta number fontstyle
3594 select time signature number fontstyle
3596 select multi measure rest number fontstyle
3598 select mark number fontstyle
3600 select scriptsize roman fontstyle
3602 select large roman fontstyle
3604 select Large roman fontstyle
3606 select dynamics fontstyle
3610 @cindex metronome mark
3612 One practical application of complicated markup is to fake a metronome
3616 #(define note '(columns
3617 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3618 #(define eight-note `(columns ,note ((kern . -0.1)
3619 (music ((raise . 3.5) "flags-u3")))))
3620 #(define dotted-eight-note
3621 `(columns ,eight-note (music "dots-dot")))
3624 \notes\relative c'' {
3625 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3631 TextScript \override #'font-shape = #'upright
3637 @node Invisible grobs
3638 @subsection Invisible grobs
3639 @cindex invisible grobs
3643 ben nog steeds niet kapot van de informatiedichtheid hier.
3649 You can imagine a number of situations where you would want to make
3650 certain grobs not show up in the output. There may be aesthetic
3651 reasons, to make the output resemble an (old) manuscript as close as
3652 possible, or to make lessons or exercises for students.
3654 Grobs can be made invisible in a number of ways:
3656 Here's an example with blanked-out notes and stems:
3657 @lilypond[singleline,verbatim]
3659 \property Voice.NoteHead \override
3661 \property Voice.Stem \override
3662 #'transparent = ##t }
3665 \property Voice.NoteHead \revert #'transparent
3666 \property Voice.Stem \revert #'transparent }
3669 \notes\relative c'' {
3671 a b c b \blanknotes c \unblanknotes d
3675 This method makes the grobs invisible but they still take the normal space.
3676 To remove all traces of the grob, you can redefine the function
3680 \notes\relative c'' {
3683 as bes c bes c d \break
3684 \property Staff.KeySignature \override #'molecule-callback = #'()
3687 \paper{linewidth=5.0\cm indent=0}
3691 A very rigorous way of removing grobs from the whole score is to remove
3692 the engraver that creates them. For example,
3694 @lilypond[singleline,verbatim]
3695 \score {\notes { c'4 d'8 e'8 g2 }
3696 \paper { \translator {
3698 \remove Stem_engraver
3704 @subsection Dirty tricks
3705 @cindex embedded tex
3707 It is possible to use @TeX{} commands in the strings, but this should be
3708 avoided because it makes it impossible for LilyPond to compute the
3709 exact length of the string, which may lead to collisions. Also, @TeX{}
3710 commands won't work with direct PostScript output (see @ref{PostScript
3713 @lilypond[fragment,relative,verbatim]
3714 a'^"3 $\\times$ \\`a deux"
3717 You can also use raw PostScript commands embedded in text scripts. This
3718 offers ultimate flexibility, but requires you to learn PostScript.
3719 Currently, embedded PostScript will @strong{not} work with direct
3720 PostScript output. Note that all dimensions that you use are in staff
3725 \notes \relative c'' {
3726 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3727 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3728 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3732 \paper { linewidth = 70*\staffspace }
3739 TODO: Move this section.
3745 Generating optically pleasing spacing is black magic. LilyPond tries
3746 to deal with a number of frequent cases. Here is an example that is
3747 not handled correctly, due to the combination of chord collisions and
3752 \context PianoStaff \notes \transpose c''' <
3753 \context Staff = up { s1 }
3754 \context Staff = down { [c8 c \translator Staff=up <c d> c
3755 \translator Staff=down c c c] }
3757 \paper { linewidth = -1 }
3765 @section Page layout
3768 The page layout is the combined product of LilyPond formatting notation,
3769 and (La)@TeX{} putting the notation on a page, including page breaks.
3770 The part of LilyPond is documented here.
3784 @subsection Paper block
3787 The most important output definition is the @code{\paper} block, for
3788 music notation. The syntax is
3791 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3794 where each of the items is one of
3797 @item An assignment.
3799 @item A context definition. See @ref{Interpretation context} for
3800 more information on context definitions.
3802 @item \stylesheet declaration. Its syntax is
3804 \stylesheet @var{alist}
3807 See @file{scm/font.scm} for details of @var{alist}.
3808 @item an @code{\elementdescriptions} declaration.
3810 \elementdescriptions @var{alist}
3812 See @file{scm/grob-description.scm} for details of
3813 @var{alist}. This command is not user-serviceable.
3817 @c . {Paper variables}
3818 @node Paper variables
3819 @subsection Paper variables
3820 @cindex Paper variables
3822 The paper block has some variables you may want to use or change:
3825 @cindex @code{indent}
3827 The indentation of the first line of music.
3828 @cindex @code{staffspace}
3830 @item @code{staffspace}
3831 The distance between two staff lines, calculated from the center
3834 @cindex @code{linewidth}
3835 @item @code{linewidth}
3836 Sets the width of the lines.
3838 If set to a negative value, a single unjustified line is produced.
3839 @c rename to singleLinePaper ?
3840 The shorthand @code{\singleLine} defines a default paper block that
3841 produces a single line.
3843 @cindex @code{textheight}
3845 @item @code{textheight}
3846 Sets the total height of the music on each page. Only used by
3849 @cindex @code{interscoreline}
3851 @item @code{interscoreline}
3852 Sets the spacing between systems. The default is 16pt.
3854 @cindex @code{interscorelinefill}
3856 @item @code{interscorelinefill}
3857 If set to a positive number, the distance between the score
3858 lines will stretch in order to fill the full page. In that
3859 case @code{interscoreline} specifies the minimum spacing.
3864 @cindex @code{stafflinethickness}
3866 @item @code{stafflinethickness}
3867 Determines the thickness of staff lines, and also acts as a scaling
3868 parameter for other line thicknesses.
3871 You may enter these dimension using units (@code{cm}, @code{in},
3872 @code{mm}, @code{pt}), or relative to another dimension
3874 linewidth = 20.0 * \staffspace
3881 @subsection Font size
3882 @cindex font size, setting
3883 @cindex staff size, setting
3884 @cindex @code{paper} file
3886 The Feta font provides musical symbols at six different sizes. These
3887 fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
3888 point. The point size of a font is the height of the five lines in a
3889 staff when displayed in the font.
3891 Definitions for these sizes are the files @file{paperSZ.ly}, where
3892 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3893 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3894 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3895 @code{paperTwentysix} are defined respectively. The default
3896 @code{\paper} block is also set. These files should be imported at toplevel, i.e.
3898 \include "paper26.ly"
3902 The font definitions are generated using a Scheme function. For more
3903 details, see the file @file{scm/font.scm}.
3909 @subsection Paper size
3914 @cindex @code{papersize}
3916 To change the paper size, you must first set the
3917 @code{papersize} paper variable variable. Set it to
3918 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3919 specification, you must set the font as described above. If you want
3920 the default font, then use the 20 point font.
3923 \paper@{ papersize = "a4" @}
3924 \include "paper16.ly"
3927 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3928 will set the paper variables @code{hsize} and @code{vsize} (used by
3929 Lilypond and @code{ly2dvi})
3933 @subsection Line break
3936 @cindex breaking lines
3938 Line breaks are normally computed automatically. They are chosen such
3939 that it looks neither cramped nor loose, and that consecutive lines have
3942 Occasionally you might want to override the automatic breaks; you can do
3943 this by specifying @code{\break}. This will force a line break at this
3944 point. Do remember that line breaks can only occur at places where there
3945 are bar lines. If you want to have a line break where there is no
3946 bar line, you can force an invisible bar line by entering @code{\bar
3947 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3949 If you want linebreaks at regular intervals, you can use the following:
3952 < \repeat 7 unfold @{ s1 * 4 \break @}
3956 This makes the following 28 measures (assuming 4/4 time) be broken every
3960 @cindex @code{\penalty}
3962 The @code{\break} and @code{\noBreak} commands are defined in terms of
3963 the penalty command:
3968 This encourages or discourages LilyPond to make a line break at this
3973 The scaling of the @code{\penalty} argument is not well-defined. The
3974 command is rather kludgey, and slated for rewriting.
3978 @subsection Page break
3981 @cindex breaking pages
3983 Page breaks are normally computed by @TeX{}, so they are not under
3984 direct control of LilyPond. However, you can insert a commands into the
3985 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3986 the command @code{\newpage}
3987 @cindex @code{\newpage}
3993 @c why do so difficult?
3994 @c maybe should explain contents of between-system.ly,
3995 @c but not now, we're talking about page breaks here.
3997 @c details, see the example file @file{input/test/between-systems.ly}
4000 @c . {Output scaling}
4001 @node Output scaling
4002 @subsection Output scaling
4017 There is no mechanism to select magnification of particular fonts,
4018 meaning that you don't have access to continuously scaled fonts.
4022 @c . {Output formats}
4023 @node Output formats
4024 @section Output formats
4026 LilyPond can output processed music in different output formats.
4030 * PostScript output::
4032 * ASCIIScript output::
4036 @subsection TeX output
4039 LilyPond will use @TeX{} by default. Even if you want to produce
4040 PostScript output for viewing or printing, you should normally have
4041 LilyPond produce @TeX{} first. The .tex output must be processed by
4042 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
4043 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
4044 used to generate the .dvi for you.
4048 Titling is not generated unless you use @file{ly2dvi}.
4051 @node PostScript output
4052 @subsection PostScript output
4053 @cindex PostScript output
4054 @cindex direct PostScript output
4056 LilyPond can produce PostScript directly, without going through @TeX{}.
4057 Currently, this is mainly useful if you cannot use TeX, because direct
4058 PostScript output has some problems; see Bugs below.
4061 $ lilypond -fps foo.ly
4062 GNU LilyPond 1.3.144
4063 Now processing: `foo.ly'
4065 Interpreting music...[3]
4066 Preprocessing elements...
4067 Calculating column positions...
4068 paper output to foo.ps...
4070 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
4076 Text font selection is broken.
4078 The .ps file does not contain the .pfa font files. To print a .ps
4079 created through direct postscript output, you should prepend the
4080 necessary .pfa files to LilyPond's .ps output, or upload them to the
4081 printer before printing.
4083 The line height calculation is broken, you must set @var{lineheight} in
4084 the paperblock if you have more than one staff in your score, e.g.
4089 % Set line height to 40 staff spaces
4095 @subsection Scheme output
4096 @cindex Scheme output
4098 In the typesetting stage, LilyPond builds a page description, which is
4099 then written to disk in postscript, @TeX{} or ASCII art. Before it is
4100 written, the page description is represented as Scheme expressions. You
4101 can also dump these Scheme expressions to a file, which may be
4102 convenient for debugging output routines. This is done with the Scheme
4106 $ lilypond -fscm foo.ly
4107 GNU LilyPond 1.3.144
4108 Now processing: `foo.ly'
4110 Interpreting music...[3]
4111 Preprocessing elements...
4112 Calculating column positions...
4113 paper output to foo.scm...
4116 ;;; Usage: guile -s x.scm > x.tex
4117 (primitive-load-path 'standalone.scm)
4121 $ guile -s foo.scm > foo.tex
4125 @node ASCIIScript output
4126 @subsection ASCIIScript output
4127 @cindex ASCIIScript output
4128 @cindex ascii script
4131 LilyPond can output ASCII Art. This is a two step process, LilyPond
4132 produces an ASCII description file, dubbed ASCIIScript (extension
4133 @file{.as}). ASCIIScript has a small and simple command set that
4134 includes font selection, character and string printing and line drawing
4135 commands. The program @file{as2text} is used to translate an .as file
4138 To produce ASCII Art, you must include an ASCII Art paper definition
4139 file in your .ly, one of:
4141 \include "paper-as5.ly"
4142 \include "paper-as9.ly"
4145 Here's an example use for ASCII Art output (the example file
4146 @file{as-email.ly} is included in the LilyPond distribution), the staff
4147 symbol has been made invisible:
4150 $ lilypond -fas as-email.ly
4151 GNU LilyPond 1.3.144
4152 Now processing: `as-email.ly'
4154 Interpreting music...[3]
4155 Preprocessing elements...
4156 Calculating column positions... [2]
4157 paper output to as-email.as...
4159 $ as2text as-email.as 2>/dev/null
4161 |/ |##|##| | | | | |
4162 /| | | | | |\ |\ |\ |\ |\ |
4163 / |_ 3 | | | | 5 | )| )| )| )| )|
4164 | /| \ 8 * * * | 8 * * * * * |
4174 The ASCII Art fonts are far from complete and not very well designed.
4175 It's easy to change the glyphs, though; if you think you can do better,
4176 have a look at @file{mf/*.af}.
4178 Lots of resizable symbols such as slurs, ties and tuplets are missing.
4180 The poor looks of most ASCII Art output and its limited general
4181 usefulness gives ASCII Art output a low priority; it may be
4182 dropped in future versions.
4189 LilyPond can produce MIDI output. The performance lacks lots of
4190 interesting effects, such as swing, articulation, slurring, etc., but it
4191 is good enough for proof-hearing the music you have entered. Ties,
4192 dynamics and tempo changes are interpreted.
4194 Dynamic marks, crescendi and decrescendi translate into MIDI volume
4195 levels. Dynamic marks translate to a fixed fraction of the available
4196 MIDI volume range, crescendi and decrescendi make the the volume vary
4197 linearly between their two extremities. The fractions be adjusted by
4198 overriding the @code{absolute-volume-alist} defined in
4199 @file{scm/midi.scm}.
4201 For each type of musical instrument (that MIDI supports), a volume range
4202 can be defined. This gives you basic equalizer control, which can
4203 enhance the quality of the MIDI output remarkably. You can add
4204 instruments and ranges or change the default settings by overriding the
4205 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
4207 Both loudness controls are combined to produce the final MIDI volume.
4212 It is currently not possible to use the percussion channel (generally
4213 channel 10 of a MIDI file).
4217 * MIDI instrument names::
4222 @subsection MIDI block
4226 The MIDI block is analogous to the paper block, but it is somewhat
4227 simpler. The @code{\midi} block can contain:
4231 @item a @code{\tempo} definition
4232 @item context definitions
4235 Assignments in the @code{\midi} block are not allowed.
4239 @cindex context definition
4241 Context definitions follow precisely the same syntax as within the
4242 \paper block. Translation modules for sound are called performers.
4243 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
4246 @node MIDI instrument names
4247 @subsection MIDI instrument names
4249 @cindex instrument names
4250 @cindex @code{Staff.midiInstrument}
4251 @cindex @code{Staff.instrument}
4253 The MIDI instrument name is set by the @code{Staff.midiInstrument}
4254 property or, if that property is not set, the @code{Staff.instrument}
4255 property. The instrument name should be chosen from the list in
4256 @ref{MIDI instruments}.
4260 If the selected string does not exactly match, then LilyPond uses the
4261 default (Grand Piano). It is not possible to select an instrument by
4271 @c FIXME: Note entry vs Music entry at top level menu is confusing.
4274 @section Music entry
4282 When entering music with LilyPond, it is easy to introduce errors. This
4283 section deals with tricks and features that help you enter music, and
4284 find and correct mistakes.
4288 @subsection Relative
4290 @cindex relative octave specification
4292 Octaves are specified by adding @code{'} and @code{,} to pitch names.
4293 When you copy existing music, it is easy to accidentally put a pitch in
4294 the wrong octave and hard to find such an error. To prevent these
4295 errors, LilyPond features octave entry.
4297 @cindex @code{\relative}
4299 \relative @var{startpitch} @var{musicexpr}
4302 The octave of notes that appear in @var{musicexpr} are calculated as
4303 follows: If no octave changing marks are used, the basic interval
4304 between this and the last note is always taken to be a fourth or less
4305 (This distance is determined without regarding alterations; a
4306 @code{fisis} following a @code{ceses} will be put above the
4309 The octave changing marks @code{'} and @code{,} can be added to raise or
4310 lower the pitch by an extra octave. Upon entering relative mode, an
4311 absolute starting pitch must be specified that will act as the
4312 predecessor of the first note of @var{musicexpr}.
4314 Entering music that changes octave frequently is easy in relative mode.
4315 @lilypond[fragment,singleline,verbatim,center]
4321 And octave changing marks are used for intervals greater than a fourth.
4322 @lilypond[fragment,verbatim,center]
4324 c g c f, c' a, e'' }
4327 If the preceding item is a chord, the first note of the chord is used
4328 to determine the first note of the next chord. However, other notes
4329 within the second chord are determined by looking at the immediately
4332 @lilypond[fragment,verbatim,center]
4339 @cindex @code{\notes}
4341 The pitch after the @code{\relative} contains a note name. To parse
4342 the pitch as a note name, you have to be in note mode, so there must
4343 be a surrounding @code{\notes} keyword (which is not
4346 The relative conversion will not affect @code{\transpose},
4347 @code{\chords} or @code{\relative} sections in its argument. If you
4348 want to use relative within transposed music, you must place an
4349 additional @code{\relative} inside the @code{\transpose}.
4354 @subsection Bar check
4358 @cindex @code{barCheckNoSynchronize}
4362 Whenever a bar check is encountered during interpretation, a warning
4363 message is issued if it doesn't fall at a measure boundary. This can
4364 help you find errors in the input. Depending on the value of
4365 @code{barCheckNoSynchronize}, the beginning of the measure will be
4366 relocated, so this can also be used to shorten measures.
4368 A bar check is entered using the bar symbol, @code{|}:
4370 \time 3/4 c2 e4 | g2.
4375 @cindex skipTypesetting
4377 Failed bar checks are most often caused by entering incorrect
4378 durations. Incorrect durations often completely garble up the score,
4379 especially if it is polyphonic, so you should start correcting the score
4380 by scanning for failed bar checks and incorrect durations. To speed up
4381 this process, you can use @code{skipTypesetting} (See @ref{Skipping
4382 corrected music})). Bar
4385 @c . {Point and click}
4386 @node Point and click
4387 @subsection Point and click
4389 Point and click lets you find notes in the input by clicking on them in
4390 the Xdvi window. This makes it very easy to find input that causes some
4391 error in the sheet music.
4393 To use it, you need the following software
4395 @unnumberedsubsec Installation
4399 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
4400 Xdvi} version 22.36 or newer.
4402 Note that most @TeX{} distributions ship with xdvik, which is a
4403 different and less well maintained program. To find out which xdvi you
4404 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
4408 Xdvi must be configured to find the TeX fonts and music
4409 fonts. Refer to the Xdvi documentation for more information.
4412 @unnumberedsubsec Using it
4414 Add one of these lines to the top of your .ly file. The first one is for
4415 line location only. The second one is more convenient, but requires
4416 patching @code{emacsclient} and @code{server.el}.
4419 #(set! point-and-click line-location)
4422 In the emacs startup file (usually @file{~/.emacs}), add the following
4427 Make sure that the environment variable @code{XEDITOR} is set
4430 emacsclient --no-wait +%l %f
4432 The second one, that also specifies the column, only works if you have
4433 patched your emacsclient and server, and have compiled your @code{.ly}
4434 file using the @code{line-column-location} setting.
4436 When viewing, control-mousebutton 1 will take you to the originating
4437 spot in the @file{.ly} file. Control-mousebutton 2 will show all
4441 @unnumberedsubsec Column location
4443 If you want emacs to jump to the exact spot (and not just the line) on a
4444 click, you must enable column positioning. To do so, you need to patch
4445 emacsclient. Apply @file{emacsclient.patch} (included with the source
4446 package) to @file{emacsclient.c} and @file{server.el} from the emacs
4447 source code. Recompile and stick the recompiled emacsclient into a bin
4448 directory, and put @file{server.el} into a elisp directory
4449 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
4450 init file, before invoking server-start.
4453 (setq load-path (cons "~/usr/share/emacs" load-path))
4456 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
4458 At the top of the @code{ly} file, replace the @code{set!} line with the
4461 #(set! point-and-click line-column-location)
4464 One final hint: if you correct large files with point-and-click, then
4465 start correcting at the end of the file. When you start at the top, and
4466 insert one line, all subsequent locations will be off by a line.
4471 When you convert the @TeX{} file to PostScript using @code{dvips}, it
4472 will complain about not finding @code{src:X:Y} files. Those complaints
4473 are harmless, and can be ignored.
4475 @node Skipping corrected music
4476 @section Skipping corrected music
4478 The property @code{Score.skipTypesetting} can be used to switch on and
4479 off typesetting completely during the interpretation phase. When
4480 typesetting is switched off, the music is processed much more quickly.
4481 You can use this to skip over the parts of a score that you have already
4484 @lilypond[fragment,singleline,verbatim]
4485 \relative c'' { c8 d
4486 \property Score.skipTypesetting = ##t
4488 \property Score.skipTypesetting = ##f
4493 @node Interpretation context
4494 @section Interpretation context
4497 * Creating contexts::
4498 * Default contexts::
4499 * Context properties::
4500 * Engravers and performers::
4501 * Changing context definitions::
4502 * Defining new contexts::
4506 Interpretation contexts are objects that only exist during a run of
4507 LilyPond. During the interpretation phase of LilyPond (when it prints
4508 "interpreting music"), the music expression in a @code{\score} block is
4509 interpreted in time order. This is the same order that humans hear and
4512 During this interpretation, the interpretation context holds the
4513 state for the current point within the music. It contains information
4517 @item What notes are playing at this point?
4518 @item What symbols will be printed at this point?
4519 @item What is the current key signature, time signature, point within
4523 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4524 contained in a @internalsref{Staff} context (because a staff can contain
4525 multiple voices at any point), a @internalsref{Staff} context is contained in
4526 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4528 Contexts associated with sheet music output are called @emph{notation
4529 contexts}, those for sound output are called @emph{performance
4530 contexts}. The default definitions of the standard notation and
4531 performance contexts can be found in @file{ly/engraver-init.ly} and
4532 @file{ly/performer-init.ly}, respectively.
4534 @node Creating contexts
4535 @subsection Creating contexts
4537 @cindex @code{\context}
4538 @cindex context selection
4540 Contexts for a music expression can be selected manually, using the
4541 following music expression.
4544 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4547 This instructs lilypond to interpret @var{musicexpr} within the context
4548 of type @var{contexttype} and with name @var{contextname}. If this
4549 context does not exist, it will be created.
4551 @lilypond[verbatim,singleline]
4553 \notes \relative c'' {
4554 c4 <d4 \context Staff = "another" e4> f
4560 In this example, the @code{c} and @code{d} are printed on the
4561 default staff. For the @code{e}, a context Staff called
4562 @code{another} is specified; since that does not exist, a new
4563 context is created. Within @code{another}, a (default) Voice context
4564 is created for the @code{e4}. When all music referring to a
4565 context is finished, the context is ended as well. So after the
4566 third quarter, @code{another} is removed.
4570 @node Default contexts
4571 @subsection Default contexts
4573 Most music expressions don't need an explicit @code{\context}
4574 declaration: they inherit the
4575 notation context from their parent. Each note is a music expression, and
4576 as you can see in the following example, only the sequential music
4577 enclosing the three notes has an explicit context.
4579 @lilypond[verbatim,singleline]
4580 \score { \notes \context Voice = goUp { c'4 d' e' } }
4583 There are some quirks that you must keep in mind when dealing with
4586 First, every top level music is interpreted by the Score context, in other
4587 words, you may think of @code{\score} working like
4590 \context Score @var{music}
4594 Second, contexts are created automatically to be able to interpret the
4595 music expressions. Consider the following example.
4597 @lilypond[verbatim, singleline]
4598 \score { \context Score \notes { c'4 ( d' )e' } }
4601 The sequential music is interpreted by the Score context initially
4602 (notice that the @code{\context} specification is redundant), but when a
4603 note is encountered, contexts are setup to accept that note. In this
4604 case, a Thread, Voice and Staff are created. The rest of the sequential
4605 music is also interpreted with the same Thread, Voice and Staff context,
4606 putting the notes on the same staff, in the same voice.
4608 This is a convenient mechanism, but do not expect opening chords to work
4609 without @code{\context}. For every note, a separate staff is
4612 @cindex explicit context
4613 @cindex starting with chords
4614 @cindex chords, starting with
4616 @lilypond[verbatim, singleline]
4617 \score { \notes <c'4 es'> }
4620 Of course, if the chord is preceded by a normal note in sequential
4621 music, the chord will be interpreted by the Thread of the preceding
4623 @lilypond[verbatim,singleline]
4624 \score { \notes { c'4 <c'4 es'> } }
4629 @node Context properties
4630 @subsection Context properties
4632 Notation contexts have properties. These properties are from
4633 the @file{.ly} file using the following expression:
4634 @cindex @code{\property}
4636 \property @var{contextname}.@var{propname} = @var{value}
4639 Sets the @var{propname} property of the context @var{contextname} to the
4640 specified Scheme expression @var{value}. All @var{propname} and
4641 @var{contextname} are strings, which are typically unquoted.
4643 Properties that are set in one context are inherited by all of the
4644 contained contexts. This means that a property valid for the
4645 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4646 example) and thus take effect in all @internalsref{Voice} contexts.
4648 Properties can be unset using the following expression:
4650 \property @var{contextname}.@var{propname} \unset
4653 @cindex properties, unsetting
4654 @cindex @code{\unset}
4656 This removes the definition of @var{propname} in @var{contextname}. If
4657 @var{propname} was not defined in @var{contextname} (but was inherited
4658 from a higher context), then this has no effect.
4663 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4664 the inverse of @code{\property \set}.
4666 @node Engravers and performers
4667 @subsection Engravers and performers
4671 Basic building blocks of translation are called engravers; they are
4672 special C++ classes.
4676 @c . {Context definitions}
4677 @node Changing context definitions
4678 @subsection Changing context definitions
4680 @cindex context definition
4681 @cindex translator definition
4683 The most common way to define a context is by extending an existing
4684 context. You can change an existing context from the paper block, by
4685 first initializing a translator with an existing context identifier:
4689 @var{context-identifier}
4692 Then you can add and remove engravers using the following syntax:
4694 \remove @var{engravername}
4695 \consists @var{engravername}
4699 Here @var{engravername} is a string, the name of an engraver in the
4703 @lilypond[verbatim,singleline]
4707 \translator { \StaffContext
4708 \remove Clef_engraver
4714 You can also set properties in a translator definition. The syntax is as
4717 @var{propname} = @var{value}
4718 @var{propname} \set @var{grob-propname} = @var{pvalue}
4719 @var{propname} \override @var{grob-propname} = @var{pvalue}
4720 @var{propname} \revert @var{grob-propname}
4722 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4723 and @code{pvalue} are Scheme expressions. These type of property
4724 assignments happen before interpretation starts, so a @code{\property}
4725 command will override any predefined settings.
4728 To simplify editing translators, all standard contexts have standard
4729 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4730 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
4732 @node Defining new contexts
4733 @subsection Defining new contexts
4735 If you want to build a context from scratch, you must also supply the
4736 following extra information:
4738 @item A name, specified by @code{\name @var{contextname}}.
4740 @item A cooperation module. This is specified by @code{\type
4747 \type "Engraver_group_engraver"
4750 \consists "Staff_symbol_engraver"
4751 \consists "Note_head_engraver"
4752 \consistsend "Axis_group_engraver"
4756 The argument of @code{\type} is the name for a special engraver that
4757 handles cooperation between simple engravers such as
4758 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4759 for this engraver are the following:
4761 @cindex @code{Engraver_group_engraver}
4762 @item @code{Engraver_group_engraver}
4763 The standard cooperation engraver.
4765 @cindex @code{Score_engraver}
4767 @item @code{Score_engraver}
4768 This is cooperation module that should be in the top level context,
4769 and only the top level context.
4771 @cindex @code{Grace_engraver_group}
4773 @item @code{Grace_engraver_group}
4774 This is a special cooperation module (resembling
4775 @code{Score_engraver}) that is used to create an embedded
4782 @item @code{\alias} @var{alternate-name}
4783 This specifies a different name. In the above example,
4784 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4786 @item @code{\consistsend} @var{engravername}
4787 Analogous to @code{\consists}, but makes sure that
4788 @var{engravername} is always added to the end of the list of
4791 Some engraver types need to be at the end of the list; this
4792 insures they stay there even if a user adds or removes engravers.
4793 End-users generally don't need this command.
4795 @item @code{\accepts} @var{contextname}
4796 Add @var{contextname} to the list of contexts this context can
4797 contain in the context hierarchy. The first listed context is the
4798 context to create by default.
4800 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4801 completeness, but is never used in practice.
4804 @item @code{\name} @var{contextname}
4805 This sets the type name of the context, e.g. @internalsref{Staff},
4806 @internalsref{Voice}. If the name is not specified, the translator won't do
4810 In the @code{\paper} block, it is also possible to define translator
4811 identifiers. Like other block identifiers, the identifier can only
4812 be used as the very first item of a translator. In order to define
4813 such an identifier outside of @code{\score}, you must do
4818 foo = \translator @{ @dots{} @}
4825 \translator @{ \foo @dots{} @}
4833 @cindex paper types, engravers, and pre-defined translators
4840 @c . {Syntactic details}
4841 @node Syntactic details
4842 @section Syntactic details
4843 @cindex Syntactic details
4845 This section describes details that were too boring to be put elsewhere.
4850 * Music expressions::
4851 * Manipulating music expressions::
4859 @subsection Top level
4862 This section describes what you may enter at top level.
4866 @subsubsection Score
4869 @cindex score definition
4871 The output is generated combining a music expression with an output
4872 definition. A score block has the following syntax:
4875 \score @{ @var{musicexpr} @var{outputdefs} @}
4878 @var{outputdefs} are zero or more output definitions. If none is
4879 supplied, the default @code{\paper} block will be added.
4883 @c . {Default output}
4884 @subsubsection Default output
4886 Default values for the @code{\paper} and @code{\midi} block are set by
4887 entering such a block at the top level.
4890 @subsubsection Header
4892 @cindex @code{\header}
4895 A header describes bibliographic information of the file's contents. It
4896 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4897 use this information for generating titles. Key values that are used by
4898 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4899 meter, arranger, piece and tagline.
4901 @cindex @code{ly2dvi}
4905 \header @{ @var{key1} = @var{val1}
4906 @var{key2} = @var{val2} @dots{} @}
4909 It is customary to put the @code{\header} at the top of the file.
4911 @subsubsection Default output
4913 A @code{\midi} or @code{\paper} block at top level sets the default
4914 paper block for all scores that lack an explicit paper block.
4918 @subsection Identifiers
4922 What has this section got to do with identifiers?
4923 It seems more appropriate in the introduction to Chapter 4,
4929 All of the information in a LilyPond input file, is internally
4930 represented as a Scheme value. In addition to normal Scheme data types
4931 (such as pair, number, boolean, etc.), LilyPond has a number of
4932 specialized data types,
4939 @item Translator_def
4943 @item Music_output_def
4944 @item Moment (rational number)
4947 LilyPond also includes some transient object types. Objects of these
4948 types are built during a LilyPond run, and do not `exist' per se within
4949 your input file. These objects are created as a result of your input
4950 file, so you can include commands in the input to manipulate them,
4951 during a lilypond run.
4954 @item Grob: short for Graphical object. See @ref{Grobs}.
4955 @item Molecule: device-independent page output object,
4956 including dimensions. Produced by some Grob functions
4958 @item Translator: object that produces audio objects or Grobs. This is
4959 not yet user accessible.
4960 @item Font_metric: object representing a font.
4964 @node Music expressions
4965 @subsection Music expressions
4967 @cindex music expressions
4969 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4970 syllables are music expressions, and you can combine music expressions
4971 to form new ones, for example by enclosing a list of expressions in
4972 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4973 compound expression is formed out of the quarter note @code{c} and a
4974 quarter note @code{d}:
4977 \sequential @{ c4 d4 @}
4980 @cindex Sequential music
4981 @cindex @code{\sequential}
4982 @cindex sequential music
4985 @cindex Simultaneous music
4986 @cindex @code{\simultaneous}
4988 The two basic compound music expressions are simultaneous and
4992 \sequential @code{@{} @var{musicexprlist} @code{@}}
4993 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4995 For both, there is a shorthand:
4997 @code{@{} @var{musicexprlist} @code{@}}
5001 @code{<} @var{musicexprlist} @code{>}
5003 for simultaneous music.
5004 In principle, the way in which you nest sequential and simultaneous to
5005 produce music is not relevant. In the following example, three chords
5006 are expressed in two different ways:
5008 @lilypond[fragment,verbatim,center]
5009 \notes \context Voice {
5010 <a c'> <b d' > <c' e'>
5011 < { a b c' } { c' d' e' } >
5016 Other compound music expressions include
5019 \transpose @var{pitch} @var{expr}
5020 \apply @var{func} @var{expr}
5021 \context @var{type} = @var{id} @var{expr}
5022 \times @var{fraction} @var{expr}
5026 @c . {Manipulating music expressions}
5027 @node Manipulating music expressions
5028 @subsection Manipulating music expressions
5030 The @code{\apply} mechanism gives you access to the internal
5031 representation of music. You can write Scheme-functions that operate
5032 directly on it. The syntax is
5034 \apply #@var{func} @var{music}
5036 This means that @var{func} is applied to @var{music}. The function
5037 @var{func} should return a music expression.
5039 This example replaces the text string of a script. It also shows a dump
5040 of the music it processes, which is useful if you want to know more
5041 about how music is stored.
5043 @lilypond[verbatim,singleline]
5044 #(define (testfunc x)
5045 (if (equal? (ly-get-mus-property x 'text) "foo")
5046 (ly-set-mus-property x 'text "bar"))
5048 (ly-set-mus-property x 'elements
5049 (map testfunc (ly-get-mus-property x 'elements)))
5054 \apply #testfunc { c'4_"foo" }
5058 For more information on what is possible, see the automatically
5059 generated documentation.
5062 Directly accessing internal representations is dangerous: the
5063 implementation is subject to changes, so you should avoid this feature
5066 A final example is a function that reverses a piece of music in time:
5068 @lilypond[verbatim,singleline]
5069 #(define (reverse-music music)
5070 (let* ((elements (ly-get-mus-property music 'elements))
5071 (reversed (reverse elements))
5072 (span-dir (ly-get-mus-property music 'span-direction)))
5073 (ly-set-mus-property music 'elements reversed)
5075 (ly-set-mus-property music 'span-direction (- span-dir)))
5076 (map reverse-music reversed)
5079 music = \notes { c'4 d'4( e'4 f'4 }
5081 \score { \context Voice {
5083 \apply #reverse-music \music
5088 More examples are given in the distributed example files in
5091 @c . {Span requests}
5097 @subsubsection Span requests
5098 @cindex Span requests
5100 Notational constructs that start and end on different notes can be
5101 entered using span requests. The syntax is as follows:
5105 \spanrequest @var{startstop} @var{type}
5109 @cindex @code{\start}
5110 @cindex @code{\stop}
5112 This defines a spanning request. The @var{startstop} parameter is either
5113 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
5114 describes what should be started. Much of the syntactic sugar is a
5115 shorthand for @code{\spanrequest}, for example,
5117 @lilypond[fragment,verbatim,center]
5118 c'4-\spanrequest \start "slur"
5119 c'4-\spanrequest \stop "slur"
5122 Among the supported types are @code{crescendo}, @code{decrescendo},
5123 @code{beam}, @code{slur}. This is an internal command. Users are
5124 encouraged to use the shorthands which are defined in the initialization
5125 file @file{spanners.ly}.
5130 @subsection Assignments
5133 Identifiers allow objects to be assigned to names during the parse
5134 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
5135 and to refer to an identifier, you precede its name with a backslash:
5136 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
5137 the input-types listed above. Identifier assignments can appear at top
5138 level in the LilyPond file, but also in @code{\paper} blocks.
5140 An identifier can be created with any string for its name, but you will
5141 only be able to refer to identifiers whose names begin with a letter,
5142 being entirely alphabetical. It is impossible to refer to an identifier
5143 whose name is the same as the name of a keyword.
5145 The right hand side of an identifier assignment is parsed completely
5146 before the assignment is done, so it is allowed to redefine an
5147 identifier in terms of its old value, e.g.
5153 When an identifier is referenced, the information it points to is
5154 copied. For this reason, an identifier reference must always be the
5155 first item in a block.
5159 \paperIdent % wrong and invalid
5163 \paperIdent % correct
5168 @c . {Lexical modes}
5170 @subsection Lexical modes
5171 @cindex Lexical modes
5174 @cindex @code{\notes}
5175 @cindex @code{\chords}
5176 @cindex @code{\lyrics}
5178 To simplify entering notes, lyrics, and chords, LilyPond has three
5179 special input modes in addition to the default mode: note, lyrics and
5180 chords mode. These input modes change the way that normal, unquoted
5181 words are interpreted: for example, the word @code{cis} may be
5182 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
5183 major triad respectively.
5185 A mode switch is entered as a compound music expression
5187 @code{\notes} @var{musicexpr}
5188 @code{\chords} @var{musicexpr}
5189 @code{\lyrics} @var{musicexpr}.
5192 In each of these cases, these expressions do not add anything to the
5193 meaning of their arguments. They just instruct the parser in what mode
5194 to parse their arguments. The modes are treated in more detail in
5195 @ref{Lyrics} and @ref{Chords}.
5197 Different input modes may be nested.
5201 @subsection Ambiguities
5206 The grammar contains a number of ambiguities. We hope to resolve them at
5210 @item The assignment
5215 is interpreted as the string identifier assignment. However,
5216 it can also be interpreted as making a string identifier @code{\foo}
5217 containing @code{"bar"}, or a music identifier @code{\foo}
5218 containing the syllable `bar'.
5220 @item If you do a nested repeat like
5232 then it is ambiguous to which @code{\repeat} the
5233 @code{\alternative} belongs. This is the classic if-then-else
5234 dilemma. It may be solved by using braces.
5236 @item The parser is not sophisticated enough to distinguish at the
5238 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
5245 @c . {Lexical details}
5246 @node Lexical details
5247 @section Lexical details
5249 Even more boring details, now on lexical side of the input parser.
5260 * Version information::
5265 @subsection Comments
5268 @cindex block comment
5269 @cindex line comment
5273 A one line comment is introduced by a @code{%} character.
5274 Block comments are started by @code{%@{} and ended by @code{%@}}.
5275 They cannot be nested.
5278 @subsection Direct Scheme
5282 @cindex Scheme, in-line code
5285 LilyPond contains a Scheme interpreter (the GUILE library) for
5286 internal use. In some places, Scheme expressions also form valid syntax:
5287 wherever it is allowed,
5291 evaluates the specified Scheme code. Example:
5293 \property Staff.TestObject \override #'foobar = #(+ 1 2)
5295 @code{\override} expects two Scheme expressions, so there are two Scheme
5296 expressions. The first one is a symbol (@code{foobar}), the second one
5297 an integer (namely, 3).
5299 In-line scheme may be used at the top level. In this case the result is
5302 Scheme is a full-blown programming language, and a full discussion is
5303 outside the scope of this document. Interested readers are referred to
5304 the website @uref{http://www.schemers.org/} for more information on
5309 @subsection Keywords
5313 Keywords start with a backslash, followed by a number of lower case
5314 alphabetic characters. These are all the keywords.
5317 apply arpeggio autochange spanrequest commandspanrequest
5318 simultaneous sequential accepts alternative bar breathe
5319 char chordmodifiers chords clef cm consists consistsend
5320 context denies duration dynamicscript elementdescriptions
5321 font grace header in lyrics key mark pitch
5322 time times midi mm name pitchnames notes outputproperty
5323 override set revert partial paper penalty property pt
5324 relative remove repeat addlyrics partcombine score
5325 script stylesheet skip textscript tempo translator
5330 @subsection Integers
5338 Formed from an optional minus sign followed by digits. Arithmetic
5339 operations cannot be done with integers, and integers cannot be mixed
5344 @cindex real numbers
5350 Formed from an optional minus sign and a sequence of digits followed
5351 by a @emph{required} decimal point and an optional exponent such as
5352 @code{-1.2e3}. Reals can be built up using the usual operations:
5353 `@code{+}', `@code{-}', `@code{*}', and
5354 `@code{/}', with parentheses for grouping.
5362 A real constant can be followed by one of the dimension keywords:
5363 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5364 points, inches and centimeters, respectively. This converts the number
5365 a number that is the internal representation of that dimension.
5373 Begins and ends with the @code{"} character. To include a @code{"}
5374 character in a string write @code{\"}. Various other backslash
5375 sequences have special interpretations as in the C language. A string
5376 that contains no spaces can be written without the quotes. Strings can
5377 be concatenated with the @code{+} operator.
5381 @subsection Main input
5384 @cindex @code{\maininput}
5386 The @code{\maininput} command is used in init files to signal that the
5387 user file must be read. This command cannot be used in a user file.
5389 @node File inclusion
5390 @subsection File inclusion
5391 @cindex @code{\include}
5393 \include @var{filename}
5396 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5397 unquoted string will not work here!) or a string identifier. The full
5398 filename including the @file{.ly} extension must be given,
5401 @node Version information
5402 @subsection Version information
5403 @cindex @code{\version}
5405 \version @var{string}
5408 Specify the version of LilyPond that a file was written for. The
5409 argument is a version string in quotes, for example @code{"1.2.0"}.
5410 This is used to detect invalid input, and to aid
5411 @code{convert-ly} a tool that automatically upgrades input files. See
5412 See @ref{convert-ly} for more information on @code{convert-ly}.
5420 @c broken with emacs-21
5421 @c {Local emac s vars}
5422 @c Local varia bles:
5424 @c minor-mod e: font-lock
5425 @c minor-mo de: outline
5426 @c outline -layout: (-1 : 0)
5427 @c outlin e-use-mode-specific-leader: "@c \."
5428 @c outli ne-primary-bullet: "{"
5429 @c outli ne-stylish-prefixes: nil
5430 @c outli ne-override-protect: t