3 @c A menu is needed before every deeper *section nesting of @node's; run
4 @c M-x texinfo-all-menus-update
5 @c to automagically fill in these menus before saving changes
7 @c FIXME: singular vs. plural: Beams/Beam
17 @c .{Reference Manual}
19 @node Reference Manual
20 @chapter Reference Manual
23 <!--- @@WEB-TITLE@@=Reference Manual --->
26 This document describes GNU LilyPond and its input format. The last
27 revision of this document was made for LilyPond 1.4.1. It supposes a
28 passing familiarity with how LilyPond input works. New users are
29 encouraged to study the tutorial first.
34 * Easier music entry::
52 * Interpretation context::
57 @c FIXME: Note entry vs Music entry at top level menu is confusing.
63 The most basic forms of music are notes. Notes on their own don't
64 form valid input, but for the sake of brevity we omit @code{\score}
65 blocks and @code{\paper} declarations.
71 * Chromatic alterations::
76 * Automatic note splitting ::
78 * Defining pitch names::
79 * Easy Notation note heads ::
87 A note is printed by specifying its pitch, and then its duration.
88 @lilypond[fragment,verbatim]
91 The grob for a note head is called @internalsref{NoteHead}.
98 @cindex Note specification
100 @cindex entering notes
102 The verbose syntax for pitch specification is
104 @cindex @code{\pitch}
106 \pitch @var{scmpitch}
109 @var{scmpitch} is a pitch scheme object.
111 In Note and Chord mode, pitches may be designated by names. The default
112 names are the Dutch note names. The notes are specified by the letters
113 @code{a} through @code{g} (where the octave is formed by notes ranging
114 from @code{c} to @code{b}). The pitch @code{c} is an octave below
115 middle C and the letters span the octave above that C.
117 @cindex note names, Dutch
119 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
120 name and a flat is formed by adding @code{-es}. Double sharps and double
121 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
122 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
123 both forms are accepted.
125 LilyPond has predefined sets of note names for various other languages.
126 To use them, simply include the language specific init file. For
127 example: @code{\include "english.ly"}. The available language files and
128 the names they define are:
131 Note Names sharp flat
132 nederlands.ly c d e f g a bes b -is -es
133 english.ly c d e f g a bf b -s/-sharp -f/-flat
134 deutsch.ly c d e f g a b h -is -es
135 norsk.ly c d e f g a b h -iss/-is -ess/-es
136 svenska.ly c d e f g a b h -iss -ess
137 italiano.ly do re mi fa sol la sib si -d -b
138 catalan.ly do re mi fa sol la sib si -d/-s -b
139 espanol.ly do re mi fa sol la sib si -s -b
148 The optional octave specification takes the form of a series of
149 single quote (`@code{'}') characters or a series of comma
150 (`@code{,}') characters. Each @code{'} raises the pitch by one
151 octave; each @code{,} lowers the pitch by an octave.
153 @lilypond[fragment,verbatim,center]
154 c' c'' es' g' as' gisis' ais'
157 @node Chromatic alterations
158 @subsection Chromatic alterations
160 Normally Accidentals signify that the pitch of a note differs from the
161 key signature. Normally, they are printed automatically depending, but
162 you may force accidentals in the following ways:
163 A reminder accidental
164 @cindex reminder accidental
166 can be forced by adding an exclamation mark @code{!} after the pitch. A
167 cautionary accidental,
168 @cindex cautionary accidental
169 @cindex parenthesized accidental
170 i.e., an accidental within parentheses can be obtained by adding the
171 question mark `@code{?}' after the pitch.
173 Each accidental symbol is an @internalsref{Accidental} grob. The
174 placement of accidentals is handled by
175 @internalsref{AccidentalPlacement}.
183 A rest is entered like a note, with note name `@code{r}':
185 @lilypond[singleline,verbatim]
189 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
190 specified using @code{R}, see @ref{Multi measure rests}.
192 For polyphonic music, it can be convenient to specify the rest position
193 directly. You can do that by entering a note, with the keyword
194 @code{\rest} appended, e.g. Rest collisions will leave these rests alone.
196 @lilypond[singleline,verbatim]
206 @cindex Invisible rest
209 An invisible rest, or skip, can be entered like a note with note name
210 @code{s}, or with @code{\skip @var{duration}}:
212 @lilypond[singleline,verbatim]
216 The @code{s} syntax is only available in Note mode and Chord mode.
217 In other situations, you should use the @code{\skip} command, and it is
218 only available in Note mode and Chord mode.
220 @c FIXME: in lyrics mode, we have " " and _
222 In Lyrics mode, you can use `@code{" "}' and `@code{_}':
223 @lilypond[singleline,verbatim]
225 \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
226 \notes\relative c'' { a2 a4 a a2 a4 a }
230 The unabbreviated `@code{\skip} @var{duration}' also works outside of
233 @lilypond[singleline,verbatim]
236 { \time 4/8 \skip 2 \time 4/4 }
237 \notes\relative c'' { a2 a1 }
242 The skip command is merely a empty musical placeholder. It does not
243 produce any output, not even transparent output.
248 @subsection Durations
252 @cindex @code{\duration}
254 The syntax for a verbose duration specification is
256 \duration @var{scmduration}
258 Here, @var{scmduration} is a Scheme object of type @code{Duration}.
261 In Note, Chord, and Lyrics mode, durations may be designated by numbers
262 and dots: durations are entered as their reciprocal values. For notes
263 longer than a whole you must use identifiers.
267 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
269 r1 r2 r4 r8 r16 r32 r64 r64
275 \notes \relative c'' {
277 a1 a2 a4 a8 a16 a32 a64 a64
279 r1 r2 r4 r8 r16 r32 r64 r64
284 \remove "Clef_engraver"
285 \remove "Staff_symbol_engraver"
286 \remove "Time_signature_engraver"
287 \consists "Pitch_squash_engraver"
294 If the duration is omitted then it is set to the previous duration
295 entered. At the start of parsing a quarter note is assumed. The
296 duration can be followed by dots (`@code{.}') to obtain dotted note
300 @lilypond[fragment,verbatim,center]
306 You can alter the length of duration by a fraction @var{N/M} by
307 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
308 will not affect the appearance of the notes or rests produced.
320 A tie connects two adjacent note heads of the same pitch. The tie in
321 effect extends the length of a note. A tie is entered with @code{~}.
323 @lilypond[fragment,verbatim,center]
324 e' ~ e' <c' e' g'> ~ <c' e' g'>
327 When ties are used with chords, all note heads whose pitches match are
328 connected. Ties are indicated using the tilde symbol `@code{~}'. If
329 you try to tie together chords which have no common pitches then no
330 ties will be created.
332 If you want less ties created for a chord, you can set
333 @code{Voice.sparseTies} to true. In this case, a single tie is used
334 for every tied chord.
335 @lilypond[fragment,verbatim,center]
336 \property Voice.sparseTies = ##t
337 <c' e' g'> ~ <c' e' g'>
340 In its meaning a tie is just a way of extending a note duration, similar
341 to the augmentation dot: the following example are two ways of notating
342 exactly the same concept.
344 @lilypond[fragment, singleline]
345 \time 3/4 c'2. c'2 ~ c'4
347 Ties should not be confused with slurs, which indicate articulation,
348 and phrasing slurs, which indicate musical phrasing.
350 The name of the tie grob is @internalsref{Tie}, and it is created in the
351 @internalsref{Voice} context.
355 At present, the tie is implemented as a separate thing, temporally
356 located in between the notes.
357 Tieing only a subset of the note heads of a chord is not supported in a
358 simple way. It can be achieved by moving the tie-engraver into the Thread
359 context and turning on and off ties per Thread.
361 @node Automatic note splitting
362 @subsection Automatic note splitting
364 There is a facility for automatically converting long notes to tied
365 notes. This is done by replacing the @code{Note_heads_engraver} by the
366 @code{Completion_heads_engraver}.
368 @lilypond[verbatim,center]
370 \notes\relative c'{ \time 2/4
371 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
375 \remove "Note_heads_engraver"
376 \consists "Completion_heads_engraver"
380 This engraver splits all running notes at the bar line, and inserts
381 ties. One of the uses of this is, is to debug complex scores: if the
382 measures are not entirely filled, then the ties exactly show how much
387 Not all durations (especially those containing tuplets) can be
388 represented exactly; the engraver will not insert tuplets.
395 @cindex @code{\times}
397 Tuplets are made out of a music expression by multiplying all duration
400 @cindex @code{\times}
402 \times @var{fraction} @var{musicexpr}
405 The duration of @var{musicexpr} will be multiplied by the fraction.
406 In print, the fraction's denominator will be printed over the notes,
407 optionally with a bracket. The most common tuplet is the triplet in
408 which 3 notes have the length of 2, so the notes are 2/3 of
409 their written length:
411 @lilypond[fragment,verbatim,center]
412 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
415 The property @code{tupletSpannerDuration} specifies how long each bracket
416 should last. With this, you can make lots of tuplets while typing
417 @code{\times} only once, thus saving typing work.
419 @lilypond[fragment, relative, singleline, verbatim]
420 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
421 \times 2/3 { c'8 c c c c c }
424 The format of the number is determined by the property
425 @code{tupletNumberFormatFunction}. The default prints only the
426 denominator, but if you set it to the Scheme function
427 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
432 The typesetting of brackets and numbers is controlled by the properties
433 @code{bracket-visibility} and @code{number-visibility}. These
434 properties can either be @code{#f}, @code{#t} or @code{'if-no-beam},
435 meaning respectively off, on, and on if there is no beam.
437 @lilypond[fragment, relative, singleline, verbatim]
438 \property Voice.TupletBracket \set #'bracket-visibility = ##t
439 \times 2/3{c'8 d e} \times 2/3{d4 e8}
440 \property Voice.TupletBracket \set #'bracket-visibility = #'if-no-beam
441 \times 2/3{c d e} \times 2/3{d4 e8}
442 \property Voice.TupletBracket \set #'bracket-visibility = ##f
443 \times 2/3{c d e} \times 2/3{d4 e8}
444 \property Voice.TupletBracket \set #'number-visibility = ##f
445 \times 2/3{c d e} \times 2/3{d4 e8}
446 \property Voice.TupletBracket \set #'number-visibility = #'if-no-beam
447 \times 2/3{c d e} \times 2/3{d4 e8}
450 @cindex @code{tupletNumberFormatFunction}
451 @cindex tuplet formatting
453 Tuplet brackets are printed as @internalsref{TupletBracket} grobs in
454 the @internalsref{Voice} context.
456 @c . {Defining pitch names}
457 @node Defining pitch names
458 @subsection Defining pitch names
460 @cindex defining pitch names
461 @cindex pitch names, defining
463 Note names and chord modifiers can be customized for nationalities. The
464 syntax is as follows.
466 @cindex @code{\pitchnames}
467 @cindex @code{\chordmodifiers}
469 \pitchnames @var{scheme-alist}
470 \chordmodifiers @var{scheme-alist}
473 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers-init.ly} for
474 specific examples on how to do this.
477 @node Easy Notation note heads
478 @subsection Easy Notation note heads
480 @cindex easy notation
483 A entirely different type of note head is the "easyplay" note head: a
484 note head that includes a note name. It is used in some publications by
485 Hal-Leonard Inc. music publishers.
487 @lilypond[singleline,verbatim]
488 \include "paper23.ly"
490 \notes { c'2 e'4 f' | g'1 }
491 \paper { \translator { \EasyNotation } }
495 Note that @internalsref{EasyNotation} overrides a @internalsref{Score} context. You
496 probably will want to print it with magnification to make it more
497 readable, see @ref{Output scaling}.
503 If you view the result with Xdvi, then staff lines will show through the
504 letters. Printing the postscript file obtained either by using dvips or
505 the @code{-f ps} option of lilypond produces the correct result.
508 @node Easier music entry
509 @section Easier music entry
515 * Skipping corrected music::
518 When entering music with LilyPond, it is easy to introduce errors. This
519 section deals with tricks and features that help you enter music, and
520 find and correct mistakes.
523 @node Relative octaves
524 @subsection Relative octaves
526 @cindex relative octave specification
528 Octaves are specified by adding @code{'} and @code{,} to pitch names.
529 When you copy existing music, it is easy to accidentally put a pitch in
530 the wrong octave and hard to find such an error. To prevent these
531 errors, LilyPond features octave entry.
533 @cindex @code{\relative}
535 \relative @var{startpitch} @var{musicexpr}
538 The octave of notes that appear in @var{musicexpr} are calculated as
539 follows: If no octave changing marks are used, the basic interval
540 between this and the last note is always taken to be a fourth or less
541 (This distance is determined without regarding alterations; a
542 @code{fisis} following a @code{ceses} will be put above the
545 The octave changing marks @code{'} and @code{,} can be added to raise or
546 lower the pitch by an extra octave. Upon entering relative mode, an
547 absolute starting pitch must be specified that will act as the
548 predecessor of the first note of @var{musicexpr}.
550 Entering music that changes octave frequently is easy in relative mode.
551 @lilypond[fragment,singleline,verbatim,center]
557 And octave changing marks are used for intervals greater than a fourth.
558 @lilypond[fragment,verbatim,center]
563 If the preceding item is a chord, the first note of the chord is used
564 to determine the first note of the next chord. However, other notes
565 within the second chord are determined by looking at the immediately
568 @lilypond[fragment,verbatim,center]
575 @cindex @code{\notes}
577 The pitch after the @code{\relative} contains a note name. To parse
578 the pitch as a note name, you have to be in note mode, so there must
579 be a surrounding @code{\notes} keyword (which is not
582 The relative conversion will not affect @code{\transpose},
583 @code{\chords} or @code{\relative} sections in its argument. If you
584 want to use relative within transposed music, you must place an
585 additional @code{\relative} inside the @code{\transpose}.
590 @subsection Bar check
594 @cindex @code{barCheckNoSynchronize}
598 Whenever a bar check is encountered during interpretation, a warning
599 message is issued if it doesn't fall at a measure boundary. This can
600 help you find errors in the input. Depending on the value of
601 @code{barCheckSynchronize}, the beginning of the measure will be
602 relocated, so this can also be used to shorten measures.
604 A bar check is entered using the bar symbol, @code{|}:
606 \time 3/4 c2 e4 | g2.
611 @cindex skipTypesetting
613 Failed bar checks are most often caused by entering incorrect
614 durations. Incorrect durations often completely garble up the score,
615 especially if it is polyphonic, so you should start correcting the score
616 by scanning for failed bar checks and incorrect durations. To speed up
617 this process, you can use @code{skipTypesetting} (See @ref{Skipping
618 corrected music})). Bar
621 @c . {Point and click}
622 @node Point and click
623 @subsection Point and click
625 Point and click lets you find notes in the input by clicking on them in
626 the Xdvi window. This makes it very easy to find input that causes some
627 error in the sheet music.
629 To use it, you need the following software
633 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
634 Xdvi} version 22.36 or newer.
636 Note that most @TeX{} distributions ship with xdvik, which is a
637 different and less well maintained program. To find out which xdvi you
638 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
642 Xdvi must be configured to find the TeX fonts and music
643 fonts. Refer to the Xdvi documentation for more information.
646 To use point-and-click, add one of these lines to the top of your .ly
647 file. The first one is for line location only. The second one is more
648 convenient, but requires patching @code{emacsclient} and
652 #(set! point-and-click line-location)
655 In the emacs startup file (usually @file{~/.emacs}), add the following
660 Make sure that the environment variable @code{XEDITOR} is set
663 emacsclient --no-wait +%l %f
665 The second one, that also specifies the column, only works if you have
666 patched your emacsclient and server, and have compiled your @code{.ly}
667 file using the @code{line-column-location} setting.
669 When viewing, control-mousebutton 1 will take you to the originating
670 spot in the @file{.ly} file. Control-mousebutton 2 will show all
673 If you want emacs to jump to the exact spot (and not just the line) on a
674 click, you must enable column positioning. To do so, you need to patch
675 emacsclient. Apply @file{emacsclient.patch} (included with the source
676 package) to @file{emacsclient.c} and @file{server.el} from the emacs
677 source code. Recompile and stick the recompiled emacsclient into a bin
678 directory, and put @file{server.el} into a elisp directory
679 (e.g. @file{~/usr/share/emacs/}). Add the following to your
680 @file{.emacs} init file, before invoking server-start.
683 (setq load-path (cons "~/usr/share/emacs" load-path))
686 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
688 At the top of the @code{ly} file, replace the @code{set!} line with the
691 #(set! point-and-click line-column-location)
694 One final hint: if you correct large files with point-and-click, then
695 start correcting at the end of the file. When you start at the top, and
696 insert one line, all subsequent locations will be off by a line.
701 When you convert the @TeX{} file to PostScript using @code{dvips}, it
702 will complain about not finding @code{src:X:Y} files. Those complaints
703 are harmless, and can be ignored.
705 @node Skipping corrected music
706 @subsection Skipping corrected music
708 The property @code{Score.skipTypesetting} can be used to switch on and
709 off typesetting completely during the interpretation phase. When
710 typesetting is switched off, the music is processed much more quickly.
711 You can use this to skip over the parts of a score that you have already
714 @lilypond[fragment,singleline,verbatim]
716 \property Score.skipTypesetting = ##t
718 \property Score.skipTypesetting = ##f
726 @section Staff notation
728 @cindex Staff notation
740 @subsection Key signature
745 Setting or changing the key signature is done with the @code{\key}
748 @code{\key} @var{pitch} @var{type}
751 @cindex @code{\minor}
752 @cindex @code{\major}
753 @cindex @code{\minor}
754 @cindex @code{\ionian}
755 @cindex @code{\locrian}
756 @cindex @code{\aeolian}
757 @cindex @code{\mixolydian}
758 @cindex @code{\lydian}
759 @cindex @code{\phrygian}
760 @cindex @code{\dorian}
762 Here, @var{type} should be @code{\major} or @code{\minor} to get
763 @var{pitch}-major or @var{pitch}-minor, respectively.
764 The standard mode names @code{\ionian},
765 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
766 @code{\phrygian}, and @code{\dorian} are also defined.
768 This command sets the context property @code{Staff.keySignature}.
769 Non-standard key signatures can be specified by setting this property
772 The printed signature is a @internalsref{KeySignature} grob, typically
773 created in @internalsref{Staff} context.
775 @cindex @code{keySignature}
782 The clef can be set or changed with the @code{\clef} command:
783 @lilypond[fragment,verbatim]
784 \key f\major c''2 \clef alto g'2
787 Supported clef-names include
788 @c Moved standard clefs to the top /MB
790 @item treble, violin, G, G2
799 G clef on 1st line, so-called French violin clef
814 By adding @code{_8} or @code{^8} to the clef name, the clef is
815 transposed one octave down or up, respectively. Note that you have to
816 enclose @var{clefname} in quotes if you use underscores or digits in the
822 The grob for this symbol is @internalsref{Clef}.
825 The full syntax for this command is
829 where @var{clefname} is a string. This command is a shortcut for
831 \property Staff.clefGlyph = @var{glyph associated with clefname}
832 \property Staff.clefPosition = @var{clef Y-position for clefname}
833 \property Staff.centralCPosition = @var{position for central C}
834 \property Staff.clefOctavation = @var{extra transposition of clefname}
836 Upon any change in these properties lilypond creates a clef
837 symbol. The mapping from @var{clefname} to the property values can be
838 found in @file{scm/clef.scm}
844 @c . {Time signature}
846 @subsection Time signature
847 @cindex Time signature
851 The time signature is set or changed by the @code{\time}
853 @lilypond[fragment,verbatim]
854 \time 2/4 c'2 \time 3/4 c'2.
857 The actual symbol that's printed can be customized with the style
859 @lilypond[fragment, verbatim, singleline]
861 \property Staff.TimeSignature \override #'style = #'C
863 \property Staff.TimeSignature \override #'style = #'()
865 \property Staff.TimeSignature \override #'style = #'C
869 The grob for this symbol is @internalsref{TimeSignature}. There are
870 many more options for its layout. They are selected through the
871 @code{style} grob property. See @file{input/test/time.ly} for more
875 The full syntax for this command is
877 \time @var{n}@code{/}@var{d}
879 where @var{n} and @var{d} are integers. This command is internally
880 translated, to the following:
882 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
883 \property Score.beatLength = #(make-moment 1 @var{d})
884 \property Score.measureLength = #(make-moment @var{n} @var{d})
887 The property @code{timeSignatureFraction} determine where bar lines
888 should be inserted, and how automatic beams should be generated.
889 Changing the value of @code{timeSignatureFraction} also causes a
890 fraction to be printed.
897 @cindex partial measure
898 @cindex measure, partial
899 @cindex shorten measures
900 @cindex @code{\partial}
902 Partial measures, for example in upbeats, are entered using the
903 @code{\partial} command:
904 @lilypond[fragment,verbatim]
905 \partial 4* 5/16 c'16 c8. f16 a'2. ~ a'8. a'16 | g'1
908 The syntax for this command is
910 \partial @var{duration}
912 This is internally translated into
914 \property Score.measurePosition = -@var{length of duration}
917 The property @code{measurePosition} contains a rational number
918 indicating how much of the measure has passed at this point.
921 @node Unmetered music
922 @subsection Unmetered music
924 Bar lines and bar numbers are calculated automatically. For unmetered
925 music (e.g. cadenzas), this is not desirable. The property
926 @code{Score.timing} can be used to switch off this automatic timing
928 @lilypond[fragment,relative,singleline,verbatim]
930 \property Score.timing = ##f
932 \property Score.timing = ##t
936 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
943 @subsection Bar lines
947 @cindex measure lines
950 Bar lines are inserted automatically by, but if you need a special
951 types of barline, you can force one using the @code{\bar} command:
952 @lilypond[fragment,verbatim]
956 The following bar types are available
957 @lilypond[fragment, relative, singleline, verbatim]
969 You are encouraged to use @code{\repeat} for repetitions. See
972 In scores with many staffs, the barlines are automatically placed at
973 top level, and they are connected between different staffs of a
974 @internalsref{StaffGroup}:
975 @lilypond[fragment, verbatim]
976 < \context StaffGroup <
977 \context Staff = up { e'4 d'
980 \context Staff = down { \clef bass c4 g e g } >
981 \context Staff = pedal { \clef bass c2 c2 } >
984 The grobs that are created at @internalsref{Staff} level. The name is
985 @internalsref{BarLine}.
987 The full syntax for this command is
991 where @var{bartype} is a string. This is a shortcut for doing
993 \property Score.whichBar = @var{bartype}
997 @cindex Bar_line_engraver
999 @cindex repeatCommands
1000 @cindex defaultBarType
1002 Whenever @code{whichBar} is set to a string, a bar line of that type is
1003 created. @code{whichBar} is usually set automatically: at the start of
1004 a measure it is set to @code{defaultBarType}. The contents of
1005 @code{repeatCommands} is used to override default measure bars.
1007 @code{whichBar} can also be set directly, using @code{\property} or
1008 @code{\bar }. These settings take precedence over the automatic
1009 @code{whichBar} settings.
1016 Polyphonic parts, i.e. parts with more than one voice on a staff can be
1017 typeset with LilyPond.
1019 The easiest way to enter such fragments, is the Scheme function
1020 @code{voicify-music}. It will split chords using the separator
1021 @code{\\}, to make multiple voices. You can use it for small,
1022 short-lived voices (make a chord of voices) or for single chords:
1024 @lilypond[verbatim,fragment]
1025 \context Voice = VA \apply #voicify-music \relative c'' {
1026 c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d >
1030 The function @code{voicify-music} instantiates @internalsref{Voice}
1031 contexts, bearing the names @code{"1"}, @code{"2"}, etc.
1033 To explicity typeset polyphonic music, instantiate a separate Voice
1034 context for each part, and use @code{\voiceOne}, up to
1035 @code{\voiceFour} to assign a stem directions and horizontal shift for
1039 @lilypond[singleline, verbatim]
1041 \context Staff < \context Voice = VA { \voiceOne cis2 b }
1042 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
1043 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
1046 The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
1047 ties, slurs and stems, and set shift directions.
1049 If you want more than four voices, you can also manually set
1050 horizontal shifts and stem directions, as is shown in the following example:
1051 @lilypond[fragment, verbatim]
1052 \context Staff \notes\relative c''<
1053 \context Voice=one {
1054 \shiftOff \stemUp e4
1056 \context Voice=two {
1057 \shiftOn \stemUp cis
1059 \context Voice=three {
1060 \shiftOnn \stemUp ais
1062 \context Voice=four {
1063 \shiftOnnn \stemUp fis
1069 Normally, note heads with a different number of dots are not merged, but
1070 if you set the grob property @code{merge-differently-dotted}, they are:
1071 @lilypond[verbatim,fragment,singleline]
1072 \apply #voicify-music < {
1074 \property Staff.NoteCollision \override
1075 #'merge-differently-dotted = ##t
1077 } \\ { [g'8. f16] [g'8. f'16] }
1081 Similarly, you can merge half note heads with eighth notes, by setting
1082 @code{merge-differently-headed}:
1083 @lilypond[fragment, relative=2,verbatim]
1084 \apply #voicify-music < {
1086 \property Staff.NoteCollision
1087 \override #'merge-differently-headed = ##t
1088 c8 c4. } \\ { c2 c2 } >
1091 LilyPond also vertically shifts rests that are opposite of a stem.
1093 @lilypond[singleline,fragment,verbatim]
1094 \context Voice \apply #voicify-music <
1099 Note head collisions (horizontal shifting of note heads) are handled by
1100 the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
1101 handles vertical shifting of rests.
1107 Resolving collisions is a very intricate subject, and LilyPond only
1108 handles a few situations. When it can not cope, you are advised to use
1109 @code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
1110 rests to override typesetting decisions.
1115 Beams are used to group short notes into chunks that are aligned with
1116 the metrum. They are inserted automatically in most cases.
1118 @lilypond[fragment,verbatim, relative=2]
1119 \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
1122 If you're not satisfied with the automatic beaming, you can enter the
1123 beams explicitly. If you have beaming patterns that differ from the
1124 defaults, you can also set the patterns for automatic beamer.
1126 The beam symbol is @internalsref{Beam} in @internalsref{Voice}
1127 context, both for automatically created and manual beams.
1130 @cindex Automatic beams
1131 @subsection Manual beams
1132 @cindex beams, manual
1136 In some cases it may be necessary to override LilyPond's automatic
1137 beaming algorithm. For example, the auto beamer will not beam over
1138 rests or bar lines, If you want that, specify the begin and end point
1139 manually using a @code{[} before the first beamed note and a @code{]}
1140 after the last note:
1142 @lilypond[fragment,relative,verbatim]
1144 r4 [r8 g' a r8] r8 [g | a] r8
1148 @cindex @code{stemLeftBeamCount}
1150 Normally, beaming patterns within a beam are determined automatically.
1151 When this mechanism fouls up, the properties
1152 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
1153 be used to control the beam subdivision on a stem. If you set either
1154 property, it's value will be used only once, and then it is erased.
1156 @lilypond[fragment,relative,verbatim]
1159 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
1162 @cindex @code{stemRightBeamCount}
1165 TODO: FIXME, we don't want this doc here.
1167 can be tweaked through
1168 grob-property @code{positions}. The value is a pair.
1169 specify vertical location of the left and right end point. Both are
1170 measured in half staff-spaces, and the middle staff line is the value
1173 @li lypond[fragment,relative,verbatim]
1174 \property Voice.Beam \set #'position = #
1175 \property Voice.Beam \set #'height = #0
1179 Here's how you'd specify a weird looking beam that instead of being
1180 horizontal, falls two staff spaces:
1186 @li lypond[fragment,relative,verbatim]
1187 \property Voice.Beam \set #'staff-position = #4
1188 \property Voice.Beam \set #'height = #-4
1195 Kneed beams are inserted automatically, when a large gap between two
1196 adjacent beamed notes is detected. This behavior can be tuned through
1197 the grob property @code{auto-knee-gap}.
1199 @cindex beams, kneed
1201 @cindex auto-knee-gap
1205 @c TODO -> why this ref? Document?
1206 @cindex @code{neutral-direction}
1210 Auto knee beams can not be used together with hara kiri staffs.
1214 * Setting automatic beam behavior ::
1217 @node Beam typography
1218 @subsection Beam typography
1220 One of the strong points of LilyPond is how beams are formatted. Beams
1221 are quantized, meaning that the left and right endpoints beams start
1222 exactly on staff lines. Without quantization, small wedges of white
1223 space appear between the beam and staff line, and this looks untidy.
1225 Beams are also slope-damped: melodies that go up or down should also
1226 have beams that go up or down, but the slope of the beams should be
1227 less than the slope of the notes themselves.
1229 Some beams should be horizontal. These are so-called concave beams.
1231 [TODO: some pictures.]
1234 @c . {Automatic beams}
1235 @node Setting automatic beam behavior
1236 @subsection Setting automatic beam behavior
1238 @cindex @code{autoBeamSettings}
1239 @cindex @code{(end * * * *)}
1240 @cindex @code{(begin * * * *)}
1241 @cindex automatic beams, tuning
1242 @cindex tuning automatic beaming
1244 In normal time signatures, automatic beams can start on any note but can
1245 only end in a few positions within the measure: beams can end on a beat,
1246 or at durations specified by the properties in
1247 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
1248 are defined in @file{scm/auto-beam.scm}.
1250 The value of @code{autoBeamSettings} is changed using
1251 @code{\override} and unset using @code{\revert}:
1253 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
1254 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
1256 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
1257 whether the rule applies to begin or end-points. The quantity
1258 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
1259 *}' designates notes of any length), @var{N}/@var{M} refers to a time
1260 signature (wildcards, `@code{* *}' may be entered to designate all time
1263 For example, if you want automatic beams to end on every quarter note,
1264 you can use the following:
1266 \property Voice.autoBeamSettings \override
1267 #'(end * * * *) = #(make-moment 1 4)
1269 Since the duration of a quarter note is 1/4 of a whole note, it is
1270 entered as @code{(make-moment 1 4)}.
1272 The same syntax can be used to specify beam starting points. In this
1273 example, automatic beams can only end on a dotted quarter note.
1275 \property Voice.autoBeamSettings \override
1276 #'(end * * * *) = #(make-moment 3 8)
1278 In 4/4 time signature, this means that automatic beams could end only on
1279 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1280 3/8 has passed within the measure).
1282 You can also restrict rules to specific time signatures. A rule that
1283 should only be applied in @var{N}/@var{M} time signature is formed by
1284 replacing the second asterisks by @var{N} and @var{M}. For example, a
1285 rule for 6/8 time exclusively looks like
1287 \property Voice.autoBeamSettings \override
1288 #'(begin * * 6 8) = ...
1291 If you want a rule to apply to certain types of beams, you can use the
1292 first pair of asterisks. Beams are classified according to the shortest
1293 note they contain. For a beam ending rule that only applies to beams
1294 with 32nd notes (and no shorter notes), you would use @code{(end 1
1298 @c Automatic beams can not be put on the last note in a score.
1300 If a score ends while an automatic beam has not been ended and is still
1301 accepting notes, this last beam will not be typeset at all.
1303 @cindex automatic beam generation
1305 @cindex @code{Voice.autoBeaming}
1308 For melodies that have lyrics, you may want to switch off
1309 automatic beaming. This is done by setting @code{Voice.autoBeaming} to
1315 It is not possible to specify beaming parameters for beams with mixed
1316 durations, that differ from the beaming parameters of all separate
1317 durations, i.e., you'll have to specify manual beams to get:
1318 @lilypond[fragment,singleline,relative]
1319 \property Voice.autoBeamSettings
1320 \override #'(end * * * *) = #(make-moment 3 8)
1321 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
1324 It is not possible to specify beaming parameters that act differently in
1325 different parts of a measure. This means that it is not possible to use
1326 automatic beaming in irregular meters such as @code{5/8}.
1329 @node Expressive marks
1330 @section Expressive marks
1345 A slur indicates that notes are to be played bound or @emph{legato}.
1346 They are entered using parentheses:
1347 @lilypond[fragment,verbatim,center]
1348 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1351 The grob for this object is @internalsref{Slur}, generally in
1352 @internalsref{Voice} context.
1354 Slurs avoid crossing stems, and are generally attached to note heads.
1355 However, in some situations with beams, slurs may be attached to stem
1356 ends. If you want to override this layout you can do this through the
1357 grob-property @code{attachment} of @internalsref{Slur} in
1358 @internalsref{Voice} context It's value is a pair of symbols, specifying
1359 the attachment type of the left and right end points.
1361 @lilypond[fragment,relative,verbatim]
1363 \property Voice.Stem \set #'length = #5.5
1365 \property Voice.Slur \set #'attachment = #'(stem . stem)
1369 If a slur would strike through a stem or beam, the slur will be moved
1370 away upward or downward. If this happens, attaching the slur to the
1371 stems might look better:
1373 @lilypond[fragment,relative,verbatim]
1376 \property Voice.Slur \set #'attachment = #'(stem . stem)
1381 Similarly, the curvature of a slur is adjusted to stay clear of note
1382 heads and stems. When that would increase the curvature too much, the
1383 slur is reverted to its default shape. The threshold for this decision
1384 is in @internalsref{Slur}'s grob-property @code{beautiful}. It is loosely
1385 related to the enclosed area between the slur and the notes. Usually,
1386 the default setting works well, but in some cases you may prefer a
1387 curved slur when LilyPond decides for a vertically moved one. You can
1388 indicate this preference by increasing the @code{beautiful} value:
1390 @lilypond[verbatim,singleline,relative]
1392 c16( a' f' a a f a, )c,
1393 c( a' f' a a f d, )c
1394 \property Voice.Slur \override #'beautiful = #5.0
1395 c( a' f' a a f d, )c
1400 Producing nice slurs is a difficult problem, and LilyPond currently
1401 uses a simple, empiric method to produce slurs. In some cases, the
1402 results of this method don't look too good. This is reflected by the
1403 @code{beautiful} property, which it is an arbitrary parameter in the
1404 slur formatter. Useful values can only be determined by trial and
1407 @cindex Adjusting slurs
1409 @node Phrasing slurs
1410 @subsection Phrasing slurs
1412 @cindex phrasing slurs
1413 @cindex phrasing marks
1415 A phrasing slur (or phrasing mark) connects chords and is used to
1416 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1419 @lilypond[fragment,verbatim,center,relative]
1420 \time 6/4 c' \( ( d ) e f ( e ) \) d
1423 Typographically, the phrasing slur behaves almost exactly like a normal
1424 slur. The grob associated with it is @internalsref{PhrasingSlur}, in
1425 @internalsref{Voice} context.
1428 @subsection Breath marks
1430 Breath marks are entered using @code{\breathe}. The result is a
1431 @internalsref{BreathingSign} grob in @internalsref{Voice} context.
1433 @lilypond[fragment,relative]
1442 @cindex beats per minute
1443 @cindex metronome marking
1445 Metronome settings can be entered as follows:
1447 @cindex @code{\tempo}
1449 \tempo @var{duration} = @var{perminute}
1452 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1457 The tempo setting is not printed, but is only used in the MIDI
1458 output. You can trick lily into producing a metronome mark,
1459 though. Details are in @ref{Text markup}.
1464 @subsection Text spanners
1465 @cindex Text spanners
1467 Some textual indications, e.g. rallentando or accelerando, often extend
1468 over many measures. This is indicated by following the text with a
1469 dotted line. You can create such texts using text spanners. The syntax
1472 \spanrequest \start "text"
1473 \spanrequest \stop "text"
1475 LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
1476 in @internalsref{Voice} context). The string to be printed, as well as the
1477 style is set through grob properties.
1479 An application---or rather, a hack---is to fake octavation indications.
1480 @lilypond[fragment,relative,verbatim]
1481 \relative c' { a''' b c a
1482 \property Voice.TextSpanner \set #'type = #'dotted-line
1483 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1484 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1485 \property Staff.centralCPosition = #-13
1486 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1505 @subsection Articulations
1506 @cindex Articulations
1508 @cindex articulations
1512 A variety of symbols can appear above and below notes to indicate
1513 different characteristics of the performance. They are added to a note
1514 by adding @code{-}@var{script}
1515 @lilypond[singleline]
1517 \notes \context Voice {
1518 \property Voice.TextScript \set #'font-family = #'typewriter
1519 \property Voice.TextScript \set #'font-shape = #'upright
1525 c''4-^_"c-\\^{ }" s4
1530 The script is automatically placed, but if you need to force
1531 directions, you can use @code{_} to force them down, or @code{^} to
1533 @lilypond[fragment, verbatim]
1538 Other symbols can be added using the syntax
1539 @var{note}@code{-\}@var{name}. Again, they can be forced up or down
1540 using @code{^} and @code{_}.
1544 \property Score.LyricSyllable \override #'font-family =#'typewriter
1545 \property Score.LyricSyllable \override #'font-shape = #'upright
1546 \context Staff \notes {
1547 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1548 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1549 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1550 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1551 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1552 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1553 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1554 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1556 \context Lyrics \lyrics {
1557 accent__ marcato__ staccatissimo__ fermata
1558 stopped__ staccato__ tenuto__ upbow
1559 downbow__ lheel__ rheel__ ltoe
1560 rtoe__ turn__ open__ flageolet
1561 reverseturn__ trill__ prall__ mordent
1562 prallprall__ prallmordent__ uprall__ downprall
1563 upmordent__ downmordent__ pralldown__ prallup__
1564 lineprall__ thumb__ segno__ coda
1568 linewidth = 5.875\in
1577 Fingering instructions can also be entered in this shorthand. For
1578 finger changes, use markup texts:
1580 @lilypond[verbatim, singleline, fragment]
1581 c'4-1 c'4-2 c'4-3 c'4-4
1586 @cindex @code{\script}
1591 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
1595 All of these note ornaments appear in the printed output but have no
1596 effect on the MIDI rendering of the music.
1598 Unfortunately, there is no support for adding fingering instructions or
1599 ornaments to individual note heads. Some hacks exist, though. See
1600 @file{input/test/script-horizontal.ly}.
1605 @subsection Text scripts
1606 @cindex Text scripts
1608 In addition, it is possible to place arbitrary strings of text or markup
1609 text (see @ref{Text markup}) above or below notes by using a string:
1612 By default, these indications do not influence the note spacing, but
1613 by using the command @code{\fatText}, the widths will be taken into
1616 @lilypond[fragment,singleline,verbatim] \relative c' {
1617 c4^"longtext" \fatText c4_"longlongtext" c4 }
1620 It is possible to use @TeX{} commands in the strings, but this should be
1621 avoided because it makes it impossible for LilyPond to compute the
1622 exact length of the string, which may lead to collisions. Also, @TeX{}
1623 commands won't work with direct PostScript output (see @ref{PostScript
1626 Text scripts are created in form of @internalsref{TextScript} grobs, in
1627 @internalsref{Voice} context.
1629 @ref{Text markup} describes how to change the font or access
1630 special symbols in text scripts.
1633 @node Adding scripts
1634 @subsection Adding scripts
1636 TODO: should junk this subsect?
1638 You can add scripts by editing @file{scm/script.scm} and
1639 @file{ly/script-init.ly}. This file contains a table, listing script
1640 definitions and aliases. The following syntax accesses a script
1641 definition from the table:
1647 Usually the @code{\script} keyword is not used directly. Various
1648 helpful identifier definitions appear in @file{script.ly}.
1653 @subsection Grace notes
1657 @cindex @code{\grace}
1661 Grace notes are ornaments are written out ornaments
1662 @lilypond[relative=2,fragment]
1663 c4 \grace c16 c4 \grace { [c16 d16] } c4
1666 In normal notation, grace notes are supposed to take up no logical
1667 time in a measure. Such an idea is practical for normal notation, but
1668 is not strict enough to put it into a program. The model that LilyPond
1669 uses for grace notes internally is that all timing is done in two
1672 Every point in musical time consists of two rational numbers: one
1673 denotes the logical time, one denotes the grace timing. The above
1674 example is shown here with timing tuples.
1676 @lilypond[relative=2,fragment]
1677 c4^"(0,0)" \grace c16^"(1/4,-1/16)" c4^"(1/4,0)" \grace {
1678 [c16^"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4^"(2/4,0)"
1681 The advantage of this approach is that you can use almost any lilypond
1682 construction together with grace notes, for example slurs and clef
1683 changes may appear halfway in between grace notes:
1685 @lilypond[relative=2,fragment]
1686 c4 \grace { [ c16 c, \clef bass c, b(] } )c4
1689 The placement of these grace notes is synchronized between different
1690 staffs, using this grace timing.
1692 @lilypond[relative=2,fragment]
1693 \context Staff = SA { e4 \grace { c16 d e f } e4 }
1694 \context Staff = SB { c4 \grace { g8 b } c4 }
1698 The syntax is as follows.
1700 \grace @var{musicexpr}
1703 Unbeamed eighth notes and shorter by default have a slash through the
1706 @lilypond[fragment,verbatim]
1707 \relative c'' \context Voice {
1708 \grace c8 c4 \grace { [c16 c16] } c4
1710 \property Voice.Stem \override #'flag-style = #'()
1712 \property Voice.Stem \revert #'flag-style
1717 A grace note expression has duration 0; the next real note is assumed to
1718 be the main note. If you want the note to appear after the main note,
1719 set @code{Voice.graceAlignPosition} to @code{1}.
1724 Grace note synchronization can also lead to surprises. Staff notation,
1725 such as key signatures, barlines, etc. are also synchronized. Take
1726 care when you mix staffs with grace notes and staffs without.
1728 @lilypond[relative=2,fragment]
1729 \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
1730 \context Staff = SB { c4 \bar "|:" d4 }
1733 Nesting @code{\grace} notes is not supported. The following may cause
1737 @code{\grace @{ \grace c32 c16 @} c4}
1739 Since the meaning of such a construct is unclear, we don't consider this
1740 a loss. Similarly, juxtaposing two @code{\grace} sections is
1741 syntactically valid, but makes no sense and may cause runtime errors.
1742 Ending a staff or score with grace notes may also generate a run-time
1743 error, since there will be no main note to attach the grace notes to.
1754 @subsection Glissando
1757 @cindex @code{\glissando}
1759 A glissando line (grob @internalsref{Glissando}) can be requested by
1760 attaching a @code{\glissando} to a notte:
1762 @lilypond[fragment,relative,verbatim]
1768 Printing of an additional text (such as @emph{gliss.}) must be done
1775 @subsection Dynamics
1788 @cindex @code{\ffff}
1798 Absolute dynamic marks are specified using an identifier after a
1799 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1800 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1801 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1802 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1804 @lilypond[verbatim,singleline,fragment,relative]
1805 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1811 @cindex @code{\decr}
1812 @cindex @code{\rced}
1818 A crescendo mark is started with @code{\cr} and terminated with
1819 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1820 started with @code{\decr} and terminated with @code{\rced}. There are
1821 also shorthands for these marks. A crescendo can be started with
1822 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1823 can be terminated with @code{\!}. Note that @code{\!} must go before
1824 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1825 after the last note. Because these marks are bound to notes, if you
1826 want several marks during one note, you have to use spacer notes.
1828 @lilypond[fragment,verbatim,center]
1829 c'' \< \! c'' d'' \decr e'' \rced
1830 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1833 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1834 is an example how to do it:
1839 @lilypond[fragment,relative,verbatim]
1841 \property Voice.crescendoText = "cresc."
1842 \property Voice.crescendoSpanner = #'dashed-line
1847 For everyday use, we recommend the identifiers @code{\cresc},
1848 @code{endcresc}, @code{\dim} and @code{\enddim}.
1852 Dynamics are grobs of @internalsref{DynamicText} and
1853 @internalsref{Hairpin}. Vertical positioning of these symbols is
1854 handled by the @internalsref{DynamicLineSpanner} grob. If you want to
1855 adjust padding or vertical direction of the dynamics, you must set
1856 properties for the @internalsref{DynamicLineSpanner} grob. Predefined
1857 identifiers to set the vertical direction are \dynamicUp and
1860 @cindex direction, of dynamics
1861 @cindex @code{\dynamicDown}
1862 @cindex @code{\dynamicUp}
1870 @cindex @code{\repeat}
1872 To specify repeats, use the @code{\repeat} keyword. Since repeats
1873 should work differently when played or printed, there are a few
1874 different variants of repeats.
1878 Repeated music is fully written (played) out. Useful for MIDI
1879 output, and entering repetitive music.
1882 This is the normal notation: Repeats are not written out, but
1883 alternative endings (voltas) are printed, left to right.
1886 Alternative endings are written stacked. This has limited use but may be
1887 used to typeset two lines of lyrics in songs with repeats, see
1888 @file{input/star-spangled-banner.ly}.
1894 Make beat or measure repeats. These look like percent signs.
1900 * Repeats and MIDI::
1901 * Manual repeat commands::
1903 * Tremolo subdivisions::
1908 @subsection Repeat syntax
1910 The syntax for repeats is
1913 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1916 If you have alternative endings, you may add
1917 @cindex @code{\alternative}
1919 \alternative @code{@{} @var{alternative1}
1921 @var{alternative3} @dots{} @code{@}}
1923 where each @var{alternative} is a music expression.
1925 Normal notation repeats are used like this:
1926 @lilypond[fragment,verbatim]
1928 \repeat volta 2 { c'4 d' e' f' }
1929 \repeat volta 2 { f' e' d' c' }
1932 With alternative endings:
1933 @lilypond[fragment,verbatim]
1935 \repeat volta 2 {c'4 d' e' f'}
1936 \alternative { {d'2 d'} {f' f} }
1939 Folded repeats look like this:
1942 @lilypond[fragment,verbatim]
1944 \repeat fold 2 {c'4 d' e' f'}
1945 \alternative { {d'2 d'} {f' f} }
1949 If you don't give enough alternatives for all of the repeats, then
1950 the first alternative is assumed to be repeated often enough to equal
1951 the specified number of repeats.
1953 @lilypond[fragment,verbatim]
1957 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1958 \alternative { { g4 g g } { a | a a a a | b2. } }
1963 @node Repeats and MIDI
1964 @subsection Repeats and MIDI
1966 @cindex expanding repeats
1968 For instructions on how to unfoldi repeats for MIDI output, see
1969 the example file @file{input/test/unfold-all-repeats.ly}.
1974 Notice that timing information is not remembered at the start of an
1975 alternative, so you have to reset timing information after a repeat,
1976 e.g. using a bar-check (See @ref{Bar check}), setting
1977 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1978 are also not repeated.
1980 It is possible to nest @code{\repeat}s, although this probably is only
1981 meaningful for unfolded repeats.
1983 Folded repeats offer little more over simultaneous music. However, it
1984 is to be expected that more functionality -- especially for the MIDI
1985 backend -- will be implemented at some point in the future.
1987 Volta repeats are printed over all staves in a score. You must turn them
1988 off explicitly, for example by doing
1990 \property Staff.VoltaBracket = \turnOff
1992 in all but the top staff.
1994 @node Manual repeat commands
1995 @subsection Manual repeat commands
1997 @cindex @code{repeatCommands}
1999 The property @code{repeatCommands} can be used to control the layout of
2000 repeats. Its value is a Scheme list of repeat commands, where each repeat
2008 @item (volta . @var{text})
2009 Print a volta bracket saying @var{text}.
2011 Stop a running volta bracket
2014 @lilypond[verbatim, fragment]
2016 \property Score.repeatCommands = #'((volta "93") end-repeat)
2018 \property Score.repeatCommands = #'((volta #f))
2023 Repeats brackets are @internalsref{VoltaBracket} grobs.
2025 @node Tremolo repeats
2026 @subsection Tremolo repeats
2027 @cindex tremolo beams
2029 To place tremolo marks between notes, use @code{\repeat} with tremolo
2031 @lilypond[verbatim,center,singleline]
2033 \context Voice \notes\relative c' {
2034 \repeat "tremolo" 8 { c16 d16 }
2035 \repeat "tremolo" 4 { c16 d16 }
2036 \repeat "tremolo" 2 { c16 d16 }
2037 \repeat "tremolo" 4 c16
2042 Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
2043 @internalsref{StemTremolo}.
2048 At present, the spacing between tremolo beams is not regular, since the
2049 spacing engine does not notice that not all notes are printed.
2051 @node Tremolo subdivisions
2052 @subsection Tremolo subdivisions
2053 @cindex tremolo marks
2054 @cindex @code{tremoloFlags}
2056 Tremolo marks can be printed on a single note by adding
2057 `@code{:}[@var{length}]' after the note. The length must be at least 8.
2058 A @var{length} value of 8 gives one line across the note stem. If the
2059 length is omitted, then then the last value (stored in
2060 @code{Voice.tremoloFlags}) is used.
2062 @lilypond[verbatim,fragment,center]
2063 c'2:8 c':32 | c': c': |
2069 Tremolos in this style do not carry over into the MIDI output.
2072 @node Measure repeats
2073 @subsection Measure repeats
2075 @cindex percent repeats
2076 @cindex measure repeats
2078 In the @code{percent} style, a note pattern can be repeated. It is
2079 printed once, and then the pattern is replaced with a special sign.
2080 Patterns of a one and two measures are replaced by percent-like signs,
2081 patterns that divide the measure length are replaced by slashes.
2083 @lilypond[verbatim,singleline]
2084 \context Voice { \repeat "percent" 4 { c'4 }
2085 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
2089 The signs are represented by these grobs: @internalsref{RepeatSlash} and
2090 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
2094 You can not nest percent repeats, e.g. by filling in the first measure
2095 with slashes, and repeating that measure with percents.
2097 @node Rhythmic music
2098 @section Rhythmic music
2105 @node Rhythmic staves
2106 @subsection Rhythmic staves
2108 Sometimes you might want to show only the rhythm of a melody. This can
2109 be done with the rhythmic staff. All pitches of notes on such a staff
2110 are squashed, and the staff itself looks has a single staff line:
2112 @lilypond[fragment,relative,verbatim]
2113 \context RhythmicStaff {
2115 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
2122 @section Piano music
2124 Piano music is an odd type of notation. Piano staves are two normal
2125 staves coupled with a brace. The staves are largely independent, but
2126 sometimes voices can cross between the two staves. The
2127 @internalsref{PianoStaff} is especially built to handle this cross-staffing
2128 behavior. In this section we discuss the @internalsref{PianoStaff} and some
2129 other pianistic peculiarities.
2132 * Automatic staff changes::
2133 * Manual staff switches::
2136 * Voice follower lines::
2140 @c . {Automatic staff changes}
2141 @node Automatic staff changes
2142 @subsection Automatic staff changes
2143 @cindex Automatic staff changes
2145 Voices can switch automatically between the top and the bottom
2146 staff. The syntax for this is
2148 \autochange @var{contexttype} \context @var{childcontexttype}
2152 This will switch the interpretation context of @var{musicexp} between
2153 a @var{contexttype} named @code{up} and @code{down}. Typically, you
2154 use @internalsref{Staff} for @var{contexttype}, and
2155 @internalsref{Voice} for @var{childcontexttype}. The autochanger
2156 switches on basis of pitch (central C is the turning point), and it
2157 looks ahead skipping over rests to switch rests in advance.
2159 @lilypond[verbatim,singleline]
2160 \score { \notes \context PianoStaff <
2161 \context Staff = "up" {
2162 \autochange Staff \context Voice = VA < \relative c' {
2163 g4 a b c d r4 a g } > }
2164 \context Staff = "down" {
2170 Note how spacer rests are used to prevent the bottom staff from
2171 terminating too soon.
2174 @node Manual staff switches
2175 @subsection Manual staff switches
2177 @cindex manual staff switches
2178 @cindex staff switch, manual
2180 Voices can be switched between staves manually, using the following command:
2182 \translator Staff = @var{staffname} @var{music}
2184 The string @var{staffname} is the name of the staff. It switches the
2185 current voice from its current staff to the Staff called
2186 @var{staffname}. Typically @var{staffname} is @code{"up"} or
2189 The formal definition of this construct is obtuse, but for the sake of
2190 completeness we give it here.
2191 @cindex @code{\translator}
2193 \translator @var{contexttype} = @var{name}
2195 Formally, this construct is a music expression indicating
2196 that the context which is a direct child of the context of type
2197 @var{contexttype} should be shifted to a context of type
2198 @var{contexttype} and the specified name.
2206 Piano pedal instruction can be expressed using
2207 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
2208 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
2210 These identifiers are shorthands for spanner commands of the types
2211 @internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
2213 @lilypond[fragment,verbatim]
2214 c''4 \spanrequest \start "Sustain" c''4
2215 c''4 \spanrequest \stop "Sustain"
2218 The symbols that are printed can be modified by setting
2219 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
2220 Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
2221 @rgrob{SustainPedal}, for example, for more information.
2223 Pedals can also be indicated by a sequence of brackets, by setting the
2224 @code{pedal-type} property of SustainPedal grobs:
2226 @lilypond[fragment,verbatim]
2227 \property Staff.SustainPedal \override #'pedal-type = #'bracket
2228 c''4 \sustainDown d''4 e''4 a'4
2229 \sustainUp \sustainDown
2230 f'4 g'4 a'4 \sustainUp
2233 A third style of pedal notation is a mixture of text and brackets,
2234 obtained by setting @code{pedal-type} to @code{mixed}:
2236 @lilypond[fragment,verbatim]
2237 \property Staff.SustainPedal \override #'pedal-type = #'mixed
2238 c''4 \sustainDown d''4 e''4 c'4
2239 \sustainUp \sustainDown
2240 f'4 g'4 a'4 \sustainUp
2243 The default '*Ped' style for sustain and damper pedals corresponds to
2244 @code{\pedal-type = #'text}. However, @code{mixed} is the default style
2245 for a sostenuto pedal:
2247 @lilypond[fragment,verbatim]
2248 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2251 For fine-tuning of the appearance of a pedal bracket, the properties
2252 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
2253 @code{PianoPedalBracket} grobs (see the detailed documentation of
2254 @rgrob{PianoPedalBracket}) can be modified. For example, the bracket
2255 may be extended to the end of the note head.
2257 @lilypond[fragment,verbatim]
2258 \property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0)
2259 c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
2266 @subsection Arpeggio
2269 @cindex broken arpeggio
2270 @cindex @code{\arpeggio}
2272 You can specify an arpeggio sign on a chord by attaching an
2273 @code{\arpeggio} to a note of the chord.
2276 @lilypond[fragment,relative,verbatim]
2277 \context Voice <c\arpeggio e g c>
2280 When an arpeggio crosses staves in piano music, you attach an arpeggio
2281 to the chords in both staves, and set
2282 @code{PianoStaff.connectArpeggios}.
2284 @lilypond[fragment,relative,verbatim]
2285 \context PianoStaff <
2286 \property PianoStaff.connectArpeggios = ##t
2287 \context Voice = one { <c'\arpeggio e g c> }
2288 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2292 This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
2293 are @code{PianoStaff.Arpeggio}.
2295 To add an arrow head to explicitly specify the direction of the
2296 arpeggio, you should set the arpeggio grob property
2297 @code{arpeggio-direction}.
2299 @lilypond[fragment,relative,verbatim]
2301 \property Voice.Arpeggio \override #'arpeggio-direction = #1
2303 \property Voice.Arpeggio \override #'arpeggio-direction = #-1
2308 A square bracket on the left indicates that the player should not
2309 arpeggiate the chord. To draw these brackets, set the
2310 @code{molecule-callback} property of @code{Arpeggio} or
2311 @code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
2312 @code{\arpeggio} statements within the chords as before.
2314 @lilypond[fragment,relative,verbatim]
2315 \context PianoStaff <
2316 \property PianoStaff.connectArpeggios = ##t
2317 \property PianoStaff.Arpeggio \override
2318 #'molecule-callback = \arpeggioBracket
2319 \context Voice = one { <c'\arpeggio e g c> }
2320 \context Voice = other { \clef bass <c,,\arpeggio e g>}
2327 It is not possible to mix connected arpeggios and unconnected arpeggios
2332 @node Voice follower lines
2333 @subsection Voice follower lines
2335 @cindex follow voice
2336 @cindex staff switching
2339 @cindex @code{followVoice}
2341 Whenever a voice switches to another staff a line connecting the notes
2342 can be printed automatically. This is enabled if the property
2343 @code{PianoStaff.followVoice} is set to true:
2345 @lilypond[fragment,relative,verbatim]
2346 \context PianoStaff <
2347 \property PianoStaff.followVoice = ##t
2348 \context Staff \context Voice {
2350 \translator Staff=two
2353 \context Staff=two {\clef bass \skip 1*2 }
2357 The associated grob is @internalsref{VoiceFollower}.
2364 * Tablatures basic::
2365 * Non-guitar tablatures::
2366 * Tablature in addition to normal staff::
2369 @node Tablatures basic
2370 @subsection Tablatures basic
2371 @cindex Tablatures basic
2373 Tablature can be typeset with Lilypond by using the
2374 @internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
2375 tablatures is a recent feature in Lilypond, most of the guitar special
2376 effects (hammer, pull, bend, ...) are not yet supported.
2378 With the @internalsref{TabStaff}, the string number associated to a note
2379 is given though the fingering mechanism, e.g. @code{c4-3} for a C
2380 quarter on the third string. The string 1 is the lowest one, and the
2381 tuning defaults to the standard guitar tuning (with 6 strings).
2383 @lilypond[fragment,verbatim]
2386 \property Staff.Stem \override #'direction = #1
2395 @node Non-guitar tablatures
2396 @subsection Non-guitar tablatures
2397 @cindex Non-guitar tablatures
2399 There are many ways to customize Lilypond tablatures.
2401 First you can change the number of string, e.g.
2402 @code{StaffSymbol \override #'line-count = #5} to have only 5 strings.
2403 Because of a kind of bug in Lilypond, you MUST create a new type of
2404 context if you want different tablatures with diiferent number of
2407 Then you can change the strings tuning. String tuning is given as a
2408 Scheme list with one integer number for each string, the number being
2409 the string note pitch if not fretted (open note).
2411 Finally, it is possible to change the Scheme function to format the
2412 tablature note text. The default is @var{fret-number-tablature-format},
2413 which uses the fret number, but for some instruments that may not use
2414 this notation, just create your own tablature-format function. This
2415 function takes three argument: the string number, the string tuning and
2419 @node Tablature in addition to normal staff
2420 @subsection Tablature in addition to normal staff
2421 @cindex Tablature in addition to normal staff
2423 It is possible to typeset both tablature and a "normal" staff, as
2424 commonly done in many parts.
2426 A common trick for that is to put the notes in a variables, and to hide
2427 the fingering information (which correspond to the string number) for
2436 \context StaffGroup <
2438 % Hide fingering number (used for string number) for the "normal" staff
2439 \property Staff.Fingering \override #'transparent = ##t
2444 \property Staff.Stem \override #'direction = #1
2461 * Automatic syllable durations::
2467 @subsection Lyrics mode
2470 To print lyrics, you must first make a music expression from the lyric
2471 text. That music expression can be printed by selecting an appropriate
2475 @cindex @code{\lyrics}
2477 You can enter lyrics in a special input mode of LilyPond. This mode is
2478 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
2479 The purpose of this mode is that you can enter lyrics as plain text,
2480 punctuation and accents without any hassle.
2482 Syllables are entered like notes, with pitches replaced by text. For
2483 example, @code{Twin- kle twin- kle} enters four syllables. Note that
2484 the hyphen has no special meaning for lyrics, and does not introduce
2487 Spaces can be introduced into a lyric either by using quotes:
2488 @code{"He could"4 not4} or by using an underscore without quotes:
2489 @code{He_could4 not4}. All unquoted underscores are converted to
2492 The precise definition of this mode can be found in @ref{Lyrics mode
2495 @c . {Printing lyrics}
2496 @node Printing lyrics
2497 @subsection Printing lyrics
2500 Lyrics are printed by interpreting them in the @internalsref{Lyrics} context.
2502 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
2503 @c Add tied and beamed melismata too.
2504 @lilypond[verbatim,singleline]
2506 \notes \relative c' {
2508 \property Staff.automaticMelismata = ##t
2509 d'2 c4 b16 ( a g a b a b ) c a2
2510 b2 c4 b8 ( a16 g ) a4 g2 }
2511 \context Lyrics \lyrics {
2513 share the soft -- ware; }
2517 Notes and syllable durations are matched automatically. This is
2518 accomplished using @code{\addlyrics}, which is documented in
2519 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
2520 the melody staff will cause tied, slurred or beamed notes to be
2521 interpreted as melismata.
2523 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
2526 @cindex lyric extender
2529 As you can see, extender lines are entered as @code{__}. This will
2530 create an extender, a line that extends over the entire duration of the
2531 lyric. This line will run all the way to the start of the next lyric,
2532 so you may want to shorten it by using a blank lyric (using @code{_}).
2533 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2538 If you want to have hyphens centered between syllables (rather than
2539 attached to the end of the first syllable) you can use the special
2540 `@code{-}@code{-}' lyric as a separate word between syllables. This
2541 will result in a hyphen whose length varies depending on the space
2542 between syllables. It will be centered between the syllables. The grob
2543 for this symbol is @code{LyricsVoice.LyricHyphen}.
2545 @cindex Lyric hyphen
2547 @node Automatic syllable durations
2548 @subsection Automatic syllable durations
2549 @cindex Automatic syllable durations
2551 @cindex automatic lyric durations
2552 @cindex @code{\addlyrics}
2554 If you have lyrics that are set to a melody, you can copy the rhythm
2555 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2558 \addlyrics @var{musicexpr1 musicexpr2}
2561 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2562 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2563 when there are events in @var{musicexpr1}.
2565 @cindex @code{automaticMelismata}
2567 If the property @code{automaticMelismata} is set in the
2568 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2571 @lilypond[verbatim,fragment]
2574 \property Voice.automaticMelismata = ##t
2575 c8 () cis d8. e16 f2
2577 \context Lyrics \lyrics {
2581 If you want the lyric lines to be above the melody staff, or in some
2582 other, more complex configuration, then build that configuration first
2583 using simultaneous music, and use @code{\addlyrics} after that.
2585 @lilypond[verbatim, singleline]
2587 \context Lyrics = LA { s1 }
2588 \context Staff = SA { s1 }
2590 \context Staff = SA \relative c' { c4 e g g }
2591 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2594 For @code{\addlyrics} you should use a single rhythm melody, and single
2595 rhythm lyrics (a constant duration is the obvious choice). If you do
2596 not, you can get undesired effects when using multiple stanzas:
2598 @lilypond[verbatim,fragment]
2601 c8 () cis d8. e16 f2
2603 \context Lyrics \lyrics
2608 It is valid (but probably not very useful) to use notes instead of
2609 lyrics for @var{musicexpr2}.
2612 @subsection More stanzas
2616 If you have multiple stanzas printed underneath each other, the vertical
2617 groups of syllables should be aligned around punctuation. LilyPond can
2618 do this if you tell it which lyric lines belong to which melody.
2620 To this end, give the Voice context an identity, and set the LyricsVoice
2621 to a name starting with that identity followed by a dash.
2622 In the following example, the Voice
2623 identity is @code{duet}, and the identities of the LyricsVoices are
2624 @code{duet-1} and @code{duet-2}.
2627 @lilypond[singleline,verbatim]
2630 \notes \relative c'' \context Voice = duet { \time 3/4
2632 \lyrics \context Lyrics <
2633 \context LyricsVoice = "duet-1" {
2634 \property LyricsVoice . stanza = "Bert"
2635 Hi, my name is bert. }
2636 \context LyricsVoice = "duet-2" {
2637 \property LyricsVoice . stanza = "Ernie"
2638 Ooooo, ch\'e -- ri, je t'aime. }
2643 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2644 first system) and @code{LyricsVoice.stz} for the following
2645 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2651 @cindex stanza numbering
2659 LilyPond has support for both entering and printing chords.
2660 @lilypond[verbatim,singleline]
2661 twoWays = \notes \transpose c'' {
2671 < \context ChordNames \twoWays
2672 \context Voice \twoWays > }
2675 This example also shows that the chord printing routines do not try to
2676 be intelligent. If you enter @code{f bes d}, it does not interpret
2677 this as an inversion.
2679 As you can see chords really are a set of pitches. They are internally
2680 stored as simultaneous music expressions. This means you can enter
2681 chords by name and print them as notes, enter them as notes and print
2682 them as chord names, or (the most common case) enter them by name, and
2687 * Printing named chords::
2692 @subsection Chords mode
2695 Chord mode is a mode where you can input sets of pitches using common
2696 names. It is introduced by the keyword @code{\chords}. It is similar
2697 to note mode, but words are also looked up in a chord modifier table
2698 (containing @code{maj}, @code{dim}, etc). Dashes and carets are used
2699 to indicate chord additions and subtractions, so articulation scripts
2700 can not be entered in Chord mode.
2702 Throughout these examples, chords have been shifted around the staff
2703 using @code{\transpose}.
2705 @lilypond[fragment,verbatim]
2709 c:9 c:9-.5+.7+ c:3-.5-
2719 The second type of modifier that may appear after the @code{:} is a
2720 named modifier. Named modifiers are listed in the file
2721 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2722 @code{min} which lower the 3rd half a step, `@code{aug}' which
2723 raises the 5th, `@code{dim}' which lowers the 5th,
2724 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2725 which replaces the 5th with a 4th.
2727 @lilypond[fragment,verbatim]
2730 c1:m c:min7 c:maj c:aug c:dim c:sus
2736 Chord subtractions are used to eliminate notes from a chord. The
2737 notes to be subtracted are listed after a @code{^} character,
2740 @lilypond[fragment,verbatim,center]
2749 Chord inversions can be specified by appending `@code{/}' and the name
2750 of a single note to a chord. In a chord inversion, the inverted note is
2751 transposed down until it is the lowest note in the chord. If the note
2752 is not in the chord, a warning will be printed.
2754 @lilypond[fragment,verbatim,center]
2764 Bass notes can be added by `@code{/+}' and
2765 the name of a single note to a chord. This has the effect of
2766 adding the specified note to the chord, lowered by an octave,
2767 so it becomes the lowest note in the chord.
2769 @lilypond[fragment,verbatim,center]
2778 The formal syntax for named chords is as follows:
2780 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2783 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2784 the chord duration in the usual notation. There are two kinds of
2785 modifiers. One type is formed by @emph{chord additions}. Additions are
2786 obtained by listing intervals separated by dots. An interval is written
2787 by its number with an optional @code{+} or @code{-} to indicate raising
2788 or lowering by half a step. Chord additions have two effects: they adds
2789 the specified interval and all lower odd numbered intervals to the
2790 chord, and they may lower or raise the specified interval.
2795 Implementation details are gory. For example @code{c:4} not only adds
2796 a fourth, but also removes the third.
2799 @c . {Printing named chords}
2800 @node Printing named chords
2801 @subsection Printing named chords
2803 @cindex printing chord names
2807 For displaying printed chord names, use the @internalsref{ChordNames} context.
2808 The chords may be entered either using the notation described above, or
2809 directly using simultaneous music.
2811 @lilypond[verbatim,singleline]
2813 \chords {a1 b c} <d f g> <e g b>
2817 \context ChordNames \scheme
2818 \context Staff \transpose c'' \scheme
2823 You can make the chord changes stand out by setting
2824 @code{ChordNames.chordChanges} to true. This will only display chord
2825 names when there's a change in the chords scheme and at the start of a
2830 c1:m c:m \break c:m c:m d
2834 \context ChordNames {
2835 \property ChordNames.chordChanges = ##t
2837 \context Staff \transpose c'' \scheme
2839 \paper{linewidth= 9.\cm}
2843 LilyPond examines chords specified as lists of notes to determine a name
2844 to give the chord. LilyPond will not try to identify chord inversions or
2845 an added bass note, which may result in strange chord names when chords
2846 are entered as a list of pitches:
2848 @lilypond[verbatim,center,singleline]
2857 \context ChordNames \scheme
2858 \context Staff \scheme
2864 By default, a chord name system proposed by Harald Banter (See
2865 @ref{Literature}) is used. The system is very regular and predictable.
2866 Typical American style chord names may be selected by setting the
2867 @code{style} property of the @code{ChordNames.ChordName} grob to
2868 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2870 Routines that determine the names to be printed are written in Scheme,
2871 and may be customized by the user. The code can be found in
2872 @file{scm/chord-name.scm}. Here's an example showing the differences in
2876 @c maybe just junk verbatim option?
2877 @lilypond[verbatim,singleline]
2887 \context ChordNames = banter \scheme
2888 \context ChordNames = american {
2889 \property ChordNames.ChordName \override
2890 #'style = #'american \scheme }
2891 \context ChordNames = jazz {
2892 \property ChordNames.ChordName \override
2893 #'style = #'jazz \scheme }
2894 \context Staff \transpose c'' \scheme
2901 @section Writing parts
2903 Orchestral music involves some special notation, both in the full score,
2904 as in the individual parts. This section explains how to tackle common
2905 problems in orchestral music.
2912 * Instrument names::
2914 * Multi measure rests::
2915 * Automatic part combining::
2916 * Hara kiri staves::
2917 * Sound output for transposing instruments::
2920 @c . {Rehearsal marks}
2921 @node Rehearsal marks
2922 @subsection Rehearsal marks
2923 @cindex Rehearsal marks
2925 @cindex @code{\mark}
2927 To print a rehearsal mark, use the @code{\mark} command.
2928 @lilypond[fragment,verbatim]
2935 c1 \mark #'(music "scripts-segno")
2940 As you can see, the mark is incremented automatically if you use
2941 @code{\mark \default}. The value to use is stored in the property
2942 @code{rehearsalMark} is used and automatically incremented. The grob
2943 is @internalsref{RehearsalMark} in @internalsref{Score} context. See
2944 @code{input/test/boxed-molecule.ly} if you need boxes around the
2948 @subsection Bar numbers
2952 @cindex measure numbers
2953 @cindex currentBarNumber
2955 They are printed at the
2956 start of the line. The number itself is a property that can be set by
2957 modifying the @code{currentBarNumber} property, i.e.
2959 \property Score.currentBarNumber = #217
2962 If you want boxed bar numbers, see the example file
2963 @code{input/test/boxed-molecule.ly}.
2965 Bar numbers are @internalsref{BarNumber} grobs.
2969 It is not possible to have bar numbers printed at regular intervals
2972 Barnumbers can collide with the StaffGroup, if there is one at the
2973 top. To solve this, You have to twiddle with the
2974 @internalsref{padding} property of @internalsref{BarNumber} if your
2975 score starts with a @internalsref{StaffGroup}.
2977 @node Instrument names
2978 @subsection Instrument names
2980 In scores, the instrument name is printed before the staff. This can
2981 be done by setting @code{Staff.instrument} and
2982 @code{Staff.instr}. This will print a string before the start of the
2983 staff. For the first start, @code{instrument} is used, for the next
2984 ones @code{instr} is used.
2986 @lilypond[verbatim,singleline]
2987 \property Staff.instrument = "ploink " { c''4 }
2990 You can also use markup texts to construct more complicated instrument
2994 @lilypond[verbatim,singleline]
2996 '((font-relative-size . -2 ) (music "accidentals--1")))
2999 \property Staff.instrument = #`((kern . 0.5) (lines
3000 "2 Clarinetti" (columns " (B" ,text-flat ")")))
3008 When you put a name on a grand staff or piano staff the width of the
3009 brace is not taken into account. You must add extra spaces to the end of
3010 the name to avoid a collision.
3013 @subsection Transpose
3015 @cindex transposition of pitches
3016 @cindex @code{\transpose}
3018 A music expression can be transposed with @code{\transpose}. The syntax
3021 \transpose @var{pitch} @var{musicexpr}
3024 This means that middle C in @var{musicexpr} is transposed to
3027 @code{\transpose} distinguishes between enharmonic pitches: both
3028 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
3029 a tone. The first version will print sharps and the second version
3032 @lilypond[singleline, verbatim]
3033 mus =\notes { \key e \major c d e f }
3034 \score { \notes \context Staff {
3037 \transpose des'' \mus
3038 \transpose cis'' \mus
3042 If you want to use both @code{\transpose} and @code{\relative}, then
3043 you must use @code{\transpose} first. @code{\relative} will have no
3044 effect music that appears inside a @code{\transpose}.
3046 @c . {Multi measure rests}
3047 @node Multi measure rests
3048 @subsection Multi measure rests
3049 @cindex Multi measure rests
3053 Multi measure rests are entered using `@code{R}'. It is specifically
3054 meant for full bar rests and for entering parts: the rest can expand to
3056 rests, or it can be printed as a single multimeasure rest This expansion
3057 is controlled by the property @code{Score.skipBars}. If this is set to true,
3058 Lily will not expand empty measures, and the appropriate number is added
3061 @lilypond[fragment,verbatim]
3062 \time 3/4 r2. | R2. | R2.*2
3063 \property Score.skipBars = ##t R2.*17 R2.*4
3066 Notice that the @code{R2.} is printed as a whole rest, centered in the
3069 @cindex whole rests for a full measure
3071 The grob for this object is @internalsref{MultiMeasureRest}.
3075 Currently, there is no way to automatically condense multiple rests
3076 into a single multimeasure rest. Multi measure rests do not take part
3079 @cindex condensing rests
3081 @node Automatic part combining
3082 @subsection Automatic part combining
3083 @cindex automatic part combining
3084 @cindex part combiner
3087 Automatic part combining is used to merge two parts of music onto a
3088 staff in an intelligent way. It is aimed primarily at typesetting
3089 orchestral scores. When the two parts are identical for a period of
3090 time, only one is shown. In places where the two parts differ, they
3091 are typeset as separate voices, and stem directions are set
3092 automatically. Also, solo and @emph{a due} parts can be identified
3095 The syntax for part combining is
3098 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
3100 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
3101 combined into one context of type @var{context}. The music expressions
3102 must be interpreted by contexts whose names should start with @code{one}
3105 The most useful function of the part combiner is to combine parts into
3106 one voice, as common for wind parts in orchestral scores:
3108 @lilypond[verbatim,singleline,fragment]
3110 \context Voice=one \partcombine Voice
3111 \context Thread=one \relative c'' {
3114 \context Thread=two \relative c'' {
3120 Notice that the first @code{g} appears only once, although it was
3121 specified twice (once in each part). Stem, slur and tie directions are
3122 set automatically, depending whether there is a solo or unisono. The
3123 first part (with context called @code{one}) always gets up stems, and
3124 `solo', while the second (called @code{two}) always gets down stems and
3127 If you just want the merging parts, and not the textual markings, you
3128 may set the property @var{soloADue} to false.
3130 @lilypond[verbatim,singleline,fragment]
3132 \property Staff.soloADue = ##f
3133 \context Voice=one \partcombine Voice
3134 \context Thread=one \relative c'' {
3137 \context Thread=two \relative c'' {
3143 There are a number of other properties that you can use to tweak the
3144 behavior of part combining, refer to the automatically generated
3145 documentation of @reng{Thread_devnull_engraver} and
3146 @reng{Voice_devnull_engraver}. Look at the documentation of the
3147 responsible engravers, @code{Thread_devnull_engraver},
3148 @code{Voice_devnull_engraver} and @code{A2_engraver}.
3152 In @code{soloADue} mode, when the two voices play the same notes on and
3153 off, the part combiner may typeset @code{a2} more than once in a
3156 @lilypond[fragment,singleline]
3158 \context Voice=one \partcombine Voice
3159 \context Thread=one \relative c'' {
3162 \context Thread=two \relative c'' {
3168 @cindex @code{Thread_devnull_engraver}
3169 @cindex @code{Voice_engraver}
3170 @cindex @code{A2_engraver}
3172 @node Hara kiri staves
3173 @subsection Hara kiri staves
3175 In orchestral scores, staff lines that only have rests are usually removed.
3176 This saves some space. LilyPond also supports this through the hara
3177 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
3178 the Japanese Samourai warriors.} staff. This staff commits suicide when
3179 it finds itself to be empty after the line-breaking process. It will
3180 not disappear when it contains normal rests, you must use multi measure
3183 The hara kiri staff is specialized version of the @internalsref{Staff}
3184 context. It is available as the context identifier
3185 @code{\HaraKiriStaffContext}. Observe how the second staff in this
3186 example disappears in the second line.
3190 \notes \relative c' <
3191 \context Staff = SA { e4 f g a \break c1 }
3192 \context Staff = SB { c4 d e f \break R1 }
3196 \translator { \HaraKiriStaffContext }
3202 @node Sound output for transposing instruments
3203 @subsection Sound output for transposing instruments
3205 When you want to make a MIDI file from a score containing transposed
3206 and untransposed instruments, you have to instruct LilyPond the pitch
3207 offset (in semitones) for the transposed instruments. This is done
3208 using the @code{transposing} property. It does not affect printed
3211 @cindex @code{transposing}
3214 \property Staff.instrument = #"Cl. in B-flat"
3215 \property Staff.transposing = #-2
3221 @node Ancient notation
3222 @section Ancient notation
3225 * Ancient note heads::
3232 @node Ancient note heads
3233 @subsection Ancient note heads
3235 To get a longa note head, you have to use mensural note heads. This
3236 is accomplished by setting the @code{style} property of the
3237 NoteHead grob to @code{mensural}. There is also a note head style
3238 @code{baroque} which gives mensural note heads for @code{\longa} and
3239 @code{\breve} but standard note heads for shorter notes.
3241 @lilypond[fragment,singleline,verbatim]
3242 \property Voice.NoteHead \set #'style = #'mensural
3243 \property Voice.NoteHead \set #'font-family = #'ancient
3248 @subsection Custodes
3253 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
3254 staff context symbol that appears at the end of a staff line. It
3255 anticipates the pitch of the first note(s) of the following line and
3256 thus helps the player or singer to manage line breaks during
3257 performance, thus enhancing readability of a score.
3262 \property Staff.Custos \set #'style = #'mensural
3267 \consists Custos_engraver
3273 Custodes were frequently used in music notation until the 17th century.
3274 There were different appearances for different notation styles.
3275 Nowadays, they have survived only in special forms of musical notation
3276 such as via the @emph{editio vaticana} dating back to the beginning of
3279 For typesetting custodes, just put a @code{Custos_engraver} into the
3280 @internalsref{Staff} context when declaring the @code{\paper} block. In this
3281 block, you can also globally control the appearance of the custos symbol
3282 by setting the custos @code{style} property. Currently supported styles
3283 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
3290 \consists Custos_engraver
3291 Custos \override #'style = #'mensural
3296 The property can also be set locally, for example in a @code{\notes}
3301 \property Staff.Custos \override #'style = #'vaticana
3302 c'1 d' e' d' \break c' d' e' d'
3307 @subsection Ancient clefs
3309 LilyPond supports a variety of clefs, many of them ancient. These can
3310 be selected from the @code{ancient} font family, by setting
3311 @code{Staff.clefGlyph}) to the following values
3320 @item clefs-vaticana_do
3321 Editio Vaticana style do clef
3322 @item clefs-vaticana_fa
3323 Editio Vaticana style fa clef
3324 @item clefs-medicaea_do
3325 Editio Medicaea style do clef
3326 @item clefs-medicaea_fa
3327 Editio Medicaea style fa clef
3328 @item clefs-mensural1_c
3329 modern style mensural C clef
3330 @item clefs-mensural2_c
3331 historic style small mensural C clef
3332 @item clefs-mensural3_c
3333 historic style big mensural C clef
3334 @item clefs-mensural1_f
3335 historic style traditional mensural F clef
3336 @item clefs-mensural2_f
3337 historic style new mensural F clef
3338 @item clefs-mensural_g
3339 historic style mensural G clef
3340 @item clefs-hufnagel_do
3341 historic style hufnagel do clef
3342 @item clefs-hufnagel_fa
3343 historic style hufnagel fa clef
3344 @item clefs-hufnagel_do_fa
3345 historic style hufnagel combined do/fa clef
3346 @item clefs-percussion
3347 modern style percussion clef
3350 @emph{Modern style} means ``as is typeset in current editions.''
3351 @emph{Historic style} means ``as was typeset or written in contemporary
3352 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
3355 @cindex Vaticana, Editio
3356 @cindex Medicaea, Editio
3357 @cindex hufnagel clefs
3361 @subsection Figured bass
3363 @cindex Basso continuo
3365 LilyPond has limited support for figured bass:
3367 @lilypond[verbatim,fragment]
3369 \context FiguredBass
3374 \context Voice { c4 g8 }
3378 The support for figured bass consists of two parts: there is an input
3379 mode, introduced by @code{\figures}, where you can enter bass figures
3380 as numbers, and there is a context called @internalsref{FiguredBass}
3381 that takes care of making @internalsref{BassFigure} grobs.
3383 In figures input mode, a group of bass figures is delimited by
3384 @code{<} and @code{>}. The duration is entered after the @code{>}.
3386 \context FiguredBass
3393 Accidentals are added to the numbers if you alterate them by
3394 appending @code{-}, @code{!} and @code{+}.
3397 \context FiguredBass
3398 \figures { <4- 6+ 7!> }
3404 Spaces or dashes may be inserted by using @code{_}. Brackets are
3405 introduced with @code{[} and @code{]}.
3408 \context FiguredBass
3409 \figures { < [4 6] 8 [_ 12]> }
3415 Although the support for figured bass may superficially resemble chord
3416 support, it works much simpler: in figured bass simply stores the
3417 numbers, and then prints the numbers you entered. There is no
3418 conversion to pitches, and no realizations of the bass are played in
3422 @c . {Tuning output}
3424 @section Tuning output
3426 LilyPond tries to take as much formatting as possible out of your
3427 hands. Nevertheless, there are situations where it needs some help, or
3428 where you want to override its decisions. In this section we discuss
3429 ways to do just that.
3431 Formatting is internally done by manipulating so called grobs (graphic
3432 objects). Each grob carries with it a set of properties (grob
3433 properties) specific to that object. For example, a stem grob has
3434 properties that specify its direction, length and thickness.
3436 The most direct way of tuning the output is by altering the values of
3437 these properties. There are two ways of doing that: first, you can
3438 temporarily change the definition of a certain type of grob, thus
3439 affecting a whole set of objects. Second, you can select one specific
3440 object, and set a grob property in that object.
3443 * Tuning groups of grobs ::
3444 * Tuning per grob ::
3452 @node Tuning groups of grobs
3453 @subsection Tuning groups of grobs
3455 @cindex grob description
3459 A grob definition is a Scheme association list, that is stored in a
3460 context property. By assigning to that property (using plain
3461 @code{\property}), you can change the resulting grobs.
3463 @lilypond[verbatim, fragment]
3464 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
3467 The @code{\property} assignment effectively empties the definition of
3468 the Stem object. One of the effects is that the recipe of how it should be
3469 printed is erased, with the effect of rendering it invisible. The above
3470 assignment is available as a standard identifier, for the case that you
3474 \property Voice.Stem = \turnOff
3481 This mechanism is fairly crude, since you can only set, but not modify,
3482 the definition of a grob. For this reason, there is a more advanced
3485 The definition of a grob is actually a list of default grob
3486 properties. For example, the definition of the Stem grob (available in
3487 @file{scm/grob-description.scm}), defines the following values for
3492 (beamed-lengths . (0.0 2.5 2.0 1.5))
3493 (Y-extent-callback . ,Stem::height)
3497 You can add a property on top of the existing definition, or remove a
3498 property, thus overriding the system defaults:
3500 c'4 \property Voice.Stem \override #'thickness = #4.0
3501 c'4 \property Voice.Stem \revert #'thickness
3504 You should balance @code{\override} and @code{\revert}. If that's too
3505 much work, you can use the @code{\set} shorthand. It performs a revert
3506 followed by an override. The following example gives exactly the same
3507 result as the previous one.
3509 c'4 \property Voice.Stem \set #'thickness = #4.0
3510 c'4 \property Voice.Stem \set #'thickness = #0.8
3513 If you use @code{\set}, you must explicitly restore the default.
3516 Formally the syntax for these constructions is
3518 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
3519 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
3520 \property @var{context}.@var{grobname} \revert @var{symbol}
3522 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
3523 and @var{grobname} are strings and @var{value} is a Scheme expression.
3526 If you revert a setting which was not set in the first place, then it
3527 has no effect. However, if the setting was set as a system default, it
3528 may remove the default value, and this may give surprising results,
3529 including crashes. In other words, @code{\override} and @code{\revert},
3530 must be carefully balanced.
3532 These are examples of correct nesting of @code{\override}, @code{\set},
3535 A clumsy but correct form:
3537 \override \revert \override \revert \override \revert
3540 Shorter version of the same:
3542 \override \set \set \revert
3545 A short form, using only @code{\set}. This requires you to know the
3548 \set \set \set \set @var{to default value}
3551 If there is no default (i.e. by default, the grob property is unset),
3554 \set \set \set \revert
3557 For the digirati, the grob description is an Scheme association
3558 list. Since a Scheme list is a singly linked list, we can treat it as a
3559 stack, and @code{\override} and @code{\revert} are just push and pop
3560 operations. This pushing and popping is also used for overriding
3561 automatic beaming settings.
3565 LilyPond will hang or crash if @var{value} contains cyclic references.
3566 The backend is not very strict in type-checking grob properties. If you
3567 @code{\revert} properties that are expected to be set by default,
3571 @cindex adjusting staff symbol
3572 @cindex StaffSymbol, using \property
3573 @cindex staff lines, setting number of
3575 Some grobs are created at the moment that their context is created. An
3576 example of such a grob is the staff itself (i.e. the horizontal lines).
3577 You can not change the appearance of the staff symbol by manipulating
3578 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
3579 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
3580 created before any @code{\override} is effective. You can deal with this
3581 either overriding properties in a @code{\translator} definition, or by
3582 using @code{\outputproperty}.
3587 @node Tuning per grob
3588 @subsection Tuning per grob
3590 @cindex \outputproperty
3592 A second way of tuning grobs is the more arcane @code{\outputproperty}
3593 feature. The syntax is as follows:
3595 \outputproperty @var{predicate} @var{symbol} = @var{value}
3597 Here @code{predicate} is a Scheme function taking a grob argument, and
3598 returning a boolean. This statement is processed by the
3599 @code{Output_property_engraver}. It instructs the engraver to feed all
3600 grobs that it sees to @var{predicate}. Whenever the predicate returns
3601 true, the grob property @var{symbol} will be set to @var{value}.
3603 You will need to combine this statement with @code{\context} to select
3604 the appropriate context to apply this to.
3606 Here are some random examples.
3609 In the following example, all note heads occurring at current staff
3610 level, are shifted up and right by setting their @code{extra-offset}
3613 @lilypond[fragment,verbatim,singleline]
3615 \context Staff \outputproperty
3616 #(make-type-checker 'note-head-interface)
3617 #'extra-offset = #'(0.5 . 0.75)
3621 @cindex @code{extra-offset}
3623 In this example, the predicate checks the @code{text} grob property, to
3624 shift only the `m.d.' text, but not the fingering instruction "2".
3625 @lilypond[verbatim,singleline]
3626 #(define (make-text-checker text)
3627 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
3630 \notes\relative c''' {
3631 \property Voice.Stem \set #'direction = #1
3632 \outputproperty #(make-text-checker "m.d.")
3633 #'extra-offset = #'(-3.5 . -4.5)
3641 If possible, avoid this feature: the semantics are not very clean, and
3642 the syntax and semantics are up for rewrite.
3647 @node Font selection
3648 @subsection Font selection
3650 Most graphics in LilyPond are composed of characters of fonts. You can
3651 alter the characteristics of the font by setting certain grob
3652 properties. The mechanism that is used for this resembles La@TeX{}'s New
3653 Font Selection Scheme. Within this scheme, a font is entirely
3654 characterized by its font name.
3656 For each grob that uses fonts (in other words, each grob that supports
3657 @code{font-interface}) a font-name must be selected before it can be
3658 printed. The font name is selected by looking at a number of grob
3663 A symbol indicating the general class of the typeface. Supported are
3664 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
3665 @code{music} (the standard music font), @code{dynamic} (font for dynamic
3666 signs) and @code{typewriter}
3669 A symbol indicating the shape of the font, there are typically several
3670 font shapes available for each font family. Choices are @code{italic},
3671 @code{caps} and @code{upright}
3674 A symbol indicating the series of the font. There are typically several
3675 font series for each font family and shape. Choices are @code{medium}
3678 @item font-relative-size
3679 A number indicating the size relative the standard size. For example,
3680 with 20pt staff height, relative size -1 corresponds to 16pt staff
3681 height, and relative size +1 corresponds to 23 pt staff height.
3683 @item font-design-size
3684 A number indicating the design size of the font.
3686 This is a feature of the Computer Modern Font: each point size has a
3687 slightly different design. Smaller design sizes are relatively wider,
3688 which enhances readability. Scalable type faces such TrueType and Adobe
3689 Type1 usually come as ``one design fits all sizes''.
3692 The name of the font, as a string, e.g. @code{"cmr12"}. This overrides
3693 all other font-qualifiers.
3697 The font is selected by taking the first font that satisfies all
3698 qualifiers specified. You can override any of these fields through
3699 @code{\override} and @code{\revert}. The special value @code{*} matches
3700 any value for that qualifier.
3703 \property Lyrics.LyricText \override #'font-series = #'bold
3704 \property Lyrics.LyricText \override #'font-shape = #'*
3707 @cindex @code{font-style}
3709 There are also pre-cooked font selection qualifiers. These are selected
3710 through the grob property @code{font-style}. For example, the style
3711 @code{finger} selects family @code{number} and relative size @code{-3}.
3712 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3713 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3716 The style sheets and tables for selecting fonts are located in
3717 @file{scm/font.scm}. Refer to this file for more information.
3720 Setting @code{font-name} overrides all other qualifiers. The value for
3721 this property should be a string, the file name of the font. You may use
3722 this to use special fonts, which are not a part of the style sheet, or
3723 which have special encodings.
3725 The size of the font may be set with the grob property
3726 @code{font-magnification}. It is the size of font, relative to its
3727 standard size. For example, @code{1.0} is normal size.
3731 Relative size is not linked to any real size.
3733 There is no style sheet provided for other fonts besides the @TeX{}
3736 @cindex font selection
3737 @cindex font magnification
3738 @cindex @code{font-interface}
3742 @subsection Text markup
3746 LilyPond has an internal mechanism to typeset texts. You can
3747 form text markup expressions by composing scheme expressions
3748 in the following way.
3750 @lilypond[verbatim, singleline]
3755 c^#'(italic "italic")
3756 d_#'((bold italic) "ff")
3758 f_#'(lines "one" (bold "two"))
3759 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3763 Normally, the Scheme markup text is stored in the @code{text} property
3764 of a grob. Formally, it is defined as follows:
3767 text: string | (head? text+)
3768 head: markup | (markup+)
3769 markup-item: property | abbrev
3770 property: (@var{key} . @var{value})
3771 abbrev: @code{columns lines roman music bold italic named super sub}
3772 @code{overstrike text finger volta timesig mmrest mark script}
3773 @code{large Large dynamic}
3776 The markup is broken down and converted into a list of grob properties,
3777 which are prepended to the property list. The @var{key}-@var{value}
3778 pair is a grob property. A list of properties available is included in
3779 the generated documentation for @rint{Text_interface}.
3781 The following abbreviations are currently defined:
3784 horizontal mode: set all text on one line (default)
3786 vertical mode: set every text on a new line
3790 selects the Feta font (the standard font for music notation glyphs),
3791 and uses named lookup
3798 lookup by character name
3800 plain text lookup (by character value)
3806 the next text or character overstrikes this one
3808 select fingering number fontstyle
3810 select volta number fontstyle
3812 select time signature number fontstyle
3814 select multi measure rest number fontstyle
3816 select mark number fontstyle
3818 select scriptsize roman fontstyle
3820 select large roman fontstyle
3822 select Large roman fontstyle
3824 select dynamics fontstyle
3828 @cindex metronome mark
3830 One practical application of complicated markup is to fake a metronome
3834 #(define note '(columns
3835 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3836 #(define eight-note `(columns ,note ((kern . -0.1)
3837 (music ((raise . 3.5) "flags-u3")))))
3838 #(define dotted-eight-note
3839 `(columns ,eight-note (music "dots-dot")))
3842 \notes\relative c'' {
3843 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3849 TextScript \override #'font-shape = #'upright
3855 @node Invisible grobs
3856 @subsection Invisible grobs
3857 @cindex invisible grobs
3861 ben nog steeds niet kapot van de informatiedichtheid hier.
3867 You can imagine a number of situations where you would want to make
3868 certain grobs not show up in the output. There may be aesthetic
3869 reasons, to make the output resemble an (old) manuscript as close as
3870 possible, or to make lessons or exercises for students.
3872 Grobs can be made invisible in a number of ways:
3874 Here's an example with blanked-out notes and stems:
3875 @lilypond[singleline,verbatim]
3877 \property Voice.NoteHead \override
3879 \property Voice.Stem \override
3880 #'transparent = ##t }
3883 \property Voice.NoteHead \revert #'transparent
3884 \property Voice.Stem \revert #'transparent }
3887 \notes\relative c'' {
3889 a b c b \blanknotes c \unblanknotes d
3893 This method makes the grobs invisible but they still take the normal space.
3894 To remove all traces of the grob, you can redefine the function
3898 \notes\relative c'' {
3901 as bes c bes c d \break
3902 \property Staff.KeySignature \override #'molecule-callback = #'()
3905 \paper{linewidth=5.0\cm indent=0}
3909 A very rigorous way of removing grobs from the whole score is to remove
3910 the engraver that creates them. For example,
3911 @lilypond[singleline,verbatim]
3912 \score {\notes { c'4 d'8 e'8 g2 }
3913 \paper { \translator {
3915 \remove Stem_engraver
3919 However, as you can see, this can lead to unexpected effects.
3922 @subsection Dirty tricks
3923 @cindex embedded tex
3925 @lilypond[fragment,relative,verbatim]
3926 a'^"3 $\\times$ \\`a deux"
3932 TODO: Move this section.
3937 Generating optically pleasing spacing is black magic. LilyPond tries
3938 to deal with a number of frequent cases. Here is an example that is
3939 not handled correctly, due to the combination of chord collisions and
3944 \context PianoStaff \notes \transpose c''' <
3945 \context Staff = up { s1 }
3946 \context Staff = down { [c8 c \translator Staff=up <c d> c
3947 \translator Staff=down c c c] }
3949 \paper { linewidth = -1 }
3957 @section Page layout
3960 The page layout is the combined product of LilyPond formatting notation,
3961 and (La)@TeX{} putting the notation on a page, including page breaks.
3962 The part of LilyPond is documented here.
3976 @subsection Paper block
3979 The most important output definition is the @code{\paper} block, for
3980 music notation. The syntax is
3983 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3986 where each of the items is one of
3989 @item An assignment.
3991 @item A context definition. See @ref{Interpretation context} for
3992 more information on context definitions.
3994 @item \stylesheet declaration. Its syntax is
3996 \stylesheet @var{alist}
3999 See @file{scm/font.scm} for details of @var{alist}.
4000 @item an @code{\elementdescriptions} declaration.
4002 \elementdescriptions @var{alist}
4004 See @file{scm/grob-description.scm} for details of
4005 @var{alist}. This command is not user-serviceable.
4009 @c . {Paper variables}
4010 @node Paper variables
4011 @subsection Paper variables
4012 @cindex Paper variables
4014 The paper block has some variables you may want to use or change:
4017 @cindex @code{indent}
4019 The indentation of the first line of music.
4020 @cindex @code{staffspace}
4022 @item @code{staffspace}
4023 The distance between two staff lines, calculated from the center
4026 @cindex @code{linewidth}
4027 @item @code{linewidth}
4028 Sets the width of the lines.
4030 If set to a negative value, a single unjustified line is produced.
4031 @c rename to singleLinePaper ?
4032 The shorthand @code{\singleLine} defines a default paper block that
4033 produces a single line.
4035 @cindex @code{textheight}
4037 @item @code{textheight}
4038 Sets the total height of the music on each page. Only used by
4041 @cindex @code{interscoreline}
4043 @item @code{interscoreline}
4044 Sets the spacing between systems. The default is 16pt.
4046 @cindex @code{interscorelinefill}
4048 @item @code{interscorelinefill}
4049 If set to a positive number, the distance between the score
4050 lines will stretch in order to fill the full page. In that
4051 case @code{interscoreline} specifies the minimum spacing.
4056 @cindex @code{stafflinethickness}
4058 @item @code{stafflinethickness}
4059 Determines the thickness of staff lines, and also acts as a scaling
4060 parameter for other line thicknesses.
4063 You may enter these dimension using units (@code{cm}, @code{in},
4064 @code{mm}, @code{pt}), or relative to another dimension
4066 linewidth = 20.0 * \staffspace
4073 @subsection Font size
4074 @cindex font size, setting
4075 @cindex staff size, setting
4076 @cindex @code{paper} file
4078 The Feta font provides musical symbols at six different sizes. These
4079 fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
4080 point. The point size of a font is the height of the five lines in a
4081 staff when displayed in the font.
4083 Definitions for these sizes are the files @file{paperSZ.ly}, where
4084 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
4085 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
4086 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
4087 @code{paperTwentysix} are defined respectively. The default
4088 @code{\paper} block is also set. These files should be imported at toplevel, i.e.
4090 \include "paper26.ly"
4094 The font definitions are generated using a Scheme function. For more
4095 details, see the file @file{scm/font.scm}.
4101 @subsection Paper size
4106 @cindex @code{papersize}
4108 To change the paper size, you must first set the
4109 @code{papersize} paper variable variable. Set it to
4110 the strings @code{a4}, @code{letter}, or @code{legal}. After this
4111 specification, you must set the font as described above. If you want
4112 the default font, then use the 20 point font.
4115 \paper@{ papersize = "a4" @}
4116 \include "paper16.ly"
4119 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
4120 will set the paper variables @code{hsize} and @code{vsize} (used by
4121 Lilypond and @code{ly2dvi})
4125 @subsection Line break
4128 @cindex breaking lines
4130 Line breaks are normally computed automatically. They are chosen such
4131 that it looks neither cramped nor loose, and that consecutive lines have
4134 Occasionally you might want to override the automatic breaks; you can do
4135 this by specifying @code{\break}. This will force a line break at this
4136 point. Do remember that line breaks can only occur at places where there
4137 are bar lines. If you want to have a line break where there is no
4138 bar line, you can force an invisible bar line by entering @code{\bar
4139 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
4141 If you want linebreaks at regular intervals, you can use the following:
4144 < \repeat 7 unfold @{ s1 * 4 \break @}
4148 This makes the following 28 measures (assuming 4/4 time) be broken every
4152 @cindex @code{\penalty}
4154 The @code{\break} and @code{\noBreak} commands are defined in terms of
4155 the penalty command:
4160 This encourages or discourages LilyPond to make a line break at this
4165 The scaling of the @code{\penalty} argument is not well-defined. The
4166 command is rather kludgey, and slated for rewriting.
4170 @subsection Page break
4173 @cindex breaking pages
4175 Page breaks are normally computed by @TeX{}, so they are not under
4176 direct control of LilyPond. However, you can insert a commands into the
4177 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
4178 the command @code{\newpage}
4179 @cindex @code{\newpage}
4185 @c why do so difficult?
4186 @c maybe should explain contents of between-system.ly,
4187 @c but not now, we're talking about page breaks here.
4189 @c details, see the example file @file{input/test/between-systems.ly}
4192 @c . {Output scaling}
4193 @node Output scaling
4194 @subsection Output scaling
4209 There is no mechanism to select magnification of particular fonts,
4210 meaning that you don't have access to continuously scaled fonts.
4214 @c . {Output formats}
4215 @node Output formats
4216 @section Output formats
4218 LilyPond can output processed music in different output formats.
4222 * PostScript output::
4224 * ASCIIScript output::
4229 @subsection TeX output
4232 LilyPond will use @TeX{} by default. Even if you want to produce
4233 PostScript output for viewing or printing, you should normally have
4234 LilyPond produce @TeX{} first. The .tex output must be processed by
4235 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
4236 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
4237 used to generate the .dvi for you.
4241 Titling is not generated unless you use @file{ly2dvi}.
4244 @node PostScript output
4245 @subsection PostScript output
4246 @cindex PostScript output
4247 @cindex direct PostScript output
4249 LilyPond can produce PostScript directly, without going through @TeX{}.
4250 Currently, this is mainly useful if you cannot use TeX, because direct
4251 PostScript output has some problems; see Bugs below.
4254 $ lilypond -fps foo.ly
4255 GNU LilyPond 1.3.144
4256 Now processing: `foo.ly'
4258 Interpreting music...[3]
4259 Preprocessing elements...
4260 Calculating column positions...
4261 paper output to foo.ps...
4263 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
4269 Text font selection is broken.
4271 The .ps file does not contain the .pfa font files. To print a .ps
4272 created through direct postscript output, you should prepend the
4273 necessary .pfa files to LilyPond's .ps output, or upload them to the
4274 printer before printing.
4276 The line height calculation is broken, you must set @var{lineheight} in
4277 the paperblock if you have more than one staff in your score, e.g.
4282 % Set line height to 40 staff spaces
4288 @subsection Scheme output
4289 @cindex Scheme output
4291 In the typesetting stage, LilyPond builds a page description, which is
4292 then written to disk in postscript, @TeX{} or ASCII art. Before it is
4293 written, the page description is represented as Scheme expressions. You
4294 can also dump these Scheme expressions to a file, which may be
4295 convenient for debugging output routines. This is done with the Scheme
4299 $ lilypond -fscm foo.ly
4300 GNU LilyPond 1.3.144
4301 Now processing: `foo.ly'
4303 Interpreting music...[3]
4304 Preprocessing elements...
4305 Calculating column positions...
4306 paper output to foo.scm...
4309 ;;; Usage: guile -s x.scm > x.tex
4310 (primitive-load-path 'standalone.scm)
4314 $ guile -s foo.scm > foo.tex
4318 @node ASCIIScript output
4319 @subsection ASCIIScript output
4320 @cindex ASCIIScript output
4321 @cindex ascii script
4324 LilyPond can output ASCII Art. This is a two step process, LilyPond
4325 produces an ASCII description file, dubbed ASCIIScript (extension
4326 @file{.as}). ASCIIScript has a small and simple command set that
4327 includes font selection, character and string printing and line drawing
4328 commands. The program @file{as2text} is used to translate an .as file
4331 To produce ASCII Art, you must include an ASCII Art paper definition
4332 file in your .ly, one of:
4334 \include "paper-as5.ly"
4335 \include "paper-as9.ly"
4338 Here's an example use for ASCII Art output (the example file
4339 @file{as-email.ly} is included in the LilyPond distribution), the staff
4340 symbol has been made invisible:
4343 $ lilypond -fas as-email.ly
4344 GNU LilyPond 1.3.144
4345 Now processing: `as-email.ly'
4347 Interpreting music...[3]
4348 Preprocessing elements...
4349 Calculating column positions... [2]
4350 paper output to as-email.as...
4352 $ as2text as-email.as 2>/dev/null
4354 |/ |##|##| | | | | |
4355 /| | | | | |\ |\ |\ |\ |\ |
4356 / |_ 3 | | | | 5 | )| )| )| )| )|
4357 | /| \ 8 * * * | 8 * * * * * |
4367 The ASCII Art fonts are far from complete and not very well designed.
4368 It's easy to change the glyphs, though; if you think you can do better,
4369 have a look at @file{mf/*.af}.
4371 Lots of resizable symbols such as slurs, ties and tuplets are missing.
4373 The poor looks of most ASCII Art output and its limited general
4374 usefulness gives ASCII Art output a low priority; it may be
4375 dropped in future versions.
4379 @subsection Sketch output
4381 @uref{http://sketch.sourceforge.net,Sketch} is a Free vector drawing
4382 program. LilyPond includes bare bones output for Sketch version 0.7.
4385 @cindex vector drawing
4386 @cindex drawing program
4393 LilyPond can produce MIDI output. The performance lacks lots of
4394 interesting effects, such as swing, articulation, slurring, etc., but it
4395 is good enough for proof-hearing the music you have entered. Ties,
4396 dynamics and tempo changes are interpreted.
4398 Dynamic marks, crescendi and decrescendi translate into MIDI volume
4399 levels. Dynamic marks translate to a fixed fraction of the available
4400 MIDI volume range, crescendi and decrescendi make the the volume vary
4401 linearly between their two extremities. The fractions be adjusted by
4402 overriding the @code{absolute-volume-alist} defined in
4403 @file{scm/midi.scm}.
4405 For each type of musical instrument (that MIDI supports), a volume range
4406 can be defined. This gives you basic equalizer control, which can
4407 enhance the quality of the MIDI output remarkably. You can add
4408 instruments and ranges or change the default settings by overriding the
4409 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
4411 Both loudness controls are combined to produce the final MIDI volume.
4416 It is currently not possible to use the percussion channel (generally
4417 channel 10 of a MIDI file).
4421 * MIDI instrument names::
4426 @subsection MIDI block
4430 The MIDI block is analogous to the paper block, but it is somewhat
4431 simpler. The @code{\midi} block can contain:
4435 @item a @code{\tempo} definition
4436 @item context definitions
4439 Assignments in the @code{\midi} block are not allowed.
4443 @cindex context definition
4445 Context definitions follow precisely the same syntax as within the
4446 \paper block. Translation modules for sound are called performers.
4447 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
4450 @node MIDI instrument names
4451 @subsection MIDI instrument names
4453 @cindex instrument names
4454 @cindex @code{Staff.midiInstrument}
4455 @cindex @code{Staff.instrument}
4457 The MIDI instrument name is set by the @code{Staff.midiInstrument}
4458 property or, if that property is not set, the @code{Staff.instrument}
4459 property. The instrument name should be chosen from the list in
4460 @ref{MIDI instruments}.
4464 If the selected string does not exactly match, then LilyPond uses the
4465 default (Grand Piano). It is not possible to select an instrument by
4475 @c FIXME: Note entry vs Music entry at top level menu is confusing.
4477 @node Interpretation context
4478 @section Interpretation context
4481 * Creating contexts::
4482 * Default contexts::
4483 * Context properties::
4484 * Engravers and performers::
4485 * Changing context definitions::
4486 * Defining new contexts::
4490 Interpretation contexts are objects that only exist during a run of
4491 LilyPond. During the interpretation phase of LilyPond (when it prints
4492 "interpreting music"), the music expression in a @code{\score} block is
4493 interpreted in time order. This is the same order that humans hear and
4496 During this interpretation, the interpretation context holds the
4497 state for the current point within the music. It contains information
4501 @item What notes are playing at this point?
4502 @item What symbols will be printed at this point?
4503 @item What is the current key signature, time signature, point within
4507 Contexts are grouped hierarchically: A @internalsref{Voice} context is
4508 contained in a @internalsref{Staff} context (because a staff can contain
4509 multiple voices at any point), a @internalsref{Staff} context is contained in
4510 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
4512 Contexts associated with sheet music output are called @emph{notation
4513 contexts}, those for sound output are called @emph{performance
4514 contexts}. The default definitions of the standard notation and
4515 performance contexts can be found in @file{ly/engraver-init.ly} and
4516 @file{ly/performer-init.ly}, respectively.
4518 @node Creating contexts
4519 @subsection Creating contexts
4521 @cindex @code{\context}
4522 @cindex context selection
4524 Contexts for a music expression can be selected manually, using the
4525 following music expression.
4528 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4531 This instructs lilypond to interpret @var{musicexpr} within the context
4532 of type @var{contexttype} and with name @var{contextname}. If this
4533 context does not exist, it will be created.
4535 @lilypond[verbatim,singleline]
4537 \notes \relative c'' {
4538 c4 <d4 \context Staff = "another" e4> f
4544 In this example, the @code{c} and @code{d} are printed on the
4545 default staff. For the @code{e}, a context Staff called
4546 @code{another} is specified; since that does not exist, a new
4547 context is created. Within @code{another}, a (default) Voice context
4548 is created for the @code{e4}. When all music referring to a
4549 context is finished, the context is ended as well. So after the
4550 third quarter, @code{another} is removed.
4554 @node Default contexts
4555 @subsection Default contexts
4557 Most music expressions don't need an explicit @code{\context}
4558 declaration: they inherit the
4559 notation context from their parent. Each note is a music expression, and
4560 as you can see in the following example, only the sequential music
4561 enclosing the three notes has an explicit context.
4563 @lilypond[verbatim,singleline]
4564 \score { \notes \context Voice = goUp { c'4 d' e' } }
4567 There are some quirks that you must keep in mind when dealing with
4570 First, every top level music is interpreted by the Score context, in other
4571 words, you may think of @code{\score} working like
4574 \context Score @var{music}
4578 Second, contexts are created automatically to be able to interpret the
4579 music expressions. Consider the following example.
4581 @lilypond[verbatim, singleline]
4582 \score { \context Score \notes { c'4 ( d' )e' } }
4585 The sequential music is interpreted by the Score context initially
4586 (notice that the @code{\context} specification is redundant), but when a
4587 note is encountered, contexts are setup to accept that note. In this
4588 case, a Thread, Voice and Staff are created. The rest of the sequential
4589 music is also interpreted with the same Thread, Voice and Staff context,
4590 putting the notes on the same staff, in the same voice.
4592 This is a convenient mechanism, but do not expect opening chords to work
4593 without @code{\context}. For every note, a separate staff is
4596 @cindex explicit context
4597 @cindex starting with chords
4598 @cindex chords, starting with
4600 @lilypond[verbatim, singleline]
4601 \score { \notes <c'4 es'> }
4604 Of course, if the chord is preceded by a normal note in sequential
4605 music, the chord will be interpreted by the Thread of the preceding
4607 @lilypond[verbatim,singleline]
4608 \score { \notes { c'4 <c'4 es'> } }
4613 @node Context properties
4614 @subsection Context properties
4616 Notation contexts have properties. These properties are from
4617 the @file{.ly} file using the following expression:
4618 @cindex @code{\property}
4620 \property @var{contextname}.@var{propname} = @var{value}
4623 Sets the @var{propname} property of the context @var{contextname} to the
4624 specified Scheme expression @var{value}. All @var{propname} and
4625 @var{contextname} are strings, which are typically unquoted.
4627 Properties that are set in one context are inherited by all of the
4628 contained contexts. This means that a property valid for the
4629 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
4630 example) and thus take effect in all @internalsref{Voice} contexts.
4632 Properties can be unset using the following expression:
4634 \property @var{contextname}.@var{propname} \unset
4637 @cindex properties, unsetting
4638 @cindex @code{\unset}
4640 This removes the definition of @var{propname} in @var{contextname}. If
4641 @var{propname} was not defined in @var{contextname} (but was inherited
4642 from a higher context), then this has no effect.
4647 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4648 the inverse of @code{\property \set}.
4650 @node Engravers and performers
4651 @subsection Engravers and performers
4655 Basic building blocks of translation are called engravers; they are
4656 special C++ classes.
4660 @c . {Context definitions}
4661 @node Changing context definitions
4662 @subsection Changing context definitions
4664 @cindex context definition
4665 @cindex translator definition
4667 The most common way to define a context is by extending an existing
4668 context. You can change an existing context from the paper block, by
4669 first initializing a translator with an existing context identifier:
4673 @var{context-identifier}
4676 Then you can add and remove engravers using the following syntax:
4678 \remove @var{engravername}
4679 \consists @var{engravername}
4683 Here @var{engravername} is a string, the name of an engraver in the
4687 @lilypond[verbatim,singleline]
4691 \translator { \StaffContext
4692 \remove Clef_engraver
4698 You can also set properties in a translator definition. The syntax is as
4701 @var{propname} = @var{value}
4702 @var{propname} \set @var{grob-propname} = @var{pvalue}
4703 @var{propname} \override @var{grob-propname} = @var{pvalue}
4704 @var{propname} \revert @var{grob-propname}
4706 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4707 and @code{pvalue} are Scheme expressions. These type of property
4708 assignments happen before interpretation starts, so a @code{\property}
4709 command will override any predefined settings.
4712 To simplify editing translators, all standard contexts have standard
4713 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4714 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
4716 @node Defining new contexts
4717 @subsection Defining new contexts
4719 If you want to build a context from scratch, you must also supply the
4720 following extra information:
4722 @item A name, specified by @code{\name @var{contextname}}.
4724 @item A cooperation module. This is specified by @code{\type
4731 \type "Engraver_group_engraver"
4734 \consists "Staff_symbol_engraver"
4735 \consists "Note_head_engraver"
4736 \consistsend "Axis_group_engraver"
4740 The argument of @code{\type} is the name for a special engraver that
4741 handles cooperation between simple engravers such as
4742 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4743 for this engraver are the following:
4745 @cindex @code{Engraver_group_engraver}
4746 @item @code{Engraver_group_engraver}
4747 The standard cooperation engraver.
4749 @cindex @code{Score_engraver}
4751 @item @code{Score_engraver}
4752 This is cooperation module that should be in the top level context,
4753 and only the top level context.
4755 @cindex @code{Grace_engraver_group}
4757 @item @code{Grace_engraver_group}
4758 This is a special cooperation module (resembling
4759 @code{Score_engraver}) that is used to create an embedded
4766 @item @code{\alias} @var{alternate-name}
4767 This specifies a different name. In the above example,
4768 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4770 @item @code{\consistsend} @var{engravername}
4771 Analogous to @code{\consists}, but makes sure that
4772 @var{engravername} is always added to the end of the list of
4775 Some engraver types need to be at the end of the list; this
4776 insures they stay there even if a user adds or removes engravers.
4777 End-users generally don't need this command.
4779 @item @code{\accepts} @var{contextname}
4780 Add @var{contextname} to the list of contexts this context can
4781 contain in the context hierarchy. The first listed context is the
4782 context to create by default.
4784 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4785 completeness, but is never used in practice.
4788 @item @code{\name} @var{contextname}
4789 This sets the type name of the context, e.g. @internalsref{Staff},
4790 @internalsref{Voice}. If the name is not specified, the translator won't do
4794 In the @code{\paper} block, it is also possible to define translator
4795 identifiers. Like other block identifiers, the identifier can only
4796 be used as the very first item of a translator. In order to define
4797 such an identifier outside of @code{\score}, you must do
4802 foo = \translator @{ @dots{} @}
4809 \translator @{ \foo @dots{} @}
4817 @cindex paper types, engravers, and pre-defined translators
4824 @c . {Syntactic details}
4825 @node Syntactic details
4826 @section Syntactic details
4827 @cindex Syntactic details
4829 This section describes details that were too boring to be put elsewhere.
4834 * Music expressions::
4835 * Manipulating music expressions::
4844 @subsection Top level
4847 This section describes what you may enter at top level.
4851 @subsubsection Score
4854 @cindex score definition
4856 The output is generated combining a music expression with an output
4857 definition. A score block has the following syntax:
4860 \score @{ @var{musicexpr} @var{outputdefs} @}
4863 @var{outputdefs} are zero or more output definitions. If none is
4864 supplied, the default @code{\paper} block will be added.
4868 @c . {Default output}
4869 @subsubsection Default output
4871 Default values for the @code{\paper} and @code{\midi} block are set by
4872 entering such a block at the top level.
4875 @subsubsection Header
4877 @cindex @code{\header}
4880 A header describes bibliographic information of the file's contents. It
4881 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4882 use this information for generating titles. Key values that are used by
4883 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4884 meter, arranger, piece and tagline.
4886 @cindex @code{ly2dvi}
4890 \header @{ @var{key1} = @var{val1}
4891 @var{key2} = @var{val2} @dots{} @}
4894 It is customary to put the @code{\header} at the top of the file.
4896 @subsubsection Default output
4898 A @code{\midi} or @code{\paper} block at top level sets the default
4899 paper block for all scores that lack an explicit paper block.
4903 @subsection Identifiers
4907 What has this section got to do with identifiers?
4908 It seems more appropriate in the introduction to Chapter 4,
4914 All of the information in a LilyPond input file, is internally
4915 represented as a Scheme value. In addition to normal Scheme data types
4916 (such as pair, number, boolean, etc.), LilyPond has a number of
4917 specialized data types,
4924 @item Translator_def
4928 @item Music_output_def
4929 @item Moment (rational number)
4932 LilyPond also includes some transient object types. Objects of these
4933 types are built during a LilyPond run, and do not `exist' per se within
4934 your input file. These objects are created as a result of your input
4935 file, so you can include commands in the input to manipulate them,
4936 during a lilypond run.
4939 @item Grob: short for Graphical object.
4940 @item Molecule: device-independent page output object,
4941 including dimensions. Produced by some Grob functions
4942 @item Translator: object that produces audio objects or Grobs. This is
4943 not yet user accessible.
4944 @item Font_metric: object representing a font.
4948 @node Music expressions
4949 @subsection Music expressions
4951 @cindex music expressions
4953 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4954 syllables are music expressions, and you can combine music expressions
4955 to form new ones, for example by enclosing a list of expressions in
4956 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4957 compound expression is formed out of the quarter note @code{c} and a
4958 quarter note @code{d}:
4961 \sequential @{ c4 d4 @}
4964 @cindex Sequential music
4965 @cindex @code{\sequential}
4966 @cindex sequential music
4969 @cindex Simultaneous music
4970 @cindex @code{\simultaneous}
4972 The two basic compound music expressions are simultaneous and
4976 \sequential @code{@{} @var{musicexprlist} @code{@}}
4977 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4979 For both, there is a shorthand:
4981 @code{@{} @var{musicexprlist} @code{@}}
4985 @code{<} @var{musicexprlist} @code{>}
4987 for simultaneous music.
4988 In principle, the way in which you nest sequential and simultaneous to
4989 produce music is not relevant. In the following example, three chords
4990 are expressed in two different ways:
4992 @lilypond[fragment,verbatim,center]
4993 \notes \context Voice {
4994 <a c'> <b d' > <c' e'>
4995 < { a b c' } { c' d' e' } >
5000 Other compound music expressions include
5003 \transpose @var{pitch} @var{expr}
5004 \apply @var{func} @var{expr}
5005 \context @var{type} = @var{id} @var{expr}
5006 \times @var{fraction} @var{expr}
5010 @c . {Manipulating music expressions}
5011 @node Manipulating music expressions
5012 @subsection Manipulating music expressions
5014 The @code{\apply} mechanism gives you access to the internal
5015 representation of music. You can write Scheme-functions that operate
5016 directly on it. The syntax is
5018 \apply #@var{func} @var{music}
5020 This means that @var{func} is applied to @var{music}. The function
5021 @var{func} should return a music expression.
5023 This example replaces the text string of a script. It also shows a dump
5024 of the music it processes, which is useful if you want to know more
5025 about how music is stored.
5027 @lilypond[verbatim,singleline]
5028 #(define (testfunc x)
5029 (if (equal? (ly-get-mus-property x 'text) "foo")
5030 (ly-set-mus-property x 'text "bar"))
5032 (ly-set-mus-property x 'elements
5033 (map testfunc (ly-get-mus-property x 'elements)))
5038 \apply #testfunc { c'4_"foo" }
5042 For more information on what is possible, see the automatically
5043 generated documentation.
5046 Directly accessing internal representations is dangerous: the
5047 implementation is subject to changes, so you should avoid this feature
5050 A final example is a function that reverses a piece of music in time:
5052 @lilypond[verbatim,singleline]
5053 #(define (reverse-music music)
5054 (let* ((elements (ly-get-mus-property music 'elements))
5055 (reversed (reverse elements))
5056 (span-dir (ly-get-mus-property music 'span-direction)))
5057 (ly-set-mus-property music 'elements reversed)
5059 (ly-set-mus-property music 'span-direction (- span-dir)))
5060 (map reverse-music reversed)
5063 music = \notes { c'4 d'4( e'4 f'4 }
5065 \score { \context Voice {
5067 \apply #reverse-music \music
5072 More examples are given in the distributed example files in
5075 @c . {Span requests}
5081 @subsection Span requests
5082 @cindex Span requests
5084 Notational constructs that start and end on different notes can be
5085 entered using span requests. The syntax is as follows:
5089 \spanrequest @var{startstop} @var{type}
5093 @cindex @code{\start}
5094 @cindex @code{\stop}
5096 This defines a spanning request. The @var{startstop} parameter is either
5097 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
5098 describes what should be started. Much of the syntactic sugar is a
5099 shorthand for @code{\spanrequest}, for example,
5101 @lilypond[fragment,verbatim,center]
5102 c'4-\spanrequest \start "slur"
5103 c'4-\spanrequest \stop "slur"
5106 Among the supported types are @code{crescendo}, @code{decrescendo},
5107 @code{beam}, @code{slur}. This is an internal command. Users are
5108 encouraged to use the shorthands which are defined in the initialization
5109 file @file{spanners.ly}.
5114 @subsection Assignments
5117 Identifiers allow objects to be assigned to names during the parse
5118 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
5119 and to refer to an identifier, you precede its name with a backslash:
5120 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
5121 the input-types listed above. Identifier assignments can appear at top
5122 level in the LilyPond file, but also in @code{\paper} blocks.
5124 An identifier can be created with any string for its name, but you will
5125 only be able to refer to identifiers whose names begin with a letter,
5126 being entirely alphabetical. It is impossible to refer to an identifier
5127 whose name is the same as the name of a keyword.
5129 The right hand side of an identifier assignment is parsed completely
5130 before the assignment is done, so it is allowed to redefine an
5131 identifier in terms of its old value, e.g.
5137 When an identifier is referenced, the information it points to is
5138 copied. For this reason, an identifier reference must always be the
5139 first item in a block.
5143 \paperIdent % wrong and invalid
5147 \paperIdent % correct
5152 @c . {Lexical modes}
5154 @subsection Lexical modes
5155 @cindex Lexical modes
5158 @cindex @code{\notes}
5159 @cindex @code{\chords}
5160 @cindex @code{\lyrics}
5162 To simplify entering notes, lyrics, and chords, LilyPond has three
5163 special input modes in addition to the default mode: note, lyrics and
5164 chords mode. These input modes change the way that normal, unquoted
5165 words are interpreted: for example, the word @code{cis} may be
5166 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
5167 major triad respectively.
5169 A mode switch is entered as a compound music expression
5171 @code{\notes} @var{musicexpr}
5172 @code{\chords} @var{musicexpr}
5173 @code{\lyrics} @var{musicexpr}.
5176 In each of these cases, these expressions do not add anything to the
5177 meaning of their arguments. They just instruct the parser in what mode
5178 to parse their arguments. The modes are treated in more detail in
5179 @ref{Lyrics} and @ref{Chords}.
5181 Different input modes may be nested.
5185 @subsection Ambiguities
5190 The grammar contains a number of ambiguities. We hope to resolve them at
5194 @item The assignment
5199 is interpreted as the string identifier assignment. However,
5200 it can also be interpreted as making a string identifier @code{\foo}
5201 containing @code{"bar"}, or a music identifier @code{\foo}
5202 containing the syllable `bar'.
5204 @item If you do a nested repeat like
5216 then it is ambiguous to which @code{\repeat} the
5217 @code{\alternative} belongs. This is the classic if-then-else
5218 dilemma. It may be solved by using braces.
5220 @item The parser is not sophisticated enough to distinguish at the
5222 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
5229 @c . {Lexical details}
5230 @node Lexical details
5231 @section Lexical details
5233 Even more boring details, now on lexical side of the input parser.
5242 * Version information::
5247 @subsection Comments
5250 @cindex block comment
5251 @cindex line comment
5255 A one line comment is introduced by a @code{%} character.
5256 Block comments are started by @code{%@{} and ended by @code{%@}}.
5257 They cannot be nested.
5260 @subsection Direct Scheme
5264 @cindex Scheme, in-line code
5267 LilyPond contains a Scheme interpreter (the GUILE library) for
5268 internal use. In some places, Scheme expressions also form valid syntax:
5269 wherever it is allowed,
5273 evaluates the specified Scheme code. Example:
5275 \property Staff.TestObject \override #'foobar = #(+ 1 2)
5277 @code{\override} expects two Scheme expressions, so there are two Scheme
5278 expressions. The first one is a symbol (@code{foobar}), the second one
5279 an integer (namely, 3).
5281 In-line scheme may be used at the top level. In this case the result is
5284 Scheme is a full-blown programming language, and a full discussion is
5285 outside the scope of this document. Interested readers are referred to
5286 the website @uref{http://www.schemers.org/} for more information on
5292 @cindex real numbers
5294 Formed from an optional minus sign and a sequence of digits followed
5295 by a @emph{required} decimal point and an optional exponent such as
5296 @code{-1.2e3}. Reals can be built up using the usual operations:
5297 `@code{+}', `@code{-}', `@code{*}', and
5298 `@code{/}', with parentheses for grouping.
5306 A real constant can be followed by one of the dimension keywords:
5307 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
5308 points, inches and centimeters, respectively. This converts the number
5309 a number that is the internal representation of that dimension.
5317 Begins and ends with the @code{"} character. To include a @code{"}
5318 character in a string write @code{\"}. Various other backslash
5319 sequences have special interpretations as in the C language. A string
5320 that contains no spaces can be written without the quotes. Strings can
5321 be concatenated with the @code{+} operator.
5325 @subsection Main input
5328 @cindex @code{\maininput}
5330 The @code{\maininput} command is used in init files to signal that the
5331 user file must be read. This command cannot be used in a user file.
5333 @node File inclusion
5334 @subsection File inclusion
5335 @cindex @code{\include}
5337 \include @var{filename}
5340 Include @var{filename}. The argument @var{filename} may be a quoted string (an
5341 unquoted string will not work here!) or a string identifier. The full
5342 filename including the @file{.ly} extension must be given,
5345 @node Version information
5346 @subsection Version information
5347 @cindex @code{\version}
5349 \version @var{string}
5352 Specify the version of LilyPond that a file was written for. The
5353 argument is a version string in quotes, for example @code{"1.2.0"}.
5354 This is used to detect invalid input, and to aid @code{convert-ly} a
5355 tool that automatically upgrades input files. See the chapter
5356 @ref{Upgrading from older LilyPond versions} for more information on
5365 @c broken with emacs-21
5366 @c {Local emac s vars}
5367 @c Local varia bles:
5369 @c minor-mod e: font-lock
5370 @c minor-mo de: outline
5371 @c outline -layout: (-1 : 0)
5372 @c outlin e-use-mode-specific-leader: "@c \."
5373 @c outli ne-primary-bullet: "{"
5374 @c outli ne-stylish-prefixes: nil
5375 @c outli ne-override-protect: t