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 \emph{This document is not complete yet}
20 \section{Introduction}
22 This document describes the the GNU LilyPond input format, which is an
23 effective language for defining music. We call this language (rather
24 arrogantly) The Musical Definition Language or Mudela, for
25 short.\footnote{If anybody comes up with a better name, we'd gladly
26 take this. Gourlay already uses Musical Description Language,
27 G-Sharp Score Definition Language. We're not being original here}
29 The first aim of Mudela is to define a piece of music, being complete
30 from both from a musical typesetting, as from a musical performing
33 The Musical Definition Language (Mudela), has a logical structure,
34 making use of identifiers, that allows for flexible input, and
35 definition reuse. See \file{MANIFESTO} for reasons and design considerations.
37 The below included for explanatory purposes only (i.e., for a complete
38 and up-to-date definition, see \file{lily/parser.y} and
41 As a related note, you should take a look at the examples and the init
42 files, as this document does not cover every aspect of mudela yet, and
46 \section{Basic elements}
50 The de-facto extension of Mudela is \file{.ly}. Files may be included by
51 entering \verb+include+ at the start of a line:
60 Line comments are introduced by a
62 Block comments are delimited
71 Occasionally, small changes in syntax across different versions of
72 Mudela might give syntax errors. To warn you about possible
73 incompatibilities, you can specify the Mudela version for which the
74 inputfile was written,
79 A perl-script which tries to convert to newer versions
80 (\file{convert-mudela}) is included in the LilyPond distribution.
84 Keywords are preceded by a backslash: \verb+\+. They contain
85 alphabetic characters only.
87 Identifiers in their normal form consist start with a backslash, a
88 alpha character, followed by alpha-numerics. Identifiers can contain
89 any characters (except whitespace,
90 \verb+$+ and \verb+%+), if you use this
94 \$i'm_a_weird!!!identifier
97 (which is the identifier with the name
98 \verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
99 characters which are not whitespace, \verb+$+ and \verb+%+.
100 \verb+$i'm_a_weird!!!string+
102 \subsection{Nesting characters}
104 Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
105 structures. For chords the \verb+<+ and the \verb+>+ are used as
108 \subsection{Constants}
110 Please note that -.5 is not a Real.
119 \subsection{Identifiers}
121 When assigning identifiers you use
128 When using identifiers they have to be escaped:
131 oboe = \melodic { ... }
132 \score{ \melodic { \oboe }}
134 \subsection{Hierarchical structures}
136 The general structure consists of declarations:
145 \TYPE{ <type specific data> }
148 (Currently, \verb+\score+ is the only type that can be instantiated
149 at top level. Currently declarations can only be done at top level)
151 Most instantiations that use an IDENTIFIER are specified as follows:
154 \TYPE{ IDENTIFIER [...] }
157 Some exceptions on this rule have been made to prevent inputting
158 Mudela becoming tedious
163 To simplify different aspects of music definition (entering the notes
164 and manipulating them) Mudela has a number of different input "modes":
171 At the start of parsing, Mudela assumes normal mode.
172 In Normal mode, a word is looked up in the following order:
175 \word keyword, identifier
177 In normalmode, a word is assumed to start with an alphabetic
178 character, followed by alpha-numeric characters.
181 Note mode (and thus Simple mudela) is introduced by
182 the keyword \verb+\melodic+. In Note mode, a word is looked up in
186 word notename, string
187 \word keyword, identifier
189 In Note mode a word is considered to have alphabetic characters only.
192 Lyrics mode (and thus Simple mudela) is introduced by the keyword \verb+\lyrics+.
194 In Lyrics mode, a word is looked up in the following order:
198 \word keyword, identifier
201 In Lyric mode every sequence of non-digit and non-white characters
202 starting with an alphabetic character or the \_ is considered a word.
205 a&@&@&TSI|{[ % a word
206 1THtrhortho % not a "word"
207 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
208 _ _ _ _ % 4 words: 4 spaces
212 These modes are of a lexical nature. Normal and Note mode largely
213 resemble each other, save the possibility of entering Reals,
214 meaning of \verb+_+ and the resolution of words
218 You enter a note by giving the name and the reciprocal of the duration:
220 \begin[fragment,verbatim]{mudela}
224 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
225 Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
227 \begin[fragment,verbatim]{mudela}
230 A % 110, uppercase octavates down
236 The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
237 signifies that this note is part of a triplet (3 in stead of 2). The
238 duration is one and a half quaver (\verb+4.+) times 2/3.
240 Notenames are just a special kind of identifiers, and can be declared
241 for any language appropriate (see \file{init/dutch.ly}). The default language
242 for notenames is defined to be dutch. In dutch, the notenames are
243 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
244 flats by adding ``es''
248 cisis disis eisis fisis gisis aisis bisis
250 cis dis eis fis gis ais bis
254 ces des es fes ges as bes
256 ceses deses eses feses geses ases beses
259 Rests are named r or s
262 s % a "space" rest, nothing is printed.
265 These notenames along with duration are enough material to construct
268 \begin[verbatim,fragment]{mudela}
274 Music is able to express more. generally speaking, the other
275 'features' are either connected between notes (slurs, beams: spanning
276 requests) or attached to notes (eg. accents). The former are
277 implemented as START and STOP stop features and then attached to the note.
285 \begin[verbatim,fragment]{mudela}
288 e8(] [)g8 <c'8] e'8> % NO nesting!
289 [2/3 c8 c8 c8]1/1 % a triplet
292 Please note that these two characters do \emph{not} necessarrily nest,
293 they should attached to the note \verb+[ <c4 c4>]+ will generate a parse
294 error for this reason.
296 \subsection{Slurs and Ties}
298 Ties connect the noteheads of adjacent notes. They are entered as follows:
300 \begin[verbatim,fragment]{mudela}
304 Slurs connect whole chords, and try to avoid crossing stems. They are
307 \begin[verbatim,fragment]{mudela}
313 Symbols which can be put at either side (above or below) of a staff
314 are entered as follows:
315 \begin[verbatim,fragment]{mudela}
316 a-^ % marcato, direction: default
317 a^- % portato, direction: above note
318 a_. % staccato, direction: below note
319 a^\fermata % predefined identifier
320 c_"marcato" % add a text
325 If you want to define your own scripts refer to \file{init/script.ly} for
329 Dynamics can be put after the notename:
331 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
334 Mudela defines the following dynamic identifiers:
337 ppp pp p mp mf df ff fff % df iso f, f is a notename.
339 and the following abbreviations:
342 \> % start decrescendo
343 \! % end crescendo/decrescendo
346 \subsection{Defaults}
348 If omit the duration of a note, a default value is substituted. For
349 this default value mudela uses the last duration explicitly entered.
351 Thus the following inputs are equivalent
353 c4 c4 c16 c16 c16 s16 c4 c16
354 c4 c c16 c c c c4 c16
357 If you are typing music which does not lie in the "small" and "large"
358 octave, you can prevent having to type \verb+'+ all the time by using the
359 \verb+\octave+ command: These two lines have the same pitch.
361 c'' d'' e'' c d e c d e
362 \octave c''; c d e ''c ''d ''e \octave c; c d e
365 By default the setting of \verb+\octave+ is 0.
369 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
372 All syllables are entered separately, separated by whitespace
374 Twin-4 kle4 twin-4 kle4 ...
377 Two syllables or words that compose a single
378 duration entry are bound together using an underscore
383 \section{Composition: forming bigger structures}
385 The previous examples tacitly assumed that a sequence of notes is
386 printed in a left to right manner. This is not entirely correct, you
387 will get the bigger picture in this section.
389 In mathematics you can form expressions by combining expressions,
390 which are ultimately some kind of atom or terminal symbol. The same
391 goes for mudela: there are some basic building blocks, and by
392 combining those you create complex music.
394 You can combine music in three ways:
396 \item If you enclose a sequence of music-elements in braces ( \verb+{+
397 and \verb+}+ ), then you form another kind of music called (Voice) with those pieces.
398 The duration of the Voice is the sum of the durations of its elements
400 { c c g g a a g2 } % twinkle twinkle
401 { { c c g g} { a a g2 } }
403 \item You can stack music by enclosing a sequence of music elements
404 with \verb+<+ and \verb+>+. This is called a Chord. The duration of a Chord is
405 the union of the durations of its elements Example:
407 <a4 {cis8 cis8} e'4> % a-major chord
410 You can form music by transposing music:
413 d % from c to the d that's one octave down
414 { e4 f4 } % the horizontal music
418 Of course you can also combine these three mechanisms.
420 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
423 The basic building block in Mudela is called Request. Examples of
424 Requests are: Timing (such as Meter), Rhythmic, Melodic, Note (which is a combination of
425 Rhythmic and Melodic), Musicscript (put an accent over a note or
426 rest), etc. For the actual up to date listing, you should consult the
427 LilyPond source code: the Request types form a big class hierarchy.
429 Normally you don't enter Requests directly, since that would be
430 tedious. Mudela has standard abbreviations for the most common
431 combination of Requests. If you enter \verb+c4+, this is an
436 notename: 0 acc: 0 oct: -1
445 The \verb+Request_chord+ is a special kind of chord which only allows
446 Requests as its elements. The examples of the previous section were
447 processed with \verb+{+ and \verb+}+ enclosing the input.
450 \subsection{Voicegroups}
452 If more than one "voice" is in a staff, then you have the option of
453 putting the different voices into so called voicegroups: members of
454 the same voicegroup share certain characteristics, among others:
461 For the actual list, see the init file \file{init/register.ly}
463 Putting different musical lines in to the same voicegroup effectively
464 makes LilyPond try to form chords of all those lines. Putting
465 different musical lines in to different voicegroups effectively makes
466 LilyPond try to set those lines as independently as possible.
468 [adsolete. Has to be fixed in lily]
470 You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
480 oboeII = \melodic { \group "oboes";
488 melodicregs \melodic{ oboeI }
493 In this example, the two oboe voices share one staff and are initially
494 in the voicegroup called "oboes". They will share beams, dynamics etc.
495 After two quavers, oboeI "pushes" its group: a new voicegroup is
496 created, called "oboes+solo". The \verb+\group "-"+ command makes the
497 voice enter "oboes" again.
499 Please do note that [] are voicegroup wide; the previous input is
500 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
501 voicegroup "oboes", albeit not in oboeI but oboeII
503 This concept may seem contorted, but it allows you to set the separate
504 oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
505 you edit the [] in the example.)
509 < { .... } {......} >
511 makes a chord (all horizontal parts are in the same voicegroup). The construct
513 < \multi 2; { ....} { .... } >
515 creates horizontal parts which behave independently. You will have to
516 set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
520 < \multi 3; { ....} { .... } >
522 creates a chord with each part in a different staff
525 \subsection{Durations}
527 A duration always starts with the duration type (1,2,4 etc), and then
528 any optional multipliers/dots
530 \subsection{Meters/groupings}
532 A meter has this form:
537 Rhythmic grouping is a concept closely associated with this. For
538 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
543 You can start the piece with a partial measure, the command takes the
544 same syntax as grouping:
549 Make the piece start with a partial measure [english translation?]
550 lasting 1 3/4 quaver.
552 These commands are also "voice elements", and constitute simple mudela
553 (consisting of stuff with duration 0).
555 \subsection{Examples}
557 Examples are included with the GNU LilyPond distribution. For the sake of
558 maintenance no long examples are included in this document.
563 This language has a number of roots. First and foremost, GNU LilyPond's
564 predecessor mpp was the inspiration of simple Mudela. Secondly, the
565 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
566 that I've written as a hobby project. ), which in turn owes a lot to
569 Now, we know, musictypesetting and raytracing do not necessarily
570 require the same input format, and we know that a lot more ways exist
571 to convert music to ASCII, but we did give this language some
572 thoughts. As always suggestions are appreciated.