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
862 #'merge-differently-dotted = ##t
864 } \\ { [g'8. f16] [g'8. f'16] }
868 Similarly, you can merge half note heads with eighth notes, by setting
869 @code{merge-differently-headed}:
870 @lilypond[fragment, relative=2,verbatim]
871 \apply #voicify-music < {
873 \property Staff.NoteCollision
874 \override #'merge-differently-headed = ##t
875 c8 c4. } \\ { c2 c2 } >
878 LilyPond also vertically shifts rests that are opposite of a stem.
880 @lilypond[singleline,fragment,verbatim]
881 \context Voice \apply #voicify-music <
886 Note head collisions (horizontal shifting of note heads) are handled by
887 the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
888 handles vertical shifting of rests.
894 Resolving collisions is a very intricate subject, and LilyPond only
895 handles a few situations. When it can not cope, you are advised to use
896 @code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
897 rests to override typesetting decisions.
902 Beams are used to group short notes into chunks that are aligned with
903 the metrum. They are inserted automatically in most cases.
905 @lilypond[fragment,verbatim, relative=2]
906 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
909 If you're not satisfied with the automatic beaming, you can enter the
910 beams explicitly. If you have beaming patterns that differ from the
911 defaults, you can also set the patterns for automatic beamer.
913 The beam symbol is @internalsref{Beam} in @internalsref{Voice}
914 context, both for automatically created and manual beams.
917 @cindex Automatic beams
918 @subsection Manual beams
919 @cindex beams, manual
923 In some cases it may be necessary to override LilyPond's automatic
924 beaming algorithm. For example, the auto beamer will not beam over
925 rests or bar lines, If you want that, specify the begin and end point
926 manually using a @code{[} before the first beamed note and a @code{]}
929 @lilypond[fragment,relative,verbatim]
931 r4 [r8 g' a r8] r8 [g | a] r8
935 @cindex @code{stemLeftBeamCount}
937 Normally, beaming patterns within a beam are determined automatically.
938 When this mechanism fouls up, the properties
939 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
940 be used to control the beam subdivision on a stem. If you set either
941 property, it's value will be used only once, and then it is erased.
943 @lilypond[fragment,relative,verbatim]
946 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
949 @cindex @code{stemRightBeamCount}
952 TODO: FIXME, we don't want this doc here.
954 can be tweaked through
955 grob-property @code{positions}. The value is a pair.
956 specify vertical location of the left and right end point. Both are
957 measured in half staff-spaces, and the middle staff line is the value
960 @li lypond[fragment,relative,verbatim]
961 \property Voice.Beam \set #'position = #
962 \property Voice.Beam \set #'height = #0
966 Here's how you'd specify a weird looking beam that instead of being
967 horizontal, falls two staff spaces:
973 @li lypond[fragment,relative,verbatim]
974 \property Voice.Beam \set #'staff-position = #4
975 \property Voice.Beam \set #'height = #-4
982 Kneed beams are inserted automatically, when a large gap between two
983 adjacent beamed notes is detected. This behavior can be tuned through
984 the grob property @code{auto-knee-gap}.
988 @cindex auto-knee-gap
992 @c TODO -> why this ref? Document?
993 @cindex @code{neutral-direction}
997 Auto knee beams can not be used together with hara kiri staffs.
1001 * Setting automatic beam behavior ::
1004 @node Beam typography
1005 @subsection Beam typography
1007 One of the strong points of LilyPond is how beams are formatted. Beams
1008 are quantized, meaning that the left and right endpoints beams start
1009 exactly on staff lines. Without quantization, small wedges of white
1010 space appear between the beam and staff line, and this looks untidy.
1012 Beams are also slope-damped: melodies that go up or down should also
1013 have beams that go up or down, but the slope of the beams should be
1014 less than the slope of the notes themselves.
1016 Some beams should be horizontal. These are so-called concave beams.
1018 [TODO: some pictures.]
1021 @c . {Automatic beams}
1022 @node Setting automatic beam behavior
1023 @subsection Setting automatic beam behavior
1025 @cindex @code{autoBeamSettings}
1026 @cindex @code{(end * * * *)}
1027 @cindex @code{(begin * * * *)}
1028 @cindex automatic beams, tuning
1029 @cindex tuning automatic beaming
1031 In normal time signatures, automatic beams can start on any note but can
1032 only end in a few positions within the measure: beams can end on a beat,
1033 or at durations specified by the properties in
1034 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
1035 are defined in @file{scm/auto-beam.scm}.
1037 The value of @code{autoBeamSettings} is changed using
1038 @code{\override} and unset using @code{\revert}:
1040 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
1041 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
1043 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
1044 whether the rule applies to begin or end-points. The quantity
1045 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
1046 *}' designates notes of any length), @var{N}/@var{M} refers to a time
1047 signature (wildcards, `@code{* *}' may be entered to designate all time
1050 For example, if you want automatic beams to end on every quarter note,
1051 you can use the following:
1053 \property Voice.autoBeamSettings \override
1054 #'(end * * * *) = #(make-moment 1 4)
1056 Since the duration of a quarter note is 1/4 of a whole note, it is
1057 entered as @code{(make-moment 1 4)}.
1059 The same syntax can be used to specify beam starting points. In this
1060 example, automatic beams can only end on a dotted quarter note.
1062 \property Voice.autoBeamSettings \override
1063 #'(end * * * *) = #(make-moment 3 8)
1065 In 4/4 time signature, this means that automatic beams could end only on
1066 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1067 3/8 has passed within the measure).
1069 You can also restrict rules to specific time signatures. A rule that
1070 should only be applied in @var{N}/@var{M} time signature is formed by
1071 replacing the second asterisks by @var{N} and @var{M}. For example, a
1072 rule for 6/8 time exclusively looks like
1074 \property Voice.autoBeamSettings \override
1075 #'(begin * * 6 8) = ...
1078 If you want a rule to apply to certain types of beams, you can use the
1079 first pair of asterisks. Beams are classified according to the shortest
1080 note they contain. For a beam ending rule that only applies to beams
1081 with 32nd notes (and no shorter notes), you would use @code{(end 1
1085 @c Automatic beams can not be put on the last note in a score.
1087 If a score ends while an automatic beam has not been ended and is still
1088 accepting notes, this last beam will not be typeset at all.
1090 @cindex automatic beam generation
1092 @cindex @code{Voice.autoBeaming}
1095 For melodies that have lyrics, you may want to switch off
1096 automatic beaming. This is done by setting @code{Voice.autoBeaming} to
1102 It is not possible to specify beaming parameters for beams with mixed
1103 durations, that differ from the beaming parameters of all separate
1104 durations, i.e., you'll have to specify manual beams to get:
1105 @lilypond[fragment,singleline,relative]
1106 \property Voice.autoBeamSettings
1107 \override #'(end * * * *) = #(make-moment 3 8)
1108 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
1111 It is not possible to specify beaming parameters that act differently in
1112 different parts of a measure. This means that it is not possible to use
1113 automatic beaming in irregular meters such as @code{5/8}.
1116 @node Expressive marks
1117 @section Expressive marks
1132 A slur indicates that notes are to be played bound or @emph{legato}.
1133 They are entered using parentheses:
1134 @lilypond[fragment,verbatim,center]
1135 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1138 The grob for this object is @internalsref{Slur}, generally in
1139 @internalsref{Voice} context.
1141 Slurs avoid crossing stems, and are generally attached to note heads.
1142 However, in some situations with beams, slurs may be attached to stem
1143 ends. If you want to override this layout you can do this through the
1144 grob-property @code{attachment} of @internalsref{Slur} in
1145 @internalsref{Voice} context It's value is a pair of symbols, specifying
1146 the attachment type of the left and right end points.
1148 @lilypond[fragment,relative,verbatim]
1150 \property Voice.Stem \set #'length = #5.5
1152 \property Voice.Slur \set #'attachment = #'(stem . stem)
1156 If a slur would strike through a stem or beam, the slur will be moved
1157 away upward or downward. If this happens, attaching the slur to the
1158 stems might look better:
1160 @lilypond[fragment,relative,verbatim]
1163 \property Voice.Slur \set #'attachment = #'(stem . stem)
1168 Similarly, the curvature of a slur is adjusted to stay clear of note
1169 heads and stems. When that would increase the curvature too much, the
1170 slur is reverted to its default shape. The threshold for this decision
1171 is in @internalsref{Slur}'s grob-property @code{beautiful}. It is loosely
1172 related to the enclosed area between the slur and the notes. Usually,
1173 the default setting works well, but in some cases you may prefer a
1174 curved slur when LilyPond decides for a vertically moved one. You can
1175 indicate this preference by increasing the @code{beautiful} value:
1177 @lilypond[verbatim,singleline,relative]
1179 c16( a' f' a a f a, )c,
1180 c( a' f' a a f d, )c
1181 \property Voice.Slur \override #'beautiful = #5.0
1182 c( a' f' a a f d, )c
1187 Producing nice slurs is a difficult problem, and LilyPond currently
1188 uses a simple, empiric method to produce slurs. In some cases, the
1189 results of this method don't look too good. This is reflected by the
1190 @code{beautiful} property, which it is an arbitrary parameter in the
1191 slur formatter. Useful values can only be determined by trial and
1194 @cindex Adjusting slurs
1196 @node Phrasing slurs
1197 @subsection Phrasing slurs
1199 @cindex phrasing slurs
1200 @cindex phrasing marks
1202 A phrasing slur (or phrasing mark) connects chords and is used to
1203 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1206 @lilypond[fragment,verbatim,center,relative]
1207 \time 6/4 c' \( ( d ) e f ( e ) \) d
1210 Typographically, the phrasing slur behaves almost exactly like a normal
1211 slur. The grob associated with it is @internalsref{PhrasingSlur}, in
1212 @internalsref{Voice} context.
1215 @subsection Breath marks
1217 Breath marks are entered using @code{\breathe}. The result is a
1218 @internalsref{BreathingSign} grob in @internalsref{Voice} context.
1220 @lilypond[fragment,relative]
1229 @cindex beats per minute
1230 @cindex metronome marking
1232 Metronome settings can be entered as follows:
1234 @cindex @code{\tempo}
1236 \tempo @var{duration} = @var{perminute}
1239 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1244 The tempo setting is not printed, but is only used in the MIDI
1245 output. You can trick lily into producing a metronome mark,
1246 though. Details are in @ref{Text markup}.
1251 @subsection Text spanners
1252 @cindex Text spanners
1254 Some textual indications, e.g. rallentando or accelerando, often extend
1255 over many measures. This is indicated by following the text with a
1256 dotted line. You can create such texts using text spanners. The syntax
1259 \spanrequest \start "text"
1260 \spanrequest \stop "text"
1262 LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
1263 in @internalsref{Voice} context). The string to be printed, as well as the
1264 style is set through grob properties.
1266 An application---or rather, a hack---is to fake octavation indications.
1267 @lilypond[fragment,relative,verbatim]
1268 \relative c' { a''' b c a
1269 \property Voice.TextSpanner \set #'type = #'dotted-line
1270 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1271 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1272 \property Staff.centralCPosition = #-13
1273 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1292 @subsection Articulations
1293 @cindex Articulations
1295 @cindex articulations
1299 A variety of symbols can appear above and below notes to indicate
1300 different characteristics of the performance. They are added to a note
1301 by adding @code{-}@var{script}
1302 @lilypond[singleline]
1304 \notes \context Voice {
1305 \property Voice.TextScript \set #'font-family = #'typewriter
1306 \property Voice.TextScript \set #'font-shape = #'upright
1312 c''4-^_"c-\\^{ }" s4
1317 The script is automatically placed, but if you need to force
1318 directions, you can use @code{_} to force them down, or @code{^} to
1320 @lilypond[fragment, verbatim]
1325 Other symbols can be added using the syntax
1326 @var{note}@code{-\}@var{name}. Again, they can be forced up or down
1327 using @code{^} and @code{_}.
1331 \property Score.LyricSyllable \override #'font-family =#'typewriter
1332 \property Score.LyricSyllable \override #'font-shape = #'upright
1333 \context Staff \notes {
1334 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1335 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1336 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1337 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1338 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1339 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1340 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1341 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1343 \context Lyrics \lyrics {
1344 accent__ marcato__ staccatissimo__ fermata
1345 stopped__ staccato__ tenuto__ upbow
1346 downbow__ lheel__ rheel__ ltoe
1347 rtoe__ turn__ open__ flageolet
1348 reverseturn__ trill__ prall__ mordent
1349 prallprall__ prallmordent__ uprall__ downprall
1350 upmordent__ downmordent__ pralldown__ prallup__
1351 lineprall__ thumb__ segno__ coda
1355 linewidth = 5.875\in
1364 Fingering instructions can also be entered in this shorthand. For
1365 finger changes, use markup texts:
1367 @lilypond[verbatim, singleline, fragment]
1368 c'4-1 c'4-2 c'4-3 c'4-4
1373 @cindex @code{\script}
1378 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
1382 All of these note ornaments appear in the printed output but have no
1383 effect on the MIDI rendering of the music.
1385 Unfortunately, there is no support for adding fingering instructions or
1386 ornaments to individual note heads. Some hacks exist, though. See
1387 @file{input/test/script-horizontal.ly}.
1392 @subsection Text scripts
1393 @cindex Text scripts
1395 In addition, it is possible to place arbitrary strings of text or markup
1396 text (see @ref{Text markup}) above or below notes by using a string:
1399 By default, these indications do not influence the note spacing, but
1400 by using the command @code{\fatText}, the widths will be taken into
1403 @lilypond[fragment,singleline,verbatim] \relative c' {
1404 c4^"longtext" \fatText c4_"longlongtext" c4 }
1407 Text scripts are created in form of @internalsref{TextScript} grobs, in
1408 @internalsref{Voice} context.
1410 @ref{Text markup} describes how to change the font or access
1411 special symbols in text scripts.
1414 @node Adding scripts
1415 @subsection Adding scripts
1417 TODO: should junk this subsect?
1419 You can add scripts by editing @file{scm/script.scm} and
1420 @file{ly/script-init.ly}. This file contains a table, listing script
1421 definitions and aliases. The following syntax accesses a script
1422 definition from the table:
1428 Usually the @code{\script} keyword is not used directly. Various
1429 helpful identifier definitions appear in @file{script.ly}.
1434 @subsection Grace notes
1438 @cindex @code{\grace}
1442 Grace notes are ornaments are written out ornaments
1443 @lilypond[relative=2,fragment]
1444 c4 \grace c16 c4 \grace { [c16 d16] } c4
1447 In normal notation, grace notes are supposed to take up no logical
1448 time in a measure. Such an idea is practical for normal notation, but
1449 is not strict enough to put it into a program. The model that LilyPond
1450 uses for grace notes internally is that all timing is done in two
1453 Every point in musical time consists of two rational numbers: one
1454 denotes the logical time, one denotes the grace timing. The above
1455 example is shown here with timing tuples.
1457 @lilypond[relative=2,fragment]
1458 c4^"(0,0)" \grace c16^"(1/4,-1/16)" c4^"(1/4,0)" \grace {
1459 [c16^"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4^"(2/4,0)"
1462 The advantage of this approach is that you can use almost any lilypond
1463 construction together with grace notes, for example slurs and clef
1464 changes may appear halfway in between grace notes:
1466 @lilypond[relative=2,fragment]
1467 c4 \grace { [ c16 c, \clef bass c, b(] } )c4
1470 The placement of these grace notes is synchronized between different
1471 staffs, using this grace timing.
1473 @lilypond[relative=2,fragment]
1474 \context Staff = SA { e4 \grace { c16 d e f } e4 }
1475 \context Staff = SB { c4 \grace { g8 b } c4 }
1479 The syntax is as follows.
1481 \grace @var{musicexpr}
1484 Unbeamed eighth notes and shorter by default have a slash through the
1487 @lilypond[fragment,verbatim]
1488 \relative c'' \context Voice {
1489 \grace c8 c4 \grace { [c16 c16] } c4
1491 \property Voice.Stem \override #'flag-style = #'()
1493 \property Voice.Stem \revert #'flag-style
1498 A grace note expression has duration 0; the next real note is assumed to
1499 be the main note. If you want the note to appear after the main note,
1500 set @code{Voice.graceAlignPosition} to @code{1}.
1505 Grace note synchronization can also lead to surprises. Staff notation,
1506 such as key signatures, barlines, etc. are also synchronized. Take
1507 care when you mix staffs with grace notes and staffs without.
1509 @lilypond[relative=2,fragment]
1510 \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
1511 \context Staff = SB { c4 \bar "|:" d4 }
1514 Nesting @code{\grace} notes is not supported. The following may cause
1518 @code{\grace @{ \grace c32 c16 @} c4}
1520 Since the meaning of such a construct is unclear, we don't consider this
1521 a loss. Similarly, juxtaposing two @code{\grace} sections is
1522 syntactically valid, but makes no sense and may cause runtime errors.
1523 Ending a staff or score with grace notes may also generate a run-time
1524 error, since there will be no main note to attach the grace notes to.
1535 @subsection Glissando
1538 @cindex @code{\glissando}
1540 A glissando line (grob @internalsref{Glissando}) can be requested by
1541 attaching a @code{\glissando} to a notte:
1543 @lilypond[fragment,relative,verbatim]
1549 Printing of an additional text (such as @emph{gliss.}) must be done
1556 @subsection Dynamics
1569 @cindex @code{\ffff}
1579 Absolute dynamic marks are specified using an identifier after a
1580 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1581 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1582 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1583 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1585 @lilypond[verbatim,singleline,fragment,relative]
1586 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1592 @cindex @code{\decr}
1593 @cindex @code{\rced}
1599 A crescendo mark is started with @code{\cr} and terminated with
1600 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1601 started with @code{\decr} and terminated with @code{\rced}. There are
1602 also shorthands for these marks. A crescendo can be started with
1603 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1604 can be terminated with @code{\!}. Note that @code{\!} must go before
1605 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1606 after the last note. Because these marks are bound to notes, if you
1607 want several marks during one note, you have to use spacer notes.
1609 @lilypond[fragment,verbatim,center]
1610 c'' \< \! c'' d'' \decr e'' \rced
1611 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1614 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1615 is an example how to do it:
1620 @lilypond[fragment,relative,verbatim]
1622 \property Voice.crescendoText = "cresc."
1623 \property Voice.crescendoSpanner = #'dashed-line
1628 For everyday use, we recommend the identifiers @code{\cresc},
1629 @code{endcresc}, @code{\dim} and @code{\enddim}.
1633 Dynamics are grobs of @internalsref{DynamicText} and
1634 @internalsref{Hairpin}. Vertical positioning of these symbols is
1635 handled by the @internalsref{DynamicLineSpanner} grob. If you want to
1636 adjust padding or vertical direction of the dynamics, you must set
1637 properties for the @internalsref{DynamicLineSpanner} grob. Predefined
1638 identifiers to set the vertical direction are \dynamicUp and
1641 @cindex direction, of dynamics
1642 @cindex @code{\dynamicDown}
1643 @cindex @code{\dynamicUp}
1651 @cindex @code{\repeat}
1653 To specify repeats, use the @code{\repeat} keyword. Since repeats
1654 should work differently when played or printed, there are a few
1655 different variants of repeats.
1659 Repeated music is fully written (played) out. Useful for MIDI
1660 output, and entering repetitive music.
1663 This is the normal notation: Repeats are not written out, but
1664 alternative endings (voltas) are printed, left to right.
1667 Alternative endings are written stacked. This has limited use but may be
1668 used to typeset two lines of lyrics in songs with repeats, see
1669 @file{input/star-spangled-banner.ly}.
1675 Make beat or measure repeats. These look like percent signs.
1681 * Repeats and MIDI::
1682 * Manual repeat commands::
1684 * Tremolo subdivisions::
1689 @subsection Repeat syntax
1691 The syntax for repeats is
1694 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1697 If you have alternative endings, you may add
1698 @cindex @code{\alternative}
1700 \alternative @code{@{} @var{alternative1}
1702 @var{alternative3} @dots{} @code{@}}
1704 where each @var{alternative} is a music expression.
1706 Normal notation repeats are used like this:
1707 @lilypond[fragment,verbatim]
1709 \repeat volta 2 { c'4 d' e' f' }
1710 \repeat volta 2 { f' e' d' c' }
1713 With alternative endings:
1714 @lilypond[fragment,verbatim]
1716 \repeat volta 2 {c'4 d' e' f'}
1717 \alternative { {d'2 d'} {f' f} }
1720 Folded repeats look like this:
1723 @lilypond[fragment,verbatim]
1725 \repeat fold 2 {c'4 d' e' f'}
1726 \alternative { {d'2 d'} {f' f} }
1730 If you don't give enough alternatives for all of the repeats, then
1731 the first alternative is assumed to be repeated often enough to equal
1732 the specified number of repeats.
1734 @lilypond[fragment,verbatim]
1738 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1739 \alternative { { g4 g g } { a | a a a a | b2. } }
1744 @node Repeats and MIDI
1745 @subsection Repeats and MIDI
1747 @cindex expanding repeats
1749 For instructions on how to unfoldi repeats for MIDI output, see
1750 the example file @file{input/test/unfold-all-repeats.ly}.
1755 Notice that timing information is not remembered at the start of an
1756 alternative, so you have to reset timing information after a repeat,
1757 e.g. using a bar-check (See @ref{Bar check}), setting
1758 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1759 are also not repeated.
1761 It is possible to nest @code{\repeat}s, although this probably is only
1762 meaningful for unfolded repeats.
1764 Folded repeats offer little more over simultaneous music. However, it
1765 is to be expected that more functionality -- especially for the MIDI
1766 backend -- will be implemented at some point in the future.
1768 Volta repeats are printed over all staves in a score. You must turn them
1769 off explicitly, for example by doing
1771 \property Staff.VoltaBracket = \turnOff
1773 in all but the top staff.
1775 @node Manual repeat commands
1776 @subsection Manual repeat commands
1778 @cindex @code{repeatCommands}
1780 The property @code{repeatCommands} can be used to control the layout of
1781 repeats. Its value is a Scheme list of repeat commands, where each repeat
1789 @item (volta . @var{text})
1790 Print a volta bracket saying @var{text}.
1792 Stop a running volta bracket
1795 @lilypond[verbatim, fragment]
1797 \property Score.repeatCommands = #'((volta "93") end-repeat)
1799 \property Score.repeatCommands = #'((volta #f))
1804 Repeats brackets are @internalsref{VoltaBracket} grobs.
1806 @node Tremolo repeats
1807 @subsection Tremolo repeats
1808 @cindex tremolo beams
1810 To place tremolo marks between notes, use @code{\repeat} with tremolo
1812 @lilypond[verbatim,center,singleline]
1814 \context Voice \notes\relative c' {
1815 \repeat "tremolo" 8 { c16 d16 }
1816 \repeat "tremolo" 4 { c16 d16 }
1817 \repeat "tremolo" 2 { c16 d16 }
1818 \repeat "tremolo" 4 c16
1823 Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
1824 @internalsref{StemTremolo}.
1829 At present, the spacing between tremolo beams is not regular, since the
1830 spacing engine does not notice that not all notes are printed.
1832 @node Tremolo subdivisions
1833 @subsection Tremolo subdivisions
1834 @cindex tremolo marks
1835 @cindex @code{tremoloFlags}
1837 Tremolo marks can be printed on a single note by adding
1838 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1839 A @var{length} value of 8 gives one line across the note stem. If the
1840 length is omitted, then then the last value (stored in
1841 @code{Voice.tremoloFlags}) is used.
1843 @lilypond[verbatim,fragment,center]
1844 c'2:8 c':32 | c': c': |
1850 Tremolos in this style do not carry over into the MIDI output.
1853 @node Measure repeats
1854 @subsection Measure repeats
1856 @cindex percent repeats
1857 @cindex measure repeats
1859 In the @code{percent} style, a note pattern can be repeated. It is
1860 printed once, and then the pattern is replaced with a special sign.
1861 Patterns of a one and two measures are replaced by percent-like signs,
1862 patterns that divide the measure length are replaced by slashes.
1864 @lilypond[verbatim,singleline]
1865 \context Voice { \repeat "percent" 4 { c'4 }
1866 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1870 The signs are represented by these grobs: @internalsref{RepeatSlash} and
1871 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
1875 You can not nest percent repeats, e.g. by filling in the first measure
1876 with slashes, and repeating that measure with percents.
1878 @node Rhythmic music
1879 @section Rhythmic music
1886 @node Rhythmic staves
1887 @subsection Rhythmic staves
1889 Sometimes you might want to show only the rhythm of a melody. This can
1890 be done with the rhythmic staff. All pitches of notes on such a staff
1891 are squashed, and the staff itself looks has a single staff line:
1893 @lilypond[fragment,relative,verbatim]
1894 \context RhythmicStaff {
1896 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1903 @section Piano music
1905 Piano music is an odd type of notation. Piano staves are two normal
1906 staves coupled with a brace. The staves are largely independent, but
1907 sometimes voices can cross between the two staves. The
1908 @internalsref{PianoStaff} is especially built to handle this cross-staffing
1909 behavior. In this section we discuss the @internalsref{PianoStaff} and some
1910 other pianistic peculiarities.
1913 * Automatic staff changes::
1914 * Manual staff switches::
1917 * Voice follower lines::
1921 @c . {Automatic staff changes}
1922 @node Automatic staff changes
1923 @subsection Automatic staff changes
1924 @cindex Automatic staff changes
1926 Voices can switch automatically between the top and the bottom
1927 staff. The syntax for this is
1929 \autochange @var{contexttype} \context @var{childcontexttype}
1933 This will switch the interpretation context of @var{musicexp} between
1934 a @var{contexttype} named @code{up} and @code{down}. Typically, you
1935 use @internalsref{Staff} for @var{contexttype}, and
1936 @internalsref{Voice} for @var{childcontexttype}. The autochanger
1937 switches on basis of pitch (central C is the turning point), and it
1938 looks ahead skipping over rests to switch rests in advance.
1940 @lilypond[verbatim,singleline]
1941 \score { \notes \context PianoStaff <
1942 \context Staff = "up" {
1943 \autochange Staff \context Voice = VA < \relative c' {
1944 g4 a b c d r4 a g } > }
1945 \context Staff = "down" {
1951 Note how spacer rests are used to prevent the bottom staff from
1952 terminating too soon.
1955 @node Manual staff switches
1956 @subsection Manual staff switches
1958 @cindex manual staff switches
1959 @cindex staff switch, manual
1961 Voices can be switched between staves manually, using the following command:
1963 \translator Staff = @var{staffname} @var{music}
1965 The string @var{staffname} is the name of the staff. It switches the
1966 current voice from its current staff to the Staff called
1967 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1970 The formal definition of this construct is obtuse, but for the sake of
1971 completeness we give it here.
1972 @cindex @code{\translator}
1974 \translator @var{contexttype} = @var{name}
1976 Formally, this construct is a music expression indicating
1977 that the context which is a direct child of the context of type
1978 @var{contexttype} should be shifted to a context of type
1979 @var{contexttype} and the specified name.
1987 Piano pedal instruction can be expressed using
1988 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
1989 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1991 These identifiers are shorthands for spanner commands of the types
1992 @internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
1994 @lilypond[fragment,verbatim]
1995 c''4 \spanrequest \start "Sustain" c''4
1996 c''4 \spanrequest \stop "Sustain"
1999 The symbols that are printed can be modified by setting
2000 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
2001 Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
2002 @rgrob{SustainPedal}, for example, for more information.
2004 Pedals can also be indicated by a sequence of brackets, by setting the
2005 @code{pedal-type} property of SustainPedal grobs:
2007 @lilypond[fragment,verbatim]
2008 \property Staff.SustainPedal \override #'pedal-type = #'bracket
2009 c''4 \sustainDown d''4 e''4 a'4
2010 \sustainUp \sustainDown
2011 f'4 g'4 a'4 \sustainUp
2014 A third style of pedal notation is a mixture of text and brackets,
2015 obtained by setting @code{pedal-type} to @code{mixed}:
2017 @lilypond[fragment,verbatim]
2018 \property Staff.SustainPedal \override #'pedal-type = #'mixed
2019 c''4 \sustainDown d''4 e''4 c'4
2020 \sustainUp \sustainDown
2021 f'4 g'4 a'4 \sustainUp
2024 The default '*Ped' style for sustain and damper pedals corresponds to
2025 @code{\pedal-type = #'text}. However, @code{mixed} is the default style
2026 for a sostenuto pedal:
2028 @lilypond[fragment,verbatim]
2029 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2032 For fine-tuning of the appearance of a pedal bracket, the properties
2033 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
2034 @code{PianoPedalBracket} grobs (see the detailed documentation of
2035 @rgrob{PianoPedalBracket}) can be modified. For example, the bracket
2036 may be extended to the end of the note head.
2038 @lilypond[fragment,verbatim]
2039 \property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0)
2040 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2047 @subsection Arpeggio
2050 @cindex broken arpeggio
2051 @cindex @code{\arpeggio}
2053 You can specify an arpeggio sign on a chord by attaching an
2054 @code{\arpeggio} to a note of the chord.
2057 @lilypond[fragment,relative,verbatim]
2058 \context Voice <c\arpeggio e g c>
2061 When an arpeggio crosses staves in piano music, you attach an arpeggio
2062 to the chords in both staves, and set
2063 @code{PianoStaff.connectArpeggios}.
2065 @lilypond[fragment,relative,verbatim]
2066 \context PianoStaff <
2067 \property PianoStaff.connectArpeggios = ##t
2068 \context Voice = one { <c'\arpeggio e g c> }
2069 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2073 This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
2074 are @code{PianoStaff.Arpeggio}.
2076 To add an arrow head to explicitly specify the direction of the
2077 arpeggio, you should set the arpeggio grob property
2078 @code{arpeggio-type}.
2080 @lilypond[fragment,relative,verbatim]
2082 \property Voice.Arpeggio \override #'arpeggio-direction = #1
2084 \property Voice.Arpeggio \override #'arpeggio-direction = #-1
2089 A square bracket on the left indicates that the player should not
2090 arpeggiate the chord. To draw these brackets, set the
2091 @code{molecule-callback} property of @code{Arpeggio} or
2092 @code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
2093 @code{\arpeggio} statements within the chords as before.
2095 @lilypond[fragment,relative,verbatim]
2096 \context PianoStaff <
2097 \property PianoStaff.connectArpeggios = ##t
2098 \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket
2099 \context Voice = one { <c'\arpeggio e g c> }
2100 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2107 It is not possible to mix connected arpeggios and unconnected arpeggios
2112 @node Voice follower lines
2113 @subsection Voice follower lines
2115 @cindex follow voice
2116 @cindex staff switching
2119 @cindex @code{followVoice}
2121 Whenever a voice switches to another staff a line connecting the notes
2122 can be printed automatically. This is enabled if the property
2123 @code{PianoStaff.followVoice} is set to true:
2125 @lilypond[fragment,relative,verbatim]
2126 \context PianoStaff <
2127 \property PianoStaff.followVoice = ##t
2128 \context Staff \context Voice {
2130 \translator Staff=two
2133 \context Staff=two {\clef bass \skip 1*2 }
2137 The associated grob is @internalsref{VoiceFollower}.
2144 * Tablatures basic::
2145 * Non-guitar tablatures::
2146 * Tablature in addition to normal staff::
2149 @node Tablatures basic
2150 @subsection Tablatures basic
2151 @cindex Tablatures basic
2153 Tablature can be typeset with Lilypond by using the
2154 @internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
2155 tablatures is a recent feature in Lilypond, most of the guitar special
2156 effects (hammer, pull, bend, ...) are not yet supported.
2158 With the @internalsref{TabStaff}, the string number associated to a note
2159 is given though the fingering mechanism, e.g. @code{c4-3} for a C
2160 quarter on the third string. The string 1 is the lowest one, and the
2161 tuning defaults to the standard guitar tuning (with 6 strings).
2163 @lilypond[fragment,verbatim]
2166 \property Staff.Stem \override #'direction = #1
2175 @node Non-guitar tablatures
2176 @subsection Non-guitar tablatures
2177 @cindex Non-guitar tablatures
2179 There are many ways to customize Lilypond tablatures.
2181 First you can change the number of string, e.g.
2182 @code{StaffSymbol \override #'line-count = #5} to have only 5 strings.
2183 Because of a kind of bug in Lilypond, you MUST create a new type of
2184 context if you want different tablatures with diiferent number of
2187 Then you can change the strings tuning. String tuning is given as a
2188 Scheme list with one integer number for each string, the number being
2189 the string note pitch if not fretted (open note).
2191 Finally, it is possible to change the Scheme function to format the
2192 tablature note text. The default is @var{fret-number-tablature-format},
2193 which uses the fret number, but for some instruments that may not use
2194 this notation, just create your own tablature-format function. This
2195 function takes three argument: the string number, the string tuning and
2199 @node Tablature in addition to normal staff
2200 @subsection Tablature in addition to normal staff
2201 @cindex Tablature in addition to normal staff
2203 It is possible to typeset both tablature and a "normal" staff, as
2204 commonly done in many parts.
2206 A common trick for that is to put the notes in a variables, and to hide
2207 the fingering information (which correspond to the string number) for
2216 \context StaffGroup <
2218 % Hide fingering number (used for string number) for the "normal" staff
2219 \property Staff.Fingering \override #'transparent = ##t
2224 \property Staff.Stem \override #'direction = #1
2241 * Automatic syllable durations::
2247 @subsection Lyrics mode
2250 To print lyrics, you must first make a music expression from the lyric
2251 text. That music expression can be printed by selecting an appropriate
2255 @cindex @code{\lyrics}
2257 You can enter lyrics in a special input mode of LilyPond. This mode is
2258 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
2259 The purpose of this mode is that you can enter lyrics as plain text,
2260 punctuation and accents without any hassle.
2262 Syllables are entered like notes, with pitches replaced by text. For
2263 example, @code{Twin- kle twin- kle} enters four syllables. Note that
2264 the hyphen has no special meaning for lyrics, and does not introduce
2267 Spaces can be introduced into a lyric either by using quotes:
2268 @code{"He could"4 not4} or by using an underscore without quotes:
2269 @code{He_could4 not4}. All unquoted underscores are converted to
2272 The precise definition of this mode can be found in @ref{Lyrics mode
2275 @c . {Printing lyrics}
2276 @node Printing lyrics
2277 @subsection Printing lyrics
2280 Lyrics are printed by interpreting them in the @internalsref{Lyrics} context.
2282 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
2283 @c Add tied and beamed melismata too.
2284 @lilypond[verbatim,singleline]
2286 \notes \relative c' {
2288 \property Staff.automaticMelismata = ##t
2289 d'2 c4 b16 ( a g a b a b ) c a2
2290 b2 c4 b8 ( a16 g ) a4 g2 }
2291 \context Lyrics \lyrics {
2293 share the soft -- ware; }
2297 Notes and syllable durations are matched automatically. This is
2298 accomplished using @code{\addlyrics}, which is documented in
2299 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
2300 the melody staff will cause tied, slurred or beamed notes to be
2301 interpreted as melismata.
2303 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
2306 @cindex lyric extender
2309 As you can see, extender lines are entered as @code{__}. This will
2310 create an extender, a line that extends over the entire duration of the
2311 lyric. This line will run all the way to the start of the next lyric,
2312 so you may want to shorten it by using a blank lyric (using @code{_}).
2313 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2318 If you want to have hyphens centered between syllables (rather than
2319 attached to the end of the first syllable) you can use the special
2320 `@code{-}@code{-}' lyric as a separate word between syllables. This
2321 will result in a hyphen whose length varies depending on the space
2322 between syllables. It will be centered between the syllables. The grob
2323 for this symbol is @code{LyricsVoice.LyricHyphen}.
2325 @cindex Lyric hyphen
2327 @node Automatic syllable durations
2328 @subsection Automatic syllable durations
2329 @cindex Automatic syllable durations
2331 @cindex automatic lyric durations
2332 @cindex @code{\addlyrics}
2334 If you have lyrics that are set to a melody, you can copy the rhythm
2335 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2338 \addlyrics @var{musicexpr1 musicexpr2}
2341 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2342 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2343 when there are events in @var{musicexpr1}.
2345 @cindex @code{automaticMelismata}
2347 If the property @code{automaticMelismata} is set in the
2348 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2351 @lilypond[verbatim,fragment]
2354 \property Voice.automaticMelismata = ##t
2355 c8 () cis d8. e16 f2
2357 \context Lyrics \lyrics {
2361 If you want the lyric lines to be above the melody staff, or in some
2362 other, more complex configuration, then build that configuration first
2363 using simultaneous music, and use @code{\addlyrics} after that.
2365 @lilypond[verbatim, singleline]
2367 \context Lyrics = LA { s1 }
2368 \context Staff = SA { s1 }
2370 \context Staff = SA \relative c' { c4 e g g }
2371 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2374 For @code{\addlyrics} you should use a single rhythm melody, and single
2375 rhythm lyrics (a constant duration is the obvious choice). If you do
2376 not, you can get undesired effects when using multiple stanzas:
2378 @lilypond[verbatim,fragment]
2381 c8 () cis d8. e16 f2
2383 \context Lyrics \lyrics
2388 It is valid (but probably not very useful) to use notes instead of
2389 lyrics for @var{musicexpr2}.
2392 @subsection More stanzas
2396 If you have multiple stanzas printed underneath each other, the vertical
2397 groups of syllables should be aligned around punctuation. LilyPond can
2398 do this if you tell it which lyric lines belong to which melody.
2400 To this end, give the Voice context an identity, and set the LyricsVoice
2401 to a name starting with that identity followed by a dash.
2402 In the following example, the Voice
2403 identity is @code{duet}, and the identities of the LyricsVoices are
2404 @code{duet-1} and @code{duet-2}.
2407 @lilypond[singleline,verbatim]
2410 \notes \relative c'' \context Voice = duet { \time 3/4
2412 \lyrics \context Lyrics <
2413 \context LyricsVoice = "duet-1" {
2414 \property LyricsVoice . stanza = "Bert"
2415 Hi, my name is bert. }
2416 \context LyricsVoice = "duet-2" {
2417 \property LyricsVoice . stanza = "Ernie"
2418 Ooooo, ch\'e -- ri, je t'aime. }
2423 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2424 first system) and @code{LyricsVoice.stz} for the following
2425 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2431 @cindex stanza numbering
2439 LilyPond has support for both entering and printing chords.
2440 @lilypond[verbatim,singleline]
2441 twoWays = \notes \transpose c'' {
2451 < \context ChordNames \twoWays
2452 \context Voice \twoWays > }
2455 This example also shows that the chord printing routines do not try to
2456 be intelligent. If you enter @code{f bes d}, it does not interpret
2457 this as an inversion.
2459 As you can see chords really are a set of pitches. They are internally
2460 stored as simultaneous music expressions. This means you can enter
2461 chords by name and print them as notes, enter them as notes and print
2462 them as chord names, or (the most common case) enter them by name, and
2467 * Printing named chords::
2472 @subsection Chords mode
2475 Chord mode is a mode where you can input sets of pitches using common
2476 names. It is introduced by the keyword @code{\chords}. It is similar
2477 to note mode, but words are also looked up in a chord modifier table
2478 (containing @code{maj}, @code{dim}, etc). Dashes and carets are used
2479 to indicate chord additions and subtractions, so articulation scripts
2480 can not be entered in Chord mode.
2482 Throughout these examples, chords have been shifted around the staff
2483 using @code{\transpose}.
2485 @lilypond[fragment,verbatim]
2489 c:9 c:9-.5+.7+ c:3-.5-
2499 The second type of modifier that may appear after the @code{:} is a
2500 named modifier. Named modifiers are listed in the file
2501 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2502 @code{min} which lower the 3rd half a step, `@code{aug}' which
2503 raises the 5th, `@code{dim}' which lowers the 5th,
2504 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2505 which replaces the 5th with a 4th.
2507 @lilypond[fragment,verbatim]
2510 c1:m c:min7 c:maj c:aug c:dim c:sus
2516 Chord subtractions are used to eliminate notes from a chord. The
2517 notes to be subtracted are listed after a @code{^} character,
2520 @lilypond[fragment,verbatim,center]
2529 Chord inversions can be specified by appending `@code{/}' and the name
2530 of a single note to a chord. In a chord inversion, the inverted note is
2531 transposed down until it is the lowest note in the chord. If the note
2532 is not in the chord, a warning will be printed.
2534 @lilypond[fragment,verbatim,center]
2544 Bass notes can be added by `@code{/+}' and
2545 the name of a single note to a chord. This has the effect of
2546 adding the specified note to the chord, lowered by an octave,
2547 so it becomes the lowest note in the chord.
2549 @lilypond[fragment,verbatim,center]
2558 The formal syntax for named chords is as follows:
2560 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2563 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2564 the chord duration in the usual notation. There are two kinds of
2565 modifiers. One type is formed by @emph{chord additions}. Additions are
2566 obtained by listing intervals separated by dots. An interval is written
2567 by its number with an optional @code{+} or @code{-} to indicate raising
2568 or lowering by half a step. Chord additions have two effects: they adds
2569 the specified interval and all lower odd numbered intervals to the
2570 chord, and they may lower or raise the specified interval.
2575 Implementation details are gory. For example @code{c:4} not only adds
2576 a fourth, but also removes the third.
2579 @c . {Printing named chords}
2580 @node Printing named chords
2581 @subsection Printing named chords
2583 @cindex printing chord names
2587 For displaying printed chord names, use the @internalsref{ChordNames} context.
2588 The chords may be entered either using the notation described above, or
2589 directly using simultaneous music.
2591 @lilypond[verbatim,singleline]
2593 \chords {a1 b c} <d f g> <e g b>
2597 \context ChordNames \scheme
2598 \context Staff \transpose c'' \scheme
2603 You can make the chord changes stand out by setting
2604 @code{ChordNames.chordChanges} to true. This will only display chord
2605 names when there's a change in the chords scheme and at the start of a
2610 c1:m c:m \break c:m c:m d
2614 \context ChordNames {
2615 \property ChordNames.chordChanges = ##t
2617 \context Staff \transpose c'' \scheme
2619 \paper{linewidth= 9.\cm}
2623 LilyPond examines chords specified as lists of notes to determine a name
2624 to give the chord. LilyPond will not try to identify chord inversions or
2625 an added bass note, which may result in strange chord names when chords
2626 are entered as a list of pitches:
2628 @lilypond[verbatim,center,singleline]
2637 \context ChordNames \scheme
2638 \context Staff \scheme
2644 By default, a chord name system proposed by Harald Banter (See
2645 @ref{Literature}) is used. The system is very regular and predictable.
2646 Typical American style chord names may be selected by setting the
2647 @code{style} property of the @code{ChordNames.ChordName} grob to
2648 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2650 Routines that determine the names to be printed are written in Scheme,
2651 and may be customized by the user. The code can be found in
2652 @file{scm/chord-name.scm}. Here's an example showing the differences in
2656 @c maybe just junk verbatim option?
2657 @lilypond[verbatim,singleline]
2667 \context ChordNames = banter \scheme
2668 \context ChordNames = american {
2669 \property ChordNames.ChordName \override
2670 #'style = #'american \scheme }
2671 \context ChordNames = jazz {
2672 \property ChordNames.ChordName \override
2673 #'style = #'jazz \scheme }
2674 \context Staff \transpose c'' \scheme
2681 @section Writing parts
2683 Orchestral music involves some special notation, both in the full score,
2684 as in the individual parts. This section explains how to tackle common
2685 problems in orchestral music.
2692 * Instrument names::
2694 * Multi measure rests::
2695 * Automatic part combining::
2696 * Hara kiri staves::
2697 * Sound output for transposing instruments::
2700 @c . {Rehearsal marks}
2701 @node Rehearsal marks
2702 @subsection Rehearsal marks
2703 @cindex Rehearsal marks
2705 @cindex @code{\mark}
2707 To print a rehearsal mark, use the @code{\mark} command.
2708 @lilypond[fragment,verbatim]
2715 c1 \mark #'(music "scripts-segno")
2720 As you can see, the mark is incremented automatically if you use
2721 @code{\mark \default}. The value to use is stored in the property
2722 @code{rehearsalMark} is used and automatically incremented. The grob
2723 is @internalsref{RehearsalMark} in @internalsref{Score} context. See
2724 @code{input/test/boxed-molecule.ly} if you need boxes around the
2728 @subsection Bar numbers
2732 @cindex measure numbers
2733 @cindex currentBarNumber
2735 They are printed at the
2736 start of the line. The number itself is a property that can be set by
2737 modifying the @code{currentBarNumber} property, i.e.
2739 \property Score.currentBarNumber = #217
2742 If you want boxed bar numbers, see the example file
2743 @code{input/test/boxed-molecule.ly}.
2745 Bar numbers are @internalsref{BarNumber} grobs.
2749 It is not possible to have bar numbers printed at regular intervals
2752 Barnumbers can collide with the StaffGroup, if there is one at the
2753 top. To solve this, You have to twiddle with the
2754 @internalsref{padding} property of @internalsref{BarNumber} if your
2755 score starts with a @internalsref{StaffGroup}.
2757 @node Instrument names
2758 @subsection Instrument names
2760 In scores, the instrument name is printed before the staff. This can
2761 be done by setting @code{Staff.instrument} and
2762 @code{Staff.instr}. This will print a string before the start of the
2763 staff. For the first start, @code{instrument} is used, for the next
2764 ones @code{instr} is used.
2766 @lilypond[verbatim,singleline]
2767 \property Staff.instrument = "ploink " { c''4 }
2770 You can also use markup texts to construct more complicated instrument
2774 @lilypond[verbatim,singleline]
2776 '((font-relative-size . -2 ) (music "accidentals--1")))
2779 \property Staff.instrument = #`((kern . 0.5) (lines
2780 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2788 When you put a name on a grand staff or piano staff the width of the
2789 brace is not taken into account. You must add extra spaces to the end of
2790 the name to avoid a collision.
2793 @subsection Transpose
2795 @cindex transposition of pitches
2796 @cindex @code{\transpose}
2798 A music expression can be transposed with @code{\transpose}. The syntax
2801 \transpose @var{pitch} @var{musicexpr}
2804 This means that middle C in @var{musicexpr} is transposed to
2807 @code{\transpose} distinguishes between enharmonic pitches: both
2808 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2809 a tone. The first version will print sharps and the second version
2812 @lilypond[singleline, verbatim]
2813 mus =\notes { \key e \major c d e f }
2814 \score { \notes \context Staff {
2817 \transpose des'' \mus
2818 \transpose cis'' \mus
2822 If you want to use both @code{\transpose} and @code{\relative}, then
2823 you must use @code{\transpose} first. @code{\relative} will have no
2824 effect music that appears inside a @code{\transpose}.
2826 @c . {Multi measure rests}
2827 @node Multi measure rests
2828 @subsection Multi measure rests
2829 @cindex Multi measure rests
2833 Multi measure rests are entered using `@code{R}'. It is specifically
2834 meant for full bar rests and for entering parts: the rest can expand to
2836 rests, or it can be printed as a single multimeasure rest This expansion
2837 is controlled by the property @code{Score.skipBars}. If this is set to true,
2838 Lily will not expand empty measures, and the appropriate number is added
2841 @lilypond[fragment,verbatim]
2842 \time 3/4 r2. | R2. | R2.*2
2843 \property Score.skipBars = ##t R2.*17 R2.*4
2846 Notice that the @code{R2.} is printed as a whole rest, centered in the
2849 @cindex whole rests for a full measure
2851 The grob for this object is @internalsref{MultiMeasureRest}.
2855 Currently, there is no way to automatically condense multiple rests
2856 into a single multimeasure rest. Multi measure rests do not take part
2859 @cindex condensing rests
2861 @node Automatic part combining
2862 @subsection Automatic part combining
2863 @cindex automatic part combining
2864 @cindex part combiner
2867 Automatic part combining is used to merge two parts of music onto a
2868 staff in an intelligent way. It is aimed primarily at typesetting
2869 orchestral scores. When the two parts are identical for a period of
2870 time, only one is shown. In places where the two parts differ, they
2871 are typeset as separate voices, and stem directions are set
2872 automatically. Also, solo and @emph{a due} parts can be identified
2875 The syntax for part combining is
2878 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2880 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2881 combined into one context of type @var{context}. The music expressions
2882 must be interpreted by contexts whose names should start with @code{one}
2885 The most useful function of the part combiner is to combine parts into
2886 one voice, as common for wind parts in orchestral scores:
2888 @lilypond[verbatim,singleline,fragment]
2890 \context Voice=one \partcombine Voice
2891 \context Thread=one \relative c'' {
2894 \context Thread=two \relative c'' {
2900 Notice that the first @code{g} appears only once, although it was
2901 specified twice (once in each part). Stem, slur and tie directions are
2902 set automatically, depending whether there is a solo or unisono. The
2903 first part (with context called @code{one}) always gets up stems, and
2904 `solo', while the second (called @code{two}) always gets down stems and
2907 If you just want the merging parts, and not the textual markings, you
2908 may set the property @var{soloADue} to false.
2910 @lilypond[verbatim,singleline,fragment]
2912 \property Staff.soloADue = ##f
2913 \context Voice=one \partcombine Voice
2914 \context Thread=one \relative c'' {
2917 \context Thread=two \relative c'' {
2923 There are a number of other properties that you can use to tweak the
2924 behavior of part combining, refer to the automatically generated
2925 documentation of @reng{Thread_devnull_engraver} and
2926 @reng{Voice_devnull_engraver}. Look at the documentation of the
2927 responsible engravers, @code{Thread_devnull_engraver},
2928 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2932 In @code{soloADue} mode, when the two voices play the same notes on and
2933 off, the part combiner may typeset @code{a2} more than once in a
2936 @lilypond[fragment,singleline]
2938 \context Voice=one \partcombine Voice
2939 \context Thread=one \relative c'' {
2942 \context Thread=two \relative c'' {
2948 @cindex @code{Thread_devnull_engraver}
2949 @cindex @code{Voice_engraver}
2950 @cindex @code{A2_engraver}
2952 @node Hara kiri staves
2953 @subsection Hara kiri staves
2955 In orchestral scores, staff lines that only have rests are usually removed.
2956 This saves some space. LilyPond also supports this through the hara
2957 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2958 the Japanese Samourai warriors.} staff. This staff commits suicide when
2959 it finds itself to be empty after the line-breaking process. It will
2960 not disappear when it contains normal rests, you must use multi measure
2963 The hara kiri staff is specialized version of the @internalsref{Staff}
2964 context. It is available as the context identifier
2965 @code{\HaraKiriStaffContext}. Observe how the second staff in this
2966 example disappears in the second line.
2970 \notes \relative c' <
2971 \context Staff = SA { e4 f g a \break c1 }
2972 \context Staff = SB { c4 d e f \break R1 }
2976 \translator { \HaraKiriStaffContext }
2982 @node Sound output for transposing instruments
2983 @subsection Sound output for transposing instruments
2985 When you want to make a MIDI file from a score containing transposed
2986 and untransposed instruments, you have to instruct LilyPond the pitch
2987 offset (in semitones) for the transposed instruments. This is done
2988 using the @code{transposing} property. It does not affect printed
2991 @cindex @code{transposing}
2994 \property Staff.instrument = #"Cl. in B-flat"
2995 \property Staff.transposing = #-2
3001 @node Ancient notation
3002 @section Ancient notation
3005 * Ancient note heads::
3010 @node Ancient note heads
3011 @subsection Ancient note heads
3013 To get a longa note head, you have to use mensural note heads. This
3014 is accomplished by setting the @code{style} property of the
3015 NoteHead grob to @code{mensural}. There is also a note head style
3016 @code{baroque} which gives mensural note heads for @code{\longa} and
3017 @code{\breve} but standard note heads for shorter notes.
3019 @lilypond[fragment,singleline,verbatim]
3020 \property Voice.NoteHead \set #'style = #'mensural
3021 \property Voice.NoteHead \set #'font-family = #'ancient
3026 @subsection Custodes
3031 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
3032 staff context symbol that appears at the end of a staff line. It
3033 anticipates the pitch of the first note(s) of the following line and
3034 thus helps the player or singer to manage line breaks during
3035 performance, thus enhancing readability of a score.
3040 \property Staff.Custos \set #'style = #'mensural
3045 \consists Custos_engraver
3051 Custodes were frequently used in music notation until the 17th century.
3052 There were different appearances for different notation styles.
3053 Nowadays, they have survived only in special forms of musical notation
3054 such as via the @emph{editio vaticana} dating back to the beginning of
3057 For typesetting custodes, just put a @code{Custos_engraver} into the
3058 @internalsref{Staff} context when declaring the @code{\paper} block. In this
3059 block, you can also globally control the appearance of the custos symbol
3060 by setting the custos @code{style} property. Currently supported styles
3061 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
3068 \consists Custos_engraver
3069 Custos \override #'style = #'mensural
3074 The property can also be set locally, for example in a @code{\notes}
3079 \property Staff.Custos \override #'style = #'vaticana
3080 c'1 d' e' d' \break c' d' e' d'
3085 @section Ancient clefs
3087 LilyPond supports a variety of clefs, many of them ancient. These can
3088 be selected from the @code{ancient} font family, by setting
3089 @code{Staff.clefGlyph}) to the following values
3098 @item clefs-vaticana_do
3099 Editio Vaticana style do clef
3100 @item clefs-vaticana_fa
3101 Editio Vaticana style fa clef
3102 @item clefs-medicaea_do
3103 Editio Medicaea style do clef
3104 @item clefs-medicaea_fa
3105 Editio Medicaea style fa clef
3106 @item clefs-mensural1_c
3107 modern style mensural C clef
3108 @item clefs-mensural2_c
3109 historic style small mensural C clef
3110 @item clefs-mensural3_c
3111 historic style big mensural C clef
3112 @item clefs-mensural1_f
3113 historic style traditional mensural F clef
3114 @item clefs-mensural2_f
3115 historic style new mensural F clef
3116 @item clefs-mensural_g
3117 historic style mensural G clef
3118 @item clefs-hufnagel_do
3119 historic style hufnagel do clef
3120 @item clefs-hufnagel_fa
3121 historic style hufnagel fa clef
3122 @item clefs-hufnagel_do_fa
3123 historic style hufnagel combined do/fa clef
3124 @item clefs-percussion
3125 modern style percussion clef
3128 @emph{Modern style} means ``as is typeset in current editions.''
3129 @emph{Historic style} means ``as was typeset or written in contemporary
3130 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
3133 @cindex Vaticana, Editio
3134 @cindex Medicaea, Editio
3135 @cindex hufnagel clefs
3141 @section Figured bass
3143 @cindex Basso continuo
3145 LilyPond has limited support for figured bass:
3147 @lilypond[verbatim,fragment]
3149 \context FiguredBass
3154 \context Voice { c4 g8 }
3158 The support for figured bass consists of two parts: there is an input
3159 mode, introduced by @code{\figures}, where you can enter bass figures
3160 as numbers, and there is a context called @internalsref{FiguredBass}
3161 that takes care of making @internalsref{BassFigure} grobs.
3163 In figures input mode, a group of bass figures is delimited by
3164 @code{<} and @code{>}. The duration is entered after the @code{>}.
3166 \context FiguredBass
3173 Accidentals are added to the numbers if you alterate them by
3174 appending @code{-}, @code{!} and @code{+}.
3177 \context FiguredBass
3178 \figures { <4- 6+ 7!> }
3184 Spaces or dashes may be inserted by using @code{_}. Brackets are
3185 introduced with @code{[} and @code{]}.
3188 \context FiguredBass
3189 \figures { < [4 6] 8 [_ 12]> }
3195 Although the support for figured bass may superficially resemble chord
3196 support, it works much simpler: in figured bass simply stores the
3197 numbers, and then prints the numbers you entered. There is no
3198 conversion to pitches, and no realizations of the bass are played in
3202 @c . {Tuning output}
3204 @section Tuning output
3206 LilyPond tries to take as much formatting as possible out of your
3207 hands. Nevertheless, there are situations where it needs some help, or
3208 where you want to override its decisions. In this section we discuss
3209 ways to do just that.
3211 Formatting is internally done by manipulating so called grobs (graphic
3212 objects). Each grob carries with it a set of properties (grob
3213 properties) specific to that object. For example, a stem grob has
3214 properties that specify its direction, length and thickness.
3216 The most direct way of tuning the output is by altering the values of
3217 these properties. There are two ways of doing that: first, you can
3218 temporarily change the definition of a certain type of grob, thus
3219 affecting a whole set of objects. Second, you can select one specific
3220 object, and set a grob property in that object.
3223 * Tuning groups of grobs ::
3224 * Tuning per grob ::
3232 @node Tuning groups of grobs
3233 @subsection Tuning groups of grobs
3235 @cindex grob description
3239 A grob definition is a Scheme association list, that is stored in a
3240 context property. By assigning to that property (using plain
3241 @code{\property}), you can change the resulting grobs.
3243 @lilypond[verbatim, fragment]
3244 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
3247 The @code{\property} assignment effectively empties the definition of
3248 the Stem object. One of the effects is that the recipe of how it should be
3249 printed is erased, with the effect of rendering it invisible. The above
3250 assignment is available as a standard identifier, for the case that you
3254 \property Voice.Stem = \turnOff
3261 This mechanism is fairly crude, since you can only set, but not modify,
3262 the definition of a grob. For this reason, there is a more advanced
3265 The definition of a grob is actually a list of default grob
3266 properties. For example, the definition of the Stem grob (available in
3267 @file{scm/grob-description.scm}), defines the following values for
3272 (beamed-lengths . (0.0 2.5 2.0 1.5))
3273 (Y-extent-callback . ,Stem::height)
3277 You can add a property on top of the existing definition, or remove a
3278 property, thus overriding the system defaults:
3280 c'4 \property Voice.Stem \override #'thickness = #4.0
3281 c'4 \property Voice.Stem \revert #'thickness
3284 You should balance @code{\override} and @code{\revert}. If that's too
3285 much work, you can use the @code{\set} shorthand. It performs a revert
3286 followed by an override. The following example gives exactly the same
3287 result as the previous one.
3289 c'4 \property Voice.Stem \set #'thickness = #4.0
3290 c'4 \property Voice.Stem \set #'thickness = #0.8
3293 If you use @code{\set}, you must explicitly restore the default.
3296 Formally the syntax for these constructions is
3298 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
3299 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
3300 \property @var{context}.@var{grobname} \revert @var{symbol}
3302 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
3303 and @var{grobname} are strings and @var{value} is a Scheme expression.
3306 If you revert a setting which was not set in the first place, then it
3307 has no effect. However, if the setting was set as a system default, it
3308 may remove the default value, and this may give surprising results,
3309 including crashes. In other words, @code{\override} and @code{\revert},
3310 must be carefully balanced.
3312 These are examples of correct nesting of @code{\override}, @code{\set},
3315 A clumsy but correct form:
3317 \override \revert \override \revert \override \revert
3320 Shorter version of the same:
3322 \override \set \set \revert
3325 A short form, using only @code{\set}. This requires you to know the
3328 \set \set \set \set @var{to default value}
3331 If there is no default (i.e. by default, the grob property is unset),
3334 \set \set \set \revert
3337 For the digirati, the grob description is an Scheme association
3338 list. Since a Scheme list is a singly linked list, we can treat it as a
3339 stack, and @code{\override} and @code{\revert} are just push and pop
3340 operations. This pushing and popping is also used for overriding
3341 automatic beaming settings.
3345 LilyPond will hang or crash if @var{value} contains cyclic references.
3346 The backend is not very strict in type-checking grob properties. If you
3347 @code{\revert} properties that are expected to be set by default,
3351 @cindex adjusting staff symbol
3352 @cindex StaffSymbol, using \property
3353 @cindex staff lines, setting number of
3355 Some grobs are created at the moment that their context is created. An
3356 example of such a grob is the staff itself (i.e. the horizontal lines).
3357 You can not change the appearance of the staff symbol by manipulating
3358 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3359 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3360 created before any @code{\override} is effective. You can deal with this
3361 either overriding properties in a @code{\translator} definition, or by
3362 using @code{\outputproperty}.
3367 @node Tuning per grob
3368 @subsection Tuning per grob
3370 @cindex \outputproperty
3372 A second way of tuning grobs is the more arcane @code{\outputproperty}
3373 feature. The syntax is as follows:
3375 \outputproperty @var{predicate} @var{symbol} = @var{value}
3377 Here @code{predicate} is a Scheme function taking a grob argument, and
3378 returning a boolean. This statement is processed by the
3379 @code{Output_property_engraver}. It instructs the engraver to feed all
3380 grobs that it sees to @var{predicate}. Whenever the predicate returns
3381 true, the grob property @var{symbol} will be set to @var{value}.
3383 You will need to combine this statement with @code{\context} to select
3384 the appropriate context to apply this to.
3386 Here are some random examples.
3389 In the following example, all note heads occurring at current staff
3390 level, are shifted up and right by setting their @code{extra-offset}
3393 @lilypond[fragment,verbatim,singleline]
3395 \context Staff \outputproperty
3396 #(make-type-checker 'note-head-interface)
3397 #'extra-offset = #'(0.5 . 0.75)
3401 @cindex @code{extra-offset}
3403 In this example, the predicate checks the @code{text} grob property, to
3404 shift only the `m.d.' text, but not the fingering instruction "2".
3405 @lilypond[verbatim,singleline]
3406 #(define (make-text-checker text)
3407 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3410 \notes\relative c''' {
3411 \property Voice.Stem \set #'direction = #1
3412 \outputproperty #(make-text-checker "m.d.")
3413 #'extra-offset = #'(-3.5 . -4.5)
3421 If possible, avoid this feature: the semantics are not very clean, and
3422 the syntax and semantics are up for rewrite.
3427 @node Font selection
3428 @subsection Font selection
3430 Most graphics in LilyPond are composed of characters of fonts. You can
3431 alter the characteristics of the font by setting certain grob
3432 properties. The mechanism that is used for this resembles La@TeX{}'s New
3433 Font Selection Scheme. Within this scheme, a font is entirely
3434 characterized by its font name.
3436 For each grob that uses fonts (in other words, each grob that supports
3437 @code{font-interface}) a font-name must be selected before it can be
3438 printed. The font name is selected by looking at a number of grob
3443 A symbol indicating the general class of the typeface. Supported are
3444 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3445 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3446 signs) and @code{typewriter}
3449 A symbol indicating the shape of the font, there are typically several
3450 font shapes available for each font family. Choices are @code{italic},
3451 @code{caps} and @code{upright}
3454 A symbol indicating the series of the font. There are typically several
3455 font series for each font family and shape. Choices are @code{medium}
3458 @item font-relative-size
3459 A number indicating the size relative the standard size. For example,
3460 with 20pt staff height, relative size -1 corresponds to 16pt staff
3461 height, and relative size +1 corresponds to 23 pt staff height.
3463 @item font-design-size
3464 A number indicating the design size of the font.
3466 This is a feature of the Computer Modern Font: each point size has a
3467 slightly different design. Smaller design sizes are relatively wider,
3468 which enhances readability. Scalable type faces such TrueType and Adobe
3469 Type1 usually come as ``one design fits all sizes''.
3472 The name of the font, without the design size, e.g. @code{cmr},
3473 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3480 The font is selected by taking the first font that satisfies all
3481 qualifiers specified. You can override any of these fields through
3482 @code{\override} and @code{\revert}. The special value @code{*} matches
3483 any value for that qualifier.
3486 \property Lyrics.LyricText \override #'font-series = #'bold
3487 \property Lyrics.LyricText \override #'font-shape = #'*
3490 @cindex @code{font-style}
3492 There are also pre-cooked font selection qualifiers. These are selected
3493 through the grob property @code{font-style}. For example, the style
3494 @code{finger} selects family @code{number} and relative size @code{-3}.
3495 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3496 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3499 The style sheets and tables for selecting fonts are located in
3500 @file{scm/font.scm}. Refer to this file for more information.
3503 Setting @code{font-name} overrides all other qualifiers. The value for
3504 this property should be a string, the file name of the font. You may use
3505 this to use special fonts, which are not a part of the style sheet, or
3506 which have special encodings.
3508 The size of the font may be set with the grob property
3509 @code{font-magnification}. It is the size of font, relative to its
3510 standard size. For example, @code{1.0} is normal size.
3514 Relative size is not linked to any real size.
3516 There is no style sheet provided for other fonts besides the @TeX{}
3519 @cindex font selection
3520 @cindex font magnification
3521 @cindex @code{font-interface}
3525 @subsection Text markup
3529 LilyPond has an internal mechanism to typeset texts. You can
3530 form text markup expressions by composing scheme expressions
3531 in the following way.
3533 @lilypond[verbatim, singleline]
3538 c^#'(italic "italic")
3539 d_#'((bold italic) "ff")
3541 f_#'(lines "one" (bold "two"))
3542 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3546 Normally, the Scheme markup text is stored in the @code{text} property
3547 of a grob. Formally, it is defined as follows:
3550 text: string | (head? text+)
3551 head: markup | (markup+)
3552 markup-item: property | abbrev
3553 property: (@var{key} . @var{value})
3554 abbrev: @code{columns lines roman music bold italic named super sub}
3555 @code{overstrike text finger volta timesig mmrest mark script}
3556 @code{large Large dynamic}
3559 The markup is broken down and converted into a list of grob properties,
3560 which are prepended to the property list. The @var{key}-@var{value}
3561 pair is a grob property. A list of properties available is included in
3562 the generated documentation for @rint{Text_interface}.
3564 The following abbreviations are currently defined:
3567 horizontal mode: set all text on one line (default)
3569 vertical mode: set every text on a new line
3573 selects the Feta font (the standard font for music notation glyphs),
3574 and uses named lookup
3581 lookup by character name
3583 plain text lookup (by character value)
3589 the next text or character overstrikes this one
3591 select fingering number fontstyle
3593 select volta number fontstyle
3595 select time signature number fontstyle
3597 select multi measure rest number fontstyle
3599 select mark number fontstyle
3601 select scriptsize roman fontstyle
3603 select large roman fontstyle
3605 select Large roman fontstyle
3607 select dynamics fontstyle
3611 @cindex metronome mark
3613 One practical application of complicated markup is to fake a metronome
3617 #(define note '(columns
3618 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3619 #(define eight-note `(columns ,note ((kern . -0.1)
3620 (music ((raise . 3.5) "flags-u3")))))
3621 #(define dotted-eight-note
3622 `(columns ,eight-note (music "dots-dot")))
3625 \notes\relative c'' {
3626 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3632 TextScript \override #'font-shape = #'upright
3638 @node Invisible grobs
3639 @subsection Invisible grobs
3640 @cindex invisible grobs
3644 ben nog steeds niet kapot van de informatiedichtheid hier.
3650 You can imagine a number of situations where you would want to make
3651 certain grobs not show up in the output. There may be aesthetic
3652 reasons, to make the output resemble an (old) manuscript as close as
3653 possible, or to make lessons or exercises for students.
3655 Grobs can be made invisible in a number of ways:
3657 Here's an example with blanked-out notes and stems:
3658 @lilypond[singleline,verbatim]
3660 \property Voice.NoteHead \override
3662 \property Voice.Stem \override
3663 #'transparent = ##t }
3666 \property Voice.NoteHead \revert #'transparent
3667 \property Voice.Stem \revert #'transparent }
3670 \notes\relative c'' {
3672 a b c b \blanknotes c \unblanknotes d
3676 This method makes the grobs invisible but they still take the normal space.
3677 To remove all traces of the grob, you can redefine the function
3681 \notes\relative c'' {
3684 as bes c bes c d \break
3685 \property Staff.KeySignature \override #'molecule-callback = #'()
3688 \paper{linewidth=5.0\cm indent=0}
3692 A very rigorous way of removing grobs from the whole score is to remove
3693 the engraver that creates them. For example,
3695 @lilypond[singleline,verbatim]
3696 \score {\notes { c'4 d'8 e'8 g2 }
3697 \paper { \translator {
3699 \remove Stem_engraver
3705 @subsection Dirty tricks
3706 @cindex embedded tex
3708 It is possible to use @TeX{} commands in the strings, but this should be
3709 avoided because it makes it impossible for LilyPond to compute the
3710 exact length of the string, which may lead to collisions. Also, @TeX{}
3711 commands won't work with direct PostScript output (see @ref{PostScript
3714 @lilypond[fragment,relative,verbatim]
3715 a'^"3 $\\times$ \\`a deux"
3718 You can also use raw PostScript commands embedded in text scripts. This
3719 offers ultimate flexibility, but requires you to learn PostScript.
3720 Currently, embedded PostScript will @strong{not} work with direct
3721 PostScript output. Note that all dimensions that you use are in staff
3726 \notes \relative c'' {
3727 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3728 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3729 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3733 \paper { linewidth = 70*\staffspace }
3740 TODO: Move this section.
3746 Generating optically pleasing spacing is black magic. LilyPond tries
3747 to deal with a number of frequent cases. Here is an example that is
3748 not handled correctly, due to the combination of chord collisions and
3753 \context PianoStaff \notes \transpose c''' <
3754 \context Staff = up { s1 }
3755 \context Staff = down { [c8 c \translator Staff=up <c d> c
3756 \translator Staff=down c c c] }
3758 \paper { linewidth = -1 }
3766 @section Page layout
3769 The page layout is the combined product of LilyPond formatting notation,
3770 and (La)@TeX{} putting the notation on a page, including page breaks.
3771 The part of LilyPond is documented here.
3785 @subsection Paper block
3788 The most important output definition is the @code{\paper} block, for
3789 music notation. The syntax is
3792 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3795 where each of the items is one of
3798 @item An assignment.
3800 @item A context definition. See @ref{Interpretation context} for
3801 more information on context definitions.
3803 @item \stylesheet declaration. Its syntax is
3805 \stylesheet @var{alist}
3808 See @file{scm/font.scm} for details of @var{alist}.
3809 @item an @code{\elementdescriptions} declaration.
3811 \elementdescriptions @var{alist}
3813 See @file{scm/grob-description.scm} for details of
3814 @var{alist}. This command is not user-serviceable.
3818 @c . {Paper variables}
3819 @node Paper variables
3820 @subsection Paper variables
3821 @cindex Paper variables
3823 The paper block has some variables you may want to use or change:
3826 @cindex @code{indent}
3828 The indentation of the first line of music.
3829 @cindex @code{staffspace}
3831 @item @code{staffspace}
3832 The distance between two staff lines, calculated from the center
3835 @cindex @code{linewidth}
3836 @item @code{linewidth}
3837 Sets the width of the lines.
3839 If set to a negative value, a single unjustified line is produced.
3840 @c rename to singleLinePaper ?
3841 The shorthand @code{\singleLine} defines a default paper block that
3842 produces a single line.
3844 @cindex @code{textheight}
3846 @item @code{textheight}
3847 Sets the total height of the music on each page. Only used by
3850 @cindex @code{interscoreline}
3852 @item @code{interscoreline}
3853 Sets the spacing between systems. The default is 16pt.
3855 @cindex @code{interscorelinefill}
3857 @item @code{interscorelinefill}
3858 If set to a positive number, the distance between the score
3859 lines will stretch in order to fill the full page. In that
3860 case @code{interscoreline} specifies the minimum spacing.
3865 @cindex @code{stafflinethickness}
3867 @item @code{stafflinethickness}
3868 Determines the thickness of staff lines, and also acts as a scaling
3869 parameter for other line thicknesses.
3872 You may enter these dimension using units (@code{cm}, @code{in},
3873 @code{mm}, @code{pt}), or relative to another dimension
3875 linewidth = 20.0 * \staffspace
3882 @subsection Font size
3883 @cindex font size, setting
3884 @cindex staff size, setting
3885 @cindex @code{paper} file
3887 The Feta font provides musical symbols at six different sizes. These
3888 fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
3889 point. The point size of a font is the height of the five lines in a
3890 staff when displayed in the font.
3892 Definitions for these sizes are the files @file{paperSZ.ly}, where
3893 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3894 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3895 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3896 @code{paperTwentysix} are defined respectively. The default
3897 @code{\paper} block is also set. These files should be imported at toplevel, i.e.
3899 \include "paper26.ly"
3903 The font definitions are generated using a Scheme function. For more
3904 details, see the file @file{scm/font.scm}.
3910 @subsection Paper size
3915 @cindex @code{papersize}
3917 To change the paper size, you must first set the
3918 @code{papersize} paper variable variable. Set it to
3919 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3920 specification, you must set the font as described above. If you want
3921 the default font, then use the 20 point font.
3924 \paper@{ papersize = "a4" @}
3925 \include "paper16.ly"
3928 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3929 will set the paper variables @code{hsize} and @code{vsize} (used by
3930 Lilypond and @code{ly2dvi})
3934 @subsection Line break
3937 @cindex breaking lines
3939 Line breaks are normally computed automatically. They are chosen such
3940 that it looks neither cramped nor loose, and that consecutive lines have
3943 Occasionally you might want to override the automatic breaks; you can do
3944 this by specifying @code{\break}. This will force a line break at this
3945 point. Do remember that line breaks can only occur at places where there
3946 are bar lines. If you want to have a line break where there is no
3947 bar line, you can force an invisible bar line by entering @code{\bar
3948 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3950 If you want linebreaks at regular intervals, you can use the following:
3953 < \repeat 7 unfold @{ s1 * 4 \break @}
3957 This makes the following 28 measures (assuming 4/4 time) be broken every
3961 @cindex @code{\penalty}
3963 The @code{\break} and @code{\noBreak} commands are defined in terms of
3964 the penalty command:
3969 This encourages or discourages LilyPond to make a line break at this
3974 The scaling of the @code{\penalty} argument is not well-defined. The
3975 command is rather kludgey, and slated for rewriting.
3979 @subsection Page break
3982 @cindex breaking pages
3984 Page breaks are normally computed by @TeX{}, so they are not under
3985 direct control of LilyPond. However, you can insert a commands into the
3986 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3987 the command @code{\newpage}
3988 @cindex @code{\newpage}
3994 @c why do so difficult?
3995 @c maybe should explain contents of between-system.ly,
3996 @c but not now, we're talking about page breaks here.
3998 @c details, see the example file @file{input/test/between-systems.ly}
4001 @c . {Output scaling}
4002 @node Output scaling
4003 @subsection Output scaling
4018 There is no mechanism to select magnification of particular fonts,
4019 meaning that you don't have access to continuously scaled fonts.
4023 @c . {Output formats}
4024 @node Output formats
4025 @section Output formats
4027 LilyPond can output processed music in different output formats.
4031 * PostScript output::
4033 * ASCIIScript output::
4037 @subsection TeX output
4040 LilyPond will use @TeX{} by default. Even if you want to produce
4041 PostScript output for viewing or printing, you should normally have
4042 LilyPond produce @TeX{} first. The .tex output must be processed by
4043 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
4044 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
4045 used to generate the .dvi for you.
4049 Titling is not generated unless you use @file{ly2dvi}.
4052 @node PostScript output
4053 @subsection PostScript output
4054 @cindex PostScript output
4055 @cindex direct PostScript output
4057 LilyPond can produce PostScript directly, without going through @TeX{}.
4058 Currently, this is mainly useful if you cannot use TeX, because direct
4059 PostScript output has some problems; see Bugs below.
4062 $ lilypond -fps foo.ly
4063 GNU LilyPond 1.3.144
4064 Now processing: `foo.ly'
4066 Interpreting music...[3]
4067 Preprocessing elements...
4068 Calculating column positions...
4069 paper output to foo.ps...
4071 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
4077 Text font selection is broken.
4079 The .ps file does not contain the .pfa font files. To print a .ps
4080 created through direct postscript output, you should prepend the
4081 necessary .pfa files to LilyPond's .ps output, or upload them to the
4082 printer before printing.
4084 The line height calculation is broken, you must set @var{lineheight} in
4085 the paperblock if you have more than one staff in your score, e.g.
4090 % Set line height to 40 staff spaces
4096 @subsection Scheme output
4097 @cindex Scheme output
4099 In the typesetting stage, LilyPond builds a page description, which is
4100 then written to disk in postscript, @TeX{} or ASCII art. Before it is
4101 written, the page description is represented as Scheme expressions. You
4102 can also dump these Scheme expressions to a file, which may be
4103 convenient for debugging output routines. This is done with the Scheme
4107 $ lilypond -fscm foo.ly
4108 GNU LilyPond 1.3.144
4109 Now processing: `foo.ly'
4111 Interpreting music...[3]
4112 Preprocessing elements...
4113 Calculating column positions...
4114 paper output to foo.scm...
4117 ;;; Usage: guile -s x.scm > x.tex
4118 (primitive-load-path 'standalone.scm)
4122 $ guile -s foo.scm > foo.tex
4126 @node ASCIIScript output
4127 @subsection ASCIIScript output
4128 @cindex ASCIIScript output
4129 @cindex ascii script
4132 LilyPond can output ASCII Art. This is a two step process, LilyPond
4133 produces an ASCII description file, dubbed ASCIIScript (extension
4134 @file{.as}). ASCIIScript has a small and simple command set that
4135 includes font selection, character and string printing and line drawing
4136 commands. The program @file{as2text} is used to translate an .as file
4139 To produce ASCII Art, you must include an ASCII Art paper definition
4140 file in your .ly, one of:
4142 \include "paper-as5.ly"
4143 \include "paper-as9.ly"
4146 Here's an example use for ASCII Art output (the example file
4147 @file{as-email.ly} is included in the LilyPond distribution), the staff
4148 symbol has been made invisible:
4151 $ lilypond -fas as-email.ly
4152 GNU LilyPond 1.3.144
4153 Now processing: `as-email.ly'
4155 Interpreting music...[3]
4156 Preprocessing elements...
4157 Calculating column positions... [2]
4158 paper output to as-email.as...
4160 $ as2text as-email.as 2>/dev/null
4162 |/ |##|##| | | | | |
4163 /| | | | | |\ |\ |\ |\ |\ |
4164 / |_ 3 | | | | 5 | )| )| )| )| )|
4165 | /| \ 8 * * * | 8 * * * * * |
4175 The ASCII Art fonts are far from complete and not very well designed.
4176 It's easy to change the glyphs, though; if you think you can do better,
4177 have a look at @file{mf/*.af}.
4179 Lots of resizable symbols such as slurs, ties and tuplets are missing.
4181 The poor looks of most ASCII Art output and its limited general
4182 usefulness gives ASCII Art output a low priority; it may be
4183 dropped in future versions.
4190 LilyPond can produce MIDI output. The performance lacks lots of
4191 interesting effects, such as swing, articulation, slurring, etc., but it
4192 is good enough for proof-hearing the music you have entered. Ties,
4193 dynamics and tempo changes are interpreted.
4195 Dynamic marks, crescendi and decrescendi translate into MIDI volume
4196 levels. Dynamic marks translate to a fixed fraction of the available
4197 MIDI volume range, crescendi and decrescendi make the the volume vary
4198 linearly between their two extremities. The fractions be adjusted by
4199 overriding the @code{absolute-volume-alist} defined in
4200 @file{scm/midi.scm}.
4202 For each type of musical instrument (that MIDI supports), a volume range
4203 can be defined. This gives you basic equalizer control, which can
4204 enhance the quality of the MIDI output remarkably. You can add
4205 instruments and ranges or change the default settings by overriding the
4206 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
4208 Both loudness controls are combined to produce the final MIDI volume.
4213 It is currently not possible to use the percussion channel (generally
4214 channel 10 of a MIDI file).
4218 * MIDI instrument names::
4223 @subsection MIDI block
4227 The MIDI block is analogous to the paper block, but it is somewhat
4228 simpler. The @code{\midi} block can contain:
4232 @item a @code{\tempo} definition
4233 @item context definitions
4236 Assignments in the @code{\midi} block are not allowed.
4240 @cindex context definition
4242 Context definitions follow precisely the same syntax as within the
4243 \paper block. Translation modules for sound are called performers.
4244 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
4247 @node MIDI instrument names
4248 @subsection MIDI instrument names
4250 @cindex instrument names
4251 @cindex @code{Staff.midiInstrument}
4252 @cindex @code{Staff.instrument}
4254 The MIDI instrument name is set by the @code{Staff.midiInstrument}
4255 property or, if that property is not set, the @code{Staff.instrument}
4256 property. The instrument name should be chosen from the list in
4257 @ref{MIDI instruments}.
4261 If the selected string does not exactly match, then LilyPond uses the
4262 default (Grand Piano). It is not possible to select an instrument by
4272 @c FIXME: Note entry vs Music entry at top level menu is confusing.
4275 @section Music entry
4283 When entering music with LilyPond, it is easy to introduce errors. This
4284 section deals with tricks and features that help you enter music, and
4285 find and correct mistakes.
4289 @subsection Relative
4291 @cindex relative octave specification
4293 Octaves are specified by adding @code{'} and @code{,} to pitch names.
4294 When you copy existing music, it is easy to accidentally put a pitch in
4295 the wrong octave and hard to find such an error. To prevent these
4296 errors, LilyPond features octave entry.
4298 @cindex @code{\relative}
4300 \relative @var{startpitch} @var{musicexpr}
4303 The octave of notes that appear in @var{musicexpr} are calculated as
4304 follows: If no octave changing marks are used, the basic interval
4305 between this and the last note is always taken to be a fourth or less
4306 (This distance is determined without regarding alterations; a
4307 @code{fisis} following a @code{ceses} will be put above the
4310 The octave changing marks @code{'} and @code{,} can be added to raise or
4311 lower the pitch by an extra octave. Upon entering relative mode, an
4312 absolute starting pitch must be specified that will act as the
4313 predecessor of the first note of @var{musicexpr}.
4315 Entering music that changes octave frequently is easy in relative mode.
4316 @lilypond[fragment,singleline,verbatim,center]
4322 And octave changing marks are used for intervals greater than a fourth.
4323 @lilypond[fragment,verbatim,center]
4325 c g c f, c' a, e'' }
4328 If the preceding item is a chord, the first note of the chord is used
4329 to determine the first note of the next chord. However, other notes
4330 within the second chord are determined by looking at the immediately
4333 @lilypond[fragment,verbatim,center]
4340 @cindex @code{\notes}
4342 The pitch after the @code{\relative} contains a note name. To parse
4343 the pitch as a note name, you have to be in note mode, so there must
4344 be a surrounding @code{\notes} keyword (which is not
4347 The relative conversion will not affect @code{\transpose},
4348 @code{\chords} or @code{\relative} sections in its argument. If you
4349 want to use relative within transposed music, you must place an
4350 additional @code{\relative} inside the @code{\transpose}.
4355 @subsection Bar check
4359 @cindex @code{barCheckNoSynchronize}
4363 Whenever a bar check is encountered during interpretation, a warning
4364 message is issued if it doesn't fall at a measure boundary. This can
4365 help you find errors in the input. Depending on the value of
4366 @code{barCheckNoSynchronize}, the beginning of the measure will be
4367 relocated, so this can also be used to shorten measures.
4369 A bar check is entered using the bar symbol, @code{|}:
4371 \time 3/4 c2 e4 | g2.
4376 @cindex skipTypesetting
4378 Failed bar checks are most often caused by entering incorrect
4379 durations. Incorrect durations often completely garble up the score,
4380 especially if it is polyphonic, so you should start correcting the score
4381 by scanning for failed bar checks and incorrect durations. To speed up
4382 this process, you can use @code{skipTypesetting} (See @ref{Skipping
4383 corrected music})). Bar
4386 @c . {Point and click}
4387 @node Point and click
4388 @subsection Point and click
4390 Point and click lets you find notes in the input by clicking on them in
4391 the Xdvi window. This makes it very easy to find input that causes some
4392 error in the sheet music.
4394 To use it, you need the following software
4396 @unnumberedsubsec Installation
4400 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
4401 Xdvi} version 22.36 or newer.
4403 Note that most @TeX{} distributions ship with xdvik, which is a
4404 different and less well maintained program. To find out which xdvi you
4405 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
4409 Xdvi must be configured to find the TeX fonts and music
4410 fonts. Refer to the Xdvi documentation for more information.
4413 @unnumberedsubsec Using it
4415 Add one of these lines to the top of your .ly file. The first one is for
4416 line location only. The second one is more convenient, but requires
4417 patching @code{emacsclient} and @code{server.el}.
4420 #(set! point-and-click line-location)
4423 In the emacs startup file (usually @file{~/.emacs}), add the following
4428 Make sure that the environment variable @code{XEDITOR} is set
4431 emacsclient --no-wait +%l %f
4433 The second one, that also specifies the column, only works if you have
4434 patched your emacsclient and server, and have compiled your @code{.ly}
4435 file using the @code{line-column-location} setting.
4437 When viewing, control-mousebutton 1 will take you to the originating
4438 spot in the @file{.ly} file. Control-mousebutton 2 will show all
4442 @unnumberedsubsec Column location
4444 If you want emacs to jump to the exact spot (and not just the line) on a
4445 click, you must enable column positioning. To do so, you need to patch
4446 emacsclient. Apply @file{emacsclient.patch} (included with the source
4447 package) to @file{emacsclient.c} and @file{server.el} from the emacs
4448 source code. Recompile and stick the recompiled emacsclient into a bin
4449 directory, and put @file{server.el} into a elisp directory
4450 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
4451 init file, before invoking server-start.
4454 (setq load-path (cons "~/usr/share/emacs" load-path))
4457 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
4459 At the top of the @code{ly} file, replace the @code{set!} line with the
4462 #(set! point-and-click line-column-location)
4465 One final hint: if you correct large files with point-and-click, then
4466 start correcting at the end of the file. When you start at the top, and
4467 insert one line, all subsequent locations will be off by a line.
4472 When you convert the @TeX{} file to PostScript using @code{dvips}, it
4473 will complain about not finding @code{src:X:Y} files. Those complaints
4474 are harmless, and can be ignored.
4476 @node Skipping corrected music
4477 @section Skipping corrected music
4479 The property @code{Score.skipTypesetting} can be used to switch on and
4480 off typesetting completely during the interpretation phase. When
4481 typesetting is switched off, the music is processed much more quickly.
4482 You can use this to skip over the parts of a score that you have already
4485 @lilypond[fragment,singleline,verbatim]
4486 \relative c'' { c8 d
4487 \property Score.skipTypesetting = ##t
4489 \property Score.skipTypesetting = ##f
4494 @node Interpretation context
4495 @section Interpretation context
4498 * Creating contexts::
4499 * Default contexts::
4500 * Context properties::
4501 * Engravers and performers::
4502 * Changing context definitions::
4503 * Defining new contexts::
4507 Interpretation contexts are objects that only exist during a run of
4508 LilyPond. During the interpretation phase of LilyPond (when it prints
4509 "interpreting music"), the music expression in a @code{\score} block is
4510 interpreted in time order. This is the same order that humans hear and
4513 During this interpretation, the interpretation context holds the
4514 state for the current point within the music. It contains information
4518 @item What notes are playing at this point?
4519 @item What symbols will be printed at this point?
4520 @item What is the current key signature, time signature, point within
4524 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4525 contained in a @internalsref{Staff} context (because a staff can contain
4526 multiple voices at any point), a @internalsref{Staff} context is contained in
4527 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4529 Contexts associated with sheet music output are called @emph{notation
4530 contexts}, those for sound output are called @emph{performance
4531 contexts}. The default definitions of the standard notation and
4532 performance contexts can be found in @file{ly/engraver-init.ly} and
4533 @file{ly/performer-init.ly}, respectively.
4535 @node Creating contexts
4536 @subsection Creating contexts
4538 @cindex @code{\context}
4539 @cindex context selection
4541 Contexts for a music expression can be selected manually, using the
4542 following music expression.
4545 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4548 This instructs lilypond to interpret @var{musicexpr} within the context
4549 of type @var{contexttype} and with name @var{contextname}. If this
4550 context does not exist, it will be created.
4552 @lilypond[verbatim,singleline]
4554 \notes \relative c'' {
4555 c4 <d4 \context Staff = "another" e4> f
4561 In this example, the @code{c} and @code{d} are printed on the
4562 default staff. For the @code{e}, a context Staff called
4563 @code{another} is specified; since that does not exist, a new
4564 context is created. Within @code{another}, a (default) Voice context
4565 is created for the @code{e4}. When all music referring to a
4566 context is finished, the context is ended as well. So after the
4567 third quarter, @code{another} is removed.
4571 @node Default contexts
4572 @subsection Default contexts
4574 Most music expressions don't need an explicit @code{\context}
4575 declaration: they inherit the
4576 notation context from their parent. Each note is a music expression, and
4577 as you can see in the following example, only the sequential music
4578 enclosing the three notes has an explicit context.
4580 @lilypond[verbatim,singleline]
4581 \score { \notes \context Voice = goUp { c'4 d' e' } }
4584 There are some quirks that you must keep in mind when dealing with
4587 First, every top level music is interpreted by the Score context, in other
4588 words, you may think of @code{\score} working like
4591 \context Score @var{music}
4595 Second, contexts are created automatically to be able to interpret the
4596 music expressions. Consider the following example.
4598 @lilypond[verbatim, singleline]
4599 \score { \context Score \notes { c'4 ( d' )e' } }
4602 The sequential music is interpreted by the Score context initially
4603 (notice that the @code{\context} specification is redundant), but when a
4604 note is encountered, contexts are setup to accept that note. In this
4605 case, a Thread, Voice and Staff are created. The rest of the sequential
4606 music is also interpreted with the same Thread, Voice and Staff context,
4607 putting the notes on the same staff, in the same voice.
4609 This is a convenient mechanism, but do not expect opening chords to work
4610 without @code{\context}. For every note, a separate staff is
4613 @cindex explicit context
4614 @cindex starting with chords
4615 @cindex chords, starting with
4617 @lilypond[verbatim, singleline]
4618 \score { \notes <c'4 es'> }
4621 Of course, if the chord is preceded by a normal note in sequential
4622 music, the chord will be interpreted by the Thread of the preceding
4624 @lilypond[verbatim,singleline]
4625 \score { \notes { c'4 <c'4 es'> } }
4630 @node Context properties
4631 @subsection Context properties
4633 Notation contexts have properties. These properties are from
4634 the @file{.ly} file using the following expression:
4635 @cindex @code{\property}
4637 \property @var{contextname}.@var{propname} = @var{value}
4640 Sets the @var{propname} property of the context @var{contextname} to the
4641 specified Scheme expression @var{value}. All @var{propname} and
4642 @var{contextname} are strings, which are typically unquoted.
4644 Properties that are set in one context are inherited by all of the
4645 contained contexts. This means that a property valid for the
4646 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4647 example) and thus take effect in all @internalsref{Voice} contexts.
4649 Properties can be unset using the following expression:
4651 \property @var{contextname}.@var{propname} \unset
4654 @cindex properties, unsetting
4655 @cindex @code{\unset}
4657 This removes the definition of @var{propname} in @var{contextname}. If
4658 @var{propname} was not defined in @var{contextname} (but was inherited
4659 from a higher context), then this has no effect.
4664 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4665 the inverse of @code{\property \set}.
4667 @node Engravers and performers
4668 @subsection Engravers and performers
4672 Basic building blocks of translation are called engravers; they are
4673 special C++ classes.
4677 @c . {Context definitions}
4678 @node Changing context definitions
4679 @subsection Changing context definitions
4681 @cindex context definition
4682 @cindex translator definition
4684 The most common way to define a context is by extending an existing
4685 context. You can change an existing context from the paper block, by
4686 first initializing a translator with an existing context identifier:
4690 @var{context-identifier}
4693 Then you can add and remove engravers using the following syntax:
4695 \remove @var{engravername}
4696 \consists @var{engravername}
4700 Here @var{engravername} is a string, the name of an engraver in the
4704 @lilypond[verbatim,singleline]
4708 \translator { \StaffContext
4709 \remove Clef_engraver
4715 You can also set properties in a translator definition. The syntax is as
4718 @var{propname} = @var{value}
4719 @var{propname} \set @var{grob-propname} = @var{pvalue}
4720 @var{propname} \override @var{grob-propname} = @var{pvalue}
4721 @var{propname} \revert @var{grob-propname}
4723 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4724 and @code{pvalue} are Scheme expressions. These type of property
4725 assignments happen before interpretation starts, so a @code{\property}
4726 command will override any predefined settings.
4729 To simplify editing translators, all standard contexts have standard
4730 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4731 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
4733 @node Defining new contexts
4734 @subsection Defining new contexts
4736 If you want to build a context from scratch, you must also supply the
4737 following extra information:
4739 @item A name, specified by @code{\name @var{contextname}}.
4741 @item A cooperation module. This is specified by @code{\type
4748 \type "Engraver_group_engraver"
4751 \consists "Staff_symbol_engraver"
4752 \consists "Note_head_engraver"
4753 \consistsend "Axis_group_engraver"
4757 The argument of @code{\type} is the name for a special engraver that
4758 handles cooperation between simple engravers such as
4759 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4760 for this engraver are the following:
4762 @cindex @code{Engraver_group_engraver}
4763 @item @code{Engraver_group_engraver}
4764 The standard cooperation engraver.
4766 @cindex @code{Score_engraver}
4768 @item @code{Score_engraver}
4769 This is cooperation module that should be in the top level context,
4770 and only the top level context.
4772 @cindex @code{Grace_engraver_group}
4774 @item @code{Grace_engraver_group}
4775 This is a special cooperation module (resembling
4776 @code{Score_engraver}) that is used to create an embedded
4783 @item @code{\alias} @var{alternate-name}
4784 This specifies a different name. In the above example,
4785 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4787 @item @code{\consistsend} @var{engravername}
4788 Analogous to @code{\consists}, but makes sure that
4789 @var{engravername} is always added to the end of the list of
4792 Some engraver types need to be at the end of the list; this
4793 insures they stay there even if a user adds or removes engravers.
4794 End-users generally don't need this command.
4796 @item @code{\accepts} @var{contextname}
4797 Add @var{contextname} to the list of contexts this context can
4798 contain in the context hierarchy. The first listed context is the
4799 context to create by default.
4801 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4802 completeness, but is never used in practice.
4805 @item @code{\name} @var{contextname}
4806 This sets the type name of the context, e.g. @internalsref{Staff},
4807 @internalsref{Voice}. If the name is not specified, the translator won't do
4811 In the @code{\paper} block, it is also possible to define translator
4812 identifiers. Like other block identifiers, the identifier can only
4813 be used as the very first item of a translator. In order to define
4814 such an identifier outside of @code{\score}, you must do
4819 foo = \translator @{ @dots{} @}
4826 \translator @{ \foo @dots{} @}
4834 @cindex paper types, engravers, and pre-defined translators
4841 @c . {Syntactic details}
4842 @node Syntactic details
4843 @section Syntactic details
4844 @cindex Syntactic details
4846 This section describes details that were too boring to be put elsewhere.
4851 * Music expressions::
4852 * Manipulating music expressions::
4860 @subsection Top level
4863 This section describes what you may enter at top level.
4867 @subsubsection Score
4870 @cindex score definition
4872 The output is generated combining a music expression with an output
4873 definition. A score block has the following syntax:
4876 \score @{ @var{musicexpr} @var{outputdefs} @}
4879 @var{outputdefs} are zero or more output definitions. If none is
4880 supplied, the default @code{\paper} block will be added.
4884 @c . {Default output}
4885 @subsubsection Default output
4887 Default values for the @code{\paper} and @code{\midi} block are set by
4888 entering such a block at the top level.
4891 @subsubsection Header
4893 @cindex @code{\header}
4896 A header describes bibliographic information of the file's contents. It
4897 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4898 use this information for generating titles. Key values that are used by
4899 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4900 meter, arranger, piece and tagline.
4902 @cindex @code{ly2dvi}
4906 \header @{ @var{key1} = @var{val1}
4907 @var{key2} = @var{val2} @dots{} @}
4910 It is customary to put the @code{\header} at the top of the file.
4912 @subsubsection Default output
4914 A @code{\midi} or @code{\paper} block at top level sets the default
4915 paper block for all scores that lack an explicit paper block.
4919 @subsection Identifiers
4923 What has this section got to do with identifiers?
4924 It seems more appropriate in the introduction to Chapter 4,
4930 All of the information in a LilyPond input file, is internally
4931 represented as a Scheme value. In addition to normal Scheme data types
4932 (such as pair, number, boolean, etc.), LilyPond has a number of
4933 specialized data types,
4940 @item Translator_def
4944 @item Music_output_def
4945 @item Moment (rational number)
4948 LilyPond also includes some transient object types. Objects of these
4949 types are built during a LilyPond run, and do not `exist' per se within
4950 your input file. These objects are created as a result of your input
4951 file, so you can include commands in the input to manipulate them,
4952 during a lilypond run.
4955 @item Grob: short for Graphical object. See @ref{Grobs}.
4956 @item Molecule: device-independent page output object,
4957 including dimensions. Produced by some Grob functions
4959 @item Translator: object that produces audio objects or Grobs. This is
4960 not yet user accessible.
4961 @item Font_metric: object representing a font.
4965 @node Music expressions
4966 @subsection Music expressions
4968 @cindex music expressions
4970 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4971 syllables are music expressions, and you can combine music expressions
4972 to form new ones, for example by enclosing a list of expressions in
4973 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4974 compound expression is formed out of the quarter note @code{c} and a
4975 quarter note @code{d}:
4978 \sequential @{ c4 d4 @}
4981 @cindex Sequential music
4982 @cindex @code{\sequential}
4983 @cindex sequential music
4986 @cindex Simultaneous music
4987 @cindex @code{\simultaneous}
4989 The two basic compound music expressions are simultaneous and
4993 \sequential @code{@{} @var{musicexprlist} @code{@}}
4994 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4996 For both, there is a shorthand:
4998 @code{@{} @var{musicexprlist} @code{@}}
5002 @code{<} @var{musicexprlist} @code{>}
5004 for simultaneous music.
5005 In principle, the way in which you nest sequential and simultaneous to
5006 produce music is not relevant. In the following example, three chords
5007 are expressed in two different ways:
5009 @lilypond[fragment,verbatim,center]
5010 \notes \context Voice {
5011 <a c'> <b d' > <c' e'>
5012 < { a b c' } { c' d' e' } >
5017 Other compound music expressions include
5020 \transpose @var{pitch} @var{expr}
5021 \apply @var{func} @var{expr}
5022 \context @var{type} = @var{id} @var{expr}
5023 \times @var{fraction} @var{expr}
5027 @c . {Manipulating music expressions}
5028 @node Manipulating music expressions
5029 @subsection Manipulating music expressions
5031 The @code{\apply} mechanism gives you access to the internal
5032 representation of music. You can write Scheme-functions that operate
5033 directly on it. The syntax is
5035 \apply #@var{func} @var{music}
5037 This means that @var{func} is applied to @var{music}. The function
5038 @var{func} should return a music expression.
5040 This example replaces the text string of a script. It also shows a dump
5041 of the music it processes, which is useful if you want to know more
5042 about how music is stored.
5044 @lilypond[verbatim,singleline]
5045 #(define (testfunc x)
5046 (if (equal? (ly-get-mus-property x 'text) "foo")
5047 (ly-set-mus-property x 'text "bar"))
5049 (ly-set-mus-property x 'elements
5050 (map testfunc (ly-get-mus-property x 'elements)))
5055 \apply #testfunc { c'4_"foo" }
5059 For more information on what is possible, see the automatically
5060 generated documentation.
5063 Directly accessing internal representations is dangerous: the
5064 implementation is subject to changes, so you should avoid this feature
5067 A final example is a function that reverses a piece of music in time:
5069 @lilypond[verbatim,singleline]
5070 #(define (reverse-music music)
5071 (let* ((elements (ly-get-mus-property music 'elements))
5072 (reversed (reverse elements))
5073 (span-dir (ly-get-mus-property music 'span-direction)))
5074 (ly-set-mus-property music 'elements reversed)
5076 (ly-set-mus-property music 'span-direction (- span-dir)))
5077 (map reverse-music reversed)
5080 music = \notes { c'4 d'4( e'4 f'4 }
5082 \score { \context Voice {
5084 \apply #reverse-music \music
5089 More examples are given in the distributed example files in
5092 @c . {Span requests}
5098 @subsubsection Span requests
5099 @cindex Span requests
5101 Notational constructs that start and end on different notes can be
5102 entered using span requests. The syntax is as follows:
5106 \spanrequest @var{startstop} @var{type}
5110 @cindex @code{\start}
5111 @cindex @code{\stop}
5113 This defines a spanning request. The @var{startstop} parameter is either
5114 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
5115 describes what should be started. Much of the syntactic sugar is a
5116 shorthand for @code{\spanrequest}, for example,
5118 @lilypond[fragment,verbatim,center]
5119 c'4-\spanrequest \start "slur"
5120 c'4-\spanrequest \stop "slur"
5123 Among the supported types are @code{crescendo}, @code{decrescendo},
5124 @code{beam}, @code{slur}. This is an internal command. Users are
5125 encouraged to use the shorthands which are defined in the initialization
5126 file @file{spanners.ly}.
5131 @subsection Assignments
5134 Identifiers allow objects to be assigned to names during the parse
5135 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
5136 and to refer to an identifier, you precede its name with a backslash:
5137 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
5138 the input-types listed above. Identifier assignments can appear at top
5139 level in the LilyPond file, but also in @code{\paper} blocks.
5141 An identifier can be created with any string for its name, but you will
5142 only be able to refer to identifiers whose names begin with a letter,
5143 being entirely alphabetical. It is impossible to refer to an identifier
5144 whose name is the same as the name of a keyword.
5146 The right hand side of an identifier assignment is parsed completely
5147 before the assignment is done, so it is allowed to redefine an
5148 identifier in terms of its old value, e.g.
5154 When an identifier is referenced, the information it points to is
5155 copied. For this reason, an identifier reference must always be the
5156 first item in a block.
5160 \paperIdent % wrong and invalid
5164 \paperIdent % correct
5169 @c . {Lexical modes}
5171 @subsection Lexical modes
5172 @cindex Lexical modes
5175 @cindex @code{\notes}
5176 @cindex @code{\chords}
5177 @cindex @code{\lyrics}
5179 To simplify entering notes, lyrics, and chords, LilyPond has three
5180 special input modes in addition to the default mode: note, lyrics and
5181 chords mode. These input modes change the way that normal, unquoted
5182 words are interpreted: for example, the word @code{cis} may be
5183 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
5184 major triad respectively.
5186 A mode switch is entered as a compound music expression
5188 @code{\notes} @var{musicexpr}
5189 @code{\chords} @var{musicexpr}
5190 @code{\lyrics} @var{musicexpr}.
5193 In each of these cases, these expressions do not add anything to the
5194 meaning of their arguments. They just instruct the parser in what mode
5195 to parse their arguments. The modes are treated in more detail in
5196 @ref{Lyrics} and @ref{Chords}.
5198 Different input modes may be nested.
5202 @subsection Ambiguities
5207 The grammar contains a number of ambiguities. We hope to resolve them at
5211 @item The assignment
5216 is interpreted as the string identifier assignment. However,
5217 it can also be interpreted as making a string identifier @code{\foo}
5218 containing @code{"bar"}, or a music identifier @code{\foo}
5219 containing the syllable `bar'.
5221 @item If you do a nested repeat like
5233 then it is ambiguous to which @code{\repeat} the
5234 @code{\alternative} belongs. This is the classic if-then-else
5235 dilemma. It may be solved by using braces.
5237 @item The parser is not sophisticated enough to distinguish at the
5239 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
5246 @c . {Lexical details}
5247 @node Lexical details
5248 @section Lexical details
5250 Even more boring details, now on lexical side of the input parser.
5261 * Version information::
5266 @subsection Comments
5269 @cindex block comment
5270 @cindex line comment
5274 A one line comment is introduced by a @code{%} character.
5275 Block comments are started by @code{%@{} and ended by @code{%@}}.
5276 They cannot be nested.
5279 @subsection Direct Scheme
5283 @cindex Scheme, in-line code
5286 LilyPond contains a Scheme interpreter (the GUILE library) for
5287 internal use. In some places, Scheme expressions also form valid syntax:
5288 wherever it is allowed,
5292 evaluates the specified Scheme code. Example:
5294 \property Staff.TestObject \override #'foobar = #(+ 1 2)
5296 @code{\override} expects two Scheme expressions, so there are two Scheme
5297 expressions. The first one is a symbol (@code{foobar}), the second one
5298 an integer (namely, 3).
5300 In-line scheme may be used at the top level. In this case the result is
5303 Scheme is a full-blown programming language, and a full discussion is
5304 outside the scope of this document. Interested readers are referred to
5305 the website @uref{http://www.schemers.org/} for more information on
5310 @subsection Keywords
5314 Keywords start with a backslash, followed by a number of lower case
5315 alphabetic characters. These are all the keywords.
5318 apply arpeggio autochange spanrequest commandspanrequest
5319 simultaneous sequential accepts alternative bar breathe
5320 char chordmodifiers chords clef cm consists consistsend
5321 context denies duration dynamicscript elementdescriptions
5322 font grace header in lyrics key mark pitch
5323 time times midi mm name pitchnames notes outputproperty
5324 override set revert partial paper penalty property pt
5325 relative remove repeat addlyrics partcombine score
5326 script stylesheet skip textscript tempo translator
5331 @subsection Integers
5339 Formed from an optional minus sign followed by digits. Arithmetic
5340 operations cannot be done with integers, and integers cannot be mixed
5345 @cindex real numbers
5351 Formed from an optional minus sign and a sequence of digits followed
5352 by a @emph{required} decimal point and an optional exponent such as
5353 @code{-1.2e3}. Reals can be built up using the usual operations:
5354 `@code{+}', `@code{-}', `@code{*}', and
5355 `@code{/}', with parentheses for grouping.
5363 A real constant can be followed by one of the dimension keywords:
5364 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5365 points, inches and centimeters, respectively. This converts the number
5366 a number that is the internal representation of that dimension.
5374 Begins and ends with the @code{"} character. To include a @code{"}
5375 character in a string write @code{\"}. Various other backslash
5376 sequences have special interpretations as in the C language. A string
5377 that contains no spaces can be written without the quotes. Strings can
5378 be concatenated with the @code{+} operator.
5382 @subsection Main input
5385 @cindex @code{\maininput}
5387 The @code{\maininput} command is used in init files to signal that the
5388 user file must be read. This command cannot be used in a user file.
5390 @node File inclusion
5391 @subsection File inclusion
5392 @cindex @code{\include}
5394 \include @var{filename}
5397 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5398 unquoted string will not work here!) or a string identifier. The full
5399 filename including the @file{.ly} extension must be given,
5402 @node Version information
5403 @subsection Version information
5404 @cindex @code{\version}
5406 \version @var{string}
5409 Specify the version of LilyPond that a file was written for. The
5410 argument is a version string in quotes, for example @code{"1.2.0"}.
5411 This is used to detect invalid input, and to aid
5412 @code{convert-ly} a tool that automatically upgrades input files. See
5413 See @ref{convert-ly} for more information on @code{convert-ly}.
5421 @c broken with emacs-21
5422 @c {Local emac s vars}
5423 @c Local varia bles:
5425 @c minor-mod e: font-lock
5426 @c minor-mo de: outline
5427 @c outline -layout: (-1 : 0)
5428 @c outlin e-use-mode-specific-leader: "@c \."
5429 @c outli ne-primary-bullet: "{"
5430 @c outli ne-stylish-prefixes: nil
5431 @c outli ne-override-protect: t