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}
10 \date{October 8, 1997}
14 \def\interexample{\par Produces the following:\par}
15 \def\preexample{\par\medskip}
16 \def\postexample{\par\medskip}
17 \def\file#1{{\texttt{#1}}}
19 \emph{This document is not complete yet}
21 \section{Introduction}
23 This document describes the the GNU LilyPond input format, which is an
24 effective language for defining music. We call this language (rather
25 arrogantly) The Musical Definition Language or Mudela, for
26 short.\footnote{If anybody comes up with a better name, we'd gladly
27 take this. Gourlay already uses Musical Description Language,
28 G-Sharp Score Definition Language. ISO standard 10743 defines a
29 Standard Music Description Language. We're not being original here}
31 The first aim of Mudela is to define a piece of music, being complete
32 from both from a musical typesetting, as from a musical performing
35 The Musical Definition Language (Mudela), has a logical structure,
36 making use of identifiers, that allows for flexible input, and
37 definition reuse. See \file{MANIFESTO} for reasons and design considerations.
39 The below included for explanatory purposes only (i.e., for a complete
40 and up-to-date definition, see \file{lily/parser.y} and
43 As a related note, you should take a look at the examples and the init
44 files, as this document does not cover every aspect of mudela yet, and
45 may be out of date.\footnote{Ok, I am being pessimistic here. This
46 just is a disclaimer. Docs usually are written after the program
47 itself.} This document intends to give an idea of how it works, it
48 is not a guide on how to use it.
51 \section{Basic elements}
55 The de-facto extension of Mudela is \file{.ly}. Files may be included by
56 entering \verb+\include+ at the start of a line:
65 Line comments are introduced by a
67 Block comments are delimited
76 Occasionally, small changes in syntax across different versions of
77 Mudela might give syntax errors. To warn you about possible
78 incompatibilities, you can specify the Mudela version for which the
79 inputfile was written,
84 A perl-script which tries to convert to newer versions
85 (\file{convert-mudela}) is included in the LilyPond distribution.
89 Keywords are preceded by a backslash: \verb+\+. They contain
90 alphabetic characters only.
92 Identifiers in their normal form consist start with a backslash, a
93 alpha character, followed by alpha-numerics. Identifiers can contain
94 any characters (except whitespace,
95 and \verb+%+), if you use this construct:
98 \$i'm_a_weird!!!identifier
101 (which is the identifier with the name
102 \verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
103 characters which are not whitespace, \verb+$+ and \verb+%+.
104 \verb+$i'm_a_weird!!!string+
105 \def\foobar{$} % silly fontlock mode
107 \subsection{Nesting characters}
109 Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
110 structures. For chords the \verb+<+ and the \verb+>+ are used as
113 \subsection{Constants}
115 Please note that -.5 is not a Real.
124 \subsection{Identifiers}
126 When assigning identifiers you use
132 If you reuse identifiers, then the previous contents will be thrown
133 away after the right hand is evaluated, eg
135 bla = \melodic { \bla }
139 When using identifiers they have to be escaped:
142 oboe = \melodic { ... }
143 \score{ \melodic { \oboe }}
146 The left-hand part of the assignment is really a string, so
148 "Foo bar 4 2 " = \melodic { .. }
151 is also a valid assignment (but you would have trouble referencing to it)
154 \subsection{Hierarchical structures}
156 The general structure consists of declarations:
165 \TYPE{ <type specific data> }
168 (Currently, \verb+\score+ is the only type that can be instantiated
169 at top level. Currently declarations can only be done at top level)
171 Most instantiations that use an IDENTIFIER are specified as follows:
174 \TYPE{ IDENTIFIER [...] }
177 Some exceptions on this rule have been made to prevent inputting
178 Mudela becoming tedious
183 To simplify different aspects of music definition (entering the notes
184 and manipulating them) Mudela has a number of different input "modes":
191 At the start of parsing, Mudela assumes normal mode.
192 In Normal mode, a word is looked up in the following order:
194 \item{\verb+word+} string
195 \item{\verb|"string"|} string
196 \item{\verb|\word|} keyword, identifier
198 In normal mode, a word is assumed to start with an alphabetic
199 character, followed by alpha-numeric characters.
201 \item[Note mode] Note mode is introduced by the keyword
202 \verb+\melodic+. In Note mode, a word is looked up in the following
205 \item{\verb+word+} notename, string
206 \item{\verb|"string"|} string
207 \item{\verb|\word|} keyword, identifier
210 In Note mode a word is considered to have alphabetic characters only,
211 so the underscore (\_) is illegal. If you accidently mistype a
212 notename, the parser will assume that you are entering a string (and
213 it will most likely complain that you should be in \verb|\lyrics| mode to
217 \item[Lyric mode] Lyrics mode (and thus Simple mudela) is introduced
218 by the keyword \verb+\lyrics+. Because of the various control
219 characters that can appear in lyrics, eg, ``foreign language''
220 accents, the inputting a string containing these has been made very
223 In Lyrics mode, a word is looked up in the following order:
225 \item{\verb+word+} string (thus a lyric)
226 \item{\verb|"string"|} string
227 \item{\verb|\word|} keyword, identifier
230 In Lyric mode every sequence of non-digit and non-white characters
231 starting with an alphabetic character or the \_ is considered a word.
234 a&@&@&TSI|{[ % a word
235 1THtrhortho % not a "word"
236 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
237 _ _ _ _ % 4 words: 4 spaces
241 These modes are of a lexical nature. Normal and Note mode largely
242 resemble each other, save the possibility of entering Reals,
243 meaning of \verb+_+ and the resolution of words
247 You enter a note by giving the name and the reciprocal of the duration:
249 \begin[fragment,verbatim]{mudela}
253 is a A-1 pitched crotchet. The ' signifies an octave change. A-1 is 440
254 Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
256 \begin[fragment,verbatim]{mudela}
259 A % 110, uppercase octavates down
265 The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
266 signifies that this note is part of a triplet (3 in stead of 2). The
267 duration is one and a half quarter note (\verb+4.+) times 2/3.
269 Notenames are just a special kind of identifiers, and can be declared
270 for any language appropriate (see \file{init/dutch.ly}). The default language
271 for notenames is defined to be Dutch. In Dutch, the notenames are
272 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
273 flats by adding ``es''
277 cisis disis eisis fisis gisis aisis bisis
279 cis dis eis fis gis ais bis
283 ces des es fes ges as bes
285 ceses deses eses feses geses ases beses
288 Rests are named r or s
291 s % a "space" rest, nothing is printed.
294 These notenames along with duration are enough material to construct
297 \begin[verbatim,fragment]{mudela}
303 Music is able to express more. generally speaking, the other
304 'features' are either connected between notes (slurs, beams: spanning
305 requests) or attached to notes (eg. accents). The former are
306 implemented as START and STOP stop features and then attached to the note.
309 \item{[ and ]} start and stop a beam
310 \item{( and )} start and stop a slur
314 \begin[verbatim,fragment]{mudela}
317 e8(] [)g8 <c'8] e'8> % NO nesting!
318 [2/3 c8 c8 c8]1/1 % a triplet
321 Please note that these two characters do \emph{not} necessarrily nest,
322 they should be attached to the note. For this reason, the construct
323 \verb+[ <c4 c4>]+ will generate a parse error.
325 \subsection{Slurs and Ties}
327 Ties connect the noteheads of adjacent notes. They are entered as follows:
329 \begin[verbatim,fragment]{mudela}
333 Slurs connect whole chords, and try to avoid crossing stems. They are
336 \begin[verbatim,fragment]{mudela}
342 Symbols which can be put at either side (above or below) of a staff
343 are entered as follows:
344 \begin[verbatim,fragment]{mudela}
345 a-^ % marcato, direction: default
346 %a^- % portato, direction: above note
347 a_. % staccato, direction: below note
348 a^\fermata % predefined identifier
349 c_"marcato" % add a text
354 If you want to define your own scripts refer to \file{init/script.ly} for
358 Dynamics can be put after the notename:
360 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
363 Mudela defines the following dynamic identifiers:
366 ppp pp p mp mf f ff fff sfz fz fp
368 and the following abbreviations:
371 \> % start decrescendo
372 \! % end crescendo/decrescendo
375 \subsection{Defaults}
377 If omit the duration of a note, a default value is substituted. For
378 this default value mudela uses the last duration explicitly entered.
380 Thus the following inputs are equivalent
382 c4 c4 c16 c16 c16 s16 c4 c16
383 c4 c c16 c c c c4 c16
386 If you are typing music which does not lie in the "small" and "large"
387 octave, you can prevent having to type \verb+'+ all the time by using the
388 \verb+\octave+ command: These two lines have the same pitch.
390 c'' d'' e'' c d e c d e
391 \octave c''; c d e ''c ''d ''e \octave c; c d e
394 By default the setting of \verb+\octave+ is 0.
398 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
401 All syllables are entered separately, separated by whitespace
403 Twin-4 kle4 twin-4 kle4 ...
406 Two syllables or words that compose a single
407 duration entry are bound together using an underscore
412 \section{Composition: forming bigger structures}
414 The previous examples tacitly assumed that a sequence of notes is
415 printed in a left to right manner. This is not entirely correct, you
416 will get the bigger picture in this section.
418 In mathematics you can form expressions by combining expressions,
419 which are ultimately some kind of atom or terminal symbol. The same
420 goes for mudela: there are some basic building blocks, and by
421 combining those you create complex music.
423 You can combine music in three ways:
425 \item If you enclose a sequence of music-elements in braces ( \verb+{+
426 and \verb+}+ ), then you form another kind of music called (Voice) with those pieces.
427 The duration of the Voice is the sum of the durations of its elements
429 { c c g g a a g2 } % twinkle twinkle
430 { { c c g g} { a a g2 } }
432 \item You can stack music by enclosing a sequence of music elements
433 with \verb+<+ and \verb+>+. This is called a Chord. The duration of a Chord is
434 the union of the durations of its elements Example:
436 <a4 {cis8 cis8} e'4> % a-major chord
439 You can form music by transposing music:
442 d % from c to the d that's one octave down
443 { e4 f4 } % the horizontal music
447 Of course you can also combine these three mechanisms.
449 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
452 The basic building block in Mudela is called Request. Examples of
453 Requests are: Timing (such as Meter), Rhythmic, Melodic, Note (which is a combination of
454 Rhythmic and Melodic), Musicscript (put an accent over a note or
455 rest), etc. For the actual up to date listing, you should consult the
456 LilyPond source code: the Request types form a big class hierarchy.
458 Normally you don't enter Requests directly, since that would be
459 tedious. Mudela has standard abbreviations for the most common
460 combination of Requests. If you enter \verb+c4+, this is an
465 notename: 0 acc: 0 oct: -1
474 The \verb+Request_chord+ is a special kind of chord which only allows
475 Requests as its elements. The examples of the previous section were
476 processed with \verb+{+ and \verb+}+ enclosing the input.
478 \subsection{Durations}
480 A duration always starts with the duration type (1,2,4 etc), and then
481 any optional multipliers/dots
483 \subsection{Meters/groupings}
485 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:
502 Make the piece start with a upstep [english translation?]
503 lasting 1 3/4 quarter notes.
505 These commands are also "voice elements", and constitute ``Music''
506 (consisting of stuff with duration 0).
509 \subsection{Voicegroups}
514 If more than one "voice" is in a staff, then you have the option of
515 putting the different voices into so called voicegroups: members of
516 the same voicegroup share certain characteristics, among others:
523 For the actual list, see the init file \file{init/register.ly}
525 Putting different musical lines in to the same voicegroup effectively
526 makes LilyPond try to form chords of all those lines. Putting
527 different musical lines in to different voicegroups effectively makes
528 LilyPond try to set those lines as independently as possible.
530 [adsolete. Has to be fixed in lily]
532 You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
543 oboeII = \melodic { \group "oboes";
551 melodicregs \melodic{ oboeI }
556 In this example, the two oboe voices share one staff and are initially
557 in the voicegroup called "oboes". They will share beams, dynamics etc.
558 After two quarter notes, oboeI "pushes" its group: a new voicegroup is
559 created, called "oboes+solo". The \verb+\group "-"+ command makes the
560 voice enter "oboes" again.
562 Please do note that [] are voicegroup wide; the previous input is
563 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
564 voicegroup "oboes", albeit not in oboeI but oboeII
566 This concept may seem contorted, but it allows you to set the separate
567 oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
568 you edit the [] in the example.)
572 < { .... } {......} >
574 makes a chord (all horizontal parts are in the same voicegroup). The construct
576 \multi 2 < { ....} { .... } >
578 creates horizontal parts which behave independently. You will have to
579 set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
583 \multi 3 < { ....} { .... } >
585 creates a chord with each part in a different staff
588 \subsection{Examples}
590 Examples are included with the GNU LilyPond distribution. For the sake of
591 maintenance no long examples are included in this document.
596 This language has a number of roots. First and foremost, GNU
597 LilyPond's predecessor mpp was the inspiration of the Note-mode input.
598 Secondly, the hierarchical structure looks a lot like Rayce's (Rayce
599 is a raytracer that I've written as a hobby project. ), which in turn
600 owes a lot to POVRay.
602 Now, we know, musictypesetting and raytracing do not necessarily
603 require the same input format, and we know that a lot more ways exist
604 to convert music to ASCII, but we did give this language some
605 thoughts. As always suggestions are appreciated.