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.
22 The below included for explanatory purposes only (i.e., for a complete
23 and up-to-date definition, see F<lily/parser.y> and F<lily/lexer.l>):
25 As a related note, you should take a look at the examples and the init
26 file, as this document does not cover every aspect of mudela yet.
30 The de-facto extension of Mudela is F<.ly>. Files may be included by
31 entering C<include> at the start of a line:
37 Line comments are introduced by a C<%>
41 Occasionally, small changes in syntax across different versions of
42 Mudela might give syntax errors. To warn you about possible
43 incompatibilities, you can specify the Mudela version for which the
44 inputfile was written,
50 Keywords are preceded by a backslash "\". They contain alphabetic
53 Identifiers in their normal form consist start with a alpha character,
54 followed by alpha-numerics. Identifiers can contain any characters
55 (except whitespace, C<$> and C<%>), if you use this construct:
57 $i'm_a_weird###identifier
59 (which is the identifier with the name
60 C<i'm_a_weird###identifier> ). C<$> Takes any sequence of
61 characters which are not whitespace, C<$> and C<%>.
63 \$i'm_a_weird###escaped_word
65 =head2 Nesting characters
67 Mudela uses the brace (C<{> and C<}>) for hierarchical structures. To
68 aid the eye in reading, for chords the < and the > are used as
73 =head2 Hierarchical structures
75 The general structure consists of declarations:
83 \TYPE{ <type specific data> }
85 (Currently, C<\score> is the only type that can be instantiated
86 at top level. Currently declarations can only be done at top level)
88 Most instantiations that use an IDENTIFIER are specified as follows:
90 \TYPE{ IDENTIFIER [...] }
92 Some exceptions on this rule have been made to prevent inputting
93 Mudela becoming tedious
98 The actual musical part of Mudela that defines a melody, is known as
101 Simple mudela is the most common type of music. It consists of a list
102 of notes or lyrics, chords, and commands.
106 To simplify different aspects of music definition (entering the notes
107 and manipulating them) Mudela has a number of different input "modes":
113 At the start of parsing, Mudela assumes normal mode.
114 In Normal mode, a word is looked up in the following order:
116 word identifier, string
117 \word keyword, identifier, string
119 In normalmode, a word is assumed to start with an alphabetic
120 character, followed by alpha-numeric characters.
124 Note mode (and thus Simple mudela) is introduced by the keyword C<\melodic>.
125 In Note mode, a word is looked up in the following order:
127 word notename, string
128 \word keyword, identifier, string
130 In Note mode a word is considered to have alphabetic characters only.
134 Lyrics mode (and thus Simple mudela) is introduced by the keyword C<\lyrics>.
136 In Lyrics mode, a word is looked up in the following order:
139 \word keyword, identifier, string
141 In Lyric mode every sequence of non-digit and non-white characters
142 starting with an alphabetic character is considered a word.
144 a&@&@&TSI|{[ % a word
145 1THtrhortho % not a "word"
146 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
151 These modes are of a lexical nature. Normal and Note mode largely
152 resemble each other, save the possibility of entering Reals,
153 meaning of C<_> and the resolution of words
157 Simple mudela basically is a sequence of the notes you want to
162 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
163 Hz concert-pitch. C<c'> is also known as the central c. More examples:
174 This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
175 signifies that this note is part of a triplet (3 in stead of 2). The
176 duration is one and a half quaver (C<4.>) times 2/3.
179 Notenames are just a special kind of identifiers, and can be declared
180 for any language appropriate (see F<dutch.ini>). The default language
181 for notenames is defined to be dutch. In dutch, the notenames are
182 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
186 cisis disis eisis fisis gisis aisis bisis
188 cis dis eis fis gis ais bis
192 ces des es fes ges as bes
194 ceses deses eses feses geses ases beses
196 The standard notenames also have uppercase versions, which octavate
199 a % 220 concert-pitch
209 These notenames along with duration are enough material to construct
215 Music is able to express more. generally speaking, the other
216 'features' are either connected between notes (slurs, beams: spanning
217 requests) or attached to notes (eg. accents). The former are
218 implemented as START and STOP stop features and then attached to the note.
228 Please note that these two characters do I<not> necessarrily nest, eg:
233 Symbols which can be put at either side of a staff are entered as follows:
235 a-^ % marcato, direction: default
236 a^- % portato, direction: above note
237 a_. % staccato, direction: below note
238 a^\script { "symbolindex" . . . } % see script.ini for details.
239 a^\fermata % predefined identifier
241 Dynamics can be put after the notename:
243 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
245 Mudela defines the following dynamic identifiers:
247 ppp pp p mp mf df ff fff % df iso f, f is a notename.
249 and the following abbreviations:
252 \> % start decrescendo
253 \! % end crescendo/decrescendo
257 To accompany a note with a text (eg, "marcato"), you should say:
263 the c- construct chooses the default up/down direction.
270 If omit the duration of a, a default value is substituted. For this
271 default value, there are two modes:
277 Use the last duration explicitly entered
281 Use the explicitly set "default duration"
285 Thus the following inputs are equivalent
287 c4 c4 c16 c16 c16 s16 c4 c16
290 c4 c c16 c c c c4 c16
293 c c c16 c16 c16 c16 c c16
298 If you are typing music which does not lie in the "small" and "large"
299 octave, you can prevent having to type C<'> all the time by using the
300 C<\octave> command: These two lines have the same pitch.
305 By default the setting of C<\octave> is 0.
309 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
312 All syllables are entered separately, separated by whitespace
314 Twin-4 kle4 twin-4 kle4 ...
316 Two syllables or words that compose a single
317 duration entry are bound together using an underscore
321 =head2 Music direction
323 Mudela reads left to right, but you can still stack voices and
324 Voice_elements which are produced in two directions: horizontal
325 (voice like) and vertical (chord like)
327 You can start horizontal music by enclosing a sequence of notes with { and }
329 { c c g g a a g2 } % twinkle twinkle
331 You can start vertical music (a "chord") by enclosing a sequence of
332 notes with < and >. Example:
334 <a cis e'> % a-major chord
336 You can also put vertical music inside horizontal music:
338 { c <c e> <c e g> <c e g c'> } % 4 increasing chords
344 {r2 r2 c c g g a a g2} > % a canon
346 The duration of a chord equals the union of the durations of each of
347 its elements. The C<\multivoice> is a construct which is explained
350 You can also glue two horizontal pieces music together with
351 concatenation operator:
353 \horOne = \melodic { c c g g }
354 \horTwo = \melodic { a a g2 }
355 \twinkle = \melodic { \horOne ++ \horTwo }
359 You can transpose horizontal music in the following way:
361 \transpose { d % from c to d that's one octave up.
362 { e4 f4 } % the horizontal music
367 Rhythms in Mudela are entered identical to Simple mudela.
368 The melodic part of the information is ignored.
372 A duration always starts with the duration type (1,2,4 etc), and then
373 any optional multipliers/dots
375 =head2 Meters/groupings
377 A meter has this form:
381 Rhythmic grouping is a concept closely associated with this. For
382 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
385 \grouping { 8*2 8*3 }
391 In concrete, a piece of Mudela has the following structure:
393 % declare pieces of music:
394 melody = \music{ <simple mudela> }
395 accompany = \music{ <simple mudela> }
397 % instantiate (=create tex, midi output) the score:
401 \commands{ <score global commands> }
402 \midi{ <midi definitions> }
403 \paper{ <paper and layout definitions }
408 Examples are included with the GNU LilyPond distribution. For the sake of
409 maintenance no long examples are included in this document.
414 This chapter deals with the internals of Mudela. In the end Mudela
415 converted to Voice, which contain Voice_elements which (in turn)
416 contain Requests. The former 2 types are basically containers (lists).
417 Consider the following simple mudela
419 \music { c4 <e4 g4> }
421 After the parsing, this is converted to: (from the debug output)
424 voice_element { dur :1/4
425 Stem_req {duration { 4}}
426 Note_req {notename: 0 acc: 0 oct: -1
430 voice_element { dur :0
431 Terminate_voice_req {}
436 voice_element { dur :1/4
437 Stem_req {duration { 4}}
438 Note_req {notename: 2 acc: 0 oct: -1
442 voice_element { dur :0
443 Terminate_voice_req {}
448 voice_element { dur :1/4
449 Stem_req {duration { 4}}
450 Note_req {notename: 4 acc: 0 oct: -1
454 voice_element { dur :0
455 Terminate_voice_req {}
462 As you can see, most information is stored in the form of a request.
463 In music typesetting, the user might want to cram a lot more symbols
464 on the paper than actually fits. To reflect this idea (the user asks
465 more than we can do), the container for this data is called Request.
468 the C<Staff> which contains the C<Voice_element>. The staff decides
469 whether to to honor the request, ignore it, or merge it with other
470 requests. Merging of requests is preferably done with other requests
471 done by members of the same voicegroups (beams, brackets, stems)
478 This language has a number of roots. First and foremost, GNU LilyPond's
479 predecessor mpp was the inspiration of simple Mudela. Secondly, the
480 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
481 that I've written as a hobby project. ), which in turn owes a lot to
484 Now, we know, musictypesetting and raytracing do not necessarily
485 require the same input format, and we know that a lot more ways exist
486 to convert music to ASCII, but we did give this language some
487 thoughts. As always suggestions are appreciated.