5 @c A menu is needed before every deeper *section nesting of @node's; run
6 @c M-x texinfo-all-menus-update
7 @c to automagically fill in these menus before saving changes
9 @c FIXME: singular vs. plural: Beams/Beam
18 @macro internalsref{NAME}
19 @uref{../lilypond-internals/\NAME\.html,\NAME\}
22 @macro seeinternals{NAME}
23 See @internalsref{\NAME\}
29 @macro seeinternals{NAME}
31 @macro internalsref{NAME}
38 @c .{Reference Manual}
40 @node Reference Manual
41 @chapter Reference Manual
44 <!--- @@WEB-TITLE@@=Reference Manual --->
47 This document describes GNU LilyPond and its input format. The last
48 revision of this document was made for LilyPond 1.4.1. It supposes a
49 passing familiarity with how LilyPond input works. New users are
50 encouraged to study the tutorial first.
52 The reference manual is ordered according to different tasks.
53 More details on the property setting mechanisms and context handling is
54 provided in @ref{Tuning output} and @ref{Interpretation context}. The
55 syntactical details are described at the end of the manual.
78 * Skipping corrected music::
79 * Interpretation context::
89 The purpose of LilyPond is explained informally by the term `music
90 typesetter'. This is not a fully correct name: not only does the
91 program print musical symbols, it also makes aesthetic decisions.
92 Symbols and their placements are @emph{generated} from a high-level
93 musical description. In other words, LilyPond would be best described
94 by `music compiler' or `music to notation compiler'.
96 LilyPond is linked to GUILE, GNU's Scheme library for extension
97 programming. The Scheme library provides the glue that holds together
98 the low-level routines and separate modules which are written in C++.
100 When lilypond is run to typeset sheet music, the following happens:
102 @item GUILE Initialization: various scheme files are read
103 @item parsing: first standard @code{ly} initialization files are read, and
104 then the user @file{ly} file is read.
105 @item interpretation: the music in the file is processed ``in playing
106 order'', i.e. the order that you use to read sheet music, or the
107 order in which notes are played. The result of this step is a typesetting
111 The typesetting specification is solved: positions and formatting is
114 @item the visible results ("virtual ink") are written to the output file.
117 During these stages different types of data play the the main role:
118 during parsing, @strong{Music} objects are created. During the
119 interpretation, @strong{contexts} are constructed, and with these contexts
120 a network of @strong{graphical objects} (``grobs'') is created. These
121 grobs contain unknown variables, and the network forms a set of
122 equations. After solving the equations and filling in these variables,
123 the printed output (in the form of @strong{molecules}) is written to an
126 These threemanship of tasks (parsing, translating, typesetting) and
127 data-structures (music, context, graphical objects) permeates the entire
128 design of the program.
130 @c FIXME: Note entry vs Music entry at top level menu is confusing.
136 The most basic forms of music are notes. We discuss how you enter them
137 here. Notes on their own don't form valid input, but for the sake of
138 brevity we omit obligatory lint such as @code{\score} blocks and
139 @code{\paper} declarations.
150 * Defining pitch names::
151 * Easy Notation note heads ::
158 A note specification has the form
161 @var{pitch}[!][?][@var{duration}]
164 The alteration refers to what note is heard, not to whether an
165 accidental is printed. This is done depending on the key and context.
166 A reminder accidental
167 @cindex reminder accidental
169 can be forced by adding an exclamation mark @code{!} after the pitch. A
170 cautionary accidental,
171 @cindex cautionary accidental
172 @cindex parenthesized accidental
173 i.e., an accidental within parentheses can be obtained by adding the
174 question mark `@code{?}' after the pitch.
176 @lilypond[fragment,verbatim,center]
177 cis' d' e' cis' c'? d' e' c'!
180 The grob for a note head is called @internalsref{NoteHead}.
188 @cindex Note specification
190 @cindex entering notes
192 The verbose syntax for pitch specification is
194 @cindex @code{\pitch}
196 \pitch @var{scmpitch}
199 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
201 In Note and Chord mode, pitches may be designated by names. The default
202 names are the Dutch note names. The notes are specified by the letters
203 @code{a} through @code{g} (where the octave is formed by notes ranging
204 from @code{c} to @code{b}). The pitch @code{c} is an octave below
205 middle C and the letters span the octave above that C.
207 @cindex note names, Dutch
209 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
210 name and a flat is formed by adding @code{-es}. Double sharps and double
211 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
212 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
213 both forms are accepted.
215 LilyPond has predefined sets of note names for various other languages.
216 To use them, simply include the language specific init file. For
217 example: @code{\include "english.ly"}. The available language files and
218 the names they define are:
221 Note Names sharp flat
222 nederlands.ly c d e f g a bes b -is -es
223 english.ly c d e f g a bf b -s/-sharp -f/-flat
224 deutsch.ly c d e f g a b h -is -es
225 norsk.ly c d e f g a b h -iss/-is -ess/-es
226 svenska.ly c d e f g a b h -iss -ess
227 italiano.ly do re mi fa sol la sib si -d -b
228 catalan.ly do re mi fa sol la sib si -d/-s -b
236 The optional octave specification takes the form of a series of
237 single quote (`@code{'}') characters or a series of comma
238 (`@code{,}') characters. Each @code{'} raises the pitch by one
239 octave; each @code{,} lowers the pitch by an octave.
241 @lilypond[fragment,verbatim,center]
242 c' c'' es' g' as' gisis' ais'
250 A rest is entered like a note, with note name `@code{r}':
252 @lilypond[singleline,verbatim]
256 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
257 specified using @code{R}, see @ref{Multi measure rests}.
259 For polyphonic music, it can be convenient to specify the rest position
260 directly. You can do that by entering a note, with the keyword
261 @code{\rest} appended, e.g. Rest collisions will leave these rests alone.
263 @lilypond[singleline,verbatim]
273 @cindex Invisible rest
276 An invisible rest, or skip, can be entered like a note with note name
279 @lilypond[singleline,verbatim]
283 Actually, this is a shorthand for the @code{\skip} command, and it is
284 only available in Note mode and Chord mode.
286 @c FIXME: in lyrics mode, we have " " and _
288 In Lyrics mode, you can use `@code{" "}' and `@code{_}':
289 @lilypond[singleline,verbatim]
291 \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
292 \notes\relative c'' { a2 a4 a a2 a4 a }
296 The unabbreviated `@code{\skip} @var{duration}' also works outside of
299 @lilypond[singleline,verbatim]
302 { \time 4/8 \skip 2 \time 4/4 }
303 \notes\relative c'' { a2 a1 }
308 Note that the skip does not produce any output, not even transparent output.
313 @subsection Durations
317 @cindex @code{\duration}
319 The syntax for a verbose duration specification is
321 \duration @var{scmduration}
323 Here, @var{scmduration} is a Scheme object of type @code{Duration}. See
324 @ref{Duration} for more information.
327 In Note, Chord, and Lyrics mode, durations may be designated by numbers
328 and dots: durations are entered as their reciprocal values. For notes
329 longer than a whole you must use identifiers.
333 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
335 r1 r2 r4 r8 r16 r32 r64 r64
341 \notes \relative c'' {
343 a1 a2 a4 a8 a16 a32 a64 a64
345 r1 r2 r4 r8 r16 r32 r64 r64
350 \remove "Clef_engraver"
351 \remove "Staff_symbol_engraver"
352 \remove "Time_signature_engraver"
353 \consists "Pitch_squash_engraver"
359 To get a longa note head, you have to use mensural note heads. This
360 is accomplished by setting the @code{style} property of the
361 NoteHead grob to @code{mensural}. There is also a note head style
362 @code{baroque} which gives mensural note heads for @code{\longa} and
363 @code{\breve} but standard note heads for shorter notes.
365 @lilypond[fragment,singleline,verbatim]
366 \property Voice.NoteHead \set #'style = #'mensural
370 If the duration is omitted then it is set to the previous duration
371 entered. At the start of parsing a quarter note is assumed. The
372 duration can be followed by dots (`@code{.}') to obtain dotted note
376 @lilypond[fragment,verbatim,center]
382 You can alter the length of duration by a fraction @var{N/M} by
383 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
384 will not affect the appearance of the notes or rests produced.
396 A tie connects two adjacent note heads of the same pitch. When used
397 with chords, it connects all the note heads whose pitches match.
398 Ties are indicated using the tilde symbol `@code{~}'. If you try to tie
399 together chords which have no common pitches then no ties will be
402 @lilypond[fragment,verbatim,center]
403 e' ~ e' <c' e' g'> ~ <c' e' g'>
406 If you dislike the amount of ties created for a chord, you set
407 @code{Voice.sparseTies} to true, resulting in a smaller number of
409 @lilypond[fragment,verbatim,center]
410 \property Voice.sparseTies = ##t
411 <c' e' g'> ~ <c' e' g'>
414 In its meaning a tie is just a way of extending a note duration, similar
415 to the augmentation dot: the following example are two ways of notating
416 exactly the same concept.
418 @lilypond[fragment, singleline]
419 \time 3/4 c'2. c'2 ~ c'4
422 The name of the tie grob is @internalsref{Tie}, and it is created in the
423 @internalsref{Voice} context.
427 At present, the tie is implemented as a separate thing, temporally
428 located in between the notes. There is also no way to convert
429 between tied notes, dotted notes and plain notes.
431 Tieing only a subset of the note heads of a chord is not supported in a
432 simple way. It can be achieved by moving the tie-engraver into the Thread
433 context and turning on and off ties per Thread.
441 @cindex @code{\times}
443 Tuplets are made out of a music expression by multiplying all duration
446 @cindex @code{\times}
448 \times @var{fraction} @var{musicexpr}
451 The duration of @var{musicexpr} will be multiplied by the fraction.
452 In print, the fraction's denominator will be printed over the notes,
453 optionally with a bracket. The most common tuplet is the triplet in
454 which 3 notes have the length of 2, so the notes are 2/3 of
455 their written length:
457 @lilypond[fragment,verbatim,center]
458 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
461 The property @code{tupletSpannerDuration} specifies how long each bracket
462 should last. With this, you can make lots of tuplets while typing
463 @code{\times} only once, thus saving typing work.
465 @lilypond[fragment, relative, singleline, verbatim]
466 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
467 \times 2/3 { c'8 c c c c c }
470 The format of the number is determined by the property
471 @code{tupletNumberFormatFunction}. The default prints only the
472 denominator, but if you set it to the Scheme function
473 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
476 The typesetting of brackets and numbers is controlled by the properties
477 @code{tuplet-bracket-visibility} and @code{tuplet-number-visibility}.
479 @lilypond[fragment, relative, singleline, verbatim]
480 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t
481 \times 2/3{c'8 d e} \times 2/3{d4 e8}
482 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam
483 \times 2/3{c d e} \times 2/3{d4 e8}
484 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f
485 \times 2/3{c d e} \times 2/3{d4 e8}
486 \property Voice.TupletBracket \set #'tuplet-number-visibility = ##f
487 \times 2/3{c d e} \times 2/3{d4 e8}
488 \property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam
489 \times 2/3{c d e} \times 2/3{d4 e8}
492 @cindex @code{tupletNumberFormatFunction}
493 @cindex tuplet formatting
495 Tuplet brackets are printed as @internalsref{TupletBracket} grobs, most
496 often in the @internalsref{Voice} context.
498 @c . {Defining pitch names}
499 @node Defining pitch names
500 @subsection Defining pitch names
502 @cindex defining pitch names
503 @cindex pitch names, defining
505 Note names and chord modifiers can be customized for nationalities. The
506 syntax is as follows.
508 @cindex @code{\pitchnames}
509 @cindex @code{\chordmodifiers}
511 \pitchnames @var{scheme-alist}
512 \chordmodifiers @var{scheme-alist}
515 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
516 specific examples on how to do this.
519 @node Easy Notation note heads
520 @subsection Easy Notation note heads
522 @cindex easy notation
525 A entirely different type of note head is the "easyplay" note head: a
526 note head that includes a note name. It is used in some publications by
527 Hal-Leonard Inc. music publishers.
529 @lilypond[singleline,verbatim]
530 \include "paper23.ly"
532 \notes { c'2 e'4 f' | g'1 }
533 \paper { \translator { \EasyNotation } }
537 Note that @internalsref{EasyNotation} overrides a @internalsref{Score} context. You
538 probably will want to print it with magnification to make it more
539 readable, see @ref{Output scaling}.
545 If you view the result with Xdvi, then staff lines will show through the
546 letters. Printing the postscript file obtained either by using dvips or
547 the @code{-f ps} option of lilypond produces the correct result.
552 @section Staff notation
554 @cindex Staff notation
566 @subsection Key signature
571 Setting or changing the key signature is done with the @code{\key}
574 @code{\key} @var{pitch} @var{type}
577 @cindex @code{\minor}
578 @cindex @code{\major}
579 @cindex @code{\minor}
580 @cindex @code{\ionian}
581 @cindex @code{\locrian}
582 @cindex @code{\aeolian}
583 @cindex @code{\mixolydian}
584 @cindex @code{\lydian}
585 @cindex @code{\phrygian}
586 @cindex @code{\dorian}
588 Here, @var{type} should be @code{\major} or @code{\minor} to get
589 @var{pitch}-major or @var{pitch}-minor, respectively.
590 The standard mode names @code{\ionian},
591 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
592 @code{\phrygian}, and @code{\dorian} are also defined.
594 This command sets the context property @code{Staff.keySignature}.
595 Non-standard key signatures can be specified by setting this property
598 The printed signature is a @internalsref{KeySignature} grob, typically
599 created in @internalsref{Staff} context.
601 @cindex @code{keySignature}
608 The clef can be set or changed with the @code{\clef} command.
616 \property Staff.clefGlyph = @var{glyph associated with clefname}
617 \property Staff.clefPosition = @var{clef Y-position for clefname}
618 \property Staff.centralCPosition = @var{position for central C}
619 \property Staff.clefOctavation = @var{extra transposition of clefname}
623 Any change in these properties creates a clef (A @internalsref{Clef} grob).
625 Supported clef-names include
627 @c Moved standard clefs to the top /MB
629 @item treble, violin, G, G2
638 G clef on 1st line, so-called French violin clef
653 By adding @code{_8} or @code{^8} to the clef name, the clef is
654 transposed one octave down or up, respectively. Note that you have to
655 enclose @var{clefname} in quotes if you use underscores or digits in the
661 Supported associated glyphs (for @code{Staff.clefGlyph}) are:
670 @item clefs-vaticana_do
671 Editio Vaticana style do clef
672 @item clefs-vaticana_fa
673 Editio Vaticana style fa clef
674 @item clefs-medicaea_do
675 Editio Medicaea style do clef
676 @item clefs-medicaea_fa
677 Editio Medicaea style fa clef
678 @item clefs-mensural1_c
679 modern style mensural C clef
680 @item clefs-mensural2_c
681 historic style small mensural C clef
682 @item clefs-mensural3_c
683 historic style big mensural C clef
684 @item clefs-mensural1_f
685 historic style traditional mensural F clef
686 @item clefs-mensural2_f
687 historic style new mensural F clef
688 @item clefs-mensural_g
689 historic style mensural G clef
690 @item clefs-hufnagel_do
691 historic style hufnagel do clef
692 @item clefs-hufnagel_fa
693 historic style hufnagel fa clef
694 @item clefs-hufnagel_do_fa
695 historic style hufnagel combined do/fa clef
696 @item clefs-percussion
697 modern style percussion clef
700 @emph{Modern style} means ``as is typeset in current editions.''
701 @emph{Historic style} means ``as was typeset or written in contemporary
702 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
705 @cindex Vaticana, Editio
706 @cindex Medicaea, Editio
707 @cindex hufnagel clefs
710 @c . {Time signature}
712 @subsection Time signature
713 @cindex Time signature
717 The time signature is set or changed by the @code{\time}
720 \time @var{n}@code{/}@var{d}
722 Internally, this is a shortcut for doing
724 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
725 \property Score.beatLength = #(make-moment 1 @var{d})
726 \property Score.measureLength = #(make-moment @var{n} @var{d})
729 These properties @code{timeSignatureFraction} determine where bar lines
730 should be inserted, and how automatic beams should be
733 Changing the value of @code{timeSignatureFraction} also causes a
734 fraction to be printed. This grob is @internalsref{TimeSignature}.
736 The actual symbol that's printed can be customized with the style
738 @lilypond[fragment, verbatim, singleline]
740 \property Staff.TimeSignature \override #'style = #'C
742 \property Staff.TimeSignature \override #'style = #'()
744 \property Staff.TimeSignature \override #'style = #'C
748 There are many more options for the layout of this grob. They are
749 selected through the @code{style} grob property.
751 @c FIXME: this isn't documented except in example?
753 @file{input/test/time.ly} for examples.
760 @cindex partial measure
761 @cindex measure, partial
762 @cindex shorten measures
763 @cindex @code{\partial}
765 Partial measures, for example in upbeats, are entered using the
766 @code{\partial} command:
768 \partial @var{duration}
771 Internally, this is a shortcut for
774 \property Score.measurePosition = -@var{length of duration}
778 The property @code{measurePosition} contains a rational number
779 indicating how much of the measure has passed at this point.
782 @node Unmetered music
783 @subsection Unmetered music
785 Bar lines and bar numbers are calculated automatically. For unmetered
786 music (e.g. cadenzas), this is not desirable. The property
787 @code{Score.timing} can be used to switch off this automatic timing
789 @lilypond[fragment,relative,singleline,verbatim]
791 \property Score.timing = ##f
793 \property Score.timing = ##t
797 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
804 @subsection Bar lines
808 @cindex measure lines
815 This is a shortcut for doing
817 \property Score.whichBar = @var{bartype}
819 The following bar types are available
821 @lilypond[fragment, relative, singleline, verbatim]
834 You are encouraged to use @code{\repeat} for repetitions. See
838 @cindex Bar_line_engraver
840 @cindex repeatCommands
841 @cindex defaultBarType
843 Whenever @code{whichBar} is set to a string, a bar line of that type is
844 created. @code{whichBar} is usually set automatically: at the start of
845 a measure it is set to @code{defaultBarType}. The contents of
846 @code{repeatCommands} is used to override default measure bars.
848 @code{whichBar} can also be set directly, using @code{\property} or
849 @code{\bar }. These settings take precedence over the automatic
850 @code{whichBar} settings.
852 @internalsref{BarLine} grobs are created by the @code{Bar_engraver}.
859 Polyphonic parts, i.e. parts with more than one voice on a staff can be
860 typeset with LilyPond.
862 The easiest way to enter such fragments, is the Scheme function
863 @code{voicify-music}. It will split chords using the separator
864 @code{\\}, to make multiple voices. You can use it for small,
865 short-lived voices (make a chord of voices) or for single chords:
867 @lilypond[verbatim,fragment]
868 \context Voice = VA \apply #voicify-music \relative c'' {
869 c4 < { f d e } \\ { b c2 } > c4 < g' \\ c, \\ f \\ d >
873 The function @code{voicify-music} instantiates @internalsref{Voice}
874 contexts, bearing the names @code{"1"}, @code{"2"}, etc.
876 To explicity typeset polyphonic music, instantiate a separate Voice
877 context for each part, and assign a stem direction to each part.
879 @lilypond[fragment,verbatim]
881 < \context Voice = VA { \stemUp b'4 a' g' f' e' }
882 \context Voice = VB { \stemDown g'4 g' g' g' g' } >
885 When there are more than two voices on a staff, you must also indicate
886 which voice should moved horizontally in case of a collision. This can
887 be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
888 @code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift}
889 in @internalsref{NoteColumn}).
891 @lilypond[fragment, verbatim]
892 \context Staff \notes\relative c''<
899 \context Voice=three {
900 \shiftOnn \stemUp ais
902 \context Voice=four {
903 \shiftOnnn \stemUp fis
908 The most convenient way is to use the identifiers @code{\voiceOne}
909 through @code{\voiceFour}, which also set slur and tie directions in the
912 @lilypond[singleline, verbatim]
914 \context Staff < \context Voice = VA { \voiceOne cis2 b }
915 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
916 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
919 Normally, note heads with a different number of dots are not merged, but
920 if you set the grob property @code{merge-differently-dotted}, they are:
922 @lilypond[verbatim,fragment,singleline]
924 \context Voice = VA { \voiceOne
926 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
929 \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] }
933 LilyPond also vertically shifts rests that are opposite of a stem.
935 @lilypond[singleline,verbatim]
937 \context Voice { \stemUp c''4 }
938 \context Voice =VB { r4 }
942 Note head collisions (horizontal shifting of note heads) are handled by
943 the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
944 handles vertical shifting of rests.
952 Resolving collisions is a very intricate subject, and LilyPond only
953 handles a few situations. When it can not cope, you are advised to use
954 @code{force-hshift} of the NoteColumn grob and @code{staff-position} of
955 the Rest grob to override typesetting decisions.
960 Beams are used to group short notes into chunks that are aligned with
961 the metrum. LilyPond guesses where beams should be inserted. If you're
962 not satisfied with the automatic beaming, you can specify which patterns
963 to beam automatically. In specific cases, you can also enter the beams
967 @c . {Automatic beams}
968 @subsection Automatic beams
970 @cindex @code{Voice.autoBeamSettings}
971 @cindex @code{(end * * * *)}
972 @cindex @code{(begin * * * *)}
975 In normal time signatures, automatic beams can start on any note but can
976 only end in a few positions within the measure: beams can end on a beat,
977 or at durations specified by the properties in
978 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
979 are defined in @file{scm/auto-beam.scm}.
981 The value of @code{autoBeamSettings} is changed using
982 @code{\override} and unset using @code{\revert}:
984 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
985 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
987 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
988 whether the rule applies to begin or end-points. The quantity
989 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
990 *}' designates notes of any length), @var{N}/@var{M} refers to a time
991 signature (wildcards, `@code{* *}' may be entered to designate all time
994 For example, if you want automatic beams to end on every quarter note,
995 you can use the following:
997 \property Voice.autoBeamSettings \override
998 #'(end * * * *) = #(make-moment 1 4)
1000 Since the duration of a quarter note is 1/4 of a whole note, it is
1001 entered as @code{(make-moment 1 4)}.
1003 The same syntax can be used to specify beam starting points. In this
1004 example, automatic beams can only end on a dotted quarter note.
1006 \property Voice.autoBeamSettings \override
1007 #'(end * * * *) = #(make-moment 3 8)
1009 In 4/4 time signature, this means that automatic beams could end only on
1010 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1011 3/8 has passed within the measure).
1013 You can also restrict rules to specific time signatures. A rule that
1014 should only be applied in @var{N}/@var{M} time signature is formed by
1015 replacing the second asterisks by @var{N} and @var{M}. For example, a
1016 rule for 6/8 time exclusively looks like
1018 \property Voice.autoBeamSettings \override
1019 #'(begin * * 6 8) = ...
1022 If you want a rule to apply to certain types of beams, you can use the
1023 first pair of asterisks. Beams are classified according to the shortest
1024 note they contain. For a beam ending rule that only applies to beams
1025 with 32nd notes (and no shorter notes), you would use @code{(end 1
1029 @c Automatic beams can not be put on the last note in a score.
1031 If a score ends while an automatic beam has not been ended and is still
1032 accepting notes, this last beam will not be typeset at all.
1034 @cindex automatic beam generation
1036 @cindex @code{Voice.noAutoBeaming}
1038 Automatic beaming is on by default, but can be switched off by setting
1039 @code{Voice.noAutoBeaming} to true. You you may find this necessary for
1040 a melody that goes with lyrics.
1044 It is not possible to specify beaming parameters for beams with mixed
1045 durations, that differ from the beaming parameters of all separate
1046 durations, i.e., you'll have to specify manual beams to get:
1047 @lilypond[fragment,singleline,relative]
1048 \property Voice.autoBeamSettings
1049 \override #'(end * * * *) = #(make-moment 3 8)
1050 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
1053 It is not possible to specify beaming parameters that act differently in
1054 different parts of a measure. This means that it is not possible to use
1055 automatic beaming in irregular meters such as @code{5/8}.
1058 @cindex Automatic beams
1059 @subsection Manual beams
1060 @cindex beams, manual
1064 In some cases it may be necessary to override LilyPond's automatic
1065 beaming algorithm. For example, the auto beamer will not beam over
1066 rests or bar lines, If you want that, specify the begin and end point
1067 manually using a @code{[} before the first beamed note and a @code{]}
1068 after the last note:
1070 @lilypond[fragment,relative,verbatim]
1072 r4 [r8 g' a r8] r8 [g | a] r8
1075 Whenever an manual beam is busy, the automatic beamer will not produce
1078 @cindex @code{stemLeftBeamCount}
1080 Normally, beaming patterns within a beam are determined automatically.
1081 When this mechanism fouls up, the properties
1082 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. can
1083 be used to control the beam subdivision on a stem. If you set either
1084 property, it's value will be used only once, and then it is erased.
1086 @lilypond[fragment,relative,verbatim]
1089 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
1092 @cindex @code{stemRightBeamCount}
1094 The beam symbol (grob @internalsref{Beam} in @internalsref{Voice}
1095 context), both for automatic and manual beams) can be tweaked through
1096 grob-properties @code{height} and @code{staff-position}. These specify
1097 vertical location and vertical span. Both are measured in half
1098 staff-spaces, @code{staff-position=0} corresponds to the middle staff
1101 Set @code{height} to zero, to get horizontal beams:
1103 @lilypond[fragment,relative,verbatim]
1104 \property Voice.Beam \set #'direction = #1
1105 \property Voice.Beam \set #'height = #0
1109 Here's how you'd specify a weird looking beam that instead of being
1110 horizontal, falls two staff spaces:
1112 @lilypond[fragment,relative,verbatim]
1113 \property Voice.Beam \set #'staff-position = #4
1114 \property Voice.Beam \set #'height = #-4
1118 @c TODO -> why this ref? Document?
1119 @cindex @code{neutral-direction}
1121 @node Expressive marks
1122 @section Expressive marks
1137 A slur indicates that notes are to be played bound or @emph{legato}.
1138 They are entered using parentheses:
1140 @lilypond[fragment,verbatim,center]
1141 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1145 Slurs avoid crossing stems, and are generally attached to note heads.
1146 However, in some situations with beams, slurs may be attached to stem
1147 ends. If you want to override this layout you can do this through the
1148 grob-property @code{attachment} of @internalsref{Slur} in
1149 @internalsref{Voice} context It's value is a pair of symbols, specifying
1150 the attachment type of the left and right end points.
1152 @lilypond[fragment,relative,verbatim]
1153 \property Voice.Slur \set #'direction = #1
1154 \property Voice.Stem \set #'length = #5.5
1156 \property Voice.Slur \set #'attachment = #'(stem . stem)
1160 If a slur would strike through a stem or beam, the slur will be moved
1161 away upward or downward. If this happens, attaching the slur to the
1162 stems might look better:
1164 @lilypond[fragment,relative,verbatim]
1165 \property Voice.Stem \set #'direction = #1
1166 \property Voice.Slur \set #'direction = #1
1168 \property Voice.Slur \set #'attachment = #'(stem . stem)
1173 Similarly, the curvature of a slur is adjusted to stay clear of note
1174 heads and stems. When that would increase the curvature too much, the
1175 slur is reverted to its default shape. The threshold for this decision
1176 is in @internalsref{Slur}'s grob-property @code{beautiful}. It is loosely
1177 related to the enclosed area between the slur and the notes. Usually,
1178 the default setting works well, but in some cases you may prefer a
1179 curved slur when LilyPond decides for a vertically moved one. You can
1180 indicate this preference by increasing the @code{beautiful} value:
1182 @lilypond[verbatim,singleline,relative]
1183 \property Voice.Beam \override #'direction = #-1
1184 \property Voice.Slur \override #'direction = #1
1185 c16( a' f' a a f a, )c,
1186 c( a' f' a a f d, )c
1187 \property Voice.Slur \override #'beautiful = #5.0
1188 c( a' f' a a f d, )c
1193 @code{beautiful} is an arbitrary parameter in the slur formatter.
1194 Useful values can only be determined by trial and error.
1196 @cindex Adjusting slurs
1198 @node Phrasing slurs
1199 @subsection Phrasing slurs
1201 @cindex phrasing slurs
1202 @cindex phrasing marks
1204 A phrasing slur (or phrasing mark) connects chords and is used to
1205 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1208 @lilypond[fragment,verbatim,center,relative]
1209 \time 6/4 c' \( ( d ) e f ( e ) \) d
1212 Typographically, the phrasing slur behaves almost exactly like a normal
1213 slur. The grob associated with it is @internalsref{PhrasingSlur}, in
1214 @internalsref{Voice} context.
1217 @subsection Breath marks
1219 Breath marks are entered using @code{\breathe}. The result is a
1220 @internalsref{BreathingSign} grob in @internalsref{Voice} context.
1222 @lilypond[fragment,relative]
1231 The current layout of the default comma style breath marks
1232 could be improved and more optional symbols should be added to the
1241 @cindex beats per minute
1242 @cindex metronome marking
1244 Metronome settings can be entered as follows:
1246 @cindex @code{\tempo}
1248 \tempo @var{duration} = @var{perminute}
1251 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1256 The tempo setting is not printed, but is only used in the MIDI
1257 output. You can trick lily into producing a metronome mark,
1258 though. Details are in @ref{Text markup}.
1263 @subsection Text spanners
1264 @cindex Text spanners
1266 Some textual indications, e.g. rallentando or accelerando, often extend
1267 over many measures. This is indicated by following the text with a
1268 dotted line. You can create such texts using text spanners. The syntax
1271 \spanrequest \start "text"
1272 \spanrequest \stop "text"
1274 LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
1275 in @internalsref{Voice} context). The string to be printed, as well as the
1276 style is set through grob properties.
1278 An application---or rather, a hack---is to fake octavation indications.
1279 @lilypond[fragment,relative,verbatim]
1280 \relative c' { a''' b c a
1281 \property Voice.TextSpanner \set #'type = #'dotted-line
1282 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1283 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1284 \property Staff.centralCPosition = #-13
1285 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1303 @subsection Articulations
1304 @cindex Articulations
1306 @cindex articulations
1310 A variety of symbols can appear above and below notes to indicate
1311 different characteristics of the performance. These symbols can be
1312 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1313 are defined in @file{script.ly}. Symbols can be forced to appear above
1314 or below the note by writing `@var{note}@code{^\}@var{name}' and
1315 `@var{note}@code{_\}@var{name}' respectively. Here is a chart showing
1316 symbols on notes, with the name of the corresponding symbol appearing
1322 \property Score.LyricSyllable \override #'font-family =#'typewriter
1323 \property Score.LyricSyllable \override #'font-shape = #'upright
1324 \context Staff \notes {
1325 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1326 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1327 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1328 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1329 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1330 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1331 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1332 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1334 \context Lyrics \lyrics {
1335 accent__ marcato__ staccatissimo__ fermata
1336 stopped__ staccato__ tenuto__ upbow
1337 downbow__ lheel__ rheel__ ltoe
1338 rtoe__ turn__ open__ flageolet
1339 reverseturn__ trill__ prall__ mordent
1340 prallprall__ prallmordent__ uprall__ downprall
1341 upmordent__ downmordent__ pralldown__ prallup__
1342 lineprall__ thumb__ segno__ coda
1346 linewidth = 5.875\in
1352 To save typing work, some shorthands are available:
1353 @lilypond[singleline]
1355 \notes \context Voice {
1356 \property Voice.TextScript \set #'font-family = #'typewriter
1357 \property Voice.TextScript \set #'font-shape = #'upright
1363 c''4-^_"c-\\^{ }" s4
1370 Fingering instructions can also be entered in this shorthand. For
1371 changes, some markup texts would be needed:
1372 @lilypond[verbatim, singleline, fragment]
1373 c'4-1 c'4-2 c'4-3 c'4-4
1378 @cindex @code{\script}
1383 You can add scripts by editing @file{scm/script.scm}. This file contains
1384 a table, listing script definitions and aliases. The following syntax
1385 accesses a script definition from the table:
1391 Usually the @code{\script} keyword is not used directly. Various
1392 helpful identifier definitions appear in @file{script.ly}.
1394 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
1398 All of these note ornaments appear in the printed output but have no
1399 effect on the MIDI rendering of the music.
1401 Unfortunately, there is no support for adding fingering instructions or
1402 ornaments to individual note heads. Some hacks exist, though. See
1403 @file{input/test/script-horizontal.ly}.
1408 @subsection Text scripts
1409 @cindex Text scripts
1411 In addition, it is possible to place arbitrary strings of text or markup
1412 text (see @ref{Text markup}) above or below notes by using a string:
1415 By default, these indications do not influence the note spacing, but
1416 if @code{Voice.textNonEmpty} is set to true the widths will be taken
1417 into account. The identifier @code{\fatText} is defined in the standard
1419 @lilypond[fragment,singleline,verbatim]
1420 \relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
1423 Text scripts are created in form of @internalsref{TextScript} grobs, in
1424 @internalsref{Voice} context.
1426 @ref{Text markup} describes how to change the font or access
1427 special symbols in text scripts.
1431 @subsection Grace notes
1440 @cindex @code{\grace}
1443 @cindex @code{graceAlignPosition}
1445 Grace notes are ornaments that are written out, but do not take up any
1446 logical time in a measure. LilyPond has limited support for grace notes.
1447 The syntax is as follows.
1449 \grace @var{musicexpr}
1452 Unbeamed eighth notes and shorter by default have a slash through the
1455 @lilypond[fragment,verbatim]
1457 \grace c8 c4 \grace { [c16 c16] } c4
1459 \property Voice.Stem \override #'flag-style = #'()
1461 \property Voice.Stem \revert #'flag-style
1466 A grace note expression has duration 0; the next real note is assumed to
1467 be the main note. If you want the note to appear after the main note,
1468 set @code{Voice.graceAlignPosition} to @code{1}.
1472 Nesting @code{\grace} notes is not supported. The following may cause
1473 run-time errors: @example
1474 @code{\grace @{ \grace c32 c16 @} c4}
1476 Since the meaning of such a construct is unclear, we don't consider this
1477 a loss. Similarly, juxtaposing two @code{\grace} sections is
1478 syntactically valid, but makes no sense and may cause runtime errors.
1479 Ending a staff or score with grace notes may also generate a run-time
1480 error, since there will be no main note to attach the grace notes to.
1491 @subsection Glissando
1494 @cindex @code{\glissando}
1496 A glissando line (grob @internalsref{Glissando}) can be requested by
1497 attaching a @code{\glissando} to a notte:
1499 @lilypond[fragment,relative,verbatim]
1505 Printing of an additional text (such as @emph{gliss.}) must be done
1512 @subsection Dynamics
1525 @cindex @code{\ffff}
1535 Absolute dynamic marks are specified using an identifier after a
1536 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1537 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1538 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1539 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1541 @lilypond[verbatim,singleline,fragment,relative]
1542 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1548 @cindex @code{\decr}
1549 @cindex @code{\rced}
1555 A crescendo mark is started with @code{\cr} and terminated with
1556 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1557 started with @code{\decr} and terminated with @code{\rced}. There are
1558 also shorthands for these marks. A crescendo can be started with
1559 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1560 can be terminated with @code{\!}. Note that @code{\!} must go before
1561 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1562 after the last note. Because these marks are bound to notes, if you
1563 want several marks during one note, you have to use spacer notes.
1565 @lilypond[fragment,verbatim,center]
1566 c'' \< \! c'' d'' \decr e'' \rced
1567 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1570 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1571 is an example how to do it:
1576 @lilypond[fragment,relative,verbatim]
1578 \property Voice.crescendoText = "cresc."
1579 \property Voice.crescendoSpanner = #'dashed-line
1584 For everyday use, we recommend the identifiers @code{\cresc},
1585 @code{endcresc}, @code{\dim} and @code{\enddim}.
1589 Dynamics are grobs of @internalsref{DynamicText} and
1590 @internalsref{Hairpin}. Vertical positioning of these symbols is handled
1591 by the @internalsref{DynamicLineSpanner} grob. If you want to adjust
1592 padding or vertical direction of the dynamics, you must set properties
1593 for the @internalsref{DynamicLineSpanner} grob. Predefined identifiers
1594 to set the vertical direction are \dynamicUp and \dynamicDown.
1596 @cindex direction, of dynamics
1597 @cindex @code{\dynamicDown}
1598 @cindex @code{\dynamicUp}
1606 @cindex @code{\repeat}
1608 To specify repeats, use the @code{\repeat} keyword. Since repeats
1609 should work differently when played or printed, there are a few
1610 different variants of repeats.
1614 Repeated music is fully written (played) out. Useful for MIDI
1615 output, and entering repetitive music.
1618 This is the normal notation: Repeats are not written out, but
1619 alternative endings (voltas) are printed, left to right.
1622 Alternative endings are written stacked. This has limited use but may be
1623 used to typeset two lines of lyrics in songs with repeats, see
1624 @file{input/star-spangled-banner.ly}.
1630 Make beat or measure repeats. These look like percent signs.
1636 * Manual repeat commands::
1638 * Tremolo subdivisions::
1643 @subsection Repeat syntax
1645 The syntax for repeats is
1648 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1651 If you have alternative endings, you may add
1652 @cindex @code{\alternative}
1654 \alternative @code{@{} @var{alternative1}
1656 @var{alternative3} @dots{} @code{@}}
1658 where each @var{alternative} is a music expression.
1660 Normal notation repeats are used like this:
1661 @lilypond[fragment,verbatim]
1663 \repeat volta 2 { c'4 d' e' f' }
1664 \repeat volta 2 { f' e' d' c' }
1667 With alternative endings:
1668 @lilypond[fragment,verbatim]
1670 \repeat volta 2 {c'4 d' e' f'}
1671 \alternative { {d'2 d'} {f' f} }
1674 Folded repeats look like this:
1677 @lilypond[fragment,verbatim]
1679 \repeat fold 2 {c'4 d' e' f'}
1680 \alternative { {d'2 d'} {f' f} }
1684 If you don't give enough alternatives for all of the repeats, then
1685 the first alternative is assumed to be repeated often enough to equal
1686 the specified number of repeats.
1688 @lilypond[fragment,verbatim]
1692 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1693 \alternative { { g4 g g } { a | a a a a | b2. } }
1698 @subsection Unfolding repeats for MIDI output.
1700 @cindex expanding repeats
1702 See @file{input/test/unfold-all-repeats.ly}.
1707 Notice that timing information is not remembered at the start of an
1708 alternative, so you have to reset timing information after a repeat,
1709 e.g. using a bar-check (See @ref{Bar check}), setting
1710 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1711 are also not repeated.
1713 It is possible to nest @code{\repeat}s, although this probably is only
1714 meaningful for unfolded repeats.
1716 Folded repeats offer little more over simultaneous music. However, it
1717 is to be expected that more functionality -- especially for the MIDI
1718 backend -- will be implemented at some point in the future.
1720 Volta repeats are printed over all staves in a score. You must turn them
1721 off explicitly, for example by doing
1723 \property Staff.VoltaBracket = \turnOff
1725 in all but the top staff.
1727 @node Manual repeat commands
1728 @subsection Manual repeat commands
1730 @cindex @code{repeatCommands}
1732 The property @code{repeatCommands} can be used to control the layout of
1733 repeats. Its value is a Scheme list of repeat commands, where each repeat
1741 @item (volta . @var{text})
1742 Print a volta bracket saying @var{text}.
1744 Stop a running volta bracket
1747 @lilypond[verbatim, fragment]
1749 \property Score.repeatCommands = #'((volta "93") end-repeat)
1751 \property Score.repeatCommands = #'((volta #f))
1756 Repeats brackets are @internalsref{VoltaBracket} grobs.
1758 @node Tremolo repeats
1759 @subsection Tremolo repeats
1760 @cindex tremolo beams
1762 To place tremolo marks between notes, use @code{\repeat} with tremolo
1764 @lilypond[verbatim,center,singleline]
1766 \context Voice \notes\relative c' {
1767 \repeat "tremolo" 8 { c16 d16 }
1768 \repeat "tremolo" 4 { c16 d16 }
1769 \repeat "tremolo" 2 { c16 d16 }
1770 \repeat "tremolo" 4 c16
1775 Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
1776 @internalsref{StemTremolo}.
1781 At present, the spacing between tremolo beams is not regular, since the
1782 spacing engine does not notice that not all notes are printed.
1784 @node Tremolo subdivisions
1785 @subsection Tremolo subdivisions
1786 @cindex tremolo marks
1787 @cindex @code{tremoloFlags}
1789 Tremolo marks can be printed on a single note by adding
1790 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1791 A @var{length} value of 8 gives one line across the note stem. If the
1792 length is omitted, then then the last value (stored in
1793 @code{Voice.tremoloFlags}) is used.
1795 @lilypond[verbatim,fragment,center]
1796 c'2:8 c':32 | c': c': |
1802 Tremolos in this style do not carry over into the MIDI output.
1805 @node Measure repeats
1806 @subsection Measure repeats
1808 @cindex percent repeats
1809 @cindex measure repeats
1811 In the @code{percent} style, a note pattern can be repeated. It is
1812 printed once, and then the pattern is replaced with a special sign.
1813 Patterns of a one and two measures are replaced by percent-like signs,
1814 patterns that divide the measure length are replaced by slashes.
1816 @lilypond[verbatim,singleline]
1817 \context Voice { \repeat "percent" 4 { c'4 }
1818 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1822 The signs are represented by these grobs: @internalsref{RepeatSlash} and
1823 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
1827 You can not nest percent repeats, e.g. by filling in the first measure
1828 with slashes, and repeating that measure with percents.
1830 @node Rhythmic music
1831 @section Rhythmic music
1838 @node Rhythmic staves
1839 @subsection Rhythmic staves
1841 Sometimes you might want to show only the rhythm of a melody. This can
1842 be done with the rhythmic staff. All pitches of notes on such a staff
1843 are squashed, and the staff itself looks has a single staff line:
1845 @lilypond[fragment,relative,verbatim]
1846 \context RhythmicStaff {
1848 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1855 @section Piano music
1857 Piano music is an odd type of notation. Piano staves are two normal
1858 staves coupled with a brace. The staves are largely independent, but
1859 sometimes voices can cross between the two staves. The
1860 @internalsref{PianoStaff} is especially built to handle this cross-staffing
1861 behavior. In this section we discuss the @internalsref{PianoStaff} and some
1862 other pianistic peculiarities.
1865 * Automatic staff changes::
1866 * Manual staff switches::
1869 * Voice follower lines::
1873 @c . {Automatic staff changes}
1874 @node Automatic staff changes
1875 @subsection Automatic staff changes
1876 @cindex Automatic staff changes
1878 Voices can switch automatically between the top and the bottom
1879 staff. The syntax for this is
1881 \autochange @var{contexttype} @var{musicexp}
1883 This will switch the interpretation context of @var{musicexp} between a
1884 @var{contexttype} named @code{up} and @code{down}. Typically, you use
1885 @internalsref{Staff} for @var{contexttype}. The autochanger switches on basis
1886 of pitch (central C is the turning point), and it looks ahead skipping
1887 over rests to switch rests in advance.
1889 @lilypond[verbatim,singleline]
1890 \score { \notes \context PianoStaff <
1891 \context Staff = "up" {
1892 \autochange Staff \context Voice = VA < \relative c' {
1893 g4 a b c d r4 a g } > }
1894 \context Staff = "down" {
1900 Note how spacer rests are used to prevent the bottom staff from
1901 terminating too soon.
1904 @node Manual staff switches
1905 @subsection Manual staff switches
1907 @cindex manual staff switches
1908 @cindex staff switch, manual
1910 Voices can be switched between staves manually, using the following command:
1912 \translator Staff = @var{staffname} @var{music}
1914 The string @var{staffname} is the name of the staff. It switches the
1915 current voice from its current staff to the Staff called
1916 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1919 The formal definition of this construct is obtuse, but for the sake of
1920 completeness we give it here.
1921 @cindex @code{\translator}
1923 \translator @var{contexttype} = @var{name}
1925 Formally, this construct is a music expression indicating
1926 that the context which is a direct child of the context of type
1927 @var{contexttype} should be shifted to a context of type
1928 @var{contexttype} and the specified name.
1936 Piano pedal instruction can be expressed using
1937 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
1938 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1940 These identifiers are shorthands for spanner commands of the types
1941 @internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
1943 @lilypond[fragment,verbatim]
1944 c''4 \spanrequest \start "Sustain" c''4
1945 c''4 \spanrequest \stop "Sustain"
1948 The symbols that are printed can be modified by setting
1949 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal
1950 types. Refer to the generated documentation of @rgrob{PianoPedal} for
1956 Currently, brackets are not supported, only text markings (i.e. `*Ped'
1962 @subsection Arpeggio
1965 @cindex broken arpeggio
1966 @cindex @code{\arpeggio}
1968 You can specify an arpeggio sign on a chord by attaching an
1969 @code{\arpeggio} to a note of the chord.
1972 @lilypond[fragment,relative,verbatim]
1973 \context Voice <c\arpeggio e g c>
1976 When an arpeggio crosses staves in piano music, you attach an arpeggio
1977 to the chords in both staves, and set
1978 @code{PianoStaff.connectArpeggios}.
1980 @lilypond[fragment,relative,verbatim]
1981 \context PianoStaff <
1982 \property PianoStaff.connectArpeggios = ##t
1983 \context Voice = one { <c'\arpeggio e g c> }
1984 \context Voice = other { \clef bass <c,,\arpeggio e g>}
1988 This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
1989 are @code{PianoStaff.Arpeggio}. @internalsref{Arpeggio}
1991 To add an arrow head to explicitly specify the direction of the
1992 arpeggio, you should set the arpeggio grob property
1993 @code{arpeggio-type}.
1995 @lilypond[fragment,relative,verbatim]
1997 \property Voice.Arpeggio \override #'arpeggio-direction = #1
1999 \property Voice.Arpeggio \override #'arpeggio-direction = #-1
2005 A square bracket on the left indicates that the player should not
2006 arpeggiate the chord.
2008 @lil ypond[fragment,relative,verbatim]
2009 \context PianoStaff <
2010 \property PianoStaff.connectArpeggios = ##t
2011 \property PianoStaff.Arpeggio \override #'arpeggio-direction = #'bracket
2012 \context Voice = one { <c'\arpeggio e g c> }
2013 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2021 It is not possible to mix connected arpeggios and unconnected arpeggios
2026 @node Voice follower lines
2027 @subsection Voice follower lines
2029 @cindex follow voice
2030 @cindex staff switching
2033 @cindex @code{followVoice}
2035 Whenever a voice switches to another staff a line connecting the notes
2036 can be printed automatically. This is enabled if the property
2037 @code{PianoStaff.followVoice} is set to true:
2039 @lilypond[fragment,relative,verbatim]
2040 \context PianoStaff <
2041 \property PianoStaff.followVoice = ##t
2042 \context Staff \context Voice {
2044 \translator Staff=two
2047 \context Staff=two {\clef bass \skip 1*2 }
2051 The associated grob is @internalsref{VoiceFollower}.
2061 * Automatic syllable durations::
2067 @subsection Lyrics mode
2070 To print lyrics, you must first make a music expression from the lyric
2071 text. That music expression can be printed by selecting an appropriate
2075 @cindex @code{\lyrics}
2077 You can enter lyrics in a special input mode of LilyPond. This mode is
2078 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
2079 The purpose of this mode is that you can enter lyrics as plain text,
2080 punctuation and accents without any hassle.
2082 Syllables are entered like notes, with pitches replaced by text. For
2083 example, @code{Twin- kle twin- kle} enters four syllables. Note that
2084 the hyphen has no special meaning for lyrics, and does not introduce
2087 Spaces can be introduced into a lyric either by using quotes:
2088 @code{"He could"4 not4} or by using an underscore without quotes:
2089 @code{He_could4 not4}. All unquoted underscores are converted to
2092 The precise definition of this mode can be found in @ref{Lyrics mode
2095 @c . {Printing lyrics}
2096 @node Printing lyrics
2097 @subsection Printing lyrics
2100 Lyrics are printed by interpreting them in the @internalsref{Lyrics} context.
2102 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
2103 @c Add tied and beamed melismata too.
2104 @lilypond[verbatim,singleline]
2106 \notes \relative c' {
2108 \property Staff.automaticMelismata = ##t
2109 d'2 c4 b16 ( a g a b a b ) c a2
2110 b2 c4 b8 ( a16 g ) a4 g2 }
2111 \context Lyrics \lyrics {
2113 share the soft -- ware; }
2117 Notes and syllable durations are matched automatically. This is
2118 accomplished using @code{\addlyrics}, which is documented in
2119 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
2120 the melody staff will cause tied, slurred or beamed notes to be
2121 interpreted as melismata.
2123 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
2126 @cindex lyric extender
2129 As you can see, extender lines are entered as @code{__}. This will
2130 create an extender, a line that extends over the entire duration of the
2131 lyric. This line will run all the way to the start of the next lyric,
2132 so you may want to shorten it by using a blank lyric (using @code{_}).
2133 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2138 If you want to have hyphens centered between syllables (rather than
2139 attached to the end of the first syllable) you can use the special
2140 `@code{-}@code{-}' lyric as a separate word between syllables. This
2141 will result in a hyphen whose length varies depending on the space
2142 between syllables. It will be centered between the syllables. The grob
2143 for this symbol is @code{LyricsVoice.LyricHyphen}.
2145 @cindex Lyric hyphen
2147 @node Automatic syllable durations
2148 @subsection Automatic syllable durations
2149 @cindex Automatic syllable durations
2151 @cindex automatic lyric durations
2152 @cindex @code{\addlyrics}
2154 If you have lyrics that are set to a melody, you can copy the rhythm
2155 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2158 \addlyrics @var{musicexpr1 musicexpr2}
2161 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2162 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2163 when there are events in @var{musicexpr1}.
2165 @cindex @code{automaticMelismata}
2167 If the property @code{automaticMelismata} is set in the
2168 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2171 @lilypond[verbatim,fragment]
2174 \property Voice.automaticMelismata = ##t
2175 c8 () cis d8. e16 f2
2177 \context Lyrics \lyrics {
2181 If you want the lyric lines to be above the melody staff, or in some
2182 other, more complex configuration, then build that configuration first
2183 using simultaneous music, and use @code{\addlyrics} after that.
2185 @lilypond[verbatim, singleline]
2187 \context Lyrics = LA { s1 }
2188 \context Staff = SA { s1 }
2190 \context Staff = SA \relative c' { c4 e g g }
2191 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2194 For @code{\addlyrics} you should use a single rhythm melody, and single
2195 rhythm lyrics (a constant duration is the obvious choice). If you do
2196 not, you can get undesired effects when using multiple stanzas:
2198 @lilypond[verbatim,fragment]
2201 c8 () cis d8. e16 f2
2203 \context Lyrics \lyrics
2208 It is valid (but probably not very useful) to use notes instead of
2209 lyrics for @var{musicexpr2}.
2212 @subsection More stanzas
2216 If you have multiple stanzas printed underneath each other, the vertical
2217 groups of syllables should be aligned around punctuation. LilyPond can
2218 do this if you tell it which lyric lines belong to which melody.
2220 To this end, give the Voice context an identity, and set the LyricsVoice
2221 to a name starting with that identity followed by a dash.
2222 In the following example, the Voice
2223 identity is @code{duet}, and the identities of the LyricsVoices are
2224 @code{duet-1} and @code{duet-2}.
2227 @lilypond[singleline,verbatim]
2230 \notes \relative c'' \context Voice = duet { \time 3/4
2232 \lyrics \context Lyrics <
2233 \context LyricsVoice = "duet-1" {
2234 \property LyricsVoice . stanza = "Bert"
2235 Hi, my name is bert. }
2236 \context LyricsVoice = "duet-2" {
2237 \property LyricsVoice . stanza = "Ernie"
2238 Ooooo, ch\'e -- ri, je t'aime. }
2243 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2244 first system) and @code{LyricsVoice.stz} for the following
2245 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2251 @cindex stanza numbering
2259 LilyPond has support for both entering and printing chords. Chords are
2260 characterized by a set of pitches. They are
2261 internally stored as simultaneous music expressions. This means you can
2262 enter chords by name and print them as note head, enter them as notes
2263 and print them as chord names, or (the most common case) enter them by
2264 name, and print them as name.
2267 @lilypond[verbatim,singleline]
2268 twoWays = \notes \transpose c'' {
2278 < \context ChordNames \twoWays
2279 \context Voice \twoWays > }
2282 Note that this example also shows that the chord printing routines do
2283 not attempt to be intelligent. If you enter @code{f bes d}, it does not
2284 interpret this as an inversion.
2288 * Printing named chords::
2293 @subsection Chords mode
2296 Chord mode is a mode where you can input sets of pitches using common
2297 names. It is introduced by the keyword @code{\chords}. It is similar
2298 to note mode, but words are also looked up in a chord modifier table
2299 (containing @code{maj}, @code{dim}, etc).
2301 Dashes and carets are used to indicate chord additions and subtractions,
2302 so articulation scripts can not be entered in Chord mode.
2304 The syntax for named chords is as follows:
2306 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2309 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2310 the chord duration in the usual notation. There are two kinds of
2311 modifiers. One type is formed by @emph{chord additions}. Additions are
2312 obtained by listing intervals separated by dots. An interval is written
2313 by its number with an optional @code{+} or @code{-} to indicate raising
2314 or lowering by half a step. Chord additions have two effects: they adds
2315 the specified interval and all lower odd numbered intervals to the
2316 chord, and they may lower or raise the specified interval.
2318 Throughout these examples, chords have been shifted around the staff
2319 using @code{\transpose}.
2321 @lilypond[fragment,verbatim]
2325 c:9 c:9-.5+.7+ c:3-.5-
2335 The second type of modifier that may appear after the @code{:} is a
2336 named modifier. Named modifiers are listed in the file
2337 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2338 @code{min} which lower the 3rd half a step, `@code{aug}' which
2339 raises the 5th, `@code{dim}' which lowers the 5th,
2340 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2341 which replaces the 5th with a 4th.
2343 @lilypond[fragment,verbatim]
2346 c1:m c:min7 c:maj c:aug c:dim c:sus
2352 Chord subtractions are used to eliminate notes from a chord. The
2353 notes to be subtracted are listed after a @code{^} character,
2356 @lilypond[fragment,verbatim,center]
2365 Chord inversions can be specified by appending `@code{/}' and the name
2366 of a single note to a chord. In a chord inversion, the inverted note is
2367 transposed down until it is the lowest note in the chord. If the note
2368 is not in the chord, a warning will be printed.
2370 @lilypond[fragment,verbatim,center]
2380 Bass notes can be added by `@code{/+}' and
2381 the name of a single note to a chord. This has the effect of
2382 adding the specified note to the chord, lowered by an octave,
2383 so it becomes the lowest note in the chord.
2385 @lilypond[fragment,verbatim,center]
2396 Implementation details are quite gory. For example @code{c:4} not only
2397 adds a fourth, but also removes the third.
2400 @c . {Printing named chords}
2401 @node Printing named chords
2402 @subsection Printing named chords
2404 @cindex printing chord names
2408 For displaying printed chord names, use the @internalsref{ChordNames} context.
2409 The chords may be entered either using the notation described above, or
2410 directly using simultaneous music.
2412 @lilypond[verbatim,singleline]
2414 \chords {a1 b c} <d f g> <e g b>
2418 \context ChordNames \scheme
2419 \context Staff \transpose c'' \scheme
2424 You can make the chord changes stand out by setting
2425 @code{ChordNames.chordChanges} to true. This will only display chord
2426 names when there's a change in the chords scheme and at the start of a
2431 c1:m c:m \break c:m c:m d
2435 \context ChordNames {
2436 \property ChordNames.chordChanges = ##t
2438 \context Staff \transpose c'' \scheme
2442 LilyPond examines chords specified as lists of notes to determine a name
2443 to give the chord. LilyPond will not try to identify chord inversions or
2444 an added bass note, which may result in strange chord names when chords
2445 are entered as a list of pitches:
2447 @lilypond[verbatim,center,singleline]
2456 \context ChordNames \scheme
2457 \context Staff \scheme
2463 By default, a chord name system proposed by Harald Banter (See
2464 @ref{Literature}) is used. The system is very regular and predictable.
2465 Typical American style chord names may be selected by setting the
2466 @code{style} property of the @code{ChordNames.ChordName} grob to
2467 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2469 Routines that determine the names to be printed are written in Scheme,
2470 and may be customized by the user. The code can be found in
2471 @file{scm/chord-name.scm}. Here's an example showing the differences in
2475 @c maybe just junk verbatim option?
2476 @lilypond[verbatim,singleline]
2486 \context ChordNames = banter \scheme
2487 \context ChordNames = american {
2488 \property ChordNames.ChordName \override
2489 #'style = #'american \scheme }
2490 \context ChordNames = jazz {
2491 \property ChordNames.ChordName \override
2492 #'style = #'jazz \scheme }
2493 \context Staff \transpose c'' \scheme
2500 @section Writing parts
2502 Orchestral music involves some special notation, both in the full score,
2503 as in the individual parts. This section explains how to tackle common
2504 problems in orchestral music.
2511 * Instrument names::
2513 * Sound output for transposing instruments::
2514 * Multi measure rests::
2515 * Automatic part combining::
2516 * Hara kiri staves::
2519 @c . {Rehearsal marks}
2520 @node Rehearsal marks
2521 @subsection Rehearsal marks
2522 @cindex Rehearsal marks
2524 @cindex @code{\mark}
2528 \mark @var{unsigned}
2533 This command prints a rehearsal mark above the system. You can provide
2534 a number, a string or a markup text as argument. If you use
2535 @code{\default}, the value of property @code{rehearsalMark} is used and
2536 automatically incremented.
2538 @lilypond[fragment,verbatim]
2544 c1 \mark #'(music "scripts-segno")
2549 The grob is @internalsref{RehearsalMark} in @internalsref{Score} context. See
2550 @code{input/test/boxed-molecule.ly} if you need boxes around the marks.
2553 @subsection Bar numbers
2557 @cindex measure numbers
2558 @cindex currentBarNumber
2560 Bar numbers are @internalsref{BarNumber} grobs. They are printed at the
2561 start of the line. The number itself is a property that can be set by
2562 modifying the @code{currentBarNumber} property, i.e.
2564 \property Score.currentBarNumber = #217
2567 If you want boxed bar numbers, see the example file
2568 @code{input/test/boxed-molecule.ly}.
2572 It is not possible to have bar numbers printed at regular intervals
2575 @node Instrument names
2576 @subsection Instrument names
2578 You can specify an instrument name for a staff by setting
2579 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2580 before the start of the staff. For the first start, @code{instrument} is
2581 used, for the next ones @code{instr} is used.
2583 @lilypond[verbatim,singleline]
2584 \property Staff.instrument = "ploink " { c''4 }
2587 You can also use markup texts to construct more complicated instrument
2591 @lilypond[verbatim,singleline]
2593 '((font-relative-size . -2 ) (music "accidentals--1")))
2596 \property Staff.instrument = #`((kern . 0.5) (lines
2597 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2605 When you put a name on a grand staff or piano staff the width of the
2606 brace is not taken into account. You must add extra spaces to the end of
2607 the name to avoid a collision.
2610 @subsection Transpose
2612 @cindex transposition of pitches
2613 @cindex @code{\transpose}
2615 A music expression can be transposed with @code{\transpose}. The syntax
2618 \transpose @var{pitch} @var{musicexpr}
2621 This means that middle C in @var{musicexpr} is transposed to
2624 @code{\transpose} distinguishes between enharmonic pitches: both
2625 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2626 a tone. The first version will print sharps and the second version
2629 @lilypond[fragment,verbatim]
2632 { \key e \major c d e f }
2634 \transpose des'' { \key e \major c d e f }
2635 \transpose cis'' { \key e \major c d e f }
2639 If you want to use both @code{\transpose} and @code{\relative}, then
2640 you must use @code{\transpose} first. @code{\relative} will have no
2641 effect music that appears inside a @code{\transpose}.
2643 @node Sound output for transposing instruments
2644 @subsection Sound output transposing instruments
2646 When you want to make a MIDI file from a score containing transposed and
2648 instruments, you have to instruct LilyPond the pitch offset (in
2649 semitones) for the transposed instruments. This is done using the
2650 @code{transposing} property. It does not affect printed output.
2652 @cindex @code{transposing}
2655 \property Staff.instrument = #"Cl. in B-flat"
2656 \property Staff.transposing = #-2
2659 @c . {Multi measure rests}
2660 @node Multi measure rests
2661 @subsection Multi measure rests
2662 @cindex Multi measure rests
2666 Multi measure rests are entered using `@code{R}'. It is specifically
2667 meant for full bar rests and for entering parts: the rest can expand to
2669 rests, or it can be printed as a single multimeasure rest This expansion
2670 is controlled by the property @code{Score.skipBars}. If this is set to true,
2671 Lily will not expand empty measures, and the appropriate number is added
2674 @lilypond[fragment,verbatim]
2675 \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2678 Notice that the @code{R2.} is printed as a whole rest, centered in the
2681 @cindex whole rests for a full measure
2683 The grob for this object is @internalsref{MultiMeasureRest}.
2687 Currently, there is no way to automatically condense multiple rests into
2688 a single multimeasure rest.
2690 @cindex condensing rests
2692 @node Automatic part combining
2693 @subsection Automatic part combining
2694 @cindex automatic part combining
2695 @cindex part combiner
2698 Automatic part combining is used to merge two parts of music onto a
2699 staff in an intelligent way. It is aimed primarily at typesetting
2700 orchestral scores. When the two parts are identical for a period of
2701 time, only one is shown. In places where the two parts differ, they are
2702 typeset as separate voices, and stem directions are set automatically.
2703 Also, solo and @emph{a due} parts can be identified and marked.
2705 The syntax for part combining is
2708 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2710 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2711 combined into one context of type @var{context}. The music expressions
2712 must be interpreted by contexts whose names should start with @code{one}
2715 The most useful function of the part combiner is to combine parts into
2716 one voice, as common for wind parts in orchestral scores:
2718 @lilypond[verbatim,singleline,fragment]
2720 \context Voice=one \partcombine Voice
2721 \context Thread=one \relative c'' {
2724 \context Thread=two \relative c'' {
2730 Notice that the first @code{g} appears only once, although it was
2731 specified twice (once in each part). Stem, slur and tie directions are
2732 set automatically, depending whether there is a solo or unisono. The
2733 first part (with context called @code{one}) always gets up stems, and
2734 `solo', while the second (called @code{two}) always gets down stems and
2737 If you just want the merging parts, and not the textual markings, you
2738 may set the property @var{soloADue} to false.
2740 @lilypond[verbatim,singleline,fragment]
2742 \property Staff.soloADue = ##f
2743 \context Voice=one \partcombine Voice
2744 \context Thread=one \relative c'' {
2747 \context Thread=two \relative c'' {
2753 There are a number of other properties that you can use to tweak the
2754 behavior of part combining, refer to the automatically generated
2755 documentation of @reng{Thread_devnull_engraver} and
2756 @reng{Voice_devnull_engraver}. Look at the documentation of the
2757 responsible engravers, @code{Thread_devnull_engraver},
2758 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2762 In @code{soloADue} mode, when the two voices play the same notes on and
2763 off, the part combiner may typeset @code{a2} more than once in a
2766 @lilypond[fragment,singleline]
2768 \context Voice=one \partcombine Voice
2769 \context Thread=one \relative c'' {
2772 \context Thread=two \relative c'' {
2778 @cindex @code{Thread_devnull_engraver}
2779 @cindex @code{Voice_engraver}
2780 @cindex @code{A2_engraver}
2782 @node Hara kiri staves
2783 @subsection Hara kiri staves
2785 In orchestral scores, staff lines that only have rests are usually removed.
2786 This saves some space. LilyPond also supports this through the hara
2787 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2788 the Japanese Samourai warriors.} staff. This staff commits suicide when
2789 it finds itself to be empty after the line-breaking process. It will
2790 not disappear when it contains normal rests, you must use multi measure
2793 The hara kiri staff is specialized version of the @internalsref{Staff}
2794 context. It is available as the context identifier
2795 @code{\HaraKiriStaffContext}. Observe how the second staff in this
2796 example disappears in the second line.
2800 \notes \relative c' <
2801 \context Staff = SA { e4 f g a \break c1 }
2802 \context Staff = SB { c4 d e f \break R1 }
2806 \translator { \HaraKiriStaffContext }
2819 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
2820 staff context symbol that appears at the end of a staff line. It
2821 anticipates the pitch of the first note(s) of the following line and
2822 thus helps the player or singer to manage line breaks during
2823 performance, thus enhancing readability of a score.
2828 \property Staff.Custos \set #'style = #'mensural
2833 \consists Custos_engraver
2839 Custodes were frequently used in music notation until the 17th century.
2840 There were different appearances for different notation styles.
2841 Nowadays, they have survived only in special forms of musical notation
2842 such as via the @emph{editio vaticana} dating back to the beginning of
2845 For typesetting custodes, just put a @code{Custos_engraver} into the
2846 @internalsref{Staff} context when declaring the @code{\paper} block. In this
2847 block, you can also globally control the appearance of the custos symbol
2848 by setting the custos @code{style} property. Currently supported styles
2849 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2856 \consists Custos_engraver
2857 Custos \override #'style = #'mensural
2862 The property can also be set locally, for example in a @code{\notes}
2867 \property Staff.Custos \override #'style = #'vaticana
2868 c'1 d' e' d' \break c' d' e' d'
2875 @section Figured bass
2877 @cindex Basso continuo
2879 TODO. see figured-bass.ly
2881 @c . {Tuning output}
2883 @section Tuning output
2885 LilyPond tries to take as much formatting as possible out of your
2886 hands. Nevertheless, there are situations where it needs some help, or
2887 where you want to override its decisions. In this section we discuss
2888 ways to do just that.
2890 Formatting is internally done by manipulating so called grobs (graphic
2891 objects). Each grob carries with it a set of properties (grob
2892 properties) specific to that object. For example, a stem grob has
2893 properties that specify its direction, length and thickness.
2895 The most direct way of tuning the output is by altering the values of
2896 these properties. There are two ways of doing that: first, you can
2897 temporarily change the definition of a certain type of grob, thus
2898 affecting a whole set of objects. Second, you can select one specific
2899 object, and set a grob property in that object.
2902 * Tuning groups of grobs ::
2903 * Tuning per grob ::
2911 @node Tuning groups of grobs
2912 @subsection Tuning groups of grobs
2914 @cindex grob description
2918 A grob definition is a Scheme association list, that is stored in a
2919 context property. By assigning to that property (using plain
2920 @code{\property}), you can change the resulting grobs.
2922 @lilypond[verbatim, fragment]
2923 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
2926 The @code{\property} assignment effectively empties the definition of
2927 the Stem object. One of the effects is that the recipe of how it should be
2928 printed is erased, with the effect of rendering it invisible. The above
2929 assignment is available as a standard identifier, for the case that you
2933 \property Voice.Stem = \turnOff
2940 This mechanism is fairly crude, since you can only set, but not modify,
2941 the definition of a grob. For this reason, there is a more advanced
2944 The definition of a grob is actually a list of default grob
2945 properties. For example, the definition of the Stem grob (available in
2946 @file{scm/grob-description.scm}), defines the following values for
2951 (beamed-lengths . (0.0 2.5 2.0 1.5))
2952 (Y-extent-callback . ,Stem::height)
2956 You can add a property on top of the existing definition, or remove a
2957 property, thus overriding the system defaults:
2959 c'4 \property Voice.Stem \override #'thickness = #4.0
2960 c'4 \property Voice.Stem \revert #'thickness
2963 You should balance @code{\override} and @code{\revert}. If that's too
2964 much work, you can use the @code{\set} shorthand. It performs a revert
2965 followed by an override. The following example gives exactly the same
2966 result as the previous one.
2968 c'4 \property Voice.Stem \set #'thickness = #4.0
2969 c'4 \property Voice.Stem \set #'thickness = #0.8
2972 If you use @code{\set}, you must explicitly restore the default.
2975 Formally the syntax for these constructions is
2977 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
2978 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
2979 \property @var{context}.@var{grobname} \revert @var{symbol}
2981 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
2982 and @var{grobname} are strings and @var{value} is a Scheme expression.
2985 If you revert a setting which was not set in the first place, then it
2986 has no effect. However, if the setting was set as a system default, it
2987 may remove the default value, and this may give surprising results,
2988 including crashes. In other words, @code{\override} and @code{\revert},
2989 must be carefully balanced.
2991 These are examples of correct nesting of @code{\override}, @code{\set},
2994 A clumsy but correct form:
2996 \override \revert \override \revert \override \revert
2999 Shorter version of the same:
3001 \override \set \set \revert
3004 A short form, using only @code{\set}. This requires you to know the
3007 \set \set \set \set @var{to default value}
3010 If there is no default (i.e. by default, the grob property is unset),
3013 \set \set \set \revert
3016 For the digirati, the grob description is an Scheme association
3017 list. Since a Scheme list is a singly linked list, we can treat it as a
3018 stack, and @code{\override} and @code{\revert} are just push and pop
3019 operations. This pushing and popping is also used for overriding
3020 automatic beaming settings.
3024 LilyPond will hang or crash if @var{value} contains cyclic references.
3025 The backend is not very strict in type-checking grob properties. If you
3026 @code{\revert} properties that are expected to be set by default,
3029 Some grobs are created at the moment that their context is created. An
3030 example of such a grob is the staff itself (i.e. the horizontal lines).
3031 You can not change the appearance of the staff symbol by manipulating
3032 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3033 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3034 created before any @code{\override} is effective. You can deal with this
3035 either overriding properties in a @code{\translator} definition, or by
3036 using @code{\outputproperty}.
3041 @node Tuning per grob
3042 @subsection Tuning per grob
3044 @cindex \outputproperty
3046 A second way of tuning grobs is the more arcane @code{\outputproperty}
3047 feature. The syntax is as follows:
3049 \outputproperty @var{predicate} @var{symbol} = @var{value}
3051 Here @code{predicate} is a Scheme function taking a grob argument, and
3052 returning a boolean. This statement is processed by the
3053 @code{Output_property_engraver}. It instructs the engraver to feed all
3054 grobs that it sees to @var{predicate}. Whenever the predicate returns
3055 true, the grob property @var{symbol} will be set to @var{value}.
3057 You will need to combine this statement with @code{\context} to select
3058 the appropriate context to apply this to.
3060 Here are some random examples.
3063 In the following example, all note heads occurring at current staff
3064 level, are shifted up and right by setting their @code{extra-offset}
3067 @lilypond[fragment,verbatim,singleline]
3069 \context Staff \outputproperty
3070 #(make-type-checker 'note-head-interface)
3071 #'extra-offset = #'(0.5 . 0.75)
3075 @cindex @code{extra-offset}
3077 In this example, the predicate checks the @code{text} grob property, to
3078 shift only the `m.d.' text, but not the fingering instruction "2".
3079 @lilypond[verbatim,singleline]
3080 #(define (make-text-checker text)
3081 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3084 \notes\relative c''' {
3085 \property Voice.Stem \set #'direction = #1
3086 \outputproperty #(make-text-checker "m.d.")
3087 #'extra-offset = #'(-3.5 . -4.5)
3095 If possible, avoid this feature: the semantics are not very clean, and
3096 the syntax and semantics are up for rewrite.
3102 @subsection What to tune?
3104 This all tells you how to tune grobs, but you don't know what variables
3105 to set? The question is not answered in this part of the manual
3106 (although you may encounter some examples.).
3108 Grob properties are tied directly to the implementation of LilyPond, and
3109 they are thus a moving target. Documentation of such variables is in the
3110 automatically generated documentation. Description of properties are
3111 generated from the source code for each version. This documentation is
3112 therefore more up to date. It should be available from the same place
3113 where you got this manual.
3115 To decide how to tune a grob, you need to find the following information
3118 which grob to modify
3120 which property to modify
3122 which context the grob comes from.
3125 Included with the automatically generated documentation is a master list
3126 of grobs. Selecting a grob will take you to an overview of the
3127 properties available for that grob.
3129 There is also a master list of contexts. Selecting one takes you to an
3130 overview of that context which lists which grob types are created there.
3133 @node Font selection
3134 @subsection Font selection
3136 Most graphics in LilyPond are composed of characters of fonts. You can
3137 alter the characteristics of the font by setting certain grob
3138 properties. The mechanism that is used for this resembles La@TeX{}'s New
3139 Font Selection Scheme. Within this scheme, a font is entirely
3140 characterized by its font name.
3142 For each grob that uses fonts (in other words, each grob that supports
3143 @code{font-interface}) a font-name must be selected before it can be
3144 printed. The font name is selected by looking at a number of grob
3149 A symbol indicating the general class of the typeface. Supported are
3150 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3151 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3152 signs) and @code{typewriter}
3155 A symbol indicating the shape of the font, there are typically several
3156 font shapes available for each font family. Choices are @code{italic},
3157 @code{caps} and @code{upright}
3160 A symbol indicating the series of the font. There are typically several
3161 font series for each font family and shape. Choices are @code{medium}
3164 @item font-relative-size
3165 A number indicating the size relative the standard size. For example,
3166 with 20pt staff height, relative size -1 corresponds to 16pt staff
3167 height, and relative size +1 corresponds to 23 pt staff height.
3169 @item font-design-size
3170 A number indicating the design size of the font.
3172 This is a feature of the Computer Modern Font: each point size has a
3173 slightly different design. Smaller design sizes are relatively wider,
3174 which enhances readability. Scalable type faces such TrueType and Adobe
3175 Type1 usually come as ``one design fits all sizes''.
3178 The name of the font, without the design size, e.g. @code{cmr},
3179 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3186 The font is selected by taking the first font that satisfies all
3187 qualifiers specified. You can override any of these fields through
3188 @code{\override} and @code{\revert}. The special value @code{*} matches
3189 any value for that qualifier.
3192 \property Lyrics.LyricText \override #'font-series = #'bold
3193 \property Lyrics.LyricText \override #'font-shape = #'*
3196 @cindex @code{font-style}
3198 There are also pre-cooked font selection qualifiers. These are selected
3199 through the grob property @code{font-style}. For example, the style
3200 @code{finger} selects family @code{number} and relative size @code{-3}.
3201 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3202 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3205 The style sheets and tables for selecting fonts are located in
3206 @file{scm/font.scm}. Refer to this file for more information.
3209 Setting @code{font-name} overrides all other qualifiers. The value for
3210 this property should be a string, the file name of the font. You may use
3211 this to use special fonts, which are not a part of the style sheet, or
3212 which have special encodings.
3214 The size of the font may be set with the grob property
3215 @code{font-magnification}. It is the size of font, relative to its
3216 standard size. For example, @code{1.0} is normal size.
3220 Relative size is not linked to any real size.
3222 There is no style sheet provided for other fonts besides the @TeX{}
3225 @cindex font selection
3226 @cindex font magnification
3227 @cindex @code{font-interface}
3231 @subsection Text markup
3235 LilyPond has an internal mechanism to typeset texts. You can
3236 form text markup expressions by composing scheme expressions
3237 in the following way.
3239 @lilypond[verbatim, singleline]
3244 c^#'(italic "italic")
3245 d_#'((bold italic) "ff")
3247 f_#'(lines "one" (bold "two"))
3248 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3252 Normally, the Scheme markup text is stored in the @code{text} property
3253 of a grob. Formally, it is defined as follows:
3256 text: string | (head? text+)
3257 head: markup | (markup+)
3258 markup-item: property | abbrev
3259 property: (@var{key} . @var{value})
3260 abbrev: @code{columns lines roman music bold italic named super sub}
3261 @code{overstrike text finger volta timesig mmrest mark script}
3262 @code{large Large dynamic}
3265 The markup is broken down and converted into a list of grob properties,
3266 which are prepended to the property list. The @var{key}-@var{value}
3267 pair is a grob property. A list of properties available is included in
3268 the generated documentation for @rint{Text_interface}.
3270 The following abbreviations are currently defined:
3273 horizontal mode: set all text on one line (default)
3275 vertical mode: set every text on a new line
3279 selects the Feta font (the standard font for music notation glyphs),
3280 and uses named lookup
3287 lookup by character name
3289 plain text lookup (by character value)
3295 the next text or character overstrikes this one
3297 select fingering number fontstyle
3299 select volta number fontstyle
3301 select time signature number fontstyle
3303 select multi measure rest number fontstyle
3305 select mark number fontstyle
3307 select scriptsize roman fontstyle
3309 select large roman fontstyle
3311 select Large roman fontstyle
3313 select dynamics fontstyle
3317 @cindex metronome mark
3319 One practical application of complicated markup is to fake a metronome
3323 #(define note '(columns
3324 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3325 #(define eight-note `(columns ,note ((kern . -0.1)
3326 (music ((raise . 3.5) "flags-u3")))))
3327 #(define dotted-eight-note
3328 `(columns ,eight-note (music "dots-dot")))
3331 \notes\relative c'' {
3332 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3338 TextScript \override #'font-shape = #'upright
3344 @node Invisible grobs
3345 @subsection Invisible grobs
3346 @cindex invisible grobs
3350 ben nog steeds niet kapot van de informatiedichtheid hier.
3356 You can imagine a number of situations where you would want to make
3357 certain grobs not show up in the output. There may be aesthetic
3358 reasons, to make the output resemble an (old) manuscript as close as
3359 possible, or to make lessons or exercises for students.
3361 Grobs can be made invisible in a number of ways:
3363 Here's an example with blanked-out notes and stems:
3364 @lilypond[singleline,verbatim]
3366 \property Voice.NoteHead \override
3368 \property Voice.Stem \override
3369 #'transparent = ##t }
3372 \property Voice.NoteHead \revert #'transparent
3373 \property Voice.Stem \revert #'transparent }
3376 \notes\relative c'' {
3378 a b c b \blanknotes c \unblanknotes d
3382 This method makes the grobs invisible but they still take the normal space.
3383 To remove all traces of the grob, you can redefine the function
3387 \notes\relative c'' {
3390 as bes c bes c d \break
3391 \property Staff.KeySignature \override #'molecule-callback = #'()
3394 \paper{linewidth=5.0\cm indent=0}
3398 A very rigorous way of removing grobs from the whole score is to remove
3399 the engraver that creates them. For example,
3401 @lilypond[singleline,verbatim]
3402 \score {\notes { c'4 d'8 e'8 g2 }
3403 \paper { \translator {
3405 \remove Stem_engraver
3411 @subsection Dirty tricks
3412 @cindex embedded tex
3414 It is possible to use @TeX{} commands in the strings, but this should be
3415 avoided because it makes it impossible for LilyPond to compute the
3416 exact length of the string, which may lead to collisions. Also, @TeX{}
3417 commands won't work with direct PostScript output (see @ref{PostScript
3420 @lilypond[fragment,relative,verbatim]
3421 a'^"3 $\\times$ \\`a deux"
3424 You can also use raw PostScript commands embedded in text scripts. This
3425 offers ultimate flexibility, but requires you to learn PostScript.
3426 Currently, embedded PostScript will @strong{not} work with direct
3427 PostScript output. Note that all dimensions that you use are in staff
3432 \notes \relative c'' {
3433 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3434 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3435 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3439 \paper { linewidth = 70*\staffspace }
3446 @section Page layout
3449 The page layout is the combined product of LilyPond formatting notation,
3450 and (La)@TeX{} putting the notation on a page, including page breaks.
3451 The part of LilyPond is documented here.
3465 @subsection Paper block
3468 The most important output definition is the @code{\paper} block, for
3469 music notation. The syntax is
3472 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3475 where each of the items is one of
3478 @item An assignment.
3480 @item A context definition. See @ref{Interpretation context} for
3481 more information on context definitions.
3483 @item \stylesheet declaration. Its syntax is
3485 \stylesheet @var{alist}
3488 See @file{scm/font.scm} for details of @var{alist}.
3489 @item an @code{\elementdescriptions} declaration.
3491 \elementdescriptions @var{alist}
3493 See @file{scm/grob-description.scm} for details of
3494 @var{alist}. This command is not user-serviceable.
3498 @c . {Paper variables}
3499 @node Paper variables
3500 @subsection Paper variables
3501 @cindex Paper variables
3503 The paper block has some variables you may want to use or change:
3506 @cindex @code{indent}
3508 The indentation of the first line of music.
3509 @cindex @code{staffspace}
3511 @item @code{staffspace}
3512 The distance between two staff lines, calculated from the center
3515 @cindex @code{linewidth}
3516 @item @code{linewidth}
3517 Sets the width of the lines.
3519 If set to a negative value, a single unjustified line is produced.
3520 @c rename to singleLinePaper ?
3521 The shorthand @code{\singleLine} defines a default paper block that
3522 produces a single line.
3524 @cindex @code{textheight}
3526 @item @code{textheight}
3527 Sets the total height of the music on each page. Only used by
3530 @cindex @code{interscoreline}
3532 @item @code{interscoreline}
3533 Sets the spacing between systems. The default is 16pt.
3535 @cindex @code{interscorelinefill}
3537 @item @code{interscorelinefill}
3538 If set to a positive number, the distance between the score
3539 lines will stretch in order to fill the full page. In that
3540 case @code{interscoreline} specifies the minimum spacing.
3545 @cindex @code{stafflinethickness}
3547 @item @code{stafflinethickness}
3548 Determines the thickness of staff lines, and also acts as a scaling
3549 parameter for other line thicknesses.
3552 You may enter these dimension using units (@code{cm}, @code{in},
3553 @code{mm}, @code{pt}), or relative to another dimension
3555 linewidth = 20.0 * \staffspace
3562 @subsection Font size
3565 The Feta font provides musical symbols at six different sizes. These
3566 fonts are 11 point, 13 point, 16 point, 20 point,
3567 23 point, and 26 point. The point size of a font is the
3568 height of the five lines in a staff when displayed in the font.
3570 Definitions for these sizes are the files @file{paperSZ.ly}, where
3571 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3572 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3573 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3574 @code{paperTwentysix} are defined respectively. The default
3575 @code{\paper} block is also set.
3577 The font definitions are generated using a Scheme function. For more
3578 details, see the file @file{scm/font.scm}.
3584 @subsection Paper size
3589 @cindex @code{papersize}
3591 To change the paper size, you must first set the
3592 @code{papersize} paper variable variable. Set it to
3593 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3594 specification, you must set the font as described above. If you want
3595 the default font, then use the 20 point font.
3598 \paper@{ papersize = "a4" @}
3599 \include "paper16.ly"
3602 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3603 will set the paper variables @code{hsize} and @code{vsize} (used by
3604 Lilypond and @code{ly2dvi})
3608 @subsection Line break
3611 @cindex breaking lines
3613 Line breaks are normally computed automatically. They are chosen such
3614 that it looks neither cramped nor loose, and that consecutive lines have
3617 Occasionally you might want to override the automatic breaks; you can do
3618 this by specifying @code{\break}. This will force a line break at this
3619 point. Do remember that line breaks can only occur at places where there
3620 are bar lines. If you want to have a line break where there is no
3621 bar line, you can force an invisible bar line by entering @code{\bar
3622 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3624 If you want linebreaks at regular intervals, you can use the following:
3627 < \repeat 7 unfold @{ s1 * 4 \break @}
3631 This makes the following 28 measures (assuming 4/4 time) be broken every
3635 @cindex @code{\penalty}
3637 The @code{\break} and @code{\noBreak} commands are defined in terms of
3638 the penalty command:
3643 This encourages or discourages LilyPond to make a line break at this
3648 The scaling of the @code{\penalty} argument is not well-defined. The
3649 command is rather kludgey, and slated for rewriting.
3653 @subsection Page break
3656 @cindex breaking pages
3658 Page breaks are normally computed by @TeX{}, so they are not under
3659 direct control of LilyPond. However, you can insert a commands into the
3660 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3661 the command @code{\newpage}
3662 @cindex @code{\newpage}
3668 @c why do so difficult?
3669 @c maybe should explain contents of between-system.ly,
3670 @c but not now, we're talking about page breaks here.
3672 @c details, see the example file @file{input/test/between-systems.ly}
3675 @c . {Output scaling}
3676 @node Output scaling
3677 @subsection Output scaling
3692 There is no mechanism to select magnification of particular fonts,
3693 meaning that you don't have access to continuously scaled fonts.
3697 @c . {Output formats}
3698 @node Output formats
3699 @section Output formats
3701 LilyPond can output processed music in different output formats.
3705 * PostScript output::
3707 * ASCIIScript output::
3711 @subsection TeX output
3714 LilyPond will use @TeX{} by default. Even if you want to produce
3715 PostScript output for viewing or printing, you should normally have
3716 LilyPond produce @TeX{} first. The .tex output must be processed by
3717 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
3718 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
3719 used to generate the .dvi for you.
3723 Titling is not generated unless you use @file{ly2dvi}.
3726 @node PostScript output
3727 @subsection PostScript output
3728 @cindex PostScript output
3729 @cindex direct PostScript output
3731 LilyPond can produce PostScript directly, without going through @TeX{}.
3732 Currently, this is mainly useful if you cannot use TeX, because direct
3733 PostScript output has some problems; see Bugs below.
3736 $ lilypond -fps foo.ly
3737 GNU LilyPond 1.3.144
3738 Now processing: `foo.ly'
3740 Interpreting music...[3]
3741 Preprocessing elements...
3742 Calculating column positions...
3743 paper output to foo.ps...
3745 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
3751 Text font selection is broken.
3753 The .ps file does not contain the .pfa font files. To print a .ps
3754 created through direct postscript output, you should prepend the
3755 necessary .pfa files to LilyPond's .ps output, or upload them to the
3756 printer before printing.
3758 The line height calculation is broken, you must set @var{lineheight} in
3759 the paperblock if you have more than one staff in your score, e.g.
3764 % Set line height to 40 staff spaces
3770 @subsection Scheme output
3771 @cindex Scheme output
3773 In the typesetting stage, LilyPond builds a page description, which is
3774 then written to disk in postscript, @TeX{} or ASCII art. Before it is
3775 written, the page description is represented as Scheme expressions. You
3776 can also dump these Scheme expressions to a file, which may be
3777 convenient for debugging output routines. This is done with the Scheme
3781 $ lilypond -fscm foo.ly
3782 GNU LilyPond 1.3.144
3783 Now processing: `foo.ly'
3785 Interpreting music...[3]
3786 Preprocessing elements...
3787 Calculating column positions...
3788 paper output to foo.scm...
3791 ;;; Usage: guile -s x.scm > x.tex
3792 (primitive-load-path 'standalone.scm)
3796 $ guile -s foo.scm > foo.tex
3800 @node ASCIIScript output
3801 @subsection ASCIIScript output
3802 @cindex ASCIIScript output
3803 @cindex ascii script
3806 LilyPond can output ASCII Art. This is a two step process, LilyPond
3807 produces an ASCII description file, dubbed ASCIIScript (extension
3808 @file{.as}). ASCIIScript has a small and simple command set that
3809 includes font selection, character and string printing and line drawing
3810 commands. The program @file{as2text} is used to translate an .as file
3813 To produce ASCII Art, you must include an ASCII Art paper definition
3814 file in your .ly, one of:
3816 \include "paper-as5.ly"
3817 \include "paper-as9.ly"
3820 Here's an example use for ASCII Art output (the example file
3821 @file{as-email.ly} is included in the LilyPond distribution), the staff
3822 symbol has been made invisible:
3825 $ lilypond -fas as-email.ly
3826 GNU LilyPond 1.3.144
3827 Now processing: `as-email.ly'
3829 Interpreting music...[3]
3830 Preprocessing elements...
3831 Calculating column positions... [2]
3832 paper output to as-email.as...
3834 $ as2text as-email.as 2>/dev/null
3836 |/ |##|##| | | | | |
3837 /| | | | | |\ |\ |\ |\ |\ |
3838 / |_ 3 | | | | 5 | )| )| )| )| )|
3839 | /| \ 8 * * * | 8 * * * * * |
3849 The ASCII Art fonts are far from complete and not very well designed.
3850 It's easy to change the glyphs, though; if you think you can do better,
3851 have a look at @file{mf/*.af}.
3853 Lots of resizable symbols such as slurs, ties and tuplets are missing.
3855 The poor looks of most ASCII Art output and its limited general
3856 usefulness gives ASCII Art output a low priority; it may be
3857 dropped in future versions.
3864 LilyPond can produce MIDI output. The performance lacks lots of
3865 interesting effects, such as swing, articulation, slurring, etc., but it
3866 is good enough for proof-hearing the music you have entered. Ties,
3867 dynamics and tempo changes are interpreted.
3869 Dynamic marks, crescendi and decrescendi translate into MIDI volume
3870 levels. Dynamic marks translate to a fixed fraction of the available
3871 MIDI volume range, crescendi and decrescendi make the the volume vary
3872 linearly between their two extremities. The fractions be adjusted by
3873 overriding the @code{absolute-volume-alist} defined in
3874 @file{scm/midi.scm}.
3876 For each type of musical instrument (that MIDI supports), a volume range
3877 can be defined. This gives you basic equalizer control, which can
3878 enhance the quality of the MIDI output remarkably. You can add
3879 instruments and ranges or change the default settings by overriding the
3880 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
3882 Both loudness controls are combined to produce the final MIDI volume.
3887 It is currently not possible to use the percussion channel (generally
3888 channel 10 of a MIDI file).
3892 * MIDI instrument names::
3897 @subsection MIDI block
3901 The MIDI block is analogous to the paper block, but it is somewhat
3902 simpler. The @code{\midi} block can contain:
3906 @item a @code{\tempo} definition
3907 @item context definitions
3910 Assignments in the @code{\midi} block are not allowed.
3914 @cindex context definition
3916 Context definitions follow precisely the same syntax as within the
3917 \paper block. Translation modules for sound are called performers.
3918 The contexts for MIDI output are defined in @file{ly/performer.ly}.
3921 @node MIDI instrument names
3922 @subsection MIDI instrument names
3924 @cindex instrument names
3925 @cindex @code{Staff.midiInstrument}
3926 @cindex @code{Staff.instrument}
3928 The MIDI instrument name is set by the @code{Staff.midiInstrument}
3929 property or, if that property is not set, the @code{Staff.instrument}
3930 property. The instrument name should be chosen from the list in
3931 @ref{MIDI instruments}.
3935 If the selected string does not exactly match, then LilyPond uses the
3936 default (Grand Piano). It is not possible to select an instrument by
3946 @c FIXME: Note entry vs Music entry at top level menu is confusing.
3949 @section Music entry
3957 When entering music with LilyPond, it is easy to introduce errors. This
3958 section deals with tricks and features that help you enter music, and
3959 find and correct mistakes.
3963 @subsection Relative
3965 @cindex relative octave specification
3967 Octaves are specified by adding @code{'} and @code{,} to pitch names.
3968 When you copy existing music, it is easy to accidentally put a pitch in
3969 the wrong octave and hard to find such an error. To prevent these
3970 errors, LilyPond features octave entry.
3972 @cindex @code{\relative}
3974 \relative @var{startpitch} @var{musicexpr}
3977 The octave of notes that appear in @var{musicexpr} are calculated as
3978 follows: If no octave changing marks are used, the basic interval
3979 between this and the last note is always taken to be a fourth or less
3980 (This distance is determined without regarding alterations; a
3981 @code{fisis} following a @code{ceses} will be put above the
3984 The octave changing marks @code{'} and @code{,} can be added to raise or
3985 lower the pitch by an extra octave. Upon entering relative mode, an
3986 absolute starting pitch must be specified that will act as the
3987 predecessor of the first note of @var{musicexpr}.
3989 Entering music that changes octave frequently is easy in relative mode.
3990 @lilypond[fragment,singleline,verbatim,center]
3996 And octave changing marks are used for intervals greater than a fourth.
3997 @lilypond[fragment,verbatim,center]
3999 c g c f, c' a, e'' }
4002 If the preceding item is a chord, the first note of the chord is used
4003 to determine the first note of the next chord. However, other notes
4004 within the second chord are determined by looking at the immediately
4007 @lilypond[fragment,verbatim,center]
4014 @cindex @code{\notes}
4016 The pitch after the @code{\relative} contains a note name. To parse
4017 the pitch as a note name, you have to be in note mode, so there must
4018 be a surrounding @code{\notes} keyword (which is not
4021 The relative conversion will not affect @code{\transpose},
4022 @code{\chords} or @code{\relative} sections in its argument. If you
4023 want to use relative within transposed music, you must place an
4024 additional @code{\relative} inside the @code{\transpose}.
4029 @subsection Bar check
4033 @cindex @code{barCheckNoSynchronize}
4037 Whenever a bar check is encountered during interpretation, a warning
4038 message is issued if it doesn't fall at a measure boundary. This can
4039 help you find errors in the input. Depending on the value of
4040 @code{barCheckNoSynchronize}, the beginning of the measure will be
4041 relocated, so this can also be used to shorten measures.
4043 A bar check is entered using the bar symbol, @code{|}:
4045 \time 3/4 c2 e4 | g2.
4050 @cindex skipTypesetting
4052 Failed bar checks are most often caused by entering incorrect
4053 durations. Incorrect durations often completely garble up the score,
4054 especially if it is polyphonic, so you should start correcting the score
4055 by scanning for failed bar checks and incorrect durations. To speed up
4056 this process, you can use @code{skipTypesetting} (See @ref{Skipping
4057 corrected music})). Bar
4060 @c . {Point and click}
4061 @node Point and click
4062 @subsection Point and click
4064 Point and click lets you find notes in the input by clicking on them in
4065 the Xdvi window. This makes it very easy to find input that causes some
4066 error in the sheet music.
4068 To use it, you need the following software
4070 @unnumberedsubsec Installation
4074 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
4075 Xdvi} version 22.36 or newer.
4077 Note that most @TeX{} distributions ship with xdvik, which is a
4078 different and less well maintained program. To find out which xdvi you
4079 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
4083 Xdvi must be configured to find the TeX fonts and music
4084 fonts. Refer to the Xdvi documentation for more information.
4087 @unnumberedsubsec Using it
4089 Add one of these lines to the top of your .ly file. The first one is for
4090 line location only. The second one is more convenient, but requires
4091 patching @code{emacsclient} and @code{server.el}.
4094 #(set! point-and-click line-location)
4097 In the emacs startup file (usually @file{~/.emacs}), add the following
4102 Make sure that the environment variable @code{XEDITOR} is set
4105 emacsclient --no-wait +%l %f
4107 The second one, that also specifies the column, only works if you have
4108 patched your emacsclient and server, and have compiled your @code{.ly}
4109 file using the @code{line-column-location} setting.
4111 When viewing, control-mousebutton 1 will take you to the originating
4112 spot in the @file{.ly} file. Control-mousebutton 2 will show all
4116 @unnumberedsubsec Column location
4118 If you want emacs to jump to the exact spot (and not just the line) on a
4119 click, you must enable column positioning. To do so, you need to patch
4120 emacsclient. Apply @file{emacsclient.patch} (included with the source
4121 package) to @file{emacsclient.c} and @file{server.el} from the emacs
4122 source code. Recompile and stick the recompiled emacsclient into a bin
4123 directory, and put @file{server.el} into a elisp directory
4124 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
4125 init file, before invoking server-start.
4128 (setq load-path (cons "~/usr/share/emacs" load-path))
4131 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
4133 At the top of the @code{ly} file, replace the @code{set!} line with the
4136 #(set! point-and-click line-column-location)
4139 One final hint: if you correct large files with point-and-click, then
4140 start correcting at the end of the file. When you start at the top, and
4141 insert one line, all subsequent locations will be off by a line.
4146 When you convert the @TeX{} file to PostScript using @code{dvips}, it
4147 will complain about not finding @code{src:X:Y} files. Those complaints
4148 are harmless, and can be ignored.
4150 @node Skipping corrected music
4151 @section Skipping corrected music
4153 The property @code{Score.skipTypesetting} can be used to switch on and
4154 off typesetting completely during the interpretation phase. When
4155 typesetting is switched off, the music is processed much more quickly.
4156 You can use this to skip over the parts of a score that you have already
4159 @lilypond[fragment,singleline,verbatim]
4160 \relative c'' { c8 d
4161 \property Score.skipTypesetting = ##t
4163 \property Score.skipTypesetting = ##f
4168 @node Interpretation context
4169 @section Interpretation context
4172 * Creating contexts::
4173 * Default contexts::
4174 * Context properties::
4175 * Engravers and performers::
4176 * Changing context definitions::
4177 * Defining new contexts::
4181 Interpretation contexts are objects that only exist during a run of
4182 LilyPond. During the interpretation phase of LilyPond (when it prints
4183 "interpreting music"), the music expression in a @code{\score} block is
4184 interpreted in time order. This is the same order that humans hear and
4187 During this interpretation, the interpretation context holds the
4188 state for the current point within the music. It contains information
4192 @item What notes are playing at this point?
4193 @item What symbols will be printed at this point?
4194 @item What is the current key signature, time signature, point within
4198 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4199 contained in a @internalsref{Staff} context (because a staff can contain
4200 multiple voices at any point), a @internalsref{Staff} context is contained in
4201 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4203 Contexts associated with sheet music output are called @emph{notation
4204 contexts}, those for sound output are called @emph{performance
4205 contexts}. The default definitions of the standard notation and
4206 performance contexts can be found in @file{ly/engraver.ly} and
4207 @file{ly/performer.ly}, respectively.
4210 @node Creating contexts
4211 @subsection Creating contexts
4213 @cindex @code{\context}
4214 @cindex context selection
4216 Contexts for a music expression can be selected manually, using the
4217 following music expression.
4220 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4223 This instructs lilypond to interpret @var{musicexpr} within the context
4224 of type @var{contexttype} and with name @var{contextname}. If this
4225 context does not exist, it will be created.
4227 @lilypond[verbatim,singleline]
4229 \notes \relative c'' {
4230 c4 <d4 \context Staff = "another" e4> f
4236 In this example, the @code{c} and @code{d} are printed on the
4237 default staff. For the @code{e}, a context Staff called
4238 @code{another} is specified; since that does not exist, a new
4239 context is created. Within @code{another}, a (default) Voice context
4240 is created for the @code{e4}. When all music referring to a
4241 context is finished, the context is ended as well. So after the
4242 third quarter, @code{another} is removed.
4246 @node Default contexts
4247 @subsection Default contexts
4249 Most music expressions don't need an explicit @code{\context}
4250 declaration: they inherit the
4251 notation context from their parent. Each note is a music expression, and
4252 as you can see in the following example, only the sequential music
4253 enclosing the three notes has an explicit context.
4255 @lilypond[verbatim,singleline]
4256 \score { \notes \context Voice = goUp { c'4 d' e' } }
4259 There are some quirks that you must keep in mind when dealing with
4262 First, every top level music is interpreted by the Score context, in other
4263 words, you may think of @code{\score} working like
4266 \context Score @var{music}
4270 Second, contexts are created automatically to be able to interpret the
4271 music expressions. Consider the following example.
4273 @lilypond[verbatim, singleline]
4274 \score { \context Score \notes { c'4 ( d' )e' } }
4277 The sequential music is interpreted by the Score context initially
4278 (notice that the @code{\context} specification is redundant), but when a
4279 note is encountered, contexts are setup to accept that note. In this
4280 case, a Thread, Voice and Staff are created. The rest of the sequential
4281 music is also interpreted with the same Thread, Voice and Staff context,
4282 putting the notes on the same staff, in the same voice.
4284 This is a convenient mechanism, but do not expect opening chords to work
4285 without @code{\context}. For every note, a separate staff is
4288 @cindex explicit context
4289 @cindex starting with chords
4290 @cindex chords, starting with
4292 @lilypond[verbatim, singleline]
4293 \score { \notes <c'4 es'> }
4296 Of course, if the chord is preceded by a normal note in sequential
4297 music, the chord will be interpreted by the Thread of the preceding
4299 @lilypond[verbatim,singleline]
4300 \score { \notes { c'4 <c'4 es'> } }
4305 @node Context properties
4306 @subsection Context properties
4308 Notation contexts have properties. These properties are from
4309 the @file{.ly} file using the following expression:
4310 @cindex @code{\property}
4312 \property @var{contextname}.@var{propname} = @var{value}
4315 Sets the @var{propname} property of the context @var{contextname} to the
4316 specified Scheme expression @var{value}. All @var{propname} and
4317 @var{contextname} are strings, which are typically unquoted.
4319 Properties that are set in one context are inherited by all of the
4320 contained contexts. This means that a property valid for the
4321 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4322 example) and thus take effect in all @internalsref{Voice} contexts.
4324 Properties can be unset using the following expression:
4326 \property @var{contextname}.@var{propname} \unset
4329 @cindex properties, unsetting
4330 @cindex @code{\unset}
4332 This removes the definition of @var{propname} in @var{contextname}. If
4333 @var{propname} was not defined in @var{contextname} (but was inherited
4334 from a higher context), then this has no effect.
4339 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4340 the inverse of @code{\property \set}.
4342 @node Engravers and performers
4343 @subsection Engravers and performers
4347 Basic building blocks of translation are called engravers; they are
4348 special C++ classes.
4352 @c . {Context definitions}
4353 @node Changing context definitions
4354 @subsection Changing context definitions
4356 @cindex context definition
4357 @cindex translator definition
4359 The most common way to define a context is by extending an existing
4360 context. You can change an existing context from the paper block, by
4361 first initializing a translator with an existing context identifier:
4365 @var{context-identifier}
4368 Then you can add and remove engravers using the following syntax:
4370 \remove @var{engravername}
4371 \consists @var{engravername}
4375 Here @var{engravername} is a string, the name of an engraver in the
4379 @lilypond[verbatim,singleline]
4383 \translator { \StaffContext
4384 \remove Clef_engraver
4390 You can also set properties in a translator definition. The syntax is as
4393 @var{propname} = @var{value}
4394 @var{propname} \set @var{grob-propname} = @var{pvalue}
4395 @var{propname} \override @var{grob-propname} = @var{pvalue}
4396 @var{propname} \revert @var{grob-propname}
4398 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4399 and @code{pvalue} are Scheme expressions. These type of property
4400 assignments happen before interpretation starts, so a @code{\property}
4401 command will override any predefined settings.
4404 To simplify editing translators, all standard contexts have standard
4405 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4406 @code{VoiceContext}, see @file{ly/engraver.ly}.
4408 @node Defining new contexts
4409 @subsection Defining new contexts
4411 If you want to build a context from scratch, you must also supply the
4412 following extra information:
4414 @item A name, specified by @code{\name @var{contextname}}.
4416 @item A cooperation module. This is specified by @code{\type
4423 \type "Engraver_group_engraver"
4426 \consists "Staff_symbol_engraver"
4427 \consists "Note_head_engraver"
4428 \consistsend "Axis_group_engraver"
4432 The argument of @code{\type} is the name for a special engraver that
4433 handles cooperation between simple engravers such as
4434 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4435 for this engraver are the following:
4437 @cindex @code{Engraver_group_engraver}
4438 @item @code{Engraver_group_engraver}
4439 The standard cooperation engraver.
4441 @cindex @code{Score_engraver}
4443 @item @code{Score_engraver}
4444 This is cooperation module that should be in the top level context,
4445 and only the top level context.
4447 @cindex @code{Grace_engraver_group}
4449 @item @code{Grace_engraver_group}
4450 This is a special cooperation module (resembling
4451 @code{Score_engraver}) that is used to create an embedded
4458 @item @code{\alias} @var{alternate-name}
4459 This specifies a different name. In the above example,
4460 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4462 @item @code{\consistsend} @var{engravername}
4463 Analogous to @code{\consists}, but makes sure that
4464 @var{engravername} is always added to the end of the list of
4467 Some engraver types need to be at the end of the list; this
4468 insures they stay there even if a user adds or removes engravers.
4469 End-users generally don't need this command.
4471 @item @code{\accepts} @var{contextname}
4472 Add @var{contextname} to the list of contexts this context can
4473 contain in the context hierarchy. The first listed context is the
4474 context to create by default.
4476 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4477 completeness, but is never used in practice.
4480 @item @code{\name} @var{contextname}
4481 This sets the type name of the context, e.g. @internalsref{Staff},
4482 @internalsref{Voice}. If the name is not specified, the translator won't do
4486 In the @code{\paper} block, it is also possible to define translator
4487 identifiers. Like other block identifiers, the identifier can only
4488 be used as the very first item of a translator. In order to define
4489 such an identifier outside of @code{\score}, you must do
4494 foo = \translator @{ @dots{} @}
4501 \translator @{ \foo @dots{} @}
4509 @cindex paper types, engravers, and pre-defined translators
4516 @c . {Syntactic details}
4517 @node Syntactic details
4518 @section Syntactic details
4519 @cindex Syntactic details
4521 This section describes details that were too boring to be put elsewhere.
4526 * Music expressions::
4527 * Manipulating music expressions::
4535 @subsection Top level
4538 This section describes what you may enter at top level.
4542 @subsubsection Score
4545 @cindex score definition
4547 The output is generated combining a music expression with an output
4548 definition. A score block has the following syntax:
4551 \score @{ @var{musicexpr} @var{outputdefs} @}
4554 @var{outputdefs} are zero or more output definitions. If none is
4555 supplied, the default @code{\paper} block will be added.
4559 @c . {Default output}
4560 @subsubsection Default output
4562 Default values for the @code{\paper} and @code{\midi} block are set by
4563 entering such a block at the top level.
4566 @subsubsection Header
4568 @cindex @code{\header}
4571 A header describes bibliographic information of the file's contents. It
4572 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4573 use this information for generating titles. Key values that are used by
4574 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4575 meter, arranger, piece and tagline.
4577 @cindex @code{ly2dvi}
4581 \header @{ @var{key1} = @var{val1}
4582 @var{key2} = @var{val2} @dots{} @}
4585 It is customary to put the @code{\header} at the top of the file.
4587 @subsubsection Default output
4589 A @code{\midi} or @code{\paper} block at top level sets the default
4590 paper block for all scores that lack an explicit paper block.
4594 @subsection Identifiers
4598 What has this section got to do with identifiers?
4599 It seems more appropriate in the introduction to Chapter 4,
4605 All of the information in a LilyPond input file, is internally
4606 represented as a Scheme value. In addition to normal Scheme data types
4607 (such as pair, number, boolean, etc.), LilyPond has a number of
4608 specialized data types,
4615 @item Translator_def
4619 @item Music_output_def
4620 @item Moment (rational number)
4623 LilyPond also includes some transient object types. Objects of these
4624 types are built during a LilyPond run, and do not `exist' per se within
4625 your input file. These objects are created as a result of your input
4626 file, so you can include commands in the input to manipulate them,
4627 during a lilypond run.
4630 @item Grob: short for Graphical object. See @ref{Grobs}.
4631 @item Molecule: device-independent page output object,
4632 including dimensions. Produced by some Grob functions
4634 @item Translator: object that produces audio objects or Grobs. This is
4635 not yet user accessible.
4636 @item Font_metric: object representing a font. (See @ref{Font metrics})
4641 @node Music expressions
4642 @subsection Music expressions
4644 @cindex music expressions
4646 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4647 syllables are music expressions, and you can combine music expressions
4648 to form new ones, for example by enclosing a list of expressions in
4649 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4650 compound expression is formed out of the quarter note @code{c} and a
4651 quarter note @code{d}:
4654 \sequential @{ c4 d4 @}
4657 @cindex Sequential music
4658 @cindex @code{\sequential}
4659 @cindex sequential music
4662 @cindex Simultaneous music
4663 @cindex @code{\simultaneous}
4665 The two basic compound music expressions are simultaneous and
4669 \sequential @code{@{} @var{musicexprlist} @code{@}}
4670 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4672 For both, there is a shorthand:
4674 @code{@{} @var{musicexprlist} @code{@}}
4678 @code{<} @var{musicexprlist} @code{>}
4680 for simultaneous music.
4681 In principle, the way in which you nest sequential and simultaneous to
4682 produce music is not relevant. In the following example, three chords
4683 are expressed in two different ways:
4685 @lilypond[fragment,verbatim,center]
4686 \notes \context Voice {
4687 <a c'> <b d' > <c' e'>
4688 < { a b c' } { c' d' e' } >
4693 Other compound music expressions include
4696 \transpose @var{pitch} @var{expr}
4697 \apply @var{func} @var{expr}
4698 \context @var{type} = @var{id} @var{expr}
4699 \times @var{fraction} @var{expr}
4703 @c . {Manipulating music expressions}
4704 @node Manipulating music expressions
4705 @subsection Manipulating music expressions
4707 The @code{\apply} mechanism gives you access to the internal
4708 representation of music. You can write Scheme-functions that operate
4709 directly on it. The syntax is
4711 \apply #@var{func} @var{music}
4713 This means that @var{func} is applied to @var{music}. The function
4714 @var{func} should return a music expression.
4716 This example replaces the text string of a script. It also shows a dump
4717 of the music it processes, which is useful if you want to know more
4718 about how music is stored.
4720 @lilypond[verbatim,singleline]
4721 #(define (testfunc x)
4722 (if (equal? (ly-get-mus-property x 'text) "foo")
4723 (ly-set-mus-property x 'text "bar"))
4725 (ly-set-mus-property x 'elements
4726 (map testfunc (ly-get-mus-property x 'elements)))
4731 \apply #testfunc { c'4_"foo" }
4735 For more information on what is possible, see the automatically
4736 generated documentation.
4739 Directly accessing internal representations is dangerous: the
4740 implementation is subject to changes, so you should avoid this feature
4743 A final example is a function that reverses a piece of music in time:
4745 @lilypond[verbatim,singleline]
4746 #(define (reverse-music music)
4747 (let* ((elements (ly-get-mus-property music 'elements))
4748 (reversed (reverse elements))
4749 (span-dir (ly-get-mus-property music 'span-direction)))
4750 (ly-set-mus-property music 'elements reversed)
4752 (ly-set-mus-property music 'span-direction (- span-dir)))
4753 (map reverse-music reversed)
4756 music = \notes { c'4 d'4( e'4 f'4 }
4758 \score { \context Voice {
4760 \apply #reverse-music \music
4765 More examples are given in the distributed example files in
4768 @c . {Span requests}
4774 @subsubsection Span requests
4775 @cindex Span requests
4777 Notational constructs that start and end on different notes can be
4778 entered using span requests. The syntax is as follows:
4782 \spanrequest @var{startstop} @var{type}
4786 @cindex @code{\start}
4787 @cindex @code{\stop}
4789 This defines a spanning request. The @var{startstop} parameter is either
4790 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
4791 describes what should be started. Much of the syntactic sugar is a
4792 shorthand for @code{\spanrequest}, for example,
4794 @lilypond[fragment,verbatim,center]
4795 c'4-\spanrequest \start "slur"
4796 c'4-\spanrequest \stop "slur"
4799 Among the supported types are @code{crescendo}, @code{decrescendo},
4800 @code{beam}, @code{slur}. This is an internal command. Users are
4801 encouraged to use the shorthands which are defined in the initialization
4802 file @file{spanners.ly}.
4807 @subsection Assignments
4810 Identifiers allow objects to be assigned to names during the parse
4811 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
4812 and to refer to an identifier, you precede its name with a backslash:
4813 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
4814 the input-types listed above. Identifier assignments can appear at top
4815 level in the LilyPond file, but also in @code{\paper} blocks.
4817 An identifier can be created with any string for its name, but you will
4818 only be able to refer to identifiers whose names begin with a letter,
4819 being entirely alphabetical. It is impossible to refer to an identifier
4820 whose name is the same as the name of a keyword.
4822 The right hand side of an identifier assignment is parsed completely
4823 before the assignment is done, so it is allowed to redefine an
4824 identifier in terms of its old value, e.g.
4830 When an identifier is referenced, the information it points to is
4831 copied. For this reason, an identifier reference must always be the
4832 first item in a block.
4836 \paperIdent % wrong and invalid
4840 \paperIdent % correct
4845 @c . {Lexical modes}
4847 @subsection Lexical modes
4848 @cindex Lexical modes
4851 @cindex @code{\notes}
4852 @cindex @code{\chords}
4853 @cindex @code{\lyrics}
4855 To simplify entering notes, lyrics, and chords, LilyPond has three
4856 special input modes in addition to the default mode: note, lyrics and
4857 chords mode. These input modes change the way that normal, unquoted
4858 words are interpreted: for example, the word @code{cis} may be
4859 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
4860 major triad respectively.
4862 A mode switch is entered as a compound music expression
4864 @code{\notes} @var{musicexpr}
4865 @code{\chords} @var{musicexpr}
4866 @code{\lyrics} @var{musicexpr}.
4869 In each of these cases, these expressions do not add anything to the
4870 meaning of their arguments. They just instruct the parser in what mode
4871 to parse their arguments. The modes are treated in more detail in
4872 @ref{Lyrics} and @ref{Chords}.
4874 Different input modes may be nested.
4878 @subsection Ambiguities
4883 The grammar contains a number of ambiguities. We hope to resolve them at
4887 @item The assignment
4892 is interpreted as the string identifier assignment. However,
4893 it can also be interpreted as making a string identifier @code{\foo}
4894 containing @code{"bar"}, or a music identifier @code{\foo}
4895 containing the syllable `bar'.
4897 @item If you do a nested repeat like
4909 then it is ambiguous to which @code{\repeat} the
4910 @code{\alternative} belongs. This is the classic if-then-else
4911 dilemma. It may be solved by using braces.
4913 @item The parser is not sophisticated enough to distinguish at the
4915 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
4922 @c . {Lexical details}
4923 @node Lexical details
4924 @section Lexical details
4926 Even more boring details, now on lexical side of the input parser.
4937 * Version information::
4942 @subsection Comments
4945 @cindex block comment
4946 @cindex line comment
4950 A one line comment is introduced by a @code{%} character.
4951 Block comments are started by @code{%@{} and ended by @code{%@}}.
4952 They cannot be nested.
4955 @subsection Direct Scheme
4959 @cindex Scheme, in-line code
4962 LilyPond contains a Scheme interpreter (the GUILE library) for
4963 internal use. In some places, Scheme expressions also form valid syntax:
4964 wherever it is allowed,
4968 evaluates the specified Scheme code. Example:
4970 \property Staff.TestObject \override #'foobar = #(+ 1 2)
4972 @code{\override} expects two Scheme expressions, so there are two Scheme
4973 expressions. The first one is a symbol (@code{foobar}), the second one
4974 an integer (namely, 3).
4976 In-line scheme may be used at the top level. In this case the result is
4979 Scheme is a full-blown programming language, and a full discussion is
4980 outside the scope of this document. Interested readers are referred to
4981 the website @uref{http://www.schemers.org/} for more information on
4986 @subsection Keywords
4990 Keywords start with a backslash, followed by a number of lower case
4991 alphabetic characters. These are all the keywords.
4994 apply arpeggio autochange spanrequest commandspanrequest
4995 simultaneous sequential accepts alternative bar breathe
4996 char chordmodifiers chords clef cm consists consistsend
4997 context denies duration dynamicscript elementdescriptions
4998 font grace header in lyrics key mark pitch
4999 time times midi mm name pitchnames notes outputproperty
5000 override set revert partial paper penalty property pt
5001 relative remove repeat addlyrics partcombine score
5002 script stylesheet skip textscript tempo translator
5007 @subsection Integers
5015 Formed from an optional minus sign followed by digits. Arithmetic
5016 operations cannot be done with integers, and integers cannot be mixed
5021 @cindex real numbers
5027 Formed from an optional minus sign and a sequence of digits followed
5028 by a @emph{required} decimal point and an optional exponent such as
5029 @code{-1.2e3}. Reals can be built up using the usual operations:
5030 `@code{+}', `@code{-}', `@code{*}', and
5031 `@code{/}', with parentheses for grouping.
5039 A real constant can be followed by one of the dimension keywords:
5040 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5041 points, inches and centimeters, respectively. This converts the number
5042 a number that is the internal representation of that dimension.
5050 Begins and ends with the @code{"} character. To include a @code{"}
5051 character in a string write @code{\"}. Various other backslash
5052 sequences have special interpretations as in the C language. A string
5053 that contains no spaces can be written without the quotes. Strings can
5054 be concatenated with the @code{+} operator.
5058 @subsection Main input
5061 @cindex @code{\maininput}
5063 The @code{\maininput} command is used in init files to signal that the
5064 user file must be read. This command cannot be used in a user file.
5066 @node File inclusion
5067 @subsection File inclusion
5068 @cindex @code{\include}
5070 \include @var{filename}
5073 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5074 unquoted string will not work here!) or a string identifier. The full
5075 filename including the @file{.ly} extension must be given,
5078 @node Version information
5079 @subsection Version information
5080 @cindex @code{\version}
5082 \version @var{string}
5085 Specify the version of LilyPond that a file was written for. The
5086 argument is a version string in quotes, for example @code{"1.2.0"}.
5087 This is used to detect invalid input, and to aid
5088 @code{convert-ly} a tool that automatically upgrades input files. See
5089 See @ref{convert-ly} for more information on @code{convert-ly}.
5097 @c broken with emacs-21
5098 @c {Local emac s vars}
5099 @c Local varia bles:
5101 @c minor-mod e: font-lock
5102 @c minor-mo de: outline
5103 @c outline -layout: (-1 : 0)
5104 @c outlin e-use-mode-specific-leader: "@c \."
5105 @c outli ne-primary-bullet: "{"
5106 @c outli ne-stylish-prefixes: nil
5107 @c outli ne-override-protect: t