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. ISO standard 10743 defines a
28 Standard Music Description Language. We're not being original here}
30 The first aim of Mudela is to define a piece of music, being complete
31 from both from a musical typesetting, as from a musical performing
34 The Musical Definition Language (Mudela), has a logical structure,
35 making use of identifiers, that allows for flexible input, and
36 definition reuse. See \file{MANIFESTO} for reasons and design considerations.
38 The below included for explanatory purposes only (i.e., for a complete
39 and up-to-date definition, see \file{lily/parser.y} and
42 As a related note, you should take a look at the examples and the init
43 files, as this document does not cover every aspect of mudela yet, and
44 may be out of date.\footnote{Ok, I am being pessimistic here. This
45 just is a disclaimer. Docs usually are written after the program itself.}
48 \section{Basic elements}
52 The de-facto extension of Mudela is \file{.ly}. Files may be included by
53 entering \verb+\include+ at the start of a line:
62 Line comments are introduced by a
64 Block comments are delimited
73 Occasionally, small changes in syntax across different versions of
74 Mudela might give syntax errors. To warn you about possible
75 incompatibilities, you can specify the Mudela version for which the
76 inputfile was written,
81 A perl-script which tries to convert to newer versions
82 (\file{convert-mudela}) is included in the LilyPond distribution.
86 Keywords are preceded by a backslash: \verb+\+. They contain
87 alphabetic characters only.
89 Identifiers in their normal form consist start with a backslash, a
90 alpha character, followed by alpha-numerics. Identifiers can contain
91 any characters (except whitespace,
92 and \verb+%+), if you use this construct:
95 \$i'm_a_weird!!!identifier
98 (which is the identifier with the name
99 \verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
100 characters which are not whitespace, \verb+$+ and \verb+%+.
101 \verb+$i'm_a_weird!!!string+
103 \subsection{Nesting characters}
105 Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
106 structures. For chords the \verb+<+ and the \verb+>+ are used as
109 \subsection{Constants}
111 Please note that -.5 is not a Real.
120 \subsection{Identifiers}
122 When assigning identifiers you use
128 If you reuse identifiers, then the previous contents will be thrown
129 away after the right hand is evaluated, eg
131 bla = \melodic { \bla }
135 When using identifiers they have to be escaped:
138 oboe = \melodic { ... }
139 \score{ \melodic { \oboe }}
141 \subsection{Hierarchical structures}
143 The general structure consists of declarations:
152 \TYPE{ <type specific data> }
155 (Currently, \verb+\score+ is the only type that can be instantiated
156 at top level. Currently declarations can only be done at top level)
158 Most instantiations that use an IDENTIFIER are specified as follows:
161 \TYPE{ IDENTIFIER [...] }
164 Some exceptions on this rule have been made to prevent inputting
165 Mudela becoming tedious
170 To simplify different aspects of music definition (entering the notes
171 and manipulating them) Mudela has a number of different input "modes":
178 At the start of parsing, Mudela assumes normal mode.
179 In Normal mode, a word is looked up in the following order:
182 \word keyword, identifier
184 In normalmode, a word is assumed to start with an alphabetic
185 character, followed by alpha-numeric characters.
188 Note mode (and thus Simple mudela) is introduced by
189 the keyword \verb+\melodic+. In Note mode, a word is looked up in
193 word notename, string
194 \word keyword, identifier
196 In Note mode a word is considered to have alphabetic characters only.
199 Lyrics mode (and thus Simple mudela) is introduced by the keyword \verb+\lyrics+.
201 In Lyrics mode, a word is looked up in the following order:
205 \word keyword, identifier
208 In Lyric mode every sequence of non-digit and non-white characters
209 starting with an alphabetic character or the \_ is considered a word.
212 a&@&@&TSI|{[ % a word
213 1THtrhortho % not a "word"
214 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
215 _ _ _ _ % 4 words: 4 spaces
219 These modes are of a lexical nature. Normal and Note mode largely
220 resemble each other, save the possibility of entering Reals,
221 meaning of \verb+_+ and the resolution of words
225 You enter a note by giving the name and the reciprocal of the duration:
227 \begin[fragment,verbatim]{mudela}
231 is a A-1 pitched crotchet. The ' signifies an octave change. A-1 is 440
232 Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
234 \begin[fragment,verbatim]{mudela}
237 A % 110, uppercase octavates down
243 The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
244 signifies that this note is part of a triplet (3 in stead of 2). The
245 duration is one and a half quarter note (\verb+4.+) times 2/3.
247 Notenames are just a special kind of identifiers, and can be declared
248 for any language appropriate (see \file{init/dutch.ly}). The default language
249 for notenames is defined to be Dutch. In Dutch, the notenames are
250 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
251 flats by adding ``es''
255 cisis disis eisis fisis gisis aisis bisis
257 cis dis eis fis gis ais bis
261 ces des es fes ges as bes
263 ceses deses eses feses geses ases beses
266 Rests are named r or s
269 s % a "space" rest, nothing is printed.
272 These notenames along with duration are enough material to construct
275 \begin[verbatim,fragment]{mudela}
281 Music is able to express more. generally speaking, the other
282 'features' are either connected between notes (slurs, beams: spanning
283 requests) or attached to notes (eg. accents). The former are
284 implemented as START and STOP stop features and then attached to the note.
292 \begin[verbatim,fragment]{mudela}
295 e8(] [)g8 <c'8] e'8> % NO nesting!
296 [2/3 c8 c8 c8]1/1 % a triplet
299 Please note that these two characters do \emph{not} necessarrily nest,
300 they should attached to the note \verb+[ <c4 c4>]+ will generate a parse
301 error for this reason.
303 \subsection{Slurs and Ties}
305 Ties connect the noteheads of adjacent notes. They are entered as follows:
307 \begin[verbatim,fragment]{mudela}
311 Slurs connect whole chords, and try to avoid crossing stems. They are
314 \begin[verbatim,fragment]{mudela}
320 Symbols which can be put at either side (above or below) of a staff
321 are entered as follows:
322 \begin[verbatim,fragment]{mudela}
323 a-^ % marcato, direction: default
324 a^- % portato, direction: above note
325 a_. % staccato, direction: below note
326 a^\fermata % predefined identifier
327 c_"marcato" % add a text
332 If you want to define your own scripts refer to \file{init/script.ly} for
336 Dynamics can be put after the notename:
338 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
341 Mudela defines the following dynamic identifiers:
344 ppp pp p mp mf f ff fff
346 and the following abbreviations:
349 \> % start decrescendo
350 \! % end crescendo/decrescendo
353 \subsection{Defaults}
355 If omit the duration of a note, a default value is substituted. For
356 this default value mudela uses the last duration explicitly entered.
358 Thus the following inputs are equivalent
360 c4 c4 c16 c16 c16 s16 c4 c16
361 c4 c c16 c c c c4 c16
364 If you are typing music which does not lie in the "small" and "large"
365 octave, you can prevent having to type \verb+'+ all the time by using the
366 \verb+\octave+ command: These two lines have the same pitch.
368 c'' d'' e'' c d e c d e
369 \octave c''; c d e ''c ''d ''e \octave c; c d e
372 By default the setting of \verb+\octave+ is 0.
376 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
379 All syllables are entered separately, separated by whitespace
381 Twin-4 kle4 twin-4 kle4 ...
384 Two syllables or words that compose a single
385 duration entry are bound together using an underscore
390 \section{Composition: forming bigger structures}
392 The previous examples tacitly assumed that a sequence of notes is
393 printed in a left to right manner. This is not entirely correct, you
394 will get the bigger picture in this section.
396 In mathematics you can form expressions by combining expressions,
397 which are ultimately some kind of atom or terminal symbol. The same
398 goes for mudela: there are some basic building blocks, and by
399 combining those you create complex music.
401 You can combine music in three ways:
403 \item If you enclose a sequence of music-elements in braces ( \verb+{+
404 and \verb+}+ ), then you form another kind of music called (Voice) with those pieces.
405 The duration of the Voice is the sum of the durations of its elements
407 { c c g g a a g2 } % twinkle twinkle
408 { { c c g g} { a a g2 } }
410 \item You can stack music by enclosing a sequence of music elements
411 with \verb+<+ and \verb+>+. This is called a Chord. The duration of a Chord is
412 the union of the durations of its elements Example:
414 <a4 {cis8 cis8} e'4> % a-major chord
417 You can form music by transposing music:
420 d % from c to the d that's one octave down
421 { e4 f4 } % the horizontal music
425 Of course you can also combine these three mechanisms.
427 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
430 The basic building block in Mudela is called Request. Examples of
431 Requests are: Timing (such as Meter), Rhythmic, Melodic, Note (which is a combination of
432 Rhythmic and Melodic), Musicscript (put an accent over a note or
433 rest), etc. For the actual up to date listing, you should consult the
434 LilyPond source code: the Request types form a big class hierarchy.
436 Normally you don't enter Requests directly, since that would be
437 tedious. Mudela has standard abbreviations for the most common
438 combination of Requests. If you enter \verb+c4+, this is an
443 notename: 0 acc: 0 oct: -1
452 The \verb+Request_chord+ is a special kind of chord which only allows
453 Requests as its elements. The examples of the previous section were
454 processed with \verb+{+ and \verb+}+ enclosing the input.
457 \subsection{Voicegroups}
459 If more than one "voice" is in a staff, then you have the option of
460 putting the different voices into so called voicegroups: members of
461 the same voicegroup share certain characteristics, among others:
468 For the actual list, see the init file \file{init/register.ly}
470 Putting different musical lines in to the same voicegroup effectively
471 makes LilyPond try to form chords of all those lines. Putting
472 different musical lines in to different voicegroups effectively makes
473 LilyPond try to set those lines as independently as possible.
475 [adsolete. Has to be fixed in lily]
477 You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
487 oboeII = \melodic { \group "oboes";
495 melodicregs \melodic{ oboeI }
500 In this example, the two oboe voices share one staff and are initially
501 in the voicegroup called "oboes". They will share beams, dynamics etc.
502 After two quarter notes, oboeI "pushes" its group: a new voicegroup is
503 created, called "oboes+solo". The \verb+\group "-"+ command makes the
504 voice enter "oboes" again.
506 Please do note that [] are voicegroup wide; the previous input is
507 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
508 voicegroup "oboes", albeit not in oboeI but oboeII
510 This concept may seem contorted, but it allows you to set the separate
511 oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
512 you edit the [] in the example.)
516 < { .... } {......} >
518 makes a chord (all horizontal parts are in the same voicegroup). The construct
520 < \multi 2; { ....} { .... } >
522 creates horizontal parts which behave independently. You will have to
523 set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
527 < \multi 3; { ....} { .... } >
529 creates a chord with each part in a different staff
532 \subsection{Durations}
534 A duration always starts with the duration type (1,2,4 etc), and then
535 any optional multipliers/dots
537 \subsection{Meters/groupings}
539 A meter has this form:
544 Rhythmic grouping is a concept closely associated with this. For
545 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
550 You can start the piece with a partial measure, the command takes the
551 same syntax as grouping:
556 Make the piece start with a partial measure [english translation?]
557 lasting 1 3/4 quarter notes.
559 These commands are also "voice elements", and constitute simple mudela
560 (consisting of stuff with duration 0).
562 \subsection{Examples}
564 Examples are included with the GNU LilyPond distribution. For the sake of
565 maintenance no long examples are included in this document.
570 This language has a number of roots. First and foremost, GNU LilyPond's
571 predecessor mpp was the inspiration of simple Mudela. Secondly, the
572 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
573 that I've written as a hobby project. ), which in turn owes a lot to
576 Now, we know, musictypesetting and raytracing do not necessarily
577 require the same input format, and we know that a lot more ways exist
578 to convert music to ASCII, but we did give this language some
579 thoughts. As always suggestions are appreciated.