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}.
607 @cindex @code{keySignature}
610 @subsubsection Clef changes
613 \clef @var{clefname} @code{;}
619 \property Staff.clefGlyph = @var{symbol associated with clefname}
620 \property Staff.clefPosition = @var{clef Y-position for clefname}
621 \property Staff.clefOctavation = @var{extra pitch of clefname}
624 Supported clef-names include
627 @item treble, violin, G, G2: G clef on 2nd line
628 @item french: G clef on 1st line
629 @item soprano: C clef on 1st line
630 @item mezzosoprano: C clef on 2nd line
631 @item alto: C clef on 3rd line
632 @item tenor: C clef on 4th line
633 @item baritone: C clef on 5th line
634 @item varbaritone: F clef on 3rd line
635 @item bass, F: F clef on 4th line
636 @item subbass: F clef on 5th line
637 @item percussion: percussion clef
640 [todo: ancient clefs]
642 Supported associated symbols (for Staff.clefGlyph) are:
645 @item clefs-C: modern style C clef
646 @item clefs-F: modern style F clef
647 @item clefs-G: modern style G clef
648 @item clefs-vaticana_do: Editio Vaticana style do clef
649 @item clefs-vaticana_fa: Editio Vaticana style fa clef
650 @item clefs-medicaea_do: Editio Medicaea style do clef
651 @item clefs-medicaea_fa: Editio Medicaea style fa clef
652 @item clefs-mensural1_c: modern style mensural C clef
653 @item clefs-mensural2_c: historic style small mensural C clef
654 @item clefs-mensural3_c: historic style big mensural C clef
655 @item clefs-mensural1_f: historic style traditional mensural F clef
656 @item clefs-mensural2_f: historic style new mensural F clef
657 @item clefs-mensural_g: historic style mensural G clef
658 @item clefs-hufnagel_do: historic style hufnagel do clef
659 @item clefs-hufnagel_fa: historic style hufnagel fa clef
660 @item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef
661 @item clefs-percussion: modern style percussion clef
664 @emph{Modern style} means "as is typeset in current editions".
665 @emph{Historic style} means "as was typeset or written in contemporary
666 historic editions". @emph{Editio XXX style} means "as is/was printed in
669 @c . {Time signature}
671 @subsection Time signature
672 @cindex Time signature
677 \time @var{numerator}@code{/}@var{denominator} @code{;}
680 A short-cut for doing
682 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
685 See the documentation of @code{timeSignatureFraction}
689 @subsubsection Partial
693 @cindex partial measure
694 @cindex measure, partial
695 @cindex shorten measures
696 @cindex @code{\partial}
698 \partial @var{duration} @code{;}
704 \property Score.measurePosition = @var{length of duration}
708 See the documentation of @code{measurePosition}.
716 [todo : collisiosn, rest-collisinos, voiceX identifiers, how to
717 which contexts to instantiate.]
721 @cindex @code{\shiftOff}
722 @item @code{\shiftOff}
723 Disable horizontal shifting of note heads that collide.
725 @cindex @code{\shiftOn}
726 @item @code{\shiftOn}
727 Enable note heads that collide with other note heads to be
728 shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
729 set different shift values.
731 @cindex @code{\stemBoth}
732 @item @code{\stemBoth}
733 Allow stems, beams, and slurs to point either upwards or
734 downwards, decided automatically by LilyPond.
736 @cindex @code{\stemDown}
737 @item @code{\stemDown}
738 Force stems, beams, and slurs to point down.
740 @cindex @code{\stemUp}
742 Force stems, beams and slurs to point up.
767 @c . {Automatic beams}
768 @subsubsection Automatic beams
771 @cindex automatic beam generation
773 @cindex @code{Voice.noAutoBeaming}
775 LilyPond will group flagged notes and generate beams autmatically, where
778 This feature can be disabled by setting the @code{Voice.noAutoBeaming}
779 property to true, which you may find necessary for the melody that goes
780 with lyrics, eg. Automatic beaming can easily be overridden for
781 specific cases by specifying explicit beams. This is discussed in the
786 @cindex @code{Voice.autoBeamSettings}
787 @cindex @code{(end * * * *)}
788 @cindex @code{(begin * * * *)}
790 A large number of Voice properties are used to decide how to generate
791 beams. Their default values appear in @file{scm/auto-beam.scm}. In
792 general, beams can begin anywhere, but their ending location is
793 significant. Beams can end on a beat, or at durations specified by the
794 properties in @code{Voice.autoBeamSettings}. To end beams every quarter
795 note, for example, you could set the property @code{(end * * * *)} to
796 @code{(make-moment 1 4)}. To end beams at every three eighth notes you
797 would set it to @code{(make-moment 1 8)}. The same syntax can be used
798 to specify beam starting points using @code{(begin * * * *)}, eg:
801 \property Voice.autoBeamSettings \override
802 #'(end * * * *) = #(make-moment 1 4)
803 \property Voice.autoBeamSettings \override
804 #'(begin * * * *) = #(make-moment 1 8)
808 To allow different settings for different time signatures, instead of
809 the first two asterisks @code{* *} you can specify a time signature; use
810 @code{(end N M * *)} to restrict the definition to
811 `@var{N}@code{/}@var{M}' time. For example, to specify beams ending
812 only for 6/8 time you would use the property @code{(end 6 8 * *)}.
814 To allow different endings for notes of different durations, instead of
815 th last two asterisks you can specify a duration; use @code{(end * * N
816 M)} to restrict the definition to beams that contain notes of
817 `@var{N}@code{/}@var{M}' duration.
819 For example, to specify beam endings for beams that contain 32nd notes,
820 you would use @code{(end * * 1 32)}.
825 @cindex Automatic beams
826 @subsubsection Manual beams
827 @cindex beams, manual
831 In some cases it may be necessary to override LilyPond's automatic
832 beaming algorithm. For example, the auto beamer will not beam over
833 rests or bar lines, so if you want that, specify the begin and end point
834 manually using @code{[} and @code{]}:
837 @lilypond[fragment,relative,verbatim]
839 r4 [r8 g'' a r8] r8 [g | a] r8
844 @cindex @code{stemLeftBeamCount}
846 If you have specific wishes for the number of beams, you can fully
847 control the number of beams through the properties
848 y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
850 @lilypond[fragment,relative,verbatim]
853 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
857 @cindex @code{stemRightBeamCount}
860 @c . {Adjusting beams}
861 @unnumberedsubsubsec Adjusting beams
862 @cindex Adjusting beams
878 A slur connects chords and is used to indicate legato. Slurs avoid
879 crossing stems. A slur is started with @code{(} and stopped with
880 @code{)}. The starting @code{(} appears to the right of the first note
881 in the slur. The terminal @code{)} appears to the left of the last note
882 in the slur. This makes it possible to put a note in slurs from both
885 @lilypond[fragment,verbatim,center]
886 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
889 @c . {Adjusting slurs}
890 @unnumberedsubsubsec Adjusting slurs
893 @node Slur attachments
894 @subsubsection Slur attachments
896 The ending of a slur should whenever possible be attached to a note
897 head. Only in some instances where beams are involved, LilyPond may
898 attach a slur to a stem end. In some cases, you may want to override
899 LilyPond's decision, e.g., to attach the slur to the stem end. This can
900 be done through @code{Voice.Slur}'s grob-property @code{attachment}:
904 @lilypond[fragment,relative,verbatim]
905 \property Voice.Slur \set #'direction = #1
906 \property Voice.Stem \set #'length = #5.5
908 \property Voice.Slur \set #'attachment = #'(stem . stem)
913 Similarly, slurs can be attached to note heads even when beams are
917 @lilypond[fragment,relative,verbatim]
918 \property Voice.Slur \set #'direction = #1
919 \property Voice.Slur \set #'attachment = #'(head . head)
920 g''16()g()g()g()d'()d()d()d
924 If a slur would strike through a stem or beam, LilyPond will move the
925 slur away vertically (upward or downward). In some cases, this may
926 cause ugly slurs that you may want to correct:
929 @lilypond[fragment,relative,verbatim]
930 \property Voice.Stem \set #'direction = #1
931 \property Voice.Slur \set #'direction = #1
933 \property Voice.Slur \set #'attachment = #'(stem . stem)
938 LilyPond will increase the curvature of a slur trying to stay free of
939 note heads and stems. However, if the curvature would increase too much,
940 the slur will be reverted to its default shape. This decision is based
941 on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
942 cases, you may find ugly slurs beautiful, and tell LilyPond so by
943 increasing the @code{beautiful} value:
945 [hoe gedefd?? wat betekent beautiful = X?]
950 \notes \context PianoStaff <
952 \context Staff=up { s1 * 6/4 }
953 \context Staff=down <
955 \autochange Staff \context Voice
957 d,8( a' d f a d f d a f d )a
965 Slur \override #'beautiful = #5.0
966 Slur \override #'direction = #1
967 Stem \override #'direction = #-1
968 autoBeamSettings \override #'(end * * * *)
973 VerticalAlignment \override #'threshold = #'(5 . 5)
980 @cindex Adusting slurs
986 @subsection Phrasing slur
987 @cindex phrasing slur
988 @cindex phrasing mark
990 A phrasing slur (or phrasing mark) connects chords and is used to
991 indicate a musical sentence. Phrasing slurs avoid crossing stems. A
992 phrasing slur is started with @code{\(} and stopped with @code{\)}. The
993 starting @code{\(} appears to the right of the first note in the
994 phrasing slur. The terminal @code{\)} appears to the left of the last
995 note in the phrasing slur.
997 @lilypond[fragment,verbatim,center,relative]
998 \time 6/4; c''\((d)e f(e)\)d
1018 A tie connects two adjacent note heads of the same pitch. When used
1019 with chords, it connects all of the note heads whose pitches match.
1020 Ties are indicated using the tilde symbol `@code{~}'.
1021 If you try to tie together chords which have no common pitches, a
1022 warning message will appear and no ties will be created.
1024 @lilypond[fragment,verbatim,center]
1025 e' ~ e' <c' e' g'> ~ <c' e' g'>
1033 @subsubsection Tuplets
1037 Tuplets are made out of a music expression by multiplying their duration
1040 @cindex @code{\times}
1042 \times @var{fraction} @var{musicexpr}
1045 The duration of @var{musicexpr} will be multiplied by the fraction.
1046 In print, the fraction's denominator will be printed over the notes,
1047 optionally with a bracket. The most common tuplet is the triplet in
1048 which 3 notes have the length of 2, so the notes are 2/3 of
1049 their written length:
1051 @lilypond[fragment,verbatim,center]
1052 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1055 [todo: document tupletSpannerDuration]
1061 @subsubsection Text spanner
1062 @cindex Text spanner
1066 @subsubsection Ottava
1068 @unnumberedsubsubsec Ottava
1070 [move to trick. Not a supported feature.]
1072 @lilypond[fragment,relative,verbatim]
1074 \property Voice.TextSpanner \set #'type = #'dotted-line
1075 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1076 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1077 \property Staff.centralCPosition = #-13
1078 a\spanrequest \start "text" b c a \spanrequest \stop "text"
1083 @c . {Span requests}
1085 @subsubsection Span requests
1086 @cindex Span requests
1088 @cindex @code{\spanrequest}
1091 \spanrequest @var{startstop} @var{type}
1093 @cindex @code{\start}
1094 @cindex @code{\stop}
1096 Define a spanning request. The @var{startstop} parameter is either -1
1097 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
1098 describes what should be started. Supported types are @code{crescendo},
1099 @code{decrescendo}, @code{beam}, @code{slur}. [FIXME: many more] This
1100 is an internal command. Users should use the shorthands which are
1101 defined in the initialization file @file{spanners.ly}.
1103 You can attach a (general) span request to a note using
1105 @lilypond[fragment,verbatim,center]
1106 c'4-\spanrequest \start "slur"
1107 c'4-\spanrequest \stop "slur"
1110 The slur syntax with parentheses is a shorthand for this.
1115 @subsection Ornaments
1124 @subsubsection Articulation
1125 @cindex Articulation
1127 @cindex articulations
1131 A variety of symbols can appear above and below notes to indicate
1132 different characteristics of the performance. These symbols can be
1133 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1134 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1135 forced to appear above or below the note by writing
1136 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1137 respectively. Here is a chart showing symbols above notes, with the
1138 name of the corresponding symbol appearing underneath.
1144 \property Score.LyricSyllable \override #'font-family =
1146 \property Score.LyricSyllable \override #'font-shape = #'upright
1147 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1148 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1149 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1150 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1151 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1152 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1153 c''-\thumb c''-\segno c''-\coda
1155 \context Lyrics \lyrics {
1156 accent__ marcato__ staccatissimo__ fermata
1157 stopped__ staccato__ tenuto__ upbow
1158 downbow__ lheel__ rheel__ ltoe
1159 rtoe__ turn__ open__ flageolet
1160 reverseturn__ trill__ prall__ mordent
1161 prallprall__ prallmordent__ uprall__ downprall
1162 thumb__ segno__ coda
1166 linewidth = 5.875\in;
1175 @subsubsection Text scripts
1176 @cindex Text scripts
1178 In addition, it is possible to place arbitrary strings of text or markup
1179 text (see @ref{Text markup}) above or below notes by using a string
1180 instead of an identifier: @code{c^"text"}. It is possible to use @TeX{}
1181 commands, but this should be avoided because this makes it impossible
1182 for LilyPond to compute the exact length of the string, which may lead
1183 to collisions. Also, @TeX{} commands won't work with direct postscript
1184 output. Fingerings can be placed by simply using digits. All of these
1185 note ornaments appear in the printed output but have no effect on the
1186 MIDI rendering of the music.
1189 @unnumberedsubsubsec Fingerings
1192 To save typing, fingering instructions (digits 0 to 9 are
1193 supported) and single characters shorthands exist for a few
1198 \notes \context Voice {
1199 \property Voice.TextScript \set #'font-family = #'typewriter
1200 \property Voice.TextScript \set #'font-shape = #'upright
1206 c''4-^_"c-\\^{ }" s4
1213 linewidth = 5.875 \in;
1221 @cindex @code{\textscript}
1225 \textscript @var{text} @var{style}
1228 Defines a text to be printed over or under a note. @var{style} is a
1229 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1230 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1232 You can attach a general textscript request using this syntax:
1237 c4-\textscript "6" "finger"
1238 c4-\textscript "foo" "normal"
1243 This is equivalent to @code{c4-6 c4-"foo"}.
1245 @cindex @code{\script}
1254 Prints a symbol above or below a note. The argument is a string which
1255 points into the script-alias table defined in @file{scm/script.scm}.
1256 Usually the @code{\script} keyword is not used directly. Various
1257 helpful identifier definitions appear in @file{script.ly}.
1259 For information on how to add scripts, consult @file{scm/script.scm}.
1266 @subsection Grace notes
1275 @cindex @code{\grace}
1278 @cindex @code{graceAlignPosition}
1281 \grace @var{musicexpr}
1284 A grace note expression has duration 0; the next real note is
1285 assumed to be the main note.
1287 You cannot have the grace note after the main note, in terms of
1288 duration, and main notes, but you can typeset the grace notes to the
1289 right of the main note using the property
1290 @code{graceAlignPosition}.
1291 @cindex @code{flagStyle}
1293 When grace music is interpreted, a score-within-a-score is set up:
1294 @var{musicexpr} has its own time bookkeeping, and you could (for
1295 example) have a separate time signature within grace notes. While in
1296 this score-within-a-score, you can create notes, beams, slurs, etc.
1297 Unbeamed eighth notes and shorter by default have a slash through the
1298 stem. This behavior can be controlled with the
1299 @code{flagStyle} property.
1302 @lilypond[fragment,verbatim]
1304 \grace c8 c4 \grace { [c16 c16] } c4
1305 \grace { \property Grace.flagStyle = "" c16 } c4
1312 At present, nesting @code{\grace} notes is not supported. The following
1313 may cause run-time errors:
1315 @code{\grace @{ \grace c32 c16 @} c4}
1317 Since the meaning of such a construct is unclear, we don't consider
1318 this a loss. Similarly, juxtaposing two @code{\grace} sections is
1319 syntactically valid, but makes no sense and may cause runtime errors.
1321 Ending a staff or score with grace notes may also generate a run-time
1322 error, since there will be no main note to attach the grace notes to.
1324 The present implementation is not robust and generally kludgy. We expect
1325 it to change after LilyPond 1.4. Syntax changes might also be
1338 * Crescendo and Decrescendo::
1347 @subsubsection Glissando
1350 @cindex @code{\glissando}
1352 A glissando line can be requested by attaching a @code{\glissando} to a
1356 @lilypond[fragment,relative,verbatim]
1361 Printing of an additional text (such as @emph{gliss.}) must be done
1368 @subsubsection Dynamics
1381 @cindex @code{\ffff}
1395 Dynamic marks are specified by using an identifier after a note:
1396 @code{c4-\ff}. The available dynamic marks are:
1397 @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f},
1398 @code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf},
1399 @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1401 @c . {Crescendo and Decrescendo}
1402 @node Crescendo and Decrescendo
1403 @subsubsection Crescendo and Decrescendo
1405 @cindex Crescendo and Decrescendo
1409 @cindex @code{\decr}
1410 @cindex @code{\rced}
1417 A crescendo mark is started with @code{\cr} and terminated with
1418 @code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
1419 started with @code{\decr} and terminated with @code{\rced}. There are
1420 also shorthands for these marks. A crescendo can be started with
1421 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1422 can be terminated with @code{\!}. Note that @code{\!} must go before
1423 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1424 after the last note. Because these marks are bound to notes, if you
1425 want to get several marks during one note, you must use spacer notes.
1427 @lilypond[fragment,verbatim,center]
1428 c'' \< \! c'' d'' \decr e'' \rced
1429 < f''1 { s4 \< \! s2 \> \! s4 } >
1432 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1433 is an example how to do it:
1435 @lilypond[fragment,relative,verbatim]
1437 \property Voice.crescendoText = "cresc."
1438 \property Voice.crescendoSpanner = #'dashed-line
1447 @subsubsection Bar lines
1451 @cindex measure lines
1458 This is a short-cut for doing
1460 \property Score.whichBar = @var{bartype}
1463 You are encouraged to use @code{\repeat} for repetitions. See
1464 @ref{Repeats}, and the documentation of @code{whichBar} in
1465 @ref{(lilypond-internals)LilyPond context properties}.
1472 @subsubsection Breath marks
1473 @cindex Breath marks
1479 @subsection Bar check
1483 @cindex @code{barCheckNoSynchronize}
1487 Whenever a bar check is encountered during interpretation, a warning
1488 message is issued if it doesn't fall at a measure boundary. This can
1489 help you find errors in the input. Depending on the value of
1490 @code{barCheckNoSynchronize}, the beginning of the measure will be
1491 relocated, so this can also be used to shorten measures.
1493 A bar check is entered using the bar symbol, @code{|}
1504 @section Piano music
1506 * Automatic staff changes::
1507 * Manual staff switches::
1514 @c . {Automatic staff changes}
1515 @node Automatic staff changes
1516 @subsection Automatic staff changes
1517 @cindex Automatic staff changes
1521 @node Manual staff switches
1522 @subsection Manual staff switches
1524 @cindex manual staff switches
1525 @cindex staff switch, manual
1527 @cindex @code{\translator}
1529 \translator @var{contexttype} = @var{name}
1532 A music expression indicating that the context which is a direct
1533 child of the a context of type @var{contexttype} should be shifted to
1534 a context of type @var{contexttype} and the specified name.
1536 Usually this is used to switch staffs in Piano music, e.g.
1539 \translator Staff = top @var{Music}
1553 @subsection Arpeggio
1556 @cindex broken arpeggio
1557 @cindex @code{\arpeggio}
1559 You can specify an arpeggio sign on a chord by attaching an
1560 @code{\arpeggio} to a note of the chord.
1564 @lilypond[fragment,relative,verbatim]
1565 \context Voice <c'\arpeggio e g c>
1569 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1570 to the chords in both staffs, and set
1571 @code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
1575 @lilypond[fragment,relative,verbatim]
1576 \context PianoStaff <
1577 \property PianoStaff.connectArpeggios = ##t
1578 \context Voice = one { <c''\arpeggio e g c> }
1579 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1586 @c . {Follow Thread}
1588 @subsection Follow Thread
1589 @cindex follow thread
1590 @cindex staff switching
1593 [todo: different name, eg. voice line ? ]
1595 @cindex @code{followThread}
1597 Whenever a voice switches to another staff a line connecting the notes
1598 can be printed automatically. This is enabled if the property
1599 @code{PianoStaff.followThread} is set to true:
1602 @lilypond[fragment,relative,verbatim]
1603 \context PianoStaff <
1604 \property PianoStaff.followThread = ##t
1605 \context Staff \context Voice {
1607 \translator Staff=two
1610 \context Staff=two {\clef bass; \skip 1*2;}
1624 * Automatic syllable durations::
1629 @subsection Lyrics mode
1633 @cindex @code{\lyrics}
1635 Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
1636 rules that make it easy to include punctuation and diacritical marks in
1637 words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
1638 format or a standard encoding without needing quotes. The precise
1639 definition of this mode is ludicrous, and this will remain so until the
1640 authors of LilyPond acquire a deeper understanding of character
1641 encoding, or someone else steps up to fix this.
1643 A word in Lyrics mode begins with: an alphabetic character, @code{_},
1644 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
1645 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
1646 any 8-bit character with ASCII code over 127, or a two-character
1647 combination of a backslash followed by one of @code{`}, @code{'},
1648 @code{"}, or @code{^}.
1650 Subsequent characters of a word can be any character that is not a digit
1651 and not white space. One important consequence of this is that a word
1652 can end with `@code{@}}', which may be confusing. However, LilyPond will
1653 issue a warning. Any @code{_} character which appears in an unquoted
1654 word is converted to a space. This provides a mechanism for introducing
1655 spaces into words without using quotes. Quoted words can also be used
1656 in Lyrics mode to specify words that cannot be written with the above
1657 rules. Here are some examples. Not all of these words are printable by
1662 2B_||_!2B % not a word because it starts with a digit
1663 ``Hello'' % not a word because it starts with `
1664 _ _ _ _ % 4 words, each one a space
1667 Since combinations of numbers and dots are used for indicating
1668 durations, you can not enter real numbers in this mode.
1670 @cindex lyrics expressions
1672 Syllables are entered like notes, with pitches replaced by text. For
1673 example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
1674 with quarter note duration. Note that the hyphen has no special
1675 meaning for lyrics, and does not introduce special symbols. See
1676 section @ref{Lexical modes} for a description of what is interpreted as
1679 Spaces can be introduced into a lyric either by using quotes
1680 (@code{"}) or by using an underscore without quotes: @code{He_could4
1681 not4}. All unquoted underscores are converted to spaces. Printing
1682 lyrics is discussed in the next section.
1685 @c . {Printing lyrics}
1686 @node Printing lyrics
1687 @subsection Printing lyrics
1691 Lyric syllables must be interpreted within a @code{Lyrics} context for
1692 printing them. Here is a full example:
1698 \notes \transpose c'' {
1700 e f g2 | e4 f g2 \bar "|.";
1702 \context Lyrics \lyrics {
1703 Va-4 der Ja- cob Va- der Ja- cob
1704 Slaapt gij nog?2 Slaapt4 gij nog?2
1716 @cindex lyric extender
1718 You may want a continuous line after the syllables to show melismata.
1719 To achieve this effect, add a @code{__} lyric as a separate word
1720 after the lyric to be extended. This will create an extender, a line
1721 that extends over the entire duration of the lyric. This line will
1722 run all the way to the start of the next lyric, so you may want to
1723 shorten it by using a blank lyric (using @code{_}).
1730 \notes \relative c'' {
1731 a4 () b () c () d | c () d () b () a | c () d () b () a
1733 \context Lyrics \lyrics {
1734 foo1 __ | bar2. __ _4 | baz1 __
1742 @cindex Lyric hyphen
1744 If you want to have hyphens centered between syllables (rather than
1745 attached to the end of the first syllable) you can use the special
1746 `@code{-}@code{-}' lyric as a separate word between syllables. This
1747 will result in a hyphen which length varies depending on the space
1748 between syllables, and which will be centered between the syllables.
1756 \notes \transpose c'' {
1758 e f g2 | e4 f g2 \bar "|.";
1760 \context Lyrics \lyrics {
1761 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1762 Slaapt gij nog?2 | Slaapt4 gij nog?2
1771 @c . {Automatic syllable durations}
1772 @node Automatic syllable durations
1773 @subsection Automatic syllable durations
1774 @cindex Automatic syllable durations
1777 [explain automatic phrasing]
1778 @cindex automatic lyric durations
1779 @cindex @code{\addlyrics}
1781 If you have lyrics that are set to a melody, you can import the rhythm
1782 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1785 \addlyrics @var{musicexpr1 musicexpr2}
1788 This means that both @var{musicexpr1} and @var{musicexpr2} are
1789 interpreted, but that every non-command atomic music expression
1790 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1791 of @var{musicexpr1}.
1792 @cindex @code{automaticMelismata}
1794 If the property @code{automaticMelismata} is set in the
1795 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1799 @lilypond[verbatim,fragment]
1802 \property Voice.automaticMelismata = ##t
1803 c8 () cis d8. e16 f2
1805 \context Lyrics \lyrics {
1810 You should use a single rhythm melody, and single rhythm lyrics (a
1811 constant duration is the obvious choice). If you do not, you will get
1812 undesired effects when using multiple stanzas:
1815 @lilypond[verbatim,fragment]
1818 c8 () cis d8. e16 f2
1820 \context Lyrics \lyrics
1827 It is valid (but probably not very useful) to use notes instead of
1828 lyrics for @var{musicexpr2}.
1837 [chords vs. simultaneous music]
1841 * Entering named chords::
1842 * Printing named chords::
1847 @subsection Chords mode
1850 Chord mode is introduced by the keyword
1851 @code{\chords}. It is similar to Note mode, but
1852 words are also looked up in a chord modifier table (containing
1853 @code{maj}, @code{dim}, etc).
1855 Since combinations of numbers and dots are used for indicating
1856 durations, you can not enter real numbers in this mode. Dashes
1857 and carets are used to indicate chord additions and subtractions,
1858 so scripts can not be entered in Chord mode.
1860 @c . {Entering named chords}
1861 @node Entering named chords
1862 @subsection Entering named chords
1863 @cindex Chords names
1865 Chord names are a way to generate simultaneous music expressions that
1866 correspond with traditional chord names. It can only be used in
1867 Chord mode (see section @ref{Lexical modes}).
1871 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1874 @var{tonic} should be the tonic note of the chord, and @var{duration}
1875 is the chord duration in the usual notation. There are two kinds of
1876 modifiers. One type is @emph{chord additions}, which are obtained by
1877 listing intervals separated by dots. An interval is written by its
1878 number with an optional @code{+} or @code{-} to indicate raising or
1879 lowering by half a step. Chord additions has two effects: It adds
1880 the specified interval and all lower odd numbered intervals to the
1881 chord, and it may lower or raise the specified interval. Intervals
1882 must be separated by a dot (@code{.}).
1885 Throughout these examples, chords have been shifted around the staff
1886 using @code{\transpose}.
1891 @lilypond[fragment,verbatim]
1895 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1907 The second type of modifier that may appear after the @code{:} is a
1908 named modifier. Named modifiers are listed in the file
1909 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
1910 @code{min} which lower the 3rd half a step, `@code{aug}' which
1911 raises the 5th, `@code{dim}' which lowers the 5th,
1912 `@code{maj}' which adds a raised 7th, and `@code{sus}'
1913 which replaces the 5th with a 4th.
1917 @lilypond[fragment,verbatim]
1920 c1:m c:min7 c:maj c:aug c:dim c:sus
1928 Chord subtractions are used to eliminate notes from a chord. The
1929 notes to be subtracted are listed after a @code{^} character,
1932 @lilypond[fragment,verbatim,center]
1941 Chord inversions can be specified by appending `@code{/}' and
1942 the name of a single note to a chord. This has the effect of
1943 lowering the specified note by an octave so it becomes the lowest
1944 note in the chord. If the specified note is not in the chord, a
1945 warning will be printed.
1947 @lilypond[fragment,verbatim,center]
1957 Bass notes can be added by `@code{/+}' and
1958 the name of a single note to a chord. This has the effect of
1959 adding the specified note to the chord, lowered by an octave,
1960 so it becomes the lowest note in the chord.
1962 @lilypond[fragment,verbatim,center]
1971 The most interesting application is printing chord names, which is
1972 explained in the next subsection.
1974 You should not combine @code{\relative} with named chords. [FIXME]
1976 @c . {Printing named chords}
1977 @node Printing named chords
1978 @subsection Printing named chords
1984 @cindex printing chord names
1987 @cindex @code{ChordNames}
1988 @cindex @code{ChordNameVoice}
1990 For displaying printed chord names, use the @code{ChordNames} and
1991 @code{ChordNameVoice} contexts. The chords may be entered either using
1992 the notation described above, or directly using simultaneous music.
1997 \chords {a1 b c} <d f g> <e g b>
2001 \context ChordNamesVoice \scheme
2002 \context Staff \transpose c'' \scheme
2004 \paper { linewidth = -1.; }
2009 You can make the chord changes stand out more by setting property
2010 @code{ChordNames.chordChanges} to true. This will only display chord
2011 names when there's a change in the chords scheme, but always display the
2012 chord name after a line break:
2018 c1:m \break c:m c:m c:m d
2023 \context ChordNames \scheme
2024 \context Staff \transpose c'' \scheme
2027 linewidth = 40 * \staffspace;
2039 LilyPond examines chords specified as lists of notes to determine a
2040 name to give the chord. LilyPond will not try to
2041 identify chord inversions or added base, which may result in strange
2042 chord names when chords are entered as a list of pitches:
2045 @lilypond[verbatim,center]
2054 \context ChordNamesVoice \scheme
2055 \context Staff \scheme
2057 \paper { linewidth = -1.; }
2062 To specify chord inversions, append @code{/<notename>}. To specify an
2063 added bass note, append @code{/+<notename}:
2066 @lilypond[verbatim,center]
2073 \context ChordNames \scheme
2074 \context Staff \transpose c'' \scheme
2076 \paper { linewidth = -1.; }
2081 The chord names that LilyPond should print are fully customizable. The
2082 code to print chord names is written in Scheme. It can be found in
2083 @file{scm/chord-name.scm}. Chord names are based on Banter style
2084 naming, which is unambiguous and has a logical structure. Typical
2085 American style chord names are implemented as a variation on Banter
2086 names, they can be selected by setting property @code{ChordName.style}
2091 \include "english.ly"
2096 df:m5- % Diminished triad
2097 c:5^3 % Root-fifth chord
2098 c:4^3 % Suspended fourth triad
2099 c:5+ % Augmented triad
2101 c:m5-.7- % Diminished seventh
2102 c:7+ % Major seventh
2103 c:7.4^3 % Dominant seventh suspended fourth
2104 c:5+.7 % Augmented dominant seventh
2105 c:m5-.7 % "Half" diminished seventh
2106 c:5-.7 % Dominant seventh flat fifth
2107 c:5-.7+ % Major seventh flat fifth
2108 c:m7+ % Minor-major seventh
2109 c:m7 % Minor seventh
2110 c:7 % Dominant seventh
2113 c:9^7 % Major triad w/added ninth
2114 c:6.9^7 % Six/Nine chord
2115 c:9 % Dominant ninth
2116 c:7+.9 % Major ninth
2117 c:m7.9 % Minor ninth
2122 \context ChordNames \scheme
2123 \context Staff \transpose c'' \scheme
2128 ChordName \override #'word-space = #1
2129 ChordName \override #'style = #'american
2136 Similarly, Jazz style chord names are implemented as a variation on
2137 American style names:
2143 c:6 % 6 = major triad with added sixth
2144 c:maj % triangle = maj
2149 c:m % m = minor triad
2150 c:m.6 % m6 = minor triad with added sixth
2151 c:m.7+ % m triangle = minor major seventh chord
2159 c:7.5+ % +7 = augmented dominant
2160 c:7.5- % 7b5 = hard diminished dominant
2167 c:13.9-^11 % 7(b9,13)
2168 c:13.9+^11 % 7(#9,13)
2170 c:13-.9-^11 % 7(b9,b13)
2171 c:13-.9+^11 % 7(#9,b13)
2173 % half diminished chords
2174 c:m5-.7 % slashed o = m7b5
2175 c:9.3-.5- % o/7(pure 9)
2178 c:m5-.7- % o = diminished seventh chord
2183 \context ChordNames \scheme
2184 \context Staff \transpose c'' \scheme
2189 ChordName \override #'word-space = #1
2190 ChordName \override #'style = #'jazz
2198 @section Writing parts
2203 * Instrument names::
2205 * Multi measure rests::
2214 tranposing midi property.
2220 @c . {Rehearsal marks}
2221 @node Rehearsal marks
2222 @subsection Rehearsal marks
2223 @cindex Rehearsal marks
2225 @cindex @code{\mark}
2226 @cindex @code{Mark_engraver}
2229 \mark @var{unsigned};
2234 With this command, you can print a rehearsal mark above the system. You
2235 can provide a number, a string or a markup text as argument. If there is
2236 no argument, the property @code{rehearsalMark} is used and automatically
2239 @lilypond[fragment,verbatim]
2245 c1 \mark #'(music "scripts-segno") ;
2250 @node Instrument names
2251 @subsection Instrument names
2253 You can specify an instrument name for a staff by setting
2254 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2255 before the start of the staff. For the first start, @code{instrument} is
2256 used, for the next ones @code{instr} is used.
2260 \property Staff.instrument = "instr " { c''4 } }
2261 \paper { linewidth = -1.;
2262 \translator { \StaffContext
2263 \consists "Instrument_name_engraver"; } } }
2266 This requires that you add the @code{Instrument_name_engraver} to the
2271 @subsection Transpose
2273 @cindex transposition of pitches
2274 @cindex @code{\transpose}
2276 A music expression can be transposed with @code{\transpose}. The syntax
2279 \transpose @var{pitch} @var{musicexpr}
2282 This means that middle C in @var{musicexpr} is transposed to
2285 @code{\transpose} distinguishes between enharmonic pitches: both
2286 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2287 a tone. The first version will print sharps and the second version
2291 @lilypond[fragment,verbatim]
2294 { \key e \major; c d e f }
2296 \transpose des'' { \key e \major; c d e f }
2297 \transpose cis'' { \key e \major; c d e f }
2303 If you want to use both @code{\transpose} and @code{\relative}, then
2304 you must use @code{\transpose} first. @code{\relative} will have no
2305 effect music that appears inside a @code{\transpose}.
2308 @c . {Multi measure rests}
2309 @node Multi measure rests
2310 @subsection Multi measure rests
2311 @cindex Multi measure rests
2315 Multi measure rests are entered using `@code{R}'. It is specifically
2316 meant for entering parts: the rest can expand to fill a score with
2317 rests, or it can be printed as a single multimeasure rest This expansion
2318 is controlled by the property @code{Score.skipBars}. If this is set to true,
2319 Lily will not expand empty measures, and the appropriate number is added
2322 @lilypond[fragment,verbatim]
2323 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2326 Currently, there is no way to condense multiple rests into a single
2329 @cindex condensing rests
2337 A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a
2338 staff context symbol that appears at the end of a staff line. It
2339 anticipates the pitch of the first note(s) of the following line and
2340 thus helps the player or singer to manage line breaks during
2341 performance, thus enhancing readability of a score.
2346 \notes { c'1 d' e' d' \break c' d' e' d' }
2350 \consists Custos_engraver;
2351 Custos \override #'style = #'mensural;
2358 Custodes were frequently used in music notation until the 16th century.
2359 There were different appearences for different notation styles.
2360 Nowadays, they have survived only in special forms of musical notation
2361 such as via the editio vaticana dating back to the beginning of the 20th
2364 For typesetting custodes, just put a @code{Custos_engraver} into the
2365 @code{StaffContext} when declaring the @code{\paper} block. In this
2366 block, you can also globally control the appearance of the custos symbol
2367 by setting the custos @code{style} property. Currently supported styles
2368 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2375 \consists Custos_engraver;
2376 Custos \override #'style = #'mensural;
2381 The property can also be set locally, for example in a @code{\notes}
2386 \property Staff.Custos \override #'style = #'vaticana
2387 c'1 d' e' d' \break c' d' e' d'
2393 @section Page layout
2407 @subsection Paper block
2410 The most important output definition is the @code{\paper} block, for
2411 music notation. The syntax is
2414 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2417 where each of the items is one of
2420 @item An assignment. The assignment must be terminated by a
2423 @item A context definition. See section @ref{Context definitions} for
2424 more information on context definitions.
2426 @item \stylesheet declaration. Its syntax is
2428 \stylesheet @var{alist}
2431 See @file{font.scm} for details of @var{alist}.
2434 @c . {Paper variables}
2435 @node Paper variables
2436 @subsection Paper variables
2437 @cindex Paper variables
2439 The paper block has some variables you may want to use or change:
2442 @cindex @code{indent}
2444 The indentation of the first line of music.
2445 @cindex @code{staffspace}
2447 @item @code{staffspace}
2448 The distance between two staff lines, calculated from the center
2449 of the lines. You should use either this or @code{stafflinethickness}
2450 as a unit for distances you modify.
2452 @cindex @code{linewidth}
2453 @item @code{linewidth}
2454 Sets the width of the lines.
2456 If set to a negative value, a single
2457 unjustified line is produced.
2459 @cindex @code{textheight}
2461 @item @code{textheight}
2462 Sets the total height of the music on each page. Only used by
2464 @cindex @code{interscoreline}
2466 @item @code{interscoreline}
2467 Sets the spacing between the score lines. Defaults to 16 pt.
2468 @cindex @code{interscorelinefill}
2470 @item @code{interscorelinefill}
2471 If set to a positive number, the distance between the score
2472 lines will stretch in order to fill the full page. In that
2473 case @code{interscoreline} specifies the minimum spacing.
2475 @cindex @code{stafflinethickness}
2477 @item @code{stafflinethickness}
2478 Determines the thickness of staff lines, and also acts as a scaling
2479 parameter for other line thicknesses.
2486 @subsection Font size
2489 The Feta font provides musical symbols at six different sizes. These
2490 fonts are 11 point, 13 point, 16 point, 20 point,
2491 23 point, and 26 point. The point size of a font is the
2492 height of the five lines in a staff when displayed in the font.
2494 Definitions for these sizes are the files @file{paperSZ.ly}, where
2495 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2496 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2497 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2498 @code{paperTwentysix} are defined respectively. The default
2499 @code{\paper} block is also set.
2501 The font definitions are generated using a Scheme function. For more
2502 details, see the file @file{font.scm}.
2508 @subsection Paper size
2513 @cindex @code{papersize}
2515 To change the paper size, you must first set the
2516 @code{papersize} variable at top level. Set it to
2517 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2518 specification, you must set the font as described above. If you want
2519 the default font, then use the 20 point font. The new paper size will
2520 not take effect if the font is not loaded and selected afterwards.
2524 \include "paper16.ly"
2528 \paper @{ \paperSixteen @}
2532 The file "paper16.ly" will now include a file named @file{a4.ly}, which
2533 will set the paper variables @code{hsize} and @code{vsize} (used by
2544 @subsection Line break
2547 @cindex breaking lines
2549 Line breaks are normally computed automatically. They are chosen such
2550 that the resulting spacing has low variation, and looks neither cramped
2553 Occasionally you might want to override the automatic breaks; you can do
2554 this by specifying @code{\break}. This will force a line break at this
2555 point. Do remember that line breaks can only occur at places where there
2556 are barlines. If you want to have a line break where there is no
2557 barline, you can force a barline by entering @code{\bar "";}.
2559 Similarly, @code{\noBreak} forbids a line break at a certain point.
2561 @cindex @code{\penalty}
2563 The @code{\break} and @code{\noBreak} commands are defined in terms of
2564 the penalty command:
2566 \penalty @var{int} @code{;}
2569 This imposes encourages or discourages LilyPond to make a line break
2572 @strong{Warning} do not use @code{\penalty} directly. It is rather
2573 kludgy, and slated for rewriting.
2577 @subsection Page break
2580 @cindex breaking pages
2583 Page breaks are normally computed by @TeX{}, so they are not under direct
2584 control. However, you can insert a commands into the @file{.tex} output to
2585 instruct @TeX{} where to break pages. For more details, see the
2586 example file @file{input/test/between-systems.ly}
2601 * MIDI instrument names::
2607 @subsection MIDI block
2611 The MIDI block is analogous to the paper block, but it is somewhat
2612 simpler. The @code{\midi} block can contain:
2616 @item a @code{\tempo} definition
2617 @item context definitions
2620 Assignments in the @code{\midi} block are not allowed.
2624 @cindex context definition
2626 Context definitions follow precisely the same syntax as within the
2627 \paper block. Translation modules for sound are called performers.
2628 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2631 @c . {MIDI instrument names}
2632 @node MIDI instrument names
2633 @subsection MIDI instrument names
2634 @cindex instrument names
2635 @cindex @code{Staff.midiInstrument}
2636 @cindex @code{Staff.instrument}
2638 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2639 property or, if that property is not set, the @code{Staff.instrument}
2640 property. The instrument name should be chosen from the following list.
2641 If the selected string does not exactly match, then LilyPond uses the
2644 [FIXME: to appendix ]
2648 "acoustic grand" "contrabass" "lead 7 (fifths)"
2649 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2650 "electric grand" "pizzicato strings" "pad 1 (new age)"
2651 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2652 "electric piano 1" "timpani" "pad 3 (polysynth)"
2653 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2654 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2655 "clav" "synthstrings 1" "pad 6 (metallic)"
2656 "celesta" "synthstrings 2" "pad 7 (halo)"
2657 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2658 "music box" "voice oohs" "fx 1 (rain)"
2659 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2660 "marimba" "orchestra hit" "fx 3 (crystal)"
2661 "xylophone" "trumpet" "fx 4 (atmosphere)"
2662 "tubular bells" "trombone" "fx 5 (brightness)"
2663 "dulcimer" "tuba" "fx 6 (goblins)"
2664 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2665 "percussive organ" "french horn" "fx 8 (sci-fi)"
2666 "rock organ" "brass section" "sitar"
2667 "church organ" "synthbrass 1" "banjo"
2668 "reed organ" "synthbrass 2" "shamisen"
2669 "accordion" "soprano sax" "koto"
2670 "harmonica" "alto sax" "kalimba"
2671 "concertina" "tenor sax" "bagpipe"
2672 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2673 "acoustic guitar (steel)" "oboe" "shanai"
2674 "electric guitar (jazz)" "english horn" "tinkle bell"
2675 "electric guitar (clean)" "bassoon" "agogo"
2676 "electric guitar (muted)" "clarinet" "steel drums"
2677 "overdriven guitar" "piccolo" "woodblock"
2678 "distorted guitar" "flute" "taiko drum"
2679 "guitar harmonics" "recorder" "melodic tom"
2680 "acoustic bass" "pan flute" "synth drum"
2681 "electric bass (finger)" "blown bottle" "reverse cymbal"
2682 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2683 "fretless bass" "whistle" "breath noise"
2684 "slap bass 1" "ocarina" "seashore"
2685 "slap bass 2" "lead 1 (square)" "bird tweet"
2686 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2687 "synth bass 2" "lead 3 (calliope)" "helicopter"
2688 "violin" "lead 4 (chiff)" "applause"
2689 "viola" "lead 5 (charang)" "gunshot"
2690 "cello" "lead 6 (voice)"
2701 @cindex beats per minute
2702 @cindex metronome marking
2704 @cindex @code{\tempo}
2706 \tempo @var{duration} = @var{perminute} @code{;}
2709 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
2710 output with 76 quarter notes per minute.
2718 @section Music entry
2729 @subsection Relative
2731 @cindex relative octave specification
2733 Octaves are specified by adding @code{'} and @code{,} to pitch names.
2734 When you copy existing music, it is easy to accidentally put a pitch in
2735 the wrong octave and hard to find such an error. To prevent these
2736 errors, LilyPond features octave entry.
2738 @cindex @code{\relative}
2740 \relative @var{startpitch} @var{musicexpr}
2743 The octave of notes that appear in @var{musicexpr} are calculated as
2744 follows: If no octave changing marks are used, the basic interval
2745 between this and the last note is always taken to be a fourth or less.
2746 The octave changing marks @code{'} and @code{,} can then
2747 be added to raise or lower the pitch by an extra octave. Upon entering
2748 relative mode, an absolute starting pitch must be specified that will
2749 act as the predecessor of the first note of @var{musicexpr}.
2751 This distance is determined without regarding accidentals: a
2752 @code{fisis} following a @code{ceses} will be put above the
2755 Entering scales is straightforward in relative mode.
2757 @lilypond[fragment,verbatim,center]
2759 g a b c d e f g g, g
2763 And octave changing marks are used for intervals greater than a fourth.
2765 @lilypond[fragment,verbatim,center]
2767 c g c f, c' a, e'' }
2770 If the preceding item is a chord, the first note of the chord is used
2771 to determine the first note of the next chord. But other notes
2772 within the second chord are determined by looking at the immediately
2775 @lilypond[fragment,verbatim,center]
2782 @cindex @code{\notes}
2784 The pitch after the @code{\relative} contains a notename. To parse
2785 the pitch as a notename, you have to be in note mode, so there must
2786 be a surrounding @code{\notes} keyword (which is not
2789 The relative conversion will not affect @code{\transpose} or
2790 @code{\relative} sections in its argument. If you want to use
2791 relative within transposed music, you must place an additional
2792 @code{\relative} inside the @code{\transpose}.
2795 @c . {Point and click}
2796 @node Point and click
2797 @subsection Point and click
2806 * Notation Contexts::
2807 * Creating contexts::
2808 * Default contexts::
2809 * Context properties::
2810 * Context definitions::
2813 @c . {Music expressions}
2817 @c . {Notation Contexts}
2818 @node Notation Contexts
2819 @subsection Notation Contexts
2821 @cindex notation contexts
2823 Notation contexts are objects that only exist during a run of LilyPond.
2824 During the interpretation phase of LilyPond (when lily prints
2825 "interpreting music"), music a @code{\score} block is interpreted in
2826 time order, i.e. in much the same order that humans read, play, and
2829 During this reading, the notation context is holds the state
2830 for the current point within the music. It contains information like
2833 @item What notes are playing at this point?
2834 @item What symbols will be printed at this point?
2835 @item What is the current key signature, time signature, point within
2839 Contexts are grouped hierarchically: A @code{Voice} context is
2840 contained in a @code{Staff} context (because a staff can contain
2841 multiple voices at any point), a @code{Staff} context is contained in
2842 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
2843 these can all contain multiple staffs).
2846 Contexts associated with sheet music output are called @emph{notation
2847 contexts}, those for sound output are called performance contexts.
2850 @node Creating contexts
2851 @subsection Creating contexts
2853 @cindex @code{\context}
2854 @cindex context selection
2856 Contexts for a music expression can be selected manually, using the
2857 following music expression.
2860 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
2863 This instructs lilypond to interpret @var{musicexpr} within the context
2864 of type @var{contexttype} and with name @var{contextname}. If this
2865 context does not exist, it will be created.
2871 \notes \relative c'' {
2872 c4 <d4 \context Staff = "another" e4> f
2879 In this example, the @code{c} and @code{d} are printed on the
2880 default staff. For the @code{e}, a context Staff called
2881 @code{another} is specified; since that does not exist, a new
2882 context is created. Within @code{another}, a (default) Voice context
2883 is created for the @code{e4}. When all music referring to a
2884 context is finished, the context is ended as well. So after the
2885 third quarter, @code{another} is removed.
2889 @node Default contexts
2890 @subsection Default contexts
2892 Most music expressions don't need @code{\context}: they inherit the
2893 notation context from their parent. Each note is a music expression, and
2894 as you can see in the following example, only the sequential music
2895 enclosing the three notes has an explicit context.
2898 \score { \notes \context Voice = goUp { c'4 d' e' } }
2901 There are some quirks that you must keep in mind when dealing with
2904 Every top-level music is interpreted by the Score context, in other
2905 words, you may think of @code{\score} working like
2908 \context Score @var{music}
2912 Sequential music follows the contexts of its "children". Take this example
2914 \score { \context Score \notes { c'4 ( d' )e' } }
2917 The sequential music is interpreted by the Score context initially
2918 (notice that the @code{\context} specification is redundant), but when a
2919 note is encountered, contexts are setup to accept that note. In this
2920 case, a Thread, Voice and Staff are created. The rest of the sequential
2921 music is also interpreted with the same Thread, Voice and Staff context,
2922 putting the notes on the same staff, in the same voice.
2924 This is a convenient mechanism, but do not expect opening chords to work
2925 without @code{\context}. For every note, a separate staff
2927 \score { \notes <c'4 es'> }
2930 Of course, if the chord is preceded by a normal note in sequential
2931 music, the chord will be interpreted by the Thread of the preceding
2934 \score { \notes { c'4 <c'4 es'> } }
2939 @node Context properties
2940 @subsection Context properties
2942 Notation contexts can be modified from within the @file{.ly} file. The
2943 following music expression does that job:
2945 @cindex @code{\property}
2947 \property @var{contextname}.@var{propname} = @var{value}
2950 Sets the @var{propname} property of the context @var{contextname} to the
2951 specified Scheme expression @var{value}. All @var{propname} and
2952 @var{contextname} are strings, which are typically unquoted.
2954 Properties that are set in one context are inherited by all of the
2955 contained contexts. This means that a property valid for the
2956 @code{Voice} context can be set in the @code{Score} context (for
2957 example) and thus take effect in all @code{Voice} contexts.
2962 @c . {Context definitions}
2963 @node Context definitions
2964 @subsection Context definitions
2966 @cindex context definition
2967 @cindex translator definition
2971 A notation contexts is defined by the following information
2976 @item The LilyPond modules that do the actual conversion of music to
2977 notation. Each module is a so-called
2982 @item How these modules should cooperate, i.e. which ``cooperation
2983 module'' should be used. This cooperation module is a special
2986 @item What other contexts the context can contain,
2988 @item What properties are defined.
2991 A context definition has this syntax:
2995 \translator @code{@{}
2996 @var{translatorinit} @var{translatormodifierlist}
3000 @var{translatorinit} can be an identifier or
3002 \type @var{typename} @code{;}
3004 where @var{typename} is one of
3007 @cindex @code{Engraver_group_engraver}
3008 @item @code{Engraver_group_engraver}
3009 The standard cooperation engraver.
3010 @cindex @code{Score_engraver}
3012 @item @code{Score_engraver}
3013 This is cooperation module that should be in the top level context.
3014 @cindex @code{Grace_engraver_group}
3016 @item @code{Grace_engraver_group}
3017 This is a special cooperation module (resembling
3018 @code{Score_engraver}) that is used to created an embedded
3022 @var{translatormodifierlist} is a list of items where each item is
3026 @item @code{\consists} @var{engravername} @code{;}
3027 Add @var{engravername} to the list of modules in this context.
3028 The order of engravers added with @code{\consists} is
3031 @item @code{\consistsend} @var{engravername} @code{;}
3032 Analogous to @code{\consists}, but makes sure that
3033 @var{engravername} is always added to the end of the list of
3036 Some engraver types need to be at the end of the list; this
3037 insures they are put there, and stay there, if a user adds or
3038 removes engravers. This command is usually not needed for
3041 @item @code{\accepts} @var{contextname} @code{;}
3042 Add @var{contextname} to the list of context this context can
3043 contain. The first listed context is the context to create by
3046 @item @code{\denies}. The opposite of @code{\accepts}. Added for
3047 completeness, but is never used in practice.
3050 @item @code{\remove} @var{engravername} @code{;}
3051 Remove a previously added (with @code{\consists}) engraver.
3053 @item @code{\name} @var{contextname} @code{;}
3054 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
3055 the name is not specified, the translator won't do anything.
3057 @item @var{propname} @code{=} @var{value} @code{;}
3058 A property assignment.
3061 In the @code{\paper} block, it is also possible to define translator
3062 identifiers. Like other block identifiers, the identifier can only
3063 be used as the very first item of a translator. In order to define
3064 such an identifier outside of @code{\score}, you must do
3070 foo = \translator @{ @dots{} @}
3077 \translator @{ \foo @dots{} @}
3085 @cindex paper types, engravers, and pre-defined translators
3087 Some pre-defined identifiers can simplify modification of
3088 translators. The pre-defined identifiers are:
3091 @cindex @code{StaffContext}
3092 @item @code{StaffContext}
3093 Default Staff context.
3094 @cindex @code{RhythmicStaffContext}
3096 @item @code{RhythmicStaffContext}
3097 Default RhythmicStaff context.
3098 @cindex @code{VoiceContext}
3100 @item @code{VoiceContext}
3101 Default Voice context.
3102 @cindex @code{ScoreContext}
3104 @item @code{ScoreContext}
3105 Default Score context.
3107 @cindex @code{HaraKiriStaffContext}
3109 @item @code{HaraKiriStaffContext}
3110 Staff context that does not print if it only contains rests.
3111 Useful for orchestral scores.@footnote{Harakiri, also called
3112 Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
3116 Using these pre-defined values, you can remove or add items to the
3125 \remove Some_engraver;
3126 \consists Different_engraver;
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}.
3156 @c . {Syntactic details}
3157 @node Syntactic details
3158 @section Syntactic details
3159 @cindex Syntactic details
3163 * Music expressions::
3164 * Manipulating music expressions::
3173 @subsection Top level
3176 This section describes what you may enter at top level.
3179 @unnumberedsubsec Score definition
3180 @cindex score definition
3182 The output is generated combining a music expression with an output
3183 definition. A score block has the following syntax:
3186 \score @{ @var{musicexpr} @var{outputdefs} @}
3189 @var{outputdefs} are zero or more output definitions. If no output
3190 definition is supplied, the default @code{\paper} block will be added.
3194 @subsubsection Score
3198 @subsubsection Paper
3206 @subsubsection Header
3208 @cindex @code{\header}
3213 \header @{ @var{key1} = @var{val1};
3214 @cindex @code{ly2dvi}
3215 @var{key2} = @var{val2}; @dots{} @}
3219 A header describes the file's contents. It can also appear in a
3220 @code{\score} block. Tools like @code{ly2dvi} can use this
3221 information for generating titles. Key values that are used by
3222 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
3223 metre, arranger, piece and tagline.
3225 It is customary to put the @code{\header} at the top of the file.
3227 @subsubsection Default output
3229 A @code{\midi} or @code{\paper} block at top-level sets the default
3231 paper block for all scores that lack an explicit paper block.
3235 @subsection Identifiers
3238 All of the information in a LilyPond input file, is represented as a
3239 Scheme value. In addition to normal Scheme data types (such as pair,
3240 number, boolean, etc.), LilyPond has a number of specialized data types,
3247 @item Translator_def
3251 @item Music_output_def
3252 @item Moment (rational number)
3255 LilyPond also includes some transient object types. Objects of these
3256 types are built during a LilyPond run, and do not `exist' per se within
3257 your input file. These objects are created as a result of your input
3258 file, so you can include commands in the input to manipulate them,
3259 during a lilypond run.
3262 @item Grob: short for Graphical object. See @ref{Grobs}.
3263 @item Molecule: device-independent page output object,
3264 including dimensions. Produced by some Grob functions
3266 @item Translator: object that produces audio objects or Grobs. This is
3267 not yet user accessible.
3268 @item Font_metric: object representing a font. (See @ref{Font metrics})
3273 @node Music expressions
3274 @subsection Music expressions
3276 @cindex music expressions
3278 Music in LilyPond is entered as a music expression. Notes, rests, lyric
3279 syllables are music expressions, and you can combine music expressions
3280 to form new ones, for example by enclosing a list of expressions in
3281 @code{\sequential @{ @}} or @code{< >}. In this example, a compound
3282 expression is formed out of the quarter note @code{c} and a quarter note
3286 \sequential @{ c4 d4 @}
3289 @cindex Sequential music
3290 @cindex @code{\sequential}
3291 @cindex sequential music
3294 @cindex Simultaneous music
3295 @cindex @code{\simultaneous}
3297 The two basic compound music expressions are simultaneous and
3301 \sequential @code{@{} @var{musicexprlist} @code{@}}
3302 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
3304 For both, there is a shorthand:
3306 @code{@{} @var{musicexprlist} @code{@}}
3310 @code{<} @var{musicexprlist} @code{>}
3312 for simultaneous music.
3313 Other compound music expressions include
3316 \transpose @var{pitch} @var{expr}
3317 \apply @var{func} @var{expr}
3318 \context @var{type} = @var{id} @var{expr}
3319 \times @var{fraction} @var{expr}
3322 In principle, the way in which you nest sequential and simultaneous to
3323 produce music is not relevant. In the following example, three chords
3324 are expressed in two different ways:
3326 @lilypond[fragment,verbatim,center]
3327 \notes \context Voice {
3328 <a c'> <b d' > <c' e'>
3329 < { a b c' } { c' d' e' } >
3333 However, in some cases, LilyPond will also try to choose contexts, and
3334 use the structure of the music expression to do so. This can have
3335 undesired effects: for example, LilyPond will create a separate staff
3336 for each note if you start a @code{\score} with a chord:
3337 @lilypond[verbatim,center]
3345 The solution is to explicitly instantiate the context you desire.
3346 In this case this is typically a Voice context
3347 @lilypond[verbatim,center]
3349 \notes\context Voice <c''4 e''>
3355 If you use @code{\context Staff} you will get separate stems for each
3356 note head, leading to collisions, so don't use that.
3360 @c . {Manipulating music expressions}
3361 @node Manipulating music expressions
3362 @subsection Manipulating music expressions
3364 The @code{\apply} mechanism gives you access to the internal
3365 representation of music. You can write Scheme-functions that operate
3366 directly on it. The syntax is
3368 \apply #@var{func} @var{music}
3370 This means that @var{func} is applied to @var{music}. The function
3371 @var{func} should return a music expression.
3373 This example replaces the text string of a script. It also shows a dump
3374 of the music it processes, which is useful if you want to know more
3375 about how music is stored.
3377 #(define (testfunc x)
3378 (if (equal? (ly-get-mus-property x 'text) "foo")
3379 (ly-set-mus-property x 'text "bar"))
3381 (ly-set-mus-property x 'elements
3382 (map testfunc (ly-get-mus-property x 'elements)))
3387 \apply #testfunc { c4_"foo" }
3391 For more information on what is possible, see the @ref{Tricks} and the
3392 automatically generated documentation.
3394 As always: directly accessing internal representations is dangerous: the
3395 implementation is subject to changes, so you should not use this if
3401 @subsection Assignments
3404 Identifiers allow objects to be assigned to names during the parse
3405 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
3406 and to refer to an identifier, you preceed its name with a backslash:
3407 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
3408 the input-types listed above. Identifier assignments can appear at top
3409 level in the LilyPond file, but also in @code{\paper} blocks.
3411 Semicolons are forbidden after top level assignments, but mandatory in
3412 other places. The rules about semicolons and assignments are very
3413 confusing, but when LilyPond input evolves more towards Scheme, we hope
3414 that this problem will grow smaller.
3416 An identifier can be created with any string for its name, but you will
3417 only be able to refer to identifiers whose names begin with a letter,
3418 being entirely alphabetical. It is impossible to refer to an identifier
3419 whose name is the same as the name of a keyword.
3421 The right hand side of an identifier assignment is parsed completely
3422 before the assignment is done, so it is allowed to redefine an
3423 identifier in terms of its old value, e.g.
3429 When an identifier is referenced, the information it points to is
3430 copied. For this reason, an identifier reference must always be the
3431 first item in a block.
3435 \paperIdent % wrong and invalid
3439 \paperIdent % correct
3443 @c . {Lexical details}
3444 @node Lexical details
3445 @subsection Lexical details
3446 @cindex Lexical details
3451 @subsubsection Comments
3457 A one line comment is introduced by a @code{%} character.
3458 Block comments are started by @code{%@{} and ended by @code{%@}}.
3459 They cannot be nested.
3461 @c . {Direct Scheme}
3462 @subsubsection Direct Scheme
3465 @cindex Scheme, in-line code
3468 LilyPond contains a Scheme interpreter (the GUILE library) for
3469 internal use. In some places Scheme expressions also form valid syntax:
3470 whereever it is allowed,
3474 evaluates the specified Scheme code. If this is used at toplevel, then
3475 the result is discarded. Example:
3477 \property Staff.TestObject \override #'foobar = #(+ 1 2)
3480 @code{\override} expects two Scheme expressions, so there are two Scheme
3481 expressions. The first one is a symbol (@code{foobar}), the second one
3482 an integer (namely, 3).
3484 Scheme is a full-blown programming language, and a full discussion is
3485 outside the scope of this document. Interested readers are referred to
3486 the website @uref{http://www.schemers.org/} for more information on
3491 @subsubsection Keywords
3495 Keywords start with a backslash, followed by a number of lower case
3496 alphabetic characters. These are all the keywords.
3499 apply arpeggio autochange spanrequest commandspanrequest
3500 simultaneous sequential accepts alternative bar breathe
3501 char chordmodifiers chords clef cm consists consistsend
3502 context denies duration dynamicscript elementdescriptions
3503 font grace header in lyrics key mark pitch
3504 time times midi mm name pitchnames notes outputproperty
3505 override set revert partial paper penalty property pt
3506 relative remove repeat addlyrics partcombine score
3507 script stylesheet skip textscript tempo translator
3512 @subsubsection Integers
3520 Formed from an optional minus sign followed by digits. Arithmetic
3521 operations cannot be done with integers, and integers cannot be mixed
3525 @subsubsection Reals
3526 @cindex real numbers
3532 Formed from an optional minus sign and a sequence of digits followed
3533 by a @emph{required} decimal point and an optional exponent such as
3534 @code{-1.2e3}. Reals can be built up using the usual operations:
3535 `@code{+}', `@code{-}', `@code{*}', and
3536 `@code{/}', with parentheses for grouping.
3544 A real constant can be followed by one of the dimension keywords:
3545 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
3546 points, inches and centimeters, respectively. This converts the number
3547 to a real that is the internal representation of dimensions.
3551 @subsubsection Strings
3555 Begins and ends with the @code{"} character. To include a @code{"}
3556 character in a string write @code{\"}. Various other backslash
3557 sequences have special interpretations as in the C language. A string
3558 that contains no spaces can be written without the quotes. See
3559 @ref{Lexical modes} for details on unquoted strings; their
3560 interpretation varies depending on the situation. Strings can be
3561 concatenated with the @code{+} operator.
3563 The tokenizer accepts the following commands. They have no grammatical
3564 function, hence they can appear anywhere in the input.
3568 @subsubsection Main input
3571 @cindex @code{\maininput}
3573 The @code{\maininput} command is used in init files to signal that the
3574 user file must be read. This command cannot be used in a user file.
3576 @c . {File inclusion}
3577 @subsubsection Main input
3580 @subsubsection File inclusion
3581 @cindex @code{\include}
3583 \include @var{filename}
3586 Include @var{filename}. The argument @var{filename} may be a quoted string (an
3587 unquoted string will not work here!) or a string identifier. The full
3588 filename including the @file{.ly} extension must be given,
3590 @subsubsection Version information
3591 @cindex @code{\version}
3593 \version @var{string} ;
3596 Specify the version of LilyPond that a file was written for. The
3597 argument is a version string in quotes, for example @code{"1.2.0"}.
3598 This is used to detect invalid input, and to aid
3599 @code{convert-ly} a tool that automatically upgrades input files. See
3600 See @ref{convert-ly} for more information on @code{convert-ly}.
3606 @subsubsection Defining pitch names
3607 @cindex Lexical modes
3608 @cindex definining pitch names
3609 @cindex pitch names, definining
3611 @cindex chord modifier names
3613 A @code{\paper} block at top level sets the default paper block. A
3614 @code{\midi} block at top level works similarly.
3617 @subsubsection Assignments
3621 Identifier assignments may appear at top level. @ref{Assignments}
3625 @c . {Direct scheme}
3626 @subsubsection Direct scheme
3627 @cindex Direct scheme
3629 Scheme statements maybe issued to produce interesting side-effects.
3632 @c . {Lexical modes}
3634 @subsection Lexical modes
3635 @cindex Lexical modes
3638 @cindex @code{\notes}
3639 @cindex @code{\chords}
3640 @cindex @code{\lyrics}
3642 To simplify entering notes, lyrics, and chords, LilyPond has three
3643 special input modes on top of the default mode: note, lyrics and chords
3644 mode. These input modes change the way that normal, unquoted words are
3645 interpreted: for example, the word @code{cis} may be interpreted as a
3646 C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
3649 A mode switch is entered as a compound music expressions
3651 @code{\notes} @var{musicexpr}
3652 @code{\chords} @var{musicexpr}
3653 @code{\lyrics} @var{musicexpr}.
3656 In each of these cases, these expressions do not add anything to the
3657 meaning of their arguments. They are just a way to indicate that the
3658 arguments should be parsed in indicated mode. The modes are treated in
3659 more detail in the sections @ref{Note entry}, @ref{Lyrics} and
3662 You may nest different input modes.
3666 @subsection Ambiguities
3671 The grammar contains a number of ambiguities. We hope to resolve them at
3675 @item The assignment
3681 can be interpreted as making a string identifier @code{\foo}
3682 containing @code{"bar"}, or a music identifier @code{\foo}
3683 containing the syllable `bar'.
3685 @item The assignment
3691 can be interpreted as making an integer identifier
3692 containing -6, or a Request identifier containing the
3693 fingering `6' (with neutral direction).
3695 @item If you do a nested repeat like
3707 then it is ambiguous to which @code{\repeat} the
3708 @code{\alternative} belongs. This is the classic if-then-else
3709 dilemma. It may be solved by using braces.
3711 @item (an as yet unidentified ambiguity :-)
3726 @unnumberedsubsec Translation property
3729 [todo: add \set/\override/\revert]
3733 @cindex output properties
3734 @unnumberedsubsec Output properties
3736 These allow you to tweak what is happening in the back-end
3737 directly. If you want to control every detail of the output
3738 formatting, this is the feature to use. The downside to this is that
3739 you need to know exactly how the backend works. Example:
3742 @lilypond[fragment,verbatim]
3744 \context Staff \outputproperty
3745 #(make-type-checker 'note-head-interface)
3746 #'extra-offset = #'(0.5 . 0.75)
3750 This selects all note heads occurring at current staff level, and sets
3751 the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting
3754 Use of this feature is entirely on your own risk: if you use this, the
3755 result will depend very heavily on the implementation of the backend,
3756 which we change regularly and unscrupulously.
3759 Don't move the finger 2, only text "m.d." ...
3761 #(define (make-text-checker text)
3762 (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
3765 \notes\relative c''' {
3766 \property Voice.Stem \set #'direction = #1
3767 \outputproperty #(make-text-checker "m.d.")
3768 #'extra-offset = #'(-3.5 . -4.5)
3771 \paper { linewidth = -1.; }
3781 @subsection Text markup
3785 LilyPond has an internal mechanism to typeset texts: you can
3786 form text markup expressions by composing scheme expressions
3787 in the following way:
3790 \score { \notes \relative c' {
3793 d-#'(lines "one" (bold "text"))
3794 e-#'(music (named "noteheads-2" "flags-u3"))
3796 \paper { linewidth = 10.\cm; } }
3799 Formally, Scheme markup text is defined as follows:
3802 text: string | (head? text+)
3803 head: markup | (markup+)
3804 markup-item: property | abbrev | @var{fontstyle}
3805 property: (@var{key} . @var{value})
3806 abbrev: @code{rows lines roman music bold italic named super sub text}
3809 The markup is broken down and converted into a list of grob properties,
3810 which are prepended to the grop's property list. The
3811 @var{key}-@var{value} pair is a grob property.
3813 [Why is this useful?]
3815 ?Snapnie: markup text is eerste item dat voldoet aan mijn gewelfdige,
3816 ideale idee van direct-en-eenmalig-per-item te zetten properties, ipv
3817 gehaspel via \property en hopen dat je property (enkel) in juiste item
3818 terecht gaat komen. Heb je deze wel bewust meegemaakt:
3820 Sender: jan@appel.lilypond.org
3821 To: Han-Wen <hanwen@cs.uu.nl>
3822 Subject: (elt) properties
3823 Organization: Jan at Appel
3824 From: janneke@gnu.org
3825 Date: 01 Nov 2000 10:39:10 +0100
3826 Message-ID: <m3og00av5t.fsf@appel.lilypond.org>
3827 User-Agent: Gnus/5.0807 (Gnus v5.8.7) Emacs/20.7
3829 Content-Type: text/plain; charset=us-ascii
3831 Xref: appel.lilypond.org vers:1991
3835 Wat ik vooral mis, is een koele manier om een propertie eenmalig aan
3836 een element te hangen. Hoop dat je zinvol over wilt meedenken; zie
3837 het monster van les-nereides. Misschien dat we 't niet moeten doen
3838 voor 1.4 maar wachten tot properties nog wat verder
3839 uitgekristalliseerd zijn?
3843 \property Voice.Stem \push #'length = #'6
3845 \property Voice.Stem \pop #'length
3848 waarmee je in feite zeg tegen de stem-engraver: vanaf nu aan moet je
3849 alle stems 6 lang maken (maakt stem); onee, doe maar weer default
3852 Maar dat is eigenlijk niet wat je bedoelt, wat je zou willen is net
3853 zo'n directe interface als wat we nu hebben voor markup text, bv. iets
3856 a+#'(Stem::length . 6) b
3858 Bij markup text kun je direct en eenmalig een reeks properties aan een
3859 enkel item toevoegen; iets wat je volgens mij vaak nodig hebt.
3861 Ik zat eerst te denken aan ``request properties'': properties
3862 toevoegen aan request, die dan worden doorgegeven aan alle items die
3863 door dat request worden gemaakt.
3865 Maar misschien zuigt dat wel te vreselijk en moeten we iets van
3866 ``volatile'' properties maken.
3870 \property Voice.Slur \push #'dash = #1
3871 \property Voice.Slur \pop #'dash
3873 \property Voice.Slur \push #'direction = #-1
3874 \property Voice.Slur \pop #'direction
3877 of de kluts waar ik brr van word, eigenlijk ook alleen doenbaar is
3878 voor wat veelgebruikte properties:
3880 slurDotted = \property Voice.Slur \push #'dash = #1
3881 slurNoDots = \property Voice.Slur \pop #'dash
3882 slurUp = \property Voice.Slur \push #'direction = #1
3883 slurDown = \property Voice.Slur \push #'direction = #-1
3884 slurBoth = \property Voice.Slur \pop #'direction
3888 \slurDotted\slurDown
3891 \slurNoDots\slurBoth
3893 zou toch graag meer iets in trant van, als je begrijpt wat ik bedoel
3895 Slur+#'((dash . 1) (direction . 1))
3897 Slur-#'(dash direction)
3901 a(+#'((dash . 1) (direction . 1))
3902 )b(+#'((dash . 1) (direction . 1))
3906 The following abbreviations are currently
3911 horizontal mode: set all text on one line (default)
3913 vertical mode: set every text on new line
3923 lookup by character name
3925 plain text lookup (by character value)
3933 @var{fontstyle} may be any of @code{finger volta timesig mmrest mark
3934 script large Large dynamic}
3938 Wat is daarmee, zijn toch gewoon grob properties van text-interface?
3941 @c .{Local emacs vars}
3944 @c minor-mode: font-lock
3945 @c minor-mode: outline
3946 @c outline-layout: (-1 : 0)
3947 @c outline-use-mode-specific-leader: "@c \."
3948 @c outline-primary-bullet: "{"
3949 @c outline-stylish-prefixes: nil
3950 @c outline-override-protect: t