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<%>. Block comments are delimited
40 by C<%{> and C<%}>. They do not nest.
44 Occasionally, small changes in syntax across different versions of
45 Mudela might give syntax errors. To warn you about possible
46 incompatibilities, you can specify the Mudela version for which the
47 inputfile was written,
51 A perl-script which tries to convert to newer versions
52 (F<convert-mudela>) is included in the LilyPond distribution.
56 Keywords are preceded by a backslash: '\'. They contain alphabetic
59 Identifiers in their normal form consist start with a alpha character,
60 followed by alpha-numerics. Identifiers can contain any characters
61 (except whitespace, C<$> and C<%>), if you use this construct:
63 $i'm_a_weird###identifier
65 (which is the identifier with the name
66 C<i'm_a_weird###identifier> ). C<$> Takes any sequence of
67 characters which are not whitespace, C<$> and C<%>.
69 \$i'm_a_weird###escaped_word
71 =head2 Nesting characters
73 Mudela uses the brace (C<{> and C<}>) for hierarchical structures. To
74 aid the eye in reading, for chords the < and the > are used as
79 Please note that -.5 is no Real.
89 =head2 Hierarchical structures
91 The general structure consists of declarations:
99 \TYPE{ <type specific data> }
101 (Currently, C<\score> is the only type that can be instantiated
102 at top level. Currently declarations can only be done at top level)
104 Most instantiations that use an IDENTIFIER are specified as follows:
106 \TYPE{ IDENTIFIER [...] }
108 Some exceptions on this rule have been made to prevent inputting
109 Mudela becoming tedious
114 The actual musical part of Mudela that defines a melody, is known as
117 Simple mudela is the most common type of music. It consists of a list
118 of notes or lyrics, chords, and commands.
122 To simplify different aspects of music definition (entering the notes
123 and manipulating them) Mudela has a number of different input "modes":
129 At the start of parsing, Mudela assumes normal mode.
130 In Normal mode, a word is looked up in the following order:
132 word identifier, string
133 \word keyword, identifier, string
135 In normalmode, a word is assumed to start with an alphabetic
136 character, followed by alpha-numeric characters.
140 Note mode (and thus Simple mudela) is introduced by the keyword C<\melodic>.
141 In Note mode, a word is looked up in the following order:
143 word notename, string
144 \word keyword, identifier, string
146 In Note mode a word is considered to have alphabetic characters only.
150 Lyrics mode (and thus Simple mudela) is introduced by the keyword C<\lyrics>.
152 In Lyrics mode, a word is looked up in the following order:
155 \word keyword, identifier, string
157 In Lyric mode every sequence of non-digit and non-white characters
158 starting with an alphabetic character or the '_'is considered a word.
160 a&@&@&TSI|{[ % a word
161 1THtrhortho % not a "word"
162 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
163 _ _ _ _ % 4 words: 4 spaces
167 These modes are of a lexical nature. Normal and Note mode largely
168 resemble each other, save the possibility of entering Reals,
169 meaning of C<_> and the resolution of words
173 Simple mudela basically is a sequence of the notes you want to
178 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
179 Hz concert-pitch. C<c'> is also known as the central c. More examples:
190 This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
191 signifies that this note is part of a triplet (3 in stead of 2). The
192 duration is one and a half quaver (C<4.>) times 2/3.
195 Notenames are just a special kind of identifiers, and can be declared
196 for any language appropriate (see F<dutch.ini>). The default language
197 for notenames is defined to be dutch. In dutch, the notenames are
198 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
202 cisis disis eisis fisis gisis aisis bisis
204 cis dis eis fis gis ais bis
208 ces des es fes ges as bes
210 ceses deses eses feses geses ases beses
212 The standard notenames also have uppercase versions, which octavate
215 a % 220 concert-pitch
221 Rests are named r or s
224 s % a "space" rest, nothing is printed.
226 These notenames along with duration are enough material to construct
232 Music is able to express more. generally speaking, the other
233 'features' are either connected between notes (slurs, beams: spanning
234 requests) or attached to notes (eg. accents). The former are
235 implemented as START and STOP stop features and then attached to the note.
245 Please note that these two characters do I<not> necessarrily nest,
246 they should attached to the note C<[ {c4 c4} ]> will generate a parse
247 error for this reason.
249 [c8 e8(] [)g8 <c'8] e'8>
251 [2/3 c8 c8 c8]1/1 % a triplet
254 =head2 Slurs and Ties
256 Ties connect the noteheads of adjecent notes. They are entered as follows:
260 Slurs connect whole chords, and try to avoid crossing stems. They are
267 Symbols which can be put at either side (above or below) of a staff
268 are entered as follows:
270 a-^ % marcato, direction: default
271 a^- % portato, direction: above note
272 a_. % staccato, direction: below note
273 a^\script { "symbolindex" . . . } % see script.ini for details.
274 a^\fermata % predefined identifier
276 Dynamics can be put after the notename:
278 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
280 Mudela defines the following dynamic identifiers:
282 ppp pp p mp mf df ff fff % df iso f, f is a notename.
284 and the following abbreviations:
287 \> % start decrescendo
288 \! % end crescendo/decrescendo
292 To accompany a note with a text (eg, "marcato"), you should say:
298 the c- construct chooses the default up/down direction.
305 If omit the duration of a, a default value is substituted. For this
306 default value, there are two modes:
312 Use the last duration explicitly entered
316 Use the explicitly set "default duration"
320 Thus the following inputs are equivalent
322 c4 c4 c16 c16 c16 s16 c4 c16
325 c4 c c16 c c c c4 c16
328 c c c16 c16 c16 c16 c c16
333 If you are typing music which does not lie in the "small" and "large"
334 octave, you can prevent having to type C<'> all the time by using the
335 C<\octave> command: These two lines have the same pitch.
340 By default the setting of C<\octave> is 0.
344 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
347 All syllables are entered separately, separated by whitespace
349 Twin-4 kle4 twin-4 kle4 ...
351 Two syllables or words that compose a single
352 duration entry are bound together using an underscore
356 =head2 Music direction
358 Mudela reads left to right, but you can still stack voices and
359 Voice_elements which are produced in two directions: horizontal
360 (voice like) and vertical (chord like)
362 A sequence of notes (horizontal) is called simple horizontal, eg
367 You can also glue two pieces of simple horizontal music together with the
368 concatenation operator:
370 horOne = \melodic { c c g g }
371 horTwo = \melodic { a a g2 }
372 twinkle = \melodic { \horOne ++ \horTwo }
374 If you enclose simple horizontal music in braces ( { } ), then you get
377 { c c g g a a g2 } % twinkle twinkle
379 You can start vertical music (a "chord") by enclosing a sequence of
380 notes with < and >. Example:
382 <a cis e'> % a-major chord
384 You can also put vertical music inside horizontal music:
386 { c <c e> <c e g> <c e g c'> } % 4 increasing chords
392 {r2 r2 c c g g a a g2} > % a canon
394 The duration of a chord equals the union of the durations of each of
395 its elements. The C<\multivoice> is a construct which is explained
401 You can transpose horizontal music in the following way:
408 d % from c to the d that's one octave down
409 { e4 f4 } % the horizontal music
413 The result is, as you can see, again simple horizontal music.
418 If more than one "voice" is in a staff, then you have the option of
419 putting the different voices into so called voicegroups: members of
420 the same voicegroup share certain characteristics, among others:
427 For the actual list, see the init file F<register.ini>
429 Putting different musical lines in to the same voicegroup effectively
430 makes LilyPond try to form chords of all those lines. Putting
431 different musical lines in to different voicegroups effectively makes
432 LilyPond try to set those lines as independently as possible.
434 You can set the voicegroup of a voice with the command C<\group>, e.g.,
444 oboeII = \melodic { \group "oboes";
452 melodicregs \melodic{ oboeI }
456 In this example, the two oboe voices share one staff and are initially
457 in the voicegroup called "oboes". They will share beams, dynamics etc.
458 After two quavers, oboeI "pushes" its group: a new voicegroup is
459 created, called "oboes+solo". The C<\group "-"> command makes the
460 voice enter "oboes" again.
462 Please do note that [] are voicegroup wide; the previous input is
463 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
464 voicegroup "oboes", albeit not in oboeI but oboeII
466 This concept may seem contorted, but it allows you to set the separate
467 oboe parts without changing the C<oboeI> and C<oboeII> (assuming that
468 you edit the [] in the example.)
472 < { .... } {......} >
474 makes a chord (all horizontal parts are in the same voicegroup). The construct
476 < \multivoice { ....} { .... } >
478 creates horizontal parts which behave independently. You will have to
479 set voicegroup features by hand (\stem and \hshift. See examples)
486 Rhythms in Mudela are entered identical to Simple mudela.
487 The melodic part of the information is ignored.
491 A duration always starts with the duration type (1,2,4 etc), and then
492 any optional multipliers/dots
494 =head2 Meters/groupings
496 A meter has this form:
500 Rhythmic grouping is a concept closely associated with this. For
501 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
506 You can start the piece with a partial measure, the command takes the
507 same syntax as grouping:
511 Make the piece start with a partial measure [transl?] lasting 1 3/4
514 These commands are also "voice elements", and constitute simple mudela
515 (consisting of stuff with duration 0).
519 In concrete, a piece of Mudela has the following structure:
521 % declare pieces of music:
522 melody = \music{ <simple mudela> }
523 accompany = \music{ <simple mudela> }
525 % instantiate (=create tex, midi output) the score:
527 \staff{ melodicregs melody }
528 \staff{ melodicregs accompany }
529 \midi{ <midi definitions> }
530 \paper{ <paper and layout definitions> }
535 Examples are included with the GNU LilyPond distribution. For the sake of
536 maintenance no long examples are included in this document.
540 The staff is a simple container (containing Voices). The so-called
541 "registers" determine the characteristics of the Staff. At this time,
542 LilyPond supports the following personalities:
548 This makes the staff into a single five line melodic staff.
552 This makes the staff into a staff which will only set Lyric_requests.
560 This language has a number of roots. First and foremost, GNU LilyPond's
561 predecessor mpp was the inspiration of simple Mudela. Secondly, the
562 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
563 that I've written as a hobby project. ), which in turn owes a lot to
566 Now, we know, musictypesetting and raytracing do not necessarily
567 require the same input format, and we know that a lot more ways exist
568 to convert music to ASCII, but we did give this language some
569 thoughts. As always suggestions are appreciated.