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 =head2 Hierarchical structures
81 The general structure consists of declarations:
89 \TYPE{ <type specific data> }
91 (Currently, C<\score> is the only type that can be instantiated
92 at top level. Currently declarations can only be done at top level)
94 Most instantiations that use an IDENTIFIER are specified as follows:
96 \TYPE{ IDENTIFIER [...] }
98 Some exceptions on this rule have been made to prevent inputting
99 Mudela becoming tedious
104 The actual musical part of Mudela that defines a melody, is known as
107 Simple mudela is the most common type of music. It consists of a list
108 of notes or lyrics, chords, and commands.
112 To simplify different aspects of music definition (entering the notes
113 and manipulating them) Mudela has a number of different input "modes":
119 At the start of parsing, Mudela assumes normal mode.
120 In Normal mode, a word is looked up in the following order:
122 word identifier, string
123 \word keyword, identifier, string
125 In normalmode, a word is assumed to start with an alphabetic
126 character, followed by alpha-numeric characters.
130 Note mode (and thus Simple mudela) is introduced by the keyword C<\melodic>.
131 In Note mode, a word is looked up in the following order:
133 word notename, string
134 \word keyword, identifier, string
136 In Note mode a word is considered to have alphabetic characters only.
140 Lyrics mode (and thus Simple mudela) is introduced by the keyword C<\lyrics>.
142 In Lyrics mode, a word is looked up in the following order:
145 \word keyword, identifier, string
147 In Lyric mode every sequence of non-digit and non-white characters
148 starting with an alphabetic character or the '_'is considered a word.
150 a&@&@&TSI|{[ % a word
151 1THtrhortho % not a "word"
152 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
153 _ _ _ _ % 4 words: 4 spaces
157 These modes are of a lexical nature. Normal and Note mode largely
158 resemble each other, save the possibility of entering Reals,
159 meaning of C<_> and the resolution of words
163 Simple mudela basically is a sequence of the notes you want to
168 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
169 Hz concert-pitch. C<c'> is also known as the central c. More examples:
180 This is an A flat, (just below 110 Hz concert-pitch). The C<*2/3>
181 signifies that this note is part of a triplet (3 in stead of 2). The
182 duration is one and a half quaver (C<4.>) times 2/3.
185 Notenames are just a special kind of identifiers, and can be declared
186 for any language appropriate (see F<dutch.ini>). The default language
187 for notenames is defined to be dutch. In dutch, the notenames are
188 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
192 cisis disis eisis fisis gisis aisis bisis
194 cis dis eis fis gis ais bis
198 ces des es fes ges as bes
200 ceses deses eses feses geses ases beses
202 The standard notenames also have uppercase versions, which octavate
205 a % 220 concert-pitch
211 Rests are named r or s
214 s % a "space" rest, nothing is printed.
216 These notenames along with duration are enough material to construct
222 Music is able to express more. generally speaking, the other
223 'features' are either connected between notes (slurs, beams: spanning
224 requests) or attached to notes (eg. accents). The former are
225 implemented as START and STOP stop features and then attached to the note.
235 Please note that these two characters do I<not> necessarrily nest,
236 they should attached to the note C<[ {c4 c4} ]> will generate a parse
237 error for this reason.
239 [c8 e8(] [)g8 <c'8] e'8>
241 [c8 c8 c8]2/3 % a triplet
244 =head2 Slurs and Ties
246 Ties connect the noteheads of adjecent notes. They are entered as follows:
250 Slurs connect whole chords, and try to avoid crossing stems. They are
257 Symbols which can be put at either side (above or below) of a staff
258 are entered as follows:
260 a-^ % marcato, direction: default
261 a^- % portato, direction: above note
262 a_. % staccato, direction: below note
263 a^\script { "symbolindex" . . . } % see script.ini for details.
264 a^\fermata % predefined identifier
266 Dynamics can be put after the notename:
268 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
270 Mudela defines the following dynamic identifiers:
272 ppp pp p mp mf df ff fff % df iso f, f is a notename.
274 and the following abbreviations:
277 \> % start decrescendo
278 \! % end crescendo/decrescendo
282 To accompany a note with a text (eg, "marcato"), you should say:
288 the c- construct chooses the default up/down direction.
295 If omit the duration of a, a default value is substituted. For this
296 default value, there are two modes:
302 Use the last duration explicitly entered
306 Use the explicitly set "default duration"
310 Thus the following inputs are equivalent
312 c4 c4 c16 c16 c16 s16 c4 c16
315 c4 c c16 c c c c4 c16
318 c c c16 c16 c16 c16 c c16
323 If you are typing music which does not lie in the "small" and "large"
324 octave, you can prevent having to type C<'> all the time by using the
325 C<\octave> command: These two lines have the same pitch.
330 By default the setting of C<\octave> is 0.
334 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
337 All syllables are entered separately, separated by whitespace
339 Twin-4 kle4 twin-4 kle4 ...
341 Two syllables or words that compose a single
342 duration entry are bound together using an underscore
346 =head2 Music direction
348 Mudela reads left to right, but you can still stack voices and
349 Voice_elements which are produced in two directions: horizontal
350 (voice like) and vertical (chord like)
352 A sequence of notes (horizontal) is called simple horizontal, eg
357 You can also glue two pieces of simple horizontal music together with the
358 concatenation operator:
360 horOne = \melodic { c c g g }
361 horTwo = \melodic { a a g2 }
362 twinkle = \melodic { \horOne ++ \horTwo }
364 If you enclose simple horizontal music in braces ( { } ), then you get
367 { c c g g a a g2 } % twinkle twinkle
369 You can start vertical music (a "chord") by enclosing a sequence of
370 notes with < and >. Example:
372 <a cis e'> % a-major chord
374 You can also put vertical music inside horizontal music:
376 { c <c e> <c e g> <c e g c'> } % 4 increasing chords
382 {r2 r2 c c g g a a g2} > % a canon
384 The duration of a chord equals the union of the durations of each of
385 its elements. The C<\multivoice> is a construct which is explained
391 You can transpose horizontal music in the following way:
398 d % from c to the d that's one octave down
399 { e4 f4 } % the horizontal music
403 The result is, as you can see, again simple horizontal music.
408 If more than one "voice" is in a staff, then you have the option of
409 putting the different voices into so called voicegroups: members of
410 the same voicegroup share certain characteristics, among others:
417 For the actual list, see the init file F<register.ini>
419 Putting different musical lines in to the same voicegroup effectively
420 makes LilyPond try to form chords of all those lines. Putting
421 different musical lines in to different voicegroups effectively makes
422 LilyPond try to set those lines as independently as possible.
424 You can set the voicegroup of a voice with the command C<\group>, e.g.,
434 oboeII = \melodic { \group "oboes";
442 melodicregs \melodic{ oboeI }
446 In this example, the two oboe voices share one staff and are initially
447 in the voicegroup called "oboes". They will share beams, dynamics etc.
448 After two quavers, oboeI "pushes" its group: a new voicegroup is
449 created, called "oboes+solo". The C<\group "-"> command makes the
450 voice enter "oboes" again.
452 Please do note that [] are voicegroup wide; the previous input is
453 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
454 voicegroup "oboes", albeit not in oboeI but oboeII
456 This concept may seem contorted, but it allows you to set the separate
457 oboe parts without changing the C<oboeI> and C<oboeII> (assuming that
458 you edit the [] in the example.)
462 < { .... } {......} >
464 makes a chord (all horizontal parts are in the same voicegroup). The construct
466 < \multivoice { ....} { .... } >
468 creates horizontal parts which behave independently. You will have to
469 set voicegroup features by hand (\stem and \hshift. See examples)
476 Rhythms in Mudela are entered identical to Simple mudela.
477 The melodic part of the information is ignored.
481 A duration always starts with the duration type (1,2,4 etc), and then
482 any optional multipliers/dots
484 =head2 Meters/groupings
486 A meter has this form:
490 Rhythmic grouping is a concept closely associated with this. For
491 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
496 You can start the piece with a partial measure, the command takes the
497 same syntax as grouping:
501 Make the piece start with a partial measure [transl?] lasting 1 3/4
504 These commands are also "voice elements", and constitute simple mudela
505 (consisting of stuff with duration 0).
509 In concrete, a piece of Mudela has the following structure:
511 % declare pieces of music:
512 melody = \music{ <simple mudela> }
513 accompany = \music{ <simple mudela> }
515 % instantiate (=create tex, midi output) the score:
517 \staff{ melodicregs melody }
518 \staff{ melodicregs accompany }
519 \midi{ <midi definitions> }
520 \paper{ <paper and layout definitions> }
525 Examples are included with the GNU LilyPond distribution. For the sake of
526 maintenance no long examples are included in this document.
531 This chapter deals with the internals of Mudela. In the end Mudela
532 converted to Voice, which contain Voice_elements which (in turn)
533 contain Requests. The former 2 types are basically containers (lists).
534 Consider the following simple mudela
536 \music { c4 <e4 g4> }
538 After the parsing, this is converted to: (from the debug output)
541 voice_element { dur :1/4
542 Stem_req {duration { 4}}
543 Note_req {notename: 0 acc: 0 oct: -1
547 voice_element { dur :0
548 Terminate_voice_req {}
553 voice_element { dur :1/4
554 Stem_req {duration { 4}}
555 Note_req {notename: 2 acc: 0 oct: -1
559 voice_element { dur :0
560 Terminate_voice_req {}
565 voice_element { dur :1/4
566 Stem_req {duration { 4}}
567 Note_req {notename: 4 acc: 0 oct: -1
571 voice_element { dur :0
572 Terminate_voice_req {}
579 As you can see, most information is stored in the form of a request.
580 In music typesetting, the user might want to cram a lot more symbols
581 on the paper than actually fits. To reflect this idea (the user asks
582 more than we can do), the container for this data is called Request.
584 A request is done to the C<Staff> which contains the
585 C<Voice_element>. The staff decides whether to to honor the request,
586 ignore it, or merge it with other requests. Merging of requests is
587 preferably done with other requests done by members of the same
588 voicegroups (beams, brackets, stems)
592 The staff is a simple container (containing Voices). The so-called
593 "registers" determine the characteristics of the Staff. At this time,
594 LilyPond supports the following personalities:
600 This makes the staff into a single five line melodic staff.
604 This makes the staff into a staff which will only set Lyric_requests.
612 This language has a number of roots. First and foremost, GNU LilyPond's
613 predecessor mpp was the inspiration of simple Mudela. Secondly, the
614 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
615 that I've written as a hobby project. ), which in turn owes a lot to
618 Now, we know, musictypesetting and raytracing do not necessarily
619 require the same input format, and we know that a lot more ways exist
620 to convert music to ASCII, but we did give this language some
621 thoughts. As always suggestions are appreciated.