1 mailto(gnu-music-discuss@gnu.org)
4 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
7 COMMENT( This document contains Mudela fragments. You need at least
8 Yodl-1.30.18 to convert this to tex or html.
12 pipethrough(date) sucks.
14 paragraphs have too much space.
19 Mainly written by Han-Wen Nienhuys,
21 with help of (among others)
26 htmlbodyopt(bgcolor)(white)
27 htmlcommand(<font color=black>)
31 \textheight 53\baselineskip
32 \advance\textheight by \topskip
33 \marginparwidth 1 in % Width of marginal notes.
34 \oddsidemargin 0.25 in % Note that \oddsidemargin = \evensidemargin
35 \evensidemargin 0.25 in
36 \marginparwidth 0.75 in
37 \textwidth 5.875 in % Width of text line.
41 whenlatex(notableofcontents())
42 whentexinfo(notableofcontents())
44 article(Typesetting music with LilyPond)
45 (Han-Wen Nienhuys and Jan Nieuwenhuizen)
46 (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
49 latexcommand(\def\interexample{})
50 latexcommand(\def\preexample{\par})
51 latexcommand(\def\postexample{\par\medskip})
52 latexcommand(\def\file#1{{code(#1)}})
55 includefile(html-disclaimer.yo-urg)
60 label(tutorial:introduction)
61 latexcommand(\parindent2pc)
63 LilyPond prints music from a specification that you, the user, supply.
64 You have to give that specification using a em(language). This
65 document is a gentle introduction to that language, which is called
66 Mudela, an abbreviation for Music Definition Language.
68 This tutorial will demonstrate how to use Mudela by presenting
69 examples of input along with resulting output. We will use English
70 terms for notation, so if you are not familiar with those, you should
71 consult the glossary that is distributed with LilyPond.
73 The examples discussed are included in the distribution, in the
74 subdirectory file(input/tutorial/). It is recommended that you
75 experiment with input yourself, to get a feel for how LilyPond behaves.
80 To demonstrate what LilyPond input looks like, we start off with a
81 full fledged, yet simple example. It is a convoluted version
82 of the famous menuet in bind(J.)bind(S.)Bach's em(Klavierbuechlein).
84 mudela(verbatim)(% lines preceded by a percent are comments.
93 d4 g,8 a b c d4 g, g |
94 e'4 c8 d e fis g4 g, g |
95 c4 d8()c b a( )b4 c8 b a g |
96 a4 [b8 a] [g fis] g2. |
101 g4 e8 fis g d cis4 b8 cis a4 |
102 a8-. b-. cis-. d-. e-. fis-.
109 linewidth = 14.0 \cm; % standard settings are too wide for a book
113 Enter it (or copy it, the filename is file(menuet.ly)), and compile it
114 with LilyPond and view the output. Details of this procedure may vary
115 from system to system. To create the output, one would issue
116 code(ly2dvi menuet). file(ly2dvi) is a program that does the job of
117 calling LilyPond and TeX() and adjusting page margins.
119 If all goes well, this will create the file file(menuet.dvi).
120 To view this output, issue the command code(xdvi menuet).
122 Now that we are familiar with the procedure to produce output, we will
123 analyse the input itself, line by line.
125 verb(% lines preceded by a percent are comments.)COMMENT(
127 )The percent sign, `code(%)', introduces a line comment. If you want to
128 make larger comments, you can use block comments. These are delimited
129 by `code(%{)' and `code(%})'COMMENT(
131 )verb(\input "paper16.ly")COMMENT(
133 )By default, LilyPond will use definitions for a staff of 20
134 nop(point)footnote(A point is the standard measure of length for
135 printing. One point is 1/72.27 inch.) high. We want smaller output
136 (16 point staff height), you have to import the settings for that
137 size, which is done.COMMENT(
139 )verb(\score {) COMMENT(
141 ) A mudela file combines music with directions for outputting that
142 music. The music is combined with the output directions by putting
143 them into a code(\score) block.
148 )This makes LilyPond ready for accepting notes.
153 ) As we will see, pitches are combinations of octave, note name and
154 chromatic alteration. In this scheme, the octave is indicated by
155 using raised quotes (`code(')') and ``lowered'' quotes (commas:
156 `code(,)'). The central C is denoted by code(c'). The C one octave
157 higher is code(c''). One and two octaves below central C is denoted
158 by code(c) and code(c,) respectively.
160 For pitches in a long piece you might have to type many quotes. To
161 remedy this, LilyPond has a ``relative'' octave entry mode. In this
162 mode, octaves of notes without quotes are chosen such that a note is
163 as close as possible to the the preceding note. If you add a
164 high-quote an extra octave is added. The lowered quote (a comma) will
165 subtract an extra octave. Because the first note has no predecessor,
166 you have to give the (absolute) pitch of the note to start with.
173 ) What follows is sequential music, i.e.,
174 notes that are to be played and printed after each other.
181 ) This command changes the time signature of the current piece: a 3/4
182 sign is printed. This commond is also used to generate bar lines
183 in the right spots.COMMENT(
189 ) This command changes the current key to G-major. Although this
190 command comes after the code(\time) command, in the output, the key
191 signature comes before the time signature: LilyPond knows about music
192 typesetting conventions. COMMENT(
194 )verb( \repeat "volta" 2 ) COMMENT(
196 ) This command tells LilyPond that the following piece of music must
197 be played twice; code("volta") volta brackets should be used for
198 alternatives---if there were any.
203 )The subject of the repeat are again sequential notes. Since
204 code(\sequential) is such a common construct, a abbreviation is
205 provided: just leave off code(\sequential), and the result is the
210 ) This is a note with pitch code(d) (determined up to octaves). The
211 relative music was started with a code(c''), so the real pitch of this
212 note is code(d''). The code(4) designates the duration of the note
213 (it is a quarter note). COMMENT(
219 )These are notes with pitch code(a') and code(b'). Because their
220 duration is the same as the code(g), there is no need to enter the
221 duration (You may enter it anyway, eg. code(a4 b4)) COMMENT(
227 ) Three more notes. The `code(|)' character is a `barcheck'. When processing the
228 music, LilyPond will check that barchecks are found at the start of
229 a measure. This can help you track down errors.
236 ) So far, no notes were chromatically altered. Here is the first one
237 that is: code(fis). Mudela by default uses Dutch note names, and
238 ``Fis'' is the Dutch note name for ``F sharp''. However, there is no
239 sharp sign in the output. The program keeps track of key signatures,
240 and will only print accidentals if they are needed.
243 )verb(c8 d e fis)COMMENT(
245 )LilyPond guesses were beams can be added to eighth and shorter notes.
246 In this case, a beam over 4 eighths is added.
250 c4 d8( )c b a( )b4 c8 b a g |
253 ) The next line shows how to make a slur:
254 the beginning and ending note of the slur is marked with an opening and
255 closing parenthesis respectively. In the line shown above this is
256 done for two slurs. Slur markers (parentheses) are between
262 )Automatic beaming can be overridden by inserting beam marks
263 (brackets). Brackets are put around notes you want beamed.COMMENT(
267 )A duration with augmentation dot is notated
268 with the duration number followed by a period.COMMENT(
273 ) This ends the sequential music to be repeated. LilyPond will typset
274 a repeat bar. COMMENT(
280 )This line shows that Lily will print an accidental if that is
281 needed: the first C sharp will be printed with an accidental, the
282 second one without. COMMENT(
284 )verb( a8-. b-. cis-. d-. e-. fis-. )COMMENT(
286 )You can enter articulation signs either in a verbose or in an
287 abbreviated form. Here we demonstrate the abbreviated form: it is
288 formed by a dash and the the character for the articulation to use,
289 e.g. code(-.) for staccato as shown above. COMMENT(
296 Rests are denoted by the special notename code(r). You can also enter
297 an invisible rest by using the special notename code(s).
302 )All articulations have a verbose form, like code(\fermata). The
303 `command' code(\fermata) is not part of the
304 core of the language (most of the other discussed elements are), but
305 it is an abbreviation of a more complicated description of a fermata.
306 code(\fermata) names that description and is therefore called an
307 em(identifier). COMMENT(
319 )This specifies a conversion from music to notation output. Most of
320 the details of this conversions (font sizes, dimensions, etc.) have
321 been taken care of, but to fit the output in this document, it has
322 to be smaller. We do this by setting the line width to 10 centimeters
323 (approximately 4 inches).
330 )The last brace ends the code(\score) block.
332 There are two things to note here. The format contains musical
333 concepts like pitches and durations, instead of symbols and positions:
334 the input format tries to capture the meaning of em(music), and not
335 notation. Therefore Second, the format tries to be em(context-free):
336 a note will sound the same regardless of the current time signature,
339 The purpose of LilyPond informally is explained by the term `music
340 typesetter'. This is not a fully correct name: not only does the
341 program print musical symbols, it also makes esthetic decisions. All
342 symbols and their placement is em(generated) from a high-level musical
343 description. In other words, LilyPond would be best
344 described by `music compiler' or `music to notation compiler'.
347 sect(Lyrics and chords)
349 In this section we show how to typeset a song of (unknown
350 origin).footnote(The author would welcome information about the origin
354 title = "The river is flowing";
355 composer = "Traditonal (?)";
357 \include "paper16.ly"
358 melody = \notes \relative c' {
361 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
362 c4 c8 d [es () d] c4 | d4 es8 d c4.
367 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
368 ri -- ver is flo -- wing down to the sea.
371 accompaniment =\chords {
373 c2-3- f-3-.7 d-min es4 c8-min r8
374 c2-min f-min7 g-7^3.5 c-min }
379 \context ChordNames \accompaniment
383 { \property Staff.noAutoBeaming = "1"
384 \property Staff.automaticMelismas = "1"
386 \context Lyrics \text
389 \paper { linewidth = 10.0\cm; }
393 The result would look this.footnote(The titling and font size shown
394 may differ, since the titling in this document is not generated by
397 center(bf(The river is flowing)
403 title = "The river is flowing";
404 composer = "Traditonal (?)";
406 \include "paper16.ly"
407 melody = \notes \relative c' {
410 c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
411 c4 c8 d [es () d] c4 | d4 es8 d c4.
416 The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
417 ri -- ver is flo -- wing down to the sea.
420 accompaniment =\chords {
422 c2-3- f-3-.7 d-min es4 c8-min r8
423 c2-min f-min7 g-7^3.5 c-min }
428 \context ChordNames \accompaniment
432 { \property Staff.noAutoBeaming = "1"
433 \property Staff.automaticMelismas = "1"
435 \context Lyrics \text
438 \paper { linewidth = 10.0\cm; }
441 Again, we will dissect the file line by line.COMMENT(
443 )verb(\header {)COMMENT(
445 )Information about the music you are about to typeset goes into a
446 code(\header) block. The information in this block is not used by
447 LilyPond, but it is included in the output. file(ly2dvi) uses this
448 information to print titles above the music.
450 title = "The river is flowing";
451 composer = "Traditonal (?)";)COMMENT(
453 )the code(\header) contains block assignments. An assignment starts
454 with a string. (which is unquoted, in this case). Then comes the
455 equal sign `code(=)'. After the equal sign comes the expression you
456 want to store. In this case, you want to put in strings. The
457 information have to be quoted, because they contain spaces. The
458 assignment is finished with a semicolon.COMMENT(
460 )code(\include "paper16.ly")COMMENT(
462 )Smaller size for inclusion in a book.COMMENT(
464 )verb(melody = \notes \relative c' {)COMMENT(
466 )The structure of the file will be the same as the previous one, a
467 code(\score) block with music in it. To keep things readable, we will
468 give the different parts of music names, and use names to construct
469 music within the score block.
473 The piece starts an anacrusis of one eighth. COMMENT(
475 )verb(c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
476 c4 c8 d [es () d] c4 | d4 es8 d c4.
480 )We use explicit beaming. Since this is a song, we turn automatic
481 beams off, and use explicit beaming where needed.COMMENT(
485 )This ends the definition of code(melody). Note that there are no
486 semicolons after declarations at top level.COMMENT(
488 )verb(text = \lyrics {)COMMENT(
490 )Another identifier assignment. This one is for the lyrics.
491 Lyrics are formed by syllables that have duration, and not by
492 notes. To make LilyPond parse words as syllables, switch it into
493 lyrics mode with code(\lyrics). The brace after code(\lyrics) again
494 is an abbreviation of code(\sequential {). COMMENT(
496 )code(The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
497 ri- ver is flo- __ wing down to the sea.
500 )The syllables themselves. They are separated by spaces. You can get
501 syllable extenders by entering code(__), and centered hyphens with
502 code(--). We enter the syllables as if they are all quarter notes in
503 length (hence the code(4)), and use a feature to align the syllables
504 to the music, which isn't all quarter notes.
508 accompaniment =\chords {
511 )We'll put chords over the music. There is a special mode (analogous
512 to code(\lyrics) and code(\notes) mode) where you can give the names
513 of the chords you want, in stead of the notes comprising the chord.
518 )There is no accompaniment during the anacrusis.COMMENT(
521 )A chords is started by a note that is the tonic of the chord. The
522 first one lasts a half note. An unadorned note creates a major
523 triad, while a minor triad is wanted. code(3-) modifies the third to
524 be small. code(7) modifies (adds) a seventh, which is small by default
525 to create the code(f a c es) chord. Multiple modifiers must be
529 )verb(d-min es4 c8-min r8)COMMENT(
531 )Some modifiers have predefined names, eg. code(min) is the same as
532 code(3-), so code(d-min) is a minor code(d) chord.COMMENT(
534 )verb(c2-min f-min7 g-7^3.5 c-min })COMMENT(
536 )You may leave out the dot between a named modifier code(min) and a
537 normal modifier code(7). Tones from a chord are removed with chord
538 substractions. Substractions are started with a caret, and they are
539 also separated by dots. In this example, code(g-7^3.5) produces a
540 minor seventh. The brace ends the sequential music. COMMENT(
543 \simultaneous {)COMMENT(
545 )We put the music together in score block. Melody, lyrics and
546 accompaniment have to sound at the same time, so they should be
547 code(\simultaneous).COMMENT(
549 )verb( % \accompaniment)COMMENT(
551 )Chords mode generates notes grouped in code(\simultaneous) music. If
552 want to see the chords in normal notation, you can remove the comment
553 sign. The chords are then printed on a staff with noteheads. COMMENT(
555 )verb(\context ChordNames \accompaniment)COMMENT(
557 )Normally, the notes that you enter are transformed into noteheads.
558 The note heads alone make no sense, they need surrounding information:
559 a key signature, a clef, staff lines, etc. They need em(context).
560 This context also is a thing that has to be created. This is done by
561 code(\context). It takes two arguments. The first is the name of a
562 em(notation) or em(interpration context). The name is a string, it
563 can be quoted with code(") quotes). The second argument is the music
564 that should be interpreted in this context.
566 By default, LilyPond will create a Staff context for you. If you
567 would remove the code(%) sign in the previous line, you see that
568 mechanism in action. For the previous line, we could have written
569 code(\context Staff \accompaniment), and get the same effect.COMMENT(
571 )verb(\addlyrics)COMMENT(
573 )The lyrics need to be aligned with the melody. This is done by
574 combining both with code(\addlyrics). code(\addlyrics) takes two
575 pieces of music (usually a melody and lyrics, in that order) and
576 aligns the lyrics syllables of the second piece under the notes of the
577 first piece. If you would reverse the order, the notes would be
578 aligned on the lyrics, which is not very useful. (Besides, it looks
581 )verb( \context Staff = mel {)COMMENT(
583 )This is first piece of music. We instantiate a code(Staff) context
584 explicitly: should you chose to remove comment before the ``note
585 heads'' version of the accompaniment, the accompaniment will be on a
586 nameless staff. In that case, the melody has to be on a different
587 staff as the accompaniment. This is accomplished by giving the melody
588 staff a different name.COMMENT(
590 )verb({ \property Staff.noAutoBeaming = "1")COMMENT(
592 )An interpretation context has variables that tune its behavior. One
593 of the variables is code(noAutoBeaming). If set and non-zero (i.e.,
594 true) LilyPond will not try to automatic beaming on the current
597 )verb( \property Staff.automaticMelismas = "1")COMMENT(
599 )Similarly, we want do not want to put a lyric syllable when there is
600 a slur. This sets up the Staff context to signal slurs while
601 code(\addlyrics) is processed. COMMENT(
603 )verb( \melody })COMMENT(
605 )Finally, we put the melody on the current. Note that the
606 code(\property) directives and code(\melody) are grouped in sequential
607 music. So the property settings are done before the melody is
610 )verb( \context Lyrics \text)COMMENT(
612 )The second argument of code(\addlyrics) is the text. Text also
613 should land on a Staff, but on a context for syllables,
614 extenders, hyphens etc. This context is called Lyrics.COMMENT(
618 )This ends code(\simultaneous).COMMENT(
620 )verb( \midi { })COMMENT(
622 )This makes the music go to a MIDI file as well. MIDI is great for
623 checking music you enter. You listen to the MIDI file, if you hear
624 something weird, its probably a typing error. code(\midi) is a `output
625 definition', a declaration that specifies how to output music
626 analogous to code(\paper { }).COMMENT(
628 )verb( \paper { linewidth = 10.0\cm; })COMMENT(
630 )We also want notation output.COMMENT(
634 )End the score block.