2 \documentclass{article}
4 \title{GNU LilyPond input format 0.1}
5 \author{Han-Wen Nienhuys}
9 \def\interexample{\par Produces the following:\par}
10 \def\preexample{\par\medskip}
11 \def\postexample{\par\medskip}
12 \def\file#1{{\texttt{#1}}}
14 \section{Introduction}
16 This document describes the the GNU LilyPond input format, which is an
17 effective language for defining music. We call this language (rather
18 arrogantly) The Musical Definition Language or Mudela, for
19 short.\footnote{If anybody comes up with a better name, we'd gladly
20 take this. Gourlay already uses Musical Description Language,
21 G-Sharp Score Definition Language. We're not being original here}
23 The first aim of Mudela is to define a piece of music,
24 being complete from both from a musical typesetting,
25 as from a musical performing point of view.
27 The Musical Definition Language (Mudela), has a logical structure,
28 making use of identifiers, that allows for flexible input, and
29 definition reuse. See MANIFESTO for reasons and design considerations.
31 The below included for explanatory purposes only (i.e., for a complete
32 and up-to-date definition, see \file{lily/parser.y} and
35 As a related note, you should take a look at the examples and the init
36 files, as this document does not cover every aspect of mudela yet, and
40 \section{Basic elements}
44 The de-facto extension of Mudela is \file{.ly}. Files may be included by
45 entering \verb+include+ at the start of a line:
54 Line comments are introduced by a
56 Block comments are delimited
65 Occasionally, small changes in syntax across different versions of
66 Mudela might give syntax errors. To warn you about possible
67 incompatibilities, you can specify the Mudela version for which the
68 inputfile was written,
73 A perl-script which tries to convert to newer versions
74 (\file{convert-mudela}) is included in the LilyPond distribution.
78 Keywords are preceded by a backslash: \verb+\+. They contain
79 alphabetic characters only.
81 Identifiers in their normal form consist start with a backslash, a
82 alpha character, followed by alpha-numerics. Identifiers can contain
83 any characters (except whitespace,
84 \verb+$+ and \verb+%+), if you use this
88 \$i'm_a_weird!!!identifier
91 (which is the identifier with the name
92 \verb+i'm_a_weird!!!identifier+). \verb+$+ Takes any sequence of
93 characters which are not whitespace, \verb+$+ and \verb+%+.
94 \verb+$i'm_a_weird!!!string+
96 \subsection{Nesting characters}
98 Mudela uses the brace (\verb+{+ and \verb+}+) for most hierarchical
99 structures. For chords the \verb+<+ and the \verb+>+ are used as
102 \subsection{Constants}
104 Please note that -.5 is not a Real.
113 \subsection{Identifiers}
115 When assigning identifiers you use
122 When using identifiers they have to be escaped:
125 oboe = \melodic { ... }
126 \score{ \melodic { \oboe }}
128 \subsection{Hierarchical structures}
130 The general structure consists of declarations:
139 \TYPE{ <type specific data> }
142 (Currently, \verb+\score+ is the only type that can be instantiated
143 at top level. Currently declarations can only be done at top level)
145 Most instantiations that use an IDENTIFIER are specified as follows:
148 \TYPE{ IDENTIFIER [...] }
151 Some exceptions on this rule have been made to prevent inputting
152 Mudela becoming tedious
157 To simplify different aspects of music definition (entering the notes
158 and manipulating them) Mudela has a number of different input "modes":
165 At the start of parsing, Mudela assumes normal mode.
166 In Normal mode, a word is looked up in the following order:
169 \word keyword, identifier
171 In normalmode, a word is assumed to start with an alphabetic
172 character, followed by alpha-numeric characters.
175 Note mode (and thus Simple mudela) is introduced by
176 the keyword \verb+\melodic+. In Note mode, a word is looked up in
180 word notename, string
181 \word keyword, identifier
183 In Note mode a word is considered to have alphabetic characters only.
186 Lyrics mode (and thus Simple mudela) is introduced by the keyword \verb+\lyrics+.
188 In Lyrics mode, a word is looked up in the following order:
192 \word keyword, identifier
195 In Lyric mode every sequence of non-digit and non-white characters
196 starting with an alphabetic character or the \_ is considered a word.
199 a&@&@&TSI|{[ % a word
200 1THtrhortho % not a "word"
201 Leise Fl\"u\ss{}teren meine Sapfe % 4 words
202 _ _ _ _ % 4 words: 4 spaces
206 These modes are of a lexical nature. Normal and Note mode largely
207 resemble each other, save the possibility of entering Reals,
208 meaning of \verb+_+ and the resolution of words
212 You enter a note by giving the name and the reciprocal of the duration:
214 \begin[fragment,verbatim]{mudela}
218 is a A-1 pitched quaver. The ' signifies an octave change. A-1 is 440
219 Hz concert-pitch. \verb+c'+ is also known as the central c. More examples:
221 \begin[fragment,verbatim]{mudela}
224 A % 110, uppercase octavates down
230 The last one is an A flat, (just below 110 Hz concert-pitch). The \verb+*2/3+
231 signifies that this note is part of a triplet (3 in stead of 2). The
232 duration is one and a half quaver (\verb+4.+) times 2/3.
234 Notenames are just a special kind of identifiers, and can be declared
235 for any language appropriate (see \file{dutch.ini}). The default language
236 for notenames is defined to be dutch. In dutch, the notenames are
237 a,b,c,d,e,f and g. Sharps are formed by adding the extension "is",
238 flats by adding ``es''
242 cisis disis eisis fisis gisis aisis bisis
244 cis dis eis fis gis ais bis
248 ces des es fes ges as bes
250 ceses deses eses feses geses ases beses
253 Rests are named r or s
256 s % a "space" rest, nothing is printed.
259 These notenames along with duration are enough material to construct
262 \begin[verbatim,fragment]{mudela}
268 Music is able to express more. generally speaking, the other
269 'features' are either connected between notes (slurs, beams: spanning
270 requests) or attached to notes (eg. accents). The former are
271 implemented as START and STOP stop features and then attached to the note.
279 \begin[verbatim,fragment]{mudela}
282 e8(] [)g8 <c'8] e'8> % NO nesting!
283 [2/3 c8 c8 c8]1/1 % a triplet
286 Please note that these two characters do \emph{not} necessarrily nest,
287 they should attached to the note \verb+[ <c4 c4>]+ will generate a parse
288 error for this reason.
290 \subsection{Slurs and Ties}
292 Ties connect the noteheads of adjacent notes. They are entered as follows:
294 \begin[fragment]{mudela}
298 Slurs connect whole chords, and try to avoid crossing stems. They are
302 \begin[fragment]{mudela}
308 Symbols which can be put at either side (above or below) of a staff
309 are entered as follows:
310 \begin[fragment]{mudela}
311 a-^ % marcato, direction: default
312 a^- % portato, direction: above note
313 a_. % staccato, direction: below note
314 a^\fermata % predefined identifier
315 c_"marcato" % add a text
320 If you want to define your own scripts refer to \file{script.ini} for
324 Dynamics can be put after the notename:
326 a4 \dynamic { 0 } % 0 = fff, 7 = ppp
329 Mudela defines the following dynamic identifiers:
332 ppp pp p mp mf df ff fff % df iso f, f is a notename.
334 and the following abbreviations:
337 \> % start decrescendo
338 \! % end crescendo/decrescendo
341 \subsection{Defaults}
343 If omit the duration of a note, a default value is substituted. For
344 this default value mudela uses the last duration explicitly entered.
346 Thus the following inputs are equivalent
348 c4 c4 c16 c16 c16 s16 c4 c16
349 c4 c c16 c c c c4 c16
352 If you are typing music which does not lie in the "small" and "large"
353 octave, you can prevent having to type \verb+'+ all the time by using the
354 \verb+\octave+ command: These two lines have the same pitch.
356 c'' d'' e'' c d e c d e
357 \octave c''; c d e ''c ''d ''e \octave c; c d e
360 By default the setting of \verb+\octave+ is 0.
364 Lyrics in Mudela resemble Simple mudela a lot, with notes substituted
367 All syllables are entered separately, separated by whitespace
369 Twin-4 kle4 twin-4 kle4 ...
372 Two syllables or words that compose a single
373 duration entry are bound together using an underscore
378 \section{Composition: forming bigger structures}
380 The previous examples tacitly assumed that a sequence of notes is
381 printed in a left to right manner. This is not entirely correct, you
382 will get the bigger picture in this section.
384 In mathematics you can form expressions by combining expressions,
385 which are ultimately some kind of atom or terminal symbol. The same
386 goes for mudela: there are some basic building blocks, and by
387 combining those you create complex music.
389 You can combine music in three ways:
391 \item If you enclose a sequence of music-elements in braces ( \verb+{+
392 and \verb+}+ ), then you form another kind of music called (Voice) with those pieces.
393 The duration of the Voice is the sum of the durations of its elements
395 { c c g g a a g2 } % twinkle twinkle
396 { { c c g g} { a a g2 } }
398 \item You can stack music by enclosing a sequence of music elements
399 with \verb+<+ and \verb+>+. This is called a Chord. The duration of a Chord is
400 the union of the durations of its elements Example:
402 <a4 {cis8 cis8} e'4> % a-major chord
405 You can form music by transposing music:
408 d % from c to the d that's one octave down
409 { e4 f4 } % the horizontal music
413 Of course you can also combine these three mechanisms.
415 { c <c e> <c e g> <c e g \transpose d' dis > } % 4 increasing chords
418 The basic building block in Mudela is called Request. Examples of
419 Requests are: Timing (such as Meter), Rhythmic, Melodic, Note (which is a combination of
420 Rhythmic and Melodic), Musicscript (put an accent over a note or
421 rest), etc. For the actual up to date listing, you should consult the
422 LilyPond source code: the Request types form a big class hierarchy.
424 Normally you don't enter Requests directly, since that would be
425 tedious. Mudela has standard abbreviations for the most common
426 combination of Requests. If you enter \verb+c4+, this is an
431 notename: 0 acc: 0 oct: -1
440 The \verb+Request_chord+ is a special kind of chord which only allows
441 Requests as its elements. The examples of the previous section were
442 processed with \verb+{+ and \verb+}+ enclosing the input.
445 \subsection{Voicegroups}
447 If more than one "voice" is in a staff, then you have the option of
448 putting the different voices into so called voicegroups: members of
449 the same voicegroup share certain characteristics, among others:
456 For the actual list, see the init file \file{register.ini}
458 Putting different musical lines in to the same voicegroup effectively
459 makes LilyPond try to form chords of all those lines. Putting
460 different musical lines in to different voicegroups effectively makes
461 LilyPond try to set those lines as independently as possible.
463 [adsolete. Has to be fixed in lily]
465 You can set the voicegroup of a voice with the command \verb+\group+, e.g.,
475 oboeII = \melodic { \group "oboes";
483 melodicregs \melodic{ oboeI }
488 In this example, the two oboe voices share one staff and are initially
489 in the voicegroup called "oboes". They will share beams, dynamics etc.
490 After two quavers, oboeI "pushes" its group: a new voicegroup is
491 created, called "oboes+solo". The \verb+\group "-"+ command makes the
492 voice enter "oboes" again.
494 Please do note that [] are voicegroup wide; the previous input is
495 valid: the beam, started in oboeI, voicegroup "oboes" is also ended in
496 voicegroup "oboes", albeit not in oboeI but oboeII
498 This concept may seem contorted, but it allows you to set the separate
499 oboe parts without changing the \verb+oboeI+ and \verb+oboeII+ (assuming that
500 you edit the [] in the example.)
504 < { .... } {......} >
506 makes a chord (all horizontal parts are in the same voicegroup). The construct
508 < \multi 2; { ....} { .... } >
510 creates horizontal parts which behave independently. You will have to
511 set voicegroup features by hand (\verb+\stem+ and \verb+\hshift+. See examples)
515 < \multi 3; { ....} { .... } >
517 creates a chord with each part in a different staff
520 \subsection{Durations}
522 A duration always starts with the duration type (1,2,4 etc), and then
523 any optional multipliers/dots
525 \subsection{Meters/groupings}
527 A meter has this form:
532 Rhythmic grouping is a concept closely associated with this. For
533 example, in a 5/8 meter, the counts are grouped 2+3. In mudela this is
538 You can start the piece with a partial measure, the command takes the
539 same syntax as grouping:
544 Make the piece start with a partial measure [english translation?]
545 lasting 1 3/4 quaver.
547 These commands are also "voice elements", and constitute simple mudela
548 (consisting of stuff with duration 0).
550 \subsection{Examples}
552 Examples are included with the GNU LilyPond distribution. For the sake of
553 maintenance no long examples are included in this document.
558 This language has a number of roots. First and foremost, GNU LilyPond's
559 predecessor mpp was the inspiration of simple Mudela. Secondly, the
560 hierarchical structure looks a lot like Rayce's (Rayce is a raytracer
561 that I've written as a hobby project. ), which in turn owes a lot to
564 Now, we know, musictypesetting and raytracing do not necessarily
565 require the same input format, and we know that a lot more ways exist
566 to convert music to ASCII, but we did give this language some
567 thoughts. As always suggestions are appreciated.