3 Mudela - GNU LilyPond input format 0.1
7 This document describes the the GNU LilyPond input format, which is an
8 effective language for defining music. We call this language
9 (rather arrogantly) The Musical Definition Language (S<Mudela 0.1>).
11 The first aim of Mudela is to define a piece of music,
12 being complete from both from a musical typesetting,
13 as from a musical performing point of view.
18 The Musical Definition Language (Mudela) S<version 2>, has a logical
19 structure, making use of typing and naming (using identifiers), that
20 allows for flexible input, and definition reuse. See MANIFESTO for
21 reasons and design considerations.
23 The below included for explanatory purposes only (i.e., for a complete
24 and up-to-date definition, see F<lily/parser.y> and F<lily/lexer.l>):
26 As a related note, you should take a look at the examples and the init
27 file, as this document does not cover every aspect of mudela yet, and
32 The de-facto extension of Mudela is F<.ly>. Files may be included by
33 entering C<include> at the start of a line:
39 Line comments are introduced by a C<%>.
43 Occasionally, small changes in syntax across different versions of
44 Mudela might give syntax errors. To warn you about possible
45 incompatibilities, you can specify the Mudela version for which the
46 inputfile was written,
50 A perl-script which tries to convert to newer versions
51 (F<convert-mudela.pod>) is included in the LilyPond distribution.
55 Keywords are preceded by a backslash "\". They contain alphabetic
58 Identifiers in their normal form consist start with a alpha character,
59 followed by alpha-numerics. Identifiers can contain any characters
60 (except whitespace, C<$> and C<%>), if you use this construct:
62 $i'm_a_weird###identifier
64 (which is the identifier with the name
65 C<i'm_a_weird###identifier> ). C<$> Takes any sequence of
66 characters which are not whitespace, C<$> and C<%>.
68 \$i'm_a_weird###escaped_word
70 =head2 Nesting characters
72 Mudela uses the brace (C<{> and C<}>) for hierarchical structures. To
73 aid the eye in reading, for chords the < and the > are used as
78 =head2 Hierarchical structures
80 The general structure consists of declarations:
88 \TYPE{ <type specific data> }
90 (Currently, C<\score> is the only type that can be instantiated
91 at top level. Currently declarations can only be done at top level)
93 Most instantiations that use an IDENTIFIER are specified as follows:
95 \TYPE{ IDENTIFIER [...] }
97 Some exceptions on this rule have been made to prevent inputting
98 Mudela becoming tedious
103 The actual musical part of Mudela that defines a melody, is known as
106 Simple mudela is the most common type of music. It consists of a list
107 of notes or lyrics, chords, and commands.
111 To simplify different aspects of music definition (entering the notes
112 and manipulating them) Mudela has a number of different input "modes":
118 At the start of parsing, Mudela assumes normal mode.
119 In Normal mode, a word is looked up in the following order:
121 word identifier, string
122 \word keyword, identifier, string
124 In normalmode, a word is assumed to start with an alphabetic
125 character, followed by alpha-numeric characters.
129 Note mode (and thus Simple mudela) is introduced by the keyword C<\melodic>.
130 In Note mode, a word is looked up in the following order:
132 word notename, string
133 \word keyword, identifier, string
135 In Note mode a word is considered to have alphabetic characters only.
139 Lyrics mode (and thus Simple mudela) is introduced by the keyword C<\lyrics>.
141 In Lyrics mode, a word is looked up in the following order:
144 \word keyword, identifier, string
146 In Lyric mode every sequence of non-digit and non-white characters
147 starting with an alphabetic character is considered a word.
149 a&@&@&TSI|{[ % a word
150 1THtrhortho % not a "word"
151 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
156 These modes are of a lexical nature. Normal and Note mode largely
157 resemble each other, save the possibility of entering Reals,
158 meaning of C<_> and the resolution of words
162 Simple mudela basically is a sequence of the notes you want to
167 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
168 Hz concert-pitch. C<c'> is also known as the central c. More examples:
179 This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
180 signifies that this note is part of a triplet (3 in stead of 2). The
181 duration is one and a half quaver (C<4.>) times 2/3.
184 Notenames are just a special kind of identifiers, and can be declared
185 for any language appropriate (see F<dutch.ini>). The default language
186 for notenames is defined to be dutch. In dutch, the notenames are
187 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
191 cisis disis eisis fisis gisis aisis bisis
193 cis dis eis fis gis ais bis
197 ces des es fes ges as bes
199 ceses deses eses feses geses ases beses
201 The standard notenames also have uppercase versions, which octavate
204 a % 220 concert-pitch
210 Rests are named r or s
213 s % a "space" rest, nothing is printed.
215 These notenames along with duration are enough material to construct
221 Music is able to express more. generally speaking, the other
222 'features' are either connected between notes (slurs, beams: spanning
223 requests) or attached to notes (eg. accents). The former are
224 implemented as START and STOP stop features and then attached to the note.
234 Please note that these two characters do I<not> necessarrily nest, eg:
237 [c8 c8 c8]2/3 % a triplet
239 Symbols which can be put at either side (above or below) of a staff
240 are entered as follows:
242 a-^ % marcato, direction: default
243 a^- % portato, direction: above note
244 a_. % staccato, direction: below note
245 a^\script { "symbolindex" . . . } % see script.ini for details.
246 a^\fermata % predefined identifier
248 Dynamics can be put after the notename:
250 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
252 Mudela defines the following dynamic identifiers:
254 ppp pp p mp mf df ff fff % df iso f, f is a notename.
256 and the following abbreviations:
259 \> % start decrescendo
260 \! % end crescendo/decrescendo
264 To accompany a note with a text (eg, "marcato"), you should say:
270 the c- construct chooses the default up/down direction.
277 If omit the duration of a, a default value is substituted. For this
278 default value, there are two modes:
284 Use the last duration explicitly entered
288 Use the explicitly set "default duration"
292 Thus the following inputs are equivalent
294 c4 c4 c16 c16 c16 s16 c4 c16
297 c4 c c16 c c c c4 c16
300 c c c16 c16 c16 c16 c c16
305 If you are typing music which does not lie in the "small" and "large"
306 octave, you can prevent having to type C<'> all the time by using the
307 C<\octave> command: These two lines have the same pitch.
312 By default the setting of C<\octave> is 0.
316 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
319 All syllables are entered separately, separated by whitespace
321 Twin-4 kle4 twin-4 kle4 ...
323 Two syllables or words that compose a single
324 duration entry are bound together using an underscore
328 =head2 Music direction
330 Mudela reads left to right, but you can still stack voices and
331 Voice_elements which are produced in two directions: horizontal
332 (voice like) and vertical (chord like)
334 A sequence of notes (horizontal) is called simple horizontal, eg
339 You can also glue two pieces of simple horizontal music together with the
340 concatenation operator:
342 horOne = \melodic { c c g g }
343 horTwo = \melodic { a a g2 }
344 twinkle = \melodic { \horOne ++ \horTwo }
346 If you enclose simple horizontal music in braces ( { } ), then you get
349 { c c g g a a g2 } % twinkle twinkle
351 You can start vertical music (a "chord") by enclosing a sequence of
352 notes with < and >. Example:
354 <a cis e'> % a-major chord
356 You can also put vertical music inside horizontal music:
358 { c <c e> <c e g> <c e g c'> } % 4 increasing chords
364 {r2 r2 c c g g a a g2} > % a canon
366 The duration of a chord equals the union of the durations of each of
367 its elements. The C<\multivoice> is a construct which is explained
373 You can transpose horizontal music in the following way:
380 d % from c to the d that's one octave down
381 { e4 f4 } % the horizontal music
385 The result is, as you can see, again simple horizontal music.
389 Rhythms in Mudela are entered identical to Simple mudela.
390 The melodic part of the information is ignored.
394 A duration always starts with the duration type (1,2,4 etc), and then
395 any optional multipliers/dots
397 =head2 Meters/groupings
399 A meter has this form:
403 Rhythmic grouping is a concept closely associated with this. For
404 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
409 You can start the piece with a partial measure, the command takes the
410 same syntax as grouping:
414 Make the piece start with a partial measure [transl?] lasting 1 3/4
417 These commands are also "voice elements", and constitute simple mudela
418 (consisting of stuff with duration 0).
422 In concrete, a piece of Mudela has the following structure:
424 % declare pieces of music:
425 melody = \music{ <simple mudela> }
426 accompany = \music{ <simple mudela> }
428 % instantiate (=create tex, midi output) the score:
430 \staff{ melodicregs melody }
431 \staff{ melodicregs accompany }
432 \midi{ <midi definitions> }
433 \paper{ <paper and layout definitions> }
438 Examples are included with the GNU LilyPond distribution. For the sake of
439 maintenance no long examples are included in this document.
444 This chapter deals with the internals of Mudela. In the end Mudela
445 converted to Voice, which contain Voice_elements which (in turn)
446 contain Requests. The former 2 types are basically containers (lists).
447 Consider the following simple mudela
449 \music { c4 <e4 g4> }
451 After the parsing, this is converted to: (from the debug output)
454 voice_element { dur :1/4
455 Stem_req {duration { 4}}
456 Note_req {notename: 0 acc: 0 oct: -1
460 voice_element { dur :0
461 Terminate_voice_req {}
466 voice_element { dur :1/4
467 Stem_req {duration { 4}}
468 Note_req {notename: 2 acc: 0 oct: -1
472 voice_element { dur :0
473 Terminate_voice_req {}
478 voice_element { dur :1/4
479 Stem_req {duration { 4}}
480 Note_req {notename: 4 acc: 0 oct: -1
484 voice_element { dur :0
485 Terminate_voice_req {}
492 As you can see, most information is stored in the form of a request.
493 In music typesetting, the user might want to cram a lot more symbols
494 on the paper than actually fits. To reflect this idea (the user asks
495 more than we can do), the container for this data is called Request.
497 A request is done to the C<Staff> which contains the
498 C<Voice_element>. The staff decides whether to to honor the request,
499 ignore it, or merge it with other requests. Merging of requests is
500 preferably done with other requests done by members of the same
501 voicegroups (beams, brackets, stems)
505 The staff is a simple container (containing Voices). The so-called
506 "registers" determine the characteristics of the Staff. At this time,
507 LilyPond supports the following personalities:
513 This makes the staff into a single five line melodic staff.
517 This makes the staff into a staff which will only set Lyric_requests.
525 This language has a number of roots. First and foremost, GNU LilyPond's
526 predecessor mpp was the inspiration of simple Mudela. Secondly, the
527 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
528 that I've written as a hobby project. ), which in turn owes a lot to
531 Now, we know, musictypesetting and raytracing do not necessarily
532 require the same input format, and we know that a lot more ways exist
533 to convert music to ASCII, but we did give this language some
534 thoughts. As always suggestions are appreciated.