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
61 The purpose of LilyPond is explained informally by the term `music
62 typesetter'. This is not a fully correct name: not only does the
63 program print musical symbols, it also makes esthetic decisions. All
64 symbols and their placement is @emph{generated} from a high-level
65 musical description. In other words, LilyPond would be best described
66 by `music compiler' or `music to notation compiler'.
68 Internally, LilyPond is written in a mixture of Scheme and C++. Most of
69 the algorithms and low-level routines are written in C++, but these low
70 level components are glued together using Scheme data
71 structures. LilyPond is linked to GUILE, GNU's Scheme library for
74 When lilypond is run to typeset sheet music, the following happens:
77 @item GUILE Initialization: various scheme files are read
78 @item parsing: first standard .ly initialization files are read, and
79 then the user @file{.ly} file is read.
80 @item interpretation: the music in the file is processed "in playing
81 order", i.e. in the same order as your eyes scan sheet music, and in the
82 same order that you hear the notes play.
85 in this step, the results of the interpretation, a typesetting
86 specification, is solved.
88 @item the visible results ("virtual ink") is written to the output file.
91 These stages, involve data of a specific type: during parsing,
92 @strong{Music} objects are created. During the interpretation,
93 @strong{context} is constructed, and with this context af network of
94 @strong{graphical objects} (``grobs'') is created. The grobs contain
95 unknown variables, and the network forms a set of equations. After
96 solving the equations and filling in these variables, the printed output
97 (in the form of @strong{molecules}) is written to an output file.
99 These threemanship of tasks (parsing, translating, typesetting) and
100 data-structures (music, context, graphical objects) permeates the entire
101 design of the program. This manual is ordered in terms of user
102 tasks. With each concept will be explained to which of the three parts
105 LilyPond input can be classified into three types:
107 @item musical expressions: a musical expression is some combination of
109 @item output definitions: recipes for translating those musical
110 expressions into performances (MIDI) or graphics (eg. PostScript).
112 @item declarations: by declaring and naming musical expressions, you
113 can enter and edit them in manageable chunks.
125 @cindex @code{\repeat}
127 In order to specify repeats, use the @code{\repeat}
128 keyword. Since repeats look and sound differently when played or
129 printed, there are a few different variants of repeats.
133 Repeated music is fully written (played) out. Useful for MIDI
137 This is the normal notation: Repeats are not written out, but
138 alternative endings (voltas) are printed, left to right.
141 Alternative endings are written stacked. Which is unfortunately not
142 practical for anything right now.
150 * Manual repeat commands::
152 * Tremolo subdivision::
156 @subsection Repeat syntax
158 The syntax for repeats is
161 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
164 If you have alternative endings, you may add
166 @cindex @code{\alternative}
168 \alternative @code{@{} @var{alternative1}
170 @var{alternative3} @dots{} @code{@}}
173 where each @var{alternative} is a Music expression.
175 Normal notation repeats are used like this:
179 @lilypond[fragment,verbatim]
181 \repeat volta 2 { c'4 d' e' f' }
182 \repeat volta 2 { f' e' d' c' }
186 With alternative endings:
190 @lilypond[fragment,verbatim]
192 \repeat volta 2 {c'4 d' e' f'}
193 \alternative { {d'2 d'} {f' f} }
197 Folded repeats look like this:@footnote{Folded repeats offer little
198 more over simultaneous music. However, it is to be expected that
199 more functionality -- especially for the MIDI backend -- will be
200 implemented at some point in the future.}
204 @lilypond[fragment,verbatim]
206 \repeat fold 2 {c'4 d' e' f'}
207 \alternative { {d'2 d'} {f' f} }
213 If you don't give enough alternatives for all of the repeats, then
214 the first alternative is assumed to be repeated often enough to equal
215 the specified number of repeats.
218 @lilypond[fragment,verbatim]
222 \repeat volta 3 { e | c2 d2 | e2 f2 | }
223 \alternative { { g4 g g } { a | a a a a | b2. } }
231 As you can see, LilyPond doesn't remember the timing information, nor
232 are slurs or ties repeated, so you have to reset timing information
233 after a repeat, eg using bar-checks, @code{Score.measurePosition} or
234 @code{\partial}. We hope to fix this after 1.4.
236 It is possible to nest @code{\repeat}, although it probably is only
237 meaningful for unfolded repeats.
239 @node Manual repeat commands
240 @subsection Manual repeat commands
242 @cindex @code{repeatCommands}
244 The property @code{repeatCommands} can be used to control the layout of
245 repeats. Its value is a Scheme list of repeat commands, where each repeat
253 @item (volta . @var{text})
254 Print a volta bracket saying @var{text}.
256 Stop a running volta bracket
259 @lilypond[verbatim, fragment]
261 \property Score.repeatCommands = #'((volta "93") end-repeat)
263 \property Score.repeatCommands = #'((volta #f))
268 @node Tremolo repeats
269 @subsection Tremolo repeats
270 @cindex tremolo beams
272 To place tremolo marks between notes, use @code{\repeat} with tremolo
274 @lilypond[verbatim,center]
276 \context Voice \notes\relative c' {
277 \repeat "tremolo" 8 { c16 d16 }
278 \repeat "tremolo" 4 { c16 d16 }
279 \repeat "tremolo" 2 { c16 d16 }
280 \repeat "tremolo" 4 c16
283 linewidth = 40*\staffspace;
288 @node Tremolo subdivision
289 @subsection Tremolo subdivision
290 @cindex tremolo marks
291 @cindex @code{tremoloFlags}
293 Tremolo marks can be printed on a single note by adding
294 `@code{:}[@var{length}]' after the note. The length must be at least 8.
295 A @var{length} value of 8 gives one line across the note stem. If the
296 length is omitted, then the last value is used, or the value of the
297 @code{tremoloFlags} property if there was no last value.
299 @lilypond[verbatim,fragment,center]
303 Tremolos in this style do not carry over into the MIDI output.
305 Using this mechanism pays off when you entering many tremolos, since the
306 default argument saves a lot of typing.
317 * Defining pitch names::
326 @subsection Notes mode
330 @cindex @code{\notes}
331 Note mode is introduced by the keyword
332 @code{\notes}. In Note mode, words can only
333 contain alphabetic characters. If @code{word} is encountered,
334 LilyPond first checks for a notename of @code{word}. If no
335 notename is found, then @code{word} is treated as a string.
337 Since combinations of numbers and dots are used for indicating
338 durations, it is not possible to enter real numbers in this mode.
347 @cindex Note specification
349 @cindex entering notes
351 The verbose syntax for pitch specification is
353 @cindex @code{\pitch}
355 \pitch @var{scmpitch}
358 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
360 In Note and Chord mode, pitches may be designated by names. The default
361 names are the Dutch note names. The notes are specified by the letters
362 @code{c} through @code{b}, where @code{c} is an octave below middle C
363 and the letters span the octave above that C. In Dutch,
364 @cindex note names, Dutch
365 a sharp is formed by adding @code{-is} to the end of a pitch name. A
366 flat is formed by adding @code{-es}. Double sharps and double flats are
367 obtained by adding @code{-isis} or @code{-eses}. @code{aes} and
368 @code{ees} are contracted to @code{as} and @code{es} in Dutch, but both
369 forms will be accepted.
371 LilyPond has predefined sets of notenames for various other languages.
372 To use them, simply include the language specific init file. For
373 example: @code{\include "english.ly"}. The available language files and
374 the names they define are:
377 Note Names sharp flat
378 nederlands.ly c d e f g a bes b -is -es
379 english.ly c d e f g a bf b -s/-sharp -f/-flat
380 deutsch.ly c d e f g a b h -is -es
381 norsk.ly c d e f g a b h -iss/-is -ess/-es
382 svenska.ly c d e f g a b h -iss -ess
383 italiano.ly do re mi fa sol la sib si -d -b
384 catalan.ly do re mi fa sol la sib si -d/-s -b
393 The optional octave specification takes the form of a series of
394 single quote (`@code{'}') characters or a series of comma
395 (`@code{,}') characters. Each @code{'} raises the pitch by one
396 octave; each @code{,} lowers the pitch by an octave.
398 @lilypond[fragment,verbatim,center]
399 c' d' e' f' g' a' b' c''
402 @lilypond[fragment,verbatim,center]
403 cis' dis' eis' fis' gis' ais' bis'
406 @lilypond[fragment,verbatim,center]
407 ces' des' es' fes' ges' as' bes'
410 @lilypond[fragment,verbatim,center]
411 cisis' eisis' gisis' aisis' beses'
414 @lilypond[fragment,verbatim,center]
415 ceses' eses' geses' ases' beses'
419 @c . {Defining pitch names}
420 @node Defining pitch names
421 @subsection Defining pitch names
423 @cindex defining pitch names
424 @cindex pitch names, defining
426 Note names and chord modifiers can be customised for nationalities. The
427 syntax is as follows.
429 @cindex @code{\pitchnames}
430 @cindex @code{\chordmodifiers}
432 \pitchnames @var{scheme-alist}
433 \chordmodifiers @var{scheme-alist}
436 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
437 specific examples how to do this. Some national note names have been
438 provided, among others: Norwegian, Swedish, German, Italian, Catalan,
439 French, Dutch and English.
444 @subsection Durations
448 @cindex @code{\duration}
450 The syntax for an verbose duration specification is
452 \duration @var{scmduration}
455 In Note, Chord, and Lyrics mode, durations may be designated by numbers
456 and dots: durations are entered as their reciprocal values. For notes
457 longer than a whole note, use identifiers.
463 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
465 r1 r2 r4 r8 r16 r32 r64 r64
471 \notes \relative c'' {
472 a\longa a\breve \autoBeamOff
473 a1 a2 a4 a8 a16 a32 a64 a64
475 r1 r2 r4 r8 r16 r32 r64 r64
480 \remove "Clef_engraver";
481 \remove "Staff_symbol_engraver";
482 \remove "Time_signature_engraver";
483 \consists "Pitch_squash_engraver";
490 As you can see, the longa is not printed. To get a longa note head, you
491 have to use a different style of note heads. See [TODO].
493 If the duration is omitted then it is set equal to the previous duration
494 entered. At the start of parsing there is no previous duration, so then
495 a quarter note is assumed. The duration can be followed by a dot
496 (`@code{.}') to obtain dotted note lengths.
499 @lilypond[fragment,verbatim,center]
505 You can alter the length of duration by writing `@code{*}@var{fraction}'
506 after it. This will not affect the appearance of note heads or rests.
512 A note specification has the form
515 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
519 LilyPond will determine what accidentals to typeset depending on the key
520 and context, so alteration refer to what note is heard, not to whether
521 accidentals are printed. A reminder accidental
522 @cindex reminder accidental
524 can be forced by adding an exclamation mark @code{!} after the pitch.
525 A cautionary accidental,
526 @cindex cautionary accidental
528 i.e., an accidental within parentheses can be obtained by adding the
529 question mark `@code{?}' after the pitch.
531 @lilypond[fragment,verbatim,center]
532 cis' d' e' cis' c'? d' e' c'!
541 Rests are entered like notes, with note name `@code{r}'.
542 There is also a note name
543 `@code{s}', which produces a space of the specified
554 \skip @var{duration} @code{;}
558 Skips the amount of time specified by @var{duration}. If no other
559 music is played, a gap will be left for the skipped time with no
560 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
561 this has the same effect as the spacer rest.
565 @c . {Music notation}
567 @section Music notation
568 @cindex Music notation
582 @code{\key} @var{pitch} @var{type} @code{;}
584 @cindex @code{\minor}
585 @cindex @code{\major}
586 @cindex @code{\minor}
587 @cindex @code{\ionian}
588 @cindex @code{\locrian}
589 @cindex @code{\aeolian}
590 @cindex @code{\mixolydian}
591 @cindex @code{\lydian}
592 @cindex @code{\phrygian}
593 @cindex @code{\dorian}
595 Change the key signature. @var{type} should be @code{\major} or
596 @code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
597 respectively. The second argument is optional; the default is major
598 keys. The @var{\context} argument can also be given as an integer,
599 which tells the number of semitones that should be added to the pitch
600 given in the subsequent @code{\key} commands to get the corresponding
601 major key, e.g., @code{\minor} is defined as 3. The standard mode names
602 @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
603 @code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
605 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
1180 In addition, it is possible to place arbitrary strings of text or
1181 @TeX{} above or below notes by using a string instead of an
1182 identifier: @code{c^"text"}. Fingerings
1183 can be placed by simply using digits. All of these note ornaments
1184 appear in the printed output but have no effect on the MIDI rendering of
1188 @unnumberedsubsubsec Fingerings
1191 To save typing, fingering instructions (digits 0 to 9 are
1192 supported) and single characters shorthands exist for a few
1197 \notes \context Voice {
1198 \property Voice.TextScript \set #'font-family = #'typewriter
1199 \property Voice.TextScript \set #'font-shape = #'upright
1205 c''4-^_"c-\\^{ }" s4
1212 linewidth = 5.875 \in;
1220 @cindex @code{\textscript}
1224 \textscript @var{text} @var{style}
1227 Defines a text to be printed over or under a note. @var{style} is a
1228 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1229 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1231 You can attach a general textscript request using this syntax:
1236 c4-\textscript "6" "finger"
1237 c4-\textscript "foo" "normal"
1242 This is equivalent to @code{c4-6 c4-"foo"}.
1244 @cindex @code{\script}
1253 Prints a symbol above or below a note. The argument is a string which
1254 points into the script-alias table defined in @file{scm/script.scm}.
1255 Usually the @code{\script} keyword is not used directly. Various
1256 helpful identifier definitions appear in @file{script.ly}.
1258 For information on how to add scripts, consult @file{scm/script.scm}.
1265 @subsection Grace notes
1274 @cindex @code{\grace}
1277 @cindex @code{graceAlignPosition}
1280 \grace @var{musicexpr}
1283 A grace note expression has duration 0; the next real note is
1284 assumed to be the main note.
1286 You cannot have the grace note after the main note, in terms of
1287 duration, and main notes, but you can typeset the grace notes to the
1288 right of the main note using the property
1289 @code{graceAlignPosition}.
1290 @cindex @code{flagStyle}
1292 When grace music is interpreted, a score-within-a-score is set up:
1293 @var{musicexpr} has its own time bookkeeping, and you could (for
1294 example) have a separate time signature within grace notes. While in
1295 this score-within-a-score, you can create notes, beams, slurs, etc.
1296 Unbeamed eighth notes and shorter by default have a slash through the
1297 stem. This behavior can be controlled with the
1298 @code{flagStyle} property.
1301 @lilypond[fragment,verbatim]
1303 \grace c8 c4 \grace { [c16 c16] } c4
1304 \grace { \property Grace.flagStyle = "" c16 } c4
1311 At present, nesting @code{\grace} notes is not supported. The following
1312 may cause run-time errors:
1314 @code{\grace @{ \grace c32 c16 @} c4}
1316 Since the meaning of such a construct is unclear, we don't consider
1317 this a loss. Similarly, juxtaposing two @code{\grace} sections is
1318 syntactically valid, but makes no sense and may cause runtime errors.
1320 Ending a staff or score with grace notes may also generate a run-time
1321 error, since there will be no main note to attach the grace notes to.
1323 The present implementation is not robust and generally kludgy. We expect
1324 it to change after LilyPond 1.4. Syntax changes might also be
1337 * Crescendo and Decrescendo::
1346 @subsubsection Glissando
1349 @cindex @code{\glissando}
1351 A glissando line can be requested by attaching a @code{\glissando} to a
1355 @lilypond[fragment,relative,verbatim]
1360 Printing of an additional text (such as @emph{gliss.}) must be done
1367 @subsubsection Dynamics
1380 @cindex @code{\ffff}
1394 Dynamic marks are specified by using an identifier after a note:
1395 @code{c4-\ff}. The available dynamic marks are:
1396 @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f},
1397 @code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf},
1398 @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1400 @c . {Crescendo and Decrescendo}
1401 @node Crescendo and Decrescendo
1402 @subsubsection Crescendo and Decrescendo
1404 @cindex Crescendo and Decrescendo
1408 @cindex @code{\decr}
1409 @cindex @code{\rced}
1416 A crescendo mark is started with @code{\cr} and terminated with
1417 @code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
1418 started with @code{\decr} and terminated with @code{\rced}. There are
1419 also shorthands for these marks. A crescendo can be started with
1420 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1421 can be terminated with @code{\!}. Note that @code{\!} must go before
1422 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1423 after the last note. Because these marks are bound to notes, if you
1424 want to get several marks during one note, you must use spacer notes.
1426 @lilypond[fragment,verbatim,center]
1427 c'' \< \! c'' d'' \decr e'' \rced
1428 < f''1 { s4 \< \! s2 \> \! s4 } >
1431 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1432 is an example how to do it:
1434 @lilypond[fragment,relative,verbatim]
1436 \property Voice.crescendoText = "cresc."
1437 \property Voice.crescendoSpanner = #'dashed-line
1446 @subsubsection Bar lines
1450 @cindex measure lines
1457 This is a short-cut for doing
1459 \property Score.whichBar = @var{bartype}
1462 You are encouraged to use @code{\repeat} for repetitions. See
1463 @ref{Repeats}, and the documentation of @code{whichBar} in
1464 @ref{(lilypond-internals)LilyPond context properties}.
1471 @subsubsection Breath marks
1472 @cindex Breath marks
1478 @subsection Bar check
1482 @cindex @code{barCheckNoSynchronize}
1486 Whenever a bar check is encountered during interpretation, a warning
1487 message is issued if it doesn't fall at a measure boundary. This can
1488 help you find errors in the input. Depending on the value of
1489 @code{barCheckNoSynchronize}, the beginning of the measure will be
1490 relocated, so this can also be used to shorten measures.
1492 A bar check is entered using the bar symbol, @code{|}
1503 @section Piano music
1505 * Automatic staff changes::
1506 * Manual staff switches::
1513 @c . {Automatic staff changes}
1514 @node Automatic staff changes
1515 @subsection Automatic staff changes
1516 @cindex Automatic staff changes
1520 @node Manual staff switches
1521 @subsection Manual staff switches
1523 @cindex manual staff switches
1524 @cindex staff switch, manual
1526 @cindex @code{\translator}
1528 \translator @var{contexttype} = @var{name}
1531 A music expression indicating that the context which is a direct
1532 child of the a context of type @var{contexttype} should be shifted to
1533 a context of type @var{contexttype} and the specified name.
1535 Usually this is used to switch staffs in Piano music, e.g.
1538 \translator Staff = top @var{Music}
1552 @subsection Arpeggio
1555 @cindex broken arpeggio
1556 @cindex @code{\arpeggio}
1558 You can specify an arpeggio sign on a chord by attaching an
1559 @code{\arpeggio} to a note of the chord.
1563 @lilypond[fragment,relative,verbatim]
1564 \context Voice <c'\arpeggio e g c>
1568 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1569 to the chords in both staffs, and set
1570 @code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
1574 @lilypond[fragment,relative,verbatim]
1575 \context PianoStaff <
1576 \property PianoStaff.connectArpeggios = ##t
1577 \context Voice = one { <c''\arpeggio e g c> }
1578 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1585 @c . {Follow Thread}
1587 @subsection Follow Thread
1588 @cindex follow thread
1589 @cindex staff switching
1592 [todo: different name, eg. voice line ? ]
1594 @cindex @code{followThread}
1596 Whenever a voice switches to another staff a line connecting the notes
1597 can be printed automatically. This is enabled if the property
1598 @code{PianoStaff.followThread} is set to true:
1601 @lilypond[fragment,relative,verbatim]
1602 \context PianoStaff <
1603 \property PianoStaff.followThread = ##t
1604 \context Staff \context Voice {
1606 \translator Staff=two
1609 \context Staff=two {\clef bass; \skip 1*2;}
1623 * Automatic syllable durations::
1628 @subsection Lyrics mode
1632 @cindex @code{\lyrics}
1634 Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
1635 rules that make it easy to include punctuation and diacritical marks in
1636 words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
1637 format or a standard encoding without needing quotes. The precise
1638 definition of this mode is ludicrous, and this will remain so until the
1639 authors of LilyPond acquire a deeper understanding of character
1640 encoding, or someone else steps up to fix this.
1642 A word in Lyrics mode begins with: an alphabetic character, @code{_},
1643 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
1644 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
1645 any 8-bit character with ASCII code over 127, or a two-character
1646 combination of a backslash followed by one of @code{`}, @code{'},
1647 @code{"}, or @code{^}.
1649 Subsequent characters of a word can be any character that is not a digit
1650 and not white space. One important consequence of this is that a word
1651 can end with `@code{@}}', which may be confusing. However, LilyPond will
1652 issue a warning. Any @code{_} character which appears in an unquoted
1653 word is converted to a space. This provides a mechanism for introducing
1654 spaces into words without using quotes. Quoted words can also be used
1655 in Lyrics mode to specify words that cannot be written with the above
1656 rules. Here are some examples. Not all of these words are printable by
1661 2B_||_!2B % not a word because it starts with a digit
1662 ``Hello'' % not a word because it starts with `
1663 _ _ _ _ % 4 words, each one a space
1666 Since combinations of numbers and dots are used for indicating
1667 durations, you can not enter real numbers in this mode.
1669 @cindex lyrics expressions
1671 Syllables are entered like notes, with pitches replaced by text. For
1672 example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
1673 with quarter note duration. Note that the hyphen has no special
1674 meaning for lyrics, and does not introduce special symbols. See
1675 section @ref{Lexical modes} for a description of what is interpreted as
1678 Spaces can be introduced into a lyric either by using quotes
1679 (@code{"}) or by using an underscore without quotes: @code{He_could4
1680 not4}. All unquoted underscores are converted to spaces. Printing
1681 lyrics is discussed in the next section.
1684 @c . {Printing lyrics}
1685 @node Printing lyrics
1686 @subsection Printing lyrics
1690 Lyric syllables must be interpreted within a @code{Lyrics} context for
1691 printing them. Here is a full example:
1697 \notes \transpose c'' {
1699 e f g2 | e4 f g2 \bar "|.";
1701 \context Lyrics \lyrics {
1702 Va-4 der Ja- cob Va- der Ja- cob
1703 Slaapt gij nog?2 Slaapt4 gij nog?2
1715 @cindex lyric extender
1717 You may want a continuous line after the syllables to show melismata.
1718 To achieve this effect, add a @code{__} lyric as a separate word
1719 after the lyric to be extended. This will create an extender, a line
1720 that extends over the entire duration of the lyric. This line will
1721 run all the way to the start of the next lyric, so you may want to
1722 shorten it by using a blank lyric (using @code{_}).
1729 \notes \relative c'' {
1730 a4 () b () c () d | c () d () b () a | c () d () b () a
1732 \context Lyrics \lyrics {
1733 foo1 __ | bar2. __ _4 | baz1 __
1741 @cindex Lyric hyphen
1743 If you want to have hyphens centered between syllables (rather than
1744 attached to the end of the first syllable) you can use the special
1745 `@code{-}@code{-}' lyric as a separate word between syllables. This
1746 will result in a hyphen which length varies depending on the space
1747 between syllables, and which will be centered between the syllables.
1755 \notes \transpose c'' {
1757 e f g2 | e4 f g2 \bar "|.";
1759 \context Lyrics \lyrics {
1760 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1761 Slaapt gij nog?2 | Slaapt4 gij nog?2
1770 @c . {Automatic syllable durations}
1771 @node Automatic syllable durations
1772 @subsection Automatic syllable durations
1773 @cindex Automatic syllable durations
1776 [explain automatic phrasing]
1777 @cindex automatic lyric durations
1778 @cindex @code{\addlyrics}
1780 If you have lyrics that are set to a melody, you can import the rhythm
1781 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1784 \addlyrics @var{musicexpr1 musicexpr2}
1787 This means that both @var{musicexpr1} and @var{musicexpr2} are
1788 interpreted, but that every non-command atomic music expression
1789 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1790 of @var{musicexpr1}.
1791 @cindex @code{automaticMelismata}
1793 If the property @code{automaticMelismata} is set in the
1794 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1798 @lilypond[verbatim,fragment]
1801 \property Voice.automaticMelismata = ##t
1802 c8 () cis d8. e16 f2
1804 \context Lyrics \lyrics {
1809 You should use a single rhythm melody, and single rhythm lyrics (a
1810 constant duration is the obvious choice). If you do not, you will get
1811 undesired effects when using multiple stanzas:
1814 @lilypond[verbatim,fragment]
1817 c8 () cis d8. e16 f2
1819 \context Lyrics \lyrics
1826 It is valid (but probably not very useful) to use notes instead of
1827 lyrics for @var{musicexpr2}.
1836 [chords vs. simultaneous music]
1840 * Entering named chords::
1841 * Printing named chords::
1846 @subsection Chords mode
1849 Chord mode is introduced by the keyword
1850 @code{\chords}. It is similar to Note mode, but
1851 words are also looked up in a chord modifier table (containing
1852 @code{maj}, @code{dim}, etc).
1854 Since combinations of numbers and dots are used for indicating
1855 durations, you can not enter real numbers in this mode. Dashes
1856 and carets are used to indicate chord additions and subtractions,
1857 so scripts can not be entered in Chord mode.
1859 @c . {Entering named chords}
1860 @node Entering named chords
1861 @subsection Entering named chords
1862 @cindex Chords names
1864 Chord names are a way to generate simultaneous music expressions that
1865 correspond with traditional chord names. It can only be used in
1866 Chord mode (see section @ref{Lexical modes}).
1870 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1873 @var{tonic} should be the tonic note of the chord, and @var{duration}
1874 is the chord duration in the usual notation. There are two kinds of
1875 modifiers. One type is @emph{chord additions}, which are obtained by
1876 listing intervals separated by dots. An interval is written by its
1877 number with an optional @code{+} or @code{-} to indicate raising or
1878 lowering by half a step. Chord additions has two effects: It adds
1879 the specified interval and all lower odd numbered intervals to the
1880 chord, and it may lower or raise the specified interval. Intervals
1881 must be separated by a dot (@code{.}).
1884 Throughout these examples, chords have been shifted around the staff
1885 using @code{\transpose}.
1890 @lilypond[fragment,verbatim]
1894 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1906 The second type of modifier that may appear after the @code{:} is a
1907 named modifier. Named modifiers are listed in the file
1908 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
1909 @code{min} which lower the 3rd half a step, `@code{aug}' which
1910 raises the 5th, `@code{dim}' which lowers the 5th,
1911 `@code{maj}' which adds a raised 7th, and `@code{sus}'
1912 which replaces the 5th with a 4th.
1916 @lilypond[fragment,verbatim]
1919 c1:m c:min7 c:maj c:aug c:dim c:sus
1927 Chord subtractions are used to eliminate notes from a chord. The
1928 notes to be subtracted are listed after a @code{^} character,
1931 @lilypond[fragment,verbatim,center]
1940 Chord inversions can be specified by appending `@code{/}' and
1941 the name of a single note to a chord. This has the effect of
1942 lowering the specified note by an octave so it becomes the lowest
1943 note in the chord. If the specified note is not in the chord, a
1944 warning will be printed.
1946 @lilypond[fragment,verbatim,center]
1956 Bass notes can be added by `@code{/+}' and
1957 the name of a single note to a chord. This has the effect of
1958 adding the specified note to the chord, lowered by an octave,
1959 so it becomes the lowest note in the chord.
1961 @lilypond[fragment,verbatim,center]
1970 The most interesting application is printing chord names, which is
1971 explained in the next subsection.
1973 You should not combine @code{\relative} with named chords. [FIXME]
1975 @c . {Printing named chords}
1976 @node Printing named chords
1977 @subsection Printing named chords
1983 @cindex printing chord names
1986 @cindex @code{ChordNames}
1987 @cindex @code{ChordNameVoice}
1989 For displaying printed chord names, use the @code{ChordNames} and
1990 @code{ChordNameVoice} contexts. The chords may be entered either using
1991 the notation described above, or directly using simultaneous music.
1996 \chords {a1 b c} <d f g> <e g b>
2000 \context ChordNamesVoice \scheme
2001 \context Staff \transpose c'' \scheme
2003 \paper { linewidth = -1.; }
2008 You can make the chord changes stand out more by setting property
2009 @code{ChordNames.chordChanges} to true. This will only display chord
2010 names when there's a change in the chords scheme, but always display the
2011 chord name after a line break:
2017 c1:m \break c:m c:m c:m d
2022 \context ChordNames \scheme
2023 \context Staff \transpose c'' \scheme
2026 linewidth = 40 * \staffspace;
2038 LilyPond examines chords specified as lists of notes to determine a
2039 name to give the chord. LilyPond will not try to
2040 identify chord inversions or added base, which may result in strange
2041 chord names when chords are entered as a list of pitches:
2044 @lilypond[verbatim,center]
2053 \context ChordNamesVoice \scheme
2054 \context Staff \scheme
2056 \paper { linewidth = -1.; }
2061 To specify chord inversions, append @code{/<notename>}. To specify an
2062 added bass note, append @code{/+<notename}:
2065 @lilypond[verbatim,center]
2072 \context ChordNames \scheme
2073 \context Staff \transpose c'' \scheme
2075 \paper { linewidth = -1.; }
2080 The chord names that LilyPond should print are fully customizable. The
2081 code to print chord names is written in Scheme. It can be found in
2082 @file{scm/chord-name.scm}. Chord names are based on Banter style
2083 naming, which is unambiguous and has a logical structure. Typical
2084 American style chord names are implemented as a variation on Banter
2085 names, they can be selected by setting property @code{ChordName.style}
2090 \include "english.ly"
2095 df:m5- % Diminished triad
2096 c:5^3 % Root-fifth chord
2097 c:4^3 % Suspended fourth triad
2098 c:5+ % Augmented triad
2100 c:m5-.7- % Diminished seventh
2101 c:7+ % Major seventh
2102 c:7.4^3 % Dominant seventh suspended fourth
2103 c:5+.7 % Augmented dominant seventh
2104 c:m5-.7 % "Half" diminished seventh
2105 c:5-.7 % Dominant seventh flat fifth
2106 c:5-.7+ % Major seventh flat fifth
2107 c:m7+ % Minor-major seventh
2108 c:m7 % Minor seventh
2109 c:7 % Dominant seventh
2112 c:9^7 % Major triad w/added ninth
2113 c:6.9^7 % Six/Nine chord
2114 c:9 % Dominant ninth
2115 c:7+.9 % Major ninth
2116 c:m7.9 % Minor ninth
2121 \context ChordNames \scheme
2122 \context Staff \transpose c'' \scheme
2127 ChordName \override #'word-space = #1
2128 ChordName \override #'style = #'american
2135 Similarly, Jazz style chord names are implemented as a variation on
2136 American style names:
2142 c:6 % 6 = major triad with added sixth
2143 c:maj % triangle = maj
2148 c:m % m = minor triad
2149 c:m.6 % m6 = minor triad with added sixth
2150 c:m.7+ % m triangle = minor major seventh chord
2158 c:7.5+ % +7 = augmented dominant
2159 c:7.5- % 7b5 = hard diminished dominant
2166 c:13.9-^11 % 7(b9,13)
2167 c:13.9+^11 % 7(#9,13)
2169 c:13-.9-^11 % 7(b9,b13)
2170 c:13-.9+^11 % 7(#9,b13)
2172 % half diminished chords
2173 c:m5-.7 % slashed o = m7b5
2174 c:9.3-.5- % o/7(pure 9)
2177 c:m5-.7- % o = diminished seventh chord
2182 \context ChordNames \scheme
2183 \context Staff \transpose c'' \scheme
2188 ChordName \override #'word-space = #1
2189 ChordName \override #'style = #'jazz
2197 @section Writing parts
2202 * Instrument names::
2204 * Multi measure rests::
2213 tranposing midi property.
2219 @c . {Rehearsal marks}
2220 @node Rehearsal marks
2221 @subsection Rehearsal marks
2222 @cindex Rehearsal marks
2224 @cindex @code{\mark}
2225 @cindex @code{Mark_engraver}
2228 \mark @var{unsigned};
2233 With this command, you can print a rehearsal mark above the system. You
2234 can provide a number, a string or a markup text as argument. If there is
2235 no argument, the property @code{rehearsalMark} is used and automatically
2238 @lilypond[fragment,verbatim]
2244 c1 \mark #'(music "scripts-segno") ;
2249 @node Instrument names
2250 @subsection Instrument names
2252 You can specify an instrument name for a staff by setting
2253 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2254 before the start of the staff. For the first start, @code{instrument} is
2255 used, for the next ones @code{instr} is used.
2259 \property Staff.instrument = "instr " { c''4 } }
2260 \paper { linewidth = -1.;
2261 \translator { \StaffContext
2262 \consists "Instrument_name_engraver"; } } }
2265 This requires that you add the @code{Instrument_name_engraver} to the
2270 @subsection Transpose
2272 @cindex transposition of pitches
2273 @cindex @code{\transpose}
2275 A music expression can be transposed with @code{\transpose}. The syntax
2278 \transpose @var{pitch} @var{musicexpr}
2281 This means that middle C in @var{musicexpr} is transposed to
2284 @code{\transpose} distinguishes between enharmonic pitches: both
2285 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2286 a tone. The first version will print sharps and the second version
2290 @lilypond[fragment,verbatim]
2293 { \key e \major; c d e f }
2295 \transpose des'' { \key e \major; c d e f }
2296 \transpose cis'' { \key e \major; c d e f }
2302 If you want to use both @code{\transpose} and @code{\relative}, then
2303 you must use @code{\transpose} first. @code{\relative} will have no
2304 effect music that appears inside a @code{\transpose}.
2307 @c . {Multi measure rests}
2308 @node Multi measure rests
2309 @subsection Multi measure rests
2310 @cindex Multi measure rests
2314 Multi measure rests are entered using `@code{R}'. It is specifically
2315 meant for entering parts: the rest can expand to fill a score with
2316 rests, or it can be printed as a single multimeasure rest This expansion
2317 is controlled by the property @code{Score.skipBars}. If this is set to true,
2318 Lily will not expand empty measures, and the appropriate number is added
2321 @lilypond[fragment,verbatim]
2322 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2325 Currently, there is no way to condense multiple rests into a single
2328 @cindex condensing rests
2336 A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a
2337 staff context symbol that appears at the end of a staff line. It
2338 anticipates the pitch of the first note(s) of the following line and
2339 thus helps the player or singer to manage line breaks during
2340 performance, thus enhancing readability of a score.
2345 \notes { c'1 d' e' d' \break c' d' e' d' }
2349 \consists Custos_engraver;
2350 Custos \override #'style = #'mensural;
2357 Custodes were frequently used in music notation until the 16th century.
2358 There were different appearences for different notation styles.
2359 Nowadays, they have survived only in special forms of musical notation
2360 such as via the editio vaticana dating back to the beginning of the 20th
2363 For typesetting custodes, just put a @code{Custos_engraver} into the
2364 @code{StaffContext} when declaring the @code{\paper} block. In this
2365 block, you can also globally control the appearance of the custos symbol
2366 by setting the custos @code{style} property. Currently supported styles
2367 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2374 \consists Custos_engraver;
2375 Custos \override #'style = #'mensural;
2380 The property can also be set locally, for example in a @code{\notes}
2385 \property Staff.Custos \override #'style = #'vaticana
2386 c'1 d' e' d' \break c' d' e' d'
2392 @section Page layout
2406 @subsection Paper block
2409 The most important output definition is the @code{\paper} block, for
2410 music notation. The syntax is
2413 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2416 where each of the items is one of
2419 @item An assignment. The assignment must be terminated by a
2422 @item A context definition. See section @ref{Context definitions} for
2423 more information on context definitions.
2425 @item \stylesheet declaration. Its syntax is
2427 \stylesheet @var{alist}
2430 See @file{font.scm} for details of @var{alist}.
2433 @c . {Paper variables}
2434 @node Paper variables
2435 @subsection Paper variables
2436 @cindex Paper variables
2438 The paper block has some variables you may want to use or change:
2441 @cindex @code{indent}
2443 The indentation of the first line of music.
2444 @cindex @code{staffspace}
2446 @item @code{staffspace}
2447 The distance between two staff lines, calculated from the center
2448 of the lines. You should use either this or @code{stafflinethickness}
2449 as a unit for distances you modify.
2451 @cindex @code{linewidth}
2452 @item @code{linewidth}
2453 Sets the width of the lines.
2455 If set to a negative value, a single
2456 unjustified line is produced.
2458 @cindex @code{textheight}
2460 @item @code{textheight}
2461 Sets the total height of the music on each page. Only used by
2463 @cindex @code{interscoreline}
2465 @item @code{interscoreline}
2466 Sets the spacing between the score lines. Defaults to 16 pt.
2467 @cindex @code{interscorelinefill}
2469 @item @code{interscorelinefill}
2470 If set to a positive number, the distance between the score
2471 lines will stretch in order to fill the full page. In that
2472 case @code{interscoreline} specifies the minimum spacing.
2474 @cindex @code{stafflinethickness}
2476 @item @code{stafflinethickness}
2477 Determines the thickness of staff lines, and also acts as a scaling
2478 parameter for other line thicknesses.
2485 @subsection Font size
2488 The Feta font provides musical symbols at six different sizes. These
2489 fonts are 11 point, 13 point, 16 point, 20 point,
2490 23 point, and 26 point. The point size of a font is the
2491 height of the five lines in a staff when displayed in the font.
2493 Definitions for these sizes are the files @file{paperSZ.ly}, where
2494 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2495 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2496 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2497 @code{paperTwentysix} are defined respectively. The default
2498 @code{\paper} block is also set.
2500 The font definitions are generated using a Scheme function. For more
2501 details, see the file @file{font.scm}.
2507 @subsection Paper size
2512 @cindex @code{papersize}
2514 To change the paper size, you must first set the
2515 @code{papersize} variable at top level. Set it to
2516 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2517 specification, you must set the font as described above. If you want
2518 the default font, then use the 20 point font. The new paper size will
2519 not take effect if the font is not loaded and selected afterwards.
2523 \include "paper16.ly"
2527 \paper @{ \paperSixteen @}
2531 The file "paper16.ly" will now include a file named @file{a4.ly}, which
2532 will set the paper variables @code{hsize} and @code{vsize} (used by
2543 @subsection Line break
2546 @cindex breaking lines
2548 Line breaks are normally computed automatically. They are chosen such
2549 that the resulting spacing has low variation, and looks neither cramped
2552 Occasionally you might want to override the automatic breaks; you can do
2553 this by specifying @code{\break}. This will force a line break at this
2554 point. Do remember that line breaks can only occur at places where there
2555 are barlines. If you want to have a line break where there is no
2556 barline, you can force a barline by entering @code{\bar "";}.
2558 Similarly, @code{\noBreak} forbids a line break at a certain point.
2560 @cindex @code{\penalty}
2562 The @code{\break} and @code{\noBreak} commands are defined in terms of
2563 the penalty command:
2565 \penalty @var{int} @code{;}
2568 This imposes encourages or discourages LilyPond to make a line break
2571 @strong{Warning} do not use @code{\penalty} directly. It is rather
2572 kludgy, and slated for rewriting.
2576 @subsection Page break
2579 @cindex breaking pages
2582 Page breaks are normally computed by @TeX{}, so they are not under direct
2583 control. However, you can insert a commands into the @file{.tex} output to
2584 instruct @TeX{} where to break pages. For more details, see the
2585 example file @file{input/test/between-systems.ly}
2600 * MIDI instrument names::
2606 @subsection MIDI block
2610 The MIDI block is analogous to the paper block, but it is somewhat
2611 simpler. The @code{\midi} block can contain:
2615 @item a @code{\tempo} definition
2616 @item context definitions
2619 Assignments in the @code{\midi} block are not allowed.
2623 @cindex context definition
2625 Context definitions follow precisely the same syntax as within the
2626 \paper block. Translation modules for sound are called performers.
2627 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2630 @c . {MIDI instrument names}
2631 @node MIDI instrument names
2632 @subsection MIDI instrument names
2633 @cindex instrument names
2634 @cindex @code{Staff.midiInstrument}
2635 @cindex @code{Staff.instrument}
2637 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2638 property or, if that property is not set, the @code{Staff.instrument}
2639 property. The instrument name should be chosen from the following list.
2640 If the selected string does not exactly match, then LilyPond uses the
2643 [FIXME: to appendix ]
2647 "acoustic grand" "contrabass" "lead 7 (fifths)"
2648 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2649 "electric grand" "pizzicato strings" "pad 1 (new age)"
2650 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2651 "electric piano 1" "timpani" "pad 3 (polysynth)"
2652 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2653 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2654 "clav" "synthstrings 1" "pad 6 (metallic)"
2655 "celesta" "synthstrings 2" "pad 7 (halo)"
2656 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2657 "music box" "voice oohs" "fx 1 (rain)"
2658 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2659 "marimba" "orchestra hit" "fx 3 (crystal)"
2660 "xylophone" "trumpet" "fx 4 (atmosphere)"
2661 "tubular bells" "trombone" "fx 5 (brightness)"
2662 "dulcimer" "tuba" "fx 6 (goblins)"
2663 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2664 "percussive organ" "french horn" "fx 8 (sci-fi)"
2665 "rock organ" "brass section" "sitar"
2666 "church organ" "synthbrass 1" "banjo"
2667 "reed organ" "synthbrass 2" "shamisen"
2668 "accordion" "soprano sax" "koto"
2669 "harmonica" "alto sax" "kalimba"
2670 "concertina" "tenor sax" "bagpipe"
2671 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2672 "acoustic guitar (steel)" "oboe" "shanai"
2673 "electric guitar (jazz)" "english horn" "tinkle bell"
2674 "electric guitar (clean)" "bassoon" "agogo"
2675 "electric guitar (muted)" "clarinet" "steel drums"
2676 "overdriven guitar" "piccolo" "woodblock"
2677 "distorted guitar" "flute" "taiko drum"
2678 "guitar harmonics" "recorder" "melodic tom"
2679 "acoustic bass" "pan flute" "synth drum"
2680 "electric bass (finger)" "blown bottle" "reverse cymbal"
2681 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2682 "fretless bass" "whistle" "breath noise"
2683 "slap bass 1" "ocarina" "seashore"
2684 "slap bass 2" "lead 1 (square)" "bird tweet"
2685 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2686 "synth bass 2" "lead 3 (calliope)" "helicopter"
2687 "violin" "lead 4 (chiff)" "applause"
2688 "viola" "lead 5 (charang)" "gunshot"
2689 "cello" "lead 6 (voice)"
2700 @cindex beats per minute
2701 @cindex metronome marking
2703 @cindex @code{\tempo}
2705 \tempo @var{duration} = @var{perminute} @code{;}
2708 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
2709 output with 76 quarter notes per minute.
2717 @section Music entry
2728 @subsection Relative
2730 @cindex relative octave specification
2732 Octaves are specified by adding @code{'} and @code{,} to pitch names.
2733 When you copy existing music, it is easy to accidentally put a pitch in
2734 the wrong octave and hard to find such an error. To prevent these
2735 errors, LilyPond features octave entry.
2737 @cindex @code{\relative}
2739 \relative @var{startpitch} @var{musicexpr}
2742 The octave of notes that appear in @var{musicexpr} are calculated as
2743 follows: If no octave changing marks are used, the basic interval
2744 between this and the last note is always taken to be a fourth or less.
2745 The octave changing marks @code{'} and @code{,} can then
2746 be added to raise or lower the pitch by an extra octave. Upon entering
2747 relative mode, an absolute starting pitch must be specified that will
2748 act as the predecessor of the first note of @var{musicexpr}.
2750 This distance is determined without regarding accidentals: a
2751 @code{fisis} following a @code{ceses} will be put above the
2754 Entering scales is straightforward in relative mode.
2756 @lilypond[fragment,verbatim,center]
2758 g a b c d e f g g, g
2762 And octave changing marks are used for intervals greater than a fourth.
2764 @lilypond[fragment,verbatim,center]
2766 c g c f, c' a, e'' }
2769 If the preceding item is a chord, the first note of the chord is used
2770 to determine the first note of the next chord. But other notes
2771 within the second chord are determined by looking at the immediately
2774 @lilypond[fragment,verbatim,center]
2781 @cindex @code{\notes}
2783 The pitch after the @code{\relative} contains a notename. To parse
2784 the pitch as a notename, you have to be in note mode, so there must
2785 be a surrounding @code{\notes} keyword (which is not
2788 The relative conversion will not affect @code{\transpose} or
2789 @code{\relative} sections in its argument. If you want to use
2790 relative within transposed music, you must place an additional
2791 @code{\relative} inside the @code{\transpose}.
2794 @c . {Point and click}
2795 @node Point and click
2796 @subsection Point and click
2805 * Selecting contexts::
2806 * Context definitions::
2807 * Notation Contexts::
2810 @c . {Music expressions}
2811 @node Selecting contexts
2812 @subsection Selecting contexts
2814 @cindex @code{\context}
2815 @cindex context selection
2818 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
2821 Interpret @var{musicexpr} within a context of type @var{contexttype}.
2822 If the context does not exist, it will be created. The new context
2823 can optionally be given a name.
2827 @c . {Context definitions}
2828 @node Context definitions
2829 @subsection Context definitions
2831 @cindex context definition
2832 @cindex translator definition
2833 @cindex engraver hacking
2836 A notation contexts is defined by the following information
2841 @item The LilyPond modules that do the actual conversion of music to
2842 notation. Each module is a so-called
2847 @item How these modules should cooperate, i.e. which ``cooperation
2848 module'' should be used. This cooperation module is a special
2851 @item What other contexts the context can contain,
2853 @item What properties are defined.
2856 A context definition has this syntax:
2860 \translator @code{@{}
2861 @var{translatorinit} @var{translatormodifierlist}
2865 @var{translatorinit} can be an identifier or
2867 \type @var{typename} @code{;}
2869 where @var{typename} is one of
2872 @cindex @code{Engraver_group_engraver}
2873 @item @code{Engraver_group_engraver}
2874 The standard cooperation engraver.
2875 @cindex @code{Score_engraver}
2877 @item @code{Score_engraver}
2878 This is cooperation module that should be in the top level context.
2879 @cindex @code{Grace_engraver_group}
2881 @item @code{Grace_engraver_group}
2882 This is a special cooperation module (resembling
2883 @code{Score_engraver}) that is used to created an embedded
2887 @var{translatormodifierlist} is a list of items where each item is
2891 @item @code{\consists} @var{engravername} @code{;}
2892 Add @var{engravername} to the list of modules in this context.
2893 The order of engravers added with @code{\consists} is
2896 @item @code{\consistsend} @var{engravername} @code{;}
2897 Analogous to @code{\consists}, but makes sure that
2898 @var{engravername} is always added to the end of the list of
2901 Some engraver types need to be at the end of the list; this
2902 insures they are put there, and stay there, if a user adds or
2903 removes engravers. This command is usually not needed for
2906 @item @code{\accepts} @var{contextname} @code{;}
2907 Add @var{contextname} to the list of context this context can
2908 contain. The first listed context is the context to create by
2911 @item @code{\denies}. The opposite of @code{\accepts}. Added for
2912 completeness, but is never used in practice.
2915 @item @code{\remove} @var{engravername} @code{;}
2916 Remove a previously added (with @code{\consists}) engraver.
2918 @item @code{\name} @var{contextname} @code{;}
2919 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2920 the name is not specified, the translator won't do anything.
2922 @item @var{propname} @code{=} @var{value} @code{;}
2923 A property assignment.
2926 In the @code{\paper} block, it is also possible to define translator
2927 identifiers. Like other block identifiers, the identifier can only
2928 be used as the very first item of a translator. In order to define
2929 such an identifier outside of @code{\score}, you must do
2935 foo = \translator @{ @dots{} @}
2942 \translator @{ \foo @dots{} @}
2950 @cindex paper types, engravers, and pre-defined translators
2952 Some pre-defined identifiers can simplify modification of
2953 translators. The pre-defined identifiers are:
2956 @cindex @code{StaffContext}
2957 @item @code{StaffContext}
2958 Default Staff context.
2959 @cindex @code{RhythmicStaffContext}
2961 @item @code{RhythmicStaffContext}
2962 Default RhythmicStaff context.
2963 @cindex @code{VoiceContext}
2965 @item @code{VoiceContext}
2966 Default Voice context.
2967 @cindex @code{ScoreContext}
2969 @item @code{ScoreContext}
2970 Default Score context.
2972 @cindex @code{HaraKiriStaffContext}
2974 @item @code{HaraKiriStaffContext}
2975 Staff context that does not print if it only contains rests.
2976 Useful for orchestral scores.@footnote{Harakiri, also called
2977 Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
2981 Using these pre-defined values, you can remove or add items to the
2990 \remove Some_engraver;
2991 \consists Different_engraver;
3001 @c . {Notation Contexts}
3002 @node Notation Contexts
3003 @subsection Notation Contexts
3005 @cindex notation contexts
3007 Notation contexts are objects that only exist during a run of
3008 LilyPond. During the interpretation phase of LilyPond, the Music
3009 expression contained in a @code{\score} block is interpreted in time
3010 order. This is the order in which humans read, play, and write
3013 A context is an object that holds the reading state of the
3014 expression; it contains information like
3017 @item What notes are playing at this point?
3018 @item What symbols will be printed at this point?
3019 @item In what style will they printed?
3020 @item What is the current key signature, time signature, point within
3024 Contexts are grouped hierarchically: A @code{Voice} context is
3025 contained in a @code{Staff} context (because a staff can contain
3026 multiple voices at any point), a @code{Staff} context is contained in
3027 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
3028 these can all contain multiple staffs).
3030 Contexts associated with sheet music output are called @emph{notation
3031 contexts}, those for sound output are called performance contexts.
3033 Contexts are created either manually or automatically. Initially, the
3034 top level music expression is interpreted by the top level context (the
3035 @code{Score} context). When a atomic music expression (i.e. a note, a
3036 rest, etc.), a nested set of contexts is created that can process these
3037 atomic expressions, as in this example:
3040 \score @{ \notes @{ c4 @} @}
3043 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
3044 context. When the note @code{c4} itself is interpreted, a set of
3045 contexts is needed that will accept notes. The default for this is a
3046 @code{Voice} context, contained in a @code{Staff} context. Creation of
3047 these contexts results in the staff being printed.
3051 You can also create contexts manually, and you probably have to do so
3052 if you want to typeset complicated multiple part material. If a
3053 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
3054 during the interpretation phase, the @var{musicexpr} argument will be
3055 interpreted with a context of type @var{name}. If you specify a name,
3056 the specific context with that name is searched.
3060 If a context of the specified type and name can not be found, a new
3061 one is created. For example,
3067 \notes \relative c'' {
3068 c4 <d4 \context Staff = "another" e4> f
3075 In this example, the @code{c} and @code{d} are printed on the
3076 default staff. For the @code{e}, a context Staff called
3077 @code{another} is specified; since that does not exist, a new
3078 context is created. Within @code{another}, a (default) Voice context
3079 is created for the @code{e4}. When all music referring to a
3080 context is finished, the context is ended as well. So after the
3081 third quarter, @code{another} is removed.
3083 Almost all music expressions inherit their interpretation context
3084 from their parent. In other words, suppose that the syntax for a
3089 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
3092 When the interpretation of this music expression starts, the context
3093 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
3096 Lastly, you may wonder, why this:
3102 \notes \relative c'' @{
3110 doesn't result in this:
3115 \notes \relative c'' {
3122 For the @code{c4}, a default @code{Staff} (with a contained
3123 @code{Voice}) context is created. After the @code{c4} ends, no
3124 music refers to this default staff, so it would be ended, with the
3125 result shown. To prevent this inconvenient behavior, the context to
3126 which the sequential music refers is adjusted during the
3127 interpretation. So after the @code{c4} ends, the context of the
3128 sequential music is also the default @code{Voice} context.
3129 The @code{d4} gets interpreted in the same context
3132 Properties that are set in one context are inherited by all of the
3133 contained contexts. This means that a property valid for the
3134 @code{Voice} context can be set in the @code{Score} context (for
3135 example) and thus take effect in all @code{Voice} contexts.
3137 Properties can be preset within the @code{\translator} block
3138 corresponding to the appropriate context. In this case, the syntax
3142 @var{propname} @code{=} @var{value}
3145 This assignment happens before interpretation starts, so a
3146 @code{\property} expression will override any predefined settings.
3148 The property settings are used during the interpretation phase. They
3149 are read by the LilyPond modules where interpretation contexts are
3150 built of. These modules are called @emph{translators}. Translators for
3151 notation are called @emph{engravers}, and translators for sound are
3152 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
3728 [todo: add \set/\override/\revert]
3731 @cindex @code{\property}
3733 \property @var{contextname}.@var{propname} = @var{value}
3736 Sets the @var{propname} property of the context @var{contextname} to
3737 the specified @var{value}. All three arguments are strings.
3738 Depending on the context, it may be necessary to quote the strings or
3739 to leave space on both sides of the dot.
3742 @cindex output properties
3743 @unnumberedsubsec Output properties
3745 These allow you to tweak what is happening in the back-end
3746 directly. If you want to control every detail of the output
3747 formatting, this is the feature to use. The downside to this is that
3748 you need to know exactly how the backend works. Example:
3751 @lilypond[fragment,verbatim]
3753 \context Staff \outputproperty
3754 #(make-type-checker 'note-head-interface)
3755 #'extra-offset = #'(0.5 . 0.75)
3759 This selects all note heads occurring at current staff level, and sets
3760 the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting
3763 Use of this feature is entirely on your own risk: if you use this, the
3764 result will depend very heavily on the implementation of the backend,
3765 which we change regularly and unscrupulously.
3768 Don't move the finger 2, only text "m.d." ...
3770 #(define (make-text-checker text)
3771 (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
3774 \notes\relative c''' {
3775 \property Voice.Stem \set #'direction = #1
3776 \outputproperty #(make-text-checker "m.d.")
3777 #'extra-offset = #'(-3.5 . -4.5)
3780 \paper { linewidth = -1.; }
3790 @subsection Text markup
3792 LilyPond has an internal mechanism to typeset texts: you can
3793 form text markup expressions by composing scheme expressions
3794 in the following way:
3797 \score { \notes \relative c' {
3800 d-#'(lines "one" (bold "text"))
3801 e-#'(music (named "noteheads-2" "flags-u3"))
3803 \paper { linewidth = 10.\cm; } }
3806 Formally, Scheme markup text is defined as follows:
3809 text: string | (markup sentence)
3810 sentence: text | sentence text
3811 markup: property | abbrev | style
3812 property: (@var{key} . @var{value})
3813 abbrev: @code{rows lines roman music bold italic named super sub text}
3814 style: @var{fontstyle}
3817 The @var{key}-@var{value} pair is a grob property. [Why is this
3818 useful?] The following abbreviations are currently defined:
3822 horizontal mode: set all text on one line (default)
3824 vertical mode: set every text on new line
3834 lookup by character name
3836 plain text lookup (by character value)
3844 @var{fontstyle} may be any of @code{finger volta timesig mmrest mark
3845 script large Large dynamic}
3850 [I still think that the semantics are weird, but well]
3852 @c .{Local emacs vars}
3855 @c minor-mode: font-lock
3856 @c minor-mode: outline
3857 @c outline-layout: (-1 : 0)
3858 @c outline-use-mode-specific-leader: "@c \."
3859 @c outline-primary-bullet: "{"
3860 @c outline-stylish-prefixes: nil
3861 @c outline-override-protect: t