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)
17 postscript, scheme output?
19 (links to?) using/existance of ly2dvi, lilypond-book
24 @c .{Reference Manual}
26 @node Reference Manual
27 @chapter Reference Manual
29 This document describes GNU LilyPond and its input format. This document
30 has been revised for LilyPond 1.3.125
59 The purpose of LilyPond is explained informally by the term `music
60 typesetter'. This is not a fully correct name: not only does the
61 program print musical symbols, it also makes esthetic decisions. All
62 symbols and their placement is @emph{generated} from a high-level
63 musical description. In other words, LilyPond would be best described
64 by `music compiler' or `music to notation compiler'.
66 Internally, LilyPond is written in a mixture of Scheme and C++. Most of
67 the algorithms and low-level routines are written in C++, but these low
68 level components are glued together using Scheme data
69 structures. LilyPond is linked to GUILE, GNU's Scheme library for
72 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 .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. in the same order as your eyes scan sheet music, and in the
80 same order that you hear the notes play.
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 These stages, involve data of a specific type: during parsing,
90 @strong{Music} objects are created. During the interpretation,
91 @strong{context} is constructed, and with this context af network of
92 @strong{graphical objects} (``grobs'') is created. The grobs contain
93 unknown variables, and the network forms a set of equations. After
94 solving the equations and filling in these variables, the printed output
95 (in the form of @strong{molecules}) is written to an output file.
97 These threemanship of tasks (parsing, translating, typesetting) and
98 data-structures (music, context, graphical objects) permeates the entire
99 design of the program. This manual is ordered in terms of user
100 tasks. With each concept will be explained to which of the three parts
103 LilyPond input can be classified into three types:
105 @item musical expressions: a musical expression is some combination of
107 @item output definitions: recipes for translating those musical
108 expressions into performances (MIDI) or graphics (eg. PostScript).
110 @item declarations: by declaring and naming musical expressions, you
111 can enter and edit them in manageable chunks.
123 @cindex @code{\repeat}
125 In order to specify repeats, use the @code{\repeat}
126 keyword. Since repeats look and sound differently when played or
127 printed, there are a few different variants of repeats.
131 Repeated music is fully written (played) out. Useful for MIDI
135 This is the normal notation: Repeats are not written out, but
136 alternative endings (voltas) are printed, left to right.
139 Alternative endings are written stacked. Which is unfortunately not
140 practical for anything right now.
148 * Manual repeat commands::
150 * Tremolo subdivision::
154 @subsection Repeat syntax
156 The syntax for repeats is
159 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
162 If you have alternative endings, you may add
164 @cindex @code{\alternative}
166 \alternative @code{@{} @var{alternative1}
168 @var{alternative3} @dots{} @code{@}}
171 where each @var{alternative} is a Music expression.
173 Normal notation repeats are used like this:
177 @lilypond[fragment,verbatim]
179 \repeat volta 2 { c'4 d' e' f' }
180 \repeat volta 2 { f' e' d' c' }
184 With alternative endings:
188 @lilypond[fragment,verbatim]
190 \repeat volta 2 {c'4 d' e' f'}
191 \alternative { {d'2 d'} {f' f} }
195 Folded repeats look like this:@footnote{Folded repeats offer little
196 more over simultaneous music. However, it is to be expected that
197 more functionality -- especially for the MIDI backend -- will be
198 implemented at some point in the future.}
202 @lilypond[fragment,verbatim]
204 \repeat fold 2 {c'4 d' e' f'}
205 \alternative { {d'2 d'} {f' f} }
211 If you don't give enough alternatives for all of the repeats, then
212 the first alternative is assumed to be repeated often enough to equal
213 the specified number of repeats.
216 @lilypond[fragment,verbatim]
220 \repeat volta 3 { e | c2 d2 | e2 f2 | }
221 \alternative { { g4 g g } { a | a a a a | b2. } }
229 As you can see, LilyPond doesn't remember the timing information, nor
230 are slurs or ties repeated, so you have to reset timing information
231 after a repeat, eg using bar-checks, @code{Score.measurePosition} or
232 @code{\partial}. We hope to fix this after 1.4.
234 It is possible to nest @code{\repeat}, although it probably is only
235 meaningful for unfolded repeats.
237 @node Manual repeat commands
238 @subsection Manual repeat commands
240 @cindex @code{repeatCommands}
242 The property @code{repeatCommands} can be used to control the layout of
243 repeats. Its value is a Scheme list of repeat commands, where each repeat
251 @item (volta . @var{text})
252 Print a volta bracket saying @var{text}.
254 Stop a running volta bracket
257 @lilypond[verbatim, fragment]
259 \property Score.repeatCommands = #'((volta "93") end-repeat)
261 \property Score.repeatCommands = #'((volta #f))
266 @node Tremolo repeats
267 @subsection Tremolo repeats
268 @cindex tremolo beams
270 To place tremolo marks between notes, use @code{\repeat} with tremolo
272 @lilypond[verbatim,center]
274 \context Voice \notes\relative c' {
275 \repeat "tremolo" 8 { c16 d16 }
276 \repeat "tremolo" 4 { c16 d16 }
277 \repeat "tremolo" 2 { c16 d16 }
278 \repeat "tremolo" 4 c16
281 linewidth = 40*\staffspace;
286 @node Tremolo subdivision
287 @subsection Tremolo subdivision
288 @cindex tremolo marks
289 @cindex @code{tremoloFlags}
291 Tremolo marks can be printed on a single note by adding
292 `@code{:}[@var{length}]' after the note. The length must be at least 8.
293 A @var{length} value of 8 gives one line across the note stem. If the
294 length is omitted, then the last value is used, or the value of the
295 @code{tremoloFlags} property if there was no last value.
297 @lilypond[verbatim,fragment,center]
301 Tremolos in this style do not carry over into the MIDI output.
303 Using this mechanism pays off when you entering many tremolos, since the
304 default argument saves a lot of typing.
315 * Defining pitch names::
324 @subsection Notes mode
328 @cindex @code{\notes}
329 Note mode is introduced by the keyword
330 @code{\notes}. In Note mode, words can only
331 contain alphabetic characters. If @code{word} is encountered,
332 LilyPond first checks for a notename of @code{word}. If no
333 notename is found, then @code{word} is treated as a string.
335 Since combinations of numbers and dots are used for indicating
336 durations, it is not possible to enter real numbers in this mode.
345 @cindex Note specification
347 @cindex entering notes
349 The verbose syntax for pitch specification is
351 @cindex @code{\pitch}
353 \pitch @var{scmpitch}
356 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
358 In Note and Chord mode, pitches may be designated by names. The default
359 names are the Dutch note names. The notes are specified by the letters
360 @code{c} through @code{b}, where @code{c} is an octave below middle C
361 and the letters span the octave above that C. In Dutch,
362 @cindex note names, Dutch
363 a sharp is formed by adding @code{-is} to the end of a pitch name. A
364 flat is formed by adding @code{-es}. Double sharps and double flats are
365 obtained by adding @code{-isis} or @code{-eses}. @code{aes} and
366 @code{ees} are contracted to @code{as} and @code{es} in Dutch, but both
367 forms will be accepted.
369 LilyPond has predefined sets of notenames for various other languages.
370 To use them, simply include the language specific init file. For
371 example: @code{\include "english.ly"}. The available language files and
372 the names they define are:
375 Note Names sharp flat
376 nederlands.ly c d e f g a bes b -is -es
377 english.ly c d e f g a bf b -s/-sharp -f/-flat
378 deutsch.ly c d e f g a b h -is -es
379 norsk.ly c d e f g a b h -iss/-is -ess/-es
380 svenska.ly c d e f g a b h -iss -ess
381 italiano.ly do re mi fa sol la sib si -d -b
382 catalan.ly do re mi fa sol la sib si -d/-s -b
391 The optional octave specification takes the form of a series of
392 single quote (`@code{'}') characters or a series of comma
393 (`@code{,}') characters. Each @code{'} raises the pitch by one
394 octave; each @code{,} lowers the pitch by an octave.
396 @lilypond[fragment,verbatim,center]
397 c' d' e' f' g' a' b' c''
400 @lilypond[fragment,verbatim,center]
401 cis' dis' eis' fis' gis' ais' bis'
404 @lilypond[fragment,verbatim,center]
405 ces' des' es' fes' ges' as' bes'
408 @lilypond[fragment,verbatim,center]
409 cisis' eisis' gisis' aisis' beses'
412 @lilypond[fragment,verbatim,center]
413 ceses' eses' geses' ases' beses'
417 @c . {Defining pitch names}
418 @node Defining pitch names
419 @subsection Defining pitch names
421 @cindex defining pitch names
422 @cindex pitch names, defining
424 Note names and chord modifiers can be customised for nationalities. The
425 syntax is as follows.
427 @cindex @code{\pitchnames}
428 @cindex @code{\chordmodifiers}
430 \pitchnames @var{scheme-alist}
431 \chordmodifiers @var{scheme-alist}
434 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
435 specific examples how to do this. Some national note names have been
436 provided, among others: Norwegian, Swedish, German, Italian, Catalan,
437 French, Dutch and English.
442 @subsection Durations
446 @cindex @code{\duration}
448 The syntax for an verbose duration specification is
450 \duration @var{scmduration}
453 In Note, Chord, and Lyrics mode, durations may be designated by numbers
454 and dots: durations are entered as their reciprocal values. For notes
455 longer than a whole note, use identifiers.
461 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
463 r1 r2 r4 r8 r16 r32 r64 r64
469 \notes \relative c'' {
470 a\longa a\breve \autoBeamOff
471 a1 a2 a4 a8 a16 a32 a64 a64
473 r1 r2 r4 r8 r16 r32 r64 r64
478 \remove "Clef_engraver";
479 \remove "Staff_symbol_engraver";
480 \remove "Time_signature_engraver";
481 \consists "Pitch_squash_engraver";
488 As you can see, the longa is not printed. To get a longa note head, you
489 have to use a different style of note heads. See [TODO].
491 If the duration is omitted then it is set equal to the previous duration
492 entered. At the start of parsing there is no previous duration, so then
493 a quarter note is assumed. The duration can be followed by a dot
494 (`@code{.}') to obtain dotted note lengths.
497 @lilypond[fragment,verbatim,center]
503 You can alter the length of duration by writing `@code{*}@var{fraction}'
504 after it. This will not affect the appearance of note heads or rests.
510 A note specification has the form
513 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
517 LilyPond will determine what accidentals to typeset depending on the key
518 and context, so alteration refer to what note is heard, not to whether
519 accidentals are printed. A reminder accidental
520 @cindex reminder accidental
522 can be forced by adding an exclamation mark @code{!} after the pitch.
523 A cautionary accidental,
524 @cindex cautionary accidental
526 i.e., an accidental within parentheses can be obtained by adding the
527 question mark `@code{?}' after the pitch.
529 @lilypond[fragment,verbatim,center]
530 cis' d' e' cis' c'? d' e' c'!
539 Rests are entered like notes, with note name `@code{r}'.
540 There is also a note name
541 `@code{s}', which produces a space of the specified
552 \skip @var{duration} @code{;}
556 Skips the amount of time specified by @var{duration}. If no other
557 music is played, a gap will be left for the skipped time with no
558 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
559 this has the same effect as the spacer rest.
563 @c . {Music notation}
565 @section Music notation
566 @cindex Music notation
580 @code{\key} @var{pitch} @var{type} @code{;}
582 @cindex @code{\minor}
583 @cindex @code{\major}
584 @cindex @code{\minor}
585 @cindex @code{\ionian}
586 @cindex @code{\locrian}
587 @cindex @code{\aeolian}
588 @cindex @code{\mixolydian}
589 @cindex @code{\lydian}
590 @cindex @code{\phrygian}
591 @cindex @code{\dorian}
593 Change the key signature. @var{type} should be @code{\major} or
594 @code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
595 respectively. The second argument is optional; the default is major
596 keys. The @var{\context} argument can also be given as an integer,
597 which tells the number of semitones that should be added to the pitch
598 given in the subsequent @code{\key} commands to get the corresponding
599 major key, e.g., @code{\minor} is defined as 3. The standard mode names
600 @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
601 @code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
603 This command sets @code{Staff.keySignature}.
605 @cindex @code{keySignature}
608 @subsubsection Clef changes
611 \clef @var{clefname} @code{;}
617 \property Staff.clefGlyph = @var{symbol associated with clefname}
618 \property Staff.clefPosition = @var{clef Y-position for clefname}
619 \property Staff.clefOctavation = @var{extra pitch of clefname}
622 Supported clef-names include
625 @item treble, violin, G, G2: G clef on 2nd line
626 @item french: G clef on 1st line
627 @item soprano: C clef on 1st line
628 @item mezzosoprano: C clef on 2nd line
629 @item alto: C clef on 3rd line
630 @item tenor: C clef on 4th line
631 @item baritone: C clef on 5th line
632 @item varbaritone: F clef on 3rd line
633 @item bass, F: F clef on 4th line
634 @item subbass: F clef on 5th line
635 @item percussion: percussion clef
638 [todo: ancient clefs]
640 Supported associated symbols (for Staff.clefGlyph) are:
643 @item clefs-C: modern style C clef
644 @item clefs-F: modern style F clef
645 @item clefs-G: modern style G clef
646 @item clefs-vaticana_do: Editio Vaticana style do clef
647 @item clefs-vaticana_fa: Editio Vaticana style fa clef
648 @item clefs-medicaea_do: Editio Medicaea style do clef
649 @item clefs-medicaea_fa: Editio Medicaea style fa clef
650 @item clefs-mensural1_c: modern style mensural C clef
651 @item clefs-mensural2_c: historic style small mensural C clef
652 @item clefs-mensural3_c: historic style big mensural C clef
653 @item clefs-mensural1_f: historic style traditional mensural F clef
654 @item clefs-mensural2_f: historic style new mensural F clef
655 @item clefs-mensural_g: historic style mensural G clef
656 @item clefs-hufnagel_do: historic style hufnagel do clef
657 @item clefs-hufnagel_fa: historic style hufnagel fa clef
658 @item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef
659 @item clefs-percussion: modern style percussion clef
662 @emph{Modern style} means "as is typeset in current editions".
663 @emph{Historic style} means "as was typeset or written in contemporary
664 historic editions". @emph{Editio XXX style} means "as is/was printed in
667 @c . {Time signature}
669 @subsection Time signature
670 @cindex Time signature
675 \time @var{numerator}@code{/}@var{denominator} @code{;}
678 A short-cut for doing
680 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
683 See the documentation of @code{timeSignatureFraction}
687 @subsubsection Partial
691 @cindex partial measure
692 @cindex measure, partial
693 @cindex shorten measures
694 @cindex @code{\partial}
696 \partial @var{duration} @code{;}
702 \property Score.measurePosition = @var{length of duration}
706 See the documentation of @code{measurePosition}.
714 [todo : collisiosn, rest-collisinos, voiceX identifiers, how to
715 which contexts to instantiate.]
719 @cindex @code{\shiftOff}
720 @item @code{\shiftOff}
721 Disable horizontal shifting of note heads that collide.
723 @cindex @code{\shiftOn}
724 @item @code{\shiftOn}
725 Enable note heads that collide with other note heads to be
726 shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
727 set different shift values.
729 @cindex @code{\stemBoth}
730 @item @code{\stemBoth}
731 Allow stems, beams, and slurs to point either upwards or
732 downwards, decided automatically by LilyPond.
734 @cindex @code{\stemDown}
735 @item @code{\stemDown}
736 Force stems, beams, and slurs to point down.
738 @cindex @code{\stemUp}
740 Force stems, beams and slurs to point up.
765 @c . {Automatic beams}
766 @subsubsection Automatic beams
769 @cindex automatic beam generation
771 @cindex @code{Voice.noAutoBeaming}
773 LilyPond will group flagged notes and generate beams autmatically, where
776 This feature can be disabled by setting the @code{Voice.noAutoBeaming}
777 property to true, which you may find necessary for the melody that goes
778 with lyrics, eg. Automatic beaming can easily be overridden for
779 specific cases by specifying explicit beams. This is discussed in the
784 @cindex @code{Voice.autoBeamSettings}
785 @cindex @code{(end * * * *)}
786 @cindex @code{(begin * * * *)}
788 A large number of Voice properties are used to decide how to generate
789 beams. Their default values appear in @file{scm/auto-beam.scm}. In
790 general, beams can begin anywhere, but their ending location is
791 significant. Beams can end on a beat, or at durations specified by the
792 properties in @code{Voice.autoBeamSettings}. To end beams every quarter
793 note, for example, you could set the property @code{(end * * * *)} to
794 @code{(make-moment 1 4)}. To end beams at every three eighth notes you
795 would set it to @code{(make-moment 1 8)}. The same syntax can be used
796 to specify beam starting points using @code{(begin * * * *)}, eg:
799 \property Voice.autoBeamSettings \override
800 #'(end * * * *) = #(make-moment 1 4)
801 \property Voice.autoBeamSettings \override
802 #'(begin * * * *) = #(make-moment 1 8)
806 To allow different settings for different time signatures, instead of
807 the first two asterisks @code{* *} you can specify a time signature; use
808 @code{(end N M * *)} to restrict the definition to
809 `@var{N}@code{/}@var{M}' time. For example, to specify beams ending
810 only for 6/8 time you would use the property @code{(end 6 8 * *)}.
812 To allow different endings for notes of different durations, instead of
813 th last two asterisks you can specify a duration; use @code{(end * * N
814 M)} to restrict the definition to beams that contain notes of
815 `@var{N}@code{/}@var{M}' duration.
817 For example, to specify beam endings for beams that contain 32nd notes,
818 you would use @code{(end * * 1 32)}.
823 @cindex Automatic beams
824 @subsubsection Manual beams
825 @cindex beams, manual
829 In some cases it may be necessary to override LilyPond's automatic
830 beaming algorithm. For example, the auto beamer will not beam over
831 rests or bar lines, so if you want that, specify the begin and end point
832 manually using @code{[} and @code{]}:
835 @lilypond[fragment,relative,verbatim]
837 r4 [r8 g'' a r8] r8 [g | a] r8
842 @cindex @code{stemLeftBeamCount}
844 If you have specific wishes for the number of beams, you can fully
845 control the number of beams through the properties
846 y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
848 @lilypond[fragment,relative,verbatim]
851 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
855 @cindex @code{stemRightBeamCount}
858 @c . {Adjusting beams}
859 @unnumberedsubsubsec Adjusting beams
860 @cindex Adjusting beams
876 A slur connects chords and is used to indicate legato. Slurs avoid
877 crossing stems. A slur is started with @code{(} and stopped with
878 @code{)}. The starting @code{(} appears to the right of the first note
879 in the slur. The terminal @code{)} appears to the left of the last note
880 in the slur. This makes it possible to put a note in slurs from both
883 @lilypond[fragment,verbatim,center]
884 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
887 @c . {Adjusting slurs}
888 @unnumberedsubsubsec Adjusting slurs
891 @node Slur attachments
892 @subsubsection Slur attachments
894 The ending of a slur should whenever possible be attached to a note
895 head. Only in some instances where beams are involved, LilyPond may
896 attach a slur to a stem end. In some cases, you may want to override
897 LilyPond's decision, e.g., to attach the slur to the stem end. This can
898 be done through @code{Voice.Slur}'s grob-property @code{attachment}:
902 @lilypond[fragment,relative,verbatim]
903 \property Voice.Slur \set #'direction = #1
904 \property Voice.Stem \set #'length = #5.5
906 \property Voice.Slur \set #'attachment = #'(stem . stem)
911 Similarly, slurs can be attached to note heads even when beams are
915 @lilypond[fragment,relative,verbatim]
916 \property Voice.Slur \set #'direction = #1
917 \property Voice.Slur \set #'attachment = #'(head . head)
918 g''16()g()g()g()d'()d()d()d
922 If a slur would strike through a stem or beam, LilyPond will move the
923 slur away vertically (upward or downward). In some cases, this may
924 cause ugly slurs that you may want to correct:
927 @lilypond[fragment,relative,verbatim]
928 \property Voice.Stem \set #'direction = #1
929 \property Voice.Slur \set #'direction = #1
931 \property Voice.Slur \set #'attachment = #'(stem . stem)
936 LilyPond will increase the curvature of a slur trying to stay free of
937 note heads and stems. However, if the curvature would increase too much,
938 the slur will be reverted to its default shape. This decision is based
939 on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
940 cases, you may find ugly slurs beautiful, and tell LilyPond so by
941 increasing the @code{beautiful} value:
943 [hoe gedefd?? wat betekent beautiful = X?]
948 \notes \context PianoStaff <
950 \context Staff=up { s1 * 6/4 }
951 \context Staff=down <
953 \autochange Staff \context Voice
955 d,8( a' d f a d f d a f d )a
963 Slur \override #'beautiful = #5.0
964 Slur \override #'direction = #1
965 Stem \override #'direction = #-1
966 autoBeamSettings \override #'(end * * * *)
971 VerticalAlignment \override #'threshold = #'(5 . 5)
978 @cindex Adusting slurs
984 @subsection Phrasing slur
985 @cindex phrasing slur
986 @cindex phrasing mark
988 A phrasing slur (or phrasing mark) connects chords and is used to
989 indicate a musical sentence. Phrasing slurs avoid crossing stems. A
990 phrasing slur is started with @code{\(} and stopped with @code{\)}. The
991 starting @code{\(} appears to the right of the first note in the
992 phrasing slur. The terminal @code{\)} appears to the left of the last
993 note in the phrasing slur.
995 @lilypond[fragment,verbatim,center,relative]
996 \time 6/4; c''\((d)e f(e)\)d
1016 A tie connects two adjacent note heads of the same pitch. When used
1017 with chords, it connects all of the note heads whose pitches match.
1018 Ties are indicated using the tilde symbol `@code{~}'.
1019 If you try to tie together chords which have no common pitches, a
1020 warning message will appear and no ties will be created.
1022 @lilypond[fragment,verbatim,center]
1023 e' ~ e' <c' e' g'> ~ <c' e' g'>
1031 @subsubsection Tuplets
1035 Tuplets are made out of a music expression by multiplying their duration
1038 @cindex @code{\times}
1040 \times @var{fraction} @var{musicexpr}
1043 The duration of @var{musicexpr} will be multiplied by the fraction.
1044 In print, the fraction's denominator will be printed over the notes,
1045 optionally with a bracket. The most common tuplet is the triplet in
1046 which 3 notes have the length of 2, so the notes are 2/3 of
1047 their written length:
1049 @lilypond[fragment,verbatim,center]
1050 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1053 [todo: document tupletSpannerDuration]
1059 @subsubsection Text spanner
1060 @cindex Text spanner
1064 @subsubsection Ottava
1066 @unnumberedsubsubsec Ottava
1068 [move to trick. Not a supported feature.]
1070 @lilypond[fragment,relative,verbatim]
1072 \property Voice.TextSpanner \set #'type = #'dotted-line
1073 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1074 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1075 \property Staff.centralCPosition = #-13
1076 a\spanrequest \start "text" b c a \spanrequest \stop "text"
1081 @c . {Span requests}
1083 @subsubsection Span requests
1084 @cindex Span requests
1086 @cindex @code{\spanrequest}
1089 \spanrequest @var{startstop} @var{type}
1091 @cindex @code{\start}
1092 @cindex @code{\stop}
1094 Define a spanning request. The @var{startstop} parameter is either -1
1095 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
1096 describes what should be started. Supported types are @code{crescendo},
1097 @code{decrescendo}, @code{beam}, @code{slur}. [FIXME: many more] This
1098 is an internal command. Users should use the shorthands which are
1099 defined in the initialization file @file{spanners.ly}.
1101 You can attach a (general) span request to a note using
1103 @lilypond[fragment,verbatim,center]
1104 c'4-\spanrequest \start "slur"
1105 c'4-\spanrequest \stop "slur"
1108 The slur syntax with parentheses is a shorthand for this.
1113 @subsection Ornaments
1122 @subsubsection Articulation
1123 @cindex Articulation
1125 @cindex articulations
1129 A variety of symbols can appear above and below notes to indicate
1130 different characteristics of the performance. These symbols can be
1131 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1132 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1133 forced to appear above or below the note by writing
1134 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1135 respectively. Here is a chart showing symbols above notes, with the
1136 name of the corresponding symbol appearing underneath.
1142 \property Score.LyricSyllable \override #'font-family =
1144 \property Score.LyricSyllable \override #'font-shape = #'upright
1145 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1146 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1147 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1148 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1149 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1150 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1151 c''-\thumb c''-\segno c''-\coda
1153 \context Lyrics \lyrics {
1154 accent__ marcato__ staccatissimo__ fermata
1155 stopped__ staccato__ tenuto__ upbow
1156 downbow__ lheel__ rheel__ ltoe
1157 rtoe__ turn__ open__ flageolet
1158 reverseturn__ trill__ prall__ mordent
1159 prallprall__ prallmordent__ uprall__ downprall
1160 thumb__ segno__ coda
1164 linewidth = 5.875\in;
1173 @subsubsection Text scripts
1174 @cindex Text scripts
1176 In addition, it is possible to place arbitrary strings of text or markup
1177 text (see @ref{Text markup}) above or below notes by using a string
1178 instead of an identifier: @code{c^"text"}. It is possible to use @TeX{}
1179 commands, but this should be avoided because this makes it impossible
1180 for LilyPond to compute the exact length of the string, which may lead
1181 to collisions. Also, @TeX{} commands won't work with direct postscript
1182 output. Fingerings can be placed by simply using digits. All of these
1183 note ornaments appear in the printed output but have no effect on the
1184 MIDI rendering of the music.
1187 @unnumberedsubsubsec Fingerings
1190 To save typing, fingering instructions (digits 0 to 9 are
1191 supported) and single characters shorthands exist for a few
1196 \notes \context Voice {
1197 \property Voice.TextScript \set #'font-family = #'typewriter
1198 \property Voice.TextScript \set #'font-shape = #'upright
1204 c''4-^_"c-\\^{ }" s4
1211 linewidth = 5.875 \in;
1219 @cindex @code{\textscript}
1223 \textscript @var{text} @var{style}
1226 Defines a text to be printed over or under a note. @var{style} is a
1227 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1228 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1230 You can attach a general textscript request using this syntax:
1235 c4-\textscript "6" "finger"
1236 c4-\textscript "foo" "normal"
1241 This is equivalent to @code{c4-6 c4-"foo"}.
1243 @cindex @code{\script}
1252 Prints a symbol above or below a note. The argument is a string which
1253 points into the script-alias table defined in @file{scm/script.scm}.
1254 Usually the @code{\script} keyword is not used directly. Various
1255 helpful identifier definitions appear in @file{script.ly}.
1257 For information on how to add scripts, consult @file{scm/script.scm}.
1264 @subsection Grace notes
1273 @cindex @code{\grace}
1276 @cindex @code{graceAlignPosition}
1279 \grace @var{musicexpr}
1282 A grace note expression has duration 0; the next real note is
1283 assumed to be the main note.
1285 You cannot have the grace note after the main note, in terms of
1286 duration, and main notes, but you can typeset the grace notes to the
1287 right of the main note using the property
1288 @code{graceAlignPosition}.
1289 @cindex @code{flagStyle}
1291 When grace music is interpreted, a score-within-a-score is set up:
1292 @var{musicexpr} has its own time bookkeeping, and you could (for
1293 example) have a separate time signature within grace notes. While in
1294 this score-within-a-score, you can create notes, beams, slurs, etc.
1295 Unbeamed eighth notes and shorter by default have a slash through the
1296 stem. This behavior can be controlled with the
1297 @code{flagStyle} property.
1300 @lilypond[fragment,verbatim]
1302 \grace c8 c4 \grace { [c16 c16] } c4
1303 \grace { \property Grace.flagStyle = "" c16 } c4
1310 At present, nesting @code{\grace} notes is not supported. The following
1311 may cause run-time errors:
1313 @code{\grace @{ \grace c32 c16 @} c4}
1315 Since the meaning of such a construct is unclear, we don't consider
1316 this a loss. Similarly, juxtaposing two @code{\grace} sections is
1317 syntactically valid, but makes no sense and may cause runtime errors.
1319 Ending a staff or score with grace notes may also generate a run-time
1320 error, since there will be no main note to attach the grace notes to.
1322 The present implementation is not robust and generally kludgy. We expect
1323 it to change after LilyPond 1.4. Syntax changes might also be
1336 * Crescendo and Decrescendo::
1345 @subsubsection Glissando
1348 @cindex @code{\glissando}
1350 A glissando line can be requested by attaching a @code{\glissando} to a
1354 @lilypond[fragment,relative,verbatim]
1359 Printing of an additional text (such as @emph{gliss.}) must be done
1366 @subsubsection Dynamics
1379 @cindex @code{\ffff}
1393 Dynamic marks are specified by using an identifier after a note:
1394 @code{c4-\ff}. The available dynamic marks are:
1395 @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f},
1396 @code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf},
1397 @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1399 @c . {Crescendo and Decrescendo}
1400 @node Crescendo and Decrescendo
1401 @subsubsection Crescendo and Decrescendo
1403 @cindex Crescendo and Decrescendo
1407 @cindex @code{\decr}
1408 @cindex @code{\rced}
1415 A crescendo mark is started with @code{\cr} and terminated with
1416 @code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
1417 started with @code{\decr} and terminated with @code{\rced}. There are
1418 also shorthands for these marks. A crescendo can be started with
1419 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1420 can be terminated with @code{\!}. Note that @code{\!} must go before
1421 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1422 after the last note. Because these marks are bound to notes, if you
1423 want to get several marks during one note, you must use spacer notes.
1425 @lilypond[fragment,verbatim,center]
1426 c'' \< \! c'' d'' \decr e'' \rced
1427 < f''1 { s4 \< \! s2 \> \! s4 } >
1430 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1431 is an example how to do it:
1433 @lilypond[fragment,relative,verbatim]
1435 \property Voice.crescendoText = "cresc."
1436 \property Voice.crescendoSpanner = #'dashed-line
1445 @subsubsection Bar lines
1449 @cindex measure lines
1456 This is a short-cut for doing
1458 \property Score.whichBar = @var{bartype}
1461 You are encouraged to use @code{\repeat} for repetitions. See
1462 @ref{Repeats}, and the documentation of @code{whichBar} in
1463 @ref{(lilypond-internals)LilyPond context properties}.
1470 @subsubsection Breath marks
1471 @cindex Breath marks
1477 @subsection Bar check
1481 @cindex @code{barCheckNoSynchronize}
1485 Whenever a bar check is encountered during interpretation, a warning
1486 message is issued if it doesn't fall at a measure boundary. This can
1487 help you find errors in the input. Depending on the value of
1488 @code{barCheckNoSynchronize}, the beginning of the measure will be
1489 relocated, so this can also be used to shorten measures.
1491 A bar check is entered using the bar symbol, @code{|}
1502 @section Piano music
1504 * Automatic staff changes::
1505 * Manual staff switches::
1512 @c . {Automatic staff changes}
1513 @node Automatic staff changes
1514 @subsection Automatic staff changes
1515 @cindex Automatic staff changes
1519 @node Manual staff switches
1520 @subsection Manual staff switches
1522 @cindex manual staff switches
1523 @cindex staff switch, manual
1525 @cindex @code{\translator}
1527 \translator @var{contexttype} = @var{name}
1530 A music expression indicating that the context which is a direct
1531 child of the a context of type @var{contexttype} should be shifted to
1532 a context of type @var{contexttype} and the specified name.
1534 Usually this is used to switch staffs in Piano music, e.g.
1537 \translator Staff = top @var{Music}
1551 @subsection Arpeggio
1554 @cindex broken arpeggio
1555 @cindex @code{\arpeggio}
1557 You can specify an arpeggio sign on a chord by attaching an
1558 @code{\arpeggio} to a note of the chord.
1562 @lilypond[fragment,relative,verbatim]
1563 \context Voice <c'\arpeggio e g c>
1567 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1568 to the chords in both staffs, and set
1569 @code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
1573 @lilypond[fragment,relative,verbatim]
1574 \context PianoStaff <
1575 \property PianoStaff.connectArpeggios = ##t
1576 \context Voice = one { <c''\arpeggio e g c> }
1577 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1584 @c . {Follow Thread}
1586 @subsection Follow Thread
1587 @cindex follow thread
1588 @cindex staff switching
1591 [todo: different name, eg. voice line ? ]
1593 @cindex @code{followThread}
1595 Whenever a voice switches to another staff a line connecting the notes
1596 can be printed automatically. This is enabled if the property
1597 @code{PianoStaff.followThread} is set to true:
1600 @lilypond[fragment,relative,verbatim]
1601 \context PianoStaff <
1602 \property PianoStaff.followThread = ##t
1603 \context Staff \context Voice {
1605 \translator Staff=two
1608 \context Staff=two {\clef bass; \skip 1*2;}
1622 * Automatic syllable durations::
1627 @subsection Lyrics mode
1631 @cindex @code{\lyrics}
1633 Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
1634 rules that make it easy to include punctuation and diacritical marks in
1635 words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
1636 format or a standard encoding without needing quotes. The precise
1637 definition of this mode is ludicrous, and this will remain so until the
1638 authors of LilyPond acquire a deeper understanding of character
1639 encoding, or someone else steps up to fix this.
1641 A word in Lyrics mode begins with: an alphabetic character, @code{_},
1642 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
1643 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
1644 any 8-bit character with ASCII code over 127, or a two-character
1645 combination of a backslash followed by one of @code{`}, @code{'},
1646 @code{"}, or @code{^}.
1648 Subsequent characters of a word can be any character that is not a digit
1649 and not white space. One important consequence of this is that a word
1650 can end with `@code{@}}', which may be confusing. However, LilyPond will
1651 issue a warning. Any @code{_} character which appears in an unquoted
1652 word is converted to a space. This provides a mechanism for introducing
1653 spaces into words without using quotes. Quoted words can also be used
1654 in Lyrics mode to specify words that cannot be written with the above
1655 rules. Here are some examples. Not all of these words are printable by
1660 2B_||_!2B % not a word because it starts with a digit
1661 ``Hello'' % not a word because it starts with `
1662 _ _ _ _ % 4 words, each one a space
1665 Since combinations of numbers and dots are used for indicating
1666 durations, you can not enter real numbers in this mode.
1668 @cindex lyrics expressions
1670 Syllables are entered like notes, with pitches replaced by text. For
1671 example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
1672 with quarter note duration. Note that the hyphen has no special
1673 meaning for lyrics, and does not introduce special symbols. See
1674 section @ref{Lexical modes} for a description of what is interpreted as
1677 Spaces can be introduced into a lyric either by using quotes
1678 (@code{"}) or by using an underscore without quotes: @code{He_could4
1679 not4}. All unquoted underscores are converted to spaces. Printing
1680 lyrics is discussed in the next section.
1683 @c . {Printing lyrics}
1684 @node Printing lyrics
1685 @subsection Printing lyrics
1689 Lyric syllables must be interpreted within a @code{Lyrics} context for
1690 printing them. Here is a full example:
1696 \notes \transpose c'' {
1698 e f g2 | e4 f g2 \bar "|.";
1700 \context Lyrics \lyrics {
1701 Va-4 der Ja- cob Va- der Ja- cob
1702 Slaapt gij nog?2 Slaapt4 gij nog?2
1714 @cindex lyric extender
1716 You may want a continuous line after the syllables to show melismata.
1717 To achieve this effect, add a @code{__} lyric as a separate word
1718 after the lyric to be extended. This will create an extender, a line
1719 that extends over the entire duration of the lyric. This line will
1720 run all the way to the start of the next lyric, so you may want to
1721 shorten it by using a blank lyric (using @code{_}).
1728 \notes \relative c'' {
1729 a4 () b () c () d | c () d () b () a | c () d () b () a
1731 \context Lyrics \lyrics {
1732 foo1 __ | bar2. __ _4 | baz1 __
1740 @cindex Lyric hyphen
1742 If you want to have hyphens centered between syllables (rather than
1743 attached to the end of the first syllable) you can use the special
1744 `@code{-}@code{-}' lyric as a separate word between syllables. This
1745 will result in a hyphen which length varies depending on the space
1746 between syllables, and which will be centered between the syllables.
1754 \notes \transpose c'' {
1756 e f g2 | e4 f g2 \bar "|.";
1758 \context Lyrics \lyrics {
1759 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1760 Slaapt gij nog?2 | Slaapt4 gij nog?2
1769 @c . {Automatic syllable durations}
1770 @node Automatic syllable durations
1771 @subsection Automatic syllable durations
1772 @cindex Automatic syllable durations
1775 [explain automatic phrasing]
1776 @cindex automatic lyric durations
1777 @cindex @code{\addlyrics}
1779 If you have lyrics that are set to a melody, you can import the rhythm
1780 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1783 \addlyrics @var{musicexpr1 musicexpr2}
1786 This means that both @var{musicexpr1} and @var{musicexpr2} are
1787 interpreted, but that every non-command atomic music expression
1788 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1789 of @var{musicexpr1}.
1790 @cindex @code{automaticMelismata}
1792 If the property @code{automaticMelismata} is set in the
1793 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1797 @lilypond[verbatim,fragment]
1800 \property Voice.automaticMelismata = ##t
1801 c8 () cis d8. e16 f2
1803 \context Lyrics \lyrics {
1808 You should use a single rhythm melody, and single rhythm lyrics (a
1809 constant duration is the obvious choice). If you do not, you will get
1810 undesired effects when using multiple stanzas:
1813 @lilypond[verbatim,fragment]
1816 c8 () cis d8. e16 f2
1818 \context Lyrics \lyrics
1825 It is valid (but probably not very useful) to use notes instead of
1826 lyrics for @var{musicexpr2}.
1835 [chords vs. simultaneous music]
1839 * Entering named chords::
1840 * Printing named chords::
1845 @subsection Chords mode
1848 Chord mode is introduced by the keyword
1849 @code{\chords}. It is similar to Note mode, but
1850 words are also looked up in a chord modifier table (containing
1851 @code{maj}, @code{dim}, etc).
1853 Since combinations of numbers and dots are used for indicating
1854 durations, you can not enter real numbers in this mode. Dashes
1855 and carets are used to indicate chord additions and subtractions,
1856 so scripts can not be entered in Chord mode.
1858 @c . {Entering named chords}
1859 @node Entering named chords
1860 @subsection Entering named chords
1861 @cindex Chords names
1863 Chord names are a way to generate simultaneous music expressions that
1864 correspond with traditional chord names. It can only be used in
1865 Chord mode (see section @ref{Lexical modes}).
1869 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1872 @var{tonic} should be the tonic note of the chord, and @var{duration}
1873 is the chord duration in the usual notation. There are two kinds of
1874 modifiers. One type is @emph{chord additions}, which are obtained by
1875 listing intervals separated by dots. An interval is written by its
1876 number with an optional @code{+} or @code{-} to indicate raising or
1877 lowering by half a step. Chord additions has two effects: It adds
1878 the specified interval and all lower odd numbered intervals to the
1879 chord, and it may lower or raise the specified interval. Intervals
1880 must be separated by a dot (@code{.}).
1883 Throughout these examples, chords have been shifted around the staff
1884 using @code{\transpose}.
1889 @lilypond[fragment,verbatim]
1893 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1905 The second type of modifier that may appear after the @code{:} is a
1906 named modifier. Named modifiers are listed in the file
1907 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
1908 @code{min} which lower the 3rd half a step, `@code{aug}' which
1909 raises the 5th, `@code{dim}' which lowers the 5th,
1910 `@code{maj}' which adds a raised 7th, and `@code{sus}'
1911 which replaces the 5th with a 4th.
1915 @lilypond[fragment,verbatim]
1918 c1:m c:min7 c:maj c:aug c:dim c:sus
1926 Chord subtractions are used to eliminate notes from a chord. The
1927 notes to be subtracted are listed after a @code{^} character,
1930 @lilypond[fragment,verbatim,center]
1939 Chord inversions can be specified by appending `@code{/}' and
1940 the name of a single note to a chord. This has the effect of
1941 lowering the specified note by an octave so it becomes the lowest
1942 note in the chord. If the specified note is not in the chord, a
1943 warning will be printed.
1945 @lilypond[fragment,verbatim,center]
1955 Bass notes can be added by `@code{/+}' and
1956 the name of a single note to a chord. This has the effect of
1957 adding the specified note to the chord, lowered by an octave,
1958 so it becomes the lowest note in the chord.
1960 @lilypond[fragment,verbatim,center]
1969 The most interesting application is printing chord names, which is
1970 explained in the next subsection.
1972 You should not combine @code{\relative} with named chords. [FIXME]
1974 @c . {Printing named chords}
1975 @node Printing named chords
1976 @subsection Printing named chords
1982 @cindex printing chord names
1985 @cindex @code{ChordNames}
1986 @cindex @code{ChordNameVoice}
1988 For displaying printed chord names, use the @code{ChordNames} and
1989 @code{ChordNameVoice} contexts. The chords may be entered either using
1990 the notation described above, or directly using simultaneous music.
1995 \chords {a1 b c} <d f g> <e g b>
1999 \context ChordNamesVoice \scheme
2000 \context Staff \transpose c'' \scheme
2002 \paper { linewidth = -1.; }
2007 You can make the chord changes stand out more by setting property
2008 @code{ChordNames.chordChanges} to true. This will only display chord
2009 names when there's a change in the chords scheme, but always display the
2010 chord name after a line break:
2016 c1:m \break c:m c:m c:m d
2021 \context ChordNames \scheme
2022 \context Staff \transpose c'' \scheme
2025 linewidth = 40 * \staffspace;
2037 LilyPond examines chords specified as lists of notes to determine a
2038 name to give the chord. LilyPond will not try to
2039 identify chord inversions or added base, which may result in strange
2040 chord names when chords are entered as a list of pitches:
2043 @lilypond[verbatim,center]
2052 \context ChordNamesVoice \scheme
2053 \context Staff \scheme
2055 \paper { linewidth = -1.; }
2060 To specify chord inversions, append @code{/<notename>}. To specify an
2061 added bass note, append @code{/+<notename}:
2064 @lilypond[verbatim,center]
2071 \context ChordNames \scheme
2072 \context Staff \transpose c'' \scheme
2074 \paper { linewidth = -1.; }
2079 The chord names that LilyPond should print are fully customizable. The
2080 code to print chord names is written in Scheme. It can be found in
2081 @file{scm/chord-name.scm}. Chord names are based on Banter style
2082 naming, which is unambiguous and has a logical structure. Typical
2083 American style chord names are implemented as a variation on Banter
2084 names, they can be selected by setting property @code{ChordName.style}
2089 \include "english.ly"
2094 df:m5- % Diminished triad
2095 c:5^3 % Root-fifth chord
2096 c:4^3 % Suspended fourth triad
2097 c:5+ % Augmented triad
2099 c:m5-.7- % Diminished seventh
2100 c:7+ % Major seventh
2101 c:7.4^3 % Dominant seventh suspended fourth
2102 c:5+.7 % Augmented dominant seventh
2103 c:m5-.7 % "Half" diminished seventh
2104 c:5-.7 % Dominant seventh flat fifth
2105 c:5-.7+ % Major seventh flat fifth
2106 c:m7+ % Minor-major seventh
2107 c:m7 % Minor seventh
2108 c:7 % Dominant seventh
2111 c:9^7 % Major triad w/added ninth
2112 c:6.9^7 % Six/Nine chord
2113 c:9 % Dominant ninth
2114 c:7+.9 % Major ninth
2115 c:m7.9 % Minor ninth
2120 \context ChordNames \scheme
2121 \context Staff \transpose c'' \scheme
2126 ChordName \override #'word-space = #1
2127 ChordName \override #'style = #'american
2134 Similarly, Jazz style chord names are implemented as a variation on
2135 American style names:
2141 c:6 % 6 = major triad with added sixth
2142 c:maj % triangle = maj
2147 c:m % m = minor triad
2148 c:m.6 % m6 = minor triad with added sixth
2149 c:m.7+ % m triangle = minor major seventh chord
2157 c:7.5+ % +7 = augmented dominant
2158 c:7.5- % 7b5 = hard diminished dominant
2165 c:13.9-^11 % 7(b9,13)
2166 c:13.9+^11 % 7(#9,13)
2168 c:13-.9-^11 % 7(b9,b13)
2169 c:13-.9+^11 % 7(#9,b13)
2171 % half diminished chords
2172 c:m5-.7 % slashed o = m7b5
2173 c:9.3-.5- % o/7(pure 9)
2176 c:m5-.7- % o = diminished seventh chord
2181 \context ChordNames \scheme
2182 \context Staff \transpose c'' \scheme
2187 ChordName \override #'word-space = #1
2188 ChordName \override #'style = #'jazz
2196 @section Writing parts
2201 * Instrument names::
2203 * Multi measure rests::
2212 tranposing midi property.
2218 @c . {Rehearsal marks}
2219 @node Rehearsal marks
2220 @subsection Rehearsal marks
2221 @cindex Rehearsal marks
2223 @cindex @code{\mark}
2224 @cindex @code{Mark_engraver}
2227 \mark @var{unsigned};
2232 With this command, you can print a rehearsal mark above the system. You
2233 can provide a number, a string or a markup text as argument. If there is
2234 no argument, the property @code{rehearsalMark} is used and automatically
2237 @lilypond[fragment,verbatim]
2243 c1 \mark #'(music "scripts-segno") ;
2248 @node Instrument names
2249 @subsection Instrument names
2251 You can specify an instrument name for a staff by setting
2252 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2253 before the start of the staff. For the first start, @code{instrument} is
2254 used, for the next ones @code{instr} is used.
2258 \property Staff.instrument = "instr " { c''4 } }
2259 \paper { linewidth = -1.;
2260 \translator { \StaffContext
2261 \consists "Instrument_name_engraver"; } } }
2264 This requires that you add the @code{Instrument_name_engraver} to the
2269 @subsection Transpose
2271 @cindex transposition of pitches
2272 @cindex @code{\transpose}
2274 A music expression can be transposed with @code{\transpose}. The syntax
2277 \transpose @var{pitch} @var{musicexpr}
2280 This means that middle C in @var{musicexpr} is transposed to
2283 @code{\transpose} distinguishes between enharmonic pitches: both
2284 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2285 a tone. The first version will print sharps and the second version
2289 @lilypond[fragment,verbatim]
2292 { \key e \major; c d e f }
2294 \transpose des'' { \key e \major; c d e f }
2295 \transpose cis'' { \key e \major; c d e f }
2301 If you want to use both @code{\transpose} and @code{\relative}, then
2302 you must use @code{\transpose} first. @code{\relative} will have no
2303 effect music that appears inside a @code{\transpose}.
2306 @c . {Multi measure rests}
2307 @node Multi measure rests
2308 @subsection Multi measure rests
2309 @cindex Multi measure rests
2313 Multi measure rests are entered using `@code{R}'. It is specifically
2314 meant for entering parts: the rest can expand to fill a score with
2315 rests, or it can be printed as a single multimeasure rest This expansion
2316 is controlled by the property @code{Score.skipBars}. If this is set to true,
2317 Lily will not expand empty measures, and the appropriate number is added
2320 @lilypond[fragment,verbatim]
2321 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2324 Currently, there is no way to condense multiple rests into a single
2327 @cindex condensing rests
2335 A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a
2336 staff context symbol that appears at the end of a staff line. It
2337 anticipates the pitch of the first note(s) of the following line and
2338 thus helps the player or singer to manage line breaks during
2339 performance, thus enhancing readability of a score.
2344 \notes { c'1 d' e' d' \break c' d' e' d' }
2348 \consists Custos_engraver;
2349 Custos \override #'style = #'mensural;
2356 Custodes were frequently used in music notation until the 16th century.
2357 There were different appearences for different notation styles.
2358 Nowadays, they have survived only in special forms of musical notation
2359 such as via the editio vaticana dating back to the beginning of the 20th
2362 For typesetting custodes, just put a @code{Custos_engraver} into the
2363 @code{StaffContext} when declaring the @code{\paper} block. In this
2364 block, you can also globally control the appearance of the custos symbol
2365 by setting the custos @code{style} property. Currently supported styles
2366 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2373 \consists Custos_engraver;
2374 Custos \override #'style = #'mensural;
2379 The property can also be set locally, for example in a @code{\notes}
2384 \property Staff.Custos \override #'style = #'vaticana
2385 c'1 d' e' d' \break c' d' e' d'
2391 @section Page layout
2405 @subsection Paper block
2408 The most important output definition is the @code{\paper} block, for
2409 music notation. The syntax is
2412 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2415 where each of the items is one of
2418 @item An assignment. The assignment must be terminated by a
2421 @item A context definition. See section @ref{Context definitions} for
2422 more information on context definitions.
2424 @item \stylesheet declaration. Its syntax is
2426 \stylesheet @var{alist}
2429 See @file{font.scm} for details of @var{alist}.
2432 @c . {Paper variables}
2433 @node Paper variables
2434 @subsection Paper variables
2435 @cindex Paper variables
2437 The paper block has some variables you may want to use or change:
2440 @cindex @code{indent}
2442 The indentation of the first line of music.
2443 @cindex @code{staffspace}
2445 @item @code{staffspace}
2446 The distance between two staff lines, calculated from the center
2447 of the lines. You should use either this or @code{stafflinethickness}
2448 as a unit for distances you modify.
2450 @cindex @code{linewidth}
2451 @item @code{linewidth}
2452 Sets the width of the lines.
2454 If set to a negative value, a single
2455 unjustified line is produced.
2457 @cindex @code{textheight}
2459 @item @code{textheight}
2460 Sets the total height of the music on each page. Only used by
2462 @cindex @code{interscoreline}
2464 @item @code{interscoreline}
2465 Sets the spacing between the score lines. Defaults to 16 pt.
2466 @cindex @code{interscorelinefill}
2468 @item @code{interscorelinefill}
2469 If set to a positive number, the distance between the score
2470 lines will stretch in order to fill the full page. In that
2471 case @code{interscoreline} specifies the minimum spacing.
2473 @cindex @code{stafflinethickness}
2475 @item @code{stafflinethickness}
2476 Determines the thickness of staff lines, and also acts as a scaling
2477 parameter for other line thicknesses.
2484 @subsection Font size
2487 The Feta font provides musical symbols at six different sizes. These
2488 fonts are 11 point, 13 point, 16 point, 20 point,
2489 23 point, and 26 point. The point size of a font is the
2490 height of the five lines in a staff when displayed in the font.
2492 Definitions for these sizes are the files @file{paperSZ.ly}, where
2493 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2494 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2495 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2496 @code{paperTwentysix} are defined respectively. The default
2497 @code{\paper} block is also set.
2499 The font definitions are generated using a Scheme function. For more
2500 details, see the file @file{font.scm}.
2506 @subsection Paper size
2511 @cindex @code{papersize}
2513 To change the paper size, you must first set the
2514 @code{papersize} variable at top level. Set it to
2515 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2516 specification, you must set the font as described above. If you want
2517 the default font, then use the 20 point font. The new paper size will
2518 not take effect if the font is not loaded and selected afterwards.
2522 \include "paper16.ly"
2526 \paper @{ \paperSixteen @}
2530 The file "paper16.ly" will now include a file named @file{a4.ly}, which
2531 will set the paper variables @code{hsize} and @code{vsize} (used by
2542 @subsection Line break
2545 @cindex breaking lines
2547 Line breaks are normally computed automatically. They are chosen such
2548 that the resulting spacing has low variation, and looks neither cramped
2551 Occasionally you might want to override the automatic breaks; you can do
2552 this by specifying @code{\break}. This will force a line break at this
2553 point. Do remember that line breaks can only occur at places where there
2554 are barlines. If you want to have a line break where there is no
2555 barline, you can force a barline by entering @code{\bar "";}.
2557 Similarly, @code{\noBreak} forbids a line break at a certain point.
2559 @cindex @code{\penalty}
2561 The @code{\break} and @code{\noBreak} commands are defined in terms of
2562 the penalty command:
2564 \penalty @var{int} @code{;}
2567 This imposes encourages or discourages LilyPond to make a line break
2570 @strong{Warning} do not use @code{\penalty} directly. It is rather
2571 kludgy, and slated for rewriting.
2575 @subsection Page break
2578 @cindex breaking pages
2581 Page breaks are normally computed by @TeX{}, so they are not under direct
2582 control. However, you can insert a commands into the @file{.tex} output to
2583 instruct @TeX{} where to break pages. For more details, see the
2584 example file @file{input/test/between-systems.ly}
2599 * MIDI instrument names::
2605 @subsection MIDI block
2609 The MIDI block is analogous to the paper block, but it is somewhat
2610 simpler. The @code{\midi} block can contain:
2614 @item a @code{\tempo} definition
2615 @item context definitions
2618 Assignments in the @code{\midi} block are not allowed.
2622 @cindex context definition
2624 Context definitions follow precisely the same syntax as within the
2625 \paper block. Translation modules for sound are called performers.
2626 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2629 @c . {MIDI instrument names}
2630 @node MIDI instrument names
2631 @subsection MIDI instrument names
2632 @cindex instrument names
2633 @cindex @code{Staff.midiInstrument}
2634 @cindex @code{Staff.instrument}
2636 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2637 property or, if that property is not set, the @code{Staff.instrument}
2638 property. The instrument name should be chosen from the following list.
2639 If the selected string does not exactly match, then LilyPond uses the
2642 [FIXME: to appendix ]
2646 "acoustic grand" "contrabass" "lead 7 (fifths)"
2647 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2648 "electric grand" "pizzicato strings" "pad 1 (new age)"
2649 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2650 "electric piano 1" "timpani" "pad 3 (polysynth)"
2651 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2652 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2653 "clav" "synthstrings 1" "pad 6 (metallic)"
2654 "celesta" "synthstrings 2" "pad 7 (halo)"
2655 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2656 "music box" "voice oohs" "fx 1 (rain)"
2657 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2658 "marimba" "orchestra hit" "fx 3 (crystal)"
2659 "xylophone" "trumpet" "fx 4 (atmosphere)"
2660 "tubular bells" "trombone" "fx 5 (brightness)"
2661 "dulcimer" "tuba" "fx 6 (goblins)"
2662 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2663 "percussive organ" "french horn" "fx 8 (sci-fi)"
2664 "rock organ" "brass section" "sitar"
2665 "church organ" "synthbrass 1" "banjo"
2666 "reed organ" "synthbrass 2" "shamisen"
2667 "accordion" "soprano sax" "koto"
2668 "harmonica" "alto sax" "kalimba"
2669 "concertina" "tenor sax" "bagpipe"
2670 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2671 "acoustic guitar (steel)" "oboe" "shanai"
2672 "electric guitar (jazz)" "english horn" "tinkle bell"
2673 "electric guitar (clean)" "bassoon" "agogo"
2674 "electric guitar (muted)" "clarinet" "steel drums"
2675 "overdriven guitar" "piccolo" "woodblock"
2676 "distorted guitar" "flute" "taiko drum"
2677 "guitar harmonics" "recorder" "melodic tom"
2678 "acoustic bass" "pan flute" "synth drum"
2679 "electric bass (finger)" "blown bottle" "reverse cymbal"
2680 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2681 "fretless bass" "whistle" "breath noise"
2682 "slap bass 1" "ocarina" "seashore"
2683 "slap bass 2" "lead 1 (square)" "bird tweet"
2684 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2685 "synth bass 2" "lead 3 (calliope)" "helicopter"
2686 "violin" "lead 4 (chiff)" "applause"
2687 "viola" "lead 5 (charang)" "gunshot"
2688 "cello" "lead 6 (voice)"
2699 @cindex beats per minute
2700 @cindex metronome marking
2702 @cindex @code{\tempo}
2704 \tempo @var{duration} = @var{perminute} @code{;}
2707 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
2708 output with 76 quarter notes per minute.
2716 @section Music entry
2727 @subsection Relative
2729 @cindex relative octave specification
2731 Octaves are specified by adding @code{'} and @code{,} to pitch names.
2732 When you copy existing music, it is easy to accidentally put a pitch in
2733 the wrong octave and hard to find such an error. To prevent these
2734 errors, LilyPond features octave entry.
2736 @cindex @code{\relative}
2738 \relative @var{startpitch} @var{musicexpr}
2741 The octave of notes that appear in @var{musicexpr} are calculated as
2742 follows: If no octave changing marks are used, the basic interval
2743 between this and the last note is always taken to be a fourth or less.
2744 The octave changing marks @code{'} and @code{,} can then
2745 be added to raise or lower the pitch by an extra octave. Upon entering
2746 relative mode, an absolute starting pitch must be specified that will
2747 act as the predecessor of the first note of @var{musicexpr}.
2749 This distance is determined without regarding accidentals: a
2750 @code{fisis} following a @code{ceses} will be put above the
2753 Entering scales is straightforward in relative mode.
2755 @lilypond[fragment,verbatim,center]
2757 g a b c d e f g g, g
2761 And octave changing marks are used for intervals greater than a fourth.
2763 @lilypond[fragment,verbatim,center]
2765 c g c f, c' a, e'' }
2768 If the preceding item is a chord, the first note of the chord is used
2769 to determine the first note of the next chord. But other notes
2770 within the second chord are determined by looking at the immediately
2773 @lilypond[fragment,verbatim,center]
2780 @cindex @code{\notes}
2782 The pitch after the @code{\relative} contains a notename. To parse
2783 the pitch as a notename, you have to be in note mode, so there must
2784 be a surrounding @code{\notes} keyword (which is not
2787 The relative conversion will not affect @code{\transpose} or
2788 @code{\relative} sections in its argument. If you want to use
2789 relative within transposed music, you must place an additional
2790 @code{\relative} inside the @code{\transpose}.
2793 @c . {Point and click}
2794 @node Point and click
2795 @subsection Point and click
2804 * Selecting contexts::
2805 * Context definitions::
2806 * Notation Contexts::
2809 @c . {Music expressions}
2810 @node Selecting contexts
2811 @subsection Selecting contexts
2813 @cindex @code{\context}
2814 @cindex context selection
2817 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
2820 Interpret @var{musicexpr} within a context of type @var{contexttype}.
2821 If the context does not exist, it will be created. The new context
2822 can optionally be given a name.
2826 @c . {Context definitions}
2827 @node Context definitions
2828 @subsection Context definitions
2830 @cindex context definition
2831 @cindex translator definition
2832 @cindex engraver hacking
2835 A notation contexts is defined by the following information
2840 @item The LilyPond modules that do the actual conversion of music to
2841 notation. Each module is a so-called
2846 @item How these modules should cooperate, i.e. which ``cooperation
2847 module'' should be used. This cooperation module is a special
2850 @item What other contexts the context can contain,
2852 @item What properties are defined.
2855 A context definition has this syntax:
2859 \translator @code{@{}
2860 @var{translatorinit} @var{translatormodifierlist}
2864 @var{translatorinit} can be an identifier or
2866 \type @var{typename} @code{;}
2868 where @var{typename} is one of
2871 @cindex @code{Engraver_group_engraver}
2872 @item @code{Engraver_group_engraver}
2873 The standard cooperation engraver.
2874 @cindex @code{Score_engraver}
2876 @item @code{Score_engraver}
2877 This is cooperation module that should be in the top level context.
2878 @cindex @code{Grace_engraver_group}
2880 @item @code{Grace_engraver_group}
2881 This is a special cooperation module (resembling
2882 @code{Score_engraver}) that is used to created an embedded
2886 @var{translatormodifierlist} is a list of items where each item is
2890 @item @code{\consists} @var{engravername} @code{;}
2891 Add @var{engravername} to the list of modules in this context.
2892 The order of engravers added with @code{\consists} is
2895 @item @code{\consistsend} @var{engravername} @code{;}
2896 Analogous to @code{\consists}, but makes sure that
2897 @var{engravername} is always added to the end of the list of
2900 Some engraver types need to be at the end of the list; this
2901 insures they are put there, and stay there, if a user adds or
2902 removes engravers. This command is usually not needed for
2905 @item @code{\accepts} @var{contextname} @code{;}
2906 Add @var{contextname} to the list of context this context can
2907 contain. The first listed context is the context to create by
2910 @item @code{\denies}. The opposite of @code{\accepts}. Added for
2911 completeness, but is never used in practice.
2914 @item @code{\remove} @var{engravername} @code{;}
2915 Remove a previously added (with @code{\consists}) engraver.
2917 @item @code{\name} @var{contextname} @code{;}
2918 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2919 the name is not specified, the translator won't do anything.
2921 @item @var{propname} @code{=} @var{value} @code{;}
2922 A property assignment.
2925 In the @code{\paper} block, it is also possible to define translator
2926 identifiers. Like other block identifiers, the identifier can only
2927 be used as the very first item of a translator. In order to define
2928 such an identifier outside of @code{\score}, you must do
2934 foo = \translator @{ @dots{} @}
2941 \translator @{ \foo @dots{} @}
2949 @cindex paper types, engravers, and pre-defined translators
2951 Some pre-defined identifiers can simplify modification of
2952 translators. The pre-defined identifiers are:
2955 @cindex @code{StaffContext}
2956 @item @code{StaffContext}
2957 Default Staff context.
2958 @cindex @code{RhythmicStaffContext}
2960 @item @code{RhythmicStaffContext}
2961 Default RhythmicStaff context.
2962 @cindex @code{VoiceContext}
2964 @item @code{VoiceContext}
2965 Default Voice context.
2966 @cindex @code{ScoreContext}
2968 @item @code{ScoreContext}
2969 Default Score context.
2971 @cindex @code{HaraKiriStaffContext}
2973 @item @code{HaraKiriStaffContext}
2974 Staff context that does not print if it only contains rests.
2975 Useful for orchestral scores.@footnote{Harakiri, also called
2976 Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
2980 Using these pre-defined values, you can remove or add items to the
2989 \remove Some_engraver;
2990 \consists Different_engraver;
3000 @c . {Notation Contexts}
3001 @node Notation Contexts
3002 @subsection Notation Contexts
3004 @cindex notation contexts
3006 Notation contexts are objects that only exist during a run of
3007 LilyPond. During the interpretation phase of LilyPond, the Music
3008 expression contained in a @code{\score} block is interpreted in time
3009 order. This is the order in which humans read, play, and write
3012 A context is an object that holds the reading state of the
3013 expression; it contains information like
3016 @item What notes are playing at this point?
3017 @item What symbols will be printed at this point?
3018 @item In what style will they printed?
3019 @item What is the current key signature, time signature, point within
3023 Contexts are grouped hierarchically: A @code{Voice} context is
3024 contained in a @code{Staff} context (because a staff can contain
3025 multiple voices at any point), a @code{Staff} context is contained in
3026 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
3027 these can all contain multiple staffs).
3029 Contexts associated with sheet music output are called @emph{notation
3030 contexts}, those for sound output are called performance contexts.
3032 Contexts are created either manually or automatically. Initially, the
3033 top level music expression is interpreted by the top level context (the
3034 @code{Score} context). When a atomic music expression (i.e. a note, a
3035 rest, etc.), a nested set of contexts is created that can process these
3036 atomic expressions, as in this example:
3039 \score @{ \notes @{ c4 @} @}
3042 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
3043 context. When the note @code{c4} itself is interpreted, a set of
3044 contexts is needed that will accept notes. The default for this is a
3045 @code{Voice} context, contained in a @code{Staff} context. Creation of
3046 these contexts results in the staff being printed.
3050 You can also create contexts manually, and you probably have to do so
3051 if you want to typeset complicated multiple part material. If a
3052 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
3053 during the interpretation phase, the @var{musicexpr} argument will be
3054 interpreted with a context of type @var{name}. If you specify a name,
3055 the specific context with that name is searched.
3059 If a context of the specified type and name can not be found, a new
3060 one is created. For example,
3066 \notes \relative c'' {
3067 c4 <d4 \context Staff = "another" e4> f
3074 In this example, the @code{c} and @code{d} are printed on the
3075 default staff. For the @code{e}, a context Staff called
3076 @code{another} is specified; since that does not exist, a new
3077 context is created. Within @code{another}, a (default) Voice context
3078 is created for the @code{e4}. When all music referring to a
3079 context is finished, the context is ended as well. So after the
3080 third quarter, @code{another} is removed.
3082 Almost all music expressions inherit their interpretation context
3083 from their parent. In other words, suppose that the syntax for a
3088 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
3091 When the interpretation of this music expression starts, the context
3092 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
3095 Lastly, you may wonder, why this:
3101 \notes \relative c'' @{
3109 doesn't result in this:
3114 \notes \relative c'' {
3121 For the @code{c4}, a default @code{Staff} (with a contained
3122 @code{Voice}) context is created. After the @code{c4} ends, no
3123 music refers to this default staff, so it would be ended, with the
3124 result shown. To prevent this inconvenient behavior, the context to
3125 which the sequential music refers is adjusted during the
3126 interpretation. So after the @code{c4} ends, the context of the
3127 sequential music is also the default @code{Voice} context.
3128 The @code{d4} gets interpreted in the same context
3131 Properties that are set in one context are inherited by all of the
3132 contained contexts. This means that a property valid for the
3133 @code{Voice} context can be set in the @code{Score} context (for
3134 example) and thus take effect in all @code{Voice} contexts.
3136 Properties can be preset within the @code{\translator} block
3137 corresponding to the appropriate context. In this case, the syntax
3141 @var{propname} @code{=} @var{value}
3144 This assignment happens before interpretation starts, so a
3145 @code{\property} expression will override any predefined settings.
3147 The property settings are used during the interpretation phase. They
3148 are read by the LilyPond modules where interpretation contexts are
3149 built of. These modules are called @emph{translators}. Translators for
3150 notation are called @emph{engravers}, and translators for sound are
3151 called @emph{performers}.
3155 @c . {Syntactic details}
3156 @node Syntactic details
3157 @section Syntactic details
3158 @cindex Syntactic details
3162 * Music expressions::
3163 * Manipulating music expressions::
3172 @subsection Top level
3175 This section describes what you may enter at top level.
3178 @unnumberedsubsec Score definition
3179 @cindex score definition
3181 The output is generated combining a music expression with an output
3182 definition. A score block has the following syntax:
3185 \score @{ @var{musicexpr} @var{outputdefs} @}
3188 @var{outputdefs} are zero or more output definitions. If no output
3189 definition is supplied, the default @code{\paper} block will be added.
3193 @subsubsection Score
3197 @subsubsection Paper
3205 @subsubsection Header
3207 @cindex @code{\header}
3212 \header @{ @var{key1} = @var{val1};
3213 @cindex @code{ly2dvi}
3214 @var{key2} = @var{val2}; @dots{} @}
3218 A header describes the file's contents. It can also appear in a
3219 @code{\score} block. Tools like @code{ly2dvi} can use this
3220 information for generating titles. Key values that are used by
3221 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
3222 metre, arranger, piece and tagline.
3224 It is customary to put the @code{\header} at the top of the file.
3226 @subsubsection Default output
3228 A @code{\midi} or @code{\paper} block at top-level sets the default
3230 paper block for all scores that lack an explicit paper block.
3234 @subsection Identifiers
3237 All of the information in a LilyPond input file, is represented as a
3238 Scheme value. In addition to normal Scheme data types (such as pair,
3239 number, boolean, etc.), LilyPond has a number of specialized data types,
3246 @item Translator_def
3250 @item Music_output_def
3251 @item Moment (rational number)
3254 LilyPond also includes some transient object types. Objects of these
3255 types are built during a LilyPond run, and do not `exist' per se within
3256 your input file. These objects are created as a result of your input
3257 file, so you can include commands in the input to manipulate them,
3258 during a lilypond run.
3261 @item Grob: short for Graphical object. See @ref{Grobs}.
3262 @item Molecule: device-independent page output object,
3263 including dimensions. Produced by some Grob functions
3265 @item Translator: object that produces audio objects or Grobs. This is
3266 not yet user accessible.
3267 @item Font_metric: object representing a font. (See @ref{Font metrics})
3272 @node Music expressions
3273 @subsection Music expressions
3275 @cindex music expressions
3277 Music in LilyPond is entered as a music expression. Notes, rests, lyric
3278 syllables are music expressions, and you can combine music expressions
3279 to form new ones, for example by enclosing a list of expressions in
3280 @code{\sequential @{ @}} or @code{< >}. In this example, a compound
3281 expression is formed out of the quarter note @code{c} and a quarter note
3285 \sequential @{ c4 d4 @}
3288 @cindex Sequential music
3289 @cindex @code{\sequential}
3290 @cindex sequential music
3293 @cindex Simultaneous music
3294 @cindex @code{\simultaneous}
3296 The two basic compound music expressions are simultaneous and
3300 \sequential @code{@{} @var{musicexprlist} @code{@}}
3301 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
3303 For both, there is a shorthand:
3305 @code{@{} @var{musicexprlist} @code{@}}
3309 @code{<} @var{musicexprlist} @code{>}
3311 for simultaneous music.
3312 Other compound music expressions include
3315 \transpose @var{pitch} @var{expr}
3316 \apply @var{func} @var{expr}
3317 \context @var{type} = @var{id} @var{expr}
3318 \times @var{fraction} @var{expr}
3321 In principle, the way in which you nest sequential and simultaneous to
3322 produce music is not relevant. In the following example, three chords
3323 are expressed in two different ways:
3325 @lilypond[fragment,verbatim,center]
3326 \notes \context Voice {
3327 <a c'> <b d' > <c' e'>
3328 < { a b c' } { c' d' e' } >
3332 However, in some cases, LilyPond will also try to choose contexts, and
3333 use the structure of the music expression to do so. This can have
3334 undesired effects: for example, LilyPond will create a separate staff
3335 for each note if you start a @code{\score} with a chord:
3336 @lilypond[verbatim,center]
3344 The solution is to explicitly instantiate the context you desire.
3345 In this case this is typically a Voice context
3346 @lilypond[verbatim,center]
3348 \notes\context Voice <c''4 e''>
3354 If you use @code{\context Staff} you will get separate stems for each
3355 note head, leading to collisions, so don't use that.
3359 @c . {Manipulating music expressions}
3360 @node Manipulating music expressions
3361 @subsection Manipulating music expressions
3363 The @code{\apply} mechanism gives you access to the internal
3364 representation of music. You can write Scheme-functions that operate
3365 directly on it. The syntax is
3367 \apply #@var{func} @var{music}
3369 This means that @var{func} is applied to @var{music}. The function
3370 @var{func} should return a music expression.
3372 This example replaces the text string of a script. It also shows a dump
3373 of the music it processes, which is useful if you want to know more
3374 about how music is stored.
3376 #(define (testfunc x)
3377 (if (equal? (ly-get-mus-property x 'text) "foo")
3378 (ly-set-mus-property x 'text "bar"))
3380 (ly-set-mus-property x 'elements
3381 (map testfunc (ly-get-mus-property x 'elements)))
3386 \apply #testfunc { c4_"foo" }
3390 For more information on what is possible, see the @ref{Tricks} and the
3391 automatically generated documentation.
3393 As always: directly accessing internal representations is dangerous: the
3394 implementation is subject to changes, so you should not use this if
3400 @subsection Assignments
3403 Identifiers allow objects to be assigned to names during the parse
3404 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
3405 and to refer to an identifier, you preceed its name with a backslash:
3406 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
3407 the input-types listed above. Identifier assignments can appear at top
3408 level in the LilyPond file, but also in @code{\paper} blocks.
3410 Semicolons are forbidden after top level assignments, but mandatory in
3411 other places. The rules about semicolons and assignments are very
3412 confusing, but when LilyPond input evolves more towards Scheme, we hope
3413 that this problem will grow smaller.
3415 An identifier can be created with any string for its name, but you will
3416 only be able to refer to identifiers whose names begin with a letter,
3417 being entirely alphabetical. It is impossible to refer to an identifier
3418 whose name is the same as the name of a keyword.
3420 The right hand side of an identifier assignment is parsed completely
3421 before the assignment is done, so it is allowed to redefine an
3422 identifier in terms of its old value, e.g.
3428 When an identifier is referenced, the information it points to is
3429 copied. For this reason, an identifier reference must always be the
3430 first item in a block.
3434 \paperIdent % wrong and invalid
3438 \paperIdent % correct
3442 @c . {Lexical details}
3443 @node Lexical details
3444 @subsection Lexical details
3445 @cindex Lexical details
3450 @subsubsection Comments
3456 A one line comment is introduced by a @code{%} character.
3457 Block comments are started by @code{%@{} and ended by @code{%@}}.
3458 They cannot be nested.
3460 @c . {Direct Scheme}
3461 @subsubsection Direct Scheme
3464 @cindex Scheme, in-line code
3467 LilyPond contains a Scheme interpreter (the GUILE library) for
3468 internal use. In some places Scheme expressions also form valid syntax:
3469 whereever it is allowed,
3473 evaluates the specified Scheme code. If this is used at toplevel, then
3474 the result is discarded. Example:
3476 \property Staff.TestObject \override #'foobar = #(+ 1 2)
3479 @code{\override} expects two Scheme expressions, so there are two Scheme
3480 expressions. The first one is a symbol (@code{foobar}), the second one
3481 an integer (namely, 3).
3483 Scheme is a full-blown programming language, and a full discussion is
3484 outside the scope of this document. Interested readers are referred to
3485 the website @uref{http://www.schemers.org/} for more information on
3490 @subsubsection Keywords
3494 Keywords start with a backslash, followed by a number of lower case
3495 alphabetic characters. These are all the keywords.
3498 apply arpeggio autochange spanrequest commandspanrequest
3499 simultaneous sequential accepts alternative bar breathe
3500 char chordmodifiers chords clef cm consists consistsend
3501 context denies duration dynamicscript elementdescriptions
3502 font grace header in lyrics key mark pitch
3503 time times midi mm name pitchnames notes outputproperty
3504 override set revert partial paper penalty property pt
3505 relative remove repeat addlyrics partcombine score
3506 script stylesheet skip textscript tempo translator
3511 @subsubsection Integers
3519 Formed from an optional minus sign followed by digits. Arithmetic
3520 operations cannot be done with integers, and integers cannot be mixed
3524 @subsubsection Reals
3525 @cindex real numbers
3531 Formed from an optional minus sign and a sequence of digits followed
3532 by a @emph{required} decimal point and an optional exponent such as
3533 @code{-1.2e3}. Reals can be built up using the usual operations:
3534 `@code{+}', `@code{-}', `@code{*}', and
3535 `@code{/}', with parentheses for grouping.
3543 A real constant can be followed by one of the dimension keywords:
3544 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
3545 points, inches and centimeters, respectively. This converts the number
3546 to a real that is the internal representation of dimensions.
3550 @subsubsection Strings
3554 Begins and ends with the @code{"} character. To include a @code{"}
3555 character in a string write @code{\"}. Various other backslash
3556 sequences have special interpretations as in the C language. A string
3557 that contains no spaces can be written without the quotes. See
3558 @ref{Lexical modes} for details on unquoted strings; their
3559 interpretation varies depending on the situation. Strings can be
3560 concatenated with the @code{+} operator.
3562 The tokenizer accepts the following commands. They have no grammatical
3563 function, hence they can appear anywhere in the input.
3567 @subsubsection Main input
3570 @cindex @code{\maininput}
3572 The @code{\maininput} command is used in init files to signal that the
3573 user file must be read. This command cannot be used in a user file.
3575 @c . {File inclusion}
3576 @subsubsection Main input
3579 @subsubsection File inclusion
3580 @cindex @code{\include}
3582 \include @var{filename}
3585 Include @var{filename}. The argument @var{filename} may be a quoted string (an
3586 unquoted string will not work here!) or a string identifier. The full
3587 filename including the @file{.ly} extension must be given,
3589 @subsubsection Version information
3590 @cindex @code{\version}
3592 \version @var{string} ;
3595 Specify the version of LilyPond that a file was written for. The
3596 argument is a version string in quotes, for example @code{"1.2.0"}.
3597 This is used to detect invalid input, and to aid
3598 @code{convert-ly} a tool that automatically upgrades input files. See
3599 See @ref{convert-ly} for more information on @code{convert-ly}.
3605 @subsubsection Defining pitch names
3606 @cindex Lexical modes
3607 @cindex definining pitch names
3608 @cindex pitch names, definining
3610 @cindex chord modifier names
3612 A @code{\paper} block at top level sets the default paper block. A
3613 @code{\midi} block at top level works similarly.
3616 @subsubsection Assignments
3620 Identifier assignments may appear at top level. @ref{Assignments}
3624 @c . {Direct scheme}
3625 @subsubsection Direct scheme
3626 @cindex Direct scheme
3628 Scheme statements maybe issued to produce interesting side-effects.
3631 @c . {Lexical modes}
3633 @subsection Lexical modes
3634 @cindex Lexical modes
3637 @cindex @code{\notes}
3638 @cindex @code{\chords}
3639 @cindex @code{\lyrics}
3641 To simplify entering notes, lyrics, and chords, LilyPond has three
3642 special input modes on top of the default mode: note, lyrics and chords
3643 mode. These input modes change the way that normal, unquoted words are
3644 interpreted: for example, the word @code{cis} may be interpreted as a
3645 C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
3648 A mode switch is entered as a compound music expressions
3650 @code{\notes} @var{musicexpr}
3651 @code{\chords} @var{musicexpr}
3652 @code{\lyrics} @var{musicexpr}.
3655 In each of these cases, these expressions do not add anything to the
3656 meaning of their arguments. They are just a way to indicate that the
3657 arguments should be parsed in indicated mode. The modes are treated in
3658 more detail in the sections @ref{Note entry}, @ref{Lyrics} and
3661 You may nest different input modes.
3665 @subsection Ambiguities
3670 The grammar contains a number of ambiguities. We hope to resolve them at
3674 @item The assignment
3680 can be interpreted as making a string identifier @code{\foo}
3681 containing @code{"bar"}, or a music identifier @code{\foo}
3682 containing the syllable `bar'.
3684 @item The assignment
3690 can be interpreted as making an integer identifier
3691 containing -6, or a Request identifier containing the
3692 fingering `6' (with neutral direction).
3694 @item If you do a nested repeat like
3706 then it is ambiguous to which @code{\repeat} the
3707 @code{\alternative} belongs. This is the classic if-then-else
3708 dilemma. It may be solved by using braces.
3710 @item (an as yet unidentified ambiguity :-)
3725 @unnumberedsubsec Translation property
3727 [todo: add \set/\override/\revert]
3730 @cindex @code{\property}
3732 \property @var{contextname}.@var{propname} = @var{value}
3735 Sets the @var{propname} property of the context @var{contextname} to
3736 the specified @var{value}. All three arguments are strings.
3737 Depending on the context, it may be necessary to quote the strings or
3738 to leave space on both sides of the dot.
3741 @cindex output properties
3742 @unnumberedsubsec Output properties
3744 These allow you to tweak what is happening in the back-end
3745 directly. If you want to control every detail of the output
3746 formatting, this is the feature to use. The downside to this is that
3747 you need to know exactly how the backend works. Example:
3750 @lilypond[fragment,verbatim]
3752 \context Staff \outputproperty
3753 #(make-type-checker 'note-head-interface)
3754 #'extra-offset = #'(0.5 . 0.75)
3758 This selects all note heads occurring at current staff level, and sets
3759 the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting
3762 Use of this feature is entirely on your own risk: if you use this, the
3763 result will depend very heavily on the implementation of the backend,
3764 which we change regularly and unscrupulously.
3767 Don't move the finger 2, only text "m.d." ...
3769 #(define (make-text-checker text)
3770 (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
3773 \notes\relative c''' {
3774 \property Voice.Stem \set #'direction = #1
3775 \outputproperty #(make-text-checker "m.d.")
3776 #'extra-offset = #'(-3.5 . -4.5)
3779 \paper { linewidth = -1.; }
3789 @subsection Text markup
3793 LilyPond has an internal mechanism to typeset texts: you can
3794 form text markup expressions by composing scheme expressions
3795 in the following way:
3798 \score { \notes \relative c' {
3801 d-#'(lines "one" (bold "text"))
3802 e-#'(music (named "noteheads-2" "flags-u3"))
3804 \paper { linewidth = 10.\cm; } }
3807 Formally, Scheme markup text is defined as follows:
3810 text: string | (head? text+)
3811 head: markup | (markup+)
3812 markup-item: property | abbrev | @var{fontstyle}
3813 property: (@var{key} . @var{value})
3814 abbrev: @code{rows lines roman music bold italic named super sub text}
3817 The markup is broken down and converted into a list of grob properties,
3818 which are prepended to the grop's property list. The
3819 @var{key}-@var{value} pair is a grob property.
3821 [Why is this useful?]
3823 ?Snapnie: markup text is eerste item dat voldoet aan mijn gewelfdige,
3824 ideale idee van direct-en-eenmalig-per-item te zetten properties, ipv
3825 gehaspel via \property en hopen dat je property (enkel) in juiste item
3826 terecht gaat komen. Heb je deze wel bewust meegemaakt:
3828 Sender: jan@appel.lilypond.org
3829 To: Han-Wen <hanwen@cs.uu.nl>
3830 Subject: (elt) properties
3831 Organization: Jan at Appel
3832 From: janneke@gnu.org
3833 Date: 01 Nov 2000 10:39:10 +0100
3834 Message-ID: <m3og00av5t.fsf@appel.lilypond.org>
3835 User-Agent: Gnus/5.0807 (Gnus v5.8.7) Emacs/20.7
3837 Content-Type: text/plain; charset=us-ascii
3839 Xref: appel.lilypond.org vers:1991
3843 Wat ik vooral mis, is een koele manier om een propertie eenmalig aan
3844 een element te hangen. Hoop dat je zinvol over wilt meedenken; zie
3845 het monster van les-nereides. Misschien dat we 't niet moeten doen
3846 voor 1.4 maar wachten tot properties nog wat verder
3847 uitgekristalliseerd zijn?
3851 \property Voice.Stem \push #'length = #'6
3853 \property Voice.Stem \pop #'length
3856 waarmee je in feite zeg tegen de stem-engraver: vanaf nu aan moet je
3857 alle stems 6 lang maken (maakt stem); onee, doe maar weer default
3860 Maar dat is eigenlijk niet wat je bedoelt, wat je zou willen is net
3861 zo'n directe interface als wat we nu hebben voor markup text, bv. iets
3864 a+#'(Stem::length . 6) b
3866 Bij markup text kun je direct en eenmalig een reeks properties aan een
3867 enkel item toevoegen; iets wat je volgens mij vaak nodig hebt.
3869 Ik zat eerst te denken aan ``request properties'': properties
3870 toevoegen aan request, die dan worden doorgegeven aan alle items die
3871 door dat request worden gemaakt.
3873 Maar misschien zuigt dat wel te vreselijk en moeten we iets van
3874 ``volatile'' properties maken.
3878 \property Voice.Slur \push #'dash = #1
3879 \property Voice.Slur \pop #'dash
3881 \property Voice.Slur \push #'direction = #-1
3882 \property Voice.Slur \pop #'direction
3885 of de kluts waar ik brr van word, eigenlijk ook alleen doenbaar is
3886 voor wat veelgebruikte properties:
3888 slurDotted = \property Voice.Slur \push #'dash = #1
3889 slurNoDots = \property Voice.Slur \pop #'dash
3890 slurUp = \property Voice.Slur \push #'direction = #1
3891 slurDown = \property Voice.Slur \push #'direction = #-1
3892 slurBoth = \property Voice.Slur \pop #'direction
3896 \slurDotted\slurDown
3899 \slurNoDots\slurBoth
3901 zou toch graag meer iets in trant van, als je begrijpt wat ik bedoel
3903 Slur+#'((dash . 1) (direction . 1))
3905 Slur-#'(dash direction)
3909 a(+#'((dash . 1) (direction . 1))
3910 )b(+#'((dash . 1) (direction . 1))
3914 The following abbreviations are currently
3919 horizontal mode: set all text on one line (default)
3921 vertical mode: set every text on new line
3931 lookup by character name
3933 plain text lookup (by character value)
3941 @var{fontstyle} may be any of @code{finger volta timesig mmrest mark
3942 script large Large dynamic}
3946 Wat is daarmee, zijn toch gewoon grob properties van text-interface?
3949 @c .{Local emacs vars}
3952 @c minor-mode: font-lock
3953 @c minor-mode: outline
3954 @c outline-layout: (-1 : 0)
3955 @c outline-use-mode-specific-leader: "@c \."
3956 @c outline-primary-bullet: "{"
3957 @c outline-stylish-prefixes: nil
3958 @c outline-override-protect: t