1 \input texinfo @c -*-texinfo-*-
2 @setfilename mudela.info
3 @settitle Reference Manual
8 * Tutorial:: a tutorial introduction to lilypond
9 * Reference Manual:: Reference Manual
10 * Glossary:: A dictionary of musical terms.
13 @macro keyindex {word}
18 @macro indexcode {word}
23 @node Tutorial, , , Top
25 * Introduction:: Introduction
26 * The first tune:: The first tune
27 * Lyrics and chords:: Lyrics and chords
28 * Piano music:: Piano music
29 * end of tutorial:: The end
33 @node Introduction, , , Tutorial
37 LilyPond prints music from a specification that you, the user, supply.
38 You have to give that specification using a @emph{language}. This
39 document is a gentle introduction to that language, which is called
40 Mudela, an acronym of Music Definition Language.
42 This tutorial will demonstrate how to use Mudela by presenting
43 examples of input along with resulting output. We will use English
44 terms for notation. In case you are not familiar with those, you may
45 consult the glossary that is distributed with LilyPond.
47 The examples discussed are included in the distribution, in the
48 subdirectory @file{input/tutorial/}. It is recommended that you
49 experiment with writing Mudela input yourself, to get a feel for
52 @node The first tune, , , Tutorial
53 @section The first tune
56 To demonstrate what LilyPond input looks like, we start off with a
57 full fledged, yet simple example. It is a convoluted version
58 of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
61 % lines preceded by a percent are comments.
65 \relative c'' \sequential{
70 d4 g,8 a b c d4 g, g |
71 e'4 c8 d e fis g4 g, g |
72 c4 d8()c b a( )b4 c8 b a g |
73 a4 [b8 a] [g fis] g2. |
78 g4 e8 fis g d cis4 b8 cis a4 |
79 a8-. b-. cis-. d-. e-. fis-.
86 % standard settings are too wide for a book
92 Enter it (or copy it, the filename is @file{menuet.ly}), compile it
93 with LilyPond and view the output. Details of this procedure may vary
94 from system to system. To create the output, one would issue the
95 command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
96 the job of running LilyPond and TeX, handling of titles and
97 adjusting of page margins.
99 If all goes well, the file @file{menuet.dvi} will be created.
100 To view this output, issue the command `@code{xdvi menuet}'.
102 Now that we are familiar with the procedure of producing output, we
103 will analyse the input, line by line.
105 Let's try to redo this
108 % lines preceded by a percent are comments.
111 The percent sign, `@code{%}', introduces a line comment. If you want to
112 make larger comments, you can use block comments. These are delimited
113 by `@code{%@{}' and `@code{%@}}'
115 @multitable @columnfractions .60 .39
118 @c @example urg: no tt font
119 @c @exdent % lines preceded by a percent are comments.
120 @exdent @code{% lines preceded by a percent are comments.}
123 The percent sign, `@code{%}', introduces a line comment. If you
124 want to make larger comments, you can use block comments. These
125 are delimited by `@code{%@{}' and `@code{%@}}'
132 By default, LilyPond will use definitions for a 20
133 point@footnote{A point is the standard measure of length for
134 printing. One point is 1/72.27 inch.} high staff. We want smaller
135 output (16 point staff height), so we must import the settings for
136 that size, which is done.@example
141 A mudela file combines music with directions for outputting that
142 music. The music is combined with the output directions by putting
143 them into a @code{\score} block.
149 This makes LilyPond ready for accepting notes.
155 As we will see, pitches are combinations of octave, note name and
156 chromatic alteration. In this scheme, the octave is indicated by
157 using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
158 `@code{,}'). The central C is denoted by @code{c'}. The C one octave
159 higher is @code{c''}. One and two octaves below the central C is
160 denoted by @code{c} and @code{c,} respectively.
162 For pitches in a long piece you might have to type many quotes. To
163 remedy this, LilyPond has a ``relative'' octave entry mode. In this
164 mode, octaves of notes without quotes are chosen such that a note is
165 as close as possible (graphically, on the staff) to the the preceding
166 note. If you add a high-quote an extra octave is added. The lowered
167 quote (a comma) will subtract an extra octave. Because the first note
168 has no predecessor, you have to give the (absolute) pitch of the note
169 to start with.@example
174 What follows is sequential music, i.e.,
175 notes that are to be played and printed after each other.@example
180 This command changes the time signature of the current piece: a 3/4
181 sign is printed. This command is also used to generate bar lines in
182 the right spots.@example
187 This command changes the current key to G-major. Although this
188 command comes after the @code{\time} command, in the output, the key
189 signature comes before the time signature: LilyPond knows about music
190 typesetting conventions. @example
195 This command tells LilyPond that the following piece of music must
196 be played twice; @code{"volta"} volta brackets should be used for
197 alternatives---if there were any.
203 The subject of the repeat is again sequential music. Since
204 @code{\sequential} is such a common construct, a shorthand is provided:
205 just leave off @code{\sequential}, and the result is the same. @example
210 This is a note with pitch @code{d} (determined up to octaves). The
211 relative music was started with a @code{c''}, so the real pitch of this
212 note is @code{d''}. The @code{4} designates the duration of the note
213 (it is a quarter note). @example
218 These are notes with pitch @code{a} and @code{b}. Because their
219 duration is the same as the @code{g}, there is no need to enter the
220 duration (You may enter it anyway, eg. @code{a4 b4}) @example
225 Three more notes. The `@code{|}' character is a `barcheck'. When
226 processing the music, LilyPond will verify that barchecks are found at
227 the start of a measure. This can help you track down errors.
229 So far, no notes were chromatically altered. Here is the first one
230 that is: @code{fis}. Mudela by default uses Dutch note names, and
231 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
232 sharp sign in the output. The program keeps track of key signatures,
233 and will only print accidentals if they are needed.
239 LilyPond guesses were beams can be added to eighth and shorter notes.
240 In this case, a beam over 4 eighths is added.
243 c4 d8( )c b a( )b4 c8 b a g |
246 The next line shows how to make a slur:
247 the beginning and ending note of the slur is marked with an opening and
248 closing parenthesis respectively. In the line shown above this is
249 done for two slurs. Slur markers (parentheses) are between
255 Automatic beaming can be overridden by inserting beam marks
256 (brackets). Brackets are put around notes you want beamed.@example
261 A duration with augmentation dot is notated
262 with the duration number followed by a period.@example
267 This ends the sequential music to be repeated. LilyPond will typeset
268 a repeat bar. @example
273 This line shows that Lily will print an accidental if that is
274 needed: the first C sharp will be printed with an accidental, the
275 second one without. @example
277 a8-. b-. cis-. d-. e-. fis-.
280 You can enter articulation signs either in a verbose form using a
281 shorthand. Here we demonstrate the shorthand: it is formed by a dash
282 and the the character for the articulation to use, e.g. `@code{-.}' for
283 staccato as shown above. @example
289 Rests are denoted by the special notename `@code{r}'. You can also enter
290 an invisible rest by using the special notename `@code{s}'.
296 All articulations have a verbose form, like @code{\fermata}. The
297 command `@code{\fermata}' is not part of the core of the language (most
298 of the other discussed elements are), but it is a shorthand for a more
299 complicated description of a fermata. @code{\fermata} names that
300 description and is therefore called an @emph{identifier}. @example
314 This specifies a conversion from music to notation output. Most of
315 the details of this conversions (font sizes, dimensions, etc.) have
316 been taken care of, but to fit the output in this document, it has
317 to be smaller. We do this by setting the line width to 14 centimeters
318 (approximately 6 inches).
324 The last brace ends the @code{\score} block.
326 There are two things to note here. The format contains musical
327 concepts like pitches and durations, instead of symbols and positions:
328 the input format tries to capture the meaning of @emph{music}, and not
329 notation. Therefore Second, the format tries to be @emph{context-free}:
330 a note will sound the same regardless of the current time signature,
333 The purpose of LilyPond is explained informally by the term `music
334 typesetter'. This is not a fully correct name: not only does the
335 program print musical symbols, it also makes esthetic decisions. All
336 symbols and their placement is @emph{generated} from a high-level musical
337 description. In other words, LilyPond would be best
338 described by `music compiler' or `music to notation compiler'.
340 @node Lyrics and chords, , , Tutorial
341 @section Lyrics and chords
343 In this section we show how to typeset a song of unknown
344 origin.@footnote{The author would welcome information about the origin
349 title = "The river is flowing";
350 composer = "Traditional (?)";
352 \include "paper16.ly"
353 melody = \notes \relative c' @{
356 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
357 c4 c8 d [es () d] c4 | d4 es8 d c4.
362 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
363 ri -- ver is flo -- wing down to the sea.
366 accompaniment =\chords @{
368 c2-3- f-3-.7 d-min es4 c8-min r8
369 c2-min f-min7 g-7^3.5 c-min @}
374 \context ChordNames \accompaniment
377 \context Staff = mel @{
378 \property Staff.noAutoBeaming = "1"
379 \property Staff.automaticMelismata = "1"
382 \context Lyrics \text
385 \paper @{ linewidth = 10.0\cm; @}
390 The result would look this@footnote{The titling and font size shown
391 may differ, since the titling in this document is not generated by
394 @center @strong{The river is flowing}
399 title = "The river is flowing";
400 composer = "Traditional (?)";
402 \include "paper16.ly"
403 melody = \notes \relative c' {
406 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
407 c4 c8 d [es () d] c4 | d4 es8 d c4.
412 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
413 ri -- ver is flo -- wing down to the sea.
416 accompaniment =\chords {
418 c2-3- f-3-.7 d-min es4 c8-min r8
419 c2-min f-min7 g-7^3.5 c-min }
424 \context ChordNames \accompaniment
427 \context Staff = mel {
428 \property Staff.noAutoBeaming = "1"
429 \property Staff.automaticMelismata = "1"
432 \context Lyrics \text
435 \paper { linewidth = 10.0\cm; }
439 Again, we will dissect the file line by line.@example
444 Information about the music you are about to typeset goes into a
445 @code{\header} block. The information in this block is not used by
446 LilyPond, but it is included in the output. @file{ly2dvi} uses this
447 information to print titles above the music.
450 title = "The river is flowing";
451 composer = "Traditional (?)";
453 the @code{\header} block contains assignments. An assignment starts
454 with a string. (which is unquoted, in this case). Then comes the
455 equal sign `@code{=}'. After the equal sign comes the expression you
456 want to store. In this case, you want to put in strings. The
457 information has to be quoted here, because it contains spaces. The
458 assignment is finished with a semicolon.@example
460 \include "paper16.ly"
463 Smaller size for inclusion in a book.@example
465 melody = \notes \relative c' @{
468 The structure of the file will be the same as the previous one, a
469 @code{\score} block with music in it. To keep things readable, we will
470 give names to the different parts of music, and use the names to
471 construct the music within the score block.
479 The piece starts with an anacrusis of one eighth. @example
481 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
482 c4 c8 d [es () d] c4 | d4 es8 d c4.
486 We use explicit beaming. Since this is a song, we will turn automatic
487 beams off, and use explicit beaming where needed.@example
492 This ends the definition of @code{melody}. Note that there are no
493 semicolons after assignments at top level.@example
498 Another identifier assignment. This one is for the lyrics.
499 Lyrics are formed by syllables that have duration, and not by
500 notes. To make LilyPond parse words as syllables, switch it into
501 lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
502 is a shorthand for @code{\sequential @{}. @example
504 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
505 ri- ver is flo- __ wing down to the sea.
509 The syllables themselves are separated by spaces. You can get syllable
510 extenders by entering `@code{__}', and centered hyphens with
511 `@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
512 in length (hence the @code{4}), and use a feature to align the
513 syllables to the music (which obviously isn't all quarter notes.)
516 accompaniment =\chords @{
519 We'll put chords over the music. There is a special mode (analogous
520 to @code{\lyrics} and @code{\notes} mode) where you can give the names
521 of the chords you want, instead of the notes comprising the chord.
527 There is no accompaniment during the anacrusis.@example
532 A chord is started by the tonic of the chord. The
533 first one lasts a half note. An unadorned note creates a major
534 triad, while a minor triad is wanted. @code{3-} modifies the third to
535 be small. @code{7} modifies (adds) a seventh, which is small by default
536 to create the @code{f a c es} chord. Multiple modifiers must be
537 separated by a dot.@example
542 Some modifiers have predefined names, eg. @code{min} is the same as
543 @code{3-}, so @code{d-min} is a minor @code{d} chord.@example
545 c2-min f-min7 g-7^3.5 c-min @}
548 A named modifier @code{min} and a normal modifier @code{7} do not have
549 to be separated by a dot. Tones from a chord are removed with chord
550 subtractions. Subtractions are started with a caret, and they are
551 also separated by dots. In this example, @code{g-7^3.5} produces a
552 minor seventh. The brace ends the sequential music. @example
558 We assemble the music in the @code{\score} block. Melody, lyrics and
559 accompaniment have to sound at the same time, so they should be
560 @code{\simultaneous}.@example
565 Chord mode generates notes grouped in @code{\simultaneous} music. If
566 you remove the comment sign, you can see the chords in normal
567 notation: they will be printed as note heads on a separate
570 \context ChordNames \accompaniment
573 Normally, the notes that you enter are transformed into note heads.
574 The note heads alone make no sense, they need surrounding information:
575 a key signature, a clef, staff lines, etc. They need @emph{context}. In
576 LilyPond, these symbols are created by objects called `interpretation
577 context'. Interpretation contexts only exist during a run of
578 LilyPond. Interpretation contexts that are for printing music (as
579 opposed to playing music) are called `notation context'.
581 By default, LilyPond will create a Staff contexts for you. If you
582 would remove the @code{%} sign in the previous line, you can see that
585 We don't want default contexts here, because we want names, not note
586 heads. An interpretation context can also created upon explicit
587 request. The keyword for such a request is @code{\context}. It takes
588 two arguments. The first is the name of a interpretation context.
589 The name is a string, it can be quoted with double quotes). The
590 second argument is the music that should be interpreted in this
591 context. For the previous line, we could have written @code{\context
592 Staff \accompaniment}, and get the same effect.@example
597 The lyrics need to be aligned with the melody. This is done by
598 combining both with @code{\addlyrics}. @code{\addlyrics} takes two
599 pieces of music (usually a melody and lyrics, in that order) and
600 aligns the syllables of the second piece under the notes of the
601 first piece. If you would reverse the order, the notes would be
602 aligned on the lyrics, which is not very useful. (Besides, it looks
605 \context Staff = mel @{
608 This is the argument of @code{\addlyrics}. We instantiate a
609 @code{Staff} context explicitly: should you chose to remove comment
610 before the ``note heads'' version of the accompaniment, the
611 accompaniment will be on a nameless staff. The melody has to be on a
612 different staff as the accompaniment. This is accomplished by giving
613 the melody staff a different name.@example
615 \property Staff.noAutoBeaming = "1"
618 An interpretation context has variables that tune its behaviour. One
619 of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
620 true) LilyPond will not try to put automatic beaming on the current
623 \property Staff.automaticMelismata = "1"
626 Similarly, we don't want to print a syllable when there is
627 a slur. This sets up the Staff context to signal slurs while
628 @code{\addlyrics} is processed. @example
634 Finally, we put the melody on the current staff. Note that the
635 @code{\property} directives and @code{\melody} are grouped in sequential
636 music, so the property settings are done before the melody is
639 \context Lyrics \text
642 The second argument of @code{\addlyrics} is the text. The text also
643 should not land on a Staff, but on a interpretation context for
644 syllables, extenders, hyphens etc. This context is called
650 This ends @code{\simultaneous}.@example
655 This makes the music go to a MIDI file. MIDI is great for
656 checking music you enter. You listen to the MIDI file: if you hear
657 something unexpected, it's probably a typing error. @code{\midi} is an
658 `output definition', a declaration that specifies how to output music
659 analogous to @code{\paper @{ @}}.@example
661 \paper @{ linewidth = 10.0\cm; @}
664 We also want notation output. The linewidth is short so the piece
665 will be set in two lines. @example
672 @node Piano music, , , Tutorial
675 Our third subject is a piece piano music. The fragment in the input
676 file is a piano reduction of the G major Sinfonia by Giovanni Battista
677 Sammartini. It was composed around 1740.
681 \include "paper16.ly";
683 viola = \notes \relative c' \context Voice = viola {
685 \property Voice.verticalDirection = \down g'8. b,16
690 oboes = \notes \relative c'' \context Voice = oboe {
691 \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
692 \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
694 { \times 2/3 { a8 g c } \! c2 }
695 \context Voice = oboeTwo {
698 \property Grace.verticalDirection = \down
703 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
704 [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
705 [<c16( e> < )e8. g>] <c8 e,>
708 hoomPah = \notes \transpose c' {
709 c8 \translator Staff = top \stemdown
710 c'8 \translator Staff = bottom \stemup }
712 hoomPahHoomPah = { [\hoomPah \hoomPah] }
714 bassvoices = \notes \relative c' {
716 \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
717 \stemdown [c8 c'8] r4
719 < {\stemup r2 <e4 c'> <c8 g'> }
720 \context Voice = reallyLow {\stemdown g2 ~ | g4 c8 } >
724 \context PianoStaff \notes <
725 \context Staff = top < \time 2/2;
726 \context Voice = viola \viola
729 \context Staff = bottom < \time 2/2; \clef bass;
736 linewidth = 15.0 \cm; }
740 If it looks like incomprehensible gibberish to you@dots{} Then you are
741 right. The author has doctored this example to have as many quirks in
742 one system as possible.@example
743 viola = \notes \relative c' \context Voice = viola @{
745 In this example, you can see multiple parts on a staff. Each part is
746 associated with one notation context. This notation context handles
747 stems and dynamics (among others). The name of this context is
748 @code{Voice}. For each part we have to make sure that there is
749 precisely one Voice context@footnote{If @code{\context} would not
750 have been specified explicitly, three @code{Voice} contexts would be
751 created: one for each note in the first chord.}.@example
754 @code{<} and @code{>} are short hands for @code{\simultaneous @{} and
755 @code{@}}. So the expression enclosed in @code{<} and @code{>} is a
756 chord. @code{\f} places a forte symbol under the chord.@example
757 \property Voice.verticalDirection = \down
759 @code{verticalDirection} is a property of the voice context. It
760 controls the directions of stems, articulations marks and other
762 If @code{verticalDirection} is set to @code{\down}
763 (identifier for the integer -1) the stems go down,
764 @code{\up} (identifier for the integer 1) makes the stems go up.@example
767 Relative octaves work a little differently with chords. The starting
768 point for the note following a chord is the first note of the chord. So
769 the @code{g} gets an octave up quote: it is a fifth above the starting
770 note of the previous chord (the central C).
775 @code{s} is a `spacer' rest. It does not print anything, but it does
776 have the duration of a rest. @example
777 oboes = \notes \relative c'' \context Voice = oboe @{
779 Now comes a part for two oboes. They play homophonically, so we
780 print the notes as one voice that makes chords. Again, we insure that
781 these notes are indeed processed by precisely one context with
782 @code{\context}.@example
783 \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
785 @code{\stemup} is an identifier reference. It is shorthand for
786 @code{\property Voice.verticalDirection = \up}. If possible, you
787 should use predefined identifiers like these for setting properties.
788 Your input will be less dependent upon the implementation of LilyPond.
790 \grace <e8( g> < )d4 f> <c2 e>
792 @code{\grace} introduces grace notes. It takes one argument, in this
793 case a chord. The slur started on the @code{e} of the chord
794 will be attached to the next note.@footnote{LilyPond will squirm
795 about unended Slurs. In this case, you can ignore the warning}.
799 Tuplets are made with the @code{\times} keyword. It takes two
800 arguments: a fraction and a piece of music. The duration of the
801 second argument is multiplied by the first argument. Triplets make
802 notes occupy 2/3 of their notated duration, so in this case the
803 fraction is 2/3. @example
804 @{ <d8 \< f> <e g> <f a> @}
806 The piece of music to be `tripletted' is sequential music containing
807 three notes. On the first chord (the @code{d}), a crescendo is started
808 with @code{\<}.@example
811 At this point, the homophonic music splits into two rhythmically
812 different parts. We can't use a sequence of chords to enter this, so
813 we make a `chord' of sequences to do it. We start with the upper
814 voice, which continues with upward stems: @example
815 @{ \times 2/3 @{ a8 g c @} \! c2 @}
817 The crescendo is ended at the half note by the escaped exclamation
818 mark `@code{\!}'. @example
819 \context Voice = oboeTwo @{
822 We can't share stems with the other voice, so we have to create a new
823 @code{Voice} context. We give it the name @code{oboeTwo} to distinguish
824 it from the other context. Stems go down in this voice. @example
827 When a grace section is processed, a @code{Grace} context is
828 created. This context acts like a miniature score of its own. It has
829 its own time bookkeeping, and you can make notes, beams, slurs
830 etc. Here fiddle with a property and make a beam. The argument of
831 @code{\grace} is sequential music.@example
832 \property Grace.verticalDirection = \down
835 Normally, grace notes are always stem up, but in this case, the upper
836 voice interferes. We set the stems down here.
838 As far as relative mode is concerned, the previous note is the
839 @code{c'''2} of the upper voice, so we have to go an octave down for
846 This ends the two-part section. @example
848 \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
850 @code{\stemboth} ends the forced stem directions. From here, stems are
851 positioned as if it were single part music.
853 The bass has a little hoom-pah melody to demonstrate parts switching
854 between staffs. Since it is repetitive, we use identifiers:@example
855 hoomPah = \notes \transpose c' @{
857 Transposing can be done with @code{\transpose}. It takes two
858 arguments; the first specifies what central C should be transposed to.
859 The second is the to-be-transposed music. As you can see, in this
860 case, the transposition is a no-op. Central C is transposed to
863 The purpose of this no-op is circumventing relative mode. Relative
864 mode can not be used in conjunction with transposition, so relative
865 mode will leave the contents of @code{\hoomPah} alone. We can use it
866 without having to worry about getting the motive in a wrong
867 octave@footnote{@code{hoomPah = \relative @dots{}} would be more
868 intuitive to use, but that would not let me plug @code{\transpose}
870 c8 \translator Staff = top \stemdown
872 We assume that the first note will be put in the lower staff. After
873 that note we switch to the upper staff with @code{\translator}. To be
874 precise, this @code{\translator} entry switches the current voice to a
875 @code{Staff} named @code{top}. So we have to name the upper staff
876 `@code{top}'. Stem directions are set to avoid interfering with the
877 oboe voices. @example
878 c'8 \translator Staff = bottom \stemup @}
880 Then a note is put on the upper staff, and we switch again. We have
881 to name the lower staff `@code{bottom}'. @example
882 hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
884 Put two of these fragments in sequence, and beam them.@example
885 bassvoices = \notes \relative c' @{
887 \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
890 Entering the bass part is easy: the hoomPahHoomPah variable is
891 referenced four times.@example
892 \context Voice = reallyLow @{\stemdown g2 ~ | g4 c8 @} >
894 After skipping some lines, we see @code{~}. This mark makes ties.@example
897 For piano music, a special context is needed to get cross staff
898 beaming right. It is called @code{PianoStaff}.@example
899 \context Staff = bottom < \time 2/2; \clef bass;
901 The bottom staff must have a different clef.@example
904 To make some more room on the line, the first (in this case the only)
905 line is not indented. The line still looks is very cramped, but that is due
906 to the format of this tutorial.
908 This example shows a lot of features, but the organisation isn't
909 perfect. For example, it would be less confusing to use a chord
910 containing sequential music than a sequence of chords for the oboe
913 [TODO: demonstrate Hara-Kiri with scores and part extraction.]
915 @node end of tutorial, , , Tutorial
918 That's all folks. From here, you can either try fiddling with input
919 files, or you can read the reference manual.
926 @node Reference Manual, , , Top
928 * Overview:: Overview
929 * Top level:: Top level
930 * notenames:: notenames
931 * Lexical conventions:: Lexical conventions
932 * notelang:: notelang
935 * Music expressions:: Music expressions
936 * Atomic music expressions:: Atomic music expressions
937 * atomicmusic:: atomicmusic
938 * notedesc:: notedesc
939 * barlines:: barlines
940 * manualbeam:: manualbeam
942 * Compound music expressions:: Compound music expressions
943 * compoundmusic:: compoundmusic
944 * relative:: relative
945 * sec-repeats:: sec-repeats
946 * transpose:: transpose
947 * Ambiguities:: Ambiguities
948 * Notation conversion specifics:: Notation conversion specifics
949 * autobeam:: autobeam
950 * lyricprint:: lyricprint
951 * Notation Contexts:: Notation Contexts
952 * contextselection:: contextselection
953 * Notation output definitions:: Notation output definitions
956 * papervars:: papervars
957 * contextdefs:: contextdefs
958 * engravers:: engravers
959 * Sound output:: Sound output
960 * midilist:: midilist
961 * Pre-defined Identifiers:: Pre-defined Identifiers
962 * Running LilyPond:: Running LilyPond
965 @chapter Reference Manual
969 @node Overview, , , Reference Manual
972 This document@footnote{This document has been revised for
973 LilyPond 1.2.} describes the the GNU LilyPond input format, which is
974 a language for defining music. We call this language @emph{Music
975 Definition Language} or @emph{Mudela}, for short.@footnote{If anybody
976 comes up with a better name, we'd gladly take this. Gourlay already
977 uses a ``Musical Description Language,'' ISO standard 10743 defines a
978 ``Standard Music Description Language.'' We're not being original
981 @emph{Mudela} is a language that allows you to
984 @item create musical expressions by combining pitches, durations
985 @item output those musical expressions to various formats
986 @item give those musical expressions and output definitions names, so
987 you can enter them in manageable chunks.
990 @emph{Mudela} aims to define a piece of music completely, both from
991 typesetting and from a performance point of view.
995 @node Top level, , , Reference Manual
1000 This section describes what you may enter at top level.
1004 @cindex score definition
1006 The output is generated combining a music expression with an output
1007 definition. A score block has the following syntax:
1010 \score @{ @var{musicexpr} @var{outputdefs} @}
1013 @var{outputdefs} are zero or more output definitions. If no output
1014 definition is supplied, the default @code{\paper} block will be added.
1025 \header @{ @var{key1} = @var{val1};
1026 @var{key2} = @var{val2}; @dots{} @}
1029 A header describes the file's contents. It can also appear in a
1030 @code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this
1031 information for generating titles. Key values that are used by
1032 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
1033 metre, arranger, piece and tagline.
1035 It is customary to put the @code{\header} at the top of the file.
1038 @node notenames, , , Reference Manual
1040 Note name tables can be specified using
1043 \notenames@keyindex{notenames}
1044 @{ @var{assignmentlist} @}
1047 @var{assignmentlist} is a list of definitions of the form
1050 @var{name} = @var{pitch}
1053 Chord modifiers can be set analogously, with
1054 @code{\chordmodifiers}@keyindex{chordmodifiers}.
1056 A @code{\paper} block at top level sets the default paper block. A
1057 @code{\midi} block at top level works similarly.
1061 LilyPond contains a Scheme interpreter (the GUILE library) for
1062 internal use. The following commands access the interpreter
1066 \scm @keyindex{scm} @var{scheme} ;
1069 Evaluates the specified Scheme code. The result is discarded.
1072 \scmfile@keyindex{scmfile} @var{filename};
1075 Reads Scheme code from the specified file. The result is discarded.
1079 Identifier assignments may appear at top level. Semicolons are
1080 forbidden after top level assignments.
1084 @node Lexical conventions, , , Reference Manual
1085 @section Lexical conventions
1087 @cindex lexical conventions
1096 A one line comment is introduced by a `@code{%}' character.
1097 Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
1098 They cannot be nested.
1104 Keywords start with a backslash, followed by a number of lower case
1105 alphabetic characters. These are all the keywords.
1168 Formed from an optional minus sign followed by digits. Arithmetic
1169 operations cannot be done with integers, and integers cannot be mixed
1177 Formed from an optional minus sign and a sequence of digits followed
1178 by a @emph{required} decimal point and an optional exponent such as
1179 @code{-1.2e3}. Reals can be built up using the usual operations:
1180 `@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
1181 `@code{/}@indexcode{/}', with parentheses for grouping.
1183 A real constant can be followed by one of the dimension
1186 @code{\mm}@keyindex{mm},
1187 @code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
1188 @code{\cm}@keyindex{cm}, for millimeters, points, inches and
1189 centimeters, respectively. This converts the number to a real that
1190 is the internal representation of dimensions.
1197 Begins and ends with the `@code{"}' character. To include a `@code{"}'
1198 character in a string write `@code{\"}'. Various other backslash
1199 sequences have special interpretations as in the C language. A
1200 string that contains no spaces can be written without the quotes.
1201 See section XREF-modes [FIXME] for details on unquoted strings; their
1202 interpretation varies depending on the situation. Strings can be
1203 concatenated with the `@code{+}' operator.
1206 The tokenizer accepts the following commands. They can appear
1210 \maininput@keyindex{maininput}
1213 This command is used in init files to signal that the user file must
1214 be read. This command cannot be used in a user file.
1217 \include@keyindex{include} @var{file}
1220 Include @var{file}. The argument @var{file} may be a quoted string (an
1221 unquoted string will not work here!) or a string identifier. The full
1222 filename including the @file{.ly} extension must be given,
1225 \version@keyindex{version} @var{string} ;
1228 Specify the version of LilyPond that a file was written for. The
1229 argument is a version string in quotes, for example @code{"1.2.0"}.
1230 This is used to detect invalid input, and to aid
1231 @code{convert-mudela}, a tool that automatically upgrades input files.
1235 @cindex other languages
1237 @node notelang, , , Reference Manual
1239 Note name definitions have been provided in various languages.
1240 Simply include the language specific init file. For example:
1241 `@code{\include "english.ly"}'. The available language files and the
1242 names they define are:
1247 Note Names sharp flat
1248 nederlands.ly c d e f g a bes b -is -es
1249 english.ly c d e f g a bf b -s/-sharp -f/-flat
1250 deutsch.ly c d e f g a b h -is -es
1251 norsk.ly c d e f g a b h -iss/-is -ess/-es
1252 svenska.ly c d e f g a b h -iss -ess
1253 italiano.ly do re mi fa sol la sid si -d -b
1254 catalan.ly do re mi fa sol la sid si -d/-s -b
1259 Pitch names can be redefined using the
1260 @code{\notenames}@keyindex{notenames} command, see
1261 subsection XREF-notenames [FIXME].
1265 @cindex lexical modes
1269 @node modes, , , Reference Manual
1271 To simplify entering notes, lyrics, and chords, @emph{Mudela} has three
1272 special input modes on top of the default mode. In each mode, words
1273 are identified on the input. If @code{"word"} is encountered, it is
1274 treated as a string. If @code{\word} is encountered, it is treated as
1275 a keyword or as an identifier. The behavior of the modes differs in
1276 two ways: Different modes treat unquoted words differently, and
1277 different modes have different rules for deciding what is a word.
1283 At the start of parsing, @emph{Mudela} is in Normal mode. In Normal
1284 mode, a word is an alphabetic character followed by alphanumeric
1285 characters. If @code{word} is encountered on the input it is
1286 treated as a string.
1291 Note mode is introduced by the keyword
1292 @code{\notes}@keyindex{notes}. In Note mode, words can only
1293 contain alphabetic characters. If @code{word} is encountered,
1294 LilyPond first checks for a notename of @code{word}. If no
1295 notename is found, then @code{word} is treated as a string.
1297 Since combinations of numbers and dots are used for indicating
1298 durations, it is not possible to enter real numbers in this mode.
1303 Chord mode is introduced by the keyword
1304 @code{\chords}@keyindex{chords}. It is similar to Note mode, but
1305 words are also looked up in a chord modifier table (containing
1306 @code{maj}, @code{dim}, etc).
1308 Since combinations of numbers and dots are used for indicating
1309 durations, you can not enter real numbers in this mode. Dashes
1310 and carets are used to indicate chord additions and subtractions,
1311 so scripts can not be entered in Chord mode.
1316 Lyrics mode is introduced by the keyword
1317 @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
1318 easy to include punctuation and diacritical marks in words. A
1319 word in Lyrics mode begins with: an alphabetic character,
1320 `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
1321 control characters @code{^A} through @code{^F}, @code{^Q} through
1322 @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
1323 over 127, or a two-character combination of a backslash followed
1324 by one of `@code{`}', `@code{'}', `@code{"}', or
1325 `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
1326 enter lyrics in TeX format or a standard encoding without
1327 needing quotes. The precise definition of this mode indeed is
1328 ludicrous. This will remain so until the authors of LilyPond
1329 acquire a deeper understanding of character encoding, or someone
1330 else steps up to fix this.}
1332 Subsequent characters of a word can be any character that is not
1333 a digit and not white space. One important consequence of this
1334 is that a word can end with `@code{@}}', which may be confusing if
1335 you thought the closing brace was going to terminate Lyrics
1336 mode.@footnote{LilyPond will issue a warning, though.} Any
1337 `@code{_}' characters which appear in an unquoted word are
1338 converted to spaces. This provides a mechanism for introducing
1339 spaces into words without using quotes. Quoted words can also be
1340 used in Lyrics mode to specify words that cannot be written with
1341 the above rules. Here are some examples. Not all of these words
1342 are printable by TeX.
1349 2B_||_!2B % not a word because it starts with a digit
1350 ``Hello'' % not a word because it starts with `
1351 _ _ _ _ % 4 words, each one a space
1356 Since combinations of numbers and dots are used for indicating
1357 durations, you can not enter real numbers in this mode.
1360 It is possible to create words that break the rules by prefixing them
1361 with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a
1362 word beginning with `@code{$}' extends until the next white space
1363 character. Such words can contain numbers (even in Note mode), or
1364 other forbidden characters. The dollar sign can be used to create
1365 and access identifiers that could not otherwise be used.@footnote{Use
1366 of `@code{$}' hampers readability and portability to future LilyPond
1367 versions, thus the use of the dollar sign is discouraged.}
1371 @node Types, , , Reference Manual
1374 @cindex types and identifiers
1376 @emph{Mudela} has a limited set of types:
1382 @item music expressions
1383 @item durations of notes and rests (specified with
1384 @code{\notenames}@keyindex{notenames})
1385 @item note name tables
1386 @item context definitions, part of output definitions. See
1387 section XREF-contextdefs [FIXME] for more information
1388 @item output definitions (like @code{\paper}@keyindex{paper} blocks
1389 and @code{\midi}@keyindex{midi} blocks)
1390 @item score definitions (@code{\score}@keyindex{score} blocks)
1393 Type is a syntactical property: @emph{Mudela} has no real type system,
1394 so there is no support for generic expressions, functions, or user
1395 defined types. For the same reason, it is not possible to mix reals
1396 and integers in arithmetic expressions, and ``type
1399 (e.g., using a string identifier to
1400 initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse
1403 Identifiers allow objects to be assigned to names. To assign an
1404 identifier, you use `@var{name}=@var{value}' and to refer to an
1405 identifier, you preceed its name with a backslash:
1406 `@code{\}@var{name}'. Identifier assignments must appear at top level
1407 in the @emph{Mudela} file. Semicolons are forbidden after assignments
1408 appearing at top level but they are obligatory after assignments
1409 appearing in the @code{\paper} block, see Section XREF-paper [FIXME].
1411 @var{value} is any of the types listed above.
1413 An identifier can be created with any string for its name, but you
1414 will only be able to refer to identifiers whose names begin with a
1415 letter, being entirely alphanumeric. It is impossible to refer to an
1416 identifier whose name is the same as the name of a keyword.
1418 The right hand side of an identifier assignment is parsed completely
1419 before the assignment is done, so it is allowed to redefine an
1420 identifier in terms of its old value, e.g.
1426 When an identifier is referenced, the information it points to is
1427 copied. Therefore it only makes sense to put identifiers for
1428 translators, output definitions, and @code{\score}@keyindex{score}
1429 blocks as the first item in a block. For this reason, if you
1430 reference a @code{\foo} variable in a @code{\foo} block, it must be the
1431 first item in the list following @code{\foo}.@footnote{@code{\paper@{\one
1432 \two@}} does not make sense, because the information of @code{\two}
1433 would overwrite the information of @code{\one}, thereby making the
1434 reference to the first identifier useless.}
1438 @node Music expressions, , , Reference Manual
1439 @section Music expressions
1441 @cindex music expressions
1443 Music in @emph{Mudela} is entered as a music expression. Notes, rests,
1444 lyric syllables are music expressions (the atomic
1446 @cindex atomic music expressions
1447 , and you can combine
1448 music expressions to form new ones. This example forms a compound
1449 expressions out of the quarter @code{c} note and a @code{d}
1453 \sequential @{ c4 d4 @}
1456 The meaning of this compound expression is to play the `@code{c}'
1457 first, and then the `@code{d}' (as opposed to playing them
1458 simultaneously, for instance).
1460 Atomic music expression are discussed in
1461 subsection XREF-atomicmusic [FIXME]. Compound music expressions are
1462 discussed in subsection XREF-compoundmusic [FIXME].
1466 @node Atomic music expressions, , , Reference Manual
1467 @section Atomic music expressions
1468 @node atomicmusic, , , Reference Manual
1477 The syntax for pitch specification is
1481 \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
1484 @var{octave} is specified by an integer, zero for the octave
1485 containing middle C. @var{note} is a number from 0 to 7, with 0
1486 corresponding to C and 7 corresponding to B. The shift is zero for a
1487 natural, negative to add flats, or positive to add sharps.
1489 In Note and Chord mode, pitches may be designated by names. See
1490 section XREF-notelang [FIXME] for pitch names in different languages.
1492 The syntax for duration specification is
1495 \duration@keyindex{duration}
1496 @{ @var{length} @var{dotcount} @}
1499 @var{length} is the negative logarithm (base 2) of the duration:
1500 1 is a half note, 2 is a quarter note, 3 is an eighth
1501 note, etc. The number of dots after the note is given by
1504 In Note, Chord, and Lyrics mode, durations may be designated by
1505 numbers and dots. See Section XREF-notelang [FIXME] for details.
1508 @node notedesc, , , Reference Manual
1510 @cindex note specification
1514 @cindex entering notes
1516 A note specification has the form
1519 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
1522 The pitch of the note is specified by the note's name.
1525 The default names are the Dutch note names. The notes are specified
1526 by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
1527 octave below middle C and the letters span the octave above that C.
1528 In Dutchcindex(notenames!Dutch), a sharp is formed by adding
1529 `@code{-is}' to the end of a pitch name. A flat is formed by adding
1530 `@code{-es}'. Double sharps and double flats are obtained by adding
1531 `@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are
1532 contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will
1535 LilyPond has predefined sets of notenames for various languages. See
1536 section XREF-notelang [FIXME] for details.
1539 The optional octave specification takes the form of a series of
1540 single quote (`@code{'}@indexcode{'}') characters or a series of comma
1541 (`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
1542 octave; each @code{,} lowers the pitch by an octave.
1544 @mudela[fragment,verbatim,center]
1545 c' d' e' f' g' a' b' c''
1548 @mudela[fragment,verbatim,center]
1549 cis' dis' eis' fis' gis' ais' bis'
1552 @mudela[fragment,verbatim,center]
1553 ces' des' es' fes' ges' as' bes'
1556 @mudela[fragment,verbatim,center]
1557 cisis' eisis' gisis' aisis' beses'
1560 @mudela[fragment,verbatim,center]
1561 ceses' eses' geses' ases' beses'
1564 Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
1565 will determine what accidentals to typeset depending on the key and
1566 context. A reminder accidental
1567 @cindex reminder accidental
1569 forced by adding an exclamation mark `@code{!}' after the pitch. A
1570 cautionary accidental,
1571 @cindex cautionary accidental
1573 accidental within parentheses can be obtained by adding the question
1574 mark `@code{?}@indexcode{?}' after the pitch.
1576 @mudela[fragment,verbatim,center]
1577 cis' d' e' cis' c'? d' e' c'!
1583 Durations are entered as their reciprocal values. For notes longer
1584 than a whole note, use identifiers.
1590 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
1599 \notes \relative c'' {
1601 a1 a2 a4 a8 a16 a32 a64 a64
1604 loose_column_distance = 2.5 * \interline;
1607 \type "Score_engraver";
1609 \consists "Note_heads_engraver";
1610 \consists "Stem_engraver";
1611 \consists "Rhythmic_column_engraver";
1622 r1 r2 r4 r8 r16 r32 r64 r64
1631 \notes \relative c'' {
1633 r1 r2 r4 r8 r16 r32 r64 r64
1636 loose_column_distance = 2.5 * \interline;
1639 \type "Score_engraver";
1641 \consists "Rest_engraver";
1642 \consists "Stem_engraver";
1643 \consists "Rhythmic_column_engraver";
1650 If the duration is omitted then it is set equal to the previous
1651 duration. If there is no previous duration, a quarter note is
1652 assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
1653 to obtain dotted note lengths.
1655 @mudela[fragment,verbatim,center]
1659 You can alter the length of duration by writing
1660 `@code{*}@var{fraction}' after it. This will not affect the
1661 appearance of note heads or rests.
1664 Rests are entered like notes, with note name `@code{r}@indexcode{r}',
1665 or `@code{R}@indexcode{R}'. There is also a note name `@code{s}@indexcode{s}',
1666 which produces a space of the specified duration.
1667 `@code{R}' is specifically meant for entering parts: the @code{R} rest
1668 can expand to fill a score with rests, or it can be printed as a
1669 single multimeasure rest.
1672 @cindex lyrics expressions
1674 Syllables are entered like notes, with pitches replaced by text. For
1675 example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
1676 with quarter note duration. Note that the hyphen has no special
1677 meaning for lyrics, and does not introduce special symbols. See
1678 section XREF-modes [FIXME] for a description of what is interpreted as
1681 Spaces can be introduced into a lyric either by using quotes
1682 (`@code{"}') or by using an underscore without quotes: `@code{He_could4
1683 not4}'. All unquoted underscores are converted to spaces. Printing
1684 lyrics is discussed in section XREF-lyricprint [FIXME].
1691 \property@keyindex{property}
1692 @var{contextname}.@var{propname} = @var{value}
1695 Sets the @var{propname} property of the context @var{contextname} to
1696 the specified @var{value}. All three arguments are strings.
1697 Depending on the context, it may be necessary to quote the strings or
1698 to leave space on both sides of the dot.
1702 @cindex translator switches
1705 \translator@keyindex{translator}
1706 @var{contexttype} = @var{name}
1709 A music expression indicating that the context which is a direct
1710 child of the a context of type @var{contexttype} should be shifted to
1711 a context of type @var{contexttype} and the specified name.
1713 Usually this is used to switch staffs in Piano music, e.g.
1716 \translator Staff = top @var{Music}
1723 Commands are music expressions that have no duration.
1728 @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
1731 Change the key signature. @var{type} should be
1732 @code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
1733 @var{pitch}-major or @var{pitch}-minor, respectively. The second
1734 argument is optional; the default is major keys. The @var{\context}
1735 argument can also be given as an integer, which tells the number of
1736 semitones that should be added to the pitch given in the subsequent
1737 @code{\key}@keyindex{key} commands to get the corresponding major key,
1738 e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
1739 mode names @code{\ionian}@keyindex{ionian},
1740 @code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
1741 @code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
1742 @code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
1747 @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
1750 Specify an arbitrary key signature. The pitches from @var{pitch} will
1751 be printed in the key signature in the order that they appear on the
1756 \mark@keyindex{mark} @var{unsigned};
1760 Prints a mark over or under (depending on the
1761 @code{markDirection}@indexcode{markDirection} property) the staff. You must add
1762 @code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for
1765 @node barlines, , , Reference Manual
1768 \bar@keyindex{bar} @var{bartype};
1771 This is a request to print a special bar symbol. It replaces the
1772 regular bar symbol with a special
1773 symbol. The argument @var{bartype} is a string which specifies the
1774 kind of bar to print. Options are @code{":|"}
1775 @cindex "|A@@@code{:|}
1778 @cindex "|B@@@code{|:}
1780 @cindex "|C@@@code{:|:}
1783 @cindex "|D@@@code{||}
1785 @cindex "|E@@@code{|.}
1788 @cindex "|F@@@code{.|}
1790 @cindex "|G@@@code{.|.}
1792 These produce, respectively, a right repeat, a left repeat, a double
1793 repeat, a double bar, a start bar, an end bar, and a thick double
1794 bar. If @var{bartype} is set to @code{"empty"} then nothing is
1795 printed, but a line break is allowed at that spot.
1797 You are encouraged to use @code{\repeat} for repetitions.
1798 See section XREF-sec-repeats [FIXME].
1803 \cadenza@keyindex{cadenza} @var{togglevalue} @code{;}
1806 Music expression that toggles the automatic generation of bar lines.
1807 If @var{togglevalue} is 1, bar line generation is turned off. If
1808 @var{togglevalue} is 0, a bar line is immediately printed and
1809 automatic bar generation is turned on.
1813 \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
1816 Change the time signature. The default time signature is 4/4.
1817 The time signature is used to generate bar lines.
1821 \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
1824 Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
1825 requests output with 76 quarter notes per minute.
1829 \partial@keyindex{partial} @var{duration} @code{;}
1836 This creates an incomplete measure (anacrusis, upbeat) at the start of
1837 the music, e.g., `@code{\partial 8*2;}' creates a starting measure
1838 lasting two eighth notes.
1842 @code{|}@indexcode{|}
1847 @cindex shorten measures
1851 `@code{|}' is a barcheck. Whenever a barcheck is encountered during
1852 interpretation, a warning message is issued if it doesn't fall at a
1853 measure boundary. This can help you finding errors in the input.
1854 The beginning of the measure will be relocated, so this can also
1855 be used to shorten measures.
1860 \penalty@keyindex{penalty} @var{int} @code{;}
1863 Discourage or encourage line breaks. See identifiers
1864 @code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
1865 section [on identifiers] [FIXME].
1869 \clef@keyindex{clef} @var{clefname} @code{;}
1872 Music expression that sets the current clef. The argument is a
1873 string which specifies the name of the clef. Several clef names are
1874 supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef
1875 name, then the clef lowered or raised an octave will be generated.
1876 Here are the supported clef names with middle C shown in each
1885 %\property Voice.textStyle = typewriter
1886 \clef subbass; c'4-"\kern -5mm subbass"
1887 \clef bass; c'4^"\kern -2mm bass"
1888 \clef baritone; c'4_"\kern -5mm baritone"
1889 \clef varbaritone; c'4^"\kern -6mm varbaritone"
1890 \clef tenor; c'4_"\kern -3mm tenor"
1891 \clef "G_8"; c'4^"\kern -2mm G\\_8"
1894 linewidth = 4.5 \in;
1906 \clef alto; c'4_"\kern -2mm alto"
1907 \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano"
1908 \clef soprano; c'4_"\kern -6mm soprano"
1909 \clef treble; c'4^"\kern -4mm treble"
1910 \clef french; c'4_"\kern -4mm french"
1913 linewidth = 4.5 \in;
1919 The three clef symbols can also be obtained using the names `@code{G}',
1920 `@code{C}' or `@code{F}', optionally followed by an integer which
1921 indicates at which note line the clef is located. An as example, the
1922 @code{mezzosoprano} clef can also be given as `@code{C2}'.
1926 \skip@keyindex{skip} @var{duration} @code{;}
1929 Skips the amount of time specified by @var{duration}. If no other
1930 music is played, a gap will be left for the skipped time with no
1931 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
1932 this has the same effect as the space rest `@code{s}'.
1937 @node manualbeam, , , Reference Manual
1939 A beam is specified by surrounding the beamed notes with brackets
1940 `@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
1942 @mudela[fragment,verbatim,center]
1943 [a'8 a'] [a'16 a' a' a']
1946 Some more elaborate constructions:
1948 @mudela[fragment,verbatim,center]
1949 [a'16 <a' c''> c'' <a' c''>]
1950 \times 2/3 { [e'8 f' g'] }
1953 Beaming can be generated automatically; see section XREF-autobeam [FIXME].
1955 To place tremolo marks
1956 @cindex tremolo beams
1957 between two notes, begin
1958 with `@code{[:}@var{length}' and end with `@code{]}'. Tremolo marks
1959 will appear instead of beams. Putting more than two notes in such a
1960 construction will produce odd effects. To create tremolo beams on a
1961 single note, simply attach `@code{:}@var{length}' to the note itself
1962 (see also section XREF-tremolo [FIXME]).
1964 @mudela[fragment,verbatim,center]
1965 [:16 e'1 g'] [:8 e'4 f']
1968 @mudela[fragment,verbatim,center]
1969 c'4:32 [:16 c'8 d'8]
1973 @cindex --@@@code{-}@code{-}
1981 The syntax for an extender mark is `@code{__}'. This syntax can only
1982 be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
1983 a hyphen that will be printed between two lyric syllables) is
1989 A tie connects two adjacent note heads of the same pitch. When used
1990 with chords, it connects all of the note heads whose pitches match.
1991 Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
1992 If you try to tie together chords which have no common pitches, a
1993 warning message will appear and no ties will be created.
1995 @mudela[fragment,verbatim,center]
1996 e' ~ e' <c' e' g'> ~ <c' e' g'>
2001 [TODO: explain Requests]
2004 @cindex articulations
2010 A variety of symbols can appear above and below notes to indicate
2011 different characteristics of the performance. These symbols can be
2012 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
2013 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
2014 forced to appear above or below the note by writing
2015 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
2016 respectively. Here is a chart showing symbols above notes, with the
2017 name of the corresponding symbol appearing underneath.
2023 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
2024 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
2025 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
2026 c''-\rtoe c''-\turn c''-\open c''-\flageolet
2027 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
2028 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
2029 c''-\thumb c''-\segno c''-\coda
2031 \context Lyrics \lyrics {
2032 accent__ marcato__ staccatissimo__ fermata
2033 stopped__ staccato__ tenuto__ upbow
2034 downbow__ lheel__ rheel__ ltoe
2035 rtoe__ turn__ open__ flageolet
2036 reverseturn__ trill__ prall__ mordent
2037 prallprall__ prallmordent__ uprall__ downprall
2038 thumb__ segno__ coda
2042 linewidth = 5.875\in;
2049 In addition, it is possible to place arbitrary strings of text or
2050 TeX above or below notes by using a string instead of an
2051 identifier: `@code{c^"text"}'. Fingerings
2054 placed by simply using digits. All of these note ornaments appear in
2055 the printed output but have no effect on the MIDI rendering of the
2058 To save typing, fingering instructions (digits 0 to 9 are
2059 supported) and single characters shorthands exist for a few
2066 \property Voice.textStyle = typewriter
2072 c''4-^_"c-\\^{ }" s4
2079 linewidth = 5.875 \in;
2086 Dynamic marks are specified by using an identifier after a note:
2087 `@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
2088 The available dynamic marks are:
2089 @code{\ppp}@keyindex{ppp},
2090 @code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
2091 @code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
2092 @code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
2093 @code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
2094 @code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
2095 @code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
2096 @code{\rfz}@keyindex{rfz}.
2101 \textscript@keyindex{textscript} @var{text} @var{style}
2104 Defines a text to be printed over or under a note. @var{style} is a
2105 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
2106 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
2108 You can attach a general textscript request using this syntax:
2113 c4-\textscript "6" "finger"
2114 c4-\textscript "foo" "normal"
2119 This is equivalent to `@code{c4-6 c4-"foo"}'.
2126 \script@keyindex{script} @var{alias}
2129 Prints a symbol above or below a note. The argument is a string
2130 which points into the script-alias table defined in @file{script.scm}.
2131 The scheme definitions specify whether the symbol follows notes into
2132 the staff, dependence of symbol placement on staff direction, and a
2133 priority for placing several symbols over one note. Usually the
2134 @code{\script}@keyindex{script} keyword is not used directly. Various
2135 helpful identifier definitions appear in @file{script.ly}.
2140 Slurs connects chords and try to avoid crossing stems. A slur is
2141 started with `@code{(}' and stopped with `@code{)}'. The
2142 starting `@code{(}' appears to the right of the first note in
2143 the slur. The terminal `@code{)}' appears to the left of the
2144 first note in the slur. This makes it possible to put a note in
2145 slurs from both sides:
2147 @mudela[fragment,verbatim,center]
2148 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
2154 A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
2155 with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
2156 @code{\decr}@keyindex{decr} and terminated with
2157 @code{\rced}@keyindex{rced}. There are also shorthands for these
2158 marks. A crescendo can be started with @code{\<}@keyindex{<} and a
2159 decrescendo can be started with @code{\>}@keyindex{>}. Either one can
2160 be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
2161 must go before the last note of the dynamic mark whereas @code{\rc}
2162 and @code{\rced} go after the last note. Because these marks are
2163 bound to notes, if you want to get several marks during one note, you
2164 must use spacer notes.
2166 @mudela[fragment,verbatim,center]
2167 c'' \< \! c'' d'' \decr e'' \rced
2168 < f''1 { s4 \< \! s2 \> \! s4 } >
2174 \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
2177 Define a spanning request. The @var{startstop} parameter is either -1
2178 (@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
2179 @var{type} is a string that describes what should be started.
2180 Supported types are @code{crescendo}, @code{decrescendo},
2181 @code{beam}, @code{slur}. This is an internal command. Users should
2182 use the shorthands which are defined in the initialization file
2185 You can attach a (general) span request to a note using
2187 @mudela[fragment,verbatim,center]
2188 c'4-\spanrequest \start "slur"
2189 c'4-\spanrequest \stop "slur"
2192 The slur syntax with parentheses is a shorthand for this.
2196 @cindex tremolo marks
2198 @node tremolo, , , Reference Manual
2200 Tremolo marks can be printed on a single note by adding
2201 `@code{:}[@var{length}]' after the note. The length must be at
2202 least 8. A @var{length} value of 8 gives one line across
2203 the note stem. If the length is omitted, then the last value is
2204 used, or the value of the @code{abbrev}@indexcode{abbrev} property if there was
2207 @mudela[verbatim,fragment,center]
2213 @node Compound music expressions, , , Reference Manual
2214 @section Compound music expressions
2216 @cindex compound music expressions
2218 @node compoundmusic, , , Reference Manual
2220 Music expressions are compound data structures. You can nest music
2221 expressions any way you like. This simple example shows how three
2222 chords can be expressed in two different ways:
2224 @mudela[fragment,verbatim,center]
2225 \notes \context Staff {
2227 <a c'> <b d' > <c' e' >
2228 <{a b c'}{c' d' e'}>
2234 @cindex context selection
2238 \context@keyindex{context}
2239 @var{contexttype} [@code{=} @var{contextname}] @var{musicexpr}
2242 Interpret @var{musicexpr} within a context of type @var{contexttype}.
2243 If the context does not exist, it will be created. The new context
2244 can optionally be given a name. See
2245 section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more
2246 information on interpretation contexts.
2254 Mode switching keywords form compound music expressions: @code{\notes}
2255 @keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
2256 @var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
2257 These expressions do not add anything to the meaning of their
2258 arguments. They are just a way to indicate that the arguments should
2259 be parsed in indicated mode. See section XREF-modes [FIXME] for more
2260 information on modes.
2262 More information on context selection can be found in
2263 section XREF-contextselection [FIXME].
2267 @cindex sequential music
2273 \sequential@keyindex{sequential}
2274 @code{@{} @var{musicexprlist} @code{@}}
2277 This means that list should be played or written in sequence, i.e.,
2278 the second after the first, the third after the second. The duration
2279 of sequential music is the the sum of the durations of the elements.
2280 There is a shorthand, which leaves out the keyword:
2284 @code{@{} @var{musicexprlist} @code{@}}
2289 @cindex simultaneous music
2296 \simultaneous@keyindex{simultaneous}
2297 @code{@{} @var{musicexprlist} @code{@}}
2300 It constructs a music expression where all of its arguments start at
2301 the same moment. The duration is the maximum of the durations of the
2302 elements. The following shorthand is a common idiom:
2306 @code{<} @var{musicexprlist} @code{>}
2309 If you try to use a chord as the first thing in your score, you might
2310 get multiple staffs instead of a chord.
2312 @mudela[verbatim,center]
2321 This happens because the chord is interpreted by a score context.
2322 Each time a note is encountered a default Voice context (along with a
2323 Staff context) is created. The solution is to explicitly instantiate
2326 @mudela[verbatim,center]
2328 \notes\context Voice <c''4 e''>
2337 @cindex relative pitch specification
2339 @node relative, , , Reference Manual
2341 It is easy to get confused by octave changing marks and accidentally
2342 putting a pitch in the wrong octave. A much better way of entering a
2343 note's octave is `the relative octave' mode.
2347 \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
2350 The octave of notes that appear in @var{musicexpr} are calculated as
2351 follows: If no octave changing marks are used, the basic interval
2352 between this and the last note is always taken to be a fourth or
2353 less.@footnote{The interval is determined without regarding
2354 accidentals. A @code{fisis} following a @code{ceses} will be put above
2355 the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
2356 can then be added to raise or lower the pitch by an extra octave.
2357 Upon entering relative mode, an absolute starting pitch must be
2358 specified that will act as the predecessor of the first note of
2361 Entering scales is straightforward in relative mode.
2363 @mudela[fragment,verbatim,center]
2369 And octave changing marks are used for intervals greater than a fourth.
2371 @mudela[fragment,verbatim,center]
2373 c g c f, c' a, e'' }
2376 If the preceding item is a chord, the first note of the chord is used
2377 to determine the first note of the next chord. But other notes
2378 within the second chord are determined by looking at the immediately
2381 @mudela[fragment,verbatim,center]
2389 The pitch after the @code{\relative} contains a notename. To parse
2390 the pitch as a notename, you have to be in note mode, so there must
2391 be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
2394 The relative conversion will not affect @code{\transpose} or
2395 @code{\relative} sections in its argument. If you want to use
2396 relative within transposed music, you must place an additional
2397 @code{\relative} inside the @code{\transpose}.
2399 It is strongly recommended to use relative pitch mode: less work,
2400 less error-prone, and more readable.
2404 Chord names are a way to generate simultaneous music expressions that
2405 correspond with traditional chord names. It can only be used in
2406 Chord mode (see section XREF-modes [FIXME]).
2410 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}].
2413 @var{tonic} should be the tonic note of the chord, and @var{duration}
2414 is the chord duration in the usual notation. There are two kinds of
2415 modifiers. One type is @emph{chord additions}, which are obtained by
2416 listing intervals separated by dots. An interval is written by its
2417 number with an optional `@code{+}' or `@code{-}' to indicate raising or
2418 lowering by half a step. Chord additions has two effects: It adds
2419 the specified interval and all lower odd numbered intervals to the
2420 chord, and it may lower or raise the specified interval. Intervals
2421 must be separated by a dot (`@code{.}').
2425 @mudela[fragment,verbatim]
2429 c-9 c-9-.5+.7+ c-3-.5- c-4.6.8
2436 The second type of modifier that may appear after the `@code{-}' is a
2437 named modifier. Named modifiers are listed in the file
2438 @file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
2439 `@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
2440 raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
2441 `@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
2442 which replaces the 5th with a 4th.
2446 @mudela[fragment,verbatim]
2449 c1-m c-min7 c-maj c-aug c-dim c-sus
2457 Chord subtractions are used to eliminate notes from a chord. The
2458 notes to be subtracted are listed after a `@code{^}' character,
2461 @mudela[fragment,verbatim,center]
2469 Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
2470 the name of a single note to a chord. This has the effect of
2471 lowering the specified note by an octave so it becomes the lowest
2472 note in the chord. If the specified note is not in the chord, a
2473 warning will be printed.
2475 @mudela[fragment,verbatim,center]
2484 Throughout these examples, chords have been shifted around the staff
2485 using @code{\transpose}.
2487 You should not combine @code{\relative} with named chords.
2493 Tuplets are made out of a music expression by multiplying their
2494 duration with a fraction.
2498 \times@keyindex{times} @var{fraction} @var{musicexpr}
2501 The duration of @var{musicexpr} will be multiplied by the fraction.
2502 In print, the fraction's denominator will be printed over the notes,
2503 optionally with a bracket. The most common tuplet is the triplet in
2504 which 3 notes have the length of 2, so the notes are 2/3 of
2505 their written length:
2507 @mudela[fragment,verbatim,center]
2508 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
2517 \grace@keyindex{grace} @var{musicexpr}
2520 A grace note expression has duration 0; the next real note is
2521 assumed to be the main note.
2523 You cannot have the grace note after the main note, in terms of
2524 duration, and main notes, but you can typeset the grace notes to the
2525 right of the main note using the property
2526 @code{graceAlignPosition}@indexcode{graceAlignPosition}.
2528 When grace music is interpreted, a score-within-a-score is set up:
2529 @var{musicexpr} has its own time bookkeeping, and you could (for
2530 example) have a separate time signature within grace notes. While in
2531 this score-within-a-score, you can create notes, beams, slurs, etc.
2532 Unbeamed eighth notes and shorter by default have a slash through the
2533 stem. This behavior can be controlled with the
2534 @code{stemStyle}@indexcode{stemStyle} property.
2538 @mudela[fragment,verbatim]
2540 \grace c8 c4 \grace { [c16 c16] } c4
2541 \grace { \property Grace.stemStyle = "" c16 } c4
2547 At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
2551 @code{\grace @{ \grace c32 c16 @} c4}
2554 may result in run-time errors of LilyPond. Since the meaning of such
2555 a construct is unclear, we don't consider this a loss. Similarly,
2556 juxtaposing two @code{\grace} sections is syntactically valid, but
2557 makes no sense and may cause runtime errors.
2559 Ending a staff or score with grace notes may also generate a run-time
2560 error, since there will be no main note to attach the grace notes to.
2566 @node sec-repeats, , , Reference Manual
2568 In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
2569 keyword. Since repeats look and sound differently when played or
2570 printed, there are a few different variants of repeats.
2574 Repeated music is fully written (played) out. Useful for MIDI
2578 This is the normal notation: Repeats are not written out, but
2579 alternative endings (voltas) are printed, left to right.
2582 Alternative endings are written stacked, which is useful for
2586 The syntax for repeats is
2590 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2593 If you have alternative endings, you may add
2597 \alternative@keyindex{alternative}
2598 @code{@{} @var{alternative1}
2600 @var{alternative3} @dots{} @code{@}}
2603 where each @var{alternative} is a Music expression.
2605 Normal notation repeats are used like this:
2609 @mudela[fragment,verbatim]
2611 \repeat volta 2 { c'4 d' e' f' }
2612 \repeat volta 2 { f' e' d' c' }
2617 With alternative endings:
2621 @mudela[fragment,verbatim]
2623 \repeat volta 2 {c'4 d' e' f'}
2624 \alternative { {d'2 d'} {f' f} }
2629 Folded repeats look like this:@footnote{Folded repeats offer little
2630 more over simultaneous music. However, it is to be expected that
2631 more functionality -- especially for the MIDI backend -- will be
2636 @mudela[fragment,verbatim]
2638 \repeat fold 2 {c'4 d' e' f'}
2639 \alternative { {d'2 d'} {f' f} }
2646 @mudela[fragment,verbatim]
2650 \repeat volta 2 { e | c2 d2 | e2 f2 | }
2651 \alternative { { g4 g g } { a | a a a a | b1 } }
2658 If you don't give enough alternatives for all of the repeats, then
2659 the first alternative is assumed to be repeated often enough to equal
2660 the specified number of repeats.
2664 @mudela[fragment,verbatim]
2667 \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
2668 \alternative { { g4 g g }
2669 {\partial 1; e4 e e }
2670 {\partial 1; a a a a | b1 } }
2677 It is possible to nest @code{\repeat}. This is not entirely
2678 supported: the notes will come be in the right places, but the repeat
2683 @cindex transposition of pitches
2685 @node transpose, , , Reference Manual
2687 A music expression can be transposed with
2688 @code{\transpose}@keyindex{transpose}. The syntax is
2692 \transpose @var{pitch} @var{musicexpr}
2695 This means that middle C in @var{musicexpr} is transposed to
2698 @code{\transpose} distinguishes between enharmonic pitches: both
2699 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2700 a tone. The first version will print sharps and the second version
2705 @mudela[fragment,verbatim]
2710 \transpose des'' { \key e; c d e f }
2711 \transpose cis'' { \key e; c d e f }
2717 If you want to use both @code{\transpose} and @code{\relative}, then
2718 you must use @code{\transpose} first. @code{\relative} will have no
2719 effect music that appears inside a @code{\transpose}.
2723 @cindex automatic lyric durations
2725 If you have lyrics that are set to a melody, you can import the
2726 rhythm of that melody into the lyrics using @code{\addlyrics}.
2727 @keyindex{addlyrics} The syntax for this is
2731 \addlyrics @var{musicexpr1 musicexpr2}
2734 This means that both @var{musicexpr1} and @var{musicexpr2} are
2735 interpreted, but that every non-command atomic music expression
2736 (``every syllable'') in @var{musicexpr2} is interpreted using timing
2737 of @var{musicexpr1}.
2739 If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
2740 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2745 @mudela[verbatim,fragment]
2748 \property Voice.automaticMelismata = "1"
2749 c8 () cis d8. e16 f2
2751 \context Lyrics \lyrics {
2757 You should use a single rhythm melody, and single rhythm lyrics (a
2758 constant duration is the obvious choice). If you do not, you will get
2759 undesired effects when using multiple stanzas:
2763 @mudela[verbatim,fragment]
2766 c8 () cis d8. e16 f2
2768 \context Lyrics \lyrics
2775 It is valid (but probably not very useful) to use notes instead of
2776 lyrics for @var{musicexpr2}.
2781 @node Ambiguities, , , Reference Manual
2782 @section Ambiguities
2786 The grammar contains a number of ambiguities.@footnote{The authors
2787 hope to resolve them at a later time.}
2790 @item The assignment
2796 can be interpreted as making a string identifier @code{\foo}
2797 containing @code{"bar"}, or a music identifier @code{\foo}
2798 containing the syllable `bar'.
2800 @item The assignment
2806 can be interpreted as making an integer identifier
2807 containing -6, or a Request identifier containing the
2808 fingering `6' (with neutral direction).
2810 @item If you do a nested repeat like
2822 then it is ambiguous to which @code{\repeat} the
2823 @code{\alternative} belongs. This is the classic if-then-else
2824 dilemma. It may be solved by using braces.
2826 @item (an as yet unidentified ambiguity :-)
2831 @node Notation conversion specifics, , , Reference Manual
2832 @section Notation conversion specifics
2836 @cindex automatic beam generation
2838 @node autobeam, , , Reference Manual
2840 By default, LilyPond will generate beams automatically. This feature
2841 can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
2842 property to 1. It can be overridden for specific cases by
2843 specifying explicit beams as described in
2844 section XREF-manualbeam [FIXME].
2846 A large number of Voice properties are used to decide how to generate
2847 beams. Their default values appear in @file{auto-beam-settings.ly}.
2848 In general, beams can begin anywhere, but their ending location is
2849 significant. Beams can end on a beat, or at durations specified by
2850 the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
2851 quarter note, for example, you could set
2852 @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
2853 at every three eighth notes you would set it to `@code{"3/8"}'. The
2854 same syntax can be used to specify beam starting points using
2855 @code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
2857 To allow different settings for different time signatures, these
2858 property names can start with `@code{time}@var{N}@code{_}@var{M}' to
2859 restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
2860 to specify beams ending only for 6/8 time you would use the
2861 property @code{Voice.time6_8beamAutoEnd}. To allow different endings
2862 for notes of different durations, the duration can be tacked onto the
2863 end of the property. To specify beam endings for beams that contain
2864 32nd notes, you would use @code{Voice.beamAutoEnd_32}.
2872 @cindex printing!chord names
2874 For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
2875 and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
2876 either using the notation described above, or directly using
2881 @mudela[fragment,verbatim]
2883 \context ChordNames {
2884 \chords{a b c} \notes{<d f g> <e g b>}
2886 \context Staff \notes {
2894 LilyPond examines chords specified as lists of notes to determine a
2895 name to give the chord. By default, LilyPond will not try to
2896 identify chord inversions:
2898 @mudela[fragment,verbatim,center]
2900 \context ChordNameVoice \notes {
2903 \context Thread \notes {
2909 If you want inversions to be recognized, you must set the property
2910 @code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
2912 @mudela[fragment,verbatim,center]
2914 \property Score.chordInversion = 1
2915 \context ChordNameVoice \notes {
2918 \context Thread \notes {
2928 @cindex printing!lyrics
2930 @node lyricprint, , , Reference Manual
2932 Lyric syllables must be interpreted within a @code{Lyrics} context
2934 @cindex context!Lyrics
2937 Here is a full example:
2944 \notes \transpose c'' {
2946 e f g2 | e4 f g2 \bar "|.";
2948 \context Lyrics \lyrics {
2949 Va-4 der Ja- cob Va- der Ja- cob
2950 Slaapt gij nog?2 Slaapt4 gij nog?2
2958 You may want a continuous line after the syllables to show melismata.
2959 To achieve this effect, add a `@code{__}' lyric as a separate word
2960 after the lyric to be extended. This will create an extender, a line
2961 that extends over the entire duration of the lyric. This line will
2962 run all the way to the start of the next lyric, so you may want to
2963 shorten it by using a blank lyric (using `@code{_}').
2970 \notes \relative c'' {
2971 a4 () b () c () d | c () d () b () a | c () d () b () a
2973 \context Lyrics \lyrics {
2974 foo1 __ | bar2. __ _4 | baz1 __
2983 If you want to have hyphens centered between syllables (rather than
2984 attached to the end of the first syllable) you can use the special
2985 `@code{-}@code{-}' lyric as a separate word between syllables. This
2986 will result in a hyphen which length varies depending on the space
2987 between syllables, and which will be centered between the syllables.
2995 \notes \transpose c'' {
2997 e f g2 | e4 f g2 \bar "|.";
2999 \context Lyrics \lyrics {
3000 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
3001 Slaapt gij nog?2 | Slaapt4 gij nog?2
3011 @node Notation Contexts, , , Reference Manual
3012 @section Notation Contexts
3014 @cindex notation contexts
3016 Notation contexts are objects that only exist during a run of
3017 LilyPond. During the interpretation phase of LilyPond, the Music
3018 expression contained in a @code{\score} block is interpreted in time
3019 order. This is the order in which humans read, play, and write
3022 A context is an object that holds the reading state of the
3023 expression; it contains information like
3026 @item What notes are playing at this point?
3027 @item What symbols will be printed at this point?
3028 @item In what style will they printed?
3029 @item What is the current key signature, time signature, point within
3033 Contexts are grouped hierarchically: A @code{Voice} context is
3034 contained in a @code{Staff} context (because a staff can contain
3035 multiple voices at any point), a @code{Staff} context is contained in
3036 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
3037 these can all contain multiple staffs).
3039 Contexts associated with sheet music output are called @emph{notation
3040 contexts}, those for sound output are called playing contexts.
3042 Contexts are created either manually or automatically. Initially,
3043 the top level music expression is interpreted by the top level
3044 context (the @code{Score} context). When a atomic music expression
3045 (i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
3046 set of contexts is created that can process these atomic expressions,
3052 \score @{ \notes < c4 > @}
3057 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
3058 context. When the note `@code{c4}' itself is interpreted, a set of
3059 contexts is needed that will accept notes. The default for this is a
3060 @code{Voice} context, contained in a @code{Staff} context. Creation of
3061 these contexts results in the staff being printed.
3064 @node contextselection, , , Reference Manual
3068 You can also create contexts manually, and you probably have to do so
3069 if you want to typeset complicated multiple part material. If a
3070 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
3071 during the interpretation phase, the @var{musicexpr} argument will be
3072 interpreted with a context of type @var{name}. If you specify a name,
3073 the specific context with that name is searched.
3075 If a context of the specified type and name can not be found, a new
3076 one is created. For example,
3082 \notes \relative c'' {
3083 c4 <d4 \context Staff = "another" e4> f
3090 In this example, the @code{c} and @code{d} are printed on the
3091 default staff. For the @code{e}, a context Staff called
3092 `@code{another}' is specified; since that does not exist, a new
3093 context is created. Within @code{another}, a (default) Voice context
3094 is created for the @code{e4}. When all music referring to a
3095 context is finished, the context is ended as well. So after the
3096 third quarter, @code{another} is removed.
3098 Almost all music expressions inherit their interpretation context
3099 from their parent. In other words, suppose that the syntax for a
3104 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
3107 When the interpretation of this music expression starts, the context
3108 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
3111 Lastly, you may wonder, why this:
3117 \notes \relative c'' @{
3125 doesn't result in this:
3130 \notes \relative c'' {
3137 For the @code{c4}, a default @code{Staff} (with a contained
3138 @code{Voice}) context is created. After the @code{c4} ends, no
3139 music refers to this default staff, so it would be ended, with the
3140 result shown. To prevent this inconvenient behavior, the context to
3141 which the sequential music refers is adjusted during the
3142 interpretation. So after the @code{c4} ends, the context of the
3143 sequential music is also the default @code{Voice} context.
3144 The @code{d4} gets interpreted in the same context
3149 These are the contexts supplied with the package. They are defined
3150 in the initialization file @file{ly/engraver.ly}.
3153 @item @code{Grace}@indexcode{Grace}
3154 The context for handling grace notes. It is instantiated
3155 automatically when you use @code{\grace}. Basically, it is an
3156 `embedded' miniature of the Score context. Since this context
3157 needs special interaction with the rest of LilyPond, you should
3158 not explicitly instantiate it.
3160 @item @code{LyricVoice}@indexcode{LyricVoice}
3161 Corresponds to a voice with lyrics. Handles the printing of a
3162 single line of lyrics.
3164 @item @code{Thread}@indexcode{Thread}
3165 Handles note heads, and is contained in the Voice context. You
3166 have to instantiate this explicitly if you want to adjust the
3167 style of individual note heads.
3169 @item @code{Voice}@indexcode{Voice}
3170 Corresponds to a voice on a staff. This context handles the
3171 conversion of dynamic signs, stems, beams, super- and subscripts,
3172 slurs, ties, and rests.
3174 You have to instantiate this explicitly if you want to have
3175 multiple voices on the same staff.
3177 @item @code{ChordNamesVoice}@indexcode{ChordNamesVoice}
3178 A voice with chord names. Handles printing of a line of chord
3181 @item @code{ChordNames}@indexcode{ChordNames}
3182 Typesets chord names. Can contain @code{ChordNamesVoice}
3185 @item @code{Lyrics}@indexcode{Lyrics}
3186 Typesets lyrics. It can contain @code{LyricVoice} contexts.
3188 @item @code{Staff}@indexcode{Staff}
3189 Handles clefs, bar lines, keys, accidentals. It can contain
3190 @code{Voice} contexts.
3192 @item @code{RhythmicStaff}@indexcode{RhythmicStaff}
3193 A context like @code{Staff} but for printing rhythms. Pitches are
3194 ignored; the notes are printed on one line. It can contain
3195 @code{Voice} contexts.
3197 @item @code{GrandStaff}@indexcode{GrandStaff}
3198 Contains @code{Staff} or @code{RhythmicStaff} contexts. It adds a
3199 brace on the left side, grouping the staffs together. The bar
3200 lines of the contained staffs are connected vertically. It can
3201 contain @code{Staff} contexts.
3203 @item @code{PianoStaff}@indexcode{PianoStaff}
3204 Just like @code{GrandStaff} but with @code{minVerticalAlign} set
3205 equal to @code{maxVerticalAlign} so that interstaff beaming and
3206 slurring can be used.
3208 @item @code{StaffGroup}@indexcode{StaffGroup}
3209 Contains @code{Staff} or @code{RhythmicStaff} contexts. Adds a
3210 bracket on the left side, grouping the staffs together. The bar
3211 lines of the contained staffs are connected vertically. It can
3212 contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
3213 @code{Lyrics} contexts.
3215 @item @code{ChoirStaff}@indexcode{ChoirStaff}
3216 Identical to @code{StaffGroup} except that the contained staffs
3217 are not connected vertically.
3219 @item @code{Score}@indexcode{Score}
3220 This is the top level notation context. No other context can
3221 contain a @code{Score} context. This context handles the
3222 administration of time signatures. It also makes sure that items
3223 such as clefs, time signatures, and key-signatures are aligned
3224 across staffs. It can contain @code{Lyrics}, @code{Staff},
3225 @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
3226 @code{ChoirStaff} contexts.
3228 You cannot explicitly instantiate a Score context (since it is
3229 not contained in any other context). It is instantiated
3230 automatically when an output definition (a @code{\score} or
3231 @code{\paper} block) is processed.
3236 Properties that are set in one context are inherited by all of the
3237 contained contexts. This means that a property valid for the
3238 @code{Voice} context can be set in the @code{Score} context (for
3239 example) and thus take effect in all @code{Voice} contexts.
3241 Properties can be preset within the @code{\translator} block
3242 corresponding to the appropriate context. In this case, the syntax
3247 @var{propname} @code{=} @var{value}
3250 This assignment happens before interpretation starts, so a
3251 @code{\property} expression will override any predefined settings.
3253 The @code{\property} expression will create any property you specify.
3254 There is no guarantee that a property will be used. So if you spell
3255 a property name wrong, there will be no error message.
3257 The property settings are used during the interpretation phase. They
3258 are read by the LilyPond modules where interpretation contexts are
3259 built of. These modules are called @emph{translators}. Translators for
3260 notation are called @emph{engravers}, and translators for sound are
3261 called @emph{performers}.
3263 The precise result of a property is determined by the implementation
3264 of the translator that reads them. Therefore, the result of a
3265 property can vary, since it is implementation and configuration
3268 In order to fully find out what properties are used, you must
3269 currently search the source code for calls to @code{get_property}.
3270 The rest of the section is devoted to an (incomplete) overview of
3271 available properties.
3274 @cindex properties!Lyrics
3277 @item @code{textStyle}@indexcode{textStyle}
3278 Set the font for lyrics. The available font choices are
3279 @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
3280 @code{typewriter}, and @code{finger}. The @code{finger} font can
3281 only display numbers. Note also that you must be careful when
3282 using @code{\property} in Lyrics mode, because of the way strings
3283 are parsed. Either put quotes around the arguments to
3284 @code{\property} or be sure to leave a space on both sides of the
3289 @cindex properties!Thread
3292 @item @code{noteheadStyle}@indexcode{noteheadStyle}
3293 Selects type of note head. Choices are @code{cross},
3294 @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
3295 They are shown in that order below.
3301 \property Staff.barNonAuto = 1
3302 \property Voice.noteHeadStyle = cross
3304 \property Voice.noteHeadStyle = diamond
3306 \property Voice.noteHeadStyle = harmonic
3308 \property Voice.noteHeadStyle = transparent
3310 \property Voice.noteHeadStyle = ""
3321 @subsubheading Grace properties
3323 @cindex properties!Grace
3327 @item @code{stemStyle}@indexcode{stemStyle}
3328 By default set to @code{"grace"} meaning that all unbeamed
3329 notes with flags are typeset with a slash through the flag.
3330 Setting to @code{""} gives standard flags.
3334 @subsubheading Voice properties
3336 @cindex properties!Voice
3339 @item @code{abbrev}@indexcode{abbrev}
3340 Set length for tremolo to be used if no length is explicitly
3343 @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
3345 Determines the extra space added between articulation marks, such
3346 as staccato, tenuto, trill, up/down bow or fermata, and the
3347 closest staff line or note.
3349 @item @code{articulationScriptVerticalDirection}
3350 @indexcode{articulationScriptVerticalDirection}
3351 Determines the location of articulation marks. Set to @code{\up}
3352 to print marks above the staff; set to @code{\down} to print marks
3353 below the staff. This property does not override explicit
3354 directions marked with `@code{^}' or `@code{_}' in the mudela file.
3356 @item @code{noAutoBeaming}@indexcode{beamAuto}
3357 If set to 1 then beams are not generated automatically.
3359 @item @code{beamAutoEnd}@indexcode{beamAutoEnd}
3360 Specifies when automatically generated beams can end. See
3361 section XREF-autobeam [FIXME].
3363 @item @code{beamAutoBegin}@indexcode{beamAutoBegin}
3364 Specifies when automatically generated beams can start. See
3365 section XREF-autobeam [FIXME].
3367 @item @code{beamquantisation}@indexcode{beamquantisation}
3368 Set to @code{\none} for no quantization. Set to @code{\normal} to
3369 quantize position and slope. Set to @code{\traditional} to avoid
3370 wedges. These three settings are available via
3371 @code{\beamposfree}@keyindex{beamposfree},
3372 @code{\beamposnormal}@keyindex{beamposnormal}, and
3373 @code{\beampostraditional}@keyindex{beampostraditional}.
3375 @item @code{beamslopedamping}@indexcode{beamslopedamping}
3376 Set to @code{\none} for undamped beams. Set to @code{\normal} for
3377 damped beams. Set to @code{\infinity} for beams with zero slope.
3379 @code{\beamslopeproportional}@keyindex{beamslopeproportional},
3380 @code{\beamslopedamped}@keyindex{beamslopedamped}, and
3381 @code{\beamslopezero}@keyindex{beamslopezero} each set the
3382 corresponding value.
3384 @item @code{dynamicDirection}@indexcode{dynamicDirection}
3385 Determines location of dynamic marks. Set to @code{\up} to print
3386 marks above the staff; set to @code{\down} to print marks below
3389 @item @code{dynamicStyle}@indexcode{dynamicStyle}
3390 Set the text style for dynamics.
3392 @item @code{fontSize}@indexcode{fontSize}
3393 Can be used to select smaller font sizes for music. The normal
3394 font size is 0, and the two smaller sizes are -1
3397 @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
3398 Force horizontal shift for collision resolution. It overrides
3399 automatic collision resolution. The value is the shift amount
3400 expressed in @code{note_width}, as set in the paper section.
3402 [FIXME: this should be moved]
3404 Lilypond always arranges note heads on alternate sides of a stem (that
3405 is, within a single voice) as necessary to prevent collisions (note head
3406 overlaps). For up stems, the upper note of a colliding pair is placed
3407 on the right side of the stem, the lower on the left. For down stems,
3408 the algorithm works in reverse.
3410 Lily also attempts to prevent collisions of note heads in different
3411 voices. A situation where chords of two or more voices are played
3412 simultaneously within one staff.
3414 By default, if only two voices (and both have opposite stem directions)
3415 are in this 'collision group', the notes both are shifted by @code{0.5
3416 \quartwidth} if there are unisons or seconds between the voices.
3418 If there are more than two voices in a collision group, shifting is
3419 inactive by default, since in this case, there are multiple chords with
3420 the same stem direction. By distinguish between those chords, LilyPond
3421 can do collision resolution in these cases as well.
3423 Distinguishing between voices with the same stem direction, is done by
3424 setting the property @code{Voice.horizontalNoteShift}. It must be set
3425 to a different integer for each voice. Then, all note heads in collision
3426 groups (not just unisons and seconds) will be offset, one voice relative
3427 another. The following fragment of sheet music shows how shifting is
3428 done, with values of @code{horizontalNoteShift} printed over and under
3429 the notes. In this case the chords are just simple notes.
3431 @c URG : mudela book bug.
3434 \notes \context Staff <
3435 \context Voice = VA { \stemup f''4^"0" }
3436 \context Voice = VB {\stemup
3437 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
3438 \context Voice = VC { \stemup \property
3439 Voice.horizontalNoteShift = 2 b'4^" 2" }
3440 \context Voice = VD { \stemdown \property
3441 Voice.horizontalNoteShift = 1 g'4_"1 " }
3442 \context Voice = VE { \stemdown e'4_"0" }
3447 If you are not satisfied with the collision resolution of LilyPond, you
3448 can override the horizontal shift value of the chord of one Voice, by
3449 setting @code{forceHorizontalShift}. This sets the amount shift,
3450 measured in black note head widths.
3452 To take complete control of note position shifts in complex passages,
3453 you have set things up for normal collisions and override all shifts by
3454 setting @code{forceHorizontalShift} to zero everywhere
3456 \property Voice.horizontalNoteShift = <n>
3457 \property Voice.forceHorizontalShift = "0.0"
3460 Then you can set the force property to a suitable value before each note
3461 that really needs it (unisons and seconds), and reset it to 0.0 after
3464 @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift}
3465 Enable LilyPond to shift notes horizontally if they collide with
3466 other notes. This is useful when typesetting many voices on one
3467 staff. The identifier @code{\shift}@keyindex{shift} is defined to
3468 enable this. Traditionally, the outer chords (the upmost and
3469 downmost voices), should have no @code{horizontalNoteShift}.
3471 @item @code{markScriptPadding}@indexcode{markScriptPadding}
3472 Determines the extra space added between the mark and the closest
3475 @item @code{markDirection}@indexcode{markDirection}
3476 Determines if marks should be printed above or below the staff.
3477 Set to @code{\up} to print marks above the staff; set to
3478 @code{\down} to print marks below the staff.
3480 @item @code{midiInstrument}@indexcode{midiInstrument}
3481 Sets the instrument for MIDI output. If this property is not set
3482 then LilyPond will use the @code{instrument} property. This must
3483 be set to one of the strings on the list of MIDI instruments that
3484 appears in section XREF-midilist [FIXME]. If you use a string which
3485 is not listed, LilyPond will silently substitute piano.
3487 @item @code{oldTieBehavior}@indexcode{oldTieBehavior}
3488 Set to 1 in order to get old tie behavior where ties would
3489 connect unequal pitches. This property is deprecated, and its
3490 use is not recommended.
3492 @item @code{restStyle}@indexcode{restStyle}
3493 Change the layout of rests shorter than quarter notes.
3494 Currently, the standard layout @code{""} and mensural notation
3495 @code{"mensural"} are available. Mensural rests of duration
3496 32 or shorter are not available.
3498 @item @code{scriptHorizontal}@indexcode{scriptHorizontal}
3499 Put scripts left or right of note heads. Support for this is
3500 limited. Accidentals will collide with scripts.
3502 @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection}
3503 Set to @code{\free} for free choice of slur direction, set to
3504 @code{\up} to force slurs up, set to @code{\down} to force slurs
3505 down. The shorthands @code{\slurup}@keyindex{slurup},
3506 @code{\slurdown}@keyindex{slurdown}, and
3507 @code{\slurboth}@keyindex{slurboth} are available.
3509 @item @code{slurDash}@indexcode{slurDash}
3510 Set to 0 for normal slurs, 1 for dotted slurs, and a
3511 larger value for dashed slurs. Identifiers
3512 @code{\slurnormal}@keyindex{slurnormal} and
3513 @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
3516 @item @code{stemLength}@indexcode{stemLength}
3517 Set length of stems. Unit is `@code{interline}/2', so
3518 @code{stemLength} defaults to 7.
3520 @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount}
3521 Specify the number of beams to draw on the left side of the next
3522 note. Overrides automatic beaming. The value is only used once,
3523 and then it is erased.
3525 @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount}
3526 Specify the number of beams to draw on the right side of the next
3527 note. Overrides automatic beaming. The value is only used once,
3528 and then it is erased.
3529 @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection}
3530 Set to @code{\free} for free choice of tie direction, set to
3531 @code{\up} to force ties up, set to @code{\down} to force ties
3534 @item @code{transposing}@indexcode{transposing}
3535 Transpose the MIDI output. Set this property to the number of
3536 half-steps to transpose by.
3539 @item @code{textEmptyDimension}@indexcode{textEmptyDimension}
3540 If set to 1 then text placed above or below the staff is
3541 assumed to have zero width.
3543 @item @code{textStyle}@indexcode{textStyle}
3544 Set the text style for superscripts and subscripts. See above
3545 for list of text styles.
3547 @item @code{textScriptPadding}@indexcode{textScriptPadding}
3548 Determines the extra space added between superscripted resp.
3549 subscripted text and the closest staff line or note.
3551 @item @code{verticalDirection}@indexcode{verticalDirection}
3552 Determines the direction of stems, subscripts, beams, slurs, and
3553 ties. Set to @code{\down} to force them down, @code{\up} to force
3554 them up, or @code{\free} to let LilyPond decide. This can be used
3555 to distinguish between voices on the same staff. The
3556 @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
3557 and @code{\stemboth}@keyindex{stemboth} identifiers set this
3561 @item @code{tupletDirection}@indexcode{tupletDirection}
3562 Determines the direction of triplets and other tuplets. Set to
3563 @code{\down} to force them below the staff, @code{\up} to force
3564 them above, or @code{\free} to let LilyPond decide.
3566 @item @code{tupletVisibility}@indexcode{tupletVisibility}
3567 Determines whether tuplets of notes are labelled. Setting
3568 to 0 shows nothing; setting to 1 shows a number;
3569 setting to 2 shows a number and a bracket if there is no
3570 beam; setting to 3 shows a number, and if there is no beam
3571 it adds a bracket; setting to 4 shows both a number and a
3572 bracket unconditionally.
3576 @subsubheading Staff properties
3578 @cindex properties!Staff
3582 @item @code{barNonAuto}@indexcode{barNonAuto}
3583 If set to 1 then bar lines will not be printed
3584 automatically; they must be explicitly created with @code{\bar}
3585 keywords. Unlike with the @code{\cadenza} keyword, measures are
3586 still counted. Bar generation will resume according to that
3587 count if this property is set to zero.
3589 @item @code{barNumberDirection}@indexcode{barNumberDirection}
3590 Set to @code{\up} or @code{\down} to put bar numbers above or below
3593 @item @code{barNumberHangOnClef}@indexcode{barNumberHangOnClef}
3594 Set to 1 to cause bar numbers to appear above or below the
3595 clef instead of on the bar line. This property is deprecated.
3598 @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
3599 Sets extra space between the bar number and the bar it labels.
3601 @item @code{barSize}@indexcode{barSize}
3602 Specify the height of the bar lines if it should be different
3603 than the staff height.
3605 @item @code{barAtLineStart}@indexcode{barAtLineStart}
3606 Set to 1 to produce a bar line after the clef at the start
3607 of each line (but not at the beginning of the music).
3609 @item @code{clefStyle}@indexcode{clefStyle}
3610 Determines how clefs are typeset. If set to @code{transparent},
3611 the clefs are not printed at all, if set to
3612 @code{fullSizeChanges}, clef changes in the middle of a line are
3613 typeset with a full size clef. By default, clef changes are
3614 typeset in smaller size.
3616 @item @code{createKeyOnClefChange}@indexcode{createKeyOnClefChange}
3617 Set to a nonempty string if you want key signatures to be printed
3618 when the clef changes. Set to the empty string if you do not
3619 want key signatures printed.
3621 @item @code{createInitdefaultClef}@indexcode{createInitdefaultClef}
3622 Specify whether clefs are created on default? (Doesn't seem to
3625 @item @code{defaultClef}@indexcode{defaultClef}
3626 Determines the default clef. See @code{\clef} keyword.
3628 @item @code{markHangOnClef}@indexcode{markHangOnClef}
3629 Set to 1 to cause marks to appear by clefs instead of by bar
3630 lines. Deprecated, use is not recommended.
3632 @item @code{marginDirection}@indexcode{marginDirection}
3633 Set to @code{\left} or @code{\right} to specify location of
3636 @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
3637 Specify extra space for marginal scripts.
3639 @item @code{forgetAccidentals}@indexcode{forgetAccidentals}
3640 Causes accidentals to be printed at every note instead of
3641 remembered for the duration of a measure.
3643 @item @code{noResetKey}@indexcode{noResetKey}
3644 Do not reset the key at the start of a measure. Accidentals will
3645 be printed only once and are in effect until overridden, possibly
3646 many measures later.
3648 @item @code{staffLineLeading}@indexcode{staffLineLeading}
3649 Specifies the distance (in points) between lines of the staff.
3651 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}
3652 Specifies the number of staff lines. The default is 5.
3654 @item @code{postBreakPadding}@indexcode{postBreakPadding}
3655 Extra space in points to be added after the clef, time signature
3656 and key signature on the staff. Deprecated, do not use.
3658 @item @code{noVoltaBraces}@indexcode{noVoltaBraces}
3659 Set to true to suppress the printing of brackets over alternate
3660 endings specified by the command @code{\alternative}.
3662 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}
3663 Sets the number of lines that the staff has.
3665 @item @code{barAlways}@indexcode{barAlways}
3666 If set to 1 a bar line is drawn after each note.
3668 @item @code{defaultBarType}@indexcode{defaultBarType}
3669 Sets the default type of bar line. See Section XREF-barlines [FIXME]
3670 for a list of available bar types.
3672 @item @code{instrument}, @code{instr}
3673 @indexcode{instrument}@indexcode{instr}
3674 If @code{Staff_margin_engraver}
3675 @cindex Staff_margin_engraver
3677 added to the Staff translator, then the @code{instrument} property
3678 is used to label the first line of the staff and the @code{instr}
3679 property is used to label subsequent lines. If the
3680 @code{midiInstrument} property is not set, then @code{instrument}
3681 is used to determine the instrument for MIDI output.
3683 @item @code{keyOctaviation}@indexcode{keyOctaviation}
3684 If set to 1, then keys are the same in all octaves. If set
3685 to 0 then the key signature for different octaves can be
3686 different and is specified independently:
3689 \keysignature bes fis'
3692 The default value is 1. Can be set to zero with
3693 @code{\specialkey} or reset to 1 with @code{\normalkey}.
3695 @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle}
3696 Changes the default two-digit layout for time signatures. The
3697 following values are recognized:
3700 @item @code{C}@indexcode{C}
3701 4/4 and 2/2 are typeset as C and struck C, respectively. All
3702 other time signatures are written with two digits.
3704 @item @code{old}@indexcode{old}
3705 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
3706 typeset with old-style mensuration marks. All other time
3707 signatures are written with two digits.
3709 @item @code{1}@indexcode{1}
3710 All time signatures are typeset with a single
3711 digit, e.g. 3/2 is written as 3.
3713 @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
3714 @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
3715 @code{old6/8alt}@indexcode{old6/8alt}
3716 Tells LilyPond to use a specific symbol as time signature.
3719 The different time signature characters are shown below with its
3725 \notes\relative c'' {
3726 \property Voice.textStyle = typewriter
3727 \property Staff.timeSignatureStyle = "C2/2"
3728 \time 2/2; a2^"C2/2" a2
3729 \property Staff.timeSignatureStyle = "C4/4"
3730 \time 2/2; a2^"C4/4" a2
3731 \property Staff.timeSignatureStyle = "old2/2"
3732 \time 2/2; a2^"old2/2" a2
3733 \property Staff.timeSignatureStyle = "old3/2"
3734 \time 2/2; a2^"old3/2" a2
3735 \property Staff.timeSignatureStyle = "old2/4"
3736 \time 2/2; a2^"old2/4" a2
3737 \property Staff.timeSignatureStyle = "old4/4"
3738 \time 2/2; a2^"old4/4" a2
3739 \property Staff.timeSignatureStyle = "old6/4"
3740 \time 2/2; a2^"old6/4" a2
3741 \property Staff.timeSignatureStyle = "old9/4"
3742 \time 2/2; a2^"old9/4" a2
3743 \property Staff.timeSignatureStyle = "old4/8"
3744 \time 2/2; a2^"old4/8" a2
3745 \property Staff.timeSignatureStyle = "old6/8"
3746 \time 2/2; a2^"old6/8" a2
3747 \property Staff.timeSignatureStyle = "old6/8alt"
3748 \time 2/2; a2^"old6/8alt" a2
3749 \property Staff.timeSignatureStyle = "old9/8"
3750 \time 2/2; a2^"old9/8" a2
3753 linewidth = 4.5 \in;
3759 @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration}
3760 Set to an integer to control the size of the brackets printed by
3761 @code{\alternative}. The integer specifies the number of whole
3762 notes duration to use for the brackets. It is rounded to the
3763 nearest measure. This can be used to shrink the length of
3764 brackets in the situation where one alternative is very large.
3765 It may have odd effects if the specified duration is longer than
3766 the music given in an @code{\alternative}.
3770 @cindex properties!GrandStaff
3773 @item @code{alignmentReference}@indexcode{alignmentReference}
3774 Set to @code{\center} for vertical alignment reference point to be
3775 in the center of the vertical group. Set to @code{\up} to put the
3776 reference point at the top of the group.
3778 @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign}
3779 Set the maximum vertical distance between staffs.
3781 @item @code{minVerticalAlign}@indexcode{minVerticalAlign}
3782 Set the minimum vertical distance between staffs.
3786 @cindex properties!Score
3789 @item @code{skipBars}@indexcode{skipBars}
3790 Set to 1 to skip the empty bars that are produced by
3791 multimeasure notes and rests. These bars will not appear on the
3792 printed output. Set to zero (the default) to expand multimeasure
3793 notes and rests into their full length, printing the appropriate
3794 number of empty bars so that synchronization with other voices is
3799 @mudela[fragment,verbatim,center]
3800 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
3808 @cindex properties!ChordNamesVoice
3811 @item @code{chordInversion}@indexcode{chordInversion}
3812 Determines whether LilyPond should look for chord inversions when
3813 translating from notes to chord names. Set to 1 to find
3814 inversions. The default is 0 which does not look for
3820 @node Notation output definitions, , , Reference Manual
3821 @section Notation output definitions
3825 @cindex notation output
3827 @cindex output definition
3829 @node paper, , , Reference Manual
3831 The most important output definition is the @code{\paper} block, for
3832 music notation. The syntax is
3836 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3839 where each of the items is one of
3842 @item An assignment. The assignment must be terminated by a
3843 semicolon. See section XREF-papervars [FIXME] for information on
3846 @item A context definition. See section XREF-contextdefs [FIXME] for
3847 more information on context definitions.
3849 @item A margin shape declaration. The syntax is
3853 \shape @var{indent1}@code{,} @var{width1}@code{,}
3854 @var{indent2}@code{,} @var{width2} @dots{} @code{;}
3859 Each pair of @var{indent} and @var{width} values is a dimension
3860 specifying how far to indent and how wide to make the line.
3861 The indentation and width of successive lines are specified by
3862 the successive pairs of dimensions. The last pair of
3863 dimensions will define the characeristics of all lines beyond
3864 those explicitly specified.
3866 @item A font declaration. Its syntax is
3870 @var{fontsize} @code{=} \font@keyindex{font} @var{fontname}
3873 @var{fontsize} is an integer describing the font to be used.
3874 0 is the default font. @var{fontname} is the basename of
3875 a font (usually a member of the Feta family).
3880 @cindex changing font size and paper size
3882 The Feta font provides musical symbols at six different sizes. These
3883 fonts are 11 point, 13 point, 16 point, 20 point,
3884 23 point, and 26 point. The point size of a font is the
3885 height of the five lines in a staff when displayed in the font.
3887 Definitions for these sizes are the files @file{paperSZ.ly}, where
3888 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
3889 any of these files, the identifiers @code{paper_eleven},
3890 @code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
3891 @code{paper_twentythree}, and @code{paper_twentysix} are defined
3892 respectively. The default @code{\paper} block is also set.
3894 To change the paper size, you must first set the
3895 @code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
3896 @code{a4}, @code{letter}, or @code{legal}. After this specification,
3897 you must set the font as described above. If you want the default
3898 font, then use the 20 point font. The new paper size will not
3899 take effect if the font is not loaded and selected afterwards. Paper
3900 size selection works by loading a file named after the paper size you
3905 @cindex paper variables
3907 @node papervars, , , Reference Manual
3909 There is a large number of paper variables that are used to control
3910 details of the layout. These variables control the defaults for the
3911 entire score. Usually, they do not have to be changed; they are by
3912 default set to values that depend on the font size in use. The
3913 values are used by the graphic objects while formatting the score;
3914 they are therefore implementation dependent. Most variables are
3915 accompanied by documentation in the initalization file
3916 @file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
3919 Nevertheless, here are some variables you may want to use or change:
3922 @item @code{indent}@indexcode{indent}
3923 The indentation of the first line of music.
3925 @item @code{interline}@indexcode{interline}
3926 The distance between two staff lines, calculated from the center
3927 of the lines. You should use either this or @code{rulethickness}
3928 as a unit for distances you modify.
3930 @item @code{linewidth}@indexcode{linewidth}
3931 Sets the width of the lines. If set to -1.0, a single
3932 unjustified line is produced.
3934 @item @code{output}@indexcode{output}
3935 Specifies an alternate name for the the output @file{s}.
3936 A @file{.tex}, @file{.midi} or @file{.ps} extension will be
3937 added to the string you specify.
3939 @item @code{rulethickness}@indexcode{rulethickness}
3940 Determines the thickness of staff and bar lines.
3942 @item @code{castingalgorithm}@indexcode{castingalgorithm}
3943 The algorithm to use for breaking lines. Choices are
3944 @code{\Gourlay}@keyindex{Gourlay} for a TeX-like dynamic
3945 programming algorithm, and @code{\Wordwrap}@keyindex{Wordwrap} for
3946 a simple algorithm. Gourlay breaking looks much better, but
3947 takes a lot more resources. Wordwrap leaves loosely spaced lines
3952 @node contextdefs, , , Reference Manual
3954 @cindex context definition
3956 A notation contexts is defined by the following information
3961 @item The LilyPond modules that do the actual conversion of music to
3962 notation. Each module is a so-called
3967 @item How these modules should cooperate, i.e. which ``cooperation
3968 module'' should be used. This cooperation module is a special
3971 @item What other contexts the context can contain,
3973 @item What properties are defined.
3976 A context definition has this syntax:
3980 \translator @code{@{}
3981 @var{translatorinit} @var{translatormodifierlist}
3985 @var{translatorinit} can be an identifier or of the form
3989 \type @var{typename} @code{;}
3992 @var{typename} is one of
3995 @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
3996 The standard cooperation engraver.
3998 @item @code{Score_engraver}@indexcode{Score_engraver}
3999 This is cooperation module that should be in the top level context.
4001 @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
4002 This is a special cooperation module (resembling
4003 @code{Score_engraver}) that is used to created an embedded
4007 @var{translatormodifierlist} is a list of items where each item is
4011 @item @code{\consists} @var{engravername} @code{;}
4012 Add @var{engravername} to the list of modules in this context.
4013 Section XREF-engravers [FIXME] contains an overview of the engravers
4014 available. The order of engravers added with @code{\consists} is
4017 @item @code{\consistsend} @var{engravername} @code{;}
4018 Analogous to @code{\consists}, but makes sure that
4019 @var{engravername} is always added to the end of the list of
4022 Some engraver types need to be at the end of the list; this
4023 insures they are put there, and stay there, if a user adds or
4024 removes engravers. This command is usually not needed for
4027 @item @code{\accepts} @var{contextname} @code{;}
4028 Add @var{contextname} to the list of context this context can
4029 contain. The first listed context the context to create by
4032 @item @code{\remove} @var{engravername} @code{;}
4033 Remove a previously added (with @code{\consists}) engraver.
4035 @item @code{\name} @var{contextname} @code{;}
4036 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
4037 the name is not specified, the translator won't do anything.
4039 @item @var{propname} @code{=} @var{value} @code{;}
4040 A property assignment. It is allowed to use reals for
4044 In the @code{\paper} block, it is also possible to define translator
4045 identifiers. Like other block identifiers, the identifier can only
4046 be used as the very first item of a translator. In order to define
4047 such an identifier outside of @code{\score}, you must do
4053 foo = \translator @{ @dots{} @}
4060 \translator @{ \foo @dots{} @}
4068 @cindex paper types, engravers, and pre-defined translators
4070 Some pre-defined identifiers can simplify modification of
4071 translators. The pre-defined identifiers are:
4074 @item @code{StaffContext}@indexcode{StaffContext}
4075 Default Staff context.
4077 @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
4078 Default RhythmicStaff context.
4080 @item @code{VoiceContext}@indexcode{VoiceContext}
4081 Default Voice context.
4083 @item @code{ScoreContext}@indexcode{ScoreContext}
4084 Default Score context.
4086 @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
4087 Score context with numbering at the Score level.
4089 @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
4090 Staff context with numbering at the Staff level.
4092 @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
4093 Staff context that does not print if it only contains rests.
4094 Useful for orchestral scores.@footnote{Harakiri, also called
4095 Seppuku, is the ritual suicide of the Samourai.}
4097 @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
4099 @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
4102 Using these pre-defined values, you can remove or add items to the
4111 \remove Some_engraver;
4112 \consists Different_engraver;
4121 @node engravers, , , Reference Manual
4123 The engravers for paper output are:
4128 @item @code{Bar_engraver}@indexcode{Bar_engraver}
4129 Engraves bar lines. Normally in @code{Staff} and
4130 @code{RhythmicStaff}.
4132 @item @code{Bar_number_engraver}@indexcode{Bar_number_engraver}
4133 Engrave bar numbers. These numbers appear at the start of each
4134 line. Not normally in any translator. Can be added to
4135 @code{Score} for score-wide numbering or to @code{Staff} for
4136 numbering on each staff.
4138 @item @code{Beam_engraver}@indexcode{Beam_engraver}
4139 Handles beam requests by engraving beams. Normally appears in
4140 the @code{Voice} translator. If omitted, then notes will be
4141 printed with flags instead of beams.
4143 @item @code{Beam_req_swallow_translator}
4144 @indexcode{Beam_req_swallow_translator}
4145 Swallows beam requests. In @code{LyricVoice}.
4147 @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver}
4148 Engraves chord names. Normally in @code{ChordNameVoice} .
4150 @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver}
4152 @item @code{Clef_engraver}@indexcode{Clef_engraver}
4153 Engraves the clef symbol. Normally in @code{Staff}.
4155 @item @code{Collision_engraver}@indexcode{Collision_engraver}
4157 @item @code{Dot_column_engraver}@indexcode{Dot_column_engraver}
4158 Engraves dots on dotted notes shifted to the right of the note.
4159 Normally in @code{Voice}. If omitted, then dots appear on top of
4162 @item @code{Dynamic_engraver}@indexcode{Dynamic_engraver}
4163 Engraves dynamics symbols. Normally in @code{Voice}.
4165 @item @code{Font_size_engraver}@indexcode{Font_size_engraver}
4167 @item @code{Key_engraver}@indexcode{Key_engraver}
4168 Engraves the key signature. Normally in @code{Staff}.
4170 @item @code{Local_key_engraver}@indexcode{Local_key_engraver}
4172 @item @code{Lyric_engraver}@indexcode{Lyric_engraver}
4173 Engraves lyrics. Normally in @code{LyricVoice}.
4175 @item @code{Multi_measure_rest_engraver}
4176 @indexcode{Multi_measure_rest_engraver}
4177 Engraves multi-measure rests that are produced with @code{R}.
4178 Normally in @code{Voice}.
4180 @item @code{Piano_bar_engraver}@indexcode{Piano_bar_engraver}
4182 @item @code{Pitch_squash_engraver}@indexcode{Pitch_squash_engraver}
4183 Treat all pitches as middle C. Used in @code{RhythmicStaff}.
4184 Note that the notes move, but the locations of accidentals stay
4187 @item @code{Priority_horizontal_align_engraver}
4188 @indexcode{Priority_horizontal_align_engraver}
4190 @item @code{Repeat_engraver}@indexcode{Repeat_engraver}
4191 Handles repeats? In @code{Staff} and @code{RhythmicStaff}.
4193 @item @code{Rest_collision_engraver}@indexcode{Rest_collision_engraver}
4194 Handles collisions of rests. In @code{Staff}.
4196 @item @code{Rest_engraver}@indexcode{Rest_engraver}
4197 Engraves rests. Normally in @code{Voice}.
4199 @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver}
4201 @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver}
4203 @item @code{Script_engraver}@indexcode{Script_engraver}
4204 Handles note ornaments generated by @code{\script}. Normally in
4207 @item @code{Separating_line_group_engraver}
4208 @indexcode{Separating_line_group_engraver}
4210 @item @code{Skip_req_swallow_translator}
4211 @indexcode{Skip_req_swallow_translator}
4213 @item @code{Slur_engraver}@indexcode{Slur_engraver}
4214 Engraves slurs. Normally in @code{Voice}.
4216 @item @code{Span_bar_engraver}@indexcode{Span_bar_engraver}
4217 Engraves lines across multiple staffs. Normally in
4218 @code{Staffgroup} and @code{GrandStaff}. Removing this from
4219 @code{StaffGroup} gives the definition of @code{ChoirStaff}.
4221 @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver}
4223 @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver}
4225 @item @code{Staff_margin_engraver}@indexcode{Staff_margin_engraver}
4226 Prints the name of the instrument (specified by
4227 @code{Staff.instrument} and @code{Staff.instr}) at the left of the
4230 @item @code{Staff_sym_engraver}@indexcode{Staff_sym_engraver}
4232 @item @code{Stem_engraver}@indexcode{Stem_engraver}
4233 Engraves stems. Normally in @code{Voice}.
4235 @item @code{Ties_engraver}@indexcode{Ties_engraver}
4236 Engraves ties. Normally in @code{Voice}.
4238 @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver}
4239 Engraves the time signature. Normally in @code{Staff} and
4240 @code{RhythmicStaff}.
4242 @item @code{Timing_engraver}@indexcode{Timing_engraver}
4243 Responsible for synchronizing timing information from staffs.
4244 Normally in @code{Score}. In order to create polyrhythmic music,
4245 this engraver should be removed from @code{Score} and placed in
4248 @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver}
4249 Engraves tuplet brackets? In @code{Staff}.
4251 @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver}
4256 @node Sound output, , , Reference Manual
4257 @section Sound output
4261 The MIDI block is analogous to the paper block, but it is simpler.
4262 The @code{\midi} block can contain:
4266 @item a @code{\tempo} definition
4267 @item context definitions
4270 Assignments in the @code{\midi} block are not allowed.
4274 @cindex context definition
4276 Context definitions follow precisely the same syntax as within the
4277 \paper block. Translation modules for sound are called performers.
4278 The contexts for MIDI output are defined in @file{ly/performer.ly}.
4282 @cindex MIDI instrument names
4284 @node midilist, , , Reference Manual
4286 The MIDI instrument name is set by the
4287 @code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
4288 if that property is not set, the
4289 @code{Staff.instrument}@indexcode{Staff.instrument} property. The
4290 instrument name should be chosen from the following list. If the
4291 selected string does not exactly match, then LilyPond uses the default
4298 "acoustic grand" "contrabass" "lead 7 (fifths)"
4299 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
4300 "electric grand" "pizzicato strings" "pad 1 (new age)"
4301 "honky-tonk" "orchestral strings" "pad 2 (warm)"
4302 "electric piano 1" "timpani" "pad 3 (polysynth)"
4303 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
4304 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
4305 "clav" "synthstrings 1" "pad 6 (metallic)"
4306 "celesta" "synthstrings 2" "pad 7 (halo)"
4307 "glockenspiel" "choir aahs" "pad 8 (sweep)"
4308 "music box" "voice oohs" "fx 1 (rain)"
4309 "vibraphone" "synth voice" "fx 2 (soundtrack)"
4310 "marimba" "orchestra hit" "fx 3 (crystal)"
4311 "xylophone" "trumpet" "fx 4 (atmosphere)"
4312 "tubular bells" "trombone" "fx 5 (brightness)"
4313 "dulcimer" "tuba" "fx 6 (goblins)"
4314 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
4315 "percussive organ" "french horn" "fx 8 (sci-fi)"
4316 "rock organ" "brass section" "sitar"
4317 "church organ" "synthbrass 1" "banjo"
4318 "reed organ" "synthbrass 2" "shamisen"
4319 "accordion" "soprano sax" "koto"
4320 "harmonica" "alto sax" "kalimba"
4321 "concertina" "tenor sax" "bagpipe"
4322 "acoustic guitar (nylon)" "baritone sax" "fiddle"
4323 "acoustic guitar (steel)" "oboe" "shanai"
4324 "electric guitar (jazz)" "english horn" "tinkle bell"
4325 "electric guitar (clean)" "bassoon" "agogo"
4326 "electric guitar (muted)" "clarinet" "steel drums"
4327 "overdriven guitar" "piccolo" "woodblock"
4328 "distorted guitar" "flute" "taiko drum"
4329 "guitar harmonics" "recorder" "melodic tom"
4330 "acoustic bass" "pan flute" "synth drum"
4331 "electric bass (finger)" "blown bottle" "reverse cymbal"
4332 "electric bass (pick)" "skakuhachi" "guitar fret noise"
4333 "fretless bass" "whistle" "breath noise"
4334 "slap bass 1" "ocarina" "seashore"
4335 "slap bass 2" "lead 1 (square)" "bird tweet"
4336 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
4337 "synth bass 2" "lead 3 (calliope)" "helicopter"
4338 "violin" "lead 4 (chiff)" "applause"
4339 "viola" "lead 5 (charang)" "gunshot"
4340 "cello" "lead 6 (voice)"
4346 @cindex MIDI types and performers
4348 The types available for MIDI translators are:
4351 @item @code{Performer_group_performer}@indexcode{Performer_group_performer}
4352 @item @code{Score_performer}@indexcode{Score_performer}
4353 @item @code{Staff_performer}@indexcode{Staff_performer}
4356 The performers for MIDI translators are:
4359 @item @code{Key_performer}@indexcode{Key_performer}
4360 @item @code{Time_signature_performer}@indexcode{Time_signature_performer}
4361 @item @code{Note_performer}@indexcode{Note_performer}
4362 @item @code{Lyric_performer}@indexcode{Lyric_performer}
4363 @item @code{Swallow_performer}@indexcode{Swallow_performer}
4368 @node Pre-defined Identifiers, , , Reference Manual
4370 @section Pre-defined Identifiers
4372 @cindex pre-defined identifiers
4375 Various identifiers are defined in the initialization files to
4376 provide shorthands for some settings. Most of them are in
4377 @file{ly/declarations.ly}.
4380 @item @code{\break}@keyindex{break}
4381 Force a line break in music by using a large argument for the
4382 keyword @code{\penalty}.
4384 @item @code{\center}@keyindex{center}
4385 Used for setting direction properties. Equals 0.
4387 @item @code{\down}@keyindex{down}
4388 Used for setting direction setting properties. Is equal
4391 @item @code{\free}@keyindex{free}
4392 Used for setting direction setting properties. Is equal
4395 @item @code{\left}@keyindex{left}
4396 Used for setting text alignment property. Is equal to -1.
4398 @item @code{\nobreak}@keyindex{nobreak}
4399 Prevent a line break in music by using a large negative argument
4400 for the keyword @code{\penalty}.
4402 @item @code{\none}@keyindex{none}
4403 Used for setting @code{Score.beamslopedamping} and
4404 @code{Score.beamquantisation} properties. Is equal to 0.
4406 @item @code{\normal}@keyindex{normal}
4407 Used for setting @code{Score.beamslopedamping} and
4408 @code{Score.beamquantisation} properties. Is equal to 1.
4410 @item @code{\normalkey}@keyindex{normalkey}
4411 Select normal key signatures where each octave has the same key
4412 signature. This sets the @code{Staff.keyoctaviation} property.
4414 @item @code{\right}@keyindex{right}
4415 Used for setting text alignment property. Is set to 1.
4417 @item @code{\shiftoff}@keyindex{shiftoff}
4418 Disable horizontal shifting of note heads that collide. Sets the
4419 @code{Voice.horizontalNoteShift} property.
4421 @item @code{\shifton}@keyindex{shifton}
4422 Enable note heads that collide with other note heads to be
4423 shifted horiztonally. Sets the @code{Voice.horizontalNoteShift}
4426 @item @code{\slurboth}@keyindex{slurboth}
4427 Allow slurs to be above or below notes. This sets the
4428 @code{Voice.slurVerticalDirection} property.
4430 @item @code{\slurdown}@keyindex{slurdown}
4431 Force slurs to be below notes. This sets the
4432 @code{Voice.slurVerticalDirection} property.
4434 @item @code{\slurup}@keyindex{slurup}
4435 Force slurs to be above notes. This sets the
4436 @code{Voice.slurVerticalDirection} property.
4438 @item @code{\specialkey}@keyindex{specialkey}
4439 Allow key signatures do differ in different octaves. This sets
4440 the @code{Staff.keyoctaviation} property.
4442 @item @code{\stemboth}@keyindex{stemboth}
4443 Allow stems, beams, and slurs to point either upwards or
4444 downwards, decided automatically by LilyPond. This sets the
4445 @code{Voice.verticalDirection} property.
4447 @item @code{\stemdown}@keyindex{stemdown}
4448 Force stems, beams, and slurs to point down. This sets the
4449 @code{Voice.verticalDirection} property.
4451 @item @code{\stemup}@keyindex{stemup}
4452 Force stems, beams and slurs to point up. This sets the
4453 @code{Voice.verticalDirection} property.
4455 @item @code{\traditional}@keyindex{traditional}
4456 Used for setting the @code{Score.beamquantisation} property. Is
4459 @item @code{\up}@keyindex{up}
4460 Used for setting various direction properties. Is equal
4466 @node Running LilyPond, , , Reference Manual
4467 @section Running LilyPond
4469 @cindex running LilyPond
4472 When invoked with a filename that has no extension, LilyPond will try
4473 adding `@file{.ly}' as an extension first, then `@file{.fly}' and
4474 finally `@file{.sly}' extension. If the filename ends with
4475 `@file{.fly}', LilyPond processes the file as music using
4476 `@file{init.fly}'. In this case, LilyPond does something like:
4482 \notes\relative c @{
4483 \input "yourfile.fly"
4492 The result of `@file{.sly}' is similar except that a single unjustified
4495 If you invoke LilyPond with a file `@file{foo.}@var{ext}' that doesn't
4496 have the `@file{.ly}' extension, then LilyPond will look for a file
4497 called `@file{init.}@var{ext}' and process this file. The file
4498 `@file{init.}@var{ext}' must contain the @code{\maininput} keyword or
4499 LilyPond will not read the user specified file.
4501 When LilyPond processes @file{filename.ly} it will produce
4502 @file{filename.tex} as output. If @file{filename.ly} contains a second
4503 @code{\paper} keyword, then LilyPond will produce @file{filename-1.tex}
4504 as well. Subsequent @code{\paper} keywords will produce sequentially
4505 numbered file names. Several files can be specified; they will each
4506 be processed independently.@footnote{Not entirely true: The status of
4509 @node Glossary, , , Top
4512 @include glossary.texi