4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c M-x texinfo-all-menus-update
6 @c to automagically fill in these menus before saving changes
15 @c .{Reference Manual}
17 @node Reference Manual
18 @chapter Reference Manual
21 <!--- @@WEB-TITLE@@=Reference Manual --->
24 This document describes GNU LilyPond and its input format. The last
25 revision of this document was made for LilyPond 1.4.1. It supposes a
26 passing familiarity with how LilyPond input works. New users are
27 encouraged to study the tutorial first.
29 The reference manual is ordered according to different tasks.
30 More details on the property setting mechanisms and context handling is
31 provided in @ref{Tuning output} and @ref{Interpretation context}. The
32 syntactical details are described at the end of the manual.
54 * Skipping corrected music::
55 * Interpretation context::
65 The purpose of LilyPond is explained informally by the term `music
66 typesetter'. This is not a fully correct name: not only does the
67 program print musical symbols, it also makes aesthetic decisions.
68 Symbols and their placements are @emph{generated} from a high-level
69 musical description. In other words, LilyPond would be best described
70 by `music compiler' or `music to notation compiler'.
72 LilyPond is linked to GUILE, GNU's Scheme library for extension
73 programming. The Scheme library provides the glue that holds together
74 the low-level routines and separate modules which are written in C++.
76 When lilypond is run to typeset sheet music, the following happens:
78 @item GUILE Initialization: various scheme files are read
79 @item parsing: first standard @code{ly} initialization files are read, and
80 then the user @file{ly} file is read.
81 @item interpretation: the music in the file is processed ``in playing
82 order'', i.e. the order that you use to read sheet music, or the
83 order in which notes are played. The result of this step is a typesetting
87 The typesetting specification is solved: positions and formatting is
90 @item the visible results ("virtual ink") are written to the output file.
93 During these stages different types of data play the the main role:
94 during parsing, @strong{Music} objects are created. During the
95 interpretation, @strong{contexts} are constructed, and with these contexts
96 a network of @strong{graphical objects} (``grobs'') is created. These
97 grobs contain unknown variables, and the network forms a set of
98 equations. After solving the equations and filling in these variables,
99 the printed output (in the form of @strong{molecules}) is written to an
102 These threemanship of tasks (parsing, translating, typesetting) and
103 data-structures (music, context, graphical objects) permeates the entire
104 design of the program.
111 The most basic forms of music are notes. We discuss how you enter them
112 here. Notes on their own don't form valid input, but for the sake of
113 brevity we omit obligatory lint such as @code{\score} blocks and
114 @code{\paper} declarations.
125 * Defining pitch names::
126 * Easy Notation note heads ::
133 A note specification has the form
136 @var{pitch}[!][?][@var{duration}]
139 The alteration refers to what note is heard, not to whether an
140 accidental is printed. This is done depending on the key and context.
141 A reminder accidental
142 @cindex reminder accidental
144 can be forced by adding an exclamation mark @code{!} after the pitch. A
145 cautionary accidental,
146 @cindex cautionary accidental
147 @cindex parenthesized accidental
148 i.e., an accidental within parentheses can be obtained by adding the
149 question mark `@code{?}' after the pitch.
151 @lilypond[fragment,verbatim,center]
152 cis' d' e' cis' c'? d' e' c'!
161 @cindex Note specification
163 @cindex entering notes
165 The verbose syntax for pitch specification is
167 @cindex @code{\pitch}
169 \pitch @var{scmpitch}
172 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
174 In Note and Chord mode, pitches may be designated by names. The default
175 names are the Dutch note names. The notes are specified by the letters
176 @code{a} through @code{g} (where the octave is formed by notes ranging
177 from @code{c} to @code{b}). The pitch @code{c} is an octave below
178 middle C and the letters span the octave above that C.
180 @cindex note names, Dutch
182 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
183 name and a flat is formed by adding @code{-es}. Double sharps and double
184 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
185 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
186 both forms are accepted.
188 LilyPond has predefined sets of note names for various other languages.
189 To use them, simply include the language specific init file. For
190 example: @code{\include "english.ly"}. The available language files and
191 the names they define are:
194 Note Names sharp flat
195 nederlands.ly c d e f g a bes b -is -es
196 english.ly c d e f g a bf b -s/-sharp -f/-flat
197 deutsch.ly c d e f g a b h -is -es
198 norsk.ly c d e f g a b h -iss/-is -ess/-es
199 svenska.ly c d e f g a b h -iss -ess
200 italiano.ly do re mi fa sol la sib si -d -b
201 catalan.ly do re mi fa sol la sib si -d/-s -b
209 The optional octave specification takes the form of a series of
210 single quote (`@code{'}') characters or a series of comma
211 (`@code{,}') characters. Each @code{'} raises the pitch by one
212 octave; each @code{,} lowers the pitch by an octave.
214 @lilypond[fragment,verbatim,center]
215 c' c'' es' g' as' gisis' ais'
223 Rests are entered like notes, with note name `@code{r}'. The grob is
224 @code{Rest}. Whole bar rests centered in the bar are specified using
225 @code{R}, see @ref{Multi measure rests}.
240 Skips the amount of time specified by @var{duration}. If no other music
241 is played, a gap will be left for the skipped time without any notes
242 printed. The shorthand is only available in Note and Chord mode.
246 @subsection Durations
250 @cindex @code{\duration}
252 The syntax for a verbose duration specification is
254 \duration @var{scmduration}
256 Here, @var{scmduration} is a Scheme object of type @code{Duration}. See
257 @ref{Duration} for more information.
260 In Note, Chord, and Lyrics mode, durations may be designated by numbers
261 and dots: durations are entered as their reciprocal values. For notes
262 longer than a whole you must use identifiers.
266 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
268 r1 r2 r4 r8 r16 r32 r64 r64
274 \notes \relative c'' {
276 a1 a2 a4 a8 a16 a32 a64 a64
278 r1 r2 r4 r8 r16 r32 r64 r64
283 \remove "Clef_engraver"
284 \remove "Staff_symbol_engraver"
285 \remove "Time_signature_engraver"
286 \consists "Pitch_squash_engraver"
292 To get a longa note head, you have to use mensural note heads. This
293 is accomplished by setting the @code{style} property of the
294 NoteHead grob to @code{mensural}. There is also a note head style
295 @code{baroque} which gives mensural note heads for @code{\longa} and
296 @code{\breve} but standard note heads for shorter notes.
298 @lilypond[fragment,singleline,verbatim]
299 \property Voice.NoteHead \set #'style = #'mensural
303 If the duration is omitted then it is set to the previous duration
304 entered. At the start of parsing a quarter note is assumed. The
305 duration can be followed by dots (`@code{.}') to obtain dotted note
309 @lilypond[fragment,verbatim,center]
315 You can alter the length of duration by a fraction @var{N/M} by
316 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
317 will not affect the appearance of the notes or rests produced.
329 A tie connects two adjacent note heads of the same pitch. When used
330 with chords, it connects all the note heads whose pitches match.
331 Ties are indicated using the tilde symbol `@code{~}'. If you try to tie
332 together chords which have no common pitches then no ties will be
335 @lilypond[fragment,verbatim,center]
336 e' ~ e' <c' e' g'> ~ <c' e' g'>
339 If you dislike the amount of ties created for a chord, you set
340 @code{Voice.sparseTies} to true, resulting in a smaller number of
342 @lilypond[fragment,verbatim,center]
343 \property Voice.sparseTies = ##t
344 <c' e' g'> ~ <c' e' g'>
347 In its meaning a tie is just a way of extending a note duration, similar
348 to the augmentation dot: the following example are two ways of notating
349 exactly the same concept.
351 @lilypond[fragment, singleline]
352 \time 3/4 c'2. c'2 ~ c'4
355 The name of the tie grob is @code{Voice.Tie}.
359 At present, the tie is implemented as a separate thing, temporally
360 located in between the notes. There is also no way to convert
361 between tied notes, dotted notes and plain notes.
363 Tieing only a subset of the note heads of a chord is not supported in a
364 simple way. It can be achieved by moving the tie-engraver into the Thread
365 context and turning on and off ties per Thread.
373 @cindex @code{\times}
375 Tuplets are made out of a music expression by multiplying all duration
378 @cindex @code{\times}
380 \times @var{fraction} @var{musicexpr}
383 The duration of @var{musicexpr} will be multiplied by the fraction.
384 In print, the fraction's denominator will be printed over the notes,
385 optionally with a bracket. The most common tuplet is the triplet in
386 which 3 notes have the length of 2, so the notes are 2/3 of
387 their written length:
389 @lilypond[fragment,verbatim,center]
390 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
393 The property @code{tupletSpannerDuration} specifies how long each bracket
394 should last. With this, you can make lots of tuplets while typing
395 @code{\times} only once, thus saving typing work.
397 @lilypond[fragment, relative, singleline, verbatim]
398 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
399 \times 2/3 { c'8 c c c c c }
402 The format of the number is determined by the property
403 @code{tupletNumberFormatFunction}. The default prints only the
404 denominator, but if you set it to the Scheme function
405 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
408 The typesetting of brackets and numbers is controlled by the properties
409 @code{tuplet-bracket-visibility} and @code{tuplet-number-visibility}.
411 @lilypond[fragment, relative, singleline, verbatim]
412 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t
413 \times 2/3{c'8 d e} \times 2/3{d4 e8}
414 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam
415 \times 2/3{c d e} \times 2/3{d4 e8}
416 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f
417 \times 2/3{c d e} \times 2/3{d4 e8}
418 \property Voice.TupletBracket \set #'tuplet-number-visibility = ##f
419 \times 2/3{c d e} \times 2/3{d4 e8}
420 \property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam
421 \times 2/3{c d e} \times 2/3{d4 e8}
424 @cindex @code{tupletNumberFormatFunction}
425 @cindex tuplet formatting
427 Tuplet brackets are printed as @code{TupletBracket} grobs
429 @c . {Defining pitch names}
430 @node Defining pitch names
431 @subsection Defining pitch names
433 @cindex defining pitch names
434 @cindex pitch names, defining
436 Note names and chord modifiers can be customized for nationalities. The
437 syntax is as follows.
439 @cindex @code{\pitchnames}
440 @cindex @code{\chordmodifiers}
442 \pitchnames @var{scheme-alist}
443 \chordmodifiers @var{scheme-alist}
446 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
447 specific examples on how to do this.
450 @node Easy Notation note heads
451 @subsection Easy Notation note heads
453 @cindex easy notation
456 A entirely different type of note head is the "easyplay" note head: a
457 note head that includes a note name. It is used in some publications by
458 Hal-Leonard Inc. music publishers.
460 @lilypond[singleline,verbatim]
461 \include "paper23.ly"
463 \notes { c'2 e'4 f' | g'1 }
464 \paper { \translator { \EasyNotation } }
468 Note that @code{EasyNotation} overrides a @code{Score} context. You
469 probably will want to print it with magnification to make it more
470 readable, see @ref{Output scaling}.
476 If you view the result with Xdvi, then staff lines will show through the
477 letters. Printing the postscript file obtained either by using dvips or
478 the @code{-f ps} option of lilypond produces the correct result.
483 @section Staff notation
485 @cindex Staff notation
497 @subsection Key signature
502 Setting or changing the key signature is done with the @code{\key}
505 @code{\key} @var{pitch} @var{type}
508 @cindex @code{\minor}
509 @cindex @code{\major}
510 @cindex @code{\minor}
511 @cindex @code{\ionian}
512 @cindex @code{\locrian}
513 @cindex @code{\aeolian}
514 @cindex @code{\mixolydian}
515 @cindex @code{\lydian}
516 @cindex @code{\phrygian}
517 @cindex @code{\dorian}
519 Here, @var{type} should be @code{\major} or @code{\minor} to get
520 @var{pitch}-major or @var{pitch}-minor, respectively.
521 The standard mode names @code{\ionian},
522 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
523 @code{\phrygian}, and @code{\dorian} are also defined.
525 This command sets the context property @code{Staff.keySignature}.
526 Non-standard key signatures can be specified by setting this property
527 directly, see the generated documentation for @rgrob{KeySignature}.
529 The printed signature is a @code{KeySignature} grob.
531 @cindex @code{keySignature}
538 The clef can be set or changed with the @code{\clef} command.
546 \property Staff.clefGlyph = @var{glyph associated with clefname}
547 \property Staff.clefPosition = @var{clef Y-position for clefname}
548 \property Staff.centralCPosition = @var{position for central C}
549 \property Staff.clefOctavation = @var{extra transposition of clefname}
552 Any change in these properties creates a clef (a @code{Clef} grob).
554 Supported clef-names include
556 @c Moved standard clefs to the top /MB
558 @item treble, violin, G, G2
567 G clef on 1st line, so-called French violin clef
582 By adding @code{_8} or @code{^8} to the clef name, the clef is
583 transposed one octave down or up, respectively.
585 Supported associated glyphs (for @code{Staff.clefGlyph}) are:
594 @item clefs-vaticana_do
595 Editio Vaticana style do clef
596 @item clefs-vaticana_fa
597 Editio Vaticana style fa clef
598 @item clefs-medicaea_do
599 Editio Medicaea style do clef
600 @item clefs-medicaea_fa
601 Editio Medicaea style fa clef
602 @item clefs-mensural1_c
603 modern style mensural C clef
604 @item clefs-mensural2_c
605 historic style small mensural C clef
606 @item clefs-mensural3_c
607 historic style big mensural C clef
608 @item clefs-mensural1_f
609 historic style traditional mensural F clef
610 @item clefs-mensural2_f
611 historic style new mensural F clef
612 @item clefs-mensural_g
613 historic style mensural G clef
614 @item clefs-hufnagel_do
615 historic style hufnagel do clef
616 @item clefs-hufnagel_fa
617 historic style hufnagel fa clef
618 @item clefs-hufnagel_do_fa
619 historic style hufnagel combined do/fa clef
620 @item clefs-percussion
621 modern style percussion clef
624 @emph{Modern style} means ``as is typeset in current editions.''
625 @emph{Historic style} means ``as was typeset or written in contemporary
626 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
629 @cindex Vaticana, Editio
630 @cindex Medicaea, Editio
631 @cindex hufnagel clefs
634 @c . {Time signature}
636 @subsection Time signature
637 @cindex Time signature
641 The time signature is set or changed by the @code{\time}
644 \time @var{n}@code{/}@var{d}
646 Internally, this is a shortcut for doing
648 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
649 \property Score.beatLength = #(make-moment 1 @var{d})
650 \property Score.measureLength = #(make-moment @var{n} @var{d})
653 These properties @code{timeSignatureFraction} determine where bar lines
654 should be inserted, and how automatic beams should be
657 Changing the value of @code{timeSignatureFraction} also causes a
658 fraction to be printed. This grob is @code{TimeSignature}.
660 The actual symbol that's printed can be customized with the style
662 @lilypond[fragment, verbatim, singleline]
664 \property Staff.TimeSignature \override #'style = #'C
666 \property Staff.TimeSignature \override #'style = #'()
668 \property Staff.TimeSignature \override #'style = #'C
672 There are many more options for the layout of this grob. They are
673 selected through the @code{style} grob property.
675 @c FIXME: this isn't documented except in example?
677 @file{input/test/time.ly} for examples.
684 @cindex partial measure
685 @cindex measure, partial
686 @cindex shorten measures
687 @cindex @code{\partial}
689 Partial measures, for example in upbeats, are entered using the
690 @code{\partial} command:
692 \partial @var{duration}
695 Internally, this is a shortcut for
698 \property Score.measurePosition = -@var{length of duration}
702 The property @code{measurePosition} contains a rational number
703 indicating how much of the measure has passed at this point.
706 @node Unmetered music
707 @subsection Unmetered music
709 Bar lines and bar numbers are calculated automatically. For unmetered
710 music (e.g. cadenzas), this is not desirable. The property
711 @code{Score.timing} can be used to switch off this automatic timing
713 @lilypond[fragment,relative,singleline,verbatim]
715 \property Score.timing = ##f
717 \property Score.timing = ##t
721 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
728 @subsection Bar lines
732 @cindex measure lines
739 This is a shortcut for doing
741 \property Score.whichBar = @var{bartype}
743 The following bar types are available
745 @lilypond[fragment, relative, singleline, verbatim]
758 You are encouraged to use @code{\repeat} for repetitions. See
762 @cindex Bar_line_engraver
764 @cindex repeatCommands
765 @cindex defaultBarType
767 Whenever @code{whichBar} is set to a string, a bar line of that type is
768 created. @code{whichBar} is usually set automatically: at the start of
769 a measure it is set to @code{defaultBarType}. The contents of
770 @code{repeatCommands} is used to override default measure bars.
772 @code{whichBar} can also be set directly, using @code{\property} or
773 @code{\bar }. These settings take precedence over the automatic
774 @code{whichBar} settings.
776 @code{BarLine} grobs are created by the @code{Bar_engraver}.
783 Polyphonic parts, i.e. parts with more than one voice on a staff can be
784 typeset with LilyPond. To use this, instantiate a separate Voice
785 context for each part, and assign a stem direction to each part.
786 @lilypond[fragment,verbatim]
788 < \context Voice = VA { \stemUp b'4 a' g' f' e' }
789 \context Voice = VB { \stemDown g'4 g' g' g' g' } >
792 When there are more than two voices on a staff, you must also indicate
793 which voice should moved horizontally in case of a collision. This can
794 be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
795 @code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift}
796 in @code{NoteColumn}).
798 @lilypond[fragment, verbatim]
799 \context Staff \notes\relative c''<
806 \context Voice=three {
807 \shiftOnn \stemUp ais
809 \context Voice=four {
810 \shiftOnnn \stemUp fis
815 The most convenient way is to use the identifiers @code{\voiceOne}
816 through @code{\voiceFour}, which also set slur and tie directions in the
819 @lilypond[singleline, verbatim]
821 \context Staff < \context Voice = VA { \voiceOne cis2 b }
822 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
823 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
826 Normally, note heads with a different number of dots are not merged, but
827 if you set the grob property @code{merge-differently-dotted}, they are:
829 @lilypond[verbatim,fragment,singleline]
831 \context Voice = VA { \voiceOne
833 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
836 \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] }
840 LilyPond also vertically shifts rests that are opposite of a stem.
842 @lilypond[singleline,verbatim]
844 \context Voice { \stemUp c''4 }
845 \context Voice =VB { r4 }
849 Note head collisions (horizontal shifting of note heads) are handled by
850 the @code{NoteCollision} grob. @code{RestCollision} handles vertical
853 @cindex @code{NoteCollision}
854 @cindex @code{RestCollision}
859 Resolving collisions is a very intricate subject, and LilyPond only
860 handles a few situations. When it can not cope, you are advised to use
861 @code{force-hshift} of the NoteColumn grob and @code{staff-position} of
862 the Rest grob to override typesetting decisions.
867 Beams are used to group short notes into chunks that are aligned with
868 the metrum. LilyPond guesses where beams should be inserted. If you're
869 not satisfied with the automatic beaming, you can specify which patterns
870 to beam automatically. In specific cases, you can also enter the beams
874 @c . {Automatic beams}
875 @subsection Automatic beams
877 @cindex @code{Voice.autoBeamSettings}
878 @cindex @code{(end * * * *)}
879 @cindex @code{(begin * * * *)}
882 In normal time signatures, automatic beams can start on any note but can
883 only end in a few positions within the measure: beams can end on a beat,
884 or at durations specified by the properties in
885 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
886 are defined in @file{scm/auto-beam.scm}.
888 The value of @code{autoBeamSettings} is changed using
889 @code{\override} and unset using @code{\revert}:
891 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
892 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
894 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
895 whether the rule applies to begin or end-points. The quantity
896 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
897 *}' designates notes of any length), @var{N}/@var{M} refers to a time
898 signature (wildcards, `@code{* *}' may be entered to designate all time
901 For example, if you want automatic beams to end on every quarter note,
902 you can use the following:
904 \property Voice.autoBeamSettings \override
905 #'(end * * * *) = #(make-moment 1 4)
907 Since the duration of a quarter note is 1/4 of a whole note, it is
908 entered as @code{(make-moment 1 4)}.
910 The same syntax can be used to specify beam starting points. In this
911 example, automatic beams can only end on a dotted quarter note.
913 \property Voice.autoBeamSettings \override
914 #'(end * * * *) = #(make-moment 3 8)
916 In 4/4 time signature, this means that automatic beams could end only on
917 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
918 3/8 has passed within the measure).
920 You can also restrict rules to specific time signatures. A rule that
921 should only be applied in @var{N}/@var{M} time signature is formed by
922 replacing the second asterisks by @var{N} and @var{M}. For example, a
923 rule for 6/8 time exclusively looks like
925 \property Voice.autoBeamSettings \override
926 #'(begin * * 6 8) = ...
929 If you want a rule to apply to certain types of beams, you can use the
930 first pair of asterisks. Beams are classified according to the shortest
931 note they contain. For a beam ending rule that only applies to beams
932 with 32nd notes (and no shorter notes), you would use @code{(end 1
936 @c Automatic beams can not be put on the last note in a score.
938 If a score ends while an automatic beam has not been ended and is still
939 accepting notes, this last beam will not be typeset at all.
941 @cindex automatic beam generation
943 @cindex @code{Voice.noAutoBeaming}
945 Automatic beaming is on by default, but can be switched off by setting
946 @code{Voice.noAutoBeaming} to true. You you may find this necessary for
947 a melody that goes with lyrics.
951 It is not possible to specify beaming parameters for beams with mixed
952 durations, that differ from the beaming parameters of all separate
953 durations, i.e., you'll have to specify manual beams to get:
954 @lilypond[fragment,singleline,relative]
955 \property Voice.autoBeamSettings
956 \override #'(end * * * *) = #(make-moment 3 8)
957 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
960 It is not possible to specify beaming parameters that act differently in
961 different parts of a measure. This means that it is not possible to use
962 automatic beaming in irregular meters such as @code{5/8}.
965 @cindex Automatic beams
966 @subsection Manual beams
967 @cindex beams, manual
971 In some cases it may be necessary to override LilyPond's automatic
972 beaming algorithm. For example, the auto beamer will not beam over
973 rests or bar lines, If you want that, specify the begin and end point
974 manually using a @code{[} before the first beamed note and a @code{]}
977 @lilypond[fragment,relative,verbatim]
979 r4 [r8 g' a r8] r8 [g | a] r8
982 Whenever an manual beam is busy, the automatic beamer will not produce
985 @cindex @code{stemLeftBeamCount}
987 Normally, beaming patterns within a beam are determined automatically.
988 When this mechanism fouls up, the properties
989 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. can
990 be used to control the beam subdivision on a stem. If you set either
991 property, it's value will be used only once, and then it is erased.
993 @lilypond[fragment,relative,verbatim]
996 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
999 @cindex @code{stemRightBeamCount}
1001 The beam symbol (grob @code{Voice.Beam}, both for automatic and manual
1002 beams) can be tweaked through grob-properties @code{height} and
1003 @code{staff-position}. These specify vertical location and vertical
1004 span. Both are measured in half staff-spaces, @code{staff-position=0}
1005 corresponds to the middle staff line.
1008 Set @code{height} to zero, to get horizontal beams:
1010 @lilypond[fragment,relative,verbatim]
1011 \property Voice.Beam \set #'direction = #1
1012 \property Voice.Beam \set #'height = #0
1016 Here's how you'd specify a weird looking beam that instead of being
1017 horizontal, falls two staff spaces:
1019 @lilypond[fragment,relative,verbatim]
1020 \property Voice.Beam \set #'staff-position = #4
1021 \property Voice.Beam \set #'height = #-4
1024 @cindex @code{default-neutral-direction}
1026 @node Expressive marks
1027 @section Expressive marks
1042 A slur indicates that notes are to be played bound or @emph{legato}.
1043 They are entered using parentheses:
1045 @lilypond[fragment,verbatim,center]
1046 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1050 Slurs avoid crossing stems, and are generally attached to note heads.
1051 However, in some situations with beams, slurs may be attached to stem
1052 ends. If you want to override this layout you can do this through the
1053 @code{Voice.Slur}'s grob-property @code{attachment}. It's value is a
1054 pair of symbols, specifying the attachment type of the left and right end points.
1056 @lilypond[fragment,relative,verbatim]
1057 \property Voice.Slur \set #'direction = #1
1058 \property Voice.Stem \set #'length = #5.5
1060 \property Voice.Slur \set #'attachment = #'(stem . stem)
1064 If a slur would strike through a stem or beam, the slur will be moved
1065 away upward or downward. If this happens, attaching the slur to the
1066 stems might look better:
1068 @lilypond[fragment,relative,verbatim]
1069 \property Voice.Stem \set #'direction = #1
1070 \property Voice.Slur \set #'direction = #1
1072 \property Voice.Slur \set #'attachment = #'(stem . stem)
1077 Similarly, the curvature of a slur is adjusted to stay clear of note
1078 heads and stems. When that would increase the curvature too much, the
1079 slur is reverted to its default shape. The threshold for this decision
1080 is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely
1081 related to the enclosed area between the slur and the notes. Usually,
1082 the default setting works well, but in some cases you may prefer a
1083 curved slur when LilyPond decides for a vertically moved one. You can
1084 indicate this preference by increasing the @code{beautiful} value:
1086 @lilypond[verbatim,singleline,relative]
1087 \property Voice.Beam \override #'direction = #-1
1088 \property Voice.Slur \override #'direction = #1
1089 c16( a' f' a a f a, )c,
1090 c( a' f' a a f d, )c
1091 \property Voice.Slur \override #'beautiful = #5.0
1092 c( a' f' a a f d, )c
1097 @code{beautiful} is an arbitrary parameter in the slur formatter.
1098 Useful values can only be determined by trial and error.
1100 @cindex Adjusting slurs
1102 @node Phrasing slurs
1103 @subsection Phrasing slurs
1105 @cindex phrasing slurs
1106 @cindex phrasing marks
1108 A phrasing slur (or phrasing mark) connects chords and is used to
1109 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1112 @lilypond[fragment,verbatim,center,relative]
1113 \time 6/4 c' \( ( d ) e f ( e ) \) d
1116 Typographically, the phrasing slur behaves almost exactly like a normal
1117 slur. The grob associated with it is @code{Voice.PhrasingSlur}.
1120 @subsection Breath marks
1122 Breath marks are entered using @code{\breathe}. The result is a
1123 @code{Voice.BreathingSign} grob.
1125 @lilypond[fragment,relative]
1134 Currently, only tick marks are supported, not comma style breath marks.
1141 @cindex beats per minute
1142 @cindex metronome marking
1144 Metronome settings can be entered as follows:
1146 @cindex @code{\tempo}
1148 \tempo @var{duration} = @var{perminute}
1151 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1156 The tempo setting is not printed, but is only used in the MIDI
1157 output. You can trick lily into producing a metronome mark,
1158 though. Details are in @ref{Text markup}.
1163 @subsection Text spanners
1164 @cindex Text spanners
1166 Some textual indications, e.g. rallentando or accelerando, often extend
1167 over many measures. This is indicated by following the text with a
1168 dotted line. You can create such texts using text spanners. The syntax
1171 \spanrequest \start "text"
1172 \spanrequest \stop "text"
1174 LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The
1175 string to be printed, as well as the style is set through grob
1178 An application---or rather, a hack---is to fake octavation indications.
1179 @lilypond[fragment,relative,verbatim]
1180 \relative c' { a''' b c a
1181 \property Voice.TextSpanner \set #'type = #'dotted-line
1182 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1183 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1184 \property Staff.centralCPosition = #-13
1185 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1203 @subsection Articulations
1204 @cindex Articulations
1206 @cindex articulations
1210 A variety of symbols can appear above and below notes to indicate
1211 different characteristics of the performance. These symbols can be
1212 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1213 are defined in @file{script.ly}. Symbols can be forced to appear above
1214 or below the note by writing `@var{note}@code{^\}@var{name}' and
1215 `@var{note}@code{_\}@var{name}' respectively. Here is a chart showing
1216 symbols on notes, with the name of the corresponding symbol appearing
1222 \property Score.LyricSyllable \override #'font-family =#'typewriter
1223 \property Score.LyricSyllable \override #'font-shape = #'upright
1224 \context Staff \notes {
1225 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1226 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1227 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1228 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1229 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1230 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1231 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1232 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1234 \context Lyrics \lyrics {
1235 accent__ marcato__ staccatissimo__ fermata
1236 stopped__ staccato__ tenuto__ upbow
1237 downbow__ lheel__ rheel__ ltoe
1238 rtoe__ turn__ open__ flageolet
1239 reverseturn__ trill__ prall__ mordent
1240 prallprall__ prallmordent__ uprall__ downprall
1241 upmordent__ downmordent__ pralldown__ prallup__
1242 lineprall__ thumb__ segno__ coda
1246 linewidth = 5.875\in
1252 To save typing work, some shorthands are available:
1253 @lilypond[singleline]
1255 \notes \context Voice {
1256 \property Voice.TextScript \set #'font-family = #'typewriter
1257 \property Voice.TextScript \set #'font-shape = #'upright
1263 c''4-^_"c-\\^{ }" s4
1270 Fingering instructions can also be entered in this shorthand.
1271 @lilypond[verbatim, singleline, fragment]
1272 c'4-1 c'4-2 c'4-3 c'4-4
1276 @cindex @code{\script}
1281 You can add scripts by editing @file{scm/script.scm}. This file contains
1282 a table, listing script definitions and aliases. The following syntax
1283 accesses a script definition from the table:
1289 Usually the @code{\script} keyword is not used directly. Various
1290 helpful identifier definitions appear in @file{script.ly}.
1292 Grobs for these objects are @code{Script} and @code{Fingering}.
1296 All of these note ornaments appear in the printed output but have no
1297 effect on the MIDI rendering of the music.
1299 Unfortunately, there is no support for adding fingering instructions or
1300 ornaments to individual note heads. Some hacks exist, though. See
1301 @file{input/test/script-horizontal.ly}.
1306 @subsection Text scripts
1307 @cindex Text scripts
1309 In addition, it is possible to place arbitrary strings of text or markup
1310 text (see @ref{Text markup}) above or below notes by using a string:
1313 By default, these indications do not influence the note spacing, but
1314 if @code{Voice.textNonEmpty} is set to true the widths will be taken
1315 into account. The identifier @code{\fatText} is defined in the standard
1317 @lilypond[fragment,singleline,verbatim]
1318 \relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
1321 Text scripts are created in form of @code{Voice.TextScript} grobs.
1323 @ref{Text markup} describes how to change the font or access
1324 special symbols in text scripts.
1328 @subsection Grace notes
1337 @cindex @code{\grace}
1340 @cindex @code{graceAlignPosition}
1342 Grace notes are ornaments that are written out, but do not take up any
1343 logical time in a measure. LilyPond has limited support for grace notes.
1344 The syntax is as follows.
1346 \grace @var{musicexpr}
1349 Unbeamed eighth notes and shorter by default have a slash through the
1352 @lilypond[fragment,verbatim]
1354 \grace c8 c4 \grace { [c16 c16] } c4
1356 \property Voice.Stem \override #'flag-style = #'()
1358 \property Voice.Stem \revert #'flag-style
1363 A grace note expression has duration 0; the next real note is assumed to
1364 be the main note. If you want the note to appear after the main note,
1365 set @code{Voice.graceAlignPosition} to @code{1}.
1369 Nesting @code{\grace} notes is not supported. The following may cause
1370 run-time errors: @example
1371 @code{\grace @{ \grace c32 c16 @} c4}
1373 Since the meaning of such a construct is unclear, we don't consider this
1374 a loss. Similarly, juxtaposing two @code{\grace} sections is
1375 syntactically valid, but makes no sense and may cause runtime errors.
1376 Ending a staff or score with grace notes may also generate a run-time
1377 error, since there will be no main note to attach the grace notes to.
1388 @subsection Glissando
1391 @cindex @code{\glissando}
1393 A glissando line (grob @code{Voice.Glissando}) can be requested by attaching a
1394 @code{\glissando} to a note:
1396 @lilypond[fragment,relative,verbatim]
1402 Printing of an additional text (such as @emph{gliss.}) must be done
1409 @subsection Dynamics
1422 @cindex @code{\ffff}
1432 Absolute dynamic marks are specified using an identifier after a
1433 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1434 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1435 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1436 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1438 @lilypond[verbatim,singleline,fragment,relative]
1439 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1445 @cindex @code{\decr}
1446 @cindex @code{\rced}
1452 A crescendo mark is started with @code{\cr} and terminated with
1453 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1454 started with @code{\decr} and terminated with @code{\rced}. There are
1455 also shorthands for these marks. A crescendo can be started with
1456 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1457 can be terminated with @code{\!}. Note that @code{\!} must go before
1458 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1459 after the last note. Because these marks are bound to notes, if you
1460 want several marks during one note, you have to use spacer notes.
1462 @lilypond[fragment,verbatim,center]
1463 c'' \< \! c'' d'' \decr e'' \rced
1464 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1467 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1468 is an example how to do it:
1473 @lilypond[fragment,relative,verbatim]
1475 \property Voice.crescendoText = "cresc."
1476 \property Voice.crescendoSpanner = #'dashed-line
1481 For everyday use, we recommend the identifiers @code{\cresc},
1482 @code{endcresc}, @code{\dim} and @code{\enddim}.
1486 Dynamics are grobs of @code{Voice.DynamicText} and
1487 @code{Voice.Hairpin}. They are put together on
1488 @code{Voice.DynamicLineSpanner} to align them vertically.
1497 @cindex @code{\repeat}
1499 To specify repeats, use the @code{\repeat} keyword. Since repeats
1500 should work differently when played or printed, there are a few
1501 different variants of repeats.
1505 Repeated music is fully written (played) out. Useful for MIDI
1506 output, and entering repetitive music.
1509 This is the normal notation: Repeats are not written out, but
1510 alternative endings (voltas) are printed, left to right.
1513 Alternative endings are written stacked. This has limited use but may be
1514 used to typeset two lines of lyrics in songs with repeats, see
1515 @file{input/star-spangled-banner.ly}.
1521 Make beat or measure repeats. These look like percent signs.
1527 * Manual repeat commands::
1529 * Tremolo subdivisions::
1534 @subsection Repeat syntax
1536 The syntax for repeats is
1539 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1542 If you have alternative endings, you may add
1543 @cindex @code{\alternative}
1545 \alternative @code{@{} @var{alternative1}
1547 @var{alternative3} @dots{} @code{@}}
1549 where each @var{alternative} is a music expression.
1551 Normal notation repeats are used like this:
1552 @lilypond[fragment,verbatim]
1554 \repeat volta 2 { c'4 d' e' f' }
1555 \repeat volta 2 { f' e' d' c' }
1558 With alternative endings:
1559 @lilypond[fragment,verbatim]
1561 \repeat volta 2 {c'4 d' e' f'}
1562 \alternative { {d'2 d'} {f' f} }
1565 Folded repeats look like this:
1568 @lilypond[fragment,verbatim]
1570 \repeat fold 2 {c'4 d' e' f'}
1571 \alternative { {d'2 d'} {f' f} }
1575 If you don't give enough alternatives for all of the repeats, then
1576 the first alternative is assumed to be repeated often enough to equal
1577 the specified number of repeats.
1579 @lilypond[fragment,verbatim]
1583 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1584 \alternative { { g4 g g } { a | a a a a | b2. } }
1591 Notice that timing information is not remembered at the start of an
1592 alternative, so you have to reset timing information after a repeat,
1593 e.g. using a bar-check (See @ref{Bar check}), setting
1594 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1595 are also not repeated.
1597 It is possible to nest @code{\repeat}s, although this probably is only
1598 meaningful for unfolded repeats.
1600 Folded repeats offer little more over simultaneous music. However, it
1601 is to be expected that more functionality -- especially for the MIDI
1602 backend -- will be implemented at some point in the future.
1604 Volta repeats are printed over all staves in a score. You must turn them
1605 off explicitly, for example by doing
1607 \property Staff.VoltaBracket = \turnOff
1609 in all but the top staff.
1611 @node Manual repeat commands
1612 @subsection Manual repeat commands
1614 @cindex @code{repeatCommands}
1616 The property @code{repeatCommands} can be used to control the layout of
1617 repeats. Its value is a Scheme list of repeat commands, where each repeat
1625 @item (volta . @var{text})
1626 Print a volta bracket saying @var{text}.
1628 Stop a running volta bracket
1631 @lilypond[verbatim, fragment]
1633 \property Score.repeatCommands = #'((volta "93") end-repeat)
1635 \property Score.repeatCommands = #'((volta #f))
1640 Repeats brackets are @code{Staff.VoltaBracket} grobs.
1642 @node Tremolo repeats
1643 @subsection Tremolo repeats
1644 @cindex tremolo beams
1646 To place tremolo marks between notes, use @code{\repeat} with tremolo
1648 @lilypond[verbatim,center,singleline]
1650 \context Voice \notes\relative c' {
1651 \repeat "tremolo" 8 { c16 d16 }
1652 \repeat "tremolo" 4 { c16 d16 }
1653 \repeat "tremolo" 2 { c16 d16 }
1654 \repeat "tremolo" 4 c16
1659 Tremolo beams are @code{Voice.Beam} grobs. Single stem tremolos are
1660 @code{Voice.StemTremolo}.
1665 At present, the spacing between tremolo beams is not regular, since the
1666 spacing engine does not notice that not all notes are printed.
1668 @node Tremolo subdivisions
1669 @subsection Tremolo subdivisions
1670 @cindex tremolo marks
1671 @cindex @code{tremoloFlags}
1673 Tremolo marks can be printed on a single note by adding
1674 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1675 A @var{length} value of 8 gives one line across the note stem. If the
1676 length is omitted, then then the last value (stored in
1677 @code{Voice.tremoloFlags}) is used.
1679 @lilypond[verbatim,fragment,center]
1680 c'2:8 c':32 | c': c': |
1686 Tremolos in this style do not carry over into the MIDI output.
1689 @node Measure repeats
1690 @subsection Measure repeats
1692 @cindex percent repeats
1693 @cindex measure repeats
1695 In the @code{percent} style, a note pattern can be repeated. It is
1696 printed once, and then the pattern is replaced with a special sign.
1697 Patterns of a one and two measures are replaced by percent-like signs,
1698 patterns that divide the measure length are replaced by slashes.
1700 @lilypond[verbatim,singleline]
1701 \context Voice { \repeat "percent" 4 { c'4 }
1702 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1706 The signs are represented by these grobs: @code{Voice.RepeatSlash} and
1707 @code{Voice.PercentRepeat} and @code{Voice.DoublePercentRepeat}.
1711 You can not nest percent repeats, e.g. by filling in the first measure
1712 with slashes, and repeating that measure with percents.
1714 @node Rhythmic music
1715 @section Rhythmic music
1722 @node Rhythmic staves
1723 @subsection Rhythmic staves
1725 Sometimes you might want to show only the rhythm of a melody. This can
1726 be done with the rhythmic staff. All pitches of notes on such a staff
1727 are squashed, and the staff itself looks has a single staff line:
1729 @lilypond[fragment,relative,verbatim]
1730 \context RhythmicStaff {
1732 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1739 @section Piano music
1741 Piano music is an odd type of notation. Piano staves are two normal
1742 staves coupled with a brace. The staves are largely independent, but
1743 sometimes voices can cross between the two staves. The
1744 @code{PianoStaff} is especially built to handle this cross-staffing
1745 behavior. In this section we discuss the @code{PianoStaff} and some
1746 other pianistic peculiarities.
1749 * Automatic staff changes::
1750 * Manual staff switches::
1753 * Voice follower lines::
1757 @c . {Automatic staff changes}
1758 @node Automatic staff changes
1759 @subsection Automatic staff changes
1760 @cindex Automatic staff changes
1762 Voices can switch automatically between the top and the bottom
1763 staff. The syntax for this is
1765 \autochange @var{contexttype} @var{musicexp}
1767 This will switch the interpretation context of @var{musicexp} between a
1768 @var{contexttype} named @code{up} and @code{down}. Typically, you use
1769 @code{Staff} for @var{contexttype}. The autochanger switches on basis
1770 of pitch (central C is the turning point), and it looks ahead skipping
1771 over rests to switch rests in advance.
1773 @lilypond[verbatim,singleline]
1774 \score { \notes \context PianoStaff <
1775 \context Staff = "up" {
1776 \autochange Staff \context Voice = VA < \relative c' {
1777 g4 a b c d r4 a g } > }
1778 \context Staff = "down" {
1784 Note how spacer rests are used to prevent the bottom staff from
1785 terminating too soon.
1788 @node Manual staff switches
1789 @subsection Manual staff switches
1791 @cindex manual staff switches
1792 @cindex staff switch, manual
1794 Voices can be switched between staves manually, using the following command:
1796 \translator Staff = @var{staffname} @var{music}
1798 The string @var{staffname} is the name of the staff. It switches the
1799 current voice from its current staff to the Staff called
1800 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1803 The formal definition of this construct is obtuse, but for the sake of
1804 completeness we give it here.
1805 @cindex @code{\translator}
1807 \translator @var{contexttype} = @var{name}
1809 Formally, this construct is a music expression indicating
1810 that the context which is a direct child of the context of type
1811 @var{contexttype} should be shifted to a context of type
1812 @var{contexttype} and the specified name.
1820 Piano pedal instruction can be expressed using
1821 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
1822 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1824 These identifiers are shorthands for spanner commands of the types
1825 @code{Sustain}, @code{UnaCorda} and @code{Sostenuto}:
1827 @lilypond[fragment,verbatim]
1828 c''4 \spanrequest \start "Sustain" c''4
1829 c''4 \spanrequest \stop "Sustain"
1832 The symbols that are printed can be modified by setting
1833 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal
1834 types. Refer to the generated documentation of @rgrob{PianoPedal} for
1840 Currently, brackets are not supported, only text markings (i.e. `*Ped'
1846 @subsection Arpeggio
1849 @cindex broken arpeggio
1850 @cindex @code{\arpeggio}
1852 You can specify an arpeggio sign on a chord by attaching an
1853 @code{\arpeggio} to a note of the chord.
1856 @lilypond[fragment,relative,verbatim]
1857 \context Voice <c\arpeggio e g c>
1860 When an arpeggio crosses staves in piano music, you attach an arpeggio
1861 to the chords in both staves, and set
1862 @code{PianoStaff.connectArpeggios}.
1864 @lilypond[fragment,relative,verbatim]
1865 \context PianoStaff <
1866 \property PianoStaff.connectArpeggios = ##t
1867 \context Voice = one { <c'\arpeggio e g c> }
1868 \context Voice = other { \clef bass <c,,\arpeggio e g>}
1872 This command creates @code{Voice.Arpeggio} grobs. Cross staff arpeggios
1873 are @code{PianoStaff.Arpeggio}.
1877 It is not possible to mix connected arpeggios and unconnected arpeggios
1882 @node Voice follower lines
1883 @subsection Voice follower lines
1885 @cindex follow voice
1886 @cindex staff switching
1889 @cindex @code{followVoice}
1891 Whenever a voice switches to another staff a line connecting the notes
1892 can be printed automatically. This is enabled if the property
1893 @code{PianoStaff.followVoice} is set to true:
1895 @lilypond[fragment,relative,verbatim]
1896 \context PianoStaff <
1897 \property PianoStaff.followVoice = ##t
1898 \context Staff \context Voice {
1900 \translator Staff=two
1903 \context Staff=two {\clef bass \skip 1*2 }
1907 The associated grob is @code{Voice.VoiceFollower}.
1917 * Automatic syllable durations::
1923 @subsection Lyrics mode
1926 To print lyrics, you must first make a music expression from the lyric
1927 text. That music expression can be printed by selecting an appropriate
1931 @cindex @code{\lyrics}
1933 You can enter lyrics in a special input mode of LilyPond. This mode is
1934 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1935 The purpose of this mode is that you can enter lyrics as plain text,
1936 punctuation and accents without any hassle.
1938 Syllables are entered like notes, with pitches replaced by text. For
1939 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1940 the hyphen has no special meaning for lyrics, and does not introduce
1943 Spaces can be introduced into a lyric either by using quotes:
1944 @code{"He could"4 not4} or by using an underscore without quotes:
1945 @code{He_could4 not4}. All unquoted underscores are converted to
1948 The precise definition of this mode can be found in @ref{Lyrics mode
1951 @c . {Printing lyrics}
1952 @node Printing lyrics
1953 @subsection Printing lyrics
1956 Lyrics are printed by interpreting them in the @code{Lyrics} context.
1958 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
1960 @lilypond[verbatim,singleline]
1961 \addlyrics \notes \relative c' {
1963 \property Staff.automaticMelismata = ##t
1964 d'2 c4 b16 ( a g a b a b ) c a2
1965 b2 c4 b8 ( a16 g ) a4 g2 }
1966 \context Lyrics \lyrics {
1968 share the soft -- ware; }
1972 Notes and syllable durations are matched automatically. This is
1973 accomplished using @code{\addlyrics}, which is documented in
1974 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
1975 the melody staff will cause slurs to be interpreted as melismata.
1977 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
1980 @cindex lyric extender
1983 As you can see, extender lines are entered as @code{__}. This will
1984 create an extender, a line that extends over the entire duration of the
1985 lyric. This line will run all the way to the start of the next lyric,
1986 so you may want to shorten it by using a blank lyric (using @code{_}).
1987 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
1992 If you want to have hyphens centered between syllables (rather than
1993 attached to the end of the first syllable) you can use the special
1994 `@code{-}@code{-}' lyric as a separate word between syllables. This
1995 will result in a hyphen whose length varies depending on the space
1996 between syllables. It will be centered between the syllables. The grob
1997 for this symbol is @code{LyricsVoice.LyricHyphen}.
1999 @cindex Lyric hyphen
2001 @node Automatic syllable durations
2002 @subsection Automatic syllable durations
2003 @cindex Automatic syllable durations
2005 @cindex automatic lyric durations
2006 @cindex @code{\addlyrics}
2008 If you have lyrics that are set to a melody, you can copy the rhythm
2009 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2012 \addlyrics @var{musicexpr1 musicexpr2}
2015 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2016 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2017 when there are events in @var{musicexpr1}.
2019 @cindex @code{automaticMelismata}
2021 If the property @code{automaticMelismata} is set in the
2022 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2025 @lilypond[verbatim,fragment]
2028 \property Voice.automaticMelismata = ##t
2029 c8 () cis d8. e16 f2
2031 \context Lyrics \lyrics {
2035 If you want the lyric lines to be above the melody staff, or in some
2036 other, more complex configuration, then build that configuration first
2037 using simultaneous music, and use @code{\addlyrics} after that.
2039 @lilypond[verbatim, singleline]
2041 \context Lyrics = LA { s1 }
2042 \context Staff = SA { s1 }
2044 \context Staff = SA \relative c' { c4 e g g }
2045 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2048 For @code{\addlyrics} you should use a single rhythm melody, and single
2049 rhythm lyrics (a constant duration is the obvious choice). If you do
2050 not, you can get undesired effects when using multiple stanzas:
2052 @lilypond[verbatim,fragment]
2055 c8 () cis d8. e16 f2
2057 \context Lyrics \lyrics
2062 It is valid (but probably not very useful) to use notes instead of
2063 lyrics for @var{musicexpr2}.
2066 @subsection More stanzas
2070 If you have multiple stanzas printed underneath each other, the vertical
2071 groups of syllables should be aligned around punctuation. LilyPond can
2072 do this if you tell it which lyric lines belong to which melody.
2074 To this end, give the Voice context an identity, and set the LyricsVoice
2075 to a name starting with that identity followed by a dash.
2076 In the following example, the Voice
2077 identity is @code{duet}, and the identities of the LyricsVoices are
2078 @code{duet-1} and @code{duet-2}.
2081 @lilypond[singleline,verbatim]
2084 \notes \relative c'' \context Voice = duet { \time 3/4
2086 \lyrics \context Lyrics <
2087 \context LyricsVoice = "duet-1" {
2088 \property LyricsVoice . stanza = "Bert"
2089 Hi, my name is bert. }
2090 \context LyricsVoice = "duet-2" {
2091 \property LyricsVoice . stanza = "Ernie"
2092 Ooooo, ch\'e -- ri, je t'aime. }
2097 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2098 first system) and @code{LyricsVoice.stz} for the following
2099 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2105 @cindex stanza numbering
2113 LilyPond has support for both entering and printing chords. Chords are
2114 characterized by a set of pitches. They are
2115 internally stored as simultaneous music expressions. This means you can
2116 enter chords by name and print them as note head, enter them as notes
2117 and print them as chord names, or (the most common case) enter them by
2118 name, and print them as name.
2121 @lilypond[verbatim,singleline]
2122 twoWays = \notes \transpose c'' {
2132 < \context ChordNames \twoWays
2133 \context Voice \twoWays > }
2136 Note that this example also shows that the chord printing routines do
2137 not attempt to be intelligent. If you enter @code{f bes d}, it does not
2138 interpret this as an inversion.
2142 * Printing named chords::
2147 @subsection Chords mode
2150 Chord mode is a mode where you can input sets of pitches using common
2151 names. It is introduced by the keyword @code{\chords}. It is similar
2152 to note mode, but words are also looked up in a chord modifier table
2153 (containing @code{maj}, @code{dim}, etc).
2155 Dashes and carets are used to indicate chord additions and subtractions,
2156 so articulation scripts can not be entered in Chord mode.
2158 The syntax for named chords is as follows:
2160 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2163 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2164 the chord duration in the usual notation. There are two kinds of
2165 modifiers. One type is formed by @emph{chord additions}. Additions are
2166 obtained by listing intervals separated by dots. An interval is written
2167 by its number with an optional @code{+} or @code{-} to indicate raising
2168 or lowering by half a step. Chord additions have two effects: they adds
2169 the specified interval and all lower odd numbered intervals to the
2170 chord, and they may lower or raise the specified interval.
2172 Throughout these examples, chords have been shifted around the staff
2173 using @code{\transpose}.
2175 @lilypond[fragment,verbatim]
2179 c:9 c:9-.5+.7+ c:3-.5-
2189 The second type of modifier that may appear after the @code{:} is a
2190 named modifier. Named modifiers are listed in the file
2191 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2192 @code{min} which lower the 3rd half a step, `@code{aug}' which
2193 raises the 5th, `@code{dim}' which lowers the 5th,
2194 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2195 which replaces the 5th with a 4th.
2197 @lilypond[fragment,verbatim]
2200 c1:m c:min7 c:maj c:aug c:dim c:sus
2206 Chord subtractions are used to eliminate notes from a chord. The
2207 notes to be subtracted are listed after a @code{^} character,
2210 @lilypond[fragment,verbatim,center]
2219 Chord inversions can be specified by appending `@code{/}' and the name
2220 of a single note to a chord. In a chord inversion, the inverted note is
2221 transposed down until it is the lowest note in the chord. If the note
2222 is not in the chord, a warning will be printed.
2224 @lilypond[fragment,verbatim,center]
2234 Bass notes can be added by `@code{/+}' and
2235 the name of a single note to a chord. This has the effect of
2236 adding the specified note to the chord, lowered by an octave,
2237 so it becomes the lowest note in the chord.
2239 @lilypond[fragment,verbatim,center]
2250 Implementation details are quite gory. For example @code{c:4} not only
2251 adds a fourth, but also removes the third.
2254 @c . {Printing named chords}
2255 @node Printing named chords
2256 @subsection Printing named chords
2258 @cindex printing chord names
2261 @cindex @code{ChordNames}
2264 For displaying printed chord names, use the @code{ChordNames} context.
2265 The chords may be entered either using the notation described above, or
2266 directly using simultaneous music.
2268 @lilypond[verbatim,singleline]
2270 \chords {a1 b c} <d f g> <e g b>
2274 \context ChordNames \scheme
2275 \context Staff \transpose c'' \scheme
2280 You can make the chord changes stand out by setting
2281 @code{ChordNames.chordChanges} to true. This will only display chord
2282 names when there's a change in the chords scheme and at the start of a
2287 c1:m c:m \break c:m c:m d
2291 \context ChordNames {
2292 \property ChordNames.chordChanges = ##t
2294 \context Staff \transpose c'' \scheme
2298 LilyPond examines chords specified as lists of notes to determine a name
2299 to give the chord. LilyPond will not try to identify chord inversions or
2300 an added bass note, which may result in strange chord names when chords
2301 are entered as a list of pitches:
2303 @lilypond[verbatim,center,singleline]
2312 \context ChordNames \scheme
2313 \context Staff \scheme
2319 By default, a chord name system proposed by Harald Banter (See
2320 @ref{Literature}) is used. The system is very regular and predictable.
2321 Typical American style chord names may be selected by setting the
2322 @code{style} property of the @code{ChordNames.ChordName} grob to
2323 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2325 Routines that determine the names to be printed are written in Scheme,
2326 and may be customized by the user. The code can be found in
2327 @file{scm/chord-name.scm}. Here's an example showing the differences in
2331 @c maybe just junk verbatim option?
2332 @lilypond[verbatim,singleline]
2342 \context ChordNames = banter \scheme
2343 \context ChordNames = american {
2344 \property ChordNames.ChordName \override
2345 #'style = #'american \scheme }
2346 \context ChordNames = jazz {
2347 \property ChordNames.ChordName \override
2348 #'style = #'jazz \scheme }
2349 \context Staff \transpose c'' \scheme
2356 @section Writing parts
2358 Orchestral music involves some special notation, both in the full score,
2359 as in the individual parts. This section explains how to tackle common
2360 problems in orchestral music.
2367 * Instrument names::
2369 * Sound output for transposing instruments::
2370 * Multi measure rests::
2371 * Automatic part combining::
2372 * Hara kiri staves::
2375 @c . {Rehearsal marks}
2376 @node Rehearsal marks
2377 @subsection Rehearsal marks
2378 @cindex Rehearsal marks
2380 @cindex @code{\mark}
2381 @cindex @code{Mark_engraver}
2384 \mark @var{unsigned}
2389 This command prints a rehearsal mark above the system. You can provide
2390 a number, a string or a markup text as argument. If you use
2391 @code{\default}, the value of property @code{rehearsalMark} is used and
2392 automatically incremented.
2394 @lilypond[fragment,verbatim]
2400 c1 \mark #'(music "scripts-segno")
2405 The grob is @code{Score.RehearsalMark}. See
2406 @code{input/test/boxed-molecule.ly} if you need boxes around the marks.
2409 @subsection Bar numbers
2411 Bar numbers (grob: @code{BarNumber}) are printed at the start of the
2412 line. See @code{input/test/boxed-molecule.ly} for boxed bar numbers.
2416 It is not possible to have bar numbers printed at regular intervals
2419 @node Instrument names
2420 @subsection Instrument names
2422 You can specify an instrument name for a staff by setting
2423 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2424 before the start of the staff. For the first start, @code{instrument} is
2425 used, for the next ones @code{instr} is used.
2427 @lilypond[verbatim,singleline]
2428 \property Staff.instrument = "ploink " { c''4 }
2431 You can also use markup texts to construct more complicated instrument
2435 @lilypond[verbatim,singleline]
2437 '((font-relative-size . -2 ) (music "accidentals--1")))
2440 \property Staff.instrument = #`((kern . 0.5) (lines
2441 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2449 When you put a name on a grand staff or piano staff the width of the
2450 brace is not taken into account. You must add extra spaces to the end of
2451 the name to avoid a collision.
2454 @subsection Transpose
2456 @cindex transposition of pitches
2457 @cindex @code{\transpose}
2459 A music expression can be transposed with @code{\transpose}. The syntax
2462 \transpose @var{pitch} @var{musicexpr}
2465 This means that middle C in @var{musicexpr} is transposed to
2468 @code{\transpose} distinguishes between enharmonic pitches: both
2469 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2470 a tone. The first version will print sharps and the second version
2473 @lilypond[fragment,verbatim]
2476 { \key e \major c d e f }
2478 \transpose des'' { \key e \major c d e f }
2479 \transpose cis'' { \key e \major c d e f }
2483 If you want to use both @code{\transpose} and @code{\relative}, then
2484 you must use @code{\transpose} first. @code{\relative} will have no
2485 effect music that appears inside a @code{\transpose}.
2487 @node Sound output for transposing instruments
2488 @subsection Sound output transposing instruments
2490 When you want to make a MIDI file from a score containing transposed and
2492 instruments, you have to instruct LilyPond the pitch offset (in
2493 semitones) for the transposed instruments. This is done using the
2494 @code{transposing} property. It does not affect printed output.
2496 @cindex @code{transposing}
2499 \property Staff.instrument = #"Cl. in B-flat"
2500 \property Staff.transposing = #-2
2503 @c . {Multi measure rests}
2504 @node Multi measure rests
2505 @subsection Multi measure rests
2506 @cindex Multi measure rests
2510 Multi measure rests are entered using `@code{R}'. It is specifically
2511 meant for full bar rests and for entering parts: the rest can expand to
2513 rests, or it can be printed as a single multimeasure rest This expansion
2514 is controlled by the property @code{Score.skipBars}. If this is set to true,
2515 Lily will not expand empty measures, and the appropriate number is added
2518 @lilypond[fragment,verbatim]
2519 \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2522 Notice that the @code{R2.} is printed as a whole rest, centered in the
2525 @cindex whole rests for a full measure
2529 Currently, there is no way to automatically condense multiple rests into
2530 a single multimeasure rest.
2532 @cindex condensing rests
2534 @node Automatic part combining
2535 @subsection Automatic part combining
2536 @cindex automatic part combining
2537 @cindex part combiner
2540 Automatic part combining is used to merge two parts of music onto a
2541 staff in an intelligent way. It is aimed primarily at typesetting
2542 orchestral scores. When the two parts are identical for a period of
2543 time, only one is shown. In places where the two parts differ, they are
2544 typeset as separate voices, and stem directions are set automatically.
2545 Also, solo and @emph{a due} parts can be identified and marked.
2547 The syntax for part combining is
2550 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2552 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2553 combined into one context of type @var{context}. The music expressions
2554 must be interpreted by contexts whose names should start with @code{one}
2557 The most useful function of the part combiner is to combine parts into
2558 one voice, as common for wind parts in orchestral scores:
2560 @lilypond[verbatim,singleline,fragment]
2562 \context Voice=one \partcombine Voice
2563 \context Thread=one \relative c'' {
2566 \context Thread=two \relative c'' {
2572 Notice that the first @code{g} appears only once, although it was
2573 specified twice (once in each part). Stem, slur and tie directions are
2574 set automatically, depending whether there is a solo or unisono. The
2575 first part (with context called @code{one}) always gets up stems, and
2576 `solo', while the second (called @code{two}) always gets down stems and
2579 If you just want the merging parts, and not the textual markings, you
2580 may set the property @var{soloADue} to false.
2582 @lilypond[verbatim,singleline,fragment]
2584 \property Staff.soloADue = ##f
2585 \context Voice=one \partcombine Voice
2586 \context Thread=one \relative c'' {
2589 \context Thread=two \relative c'' {
2595 There are a number of other properties that you can use to tweak the
2596 behavior of part combining, refer to the automatically generated
2597 documentation of @reng{Thread_devnull_engraver} and
2598 @reng{Voice_devnull_engraver}. Look at the documentation of the
2599 responsible engravers, @code{Thread_devnull_engraver},
2600 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2604 In @code{soloADue} mode, when the two voices play the same notes on and
2605 off, the part combiner may typeset @code{a2} more than once in a
2608 @lilypond[fragment,singleline]
2610 \context Voice=one \partcombine Voice
2611 \context Thread=one \relative c'' {
2614 \context Thread=two \relative c'' {
2620 @cindex @code{Thread_devnull_engraver}
2621 @cindex @code{Voice_engraver}
2622 @cindex @code{A2_engraver}
2624 @node Hara kiri staves
2625 @subsection Hara kiri staves
2627 In orchestral scores, staff lines that only have rests are usually removed.
2628 This saves some space. LilyPond also supports this through the hara
2629 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2630 the Japanese Samourai warriors.} staff. This staff commits suicide when
2631 it finds itself to be empty after the line-breaking process. It will
2632 not disappear when it contains normal rests, you must use multi measure
2635 The hara kiri staff is specialized version of the Staff context. It is
2636 available as the context identifier @code{\HaraKiriStaffContext}.
2637 Observe how the second staff in this example disappears in the second
2642 \notes \relative c' <
2643 \context Staff = SA { e4 f g a \break c1 }
2644 \context Staff = SB { c4 d e f \break R1 }
2648 \translator { \HaraKiriStaffContext }
2661 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
2662 staff context symbol that appears at the end of a staff line. It
2663 anticipates the pitch of the first note(s) of the following line and
2664 thus helps the player or singer to manage line breaks during
2665 performance, thus enhancing readability of a score.
2670 \property Staff.Custos \set #'style = #'mensural
2675 \consists Custos_engraver
2681 Custodes were frequently used in music notation until the 17th century.
2682 There were different appearances for different notation styles.
2683 Nowadays, they have survived only in special forms of musical notation
2684 such as via the @emph{editio vaticana} dating back to the beginning of
2687 For typesetting custodes, just put a @code{Custos_engraver} into the
2688 @code{StaffContext} when declaring the @code{\paper} block. In this
2689 block, you can also globally control the appearance of the custos symbol
2690 by setting the custos @code{style} property. Currently supported styles
2691 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2698 \consists Custos_engraver
2699 Custos \override #'style = #'mensural
2704 The property can also be set locally, for example in a @code{\notes}
2709 \property Staff.Custos \override #'style = #'vaticana
2710 c'1 d' e' d' \break c' d' e' d'
2714 @c . {Tuning output}
2716 @section Tuning output
2718 LilyPond tries to take as much formatting as possible out of your
2719 hands. Nevertheless, there are situations where it needs some help, or
2720 where you want to override its decisions. In this section we discuss
2721 ways to do just that.
2723 Formatting is internally done by manipulating so called grobs (graphic
2724 objects). Each grob carries with it a set of properties (grob
2725 properties) specific to that object. For example, a stem grob has
2726 properties that specify its direction, length and thickness.
2728 The most direct way of tuning the output is by altering the values of
2729 these properties. There are two ways of doing that: first, you can
2730 temporarily change the definition of a certain type of grob, thus
2731 affecting a whole set of objects. Second, you can select one specific
2732 object, and set a grob property in that object.
2735 * Tuning groups of grobs ::
2736 * Tuning per grob ::
2744 @node Tuning groups of grobs
2745 @subsection Tuning groups of grobs
2747 @cindex grob description
2751 A grob definition is a Scheme association list, that is stored in a
2752 context property. By assigning to that property (using plain
2753 @code{\property}), you can change the resulting grobs.
2755 @lilypond[verbatim, fragment]
2756 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
2759 The @code{\property} assignment effectively empties the definition of
2760 the Stem object. One of the effects is that the recipe of how it should be
2761 printed is erased, with the effect of rendering it invisible. The above
2762 assignment is available as a standard identifier, for the case that you
2766 \property Voice.Stem = \turnOff
2773 This mechanism is fairly crude, since you can only set, but not modify,
2774 the definition of a grob. For this reason, there is a more advanced
2777 The definition of a grob is actually a list of default grob
2778 properties. For example, the definition of the Stem grob (available in
2779 @file{scm/grob-description.scm}), defines the following values for
2784 (beamed-lengths . (0.0 2.5 2.0 1.5))
2785 (Y-extent-callback . ,Stem::height)
2789 You can add a property on top of the existing definition, or remove a
2790 property, thus overriding the system defaults:
2792 c'4 \property Voice.Stem \override #'thickness = #4.0
2793 c'4 \property Voice.Stem \revert #'thickness
2796 You should balance @code{\override} and @code{\revert}. If that's too
2797 much work, you can use the @code{\set} shorthand. It performs a revert
2798 followed by an override. The following example gives exactly the same
2799 result as the previous one.
2801 c'4 \property Voice.Stem \set #'thickness = #4.0
2802 c'4 \property Voice.Stem \set #'thickness = #0.8
2805 If you use @code{\set}, you must explicitly restore the default.
2808 Formally the syntax for these constructions is
2810 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
2811 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
2812 \property @var{context}.@var{grobname} \revert @var{symbol}
2814 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
2815 and @var{grobname} are strings and @var{value} is a Scheme expression.
2818 If you revert a setting which was not set in the first place, then it
2819 has no effect. However, if the setting was set as a system default, it
2820 may remove the default value, and this may give surprising results,
2821 including crashes. In other words, @code{\override} and @code{\revert},
2822 must be carefully balanced.
2824 These are examples of correct nesting of @code{\override}, @code{\set},
2827 A clumsy but correct form:
2829 \override \revert \override \revert \override \revert
2832 Shorter version of the same:
2834 \override \set \set \revert
2837 A short form, using only @code{\set}. This requires you to know the
2840 \set \set \set \set @var{to default value}
2843 If there is no default (i.e. by default, the grob property is unset),
2846 \set \set \set \revert
2849 For the digirati, the grob description is an Scheme association
2850 list. Since a Scheme list is a singly linked list, we can treat it as a
2851 stack, and @code{\override} and @code{\revert} are just push and pop
2852 operations. This pushing and popping is also used for overriding
2853 automatic beaming settings.
2857 LilyPond will hang or crash if @var{value} contains cyclic references.
2858 The backend is not very strict in type-checking grob properties. If you
2859 @code{\revert} properties that are expected to be set by default,
2862 Some grobs are created at the moment that their context is created. An
2863 example of such a grob is the staff itself (i.e. the horizontal lines).
2864 You can not change the appearance of the staff symbol by manipulating
2865 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
2866 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
2867 created before any @code{\override} is effective. You can deal with this
2868 either overriding properties in a @code{\translator} definition, or by
2869 using @code{\outputproperty}.
2874 @node Tuning per grob
2875 @subsection Tuning per grob
2877 @cindex \outputproperty
2879 A second way of tuning grobs is the more arcane @code{\outputproperty}
2880 feature. The syntax is as follows:
2882 \outputproperty @var{predicate} @var{symbol} = @var{value}
2884 Here @code{predicate} is a Scheme function taking a grob argument, and
2885 returning a boolean. This statement is processed by the
2886 @code{Output_property_engraver}. It instructs the engraver to feed all
2887 grobs that it sees to @var{predicate}. Whenever the predicate returns
2888 true, the grob property @var{symbol} will be set to @var{value}.
2890 You will need to combine this statement with @code{\context} to select
2891 the appropriate context to apply this to.
2893 Here are some random examples.
2896 In the following example, all note heads occurring at current staff
2897 level, are shifted up and right by setting their @code{extra-offset}
2900 @lilypond[fragment,verbatim,singleline]
2902 \context Staff \outputproperty
2903 #(make-type-checker 'note-head-interface)
2904 #'extra-offset = #'(0.5 . 0.75)
2908 @cindex @code{extra-offset}
2910 In this example, the predicate checks the @code{text} grob property, to
2911 shift only the `m.d.' text, but not the fingering instruction "2".
2912 @lilypond[verbatim,singleline]
2913 #(define (make-text-checker text)
2914 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
2917 \notes\relative c''' {
2918 \property Voice.Stem \set #'direction = #1
2919 \outputproperty #(make-text-checker "m.d.")
2920 #'extra-offset = #'(-3.5 . -4.5)
2928 If possible, avoid this feature: the semantics are not very clean, and
2929 the syntax and semantics are up for rewrite.
2935 @subsection What to tune?
2937 This all tells you how to tune grobs, but you don't know what variables
2938 to set? The question is not answered in this part of the manual
2939 (although you may encounter some examples.).
2941 Grob properties are tied directly to the implementation of LilyPond, and
2942 they are thus a moving target. Documentation of such variables is in the
2943 automatically generated documentation. Description of properties are
2944 generated from the source code for each version. This documentation is
2945 therefore more up to date. It should be available from the same place
2946 where you got this manual.
2948 To decide how to tune a grob, you need to find the following information
2951 which grob to modify
2953 which property to modify
2955 which context the grob comes from.
2958 Included with the automatically generated documentation is a master list
2959 of grobs. Selecting a grob will take you to an overview of the
2960 properties available for that grob.
2962 There is also a master list of contexts. Selecting one takes you to an
2963 overview of that context which lists which grob types are created there.
2966 @node Font selection
2967 @subsection Font selection
2969 Most graphics in LilyPond are composed of characters of fonts. You can
2970 alter the characteristics of the font by setting certain grob
2971 properties. The mechanism that is used for this resembles La@TeX{}'s New
2972 Font Selection Scheme. Within this scheme, a font is entirely
2973 characterized by its font name.
2975 For each grob that uses fonts (in other words, each grob that supports
2976 @code{font-interface}) a font-name must be selected before it can be
2977 printed. The font name is selected by looking at a number of grob
2982 A symbol indicating the general class of the typeface. Supported are
2983 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
2984 @code{music} (the standard music font), @code{dynamic} (font for dynamic
2985 signs) and @code{typewriter}
2988 A symbol indicating the shape of the font, there are typically several
2989 font shapes available for each font family. Choices are @code{italic},
2990 @code{caps} and @code{upright}
2993 A symbol indicating the series of the font. There are typically several
2994 font series for each font family and shape. Choices are @code{medium}
2997 @item font-relative-size
2998 A number indicating the size relative the standard size. For example,
2999 with 20pt staff height, relative size -1 corresponds to 16pt staff
3000 height, and relative size +1 corresponds to 23 pt staff height.
3002 @item font-design-size
3003 A number indicating the design size of the font.
3005 This is a feature of the Computer Modern Font: each point size has a
3006 slightly different design. Smaller design sizes are relatively wider,
3007 which enhances readability. Scalable type faces such TrueType and Adobe
3008 Type1 usually come as ``one design fits all sizes''.
3011 The name of the font, without the design size, e.g. @code{cmr},
3012 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3017 The font is selected by taking the first font that satisfies all
3018 qualifiers specified. You can override any of these fields through
3019 @code{\override} and @code{\revert}. The special value @code{*} matches
3020 any value for that qualifier.
3023 \property Lyrics.LyricText \override #'font-series = #'bold
3024 \property Lyrics.LyricText \override #'font-shape = #'*
3027 @cindex @code{font-style}
3029 There are also pre-cooked font selection qualifiers. These are selected
3030 through the grob property @code{font-style}. For example, the style
3031 @code{finger} selects family @code{number} and relative size @code{-3}.
3032 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3033 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3036 The style sheets and tables for selecting fonts are located in
3037 @file{scm/font.scm}. Refer to this file for more information.
3041 Relative size is not linked to any real size.
3043 There is no mechanism to select magnification of particular fonts,
3044 meaning that you don't have access to continuously scaled fonts. You
3045 can scale the entire output, of course, see @ref{Output scaling}.
3047 There is no style sheet provided for other fonts besides the @TeX{}
3050 @cindex font selection
3051 @cindex font magnification
3052 @cindex @code{font-interface}
3056 @subsection Text markup
3060 LilyPond has an internal mechanism to typeset texts. You can
3061 form text markup expressions by composing scheme expressions
3062 in the following way.
3064 @lilypond[verbatim, singleline]
3069 c^#'(italic "italic")
3070 d_#'((bold italic) "ff")
3072 f_#'(lines "one" (bold "two"))
3073 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3077 Normally, the Scheme markup text is stored in the @code{text} property
3078 of a grob. Formally, it is defined as follows:
3081 text: string | (head? text+)
3082 head: markup | (markup+)
3083 markup-item: property | abbrev
3084 property: (@var{key} . @var{value})
3085 abbrev: @code{columns lines roman music bold italic named super sub}
3086 @code{overstrike text finger volta timesig mmrest mark script}
3087 @code{large Large dynamic}
3090 The markup is broken down and converted into a list of grob properties,
3091 which are prepended to the property list. The @var{key}-@var{value}
3092 pair is a grob property. A list of properties available is included in
3093 the generated documentation for @rint{Text_interface}.
3095 The following abbreviations are currently defined:
3098 horizontal mode: set all text on one line (default)
3100 vertical mode: set every text on a new line
3104 selects the Feta font (the standard font for music notation glyphs),
3105 and uses named lookup
3112 lookup by character name
3114 plain text lookup (by character value)
3120 the next text or character overstrikes this one
3122 select fingering number fontstyle
3124 select volta number fontstyle
3126 select time signature number fontstyle
3128 select multi measure rest number fontstyle
3130 select mark number fontstyle
3132 select scriptsize roman fontstyle
3134 select large roman fontstyle
3136 select Large roman fontstyle
3138 select dynamics fontstyle
3142 @cindex metronome mark
3144 One practical application of complicated markup is to fake a metronome
3148 #(define note '(columns
3149 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3150 #(define eight-note `(columns ,note ((kern . -0.1)
3151 (music ((raise . 3.5) "flags-u3")))))
3152 #(define dotted-eight-note
3153 `(columns ,eight-note (music "dots-dot")))
3156 \notes\relative c'' {
3157 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3163 TextScript \override #'font-shape = #'upright
3169 @node Invisible grobs
3170 @subsection Invisible grobs
3171 @cindex invisible grobs
3175 ben nog steeds niet kapot van de informatiedichtheid hier.
3181 You can imagine a number of situations where you would want to make
3182 certain grobs not show up in the output. There may be aesthetic
3183 reasons, to make the output resemble an (old) manuscript as close as
3184 possible, or to make lessons or exercises for students.
3186 Grobs can be made invisible in a number of ways:
3188 Here's an example with blanked-out notes and stems:
3189 @lilypond[singleline,verbatim]
3191 \property Voice.NoteHead \override
3193 \property Voice.Stem \override
3194 #'transparent = ##t }
3197 \property Voice.NoteHead \revert #'transparent
3198 \property Voice.Stem \revert #'transparent }
3201 \notes\relative c'' {
3203 a b c b \blanknotes c \unblanknotes d
3207 This method makes the grobs invisible but they still take the normal space.
3208 To remove all traces of the grob, you can redefine the function
3212 \notes\relative c'' {
3215 as bes c bes c d \break
3216 \property Staff.KeySignature \override #'molecule-callback = #'()
3219 \paper{linewidth=5.0\cm indent=0}
3223 A very rigorous way of removing grobs from the whole score is to remove
3224 the engraver that creates them. For example,
3226 @lilypond[singleline,verbatim]
3227 \score {\notes { c'4 d'8 e'8 g2 }
3228 \paper { \translator {
3230 \remove Stem_engraver
3236 @subsection Dirty tricks
3237 @cindex embedded tex
3239 It is possible to use @TeX{} commands in the strings, but this should be
3240 avoided because it makes it impossible for LilyPond to compute the
3241 exact length of the string, which may lead to collisions. Also, @TeX{}
3242 commands won't work with direct PostScript output (see @ref{PostScript
3245 @lilypond[fragment,relative,verbatim]
3246 a'^"3 $\\times$ \\`a deux"
3249 You can also use raw PostScript commands embedded in text scripts. This
3250 offers ultimate flexibility, but requires you to learn PostScript.
3251 Currently, embedded PostScript will @strong{not} work with direct
3252 PostScript output. Note that all dimensions that you use are in staff
3257 \notes \relative c'' {
3258 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3259 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3260 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3264 \paper { linewidth = 70*\staffspace }
3271 @section Page layout
3274 The page layout is the combined product of LilyPond formatting notation,
3275 and (La)@TeX{} putting the notation on a page, including page breaks.
3276 The part of LilyPond is documented here.
3290 @subsection Paper block
3293 The most important output definition is the @code{\paper} block, for
3294 music notation. The syntax is
3297 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3300 where each of the items is one of
3303 @item An assignment.
3305 @item A context definition. See @ref{Interpretation context} for
3306 more information on context definitions.
3308 @item \stylesheet declaration. Its syntax is
3310 \stylesheet @var{alist}
3313 See @file{scm/font.scm} for details of @var{alist}.
3314 @item an @code{\elementdescriptions} declaration.
3316 \elementdescriptions @var{alist}
3318 See @file{scm/grob-description.scm} for details of
3319 @var{alist}. This command is not user-serviceable.
3323 @c . {Paper variables}
3324 @node Paper variables
3325 @subsection Paper variables
3326 @cindex Paper variables
3328 The paper block has some variables you may want to use or change:
3331 @cindex @code{indent}
3333 The indentation of the first line of music.
3334 @cindex @code{staffspace}
3336 @item @code{staffspace}
3337 The distance between two staff lines, calculated from the center
3340 @cindex @code{linewidth}
3341 @item @code{linewidth}
3342 Sets the width of the lines.
3344 If set to a negative value, a single unjustified line is produced.
3345 @c rename to singleLinePaper ?
3346 The shorthand @code{\singleLine} defines a default paper block that
3347 produces a single line.
3349 @cindex @code{textheight}
3351 @item @code{textheight}
3352 Sets the total height of the music on each page. Only used by
3355 @cindex @code{interscoreline}
3357 @item @code{interscoreline}
3358 Sets the spacing between systems. The default is 16pt.
3360 @cindex @code{interscorelinefill}
3362 @item @code{interscorelinefill}
3363 If set to a positive number, the distance between the score
3364 lines will stretch in order to fill the full page. In that
3365 case @code{interscoreline} specifies the minimum spacing.
3370 @cindex @code{stafflinethickness}
3372 @item @code{stafflinethickness}
3373 Determines the thickness of staff lines, and also acts as a scaling
3374 parameter for other line thicknesses.
3377 You may enter these dimension using units (@code{cm}, @code{in},
3378 @code{mm}, @code{pt}), or relative to another dimension
3380 linewidth = 20.0 * \staffspace
3387 @subsection Font size
3390 The Feta font provides musical symbols at six different sizes. These
3391 fonts are 11 point, 13 point, 16 point, 20 point,
3392 23 point, and 26 point. The point size of a font is the
3393 height of the five lines in a staff when displayed in the font.
3395 Definitions for these sizes are the files @file{paperSZ.ly}, where
3396 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3397 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3398 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3399 @code{paperTwentysix} are defined respectively. The default
3400 @code{\paper} block is also set.
3402 The font definitions are generated using a Scheme function. For more
3403 details, see the file @file{scm/font.scm}.
3409 @subsection Paper size
3414 @cindex @code{papersize}
3416 To change the paper size, you must first set the
3417 @code{papersize} variable at top level. Set it to
3418 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3419 specification, you must set the font as described above. If you want
3420 the default font, then use the 20 point font.
3424 \include "paper16.ly"
3427 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3428 will set the paper variables @code{hsize} and @code{vsize} (used by
3433 @subsection Line break
3436 @cindex breaking lines
3438 Line breaks are normally computed automatically. They are chosen such
3439 that the resulting spacing has low variation, and looks neither cramped
3442 Occasionally you might want to override the automatic breaks; you can do
3443 this by specifying @code{\break}. This will force a line break at this
3444 point. Do remember that line breaks can only occur at places where there
3445 are bar lines. If you want to have a line break where there is no
3446 bar line, you can force an invisible bar line by entering @code{\bar
3447 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3449 @cindex @code{\penalty}
3451 The @code{\break} and @code{\noBreak} commands are defined in terms of
3452 the penalty command:
3457 This encourages or discourages LilyPond to make a line break at this
3462 The scaling of the @code{\penalty} argument is not well-defined. The
3463 command is rather kludgey, and slated for rewriting.
3467 @subsection Page break
3470 @cindex breaking pages
3472 Page breaks are normally computed by @TeX{}, so they are not under
3473 direct control of LilyPond. However, you can insert a commands into the
3474 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3475 the command @code{\newpage}
3476 @cindex @code{\newpage}
3482 @c why do so difficult?
3483 @c maybe should explain contents of between-system.ly,
3484 @c but not now, we're talking about page breaks here.
3486 @c details, see the example file @file{input/test/between-systems.ly}
3489 @c . {Output scaling}
3490 @node Output scaling
3491 @subsection Output scaling
3506 There is no mechanism to select magnification of particular fonts,
3507 meaning that you don't have access to continuously scaled fonts.
3511 @c . {Output formats}
3512 @node Output formats
3513 @section Output formats
3515 LilyPond can output processed music in different output formats.
3519 * PostScript output::
3521 * ASCIIScript output::
3525 @subsection TeX output
3528 LilyPond will use @TeX{} by default. Even if you want to produce
3529 PostScript output for viewing or printing, you should normally have
3530 LilyPond produce @TeX{} first. The .tex output must be processed by
3531 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
3532 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
3533 used to generate the .dvi for you.
3537 Titling is not generated unless you use @file{ly2dvi}.
3540 @node PostScript output
3541 @subsection PostScript output
3542 @cindex PostScript output
3543 @cindex direct PostScript output
3545 LilyPond can produce PostScript directly, without going through @TeX{}.
3546 Currently, this is mainly useful if you cannot use TeX, because direct
3547 PostScript output has some problems; see Bugs below.
3550 $ lilypond -fps foo.ly
3551 GNU LilyPond 1.3.144
3552 Now processing: `foo.ly'
3554 Interpreting music...[3]
3555 Preprocessing elements...
3556 Calculating column positions...
3557 paper output to foo.ps...
3559 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
3565 Text font selection is broken.
3567 The .ps file does not contain the .pfa font files. To print a .ps
3568 created through direct postscript output, you should prepend the
3569 necessary .pfa files to LilyPond's .ps output, or upload them to the
3570 printer before printing.
3572 The line height calculation is broken, you must set @var{lineheight} in
3573 the paperblock if you have more than one staff in your score, e.g.
3578 % Set line height to 40 staff spaces
3584 @subsection Scheme output
3585 @cindex Scheme output
3587 In the typesetting stage, LilyPond builds a page description, which is
3588 then written to disk in postscript, @TeX{} or ASCII art. Before it is
3589 written, the page description is represented as Scheme expressions. You
3590 can also dump these Scheme expressions to a file, which may be
3591 convenient for debugging output routines. This is done with the Scheme
3595 $ lilypond -fscm foo.ly
3596 GNU LilyPond 1.3.144
3597 Now processing: `foo.ly'
3599 Interpreting music...[3]
3600 Preprocessing elements...
3601 Calculating column positions...
3602 paper output to foo.scm...
3605 ;;; Usage: guile -s x.scm > x.tex
3606 (primitive-load-path 'standalone.scm)
3610 $ guile -s foo.scm > foo.tex
3614 @node ASCIIScript output
3615 @subsection ASCIIScript output
3616 @cindex ASCIIScript output
3617 @cindex ascii script
3620 LilyPond can output ASCII Art. This is a two step process, LilyPond
3621 produces an ASCII description file, dubbed ASCIIScript (extension
3622 @file{.as}). ASCIIScript has a small and simple command set that
3623 includes font selection, character and string printing and line drawing
3624 commands. The program @file{as2text} is used to translate an .as file
3627 To produce ASCII Art, you must include an ASCII Art paper definition
3628 file in your .ly, one of:
3630 \include "paper-as5.ly"
3631 \include "paper-as9.ly"
3634 Here's an example use for ASCII Art output (the example file
3635 @file{as-email.ly} is included in the LilyPond distribution), the staff
3636 symbol has been made invisible:
3639 $ lilypond -fas as-email.ly
3640 GNU LilyPond 1.3.144
3641 Now processing: `as-email.ly'
3643 Interpreting music...[3]
3644 Preprocessing elements...
3645 Calculating column positions... [2]
3646 paper output to as-email.as...
3648 $ as2text as-email.as 2>/dev/null
3650 |/ |##|##| | | | | |
3651 /| | | | | |\ |\ |\ |\ |\ |
3652 / |_ 3 | | | | 5 | )| )| )| )| )|
3653 | /| \ 8 * * * | 8 * * * * * |
3663 The ASCII Art fonts are far from complete and not very well designed.
3664 It's easy to change the glyphs, though; if you think you can do better,
3665 have a look at @file{mf/*.af}.
3667 Lots of resizable symbols such as slurs, ties and tuplets are missing.
3669 The poor looks of most ASCII Art output and its limited general
3670 usefulness gives ASCII Art output a low priority; it may be
3671 dropped in future versions.
3678 LilyPond can produce MIDI output. The performance lacks lots of
3679 interesting effects, such as swing, articulation, slurring, etc., but it
3680 is good enough for proof-hearing the music you have entered. Ties,
3681 dynamics and tempo changes are interpreted.
3683 Dynamic marks, crescendi and decrescendi translate into MIDI volume
3684 levels. Dynamic marks translate to a fixed fraction of the available
3685 MIDI volume range, crescendi and decrescendi make the the volume vary
3686 linearly between their two extremities. The fractions be adjusted by
3687 overriding the @code{absolute-volume-alist} defined in
3688 @file{scm/midi.scm}.
3690 For each type of musical instrument (that MIDI supports), a volume range
3691 can be defined. This gives you basic equalizer control, which can
3692 enhance the quality of the MIDI output remarkably. You can add
3693 instruments and ranges or change the default settings by overriding the
3694 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
3696 Both loudness controls are combined to produce the final MIDI volume.
3701 It is currently not possible to use the percussion channel (generally
3702 channel 10 of a MIDI file).
3706 * MIDI instrument names::
3711 @subsection MIDI block
3715 The MIDI block is analogous to the paper block, but it is somewhat
3716 simpler. The @code{\midi} block can contain:
3720 @item a @code{\tempo} definition
3721 @item context definitions
3724 Assignments in the @code{\midi} block are not allowed.
3728 @cindex context definition
3730 Context definitions follow precisely the same syntax as within the
3731 \paper block. Translation modules for sound are called performers.
3732 The contexts for MIDI output are defined in @file{ly/performer.ly}.
3735 @node MIDI instrument names
3736 @subsection MIDI instrument names
3738 @cindex instrument names
3739 @cindex @code{Staff.midiInstrument}
3740 @cindex @code{Staff.instrument}
3742 The MIDI instrument name is set by the @code{Staff.midiInstrument}
3743 property or, if that property is not set, the @code{Staff.instrument}
3744 property. The instrument name should be chosen from the list in
3745 @ref{MIDI instruments}.
3749 If the selected string does not exactly match, then LilyPond uses the
3750 default (Grand Piano). It is not possible to select an instrument by
3763 @section Music entry
3771 When entering music with LilyPond, it is easy to introduce errors. This
3772 section deals with tricks and features that help you enter music, and
3773 find and correct mistakes.
3777 @subsection Relative
3779 @cindex relative octave specification
3781 Octaves are specified by adding @code{'} and @code{,} to pitch names.
3782 When you copy existing music, it is easy to accidentally put a pitch in
3783 the wrong octave and hard to find such an error. To prevent these
3784 errors, LilyPond features octave entry.
3786 @cindex @code{\relative}
3788 \relative @var{startpitch} @var{musicexpr}
3791 The octave of notes that appear in @var{musicexpr} are calculated as
3792 follows: If no octave changing marks are used, the basic interval
3793 between this and the last note is always taken to be a fourth or less
3794 (This distance is determined without regarding alterations; a
3795 @code{fisis} following a @code{ceses} will be put above the
3798 The octave changing marks @code{'} and @code{,} can be added to raise or
3799 lower the pitch by an extra octave. Upon entering relative mode, an
3800 absolute starting pitch must be specified that will act as the
3801 predecessor of the first note of @var{musicexpr}.
3803 Entering music that changes octave frequently is easy in relative mode.
3804 @lilypond[fragment,singleline,verbatim,center]
3810 And octave changing marks are used for intervals greater than a fourth.
3811 @lilypond[fragment,verbatim,center]
3813 c g c f, c' a, e'' }
3816 If the preceding item is a chord, the first note of the chord is used
3817 to determine the first note of the next chord. However, other notes
3818 within the second chord are determined by looking at the immediately
3821 @lilypond[fragment,verbatim,center]
3828 @cindex @code{\notes}
3830 The pitch after the @code{\relative} contains a note name. To parse
3831 the pitch as a note name, you have to be in note mode, so there must
3832 be a surrounding @code{\notes} keyword (which is not
3835 The relative conversion will not affect @code{\transpose},
3836 @code{\chords} or @code{\relative} sections in its argument. If you
3837 want to use relative within transposed music, you must place an
3838 additional @code{\relative} inside the @code{\transpose}.
3843 @subsection Bar check
3847 @cindex @code{barCheckNoSynchronize}
3851 Whenever a bar check is encountered during interpretation, a warning
3852 message is issued if it doesn't fall at a measure boundary. This can
3853 help you find errors in the input. Depending on the value of
3854 @code{barCheckNoSynchronize}, the beginning of the measure will be
3855 relocated, so this can also be used to shorten measures.
3857 A bar check is entered using the bar symbol, @code{|}:
3859 \time 3/4 c2 e4 | g2.
3862 @c . {Point and click}
3863 @node Point and click
3864 @subsection Point and click
3866 Point and click lets you find notes in the input by clicking on them in
3867 the Xdvi window. This makes it very easy to find input that causes some
3868 error in the sheet music.
3870 To use it, you need the following software
3872 @unnumberedsubsec Installation
3876 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
3877 Xdvi} version 22.36 or newer.
3879 Note that most @TeX{} distributions ship with xdvik, which is a
3880 different and less well maintained program. To find out which xdvi you
3881 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
3885 Xdvi must be configured to find the TeX fonts and music
3886 fonts. Refer to the Xdvi documentation for more information.
3889 @unnumberedsubsec Using it
3891 Add one of these lines to the top of your .ly file. The first one is for
3892 line location only. The second one is more convenient, but requires
3893 patching @code{emacsclient} and @code{server.el}.
3896 #(set! point-and-click line-location)
3899 In the emacs startup file (usually @file{~/.emacs}), add the following
3904 Make sure that the environment variable @code{XEDITOR} is set
3907 emacsclient --no-wait +%l %f
3909 The second one, that also specifies the column, only works if you have
3910 patched your emacsclient and server, and have compiled your @code{.ly}
3911 file using the @code{line-column-location} setting.
3913 When viewing, control-mousebutton 1 will take you to the originating
3914 spot in the @file{.ly} file. Control-mousebutton 2 will show all
3918 @unnumberedsubsec Column location
3920 If you want emacs to jump to the exact spot (and not just the line) on a
3921 click, you must enable column positioning. To do so, you need to patch
3922 emacsclient. Apply @file{emacsclient.patch} (included with the source
3923 package) to @file{emacsclient.c} and @file{server.el} from the emacs
3924 source code. Recompile and stick the recompiled emacsclient into a bin
3925 directory, and put @file{server.el} into a elisp directory
3926 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
3927 init file, before invoking server-start.
3930 (setq load-path (cons "~/usr/share/emacs" load-path))
3933 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
3935 At the top of the @code{ly} file, replace the @code{set!} line with the
3938 #(set! point-and-click line-column-location)
3941 One final hint: if you correct large files with point-and-click, then
3942 start correcting at the end of the file. When you start at the top, and
3943 insert one line, all subsequent locations will be off by a line.
3948 When you convert the @TeX{} file to PostScript using @code{dvips}, it
3949 will complain about not finding @code{src:X:Y} files. Those complaints
3950 are harmless, and can be ignored.
3952 @node Skipping corrected music
3953 @section Skipping corrected music
3955 The property @code{Score.skipTypesetting} can be used to switch on and
3956 off typesetting completely during the interpretation phase. When
3957 typesetting is switched off, the music is processed much more quickly.
3958 You can use this to skip over the parts of a score that you have already
3961 @lilypond[fragment,singleline,verbatim]
3962 \relative c'' { c8 d
3963 \property Score.skipTypesetting = ##t
3965 \property Score.skipTypesetting = ##f
3970 @node Interpretation context
3971 @section Interpretation context
3974 * Creating contexts::
3975 * Default contexts::
3976 * Context properties::
3977 * Engravers and performers::
3978 * Changing context definitions::
3979 * Defining new contexts::
3983 Interpretation contexts are objects that only exist during a run of
3984 LilyPond. During the interpretation phase of LilyPond (when it prints
3985 "interpreting music"), the music expression in a @code{\score} block is
3986 interpreted in time order. This is the same order that humans hear and
3989 During this interpretation, the interpretation context holds the
3990 state for the current point within the music. It contains information
3994 @item What notes are playing at this point?
3995 @item What symbols will be printed at this point?
3996 @item What is the current key signature, time signature, point within
4000 Contexts are grouped hierarchically: A @code{Voice} context is
4001 contained in a @code{Staff} context (because a staff can contain
4002 multiple voices at any point), a @code{Staff} context is contained in
4003 @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context.
4005 Contexts associated with sheet music output are called @emph{notation
4006 contexts}, those for sound output are called @emph{performance
4007 contexts}. The default definitions of the standard notation and
4008 performance contexts can be found in @file{ly/engraver.ly} and
4009 @file{ly/performer.ly}, respectively.
4012 @node Creating contexts
4013 @subsection Creating contexts
4015 @cindex @code{\context}
4016 @cindex context selection
4018 Contexts for a music expression can be selected manually, using the
4019 following music expression.
4022 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4025 This instructs lilypond to interpret @var{musicexpr} within the context
4026 of type @var{contexttype} and with name @var{contextname}. If this
4027 context does not exist, it will be created.
4029 @lilypond[verbatim,singleline]
4031 \notes \relative c'' {
4032 c4 <d4 \context Staff = "another" e4> f
4038 In this example, the @code{c} and @code{d} are printed on the
4039 default staff. For the @code{e}, a context Staff called
4040 @code{another} is specified; since that does not exist, a new
4041 context is created. Within @code{another}, a (default) Voice context
4042 is created for the @code{e4}. When all music referring to a
4043 context is finished, the context is ended as well. So after the
4044 third quarter, @code{another} is removed.
4048 @node Default contexts
4049 @subsection Default contexts
4051 Most music expressions don't need an explicit @code{\context}
4052 declaration: they inherit the
4053 notation context from their parent. Each note is a music expression, and
4054 as you can see in the following example, only the sequential music
4055 enclosing the three notes has an explicit context.
4057 @lilypond[verbatim,singleline]
4058 \score { \notes \context Voice = goUp { c'4 d' e' } }
4061 There are some quirks that you must keep in mind when dealing with
4064 First, every top level music is interpreted by the Score context, in other
4065 words, you may think of @code{\score} working like
4068 \context Score @var{music}
4072 Second, contexts are created automatically to be able to interpret the
4073 music expressions. Consider the following example.
4075 @lilypond[verbatim, singleline]
4076 \score { \context Score \notes { c'4 ( d' )e' } }
4079 The sequential music is interpreted by the Score context initially
4080 (notice that the @code{\context} specification is redundant), but when a
4081 note is encountered, contexts are setup to accept that note. In this
4082 case, a Thread, Voice and Staff are created. The rest of the sequential
4083 music is also interpreted with the same Thread, Voice and Staff context,
4084 putting the notes on the same staff, in the same voice.
4086 This is a convenient mechanism, but do not expect opening chords to work
4087 without @code{\context}. For every note, a separate staff is
4090 @lilypond[verbatim, singleline]
4091 \score { \notes <c'4 es'> }
4094 Of course, if the chord is preceded by a normal note in sequential
4095 music, the chord will be interpreted by the Thread of the preceding
4097 @lilypond[verbatim,singleline]
4098 \score { \notes { c'4 <c'4 es'> } }
4103 @node Context properties
4104 @subsection Context properties
4106 Notation contexts have properties. These properties are from
4107 the @file{.ly} file using the following expression:
4108 @cindex @code{\property}
4110 \property @var{contextname}.@var{propname} = @var{value}
4113 Sets the @var{propname} property of the context @var{contextname} to the
4114 specified Scheme expression @var{value}. All @var{propname} and
4115 @var{contextname} are strings, which are typically unquoted.
4117 Properties that are set in one context are inherited by all of the
4118 contained contexts. This means that a property valid for the
4119 @code{Voice} context can be set in the @code{Score} context (for
4120 example) and thus take effect in all @code{Voice} contexts.
4122 Properties can be unset using the following expression:
4124 \property @var{contextname}.@var{propname} \unset
4127 @cindex properties, unsetting
4128 @cindex @code{\unset}
4130 This removes the definition of @var{propname} in @var{contextname}. If
4131 @var{propname} was not defined in @var{contextname} (but was inherited
4132 from a higher context), then this has no effect.
4137 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4138 the inverse of @code{\property \set}.
4140 @node Engravers and performers
4141 @subsection Engravers and performers
4145 Basic building blocks of translation are called engravers; they are
4146 special C++ classes.
4150 @c . {Context definitions}
4151 @node Changing context definitions
4152 @subsection Changing context definitions
4154 @cindex context definition
4155 @cindex translator definition
4157 The most common way to define a context is by extending an existing
4158 context. You can change an existing context from the paper block, by
4159 first initializing a translator with an existing context identifier:
4163 @var{context-identifier}
4166 Then you can add and remove engravers using the following syntax:
4168 \remove @var{engravername}
4169 \consists @var{engravername}
4173 Here @var{engravername} is a string, the name of an engraver in the
4177 @lilypond[verbatim,singleline]
4181 \translator { \StaffContext
4182 \remove Clef_engraver
4188 You can also set properties in a translator definition. The syntax is as
4191 @var{propname} = @var{value}
4192 @var{propname} \set @var{grob-propname} = @var{pvalue}
4193 @var{propname} \override @var{grob-propname} = @var{pvalue}
4194 @var{propname} \revert @var{grob-propname}
4196 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4197 and @code{pvalue} are Scheme expressions. These type of property
4198 assignments happen before interpretation starts, so a @code{\property}
4199 command will override any predefined settings.
4202 To simplify editing translators, all standard contexts have standard
4203 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4204 @code{VoiceContext}, see @file{ly/engraver.ly}.
4206 @node Defining new contexts
4207 @subsection Defining new contexts
4209 If you want to build a context from scratch, you must also supply the
4210 following extra information:
4212 @item A name, specified by @code{\name @var{contextname}}.
4214 @item A cooperation module. This is specified by @code{\type
4221 \type "Engraver_group_engraver"
4224 \consists "Staff_symbol_engraver"
4225 \consists "Note_head_engraver"
4226 \consistsend "Axis_group_engraver"
4230 The argument of @code{\type} is the name for a special engraver that
4231 handles cooperation between simple engravers such as
4232 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4233 for this engraver are the following:
4235 @cindex @code{Engraver_group_engraver}
4236 @item @code{Engraver_group_engraver}
4237 The standard cooperation engraver.
4239 @cindex @code{Score_engraver}
4241 @item @code{Score_engraver}
4242 This is cooperation module that should be in the top level context,
4243 and only the top level context.
4245 @cindex @code{Grace_engraver_group}
4247 @item @code{Grace_engraver_group}
4248 This is a special cooperation module (resembling
4249 @code{Score_engraver}) that is used to create an embedded
4256 @item @code{\alias} @var{alternate-name}
4257 This specifies a different name. In the above example,
4258 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4260 @item @code{\consistsend} @var{engravername}
4261 Analogous to @code{\consists}, but makes sure that
4262 @var{engravername} is always added to the end of the list of
4265 Some engraver types need to be at the end of the list; this
4266 insures they stay there even if a user adds or removes engravers.
4267 End-users generally don't need this command.
4269 @item @code{\accepts} @var{contextname}
4270 Add @var{contextname} to the list of contexts this context can
4271 contain in the context hierarchy. The first listed context is the
4272 context to create by default.
4274 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4275 completeness, but is never used in practice.
4278 @item @code{\name} @var{contextname}
4279 This sets the type name of the context, e.g. @code{Staff},
4280 @code{Voice}. If the name is not specified, the translator won't do
4284 In the @code{\paper} block, it is also possible to define translator
4285 identifiers. Like other block identifiers, the identifier can only
4286 be used as the very first item of a translator. In order to define
4287 such an identifier outside of @code{\score}, you must do
4292 foo = \translator @{ @dots{} @}
4299 \translator @{ \foo @dots{} @}
4307 @cindex paper types, engravers, and pre-defined translators
4314 @c . {Syntactic details}
4315 @node Syntactic details
4316 @section Syntactic details
4317 @cindex Syntactic details
4319 This section describes details that were too boring to be put elsewhere.
4324 * Music expressions::
4325 * Manipulating music expressions::
4333 @subsection Top level
4336 This section describes what you may enter at top level.
4340 @subsubsection Score
4343 @cindex score definition
4345 The output is generated combining a music expression with an output
4346 definition. A score block has the following syntax:
4349 \score @{ @var{musicexpr} @var{outputdefs} @}
4352 @var{outputdefs} are zero or more output definitions. If none is
4353 supplied, the default @code{\paper} block will be added.
4357 @c . {Default output}
4358 @subsubsection Default output
4360 Default values for the @code{\paper} and @code{\midi} block are set by
4361 entering such a block at the top level.
4364 @subsubsection Header
4366 @cindex @code{\header}
4369 A header describes bibliographic information of the file's contents. It
4370 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4371 use this information for generating titles. Key values that are used by
4372 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4373 meter, arranger, piece and tagline.
4375 @cindex @code{ly2dvi}
4379 \header @{ @var{key1} = @var{val1}
4380 @var{key2} = @var{val2} @dots{} @}
4383 It is customary to put the @code{\header} at the top of the file.
4385 @subsubsection Default output
4387 A @code{\midi} or @code{\paper} block at top level sets the default
4388 paper block for all scores that lack an explicit paper block.
4392 @subsection Identifiers
4396 What has this section got to do with identifiers?
4397 It seems more appropriate in the introduction to Chapter 4,
4403 All of the information in a LilyPond input file, is internally
4404 represented as a Scheme value. In addition to normal Scheme data types
4405 (such as pair, number, boolean, etc.), LilyPond has a number of
4406 specialized data types,
4413 @item Translator_def
4417 @item Music_output_def
4418 @item Moment (rational number)
4421 LilyPond also includes some transient object types. Objects of these
4422 types are built during a LilyPond run, and do not `exist' per se within
4423 your input file. These objects are created as a result of your input
4424 file, so you can include commands in the input to manipulate them,
4425 during a lilypond run.
4428 @item Grob: short for Graphical object. See @ref{Grobs}.
4429 @item Molecule: device-independent page output object,
4430 including dimensions. Produced by some Grob functions
4432 @item Translator: object that produces audio objects or Grobs. This is
4433 not yet user accessible.
4434 @item Font_metric: object representing a font. (See @ref{Font metrics})
4439 @node Music expressions
4440 @subsection Music expressions
4442 @cindex music expressions
4444 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4445 syllables are music expressions, and you can combine music expressions
4446 to form new ones, for example by enclosing a list of expressions in
4447 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4448 compound expression is formed out of the quarter note @code{c} and a
4449 quarter note @code{d}:
4452 \sequential @{ c4 d4 @}
4455 @cindex Sequential music
4456 @cindex @code{\sequential}
4457 @cindex sequential music
4460 @cindex Simultaneous music
4461 @cindex @code{\simultaneous}
4463 The two basic compound music expressions are simultaneous and
4467 \sequential @code{@{} @var{musicexprlist} @code{@}}
4468 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4470 For both, there is a shorthand:
4472 @code{@{} @var{musicexprlist} @code{@}}
4476 @code{<} @var{musicexprlist} @code{>}
4478 for simultaneous music.
4479 In principle, the way in which you nest sequential and simultaneous to
4480 produce music is not relevant. In the following example, three chords
4481 are expressed in two different ways:
4483 @lilypond[fragment,verbatim,center]
4484 \notes \context Voice {
4485 <a c'> <b d' > <c' e'>
4486 < { a b c' } { c' d' e' } >
4491 Other compound music expressions include
4494 \transpose @var{pitch} @var{expr}
4495 \apply @var{func} @var{expr}
4496 \context @var{type} = @var{id} @var{expr}
4497 \times @var{fraction} @var{expr}
4501 @c . {Manipulating music expressions}
4502 @node Manipulating music expressions
4503 @subsection Manipulating music expressions
4505 The @code{\apply} mechanism gives you access to the internal
4506 representation of music. You can write Scheme-functions that operate
4507 directly on it. The syntax is
4509 \apply #@var{func} @var{music}
4511 This means that @var{func} is applied to @var{music}. The function
4512 @var{func} should return a music expression.
4514 This example replaces the text string of a script. It also shows a dump
4515 of the music it processes, which is useful if you want to know more
4516 about how music is stored.
4518 @lilypond[verbatim,singleline]
4519 #(define (testfunc x)
4520 (if (equal? (ly-get-mus-property x 'text) "foo")
4521 (ly-set-mus-property x 'text "bar"))
4523 (ly-set-mus-property x 'elements
4524 (map testfunc (ly-get-mus-property x 'elements)))
4529 \apply #testfunc { c'4_"foo" }
4533 For more information on what is possible, see the automatically
4534 generated documentation.
4537 Directly accessing internal representations is dangerous: the
4538 implementation is subject to changes, so you should avoid this feature
4541 A final example is a function that reverses a piece of music in time:
4543 @lilypond[verbatim,singleline]
4544 #(define (reverse-music music)
4545 (let* ((elements (ly-get-mus-property music 'elements))
4546 (reversed (reverse elements))
4547 (span-dir (ly-get-mus-property music 'span-direction)))
4548 (ly-set-mus-property music 'elements reversed)
4550 (ly-set-mus-property music 'span-direction (- span-dir)))
4551 (map reverse-music reversed)
4554 music = \notes { c'4 d'4( e'4 f'4 }
4556 \score { \context Voice {
4558 \apply #reverse-music \music
4563 More examples are given in the distributed example files in
4566 @c . {Span requests}
4572 @subsubsection Span requests
4573 @cindex Span requests
4575 Notational constructs that start and end on different notes can be
4576 entered using span requests. The syntax is as follows:
4580 \spanrequest @var{startstop} @var{type}
4584 @cindex @code{\start}
4585 @cindex @code{\stop}
4587 This defines a spanning request. The @var{startstop} parameter is either
4588 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
4589 describes what should be started. Much of the syntactic sugar is a
4590 shorthand for @code{\spanrequest}, for example,
4592 @lilypond[fragment,verbatim,center]
4593 c'4-\spanrequest \start "slur"
4594 c'4-\spanrequest \stop "slur"
4597 Among the supported types are @code{crescendo}, @code{decrescendo},
4598 @code{beam}, @code{slur}. This is an internal command. Users are
4599 encouraged to use the shorthands which are defined in the initialization
4600 file @file{spanners.ly}.
4605 @subsection Assignments
4608 Identifiers allow objects to be assigned to names during the parse
4609 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
4610 and to refer to an identifier, you precede its name with a backslash:
4611 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
4612 the input-types listed above. Identifier assignments can appear at top
4613 level in the LilyPond file, but also in @code{\paper} blocks.
4615 An identifier can be created with any string for its name, but you will
4616 only be able to refer to identifiers whose names begin with a letter,
4617 being entirely alphabetical. It is impossible to refer to an identifier
4618 whose name is the same as the name of a keyword.
4620 The right hand side of an identifier assignment is parsed completely
4621 before the assignment is done, so it is allowed to redefine an
4622 identifier in terms of its old value, e.g.
4628 When an identifier is referenced, the information it points to is
4629 copied. For this reason, an identifier reference must always be the
4630 first item in a block.
4634 \paperIdent % wrong and invalid
4638 \paperIdent % correct
4643 @c . {Lexical modes}
4645 @subsection Lexical modes
4646 @cindex Lexical modes
4649 @cindex @code{\notes}
4650 @cindex @code{\chords}
4651 @cindex @code{\lyrics}
4653 To simplify entering notes, lyrics, and chords, LilyPond has three
4654 special input modes in addition to the default mode: note, lyrics and
4655 chords mode. These input modes change the way that normal, unquoted
4656 words are interpreted: for example, the word @code{cis} may be
4657 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
4658 major triad respectively.
4660 A mode switch is entered as a compound music expression
4662 @code{\notes} @var{musicexpr}
4663 @code{\chords} @var{musicexpr}
4664 @code{\lyrics} @var{musicexpr}.
4667 In each of these cases, these expressions do not add anything to the
4668 meaning of their arguments. They just instruct the parser in what mode
4669 to parse their arguments. The modes are treated in more detail in
4670 @ref{Lyrics} and @ref{Chords}.
4672 Different input modes may be nested.
4676 @subsection Ambiguities
4681 The grammar contains a number of ambiguities. We hope to resolve them at
4685 @item The assignment
4690 is interpreted as the string identifier assignment. However,
4691 it can also be interpreted as making a string identifier @code{\foo}
4692 containing @code{"bar"}, or a music identifier @code{\foo}
4693 containing the syllable `bar'.
4695 @item If you do a nested repeat like
4707 then it is ambiguous to which @code{\repeat} the
4708 @code{\alternative} belongs. This is the classic if-then-else
4709 dilemma. It may be solved by using braces.
4711 @item The parser is not sophisticated enough to distinguish at the
4713 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
4720 @c . {Lexical details}
4721 @node Lexical details
4722 @section Lexical details
4724 Even more boring details, now on lexical side of the input parser.
4735 * Version information::
4740 @subsection Comments
4743 @cindex block comment
4744 @cindex line comment
4748 A one line comment is introduced by a @code{%} character.
4749 Block comments are started by @code{%@{} and ended by @code{%@}}.
4750 They cannot be nested.
4753 @subsection Direct Scheme
4757 @cindex Scheme, in-line code
4760 LilyPond contains a Scheme interpreter (the GUILE library) for
4761 internal use. In some places, Scheme expressions also form valid syntax:
4762 wherever it is allowed,
4766 evaluates the specified Scheme code. Example:
4768 \property Staff.TestObject \override #'foobar = #(+ 1 2)
4770 @code{\override} expects two Scheme expressions, so there are two Scheme
4771 expressions. The first one is a symbol (@code{foobar}), the second one
4772 an integer (namely, 3).
4774 In-line scheme may be used at the top level. In this case the result is
4777 Scheme is a full-blown programming language, and a full discussion is
4778 outside the scope of this document. Interested readers are referred to
4779 the website @uref{http://www.schemers.org/} for more information on
4784 @subsection Keywords
4788 Keywords start with a backslash, followed by a number of lower case
4789 alphabetic characters. These are all the keywords.
4792 apply arpeggio autochange spanrequest commandspanrequest
4793 simultaneous sequential accepts alternative bar breathe
4794 char chordmodifiers chords clef cm consists consistsend
4795 context denies duration dynamicscript elementdescriptions
4796 font grace header in lyrics key mark pitch
4797 time times midi mm name pitchnames notes outputproperty
4798 override set revert partial paper penalty property pt
4799 relative remove repeat addlyrics partcombine score
4800 script stylesheet skip textscript tempo translator
4805 @subsection Integers
4813 Formed from an optional minus sign followed by digits. Arithmetic
4814 operations cannot be done with integers, and integers cannot be mixed
4819 @cindex real numbers
4825 Formed from an optional minus sign and a sequence of digits followed
4826 by a @emph{required} decimal point and an optional exponent such as
4827 @code{-1.2e3}. Reals can be built up using the usual operations:
4828 `@code{+}', `@code{-}', `@code{*}', and
4829 `@code{/}', with parentheses for grouping.
4837 A real constant can be followed by one of the dimension keywords:
4838 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
4839 points, inches and centimeters, respectively. This converts the number
4840 a number that is the internal representation of that dimension.
4848 Begins and ends with the @code{"} character. To include a @code{"}
4849 character in a string write @code{\"}. Various other backslash
4850 sequences have special interpretations as in the C language. A string
4851 that contains no spaces can be written without the quotes. Strings can
4852 be concatenated with the @code{+} operator.
4856 @subsection Main input
4859 @cindex @code{\maininput}
4861 The @code{\maininput} command is used in init files to signal that the
4862 user file must be read. This command cannot be used in a user file.
4864 @node File inclusion
4865 @subsection File inclusion
4866 @cindex @code{\include}
4868 \include @var{filename}
4871 Include @var{filename}. The argument @var{filename} may be a quoted string (an
4872 unquoted string will not work here!) or a string identifier. The full
4873 filename including the @file{.ly} extension must be given,
4876 @node Version information
4877 @subsection Version information
4878 @cindex @code{\version}
4880 \version @var{string}
4883 Specify the version of LilyPond that a file was written for. The
4884 argument is a version string in quotes, for example @code{"1.2.0"}.
4885 This is used to detect invalid input, and to aid
4886 @code{convert-ly} a tool that automatically upgrades input files. See
4887 See @ref{convert-ly} for more information on @code{convert-ly}.
4896 @c .{Local emacs vars}
4899 @c minor-mode: font-lock
4900 @c minor-mode: outline
4901 @c outline-layout: (-1 : 0)
4902 @c outline-use-mode-specific-leader: "@c \."
4903 @c outline-primary-bullet: "{"
4904 @c outline-stylish-prefixes: nil
4905 @c outline-override-protect: t