3 % this document should be run through the mudela-book script after lilypond
6 \documentclass{article}
8 \title{GNU LilyPond input format 0.1}
9 \author{Han-Wen Nienhuys}
13 \def\interexample{\par Produces the following:\par}
14 \def\preexample{\par\medskip}
15 \def\postexample{\par\medskip}
16 \def\file#1{{\texttt{#1}}}
18 \section{Introduction}
20 This document describes the the GNU LilyPond input format, which is an
21 effective language for defining music. We call this language (rather
22 arrogantly) The Musical Definition Language or Mudela, for
23 short.\footnote{If anybody comes up with a better name, we'd gladly
24 take this. Gourlay already uses Musical Description Language,
25 G-Sharp Score Definition Language. We're not being original here}
27 The first aim of Mudela is to define a piece of music,
28 being complete from both from a musical typesetting,
29 as from a musical performing point of view.
31 The Musical Definition Language (Mudela), has a logical structure,
32 making use of identifiers, that allows for flexible input, and
33 definition reuse. See MANIFESTO for reasons and design considerations.
35 The below included for explanatory purposes only (i.e., for a complete
36 and up-to-date definition, see \file{lily/parser.y} and
39 As a related note, you should take a look at the examples and the init
40 files, as this document does not cover every aspect of mudela yet, and
44 \section{Basic elements}
48 The de-facto extension of Mudela is \file{.ly}. Files may be included by
49 entering \verb+include+ at the start of a line:
58 Line comments are introduced by a
60 Block comments are delimited
69 Occasionally, small changes in syntax across different versions of
70 Mudela might give syntax errors. To warn you about possible
71 incompatibilities, you can specify the Mudela version for which the
72 inputfile was written,
77 A perl-script which tries to convert to newer versions
78 (\file{convert-mudela}) is included in the LilyPond distribution.
82 Keywords are preceded by a backslash: \verb+\+. They contain
83 alphabetic characters only.
85 Identifiers in their normal form consist start with a backslash, a
86 alpha character, followed by alpha-numerics. Identifiers can contain
87 any characters (except whitespace,
88 \verb+$+ and \verb+%+), if you use this
92 \$i'm_a_weird!!!identifier
95 (which is the identifier with the name
96 \verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
97 characters which are not whitespace, \verb+$+ and \verb+%+.
98 \verb+$i'm_a_weird!!!string+
100 \subsection{Nesting characters}
102 Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
103 structures. For chords the \verb+<+ and the \verb+>+ are used as
106 \subsection{Constants}
108 Please note that -.5 is not a Real.
117 \subsection{Identifiers}
119 When assigning identifiers you use
126 When using identifiers they have to be escaped:
129 oboe = \melodic { ... }
130 \score{ \melodic { \oboe }}
132 \subsection{Hierarchical structures}
134 The general structure consists of declarations:
143 \TYPE{ <type specific data> }
146 (Currently, \verb+\score+ is the only type that can be instantiated
147 at top level. Currently declarations can only be done at top level)
149 Most instantiations that use an IDENTIFIER are specified as follows:
152 \TYPE{ IDENTIFIER [...] }
155 Some exceptions on this rule have been made to prevent inputting
156 Mudela becoming tedious
161 To simplify different aspects of music definition (entering the notes
162 and manipulating them) Mudela has a number of different input "modes":
169 At the start of parsing, Mudela assumes normal mode.
170 In Normal mode, a word is looked up in the following order:
173 \word keyword, identifier
175 In normalmode, a word is assumed to start with an alphabetic
176 character, followed by alpha-numeric characters.
179 Note mode (and thus Simple mudela) is introduced by
180 the keyword \verb+\melodic+. In Note mode, a word is looked up in
184 word notename, string
185 \word keyword, identifier
187 In Note mode a word is considered to have alphabetic characters only.
190 Lyrics mode (and thus Simple mudela) is introduced by the keyword \verb+\lyrics+.
192 In Lyrics mode, a word is looked up in the following order:
196 \word keyword, identifier
199 In Lyric mode every sequence of non-digit and non-white characters
200 starting with an alphabetic character or the \_ is considered a word.
203 a&@&@&TSI|{[ % a word
204 1THtrhortho % not a "word"
205 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
206 _ _ _ _ % 4 words: 4 spaces
210 These modes are of a lexical nature. Normal and Note mode largely
211 resemble each other, save the possibility of entering Reals,
212 meaning of \verb+_+ and the resolution of words
216 You enter a note by giving the name and the reciprocal of the duration:
218 \begin[fragment,verbatim]{mudela}
222 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
223 Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
225 \begin[fragment,verbatim]{mudela}
228 A % 110, uppercase octavates down
234 The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
235 signifies that this note is part of a triplet (3 in stead of 2). The
236 duration is one and a half quaver (\verb+4.+) times 2/3.
238 Notenames are just a special kind of identifiers, and can be declared
239 for any language appropriate (see \file{init/dutch.ly}). The default language
240 for notenames is defined to be dutch. In dutch, the notenames are
241 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
242 flats by adding ``es''
246 cisis disis eisis fisis gisis aisis bisis
248 cis dis eis fis gis ais bis
252 ces des es fes ges as bes
254 ceses deses eses feses geses ases beses
257 Rests are named r or s
260 s % a "space" rest, nothing is printed.
263 These notenames along with duration are enough material to construct
266 \begin[verbatim,fragment]{mudela}
272 Music is able to express more. generally speaking, the other
273 'features' are either connected between notes (slurs, beams: spanning
274 requests) or attached to notes (eg. accents). The former are
275 implemented as START and STOP stop features and then attached to the note.
283 \begin[verbatim,fragment]{mudela}
286 e8(] [)g8 <c'8] e'8> % NO nesting!
287 [2/3 c8 c8 c8]1/1 % a triplet
290 Please note that these two characters do \emph{not} necessarrily nest,
291 they should attached to the note \verb+[ <c4 c4>]+ will generate a parse
292 error for this reason.
294 \subsection{Slurs and Ties}
296 Ties connect the noteheads of adjacent notes. They are entered as follows:
298 \begin[verbatim,fragment]{mudela}
302 Slurs connect whole chords, and try to avoid crossing stems. They are
305 \begin[verbatim,fragment]{mudela}
311 Symbols which can be put at either side (above or below) of a staff
312 are entered as follows:
313 \begin[verbatim,fragment]{mudela}
314 a-^ % marcato, direction: default
315 a^- % portato, direction: above note
316 a_. % staccato, direction: below note
317 a^\fermata % predefined identifier
318 c_"marcato" % add a text
323 If you want to define your own scripts refer to \file{init/script.ly} for
327 Dynamics can be put after the notename:
329 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
332 Mudela defines the following dynamic identifiers:
335 ppp pp p mp mf df ff fff % df iso f, f is a notename.
337 and the following abbreviations:
340 \> % start decrescendo
341 \! % end crescendo/decrescendo
344 \subsection{Defaults}
346 If omit the duration of a note, a default value is substituted. For
347 this default value mudela uses the last duration explicitly entered.
349 Thus the following inputs are equivalent
351 c4 c4 c16 c16 c16 s16 c4 c16
352 c4 c c16 c c c c4 c16
355 If you are typing music which does not lie in the "small" and "large"
356 octave, you can prevent having to type \verb+'+ all the time by using the
357 \verb+\octave+ command: These two lines have the same pitch.
359 c'' d'' e'' c d e c d e
360 \octave c''; c d e ''c ''d ''e \octave c; c d e
363 By default the setting of \verb+\octave+ is 0.
367 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
370 All syllables are entered separately, separated by whitespace
372 Twin-4 kle4 twin-4 kle4 ...
375 Two syllables or words that compose a single
376 duration entry are bound together using an underscore
381 \section{Composition: forming bigger structures}
383 The previous examples tacitly assumed that a sequence of notes is
384 printed in a left to right manner. This is not entirely correct, you
385 will get the bigger picture in this section.
387 In mathematics you can form expressions by combining expressions,
388 which are ultimately some kind of atom or terminal symbol. The same
389 goes for mudela: there are some basic building blocks, and by
390 combining those you create complex music.
392 You can combine music in three ways:
394 \item If you enclose a sequence of music-elements in braces ( \verb+{+
395 and \verb+}+ ), then you form another kind of music called (Voice) with those pieces.
396 The duration of the Voice is the sum of the durations of its elements
398 { c c g g a a g2 } % twinkle twinkle
399 { { c c g g} { a a g2 } }
401 \item You can stack music by enclosing a sequence of music elements
402 with \verb+<+ and \verb+>+. This is called a Chord. The duration of a Chord is
403 the union of the durations of its elements Example:
405 <a4 {cis8 cis8} e'4> % a-major chord
408 You can form music by transposing music:
411 d % from c to the d that's one octave down
412 { e4 f4 } % the horizontal music
416 Of course you can also combine these three mechanisms.
418 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
421 The basic building block in Mudela is called Request. Examples of
422 Requests are: Timing (such as Meter), Rhythmic, Melodic, Note (which is a combination of
423 Rhythmic and Melodic), Musicscript (put an accent over a note or
424 rest), etc. For the actual up to date listing, you should consult the
425 LilyPond source code: the Request types form a big class hierarchy.
427 Normally you don't enter Requests directly, since that would be
428 tedious. Mudela has standard abbreviations for the most common
429 combination of Requests. If you enter \verb+c4+, this is an
434 notename: 0 acc: 0 oct: -1
443 The \verb+Request_chord+ is a special kind of chord which only allows
444 Requests as its elements. The examples of the previous section were
445 processed with \verb+{+ and \verb+}+ enclosing the input.
448 \subsection{Voicegroups}
450 If more than one "voice" is in a staff, then you have the option of
451 putting the different voices into so called voicegroups: members of
452 the same voicegroup share certain characteristics, among others:
459 For the actual list, see the init file \file{init/register.ly}
461 Putting different musical lines in to the same voicegroup effectively
462 makes LilyPond try to form chords of all those lines. Putting
463 different musical lines in to different voicegroups effectively makes
464 LilyPond try to set those lines as independently as possible.
466 [adsolete. Has to be fixed in lily]
468 You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
478 oboeII = \melodic { \group "oboes";
486 melodicregs \melodic{ oboeI }
491 In this example, the two oboe voices share one staff and are initially
492 in the voicegroup called "oboes". They will share beams, dynamics etc.
493 After two quavers, oboeI "pushes" its group: a new voicegroup is
494 created, called "oboes+solo". The \verb+\group "-"+ command makes the
495 voice enter "oboes" again.
497 Please do note that [] are voicegroup wide; the previous input is
498 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
499 voicegroup "oboes", albeit not in oboeI but oboeII
501 This concept may seem contorted, but it allows you to set the separate
502 oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
503 you edit the [] in the example.)
507 < { .... } {......} >
509 makes a chord (all horizontal parts are in the same voicegroup). The construct
511 < \multi 2; { ....} { .... } >
513 creates horizontal parts which behave independently. You will have to
514 set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
518 < \multi 3; { ....} { .... } >
520 creates a chord with each part in a different staff
523 \subsection{Durations}
525 A duration always starts with the duration type (1,2,4 etc), and then
526 any optional multipliers/dots
528 \subsection{Meters/groupings}
530 A meter has this form:
535 Rhythmic grouping is a concept closely associated with this. For
536 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
541 You can start the piece with a partial measure, the command takes the
542 same syntax as grouping:
547 Make the piece start with a partial measure [english translation?]
548 lasting 1 3/4 quaver.
550 These commands are also "voice elements", and constitute simple mudela
551 (consisting of stuff with duration 0).
553 \subsection{Examples}
555 Examples are included with the GNU LilyPond distribution. For the sake of
556 maintenance no long examples are included in this document.
561 This language has a number of roots. First and foremost, GNU LilyPond's
562 predecessor mpp was the inspiration of simple Mudela. Secondly, the
563 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
564 that I've written as a hobby project. ), which in turn owes a lot to
567 Now, we know, musictypesetting and raytracing do not necessarily
568 require the same input format, and we know that a lot more ways exist
569 to convert music to ASCII, but we did give this language some
570 thoughts. As always suggestions are appreciated.