3 @c - Reinsert subsection commands that were lost in the
4 @c ancient conversion from YODL! /MB
5 @c - Restructure! Separate internal commands from user level commands. /MB
6 @c - Add some words about Guile. /MB
7 @c - Fix indexing (keyindex) so it doesn't add line breaks /MB
9 @node Reference Manual, , , Top
10 @chapter Reference Manual
14 * Top level:: Top level
15 * notenames:: notenames
16 * Lexical conventions:: Lexical conventions
17 * Other languages:: notelang
20 * Music expressions:: Music expressions
21 * Atomic music expressions:: Atomic music expressions
22 * Note specification:: notedesc
24 * Manual beams:: Manual beam
25 * stem tremolo:: tremolo
26 * Compound music expressions:: Compound music expressions
29 * transpose:: transpose
30 * Ambiguities:: Ambiguities
31 * Notation conversion specifics:: Notation conversion specifics
33 * lyricprint:: lyricprint
34 * Notation Contexts:: Notation Contexts
35 * Properties:: Changing formatting
36 * Notation output definitions:: Notation output definitions
38 * Paper variables:: papervars
39 * contextdefs:: contextdefs
40 * Sound output:: Sound output
42 * Pre-defined Identifiers:: Pre-defined Identifiers
43 @c May be fragile. Better make single link to generated doco?
44 * Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
45 * Engravers:(lilypond-internals)LilyPond engravers.
46 * Backend:(lilypond-internals)LilyPond backend.
51 @node Overview, , , Reference Manual
54 This document@footnote{This document has been revised for
55 LilyPond 1.2.} describes the the GNU LilyPond input format, which is
56 a language for defining music. We call this language @emph{Music
57 Definition Language} or @emph{Mudela}, for short.@footnote{If anybody
58 comes up with a better name, we'd gladly take this. Gourlay already
59 uses a ``Musical Description Language,'' ISO standard 10743 defines a
60 ``Standard Music Description Language.'' We're not being original
63 @emph{Mudela} is a language that allows you to
66 @item create musical expressions by combining pitches, durations
67 @item output those musical expressions to various formats
68 @item give those musical expressions and output definitions names, so
69 you can enter them in manageable chunks.
72 @emph{Mudela} aims to define a piece of music completely, both from
73 typesetting and from a performance point of view.
77 @node Top level, , , Reference Manual
82 This section describes what you may enter at top level.
86 @cindex score definition
88 The output is generated combining a music expression with an output
89 definition. A score block has the following syntax:
92 \score @{ @var{musicexpr} @var{outputdefs} @}
95 @var{outputdefs} are zero or more output definitions. If no output
96 definition is supplied, the default @code{\paper} block will be added.
107 \header @{ @var{key1} = @var{val1};
108 @var{key2} = @var{val2}; @dots{} @}
111 A header describes the file's contents. It can also appear in a
112 @code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this
113 information for generating titles. Key values that are used by
114 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
115 metre, arranger, piece and tagline.
117 It is customary to put the @code{\header} at the top of the file.
120 @node notenames, , , Reference Manual
122 Note name tables can be specified using
125 \notenames@keyindex{notenames}
126 @{ @var{assignmentlist} @}
129 @var{assignmentlist} is a list of definitions of the form
132 @var{name} = @var{pitch}
135 Chord modifiers can be set analogously, with
136 @code{\chordmodifiers}@keyindex{chordmodifiers}.
138 A @code{\paper} block at top level sets the default paper block. A
139 @code{\midi} block at top level works similarly.
143 LilyPond contains a Scheme interpreter (the GUILE library) for
144 internal use. The following commands access the interpreter
151 Evaluates the specified Scheme code. The result is discarded.
153 Identifier assignments may appear at top level. Semicolons are
154 forbidden after top level assignments.
158 @node Lexical conventions, , , Reference Manual
159 @section Lexical conventions
161 @cindex lexical conventions
170 A one line comment is introduced by a `@code{%}' character.
171 Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
172 They cannot be nested.
178 Keywords start with a backslash, followed by a number of lower case
179 alphabetic characters. These are all the keywords.
242 Formed from an optional minus sign followed by digits. Arithmetic
243 operations cannot be done with integers, and integers cannot be mixed
251 Formed from an optional minus sign and a sequence of digits followed
252 by a @emph{required} decimal point and an optional exponent such as
253 @code{-1.2e3}. Reals can be built up using the usual operations:
254 `@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
255 `@code{/}@indexcode{/}', with parentheses for grouping.
257 A real constant can be followed by one of the dimension
260 @code{\mm}@keyindex{mm},
261 @code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
262 @code{\cm}@keyindex{cm}, for millimeters, points, inches and
263 centimeters, respectively. This converts the number to a real that
264 is the internal representation of dimensions.
271 Begins and ends with the `@code{"}' character. To include a `@code{"}'
272 character in a string write `@code{\"}'. Various other backslash
273 sequences have special interpretations as in the C language. A
274 string that contains no spaces can be written without the quotes.
275 See section XREF-modes [FIXME] for details on unquoted strings; their
276 interpretation varies depending on the situation. Strings can be
277 concatenated with the `@code{+}' operator.
280 The tokenizer accepts the following commands. They can appear
284 \maininput@keyindex{maininput}
287 This command is used in init files to signal that the user file must
288 be read. This command cannot be used in a user file.
291 \include@keyindex{include} @var{file}
294 Include @var{file}. The argument @var{file} may be a quoted string (an
295 unquoted string will not work here!) or a string identifier. The full
296 filename including the @file{.ly} extension must be given,
299 \version@keyindex{version} @var{string} ;
302 Specify the version of LilyPond that a file was written for. The
303 argument is a version string in quotes, for example @code{"1.2.0"}.
304 This is used to detect invalid input, and to aid
305 @code{convert-mudela}, a tool that automatically upgrades input files.
309 @cindex other languages
311 @node Other languages, , , Reference Manual
313 Note name definitions have been provided in various languages.
314 Simply include the language specific init file. For example:
315 `@code{\include "english.ly"}'. The available language files and the
316 names they define are:
319 Note Names sharp flat
320 nederlands.ly c d e f g a bes b -is -es
321 english.ly c d e f g a bf b -s/-sharp -f/-flat
322 deutsch.ly c d e f g a b h -is -es
323 norsk.ly c d e f g a b h -iss/-is -ess/-es
324 svenska.ly c d e f g a b h -iss -ess
325 italiano.ly do re mi fa sol la sib si -d -b
326 catalan.ly do re mi fa sol la sib si -d/-s -b
329 Pitch names can be redefined using the
330 @code{\notenames}@keyindex{notenames} command, see
331 subsection XREF-notenames [FIXME].
335 @cindex lexical modes
339 @node modes, , , Reference Manual
341 To simplify entering notes, lyrics, and chords, @emph{Mudela} has three
342 special input modes on top of the default mode. In each mode, words
343 are identified on the input. If @code{"word"} is encountered, it is
344 treated as a string. If @code{\word} is encountered, it is treated as
345 a keyword or as an identifier. The behavior of the modes differs in
346 two ways: Different modes treat unquoted words differently, and
347 different modes have different rules for deciding what is a word.
353 At the start of parsing, @emph{Mudela} is in Normal mode. In Normal
354 mode, a word is an alphabetic character followed by alphanumeric
355 characters. If @code{word} is encountered on the input it is
361 Note mode is introduced by the keyword
362 @code{\notes}@keyindex{notes}. In Note mode, words can only
363 contain alphabetic characters. If @code{word} is encountered,
364 LilyPond first checks for a notename of @code{word}. If no
365 notename is found, then @code{word} is treated as a string.
367 Since combinations of numbers and dots are used for indicating
368 durations, it is not possible to enter real numbers in this mode.
373 Chord mode is introduced by the keyword
374 @code{\chords}@keyindex{chords}. It is similar to Note mode, but
375 words are also looked up in a chord modifier table (containing
376 @code{maj}, @code{dim}, etc).
378 Since combinations of numbers and dots are used for indicating
379 durations, you can not enter real numbers in this mode. Dashes
380 and carets are used to indicate chord additions and subtractions,
381 so scripts can not be entered in Chord mode.
386 Lyrics mode is introduced by the keyword
387 @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
388 easy to include punctuation and diacritical marks in words. A
389 word in Lyrics mode begins with: an alphabetic character,
390 `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
391 control characters @code{^A} through @code{^F}, @code{^Q} through
392 @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
393 over 127, or a two-character combination of a backslash followed
394 by one of `@code{`}', `@code{'}', `@code{"}', or
395 `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
396 enter lyrics in @TeX{} format or a standard encoding without
397 needing quotes. The precise definition of this mode indeed is
398 ludicrous. This will remain so until the authors of LilyPond
399 acquire a deeper understanding of character encoding, or someone
400 else steps up to fix this.}
402 Subsequent characters of a word can be any character that is not
403 a digit and not white space. One important consequence of this
404 is that a word can end with `@code{@}}', which may be confusing if
405 you thought the closing brace was going to terminate Lyrics
406 mode.@footnote{LilyPond will issue a warning, though.} Any
407 `@code{_}' character which appears in an unquoted word is
408 converted to a space. This provides a mechanism for introducing
409 spaces into words without using quotes. Quoted words can also be
410 used in Lyrics mode to specify words that cannot be written with
411 the above rules. Here are some examples. Not all of these words
412 are printable by @TeX{}.
416 2B_||_!2B % not a word because it starts with a digit
417 ``Hello'' % not a word because it starts with `
418 _ _ _ _ % 4 words, each one a space
421 Since combinations of numbers and dots are used for indicating
422 durations, you can not enter real numbers in this mode.
425 It is possible to create words that break the rules by prefixing them
426 with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a
427 word beginning with `@code{$}' extends until the next white space
428 character. Such words can contain numbers (even in Note mode), or
429 other forbidden characters. The dollar sign can be used to create
430 and access identifiers that could not otherwise be used.@footnote{Use
431 of `@code{$}' hampers readability and portability to future LilyPond
432 versions, thus the use of the dollar sign is discouraged.}
436 @node Types, , , Reference Manual
439 @cindex types and identifiers
441 @emph{Mudela} has a limited set of types:
447 @item music expressions
448 @item durations of notes and rests (specified with
449 @code{\notenames}@keyindex{notenames})
450 @item note name tables
451 @item context definitions, part of output definitions. See
452 section XREF-contextdefs [FIXME] for more information
453 @item output definitions (like @code{\paper}@keyindex{paper} blocks
454 and @code{\midi}@keyindex{midi} blocks)
455 @item score definitions (@code{\score}@keyindex{score} blocks)
458 Type is a syntactical property: @emph{Mudela} has no real type system,
459 so there is no support for generic expressions, functions, or user
460 defined types. For the same reason, it is not possible to mix reals
461 and integers in arithmetic expressions, and ``type
464 (e.g., using a string identifier to
465 initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse
468 Identifiers allow objects to be assigned to names. To assign an
469 identifier, you use `@var{name}=@var{value}' and to refer to an
470 identifier, you preceed its name with a backslash:
471 `@code{\}@var{name}'. Identifier assignments must appear at top level
472 in the @emph{Mudela} file. Semicolons are forbidden after assignments
473 appearing at top level but they are obligatory after assignments
474 appearing in the @code{\paper} block, see Section XREF-paper [FIXME].
476 @var{value} is any of the types listed above.
478 An identifier can be created with any string for its name, but you
479 will only be able to refer to identifiers whose names begin with a
480 letter, being entirely alphanumeric. It is impossible to refer to an
481 identifier whose name is the same as the name of a keyword.
483 The right hand side of an identifier assignment is parsed completely
484 before the assignment is done, so it is allowed to redefine an
485 identifier in terms of its old value, e.g.
491 When an identifier is referenced, the information it points to is
492 copied. Therefore it only makes sense to put identifiers for
493 translators, output definitions, and @code{\score}@keyindex{score}
494 blocks as the first item in a block. For this reason, if you
495 reference a @code{\foo} variable in a @code{\foo} block, it must be the
496 first item in the list following @code{\foo}.@footnote{@code{\paper@{\one
497 \two@}} does not make sense, because the information of @code{\two}
498 would overwrite the information of @code{\one}, thereby making the
499 reference to the first identifier useless.}
503 @node Music expressions, , , Reference Manual
504 @section Music expressions
506 @cindex music expressions
508 Music in @emph{Mudela} is entered as a music expression. Notes, rests,
509 lyric syllables are music expressions (the atomic
511 @cindex atomic music expressions
512 , and you can combine
513 music expressions to form new ones. This example forms a compound
514 expressions out of the quarter @code{c} note and a @code{d}
518 \sequential @{ c4 d4 @}
521 The meaning of this compound expression is to play the `@code{c}'
522 first, and then the `@code{d}' (as opposed to playing them
523 simultaneously, for instance).
525 Atomic music expression are discussed in
526 subsection XREF-atomicmusic [FIXME]. Compound music expressions are
527 discussed in subsection XREF-compoundmusic [FIXME].
531 @node Atomic music expressions, , , Reference Manual
532 @section Atomic music expressions
542 The syntax for pitch specification is
546 \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
549 @var{octave} is specified by an integer, zero for the octave
550 containing middle C. @var{note} is a number from 0 to 7, with 0
551 corresponding to C and 7 corresponding to B. The shift is zero for a
552 natural, negative to add flats, or positive to add sharps.
554 In Note and Chord mode, pitches may be designated by names. See
555 section XREF-notelang [FIXME] for pitch names in different languages.
557 The syntax for duration specification is
560 \duration@keyindex{duration}
561 @{ @var{length} @var{dotcount} @}
564 @var{length} is the negative logarithm (base 2) of the duration:
565 1 is a half note, 2 is a quarter note, 3 is an eighth
566 note, etc. The number of dots after the note is given by
569 In Note, Chord, and Lyrics mode, durations may be designated by
570 numbers and dots. See Section XREF-notelang [FIXME] for details.
573 @node Note specification, , , Reference Manual
575 @cindex note specification
579 @cindex entering notes
581 A note specification has the form
584 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
587 The pitch of the note is specified by the note's name.
590 The default names are the Dutch note names. The notes are specified
591 by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
592 octave below middle C and the letters span the octave above that C.
593 In Dutchcindex(notenames!Dutch), a sharp is formed by adding
594 `@code{-is}' to the end of a pitch name. A flat is formed by adding
595 `@code{-es}'. Double sharps and double flats are obtained by adding
596 `@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are
597 contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will
600 LilyPond has predefined sets of notenames for various languages. See
601 section XREF-notelang [FIXME] for details.
604 The optional octave specification takes the form of a series of
605 single quote (`@code{'}@indexcode{'}') characters or a series of comma
606 (`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
607 octave; each @code{,} lowers the pitch by an octave.
609 @mudela[fragment,verbatim,center]
610 c' d' e' f' g' a' b' c''
613 @mudela[fragment,verbatim,center]
614 cis' dis' eis' fis' gis' ais' bis'
617 @mudela[fragment,verbatim,center]
618 ces' des' es' fes' ges' as' bes'
621 @mudela[fragment,verbatim,center]
622 cisis' eisis' gisis' aisis' beses'
625 @mudela[fragment,verbatim,center]
626 ceses' eses' geses' ases' beses'
629 Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
630 will determine what accidentals to typeset depending on the key and
631 context. A reminder accidental
632 @cindex reminder accidental
634 forced by adding an exclamation mark `@code{!}' after the pitch. A
635 cautionary accidental,
636 @cindex cautionary accidental
638 accidental within parentheses can be obtained by adding the question
639 mark `@code{?}@indexcode{?}' after the pitch.
641 @mudela[fragment,verbatim,center]
642 cis' d' e' cis' c'? d' e' c'!
648 Durations are entered as their reciprocal values. For notes longer
649 than a whole note, use identifiers.
655 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
664 \notes \relative c'' {
666 a1 a2 a4 a8 a16 a32 a64 a64
671 \remove "Clef_engraver";
672 \remove "Staff_symbol_engraver";
683 r1 r2 r4 r8 r16 r32 r64 r64
692 \notes \relative c'' {
694 r1 r2 r4 r8 r16 r32 r64 r64
697 loose_column_distance = 2.5 * \staffspace;
701 \remove "Clef_engraver";
702 \remove "Staff_symbol_engraver";
703 \remove "Bar_engraver";
710 If the duration is omitted then it is set equal to the previous
711 duration. If there is no previous duration, a quarter note is
712 assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
713 to obtain dotted note lengths.
715 @mudela[fragment,verbatim,center]
719 You can alter the length of duration by writing
720 `@code{*}@var{fraction}' after it. This will not affect the
721 appearance of note heads or rests.
724 Rests are entered like notes, with note name `@code{r}@indexcode{r}',
725 or `@code{R}@indexcode{R}'. There is also a note name
726 `@code{s}@indexcode{s}', which produces a space of the specified
727 duration. `@code{R}' is specifically meant for entering parts: the
728 @code{R} rest can expand to fill a score with rests, or it can be
729 printed as a single multimeasure rest.
731 You can control the expansion by setting the property
732 @code{Score.skipBars}. If this is set to true, Lily will not expand
733 empty measures, and the multimeasure rests automatically adds the
737 @cindex lyrics expressions
739 Syllables are entered like notes, with pitches replaced by text. For
740 example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
741 with quarter note duration. Note that the hyphen has no special
742 meaning for lyrics, and does not introduce special symbols. See
743 section XREF-modes [FIXME] for a description of what is interpreted as
746 Spaces can be introduced into a lyric either by using quotes
747 (`@code{"}') or by using an underscore without quotes: `@code{He_could4
748 not4}'. All unquoted underscores are converted to spaces. Printing
749 lyrics is discussed in section XREF-lyricprint [FIXME].
756 \property@keyindex{property}
757 @var{contextname}.@var{propname} = @var{value}
760 Sets the @var{propname} property of the context @var{contextname} to
761 the specified @var{value}. All three arguments are strings.
762 Depending on the context, it may be necessary to quote the strings or
763 to leave space on both sides of the dot.
767 @cindex translator switches
770 \translator@keyindex{translator}
771 @var{contexttype} = @var{name}
774 A music expression indicating that the context which is a direct
775 child of the a context of type @var{contexttype} should be shifted to
776 a context of type @var{contexttype} and the specified name.
778 Usually this is used to switch staffs in Piano music, e.g.
781 \translator Staff = top @var{Music}
785 @cindex output properties
788 These allow you to tweak what is happening in the back-end
789 directly. If you want to control every detail of the output
790 formatting, this is the feature to use. The downside to this is that
791 you need to know exactly how the backend works. Example:
794 @mudela[fragment,verbatim]
796 \context Staff \outputproperty
797 #(make-type-checker 'Note_head)
798 #'extra-offset = #'(5.0 . 7.5)
802 This selects all note heads occurring at current staff level, and sets
803 the extra-offset of those heads to (5,7.5), shifting them up and
806 Use of this feature is entirely on your own risk: if you use this, the
807 result will depend very heavily on the implentation of the backend,
808 which we change unscrupulously.
815 Commands are music expressions that have no duration.
820 @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
823 Change the key signature. @var{type} should be
824 @code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
825 @var{pitch}-major or @var{pitch}-minor, respectively. The second
826 argument is optional; the default is major keys. The @var{\context}
827 argument can also be given as an integer, which tells the number of
828 semitones that should be added to the pitch given in the subsequent
829 @code{\key}@keyindex{key} commands to get the corresponding major key,
830 e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
831 mode names @code{\ionian}@keyindex{ionian},
832 @code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
833 @code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
834 @code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
839 @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
842 Specify an arbitrary key signature. The pitches from @var{pitch} will
843 be printed in the key signature in the order that they appear on the
848 \mark@keyindex{mark} @var{unsigned};
852 Prints a mark over or under (depending on the
853 @code{markDirection}@indexcode{markDirection} property) the staff. You must add
854 @code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for
857 @node barlines, , , Reference Manual
860 \bar@keyindex{bar} @var{bartype};
863 This is a request to print a special bar symbol. It replaces the
864 regular bar symbol with a special
865 symbol. The argument @var{bartype} is a string which specifies the
866 kind of bar to print. Options are @code{":|"}
867 @cindex "|A@@@code{:|}
870 @cindex "|B@@@code{|:}
872 @cindex "|C@@@code{:|:}
875 @cindex "|D@@@code{||}
877 @cindex "|E@@@code{|.}
880 @cindex "|F@@@code{.|}
882 @cindex "|G@@@code{.|.}
884 These produce, respectively, a right repeat, a left repeat, a double
885 repeat, a double bar, a start bar, an end bar, and a thick double
886 bar. If @var{bartype} is set to @code{"empty"} then nothing is
887 printed, but a line break is allowed at that spot.
889 You are encouraged to use @code{\repeat} for repetitions.
890 See section XREF-sec-repeats [FIXME].
897 \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
900 Change the time signature. The default time signature is 4/4.
901 The time signature is used to generate bar lines.
905 \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
908 Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
909 requests output with 76 quarter notes per minute.
913 \partial@keyindex{partial} @var{duration} @code{;}
920 This creates an incomplete measure (anacrusis, upbeat) at the start of
921 the music, e.g., `@code{\partial 8*2;}' creates a starting measure
922 lasting two eighth notes.
926 @code{|}@indexcode{|}
931 @cindex shorten measures
935 `@code{|}' is a bar check. Whenever a bar check is encountered during
936 interpretation, a warning message is issued if it doesn't fall at a
937 measure boundary. This can help you finding errors in the input.
938 The beginning of the measure will be relocated, so this can also
939 be used to shorten measures.
944 \penalty@keyindex{penalty} @var{int} @code{;}
947 Discourage or encourage line breaks. See identifiers
948 @code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
949 section [on identifiers] [FIXME].
953 \clef@keyindex{clef} @var{clefname} @code{;}
956 Music expression that sets the current clef. The argument is a
957 string which specifies the name of the clef. Several clef names are
958 supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef
959 name, then the clef lowered or raised an octave will be generated.
960 Here are the supported clef names with middle C shown in each
969 %\property Voice.textStyle = typewriter
970 \clef subbass; c'4-"\kern -5mm subbass"
971 \clef bass; c'4^"\kern -2mm bass"
972 \clef baritone; c'4_"\kern -5mm baritone"
973 \clef varbaritone; c'4^"\kern -6mm varbaritone"
974 \clef tenor; c'4_"\kern -3mm tenor"
975 \clef "G_8"; c'4^"\kern -2mm G\\_8"
990 \clef alto; c'4_"\kern -2mm alto"
991 \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano"
992 \clef soprano; c'4_"\kern -6mm soprano"
993 \clef treble; c'4^"\kern -4mm treble"
994 \clef french; c'4_"\kern -4mm french"
1003 The three clef symbols can also be obtained using the names `@code{G}',
1004 `@code{C}' or `@code{F}', optionally followed by an integer which
1005 indicates at which note line the clef is located. An as example, the
1006 @code{mezzosoprano} clef can also be given as `@code{C2}'.
1010 \skip@keyindex{skip} @var{duration} @code{;}
1013 Skips the amount of time specified by @var{duration}. If no other
1014 music is played, a gap will be left for the skipped time with no
1015 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
1016 this has the same effect as the space rest `@code{s}'.
1021 @node Manual beams, , , Reference Manual
1023 A beam is specified by surrounding the beamed notes with brackets
1024 `@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
1026 @mudela[fragment,verbatim,center]
1027 [a'8 a'] [a'16 a' a' a']
1030 Some more elaborate constructions:
1032 @mudela[fragment,verbatim,center]
1033 [a'16 <a' c''> c'' <a' c''>]
1034 \times 2/3 { [e'8 f' g'] }
1037 Beaming can be generated automatically; see section XREF-autobeam [FIXME].
1041 To place tremolo marks between notes, use @code{\repeat} with tremolo
1043 @cindex tremolo beams
1044 To create tremolo beams on a single note, simply attach
1045 `@code{:}@var{length}' to the note itself (see also section
1046 XREF-tremolo [FIXME]).
1049 @mudela[fragment,verbatim,center]
1050 \repeat "tremolo" 8 { c16 d16 }
1051 \repeat "tremolo" 4 { c16 d16 }
1054 @mudela[fragment,verbatim,center]
1059 @cindex --@@@code{-}@code{-}
1067 The syntax for an extender mark is `@code{__}'. This syntax can only
1068 be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
1069 a hyphen that will be printed between two lyric syllables) is
1075 A tie connects two adjacent note heads of the same pitch. When used
1076 with chords, it connects all of the note heads whose pitches match.
1077 Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
1078 If you try to tie together chords which have no common pitches, a
1079 warning message will appear and no ties will be created.
1081 @mudela[fragment,verbatim,center]
1082 e' ~ e' <c' e' g'> ~ <c' e' g'>
1087 [TODO: explain Requests]
1090 @cindex articulations
1096 A variety of symbols can appear above and below notes to indicate
1097 different characteristics of the performance. These symbols can be
1098 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1099 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1100 forced to appear above or below the note by writing
1101 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1102 respectively. Here is a chart showing symbols above notes, with the
1103 name of the corresponding symbol appearing underneath.
1109 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1110 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1111 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1112 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1113 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1114 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1115 c''-\thumb c''-\segno c''-\coda
1117 \context Lyrics \lyrics {
1118 accent__ marcato__ staccatissimo__ fermata
1119 stopped__ staccato__ tenuto__ upbow
1120 downbow__ lheel__ rheel__ ltoe
1121 rtoe__ turn__ open__ flageolet
1122 reverseturn__ trill__ prall__ mordent
1123 prallprall__ prallmordent__ uprall__ downprall
1124 thumb__ segno__ coda
1128 linewidth = 5.875\in;
1135 In addition, it is possible to place arbitrary strings of text or
1136 @TeX{} above or below notes by using a string instead of an
1137 identifier: `@code{c^"text"}'. Fingerings
1140 placed by simply using digits. All of these note ornaments appear in
1141 the printed output but have no effect on the MIDI rendering of the
1144 To save typing, fingering instructions (digits 0 to 9 are
1145 supported) and single characters shorthands exist for a few
1152 \property Voice.textStyle = typewriter
1158 c''4-^_"c-\\^{ }" s4
1165 linewidth = 5.875 \in;
1172 Dynamic marks are specified by using an identifier after a note:
1173 `@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
1174 The available dynamic marks are:
1175 @code{\ppp}@keyindex{ppp},
1176 @code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
1177 @code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
1178 @code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
1179 @code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
1180 @code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
1181 @code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
1182 @code{\rfz}@keyindex{rfz}.
1187 \textscript@keyindex{textscript} @var{text} @var{style}
1190 Defines a text to be printed over or under a note. @var{style} is a
1191 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1192 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1194 You can attach a general textscript request using this syntax:
1199 c4-\textscript "6" "finger"
1200 c4-\textscript "foo" "normal"
1205 This is equivalent to `@code{c4-6 c4-"foo"}'.
1212 \script@keyindex{script} @var{alias}
1215 Prints a symbol above or below a note. The argument is a string
1216 which points into the script-alias table defined in @file{script.scm}.
1217 The scheme definitions specify whether the symbol follows notes into
1218 the staff, dependence of symbol placement on staff direction, and a
1219 priority for placing several symbols over one note. Usually the
1220 @code{\script}@keyindex{script} keyword is not used directly. Various
1221 helpful identifier definitions appear in @file{script.ly}.
1226 Slurs connects chords and try to avoid crossing stems. A slur is
1227 started with `@code{(}' and stopped with `@code{)}'. The
1228 starting `@code{(}' appears to the right of the first note in
1229 the slur. The terminal `@code{)}' appears to the left of the
1230 first note in the slur. This makes it possible to put a note in
1231 slurs from both sides:
1233 @mudela[fragment,verbatim,center]
1234 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1240 A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
1241 with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
1242 @code{\decr}@keyindex{decr} and terminated with
1243 @code{\rced}@keyindex{rced}. There are also shorthands for these
1244 marks. A crescendo can be started with @code{\<}@keyindex{<} and a
1245 decrescendo can be started with @code{\>}@keyindex{>}. Either one can
1246 be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
1247 must go before the last note of the dynamic mark whereas @code{\rc}
1248 and @code{\rced} go after the last note. Because these marks are
1249 bound to notes, if you want to get several marks during one note, you
1250 must use spacer notes.
1252 @mudela[fragment,verbatim,center]
1253 c'' \< \! c'' d'' \decr e'' \rced
1254 < f''1 { s4 \< \! s2 \> \! s4 } >
1260 \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
1263 Define a spanning request. The @var{startstop} parameter is either -1
1264 (@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
1265 @var{type} is a string that describes what should be started.
1266 Supported types are @code{crescendo}, @code{decrescendo},
1267 @code{beam}, @code{slur}. This is an internal command. Users should
1268 use the shorthands which are defined in the initialization file
1271 You can attach a (general) span request to a note using
1273 @mudela[fragment,verbatim,center]
1274 c'4-\spanrequest \start "slur"
1275 c'4-\spanrequest \stop "slur"
1278 The slur syntax with parentheses is a shorthand for this.
1282 @cindex tremolo marks
1284 @node stem tremolo, , , Reference Manual
1286 Tremolo marks can be printed on a single note by adding
1287 `@code{:}[@var{length}]' after the note. The length must be at
1288 least 8. A @var{length} value of 8 gives one line across
1289 the note stem. If the length is omitted, then the last value is
1290 used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
1293 @mudela[verbatim,fragment,center]
1299 @node Compound music expressions, , , Reference Manual
1300 @section Compound music expressions
1302 @cindex compound music expressions
1304 Music expressions are compound data structures. You can nest music
1305 expressions any way you like. This simple example shows how three
1306 chords can be expressed in two different ways:
1308 @mudela[fragment,verbatim,center]
1309 \notes \context Staff {
1311 <a c'> <b d' > <c' e'>
1312 < { a b c' } { c' d' e' } >
1316 @cindex context selection
1317 @c @keyindex{context}
1320 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
1323 Interpret @var{musicexpr} within a context of type @var{contexttype}.
1324 If the context does not exist, it will be created. The new context
1325 can optionally be given a name. See
1326 section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more
1327 information on interpretation contexts.
1335 Mode switching keywords form compound music expressions: @code{\notes}
1336 @keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
1337 @var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
1338 These expressions do not add anything to the meaning of their
1339 arguments. They are just a way to indicate that the arguments should
1340 be parsed in indicated mode. See section XREF-modes [FIXME] for more
1341 information on modes.
1343 More information on context selection can be found in
1344 section XREF-contextselection [FIXME].
1348 @cindex sequential music
1354 \sequential@keyindex{sequential}
1355 @code{@{} @var{musicexprlist} @code{@}}
1358 This means that list should be played or written in sequence, i.e.,
1359 the second after the first, the third after the second. The duration
1360 of sequential music is the the sum of the durations of the elements.
1361 There is a shorthand, which leaves out the keyword:
1365 @code{@{} @var{musicexprlist} @code{@}}
1370 @cindex simultaneous music
1377 \simultaneous@keyindex{simultaneous}
1378 @code{@{} @var{musicexprlist} @code{@}}
1381 It constructs a music expression where all of its arguments start at
1382 the same moment. The duration is the maximum of the durations of the
1383 elements. The following shorthand is a common idiom:
1387 @code{<} @var{musicexprlist} @code{>}
1390 If you try to use a chord as the first thing in your score, you might
1391 get multiple staffs instead of a chord.
1393 @mudela[verbatim,center]
1402 This happens because the chord is interpreted by a score context.
1403 Each time a note is encountered a default Voice context (along with a
1404 Staff context) is created. The solution is to explicitly instantiate
1407 @mudela[verbatim,center]
1409 \notes\context Voice <c''4 e''>
1418 @cindex relative pitch specification
1420 @node relative, , , Reference Manual
1422 It is easy to get confused by octave changing marks and accidentally
1423 putting a pitch in the wrong octave. A much better way of entering a
1424 note's octave is `the relative octave' mode.
1428 \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
1431 The octave of notes that appear in @var{musicexpr} are calculated as
1432 follows: If no octave changing marks are used, the basic interval
1433 between this and the last note is always taken to be a fourth or
1434 less.@footnote{The interval is determined without regarding
1435 accidentals. A @code{fisis} following a @code{ceses} will be put above
1436 the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
1437 can then be added to raise or lower the pitch by an extra octave.
1438 Upon entering relative mode, an absolute starting pitch must be
1439 specified that will act as the predecessor of the first note of
1442 Entering scales is straightforward in relative mode.
1444 @mudela[fragment,verbatim,center]
1450 And octave changing marks are used for intervals greater than a fourth.
1452 @mudela[fragment,verbatim,center]
1454 c g c f, c' a, e'' }
1457 If the preceding item is a chord, the first note of the chord is used
1458 to determine the first note of the next chord. But other notes
1459 within the second chord are determined by looking at the immediately
1462 @mudela[fragment,verbatim,center]
1470 The pitch after the @code{\relative} contains a notename. To parse
1471 the pitch as a notename, you have to be in note mode, so there must
1472 be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
1475 The relative conversion will not affect @code{\transpose} or
1476 @code{\relative} sections in its argument. If you want to use
1477 relative within transposed music, you must place an additional
1478 @code{\relative} inside the @code{\transpose}.
1480 It is strongly recommended to use relative pitch mode: less work,
1481 less error-prone, and more readable.
1485 Chord names are a way to generate simultaneous music expressions that
1486 correspond with traditional chord names. It can only be used in
1487 Chord mode (see section XREF-modes [FIXME]).
1491 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1494 @var{tonic} should be the tonic note of the chord, and @var{duration}
1495 is the chord duration in the usual notation. There are two kinds of
1496 modifiers. One type is @emph{chord additions}, which are obtained by
1497 listing intervals separated by dots. An interval is written by its
1498 number with an optional `@code{+}' or `@code{-}' to indicate raising or
1499 lowering by half a step. Chord additions has two effects: It adds
1500 the specified interval and all lower odd numbered intervals to the
1501 chord, and it may lower or raise the specified interval. Intervals
1502 must be separated by a dot (`@code{.}').
1506 @mudela[fragment,verbatim]
1510 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1517 The second type of modifier that may appear after the `@code{:}' is a
1518 named modifier. Named modifiers are listed in the file
1519 @file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
1520 `@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
1521 raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
1522 `@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
1523 which replaces the 5th with a 4th.
1527 @mudela[fragment,verbatim]
1530 c1:m c:min7 c:maj c:aug c:dim c:sus
1538 Chord subtractions are used to eliminate notes from a chord. The
1539 notes to be subtracted are listed after a `@code{^}' character,
1542 @mudela[fragment,verbatim,center]
1550 Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
1551 the name of a single note to a chord. This has the effect of
1552 lowering the specified note by an octave so it becomes the lowest
1553 note in the chord. If the specified note is not in the chord, a
1554 warning will be printed.
1556 @mudela[fragment,verbatim,center]
1565 Bass notes can be added by `@code{/+}@indexcode{/+}' and
1566 the name of a single note to a chord. This has the effect of
1567 adding the specified note to the chord, lowered by an octave,
1568 so it becomes the lowest note in the chord.
1570 @mudela[fragment,verbatim,center]
1579 Throughout these examples, chords have been shifted around the staff
1580 using @code{\transpose}.
1582 You should not combine @code{\relative} with named chords.
1588 Tuplets are made out of a music expression by multiplying their
1589 duration with a fraction.
1593 \times@keyindex{times} @var{fraction} @var{musicexpr}
1596 The duration of @var{musicexpr} will be multiplied by the fraction.
1597 In print, the fraction's denominator will be printed over the notes,
1598 optionally with a bracket. The most common tuplet is the triplet in
1599 which 3 notes have the length of 2, so the notes are 2/3 of
1600 their written length:
1602 @mudela[fragment,verbatim,center]
1603 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1612 \grace@keyindex{grace} @var{musicexpr}
1615 A grace note expression has duration 0; the next real note is
1616 assumed to be the main note.
1618 You cannot have the grace note after the main note, in terms of
1619 duration, and main notes, but you can typeset the grace notes to the
1620 right of the main note using the property
1621 @code{graceAlignPosition}@indexcode{graceAlignPosition}.
1623 When grace music is interpreted, a score-within-a-score is set up:
1624 @var{musicexpr} has its own time bookkeeping, and you could (for
1625 example) have a separate time signature within grace notes. While in
1626 this score-within-a-score, you can create notes, beams, slurs, etc.
1627 Unbeamed eighth notes and shorter by default have a slash through the
1628 stem. This behavior can be controlled with the
1629 @code{flagStyle}@indexcode{flagStyle} property.
1633 @mudela[fragment,verbatim]
1635 \grace c8 c4 \grace { [c16 c16] } c4
1636 \grace { \property Grace.flagStyle = "" c16 } c4
1642 At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
1646 @code{\grace @{ \grace c32 c16 @} c4}
1649 may result in run-time errors of LilyPond. Since the meaning of such
1650 a construct is unclear, we don't consider this a loss. Similarly,
1651 juxtaposing two @code{\grace} sections is syntactically valid, but
1652 makes no sense and may cause runtime errors.
1654 Ending a staff or score with grace notes may also generate a run-time
1655 error, since there will be no main note to attach the grace notes to.
1661 @node Repeats, , , Reference Manual
1663 In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
1664 keyword. Since repeats look and sound differently when played or
1665 printed, there are a few different variants of repeats.
1669 Repeated music is fully written (played) out. Useful for MIDI
1673 This is the normal notation: Repeats are not written out, but
1674 alternative endings (voltas) are printed, left to right.
1677 Alternative endings are written stacked, which is useful for
1681 The syntax for repeats is
1685 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1688 If you have alternative endings, you may add
1692 \alternative@keyindex{alternative}
1693 @code{@{} @var{alternative1}
1695 @var{alternative3} @dots{} @code{@}}
1698 where each @var{alternative} is a Music expression.
1700 Normal notation repeats are used like this:
1704 @mudela[fragment,verbatim]
1706 \repeat volta 2 { c'4 d' e' f' }
1707 \repeat volta 2 { f' e' d' c' }
1712 With alternative endings:
1716 @mudela[fragment,verbatim]
1718 \repeat volta 2 {c'4 d' e' f'}
1719 \alternative { {d'2 d'} {f' f} }
1724 Folded repeats look like this:@footnote{Folded repeats offer little
1725 more over simultaneous music. However, it is to be expected that
1726 more functionality -- especially for the MIDI backend -- will be
1731 @mudela[fragment,verbatim]
1733 \repeat fold 2 {c'4 d' e' f'}
1734 \alternative { {d'2 d'} {f' f} }
1741 @mudela[fragment,verbatim]
1745 \repeat volta 2 { e | c2 d2 | e2 f2 | }
1746 \alternative { { g4 g g } { a | a a a a | b1 } }
1753 If you don't give enough alternatives for all of the repeats, then
1754 the first alternative is assumed to be repeated often enough to equal
1755 the specified number of repeats.
1759 @mudela[fragment,verbatim]
1762 \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
1763 \alternative { { g4 g g }
1764 {\partial 1; e4 e e }
1765 {\partial 1; a a a a | b1 } }
1772 It is possible to nest @code{\repeat}. This is not entirely
1773 supported: the notes will come be in the right places, but the repeat
1778 @cindex transposition of pitches
1780 @node transpose, , , Reference Manual
1782 A music expression can be transposed with
1783 @code{\transpose}@keyindex{transpose}. The syntax is
1787 \transpose @var{pitch} @var{musicexpr}
1790 This means that middle C in @var{musicexpr} is transposed to
1793 @code{\transpose} distinguishes between enharmonic pitches: both
1794 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
1795 a tone. The first version will print sharps and the second version
1800 @mudela[fragment,verbatim]
1803 { \key e \major; c d e f }
1805 \transpose des'' { \key e \major; c d e f }
1806 \transpose cis'' { \key e \major; c d e f }
1812 If you want to use both @code{\transpose} and @code{\relative}, then
1813 you must use @code{\transpose} first. @code{\relative} will have no
1814 effect music that appears inside a @code{\transpose}.
1818 @cindex automatic lyric durations
1820 If you have lyrics that are set to a melody, you can import the
1821 rhythm of that melody into the lyrics using @code{\addlyrics}.
1822 @keyindex{addlyrics} The syntax for this is
1826 \addlyrics @var{musicexpr1 musicexpr2}
1829 This means that both @var{musicexpr1} and @var{musicexpr2} are
1830 interpreted, but that every non-command atomic music expression
1831 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1832 of @var{musicexpr1}.
1834 If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
1835 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1840 @mudela[verbatim,fragment]
1843 \property Voice.automaticMelismata = ##t
1844 c8 () cis d8. e16 f2
1846 \context Lyrics \lyrics {
1852 You should use a single rhythm melody, and single rhythm lyrics (a
1853 constant duration is the obvious choice). If you do not, you will get
1854 undesired effects when using multiple stanzas:
1858 @mudela[verbatim,fragment]
1861 c8 () cis d8. e16 f2
1863 \context Lyrics \lyrics
1870 It is valid (but probably not very useful) to use notes instead of
1871 lyrics for @var{musicexpr2}.
1876 @node Ambiguities, , , Reference Manual
1877 @section Ambiguities
1881 The grammar contains a number of ambiguities.@footnote{The authors
1882 hope to resolve them at a later time.}
1885 @item The assignment
1891 can be interpreted as making a string identifier @code{\foo}
1892 containing @code{"bar"}, or a music identifier @code{\foo}
1893 containing the syllable `bar'.
1895 @item The assignment
1901 can be interpreted as making an integer identifier
1902 containing -6, or a Request identifier containing the
1903 fingering `6' (with neutral direction).
1905 @item If you do a nested repeat like
1917 then it is ambiguous to which @code{\repeat} the
1918 @code{\alternative} belongs. This is the classic if-then-else
1919 dilemma. It may be solved by using braces.
1921 @item (an as yet unidentified ambiguity :-)
1926 @node Notation conversion specifics, , , Reference Manual
1927 @section Notation conversion specifics
1931 @cindex automatic beam generation
1933 @node autobeam, , , Reference Manual
1935 By default, LilyPond will generate beams automatically. This feature
1936 can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
1937 property to 1. It can be overridden for specific cases by
1938 specifying explicit beams as described in
1939 section XREF-manualbeam [FIXME].
1941 A large number of Voice properties are used to decide how to generate
1942 beams. Their default values appear in @file{auto-beam-settings.ly}.
1943 In general, beams can begin anywhere, but their ending location is
1944 significant. Beams can end on a beat, or at durations specified by
1945 the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
1946 quarter note, for example, you could set
1947 @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
1948 at every three eighth notes you would set it to `@code{"3/8"}'. The
1949 same syntax can be used to specify beam starting points using
1950 @code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
1952 To allow different settings for different time signatures, these
1953 property names can start with `@code{time}@var{N}@code{_}@var{M}' to
1954 restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
1955 to specify beams ending only for 6/8 time you would use the
1956 property @code{Voice.time6_8beamAutoEnd}. To allow different endings
1957 for notes of different durations, the duration can be tacked onto the
1958 end of the property. To specify beam endings for beams that contain
1959 32nd notes, you would use @code{Voice.beamAutoEnd_32}.
1967 @cindex printing!chord names
1969 For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
1970 and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
1971 either using the notation described above, or directly using
1976 @mudela[fragment,verbatim]
1978 \context ChordNames {
1979 \chords{a b c} \notes{<d f g> <e g b>}
1981 \context Staff \notes {
1989 LilyPond examines chords specified as lists of notes to determine a
1990 name to give the chord. By default, LilyPond will not try to
1991 identify chord inversions:
1993 @mudela[fragment,verbatim,center]
1995 \context ChordNameVoice \notes {
1998 \context Thread \notes {
2004 If you want inversions to be recognized, you must set the property
2005 @code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
2007 @mudela[fragment,verbatim,center]
2009 \property Score.chordInversion = ##t
2010 \context ChordNameVoice \notes {
2013 \context Thread \notes {
2023 @cindex printing!lyrics
2025 @node lyricprint, , , Reference Manual
2027 Lyric syllables must be interpreted within a @code{Lyrics} context
2029 @cindex context!Lyrics
2032 Here is a full example:
2039 \notes \transpose c'' {
2041 e f g2 | e4 f g2 \bar "|.";
2043 \context Lyrics \lyrics {
2044 Va-4 der Ja- cob Va- der Ja- cob
2045 Slaapt gij nog?2 Slaapt4 gij nog?2
2053 You may want a continuous line after the syllables to show melismata.
2054 To achieve this effect, add a `@code{__}' lyric as a separate word
2055 after the lyric to be extended. This will create an extender, a line
2056 that extends over the entire duration of the lyric. This line will
2057 run all the way to the start of the next lyric, so you may want to
2058 shorten it by using a blank lyric (using `@code{_}').
2065 \notes \relative c'' {
2066 a4 () b () c () d | c () d () b () a | c () d () b () a
2068 \context Lyrics \lyrics {
2069 foo1 __ | bar2. __ _4 | baz1 __
2078 If you want to have hyphens centered between syllables (rather than
2079 attached to the end of the first syllable) you can use the special
2080 `@code{-}@code{-}' lyric as a separate word between syllables. This
2081 will result in a hyphen which length varies depending on the space
2082 between syllables, and which will be centered between the syllables.
2090 \notes \transpose c'' {
2092 e f g2 | e4 f g2 \bar "|.";
2094 \context Lyrics \lyrics {
2095 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
2096 Slaapt gij nog?2 | Slaapt4 gij nog?2
2106 @node Notation Contexts, , , Reference Manual
2107 @section Notation Contexts
2109 @cindex notation contexts
2111 Notation contexts are objects that only exist during a run of
2112 LilyPond. During the interpretation phase of LilyPond, the Music
2113 expression contained in a @code{\score} block is interpreted in time
2114 order. This is the order in which humans read, play, and write
2117 A context is an object that holds the reading state of the
2118 expression; it contains information like
2121 @item What notes are playing at this point?
2122 @item What symbols will be printed at this point?
2123 @item In what style will they printed?
2124 @item What is the current key signature, time signature, point within
2128 Contexts are grouped hierarchically: A @code{Voice} context is
2129 contained in a @code{Staff} context (because a staff can contain
2130 multiple voices at any point), a @code{Staff} context is contained in
2131 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
2132 these can all contain multiple staffs).
2134 Contexts associated with sheet music output are called @emph{notation
2135 contexts}, those for sound output are called playing contexts.
2137 Contexts are created either manually or automatically. Initially,
2138 the top level music expression is interpreted by the top level
2139 context (the @code{Score} context). When a atomic music expression
2140 (i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
2141 set of contexts is created that can process these atomic expressions,
2147 \score @{ \notes < c4 > @}
2152 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
2153 context. When the note `@code{c4}' itself is interpreted, a set of
2154 contexts is needed that will accept notes. The default for this is a
2155 @code{Voice} context, contained in a @code{Staff} context. Creation of
2156 these contexts results in the staff being printed.
2161 You can also create contexts manually, and you probably have to do so
2162 if you want to typeset complicated multiple part material. If a
2163 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
2164 during the interpretation phase, the @var{musicexpr} argument will be
2165 interpreted with a context of type @var{name}. If you specify a name,
2166 the specific context with that name is searched.
2168 If a context of the specified type and name can not be found, a new
2169 one is created. For example,
2175 \notes \relative c'' {
2176 c4 <d4 \context Staff = "another" e4> f
2183 In this example, the @code{c} and @code{d} are printed on the
2184 default staff. For the @code{e}, a context Staff called
2185 `@code{another}' is specified; since that does not exist, a new
2186 context is created. Within @code{another}, a (default) Voice context
2187 is created for the @code{e4}. When all music referring to a
2188 context is finished, the context is ended as well. So after the
2189 third quarter, @code{another} is removed.
2191 Almost all music expressions inherit their interpretation context
2192 from their parent. In other words, suppose that the syntax for a
2197 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
2200 When the interpretation of this music expression starts, the context
2201 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
2204 Lastly, you may wonder, why this:
2210 \notes \relative c'' @{
2218 doesn't result in this:
2223 \notes \relative c'' {
2230 For the @code{c4}, a default @code{Staff} (with a contained
2231 @code{Voice}) context is created. After the @code{c4} ends, no
2232 music refers to this default staff, so it would be ended, with the
2233 result shown. To prevent this inconvenient behavior, the context to
2234 which the sequential music refers is adjusted during the
2235 interpretation. So after the @code{c4} ends, the context of the
2236 sequential music is also the default @code{Voice} context.
2237 The @code{d4} gets interpreted in the same context
2242 These are the contexts supplied with the package. They are defined
2243 in the initialization file @file{ly/engraver.ly}.
2250 Properties that are set in one context are inherited by all of the
2251 contained contexts. This means that a property valid for the
2252 @code{Voice} context can be set in the @code{Score} context (for
2253 example) and thus take effect in all @code{Voice} contexts.
2255 Properties can be preset within the @code{\translator} block
2256 corresponding to the appropriate context. In this case, the syntax
2261 @var{propname} @code{=} @var{value}
2264 This assignment happens before interpretation starts, so a
2265 @code{\property} expression will override any predefined settings.
2267 The @code{\property} expression will create any property you specify.
2268 There is no guarantee that a property will be used. So if you spell
2269 a property name wrong, there will be no error message.
2271 The property settings are used during the interpretation phase. They
2272 are read by the LilyPond modules where interpretation contexts are
2273 built of. These modules are called @emph{translators}. Translators for
2274 notation are called @emph{engravers}, and translators for sound are
2275 called @emph{performers}.
2277 The precise result of a property is determined by the implementation
2278 of the translator that reads them. Therefore, the result of a
2279 property can vary, since it is implementation and configuration
2282 In order to fully find out what properties are used, you must
2283 currently search the source code for calls to @code{get_property}.
2284 The rest of the section is devoted to an (incomplete) overview of
2285 available properties.
2287 @mbinclude properties.itely
2289 @node Notation output definitions, , , Reference Manual
2290 @section Notation output definitions
2294 @cindex notation output
2296 @cindex output definition
2298 @node paper, , , Reference Manual
2300 The most important output definition is the @code{\paper} block, for
2301 music notation. The syntax is
2305 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2308 where each of the items is one of
2311 @item An assignment. The assignment must be terminated by a
2312 semicolon. See section XREF-papervars [FIXME] for information on
2315 @item A context definition. See section XREF-contextdefs [FIXME] for
2316 more information on context definitions.
2321 A margin shape declaration. The syntax is
2325 \shape @var{indent1}@code{,} @var{width1}@code{,}
2326 @var{indent2}@code{,} @var{width2} @dots{} @code{;}
2331 Each pair of @var{indent} and @var{width} values is a dimension
2332 specifying how far to indent and how wide to make the line.
2333 The indentation and width of successive lines are specified by
2334 the successive pairs of dimensions. The last pair of
2335 dimensions will define the characeristics of all lines beyond
2336 those explicitly specified.
2338 @item \stylesheet declaration. Its syntax is
2341 \stylesheet @var{scm}
2345 See font.scm for details of @var{scm}
2350 @cindex changing font size and paper size
2352 The Feta font provides musical symbols at six different sizes. These
2353 fonts are 11 point, 13 point, 16 point, 20 point,
2354 23 point, and 26 point. The point size of a font is the
2355 height of the five lines in a staff when displayed in the font.
2357 Definitions for these sizes are the files @file{paperSZ.ly}, where
2358 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
2359 any of these files, the identifiers @code{paper_eleven},
2360 @code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
2361 @code{paper_twentythree}, and @code{paper_twentysix} are defined
2362 respectively. The default @code{\paper} block is also set.
2364 To change the paper size, you must first set the
2365 @code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
2366 @code{a4}, @code{letter}, or @code{legal}. After this specification,
2367 you must set the font as described above. If you want the default
2368 font, then use the 20 point font. The new paper size will not
2369 take effect if the font is not loaded and selected afterwards. Paper
2370 size selection works by loading a file named after the paper size you
2375 @cindex paper variables
2377 @node Paper variables, , , Reference Manual
2379 There is a large number of paper variables that are used to control
2380 details of the layout. These variables control the defaults for the
2381 entire score. Usually, they do not have to be changed; they are by
2382 default set to values that depend on the font size in use. The
2383 values are used by the graphic objects while formatting the score;
2384 they are therefore implementation dependent. Most variables are
2385 accompanied by documentation in the initalization file
2386 @file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
2389 Nevertheless, here are some variables you may want to use or change:
2392 @item @code{indent}@indexcode{indent}
2393 The indentation of the first line of music.
2395 @item @code{staffspace}@indexcode{staffspace}
2396 The distance between two staff lines, calculated from the center
2397 of the lines. You should use either this or @code{rulethickness}
2398 as a unit for distances you modify.
2400 @item @code{linewidth}@indexcode{linewidth}
2401 Sets the width of the lines. If set to -1.0, a single
2402 unjustified line is produced.
2404 @item @code{textheight}@indexcode{textheight}
2405 Sets the total height of the music on each page. Only used by
2408 @item @code{interscoreline}@indexcode{interscoreline}
2409 Sets the spacing between the score lines. Defaults to 16 pt.
2411 @item @code{interscorelinefill}@indexcode{interscorelinefill}
2412 If set to a positive number, the distance between the score
2413 lines will stretch in order to fill the full page. In that
2414 case @code{interscoreline} specifies the minimum spacing.
2417 @item @code{stafflinethickness}@indexcode{stafflinethickness}
2418 Determines the thickness of staff and bar lines.
2422 @node contextdefs, , , Reference Manual
2424 @cindex context definition
2426 A notation contexts is defined by the following information
2431 @item The LilyPond modules that do the actual conversion of music to
2432 notation. Each module is a so-called
2437 @item How these modules should cooperate, i.e. which ``cooperation
2438 module'' should be used. This cooperation module is a special
2441 @item What other contexts the context can contain,
2443 @item What properties are defined.
2446 A context definition has this syntax:
2450 \translator @code{@{}
2451 @var{translatorinit} @var{translatormodifierlist}
2455 @var{translatorinit} can be an identifier or of the form
2459 \type @var{typename} @code{;}
2462 @var{typename} is one of
2465 @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
2466 The standard cooperation engraver.
2468 @item @code{Score_engraver}@indexcode{Score_engraver}
2469 This is cooperation module that should be in the top level context.
2471 @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
2472 This is a special cooperation module (resembling
2473 @code{Score_engraver}) that is used to created an embedded
2477 @var{translatormodifierlist} is a list of items where each item is
2481 @item @code{\consists} @var{engravername} @code{;}
2482 Add @var{engravername} to the list of modules in this context.
2483 Section XREF-engravers [FIXME] contains an overview of the engravers
2484 available. The order of engravers added with @code{\consists} is
2487 @item @code{\consistsend} @var{engravername} @code{;}
2488 Analogous to @code{\consists}, but makes sure that
2489 @var{engravername} is always added to the end of the list of
2492 Some engraver types need to be at the end of the list; this
2493 insures they are put there, and stay there, if a user adds or
2494 removes engravers. This command is usually not needed for
2497 @item @code{\accepts} @var{contextname} @code{;}
2498 Add @var{contextname} to the list of context this context can
2499 contain. The first listed context the context to create by
2502 @item @code{\remove} @var{engravername} @code{;}
2503 Remove a previously added (with @code{\consists}) engraver.
2505 @item @code{\name} @var{contextname} @code{;}
2506 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2507 the name is not specified, the translator won't do anything.
2509 @item @var{propname} @code{=} @var{value} @code{;}
2510 A property assignment. It is allowed to use reals for
2514 In the @code{\paper} block, it is also possible to define translator
2515 identifiers. Like other block identifiers, the identifier can only
2516 be used as the very first item of a translator. In order to define
2517 such an identifier outside of @code{\score}, you must do
2523 foo = \translator @{ @dots{} @}
2530 \translator @{ \foo @dots{} @}
2538 @cindex paper types, engravers, and pre-defined translators
2540 Some pre-defined identifiers can simplify modification of
2541 translators. The pre-defined identifiers are:
2544 @item @code{StaffContext}@indexcode{StaffContext}
2545 Default Staff context.
2547 @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
2548 Default RhythmicStaff context.
2550 @item @code{VoiceContext}@indexcode{VoiceContext}
2551 Default Voice context.
2553 @item @code{ScoreContext}@indexcode{ScoreContext}
2554 Default Score context.
2556 @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
2557 Score context with numbering at the Score level.
2559 @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
2560 Staff context with numbering at the Staff level.
2562 @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
2563 Staff context that does not print if it only contains rests.
2564 Useful for orchestral scores.@footnote{Harakiri, also called
2565 Seppuku, is the ritual suicide of the Samourai.}
2567 @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
2569 @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
2572 Using these pre-defined values, you can remove or add items to the
2581 \remove Some_engraver;
2582 \consists Different_engraver;
2590 @node Sound output, , , Reference Manual
2591 @section Sound output
2595 The MIDI block is analogous to the paper block, but it is simpler.
2596 The @code{\midi} block can contain:
2600 @item a @code{\tempo} definition
2601 @item context definitions
2604 Assignments in the @code{\midi} block are not allowed.
2608 @cindex context definition
2610 Context definitions follow precisely the same syntax as within the
2611 \paper block. Translation modules for sound are called performers.
2612 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2616 @cindex MIDI instrument names
2618 @node midilist, , , Reference Manual
2620 The MIDI instrument name is set by the
2621 @code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
2622 if that property is not set, the
2623 @code{Staff.instrument}@indexcode{Staff.instrument} property. The
2624 instrument name should be chosen from the following list. If the
2625 selected string does not exactly match, then LilyPond uses the default
2631 "acoustic grand" "contrabass" "lead 7 (fifths)"
2632 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2633 "electric grand" "pizzicato strings" "pad 1 (new age)"
2634 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2635 "electric piano 1" "timpani" "pad 3 (polysynth)"
2636 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2637 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2638 "clav" "synthstrings 1" "pad 6 (metallic)"
2639 "celesta" "synthstrings 2" "pad 7 (halo)"
2640 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2641 "music box" "voice oohs" "fx 1 (rain)"
2642 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2643 "marimba" "orchestra hit" "fx 3 (crystal)"
2644 "xylophone" "trumpet" "fx 4 (atmosphere)"
2645 "tubular bells" "trombone" "fx 5 (brightness)"
2646 "dulcimer" "tuba" "fx 6 (goblins)"
2647 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2648 "percussive organ" "french horn" "fx 8 (sci-fi)"
2649 "rock organ" "brass section" "sitar"
2650 "church organ" "synthbrass 1" "banjo"
2651 "reed organ" "synthbrass 2" "shamisen"
2652 "accordion" "soprano sax" "koto"
2653 "harmonica" "alto sax" "kalimba"
2654 "concertina" "tenor sax" "bagpipe"
2655 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2656 "acoustic guitar (steel)" "oboe" "shanai"
2657 "electric guitar (jazz)" "english horn" "tinkle bell"
2658 "electric guitar (clean)" "bassoon" "agogo"
2659 "electric guitar (muted)" "clarinet" "steel drums"
2660 "overdriven guitar" "piccolo" "woodblock"
2661 "distorted guitar" "flute" "taiko drum"
2662 "guitar harmonics" "recorder" "melodic tom"
2663 "acoustic bass" "pan flute" "synth drum"
2664 "electric bass (finger)" "blown bottle" "reverse cymbal"
2665 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2666 "fretless bass" "whistle" "breath noise"
2667 "slap bass 1" "ocarina" "seashore"
2668 "slap bass 2" "lead 1 (square)" "bird tweet"
2669 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2670 "synth bass 2" "lead 3 (calliope)" "helicopter"
2671 "violin" "lead 4 (chiff)" "applause"
2672 "viola" "lead 5 (charang)" "gunshot"
2673 "cello" "lead 6 (voice)"
2679 @cindex MIDI types and performers
2681 The types available for MIDI translators are:
2684 @item @code{Performer_group_performer}@indexcode{Performer_group_performer}
2685 @item @code{Score_performer}@indexcode{Score_performer}
2686 @item @code{Staff_performer}@indexcode{Staff_performer}
2689 The performers for MIDI translators are:
2692 @item @code{Key_performer}@indexcode{Key_performer}
2693 @item @code{Time_signature_performer}@indexcode{Time_signature_performer}
2694 @item @code{Note_performer}@indexcode{Note_performer}
2695 @item @code{Lyric_performer}@indexcode{Lyric_performer}
2696 @item @code{Swallow_performer}@indexcode{Swallow_performer}
2701 @node Pre-defined Identifiers, , , Reference Manual
2703 @section Pre-defined Identifiers
2705 @cindex pre-defined identifiers
2708 Various identifiers are defined in the initialization files to
2709 provide shorthands for some settings. Most of them are in
2710 @file{ly/declarations.ly}.
2713 @item @code{\break}@keyindex{break}
2714 Force a line break in music by using a large argument for the
2715 keyword @code{\penalty}.
2717 @item @code{\center}@keyindex{center}
2718 Used for setting direction properties. Equals 0.
2720 @item @code{\down}@keyindex{down}
2721 Used for setting direction setting properties. Is equal
2724 @item @code{\free}@keyindex{free}
2725 Used for setting direction setting properties. Is equal
2728 @item @code{\left}@keyindex{left}
2729 Used for setting text alignment property. Is equal to -1.
2731 @item @code{\nobreak}@keyindex{nobreak}
2732 Prevent a line break in music by using a large negative argument
2733 for the keyword @code{\penalty}.
2735 @item @code{\none}@keyindex{none}
2736 Used for setting @code{Score.beamslopedamping} and
2737 @code{Score.beamquantisation} properties. Is equal to 0.
2739 @item @code{\normal}@keyindex{normal}
2740 Used for setting @code{Score.beamslopedamping} and
2741 @code{Score.beamquantisation} properties. Is equal to 1.
2743 @item @code{\normalkey}@keyindex{normalkey}
2744 Select normal key signatures where each octave has the same key
2745 signature. This sets the @code{Staff.keyoctaviation} property.
2747 @item @code{\right}@keyindex{right}
2748 Used for setting text alignment property. Is set to 1.
2750 @item @code{\shiftoff}@keyindex{shiftOff}
2751 Disable horizontal shifting of note heads that collide. Sets the
2752 @code{Voice.horizontalNoteShift} property.
2754 @item @code{\shiftOn}@keyindex{shiftOn}
2755 Enable note heads that collide with other note heads to be
2756 shifted horiztonally. Sets the @code{Voice.horizontalNoteShift}
2759 @item @code{\slurBoth}@keyindex{slurBoth}
2760 Allow slurs to be above or below notes. This sets the
2761 @code{Voice.slurVerticalDirection} property.
2763 @item @code{\slurDown}@keyindex{slurDown}
2764 Force slurs to be below notes. This sets the
2765 @code{Voice.slurVerticalDirection} property.
2767 @item @code{\slurUp}@keyindex{slurUp}
2768 Force slurs to be above notes. This sets the
2769 @code{Voice.slurVerticalDirection} property.
2771 @item @code{\specialkey}@keyindex{specialkey}
2772 Allow key signatures do differ in different octaves. This sets
2773 the @code{Staff.keyoctaviation} property.
2775 @item @code{\stemBoth}@keyindex{stemBoth}
2776 Allow stems, beams, and slurs to point either upwards or
2777 downwards, decided automatically by LilyPond. This sets the
2778 @code{Voice.verticalDirection} property.
2780 @item @code{\stemdown}@keyindex{stemdown}
2781 Force stems, beams, and slurs to point down. This sets the
2782 @code{Voice.verticalDirection} property.
2784 @item @code{\stemUp}@keyindex{stemUp}
2785 Force stems, beams and slurs to point up. This sets the
2786 @code{Voice.verticalDirection} property.
2788 @item @code{\traditional}@keyindex{traditional}
2789 Used for setting the @code{Score.beamquantisation} property. Is
2792 @item @code{\up}@keyindex{up}
2793 Used for setting various direction properties. Is equal