1 mailto(gnu-music-discuss@gnu.org)
4 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
8 DEFINEMACRO(Large)(1)(\
9 whenlatex(latexcommand(\Large{)ARG1+latexcommand(}))\
10 whentexinfo(texinfocommand(@strong{)ARG1+texinfocommand(}))\
11 whenhtml(htmlcommand(<font size=+2>)ARG1+htmlcommand(</font>))\
14 COMMENT( This document contains Mudela fragments. You need at least
15 Yodl-1.30.18 to convert this to tex or html.
19 * pipethrough(date) sucks.
20 * paragraphs have too much space.
21 * fix the amount of spaces (urg:tabs) at the start of verb() blocks
22 or even better: do verb and description side-by side
23 (TeX: use minipage construct):
28 The explaining texts are right in between examples.
29 Constructs like 'This shows' and 'The next line' are esp.
34 Mainly written by Han-Wen Nienhuys,
36 with help of (among others)
41 htmlbodyopt(bgcolor)(white)
42 htmlcommand(<font color=black>)
46 \textheight 53\baselineskip
47 \advance\textheight by \topskip
48 \marginparwidth 1 in % Width of marginal notes.
49 \oddsidemargin 0.25 in % Note that \oddsidemargin = \evensidemargin
50 \evensidemargin 0.25 in
51 \marginparwidth 0.75 in
52 \textwidth 5.875 in % Width of text line.
56 whenlatex(notableofcontents())
57 whentexinfo(notableofcontents())
59 article(Typesetting music with LilyPond)
60 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
61 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
64 latexcommand(\def\interexample{})
65 latexcommand(\def\preexample{\par})
66 latexcommand(\def\postexample{\par\medskip})
67 latexcommand(\def\file#1{{code(#1)}})
70 includefile(html-disclaimer.yo-urg)
75 label(tutorial:introduction)
76 latexcommand(\parindent2pc)
78 LilyPond prints music from a specification that you, the user, supply.
79 You have to give that specification using a em(language). This
80 document is a gentle introduction to that language, which is called
81 Mudela, an acronym of Music Definition Language.
83 This tutorial will demonstrate how to use Mudela by presenting
84 examples of input along with resulting output. We will use English
85 terms for notation. In case you are not familiar with those, you may
86 consult the glossary that is distributed with LilyPond.
88 The examples discussed are included in the distribution, in the
89 subdirectory file(input/tutorial/). It is recommended that you
90 experiment with writing Mudela input yourself, to get a feel for
96 To demonstrate what LilyPond input looks like, we start off with a
97 full fledged, yet simple example. It is a convoluted version
98 of the famous menuet in bind(J.)bind(S.)Bach's em(Klavierbuechlein).
100 COMMENT(urg: the fermata sign is placed below the note by default)
101 mudela(verbatim)(% lines preceded by a percent are comments.
102 \include "paper16.ly"
110 d4 g,8 a b c d4 g, g |
111 e'4 c8 d e fis g4 g, g |
112 c4 d8()c b a( )b4 c8 b a g |
113 a4 [b8 a] [g fis] g2. |
118 g4 e8 fis g d cis4 b8 cis a4 |
119 a8-. b-. cis-. d-. e-. fis-.
126 % standard settings are too wide for a book
127 linewidth = 14.0 \cm;
131 Enter it (or copy it, the filename is file(menuet.ly)), compile it
132 with LilyPond and view the output. Details of this procedure may vary
133 from system to system. To create the output, one would issue the
134 command `code(ly2dvi menuet)'. file(ly2dvi) is a program that does
135 the job of running LilyPond and TeX(), handling of titles and
136 adjusting of page margins.
138 If all goes well, the file file(menuet.dvi) will be created.
139 To view this output, issue the command `code(xdvi menuet)'.
141 Now that we are familiar with the procedure of producing output, we
142 will analyse the input, line by line.COMMENT(
145 % lines preceded by a percent are comments.
148 )The percent sign, `code(%)', introduces a line comment. If you want to
149 make larger comments, you can use block comments. These are delimited
150 by `code(%{)' and `code(%})'COMMENT(
156 )By default, LilyPond will use definitions for a 20
157 nop(point)footnote(A point is the standard measure of length for
158 printing. One point is 1/72.27 inch.) high staff. We want smaller
159 output (16 point staff height), so we must import the settings for
160 that size, which is done.COMMENT(
166 ) A mudela file combines music with directions for outputting that
167 music. The music is combined with the output directions by putting
168 them into a code(\score) block.
173 )This makes LilyPond ready for accepting notes.
178 ) As we will see, pitches are combinations of octave, note name and
179 chromatic alteration. In this scheme, the octave is indicated by
180 using raised quotes (`code(')') and ``lowered'' quotes (commas:
181 `code(,)'). The central C is denoted by code(c'). The C one octave
182 higher is code(c''). One and two octaves below the central C is
183 denoted by code(c) and code(c,) respectively.
185 For pitches in a long piece you might have to type many quotes. To
186 remedy this, LilyPond has a ``relative'' octave entry mode. In this
187 mode, octaves of notes without quotes are chosen such that a note is
188 as close as possible (graphically, on the staff) to the the preceding
189 note. If you add a high-quote an extra octave is added. The lowered
190 quote (a comma) will subtract an extra octave. Because the first note
191 has no predecessor, you have to give the (absolute) pitch of the note
192 to start with.COMMENT(
198 ) What follows is sequential music, i.e.,
199 notes that are to be played and printed after each other.COMMENT(
205 ) This command changes the time signature of the current piece: a 3/4
206 sign is printed. This command is also used to generate bar lines in
207 the right spots.COMMENT(
213 ) This command changes the current key to G-major. Although this
214 command comes after the code(\time) command, in the output, the key
215 signature comes before the time signature: LilyPond knows about music
216 typesetting conventions. COMMENT(
222 ) This command tells LilyPond that the following piece of music must
223 be played twice; code("volta") volta brackets should be used for
224 alternatives---if there were any.
231 )The subject of the repeat is again sequential music. Since
232 code(\sequential) is such a common construct, a shorthand is provided:
233 just leave off code(\sequential), and the result is the same. COMMENT(
239 ) This is a note with pitch code(d) (determined up to octaves). The
240 relative music was started with a code(c''), so the real pitch of this
241 note is code(d''). The code(4) designates the duration of the note
242 (it is a quarter note). COMMENT(
248 )These are notes with pitch code(a') and code(b'). Because their
249 duration is the same as the code(g), there is no need to enter the
250 duration (You may enter it anyway, eg. code(a4 b4)) COMMENT(
256 ) Three more notes. The `code(|)' character is a `barcheck'. When
257 processing the music, LilyPond will verify that barchecks are found at
258 the start of a measure. This can help you track down errors.
265 ) So far, no notes were chromatically altered. Here is the first one
266 that is: code(fis). Mudela by default uses Dutch note names, and
267 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
268 sharp sign in the output. The program keeps track of key signatures,
269 and will only print accidentals if they are needed.
276 )LilyPond guesses were beams can be added to eighth and shorter notes.
277 In this case, a beam over 4 eighths is added.
281 c4 d8( )c b a( )b4 c8 b a g |
284 ) The next line shows how to make a slur:
285 the beginning and ending note of the slur is marked with an opening and
286 closing parenthesis respectively. In the line shown above this is
287 done for two slurs. Slur markers (parentheses) are between
293 )Automatic beaming can be overridden by inserting beam marks
294 (brackets). Brackets are put around notes you want beamed.COMMENT(
300 )A duration with augmentation dot is notated
301 with the duration number followed by a period.COMMENT(
306 ) This ends the sequential music to be repeated. LilyPond will typeset
307 a repeat bar. COMMENT(
313 )This line shows that Lily will print an accidental if that is
314 needed: the first C sharp will be printed with an accidental, the
315 second one without. COMMENT(
318 a8-. b-. cis-. d-. e-. fis-.
321 )You can enter articulation signs either in a verbose form using a
322 shorthand. Here we demonstrate the shorthand: it is formed by a dash
323 and the the character for the articulation to use, e.g. `code(-.)' for
324 staccato as shown above. COMMENT(
331 Rests are denoted by the special notename `code(r)'. You can also enter
332 an invisible rest by using the special notename `code(s)'.
337 )All articulations have a verbose form, like code(\fermata). The
338 command `code(\fermata)' is not part of the core of the language (most
339 of the other discussed elements are), but it is a shorthand for a more
340 complicated description of a fermata. code(\fermata) names that
341 description and is therefore called an em(identifier). COMMENT(
357 )This specifies a conversion from music to notation output. Most of
358 the details of this conversions (font sizes, dimensions, etc.) have
359 been taken care of, but to fit the output in this document, it has
360 to be smaller. We do this by setting the line width to 14 centimeters
361 (approximately 6 inches).
368 )The last brace ends the code(\score) block.
370 There are two things to note here. The format contains musical
371 concepts like pitches and durations, instead of symbols and positions:
372 the input format tries to capture the meaning of em(music), and not
373 notation. Therefore Second, the format tries to be em(context-free):
374 a note will sound the same regardless of the current time signature,
377 The purpose of LilyPond is explained informally by the term `music
378 typesetter'. This is not a fully correct name: not only does the
379 program print musical symbols, it also makes esthetic decisions. All
380 symbols and their placement is em(generated) from a high-level musical
381 description. In other words, LilyPond would be best
382 described by `music compiler' or `music to notation compiler'.
385 sect(Lyrics and chords)
387 In this section we show how to typeset a song of (unknown
388 origin)footnote(The author would welcome information about the origin
392 title = "The river is flowing";
393 composer = "Traditonal (?)";
395 \include "paper16.ly"
396 melody = \notes \relative c' {
399 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
400 c4 c8 d [es () d] c4 | d4 es8 d c4.
405 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
406 ri -- ver is flo -- wing down to the sea.
409 accompaniment =\chords {
411 c2-3- f-3-.7 d-min es4 c8-min r8
412 c2-min f-min7 g-7^3.5 c-min }
417 \context ChordNames \accompaniment
420 \context Staff = mel {
421 \property Staff.noAutoBeaming = "1"
422 \property Staff.automaticMelismas = "1"
425 \context Lyrics \text
428 \paper { linewidth = 10.0\cm; }
432 The result would look bind(this)footnote(The titling and font size shown
433 may differ, since the titling in this document is not generated by
436 center(bf(Large(The river is flowing))
441 mudela(center)(\header {
442 title = "The river is flowing";
443 composer = "Traditonal (?)";
445 \include "paper16.ly"
446 melody = \notes \relative c' {
449 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
450 c4 c8 d [es () d] c4 | d4 es8 d c4.
455 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
456 ri -- ver is flo -- wing down to the sea.
459 accompaniment =\chords {
461 c2-3- f-3-.7 d-min es4 c8-min r8
462 c2-min f-min7 g-7^3.5 c-min }
467 \context ChordNames \accompaniment
470 \context Staff = mel {
471 \property Staff.noAutoBeaming = "1"
472 \property Staff.automaticMelismas = "1"
475 \context Lyrics \text
478 \paper { linewidth = 10.0\cm; }
481 Again, we will dissect the file line by line.COMMENT(
487 )Information about the music you are about to typeset goes into a
488 code(\header) block. The information in this block is not used by
489 LilyPond, but it is included in the output. file(ly2dvi) uses this
490 information to print titles above the music.
492 title = "The river is flowing";
493 composer = "Traditonal (?)";)COMMENT(
495 )the code(\header) contains block assignments. An assignment starts
496 with a string. (which is unquoted, in this case). Then comes the
497 equal sign `code(=)'. After the equal sign comes the expression you
498 want to store. In this case, you want to put in strings. The
499 information have to be quoted, because they contain spaces. The
500 assignment is finished with a semicolon.COMMENT(
503 \include "paper16.ly"
506 )Smaller size for inclusion in a book.COMMENT(
509 melody = \notes \relative c' {
512 )The structure of the file will be the same as the previous one, a
513 code(\score) block with music in it. To keep things readable, we will
514 give the different parts of music names, and use names to construct
515 music within the score block.
521 The piece starts an anacrusis of one eighth. COMMENT(
524 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
525 c4 c8 d [es () d] c4 | d4 es8 d c4.
529 )We use explicit beaming. Since this is a song, we turn automatic
530 beams off, and use explicit beaming where needed.COMMENT(
536 )This ends the definition of code(melody). Note that there are no
537 semicolons after declarations at top level.COMMENT(
543 )Another identifier assignment. This one is for the lyrics.
544 Lyrics are formed by syllables that have duration, and not by
545 notes. To make LilyPond parse words as syllables, switch it into
546 lyrics mode with code(\lyrics). Again, the brace after code(\lyrics)
547 is a shorthand for code(\sequential {). COMMENT(
550 The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
551 ri- ver is flo- __ wing down to the sea.
555 )The syllables themselves, separated by spaces. You can get syllable
556 extenders by entering `code(__)', and centered hyphens with
557 `code(--)'. We enter the syllables as if they are all quarter notes
558 in length (hence the code(4)), and use a feature to align the
559 syllables to the music, which obviously isn't all quarter notes.
563 accompaniment =\chords {
566 )We'll put chords over the music. There is a special mode (analogous
567 to code(\lyrics) and code(\notes) mode) where you can give the names
568 of the chords you want, instead of the notes comprising the chord.
575 )There is no accompaniment during the anacrusis.COMMENT(
579 )A chords is started by a note that is the tonic of the chord. The
580 first one lasts a half note. An unadorned note creates a major
581 triad, while a minor triad is wanted. code(3-) modifies the third to
582 be small. code(7) modifies (adds) a seventh, which is small by default
583 to create the code(f a c es) chord. Multiple modifiers must be
584 separated by a dot.COMMENT(
590 )Some modifiers have predefined names, eg. code(min) is the same as
591 code(3-), so code(d-min) is a minor code(d) chord.COMMENT(
594 c2-min f-min7 g-7^3.5 c-min }
597 )A named modifier code(min) and a normal modifier code(7) do not have
598 to be separated by a dot. Tones from a chord are removed with chord
599 subtractions. Subtractions are started with a caret, and they are
600 also separated by dots. In this example, code(g-7^3.5) produces a
601 minor seventh. The brace ends the sequential music. COMMENT(
608 )We assemble the music in the code(\score) block. Melody, lyrics and
609 accompaniment have to sound at the same time, so they should be
610 code(\simultaneous).COMMENT(
616 )Chord mode generates notes grouped in code(\simultaneous) music. If
617 you remove the comment sign, you can see the chords in normal
618 notation. The chords will then be printed as chords of note heads on
619 a separate staff. COMMENT(
622 \context ChordNames \accompaniment
625 )Normally, the notes that you enter are transformed into note heads.
626 The note heads alone make no sense, they need surrounding information:
627 a key signature, a clef, staff lines, etc. They need em(context).
628 This context also is a thing that has to be created. This is done by
629 code(\context). It takes two arguments. The first is the name of a
630 em(notation) or em(interpration context). The name is a string, it
631 can be quoted with code(") quotes). The second argument is the music
632 that should be interpreted in this context.
634 By default, LilyPond will create a Staff context for you. If you
635 would remove the code(%) sign in the previous line, you see that
636 mechanism in action. For the previous line, we could have written
637 code(\context Staff \accompaniment), and get the same effect.COMMENT(
643 )The lyrics need to be aligned with the melody. This is done by
644 combining both with code(\addlyrics). code(\addlyrics) takes two
645 pieces of music (usually a melody and lyrics, in that order) and
646 aligns the lyrics syllables of the second piece under the notes of the
647 first piece. If you would reverse the order, the notes would be
648 aligned on the lyrics, which is not very useful. (Besides, it looks
652 \context Staff = mel {
655 )This is first piece of music. We instantiate a code(Staff) context
656 explicitly: should you chose to remove comment before the ``note
657 heads'' version of the accompaniment, the accompaniment will be on a
658 nameless staff. In that case, the melody has to be on a different
659 staff as the accompaniment. This is accomplished by giving the melody
660 staff a different name.COMMENT(
663 \property Staff.noAutoBeaming = "1"
666 )An interpretation context has variables that tune its behaviour. One
667 of the variables is code(noAutoBeaming). If set and non-zero (i.e.,
668 true) LilyPond will not try to automatic beaming on the current
672 \property Staff.automaticMelismas = "1"
675 )Similarly, we want do not want to put a lyric syllable when there is
676 a slur. This sets up the Staff context to signal slurs while
677 code(\addlyrics) is processed. COMMENT(
684 )Finally, we put the melody on the current. Note that the
685 code(\property) directives and code(\melody) are grouped in sequential
686 music. So the property settings are done before the melody is
690 \context Lyrics \text
693 )The second argument of code(\addlyrics) is the text. Text also
694 should land on a Staff, but on a context for syllables,
695 extenders, hyphens etc. This context is called Lyrics.COMMENT(
701 )This ends code(\simultaneous).COMMENT(
707 )This makes the music go to a MIDI file as well. MIDI is great for
708 checking music you enter. You listen to the MIDI file: if you hear
709 something unexpected, it's probably a typing error. code(\midi) is a
710 `output definition', a declaration that specifies how to output music
711 analogous to code(\paper { }).COMMENT(
714 \paper { linewidth = 10.0\cm; }
717 )We also want notation output.COMMENT(
723 )End the score block.