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)
19 postscript, scheme output?
21 (links to?) using/existance of ly2dvi, lilypond-book
26 @c .{Reference Manual}
28 @node Reference Manual
29 @chapter Reference Manual
31 This document describes GNU LilyPond and its input format. This document
32 has been revised for LilyPond 1.3.125
62 The purpose of LilyPond is explained informally by the term `music
63 typesetter'. This is not a fully correct name: not only does the
64 program print musical symbols, it also makes esthetic decisions. All
65 symbols and their placement is @emph{generated} from a high-level
66 musical description. In other words, LilyPond would be best described
67 by `music compiler' or `music to notation compiler'.
69 Internally, LilyPond is written in a mixture of Scheme and C++. Most of
70 the algorithms and low-level routines are written in C++, but these low
71 level components are glued together using Scheme data
72 structures. LilyPond is linked to GUILE, GNU's Scheme library for
75 When lilypond is run to typeset sheet music, the following happens:
78 @item GUILE Initialization: various scheme files are read
79 @item parsing: first standard .ly initialization files are read, and
80 then the user @file{.ly} file is read.
81 @item interpretation: the music in the file is processed "in playing
82 order", i.e. in the same order as your eyes scan sheet music, and in the
83 same order that you hear the notes play.
86 in this step, the results of the interpretation, a typesetting
87 specification, is solved.
89 @item the visible results ("virtual ink") is written to the output file.
92 These stages, involve data of a specific type: during parsing,
93 @strong{Music} objects are created. During the interpretation,
94 @strong{context} is constructed, and with this context af network of
95 @strong{graphical objects} (``grobs'') is created. The grobs contain
96 unknown variables, and the network forms a set of equations. After
97 solving the equations and filling in these variables, the printed output
98 (in the form of @strong{molecules}) is written to an output file.
100 These threemanship of tasks (parsing, translating, typesetting) and
101 data-structures (music, context, graphical objects) permeates the entire
102 design of the program. This manual is ordered in terms of user
103 tasks. With each concept will be explained to which of the three parts
106 LilyPond input can be classified into three types:
108 @item musical expressions: a musical expression is some combination of
110 @item output definitions: recipes for translating those musical
111 expressions into performances (MIDI) or graphics (eg. PostScript).
113 @item declarations: by declaring and naming musical expressions, you
114 can enter and edit them in manageable chunks.
119 @c . {Modifying music}
120 @node Modifying music
121 @section Modifying music
122 @cindex Modifying music
124 FIXME: more verbose titling:
128 Repeating music expressions?
138 Apply allows a Scheme-function to operate directly on the internal
139 representation of music.
141 \apply #@var{func} @var{music}
143 The function takes two arguments, being a function and an musical
144 argument for that function. The function should return a music
147 This example replaces the text string of a script. It also shows a dump
148 of the music it processes.
150 #(define (testfunc x)
151 (if (equal? (ly-get-mus-property x 'text) "foo")
152 (ly-set-mus-property x 'text "bar"))
154 (ly-set-mus-property x 'elements
155 (map testfunc (ly-get-mus-property x 'elements)))
160 \apply #testfunc { c4_"foo" }
164 For more information on what is possible, see the @ref{Tricks} and the
165 automatically generated documentation.
175 @cindex @code{\repeat}
177 In order to specify repeats, use the @code{\repeat}
178 keyword. Since repeats look and sound differently when played or
179 printed, there are a few different variants of repeats.
183 Repeated music is fully written (played) out. Useful for MIDI
187 This is the normal notation: Repeats are not written out, but
188 alternative endings (voltas) are printed, left to right.
191 Alternative endings are written stacked. Which is unfortunately not
192 practical for anything right now.
200 * Manual repeat commands::
202 * Tremolo subdivision::
206 @subsection Repeat syntax
208 The syntax for repeats is
211 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
214 If you have alternative endings, you may add
216 @cindex @code{\alternative}
218 \alternative @code{@{} @var{alternative1}
220 @var{alternative3} @dots{} @code{@}}
223 where each @var{alternative} is a Music expression.
225 Normal notation repeats are used like this:
229 @lilypond[fragment,verbatim]
231 \repeat volta 2 { c'4 d' e' f' }
232 \repeat volta 2 { f' e' d' c' }
236 With alternative endings:
240 @lilypond[fragment,verbatim]
242 \repeat volta 2 {c'4 d' e' f'}
243 \alternative { {d'2 d'} {f' f} }
247 Folded repeats look like this:@footnote{Folded repeats offer little
248 more over simultaneous music. However, it is to be expected that
249 more functionality -- especially for the MIDI backend -- will be
250 implemented at some point in the future.}
254 @lilypond[fragment,verbatim]
256 \repeat fold 2 {c'4 d' e' f'}
257 \alternative { {d'2 d'} {f' f} }
263 If you don't give enough alternatives for all of the repeats, then
264 the first alternative is assumed to be repeated often enough to equal
265 the specified number of repeats.
268 @lilypond[fragment,verbatim]
272 \repeat volta 3 { e | c2 d2 | e2 f2 | }
273 \alternative { { g4 g g } { a | a a a a | b2. } }
281 As you can see, LilyPond doesn't remember the timing information, nor
282 are slurs or ties repeated, so you have to reset timing information
283 after a repeat, eg using bar-checks, @code{Score.measurePosition} or
284 @code{\partial}. We hope to fix this after 1.4.
286 It is possible to nest @code{\repeat}, although it probably is only
287 meaningful for unfolded repeats.
289 @node Manual repeat commands
290 @subsection Manual repeat commands
292 @cindex @code{repeatCommands}
294 The property @code{repeatCommands} can be used to control the layout of
295 repeats. Its value is a Scheme list of repeat commands, where each repeat
303 @item (volta . @var{text})
304 Print a volta bracket saying @var{text}.
306 Stop a running volta bracket
309 @lilypond[verbatim, fragment]
311 \property Score.repeatCommands = #'((volta "93") end-repeat)
313 \property Score.repeatCommands = #'((volta #f))
318 @node Tremolo repeats
319 @subsection Tremolo repeats
320 @cindex tremolo beams
322 To place tremolo marks between notes, use @code{\repeat} with tremolo
324 @lilypond[verbatim,center]
326 \context Voice \notes\relative c' {
327 \repeat "tremolo" 8 { c16 d16 }
328 \repeat "tremolo" 4 { c16 d16 }
329 \repeat "tremolo" 2 { c16 d16 }
330 \repeat "tremolo" 4 c16
333 linewidth = 40*\staffspace;
338 @node Tremolo subdivision
339 @subsection Tremolo subdivision
340 @cindex tremolo marks
341 @cindex @code{tremoloFlags}
343 Tremolo marks can be printed on a single note by adding
344 `@code{:}[@var{length}]' after the note. The length must be at least 8.
345 A @var{length} value of 8 gives one line across the note stem. If the
346 length is omitted, then the last value is used, or the value of the
347 @code{tremoloFlags} property if there was no last value.
349 @lilypond[verbatim,fragment,center]
353 Tremolos in this style do not carry over into the MIDI output.
355 Using this mechanism pays off when you entering many tremolos, since the
356 default argument saves a lot of typing.
367 * Defining pitch names::
376 @subsection Notes mode
380 @cindex @code{\notes}
381 Note mode is introduced by the keyword
382 @code{\notes}. In Note mode, words can only
383 contain alphabetic characters. If @code{word} is encountered,
384 LilyPond first checks for a notename of @code{word}. If no
385 notename is found, then @code{word} is treated as a string.
387 Since combinations of numbers and dots are used for indicating
388 durations, it is not possible to enter real numbers in this mode.
397 @cindex Note specification
399 @cindex entering notes
401 The verbose syntax for pitch specification is
403 @cindex @code{\pitch}
405 \pitch @var{scmpitch}
408 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
410 In Note and Chord mode, pitches may be designated by names. The default
411 names are the Dutch note names. The notes are specified by the letters
412 @code{c} through @code{b}, where @code{c} is an octave below middle C
413 and the letters span the octave above that C. In Dutch,
414 @cindex note names, Dutch
415 a sharp is formed by adding @code{-is} to the end of a pitch name. A
416 flat is formed by adding @code{-es}. Double sharps and double flats are
417 obtained by adding @code{-isis} or @code{-eses}. @code{aes} and
418 @code{ees} are contracted to @code{as} and @code{es} in Dutch, but both
419 forms will be accepted.
421 LilyPond has predefined sets of notenames for various other languages.
422 To use them, simply include the language specific init file. For
423 example: @code{\include "english.ly"}. The available language files and
424 the names they define are:
427 Note Names sharp flat
428 nederlands.ly c d e f g a bes b -is -es
429 english.ly c d e f g a bf b -s/-sharp -f/-flat
430 deutsch.ly c d e f g a b h -is -es
431 norsk.ly c d e f g a b h -iss/-is -ess/-es
432 svenska.ly c d e f g a b h -iss -ess
433 italiano.ly do re mi fa sol la sib si -d -b
434 catalan.ly do re mi fa sol la sib si -d/-s -b
443 The optional octave specification takes the form of a series of
444 single quote (`@code{'}') characters or a series of comma
445 (`@code{,}') characters. Each @code{'} raises the pitch by one
446 octave; each @code{,} lowers the pitch by an octave.
448 @lilypond[fragment,verbatim,center]
449 c' d' e' f' g' a' b' c''
452 @lilypond[fragment,verbatim,center]
453 cis' dis' eis' fis' gis' ais' bis'
456 @lilypond[fragment,verbatim,center]
457 ces' des' es' fes' ges' as' bes'
460 @lilypond[fragment,verbatim,center]
461 cisis' eisis' gisis' aisis' beses'
464 @lilypond[fragment,verbatim,center]
465 ceses' eses' geses' ases' beses'
469 @c . {Defining pitch names}
470 @node Defining pitch names
471 @subsection Defining pitch names
473 @cindex defining pitch names
474 @cindex pitch names, defining
476 Note names and chord modifiers can be customised for nationalities. The
477 syntax is as follows.
479 @cindex @code{\pitchnames}
480 @cindex @code{\chordmodifiers}
482 \pitchnames @var{scheme-alist}
483 \chordmodifiers @var{scheme-alist}
486 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
487 specific examples how to do this. Some national note names have been
488 provided, among others: Norwegian, Swedish, German, Italian, Catalan,
489 French, Dutch and English.
494 @subsection Durations
498 @cindex @code{\duration}
500 The syntax for an verbose duration specification is
502 \duration @var{scmduration}
505 In Note, Chord, and Lyrics mode, durations may be designated by numbers
506 and dots: durations are entered as their reciprocal values. For notes
507 longer than a whole note, use identifiers.
513 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
515 r1 r2 r4 r8 r16 r32 r64 r64
521 \notes \relative c'' {
522 a\longa a\breve \autoBeamOff
523 a1 a2 a4 a8 a16 a32 a64 a64
525 r1 r2 r4 r8 r16 r32 r64 r64
530 \remove "Clef_engraver";
531 \remove "Staff_symbol_engraver";
532 \remove "Time_signature_engraver";
533 \consists "Pitch_squash_engraver";
540 As you can see, the longa is not printed. To get a longa note head, you
541 have to use a different style of note heads. See [TODO].
543 If the duration is omitted then it is set equal to the previous duration
544 entered. At the start of parsing there is no previous duration, so then
545 a quarter note is assumed. The duration can be followed by a dot
546 (`@code{.}') to obtain dotted note lengths.
549 @lilypond[fragment,verbatim,center]
555 You can alter the length of duration by writing `@code{*}@var{fraction}'
556 after it. This will not affect the appearance of note heads or rests.
562 A note specification has the form
565 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
569 LilyPond will determine what accidentals to typeset depending on the key
570 and context, so alteration refer to what note is heard, not to whether
571 accidentals are printed. A reminder accidental
572 @cindex reminder accidental
574 can be forced by adding an exclamation mark @code{!} after the pitch.
575 A cautionary accidental,
576 @cindex cautionary accidental
578 i.e., an accidental within parentheses can be obtained by adding the
579 question mark `@code{?}' after the pitch.
581 @lilypond[fragment,verbatim,center]
582 cis' d' e' cis' c'? d' e' c'!
591 Rests are entered like notes, with note name `@code{r}'.
592 There is also a note name
593 `@code{s}', which produces a space of the specified
604 \skip @var{duration} @code{;}
608 Skips the amount of time specified by @var{duration}. If no other
609 music is played, a gap will be left for the skipped time with no
610 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
611 this has the same effect as the spacer rest.
615 @c . {Music notation}
617 @section Music notation
618 @cindex Music notation
632 @code{\key} @var{pitch} @var{type} @code{;}
634 @cindex @code{\minor}
635 @cindex @code{\major}
636 @cindex @code{\minor}
637 @cindex @code{\ionian}
638 @cindex @code{\locrian}
639 @cindex @code{\aeolian}
640 @cindex @code{\mixolydian}
641 @cindex @code{\lydian}
642 @cindex @code{\phrygian}
643 @cindex @code{\dorian}
645 Change the key signature. @var{type} should be @code{\major} or
646 @code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
647 respectively. The second argument is optional; the default is major
648 keys. The @var{\context} argument can also be given as an integer,
649 which tells the number of semitones that should be added to the pitch
650 given in the subsequent @code{\key} commands to get the corresponding
651 major key, e.g., @code{\minor} is defined as 3. The standard mode names
652 @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
653 @code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
655 This command sets @code{Staff.keySignature}.
657 @cindex @code{keySignature}
660 @subsubsection Clef changes
663 \clef @var{clefname} @code{;}
669 \property Staff.clefGlyph = @var{symbol associated with clefname}
670 \property Staff.clefPosition = @var{clef Y-position for clefname}
671 \property Staff.clefOctavation = @var{extra pitch of clefname}
674 Supported clef-names include
677 @item treble, violin, G, G2: G clef on 2nd line
678 @item french: G clef on 1st line
679 @item soprano: C clef on 1st line
680 @item mezzosoprano: C clef on 2nd line
681 @item alto: C clef on 3rd line
682 @item tenor: C clef on 4th line
683 @item baritone: C clef on 5th line
684 @item varbaritone: F clef on 3rd line
685 @item bass, F: F clef on 4th line
686 @item subbass: F clef on 5th line
687 @item percussion: percussion clef
690 [todo: ancient clefs]
692 Supported associated symbols (for Staff.clefGlyph) are:
695 @item clefs-C: modern style C clef
696 @item clefs-F: modern style F clef
697 @item clefs-G: modern style G clef
698 @item clefs-vaticana_do: Editio Vaticana style do clef
699 @item clefs-vaticana_fa: Editio Vaticana style fa clef
700 @item clefs-medicaea_do: Editio Medicaea style do clef
701 @item clefs-medicaea_fa: Editio Medicaea style fa clef
702 @item clefs-mensural1_c: modern style mensural C clef
703 @item clefs-mensural2_c: historic style small mensural C clef
704 @item clefs-mensural3_c: historic style big mensural C clef
705 @item clefs-mensural1_f: historic style traditional mensural F clef
706 @item clefs-mensural2_f: historic style new mensural F clef
707 @item clefs-mensural_g: historic style mensural G clef
708 @item clefs-hufnagel_do: historic style hufnagel do clef
709 @item clefs-hufnagel_fa: historic style hufnagel fa clef
710 @item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef
711 @item clefs-percussion: modern style percussion clef
714 @emph{Modern style} means "as is typeset in current editions".
715 @emph{Historic style} means "as was typeset or written in contemporary
716 historic editions". @emph{Editio XXX style} means "as is/was printed in
719 @c . {Time signature}
721 @subsection Time signature
722 @cindex Time signature
727 \time @var{numerator}@code{/}@var{denominator} @code{;}
730 A short-cut for doing
732 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
735 See the documentation of @code{timeSignatureFraction}
739 @subsubsection Partial
743 @cindex partial measure
744 @cindex measure, partial
745 @cindex shorten measures
746 @cindex @code{\partial}
748 \partial @var{duration} @code{;}
754 \property Score.measurePosition = @var{length of duration}
758 See the documentation of @code{measurePosition}.
766 [todo : collisiosn, rest-collisinos, voiceX identifiers, how to
767 which contexts to instantiate.]
771 @cindex @code{\shiftOff}
772 @item @code{\shiftOff}
773 Disable horizontal shifting of note heads that collide.
775 @cindex @code{\shiftOn}
776 @item @code{\shiftOn}
777 Enable note heads that collide with other note heads to be
778 shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
779 set different shift values.
781 @cindex @code{\stemBoth}
782 @item @code{\stemBoth}
783 Allow stems, beams, and slurs to point either upwards or
784 downwards, decided automatically by LilyPond.
786 @cindex @code{\stemDown}
787 @item @code{\stemDown}
788 Force stems, beams, and slurs to point down.
790 @cindex @code{\stemUp}
792 Force stems, beams and slurs to point up.
817 @c . {Automatic beams}
818 @subsubsection Automatic beams
821 @cindex automatic beam generation
823 @cindex @code{Voice.noAutoBeaming}
825 LilyPond will group flagged notes and generate beams autmatically, where
828 This feature can be disabled by setting the @code{Voice.noAutoBeaming}
829 property to true, which you may find necessary for the melody that goes
830 with lyrics, eg. Automatic beaming can easily be overridden for
831 specific cases by specifying explicit beams. This is discussed in the
836 @cindex @code{Voice.autoBeamSettings}
837 @cindex @code{(end * * * *)}
838 @cindex @code{(begin * * * *)}
840 A large number of Voice properties are used to decide how to generate
841 beams. Their default values appear in @file{scm/auto-beam.scm}. In
842 general, beams can begin anywhere, but their ending location is
843 significant. Beams can end on a beat, or at durations specified by the
844 properties in @code{Voice.autoBeamSettings}. To end beams every quarter
845 note, for example, you could set the property @code{(end * * * *)} to
846 @code{(make-moment 1 4)}. To end beams at every three eighth notes you
847 would set it to @code{(make-moment 1 8)}. The same syntax can be used
848 to specify beam starting points using @code{(begin * * * *)}, eg:
851 \property Voice.autoBeamSettings \override
852 #'(end * * * *) = #(make-moment 1 4)
853 \property Voice.autoBeamSettings \override
854 #'(begin * * * *) = #(make-moment 1 8)
858 To allow different settings for different time signatures, instead of
859 the first two asterisks @code{* *} you can specify a time signature; use
860 @code{(end N M * *)} to restrict the definition to
861 `@var{N}@code{/}@var{M}' time. For example, to specify beams ending
862 only for 6/8 time you would use the property @code{(end 6 8 * *)}.
864 To allow different endings for notes of different durations, instead of
865 th last two asterisks you can specify a duration; use @code{(end * * N
866 M)} to restrict the definition to beams that contain notes of
867 `@var{N}@code{/}@var{M}' duration.
869 For example, to specify beam endings for beams that contain 32nd notes,
870 you would use @code{(end * * 1 32)}.
875 @cindex Automatic beams
876 @subsubsection Manual beams
877 @cindex beams, manual
881 In some cases it may be necessary to override LilyPond's automatic
882 beaming algorithm. For example, the auto beamer will not beam over
883 rests or bar lines, so if you want that, specify the begin and end point
884 manually using @code{[} and @code{]}:
887 @lilypond[fragment,relative,verbatim]
889 r4 [r8 g'' a r8] r8 [g | a] r8
894 @cindex @code{stemLeftBeamCount}
896 If you have specific wishes for the number of beams, you can fully
897 control the number of beams through the properties
898 y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
900 @lilypond[fragment,relative,verbatim]
903 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
907 @cindex @code{stemRightBeamCount}
910 @c . {Adjusting beams}
911 @unnumberedsubsubsec Adjusting beams
912 @cindex Adjusting beams
928 A slur connects chords and is used to indicate legato. Slurs avoid
929 crossing stems. A slur is started with @code{(} and stopped with
930 @code{)}. The starting @code{(} appears to the right of the first note
931 in the slur. The terminal @code{)} appears to the left of the last note
932 in the slur. This makes it possible to put a note in slurs from both
935 @lilypond[fragment,verbatim,center]
936 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
939 @c . {Adjusting slurs}
940 @unnumberedsubsubsec Adjusting slurs
943 @node Slur attachments
944 @subsubsection Slur attachments
946 The ending of a slur should whenever possible be attached to a note
947 head. Only in some instances where beams are involved, LilyPond may
948 attach a slur to a stem end. In some cases, you may want to override
949 LilyPond's decision, e.g., to attach the slur to the stem end. This can
950 be done through @code{Voice.Slur}'s grob-property @code{attachment}:
954 @lilypond[fragment,relative,verbatim]
955 \property Voice.Slur \set #'direction = #1
956 \property Voice.Stem \set #'length = #5.5
958 \property Voice.Slur \set #'attachment = #'(stem . stem)
963 Similarly, slurs can be attached to note heads even when beams are
967 @lilypond[fragment,relative,verbatim]
968 \property Voice.Slur \set #'direction = #1
969 \property Voice.Slur \set #'attachment = #'(head . head)
970 g''16()g()g()g()d'()d()d()d
974 If a slur would strike through a stem or beam, LilyPond will move the
975 slur away vertically (upward or downward). In some cases, this may
976 cause ugly slurs that you may want to correct:
979 @lilypond[fragment,relative,verbatim]
980 \property Voice.Stem \set #'direction = #1
981 \property Voice.Slur \set #'direction = #1
983 \property Voice.Slur \set #'attachment = #'(stem . stem)
988 LilyPond will increase the curvature of a slur trying to stay free of
989 note heads and stems. However, if the curvature would increase too much,
990 the slur will be reverted to its default shape. This decision is based
991 on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
992 cases, you may find ugly slurs beautiful, and tell LilyPond so by
993 increasing the @code{beautiful} value:
995 [hoe gedefd?? wat betekent beautiful = X?]
1000 \notes \context PianoStaff <
1002 \context Staff=up { s1 * 6/4 }
1003 \context Staff=down <
1005 \autochange Staff \context Voice
1006 \notes \relative c {
1007 d,8( a' d f a d f d a f d )a
1015 Slur \override #'beautiful = #5.0
1016 Slur \override #'direction = #1
1017 Stem \override #'direction = #-1
1018 autoBeamSettings \override #'(end * * * *)
1019 = #(make-moment 1 2)
1023 VerticalAlignment \override #'threshold = #'(5 . 5)
1030 @cindex Adusting slurs
1034 @c . {Phrasing slur}
1036 @subsection Phrasing slur
1037 @cindex phrasing slur
1038 @cindex phrasing mark
1040 A phrasing slur (or phrasing mark) connects chords and is used to
1041 indicate a musical sentence. Phrasing slurs avoid crossing stems. A
1042 phrasing slur is started with @code{\(} and stopped with @code{\)}. The
1043 starting @code{\(} appears to the right of the first note in the
1044 phrasing slur. The terminal @code{\)} appears to the left of the last
1045 note in the phrasing slur.
1047 @lilypond[fragment,verbatim,center,relative]
1048 \time 6/4; c''\((d)e f(e)\)d
1068 A tie connects two adjacent note heads of the same pitch. When used
1069 with chords, it connects all of the note heads whose pitches match.
1070 Ties are indicated using the tilde symbol `@code{~}'.
1071 If you try to tie together chords which have no common pitches, a
1072 warning message will appear and no ties will be created.
1074 @lilypond[fragment,verbatim,center]
1075 e' ~ e' <c' e' g'> ~ <c' e' g'>
1083 @subsubsection Tuplets
1087 Tuplets are made out of a music expression by multiplying their duration
1090 @cindex @code{\times}
1092 \times @var{fraction} @var{musicexpr}
1095 The duration of @var{musicexpr} will be multiplied by the fraction.
1096 In print, the fraction's denominator will be printed over the notes,
1097 optionally with a bracket. The most common tuplet is the triplet in
1098 which 3 notes have the length of 2, so the notes are 2/3 of
1099 their written length:
1101 @lilypond[fragment,verbatim,center]
1102 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1105 [todo: document tupletSpannerDuration]
1111 @subsubsection Text spanner
1112 @cindex Text spanner
1116 @subsubsection Ottava
1118 @unnumberedsubsubsec Ottava
1120 [move to trick. Not a supported feature.]
1122 @lilypond[fragment,relative,verbatim]
1124 \property Voice.TextSpanner \set #'type = #'dotted-line
1125 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1126 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1127 \property Staff.centralCPosition = #-13
1128 a\spanrequest \start "text" b c a \spanrequest \stop "text"
1133 @c . {Span requests}
1135 @subsubsection Span requests
1136 @cindex Span requests
1138 @cindex @code{\spanrequest}
1141 \spanrequest @var{startstop} @var{type}
1143 @cindex @code{\start}
1144 @cindex @code{\stop}
1146 Define a spanning request. The @var{startstop} parameter is either -1
1147 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
1148 describes what should be started. Supported types are @code{crescendo},
1149 @code{decrescendo}, @code{beam}, @code{slur}. [FIXME: many more] This
1150 is an internal command. Users should use the shorthands which are
1151 defined in the initialization file @file{spanners.ly}.
1153 You can attach a (general) span request to a note using
1155 @lilypond[fragment,verbatim,center]
1156 c'4-\spanrequest \start "slur"
1157 c'4-\spanrequest \stop "slur"
1160 The slur syntax with parentheses is a shorthand for this.
1165 @subsection Ornaments
1174 @subsubsection Articulation
1175 @cindex Articulation
1177 @cindex articulations
1181 A variety of symbols can appear above and below notes to indicate
1182 different characteristics of the performance. These symbols can be
1183 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1184 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1185 forced to appear above or below the note by writing
1186 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1187 respectively. Here is a chart showing symbols above notes, with the
1188 name of the corresponding symbol appearing underneath.
1194 \property Score.LyricSyllable \override #'font-family =
1196 \property Score.LyricSyllable \override #'font-shape = #'upright
1197 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1198 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1199 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1200 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1201 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1202 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1203 c''-\thumb c''-\segno c''-\coda
1205 \context Lyrics \lyrics {
1206 accent__ marcato__ staccatissimo__ fermata
1207 stopped__ staccato__ tenuto__ upbow
1208 downbow__ lheel__ rheel__ ltoe
1209 rtoe__ turn__ open__ flageolet
1210 reverseturn__ trill__ prall__ mordent
1211 prallprall__ prallmordent__ uprall__ downprall
1212 thumb__ segno__ coda
1216 linewidth = 5.875\in;
1225 @subsubsection Text scripts
1226 @cindex Text scripts
1230 In addition, it is possible to place arbitrary strings of text or
1231 @TeX{} above or below notes by using a string instead of an
1232 identifier: @code{c^"text"}. Fingerings
1233 can be placed by simply using digits. All of these note ornaments
1234 appear in the printed output but have no effect on the MIDI rendering of
1238 @unnumberedsubsubsec Fingerings
1241 To save typing, fingering instructions (digits 0 to 9 are
1242 supported) and single characters shorthands exist for a few
1247 \notes \context Voice {
1248 \property Voice.TextScript \set #'font-family = #'typewriter
1249 \property Voice.TextScript \set #'font-shape = #'upright
1255 c''4-^_"c-\\^{ }" s4
1262 linewidth = 5.875 \in;
1270 @cindex @code{\textscript}
1274 \textscript @var{text} @var{style}
1277 Defines a text to be printed over or under a note. @var{style} is a
1278 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1279 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1281 You can attach a general textscript request using this syntax:
1286 c4-\textscript "6" "finger"
1287 c4-\textscript "foo" "normal"
1292 This is equivalent to @code{c4-6 c4-"foo"}.
1294 @cindex @code{\script}
1303 Prints a symbol above or below a note. The argument is a string which
1304 points into the script-alias table defined in @file{scm/script.scm}.
1305 Usually the @code{\script} keyword is not used directly. Various
1306 helpful identifier definitions appear in @file{script.ly}.
1308 For information on how to add scripts, consult @file{scm/script.scm}.
1315 @subsection Grace notes
1324 @cindex @code{\grace}
1327 @cindex @code{graceAlignPosition}
1330 \grace @var{musicexpr}
1333 A grace note expression has duration 0; the next real note is
1334 assumed to be the main note.
1336 You cannot have the grace note after the main note, in terms of
1337 duration, and main notes, but you can typeset the grace notes to the
1338 right of the main note using the property
1339 @code{graceAlignPosition}.
1340 @cindex @code{flagStyle}
1342 When grace music is interpreted, a score-within-a-score is set up:
1343 @var{musicexpr} has its own time bookkeeping, and you could (for
1344 example) have a separate time signature within grace notes. While in
1345 this score-within-a-score, you can create notes, beams, slurs, etc.
1346 Unbeamed eighth notes and shorter by default have a slash through the
1347 stem. This behavior can be controlled with the
1348 @code{flagStyle} property.
1351 @lilypond[fragment,verbatim]
1353 \grace c8 c4 \grace { [c16 c16] } c4
1354 \grace { \property Grace.flagStyle = "" c16 } c4
1361 At present, nesting @code{\grace} notes is not supported. The following
1362 may cause run-time errors:
1364 @code{\grace @{ \grace c32 c16 @} c4}
1366 Since the meaning of such a construct is unclear, we don't consider
1367 this a loss. Similarly, juxtaposing two @code{\grace} sections is
1368 syntactically valid, but makes no sense and may cause runtime errors.
1370 Ending a staff or score with grace notes may also generate a run-time
1371 error, since there will be no main note to attach the grace notes to.
1373 The present implementation is not robust and generally kludgy. We expect
1374 it to change after LilyPond 1.4. Syntax changes might also be
1387 * Crescendo and Decrescendo::
1396 @subsubsection Glissando
1399 @cindex @code{\glissando}
1401 A glissando line can be requested by attaching a @code{\glissando} to a
1405 @lilypond[fragment,relative,verbatim]
1410 Printing of an additional text (such as @emph{gliss.}) must be done
1417 @subsubsection Dynamics
1430 @cindex @code{\ffff}
1444 Dynamic marks are specified by using an identifier after a note:
1445 @code{c4-\ff}. The available dynamic marks are:
1446 @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f},
1447 @code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf},
1448 @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1450 @c . {Crescendo and Decrescendo}
1451 @node Crescendo and Decrescendo
1452 @subsubsection Crescendo and Decrescendo
1454 @cindex Crescendo and Decrescendo
1458 @cindex @code{\decr}
1459 @cindex @code{\rced}
1466 A crescendo mark is started with @code{\cr} and terminated with
1467 @code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
1468 started with @code{\decr} and terminated with @code{\rced}. There are
1469 also shorthands for these marks. A crescendo can be started with
1470 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1471 can be terminated with @code{\!}. Note that @code{\!} must go before
1472 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1473 after the last note. Because these marks are bound to notes, if you
1474 want to get several marks during one note, you must use spacer notes.
1476 @lilypond[fragment,verbatim,center]
1477 c'' \< \! c'' d'' \decr e'' \rced
1478 < f''1 { s4 \< \! s2 \> \! s4 } >
1481 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1482 is an example how to do it:
1484 @lilypond[fragment,relative,verbatim]
1486 \property Voice.crescendoText = "cresc."
1487 \property Voice.crescendoSpanner = #'dashed-line
1496 @subsubsection Bar lines
1500 @cindex measure lines
1507 This is a short-cut for doing
1509 \property Score.whichBar = @var{bartype}
1512 You are encouraged to use @code{\repeat} for repetitions. See
1513 @ref{Repeats}, and the documentation of @code{whichBar} in
1514 @ref{(lilypond-internals)LilyPond context properties}.
1521 @subsubsection Breath marks
1522 @cindex Breath marks
1528 @subsection Bar check
1532 @cindex @code{barCheckNoSynchronize}
1536 Whenever a bar check is encountered during interpretation, a warning
1537 message is issued if it doesn't fall at a measure boundary. This can
1538 help you find errors in the input. Depending on the value of
1539 @code{barCheckNoSynchronize}, the beginning of the measure will be
1540 relocated, so this can also be used to shorten measures.
1542 A bar check is entered using the bar symbol, @code{|}
1553 @section Piano music
1555 * Automatic staff changes::
1556 * Manual staff switches::
1563 @c . {Automatic staff changes}
1564 @node Automatic staff changes
1565 @subsection Automatic staff changes
1566 @cindex Automatic staff changes
1570 @node Manual staff switches
1571 @subsection Manual staff switches
1573 @cindex manual staff switches
1574 @cindex staff switch, manual
1576 @cindex @code{\translator}
1578 \translator @var{contexttype} = @var{name}
1581 A music expression indicating that the context which is a direct
1582 child of the a context of type @var{contexttype} should be shifted to
1583 a context of type @var{contexttype} and the specified name.
1585 Usually this is used to switch staffs in Piano music, e.g.
1588 \translator Staff = top @var{Music}
1602 @subsection Arpeggio
1605 @cindex broken arpeggio
1606 @cindex @code{\arpeggio}
1608 You can specify an arpeggio sign on a chord by attaching an
1609 @code{\arpeggio} to a note of the chord.
1613 @lilypond[fragment,relative,verbatim]
1614 \context Voice <c'\arpeggio e g c>
1618 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1619 to the chords in both staffs, and set
1620 @code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
1624 @lilypond[fragment,relative,verbatim]
1625 \context PianoStaff <
1626 \property PianoStaff.connectArpeggios = ##t
1627 \context Voice = one { <c''\arpeggio e g c> }
1628 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1635 @c . {Follow Thread}
1637 @subsection Follow Thread
1638 @cindex follow thread
1639 @cindex staff switching
1642 [todo: different name, eg. voice line ? ]
1644 @cindex @code{followThread}
1646 Whenever a voice switches to another staff a line connecting the notes
1647 can be printed automatically. This is enabled if the property
1648 @code{PianoStaff.followThread} is set to true:
1651 @lilypond[fragment,relative,verbatim]
1652 \context PianoStaff <
1653 \property PianoStaff.followThread = ##t
1654 \context Staff \context Voice {
1656 \translator Staff=two
1659 \context Staff=two {\clef bass; \skip 1*2;}
1673 * Automatic syllable durations::
1678 @subsection Lyrics mode
1682 @cindex @code{\lyrics}
1684 Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
1685 rules that make it easy to include punctuation and diacritical marks in
1686 words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
1687 format or a standard encoding without needing quotes. The precise
1688 definition of this mode is ludicrous, and this will remain so until the
1689 authors of LilyPond acquire a deeper understanding of character
1690 encoding, or someone else steps up to fix this.
1692 A word in Lyrics mode begins with: an alphabetic character, @code{_},
1693 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
1694 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
1695 any 8-bit character with ASCII code over 127, or a two-character
1696 combination of a backslash followed by one of @code{`}, @code{'},
1697 @code{"}, or @code{^}.
1699 Subsequent characters of a word can be any character that is not a digit
1700 and not white space. One important consequence of this is that a word
1701 can end with `@code{@}}', which may be confusing. However, LilyPond will
1702 issue a warning. Any @code{_} character which appears in an unquoted
1703 word is converted to a space. This provides a mechanism for introducing
1704 spaces into words without using quotes. Quoted words can also be used
1705 in Lyrics mode to specify words that cannot be written with the above
1706 rules. Here are some examples. Not all of these words are printable by
1711 2B_||_!2B % not a word because it starts with a digit
1712 ``Hello'' % not a word because it starts with `
1713 _ _ _ _ % 4 words, each one a space
1716 Since combinations of numbers and dots are used for indicating
1717 durations, you can not enter real numbers in this mode.
1719 @cindex lyrics expressions
1721 Syllables are entered like notes, with pitches replaced by text. For
1722 example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
1723 with quarter note duration. Note that the hyphen has no special
1724 meaning for lyrics, and does not introduce special symbols. See
1725 section @ref{Lexical modes} for a description of what is interpreted as
1728 Spaces can be introduced into a lyric either by using quotes
1729 (@code{"}) or by using an underscore without quotes: @code{He_could4
1730 not4}. All unquoted underscores are converted to spaces. Printing
1731 lyrics is discussed in the next section.
1734 @c . {Printing lyrics}
1735 @node Printing lyrics
1736 @subsection Printing lyrics
1740 Lyric syllables must be interpreted within a @code{Lyrics} context for
1741 printing them. Here is a full example:
1747 \notes \transpose c'' {
1749 e f g2 | e4 f g2 \bar "|.";
1751 \context Lyrics \lyrics {
1752 Va-4 der Ja- cob Va- der Ja- cob
1753 Slaapt gij nog?2 Slaapt4 gij nog?2
1765 @cindex lyric extender
1767 You may want a continuous line after the syllables to show melismata.
1768 To achieve this effect, add a @code{__} lyric as a separate word
1769 after the lyric to be extended. This will create an extender, a line
1770 that extends over the entire duration of the lyric. This line will
1771 run all the way to the start of the next lyric, so you may want to
1772 shorten it by using a blank lyric (using @code{_}).
1779 \notes \relative c'' {
1780 a4 () b () c () d | c () d () b () a | c () d () b () a
1782 \context Lyrics \lyrics {
1783 foo1 __ | bar2. __ _4 | baz1 __
1791 @cindex Lyric hyphen
1793 If you want to have hyphens centered between syllables (rather than
1794 attached to the end of the first syllable) you can use the special
1795 `@code{-}@code{-}' lyric as a separate word between syllables. This
1796 will result in a hyphen which length varies depending on the space
1797 between syllables, and which will be centered between the syllables.
1805 \notes \transpose c'' {
1807 e f g2 | e4 f g2 \bar "|.";
1809 \context Lyrics \lyrics {
1810 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1811 Slaapt gij nog?2 | Slaapt4 gij nog?2
1820 @c . {Automatic syllable durations}
1821 @node Automatic syllable durations
1822 @subsection Automatic syllable durations
1823 @cindex Automatic syllable durations
1826 [explain automatic phrasing]
1827 @cindex automatic lyric durations
1828 @cindex @code{\addlyrics}
1830 If you have lyrics that are set to a melody, you can import the rhythm
1831 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1834 \addlyrics @var{musicexpr1 musicexpr2}
1837 This means that both @var{musicexpr1} and @var{musicexpr2} are
1838 interpreted, but that every non-command atomic music expression
1839 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1840 of @var{musicexpr1}.
1841 @cindex @code{automaticMelismata}
1843 If the property @code{automaticMelismata} is set in the
1844 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1848 @lilypond[verbatim,fragment]
1851 \property Voice.automaticMelismata = ##t
1852 c8 () cis d8. e16 f2
1854 \context Lyrics \lyrics {
1859 You should use a single rhythm melody, and single rhythm lyrics (a
1860 constant duration is the obvious choice). If you do not, you will get
1861 undesired effects when using multiple stanzas:
1864 @lilypond[verbatim,fragment]
1867 c8 () cis d8. e16 f2
1869 \context Lyrics \lyrics
1876 It is valid (but probably not very useful) to use notes instead of
1877 lyrics for @var{musicexpr2}.
1886 [chords vs. simultaneous music]
1890 * Entering named chords::
1891 * Printing named chords::
1896 @subsection Chords mode
1899 Chord mode is introduced by the keyword
1900 @code{\chords}. It is similar to Note mode, but
1901 words are also looked up in a chord modifier table (containing
1902 @code{maj}, @code{dim}, etc).
1904 Since combinations of numbers and dots are used for indicating
1905 durations, you can not enter real numbers in this mode. Dashes
1906 and carets are used to indicate chord additions and subtractions,
1907 so scripts can not be entered in Chord mode.
1909 @c . {Entering named chords}
1910 @node Entering named chords
1911 @subsection Entering named chords
1912 @cindex Chords names
1914 Chord names are a way to generate simultaneous music expressions that
1915 correspond with traditional chord names. It can only be used in
1916 Chord mode (see section @ref{Lexical modes}).
1920 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1923 @var{tonic} should be the tonic note of the chord, and @var{duration}
1924 is the chord duration in the usual notation. There are two kinds of
1925 modifiers. One type is @emph{chord additions}, which are obtained by
1926 listing intervals separated by dots. An interval is written by its
1927 number with an optional @code{+} or @code{-} to indicate raising or
1928 lowering by half a step. Chord additions has two effects: It adds
1929 the specified interval and all lower odd numbered intervals to the
1930 chord, and it may lower or raise the specified interval. Intervals
1931 must be separated by a dot (@code{.}).
1934 Throughout these examples, chords have been shifted around the staff
1935 using @code{\transpose}.
1940 @lilypond[fragment,verbatim]
1944 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1956 The second type of modifier that may appear after the @code{:} is a
1957 named modifier. Named modifiers are listed in the file
1958 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
1959 @code{min} which lower the 3rd half a step, `@code{aug}' which
1960 raises the 5th, `@code{dim}' which lowers the 5th,
1961 `@code{maj}' which adds a raised 7th, and `@code{sus}'
1962 which replaces the 5th with a 4th.
1966 @lilypond[fragment,verbatim]
1969 c1:m c:min7 c:maj c:aug c:dim c:sus
1977 Chord subtractions are used to eliminate notes from a chord. The
1978 notes to be subtracted are listed after a @code{^} character,
1981 @lilypond[fragment,verbatim,center]
1990 Chord inversions can be specified by appending `@code{/}' and
1991 the name of a single note to a chord. This has the effect of
1992 lowering the specified note by an octave so it becomes the lowest
1993 note in the chord. If the specified note is not in the chord, a
1994 warning will be printed.
1996 @lilypond[fragment,verbatim,center]
2006 Bass notes can be added by `@code{/+}' and
2007 the name of a single note to a chord. This has the effect of
2008 adding the specified note to the chord, lowered by an octave,
2009 so it becomes the lowest note in the chord.
2011 @lilypond[fragment,verbatim,center]
2020 The most interesting application is printing chord names, which is
2021 explained in the next subsection.
2023 You should not combine @code{\relative} with named chords. [FIXME]
2025 @c . {Printing named chords}
2026 @node Printing named chords
2027 @subsection Printing named chords
2033 @cindex printing chord names
2036 @cindex @code{ChordNames}
2037 @cindex @code{ChordNameVoice}
2039 For displaying printed chord names, use the @code{ChordNames} and
2040 @code{ChordNameVoice} contexts. The chords may be entered either using
2041 the notation described above, or directly using simultaneous music.
2046 \chords {a1 b c} <d f g> <e g b>
2050 \context ChordNamesVoice \scheme
2051 \context Staff \transpose c'' \scheme
2053 \paper { linewidth = -1.; }
2058 You can make the chord changes stand out more by setting property
2059 @code{ChordNames.chordChanges} to true. This will only display chord
2060 names when there's a change in the chords scheme, but always display the
2061 chord name after a line break:
2067 c1:m \break c:m c:m c:m d
2072 \context ChordNames \scheme
2073 \context Staff \transpose c'' \scheme
2076 linewidth = 40 * \staffspace;
2088 LilyPond examines chords specified as lists of notes to determine a
2089 name to give the chord. LilyPond will not try to
2090 identify chord inversions or added base, which may result in strange
2091 chord names when chords are entered as a list of pitches:
2094 @lilypond[verbatim,center]
2103 \context ChordNamesVoice \scheme
2104 \context Staff \scheme
2106 \paper { linewidth = -1.; }
2111 To specify chord inversions, append @code{/<notename>}. To specify an
2112 added bass note, append @code{/+<notename}:
2115 @lilypond[verbatim,center]
2122 \context ChordNames \scheme
2123 \context Staff \transpose c'' \scheme
2125 \paper { linewidth = -1.; }
2130 The chord names that LilyPond should print are fully customizable. The
2131 code to print chord names is written in Scheme. It can be found in
2132 @file{scm/chord-name.scm}. Chord names are based on Banter style
2133 naming, which is unambiguous and has a logical structure. Typical
2134 American style chord names are implemented as a variation on Banter
2135 names, they can be selected by setting property @code{ChordName.style}
2140 \include "english.ly"
2145 df:m5- % Diminished triad
2146 c:5^3 % Root-fifth chord
2147 c:4^3 % Suspended fourth triad
2148 c:5+ % Augmented triad
2150 c:m5-.7- % Diminished seventh
2151 c:7+ % Major seventh
2152 c:7.4^3 % Dominant seventh suspended fourth
2153 c:5+.7 % Augmented dominant seventh
2154 c:m5-.7 % "Half" diminished seventh
2155 c:5-.7 % Dominant seventh flat fifth
2156 c:5-.7+ % Major seventh flat fifth
2157 c:m7+ % Minor-major seventh
2158 c:m7 % Minor seventh
2159 c:7 % Dominant seventh
2162 c:9^7 % Major triad w/added ninth
2163 c:6.9^7 % Six/Nine chord
2164 c:9 % Dominant ninth
2165 c:7+.9 % Major ninth
2166 c:m7.9 % Minor ninth
2171 \context ChordNames \scheme
2172 \context Staff \transpose c'' \scheme
2177 ChordName \override #'word-space = #1
2178 ChordName \override #'style = #'american
2185 Similarly, Jazz style chord names are implemented as a variation on
2186 American style names:
2192 c:6 % 6 = major triad with added sixth
2193 c:maj % triangle = maj
2198 c:m % m = minor triad
2199 c:m.6 % m6 = minor triad with added sixth
2200 c:m.7+ % m triangle = minor major seventh chord
2208 c:7.5+ % +7 = augmented dominant
2209 c:7.5- % 7b5 = hard diminished dominant
2216 c:13.9-^11 % 7(b9,13)
2217 c:13.9+^11 % 7(#9,13)
2219 c:13-.9-^11 % 7(b9,b13)
2220 c:13-.9+^11 % 7(#9,b13)
2222 % half diminished chords
2223 c:m5-.7 % slashed o = m7b5
2224 c:9.3-.5- % o/7(pure 9)
2227 c:m5-.7- % o = diminished seventh chord
2232 \context ChordNames \scheme
2233 \context Staff \transpose c'' \scheme
2238 ChordName \override #'word-space = #1
2239 ChordName \override #'style = #'jazz
2247 @section Writing parts
2253 * Multi measure rests::
2264 tranposing midi property.
2270 @c . {Rehearsal marks}
2271 @node Rehearsal marks
2272 @subsection Rehearsal marks
2273 @cindex Rehearsal marks
2275 @cindex @code{\mark}
2276 @cindex @code{Mark_engraver}
2279 \mark @var{unsigned};
2284 With this command, you can print a rehearsal mark above the system. You
2285 can provide a number, a string or a markup text as argument. If there is
2286 no argument, the property @code{rehearsalMark} is used and automatically
2289 @lilypond[fragment,verbatim]
2295 c1 \mark #'(music "scripts-segno") ;
2301 @subsection Transpose
2303 @cindex transposition of pitches
2304 @cindex @code{\transpose}
2306 A music expression can be transposed with @code{\transpose}. The syntax
2309 \transpose @var{pitch} @var{musicexpr}
2312 This means that middle C in @var{musicexpr} is transposed to
2315 @code{\transpose} distinguishes between enharmonic pitches: both
2316 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2317 a tone. The first version will print sharps and the second version
2321 @lilypond[fragment,verbatim]
2324 { \key e \major; c d e f }
2326 \transpose des'' { \key e \major; c d e f }
2327 \transpose cis'' { \key e \major; c d e f }
2333 If you want to use both @code{\transpose} and @code{\relative}, then
2334 you must use @code{\transpose} first. @code{\relative} will have no
2335 effect music that appears inside a @code{\transpose}.
2338 @c . {Multi measure rests}
2339 @node Multi measure rests
2340 @subsection Multi measure rests
2341 @cindex Multi measure rests
2345 Multi measure rests are entered using `@code{R}'. It is specifically
2346 meant for entering parts: the rest can expand to fill a score with
2347 rests, or it can be printed as a single multimeasure rest This expansion
2348 is controlled by the property @code{Score.skipBars}. If this is set to true,
2349 Lily will not expand empty measures, and the appropriate number is added
2352 @lilypond[fragment,verbatim]
2353 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2356 Currently, there is no way to condense multiple rests into a single
2359 @cindex condensing rests
2367 A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a
2368 staff context symbol that appears at the end of a staff line. It
2369 anticipates the pitch of the first note(s) of the following line and
2370 thus helps the player or singer to manage line breaks during
2371 performance, thus enhancing readability of a score.
2376 \notes { c'1 d' e' d' \break c' d' e' d' }
2380 \consists Custos_engraver;
2381 Custos \override #'style = #'mensural;
2388 Custodes were frequently used in music notation until the 16th century.
2389 There were different appearences for different notation styles.
2390 Nowadays, they have survived only in special forms of musical notation
2391 such as via the editio vaticana dating back to the beginning of the 20th
2394 For typesetting custodes, just put a @code{Custos_engraver} into the
2395 @code{StaffContext} when declaring the @code{\paper} block. In this
2396 block, you can also globally control the appearance of the custos symbol
2397 by setting the custos @code{style} property. Currently supported styles
2398 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2405 \consists Custos_engraver;
2406 Custos \override #'style = #'mensural;
2411 The property can also be set locally, for example in a @code{\notes}
2416 \property Staff.Custos \override #'style = #'vaticana
2417 c'1 d' e' d' \break c' d' e' d'
2423 @section Page layout
2437 @subsection Paper block
2440 The most important output definition is the @code{\paper} block, for
2441 music notation. The syntax is
2444 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2447 where each of the items is one of
2450 @item An assignment. The assignment must be terminated by a
2453 @item A context definition. See section @ref{Context definitions} for
2454 more information on context definitions.
2456 @item \stylesheet declaration. Its syntax is
2458 \stylesheet @var{alist}
2461 See @file{font.scm} for details of @var{alist}.
2464 @c . {Paper variables}
2465 @node Paper variables
2466 @subsection Paper variables
2467 @cindex Paper variables
2469 The paper block has some variables you may want to use or change:
2472 @cindex @code{indent}
2474 The indentation of the first line of music.
2475 @cindex @code{staffspace}
2477 @item @code{staffspace}
2478 The distance between two staff lines, calculated from the center
2479 of the lines. You should use either this or @code{stafflinethickness}
2480 as a unit for distances you modify.
2482 @cindex @code{linewidth}
2483 @item @code{linewidth}
2484 Sets the width of the lines.
2486 If set to a negative value, a single
2487 unjustified line is produced.
2489 @cindex @code{textheight}
2491 @item @code{textheight}
2492 Sets the total height of the music on each page. Only used by
2494 @cindex @code{interscoreline}
2496 @item @code{interscoreline}
2497 Sets the spacing between the score lines. Defaults to 16 pt.
2498 @cindex @code{interscorelinefill}
2500 @item @code{interscorelinefill}
2501 If set to a positive number, the distance between the score
2502 lines will stretch in order to fill the full page. In that
2503 case @code{interscoreline} specifies the minimum spacing.
2505 @cindex @code{stafflinethickness}
2507 @item @code{stafflinethickness}
2508 Determines the thickness of staff lines, and also acts as a scaling
2509 parameter for other line thicknesses.
2516 @subsection Font size
2519 The Feta font provides musical symbols at six different sizes. These
2520 fonts are 11 point, 13 point, 16 point, 20 point,
2521 23 point, and 26 point. The point size of a font is the
2522 height of the five lines in a staff when displayed in the font.
2524 Definitions for these sizes are the files @file{paperSZ.ly}, where
2525 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2526 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2527 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2528 @code{paperTwentysix} are defined respectively. The default
2529 @code{\paper} block is also set.
2531 The font definitions are generated using a Scheme function. For more
2532 details, see the file @file{font.scm}.
2538 @subsection Paper size
2543 @cindex @code{papersize}
2545 To change the paper size, you must first set the
2546 @code{papersize} variable at top level. Set it to
2547 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2548 specification, you must set the font as described above. If you want
2549 the default font, then use the 20 point font. The new paper size will
2550 not take effect if the font is not loaded and selected afterwards.
2554 \include "paper16.ly"
2558 \paper @{ \paperSixteen @}
2562 The file "paper16.ly" will now include a file named @file{a4.ly}, which
2563 will set the paper variables @code{hsize} and @code{vsize} (used by
2574 @subsection Line break
2577 @cindex breaking lines
2579 Line breaks are normally computed automatically. They are chosen such
2580 that the resulting spacing has low variation, and looks neither cramped
2583 Occasionally you might want to override the automatic breaks; you can do
2584 this by specifying @code{\break}. This will force a line break at this
2585 point. Do remember that line breaks can only occur at places where there
2586 are barlines. If you want to have a line break where there is no
2587 barline, you can force a barline by entering @code{\bar "";}.
2589 Similarly, @code{\noBreak} forbids a line break at a certain point.
2591 @cindex @code{\penalty}
2593 The @code{\break} and @code{\noBreak} commands are defined in terms of
2594 the penalty command:
2596 \penalty @var{int} @code{;}
2599 This imposes encourages or discourages LilyPond to make a line break
2602 @strong{Warning} do not use @code{\penalty} directly. It is rather
2603 kludgy, and slated for rewriting.
2607 @subsection Page break
2610 @cindex breaking pages
2613 Page breaks are normally computed by @TeX{}, so they are not under direct
2614 control. However, you can insert a commands into the @file{.tex} output to
2615 instruct @TeX{} where to break pages. For more details, see the
2616 example file @file{input/test/between-systems.ly}
2631 * MIDI instrument names::
2637 @subsection MIDI block
2641 The MIDI block is analogous to the paper block, but it is somewhat
2642 simpler. The @code{\midi} block can contain:
2646 @item a @code{\tempo} definition
2647 @item context definitions
2650 Assignments in the @code{\midi} block are not allowed.
2654 @cindex context definition
2656 Context definitions follow precisely the same syntax as within the
2657 \paper block. Translation modules for sound are called performers.
2658 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2661 @c . {MIDI instrument names}
2662 @node MIDI instrument names
2663 @subsection MIDI instrument names
2664 @cindex instrument names
2665 @cindex @code{Staff.midiInstrument}
2666 @cindex @code{Staff.instrument}
2668 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2669 property or, if that property is not set, the @code{Staff.instrument}
2670 property. The instrument name should be chosen from the following list.
2671 If the selected string does not exactly match, then LilyPond uses the
2674 [FIXME: to appendix ]
2678 "acoustic grand" "contrabass" "lead 7 (fifths)"
2679 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2680 "electric grand" "pizzicato strings" "pad 1 (new age)"
2681 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2682 "electric piano 1" "timpani" "pad 3 (polysynth)"
2683 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2684 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2685 "clav" "synthstrings 1" "pad 6 (metallic)"
2686 "celesta" "synthstrings 2" "pad 7 (halo)"
2687 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2688 "music box" "voice oohs" "fx 1 (rain)"
2689 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2690 "marimba" "orchestra hit" "fx 3 (crystal)"
2691 "xylophone" "trumpet" "fx 4 (atmosphere)"
2692 "tubular bells" "trombone" "fx 5 (brightness)"
2693 "dulcimer" "tuba" "fx 6 (goblins)"
2694 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2695 "percussive organ" "french horn" "fx 8 (sci-fi)"
2696 "rock organ" "brass section" "sitar"
2697 "church organ" "synthbrass 1" "banjo"
2698 "reed organ" "synthbrass 2" "shamisen"
2699 "accordion" "soprano sax" "koto"
2700 "harmonica" "alto sax" "kalimba"
2701 "concertina" "tenor sax" "bagpipe"
2702 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2703 "acoustic guitar (steel)" "oboe" "shanai"
2704 "electric guitar (jazz)" "english horn" "tinkle bell"
2705 "electric guitar (clean)" "bassoon" "agogo"
2706 "electric guitar (muted)" "clarinet" "steel drums"
2707 "overdriven guitar" "piccolo" "woodblock"
2708 "distorted guitar" "flute" "taiko drum"
2709 "guitar harmonics" "recorder" "melodic tom"
2710 "acoustic bass" "pan flute" "synth drum"
2711 "electric bass (finger)" "blown bottle" "reverse cymbal"
2712 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2713 "fretless bass" "whistle" "breath noise"
2714 "slap bass 1" "ocarina" "seashore"
2715 "slap bass 2" "lead 1 (square)" "bird tweet"
2716 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2717 "synth bass 2" "lead 3 (calliope)" "helicopter"
2718 "violin" "lead 4 (chiff)" "applause"
2719 "viola" "lead 5 (charang)" "gunshot"
2720 "cello" "lead 6 (voice)"
2731 @cindex beats per minute
2732 @cindex metronome marking
2734 @cindex @code{\tempo}
2736 \tempo @var{duration} = @var{perminute} @code{;}
2739 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
2740 output with 76 quarter notes per minute.
2748 @section Music entry
2759 @subsection Relative
2761 @cindex relative octave specification
2763 Octaves are specified by adding @code{'} and @code{,} to pitch names.
2764 When you copy existing music, it is easy to accidentally put a pitch in
2765 the wrong octave and hard to find such an error. To prevent these
2766 errors, LilyPond features octave entry.
2768 @cindex @code{\relative}
2770 \relative @var{startpitch} @var{musicexpr}
2773 The octave of notes that appear in @var{musicexpr} are calculated as
2774 follows: If no octave changing marks are used, the basic interval
2775 between this and the last note is always taken to be a fourth or less.
2776 The octave changing marks @code{'} and @code{,} can then
2777 be added to raise or lower the pitch by an extra octave. Upon entering
2778 relative mode, an absolute starting pitch must be specified that will
2779 act as the predecessor of the first note of @var{musicexpr}.
2781 This distance is determined without regarding accidentals: a
2782 @code{fisis} following a @code{ceses} will be put above the
2785 Entering scales is straightforward in relative mode.
2787 @lilypond[fragment,verbatim,center]
2789 g a b c d e f g g, g
2793 And octave changing marks are used for intervals greater than a fourth.
2795 @lilypond[fragment,verbatim,center]
2797 c g c f, c' a, e'' }
2800 If the preceding item is a chord, the first note of the chord is used
2801 to determine the first note of the next chord. But other notes
2802 within the second chord are determined by looking at the immediately
2805 @lilypond[fragment,verbatim,center]
2812 @cindex @code{\notes}
2814 The pitch after the @code{\relative} contains a notename. To parse
2815 the pitch as a notename, you have to be in note mode, so there must
2816 be a surrounding @code{\notes} keyword (which is not
2819 The relative conversion will not affect @code{\transpose} or
2820 @code{\relative} sections in its argument. If you want to use
2821 relative within transposed music, you must place an additional
2822 @code{\relative} inside the @code{\transpose}.
2825 @c . {Point and click}
2826 @node Point and click
2827 @subsection Point and click
2836 * Selecting contexts::
2837 * Context definitions::
2838 * Notation Contexts::
2841 @c . {Music expressions}
2842 @node Selecting contexts
2843 @subsection Selecting contexts
2845 @cindex @code{\context}
2846 @cindex context selection
2849 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
2852 Interpret @var{musicexpr} within a context of type @var{contexttype}.
2853 If the context does not exist, it will be created. The new context
2854 can optionally be given a name.
2858 @c . {Context definitions}
2859 @node Context definitions
2860 @subsection Context definitions
2862 @cindex context definition
2863 @cindex translator definition
2864 @cindex engraver hacking
2867 A notation contexts is defined by the following information
2872 @item The LilyPond modules that do the actual conversion of music to
2873 notation. Each module is a so-called
2878 @item How these modules should cooperate, i.e. which ``cooperation
2879 module'' should be used. This cooperation module is a special
2882 @item What other contexts the context can contain,
2884 @item What properties are defined.
2887 A context definition has this syntax:
2891 \translator @code{@{}
2892 @var{translatorinit} @var{translatormodifierlist}
2896 @var{translatorinit} can be an identifier or
2898 \type @var{typename} @code{;}
2900 where @var{typename} is one of
2903 @cindex @code{Engraver_group_engraver}
2904 @item @code{Engraver_group_engraver}
2905 The standard cooperation engraver.
2906 @cindex @code{Score_engraver}
2908 @item @code{Score_engraver}
2909 This is cooperation module that should be in the top level context.
2910 @cindex @code{Grace_engraver_group}
2912 @item @code{Grace_engraver_group}
2913 This is a special cooperation module (resembling
2914 @code{Score_engraver}) that is used to created an embedded
2918 @var{translatormodifierlist} is a list of items where each item is
2922 @item @code{\consists} @var{engravername} @code{;}
2923 Add @var{engravername} to the list of modules in this context.
2924 The order of engravers added with @code{\consists} is
2927 @item @code{\consistsend} @var{engravername} @code{;}
2928 Analogous to @code{\consists}, but makes sure that
2929 @var{engravername} is always added to the end of the list of
2932 Some engraver types need to be at the end of the list; this
2933 insures they are put there, and stay there, if a user adds or
2934 removes engravers. This command is usually not needed for
2937 @item @code{\accepts} @var{contextname} @code{;}
2938 Add @var{contextname} to the list of context this context can
2939 contain. The first listed context is the context to create by
2942 @item @code{\denies}. The opposite of @code{\accepts}. Added for
2943 completeness, but is never used in practice.
2946 @item @code{\remove} @var{engravername} @code{;}
2947 Remove a previously added (with @code{\consists}) engraver.
2949 @item @code{\name} @var{contextname} @code{;}
2950 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2951 the name is not specified, the translator won't do anything.
2953 @item @var{propname} @code{=} @var{value} @code{;}
2954 A property assignment.
2957 In the @code{\paper} block, it is also possible to define translator
2958 identifiers. Like other block identifiers, the identifier can only
2959 be used as the very first item of a translator. In order to define
2960 such an identifier outside of @code{\score}, you must do
2966 foo = \translator @{ @dots{} @}
2973 \translator @{ \foo @dots{} @}
2981 @cindex paper types, engravers, and pre-defined translators
2983 Some pre-defined identifiers can simplify modification of
2984 translators. The pre-defined identifiers are:
2987 @cindex @code{StaffContext}
2988 @item @code{StaffContext}
2989 Default Staff context.
2990 @cindex @code{RhythmicStaffContext}
2992 @item @code{RhythmicStaffContext}
2993 Default RhythmicStaff context.
2994 @cindex @code{VoiceContext}
2996 @item @code{VoiceContext}
2997 Default Voice context.
2998 @cindex @code{ScoreContext}
3000 @item @code{ScoreContext}
3001 Default Score context.
3003 @cindex @code{HaraKiriStaffContext}
3005 @item @code{HaraKiriStaffContext}
3006 Staff context that does not print if it only contains rests.
3007 Useful for orchestral scores.@footnote{Harakiri, also called
3008 Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
3012 Using these pre-defined values, you can remove or add items to the
3021 \remove Some_engraver;
3022 \consists Different_engraver;
3032 @c . {Notation Contexts}
3033 @node Notation Contexts
3034 @subsection Notation Contexts
3036 @cindex notation contexts
3038 Notation contexts are objects that only exist during a run of
3039 LilyPond. During the interpretation phase of LilyPond, the Music
3040 expression contained in a @code{\score} block is interpreted in time
3041 order. This is the order in which humans read, play, and write
3044 A context is an object that holds the reading state of the
3045 expression; it contains information like
3048 @item What notes are playing at this point?
3049 @item What symbols will be printed at this point?
3050 @item In what style will they printed?
3051 @item What is the current key signature, time signature, point within
3055 Contexts are grouped hierarchically: A @code{Voice} context is
3056 contained in a @code{Staff} context (because a staff can contain
3057 multiple voices at any point), a @code{Staff} context is contained in
3058 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
3059 these can all contain multiple staffs).
3061 Contexts associated with sheet music output are called @emph{notation
3062 contexts}, those for sound output are called performance contexts.
3064 Contexts are created either manually or automatically. Initially, the
3065 top level music expression is interpreted by the top level context (the
3066 @code{Score} context). When a atomic music expression (i.e. a note, a
3067 rest, etc.), a nested set of contexts is created that can process these
3068 atomic expressions, as in this example:
3071 \score @{ \notes @{ c4 @} @}
3074 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
3075 context. When the note @code{c4} itself is interpreted, a set of
3076 contexts is needed that will accept notes. The default for this is a
3077 @code{Voice} context, contained in a @code{Staff} context. Creation of
3078 these contexts results in the staff being printed.
3082 You can also create contexts manually, and you probably have to do so
3083 if you want to typeset complicated multiple part material. If a
3084 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
3085 during the interpretation phase, the @var{musicexpr} argument will be
3086 interpreted with a context of type @var{name}. If you specify a name,
3087 the specific context with that name is searched.
3091 If a context of the specified type and name can not be found, a new
3092 one is created. For example,
3098 \notes \relative c'' {
3099 c4 <d4 \context Staff = "another" e4> f
3106 In this example, the @code{c} and @code{d} are printed on the
3107 default staff. For the @code{e}, a context Staff called
3108 @code{another} is specified; since that does not exist, a new
3109 context is created. Within @code{another}, a (default) Voice context
3110 is created for the @code{e4}. When all music referring to a
3111 context is finished, the context is ended as well. So after the
3112 third quarter, @code{another} is removed.
3114 Almost all music expressions inherit their interpretation context
3115 from their parent. In other words, suppose that the syntax for a
3120 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
3123 When the interpretation of this music expression starts, the context
3124 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
3127 Lastly, you may wonder, why this:
3133 \notes \relative c'' @{
3141 doesn't result in this:
3146 \notes \relative c'' {
3153 For the @code{c4}, a default @code{Staff} (with a contained
3154 @code{Voice}) context is created. After the @code{c4} ends, no
3155 music refers to this default staff, so it would be ended, with the
3156 result shown. To prevent this inconvenient behavior, the context to
3157 which the sequential music refers is adjusted during the
3158 interpretation. So after the @code{c4} ends, the context of the
3159 sequential music is also the default @code{Voice} context.
3160 The @code{d4} gets interpreted in the same context
3163 Properties that are set in one context are inherited by all of the
3164 contained contexts. This means that a property valid for the
3165 @code{Voice} context can be set in the @code{Score} context (for
3166 example) and thus take effect in all @code{Voice} contexts.
3168 Properties can be preset within the @code{\translator} block
3169 corresponding to the appropriate context. In this case, the syntax
3173 @var{propname} @code{=} @var{value}
3176 This assignment happens before interpretation starts, so a
3177 @code{\property} expression will override any predefined settings.
3179 The property settings are used during the interpretation phase. They
3180 are read by the LilyPond modules where interpretation contexts are
3181 built of. These modules are called @emph{translators}. Translators for
3182 notation are called @emph{engravers}, and translators for sound are
3183 called @emph{performers}.
3187 @c . {Syntactic details}
3188 @node Syntactic details
3189 @section Syntactic details
3190 @cindex Syntactic details
3194 * Music expressions::
3203 @subsection Top level
3206 This section describes what you may enter at top level.
3209 @unnumberedsubsec Score definition
3210 @cindex score definition
3212 The output is generated combining a music expression with an output
3213 definition. A score block has the following syntax:
3216 \score @{ @var{musicexpr} @var{outputdefs} @}
3219 @var{outputdefs} are zero or more output definitions. If no output
3220 definition is supplied, the default @code{\paper} block will be added.
3224 @subsubsection Score
3228 @subsubsection Paper
3236 @subsubsection Header
3238 @cindex @code{\header}
3243 \header @{ @var{key1} = @var{val1};
3244 @cindex @code{ly2dvi}
3245 @var{key2} = @var{val2}; @dots{} @}
3249 A header describes the file's contents. It can also appear in a
3250 @code{\score} block. Tools like @code{ly2dvi} can use this
3251 information for generating titles. Key values that are used by
3252 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
3253 metre, arranger, piece and tagline.
3255 It is customary to put the @code{\header} at the top of the file.
3257 @subsubsection Default output
3259 A @code{\midi} or @code{\paper} block at top-level sets the default
3261 paper block for all scores that lack an explicit paper block.
3265 @subsection Identifiers
3268 All of the information in a LilyPond input file, is represented as a
3269 Scheme value. In addition to normal Scheme data types (such as pair,
3270 number, boolean, etc.), LilyPond has a number of specialized data types,
3277 @item Translator_def
3281 @item Music_output_def
3282 @item Moment (rational number)
3285 LilyPond also includes some transient object types. Objects of these
3286 types are built during a LilyPond run, and do not `exist' per se within
3287 your input file. These objects are created as a result of your input
3288 file, so you can include commands in the input to manipulate them,
3289 during a lilypond run.
3292 @item Grob: short for Graphical object. See @ref{Grobs}.
3293 @item Molecule: device-independent page output object,
3294 including dimensions. Produced by some Grob functions
3296 @item Translator: object that produces audio objects or Grobs. This is
3297 not yet user accessible.
3298 @item Font_metric: object representing a font. (See @ref{Font metrics})
3303 @node Music expressions
3304 @subsection Music expressions
3306 @cindex music expressions
3308 Music in LilyPond is entered as a music expression. Notes, rests, lyric
3309 syllables are music expressions, and you can combine music expressions
3310 to form new ones, for example by enclosing a list of expressions in
3311 @code{\sequential @{ @}} or @code{< >}. In this example, a compound
3312 expression is formed out of the quarter note @code{c} and a quarter note
3316 \sequential @{ c4 d4 @}
3319 @cindex Sequential music
3320 @cindex @code{\sequential}
3321 @cindex sequential music
3324 @cindex Simultaneous music
3325 @cindex @code{\simultaneous}
3327 The two basic compound music expressions are simultaneous and
3331 \sequential @code{@{} @var{musicexprlist} @code{@}}
3332 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
3334 For both, there is a shorthand:
3336 @code{@{} @var{musicexprlist} @code{@}}
3340 @code{<} @var{musicexprlist} @code{>}
3342 for simultaneous music.
3343 Other compound music expressions include
3346 \transpose @var{pitch} @var{expr}
3347 \apply @var{func} @var{expr}
3348 \context @var{type} = @var{id} @var{expr}
3349 \times @var{fraction} @var{expr}
3352 In principle, the way in which you nest sequential and simultaneous to
3353 produce music is not relevant. In the following example, three chords
3354 are expressed in two different ways:
3356 @lilypond[fragment,verbatim,center]
3357 \notes \context Voice {
3358 <a c'> <b d' > <c' e'>
3359 < { a b c' } { c' d' e' } >
3363 However, in some cases, LilyPond will also try to choose contexts, and
3364 use the structure of the music expression to do so. This can have
3365 undesired effects: for example, LilyPond will create a separate staff
3366 for each note if you start a @code{\score} with a chord:
3367 @lilypond[verbatim,center]
3375 The solution is to explicitly instantiate the context you desire.
3376 In this case this is typically a Voice context
3377 @lilypond[verbatim,center]
3379 \notes\context Voice <c''4 e''>
3385 If you use @code{\context Staff} you will get separate stems for each
3386 note head, leading to collisions, so don't use that.
3392 @subsection Assignments
3395 Identifiers allow objects to be assigned to names during the parse
3396 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
3397 and to refer to an identifier, you preceed its name with a backslash:
3398 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
3399 the input-types listed above. Identifier assignments can appear at top
3400 level in the LilyPond file, but also in @code{\paper} blocks.
3402 Semicolons are forbidden after top level assignments, but mandatory in
3403 other places. The rules about semicolons and assignments are very
3404 confusing, but when LilyPond input evolves more towards Scheme, we hope
3405 that this problem will grow smaller.
3407 An identifier can be created with any string for its name, but you will
3408 only be able to refer to identifiers whose names begin with a letter,
3409 being entirely alphabetical. It is impossible to refer to an identifier
3410 whose name is the same as the name of a keyword.
3412 The right hand side of an identifier assignment is parsed completely
3413 before the assignment is done, so it is allowed to redefine an
3414 identifier in terms of its old value, e.g.
3420 When an identifier is referenced, the information it points to is
3421 copied. For this reason, an identifier reference must always be the
3422 first item in a block.
3426 \paperIdent % wrong and invalid
3430 \paperIdent % correct
3434 @c . {Lexical details}
3435 @node Lexical details
3436 @subsection Lexical details
3437 @cindex Lexical details
3442 @subsubsection Comments
3448 A one line comment is introduced by a @code{%} character.
3449 Block comments are started by @code{%@{} and ended by @code{%@}}.
3450 They cannot be nested.
3452 @c . {Direct Scheme}
3453 @subsubsection Direct Scheme
3456 @cindex Scheme, in-line code
3459 LilyPond contains a Scheme interpreter (the GUILE library) for
3460 internal use. In some places Scheme expressions also form valid syntax:
3461 whereever it is allowed,
3465 evaluates the specified Scheme code. If this is used at toplevel, then
3466 the result is discarded. Example:
3468 \property Staff.TestObject \override #'foobar = #(+ 1 2)
3471 @code{\override} expects two Scheme expressions, so there are two Scheme
3472 expressions. The first one is a symbol (@code{foobar}), the second one
3473 an integer (namely, 3).
3475 Scheme is a full-blown programming language, and a full discussion is
3476 outside the scope of this document. Interested readers are referred to
3477 the website @uref{http://www.schemers.org/} for more information on
3482 @subsubsection Keywords
3486 Keywords start with a backslash, followed by a number of lower case
3487 alphabetic characters. These are all the keywords.
3490 apply arpeggio autochange spanrequest commandspanrequest
3491 simultaneous sequential accepts alternative bar breathe
3492 char chordmodifiers chords clef cm consists consistsend
3493 context denies duration dynamicscript elementdescriptions
3494 font grace header in lyrics key mark pitch
3495 time times midi mm name pitchnames notes outputproperty
3496 override set revert partial paper penalty property pt
3497 relative remove repeat addlyrics partcombine score
3498 script stylesheet skip textscript tempo translator
3503 @subsubsection Integers
3511 Formed from an optional minus sign followed by digits. Arithmetic
3512 operations cannot be done with integers, and integers cannot be mixed
3516 @subsubsection Reals
3517 @cindex real numbers
3523 Formed from an optional minus sign and a sequence of digits followed
3524 by a @emph{required} decimal point and an optional exponent such as
3525 @code{-1.2e3}. Reals can be built up using the usual operations:
3526 `@code{+}', `@code{-}', `@code{*}', and
3527 `@code{/}', with parentheses for grouping.
3535 A real constant can be followed by one of the dimension keywords:
3536 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
3537 points, inches and centimeters, respectively. This converts the number
3538 to a real that is the internal representation of dimensions.
3542 @subsubsection Strings
3546 Begins and ends with the @code{"} character. To include a @code{"}
3547 character in a string write @code{\"}. Various other backslash
3548 sequences have special interpretations as in the C language. A string
3549 that contains no spaces can be written without the quotes. See
3550 @ref{Lexical modes} for details on unquoted strings; their
3551 interpretation varies depending on the situation. Strings can be
3552 concatenated with the @code{+} operator.
3554 The tokenizer accepts the following commands. They have no grammatical
3555 function, hence they can appear anywhere in the input.
3559 @subsubsection Main input
3562 @cindex @code{\maininput}
3564 The @code{\maininput} command is used in init files to signal that the
3565 user file must be read. This command cannot be used in a user file.
3567 @c . {File inclusion}
3568 @subsubsection Main input
3571 @subsubsection File inclusion
3572 @cindex @code{\include}
3574 \include @var{filename}
3577 Include @var{filename}. The argument @var{filename} may be a quoted string (an
3578 unquoted string will not work here!) or a string identifier. The full
3579 filename including the @file{.ly} extension must be given,
3581 @subsubsection Version information
3582 @cindex @code{\version}
3584 \version @var{string} ;
3587 Specify the version of LilyPond that a file was written for. The
3588 argument is a version string in quotes, for example @code{"1.2.0"}.
3589 This is used to detect invalid input, and to aid
3590 @code{convert-ly} a tool that automatically upgrades input files. See
3591 See @ref{convert-ly} for more information on @code{convert-ly}.
3597 @subsubsection Defining pitch names
3598 @cindex Lexical modes
3599 @cindex definining pitch names
3600 @cindex pitch names, definining
3602 @cindex chord modifier names
3604 A @code{\paper} block at top level sets the default paper block. A
3605 @code{\midi} block at top level works similarly.
3608 @subsubsection Assignments
3612 Identifier assignments may appear at top level. @ref{Assignments}
3616 @c . {Direct scheme}
3617 @subsubsection Direct scheme
3618 @cindex Direct scheme
3620 Scheme statements maybe issued to produce interesting side-effects.
3623 @c . {Lexical modes}
3625 @subsection Lexical modes
3626 @cindex Lexical modes
3629 @cindex @code{\notes}
3630 @cindex @code{\chords}
3631 @cindex @code{\lyrics}
3633 To simplify entering notes, lyrics, and chords, LilyPond has three
3634 special input modes on top of the default mode: note, lyrics and chords
3635 mode. These input modes change the way that normal, unquoted words are
3636 interpreted: for example, the word @code{cis} may be interpreted as a
3637 C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
3640 A mode switch is entered as a compound music expressions
3642 @code{\notes} @var{musicexpr}
3643 @code{\chords} @var{musicexpr}
3644 @code{\lyrics} @var{musicexpr}.
3647 In each of these cases, these expressions do not add anything to the
3648 meaning of their arguments. They are just a way to indicate that the
3649 arguments should be parsed in indicated mode. The modes are treated in
3650 more detail in the sections @ref{Note entry}, @ref{Lyrics} and
3653 You may nest different input modes.
3657 @subsection Ambiguities
3662 The grammar contains a number of ambiguities. We hope to resolve them at
3666 @item The assignment
3672 can be interpreted as making a string identifier @code{\foo}
3673 containing @code{"bar"}, or a music identifier @code{\foo}
3674 containing the syllable `bar'.
3676 @item The assignment
3682 can be interpreted as making an integer identifier
3683 containing -6, or a Request identifier containing the
3684 fingering `6' (with neutral direction).
3686 @item If you do a nested repeat like
3698 then it is ambiguous to which @code{\repeat} the
3699 @code{\alternative} belongs. This is the classic if-then-else
3700 dilemma. It may be solved by using braces.
3702 @item (an as yet unidentified ambiguity :-)
3717 @unnumberedsubsec Translation property
3719 [todo: add \set/\override/\revert]
3722 @cindex @code{\property}
3724 \property @var{contextname}.@var{propname} = @var{value}
3727 Sets the @var{propname} property of the context @var{contextname} to
3728 the specified @var{value}. All three arguments are strings.
3729 Depending on the context, it may be necessary to quote the strings or
3730 to leave space on both sides of the dot.
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.; }
3779 @c .{Local emacs vars}
3782 @c minor-mode: font-lock
3783 @c minor-mode: outline
3784 @c outline-layout: (-1 : 0)
3785 @c outline-use-mode-specific-leader: "@c \."
3786 @c outline-primary-bullet: "{"
3787 @c outline-stylish-prefixes: nil
3788 @c outline-override-protect: t