3 @c A menu is needed before every deeper *section nesting of @node's; run
4 @c M-x texinfo-all-menus-update
5 @c to automagically fill in these menus before saving changes
7 @c FIXME: singular vs. plural: Beams/Beam
16 @macro internalsref{NAME}
17 @uref{../lilypond-internals/\NAME\.html,\NAME\}
20 @macro seeinternals{NAME}
21 See @internalsref{\NAME\}
27 @macro seeinternals{NAME}
29 @macro internalsref{NAME}
34 @c .{Reference Manual}
36 @node Reference Manual
37 @chapter Reference Manual
40 <!--- @@WEB-TITLE@@=Reference Manual --->
43 This document describes GNU LilyPond and its input format. The last
44 revision of this document was made for LilyPond 1.4.1. It supposes a
45 passing familiarity with how LilyPond input works. New users are
46 encouraged to study the tutorial first.
70 * Skipping corrected music::
71 * Interpretation context::
76 @c FIXME: Note entry vs Music entry at top level menu is confusing.
82 The most basic forms of music are notes. Notes on their own don't
83 form valid input, but for the sake of brevity we omit @code{\score}
84 blocks and @code{\paper} declarations.
90 * Chromatic alterations::
95 * Automatic note splitting ::
97 * Defining pitch names::
98 * Easy Notation note heads ::
106 A note is printed by specifying its pitch, and then its duration.
107 @lilypond[fragment,verbatim]
110 The grob for a note head is called @internalsref{NoteHead}.
117 @cindex Note specification
119 @cindex entering notes
121 The verbose syntax for pitch specification is
123 @cindex @code{\pitch}
125 \pitch @var{scmpitch}
128 @var{scmpitch} is a pitch scheme object.
130 In Note and Chord mode, pitches may be designated by names. The default
131 names are the Dutch note names. The notes are specified by the letters
132 @code{a} through @code{g} (where the octave is formed by notes ranging
133 from @code{c} to @code{b}). The pitch @code{c} is an octave below
134 middle C and the letters span the octave above that C.
136 @cindex note names, Dutch
138 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
139 name and a flat is formed by adding @code{-es}. Double sharps and double
140 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
141 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
142 both forms are accepted.
144 LilyPond has predefined sets of note names for various other languages.
145 To use them, simply include the language specific init file. For
146 example: @code{\include "english.ly"}. The available language files and
147 the names they define are:
150 Note Names sharp flat
151 nederlands.ly c d e f g a bes b -is -es
152 english.ly c d e f g a bf b -s/-sharp -f/-flat
153 deutsch.ly c d e f g a b h -is -es
154 norsk.ly c d e f g a b h -iss/-is -ess/-es
155 svenska.ly c d e f g a b h -iss -ess
156 italiano.ly do re mi fa sol la sib si -d -b
157 catalan.ly do re mi fa sol la sib si -d/-s -b
165 The optional octave specification takes the form of a series of
166 single quote (`@code{'}') characters or a series of comma
167 (`@code{,}') characters. Each @code{'} raises the pitch by one
168 octave; each @code{,} lowers the pitch by an octave.
170 @lilypond[fragment,verbatim,center]
171 c' c'' es' g' as' gisis' ais'
174 @node Chromatic alterations
175 @subsection Chromatic alterations
177 Normally Accidentals signify that the pitch of a note differs from the
178 key signature. Normally, they are printed automatically depending, but
179 you may force accidentals in the following ways:
180 A reminder accidental
181 @cindex reminder accidental
183 can be forced by adding an exclamation mark @code{!} after the pitch. A
184 cautionary accidental,
185 @cindex cautionary accidental
186 @cindex parenthesized accidental
187 i.e., an accidental within parentheses can be obtained by adding the
188 question mark `@code{?}' after the pitch.
190 Each accidental symbol is an @internalsref{Accidental} grob. The
191 placement of accidentals is handled by
192 @internalsref{AccidentalPlacement}.
200 A rest is entered like a note, with note name `@code{r}':
202 @lilypond[singleline,verbatim]
206 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
207 specified using @code{R}, see @ref{Multi measure rests}.
209 For polyphonic music, it can be convenient to specify the rest position
210 directly. You can do that by entering a note, with the keyword
211 @code{\rest} appended, e.g. Rest collisions will leave these rests alone.
213 @lilypond[singleline,verbatim]
223 @cindex Invisible rest
226 An invisible rest, or skip, can be entered like a note with note name
227 @code{s}, or with @code{\skip @var{duration}}:
229 @lilypond[singleline,verbatim]
233 The @code{s} syntax is only available in Note mode and Chord mode.
234 In other situations, you should use the @code{\skip} command, and it is
235 only available in Note mode and Chord mode.
237 @c FIXME: in lyrics mode, we have " " and _
239 In Lyrics mode, you can use `@code{" "}' and `@code{_}':
240 @lilypond[singleline,verbatim]
242 \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
243 \notes\relative c'' { a2 a4 a a2 a4 a }
247 The unabbreviated `@code{\skip} @var{duration}' also works outside of
250 @lilypond[singleline,verbatim]
253 { \time 4/8 \skip 2 \time 4/4 }
254 \notes\relative c'' { a2 a1 }
259 The skip command is merely a empty musical placeholder. It does not
260 produce any output, not even transparent output.
265 @subsection Durations
269 @cindex @code{\duration}
271 The syntax for a verbose duration specification is
273 \duration @var{scmduration}
275 Here, @var{scmduration} is a Scheme object of type @code{Duration}.
278 In Note, Chord, and Lyrics mode, durations may be designated by numbers
279 and dots: durations are entered as their reciprocal values. For notes
280 longer than a whole you must use identifiers.
284 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
286 r1 r2 r4 r8 r16 r32 r64 r64
292 \notes \relative c'' {
294 a1 a2 a4 a8 a16 a32 a64 a64
296 r1 r2 r4 r8 r16 r32 r64 r64
301 \remove "Clef_engraver"
302 \remove "Staff_symbol_engraver"
303 \remove "Time_signature_engraver"
304 \consists "Pitch_squash_engraver"
311 If the duration is omitted then it is set to the previous duration
312 entered. At the start of parsing a quarter note is assumed. The
313 duration can be followed by dots (`@code{.}') to obtain dotted note
317 @lilypond[fragment,verbatim,center]
323 You can alter the length of duration by a fraction @var{N/M} by
324 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
325 will not affect the appearance of the notes or rests produced.
337 A tie connects two adjacent note heads of the same pitch. The tie in
338 effect extends the length of a note. A tie is entered with @code{~}.
340 @lilypond[fragment,verbatim,center]
341 e' ~ e' <c' e' g'> ~ <c' e' g'>
344 When ties are used with chords, all note heads whose pitches match are
345 connected. Ties are indicated using the tilde symbol `@code{~}'. If
346 you try to tie together chords which have no common pitches then no
347 ties will be created.
349 If you want less ties created for a chord, you can set
350 @code{Voice.sparseTies} to true. In this case, a single tie is used
351 for every tied chord.
352 @lilypond[fragment,verbatim,center]
353 \property Voice.sparseTies = ##t
354 <c' e' g'> ~ <c' e' g'>
357 In its meaning a tie is just a way of extending a note duration, similar
358 to the augmentation dot: the following example are two ways of notating
359 exactly the same concept.
361 @lilypond[fragment, singleline]
362 \time 3/4 c'2. c'2 ~ c'4
364 Ties should not be confused with slurs, which indicate articulation,
365 and phrasing slurs, which indicate musical phrasing.
367 The name of the tie grob is @internalsref{Tie}, and it is created in the
368 @internalsref{Voice} context.
372 At present, the tie is implemented as a separate thing, temporally
373 located in between the notes.
374 Tieing only a subset of the note heads of a chord is not supported in a
375 simple way. It can be achieved by moving the tie-engraver into the Thread
376 context and turning on and off ties per Thread.
378 @node Automatic note splitting
379 @subsection Automatic note splitting
381 There is a facility for automatically converting long notes to tied
382 notes. This is done by replacing the @code{Note_heads_engraver} by the
383 @code{Completion_heads_engraver}.
385 @lilypond[verbatim,center]
387 \notes\relative c'{ \time 2/4
388 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
392 \remove "Note_heads_engraver"
393 \consists "Completion_heads_engraver"
397 This engraver splits all running notes at the bar line, and inserts
398 ties. One of the uses of this is, is to debug complex scores: if the
399 measures are not entirely filled, then the ties exactly show how much
404 Not all durations (especially those containing tuplets) can be
405 represented exactly; the engraver will not insert tuplets.
412 @cindex @code{\times}
414 Tuplets are made out of a music expression by multiplying all duration
417 @cindex @code{\times}
419 \times @var{fraction} @var{musicexpr}
422 The duration of @var{musicexpr} will be multiplied by the fraction.
423 In print, the fraction's denominator will be printed over the notes,
424 optionally with a bracket. The most common tuplet is the triplet in
425 which 3 notes have the length of 2, so the notes are 2/3 of
426 their written length:
428 @lilypond[fragment,verbatim,center]
429 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
432 The property @code{tupletSpannerDuration} specifies how long each bracket
433 should last. With this, you can make lots of tuplets while typing
434 @code{\times} only once, thus saving typing work.
436 @lilypond[fragment, relative, singleline, verbatim]
437 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
438 \times 2/3 { c'8 c c c c c }
441 The format of the number is determined by the property
442 @code{tupletNumberFormatFunction}. The default prints only the
443 denominator, but if you set it to the Scheme function
444 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
449 The typesetting of brackets and numbers is controlled by the properties
450 @code{bracket-visibility} and @code{number-visibility}. These
451 properties can either be @code{#f}, @code{#t} or @code{'if-no-beam},
452 meaning respectively off, on, and on if there is no beam.
454 @lilypond[fragment, relative, singleline, verbatim]
455 \property Voice.TupletBracket \set #'bracket-visibility = ##t
456 \times 2/3{c'8 d e} \times 2/3{d4 e8}
457 \property Voice.TupletBracket \set #'bracket-visibility = #'if-no-beam
458 \times 2/3{c d e} \times 2/3{d4 e8}
459 \property Voice.TupletBracket \set #'bracket-visibility = ##f
460 \times 2/3{c d e} \times 2/3{d4 e8}
461 \property Voice.TupletBracket \set #'number-visibility = ##f
462 \times 2/3{c d e} \times 2/3{d4 e8}
463 \property Voice.TupletBracket \set #'number-visibility = #'if-no-beam
464 \times 2/3{c d e} \times 2/3{d4 e8}
467 @cindex @code{tupletNumberFormatFunction}
468 @cindex tuplet formatting
470 Tuplet brackets are printed as @internalsref{TupletBracket} grobs in
471 the @internalsref{Voice} context.
473 @c . {Defining pitch names}
474 @node Defining pitch names
475 @subsection Defining pitch names
477 @cindex defining pitch names
478 @cindex pitch names, defining
480 Note names and chord modifiers can be customized for nationalities. The
481 syntax is as follows.
483 @cindex @code{\pitchnames}
484 @cindex @code{\chordmodifiers}
486 \pitchnames @var{scheme-alist}
487 \chordmodifiers @var{scheme-alist}
490 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers-init.ly} for
491 specific examples on how to do this.
494 @node Easy Notation note heads
495 @subsection Easy Notation note heads
497 @cindex easy notation
500 A entirely different type of note head is the "easyplay" note head: a
501 note head that includes a note name. It is used in some publications by
502 Hal-Leonard Inc. music publishers.
504 @lilypond[singleline,verbatim]
505 \include "paper23.ly"
507 \notes { c'2 e'4 f' | g'1 }
508 \paper { \translator { \EasyNotation } }
512 Note that @internalsref{EasyNotation} overrides a @internalsref{Score} context. You
513 probably will want to print it with magnification to make it more
514 readable, see @ref{Output scaling}.
520 If you view the result with Xdvi, then staff lines will show through the
521 letters. Printing the postscript file obtained either by using dvips or
522 the @code{-f ps} option of lilypond produces the correct result.
527 @section Staff notation
529 @cindex Staff notation
541 @subsection Key signature
546 Setting or changing the key signature is done with the @code{\key}
549 @code{\key} @var{pitch} @var{type}
552 @cindex @code{\minor}
553 @cindex @code{\major}
554 @cindex @code{\minor}
555 @cindex @code{\ionian}
556 @cindex @code{\locrian}
557 @cindex @code{\aeolian}
558 @cindex @code{\mixolydian}
559 @cindex @code{\lydian}
560 @cindex @code{\phrygian}
561 @cindex @code{\dorian}
563 Here, @var{type} should be @code{\major} or @code{\minor} to get
564 @var{pitch}-major or @var{pitch}-minor, respectively.
565 The standard mode names @code{\ionian},
566 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
567 @code{\phrygian}, and @code{\dorian} are also defined.
569 This command sets the context property @code{Staff.keySignature}.
570 Non-standard key signatures can be specified by setting this property
573 The printed signature is a @internalsref{KeySignature} grob, typically
574 created in @internalsref{Staff} context.
576 @cindex @code{keySignature}
583 The clef can be set or changed with the @code{\clef} command:
584 @lilypond[fragment,verbatim]
585 \key f\major c''2 \clef alto g'2
588 Supported clef-names include
589 @c Moved standard clefs to the top /MB
591 @item treble, violin, G, G2
600 G clef on 1st line, so-called French violin clef
615 By adding @code{_8} or @code{^8} to the clef name, the clef is
616 transposed one octave down or up, respectively. Note that you have to
617 enclose @var{clefname} in quotes if you use underscores or digits in the
623 The grob for this symbol is @internalsref{Clef}.
626 The full syntax for this command is
630 where @var{clefname} is a string. This command is a shortcut for
632 \property Staff.clefGlyph = @var{glyph associated with clefname}
633 \property Staff.clefPosition = @var{clef Y-position for clefname}
634 \property Staff.centralCPosition = @var{position for central C}
635 \property Staff.clefOctavation = @var{extra transposition of clefname}
637 Upon any change in these properties lilypond creates a clef
638 symbol. The mapping from @var{clefname} to the property values can be
639 found in @file{scm/clef.scm}
645 @c . {Time signature}
647 @subsection Time signature
648 @cindex Time signature
652 The time signature is set or changed by the @code{\time}
654 @lilypond[fragment,verbatim]
655 \time 2/4 c'2 \time 3/4 c'2.
658 The actual symbol that's printed can be customized with the style
660 @lilypond[fragment, verbatim, singleline]
662 \property Staff.TimeSignature \override #'style = #'C
664 \property Staff.TimeSignature \override #'style = #'()
666 \property Staff.TimeSignature \override #'style = #'C
670 The grob for this symbol is @internalsref{TimeSignature}. There are
671 many more options for its layout. They are selected through the
672 @code{style} grob property. See @file{input/test/time.ly} for more
676 The full syntax for this command is
678 \time @var{n}@code{/}@var{d}
680 where @var{n} and @var{d} are integers. This command is internally
681 translated, to the following:
683 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
684 \property Score.beatLength = #(make-moment 1 @var{d})
685 \property Score.measureLength = #(make-moment @var{n} @var{d})
688 The property @code{timeSignatureFraction} determine where bar lines
689 should be inserted, and how automatic beams should be generated.
690 Changing the value of @code{timeSignatureFraction} also causes a
691 fraction to be printed.
698 @cindex partial measure
699 @cindex measure, partial
700 @cindex shorten measures
701 @cindex @code{\partial}
703 Partial measures, for example in upbeats, are entered using the
704 @code{\partial} command:
705 @lilypond[fragment,verbatim]
706 \partial 4* 5/16 c'16 c8. f16 a'2. ~ a'8. a'16 | g'1
709 The syntax for this command is
711 \partial @var{duration}
713 This is internally translated into
715 \property Score.measurePosition = -@var{length of duration}
718 The property @code{measurePosition} contains a rational number
719 indicating how much of the measure has passed at this point.
722 @node Unmetered music
723 @subsection Unmetered music
725 Bar lines and bar numbers are calculated automatically. For unmetered
726 music (e.g. cadenzas), this is not desirable. The property
727 @code{Score.timing} can be used to switch off this automatic timing
729 @lilypond[fragment,relative,singleline,verbatim]
731 \property Score.timing = ##f
733 \property Score.timing = ##t
737 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
744 @subsection Bar lines
748 @cindex measure lines
751 Bar lines are inserted automatically by, but if you need a special
752 types of barline, you can force one using the @code{\bar} command:
753 @lilypond[fragment,verbatim]
757 The following bar types are available
758 @lilypond[fragment, relative, singleline, verbatim]
770 You are encouraged to use @code{\repeat} for repetitions. See
773 In scores with many staffs, the barlines are automatically placed at
774 top level, and they are connected between different staffs of a
775 @internalsref{StaffGroup}:
776 @lilypond[fragment, verbatim]
777 < \context StaffGroup <
778 \context Staff = up { e'4 d'
781 \context Staff = down { c4 g e g } >
782 \context Staff = pedal { c2 c2 } >
785 The grobs that are created at @internalsref{Staff} level. The name is
786 @internalsref{BarLine}.
788 The full syntax for this command is
792 where @var{bartype} is a string. This is a shortcut for doing
794 \property Score.whichBar = @var{bartype}
798 @cindex Bar_line_engraver
800 @cindex repeatCommands
801 @cindex defaultBarType
803 Whenever @code{whichBar} is set to a string, a bar line of that type is
804 created. @code{whichBar} is usually set automatically: at the start of
805 a measure it is set to @code{defaultBarType}. The contents of
806 @code{repeatCommands} is used to override default measure bars.
808 @code{whichBar} can also be set directly, using @code{\property} or
809 @code{\bar }. These settings take precedence over the automatic
810 @code{whichBar} settings.
817 Polyphonic parts, i.e. parts with more than one voice on a staff can be
818 typeset with LilyPond.
820 The easiest way to enter such fragments, is the Scheme function
821 @code{voicify-music}. It will split chords using the separator
822 @code{\\}, to make multiple voices. You can use it for small,
823 short-lived voices (make a chord of voices) or for single chords:
825 @lilypond[verbatim,fragment]
826 \context Voice = VA \apply #voicify-music \relative c'' {
827 c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
831 The function @code{voicify-music} instantiates @internalsref{Voice}
832 contexts, bearing the names @code{"1"}, @code{"2"}, etc.
834 To explicity typeset polyphonic music, instantiate a separate Voice
835 context for each part, and use @code{\voiceOne}, up to
836 @code{\voiceFour} to assign a stem directions and horizontal shift for
840 @lilypond[singleline, verbatim]
842 \context Staff < \context Voice = VA { \voiceOne cis2 b }
843 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
844 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
847 The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
848 ties, slurs and stems, and set shift directions.
850 If you want more than four voices, you can also manually set
851 horizontal shifts and stem directions, as is shown in the following example:
852 @lilypond[fragment, verbatim]
853 \context Staff \notes\relative c''<
860 \context Voice=three {
861 \shiftOnn \stemUp ais
863 \context Voice=four {
864 \shiftOnnn \stemUp fis
870 Normally, note heads with a different number of dots are not merged, but
871 if you set the grob property @code{merge-differently-dotted}, they are:
872 @lilypond[verbatim,fragment,singleline]
873 \apply #voicify-music < {
875 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
877 } \\ { [g'8. f16] [g'8. f'16] }
881 Similarly, you can merge half note heads with eighth notes, by setting
882 @code{merge-differently-headed}:
883 @lilypond[fragment, relative=2,verbatim]
884 \apply #voicify-music < {
886 \property Staff.NoteCollision
887 \override #'merge-differently-headed = ##t
888 c8 c4. } \\ { c2 c2 } >
891 LilyPond also vertically shifts rests that are opposite of a stem.
893 @lilypond[singleline,fragment,verbatim]
894 \apply #voicify-music <
899 Note head collisions (horizontal shifting of note heads) are handled by
900 the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
901 handles vertical shifting of rests.
907 Resolving collisions is a very intricate subject, and LilyPond only
908 handles a few situations. When it can not cope, you are advised to use
909 @code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
910 rests to override typesetting decisions.
915 Beams are used to group short notes into chunks that are aligned with
916 the metrum. They are inserted automatically in most cases.
918 @lilypond[fragment,verbatim, relative=2]
919 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
922 If you're not satisfied with the automatic beaming, you can enter the
923 beams explicitly. If you have beaming patterns that differ from the
924 defaults, you can also set the patterns for automatic beamer.
926 The beam symbol is @internalsref{Beam} in @internalsref{Voice}
927 context, both for automatically created and manual beams.
930 @cindex Automatic beams
931 @subsection Manual beams
932 @cindex beams, manual
936 In some cases it may be necessary to override LilyPond's automatic
937 beaming algorithm. For example, the auto beamer will not beam over
938 rests or bar lines, If you want that, specify the begin and end point
939 manually using a @code{[} before the first beamed note and a @code{]}
942 @lilypond[fragment,relative,verbatim]
944 r4 [r8 g' a r8] r8 [g | a] r8
948 @cindex @code{stemLeftBeamCount}
950 Normally, beaming patterns within a beam are determined automatically.
951 When this mechanism fouls up, the properties
952 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
953 be used to control the beam subdivision on a stem. If you set either
954 property, it's value will be used only once, and then it is erased.
956 @lilypond[fragment,relative,verbatim]
959 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
962 @cindex @code{stemRightBeamCount}
965 TODO: FIXME, we don't want this doc here.
967 can be tweaked through
968 grob-property @code{positions}. The value is a pair.
969 specify vertical location of the left and right end point. Both are
970 measured in half staff-spaces, and the middle staff line is the value
973 @li lypond[fragment,relative,verbatim]
974 \property Voice.Beam \set #'position = #
975 \property Voice.Beam \set #'height = #0
979 Here's how you'd specify a weird looking beam that instead of being
980 horizontal, falls two staff spaces:
986 @li lypond[fragment,relative,verbatim]
987 \property Voice.Beam \set #'staff-position = #4
988 \property Voice.Beam \set #'height = #-4
995 Kneed beams are inserted automatically, when a large gap between two
996 adjacent beamed notes is detected. This behavior can be tuned through
997 the grob property @code{auto-knee-gap}.
1001 @cindex auto-knee-gap
1005 @c TODO -> why this ref? Document?
1006 @cindex @code{neutral-direction}
1010 Auto knee beams can not be used together with hara kiri staffs.
1014 * Setting automatic beam behavior ::
1017 @node Beam typography
1018 @subsection Beam typography
1020 One of the strong points of LilyPond is how beams are formatted. Beams
1021 are quantized, meaning that the left and right endpoints beams start
1022 exactly on staff lines. Without quantization, small wedges of white
1023 space appear between the beam and staff line, and this looks untidy.
1025 Beams are also slope-damped: melodies that go up or down should also
1026 have beams that go up or down, but the slope of the beams should be
1027 less than the slope of the notes themselves.
1029 Some beams should be horizontal. These are so-called concave beams.
1031 [TODO: some pictures.]
1034 @c . {Automatic beams}
1035 @node Setting automatic beam behavior
1036 @subsection Setting automatic beam behavior
1038 @cindex @code{autoBeamSettings}
1039 @cindex @code{(end * * * *)}
1040 @cindex @code{(begin * * * *)}
1041 @cindex automatic beams, tuning
1042 @cindex tuning automatic beaming
1044 In normal time signatures, automatic beams can start on any note but can
1045 only end in a few positions within the measure: beams can end on a beat,
1046 or at durations specified by the properties in
1047 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
1048 are defined in @file{scm/auto-beam.scm}.
1050 The value of @code{autoBeamSettings} is changed using
1051 @code{\override} and unset using @code{\revert}:
1053 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
1054 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
1056 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
1057 whether the rule applies to begin or end-points. The quantity
1058 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
1059 *}' designates notes of any length), @var{N}/@var{M} refers to a time
1060 signature (wildcards, `@code{* *}' may be entered to designate all time
1063 For example, if you want automatic beams to end on every quarter note,
1064 you can use the following:
1066 \property Voice.autoBeamSettings \override
1067 #'(end * * * *) = #(make-moment 1 4)
1069 Since the duration of a quarter note is 1/4 of a whole note, it is
1070 entered as @code{(make-moment 1 4)}.
1072 The same syntax can be used to specify beam starting points. In this
1073 example, automatic beams can only end on a dotted quarter note.
1075 \property Voice.autoBeamSettings \override
1076 #'(end * * * *) = #(make-moment 3 8)
1078 In 4/4 time signature, this means that automatic beams could end only on
1079 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1080 3/8 has passed within the measure).
1082 You can also restrict rules to specific time signatures. A rule that
1083 should only be applied in @var{N}/@var{M} time signature is formed by
1084 replacing the second asterisks by @var{N} and @var{M}. For example, a
1085 rule for 6/8 time exclusively looks like
1087 \property Voice.autoBeamSettings \override
1088 #'(begin * * 6 8) = ...
1091 If you want a rule to apply to certain types of beams, you can use the
1092 first pair of asterisks. Beams are classified according to the shortest
1093 note they contain. For a beam ending rule that only applies to beams
1094 with 32nd notes (and no shorter notes), you would use @code{(end 1
1098 @c Automatic beams can not be put on the last note in a score.
1100 If a score ends while an automatic beam has not been ended and is still
1101 accepting notes, this last beam will not be typeset at all.
1103 @cindex automatic beam generation
1105 @cindex @code{Voice.autoBeaming}
1108 For melodies that have lyrics, you may want to switch off
1109 automatic beaming. This is done by setting @code{Voice.autoBeaming} to
1115 It is not possible to specify beaming parameters for beams with mixed
1116 durations, that differ from the beaming parameters of all separate
1117 durations, i.e., you'll have to specify manual beams to get:
1118 @lilypond[fragment,singleline,relative]
1119 \property Voice.autoBeamSettings
1120 \override #'(end * * * *) = #(make-moment 3 8)
1121 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
1124 It is not possible to specify beaming parameters that act differently in
1125 different parts of a measure. This means that it is not possible to use
1126 automatic beaming in irregular meters such as @code{5/8}.
1129 @node Expressive marks
1130 @section Expressive marks
1145 A slur indicates that notes are to be played bound or @emph{legato}.
1146 They are entered using parentheses:
1148 @lilypond[fragment,verbatim,center]
1149 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1153 Slurs avoid crossing stems, and are generally attached to note heads.
1154 However, in some situations with beams, slurs may be attached to stem
1155 ends. If you want to override this layout you can do this through the
1156 grob-property @code{attachment} of @internalsref{Slur} in
1157 @internalsref{Voice} context It's value is a pair of symbols, specifying
1158 the attachment type of the left and right end points.
1160 @lilypond[fragment,relative,verbatim]
1162 \property Voice.Stem \set #'length = #5.5
1164 \property Voice.Slur \set #'attachment = #'(stem . stem)
1168 If a slur would strike through a stem or beam, the slur will be moved
1169 away upward or downward. If this happens, attaching the slur to the
1170 stems might look better:
1172 @lilypond[fragment,relative,verbatim]
1175 \property Voice.Slur \set #'attachment = #'(stem . stem)
1180 Similarly, the curvature of a slur is adjusted to stay clear of note
1181 heads and stems. When that would increase the curvature too much, the
1182 slur is reverted to its default shape. The threshold for this decision
1183 is in @internalsref{Slur}'s grob-property @code{beautiful}. It is loosely
1184 related to the enclosed area between the slur and the notes. Usually,
1185 the default setting works well, but in some cases you may prefer a
1186 curved slur when LilyPond decides for a vertically moved one. You can
1187 indicate this preference by increasing the @code{beautiful} value:
1189 @lilypond[verbatim,singleline,relative]
1191 c16( a' f' a a f a, )c,
1192 c( a' f' a a f d, )c
1193 \property Voice.Slur \override #'beautiful = #5.0
1194 c( a' f' a a f d, )c
1199 Producing nice slurs is a difficult problem, and LilyPond currently
1200 uses a simple, empiric method to produce slurs. In some cases, the
1201 results of this method don't look too good. This is reflected by the
1202 @code{beautiful} parameter. It is an arbitrary parameter in the slur
1203 formatter. Useful values can only be determined by trial and error.
1205 @cindex Adjusting slurs
1207 @node Phrasing slurs
1208 @subsection Phrasing slurs
1210 @cindex phrasing slurs
1211 @cindex phrasing marks
1213 A phrasing slur (or phrasing mark) connects chords and is used to
1214 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1217 @lilypond[fragment,verbatim,center,relative]
1218 \time 6/4 c' \( ( d ) e f ( e ) \) d
1221 Typographically, the phrasing slur behaves almost exactly like a normal
1222 slur. The grob associated with it is @internalsref{PhrasingSlur}, in
1223 @internalsref{Voice} context.
1226 @subsection Breath marks
1228 Breath marks are entered using @code{\breathe}. The result is a
1229 @internalsref{BreathingSign} grob in @internalsref{Voice} context.
1231 @lilypond[fragment,relative]
1240 @cindex beats per minute
1241 @cindex metronome marking
1243 Metronome settings can be entered as follows:
1245 @cindex @code{\tempo}
1247 \tempo @var{duration} = @var{perminute}
1250 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1255 The tempo setting is not printed, but is only used in the MIDI
1256 output. You can trick lily into producing a metronome mark,
1257 though. Details are in @ref{Text markup}.
1262 @subsection Text spanners
1263 @cindex Text spanners
1265 Some textual indications, e.g. rallentando or accelerando, often extend
1266 over many measures. This is indicated by following the text with a
1267 dotted line. You can create such texts using text spanners. The syntax
1270 \spanrequest \start "text"
1271 \spanrequest \stop "text"
1273 LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
1274 in @internalsref{Voice} context). The string to be printed, as well as the
1275 style is set through grob properties.
1277 An application---or rather, a hack---is to fake octavation indications.
1278 @lilypond[fragment,relative,verbatim]
1279 \relative c' { a''' b c a
1280 \property Voice.TextSpanner \set #'type = #'dotted-line
1281 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1282 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1283 \property Staff.centralCPosition = #-13
1284 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1302 @subsection Articulations
1303 @cindex Articulations
1305 @cindex articulations
1309 A variety of symbols can appear above and below notes to indicate
1310 different characteristics of the performance. They are added to a note
1311 by adding @code{-}@var{script}
1312 @lilypond[singleline]
1314 \notes \context Voice {
1315 \property Voice.TextScript \set #'font-family = #'typewriter
1316 \property Voice.TextScript \set #'font-shape = #'upright
1322 c''4-^_"c-\\^{ }" s4
1327 The script is automatically placed, but if you need to force
1328 directions, you can use @code{_} to force them down, or @code{^} to
1330 @lilypond[fragment, verbatim]
1335 Other symbols can be added using the syntax
1336 @var{note}@code{-\}@var{name}. Again, they can be forced up or down
1337 using @code{^} and @code{_}.
1341 \property Score.LyricSyllable \override #'font-family =#'typewriter
1342 \property Score.LyricSyllable \override #'font-shape = #'upright
1343 \context Staff \notes {
1344 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1345 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1346 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1347 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1348 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1349 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1350 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1351 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1353 \context Lyrics \lyrics {
1354 accent__ marcato__ staccatissimo__ fermata
1355 stopped__ staccato__ tenuto__ upbow
1356 downbow__ lheel__ rheel__ ltoe
1357 rtoe__ turn__ open__ flageolet
1358 reverseturn__ trill__ prall__ mordent
1359 prallprall__ prallmordent__ uprall__ downprall
1360 upmordent__ downmordent__ pralldown__ prallup__
1361 lineprall__ thumb__ segno__ coda
1365 linewidth = 5.875\in
1374 Fingering instructions can also be entered in this shorthand. For
1375 finger changes, use markup texts:
1377 @lilypond[verbatim, singleline, fragment]
1378 c'4-1 c'4-2 c'4-3 c'4-4
1383 @cindex @code{\script}
1388 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
1392 All of these note ornaments appear in the printed output but have no
1393 effect on the MIDI rendering of the music.
1395 Unfortunately, there is no support for adding fingering instructions or
1396 ornaments to individual note heads. Some hacks exist, though. See
1397 @file{input/test/script-horizontal.ly}.
1402 @subsection Text scripts
1403 @cindex Text scripts
1405 In addition, it is possible to place arbitrary strings of text or markup
1406 text (see @ref{Text markup}) above or below notes by using a string:
1409 By default, these indications do not influence the note spacing, but
1410 by using the command @code{\fatText}, the widths will be taken into
1411 account. @lilypond[fragment,singleline,verbatim] \relative c' {
1412 c4^"longtext" \fatText c4_"longlongtext" c4 }
1415 Text scripts are created in form of @internalsref{TextScript} grobs, in
1416 @internalsref{Voice} context.
1418 @ref{Text markup} describes how to change the font or access
1419 special symbols in text scripts.
1422 @node Adding scripts
1423 @subsection Adding scripts
1425 TODO: should junk this subsect?
1427 You can add scripts by editing @file{scm/script.scm} and
1428 @file{ly/script-init.ly}. This file contains a table, listing script
1429 definitions and aliases. The following syntax accesses a script
1430 definition from the table:
1436 Usually the @code{\script} keyword is not used directly. Various
1437 helpful identifier definitions appear in @file{script.ly}.
1442 @subsection Grace notes
1447 @cindex @code{\grace}
1450 @cindex @code{graceAlignPosition}
1453 Grace notes are ornaments that are written out, but do not take up any
1454 logical time in a measure. LilyPond has limited support for grace notes.
1455 The syntax is as follows.
1457 \grace @var{musicexpr}
1460 Unbeamed eighth notes and shorter by default have a slash through the
1463 @lilypond[fragment,verbatim]
1464 \relative c'' \context Voice {
1465 \grace c8 c4 \grace { [c16 c16] } c4
1467 \property Voice.Stem \override #'flag-style = #'()
1469 \property Voice.Stem \revert #'flag-style
1474 A grace note expression has duration 0; the next real note is assumed to
1475 be the main note. If you want the note to appear after the main note,
1476 set @code{Voice.graceAlignPosition} to @code{1}.
1480 Nesting @code{\grace} notes is not supported. The following may cause
1481 run-time errors: @example
1482 @code{\grace @{ \grace c32 c16 @} c4}
1484 Since the meaning of such a construct is unclear, we don't consider this
1485 a loss. Similarly, juxtaposing two @code{\grace} sections is
1486 syntactically valid, but makes no sense and may cause runtime errors.
1487 Ending a staff or score with grace notes may also generate a run-time
1488 error, since there will be no main note to attach the grace notes to.
1499 @subsection Glissando
1502 @cindex @code{\glissando}
1504 A glissando line (grob @internalsref{Glissando}) can be requested by
1505 attaching a @code{\glissando} to a notte:
1507 @lilypond[fragment,relative,verbatim]
1513 Printing of an additional text (such as @emph{gliss.}) must be done
1520 @subsection Dynamics
1533 @cindex @code{\ffff}
1543 Absolute dynamic marks are specified using an identifier after a
1544 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1545 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1546 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1547 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1549 @lilypond[verbatim,singleline,fragment,relative]
1550 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1556 @cindex @code{\decr}
1557 @cindex @code{\rced}
1563 A crescendo mark is started with @code{\cr} and terminated with
1564 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1565 started with @code{\decr} and terminated with @code{\rced}. There are
1566 also shorthands for these marks. A crescendo can be started with
1567 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1568 can be terminated with @code{\!}. Note that @code{\!} must go before
1569 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1570 after the last note. Because these marks are bound to notes, if you
1571 want several marks during one note, you have to use spacer notes.
1573 @lilypond[fragment,verbatim,center]
1574 c'' \< \! c'' d'' \decr e'' \rced
1575 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1578 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1579 is an example how to do it:
1584 @lilypond[fragment,relative,verbatim]
1586 \property Voice.crescendoText = "cresc."
1587 \property Voice.crescendoSpanner = #'dashed-line
1592 For everyday use, we recommend the identifiers @code{\cresc},
1593 @code{endcresc}, @code{\dim} and @code{\enddim}.
1597 Dynamics are grobs of @internalsref{DynamicText} and
1598 @internalsref{Hairpin}. Vertical positioning of these symbols is handled
1599 by the @internalsref{DynamicLineSpanner} grob. If you want to adjust
1600 padding or vertical direction of the dynamics, you must set properties
1601 for the @internalsref{DynamicLineSpanner} grob. Predefined identifiers
1602 to set the vertical direction are \dynamicUp and \dynamicDown.
1604 @cindex direction, of dynamics
1605 @cindex @code{\dynamicDown}
1606 @cindex @code{\dynamicUp}
1614 @cindex @code{\repeat}
1616 To specify repeats, use the @code{\repeat} keyword. Since repeats
1617 should work differently when played or printed, there are a few
1618 different variants of repeats.
1622 Repeated music is fully written (played) out. Useful for MIDI
1623 output, and entering repetitive music.
1626 This is the normal notation: Repeats are not written out, but
1627 alternative endings (voltas) are printed, left to right.
1630 Alternative endings are written stacked. This has limited use but may be
1631 used to typeset two lines of lyrics in songs with repeats, see
1632 @file{input/star-spangled-banner.ly}.
1638 Make beat or measure repeats. These look like percent signs.
1644 * Repeats and MIDI::
1645 * Manual repeat commands::
1647 * Tremolo subdivisions::
1652 @subsection Repeat syntax
1654 The syntax for repeats is
1657 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1660 If you have alternative endings, you may add
1661 @cindex @code{\alternative}
1663 \alternative @code{@{} @var{alternative1}
1665 @var{alternative3} @dots{} @code{@}}
1667 where each @var{alternative} is a music expression.
1669 Normal notation repeats are used like this:
1670 @lilypond[fragment,verbatim]
1672 \repeat volta 2 { c'4 d' e' f' }
1673 \repeat volta 2 { f' e' d' c' }
1676 With alternative endings:
1677 @lilypond[fragment,verbatim]
1679 \repeat volta 2 {c'4 d' e' f'}
1680 \alternative { {d'2 d'} {f' f} }
1683 Folded repeats look like this:
1686 @lilypond[fragment,verbatim]
1688 \repeat fold 2 {c'4 d' e' f'}
1689 \alternative { {d'2 d'} {f' f} }
1693 If you don't give enough alternatives for all of the repeats, then
1694 the first alternative is assumed to be repeated often enough to equal
1695 the specified number of repeats.
1697 @lilypond[fragment,verbatim]
1701 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1702 \alternative { { g4 g g } { a | a a a a | b2. } }
1707 @node Repeats and MIDI
1708 @subsection Repeats and MIDI
1710 @cindex expanding repeats
1712 For instructions on how to unfoldi repeats for MIDI output, see
1713 the example file @file{input/test/unfold-all-repeats.ly}.
1718 Notice that timing information is not remembered at the start of an
1719 alternative, so you have to reset timing information after a repeat,
1720 e.g. using a bar-check (See @ref{Bar check}), setting
1721 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1722 are also not repeated.
1724 It is possible to nest @code{\repeat}s, although this probably is only
1725 meaningful for unfolded repeats.
1727 Folded repeats offer little more over simultaneous music. However, it
1728 is to be expected that more functionality -- especially for the MIDI
1729 backend -- will be implemented at some point in the future.
1731 Volta repeats are printed over all staves in a score. You must turn them
1732 off explicitly, for example by doing
1734 \property Staff.VoltaBracket = \turnOff
1736 in all but the top staff.
1738 @node Manual repeat commands
1739 @subsection Manual repeat commands
1741 @cindex @code{repeatCommands}
1743 The property @code{repeatCommands} can be used to control the layout of
1744 repeats. Its value is a Scheme list of repeat commands, where each repeat
1752 @item (volta . @var{text})
1753 Print a volta bracket saying @var{text}.
1755 Stop a running volta bracket
1758 @lilypond[verbatim, fragment]
1760 \property Score.repeatCommands = #'((volta "93") end-repeat)
1762 \property Score.repeatCommands = #'((volta #f))
1767 Repeats brackets are @internalsref{VoltaBracket} grobs.
1769 @node Tremolo repeats
1770 @subsection Tremolo repeats
1771 @cindex tremolo beams
1773 To place tremolo marks between notes, use @code{\repeat} with tremolo
1775 @lilypond[verbatim,center,singleline]
1777 \context Voice \notes\relative c' {
1778 \repeat "tremolo" 8 { c16 d16 }
1779 \repeat "tremolo" 4 { c16 d16 }
1780 \repeat "tremolo" 2 { c16 d16 }
1781 \repeat "tremolo" 4 c16
1786 Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
1787 @internalsref{StemTremolo}.
1792 At present, the spacing between tremolo beams is not regular, since the
1793 spacing engine does not notice that not all notes are printed.
1795 @node Tremolo subdivisions
1796 @subsection Tremolo subdivisions
1797 @cindex tremolo marks
1798 @cindex @code{tremoloFlags}
1800 Tremolo marks can be printed on a single note by adding
1801 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1802 A @var{length} value of 8 gives one line across the note stem. If the
1803 length is omitted, then then the last value (stored in
1804 @code{Voice.tremoloFlags}) is used.
1806 @lilypond[verbatim,fragment,center]
1807 c'2:8 c':32 | c': c': |
1813 Tremolos in this style do not carry over into the MIDI output.
1816 @node Measure repeats
1817 @subsection Measure repeats
1819 @cindex percent repeats
1820 @cindex measure repeats
1822 In the @code{percent} style, a note pattern can be repeated. It is
1823 printed once, and then the pattern is replaced with a special sign.
1824 Patterns of a one and two measures are replaced by percent-like signs,
1825 patterns that divide the measure length are replaced by slashes.
1827 @lilypond[verbatim,singleline]
1828 \context Voice { \repeat "percent" 4 { c'4 }
1829 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1833 The signs are represented by these grobs: @internalsref{RepeatSlash} and
1834 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
1838 You can not nest percent repeats, e.g. by filling in the first measure
1839 with slashes, and repeating that measure with percents.
1841 @node Rhythmic music
1842 @section Rhythmic music
1849 @node Rhythmic staves
1850 @subsection Rhythmic staves
1852 Sometimes you might want to show only the rhythm of a melody. This can
1853 be done with the rhythmic staff. All pitches of notes on such a staff
1854 are squashed, and the staff itself looks has a single staff line:
1856 @lilypond[fragment,relative,verbatim]
1857 \context RhythmicStaff {
1859 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1866 @section Piano music
1868 Piano music is an odd type of notation. Piano staves are two normal
1869 staves coupled with a brace. The staves are largely independent, but
1870 sometimes voices can cross between the two staves. The
1871 @internalsref{PianoStaff} is especially built to handle this cross-staffing
1872 behavior. In this section we discuss the @internalsref{PianoStaff} and some
1873 other pianistic peculiarities.
1876 * Automatic staff changes::
1877 * Manual staff switches::
1880 * Voice follower lines::
1884 @c . {Automatic staff changes}
1885 @node Automatic staff changes
1886 @subsection Automatic staff changes
1887 @cindex Automatic staff changes
1889 Voices can switch automatically between the top and the bottom
1890 staff. The syntax for this is
1892 \autochange @var{contexttype} \context @var{childcontexttype}
1896 This will switch the interpretation context of @var{musicexp} between
1897 a @var{contexttype} named @code{up} and @code{down}. Typically, you
1898 use @internalsref{Staff} for @var{contexttype}, and
1899 @internalsref{Voice} for @var{childcontexttype}. The autochanger
1900 switches on basis of pitch (central C is the turning point), and it
1901 looks ahead skipping over rests to switch rests in advance.
1903 @lilypond[verbatim,singleline]
1904 \score { \notes \context PianoStaff <
1905 \context Staff = "up" {
1906 \autochange Staff \context Voice = VA < \relative c' {
1907 g4 a b c d r4 a g } > }
1908 \context Staff = "down" {
1914 Note how spacer rests are used to prevent the bottom staff from
1915 terminating too soon.
1918 @node Manual staff switches
1919 @subsection Manual staff switches
1921 @cindex manual staff switches
1922 @cindex staff switch, manual
1924 Voices can be switched between staves manually, using the following command:
1926 \translator Staff = @var{staffname} @var{music}
1928 The string @var{staffname} is the name of the staff. It switches the
1929 current voice from its current staff to the Staff called
1930 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1933 The formal definition of this construct is obtuse, but for the sake of
1934 completeness we give it here.
1935 @cindex @code{\translator}
1937 \translator @var{contexttype} = @var{name}
1939 Formally, this construct is a music expression indicating
1940 that the context which is a direct child of the context of type
1941 @var{contexttype} should be shifted to a context of type
1942 @var{contexttype} and the specified name.
1950 Piano pedal instruction can be expressed using
1951 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
1952 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1954 These identifiers are shorthands for spanner commands of the types
1955 @internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
1957 @lilypond[fragment,verbatim]
1958 c''4 \spanrequest \start "Sustain" c''4
1959 c''4 \spanrequest \stop "Sustain"
1962 The symbols that are printed can be modified by setting
1963 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
1964 Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
1965 @rgrob{SustainPedal}, for example, for more information.
1967 Pedals can also be indicated by a sequence of brackets, by setting the
1968 @code{pedal-type} property of SustainPedal grobs:
1970 @lilypond[fragment,verbatim]
1971 \property Staff.SustainPedal \override #'pedal-type = #'bracket
1972 c''4 \sustainDown d''4 e''4 a'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
1975 A third style of pedal notation is a mixture of text and brackets,
1976 obtained by setting @code{pedal-type} to @code{mixed}:
1978 @lilypond[fragment,verbatim]
1979 \property Staff.SustainPedal \override #'pedal-type = #'mixed
1980 c''4 \sustainDown d''4 e''4 c'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
1983 The default '*Ped' style for sustain and damper pedals corresponds to
1984 @code{\pedal-type = #'text}. However, @code{mixed} is the default style
1985 for a sostenuto pedal:
1987 @lilypond[fragment,verbatim]
1988 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
1991 For fine-tuning of the appearance of a pedal bracket, the properties
1992 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
1993 @code{PianoPedalBracket} grobs (see the detailed documentation of
1994 @rgrob{PianoPedalBracket}) can be modified. For example, the bracket
1995 may be extended to the end of the note head.
1997 @lilypond[fragment,verbatim]
1998 \property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0)
1999 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2006 @subsection Arpeggio
2009 @cindex broken arpeggio
2010 @cindex @code{\arpeggio}
2012 You can specify an arpeggio sign on a chord by attaching an
2013 @code{\arpeggio} to a note of the chord.
2016 @lilypond[fragment,relative,verbatim]
2017 \context Voice <c\arpeggio e g c>
2020 When an arpeggio crosses staves in piano music, you attach an arpeggio
2021 to the chords in both staves, and set
2022 @code{PianoStaff.connectArpeggios}.
2024 @lilypond[fragment,relative,verbatim]
2025 \context PianoStaff <
2026 \property PianoStaff.connectArpeggios = ##t
2027 \context Voice = one { <c'\arpeggio e g c> }
2028 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2032 This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
2033 are @code{PianoStaff.Arpeggio}.
2035 To add an arrow head to explicitly specify the direction of the
2036 arpeggio, you should set the arpeggio grob property
2037 @code{arpeggio-type}.
2039 @lilypond[fragment,relative,verbatim]
2041 \property Voice.Arpeggio \override #'arpeggio-direction = #1
2043 \property Voice.Arpeggio \override #'arpeggio-direction = #-1
2048 A square bracket on the left indicates that the player should not
2049 arpeggiate the chord. To draw these brackets, set the
2050 @code{molecule-callback} property of @code{Arpeggio} or
2051 @code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
2052 @code{\arpeggio} statements within the chords as before.
2054 @lilypond[fragment,relative,verbatim]
2055 \context PianoStaff <
2056 \property PianoStaff.connectArpeggios = ##t
2057 \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket
2058 \context Voice = one { <c'\arpeggio e g c> }
2059 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2066 It is not possible to mix connected arpeggios and unconnected arpeggios
2071 @node Voice follower lines
2072 @subsection Voice follower lines
2074 @cindex follow voice
2075 @cindex staff switching
2078 @cindex @code{followVoice}
2080 Whenever a voice switches to another staff a line connecting the notes
2081 can be printed automatically. This is enabled if the property
2082 @code{PianoStaff.followVoice} is set to true:
2084 @lilypond[fragment,relative,verbatim]
2085 \context PianoStaff <
2086 \property PianoStaff.followVoice = ##t
2087 \context Staff \context Voice {
2089 \translator Staff=two
2092 \context Staff=two {\clef bass \skip 1*2 }
2096 The associated grob is @internalsref{VoiceFollower}.
2106 * Automatic syllable durations::
2112 @subsection Lyrics mode
2115 To print lyrics, you must first make a music expression from the lyric
2116 text. That music expression can be printed by selecting an appropriate
2120 @cindex @code{\lyrics}
2122 You can enter lyrics in a special input mode of LilyPond. This mode is
2123 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
2124 The purpose of this mode is that you can enter lyrics as plain text,
2125 punctuation and accents without any hassle.
2127 Syllables are entered like notes, with pitches replaced by text. For
2128 example, @code{Twin- kle twin- kle} enters four syllables. Note that
2129 the hyphen has no special meaning for lyrics, and does not introduce
2132 Spaces can be introduced into a lyric either by using quotes:
2133 @code{"He could"4 not4} or by using an underscore without quotes:
2134 @code{He_could4 not4}. All unquoted underscores are converted to
2137 The precise definition of this mode can be found in @ref{Lyrics mode
2140 @c . {Printing lyrics}
2141 @node Printing lyrics
2142 @subsection Printing lyrics
2145 Lyrics are printed by interpreting them in the @internalsref{Lyrics} context.
2147 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
2148 @c Add tied and beamed melismata too.
2149 @lilypond[verbatim,singleline]
2151 \notes \relative c' {
2153 \property Staff.automaticMelismata = ##t
2154 d'2 c4 b16 ( a g a b a b ) c a2
2155 b2 c4 b8 ( a16 g ) a4 g2 }
2156 \context Lyrics \lyrics {
2158 share the soft -- ware; }
2162 Notes and syllable durations are matched automatically. This is
2163 accomplished using @code{\addlyrics}, which is documented in
2164 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
2165 the melody staff will cause tied, slurred or beamed notes to be
2166 interpreted as melismata.
2168 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
2171 @cindex lyric extender
2174 As you can see, extender lines are entered as @code{__}. This will
2175 create an extender, a line that extends over the entire duration of the
2176 lyric. This line will run all the way to the start of the next lyric,
2177 so you may want to shorten it by using a blank lyric (using @code{_}).
2178 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2183 If you want to have hyphens centered between syllables (rather than
2184 attached to the end of the first syllable) you can use the special
2185 `@code{-}@code{-}' lyric as a separate word between syllables. This
2186 will result in a hyphen whose length varies depending on the space
2187 between syllables. It will be centered between the syllables. The grob
2188 for this symbol is @code{LyricsVoice.LyricHyphen}.
2190 @cindex Lyric hyphen
2192 @node Automatic syllable durations
2193 @subsection Automatic syllable durations
2194 @cindex Automatic syllable durations
2196 @cindex automatic lyric durations
2197 @cindex @code{\addlyrics}
2199 If you have lyrics that are set to a melody, you can copy the rhythm
2200 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2203 \addlyrics @var{musicexpr1 musicexpr2}
2206 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2207 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2208 when there are events in @var{musicexpr1}.
2210 @cindex @code{automaticMelismata}
2212 If the property @code{automaticMelismata} is set in the
2213 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2216 @lilypond[verbatim,fragment]
2219 \property Voice.automaticMelismata = ##t
2220 c8 () cis d8. e16 f2
2222 \context Lyrics \lyrics {
2226 If you want the lyric lines to be above the melody staff, or in some
2227 other, more complex configuration, then build that configuration first
2228 using simultaneous music, and use @code{\addlyrics} after that.
2230 @lilypond[verbatim, singleline]
2232 \context Lyrics = LA { s1 }
2233 \context Staff = SA { s1 }
2235 \context Staff = SA \relative c' { c4 e g g }
2236 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2239 For @code{\addlyrics} you should use a single rhythm melody, and single
2240 rhythm lyrics (a constant duration is the obvious choice). If you do
2241 not, you can get undesired effects when using multiple stanzas:
2243 @lilypond[verbatim,fragment]
2246 c8 () cis d8. e16 f2
2248 \context Lyrics \lyrics
2253 It is valid (but probably not very useful) to use notes instead of
2254 lyrics for @var{musicexpr2}.
2257 @subsection More stanzas
2261 If you have multiple stanzas printed underneath each other, the vertical
2262 groups of syllables should be aligned around punctuation. LilyPond can
2263 do this if you tell it which lyric lines belong to which melody.
2265 To this end, give the Voice context an identity, and set the LyricsVoice
2266 to a name starting with that identity followed by a dash.
2267 In the following example, the Voice
2268 identity is @code{duet}, and the identities of the LyricsVoices are
2269 @code{duet-1} and @code{duet-2}.
2272 @lilypond[singleline,verbatim]
2275 \notes \relative c'' \context Voice = duet { \time 3/4
2277 \lyrics \context Lyrics <
2278 \context LyricsVoice = "duet-1" {
2279 \property LyricsVoice . stanza = "Bert"
2280 Hi, my name is bert. }
2281 \context LyricsVoice = "duet-2" {
2282 \property LyricsVoice . stanza = "Ernie"
2283 Ooooo, ch\'e -- ri, je t'aime. }
2288 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2289 first system) and @code{LyricsVoice.stz} for the following
2290 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2296 @cindex stanza numbering
2304 LilyPond has support for both entering and printing chords. Chords are
2305 characterized by a set of pitches. They are
2306 internally stored as simultaneous music expressions. This means you can
2307 enter chords by name and print them as note head, enter them as notes
2308 and print them as chord names, or (the most common case) enter them by
2309 name, and print them as name.
2312 @lilypond[verbatim,singleline]
2313 twoWays = \notes \transpose c'' {
2323 < \context ChordNames \twoWays
2324 \context Voice \twoWays > }
2327 Note that this example also shows that the chord printing routines do
2328 not attempt to be intelligent. If you enter @code{f bes d}, it does not
2329 interpret this as an inversion.
2333 * Printing named chords::
2338 @subsection Chords mode
2341 Chord mode is a mode where you can input sets of pitches using common
2342 names. It is introduced by the keyword @code{\chords}. It is similar
2343 to note mode, but words are also looked up in a chord modifier table
2344 (containing @code{maj}, @code{dim}, etc).
2346 Dashes and carets are used to indicate chord additions and subtractions,
2347 so articulation scripts can not be entered in Chord mode.
2349 The syntax for named chords is as follows:
2351 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2354 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2355 the chord duration in the usual notation. There are two kinds of
2356 modifiers. One type is formed by @emph{chord additions}. Additions are
2357 obtained by listing intervals separated by dots. An interval is written
2358 by its number with an optional @code{+} or @code{-} to indicate raising
2359 or lowering by half a step. Chord additions have two effects: they adds
2360 the specified interval and all lower odd numbered intervals to the
2361 chord, and they may lower or raise the specified interval.
2363 Throughout these examples, chords have been shifted around the staff
2364 using @code{\transpose}.
2366 @lilypond[fragment,verbatim]
2370 c:9 c:9-.5+.7+ c:3-.5-
2380 The second type of modifier that may appear after the @code{:} is a
2381 named modifier. Named modifiers are listed in the file
2382 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2383 @code{min} which lower the 3rd half a step, `@code{aug}' which
2384 raises the 5th, `@code{dim}' which lowers the 5th,
2385 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2386 which replaces the 5th with a 4th.
2388 @lilypond[fragment,verbatim]
2391 c1:m c:min7 c:maj c:aug c:dim c:sus
2397 Chord subtractions are used to eliminate notes from a chord. The
2398 notes to be subtracted are listed after a @code{^} character,
2401 @lilypond[fragment,verbatim,center]
2410 Chord inversions can be specified by appending `@code{/}' and the name
2411 of a single note to a chord. In a chord inversion, the inverted note is
2412 transposed down until it is the lowest note in the chord. If the note
2413 is not in the chord, a warning will be printed.
2415 @lilypond[fragment,verbatim,center]
2425 Bass notes can be added by `@code{/+}' and
2426 the name of a single note to a chord. This has the effect of
2427 adding the specified note to the chord, lowered by an octave,
2428 so it becomes the lowest note in the chord.
2430 @lilypond[fragment,verbatim,center]
2441 Implementation details are quite gory. For example @code{c:4} not only
2442 adds a fourth, but also removes the third.
2445 @c . {Printing named chords}
2446 @node Printing named chords
2447 @subsection Printing named chords
2449 @cindex printing chord names
2453 For displaying printed chord names, use the @internalsref{ChordNames} context.
2454 The chords may be entered either using the notation described above, or
2455 directly using simultaneous music.
2457 @lilypond[verbatim,singleline]
2459 \chords {a1 b c} <d f g> <e g b>
2463 \context ChordNames \scheme
2464 \context Staff \transpose c'' \scheme
2469 You can make the chord changes stand out by setting
2470 @code{ChordNames.chordChanges} to true. This will only display chord
2471 names when there's a change in the chords scheme and at the start of a
2476 c1:m c:m \break c:m c:m d
2480 \context ChordNames {
2481 \property ChordNames.chordChanges = ##t
2483 \context Staff \transpose c'' \scheme
2487 LilyPond examines chords specified as lists of notes to determine a name
2488 to give the chord. LilyPond will not try to identify chord inversions or
2489 an added bass note, which may result in strange chord names when chords
2490 are entered as a list of pitches:
2492 @lilypond[verbatim,center,singleline]
2501 \context ChordNames \scheme
2502 \context Staff \scheme
2508 By default, a chord name system proposed by Harald Banter (See
2509 @ref{Literature}) is used. The system is very regular and predictable.
2510 Typical American style chord names may be selected by setting the
2511 @code{style} property of the @code{ChordNames.ChordName} grob to
2512 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2514 Routines that determine the names to be printed are written in Scheme,
2515 and may be customized by the user. The code can be found in
2516 @file{scm/chord-name.scm}. Here's an example showing the differences in
2520 @c maybe just junk verbatim option?
2521 @lilypond[verbatim,singleline]
2531 \context ChordNames = banter \scheme
2532 \context ChordNames = american {
2533 \property ChordNames.ChordName \override
2534 #'style = #'american \scheme }
2535 \context ChordNames = jazz {
2536 \property ChordNames.ChordName \override
2537 #'style = #'jazz \scheme }
2538 \context Staff \transpose c'' \scheme
2545 @section Writing parts
2547 Orchestral music involves some special notation, both in the full score,
2548 as in the individual parts. This section explains how to tackle common
2549 problems in orchestral music.
2556 * Instrument names::
2558 * Sound output for transposing instruments::
2559 * Multi measure rests::
2560 * Automatic part combining::
2561 * Hara kiri staves::
2564 @c . {Rehearsal marks}
2565 @node Rehearsal marks
2566 @subsection Rehearsal marks
2567 @cindex Rehearsal marks
2569 @cindex @code{\mark}
2573 \mark @var{unsigned}
2578 This command prints a rehearsal mark above the system. You can provide
2579 a number, a string or a markup text as argument. If you use
2580 @code{\default}, the value of property @code{rehearsalMark} is used and
2581 automatically incremented.
2583 @lilypond[fragment,verbatim]
2589 c1 \mark #'(music "scripts-segno")
2594 The grob is @internalsref{RehearsalMark} in @internalsref{Score} context. See
2595 @code{input/test/boxed-molecule.ly} if you need boxes around the marks.
2598 @subsection Bar numbers
2602 @cindex measure numbers
2603 @cindex currentBarNumber
2605 Bar numbers are @internalsref{BarNumber} grobs. They are printed at the
2606 start of the line. The number itself is a property that can be set by
2607 modifying the @code{currentBarNumber} property, i.e.
2609 \property Score.currentBarNumber = #217
2612 If you want boxed bar numbers, see the example file
2613 @code{input/test/boxed-molecule.ly}.
2617 It is not possible to have bar numbers printed at regular intervals
2620 @node Instrument names
2621 @subsection Instrument names
2623 You can specify an instrument name for a staff by setting
2624 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2625 before the start of the staff. For the first start, @code{instrument} is
2626 used, for the next ones @code{instr} is used.
2628 @lilypond[verbatim,singleline]
2629 \property Staff.instrument = "ploink " { c''4 }
2632 You can also use markup texts to construct more complicated instrument
2636 @lilypond[verbatim,singleline]
2638 '((font-relative-size . -2 ) (music "accidentals--1")))
2641 \property Staff.instrument = #`((kern . 0.5) (lines
2642 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2650 When you put a name on a grand staff or piano staff the width of the
2651 brace is not taken into account. You must add extra spaces to the end of
2652 the name to avoid a collision.
2655 @subsection Transpose
2657 @cindex transposition of pitches
2658 @cindex @code{\transpose}
2660 A music expression can be transposed with @code{\transpose}. The syntax
2663 \transpose @var{pitch} @var{musicexpr}
2666 This means that middle C in @var{musicexpr} is transposed to
2669 @code{\transpose} distinguishes between enharmonic pitches: both
2670 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2671 a tone. The first version will print sharps and the second version
2674 @lilypond[fragment,verbatim]
2677 { \key e \major c d e f }
2679 \transpose des'' { \key e \major c d e f }
2680 \transpose cis'' { \key e \major c d e f }
2684 If you want to use both @code{\transpose} and @code{\relative}, then
2685 you must use @code{\transpose} first. @code{\relative} will have no
2686 effect music that appears inside a @code{\transpose}.
2688 @node Sound output for transposing instruments
2689 @subsection Sound output transposing instruments
2691 When you want to make a MIDI file from a score containing transposed and
2693 instruments, you have to instruct LilyPond the pitch offset (in
2694 semitones) for the transposed instruments. This is done using the
2695 @code{transposing} property. It does not affect printed output.
2697 @cindex @code{transposing}
2700 \property Staff.instrument = #"Cl. in B-flat"
2701 \property Staff.transposing = #-2
2704 @c . {Multi measure rests}
2705 @node Multi measure rests
2706 @subsection Multi measure rests
2707 @cindex Multi measure rests
2711 Multi measure rests are entered using `@code{R}'. It is specifically
2712 meant for full bar rests and for entering parts: the rest can expand to
2714 rests, or it can be printed as a single multimeasure rest This expansion
2715 is controlled by the property @code{Score.skipBars}. If this is set to true,
2716 Lily will not expand empty measures, and the appropriate number is added
2719 @lilypond[fragment,verbatim]
2720 \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2723 Notice that the @code{R2.} is printed as a whole rest, centered in the
2726 @cindex whole rests for a full measure
2728 The grob for this object is @internalsref{MultiMeasureRest}.
2732 Currently, there is no way to automatically condense multiple rests into
2733 a single multimeasure rest.
2735 @cindex condensing rests
2737 @node Automatic part combining
2738 @subsection Automatic part combining
2739 @cindex automatic part combining
2740 @cindex part combiner
2743 Automatic part combining is used to merge two parts of music onto a
2744 staff in an intelligent way. It is aimed primarily at typesetting
2745 orchestral scores. When the two parts are identical for a period of
2746 time, only one is shown. In places where the two parts differ, they are
2747 typeset as separate voices, and stem directions are set automatically.
2748 Also, solo and @emph{a due} parts can be identified and marked.
2750 The syntax for part combining is
2753 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2755 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2756 combined into one context of type @var{context}. The music expressions
2757 must be interpreted by contexts whose names should start with @code{one}
2760 The most useful function of the part combiner is to combine parts into
2761 one voice, as common for wind parts in orchestral scores:
2763 @lilypond[verbatim,singleline,fragment]
2765 \context Voice=one \partcombine Voice
2766 \context Thread=one \relative c'' {
2769 \context Thread=two \relative c'' {
2775 Notice that the first @code{g} appears only once, although it was
2776 specified twice (once in each part). Stem, slur and tie directions are
2777 set automatically, depending whether there is a solo or unisono. The
2778 first part (with context called @code{one}) always gets up stems, and
2779 `solo', while the second (called @code{two}) always gets down stems and
2782 If you just want the merging parts, and not the textual markings, you
2783 may set the property @var{soloADue} to false.
2785 @lilypond[verbatim,singleline,fragment]
2787 \property Staff.soloADue = ##f
2788 \context Voice=one \partcombine Voice
2789 \context Thread=one \relative c'' {
2792 \context Thread=two \relative c'' {
2798 There are a number of other properties that you can use to tweak the
2799 behavior of part combining, refer to the automatically generated
2800 documentation of @reng{Thread_devnull_engraver} and
2801 @reng{Voice_devnull_engraver}. Look at the documentation of the
2802 responsible engravers, @code{Thread_devnull_engraver},
2803 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2807 In @code{soloADue} mode, when the two voices play the same notes on and
2808 off, the part combiner may typeset @code{a2} more than once in a
2811 @lilypond[fragment,singleline]
2813 \context Voice=one \partcombine Voice
2814 \context Thread=one \relative c'' {
2817 \context Thread=two \relative c'' {
2823 @cindex @code{Thread_devnull_engraver}
2824 @cindex @code{Voice_engraver}
2825 @cindex @code{A2_engraver}
2827 @node Hara kiri staves
2828 @subsection Hara kiri staves
2830 In orchestral scores, staff lines that only have rests are usually removed.
2831 This saves some space. LilyPond also supports this through the hara
2832 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2833 the Japanese Samourai warriors.} staff. This staff commits suicide when
2834 it finds itself to be empty after the line-breaking process. It will
2835 not disappear when it contains normal rests, you must use multi measure
2838 The hara kiri staff is specialized version of the @internalsref{Staff}
2839 context. It is available as the context identifier
2840 @code{\HaraKiriStaffContext}. Observe how the second staff in this
2841 example disappears in the second line.
2845 \notes \relative c' <
2846 \context Staff = SA { e4 f g a \break c1 }
2847 \context Staff = SB { c4 d e f \break R1 }
2851 \translator { \HaraKiriStaffContext }
2859 @node Ancient notation
2860 @section Ancient notation
2863 * Ancient note heads::
2868 @node Ancient note heads
2869 @subsection Ancient note heads
2871 To get a longa note head, you have to use mensural note heads. This
2872 is accomplished by setting the @code{style} property of the
2873 NoteHead grob to @code{mensural}. There is also a note head style
2874 @code{baroque} which gives mensural note heads for @code{\longa} and
2875 @code{\breve} but standard note heads for shorter notes.
2877 @lilypond[fragment,singleline,verbatim]
2878 \property Voice.NoteHead \set #'style = #'mensural
2879 \property Voice.NoteHead \set #'font-family = #'ancient
2884 @subsection Custodes
2889 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
2890 staff context symbol that appears at the end of a staff line. It
2891 anticipates the pitch of the first note(s) of the following line and
2892 thus helps the player or singer to manage line breaks during
2893 performance, thus enhancing readability of a score.
2898 \property Staff.Custos \set #'style = #'mensural
2903 \consists Custos_engraver
2909 Custodes were frequently used in music notation until the 17th century.
2910 There were different appearances for different notation styles.
2911 Nowadays, they have survived only in special forms of musical notation
2912 such as via the @emph{editio vaticana} dating back to the beginning of
2915 For typesetting custodes, just put a @code{Custos_engraver} into the
2916 @internalsref{Staff} context when declaring the @code{\paper} block. In this
2917 block, you can also globally control the appearance of the custos symbol
2918 by setting the custos @code{style} property. Currently supported styles
2919 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2926 \consists Custos_engraver
2927 Custos \override #'style = #'mensural
2932 The property can also be set locally, for example in a @code{\notes}
2937 \property Staff.Custos \override #'style = #'vaticana
2938 c'1 d' e' d' \break c' d' e' d'
2943 @section Ancient clefs
2945 LilyPond supports a variety of clefs, many of them ancient. These can
2946 be selected from the @code{ancient} font family, by setting
2947 @code{Staff.clefGlyph}) to the following values
2956 @item clefs-vaticana_do
2957 Editio Vaticana style do clef
2958 @item clefs-vaticana_fa
2959 Editio Vaticana style fa clef
2960 @item clefs-medicaea_do
2961 Editio Medicaea style do clef
2962 @item clefs-medicaea_fa
2963 Editio Medicaea style fa clef
2964 @item clefs-mensural1_c
2965 modern style mensural C clef
2966 @item clefs-mensural2_c
2967 historic style small mensural C clef
2968 @item clefs-mensural3_c
2969 historic style big mensural C clef
2970 @item clefs-mensural1_f
2971 historic style traditional mensural F clef
2972 @item clefs-mensural2_f
2973 historic style new mensural F clef
2974 @item clefs-mensural_g
2975 historic style mensural G clef
2976 @item clefs-hufnagel_do
2977 historic style hufnagel do clef
2978 @item clefs-hufnagel_fa
2979 historic style hufnagel fa clef
2980 @item clefs-hufnagel_do_fa
2981 historic style hufnagel combined do/fa clef
2982 @item clefs-percussion
2983 modern style percussion clef
2986 @emph{Modern style} means ``as is typeset in current editions.''
2987 @emph{Historic style} means ``as was typeset or written in contemporary
2988 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
2991 @cindex Vaticana, Editio
2992 @cindex Medicaea, Editio
2993 @cindex hufnagel clefs
2999 @section Figured bass
3001 @cindex Basso continuo
3003 TODO. see figured-bass.ly
3005 @c . {Tuning output}
3007 @section Tuning output
3009 LilyPond tries to take as much formatting as possible out of your
3010 hands. Nevertheless, there are situations where it needs some help, or
3011 where you want to override its decisions. In this section we discuss
3012 ways to do just that.
3014 Formatting is internally done by manipulating so called grobs (graphic
3015 objects). Each grob carries with it a set of properties (grob
3016 properties) specific to that object. For example, a stem grob has
3017 properties that specify its direction, length and thickness.
3019 The most direct way of tuning the output is by altering the values of
3020 these properties. There are two ways of doing that: first, you can
3021 temporarily change the definition of a certain type of grob, thus
3022 affecting a whole set of objects. Second, you can select one specific
3023 object, and set a grob property in that object.
3026 * Tuning groups of grobs ::
3027 * Tuning per grob ::
3035 @node Tuning groups of grobs
3036 @subsection Tuning groups of grobs
3038 @cindex grob description
3042 A grob definition is a Scheme association list, that is stored in a
3043 context property. By assigning to that property (using plain
3044 @code{\property}), you can change the resulting grobs.
3046 @lilypond[verbatim, fragment]
3047 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
3050 The @code{\property} assignment effectively empties the definition of
3051 the Stem object. One of the effects is that the recipe of how it should be
3052 printed is erased, with the effect of rendering it invisible. The above
3053 assignment is available as a standard identifier, for the case that you
3057 \property Voice.Stem = \turnOff
3064 This mechanism is fairly crude, since you can only set, but not modify,
3065 the definition of a grob. For this reason, there is a more advanced
3068 The definition of a grob is actually a list of default grob
3069 properties. For example, the definition of the Stem grob (available in
3070 @file{scm/grob-description.scm}), defines the following values for
3075 (beamed-lengths . (0.0 2.5 2.0 1.5))
3076 (Y-extent-callback . ,Stem::height)
3080 You can add a property on top of the existing definition, or remove a
3081 property, thus overriding the system defaults:
3083 c'4 \property Voice.Stem \override #'thickness = #4.0
3084 c'4 \property Voice.Stem \revert #'thickness
3087 You should balance @code{\override} and @code{\revert}. If that's too
3088 much work, you can use the @code{\set} shorthand. It performs a revert
3089 followed by an override. The following example gives exactly the same
3090 result as the previous one.
3092 c'4 \property Voice.Stem \set #'thickness = #4.0
3093 c'4 \property Voice.Stem \set #'thickness = #0.8
3096 If you use @code{\set}, you must explicitly restore the default.
3099 Formally the syntax for these constructions is
3101 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
3102 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
3103 \property @var{context}.@var{grobname} \revert @var{symbol}
3105 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
3106 and @var{grobname} are strings and @var{value} is a Scheme expression.
3109 If you revert a setting which was not set in the first place, then it
3110 has no effect. However, if the setting was set as a system default, it
3111 may remove the default value, and this may give surprising results,
3112 including crashes. In other words, @code{\override} and @code{\revert},
3113 must be carefully balanced.
3115 These are examples of correct nesting of @code{\override}, @code{\set},
3118 A clumsy but correct form:
3120 \override \revert \override \revert \override \revert
3123 Shorter version of the same:
3125 \override \set \set \revert
3128 A short form, using only @code{\set}. This requires you to know the
3131 \set \set \set \set @var{to default value}
3134 If there is no default (i.e. by default, the grob property is unset),
3137 \set \set \set \revert
3140 For the digirati, the grob description is an Scheme association
3141 list. Since a Scheme list is a singly linked list, we can treat it as a
3142 stack, and @code{\override} and @code{\revert} are just push and pop
3143 operations. This pushing and popping is also used for overriding
3144 automatic beaming settings.
3148 LilyPond will hang or crash if @var{value} contains cyclic references.
3149 The backend is not very strict in type-checking grob properties. If you
3150 @code{\revert} properties that are expected to be set by default,
3153 Some grobs are created at the moment that their context is created. An
3154 example of such a grob is the staff itself (i.e. the horizontal lines).
3155 You can not change the appearance of the staff symbol by manipulating
3156 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3157 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3158 created before any @code{\override} is effective. You can deal with this
3159 either overriding properties in a @code{\translator} definition, or by
3160 using @code{\outputproperty}.
3165 @node Tuning per grob
3166 @subsection Tuning per grob
3168 @cindex \outputproperty
3170 A second way of tuning grobs is the more arcane @code{\outputproperty}
3171 feature. The syntax is as follows:
3173 \outputproperty @var{predicate} @var{symbol} = @var{value}
3175 Here @code{predicate} is a Scheme function taking a grob argument, and
3176 returning a boolean. This statement is processed by the
3177 @code{Output_property_engraver}. It instructs the engraver to feed all
3178 grobs that it sees to @var{predicate}. Whenever the predicate returns
3179 true, the grob property @var{symbol} will be set to @var{value}.
3181 You will need to combine this statement with @code{\context} to select
3182 the appropriate context to apply this to.
3184 Here are some random examples.
3187 In the following example, all note heads occurring at current staff
3188 level, are shifted up and right by setting their @code{extra-offset}
3191 @lilypond[fragment,verbatim,singleline]
3193 \context Staff \outputproperty
3194 #(make-type-checker 'note-head-interface)
3195 #'extra-offset = #'(0.5 . 0.75)
3199 @cindex @code{extra-offset}
3201 In this example, the predicate checks the @code{text} grob property, to
3202 shift only the `m.d.' text, but not the fingering instruction "2".
3203 @lilypond[verbatim,singleline]
3204 #(define (make-text-checker text)
3205 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3208 \notes\relative c''' {
3209 \property Voice.Stem \set #'direction = #1
3210 \outputproperty #(make-text-checker "m.d.")
3211 #'extra-offset = #'(-3.5 . -4.5)
3219 If possible, avoid this feature: the semantics are not very clean, and
3220 the syntax and semantics are up for rewrite.
3226 @subsection What to tune?
3228 This all tells you how to tune grobs, but you don't know what variables
3229 to set? The question is not answered in this part of the manual
3230 (although you may encounter some examples.).
3232 Grob properties are tied directly to the implementation of LilyPond, and
3233 they are thus a moving target. Documentation of such variables is in the
3234 automatically generated documentation. Description of properties are
3235 generated from the source code for each version. This documentation is
3236 therefore more up to date. It should be available from the same place
3237 where you got this manual.
3239 To decide how to tune a grob, you need to find the following information
3242 which grob to modify
3244 which property to modify
3246 which context the grob comes from.
3249 Included with the automatically generated documentation is a master list
3250 of grobs. Selecting a grob will take you to an overview of the
3251 properties available for that grob.
3253 There is also a master list of contexts. Selecting one takes you to an
3254 overview of that context which lists which grob types are created there.
3257 @node Font selection
3258 @subsection Font selection
3260 Most graphics in LilyPond are composed of characters of fonts. You can
3261 alter the characteristics of the font by setting certain grob
3262 properties. The mechanism that is used for this resembles La@TeX{}'s New
3263 Font Selection Scheme. Within this scheme, a font is entirely
3264 characterized by its font name.
3266 For each grob that uses fonts (in other words, each grob that supports
3267 @code{font-interface}) a font-name must be selected before it can be
3268 printed. The font name is selected by looking at a number of grob
3273 A symbol indicating the general class of the typeface. Supported are
3274 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3275 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3276 signs) and @code{typewriter}
3279 A symbol indicating the shape of the font, there are typically several
3280 font shapes available for each font family. Choices are @code{italic},
3281 @code{caps} and @code{upright}
3284 A symbol indicating the series of the font. There are typically several
3285 font series for each font family and shape. Choices are @code{medium}
3288 @item font-relative-size
3289 A number indicating the size relative the standard size. For example,
3290 with 20pt staff height, relative size -1 corresponds to 16pt staff
3291 height, and relative size +1 corresponds to 23 pt staff height.
3293 @item font-design-size
3294 A number indicating the design size of the font.
3296 This is a feature of the Computer Modern Font: each point size has a
3297 slightly different design. Smaller design sizes are relatively wider,
3298 which enhances readability. Scalable type faces such TrueType and Adobe
3299 Type1 usually come as ``one design fits all sizes''.
3302 The name of the font, without the design size, e.g. @code{cmr},
3303 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3310 The font is selected by taking the first font that satisfies all
3311 qualifiers specified. You can override any of these fields through
3312 @code{\override} and @code{\revert}. The special value @code{*} matches
3313 any value for that qualifier.
3316 \property Lyrics.LyricText \override #'font-series = #'bold
3317 \property Lyrics.LyricText \override #'font-shape = #'*
3320 @cindex @code{font-style}
3322 There are also pre-cooked font selection qualifiers. These are selected
3323 through the grob property @code{font-style}. For example, the style
3324 @code{finger} selects family @code{number} and relative size @code{-3}.
3325 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3326 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3329 The style sheets and tables for selecting fonts are located in
3330 @file{scm/font.scm}. Refer to this file for more information.
3333 Setting @code{font-name} overrides all other qualifiers. The value for
3334 this property should be a string, the file name of the font. You may use
3335 this to use special fonts, which are not a part of the style sheet, or
3336 which have special encodings.
3338 The size of the font may be set with the grob property
3339 @code{font-magnification}. It is the size of font, relative to its
3340 standard size. For example, @code{1.0} is normal size.
3344 Relative size is not linked to any real size.
3346 There is no style sheet provided for other fonts besides the @TeX{}
3349 @cindex font selection
3350 @cindex font magnification
3351 @cindex @code{font-interface}
3355 @subsection Text markup
3359 LilyPond has an internal mechanism to typeset texts. You can
3360 form text markup expressions by composing scheme expressions
3361 in the following way.
3363 @lilypond[verbatim, singleline]
3368 c^#'(italic "italic")
3369 d_#'((bold italic) "ff")
3371 f_#'(lines "one" (bold "two"))
3372 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3376 Normally, the Scheme markup text is stored in the @code{text} property
3377 of a grob. Formally, it is defined as follows:
3380 text: string | (head? text+)
3381 head: markup | (markup+)
3382 markup-item: property | abbrev
3383 property: (@var{key} . @var{value})
3384 abbrev: @code{columns lines roman music bold italic named super sub}
3385 @code{overstrike text finger volta timesig mmrest mark script}
3386 @code{large Large dynamic}
3389 The markup is broken down and converted into a list of grob properties,
3390 which are prepended to the property list. The @var{key}-@var{value}
3391 pair is a grob property. A list of properties available is included in
3392 the generated documentation for @rint{Text_interface}.
3394 The following abbreviations are currently defined:
3397 horizontal mode: set all text on one line (default)
3399 vertical mode: set every text on a new line
3403 selects the Feta font (the standard font for music notation glyphs),
3404 and uses named lookup
3411 lookup by character name
3413 plain text lookup (by character value)
3419 the next text or character overstrikes this one
3421 select fingering number fontstyle
3423 select volta number fontstyle
3425 select time signature number fontstyle
3427 select multi measure rest number fontstyle
3429 select mark number fontstyle
3431 select scriptsize roman fontstyle
3433 select large roman fontstyle
3435 select Large roman fontstyle
3437 select dynamics fontstyle
3441 @cindex metronome mark
3443 One practical application of complicated markup is to fake a metronome
3447 #(define note '(columns
3448 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3449 #(define eight-note `(columns ,note ((kern . -0.1)
3450 (music ((raise . 3.5) "flags-u3")))))
3451 #(define dotted-eight-note
3452 `(columns ,eight-note (music "dots-dot")))
3455 \notes\relative c'' {
3456 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3462 TextScript \override #'font-shape = #'upright
3468 @node Invisible grobs
3469 @subsection Invisible grobs
3470 @cindex invisible grobs
3474 ben nog steeds niet kapot van de informatiedichtheid hier.
3480 You can imagine a number of situations where you would want to make
3481 certain grobs not show up in the output. There may be aesthetic
3482 reasons, to make the output resemble an (old) manuscript as close as
3483 possible, or to make lessons or exercises for students.
3485 Grobs can be made invisible in a number of ways:
3487 Here's an example with blanked-out notes and stems:
3488 @lilypond[singleline,verbatim]
3490 \property Voice.NoteHead \override
3492 \property Voice.Stem \override
3493 #'transparent = ##t }
3496 \property Voice.NoteHead \revert #'transparent
3497 \property Voice.Stem \revert #'transparent }
3500 \notes\relative c'' {
3502 a b c b \blanknotes c \unblanknotes d
3506 This method makes the grobs invisible but they still take the normal space.
3507 To remove all traces of the grob, you can redefine the function
3511 \notes\relative c'' {
3514 as bes c bes c d \break
3515 \property Staff.KeySignature \override #'molecule-callback = #'()
3518 \paper{linewidth=5.0\cm indent=0}
3522 A very rigorous way of removing grobs from the whole score is to remove
3523 the engraver that creates them. For example,
3525 @lilypond[singleline,verbatim]
3526 \score {\notes { c'4 d'8 e'8 g2 }
3527 \paper { \translator {
3529 \remove Stem_engraver
3535 @subsection Dirty tricks
3536 @cindex embedded tex
3538 It is possible to use @TeX{} commands in the strings, but this should be
3539 avoided because it makes it impossible for LilyPond to compute the
3540 exact length of the string, which may lead to collisions. Also, @TeX{}
3541 commands won't work with direct PostScript output (see @ref{PostScript
3544 @lilypond[fragment,relative,verbatim]
3545 a'^"3 $\\times$ \\`a deux"
3548 You can also use raw PostScript commands embedded in text scripts. This
3549 offers ultimate flexibility, but requires you to learn PostScript.
3550 Currently, embedded PostScript will @strong{not} work with direct
3551 PostScript output. Note that all dimensions that you use are in staff
3556 \notes \relative c'' {
3557 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3558 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3559 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3563 \paper { linewidth = 70*\staffspace }
3570 @section Page layout
3573 The page layout is the combined product of LilyPond formatting notation,
3574 and (La)@TeX{} putting the notation on a page, including page breaks.
3575 The part of LilyPond is documented here.
3589 @subsection Paper block
3592 The most important output definition is the @code{\paper} block, for
3593 music notation. The syntax is
3596 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3599 where each of the items is one of
3602 @item An assignment.
3604 @item A context definition. See @ref{Interpretation context} for
3605 more information on context definitions.
3607 @item \stylesheet declaration. Its syntax is
3609 \stylesheet @var{alist}
3612 See @file{scm/font.scm} for details of @var{alist}.
3613 @item an @code{\elementdescriptions} declaration.
3615 \elementdescriptions @var{alist}
3617 See @file{scm/grob-description.scm} for details of
3618 @var{alist}. This command is not user-serviceable.
3622 @c . {Paper variables}
3623 @node Paper variables
3624 @subsection Paper variables
3625 @cindex Paper variables
3627 The paper block has some variables you may want to use or change:
3630 @cindex @code{indent}
3632 The indentation of the first line of music.
3633 @cindex @code{staffspace}
3635 @item @code{staffspace}
3636 The distance between two staff lines, calculated from the center
3639 @cindex @code{linewidth}
3640 @item @code{linewidth}
3641 Sets the width of the lines.
3643 If set to a negative value, a single unjustified line is produced.
3644 @c rename to singleLinePaper ?
3645 The shorthand @code{\singleLine} defines a default paper block that
3646 produces a single line.
3648 @cindex @code{textheight}
3650 @item @code{textheight}
3651 Sets the total height of the music on each page. Only used by
3654 @cindex @code{interscoreline}
3656 @item @code{interscoreline}
3657 Sets the spacing between systems. The default is 16pt.
3659 @cindex @code{interscorelinefill}
3661 @item @code{interscorelinefill}
3662 If set to a positive number, the distance between the score
3663 lines will stretch in order to fill the full page. In that
3664 case @code{interscoreline} specifies the minimum spacing.
3669 @cindex @code{stafflinethickness}
3671 @item @code{stafflinethickness}
3672 Determines the thickness of staff lines, and also acts as a scaling
3673 parameter for other line thicknesses.
3676 You may enter these dimension using units (@code{cm}, @code{in},
3677 @code{mm}, @code{pt}), or relative to another dimension
3679 linewidth = 20.0 * \staffspace
3686 @subsection Font size
3687 @cindex font size, setting
3688 @cindex staff size, setting
3689 @cindex @code{paper} file
3691 The Feta font provides musical symbols at six different sizes. These
3692 fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
3693 point. The point size of a font is the height of the five lines in a
3694 staff when displayed in the font.
3696 Definitions for these sizes are the files @file{paperSZ.ly}, where
3697 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3698 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3699 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3700 @code{paperTwentysix} are defined respectively. The default
3701 @code{\paper} block is also set. These files should be imported at toplevel, i.e.
3703 \include "paper26.ly"
3707 The font definitions are generated using a Scheme function. For more
3708 details, see the file @file{scm/font.scm}.
3714 @subsection Paper size
3719 @cindex @code{papersize}
3721 To change the paper size, you must first set the
3722 @code{papersize} paper variable variable. Set it to
3723 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3724 specification, you must set the font as described above. If you want
3725 the default font, then use the 20 point font.
3728 \paper@{ papersize = "a4" @}
3729 \include "paper16.ly"
3732 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3733 will set the paper variables @code{hsize} and @code{vsize} (used by
3734 Lilypond and @code{ly2dvi})
3738 @subsection Line break
3741 @cindex breaking lines
3743 Line breaks are normally computed automatically. They are chosen such
3744 that it looks neither cramped nor loose, and that consecutive lines have
3747 Occasionally you might want to override the automatic breaks; you can do
3748 this by specifying @code{\break}. This will force a line break at this
3749 point. Do remember that line breaks can only occur at places where there
3750 are bar lines. If you want to have a line break where there is no
3751 bar line, you can force an invisible bar line by entering @code{\bar
3752 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3754 If you want linebreaks at regular intervals, you can use the following:
3757 < \repeat 7 unfold @{ s1 * 4 \break @}
3761 This makes the following 28 measures (assuming 4/4 time) be broken every
3765 @cindex @code{\penalty}
3767 The @code{\break} and @code{\noBreak} commands are defined in terms of
3768 the penalty command:
3773 This encourages or discourages LilyPond to make a line break at this
3778 The scaling of the @code{\penalty} argument is not well-defined. The
3779 command is rather kludgey, and slated for rewriting.
3783 @subsection Page break
3786 @cindex breaking pages
3788 Page breaks are normally computed by @TeX{}, so they are not under
3789 direct control of LilyPond. However, you can insert a commands into the
3790 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3791 the command @code{\newpage}
3792 @cindex @code{\newpage}
3798 @c why do so difficult?
3799 @c maybe should explain contents of between-system.ly,
3800 @c but not now, we're talking about page breaks here.
3802 @c details, see the example file @file{input/test/between-systems.ly}
3805 @c . {Output scaling}
3806 @node Output scaling
3807 @subsection Output scaling
3822 There is no mechanism to select magnification of particular fonts,
3823 meaning that you don't have access to continuously scaled fonts.
3827 @c . {Output formats}
3828 @node Output formats
3829 @section Output formats
3831 LilyPond can output processed music in different output formats.
3835 * PostScript output::
3837 * ASCIIScript output::
3841 @subsection TeX output
3844 LilyPond will use @TeX{} by default. Even if you want to produce
3845 PostScript output for viewing or printing, you should normally have
3846 LilyPond produce @TeX{} first. The .tex output must be processed by
3847 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
3848 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
3849 used to generate the .dvi for you.
3853 Titling is not generated unless you use @file{ly2dvi}.
3856 @node PostScript output
3857 @subsection PostScript output
3858 @cindex PostScript output
3859 @cindex direct PostScript output
3861 LilyPond can produce PostScript directly, without going through @TeX{}.
3862 Currently, this is mainly useful if you cannot use TeX, because direct
3863 PostScript output has some problems; see Bugs below.
3866 $ lilypond -fps foo.ly
3867 GNU LilyPond 1.3.144
3868 Now processing: `foo.ly'
3870 Interpreting music...[3]
3871 Preprocessing elements...
3872 Calculating column positions...
3873 paper output to foo.ps...
3875 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
3881 Text font selection is broken.
3883 The .ps file does not contain the .pfa font files. To print a .ps
3884 created through direct postscript output, you should prepend the
3885 necessary .pfa files to LilyPond's .ps output, or upload them to the
3886 printer before printing.
3888 The line height calculation is broken, you must set @var{lineheight} in
3889 the paperblock if you have more than one staff in your score, e.g.
3894 % Set line height to 40 staff spaces
3900 @subsection Scheme output
3901 @cindex Scheme output
3903 In the typesetting stage, LilyPond builds a page description, which is
3904 then written to disk in postscript, @TeX{} or ASCII art. Before it is
3905 written, the page description is represented as Scheme expressions. You
3906 can also dump these Scheme expressions to a file, which may be
3907 convenient for debugging output routines. This is done with the Scheme
3911 $ lilypond -fscm foo.ly
3912 GNU LilyPond 1.3.144
3913 Now processing: `foo.ly'
3915 Interpreting music...[3]
3916 Preprocessing elements...
3917 Calculating column positions...
3918 paper output to foo.scm...
3921 ;;; Usage: guile -s x.scm > x.tex
3922 (primitive-load-path 'standalone.scm)
3926 $ guile -s foo.scm > foo.tex
3930 @node ASCIIScript output
3931 @subsection ASCIIScript output
3932 @cindex ASCIIScript output
3933 @cindex ascii script
3936 LilyPond can output ASCII Art. This is a two step process, LilyPond
3937 produces an ASCII description file, dubbed ASCIIScript (extension
3938 @file{.as}). ASCIIScript has a small and simple command set that
3939 includes font selection, character and string printing and line drawing
3940 commands. The program @file{as2text} is used to translate an .as file
3943 To produce ASCII Art, you must include an ASCII Art paper definition
3944 file in your .ly, one of:
3946 \include "paper-as5.ly"
3947 \include "paper-as9.ly"
3950 Here's an example use for ASCII Art output (the example file
3951 @file{as-email.ly} is included in the LilyPond distribution), the staff
3952 symbol has been made invisible:
3955 $ lilypond -fas as-email.ly
3956 GNU LilyPond 1.3.144
3957 Now processing: `as-email.ly'
3959 Interpreting music...[3]
3960 Preprocessing elements...
3961 Calculating column positions... [2]
3962 paper output to as-email.as...
3964 $ as2text as-email.as 2>/dev/null
3966 |/ |##|##| | | | | |
3967 /| | | | | |\ |\ |\ |\ |\ |
3968 / |_ 3 | | | | 5 | )| )| )| )| )|
3969 | /| \ 8 * * * | 8 * * * * * |
3979 The ASCII Art fonts are far from complete and not very well designed.
3980 It's easy to change the glyphs, though; if you think you can do better,
3981 have a look at @file{mf/*.af}.
3983 Lots of resizable symbols such as slurs, ties and tuplets are missing.
3985 The poor looks of most ASCII Art output and its limited general
3986 usefulness gives ASCII Art output a low priority; it may be
3987 dropped in future versions.
3994 LilyPond can produce MIDI output. The performance lacks lots of
3995 interesting effects, such as swing, articulation, slurring, etc., but it
3996 is good enough for proof-hearing the music you have entered. Ties,
3997 dynamics and tempo changes are interpreted.
3999 Dynamic marks, crescendi and decrescendi translate into MIDI volume
4000 levels. Dynamic marks translate to a fixed fraction of the available
4001 MIDI volume range, crescendi and decrescendi make the the volume vary
4002 linearly between their two extremities. The fractions be adjusted by
4003 overriding the @code{absolute-volume-alist} defined in
4004 @file{scm/midi.scm}.
4006 For each type of musical instrument (that MIDI supports), a volume range
4007 can be defined. This gives you basic equalizer control, which can
4008 enhance the quality of the MIDI output remarkably. You can add
4009 instruments and ranges or change the default settings by overriding the
4010 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
4012 Both loudness controls are combined to produce the final MIDI volume.
4017 It is currently not possible to use the percussion channel (generally
4018 channel 10 of a MIDI file).
4022 * MIDI instrument names::
4027 @subsection MIDI block
4031 The MIDI block is analogous to the paper block, but it is somewhat
4032 simpler. The @code{\midi} block can contain:
4036 @item a @code{\tempo} definition
4037 @item context definitions
4040 Assignments in the @code{\midi} block are not allowed.
4044 @cindex context definition
4046 Context definitions follow precisely the same syntax as within the
4047 \paper block. Translation modules for sound are called performers.
4048 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
4051 @node MIDI instrument names
4052 @subsection MIDI instrument names
4054 @cindex instrument names
4055 @cindex @code{Staff.midiInstrument}
4056 @cindex @code{Staff.instrument}
4058 The MIDI instrument name is set by the @code{Staff.midiInstrument}
4059 property or, if that property is not set, the @code{Staff.instrument}
4060 property. The instrument name should be chosen from the list in
4061 @ref{MIDI instruments}.
4065 If the selected string does not exactly match, then LilyPond uses the
4066 default (Grand Piano). It is not possible to select an instrument by
4076 @c FIXME: Note entry vs Music entry at top level menu is confusing.
4079 @section Music entry
4087 When entering music with LilyPond, it is easy to introduce errors. This
4088 section deals with tricks and features that help you enter music, and
4089 find and correct mistakes.
4093 @subsection Relative
4095 @cindex relative octave specification
4097 Octaves are specified by adding @code{'} and @code{,} to pitch names.
4098 When you copy existing music, it is easy to accidentally put a pitch in
4099 the wrong octave and hard to find such an error. To prevent these
4100 errors, LilyPond features octave entry.
4102 @cindex @code{\relative}
4104 \relative @var{startpitch} @var{musicexpr}
4107 The octave of notes that appear in @var{musicexpr} are calculated as
4108 follows: If no octave changing marks are used, the basic interval
4109 between this and the last note is always taken to be a fourth or less
4110 (This distance is determined without regarding alterations; a
4111 @code{fisis} following a @code{ceses} will be put above the
4114 The octave changing marks @code{'} and @code{,} can be added to raise or
4115 lower the pitch by an extra octave. Upon entering relative mode, an
4116 absolute starting pitch must be specified that will act as the
4117 predecessor of the first note of @var{musicexpr}.
4119 Entering music that changes octave frequently is easy in relative mode.
4120 @lilypond[fragment,singleline,verbatim,center]
4126 And octave changing marks are used for intervals greater than a fourth.
4127 @lilypond[fragment,verbatim,center]
4129 c g c f, c' a, e'' }
4132 If the preceding item is a chord, the first note of the chord is used
4133 to determine the first note of the next chord. However, other notes
4134 within the second chord are determined by looking at the immediately
4137 @lilypond[fragment,verbatim,center]
4144 @cindex @code{\notes}
4146 The pitch after the @code{\relative} contains a note name. To parse
4147 the pitch as a note name, you have to be in note mode, so there must
4148 be a surrounding @code{\notes} keyword (which is not
4151 The relative conversion will not affect @code{\transpose},
4152 @code{\chords} or @code{\relative} sections in its argument. If you
4153 want to use relative within transposed music, you must place an
4154 additional @code{\relative} inside the @code{\transpose}.
4159 @subsection Bar check
4163 @cindex @code{barCheckNoSynchronize}
4167 Whenever a bar check is encountered during interpretation, a warning
4168 message is issued if it doesn't fall at a measure boundary. This can
4169 help you find errors in the input. Depending on the value of
4170 @code{barCheckNoSynchronize}, the beginning of the measure will be
4171 relocated, so this can also be used to shorten measures.
4173 A bar check is entered using the bar symbol, @code{|}:
4175 \time 3/4 c2 e4 | g2.
4180 @cindex skipTypesetting
4182 Failed bar checks are most often caused by entering incorrect
4183 durations. Incorrect durations often completely garble up the score,
4184 especially if it is polyphonic, so you should start correcting the score
4185 by scanning for failed bar checks and incorrect durations. To speed up
4186 this process, you can use @code{skipTypesetting} (See @ref{Skipping
4187 corrected music})). Bar
4190 @c . {Point and click}
4191 @node Point and click
4192 @subsection Point and click
4194 Point and click lets you find notes in the input by clicking on them in
4195 the Xdvi window. This makes it very easy to find input that causes some
4196 error in the sheet music.
4198 To use it, you need the following software
4200 @unnumberedsubsec Installation
4204 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
4205 Xdvi} version 22.36 or newer.
4207 Note that most @TeX{} distributions ship with xdvik, which is a
4208 different and less well maintained program. To find out which xdvi you
4209 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
4213 Xdvi must be configured to find the TeX fonts and music
4214 fonts. Refer to the Xdvi documentation for more information.
4217 @unnumberedsubsec Using it
4219 Add one of these lines to the top of your .ly file. The first one is for
4220 line location only. The second one is more convenient, but requires
4221 patching @code{emacsclient} and @code{server.el}.
4224 #(set! point-and-click line-location)
4227 In the emacs startup file (usually @file{~/.emacs}), add the following
4232 Make sure that the environment variable @code{XEDITOR} is set
4235 emacsclient --no-wait +%l %f
4237 The second one, that also specifies the column, only works if you have
4238 patched your emacsclient and server, and have compiled your @code{.ly}
4239 file using the @code{line-column-location} setting.
4241 When viewing, control-mousebutton 1 will take you to the originating
4242 spot in the @file{.ly} file. Control-mousebutton 2 will show all
4246 @unnumberedsubsec Column location
4248 If you want emacs to jump to the exact spot (and not just the line) on a
4249 click, you must enable column positioning. To do so, you need to patch
4250 emacsclient. Apply @file{emacsclient.patch} (included with the source
4251 package) to @file{emacsclient.c} and @file{server.el} from the emacs
4252 source code. Recompile and stick the recompiled emacsclient into a bin
4253 directory, and put @file{server.el} into a elisp directory
4254 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
4255 init file, before invoking server-start.
4258 (setq load-path (cons "~/usr/share/emacs" load-path))
4261 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
4263 At the top of the @code{ly} file, replace the @code{set!} line with the
4266 #(set! point-and-click line-column-location)
4269 One final hint: if you correct large files with point-and-click, then
4270 start correcting at the end of the file. When you start at the top, and
4271 insert one line, all subsequent locations will be off by a line.
4276 When you convert the @TeX{} file to PostScript using @code{dvips}, it
4277 will complain about not finding @code{src:X:Y} files. Those complaints
4278 are harmless, and can be ignored.
4280 @node Skipping corrected music
4281 @section Skipping corrected music
4283 The property @code{Score.skipTypesetting} can be used to switch on and
4284 off typesetting completely during the interpretation phase. When
4285 typesetting is switched off, the music is processed much more quickly.
4286 You can use this to skip over the parts of a score that you have already
4289 @lilypond[fragment,singleline,verbatim]
4290 \relative c'' { c8 d
4291 \property Score.skipTypesetting = ##t
4293 \property Score.skipTypesetting = ##f
4298 @node Interpretation context
4299 @section Interpretation context
4302 * Creating contexts::
4303 * Default contexts::
4304 * Context properties::
4305 * Engravers and performers::
4306 * Changing context definitions::
4307 * Defining new contexts::
4311 Interpretation contexts are objects that only exist during a run of
4312 LilyPond. During the interpretation phase of LilyPond (when it prints
4313 "interpreting music"), the music expression in a @code{\score} block is
4314 interpreted in time order. This is the same order that humans hear and
4317 During this interpretation, the interpretation context holds the
4318 state for the current point within the music. It contains information
4322 @item What notes are playing at this point?
4323 @item What symbols will be printed at this point?
4324 @item What is the current key signature, time signature, point within
4328 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4329 contained in a @internalsref{Staff} context (because a staff can contain
4330 multiple voices at any point), a @internalsref{Staff} context is contained in
4331 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4333 Contexts associated with sheet music output are called @emph{notation
4334 contexts}, those for sound output are called @emph{performance
4335 contexts}. The default definitions of the standard notation and
4336 performance contexts can be found in @file{ly/engraver-init.ly} and
4337 @file{ly/performer-init.ly}, respectively.
4339 @node Creating contexts
4340 @subsection Creating contexts
4342 @cindex @code{\context}
4343 @cindex context selection
4345 Contexts for a music expression can be selected manually, using the
4346 following music expression.
4349 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4352 This instructs lilypond to interpret @var{musicexpr} within the context
4353 of type @var{contexttype} and with name @var{contextname}. If this
4354 context does not exist, it will be created.
4356 @lilypond[verbatim,singleline]
4358 \notes \relative c'' {
4359 c4 <d4 \context Staff = "another" e4> f
4365 In this example, the @code{c} and @code{d} are printed on the
4366 default staff. For the @code{e}, a context Staff called
4367 @code{another} is specified; since that does not exist, a new
4368 context is created. Within @code{another}, a (default) Voice context
4369 is created for the @code{e4}. When all music referring to a
4370 context is finished, the context is ended as well. So after the
4371 third quarter, @code{another} is removed.
4375 @node Default contexts
4376 @subsection Default contexts
4378 Most music expressions don't need an explicit @code{\context}
4379 declaration: they inherit the
4380 notation context from their parent. Each note is a music expression, and
4381 as you can see in the following example, only the sequential music
4382 enclosing the three notes has an explicit context.
4384 @lilypond[verbatim,singleline]
4385 \score { \notes \context Voice = goUp { c'4 d' e' } }
4388 There are some quirks that you must keep in mind when dealing with
4391 First, every top level music is interpreted by the Score context, in other
4392 words, you may think of @code{\score} working like
4395 \context Score @var{music}
4399 Second, contexts are created automatically to be able to interpret the
4400 music expressions. Consider the following example.
4402 @lilypond[verbatim, singleline]
4403 \score { \context Score \notes { c'4 ( d' )e' } }
4406 The sequential music is interpreted by the Score context initially
4407 (notice that the @code{\context} specification is redundant), but when a
4408 note is encountered, contexts are setup to accept that note. In this
4409 case, a Thread, Voice and Staff are created. The rest of the sequential
4410 music is also interpreted with the same Thread, Voice and Staff context,
4411 putting the notes on the same staff, in the same voice.
4413 This is a convenient mechanism, but do not expect opening chords to work
4414 without @code{\context}. For every note, a separate staff is
4417 @cindex explicit context
4418 @cindex starting with chords
4419 @cindex chords, starting with
4421 @lilypond[verbatim, singleline]
4422 \score { \notes <c'4 es'> }
4425 Of course, if the chord is preceded by a normal note in sequential
4426 music, the chord will be interpreted by the Thread of the preceding
4428 @lilypond[verbatim,singleline]
4429 \score { \notes { c'4 <c'4 es'> } }
4434 @node Context properties
4435 @subsection Context properties
4437 Notation contexts have properties. These properties are from
4438 the @file{.ly} file using the following expression:
4439 @cindex @code{\property}
4441 \property @var{contextname}.@var{propname} = @var{value}
4444 Sets the @var{propname} property of the context @var{contextname} to the
4445 specified Scheme expression @var{value}. All @var{propname} and
4446 @var{contextname} are strings, which are typically unquoted.
4448 Properties that are set in one context are inherited by all of the
4449 contained contexts. This means that a property valid for the
4450 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4451 example) and thus take effect in all @internalsref{Voice} contexts.
4453 Properties can be unset using the following expression:
4455 \property @var{contextname}.@var{propname} \unset
4458 @cindex properties, unsetting
4459 @cindex @code{\unset}
4461 This removes the definition of @var{propname} in @var{contextname}. If
4462 @var{propname} was not defined in @var{contextname} (but was inherited
4463 from a higher context), then this has no effect.
4468 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4469 the inverse of @code{\property \set}.
4471 @node Engravers and performers
4472 @subsection Engravers and performers
4476 Basic building blocks of translation are called engravers; they are
4477 special C++ classes.
4481 @c . {Context definitions}
4482 @node Changing context definitions
4483 @subsection Changing context definitions
4485 @cindex context definition
4486 @cindex translator definition
4488 The most common way to define a context is by extending an existing
4489 context. You can change an existing context from the paper block, by
4490 first initializing a translator with an existing context identifier:
4494 @var{context-identifier}
4497 Then you can add and remove engravers using the following syntax:
4499 \remove @var{engravername}
4500 \consists @var{engravername}
4504 Here @var{engravername} is a string, the name of an engraver in the
4508 @lilypond[verbatim,singleline]
4512 \translator { \StaffContext
4513 \remove Clef_engraver
4519 You can also set properties in a translator definition. The syntax is as
4522 @var{propname} = @var{value}
4523 @var{propname} \set @var{grob-propname} = @var{pvalue}
4524 @var{propname} \override @var{grob-propname} = @var{pvalue}
4525 @var{propname} \revert @var{grob-propname}
4527 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4528 and @code{pvalue} are Scheme expressions. These type of property
4529 assignments happen before interpretation starts, so a @code{\property}
4530 command will override any predefined settings.
4533 To simplify editing translators, all standard contexts have standard
4534 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4535 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
4537 @node Defining new contexts
4538 @subsection Defining new contexts
4540 If you want to build a context from scratch, you must also supply the
4541 following extra information:
4543 @item A name, specified by @code{\name @var{contextname}}.
4545 @item A cooperation module. This is specified by @code{\type
4552 \type "Engraver_group_engraver"
4555 \consists "Staff_symbol_engraver"
4556 \consists "Note_head_engraver"
4557 \consistsend "Axis_group_engraver"
4561 The argument of @code{\type} is the name for a special engraver that
4562 handles cooperation between simple engravers such as
4563 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4564 for this engraver are the following:
4566 @cindex @code{Engraver_group_engraver}
4567 @item @code{Engraver_group_engraver}
4568 The standard cooperation engraver.
4570 @cindex @code{Score_engraver}
4572 @item @code{Score_engraver}
4573 This is cooperation module that should be in the top level context,
4574 and only the top level context.
4576 @cindex @code{Grace_engraver_group}
4578 @item @code{Grace_engraver_group}
4579 This is a special cooperation module (resembling
4580 @code{Score_engraver}) that is used to create an embedded
4587 @item @code{\alias} @var{alternate-name}
4588 This specifies a different name. In the above example,
4589 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4591 @item @code{\consistsend} @var{engravername}
4592 Analogous to @code{\consists}, but makes sure that
4593 @var{engravername} is always added to the end of the list of
4596 Some engraver types need to be at the end of the list; this
4597 insures they stay there even if a user adds or removes engravers.
4598 End-users generally don't need this command.
4600 @item @code{\accepts} @var{contextname}
4601 Add @var{contextname} to the list of contexts this context can
4602 contain in the context hierarchy. The first listed context is the
4603 context to create by default.
4605 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4606 completeness, but is never used in practice.
4609 @item @code{\name} @var{contextname}
4610 This sets the type name of the context, e.g. @internalsref{Staff},
4611 @internalsref{Voice}. If the name is not specified, the translator won't do
4615 In the @code{\paper} block, it is also possible to define translator
4616 identifiers. Like other block identifiers, the identifier can only
4617 be used as the very first item of a translator. In order to define
4618 such an identifier outside of @code{\score}, you must do
4623 foo = \translator @{ @dots{} @}
4630 \translator @{ \foo @dots{} @}
4638 @cindex paper types, engravers, and pre-defined translators
4645 @c . {Syntactic details}
4646 @node Syntactic details
4647 @section Syntactic details
4648 @cindex Syntactic details
4650 This section describes details that were too boring to be put elsewhere.
4655 * Music expressions::
4656 * Manipulating music expressions::
4664 @subsection Top level
4667 This section describes what you may enter at top level.
4671 @subsubsection Score
4674 @cindex score definition
4676 The output is generated combining a music expression with an output
4677 definition. A score block has the following syntax:
4680 \score @{ @var{musicexpr} @var{outputdefs} @}
4683 @var{outputdefs} are zero or more output definitions. If none is
4684 supplied, the default @code{\paper} block will be added.
4688 @c . {Default output}
4689 @subsubsection Default output
4691 Default values for the @code{\paper} and @code{\midi} block are set by
4692 entering such a block at the top level.
4695 @subsubsection Header
4697 @cindex @code{\header}
4700 A header describes bibliographic information of the file's contents. It
4701 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4702 use this information for generating titles. Key values that are used by
4703 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4704 meter, arranger, piece and tagline.
4706 @cindex @code{ly2dvi}
4710 \header @{ @var{key1} = @var{val1}
4711 @var{key2} = @var{val2} @dots{} @}
4714 It is customary to put the @code{\header} at the top of the file.
4716 @subsubsection Default output
4718 A @code{\midi} or @code{\paper} block at top level sets the default
4719 paper block for all scores that lack an explicit paper block.
4723 @subsection Identifiers
4727 What has this section got to do with identifiers?
4728 It seems more appropriate in the introduction to Chapter 4,
4734 All of the information in a LilyPond input file, is internally
4735 represented as a Scheme value. In addition to normal Scheme data types
4736 (such as pair, number, boolean, etc.), LilyPond has a number of
4737 specialized data types,
4744 @item Translator_def
4748 @item Music_output_def
4749 @item Moment (rational number)
4752 LilyPond also includes some transient object types. Objects of these
4753 types are built during a LilyPond run, and do not `exist' per se within
4754 your input file. These objects are created as a result of your input
4755 file, so you can include commands in the input to manipulate them,
4756 during a lilypond run.
4759 @item Grob: short for Graphical object. See @ref{Grobs}.
4760 @item Molecule: device-independent page output object,
4761 including dimensions. Produced by some Grob functions
4763 @item Translator: object that produces audio objects or Grobs. This is
4764 not yet user accessible.
4765 @item Font_metric: object representing a font.
4769 @node Music expressions
4770 @subsection Music expressions
4772 @cindex music expressions
4774 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4775 syllables are music expressions, and you can combine music expressions
4776 to form new ones, for example by enclosing a list of expressions in
4777 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4778 compound expression is formed out of the quarter note @code{c} and a
4779 quarter note @code{d}:
4782 \sequential @{ c4 d4 @}
4785 @cindex Sequential music
4786 @cindex @code{\sequential}
4787 @cindex sequential music
4790 @cindex Simultaneous music
4791 @cindex @code{\simultaneous}
4793 The two basic compound music expressions are simultaneous and
4797 \sequential @code{@{} @var{musicexprlist} @code{@}}
4798 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4800 For both, there is a shorthand:
4802 @code{@{} @var{musicexprlist} @code{@}}
4806 @code{<} @var{musicexprlist} @code{>}
4808 for simultaneous music.
4809 In principle, the way in which you nest sequential and simultaneous to
4810 produce music is not relevant. In the following example, three chords
4811 are expressed in two different ways:
4813 @lilypond[fragment,verbatim,center]
4814 \notes \context Voice {
4815 <a c'> <b d' > <c' e'>
4816 < { a b c' } { c' d' e' } >
4821 Other compound music expressions include
4824 \transpose @var{pitch} @var{expr}
4825 \apply @var{func} @var{expr}
4826 \context @var{type} = @var{id} @var{expr}
4827 \times @var{fraction} @var{expr}
4831 @c . {Manipulating music expressions}
4832 @node Manipulating music expressions
4833 @subsection Manipulating music expressions
4835 The @code{\apply} mechanism gives you access to the internal
4836 representation of music. You can write Scheme-functions that operate
4837 directly on it. The syntax is
4839 \apply #@var{func} @var{music}
4841 This means that @var{func} is applied to @var{music}. The function
4842 @var{func} should return a music expression.
4844 This example replaces the text string of a script. It also shows a dump
4845 of the music it processes, which is useful if you want to know more
4846 about how music is stored.
4848 @lilypond[verbatim,singleline]
4849 #(define (testfunc x)
4850 (if (equal? (ly-get-mus-property x 'text) "foo")
4851 (ly-set-mus-property x 'text "bar"))
4853 (ly-set-mus-property x 'elements
4854 (map testfunc (ly-get-mus-property x 'elements)))
4859 \apply #testfunc { c'4_"foo" }
4863 For more information on what is possible, see the automatically
4864 generated documentation.
4867 Directly accessing internal representations is dangerous: the
4868 implementation is subject to changes, so you should avoid this feature
4871 A final example is a function that reverses a piece of music in time:
4873 @lilypond[verbatim,singleline]
4874 #(define (reverse-music music)
4875 (let* ((elements (ly-get-mus-property music 'elements))
4876 (reversed (reverse elements))
4877 (span-dir (ly-get-mus-property music 'span-direction)))
4878 (ly-set-mus-property music 'elements reversed)
4880 (ly-set-mus-property music 'span-direction (- span-dir)))
4881 (map reverse-music reversed)
4884 music = \notes { c'4 d'4( e'4 f'4 }
4886 \score { \context Voice {
4888 \apply #reverse-music \music
4893 More examples are given in the distributed example files in
4896 @c . {Span requests}
4902 @subsubsection Span requests
4903 @cindex Span requests
4905 Notational constructs that start and end on different notes can be
4906 entered using span requests. The syntax is as follows:
4910 \spanrequest @var{startstop} @var{type}
4914 @cindex @code{\start}
4915 @cindex @code{\stop}
4917 This defines a spanning request. The @var{startstop} parameter is either
4918 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
4919 describes what should be started. Much of the syntactic sugar is a
4920 shorthand for @code{\spanrequest}, for example,
4922 @lilypond[fragment,verbatim,center]
4923 c'4-\spanrequest \start "slur"
4924 c'4-\spanrequest \stop "slur"
4927 Among the supported types are @code{crescendo}, @code{decrescendo},
4928 @code{beam}, @code{slur}. This is an internal command. Users are
4929 encouraged to use the shorthands which are defined in the initialization
4930 file @file{spanners.ly}.
4935 @subsection Assignments
4938 Identifiers allow objects to be assigned to names during the parse
4939 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
4940 and to refer to an identifier, you precede its name with a backslash:
4941 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
4942 the input-types listed above. Identifier assignments can appear at top
4943 level in the LilyPond file, but also in @code{\paper} blocks.
4945 An identifier can be created with any string for its name, but you will
4946 only be able to refer to identifiers whose names begin with a letter,
4947 being entirely alphabetical. It is impossible to refer to an identifier
4948 whose name is the same as the name of a keyword.
4950 The right hand side of an identifier assignment is parsed completely
4951 before the assignment is done, so it is allowed to redefine an
4952 identifier in terms of its old value, e.g.
4958 When an identifier is referenced, the information it points to is
4959 copied. For this reason, an identifier reference must always be the
4960 first item in a block.
4964 \paperIdent % wrong and invalid
4968 \paperIdent % correct
4973 @c . {Lexical modes}
4975 @subsection Lexical modes
4976 @cindex Lexical modes
4979 @cindex @code{\notes}
4980 @cindex @code{\chords}
4981 @cindex @code{\lyrics}
4983 To simplify entering notes, lyrics, and chords, LilyPond has three
4984 special input modes in addition to the default mode: note, lyrics and
4985 chords mode. These input modes change the way that normal, unquoted
4986 words are interpreted: for example, the word @code{cis} may be
4987 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
4988 major triad respectively.
4990 A mode switch is entered as a compound music expression
4992 @code{\notes} @var{musicexpr}
4993 @code{\chords} @var{musicexpr}
4994 @code{\lyrics} @var{musicexpr}.
4997 In each of these cases, these expressions do not add anything to the
4998 meaning of their arguments. They just instruct the parser in what mode
4999 to parse their arguments. The modes are treated in more detail in
5000 @ref{Lyrics} and @ref{Chords}.
5002 Different input modes may be nested.
5006 @subsection Ambiguities
5011 The grammar contains a number of ambiguities. We hope to resolve them at
5015 @item The assignment
5020 is interpreted as the string identifier assignment. However,
5021 it can also be interpreted as making a string identifier @code{\foo}
5022 containing @code{"bar"}, or a music identifier @code{\foo}
5023 containing the syllable `bar'.
5025 @item If you do a nested repeat like
5037 then it is ambiguous to which @code{\repeat} the
5038 @code{\alternative} belongs. This is the classic if-then-else
5039 dilemma. It may be solved by using braces.
5041 @item The parser is not sophisticated enough to distinguish at the
5043 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
5050 @c . {Lexical details}
5051 @node Lexical details
5052 @section Lexical details
5054 Even more boring details, now on lexical side of the input parser.
5065 * Version information::
5070 @subsection Comments
5073 @cindex block comment
5074 @cindex line comment
5078 A one line comment is introduced by a @code{%} character.
5079 Block comments are started by @code{%@{} and ended by @code{%@}}.
5080 They cannot be nested.
5083 @subsection Direct Scheme
5087 @cindex Scheme, in-line code
5090 LilyPond contains a Scheme interpreter (the GUILE library) for
5091 internal use. In some places, Scheme expressions also form valid syntax:
5092 wherever it is allowed,
5096 evaluates the specified Scheme code. Example:
5098 \property Staff.TestObject \override #'foobar = #(+ 1 2)
5100 @code{\override} expects two Scheme expressions, so there are two Scheme
5101 expressions. The first one is a symbol (@code{foobar}), the second one
5102 an integer (namely, 3).
5104 In-line scheme may be used at the top level. In this case the result is
5107 Scheme is a full-blown programming language, and a full discussion is
5108 outside the scope of this document. Interested readers are referred to
5109 the website @uref{http://www.schemers.org/} for more information on
5114 @subsection Keywords
5118 Keywords start with a backslash, followed by a number of lower case
5119 alphabetic characters. These are all the keywords.
5122 apply arpeggio autochange spanrequest commandspanrequest
5123 simultaneous sequential accepts alternative bar breathe
5124 char chordmodifiers chords clef cm consists consistsend
5125 context denies duration dynamicscript elementdescriptions
5126 font grace header in lyrics key mark pitch
5127 time times midi mm name pitchnames notes outputproperty
5128 override set revert partial paper penalty property pt
5129 relative remove repeat addlyrics partcombine score
5130 script stylesheet skip textscript tempo translator
5135 @subsection Integers
5143 Formed from an optional minus sign followed by digits. Arithmetic
5144 operations cannot be done with integers, and integers cannot be mixed
5149 @cindex real numbers
5155 Formed from an optional minus sign and a sequence of digits followed
5156 by a @emph{required} decimal point and an optional exponent such as
5157 @code{-1.2e3}. Reals can be built up using the usual operations:
5158 `@code{+}', `@code{-}', `@code{*}', and
5159 `@code{/}', with parentheses for grouping.
5167 A real constant can be followed by one of the dimension keywords:
5168 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5169 points, inches and centimeters, respectively. This converts the number
5170 a number that is the internal representation of that dimension.
5178 Begins and ends with the @code{"} character. To include a @code{"}
5179 character in a string write @code{\"}. Various other backslash
5180 sequences have special interpretations as in the C language. A string
5181 that contains no spaces can be written without the quotes. Strings can
5182 be concatenated with the @code{+} operator.
5186 @subsection Main input
5189 @cindex @code{\maininput}
5191 The @code{\maininput} command is used in init files to signal that the
5192 user file must be read. This command cannot be used in a user file.
5194 @node File inclusion
5195 @subsection File inclusion
5196 @cindex @code{\include}
5198 \include @var{filename}
5201 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5202 unquoted string will not work here!) or a string identifier. The full
5203 filename including the @file{.ly} extension must be given,
5206 @node Version information
5207 @subsection Version information
5208 @cindex @code{\version}
5210 \version @var{string}
5213 Specify the version of LilyPond that a file was written for. The
5214 argument is a version string in quotes, for example @code{"1.2.0"}.
5215 This is used to detect invalid input, and to aid
5216 @code{convert-ly} a tool that automatically upgrades input files. See
5217 See @ref{convert-ly} for more information on @code{convert-ly}.
5225 @c broken with emacs-21
5226 @c {Local emac s vars}
5227 @c Local varia bles:
5229 @c minor-mod e: font-lock
5230 @c minor-mo de: outline
5231 @c outline -layout: (-1 : 0)
5232 @c outlin e-use-mode-specific-leader: "@c \."
5233 @c outli ne-primary-bullet: "{"
5234 @c outli ne-stylish-prefixes: nil
5235 @c outli ne-override-protect: t