3 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
7 redef(code)(1)(tt(ARG1))
12 the use of semicolons needs to be documented once it settles down
13 \times needs documentation with examples somewhere once it works (?)
15 the explanation of how lyrics mode parses words seems ridiculous.
16 Is there a simple way to explain this, or is the behavior
17 too complicated for a reasonable explanation?
21 COMMENT( This document contains Mudela fragments. You need at least
22 Yodl-1.30.18 to convert this to tex or html.
29 htmlbodyopt(bgcolor)(white)
30 htmlcommand(<font color=black>)
33 \setlength{\topmargin}{-0.25in}
34 \setlength{\textheight}{9in}
35 \setlength{\textwidth}{5.875in}
36 \setlength{\oddsidemargin}{0.25in}
37 \setlength{\evensidemargin}{0.25in}
41 whentexinfo(notableofcontents())
43 article(Mudela 1.0.7 / LilyPond 1.0.15 Reference Manual)
44 (Adrian Mariano, Han-Wen Nienhuys and Jan Nieuwenhuizen)
45 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
51 * paragraphs have too much space.
56 latexcommand(\def\interexample{})
57 latexcommand(\def\preexample{\par})
58 latexcommand(\def\postexample{\par\medskip})
59 latexcommand(\def\file#1{{code(#1)}})
61 latexcommand(\def\texttt#1{\tt #1})
62 latexcommand(\def\textbf#1{\bf #1})
65 COMMENT(urg, texinfo include breaks)
67 includefile(html-disclaimer.yo-urg)
70 bf(This document is not up to date). All rendered examples of course
71 are current, but the rest probably isn't. Adjusting the tutorial was
72 considered more important than writing the reference manual. We
73 apologize for the inconvenience. For a complete and up-to-date
74 definition, see file(lily/parser.yy), file(lily/lexer.ll), and the
77 This document describes the the GNU LilyPond input format, which is an
78 effective language for defining music. We call this language (rather
79 arrogantly) The Musical Definition Language or Mudela, for
80 short.footnote(If anybody comes up with a better name, we'd gladly
81 take this. Gourlay already uses Musical Description Language,
82 G-Sharp Score Definition Language. ISO standard 10743 defines a
83 Standard Music Description Language. We're not being original here.)
85 The first aim of Mudela is to define a piece of music, being complete
86 from both from a musical typesetting, as from a musical performing
89 The Musical Definition Language (Mudela), has a logical structure,
90 making use of identifiers, that allows for flexible input, and
91 definition reuse. See the documentation file file(MANIFESTO), included
92 with the LilyPond sources for reasons and design considerations.
95 sect(Running LilyPond)
97 When invoked with a filename that has no extension, LilyPond will try adding
98 a file(.fly) extension first, and a file(.ly) extension second.
99 If the filename ends with
100 file(.fly), LilyPond processes the file as music using
101 file(init.fly). In this case, LilyPond does something
105 \input "yourfile.fly"
110 If you invoke LilyPond with a file file(foo.)var(ext) that doesn't
111 have the file(.ly) extension then LilyPond will look for a file called
112 file(init.)var(ext) and process this file. The file
113 file(init.)var(ext) must contain the code(\maininput) keyword or LilyPond
114 will not read the user specified file.
119 subsect(Basic Mudela)
121 A Mudela file consists of keywords with arguments and identifier
122 assignments separated by spaces, tabs or newlines. Semicolons are
123 used by some keywords but are not generally required. A one line
124 comment is introduced by a code(%) character. Block comments are
125 started by code(%{) and ended by code(%}). They cannot be nested.
127 Mudela supports several types:
132 Formed from an optional minus sign followed by digits. Arithmetic
133 operations cannot be done with integers, and integers cannot be mixed
137 Formed from an optional minus sign and a sequence of digits followed
138 by a emph(required) decimal point and an optional exponent such as
139 code(-1.2e3). Reals can be built up using the usual operations:
140 code(+), code(-), code(*), and code(/), with parentheses for grouping.
143 Begins and ends with the code(") character. To include a code(")
144 character in a string write code(\"). Various other backslash
145 sequences have special interpretations as in the C language. A string
146 that contains no spaces can be written without the quotes. See
147 Section ref(modes) for details on unquoted strings; their
148 interpretation varies depending on the situation. On the right side
149 of identifier assignments and within the code(\header) keyword,
150 strings can be concatenated using the code(+) character.
152 dit(dimension) Consists of a real followed by one of the dimension
153 keywords: code(\mm), code(\pt), code(\in), or code(\cm). Dimensions
154 are converted immediately to a real which gives the dimension in
155 points, so they can be mixed with reals, but the result is no longer
156 of type dimension. The keywords that require a dimension
157 (code(\shape) and code(\symboltables)) will not accept this.
160 A pitch is a string which is the name of a pitch. Example: code(a).
161 The pitch names can be redefined with the code(\notenames) keyword.
162 See Section(notelang) for pitch names in different languages. Pitches
163 can only be specified inside note mode which is specified with
164 code(\notes). Therefore, keywords which require pitch arguments must
165 appear inside code(\notes).
168 Music is a compound type: arbitrarily complicated expressions with a
169 hierarchical structure can be formed from simple building blocks. The
170 simplest expression of type music is a single note. A note is formed
171 from a pitch and an optional duration and must be specified within
172 code(\notes). See Section ref(notedesc) for details. More
173 complicated expressions of type music are formed by surrounding a
174 sequence of expressions of type music with braces code({) and code(})
175 or with angle brackets code(<) and code(>). Items appearing in braces
176 will be treated as serial. Items in angle brackets will be
177 simultaneous. So for example code({ c e g }) represents an arpeggio
178 and code(< c e g >) represents a chord. These items can be nested any
179 way you like. This simple example shows how three chords can be
180 expressed in two different ways:
181 mudela(fragment,verbatim,center)(
182 \notes<{a b c'}{c' d' e'}{e' f' g'}>
183 \notes{<a c' e'><b d' f'><c' e' g'>}
190 Compound types are built up from the simple types. The compound types
191 are: arglist, assignlist and musiclist. An arglist is a
192 white space separated list of integers, reals and or strings surrounded
193 by braces code({) and code(}). An assignlist is a list of
194 identifier assignments, which have the form var(key)code(=)var(value).
195 A statement in Mudela has one of three forms:
196 verb(\keyword argument
197 \keyword argument1 argument2 ... ;
203 Identifiers allow names to be assigned to constants, music, or other
204 Mudela structures. To assign an identifier you use
205 var(name)=var(value) and to refer to an identifier, you preceed its
206 name with a backslash: code(\)var(name). It is legal to redefine an
207 identifier in terms of its old value: code(foo = \foo * 2.0).
208 Identifier assignments must appear at the top level in the Mudela
211 An identifier can be created with any string for its name, but you
212 will only be able to refer to identifiers whose names begin with a
213 letter and are entirely alphanumeric. It is also impossible to refer
214 to an identifier whose name is the same as the name of a keyword. The
215 following words are keywords:
216 verb(absdynamic header musicalpitch remove times
217 accepts in name score translator
218 bar include notenames script transpose
219 cadenza key notes shape type
220 clef keysignature paper skip version
221 cm lyrics partial spandynamic
222 consists maininput penalty symboltables
223 duration mark property table
225 grouping mm relative time)
227 The right hand side of an identifier assignment is parsed completely
228 when the assignment is made. It therefore must have any context
229 specified in the definition. For example, you must write
230 code(foo=\notes{a8 b c}) rather than code(foo={a8 b c}). Even though
231 the context is specified in the definition, you must refer to the
232 identifier inside the correct context:
233 verb(foo = \paper{ linewidth = 6.0\in; }
238 If code(\foo) is used here without the surrounding code(\paper) then
239 an error will result. Note however that the following is acceptible
240 verb(foo = \notes { ... }
242 It is not necessary to specify code(\notes).
244 Identifiers can be set equal to integers, reals, strings, music,
245 durations (specified with code(\duration)), note ornaments (specified
246 with code(\script), dynamics commands, or code(:)), note name tables
247 (specified with code(\notenames), translator definitions, the
248 code(\paper) block, the code(\midi) block or the code(\score) block.
249 When identifiers are used for translators, the code(\paper),
250 code(\midi), and code(\score) blocks, they may only be referred to as
251 the first item in a block. So code(\paper{\one \two}) is illegal
252 because the identifier code(\two) is not the first thing in the block.
253 Unlike other identifier definitions, translator identifier definitions
254 can only appear within code(\midi) or code(\paper) blocks. See
255 Section ref(translators) for more information.
259 subsect(Hierarchical structures)
261 The general structure consists of declarations:
262 verb(IDENTIFIER = \TYPE{
267 verb(\TYPE{ <type specific data> })
269 (Currently, code(\score) is the only type that can be instantiated
272 Most instantiations that use an IDENTIFIER are specified as follows:
274 verb(\TYPE{ \IDENTIFIER [...] })
276 Some exceptions on this rule have been made to prevent inputting
277 Mudela becoming tedious
284 To simplify different aspects of music definition (entering the notes
285 and manipulating them) Mudela has three different input modes which
286 affect how unquoted strings are interpreted.
287 In each mode, words are identified on the input. If code("word") is
288 encountered, it is treated as a string. If code(\word) is
289 encountered it is treated as a keyword or as an identifier. The
290 behavior of the modes differs in two ways: different modes treat
291 unquoted words different, and different modes have different rules for
292 deciding what is a word.
297 At the start of parsing, Mudela is in normal mode.
298 In normal mode, a word is an alphabetic character followed by
299 alphanumeric characters. If code(word) is encountered on the input it
300 is treated as a string.
302 dit(Note mode) Note mode is introduced by the keyword
303 code(\notes). In Note mode, words can only contain alphabetic
304 characters. If code(word) is encountered, LilyPond first checks for a
305 notename of code(word). If no notename is found, then code(word) is
306 treated as a string. If you mistype a notename, the parser will most
307 likely complain that you should be in code(\lyrics) mode to do lyrics.
309 dit(Lyric mode) Lyrics mode is introduced by the keyword
310 code(\lyrics). This mode is has rules that make it easy to include
311 punctuation and diacritical marks in words. A word in Lyrics mode
312 begins with: an alphabetic character, code(_),
313 code(?), code(!), code(:), code('),
314 the control characters code(^A) through code(^F), code(^Q) through
315 code(^W), code(^Y), code(^^), any 8-bit character with ASCII code over
316 127, or a two character combination of a backslash followed by one
317 of code(`), code('), code(") or code(^).
318 Subsequent characters of a word can be any character that is not a
319 digit and not white space. One important consequence of this is that
320 a word can end with code(}), which may be confusing if you thought the
321 code(}) was going to terminate lyrics mode. Any code(_) characters
322 which appear in an unquoted word are converted to spaces, providing a
323 mechanism for introducing spaces into words without using quotes.
324 Quoted words can also be used in lyrics mode to specify words that
325 cannot be specified with the above rules. Here are some examples.
326 Not all of these words are printable by TeX().
327 verb(a&@&@&TSI|{[ % a word
329 1THtrhortho % not a word because it starts with a digit
330 ``Hello'' % not a word because it starts with `
331 Leise DOEXPAND(Fl\)DOEXPAND("u\)ss{}teren meine Sapfe % 4 words
332 _ _ _ _ % 4 words, each one a space
337 These modes are of a lexical nature. Normal and Note mode largely
338 resemble each other, save the possibility of entering Reals,
339 meaning of code(_) and the resolution of words
341 What's this about reals? When can you enter them or not enter them?)
344 sect(Note Description)
347 subsect(Basic Note Specification)
349 A note specification has the form
350 var(pitch)[var(octavespec)][code(!)][code(?)][var(duration)].
351 The pitch of the note is specified by the note's name.
353 LilyPond has predefined note names for various languages. The default
354 names are the Dutch note names. The notes are specified by the
355 letters code(c) through code(b), where code(c) is an octave below
356 middle C and the letters span the ocatave above that C.
357 In Dutch, a sharp is formed by adding
358 code(-is) to the end of a pitch name. A flat is formed by adding code(-es).
359 Double sharps and double flats are obtained by adding code(-isis) or
361 Lily has predefined sets of notenames
362 for various nop(languages). See Section ref(notelang) for details.
363 Rests are specified with the note name code(r) or code(R).
364 There is also a note name code(s) which produces a nonprinting note of the
367 The optional octave specification takes the form of a series of single
369 code(') characters or a series of comma code(,) characters. Each
370 code(') raises the pitch by one octave; each code(,) lowers the pitch
373 mudela(fragment,verbatim,center)(
374 c' d' e' f' g' a' b' c''
377 mudela(fragment,verbatim,center)(
378 cis' dis' eis' fis' gis' ais' bis'
381 mudela(fragment,verbatim,center)(
382 ces' des' es' fes' ges' as' bes'
385 mudela(fragment,verbatim,center)(
386 cisis' eisis' gisis' aisis' beses'
389 mudela(fragment,verbatim,center)(
390 ceses' eses' geses' ases' beses'
393 Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
394 will determine what accidentals to typeset depending on the key and
396 A reminder accidental can be forced by
397 using the optional exclamation mark `code(!)'
399 A cautionary accidental, i.e., an accidental within paranthesis
400 can be obtained using the optional question mark `code(?)' on the pitch.
401 mudela(fragment,verbatim,center)(
402 cis' d' e' cis' c'? d' e' c'!
406 Durations are entered as their reciprocal values
407 mudela(fragment,verbatim,center)(
408 a'1 a'2 a'4 a a'8 a a'16 a'32 a'64
410 mudela(fragment,verbatim,center)(
414 If the duration is omitted then it is set equal to the previous
415 duration. If there is no previous duration, then a quarter note is
417 The duration can be followed by a dot code(.) to obtain dotted note
419 mudela(fragment,verbatim,center)(
423 In addition, the duration can be followed by a multiplier which is
424 introduced with the asterisk code(*) and can be an integer or a
425 fraction. The multiplier changes the duration that LilyPond uses
426 internally for the note, but for notes it
427 does not change the symbol that is printed.
428 mudela(fragment,verbatim,center)(
429 c'4*2 c'4*2 d'8*2/3 d'8*2/3
431 For long rests with durations equal to an integer number of whole notes,
432 LilyPond produces output that indicates the duration of the rest. If you use
433 code(r) then one rest symbol will be printed and several measures left blank.
434 If you use code(R) then all of the measure will be filled with whole rests.
435 If you set the code(Score.SkipBars) property, then only one measure will be
436 printed; with code(R), a number indicating the length of the rest will be
438 mudela(fragment,verbatim,center)(
440 \property Score.SkipBars=1
443 Extra long notes can be obtained using the code(\breve) and
444 code(longa) durations:
445 mudela(fragment,verbatim,center)(
450 subsect(Note Spanners: Beams, Tuplets, Slurs and Ties)
452 A beam is specified by surrounding the beamed notes with brackets
454 mudela(fragment,verbatim,center)(
455 [a'8 a'] [a'16 a' a' a']
458 In order to create triplets, you must use a length multiplier after
459 the brackets. An open bracket code([) followed by a fraction
460 instructs LilyPond to print a number over the beam, and it also
461 starts multiplying all note lengths by the fraction. The closing
462 bracket code(]) should be followed by the fraction code(1/1) in order
463 to restore normal note lengths. To create a triplet without a beam,
464 place a backslace code(\) before the opening and closing brackets.
466 For example, in an ordinary triplet, the notes have duration 2/3 as
468 mudela(fragment,verbatim,center)(
469 [2/3 a'8 a' a' ]1/1 \[2/3 b'4 b' b'\]1/1
472 There is a shorthand that can be used when you
473 want notes lengths multiplied by 2/n.
474 The 2 can be omitted after the open bracket
475 and the first 1 can be omitted after the closing bracket.
476 mudela(fragment,verbatim,center)(
477 [/3 b'8 b' b' ]/1 \[/3 a'4 a'8\]/1
480 COMMENT(This next bit needs to be fixed...or the language needs to be
483 Here is a combination
484 mudela(fragment,verbatim,center)(
485 [/3 a'8 a'16 a'] a'8 \]
488 Another type of spanner is the slur. Slurs connects chords and try to
489 avoid crossing stems. A slur is started with code(CHAR(40)) and stopped with
490 code(CHAR(41)). The starting code(CHAR(40)) appears to the right of the first note
491 in the slur. The terminal code(CHAR(41)) apppears to the left of the first
492 note in the slur. This makes it possible to put a note in slurs from
494 mudela(fragment,verbatim,center)(
495 f'()g'()a' [a'8 b']( a'4 g' )f'
498 A tie connects two adjacent note heads. When used with chords, it
499 connects all of the note heads. Ties are indicated using the tilde symbol
500 code(~) by analogy with TeX()'s tie which connects words. For ties
501 between chords, the input convention is somewhat peculiar. You cannot
502 write code(<c g>~<c g>), but rather must put the tilde after
503 a note within the first chord.
505 mudela(fragment,verbatim,center)(
506 e' ~ e' <c'~ e' g'><c' e' g'>
510 subsect(Note Ornaments)
512 A variety of symbols can appear above and below notes to indicate
513 different characteristics of the performance.
515 added to a note with `var(note)code(-\)var(name)'. Numerous different
516 symbols are defined in file(script.ly). Each symbol is defined using
517 the code(\script) keyword which specifies where symbols appear.
518 Symbols can be forced to appear above the note by writing
519 `var(note)code(^\)var(name)', and they can be forced to appear below
520 by writing `var(note)code(_\)var(name)'. Here is a chart showing
521 symbols above notes, with the name of the corresponding symbol
522 appearing underneath.
526 < \notes{ c''-\accent c''-\marcato c''-\staccatissimo f'-\fermata
527 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow c''-\downbow
528 c''-\lheel c''-\rheel c''-\ltoe c''-\rtoe c''-\turn
529 c''-\open c''-\flageolet c''-\reverseturn
531 c''-\prall c''-\mordent c''-\prallprall c''-\prallmordent
532 c''-\upprall c''-\downprall }
533 \type Lyrics \lyrics{
534 accent marcato staccatissimo fermata stopped
535 staccato tenuto upbow downbow lheel rheel ltoe rtoe turn
536 open flageolet reverseturn
538 mordent prallprall prallmordent uprall downprall }>
539 \paper{linewidth = 5.875\in;
545 COMMENT( The following are defined in script.ly but do not work:
547 portato lbheel rbheel lbtoe rbtoe lfheel rfheel lftoe rftoe )
549 In addition, it is possible to place arbitrary strings of text or
550 TeX() above or below notes by using a string instead of an identifier:
551 `code(c^"text")'. Fingerings can be placed by simply using digits.
552 All of these note ornaments appear in the printed output but have no
553 effect on the MIDI rendering of the music.
555 To save typing, a few common symbols can be abbreviated with
559 \property Voice.textstyle = typewriter
565 c''4-^_"c-\\^{ }" s4 }
566 \paper { linewidth = 12.\cm; }})
568 Dynamic marks are specified by using an identifier after a note
569 without a dash: code(c4 \ff). Note that this syntax is inconsistent
570 with the syntax for other types of ornaments. The available dynamic
571 marks are: code(\ppp), code(\pp), code(\p), code(\mp), code(\mf),
572 code(\f), code(\ff), code(\fff), code(\fp), code(sf), and code(\sfz).
574 A crescendo mark is started with code(\cr) and terminated with
575 code(\rc). A decrescendo mark is started with code(\decr) and
576 terminated with code(\rced). There are also shorthands for these
577 marks. A crescendo can be started with code(\<) and a decrescendo can
578 be started with code(\>). Either one can be terminated with code(\!).
580 Tremolo marks can be printed by a note by adding code(:)[var(length)]
581 after the note. The length must be at least 8. A var(length) value
582 of 8 gives one line across the note stem.
583 If the length is omitted,
584 then the last value is used, or the value of the code(Abbrev)
585 property if there was no last value. To place tremolo marks in
586 between two notes, begin with code([:)var(length) and end with code(]).
587 The tremolo marks will appear instead of beams. Putting more than two
588 notes in such a construction will produce odd effects.
589 mudela(fragment,verbatim,center)(
590 c'2:8 c':32 [:16 e'1 g'] [:8 e'4 f']
594 Is the last paragraph correct? Is it called "tremolo"? Why is
595 "abbreviation" used? (What is the unabreviated form?)
598 mudela(fragment,verbatim,center)(
605 sect(Other Ways to Enter Pitches)
607 subsect(Pitch Names in Other Languages)
610 The pitch names can be easily redefined using the code(\notenames) command.
611 Note name definitions have been provided in various languages.
612 Simply include the language specific init file. For example:
613 code(\include "english.ly"). The available language files and the names
616 verb( Note Names sharp flat
617 nederlands.ly c d e f g a bes b -is -es
618 english.ly c d e f g a bf b -s/-sharp -f/-flat
619 deutsch.ly c d e f g a b h -is -es
620 norsk.ly c d e f g a b h -iss/-is -ess/-es
621 svenska.ly c d e f g a b h -iss -ess
622 italiano.ly do re mi fa sol la sid si -d -b)
624 subsect(Relative Pitch Specification)
627 One very common error when entering music is to place notes in the wrong
628 octave. One way to avoid being confused by large numbers of octave changing
630 the code(\relative) keyword.
631 Music which appears within code(\relative) is
632 interpreted differently. The octave of a note is determined by making it as
633 close to the previous note as possible. The octave changing marks code(') and
634 code(,) can then be added to raise or lower this note by octaves. You have to
635 specify a starting pitch because the first note of a list has no predecessor.
637 mudela(fragment,verbatim,center)(
638 \relative c'' { c d b c, d b c' d
642 When the preceeding item is a chord, the first note of the chord is used to
643 determine the first note of the next chord. But other notes within the second
644 chord are determined by looking at the immediately preceeding note.
646 mudela(fragment,verbatim,center)(
647 \relative c' { <c e g>
651 The code(\relative) keyword can only appear in music, so there must be a
652 surrounding code(\notes) keyword which does not appear in the fragments shown
653 above. Also note that if the music passed to a code(\relative) keyword
654 contains a code(\transpose) keyword, the tranposed music will not be
655 processed in relative mode. An additional code(\relative) must be placed
656 inside the code(\transpose).
659 subsect(Tranposition of Pitches)
662 Another way to modify the meaning of the note names is to use the
663 code(\transpose) keyword. This keyword allows you to transpose music.
664 To use transposition, specify the pitch that middle C should be tranposed to.
665 It is important to distinguish between enharmonic pitches as they can produce
666 different transpositions. To transpose up half a step, for example, either
667 code(\transpose cis') or code(\transpose des') will work. But the first
668 version will print sharps and the second version will print flats.
669 In this example, a scale in the key of E is transposed to F, or to E-sharp
671 mudela(fragment,verbatim,center)(
672 \relative c' { \key e;
673 e fis gis a b cis dis e }
675 mudela(fragment,verbatim,center)(
676 \transpose des' \relative c' { \key e;
677 e fis gis a b cis dis e }
679 mudela(fragment,verbatim,center)(
680 \transpose cis' \relative c' { \key e;
681 e fis gis a b cis dis e }
683 If you want to use both code(\transpose) and code(\relative), then you must use
684 code(\transpose) first. Any code(\relative) keywords that are outside the
685 code(\transpose) have no effect on notes that appear inside the
690 Lyrics are entered like notes, with pitches replaced
691 by text. For example code(Twin-4 kle4 twin-4 kle4) enters four
692 syllables, each with quarter note duration. Note that the hyphen has
693 no special meaning for lyrics, and does not introduce special symbols.
694 See Section ref(modes) for a description of what is interpreted as a lyric.
696 In order to instruct LilyPond to write lyrics underneath the
697 staff, you must enter the lyrics context with code(\type Lyrics).
698 Lyrics should be entered in lyrics mode which is entered with code(\lyrics).
700 Spaces can be introduced into a lyric either by using quotes (code("))
701 or by using an underscore without quotes: code(He_could4 not4). All
702 unquoted underscores are converted to spaces. Here is a full example:
703 mudela(verbatim)(\score{
704 < \notes \transpose c'' {c d e c | c d e c | e f g'2 |
705 e'4 f g'2 \bar "|."; }
706 \type Lyrics \lyrics {
707 DOEXPAND(Fr\)`e-4 re Ja- que DOEXPAND(Fr\)`e- re Ja- que
708 Dor- mez vous?2 Dor-4 mez vous?2 }
716 Why does this warrant an URG?
722 sect(Chords and Voices)
724 Here's a simple chord
725 mudela(fragment,verbatim,center)(
730 mudela(fragment,verbatim,center)(
739 mudela(fragment,verbatim)(
741 { \voiceone c'4 g' c' g' }
750 LilyPond aligns all musical objects according to the amount of time
751 they occupy. All of these objects have a duration. When music is
752 written sequentially using braces the duration is the sum of the
753 durations of the elements. When music is stacked into simultaneous music
755 brackets, the duration is the maximum of the durations of the
758 Because LilyPond knows the durations of all musical elements, the time
759 signature enables LilyPond to draw bar lines automatically. The time
760 signature is specified with the code(\time) keyword: code(\time 3/4).
761 If no time signature is given, LilyPond assumes 4/4. The automatic
762 generation of bar lines can toggled with the code(\cadenza) keyword,
763 and an incomplete measure at the start of the music can be created
764 using the code(\partial) keyword: code(\partial 8*2;) creates a
765 starting measure lasting two eighth notes.
767 In order to help with error checking, you can insert bar markers in
768 your music by typing code(|). Whenever LilyPond encounters a code(|)
769 that doesn't fall at a measure boundary, she prints a warning message.
771 Rhythmic grouping is a concept closely associated with this.
772 A default grouping is selected for the chosen time signature.
773 The default consists of combinations of 2 and 3 beats with as many
774 groups of 3 as possible, and the groups of 3 coming first. For
775 example, 4/4 is divided into 2+2 and 8/8 is divided into 3+3+2. This
776 default grouping can be changed using the \grouping keyword which
777 takes a list of durations to specify the grouping.
781 sect(Composition: forming bigger structures)
784 The computer savy user may be interested in a more formal
785 specification. We can capture what have learned about forming
786 sentences in Mudela in a context-free grammar.
788 latexcommand(\smallskip)
791 row(cell(em(Music))cell(: em(Note)))
792 row(cell()cell(code(|) em(Rest)))
793 row(cell()cell(code(|) code({) em(MusicList) code(})))
794 row(cell()cell(code(|) code(<) em(MusicList) code(>)))
795 row(cell()cell(code(|) em(Command)))
796 row(cell()cell(code(|) code(\type) em(string) code(=) em(string) em(Music)))
798 row(cell(em(MusicList))cell(: em(empty)))
799 row(cell()cell(code(|) em(MusicList) em(Music)))
803 latexcommand(\smallskip)
805 In mathematics you can form expressions by combining expressions,
806 which are ultimately some kind of atom or terminal symbol. The same
807 goes for Mudela: there are some basic building blocks, and by
808 combining those you create complex music.
810 You can combine music in three ways:
812 it()If you enclose a sequence of music-elements in braces ( code({)
813 and code(}) ), then you form another kind of music called
816 The duration of sequential composition is the sum of the durations of its elements
818 { c c g g a a g2 } % twinkle twinkle
819 { { c c g g} { a a g2 } }
821 it()You can stack music by enclosing a sequence of music elements
822 with code(<) and code(>). This is called simultaneous music.
823 The duration of a simultaneous composition is the maximum of the durations
824 of its elements Example:
826 <a4 {cis8 cis8} e'4> % a-major chord
828 it()You can form music by transposing music:
831 d % from c to the d that's almost one octave down
832 { e4 f4 } % the horizontal music
836 it()verb(\translator)
840 Of course you can also combine these three mechanisms.
842 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
850 Keywords sometimes appear alone, but usually they require arguments.
851 A keyword may have a single argument, a sequence of arguments in
852 braces, or a sequence of arguments separated by spaces and terminated
853 by a semicolon. The precise syntax of each keyword is shown below.
854 Keywords must appear in the right context. If you use a keyword in
855 the wrong place, even if the usage is syntactically correct, you will
856 get the message ``parse error'' from LilyPond.
861 dit(code(\absdynamic) code({) var(code) code(})) Internal keyword for
862 printing dynamic marks such as $f$ under music. The parameter
863 var(code) is unsigned and specifies the dynamic mark to print.
864 Normally you should use the more user friendly abbreviations defined
865 in the init file file(dynamic.ly).
867 dit(code(\accepts) var(string)code(;)) This keyword can appear only within a
868 code(\translator) block. It specifies what contexts are allowed with the
869 context that is being defined. See Section ref(translators).
871 dit(code(\bar) var(bartype)code(;)) Prints a special bar symbol, or at
872 measure boundaries, replaces the regular bar symbol with a special
873 symbol. The argument var(bartype) is a string which specifies the
874 kind of bar to print. Options are code(":|"), code("|:"),
875 code(":|:"), code("||"), code("|."), code(".|"), or code(".|.").
876 These produce respectively a right repeat, a left repeat, a double
877 repeat, a double bar, a start bar, an end bar, or a thick double bar.
878 If var(bartype) is set to code("empty") then nothing is printed, but a
879 line break is allowed at that spot. Note that the printing of special bars
880 has no effect on the MIDI output.
882 dit(code(\cadenza) var(togglevalue)code(;)) Toggles the automatic generation
883 of bar lines. If var(togglevalue) is 0 then bar line generation is
884 turne off. If var(togglevalue) is 1 then a bar is immediately
885 printed and bar generation is turned on.
887 dit(code(\clef) var(clefname)code(;)) Allowed only in music.
888 Sets the current clef. The argument is
889 a string which specifies the name of the clef. Several clef names are
890 supported. If code(_8) or code(^8) is added to the end of a clef
891 name then the clef lowered or raised an octave will be generated.
892 Here are the supported clef names with middle C shown in each clef:
896 %\property Voice.textstyle = typewriter
897 \clef subbass; c'4-"\kern-10mm subbass"
898 \clef bass; c'4^"\kern -8mm bass"
899 \clef baritone; c'4_"\kern -10mm baritone"
900 \clef varbaritone; c'4^"\kern -10mm varbaritone"
901 \clef tenor; c'4_"\kern -10mm tenor"
902 \clef "G_8"; c'4^"\kern -6mm G\_8" }
903 \paper{ linewidth= 4.5 \in; }
908 \notes{\cadenza 1; \clef alto; c'4_"\kern -10mm alto"
909 \clef mezzosoprano; c'4^"\kern -10mm mezzosoprano"
910 \clef soprano; c'4_"\kern -10mm soprano"
911 \clef treble; c'4^"\kern -6mm treble"
912 \clef french; c'4_"\kern -10mm french" }
913 \paper{ linewidth= 4.5 \in; }
916 The treble clef can also be obtained using the names code(G) or
917 code(violin). The bass clef is also available by code(\clef F).
919 dit(code(\cm)) Specify a dimension in centimeters.
921 dit(code(\consists) var(string)code(;)) This keyword can appear only within a
922 code(\translator) block. It specifies that an engraver or performer named
923 var(string) should be added to the translator. See Section
926 dit(code(\duration) code({) var(length) var(dotcount) code(})) Specify note
927 duration. The parameter var(length) is the negative logarithm (base
928 2) of duration: 1 is a half note, 2 is a quarter note, 3 is an eighth
929 note, etc. The number of dots after the note is given by
932 dit(code(\font) var(string)) Internal keyword. Used within
933 code(\symboltables) to specify the font.
935 dit(code(\grouping) var(durationseq)code(;)) Sets the metric structure of
936 the measure. Each argument specifies the duration of one metric unit.
937 For example, code(\duration 16*5;) specifies a grouping of five beats
938 together in 5/16 time. The default grouping is to have as many groups
939 of 3 as possible followed by groups of two.
941 dit(code(\header) code({) var(key1) = var(val1); var(key2) = var(val2); ... code(}))
942 Specifies information about the music. A header should appear at the
943 top of the file describing the file's contents. If a file has
944 multiple code(\score) blocks, then a header should appear in
945 each score block describing its contents. Tools like code(ly2dvi) can
946 use this information for generating titles. Some possible key values
947 are: title, opus, description, composer, enteredby, and copyright.
949 dit(code(\in)) Specify a dimension in inches.
951 dit(code(\include) var(file)) Include the specified file. The
952 argument var(file) is a string. The full filename including the
953 file(.ly) extension must be given, and the filename must be quoted.
954 (An unquoted string will not work here.)
956 dit(code(\key) var(pitch) var(type) code(;)) Change the key signature.
957 var(type) should be code(\major) or code(\minor) to get
958 var(pitch)-major or var(pitch)-minor, respectively. The second
959 argument is optional, the default is major keys.
960 The var(\type) argument can also be given as an integer, which tells
961 the number of semitones that should be added to the pitch given in the
962 subsequent code(\key) commands to get the corresponding major key,
963 e.g. code(\minor) is defined as 3.
965 dit(code(\keysignature) var(pitchseq)code(;))
966 Specify an arbitrary key signature. The pitches from var(pitch) will
967 be printed in the key signature in the order that they appear on the list.
969 dit(code(\lyrics) var(lyriclist)) Parse var(lyriclist) in lyrics mode.
971 dit(code(\maininput)) Internal command. This command is used for creating init
972 files like file(init.fly) that read the user file into the middle of another
973 file. Using it in a user file will lead to an infinite loop.
975 dit(code(\mark) var(unsigned)code(;) or code(\mark) var(string)code(;))
976 Allowed in music only. Prints a mark over or under (?) the staff.
977 You must add code(Mark_engraver) to the Score context and it only
978 seems to work if the mark appears at the beginning of a line.
980 dit(code(\midi) var(statementlist)) Appears in a score block to
981 indicate that musical output should be produced and to set output
982 parameters. Can also appear at the top level to set default output
983 parameters. See code(\tempo).
985 dit(code(\mm)) Specify a dimension in millimeters.
987 dit(code(\musicalpitch) code({) var(octave) var(note) var(shift) code(}))
988 Specify note pitch. The octave is specified by an integer,
989 zero for the octave containing middle C. The note is a number from 0
990 to 7, with 0 corresponding to C and 7 corresponding to B. The shift
991 is zero for a natural, negative to add flats, or positive to add
994 dit(code(\name) var(context)code(;)) Appears within code(\translator) to
995 specify the name of the context that the translator handles. See Section
998 dit(code(\notenames) var(assignmentlist)) Define new note names. This
999 keyword can appear only at the top level.
1000 The argument is a list of definitions of the form
1001 var(name) = var(pitch), where var(pitch) is specified with the
1002 code(\musicalpitch) keyword.
1004 dit(code(\notes) var(music)) Enter note mode and process the
1007 dit(code(\)code(output) var(string)code(;)) Generate a parse error.
1009 dit(code(\paper) var(statmentlist))
1010 Appears in a score block to indicate that the music should be printed
1011 or to set output parameters. Can also appear at the top level to set
1012 default output parameters for all of the score blocks.
1013 The var(statmentlist) contains statements that change features of the
1014 output. See Section ref(paper).
1016 dit(code(\partial) var(duration)code(;)) Specify that the first measure of
1017 the music lasts only for the specified duration.
1019 dit(code(\penalty) code(=) var(int)code(;)) Allowed only in music.
1020 Discourage or encourage line breaks. See identifiers code(\break) and
1021 code(\nobreak) in Section ref(ident).
1023 dit(code(\property) var(contextname)code(.)var(propname) code(=) var(value))
1024 Sets the var(propname) property of the context var(contextname) to the
1025 specified var(value). All three arguments are strings. Depending on
1026 the context it may be necessary to quote the strings or to leave space
1027 on both sides of the dot.
1029 dit(code(\pt)) Specify a dimension in points.
1031 dit(code(\relative) var(pitch) var(music)) Processes the specified
1032 var(music) in relative pitch
1033 mode. In this mode, the octave of a pitch is chosen so that the
1034 pitch is closest to the preceeding pitch.
1035 The argument var(pitch) is
1036 the starting pitch for this comparision. In the case of chords, the
1037 first note of a chord is used as the base for the first pitches in the next
1038 chord. See Section ref(relative).
1040 dit(code(\remove) var(string)code(;)) Can appear only in a
1041 code(\translator) block. Specifies that a performer or engraver named
1042 var(string) should be removed. See Section ref(translators).
1044 dit(code(\score) var(statementlist)) Create a Score context. This
1045 is the top level notation context.
1046 COMMENT(this still needs work)
1048 dit(code(\script) code({) var(name) var(instaff) var(withstem)
1049 var(location) var(invertible) var(priority) code(})) This keyword is
1050 used the initialization file(script.ly) to define the various symbols
1051 that can appear above and below notes. The first argument is the name
1052 of the symbol. The second argument var(instaff) is 1 if the symbol
1053 follows the notehead into the staff and 0 if the symbol stays above or
1054 below the staff lines. The third parameter var(withstem) is 0 if the
1055 symbol's placement does not depend on the stem direction; it is 1 if
1056 the symbol should be at the stem end of the note and it is -1 if the
1057 symbol should be at the note head end of the note. The argument
1058 var(location) is set to 1 for symbols that always appear above the
1059 staff; it is -1 for symbols that appear below the staff. If
1060 var(invertible) is set to 1 then the symbol can be inverted; otherwise
1061 it cannot. The last argument var(priority) sets a priority for the
1062 order of placement of several symbols on a single note.
1064 dit(code(\shape) code(=) var(indent1) var(width1) var(indent2)
1065 var(width2) ... code(;)) Allowed only within code(\paper). Each pair
1066 of var(indent) and var(width) values is a dimension specifying how far
1067 to indent and how wide to make the line. The indentation and width of
1068 successive lines are specified by the successive pairs of dimensions.
1069 The last pair of dimensions will define the characeristics of all
1070 lines beyond those explicitly specified.
1072 COMMENT(First pair of dimensions seems to be skipped. At least it is
1073 in the example file denneboom.ly.)
1075 dit(code(\skip) var(duration)code(;)) Skips the amount of time specified by
1076 var(duration). A gap will be left for the skipped time with no notes
1077 printed. It works in Note Mode or Lyrics Mode (but generates a
1078 mysterious error in lyrics).
1080 dit(code(\spandynamic) code({) var(kind) var(toggle) code(})) Internal
1081 keyword for crescendo and decrescendo symbols. The first parameter
1082 var(kind) is set to 1 for a crescendo and -1 for a decrescendo. The
1083 second parameter is set to 1 to start the mark and 2 to stop it.
1084 Users should use the abbreviations which are defined in the
1085 initialization file file(dynamic.ly).
1087 dit(code(\symboltables)) Internal keyword. Used to create symbol
1088 tables. See initialization files file(paper*.ly), file(feta*.ly), and
1091 dit(code(\table)) Internal keyword. Used within code(\symboltables)
1092 to specify the tables. See initialization files.
1094 dit(code(\tempo) var(duration) = var(perminute)code(;)) Used within
1095 code(\midi) or within music to specify the tempo. For example,
1096 `code(\midi { \tempo 4 = 76;})' requests output with 76 quarter notes
1097 per minute. Note that if the music contains several tempo commands,
1098 only the last one is used to set the tempo for the entire MIDI output.
1099 COMMENT(Is this true?)
1101 dit(code(\time) var(numerator)code(/)var(denominator)code(;)) Change the time
1102 signature. The default time signature is 4/4.
1104 dit(code(\times) var(numerator)code(/)var(denominator) var(music))
1105 Multiply the duration of var(music) by the specified fraction.
1107 dit(code(\translator) var(statements) or code(\translator)
1108 var(context) = var(name)) The first variant appears only within
1109 code(\paper) and specifies a translator for
1110 converting music to notation. The translator is specified with a
1111 single code(\type) statement and a series of code(\accepts), and
1112 code(\consists) statements. See Section ref(translators).
1113 The second variant appears in
1114 music. It specifies that the current the contexts
1115 contained within the specified context should be shifted to the
1116 context with the specified name.
1118 COMMENT( \translator seems like a strange name for the second
1119 operation, and is the overloading desireable? )
1121 dit(code(\transpose) var(pitch) var(music)) Transposes the specified
1122 music. Middle C is tranposed to var(pitch). This is allowed in music only,
1123 and if it appears inside code(\relative), then any notes specified for
1124 transposition should be specified inside another code(\relative). See Section
1127 dit(code(\type) var(contexttype) [code(=) var(contextname)]
1128 var(music) or code(\type) var(translatortype)code(;)) The first
1129 variant is used only within music to create an instance of a
1130 context. The new context can optionally be given a name. The
1131 specified var(music) is processed in the new context. The second
1132 variant appears within a code(\translator) block and specifies the
1133 type of translator being created.
1135 dit(code(\version) var(string)) Specify the version of Mudela that a
1136 file was written for. The argument is the version number, for example
1137 code("1.0.1"). Note that the Mudela version is different from the
1143 sect(Notation Contexts)
1145 Notation contexts provide information that appears in printed music
1146 but not in the music itself. A new musical context is created using
1147 the code(\type) keyword: `code(\type) var(contexttype) [code(=)
1148 var(contextname)] var(music)'. The following context types are
1153 dit(code(LyricVoice)) Corresponds to a voice with lyrics. Handles the printing
1154 of a single line of lyrics.
1156 dit(code(Voice)) Corresponds to a voice on a staff.
1157 This context handles the conversion of noteheads,
1158 dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests.
1160 dit(code(Lyrics)) Typesets lyrics. It can contain code(LyricVoice) contexts.
1162 dit(code(Staff)) Handles clefs, bar lines, keys,
1163 accidentals. It can contain code(Voice) contexts.
1165 dit(code(RhythmicStaff)) A context like code(Staff) but for printing
1166 rhythms. Pitches are ignored; the notes are printed on one line.
1167 It can contain code(Voice) contexts.
1169 dit(code(GrandStaff)) Contains code(Staff) or code(RhythmicStaff)
1170 contexts. It adds a brace on the left side grouping the staffs
1171 together. The bar lines of the contained staffs are connected vertically.
1172 It can contain code(Staff) contexts.
1174 dit(code(StaffGroup)) Contains code(Staff) or code(RhythmicStaff)
1175 contexsts. Adds a bracket on the left side, grouping the staffs
1176 together. The bar lines of the contained staffs are connected vertically.
1177 It can contain code(Staff), code(RhythmicStaff), code(GrandStaff) or code(Lyrics) contexts.
1179 dit(code(ChoirStaff)) Identical to code(StaffGroup) except that the
1180 contained staffs are not connected vertically.
1182 dit(code(Score)) This is the top level notation context. It is specified with
1183 the code(\score) keyword rather than the code(\type) command. No
1184 other context can contain a code(Score) context. This context handles
1185 the administration of time signatures. It also makes sure that items
1186 such as clefs, time signatures, and key-signatures are aligned across
1187 staffs. It can contain code(Lyrics), code(Staff),
1188 code(RhythmicStaff), code(GrandStaff), code(StaffGroup), and
1189 code(ChoirStaff) contexts.
1193 The various contexts have properties associated with them. These
1194 properties can be changed using the code(\property) command:
1195 `code(\property) var(context)code(.)var(propname) code(=) var(value)'.
1196 Properties can also be set within the code(\translator) block
1197 corresponding to the appropriate context. In this case, they are
1198 assigned by `var(propname) code(=) var(value)'. The settings made with
1199 code(\property) are processed after settings made in the code(\translator)
1200 block, so the code(\property) settings will override code(\translator)
1203 The code(\property) keyword will create any property you specify.
1204 There is no guarantee that a property will actually be used. If you
1205 spell a property name wrong, there will be no error message. In order to find
1206 out what properties are used, you must search the source code
1207 for code(get_property).
1208 Properties that are set in one context are inherited by all of the
1209 contained contexts. This means that a property valid for the Voice
1210 context can be set in the Score context (for example) and thus take
1211 effect in all Voice contexts.
1213 subsubsubsect(Lyrics properties)
1217 dit(code(textstyle)) Set the font for lyrics. The available font
1218 choices are code(roman), code(italic), code(bold), code(large),
1219 code(Large), code(typewriter), and code(finger). The code(finger)
1220 font can only display numbers. Note also that you must be careful
1221 when using code(\property) in Lyrics mode. Because of the way strings
1222 are parsed, either put quotes around the arguments to code(\property)
1223 or be sure to leave a space on both sides of the dot.
1225 dit(code(textalignment)) Controls alignment of lyrics. Set to code(\left)
1226 to align the left end of the lyric with the note; set to code(\right) to
1227 align the right end of the lyric with the note. Set to code(\center) to
1228 align the center of the lyric with the note.
1232 subsubsubsect(Voice properties)
1236 dit(code("midi_instrument")) Sets the instrument for MIDI output. This
1237 property name must be quoted because of the embedded underscore. If
1238 this property is not set then LilyPond will use the code(instrument)
1239 property. This must be set to one of the strings on the list of MIDI
1240 instruments that appears in Section ref(midilist). If you use a
1241 string which is not listed, LilyPond will silently substitute piano.
1243 dit(code(transposing)) Tranpose the MIDI output. Set this property to
1244 the number of half-steps to transpose by.
1246 dit(code(ydirection)) Determines the direction of stems, subscripts,
1247 beams, slurs, and ties. Set to code(\down) to force them down,
1248 code(\up) to force them up, or code(\free) to let LilyPond decide.
1249 This can be used to distinguish between voices on the same staff. The
1250 code(\stemdown), code(\stemup), and code(\stemboth) identifiers set
1251 this property. See also the identifiers code(\voiceone),
1252 code(\voicetwo), code(\voicethree) and code(\voicefour).
1254 dit(code(slurydirection)) Set to code(\free) for free choice of slur
1255 direction, set to code(\up) to force slurs up, set to code(\down) to
1256 force slurs down. The shorthands code(\slurup), code(\slurdown), and
1257 code(\slurboth) are available.
1259 dit(code(slurdash)) Set to 0 for normal slurs, 1 for dotted slurs, and
1260 a larger value for dashed slurs. Identifiers code(\slurnormal) and
1261 code(\slurdotted) are predefined to set the first two settings.
1263 dit(code(hshift)) Set to 1 to enable LilyPond to shift notes
1264 horizontally if they collide with other notes. This is useful when
1265 typesetting many voices on one staff. The identifier code(\shift) is
1266 defined to enable this.
1268 dit(code(dynamicdir)) Determines location of dynamic marks. Set to
1269 code(\up) to print marks above the staff; set to code(\down) to print
1270 marks below the staff.
1272 dit(code(textalignment)) Controls alignment of superscripted and
1273 subscripted text. Set to \left to align the left end of the text with
1274 the note; set to \right to align the right end of the text with the
1275 note. Set to \center to align the center of the text with the note.
1277 dit(code(textstyle)) Set the text style for superscripts and
1278 subscripts. See above for list of text styles.
1280 dit(code(fontsize)) Can be used to select smaller font sizes for
1281 music. The normal font size is 0, and the two smaller sizes are -1
1284 dit(code(pletvisibility)) Determines whether tuplets of notes are
1285 labelled. Setting to 0 shows nothing; setting to 1 shows a number;
1286 setting to 2 shows a number and a bracket if there is no beam; setting
1287 to 3 shows a number, and if there is no beam it adds a bracket;
1288 setting to 4 shows both a number and a bracket unconditionally.
1292 subsubsubsect(Staff properties)
1296 dit(code(defaultClef)) Determines the default clef. See code(\clef)
1299 dit(code(nolines)) Sets the number of lines that the staff has.
1301 dit(code(barAlways)) If set to 1 a bar line is drawn after each note.
1303 dit(code(defaultBarType)) Sets the default type of bar line. See
1306 dit(code(keyoctaviation)) If set to 1, then keys are the same in all
1307 octaves. If set to 0 then the key signature for different octaves can
1308 be different and is specified independently: code(\keysignature bes
1309 fis'). The default value is 1. Can be set to zero with
1310 code(\specialkey) or reset to 1 with code(\normalkey).
1312 dit(code(instrument) and code(instr)) If code(Staff_margin_engraver)
1313 is added to the Staff translator, then the code(instrument) property
1314 is used to label the first line of the staff and the code(instr)
1315 property is used to label subsequent lines. If the
1316 code(midi_instrument) property is not set then code(instrument) is
1317 used to determine the instrument for MIDI output.
1318 COMMENT(This prints the instrument name on top of the staff lines.)
1320 dit(code(abbrev)) Set length for tremolo to be used if no length is
1321 explicitly specified.
1323 dit(code(createKeyOnClefChange)) Set to a nonempty string if you want key
1324 signatures to be printed when the clef changes. Set to the empty string (the
1325 default) if you do not want key signatures printed.
1328 dit(code(timeSignatureStyle)) Changes the default two-digit layout
1329 for time signatures. The following values are recognized:
1331 dit(code(C)) 4/4 and 2/2 are typeset as C and struck C,
1332 respectively. All other time signatures are written with two digits.
1333 dit(code(old)) 2/2, 3/2, 3/4, 4/4, 6/4 and 9/4 are typeset with
1334 old-style mensuration marks. All other time signatures are
1335 written with two digits.
1336 dit(code(1)) All time signatures are typeset with a single
1337 digit, e.g. 3/2 is written as 3.
1338 dit(code(C2/2), code(C4/4), code(old2/2), code(old3/2),
1339 code(old3/4), code(old4/4), code(old6/4) or
1340 code(old9/4)) Tells Lilypond to use a specific symbol as time
1343 The different time signature characters are shown below with
1345 mudela(fragment,center)(
1347 \property Voice.textstyle = typewriter
1348 \property Staff.timeSignatureStyle = "C2/2"
1349 \time 2/2; a2^"C2/2" a2
1350 \property Staff.timeSignatureStyle = "C4/4"
1351 \time 2/2; a2^"C4/4" a2
1352 \property Staff.timeSignatureStyle = "old2/2"
1353 \time 2/2; a2^"old2/2" a2
1354 \property Staff.timeSignatureStyle = "old3/2"
1355 \time 2/2; a2^"old3/2" a2
1356 \property Staff.timeSignatureStyle = "old4/4"
1357 \time 2/2; a2^"old4/4" a2
1358 \property Staff.timeSignatureStyle = "old6/4"
1359 \time 2/2; a2^"old6/4" a2
1360 \property Staff.timeSignatureStyle = "old9/4"
1361 \time 2/2; a2^"old9/4" a2
1370 subsubsubsect(GrandStaff properties)
1374 dit(code(maxVerticalAlign)) Set the maximum vertical distance between
1377 dit(code(minVerticalAlign)) Set the minimum vertical distance between
1382 subsubsubsect(Score properties)
1386 dit(code(SkipBars)) Set to 1 to skip the empty bars that are produced
1387 by multimeasure notes and rests. These bars will not appear on the
1388 printed output. Set to zero (the default) to expand multimeasure
1389 notes and rests into their full length, printing the appropriate
1390 number of empty bars so that synrchonization with other voices is
1391 preserved. COMMENT(meaning of "skip" here seems to be different from
1392 the meaning used for the keyword \skip.)
1394 dit(code(beamquantisation)) Set to code(\none) for no quantization.
1395 Set to code(\normal) to quantize position and slope. Set to
1396 code(\traditional) to avoid wedges. These three settings are
1397 available via code(\beamposfree), code(\beamposnormal), and
1398 code(\beampostraditional).
1400 dit(code(beamslopedamping)) Set to code(\none) for undamped beams.
1401 Set to code(\normal) for damped beams. Set to code(\infinity) for
1402 beams with zero slope. The identifiers code(\beamslopeproportional),
1403 code(\beamslopedamped), and code(\beamslopezero) each set the
1404 corresponding value.
1413 bar-number-engraver.cc: "barScriptPadding" vertical space for numbers
1414 mark-engraver.cc: "markScriptPadding" vertical space for marks
1415 span-bar-engraver.cc: "singleStaffBracket" do single staffs get a bracket?
1416 bar-column-engraver.cc: "barColumnPriority"
1417 bar-number-engraver.cc: "barNumberBreakPriority" Control horizontal ordering
1418 mark-engraver.cc: "markBreakPriority" of bars, clefs, keysig
1419 staff-margin-engraver.cc:"marginBreakPriority" etc. Slated for revision
1422 sect(Pre-defined Identifiers)
1425 Various identifiers are defined in the initialization files to
1426 provide shorthands for some settings.
1429 dit(code(\break)) Force a line break in music by using a large
1430 argument for the keyword code(\penalty).
1431 dit(code(\center)) Used for setting textalignment property. Is set to 0.
1432 dit(code(\cr)) Start a crescendo.
1433 dit(code(\decr)) Start a decrescendo.
1434 dit(code(\down)) Used for setting direction setting properties. Is
1436 dit(code(\f)) Print forte symbol on the preceeding note.
1437 dit(code(\ff)) Print fortissimo symbol on the preceeding note.
1438 dit(code(\fff)) Print fortississimo symbol on preceeding note.
1439 dit(code(\fp)) Print fortepiano symbol on preceeding note.
1440 dit(code(\free)) Used for setting direction setting properties. Is
1442 dit(code(\Gourlay)) Used for setting the paper variable
1443 code(castingalgorithm). Is equal to 1.0.
1444 dit(code(\infinity)) Used for setting the Score.beamslopedamping
1445 property. Is actually equal to 10000.
1446 dit(code(\left)) Used for setting textalignment property. Is equal to -1.
1447 dit(code(\major)) Used as the second argument of the code(\key)
1448 command to get a major key.
1449 dit(code(\minor)) Used as the second argument of the code(\key)
1450 command to get a minor key.
1451 dit(code(\mf)) Print mezzoforte symbol on preceeding note.
1452 dit(code(\mp)) Print mezzopiano symbol on preceeding note.
1453 dit(code(\nobreak)) Prevent a line break in music by using a large
1454 negative argument for the keyword code(\penalty).
1455 dit(code(\none)) Used for setting Score.beamslopedamping and
1456 Score.beamquantisation properties. Is equal to 0.
1457 dit(code(\normal)) Used for setting Score.beamslopedamping and
1458 Score.beamquantisation properties. Is equal to 1.
1459 dit(code(\normalkey)) Select normal key signatures where each octave
1460 has the same key signature. This sets the Staff.keyoctaviation property.
1461 dit(code(\p)) Print a piano symbol on preceeding note.
1462 dit(code(\pp)) Print pianissimo symbol on preceeding note.
1463 dit(code(\ppp)) Print pianississimo symbol on preceeding note.
1464 dit(code(\rc)) Terminate a crescendo.
1465 dit(code(\rced)) Terminate a decrescendo
1466 dit(code(\right)) Used for setting textalignment property. Is set to 1.
1467 dit(code(\sf)) Print a ?? symbol on preceeding note.
1468 dit(code(\sfz)) Print a ?? symbol on preceeding note.
1469 dit(code(\shiftoff)) Disable horizontal shifting of note heads that collide.
1470 Sets the Voice.hshift property.
1471 dit(code(\shifton)) Enable note heads that collide with other note heads
1472 to be shifted horiztonally. Sets the Voice.hshift property.
1473 dit(code(\slurboth)) Allow slurs to be above or below notes. This
1474 sets the Voice.slurydirection property.
1475 dit(code(\slurdown)) Force slurs to be below notes. This sets the
1476 Voice.slurydirection property.
1477 dit(code(\slurup)) Force slurs to be above notes. This sets the
1478 Voice.slurydirection property.
1479 dit(code(\specialkey)) Allow keys signatures do differ in different
1480 octaves. This sets the Staff.keyoctaviation property.
1481 dit(code(\stemboth)) Allow stems, beams, and slurs to point either
1482 direction. This sets the Voice.ydirection property.
1483 dit(code(\stemdown)) Force stems, beams, and slurs to point down.
1484 This sets the Voice.ydirection property.
1485 dit(code(\stemup)) Force stems, beams and slurs to point up. This
1486 sets the Voice.ydirection property.
1487 dit(code(\traditional)) Used for setting the
1488 Score.beamquantisation property. Is equal to 2.
1489 dit(code(\up)) Used for setting various direction properties. Is
1491 dit(code(\voiceone)) Enter Voice context called code(one) and force stems down.
1492 (See code(\stemdown).)
1493 dit(code(\voicetwo)) Enter Voice context called code(two) and force stems
1494 up. (See code(\stemup).)
1495 dit(code(\voicethree)) Enter Voice context called code(three) and force stems
1497 dit(code(\voicefour)) Enter Voice context called code(four), force stems down
1498 and turn on horizontal shifting. (See code(\stemdown) and code(\shifton).)
1499 dit(code(\Wordwrap)) Used for setting the paper variable
1500 code(castingalgorithm). Equal to 0.0.
1508 The output produced by LilyPond is controlled by the code(\paper) and
1509 code(\midi) keywords. These keywords appear in the code(\score) block
1510 to indicate that printed or musical output should be produced. If
1511 neither keyword appears in a code(\score) block, then paper output is
1512 produced but MIDI output is not produced.
1514 The contents of the code(\paper) and code(\midi) blocks can change the
1515 output in various ways. These blocks can appear at the top level of a
1516 Mudela file to set default parameters for each type of output. It is
1517 still necessary to explicitly specify the output type in the
1518 code(\score) blocks if you don't want the default behavior of
1519 producing only paper output.
1521 The code(\paper) and code(\midi) blocks
1522 may begin with an optional identifier reference. No
1523 identifier references are allowed anywhere else in the block.
1524 The code(\paper) block can contain the code(\shape) keyword; the
1525 code(\midi) block can contain the code(\tempo) keyword. Both of them
1526 can contain code(\translator) keywords. The code(\paper) block can
1527 also contain identifier assignments and parameter assignments. Unlike
1528 at the top level, these assignments must be terminated by a semicolon.
1531 subsect(Paper variables)
1533 There are a large number of paper variables that are used to control
1534 details of the layout. Usually you will not want to change these
1535 variables; they are set by default to vaules that depend on the font
1536 size in use. The only way to find out what variables are supported is
1537 to search the source code for code(get_var). Two variables that you
1538 may want to change are code(linewidth) and code(indent).
1540 In order to change the font size used for the output, many variables
1541 need to be changed. Some identifiers and initialization files can
1542 simplify this process. The default size is 20pt. In order to select
1543 a different size, you must do two things. At the top level, do
1544 code(\include "paper)var(SZ)code(.ly") where var(SZ) is the height of
1545 the staff in points. Values presently allowed are 11, 13, 16, 20, and
1546 26. This loads some definitions, but does not cause them to take
1547 effect. In order to actually change the size, you must use one of the
1548 identifiers: code(\paper_eleven), code(\paper_thirteen),
1549 code(\paper_sixteen), code(\paper_twenty) or code(\paper_twentysix)
1550 inside a code(\paper) block.
1554 dit(var(integer)) If an integer appears on the left side of an
1555 assignment then a code(\symboltables) keyword must appear on the right
1556 side. This defines a music font at a particular size. See Voice
1557 property code(\fontsize).
1559 dit(code(arithmetic_basicspace) and code(arithmetic_multiplier))
1560 The space taken by a note is determined by the formula
1561 verb(arithmetic_multiplier * ( c + time ))
1562 where code(time) is the amount of time a note occupies. The value of
1563 code(c) is affected by code(arithmetic_basicspace). Increasing
1564 code(arithmetic_basicspace) will increase code(c).
1565 dit(code(barsize)) Specify height of bars. This value may need to be
1566 adjusted if you change the number of lines in the staff.
1567 dit(code(beam_dir_algorithm)) Specify algorithm for determining
1568 whether beams go up or down. It is real valued. If set to 2.0 then
1569 majority selection is used. If set to 3.0, then mean selection is
1570 used based on the mean center distance. If set to 4.0 then median
1571 selection is used, based on the median center distance.
1572 dit(code(beam_ideal_stem1))
1573 dit(code(beam_ideal_stem2))
1574 dit(code(beam_minimum_stem1))
1575 dit(code(beam_minimum_stem2))
1576 dit(code(beam_multiple_break))
1577 dit(code(beam_slope_damp_correct_factor))
1578 dit(code(beam_thickness)) Specify the thickness of beams.
1579 dit(code(castingalgorithm))
1580 dit(code(forced_stem_shorten)) Stems that have been forced to go the
1581 unnatural direction are shortened by this amount. Equal to
1582 code(\interline) by default.
1583 dit(code(gourlay_energybound))
1584 dit(code(gourlay_maxmeasures)) Maximum number of measures per line
1585 when using Gourlay method.
1586 Decreasing this greatly reduces computation time. Default value: 10.
1587 dit(code(indent)) Sets the indentation of the first line of music.
1588 dit(code(interbeam))
1589 dit(code(interbeam4))
1590 dit(code(interline)) The distance between two staff
1591 lines, calculated from the center of the lines.
1592 dit(code(linewidth)) Sets the width of the lines. If it is set to
1593 -1.0, then a single unjustified line is produced.
1594 dit(code(notewidth)) Width of an average note head.
1595 dit(code(output)) Specifies an alternate
1596 name for the TeX() output. A file(.tex) extension will be added to
1597 the string you specify.
1598 dit(code(rulethickness)) Determines thickness of staff lines and bars.
1599 dit(code(slur_clip_angle))
1600 dit(code(slur_clip_height))
1601 dit(code(slur_clip_ratio))
1602 dit(code(slur_height_limit)) Specifies the maximum height of slurs.
1603 Normally equal to staff_height.
1604 dit(code(slur_ratio)) Specifes the ratio of slur hight to slur width
1605 to aim for. Default value is 0.3.
1606 dit(code(slur_rc_factor))
1607 dit(code(slur_slope_damping)) Allows slurs to start and end at
1608 different heights ???? Default value is 0.5.
1609 dit(code(slur_thickness)) Specify slur thickness. Equal to code(1.4 *
1610 \staffline) by default.
1611 dit(code(slur_x_gap)) Horizontal space between note and slur. Set to
1612 code(\interline / 5) by default.
1613 dit(code(slur_x_minimum))
1614 dit(code(staffheight)) The height of the staff from the center of the
1615 bottom line to the center of the top line. Equal to to code(4 * \interline).
1616 dit(code(stem_length)) Specify length of stems for notes in the staff
1617 that don't have beams.
1618 dit(code(stemthickness)) Specifies the thickness of the stem lines.
1619 dit(code(tie_slope_damping))
1620 dit(code(tie_x_minimum))
1624 subsect(MIDI Instrument Names)
1627 The MIDI instrument name is set by the code(Staff."midi_instrument")
1628 property or, if that property is not set, the code(Staff.instrument)
1629 property. The instrument name should be chosen from this list. If
1630 string does not exactly match one from this list then LilyPond uses
1633 COMMENT( acordina = accordion, tango accordian = concertina
1634 distortion guitar = distorted guitar
1635 orchestral strings = harp
1636 pan flute = wood flute? )
1638 verb("acoustic grand" "contrabass" "lead 7 (fifths)"
1639 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
1640 "electric grand" "pizzicato strings" "pad 1 (new age)"
1641 "honky-tonk" "orchestral strings" "pad 2 (warm)"
1642 "electric piano 1" "timpani" "pad 3 (polysynth)"
1643 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
1644 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
1645 "clav" "synthstrings 1" "pad 6 (metallic)"
1646 "celesta" "synthstrings 2" "pad 7 (halo)"
1647 "glockenspiel" "choir aahs" "pad 8 (sweep)"
1648 "music box" "voice oohs" "fx 1 (rain)"
1649 "vibraphone" "synth voice" "fx 2 (soundtrack)"
1650 "marimba" "orchestra hit" "fx 3 (crystal)"
1651 "xylophone" "trumpet" "fx 4 (atmosphere)"
1652 "tubular bells" "trombone" "fx 5 (brightness)"
1653 "dulcimer" "tuba" "fx 6 (goblins)"
1654 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
1655 "percussive organ" "french horn" "fx 8 (sci-fi)"
1656 "rock organ" "brass section" "sitar"
1657 "church organ" "synthbrass 1" "banjo"
1658 "reed organ" "synthbrass 2" "shamisen"
1659 "accordion" "soprano sax" "koto"
1660 "harmonica" "alto sax" "kalimba"
1661 "concertina" "tenor sax" "bagpipe"
1662 "acoustic guitar (nylon)" "baritone sax" "fiddle"
1663 "acoustic guitar (steel)" "oboe" "shanai"
1664 "electric guitar (jazz)" "english horn" "tinkle bell"
1665 "electric guitar (clean)" "bassoon" "agogo"
1666 "electric guitar (muted)" "clarinet" "steel drums"
1667 "overdriven guitar" "piccolo" "woodblock"
1668 "distorted guitar" "flute" "taiko drum"
1669 "guitar harmonics" "recorder" "melodic tom"
1670 "acoustic bass" "pan flute" "synth drum"
1671 "electric bass (finger)" "blown bottle" "reverse cymbal"
1672 "electric bass (pick)" "skakuhachi" "guitar fret noise"
1673 "fretless bass" "whistle" "breath noise"
1674 "slap bass 1" "ocarina" "seashore"
1675 "slap bass 2" "lead 1 (square)" "bird tweet"
1676 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
1677 "synth bass 2" "lead 3 (calliope)" "helicopter"
1678 "violin" "lead 4 (chiff)" "applause"
1679 "viola" "lead 5 (charang)" "gunshot"
1680 "cello" "lead 6 (voice)")
1684 subsect(Translators)
1687 The behavior of notation contexts is defined by the translators for
1688 those contexts. The translator for a context specifies what notations
1689 are handled by the context, it specifies what other contexts the
1690 context can contain, and it sets property values for the context.
1691 There are different translators for each type of output. The
1692 translators for paper output are defined in file(engraver.ly). The
1693 translators for MIDI output are defined in file(performer.ly).
1695 The first thing that appears inside a code(\translator) definition is
1696 the type of the context being created. This is specified with the
1697 code(\type) keyword: code(\type) var(typename)code(;). After the type
1698 of the context is specified, property assignments, the code(\name)
1699 keyword and code(\consists), code(\accepts), and code(\remove)
1700 keywords can appear in any order. The code(\name) keyword specifies
1701 the name of the context that is handled by the translator. If the
1702 name is not specified, the translator won't do anything. Each
1703 code(\accepts) keyword specifies what contexts can be contained inside
1704 this one. The code(\consists) keywords specify which notations are
1705 handled by the context. Each code(\consists) keyword specifies the
1706 name of an engraver (for paper ouput) or performer (for MIDI output)
1707 which handles a certain notation. The code(\remove) keyword can be
1708 used to remove a performer or engraver from the translator.
1710 In the code(\paper) block, it is also possible to define translator
1711 identifiers. Like other block identifiers, the identifier can only
1712 be used as the very first item of a translator. In order to define
1713 such an identifier outside of code(\score), you must do
1714 verb(\paper{ foo=\translator{ ... }
1717 \paper{ \translator{ \foo ... } }
1720 Some All of the standard translators have predefined identifiers, making
1721 it easy to redefine these contexts by adding or removing items.
1722 The predefined identifiers are: code(StaffContext),
1723 code(RhythmicStaffContext), code(VoiceContext), code(ScoreContext), code(ScoreWithNumbers)
1726 subsubsect(Paper Types and Engravers and Pre-defined Translators)
1728 Some pre-defined identifiers can simplify modification of translators.
1729 The pre-defined identifiers are:
1731 dit(code(StaffContext)) Default Staff context.
1732 dit(code(RhythmicStaffContext)) Default RhythmicStaff context.
1733 dit(code(VoiceContext)) Default Voice context.
1734 dit(code(ScoreContext)) Default Score context.
1735 dit(code(ScoreWithNumbers)) Score context with numbering at the
1737 dit(code(BarNumberingStaffContext)) Staff context with numbering at
1739 dit(code(HaraKiriStaffContext))
1740 dit(code(OrchestralPartStaffContext))
1741 dit(code(OrchestralScoreContext))
1743 Using these pre-defined values, you can remove or add items to the
1744 translator verb(\paper{ \translator{ \StaffContext
1745 \remove Some_engraver;
1746 \consists Different_engraver; }})
1750 There are four types for paper translators:
1752 dit(code(Engraver_group_engraver))
1753 dit(code(Hara_kiri_line_group_engraver))
1754 dit(code(Line_group_engraver_group))
1755 dit(code(Score_engraver))
1757 COMMENT( The names of these types seem somewhat confusing. )
1759 The engravers for paper output are:
1762 dit(code(Abbreviation_beam_engraver))
1763 dit(code(Bar_column_engraver))
1764 dit(code(Bar_engraver)) Engraves bar lines. Normally in code(Staff) and
1765 code(RhythmicStaff).
1766 dit(code(Bar_number_engraver)) Engrave bar numbers. These numbers
1767 appear at the start of each line. Not normally in any translator. Can
1768 be added to code(Score) for Score-wide numbering or to code(Staff) for
1769 numbering on each staff.
1771 dit(code(Beam_engraver)) Handles beam requests by engraving beams. Normally
1772 appears in the code(Voice) translator. If omitted, then notes will be printed
1773 with flags instead of beams.
1775 dit(code(Beam_req_swallow_translator)) Swallows beam requests. In
1777 dit(code(Clef_engraver)) Engraves the clef symbol. Normally in code(Staff).
1778 dit(code(Collision_engraver))
1779 dit(code(Dot_column_engraver)) Engraves dots on dotted notes shifted to the
1780 right of the note. Normally in code(Voice). If omitted, then dots appear on
1782 dit(code(Dynamic_engraver)) Engraves dynamics symbols. Normally in code(Voice).
1783 dit(code(Font_size_engraver))
1784 dit(code(Key_engraver)) Engraves the key signature. Normally in code(Staff).
1785 dit(code(Local_key_engraver))
1786 dit(code(Lyric_engraver)) Engraves lyrics. Normally in code(LyricVoice).
1787 dit(code(Multi_measure_rest_engraver)) Engraves multi-measure rests that are
1788 produced with code(R). Normally in code(Voice).
1789 dit(code(Note_heads_engraver)) Engraves note heads. Normally in code(Voice).
1790 Removing this gives a fatal error.
1791 COMMENT(Perhaps should be Note_head_engraver)
1792 dit(code(Piano_bar_engraver))
1793 dit(code(Pitch_squash_engraver)) Treat all pitches as middle C. Used in
1794 code(RhythmicStaff). Note that the notes move, but the locations of
1795 accidentals stay the same.
1796 dit(code(Plet_engraver)) Engraves brackets and the number over tuplets. In
1798 dit(code(Plet_swallow_engraver)) Swallows tuplet requests without any output.
1799 In code(LyricVoice).
1800 COMMENT( Should this be named Plet_req_swallow_translator? )
1801 dit(code(Priority_horizontal_align_engraver))
1802 dit(code(Rest_collision_engraver)) Handles collisions of rests. In code(Staff).
1803 dit(code(Rest_engraver)) Engraves rests. Normally in code(Voice).
1804 dit(code(Rhythmic_column_engraver))
1805 dit(code(Score_priority_engraver))
1806 dit(code(Script_engraver)) Handles note ornaments generated by code(\script).
1807 Normally in code(Voice).
1808 dit(code(Separating_line_group_engraver))
1809 dit(code(Skip_req_swallow_translator))
1810 dit(code(Slur_engraver)) Engraves slurs. Normally in code(Voice).
1811 dit(code(Span_bar_engraver)) Engraves lines across multiple staffs. Normally
1812 in code(Staffgroup) and code(GrandStaff). Removing this from code(StaffGroup)
1813 gives the definition of code(ChoirStaff).
1814 dit(code(Span_score_bar_engraver))
1815 dit(code(Staff_group_bar_engraver))
1816 dit(code(Staff_margin_engraver)) Prints the name of the instrument
1817 (specified by code(Staff.instrument) and code(Staff.instr)) at the
1819 dit(code(Staff_sym_engraver))
1820 dit(code(Stem_engraver)) Engraves stems. Normally in code(Voice).
1821 dit(code(Ties_engraver)) Engraves ties. Normally in code(Voice).
1822 dit(code(Time_signature_engraver)) Engraves the time signature. Normally in
1823 code(Staff) and code(RhythmicStaff).
1824 dit(code(Timing_engraver)) Responsible for synchronizing timing information
1825 from staffs. Normally in code(Score). In order to create polyrhythmic music,
1826 this engraver should be removed from code(Score) and placed in code(Staff).
1827 dit(code(Vertical_align_engraver))
1831 subsubsect(MIDI Types and Performers)
1833 The types available for MIDI translators are:
1835 dit(code(Performer_group_performer))
1836 dit(code(Score_performer))
1837 dit(code(Staff_performer))
1840 The performers for MIDI translators are:
1842 dit(code(Key_performer))
1843 dit(code(Time_signature_performer))
1844 dit(code(Note_performer))
1845 dit(code(Lyric_performer))
1846 dit(code(Swallow_performer))