4 @c A menu is needed before every deeper *section nesting of @nodes
5 @c Run M-x texinfo-all-menus-update
6 @c to automagically fill in these menus
7 @c before saving changes
15 Rhythm staff (clef, x-notehead)
21 @unnumberedsubsec Bugs
25 @c .{Reference Manual}
27 @node Reference Manual
28 @chapter Reference Manual
30 This document describes GNU LilyPond and its input format. The last
31 revision of this document was for LilyPond 1.3.136.
52 * Interpretation context::
62 The purpose of LilyPond is explained informally by the term `music
63 typesetter'. This is not a fully correct name: not only does the
64 program print musical symbols, it also makes esthetic decisions.
65 Symbols and their placements are @emph{generated} from a high-level
66 musical description. In other words, LilyPond would be best described
67 by `music compiler' or `music to notation compiler'.
69 LilyPond is linked to GUILE, GNU's Scheme library for extension. The
70 Scheme library provides the glue that holds together the low-level
71 routines and separate modules general, which are C++
73 When lilypond is run to typeset sheet music, the following happens:
75 @item GUILE Initialization: various scheme files are read
76 @item parsing: first standard @code{ly} initialization files are read, and
77 then the user @file{ly} file is read.
78 @item interpretation: the music in the file is processed ``in playing
79 order'', i.e. the order that you use to read sheet music, or the
80 order in which notes are played.
83 in this step, the results of the interpretation, a typesetting
84 specification, is solved.
86 @item the visible results ("virtual ink") is written to the output file.
89 During these stages different types of data play the the main role:
90 during parsing, @strong{Music} objects are created. During the
91 interpretation, @strong{context} is constructed, and with this context
92 af network of @strong{graphical objects} (``grobs'') is created. The
93 grobs contain unknown variables, and the network forms a set of
94 equations. After solving the equations and filling in these variables,
95 the printed output (in the form of @strong{molecules}) is written to an
98 These threemanship of tasks (parsing, translating, typesetting) and
99 data-structures (music, context, graphical objects) permeates the entire
100 design of the program. This manual is ordered in terms of user
101 tasks. With each concept will be explained to which of the three parts
110 The most basic forms of music are notes. We discuss how you enter them
111 here. Notes on their own don't form valid input, but for the sake of
112 brevity we omit obligotary lint such as @code{\score} blocks and
113 @code{\paper} declarations.
118 * Defining pitch names::
121 * Easy Notation note heads ::
133 @cindex Note specification
135 @cindex entering notes
137 The verbose syntax for pitch specification is
139 @cindex @code{\pitch}
141 \pitch @var{scmpitch}
144 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
146 In Note and Chord mode, pitches may be designated by names. The default
147 names are the Dutch note names. The notes are specified by the letters
148 @code{a} through @code{g} (where the octave is formed by notes ranging
149 from @code{c}, to @code{b}). The pitch @code{c} is an octave below
150 middle C and the letters span the octave above that C.
152 @cindex note names, Dutch
154 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
155 name. A flat is formed by adding @code{-es}. Double sharps and double
156 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
157 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
158 both forms are accepted.
160 LilyPond has predefined sets of notenames for various other languages.
161 To use them, simply include the language specific init file. For
162 example: @code{\include "english.ly"}. The available language files and
163 the names they define are:
166 Note Names sharp flat
167 nederlands.ly c d e f g a bes b -is -es
168 english.ly c d e f g a bf b -s/-sharp -f/-flat
169 deutsch.ly c d e f g a b h -is -es
170 norsk.ly c d e f g a b h -iss/-is -ess/-es
171 svenska.ly c d e f g a b h -iss -ess
172 italiano.ly do re mi fa sol la sib si -d -b
173 catalan.ly do re mi fa sol la sib si -d/-s -b
181 The optional octave specification takes the form of a series of
182 single quote (`@code{'}') characters or a series of comma
183 (`@code{,}') characters. Each @code{'} raises the pitch by one
184 octave; each @code{,} lowers the pitch by an octave.
186 @lilypond[fragment,verbatim,center]
187 c' c'' es' g' as' gisis' ais'
190 @c . {Defining pitch names}
191 @node Defining pitch names
192 @subsection Defining pitch names
194 @cindex defining pitch names
195 @cindex pitch names, defining
197 Note names and chord modifiers can be customised for nationalities. The
198 syntax is as follows.
200 @cindex @code{\pitchnames}
201 @cindex @code{\chordmodifiers}
203 \pitchnames @var{scheme-alist}
204 \chordmodifiers @var{scheme-alist}
207 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
208 specific examples how to do this.
214 @subsection Durations
218 @cindex @code{\duration}
220 The syntax for a verbose duration specification is
222 \duration @var{scmduration}
224 Here, @var{scmduration} is a Scheme object of type Duration. See
225 @ref{Duration} for more information.
228 In Note, Chord, and Lyrics mode, durations may be designated by numbers
229 and dots: durations are entered as their reciprocal values. For notes
230 longer than a whole note, use identifiers.
236 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
238 r1 r2 r4 r8 r16 r32 r64 r64
244 \notes \relative c'' {
245 a\longa a\breve \autoBeamOff
246 a1 a2 a4 a8 a16 a32 a64 a64
248 r1 r2 r4 r8 r16 r32 r64 r64
253 \remove "Clef_engraver";
254 \remove "Staff_symbol_engraver";
255 \remove "Time_signature_engraver";
256 \consists "Pitch_squash_engraver";
263 As you can see, the longa is not printed. To get a longa note head, you
264 have to use a mensural note heads. This is done accomplished by setting
265 the @code{style} property of the NoteHead grob to @code{mensural}.
267 If the duration is omitted then it is set to the previous duration
268 entered. At the start of parsing a quarter note is assumed. The
269 duration can be followed by a dot (`@code{.}') to obtain dotted note
273 @lilypond[fragment,verbatim,center]
279 You can alter the length of duration by appending
280 `@code{*}@var{fraction}'. This will not affect the appearance of the
281 notes or rests produced.
287 A note specification has the form
290 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
293 LilyPond will determine what accidentals to typeset depending on the key
294 and context. The alteration refers to what note is heard, not to whether
295 an accidental is printed. A reminder accidental
296 @cindex reminder accidental
298 can be forced by adding an exclamation mark @code{!} after the pitch. A
299 cautionary accidental,
300 @cindex cautionary accidental
301 i.e., an accidental within parentheses can be obtained by adding the
302 question mark `@code{?}' after the pitch.
304 @lilypond[fragment,verbatim,center]
305 cis' d' e' cis' c'? d' e' c'!
309 @node Easy Notation note heads
310 @subsection Easy Notation note heads
312 @cindex easy notation
315 A entirely different type of note head is the "easyplay" note head: a
316 note head that includes a note name. It is used in some publications by
317 Hal-Leonard Inc. music publishers.
319 @lilypond[singleline,verbatim]
320 \include "paper26.ly"
322 \notes { c'2 e'4 f' | g'1 }
323 \paper { \translator { \EasyNotation } }
327 Note that @code{EasyNotation} overrides a @code{Score} context. You
328 probably will want to print it with magnification to make it better
334 If you view the result with Xdvi, then staff lines will show through the
335 letters. Printing the postscript file obtained either by using dvips or
336 the @code{-f ps} option of lilypond will produce the desired result.
346 A tie connects two adjacent note heads of the same pitch. When used
347 with chords, it connects all of the note heads whose pitches match.
348 Ties are indicated using the tilde symbol `@code{~}'.
349 If you try to tie together chords which have no common pitches, a
350 warning message will appear and no ties will be created.
352 @lilypond[fragment,verbatim,center]
353 e' ~ e' <c' e' g'> ~ <c' e' g'>
356 If you dislike the amount of ties created for a chord, you set
357 @code{Thread.sparseTies} to true, resulting in a smaller number of
359 @lilypond[fragment,verbatim,center]
360 \property Thread.sparseTies = ##t
361 <c' e' g'> ~ <c' e' g'>
364 In its meaning a tie is just a way of extending a note duration, similar
365 to the augmentation dot: the following example are three ways of notating
366 exactly the same concept.
367 @lilypond[fragment, singleline]
373 At present, the tie is implemented as a separate thing, temporally
374 located in between the notes. There is also no way to convert
375 between tied notes, dotted notes and plain notes.
377 Tieing only a subset of the note heads of a chord is not supported in a
378 simple way. It can be achieved by moving the tie-engraver into Thread
379 context and turning off ties per Thread.
388 @subsubsection Tuplets
392 Tuplets are made out of a music expression by multiplying their duration
395 @cindex @code{\times}
397 \times @var{fraction} @var{musicexpr}
400 The duration of @var{musicexpr} will be multiplied by the fraction.
401 In print, the fraction's denominator will be printed over the notes,
402 optionally with a bracket. The most common tuplet is the triplet in
403 which 3 notes have the length of 2, so the notes are 2/3 of
404 their written length:
406 @lilypond[fragment,verbatim,center]
407 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
410 [todo: document tupletSpannerDuration]
420 Rests are entered like notes, with note name `@code{r}'.
430 \skip @var{duration} @code{;}
435 Skips the amount of time specified by @var{duration}. If no other music
436 is played, a gap will be left for the skipped time with no notes
437 printed. The short hand is only available in Note and Chord mode.
442 @subsection Note mode
447 @cindex @code{\notes}
449 Note mode is the lexical mode generally used for inputting notes. The
455 This instructs the tokenizer to interpret @var{expr} in note mode. If a
456 a sequence of alfabetical characters, like @code{foobar}, LilyPond first
457 checks if @code{foobar} is a pitch name. If it is not a pitch name,
458 then it is treated as a string.
460 Numbers and dots indicate durations, so you can enter floating point
461 numbers in this mode.
465 @section Staff notation
467 @cindex Staff notation
477 @subsection Key signature
482 Changing the key signature is done with the @code{\key} command.
484 @code{\key} @var{pitch} @var{type} @code{;}
487 @cindex @code{\minor}
488 @cindex @code{\major}
489 @cindex @code{\minor}
490 @cindex @code{\ionian}
491 @cindex @code{\locrian}
492 @cindex @code{\aeolian}
493 @cindex @code{\mixolydian}
494 @cindex @code{\lydian}
495 @cindex @code{\phrygian}
496 @cindex @code{\dorian}
498 Here, @var{type} should be @code{\major} or @code{\minor} to get
499 @var{pitch}-major or @var{pitch}-minor, respectively. The second
500 argument is optional; the default is major keys. The @var{\context}
501 argument can also be given as an integer, which tells the number of
502 semitones that should be added to the pitch given in the subsequent
503 @code{\key} commands to get the corresponding major key, e.g.,
504 @code{\minor} is defined as 3. The standard mode names @code{\ionian},
505 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
506 @code{\phrygian}, and @code{\dorian} are also defined.
508 This command sets context property @code{Staff.keySignature}.
510 @cindex @code{keySignature}
513 @subsection Clef changes
516 \clef @var{clefname} @code{;}
522 \property Staff.clefGlyph = @var{glyph associated with clefname}
523 \property Staff.clefPosition = @var{clef Y-position for clefname}
524 \property Staff.clefOctavation = @var{extra pitch of clefname}
527 Supported clef-names include
530 @item treble, violin, G, G2: G clef on 2nd line
531 @item french: G clef on 1st line
532 @item soprano: C clef on 1st line
533 @item mezzosoprano: C clef on 2nd line
534 @item alto: C clef on 3rd line
535 @item tenor: C clef on 4th line
536 @item baritone: C clef on 5th line
537 @item varbaritone: F clef on 3rd line
538 @item bass, F: F clef on 4th line
539 @item subbass: F clef on 5th line
540 @item percussion: percussion clef
543 Supported associated glyphs (for @code{Staff.clefGlyph}) are:
546 @item clefs-C: modern style C clef
547 @item clefs-F: modern style F clef
548 @item clefs-G: modern style G clef
549 @item clefs-vaticana_do: Editio Vaticana style do clef
550 @item clefs-vaticana_fa: Editio Vaticana style fa clef
551 @item clefs-medicaea_do: Editio Medicaea style do clef
552 @item clefs-medicaea_fa: Editio Medicaea style fa clef
553 @item clefs-mensural1_c: modern style mensural C clef
554 @item clefs-mensural2_c: historic style small mensural C clef
555 @item clefs-mensural3_c: historic style big mensural C clef
556 @item clefs-mensural1_f: historic style traditional mensural F clef
557 @item clefs-mensural2_f: historic style new mensural F clef
558 @item clefs-mensural_g: historic style mensural G clef
559 @item clefs-hufnagel_do: historic style hufnagel do clef
560 @item clefs-hufnagel_fa: historic style hufnagel fa clef
561 @item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef
562 @item clefs-percussion: modern style percussion clef
565 @emph{Modern style} means ``as is typeset in current editions.''
566 @emph{Historic style} means ``as was typeset or written in contemporary
567 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
570 @cindex Vaticana, Editio
571 @cindex Medicaea, Editio
572 @cindex hufnagel clefs
575 @c . {Time signature}
577 @subsection Time signature
578 @cindex Time signature
582 The time signature is changed by the @code{\time} command. Syntax:
584 \time @var{numerator}@code{/}@var{denominator} @code{;}
586 Internally, this is a short-cut for doing
588 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
591 [TODO: discuss options for layout]
594 @subsubsection Partial
598 @cindex partial measure
599 @cindex measure, partial
600 @cindex shorten measures
601 @cindex @code{\partial}
603 Partial measures are entered using the @code{\partial} command:
605 \partial @var{duration} @code{;}
608 Internally, this is a short cut for
611 \property Score.measurePosition = -@var{length of duration}
617 @subsection Bar lines
621 @cindex measure lines
628 This is a short-cut for doing
630 \property Score.whichBar = @var{bartype}
633 You are encouraged to use @code{\repeat} for repetitions. See
634 @ref{Repeats}, and the documentation of @code{whichBar} in the generated
638 @cindex Bar_line_engraver
640 @cindex repeatCommands
641 @cindex defaultBarType
643 Bar lines are created by the @code{Bar_line_engraver}. That engraver examines
644 @code{whichBar} at every moment. Whenever it is set to a string, it will
645 create a bar with that type. @code{whichBar} is usually set
646 automatically: at the start of a measure it is set to
647 @code{defaultBarType}. The contents of @code{repeatCommands} is used to
648 override default measure bars.
650 @code{whichBar} can also be set directly, using @code{\property} or
651 @code{\bar ; }. These settings take precedence over automatic @code{whichBar}
660 [TODO: collisions, rest-collisinos, voiceX identifiers, how to
661 which contexts to instantiate.]
665 @cindex @code{\shiftOff}
666 @item @code{\shiftOff}
667 Disable horizontal shifting of note heads that collide.
669 @cindex @code{\shiftOn}
670 @item @code{\shiftOn}
671 Enable note heads that collide with other note heads to be
672 shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
673 set different shift values.
675 @cindex @code{\stemBoth}
676 @item @code{\stemBoth}
677 Allow stems and beams to point either upwards or
678 downwards, decided automatically by LilyPond.
680 @cindex @code{\stemDown}
681 @item @code{\stemDown}
682 Force stems and beams to point down.
684 @cindex @code{\stemUp}
686 Force stems and beams to point up.
689 @cindex @code{\slurBoth}
690 @cindex @code{\slurDown}
691 @cindex @code{\slurUp}
692 Similarly, for slurs use
696 @cindex @code{\slurBoth}
697 @cindex @code{\slurDown}
698 @cindex @code{\slurUp}
708 Beams are used to group short notes into chunks that are aligned with
709 the metrum. LilyPond guesses where beams should be inserted, but if
710 you're not satisfied with the automatic beaming, you can either instruct
711 lilypond which patterns to beam automatically. In specific cases, you
712 can also specify explicitly what to beam and what not.
715 @c . {Automatic beams}
716 @subsection Automatic beams
718 @cindex @code{Voice.autoBeamSettings}
719 @cindex @code{(end * * * *)}
720 @cindex @code{(begin * * * *)}
722 A large number of Voice properties are used to decide how to generate
723 beams. Their default values appear in @file{scm/auto-beam.scm}.
725 By default, automatic beams can start on any note@footnote{In exotic
726 time signatures such as 1/8 and 1/16 this is not true} but can only end
727 in a few positions within the measure: they can end on a beat, or at
728 durations specified by the properties in
729 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
730 are defined in @file{scm/auto-beam.scm}.
732 The syntax for changing the value @code{autoBeamSettings} is set using
733 @code{\override} and unset using @code{\revert}:
735 \property Voice.autoBeamSettings \override #'(@var{BE} @var{N} @var{M} @var{P} @var{Q}) = @var{dur}
736 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{N} @var{M} @var{P} @var{Q})
738 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
739 whether the rule applies to begin or end-points. The quantity
740 @var{N}/@var{M} refers to a time signature (@code{* *} may be entered to
741 designate all time signatures), @var{P}/@var{Q} refers to the length of
742 the beamed notes (@code{* *} designate notes of any length).
744 If you want automatic beams to end on every quarter note, you can
747 \property Voice.autoBeamSettings \override
748 #'(end * * * *) = #(make-moment 1 4)
750 The duration a quarter note is 1/4 of a whole note. It is entered as
751 @code{(make-moment 1 4)}.
753 The same syntax can be used to specify beam starting points. In this
754 example, you automatic beams can only end on a dotted quarter note.
756 \property Voice.autoBeamSettings \override
757 #'(begin * * * *) = #(make-moment 3 8)
759 In 4/4 time signature, this means that automatic beams could end only on
760 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
761 3/8 has passed within the measure).
763 You can also restrict rules to specific time signatures. A rule that
764 should only be applied in @var{N}/@var{M} time signature is formed by
765 replacing the first asterisks by @var{N} and @var{M}. For example, a
766 rule for 6/8 time exclusively looks like
768 \property Voice.autoBeamSettings \override
769 #'(begin 6 8 * *) = ...
772 If you want a rule to apply to certain types of beams, you can use the
773 second pair of asterisks. Beams are classified according to the shortest
774 note they contain. For a beam ending rule that only applies to beams
775 with 32nd notes (and no shorter notes), you would use @code{(end * * 1
778 [say something about irregular meters. eg 5/8 = 2+3/8, 3+2/8]
780 Automatic beams can not be put on the last note in a score.
782 @cindex automatic beam generation
784 @cindex @code{Voice.noAutoBeaming}
786 Automatic beaming is on by default, but it can switched off by setting
787 @code{Voice.noAutoBeaming} to true. You you may find this necessary for
788 a melody that goes with lyrics.
791 @cindex Automatic beams
792 @subsubsection Manual beams
793 @cindex beams, manual
797 In some cases it may be necessary to override LilyPond's automatic
798 beaming algorithm. For example, the auto beamer will not beam over
799 rests or bar lines, so if you want that, specify the begin and end point
800 manually using @code{[} and @code{]}:
803 @lilypond[fragment,relative,verbatim]
805 r4 [r8 g'' a r8] r8 [g | a] r8
808 Whenever an manual beam is busy, the auto beam will not produce
811 @cindex @code{stemLeftBeamCount}
813 If you have specific wishes for the number of beams, you can fully
814 control the number of beams through the properties
815 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
817 @lilypond[fragment,relative,verbatim]
820 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
824 @cindex @code{stemRightBeamCount}
827 [FIXME: explain common tweaks.]
830 @node Expressive marks
831 @section Expressive marks
844 A slur indicates that notes are to be played bound or @emph{legato}. In
845 lilypond, they are entered using parentheses:
846 @lilypond[fragment,verbatim,center]
847 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
851 Slurs avoid crossing stems, and are attached to note heads whenever
852 possible. In some instances involving beams slurs may be attached to a
853 stem end. If you want to override this layout you can do this through
854 @code{Voice.Slur}'s grob-property @code{attachment}:
856 [TODO: remove this section]
857 Maybe reinclude other slur features and move back to tricks? Esp. the
858 second example, how to fix, can be very helpful.
861 @lilypond[fragment,relative,verbatim]
862 \property Voice.Slur \set #'direction = #1
863 \property Voice.Stem \set #'length = #5.5
865 \property Voice.Slur \set #'attachment = #'(stem . stem)
870 If a slur would strike through a stem or beam, the slur will be moved
871 away upward or downward. If this happens, attaching the slur to the
872 stems might look better:
875 @lilypond[fragment,relative,verbatim]
876 \property Voice.Stem \set #'direction = #1
877 \property Voice.Slur \set #'direction = #1
879 \property Voice.Slur \set #'attachment = #'(stem . stem)
885 Similarly, the curvature of a slur is adjusted to stay clear of note
886 heads and stems. When that would increase the curvature too much, the
887 slur is reverted to its default shape. The threshold for this decision
888 is in @code{Voice.Slur}'s grob-property @code{beautiful}. In some
889 cases, you may prefer curved slurs to vertically moved ones. You can
890 express this by increasing the @code{beautiful} value:
892 [hoe gedefd?? wat betekent beautiful = X?]
894 [dit voorbeeld is te lang: junken, of inkorten]
897 @lilypond[verbatim,singleline]
899 \notes \context PianoStaff <
901 \context Staff=up { s1 * 6/4 }
902 \context Staff=down <
904 \autochange Staff \context Voice
906 d,8( a' d f a d f d a f d )a
913 Slur \override #'beautiful = #5.0
914 Slur \override #'direction = #1
915 Stem \override #'direction = #-1
916 autoBeamSettings \override #'(end * * * *)
921 VerticalAlignment \override #'threshold = #'(5 . 5)
928 @cindex Adusting slurs
931 @subsection Phrasing slur
933 @cindex phrasing slur
934 @cindex phrasing mark
936 A phrasing slur (or phrasing mark) connects chords and is used to
937 indicate a musical sentence. It is entered using @code{\(} and
940 @lilypond[fragment,verbatim,center,relative]
941 \time 6/4; c''\((d)e f(e)\)d
944 Typographically, the phrasing slur behaves almost exactly like a normal
945 slur. The grob associated with it is @code{Voice.PhrasingSlur}.
948 @subsection Breath marks
950 Breath marks are entered using @code{\breathe}:
952 @lilypond[fragment,relative]
956 Currently, only tick marks are supported, comma style breath marks are
957 not. The grob for this object is called @code{Voice.BreathingSign}.
962 Currently, only tick marks are supported, comma style breath marks are
970 @cindex beats per minute
971 @cindex metronome marking
973 @cindex @code{\tempo}
975 \tempo @var{duration} = @var{perminute} @code{;}
978 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
979 output with 76 quarter notes per minute.
983 The tempo setting is not printed, but is currently only used in the MIDI
995 @subsubsection Text spanner
998 Some textual indications, e.g. rallentando, accelerando, often extend
999 over a many measures. This is indicated by following the text with a
1000 dotted line. You can create such texts in LilyPond using
1001 text spanners. The syntax is as follows:
1003 \spanrequest \start "text"
1004 \spanrequest \stop "text"
1006 LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The
1007 string to be printed, as well as the style is set through grob
1010 An application---or rather, a hack---is to fake octavation indications.
1011 @lilypond[fragment,relative,verbatim]
1012 \relative c' { a'''' b c a
1013 \property Voice.TextSpanner \set #'type = #'dotted-line
1014 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1015 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1016 \property Staff.centralCPosition = #-13
1017 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1033 @subsection Articulation
1034 @cindex Articulation
1036 @cindex articulations
1040 A variety of symbols can appear above and below notes to indicate
1041 different characteristics of the performance. These symbols can be
1042 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1043 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1044 forced to appear above or below the note by writing
1045 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1046 respectively. Here is a chart showing symbols above notes, with the
1047 name of the corresponding symbol appearing underneath.
1052 \property Score.LyricSyllable \override #'font-family =
1054 \property Score.LyricSyllable \override #'font-shape = #'upright
1055 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1056 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1057 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1058 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1059 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1060 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1061 c''-\thumb c''-\segno c''-\coda
1063 \context Lyrics \lyrics {
1064 accent__ marcato__ staccatissimo__ fermata
1065 stopped__ staccato__ tenuto__ upbow
1066 downbow__ lheel__ rheel__ ltoe
1067 rtoe__ turn__ open__ flageolet
1068 reverseturn__ trill__ prall__ mordent
1069 prallprall__ prallmordent__ uprall__ downprall
1070 thumb__ segno__ coda
1074 linewidth = 5.875\in;
1080 To save typing work, some shorthands are available:
1081 @lilypond[singleline]
1083 \notes \context Voice {
1084 \property Voice.TextScript \set #'font-family = #'typewriter
1085 \property Voice.TextScript \set #'font-shape = #'upright
1091 c''4-^_"c-\\^{ }" s4
1098 Fingering instructions can also be entered in this shorthand.
1099 @lilypond[verbatim, singleline, fragment]
1100 c'4-1 c'4-2 c'4-3 c'4-4
1104 @cindex @code{\script}
1113 Defines a script printing request. The argument is a string which
1114 points into the script-alias table defined in @file{scm/script.scm}.
1115 Usually the @code{\script} keyword is not used directly. Various
1116 helpful identifier definitions appear in @file{script.ly}.
1118 For information on how to add scripts, consult @file{scm/script.scm}.
1123 All of these note ornaments appear in the printed output but have no
1124 effect on the MIDI rendering of the music.
1126 Unfortunately, there is no support adding fingering instructions or
1127 ornaments to individual note heads. Some hacks exist, though. See
1128 @file{input/test/script-horizontal.ly}.
1133 @subsection Text scripts
1134 @cindex Text scripts
1136 In addition, it is possible to place arbitrary strings of text or markup
1137 text (see @ref{Text markup}) above or below notes by using a string:
1138 @code{c^"text"}. The text is typeset in italic by default.
1140 The amount of space taken by these indications by default does not
1141 influence, spacing, but setting @code{Voice.textNonEmpty} to true will
1142 take the widths into account. The identifier @code{\fattext} is defined
1143 in the standard includes.
1144 @lilypond[fragment,singleline]
1145 \relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
1148 Text scripts are created in form of @code{Voice.TextScript} grobs.
1150 For purposes of defining identifiers, a more verbose form also exists:
1153 \textscript @var{text}
1156 Defines a text to be printed over or under a note. @var{text} is a
1157 string or a markup text.
1161 foo = \textscript #'(finger "6")
1168 This is equivalent to @code{c4-6 c4-"foo"}.
1173 @subsection Grace notes
1182 @cindex @code{\grace}
1185 @cindex @code{graceAlignPosition}
1187 Grace notes are ornaments that are written out, but do not take up any
1188 logical time in a measure. LilyPond has limited support for grace notes.
1189 The syntax is as follows.
1191 \grace @var{musicexpr}
1194 When grace music is interpreted, a score-within-a-score is set up:
1195 @var{musicexpr} has its own time bookkeeping, and you could (for
1196 example) have a separate time signature within grace notes. While in
1197 this score-within-a-score, you can create notes, beams, slurs, etc.
1198 Unbeamed eighth notes and shorter by default have a slash through the
1199 stem. This behavior can be controlled with the
1200 @code{Stem}.@code{flag-style} property.
1203 @lilypond[fragment,verbatim]
1205 \grace c8 c4 \grace { [c16 c16] } c4
1206 \grace { \property Grace.Stem \override #'flag-style = ##f c16 } c4
1213 At present, nesting @code{\grace} notes is not supported. The following
1214 may cause run-time errors:
1216 @code{\grace @{ \grace c32 c16 @} c4}
1218 Since the meaning of such a construct is unclear, we don't consider this
1219 a loss. Similarly, juxtaposing two @code{\grace} sections is
1220 syntactically valid, but makes no sense and may cause runtime errors.
1221 Ending a staff or score with grace notes may also generate a run-time
1222 error, since there will be no main note to attach the grace notes to.
1225 A grace note expression has duration 0; the next real note is assumed to
1226 be the main note. If you want the note to appear after the main note,
1227 set @code{Voice.graceAlignPosition} to @code{1}.
1231 The present implementation of grace notes is not robust and generally
1232 kludgy. We expect it to change after LilyPond 1.4. Syntax changes might
1233 also be implemented.
1246 @subsubsection Glissando
1249 @cindex @code{\glissando}
1251 A glissando line can be requested by attaching a @code{\glissando} to a
1255 @lilypond[fragment,relative,verbatim]
1262 Printing of an additional text (such as @emph{gliss.}) must be done
1269 @subsubsection Dynamics
1282 @cindex @code{\ffff}
1292 Absolute dynamic marks are specified by using an identifier after a
1293 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1294 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1295 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1296 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1299 @cindex Crescendo and Decrescendo
1303 @cindex @code{\decr}
1304 @cindex @code{\rced}
1310 A crescendo mark is started with @code{\cr} and terminated with
1311 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1312 started with @code{\decr} and terminated with @code{\rced}. There are
1313 also shorthands for these marks. A crescendo can be started with
1314 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1315 can be terminated with @code{\!}. Note that @code{\!} must go before
1316 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1317 after the last note. Because these marks are bound to notes, if you
1318 want to get several marks during one note, you must use spacer notes.
1320 @lilypond[fragment,verbatim,center]
1321 c'' \< \! c'' d'' \decr e'' \rced
1322 < f''1 { s4 \< \! s2 \> \! s4 } >
1327 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1328 is an example how to do it:
1330 @lilypond[fragment,relative,verbatim]
1332 \property Voice.crescendoText = "cresc."
1333 \property Voice.crescendoSpanner = #'dashed-line
1349 @cindex @code{\repeat}
1351 To specify repeats, use the @code{\repeat} keyword. Since repeats
1352 should work differently when played or printed, there are a few
1353 different variants of repeats.
1357 Repeated music is fully written (played) out. Useful for MIDI
1361 This is the normal notation: Repeats are not written out, but
1362 alternative endings (voltas) are printed, left to right.
1365 Alternative endings are written stacked. Which is unfortunately not
1366 practical for anything right now.
1372 Make measure repeats. These look like percent signs.
1378 * Manual repeat commands::
1380 * Tremolo subdivision::
1385 @subsection Repeat syntax
1387 The syntax for repeats is
1390 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1393 If you have alternative endings, you may add
1394 @cindex @code{\alternative}
1396 \alternative @code{@{} @var{alternative1}
1398 @var{alternative3} @dots{} @code{@}}
1400 where each @var{alternative} is a music expression.
1402 Normal notation repeats are used like this:
1403 @lilypond[fragment,verbatim]
1405 \repeat volta 2 { c'4 d' e' f' }
1406 \repeat volta 2 { f' e' d' c' }
1409 With alternative endings:
1411 @lilypond[fragment,verbatim]
1413 \repeat volta 2 {c'4 d' e' f'}
1414 \alternative { {d'2 d'} {f' f} }
1418 Folded repeats look like this:@footnote{Folded repeats offer little
1419 more over simultaneous music. However, it is to be expected that
1420 more functionality -- especially for the MIDI backend -- will be
1421 implemented at some point in the future.}
1424 @lilypond[fragment,verbatim]
1426 \repeat fold 2 {c'4 d' e' f'}
1427 \alternative { {d'2 d'} {f' f} }
1433 If you don't give enough alternatives for all of the repeats, then
1434 the first alternative is assumed to be repeated often enough to equal
1435 the specified number of repeats.
1438 @lilypond[fragment,verbatim]
1442 \repeat volta 3 { e | c2 d2 | e2 f2 | }
1443 \alternative { { g4 g g } { a | a a a a | b2. } }
1451 As you can see, LilyPond doesn't remember the timing information, nor
1452 are slurs or ties repeated, so you have to reset timing information
1453 after a repeat, e.g. using a bar-check (See @ref{Bar check}),
1454 @code{Score.measurePosition} or @code{\partial}. We hope to fix this
1457 It is possible to nest @code{\repeat}, although it probably is only
1458 meaningful for unfolded repeats.
1460 @node Manual repeat commands
1461 @subsection Manual repeat commands
1463 @cindex @code{repeatCommands}
1465 The property @code{repeatCommands} can be used to control the layout of
1466 repeats. Its value is a Scheme list of repeat commands, where each repeat
1474 @item (volta . @var{text})
1475 Print a volta bracket saying @var{text}.
1477 Stop a running volta bracket
1480 @lilypond[verbatim, fragment]
1482 \property Score.repeatCommands = #'((volta "93") end-repeat)
1484 \property Score.repeatCommands = #'((volta #f))
1489 @node Tremolo repeats
1490 @subsection Tremolo repeats
1491 @cindex tremolo beams
1493 To place tremolo marks between notes, use @code{\repeat} with tremolo
1495 @lilypond[verbatim,center,singleline]
1497 \context Voice \notes\relative c' {
1498 \repeat "tremolo" 8 { c16 d16 }
1499 \repeat "tremolo" 4 { c16 d16 }
1500 \repeat "tremolo" 2 { c16 d16 }
1501 \repeat "tremolo" 4 c16
1509 At present, the spacing between tremolo beams is not regular, since the
1510 spacing engine does not notice that not all notes are printed.
1512 @node Tremolo subdivision
1513 @subsection Tremolo subdivision
1514 @cindex tremolo marks
1515 @cindex @code{tremoloFlags}
1517 Tremolo marks can be printed on a single note by adding
1518 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1519 A @var{length} value of 8 gives one line across the note stem. If the
1520 length is omitted, then then the last value (stored in
1521 @code{Voice.tremoloFlags}) is used.
1523 @lilypond[verbatim,fragment,center]
1526 Using this mechanism pays off when you entering many tremolos, since the
1527 default argument saves a lot of typing.
1532 Tremolos in this style do not carry over into the MIDI output.
1535 @node Measure repeats
1536 @subsection Measure repeats
1538 @cindex percent repeats
1539 @cindex measure repeats
1541 In the @code{percent} style, a note pattern can be repeated. It is
1542 printed once, and then the pattern is replaced with a special sign.
1544 @lilypond[verbatim,singleline]
1545 \context Voice { \repeat "percent" 5 { c'1 } }
1548 At present, only repeats of whole measures are supported.
1552 @section Piano music
1554 Piano music is an odd type of notation: two staffs are largely
1555 independent, but sometimes voices can cross between the two staffs. The
1556 @code{PianoStaff} is especially built to handle this cross-staffing
1557 behavior. In this section we discuss the @code{PianoStaff} and some
1558 other pianistic peculiarities.
1561 * Automatic staff changes::
1562 * Manual staff switches::
1569 @c . {Automatic staff changes}
1570 @node Automatic staff changes
1571 @subsection Automatic staff changes
1572 @cindex Automatic staff changes
1574 Voices can be switched from top to bottom staff automatically. The
1577 \autochange @var{contexttype} @var{musicexp}
1579 This will switch notation context of @var{musicexp} between a
1580 @var{contexttype} named @code{up} and @code{down}. Typically, you use
1581 @code{Staff} for @var{contexttype}. The autochanger switches on basis
1582 of pitch (central C is the turning point), and it looks ahead skipping
1583 over rests to switch rests in advance.
1585 @lilypond[verbatim,singleline]
1586 \score { \notes \context PianoStaff <
1587 \context Staff = "up" {
1588 \autochange Staff \context Voice = VA < \relative c' {
1589 g4 a b c d r4 a g } > }
1590 \context Staff = "down" {
1596 Note how spacer rests are used to prevent the bottom staff from
1597 terminating too soon.
1600 @node Manual staff switches
1601 @subsection Manual staff switches
1603 @cindex manual staff switches
1604 @cindex staff switch, manual
1606 Voices can be switched between staffs manually, using the following command:
1608 \translator Staff = @var{which} @var{music}
1610 The string @var{which} is the name of the staff. Typically it is
1611 @code{"up"} or @code{"down"}.
1613 Formally, this construct is a music expression indicating that the
1614 context which is a direct child of the a context of type
1615 @var{contexttype} should be shifted to a context of type
1616 @var{contexttype} and the specified name.
1618 @cindex @code{\translator}
1620 \translator @var{contexttype} = @var{name}
1629 Piano pedal instruction can be expressed using
1630 @code{\sustainDown}, @code{\sustainUp}, @code{\unaChorda},
1631 @code{\treChorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1633 These identifiers are short hands for spanner commands of the types
1634 @code{Sustain}, @code{UnaChorda} and @code{Sostenuto}:
1636 @lilypond[fragment,verbatim]
1637 c''4 \spanrequest \start "Sustain" c''4 c''4 \spanrequest \stop "Sustain"
1640 The symbols that are printed can be modified by setting
1641 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal
1642 types. Refer to the generated documentation for more information.
1647 Currently, brackets are not supported, only text markings (ie. *Ped
1653 @subsection Arpeggio
1656 @cindex broken arpeggio
1657 @cindex @code{\arpeggio}
1659 You can specify an arpeggio sign on a chord by attaching an
1660 @code{\arpeggio} to a note of the chord.
1664 @lilypond[fragment,relative,verbatim]
1665 \context Voice <c'\arpeggio e g c>
1669 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1670 to the chords in both staffs, and set
1671 @code{PianoStaff.connectArpeggios}.
1674 @lilypond[fragment,relative,verbatim]
1675 \context PianoStaff <
1676 \property PianoStaff.connectArpeggios = ##t
1677 \context Voice = one { <c''\arpeggio e g c> }
1678 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1683 This command creates @code{Arpeggio} grobs.
1687 It is not possible to mix
1688 connected arpeggios and unconnected arpeggios at the same time.
1691 @c . {Follow Thread}
1693 @subsection Follow Thread
1695 @cindex follow thread
1696 @cindex staff switching
1699 [todo: figure out different name, eg. voice line, switch indicator ? ]
1701 @cindex @code{followThread}
1703 Whenever a voice switches to another staff a line connecting the notes
1704 can be printed automatically. This is enabled if the property
1705 @code{PianoStaff.followThread} is set to true:
1708 @lilypond[fragment,relative,verbatim]
1709 \context PianoStaff <
1710 \property PianoStaff.followThread = ##t
1711 \context Staff \context Voice {
1713 \translator Staff=two
1716 \context Staff=two {\clef bass; \skip 1*2;}
1730 * Automatic syllable durations::
1736 @subsection Lyrics mode
1739 To print lyrics in LilyPond, you must first make a music expression from
1740 the lyric text. When they're in a music expression, that music
1741 expression can be printed by selecting an appropriate context. We shall
1742 discuss lyric printing in this order.
1746 @cindex @code{\lyrics}
1748 You can enter lyrics in a special input mode of LilyPond. This mode is
1749 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1750 The purpose of this mode is that you can enter lyrics as plain text,
1751 punctuation and accents without any hassle.
1753 The precise definition of this mode is in @ref{Lyrics mode
1754 definition}. The definition itself is ludicrous, and this will remain so
1755 until the authors of LilyPond acquire a deeper understanding of
1756 character encoding, or someone else steps up to fix this.
1758 Syllables are entered like notes, with pitches replaced by text. For
1759 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1760 the hyphen has no special meaning for lyrics, and does not introduce
1763 Spaces can be introduced into a lyric either by using quotes
1764 (@code{"}) or by using an underscore without quotes: @code{He_could4
1765 not4}. All unquoted underscores are converted to spaces.
1767 @c . {Printing lyrics}
1768 @node Printing lyrics
1769 @subsection Printing lyrics
1772 Normally, you will want to have notes and syllables matched
1773 automatically. This is accomplished using @code{\addlyrics}, which is
1774 documented in @ref{Automatic syllable durations}. Setting
1775 @code{automaticMelismata} in the melody staff, will cause slurs to be
1776 interpreted as melismata. Lyric syllables must be interpreted within a
1777 @code{Lyrics} context in order to printing them.
1779 @lilypond[verbatim,singleline]
1780 \addlyrics \notes \relative c' {
1782 \property Staff.automaticMelismata = ##t
1785 \context Lyrics \lyrics {
1787 share the so -- ftware; }
1791 @cindex lyric extender
1794 As you can see, extender lines are entered as @code{__}. This will
1795 create an extender, a line that extends over the entire duration of the
1796 lyric. This line will run all the way to the start of the next lyric,
1797 so you may want to shorten it by using a blank lyric (using @code{_}).
1801 If you want to have hyphens centered between syllables (rather than
1802 attached to the end of the first syllable) you can use the special
1803 `@code{-}@code{-}' lyric as a separate word between syllables. This
1804 will result in a hyphen which length varies depending on the space
1805 between syllables, and which will be centered between the syllables.
1807 @cindex Lyric hyphen
1809 @node Automatic syllable durations
1810 @subsection Automatic syllable durations
1811 @cindex Automatic syllable durations
1813 @cindex automatic lyric durations
1814 @cindex @code{\addlyrics}
1816 If you have lyrics that are set to a melody, you can import the rhythm
1817 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1820 \addlyrics @var{musicexpr1 musicexpr2}
1823 This means that both @var{musicexpr1} and @var{musicexpr2} are
1824 interpreted, but that every non-command atomic music expression
1825 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1826 of @var{musicexpr1}.
1827 @cindex @code{automaticMelismata}
1829 If the property @code{automaticMelismata} is set in the
1830 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1833 @lilypond[verbatim,fragment]
1836 \property Voice.automaticMelismata = ##t
1837 c8 () cis d8. e16 f2
1839 \context Lyrics \lyrics {
1843 If you want the lyric lines to be above the melody staff, or in some
1844 other, more complex configuration, then build that configuration first
1845 using simultaneous music, and use @code{\addlyrics} after that.
1847 @lilypond[verbatim, singleline]
1849 \context Lyrics = LA { s1 }
1850 \context Staff = SA { s1 }
1852 \context Staff = SA \relative c' { c4 e g g }
1853 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
1856 For @code{\addlyrics} you should use a single rhythm melody, and single
1857 rhythm lyrics (a constant duration is the obvious choice). If you do
1858 not, you can get undesired effects when using multiple stanzas:
1860 @lilypond[verbatim,fragment]
1863 c8 () cis d8. e16 f2
1865 \context Lyrics \lyrics
1870 It is valid (but probably not very useful) to use notes instead of
1871 lyrics for @var{musicexpr2}.
1874 @subsection More stanzas
1878 If you have multiple stanzas printed underneath each other, the separate
1879 syllables should be aligned around punctuation. LilyPond can do this if
1880 you explain it which lyric lines belong to which melody.
1882 To this end, give the Voice context an identity, and set the LyricsVoice
1883 to name starting with that identity. In the following example, the Voice
1884 identity is @code{duet}, and the identities of the LyricsVoices are
1885 @code{duet-1} and @code{duet-2}.
1888 @lilypond[singleline,verbatim]
1891 \notes \relative c'' \context Voice = duet { \time 3/4;
1893 \lyrics \context Lyrics <
1894 \context LyricsVoice = "duet-1" {
1895 \property LyricsVoice . stanza = "Bert"
1896 Hi, my name is bert. }
1897 \context LyricsVoice = "duet-2" {
1898 \property LyricsVoice . stanza = "Ernie"
1899 Ooooo, ch\'e -- ri, je t'aime. }
1904 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
1905 first system) and @code{LyricsVoice.stz} for the following systems.
1907 @cindex stanza numbering
1915 LilyPond has support for both entering and printing chords. Chords are
1916 a harmonic device that is characterized by a set of pitches. It is
1917 something different from simultaneous music, although you can express a
1918 chord using simultaneous music. In fact, chords are internally stored as
1919 simultaneous music expressions. This means you can enter chords by name,
1920 and print them as note head, or enter as notes and print as chord names:
1923 @lilypond[verbatim,singleline]
1924 twoWays = \notes \transpose c'' {
1934 < \context ChordNames \twoWays
1935 \context Staff \twoWays > }
1938 Note that this example also shows that the LilyPond chord does not
1939 attempt to be intelligent, if you enter @code{f bes d}, it does no
1940 attempt to find out whether it this is an inversion.
1944 * Printing named chords::
1949 @subsection Chords mode
1952 Chord mode is a mode where you can input sets of pitches using common
1953 names. It is introduced by the keyword @code{\chords}. It is similar
1954 to note mode, but words are also looked up in a chord modifier table
1955 (containing @code{maj}, @code{dim}, etc).
1957 Dashes and carets are used to indicate chord additions and subtractions,
1958 so articulation scripts can not be entered in Chord mode.
1960 The syntax for named chords is as follows:
1963 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1966 @var{tonic} should be the tonic note of the chord, and @var{duration}
1967 is the chord duration in the usual notation. There are two kinds of
1968 modifiers. One type is @emph{chord additions}, which are obtained by
1969 listing intervals separated by dots. An interval is written by its
1970 number with an optional @code{+} or @code{-} to indicate raising or
1971 lowering by half a step. Chord additions has two effects: It adds
1972 the specified interval and all lower odd numbered intervals to the
1973 chord, and it may lower or raise the specified interval. Intervals
1974 must be separated by a dot (@code{.}).
1976 Throughout these examples, chords have been shifted around the staff
1977 using @code{\transpose}.
1982 @lilypond[fragment,verbatim]
1986 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1998 The second type of modifier that may appear after the @code{:} is a
1999 named modifier. Named modifiers are listed in the file
2000 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2001 @code{min} which lower the 3rd half a step, `@code{aug}' which
2002 raises the 5th, `@code{dim}' which lowers the 5th,
2003 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2004 which replaces the 5th with a 4th.
2008 @lilypond[fragment,verbatim]
2011 c1:m c:min7 c:maj c:aug c:dim c:sus
2019 Chord subtractions are used to eliminate notes from a chord. The
2020 notes to be subtracted are listed after a @code{^} character,
2023 @lilypond[fragment,verbatim,center]
2032 Chord inversions can be specified by appending `@code{/}' and the name
2033 of a single note to a chord. In a chord inversion, the inverted note is
2034 transposed down until it is the lowest note in the chord. If the
2035 specified note is not in the chord, a warning will be printed.
2037 @lilypond[fragment,verbatim,center]
2047 Bass notes can be added by `@code{/+}' and
2048 the name of a single note to a chord. This has the effect of
2049 adding the specified note to the chord, lowered by an octave,
2050 so it becomes the lowest note in the chord.
2052 @lilypond[fragment,verbatim,center]
2064 @c . {Printing named chords}
2065 @node Printing named chords
2066 @subsection Printing named chords
2068 @cindex printing chord names
2071 @cindex @code{ChordNames}
2074 For displaying printed chord names, use the @code{ChordNames} context.
2075 The chords may be entered either using the notation described above, or
2076 directly using simultaneous music.
2079 @lilypond[verbatim,singleline]
2081 \chords {a1 b c} <d f g> <e g b>
2085 \context ChordNames \scheme
2086 \context Staff \transpose c'' \scheme
2092 You can make the chord changes stand out by setting property
2093 @code{ChordNames.chordChanges} to true. This will only display chord
2094 names when there's a change in the chords scheme and at the start of the
2100 c1:m \break c:m c:m c:m d
2105 \context ChordNames {
2106 \property ChordNames.chordChanges = ##t
2108 \context Staff \transpose c'' \scheme
2113 LilyPond examines chords specified as lists of notes to determine a name
2114 to give the chord. LilyPond will not try to identify chord inversions or
2115 added base, which may result in strange chord names when chords are
2116 entered as a list of pitches:
2121 @lilypond[verbatim,center,singleline]
2130 \context ChordNamesVoice \scheme
2131 \context Staff \scheme
2138 By default LilyPond uses chord name system proposed by Harald Banter
2139 (See @ref{Literature}). The system is is unambiguous and has a logical
2140 structure. Typical American style chord names may be selected by
2141 setting the @code{style} property of the @code{ChordNames.ChordName}
2142 grob to @code{'american}. Similarly @code{'jazz} selects Jazz
2145 Routines that determine the names to be printed are written in Scheme,
2146 and may be customized by the user. The code can be found in
2147 @file{scm/chord-name.scm}.
2149 [3 short examples showing differences between american, banter and jazz]
2152 @section Writing parts
2154 Orchestral music involves some special notation, both in the full score,
2155 as in the individual parts. This section explains how to tackle common
2156 problems in orchestral music.
2163 * Instrument names::
2165 * Sound output for transposing instruments::
2166 * Multi measure rests::
2167 * Automatic part combining::
2168 * Hara-kiri staffs::
2171 @c . {Rehearsal marks}
2172 @node Rehearsal marks
2173 @subsection Rehearsal marks
2174 @cindex Rehearsal marks
2176 @cindex @code{\mark}
2177 @cindex @code{Mark_engraver}
2180 \mark @var{unsigned};
2185 With this command, you can print a rehearsal mark above the system. You
2186 can provide a number, a string or a markup text as argument. If there is
2187 no argument, the property @code{rehearsalMark} is used and automatically
2190 @lilypond[fragment,verbatim]
2196 c1 \mark #'(music "scripts-segno") ;
2202 @subsection Bar numbers
2204 Bar numbers are printed at the start of the line by default. This is
2205 done by the @code{Bar_number_engraver} in the Score context.
2209 It is currently not possible to make boxed bar numbers, or print them at
2213 @node Instrument names
2214 @subsection Instrument names
2216 You can specify an instrument name for a staff by setting
2217 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2218 before the start of the staff. For the first start, @code{instrument} is
2219 used, for the next ones @code{instr} is used.
2221 @lilypond[verbatim,singleline]
2223 \property Staff.instrument = "ploink " { c''4 } }
2225 \translator { \StaffContext
2226 \consists "Instrument_name_engraver"; } } }
2229 This requires that you add the @code{Instrument_name_engraver} to the
2234 @subsection Transpose
2236 @cindex transposition of pitches
2237 @cindex @code{\transpose}
2239 A music expression can be transposed with @code{\transpose}. The syntax
2242 \transpose @var{pitch} @var{musicexpr}
2245 This means that middle C in @var{musicexpr} is transposed to
2248 @code{\transpose} distinguishes between enharmonic pitches: both
2249 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2250 a tone. The first version will print sharps and the second version
2254 @lilypond[fragment,verbatim]
2257 { \key e \major; c d e f }
2259 \transpose des'' { \key e \major; c d e f }
2260 \transpose cis'' { \key e \major; c d e f }
2266 If you want to use both @code{\transpose} and @code{\relative}, then
2267 you must use @code{\transpose} first. @code{\relative} will have no
2268 effect music that appears inside a @code{\transpose}.
2270 @node Sound output for transposing instruments
2271 @subsection Sound output transposing instruments
2273 When you want to play a score containing transposed and untransposed
2274 instruments, you have to instruct LilyPond the pitch offset (in
2275 semitones) for the transposed instruments. This is done using the
2276 @code{transposing} property. It does not affect printed output.
2278 @cindex @code{transposing}
2281 \property Staff.instrument = #"Cl. in B-flat"
2282 \property Staff.transposing = #-2
2286 @c . {Multi measure rests}
2287 @node Multi measure rests
2288 @subsection Multi measure rests
2289 @cindex Multi measure rests
2293 Multi measure rests are entered using `@code{R}'. It is specifically
2294 meant for entering parts: the rest can expand to fill a score with
2295 rests, or it can be printed as a single multimeasure rest This expansion
2296 is controlled by the property @code{Score.skipBars}. If this is set to true,
2297 Lily will not expand empty measures, and the appropriate number is added
2300 @lilypond[fragment,verbatim]
2301 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2304 Currently, there is no way to condense multiple rests into a single
2307 @cindex condensing rests
2309 @node Automatic part combining
2310 @subsection Automatic part combining
2311 @cindex automatic part combining
2312 @cindex part combiner
2314 Automatic part combining is used to merge two parts of music onto on
2315 staff in an intelligent way. It is aimed primarily at typesetting Hymns
2316 and orchestral scores. When the two parts are identical for a period of
2317 time, only one is shown. In places where the two parts differ, stem
2318 directions are set automatically. Also, soli and @`{a} due parts can be
2319 identified and marke.
2321 The syntax for part combining is
2324 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2327 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2328 combined into one context @var{context}. The names of the music
2329 expressions must start with the prefixes @code{one} and @code{two}.
2331 [Name of music expressions? is that context name? ]
2333 The most useful function of the part combiner to combining threads into
2334 one voice, as common for wind parts in orchestral scores:
2336 @lilypond[verbatim,singleline,fragment]
2338 \context Voice=one \partcombine Voice
2339 \context Thread=one \notes\relative c'' {
2342 \context Thread=two \notes\relative c'' {
2348 Notice that the first @code{g} appears only once, although it was
2349 specified twice (once in each Thread). Also note that stem, slur and tie
2350 directions are set automatically, depending whether there is a solo or
2353 There is actually a third engraver involved in part combining; the
2354 @code{Voice_devnull_engraver}. This one takes care of removing
2355 redundant spanners such as beams, slurs, ties, crescendi, etc. Note that
2356 the Thread called one always gets up stems, and "solo", while @code{two}
2357 always gets down stems and "Solo II".
2359 If you just want the splitting of Threads and setting of directions, and
2360 not the textual markings, you may set the property @var{soloADue} to
2361 false. There are a number of other properties that you can use to tweak
2362 the behavior of part combining, refer to the automatically generated
2363 documentation. Look for @code{Thread_devnull_engraver}
2364 @code{Voice_engraver} and @code{A2_engraver}.
2366 @cindex @code{Thread_devnull_engraver}
2367 @cindex @code{Voice_engraver}
2368 @cindex @code{A2_engraver}
2370 @node Hara-kiri staffs
2371 @subsection Hara-kiri staffs
2374 [TODO]@footnote{Harakiri, also called Seppuku, is the ritual suicide of
2375 the Japanese Samourai warriors.}
2385 A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a
2386 staff context symbol that appears at the end of a staff line. It
2387 anticipates the pitch of the first note(s) of the following line and
2388 thus helps the player or singer to manage line breaks during
2389 performance, thus enhancing readability of a score.
2394 \notes { c'1 d' e' d' \break c' d' e' d' }
2398 \consists Custos_engraver;
2399 Custos \override #'style = #'mensural;
2406 Custodes were frequently used in music notation until the 16th century.
2407 There were different appearences for different notation styles.
2408 Nowadays, they have survived only in special forms of musical notation
2409 such as via the @emph{editio vaticana} dating back to the beginning of
2412 For typesetting custodes, just put a @code{Custos_engraver} into the
2413 @code{StaffContext} when declaring the @code{\paper} block. In this
2414 block, you can also globally control the appearance of the custos symbol
2415 by setting the custos @code{style} property. Currently supported styles
2416 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2423 \consists Custos_engraver;
2424 Custos \override #'style = #'mensural;
2429 The property can also be set locally, for example in a @code{\notes}
2434 \property Staff.Custos \override #'style = #'vaticana
2435 c'1 d' e' d' \break c' d' e' d'
2439 @c . {Tuning output}
2441 @section Tuning output
2443 LilyPond tries to take as much formatting as possible out of your
2444 hands. Nevertheless, there are situations where it needs some help, or
2445 where you want to override its decisions. In this section we discuss
2446 ways to do just that.
2448 Notation output is specified in so called grobs (graphic objects). Each
2449 grob carries with it a set of properties (grob properties) specific to
2450 that object. For example, a stem grob has properties that specify its
2451 direction, length and thickness.
2455 The most common way of tuning the output is to alter the values of these
2456 properties. There are two ways of doing that: first, you can
2457 specifically select a set of grobs at one point, and set properties as
2458 you wish, or secondly, you can (temporarily) modify the definition of a
2459 grob, thereby affecting an entire group of grobs.
2464 * Tuning groups of grobs ::
2465 * Tuning per grob ::
2470 @node Tuning groups of grobs
2471 @subsection Tuning groups of grobs
2473 @cindex grob description
2475 A grob definition is a Scheme association list, that is stored in a context
2476 property. By assigning to that property (using plain @code{\property}),
2477 you can change the resulting grobs.
2479 @lilypond[verbatim, fragment]
2480 c'4 \property Voice.Stem \override #'meta = #'((interfaces . ())) c'4
2483 The @code{\property} statement effectively empties the definition of the
2484 Stem object. One of the effects is that property specifying how it
2485 should be printed is erased, with the effect of rendering it invisible.
2491 This mechanism is fairly crude, since you can only set, but not modify,
2492 the definition of a grob. For this reason, there is a more advanced
2493 mechanism: you can add a property on top of an existing definition, or
2494 remove a property: @code{\override} adds a settings, @code{\revert}
2495 removes that setting.
2498 c'4 \property Voice.Stem \override #'thickness = #4.0
2499 c'4 \property Voice.Stem \revert #'thickness
2503 For the digirati, the grob description is an Scheme association
2504 list. Since it is singly linked, we can treat it as a stack, and
2505 @code{\override} and @code{\revert} are just push and pop
2506 operations. This pushing and popping is also used for overriding automatic
2509 If you revert a setting which was not set in the first place, then it
2510 has no effect. However, if the setting was set as a system default, it
2511 may remove the default value, and this may give surprising results,
2512 including crashes. In other words, if you use @code{\override} and
2513 @code{\revert}, be sure to balance the overrides and reverts.
2515 If balancing them is too much work, use the @code{\set} shorthand. It
2516 performs a revert followed by an override:
2518 \property Voice.Stem \set #'thickness = #2.0
2521 Formally the syntax for these constructions is
2523 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
2524 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
2525 \property @var{context}.@var{grobname} \revert @var{symbol}
2527 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
2528 and @var{grobname} are strings and @var{value} is a Scheme expression.
2532 LilyPond will hang or crash if @var{value} contains cyclic references.
2536 @node Tuning per grob
2537 @subsection Tuning per grob
2539 @cindex \outputproperty
2541 A second way of tuning grobs is the more arcane @code{\outputproperty}
2543 Syntax is as follows
2545 \outputproperty @var{predicate} @var{symbol} = @var{value}
2547 Here @code{predicate} is a Scheme function taking a grob argument, and
2548 returning a boolean. This statement is processed by the
2549 @code{Output_property_engraver}. It instructs the engraver to feed all
2550 grobs that it sees to @var{predicate}. Whenever the predicate returns
2551 true, the grob property @var{symbol} will be set to @var{value}.
2553 You will need to combine this statement with @code{\context} to select
2554 the appropriate context to apply this to.
2556 If possible, avoid this feature: the semantics are not very clean, and
2557 the syntax and semantics are up for rewrite.
2559 Here are some random examples:
2561 @lilypond[fragment,verbatim,singleline]
2563 \context Staff \outputproperty
2564 #(make-type-checker 'note-head-interface)
2565 #'extra-offset = #'(0.5 . 0.75)
2569 @cindex @code{extra-offset}
2571 This selects all note heads occurring at current staff level, and sets
2572 the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting
2575 Move the text "m.d.", but not the fingering instruction "2".
2576 @lilypond[verbatim,singleline]
2577 #(define (make-text-checker text)
2578 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
2581 \notes\relative c''' {
2582 \property Voice.Stem \set #'direction = #1
2583 \outputproperty #(make-text-checker "m.d.")
2584 #'extra-offset = #'(-3.5 . -4.5)
2594 @subsection What to tune?
2596 This all tells you how to tune grobs, but what variables are there? The
2597 question is not answered in this manual (although you may encounter
2600 Grob properties are tied directly to the implementation of LilyPond, and
2601 they are thus a moving target. Documentation of such variables are part
2602 of the generated documentation: this documentation is generated from the
2603 sourcecode of lily for each version, so it is usually mch more up to
2604 date than this manual. It should be available from the same place where
2605 you got this manual.
2607 To decide how to tune a grob, you need to find the following information
2610 which grob to modify
2612 which property to modify
2614 which context the grob comes from.
2617 Included with the automatically generated documentation is a master list
2618 of grobs. Each one can be clicked, taking you to a overview of the
2619 available properties.
2621 There is also a master list of contexts. Clicking each takes you to an
2622 overview of the context, listing which grob types are created there.
2627 @subsection Text markup
2631 LilyPond has an internal mechanism to typeset texts. You can
2632 form text markup expressions by composing scheme expressions
2633 in the following way.
2638 @lilypond[verbatim, singleline]
2641 c^#'(upright "upright")
2642 c_#'((bold upright) "bold")
2643 d^#'(lines "one" ((bold upright) "two"))
2644 e_#'(music (named "noteheads-2" "flags-u3"))
2648 Normally, the Scheme markup text is stored in the @code{text} property
2649 of a grob. Formally, it is defined as follows:
2652 text: string | (head? text+)
2653 head: markup | (markup+)
2654 markup-item: property | abbrev | @var{fontstyle}
2655 property: (@var{key} . @var{value})
2656 abbrev: @code{rows lines roman music bold italic named super sub text}
2659 The markup is broken down and converted into a list of grob properties,
2660 which are prepended to the property list. The @var{key}-@var{value}
2661 pair is a grob property.
2663 The following abbreviations are currently
2668 horizontal mode: set all text on one line (default)
2670 vertical mode: set every text on new line
2680 lookup by character name
2682 plain text lookup (by character value)
2689 @var{fontstyle} may be any of @code{finger volta timesig mmrest mark
2690 script large Large dynamic}
2692 [wat is het verschil tussen fontstyle en abbrev?]
2695 It is possible to use @TeX{} commands in the strings, but this should be
2696 avoided because this makes it impossible for LilyPond to compute the
2697 exact length of the string, which may lead to collisions. Also, @TeX{}
2698 commands won't work with direct postscript output.
2702 @section Page layout
2716 @subsection Paper block
2719 The most important output definition is the @code{\paper} block, for
2720 music notation. The syntax is
2723 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2726 where each of the items is one of
2729 @item An assignment. The assignment must be terminated by a
2732 @item A context definition. See @ref{Notation Contexts} for
2733 more information on context definitions.
2735 @item \stylesheet declaration. Its syntax is
2737 \stylesheet @var{alist}
2740 See @file{scm/font.scm} for details of @var{alist}.
2741 @item an \elementdescriptions declaration.
2743 \elementdescriptions @var{alist}
2745 See @file{scm/grob-description.scm} for details of @var{alist}.
2749 @c . {Paper variables}
2750 @node Paper variables
2751 @subsection Paper variables
2752 @cindex Paper variables
2754 The paper block has some variables you may want to use or change:
2757 @cindex @code{indent}
2759 The indentation of the first line of music.
2760 @cindex @code{staffspace}
2762 @item @code{staffspace}
2763 The distance between two staff lines, calculated from the center
2764 of the lines. If you want scale independent output, then you should
2765 use either this or @code{stafflinethickness}
2766 as a unit for distances you modify.
2768 @cindex @code{linewidth}
2769 @item @code{linewidth}
2770 Sets the width of the lines.
2772 If set to a negative value, a single
2773 unjustified line is produced.
2775 @cindex @code{textheight}
2777 @item @code{textheight}
2778 Sets the total height of the music on each page. Only used by
2781 @cindex @code{interscoreline}
2783 @item @code{interscoreline}
2784 Sets the spacing between systems.
2786 @cindex @code{interscorelinefill}
2790 @item @code{interscorelinefill}
2791 If set to a positive number, the distance between the score
2792 lines will stretch in order to fill the full page. In that
2793 case @code{interscoreline} specifies the minimum spacing.
2798 @cindex @code{stafflinethickness}
2800 @item @code{stafflinethickness}
2801 Determines the thickness of staff lines, and also acts as a scaling
2802 parameter for other line thicknesses.
2809 @subsection Font size
2812 The Feta font provides musical symbols at six different sizes. These
2813 fonts are 11 point, 13 point, 16 point, 20 point,
2814 23 point, and 26 point. The point size of a font is the
2815 height of the five lines in a staff when displayed in the font.
2817 Definitions for these sizes are the files @file{paperSZ.ly}, where
2818 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2819 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2820 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2821 @code{paperTwentysix} are defined respectively. The default
2822 @code{\paper} block is also set.
2824 The font definitions are generated using a Scheme function. For more
2825 details, see the file @file{font.scm}.
2831 @subsection Paper size
2836 @cindex @code{papersize}
2838 To change the paper size, you must first set the
2839 @code{papersize} variable at top level. Set it to
2840 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2841 specification, you must set the font as described above. If you want
2842 the default font, then use the 20 point font. The new paper size will
2843 not take effect if the font is not loaded and selected afterwards.
2847 \include "paper16.ly"
2851 \paper @{ \paperSixteen @}
2855 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
2856 will set the paper variables @code{hsize} and @code{vsize} (used by
2867 @subsection Line break
2870 @cindex breaking lines
2872 Line breaks are normally computed automatically. They are chosen such
2873 that the resulting spacing has low variation, and looks neither cramped
2876 Occasionally you might want to override the automatic breaks; you can do
2877 this by specifying @code{\break}. This will force a line break at this
2878 point. Do remember that line breaks can only occur at places where there
2879 are barlines. If you want to have a line break where there is no
2880 barline, you can force an invisible barline by entering @code{\bar "";}.
2882 Similarly, @code{\noBreak} forbids a line break at a certain point.
2884 @cindex @code{\penalty}
2886 The @code{\break} and @code{\noBreak} commands are defined in terms of
2887 the penalty command:
2889 \penalty @var{int} @code{;}
2892 This encourages or discourages LilyPond to make a line break at this
2897 The scaling of the @code{\penalty} argument is not well-defined. The
2898 command is rather kludgy, and slated for rewriting.
2902 @subsection Page break
2905 @cindex breaking pages
2908 Page breaks are normally computed by @TeX{}, so they are not under
2909 direct control of LilyPond. However, you can insert a commands into the
2910 @file{.tex} output to instruct @TeX{} where to break pages. For more
2911 details, see the example file @file{input/test/between-systems.ly}
2922 LilyPond can produce MIDI output. The performance lacks lots of
2923 interesting effects, such as swing, articulation, slurring, tieing,
2924 etc., but it is good enough for proof-hearing the music you enter.
2926 Dynamics and tempo changes are interpreted. [TODO: mention volume
2927 control/Instrument Equaliser]
2932 It is currently not possible to use the percussion channel (generally
2933 channel 10 of a MIDI file).
2937 * MIDI instrument names::
2942 @subsection MIDI block
2946 The MIDI block is analogous to the paper block, but it is somewhat
2947 simpler. The @code{\midi} block can contain:
2951 @item a @code{\tempo} definition
2952 @item context definitions
2955 Assignments in the @code{\midi} block are not allowed.
2959 @cindex context definition
2961 Context definitions follow precisely the same syntax as within the
2962 \paper block. Translation modules for sound are called performers.
2963 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2966 @node MIDI instrument names
2967 @subsection MIDI instrument names
2969 @cindex instrument names
2970 @cindex @code{Staff.midiInstrument}
2971 @cindex @code{Staff.instrument}
2973 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2974 property or, if that property is not set, the @code{Staff.instrument}
2975 property. The instrument name should be chosen from the list in
2976 @ref{MIDI Instrument}.
2980 If the selected string does not exactly match, then LilyPond uses the
2981 default piano. It is not possible to select an instrument by number.
2993 @section Music entry
3005 @subsection Relative
3007 @cindex relative octave specification
3009 Octaves are specified by adding @code{'} and @code{,} to pitch names.
3010 When you copy existing music, it is easy to accidentally put a pitch in
3011 the wrong octave and hard to find such an error. To prevent these
3012 errors, LilyPond features octave entry.
3014 @cindex @code{\relative}
3016 \relative @var{startpitch} @var{musicexpr}
3019 The octave of notes that appear in @var{musicexpr} are calculated as
3020 follows: If no octave changing marks are used, the basic interval
3021 between this and the last note is always taken to be a fourth or less.
3022 The octave changing marks @code{'} and @code{,} can then
3023 be added to raise or lower the pitch by an extra octave. Upon entering
3024 relative mode, an absolute starting pitch must be specified that will
3025 act as the predecessor of the first note of @var{musicexpr}.
3027 This distance is determined without regarding accidentals: a
3028 @code{fisis} following a @code{ceses} will be put above the
3031 Entering scales is straightforward in relative mode.
3033 @lilypond[fragment,verbatim,center]
3035 g a b c d e f g g, g
3039 And octave changing marks are used for intervals greater than a fourth.
3041 @lilypond[fragment,verbatim,center]
3043 c g c f, c' a, e'' }
3046 If the preceding item is a chord, the first note of the chord is used
3047 to determine the first note of the next chord. But other notes
3048 within the second chord are determined by looking at the immediately
3051 @lilypond[fragment,verbatim,center]
3058 @cindex @code{\notes}
3060 The pitch after the @code{\relative} contains a notename. To parse
3061 the pitch as a notename, you have to be in note mode, so there must
3062 be a surrounding @code{\notes} keyword (which is not
3065 The relative conversion will not affect @code{\transpose},
3066 @code{\chords} or @code{\relative} sections in its argument. If you
3067 want to use relative within transposed music, you must place an
3068 additional @code{\relative} inside the @code{\transpose}.
3073 @subsection Bar check
3077 @cindex @code{barCheckNoSynchronize}
3081 Whenever a bar check is encountered during interpretation, a warning
3082 message is issued if it doesn't fall at a measure boundary. This can
3083 help you find errors in the input. Depending on the value of
3084 @code{barCheckNoSynchronize}, the beginning of the measure will be
3085 relocated, so this can also be used to shorten measures.
3087 A bar check is entered using the bar symbol, @code{|}
3091 @c . {Point and click}
3092 @node Point and click
3093 @subsection Point and click
3097 @node Interpretation context
3098 @section Interpretation context
3101 * Notation Contexts::
3102 * Creating contexts::
3103 * Default contexts::
3104 * Context properties::
3105 * Changing context definitions::
3106 * Defining new contexts::
3110 @c . {Notation Contexts}
3111 @node Notation Contexts
3112 @subsection Notation Contexts
3114 @cindex notation contexts
3116 Notation contexts are objects that only exist during a run of LilyPond.
3117 During the interpretation phase of LilyPond (when lily prints
3118 "interpreting music"), music a @code{\score} block is interpreted in
3119 time order, i.e. in much the same order that humans read, play, and
3122 During this reading, the notation context is holds the state
3123 for the current point within the music. It contains information like
3126 @item What notes are playing at this point?
3127 @item What symbols will be printed at this point?
3128 @item What is the current key signature, time signature, point within
3132 Contexts are grouped hierarchically: A @code{Voice} context is
3133 contained in a @code{Staff} context (because a staff can contain
3134 multiple voices at any point), a @code{Staff} context is contained in
3135 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
3136 these can all contain multiple staffs).
3139 Contexts associated with sheet music output are called @emph{notation
3140 contexts}, those for sound output are called performance contexts.
3143 @node Creating contexts
3144 @subsection Creating contexts
3146 @cindex @code{\context}
3147 @cindex context selection
3149 Contexts for a music expression can be selected manually, using the
3150 following music expression.
3153 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
3156 This instructs lilypond to interpret @var{musicexpr} within the context
3157 of type @var{contexttype} and with name @var{contextname}. If this
3158 context does not exist, it will be created.
3162 @lilypond[verbatim,singleline]
3164 \notes \relative c'' {
3165 c4 <d4 \context Staff = "another" e4> f
3172 In this example, the @code{c} and @code{d} are printed on the
3173 default staff. For the @code{e}, a context Staff called
3174 @code{another} is specified; since that does not exist, a new
3175 context is created. Within @code{another}, a (default) Voice context
3176 is created for the @code{e4}. When all music referring to a
3177 context is finished, the context is ended as well. So after the
3178 third quarter, @code{another} is removed.
3182 @node Default contexts
3183 @subsection Default contexts
3185 Most music expressions don't need @code{\context}: they inherit the
3186 notation context from their parent. Each note is a music expression, and
3187 as you can see in the following example, only the sequential music
3188 enclosing the three notes has an explicit context.
3190 @lilypond[verbatim,singleline]
3191 \score { \notes \context Voice = goUp { c'4 d' e' } }
3194 There are some quirks that you must keep in mind when dealing with
3197 Every top-level music is interpreted by the Score context, in other
3198 words, you may think of @code{\score} working like
3201 \context Score @var{music}
3205 Sequential music follows the contexts of its "children". Take this example
3206 @lilypond[verbatim, singleline]
3207 \score { \context Score \notes { c'4 ( d' )e' } }
3210 The sequential music is interpreted by the Score context initially
3211 (notice that the @code{\context} specification is redundant), but when a
3212 note is encountered, contexts are setup to accept that note. In this
3213 case, a Thread, Voice and Staff are created. The rest of the sequential
3214 music is also interpreted with the same Thread, Voice and Staff context,
3215 putting the notes on the same staff, in the same voice.
3217 This is a convenient mechanism, but do not expect opening chords to work
3218 without @code{\context}. For every note, a separate staff is
3221 @lilypond[verbatim, singleline]
3222 \score { \notes <c'4 es'> }
3225 Of course, if the chord is preceded by a normal note in sequential
3226 music, the chord will be interpreted by the Thread of the preceding
3228 @lilypond[verbatim,singleline]
3229 \score { \notes { c'4 <c'4 es'> } }
3234 @node Context properties
3235 @subsection Context properties
3237 Notation contexts can be modified from within the @file{.ly} file. The
3238 following music expression does that job:
3240 @cindex @code{\property}
3242 \property @var{contextname}.@var{propname} = @var{value}
3245 Sets the @var{propname} property of the context @var{contextname} to the
3246 specified Scheme expression @var{value}. All @var{propname} and
3247 @var{contextname} are strings, which are typically unquoted.
3249 Properties that are set in one context are inherited by all of the
3250 contained contexts. This means that a property valid for the
3251 @code{Voice} context can be set in the @code{Score} context (for
3252 example) and thus take effect in all @code{Voice} contexts.
3254 Properties can be unset using the following expression:
3256 \property @var{contextname}.@var{propname} \unset
3259 This removes the definition of @var{propname} in @var{contextname}. If
3260 @var{propname} was not defined in @var{contextname} (but was inherited
3261 from a higher context), then this has no effect.
3266 @code{\property \unset} is not the inverse of @code{\property \set}
3271 @c . {Context definitions}
3272 @node Changing context definitions
3273 @subsection Changing context definitions
3275 @cindex context definition
3276 @cindex translator definition
3278 The most common way to define a context is by extending an existing
3279 context. You can change an existing context from the paper block, by
3280 first initializing a translator with an existing context identifier:
3284 @var{context-identifier}
3287 Then you can add engravers, remove engravers and set context
3288 properties. The syntax for these operations are respectively
3290 \remove @var{engravername}
3291 \consists @var{engravername}
3292 @var{propname} = @var{value}
3295 Here @var{engravername} is a string, the name of an engraver in the
3296 system. @var{propname} is a string and @var{value} is a Scheme
3299 @lilypond[verbatim,singleline]
3303 \translator { \StaffContext
3304 \consists Instrument_name_engraver;
3306 \remove Clef_engraver;
3312 These type of property assignments happen before interpretation starts,
3313 so a @code{\property} expression will override any predefined settings.
3315 Engravers are the actual C++ modules that do the work in the
3316 interpretation phase.
3319 There are some pre-defined identifiers to simplify editing translators,
3320 they are defined in @file{ly/engraver.ly}. These pre-defined
3324 @cindex @code{StaffContext}
3325 @item @code{StaffContext}
3326 Default Staff context.
3327 @cindex @code{RhythmicStaffContext}
3329 @item @code{RhythmicStaffContext}
3330 Default RhythmicStaff context.
3331 @cindex @code{VoiceContext}
3333 @item @code{VoiceContext}
3334 Default Voice context.
3335 @cindex @code{ScoreContext}
3337 @item @code{ScoreContext}
3338 Default Score context.
3340 @cindex @code{HaraKiriStaffContext}
3342 @item @code{HaraKiriStaffContext}
3343 Staff context that does not print if it only contains rests. See
3344 @ref{Hara-kiri staffs}.
3347 @node Defining new contexts
3348 @subsection Defining new contexts
3350 If you want to build a context from scratch, you must also supply the
3351 following extra information:
3353 @item A name, specified by @code{\name @var{contextname};}.
3355 @item A cooperation engraver. This is specified by @code{\type
3360 A context definition has this syntax:
3364 \translator @code{@{}
3365 @var{translatorinit} @var{translatormodifierlist}
3369 @var{translatorinit} can be an identifier or
3373 where @var{typename} is one of
3375 The cooperation engraver groups other engravers, and specifies how they
3376 should cooperate. Choices are:
3379 @cindex @code{Engraver_group_engraver}
3380 @item @code{Engraver_group_engraver}
3381 The standard cooperation engraver.
3383 @cindex @code{Score_engraver}
3385 @item @code{Score_engraver}
3386 This is cooperation module that should be in the top level context,
3387 and only the toplevel context.
3389 @cindex @code{Grace_engraver_group}
3391 @item @code{Grace_engraver_group}
3392 This is a special cooperation module (resembling
3393 @code{Score_engraver}) that is used to created an embedded
3397 @var{translatormodifierlist} is a list of items where each item is
3401 @item @code{\consists} @var{engravername} @code{;}
3402 Add @var{engravername} to the list of modules in this context.
3403 The order of engravers added with @code{\consists} is
3406 @item @code{\consistsend} @var{engravername} @code{;}
3407 Analogous to @code{\consists}, but makes sure that
3408 @var{engravername} is always added to the end of the list of
3411 Some engraver types need to be at the end of the list; this
3412 insures they are put there, and stay there, if a user adds or
3413 removes engravers. This command is usually not needed for
3416 @item @code{\accepts} @var{contextname} @code{;}
3417 Add @var{contextname} to the list of context this context can
3418 contain. The first listed context is the context to create by
3421 @item @code{\denies}. The opposite of @code{\accepts}. Added for
3422 completeness, but is never used in practice.
3425 @item @code{\remove} @var{engravername} @code{;}
3426 Remove a previously added (with @code{\consists}) engraver.
3428 @item @code{\name} @var{contextname} @code{;}
3429 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
3430 the name is not specified, the translator won't do anything.
3432 @item @var{propname} @code{=} @var{value} @code{;}
3433 A property assignment.
3436 In the @code{\paper} block, it is also possible to define translator
3437 identifiers. Like other block identifiers, the identifier can only
3438 be used as the very first item of a translator. In order to define
3439 such an identifier outside of @code{\score}, you must do
3445 foo = \translator @{ @dots{} @}
3452 \translator @{ \foo @dots{} @}
3460 @cindex paper types, engravers, and pre-defined translators
3465 Properties can be preset within the @code{\translator} block
3466 corresponding to the appropriate context. In this case, the syntax
3470 @var{propname} @code{=} @var{value}
3473 The property settings are used during the interpretation phase. They
3474 are read by the LilyPond modules where interpretation contexts are
3475 built of. These modules are called @emph{translators}. Translators for
3476 notation are called @emph{engravers}, and translators for sound are
3477 called @emph{performers}.
3482 @c . {Syntactic details}
3483 @node Syntactic details
3484 @section Syntactic details
3485 @cindex Syntactic details
3489 * Music expressions::
3490 * Manipulating music expressions::
3498 @subsection Top level
3501 This section describes what you may enter at top level.
3505 @subsubsection Score
3508 @cindex score definition
3510 The output is generated combining a music expression with an output
3511 definition. A score block has the following syntax:
3514 \score @{ @var{musicexpr} @var{outputdefs} @}
3517 @var{outputdefs} are zero or more output definitions. If no output
3518 definition is supplied, the default @code{\paper} block will be added.
3522 @c . {Default output}
3523 @subsubsection Default output
3525 Default values for the @code{\paper} and @code{\midi} block are set by
3526 entering such a block at top-level.
3529 @subsubsection Header
3531 @cindex @code{\header}
3536 \header @{ @var{key1} = @var{val1};
3537 @cindex @code{ly2dvi}
3538 @var{key2} = @var{val2}; @dots{} @}
3542 A header describes the file's contents. It can also appear in a
3543 @code{\score} block. Tools like @code{ly2dvi} can use this
3544 information for generating titles. Key values that are used by
3545 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
3546 metre, arranger, piece and tagline.
3548 It is customary to put the @code{\header} at the top of the file.
3550 @subsubsection Default output
3552 A @code{\midi} or @code{\paper} block at top-level sets the default
3554 paper block for all scores that lack an explicit paper block.
3558 @subsection Identifiers
3561 All of the information in a LilyPond input file, is represented as a
3562 Scheme value. In addition to normal Scheme data types (such as pair,
3563 number, boolean, etc.), LilyPond has a number of specialized data types,
3570 @item Translator_def
3574 @item Music_output_def
3575 @item Moment (rational number)
3578 LilyPond also includes some transient object types. Objects of these
3579 types are built during a LilyPond run, and do not `exist' per se within
3580 your input file. These objects are created as a result of your input
3581 file, so you can include commands in the input to manipulate them,
3582 during a lilypond run.
3585 @item Grob: short for Graphical object. See @ref{Grobs}.
3586 @item Molecule: device-independent page output object,
3587 including dimensions. Produced by some Grob functions
3589 @item Translator: object that produces audio objects or Grobs. This is
3590 not yet user accessible.
3591 @item Font_metric: object representing a font. (See @ref{Font metrics})
3596 @node Music expressions
3597 @subsection Music expressions
3599 @cindex music expressions
3601 Music in LilyPond is entered as a music expression. Notes, rests, lyric
3602 syllables are music expressions, and you can combine music expressions
3603 to form new ones, for example by enclosing a list of expressions in
3604 @code{\sequential @{ @}} or @code{< >}. In this example, a compound
3605 expression is formed out of the quarter note @code{c} and a quarter note
3609 \sequential @{ c4 d4 @}
3612 @cindex Sequential music
3613 @cindex @code{\sequential}
3614 @cindex sequential music
3617 @cindex Simultaneous music
3618 @cindex @code{\simultaneous}
3620 The two basic compound music expressions are simultaneous and
3624 \sequential @code{@{} @var{musicexprlist} @code{@}}
3625 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
3627 For both, there is a shorthand:
3629 @code{@{} @var{musicexprlist} @code{@}}
3633 @code{<} @var{musicexprlist} @code{>}
3635 for simultaneous music.
3636 In principle, the way in which you nest sequential and simultaneous to
3637 produce music is not relevant. In the following example, three chords
3638 are expressed in two different ways:
3640 @lilypond[fragment,verbatim,center]
3641 \notes \context Voice {
3642 <a c'> <b d' > <c' e'>
3643 < { a b c' } { c' d' e' } >
3648 Other compound music expressions include
3651 \transpose @var{pitch} @var{expr}
3652 \apply @var{func} @var{expr}
3653 \context @var{type} = @var{id} @var{expr}
3654 \times @var{fraction} @var{expr}
3658 @c . {Manipulating music expressions}
3659 @node Manipulating music expressions
3660 @subsection Manipulating music expressions
3662 The @code{\apply} mechanism gives you access to the internal
3663 representation of music. You can write Scheme-functions that operate
3664 directly on it. The syntax is
3666 \apply #@var{func} @var{music}
3668 This means that @var{func} is applied to @var{music}. The function
3669 @var{func} should return a music expression.
3671 This example replaces the text string of a script. It also shows a dump
3672 of the music it processes, which is useful if you want to know more
3673 about how music is stored.
3675 #(define (testfunc x)
3676 (if (equal? (ly-get-mus-property x 'text) "foo")
3677 (ly-set-mus-property x 'text "bar"))
3679 (ly-set-mus-property x 'elements
3680 (map testfunc (ly-get-mus-property x 'elements)))
3685 \apply #testfunc { c4_"foo" }
3689 For more information on what is possible, see the @ref{Tricks} and the
3690 automatically generated documentation.
3693 Directly accessing internal representations is dangerous: the
3694 implementation is subject to changes, so you should avoid this feature
3699 @c . {Span requests}
3705 @subsubsection Span requests
3706 @cindex Span requests
3708 Notational constructs that start and end on different notes can be
3709 entered using span requests. The syntax is as follows:
3713 \spanrequest @var{startstop} @var{type}
3717 @cindex @code{\start}
3718 @cindex @code{\stop}
3720 This defines a spanning request. The @var{startstop} parameter is either
3721 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
3722 describes what should be started. Much of the syntactic sugar is a
3723 shorthand for @code{\spanrequest}, for example,
3725 @lilypond[fragment,verbatim,center]
3726 c'4-\spanrequest \start "slur"
3727 c'4-\spanrequest \stop "slur"
3730 Among the supported types are @code{crescendo}, @code{decrescendo},
3731 @code{beam}, @code{slur}. This is an internal command. Users are
3732 encouraged to use the shorthands which are defined in the initialization
3733 file @file{spanners.ly}.
3738 @subsection Assignments
3741 Identifiers allow objects to be assigned to names during the parse
3742 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
3743 and to refer to an identifier, you preceed its name with a backslash:
3744 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
3745 the input-types listed above. Identifier assignments can appear at top
3746 level in the LilyPond file, but also in @code{\paper} blocks.
3748 Semicolons are forbidden after top level assignments, but mandatory in
3749 other places. The rules about semicolons and assignments are very
3750 confusing, but when LilyPond input evolves more towards Scheme, we hope
3751 that this problem will grow smaller.
3753 An identifier can be created with any string for its name, but you will
3754 only be able to refer to identifiers whose names begin with a letter,
3755 being entirely alphabetical. It is impossible to refer to an identifier
3756 whose name is the same as the name of a keyword.
3758 The right hand side of an identifier assignment is parsed completely
3759 before the assignment is done, so it is allowed to redefine an
3760 identifier in terms of its old value, e.g.
3766 When an identifier is referenced, the information it points to is
3767 copied. For this reason, an identifier reference must always be the
3768 first item in a block.
3772 \paperIdent % wrong and invalid
3776 \paperIdent % correct
3781 @c . {Lexical modes}
3783 @subsection Lexical modes
3784 @cindex Lexical modes
3787 @cindex @code{\notes}
3788 @cindex @code{\chords}
3789 @cindex @code{\lyrics}
3791 To simplify entering notes, lyrics, and chords, LilyPond has three
3792 special input modes on top of the default mode: note, lyrics and chords
3793 mode. These input modes change the way that normal, unquoted words are
3794 interpreted: for example, the word @code{cis} may be interpreted as a
3795 C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
3798 A mode switch is entered as a compound music expressions
3800 @code{\notes} @var{musicexpr}
3801 @code{\chords} @var{musicexpr}
3802 @code{\lyrics} @var{musicexpr}.
3805 In each of these cases, these expressions do not add anything to the
3806 meaning of their arguments. They are just a way to indicate that the
3807 arguments should be parsed in indicated mode. The modes are treated in
3808 more detail in the @ref{Note entry}, @ref{Lyrics} and
3811 You may nest different input modes.
3815 @subsection Ambiguities
3820 The grammar contains a number of ambiguities. We hope to resolve them at
3824 @item The assignment
3830 can be interpreted as making a string identifier @code{\foo}
3831 containing @code{"bar"}, or a music identifier @code{\foo}
3832 containing the syllable `bar'.
3834 @item The assignment
3840 can be interpreted as making an integer identifier
3841 containing -6, or a Request identifier containing the
3842 fingering `6' (with neutral direction).
3844 @item If you do a nested repeat like
3856 then it is ambiguous to which @code{\repeat} the
3857 @code{\alternative} belongs. This is the classic if-then-else
3858 dilemma. It may be solved by using braces.
3860 @item (an as yet unidentified ambiguity :-)
3864 @c . {Lexical details}
3865 @node Lexical details
3866 @section Lexical details
3877 * Version information::
3882 @subsection Comments
3885 @cindex block comment
3886 @cindex line comment
3890 A one line comment is introduced by a @code{%} character.
3891 Block comments are started by @code{%@{} and ended by @code{%@}}.
3892 They cannot be nested.
3895 @subsection Direct Scheme
3899 @cindex Scheme, in-line code
3902 LilyPond contains a Scheme interpreter (the GUILE library) for
3903 internal use. In some places Scheme expressions also form valid syntax:
3904 whereever it is allowed,
3908 evaluates the specified Scheme code. If this is used at toplevel, then
3909 the result is discarded. Example:
3911 \property Staff.TestObject \override #'foobar = #(+ 1 2)
3914 @code{\override} expects two Scheme expressions, so there are two Scheme
3915 expressions. The first one is a symbol (@code{foobar}), the second one
3916 an integer (namely, 3).
3918 Scheme is a full-blown programming language, and a full discussion is
3919 outside the scope of this document. Interested readers are referred to
3920 the website @uref{http://www.schemers.org/} for more information on
3925 @subsection Keywords
3929 Keywords start with a backslash, followed by a number of lower case
3930 alphabetic characters. These are all the keywords.
3933 apply arpeggio autochange spanrequest commandspanrequest
3934 simultaneous sequential accepts alternative bar breathe
3935 char chordmodifiers chords clef cm consists consistsend
3936 context denies duration dynamicscript elementdescriptions
3937 font grace header in lyrics key mark pitch
3938 time times midi mm name pitchnames notes outputproperty
3939 override set revert partial paper penalty property pt
3940 relative remove repeat addlyrics partcombine score
3941 script stylesheet skip textscript tempo translator
3946 @subsection Integers
3954 Formed from an optional minus sign followed by digits. Arithmetic
3955 operations cannot be done with integers, and integers cannot be mixed
3960 @cindex real numbers
3966 Formed from an optional minus sign and a sequence of digits followed
3967 by a @emph{required} decimal point and an optional exponent such as
3968 @code{-1.2e3}. Reals can be built up using the usual operations:
3969 `@code{+}', `@code{-}', `@code{*}', and
3970 `@code{/}', with parentheses for grouping.
3978 A real constant can be followed by one of the dimension keywords:
3979 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
3980 points, inches and centimeters, respectively. This converts the number
3981 to a real that is the internal representation of dimensions.
3989 Begins and ends with the @code{"} character. To include a @code{"}
3990 character in a string write @code{\"}. Various other backslash
3991 sequences have special interpretations as in the C language. A string
3992 that contains no spaces can be written without the quotes. See
3993 @ref{Lexical modes} for details on unquoted strings; their
3994 interpretation varies depending on the situation. Strings can be
3995 concatenated with the @code{+} operator.
3997 The tokenizer accepts the following commands. They have no grammatical
3998 function, hence they can appear anywhere in the input.
4002 @subsection Main input
4005 @cindex @code{\maininput}
4007 The @code{\maininput} command is used in init files to signal that the
4008 user file must be read. This command cannot be used in a user file.
4010 @node File inclusion
4011 @subsection File inclusion
4012 @cindex @code{\include}
4014 \include @var{filename}
4017 Include @var{filename}. The argument @var{filename} may be a quoted string (an
4018 unquoted string will not work here!) or a string identifier. The full
4019 filename including the @file{.ly} extension must be given,
4022 @node Version information
4023 @subsection Version information
4024 @cindex @code{\version}
4026 \version @var{string} ;
4029 Specify the version of LilyPond that a file was written for. The
4030 argument is a version string in quotes, for example @code{"1.2.0"}.
4031 This is used to detect invalid input, and to aid
4032 @code{convert-ly} a tool that automatically upgrades input files. See
4033 See @ref{convert-ly} for more information on @code{convert-ly}.
4042 @c .{Local emacs vars}
4045 @c minor-mode: font-lock
4046 @c minor-mode: outline
4047 @c outline-layout: (-1 : 0)
4048 @c outline-use-mode-specific-leader: "@c \."
4049 @c outline-primary-bullet: "{"
4050 @c outline-stylish-prefixes: nil
4051 @c outline-override-protect: t