1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 @node Fundamental concepts
5 @chapter Fundamental concepts
8 * How LilyPond files work::
9 * Voices contain music::
10 * TODO new sec fundamental::
11 * Extending the templates::
16 @node How LilyPond files work
17 @section How LilyPond files work
19 The LilyPond input format is quite free-form, giving experienced
20 users a lot of flexibility to structure their files however they
21 wish. However, this flexibility can make things confusing for new
22 users. This section will explain some of this structure, but may
23 gloss over some details in favor of simplicity. For a complete
24 description of the input format, see @ruser{File structure}.
27 * Introduction to the LilyPond file structure::
28 * Score is a (single) compound musical expression::
31 @node Introduction to the LilyPond file structure
32 @subsection Introduction to the LilyPond file structure
34 A basic example of a lilypond input file is
39 @var{...compound music expression...} % all the music goes here!
47 There are many variations of this basic pattern, but this
48 example serves as a useful starting place.
50 At this point, you may be confused, since you have never seen a
51 @code{\score@{@}} before. This is because LilyPond automatically
52 adds the extra commands when you give it simple input. LilyPond
53 treats input like this:
62 as shorthand for this:
73 In other words, if the input contains a single music expression,
74 LilyPond will interpret the file as though the music expression
75 was wrapped up inside a @code{\score@{@}}.
79 A @code{\score} must begin with a compound music expression.
80 Remember that a music expression could be anything from a single
86 @var{...insert the whole score of a Wagner opera in here...}
92 Since everything is inside @code{@{ ... @}}, it counts
93 as one music expression.
95 As we saw previously, the @code{\score} can contain other things,
108 Some people put some of those commands outside the @code{\score}
109 block -- for example, @code{\header} is often placed above the
110 @code{\score}. That's just another shorthand that LilyPond
117 Another great shorthand is the ability to define variables. All
118 the templates use this
121 melody = \relative c' @{
130 When LilyPond looks at this file, it takes the value of
131 @code{melody} (everything after the equals sign) and inserts it
132 whenever it sees @code{\melody}. There's nothing special about
133 the names -- it could be @code{melody}, @code{global},
134 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
135 whatever variable names you want. For more details, see
136 @ruser{Saving typing with variables and functions}.
141 For a complete definition of the input format, see @ruser{File
145 @node Score is a (single) compound musical expression
146 @subsection Score is a (single) compound musical expression
148 @cindex Compound music expression
149 @cindex Music expression, compound
151 We saw the general organization of LilyPond input files in the
152 previous section, @ref{How LilyPond files work}. But we seemed to
153 skip over the most important part: how do we figure out what to
154 write after @code{\score}?
156 We didn't skip over it at all. The big mystery is simply that
157 there @emph{is} no mystery. This line explains it all:
160 @emph{A @code{\score} must begin with a compound music expression.}
164 You may find it useful to review @ruser{Music expressions
165 explained}. In that section, we saw how to build big music
166 expressions from small pieces -- we started from notes, then
167 chords, etc. Now we're going to start from a big music expression
168 and work our way down.
172 @{ % this brace begins the overall compound music expression
174 @var{...insert the whole score of a Wagner opera in here...}
176 @} % this brace ends the overall compound music expression
181 A whole Wagner opera would easily double the length of this
182 manual, so let's just add a singer and piano. We don't need a
183 @code{GrandStaff} for this ensemble, so we shall remove it. We
184 @emph{do} need a singer and a piano, though.
190 \new Staff = "singer" <<
192 \new PianoStaff = piano <<
200 Remember that we use @code{<<} and @code{>>} to show simultaneous
201 music. And we definitely want to show the vocal part and piano
202 part at the same time, not one after the other!
208 \new Staff = "singer" <<
209 \new Voice = "vocal" @{ @}
211 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
212 \new PianoStaff = "piano" <<
213 \new Staff = "upper" @{ @}
214 \new Staff = "lower" @{ @}
222 Now we have a lot more details. We have the singer's staff: it
223 contains a @code{Voice} (in LilyPond, this term refers to a set of
224 notes, not necessarily vocal notes -- for example, a violin
225 generally plays one voice) and some lyrics. We also have a piano
226 staff: it contains an upper staff (right hand) and a lower staff
229 At this stage, we could start filling in notes. Inside the curly
230 braces next to @code{\new Voice = vocal}, we could start writing
238 But if we did that, the @code{\score} section would get pretty
239 long, and it would be harder to understand what was happening. So
240 let's use variables instead.
250 \new Staff = "singer" <<
251 \new Voice = "vocal" @{ \melody @}
253 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
254 \new PianoStaff = "piano" <<
255 \new Staff = "upper" @{ \upper @}
256 \new Staff = "lower" @{ \lower @}
265 Remember that you can use almost any name you like. The
266 limitations on variable names are detailed in @ruser{File
269 When writing (or reading) a @code{\score} section, just take it
270 slowly and carefully. Start with the outer layer, then work on
271 each smaller layer. It also really helps to be strict with
272 indentation -- make sure that each item on the same layer starts
273 on the same horizontal position in your text editor.
276 @node Voices contain music
277 @section Voices contain music
279 TODO: something cheesy and vaguely witty about voices being the
280 fundamental thing that includes music in lilypond.
283 * I'm seeing Voices::
284 * Explicitly instantiating voices::
285 * Voices and vocals::
288 @c too cheesy? I'm not certain. -gp
289 @node I'm seeing Voices
290 @subsection I'm seeing Voices
294 TODO: add intro about voices vs. layers vs. whatever.
296 TODO: sex this up with colors and stuff. -gp
298 TODO: actually, a general rewrite is needed. -gp
301 The easiest way to enter fragments with more than one voice on a
302 staff is to enter each voice as a sequence (with @code{@{...@}}),
303 and combine them simultaneously, separating the voices with
308 @lilypond[quote,verbatim,fragment]
309 \new Staff \relative c' {
312 { g4 f e | d2 e2 } \\
313 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
321 The separator causes @internalsref{Voice}
322 contexts@footnote{Polyphonic voices are sometimes
323 called @q{layers} in other notation packages} to be instantiated.
324 They bear the names @code{"1"}, @code{"2"}, etc. In each of these
325 contexts, vertical direction of slurs, stems, etc., is set
328 These voices are all separate from the voice that contains the
329 notes just outside the @code{<< \\ >>} construct. This should be
330 noted when making changes at the voice level. This also means
331 that slurs and ties cannot go into or out of a @code{<< \\ >>}
332 construct. Conversely, parallel voices from separate @code{<< \\
333 >>} constructs on the same staff are the same voice. Here is the
334 same example, with different noteheads and colors for each voice.
335 Note that the change to the note-head style in the main voice does
336 not affect the inside of the @code{<< \\ >>} constructs. Also,
337 the change to the second voice in the first @code{<< \\ >>}
338 construct is effective in the second @code{<< \\ >>}, and the
339 voice is tied across the two constructs.
341 @cindex note heads, styles
343 @lilypond[quote,verbatim,fragment]
344 \new Staff \relative c' {
345 \override NoteHead #'style = #'cross
346 \override NoteHead #'color = #red
350 { \override NoteHead #'style = #'triangle
351 \override NoteHead #'color = #blue
356 { c8 b16 a b8 g ~ g2 } \\
357 { \override NoteHead #'style = #'slash
358 \override NoteHead #'color = #green
364 Polyphony does not change the relationship of notes within a
365 @code{\relative @{ @}} block. Each note is calculated relative to
366 the note immediately preceding it.
369 \relative @{ noteA << noteB \\ noteC >> noteD @}
372 @code{noteC} is relative to @code{noteB}, not @code{noteA};
373 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
377 @node Explicitly instantiating voices
378 @subsection Explicitly instantiating voices
380 TODO: more colors and stuff.
382 @internalsref{Voice} contexts can also be instantiated manually
383 inside a @code{<< >>} block to create polyphonic music, using
384 @code{\voiceOne}, up to @code{\voiceFour} to assign stem
385 directions and a horizontal shift for each part.
389 << \upper \\ \lower >>
397 \new Voice = "1" @{ \voiceOne \upper @}
398 \new Voice = "2" @{ \voiceTwo \lower @}
402 The @code{\voiceXXX} commands set the direction of stems, slurs,
403 ties, articulations, text annotations, augmentation dots of dotted
404 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
405 make these objects point upwards, while @code{\voiceTwo} and
406 @code{\voiceFour} make them point downwards. The command
407 @code{\oneVoice} will revert back to the normal setting.
409 An expression that appears directly inside a @code{<< >>} belongs
410 to the main voice. This is useful when extra voices appear while
411 the main voice is playing. Here is a more correct rendition of
412 the example from the previous section. The crossed colored
413 noteheads demonstrate that the main melody is now in a single
416 @lilypond[quote,ragged-right,verbatim]
417 \new Staff \relative c' {
418 \override NoteHead #'style = #'cross
419 \override NoteHead #'color = #red
424 \new Voice="1" { \voiceTwo
425 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
428 \new Voice { \voiceThree
437 The correct definition of the voices allows the melody to be
440 @lilypond[quote,ragged-right,verbatim]
441 \new Staff \relative c' {
446 \context Voice="1" { \voiceTwo
447 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
450 \new Voice { \voiceThree
459 Avoiding the @code{\\} separator also allows nesting polyphony
460 constructs, which in some case might be a more natural way to
463 @lilypond[quote,ragged-right,verbatim]
464 \new Staff \relative c' {
469 \context Voice="1" { \voiceTwo
473 \new Voice { \voiceThree
486 @node Voices and vocals
487 @subsection Voices and vocals
489 Vocal music presents a special difficulty: we need to combine two
490 expressions -- notes and lyrics.
492 You have already seen the @code{\lyricsAdd@{@}} command, which
493 handles simple cases for you. However, @code{\lyricsAdd@{@}} is
494 very limited. For most music, you must explicitly link the lyrics
495 to the notes with @code{\lyricsTo@{@}}
497 @lilypond[quote,verbatim,fragment]
499 \new Voice = "one" \relative c'' {
502 c4 b8. a16 g4. f8 e4 d c2
504 \new Lyrics \lyricsto "one" {
505 No more let sins and sor -- rows grow.
510 TODO: get some vocal person to write more.
513 @node TODO new sec fundamental
514 @section TODO new sec fundamental
520 * On the un-nestedness of brackets and ties::
523 @c my name start sucking the more docs I write. -gp
524 @node On the un-nestedness of brackets and ties
525 @subsection On the un-nestedness of brackets and ties
527 Different kinds of brackets and ties may be mixed freely,
529 TODO: improve this example
531 @lilypond[quote,verbatim,fragment,ragged-right]
533 r16[ g16 \times 2/3 {r16 e'8] }
534 g16( a \times 2/3 {b d e') }
535 g8[( a \times 2/3 {b d') e'~]}
536 \times 4/5 {e'32\( a b d' e'} a'4.\)
540 TODO... add more info? Fluff up the first sentence?
543 @node Extending the templates
544 @section Extending the templates
546 You've read the tutorial, you know how to write music. But how can you
547 get the staves that you want? The templates are ok, but what if you
548 want something that isn't covered?
551 * Soprano and cello::
552 * TODO another example of extending templates::
555 @node Soprano and cello
556 @unnumberedsubsec Soprano and cello
558 Start off with the template that seems closest to what you want to end
559 up with. Let's say that you want to write something for soprano and
560 cello. In this case, we would start with @q{Notes and lyrics} (for the
565 melody = \relative c' @{
579 \new Voice = "one" @{
583 \new Lyrics \lyricsto "one" \text
590 Now we want to add a cello part. Let's look at the @q{Notes only} example:
594 melody = \relative c' @{
609 We don't need two @code{\version} commands. We'll need the @code{melody}
610 section. We don't want two @code{\score} sections -- if we had two
611 @code{\score}s, we'd get the two parts separately. We want them together,
612 as a duet. Within the @code{\score} section, we don't need two
613 @code{\layout} or @code{\midi}.
615 If we simply cut and paste the @code{melody} section, we would end up with
616 two @code{melody} sections. So let's rename them. We'll call the section
617 for the soprano @code{sopranoMusic} and the section for the cello
618 @code{celloMusic}. While we're doing this, let's rename @code{text}
619 to be @code{sopranoLyrics}. Remember to rename both instances of all
620 these names -- both the initial definition (the
621 @code{melody = relative c' @{ } part) and the name's use (in the
622 @code{\score} section).
624 While we're doing this, let's change the cello part's staff -- celli
625 normally use bass clef. We'll also give the cello some different
630 sopranoMusic = \relative c' @{
638 sopranoLyrics = \lyricmode @{
642 celloMusic = \relative c @{
652 \new Voice = "one" @{
656 \new Lyrics \lyricsto "one" \sopranoLyrics
663 This is looking promising, but the cello part won't appear in the
664 score -- we haven't used it in the @code{\score} section. If we
665 want the cello part to appear under the soprano part, we need to add
668 \new Staff \celloMusic
672 underneath the soprano stuff. We also need to add @code{<<} and
673 @code{>>} around the music -- that tells LilyPond that there's
674 more than one thing (in this case, @code{Staff}) happening at once. The
675 @code{\score} looks like this now
681 \new Voice = "one" @{
685 \new Lyrics \lyricsto "one" \sopranoLyrics
687 \new Staff \celloMusic
695 This looks a bit messy; the indentation is messed up now. That is
696 easily fixed. Here's the complete soprano and cello template.
698 @lilypond[quote,verbatim,ragged-right]
700 sopranoMusic = \relative c' {
708 sopranoLyrics = \lyricmode {
712 celloMusic = \relative c {
727 \new Lyrics \lyricsto "one" \sopranoLyrics
729 \new Staff \celloMusic
737 @node TODO another example of extending templates
738 @unnumberedsubsec TODO another example of extending templates
740 TODO: somebody else fill this in. You guys like vocal stuff,
741 right? Get to it. :) -gp
745 @node Scores and parts
746 @section Scores and parts
748 TODO: this is really old stuff from the really old tutorial.
749 Rewrite, fix, etc. -gp
751 In orchestral music, all notes are printed twice. Once in a part for
752 the musicians, and once in a full score for the conductor. Variables can
753 be used to avoid double work. The music is entered once, and stored in
754 a variable. The contents of that variable is then used to generate
755 both the part and the full score.
757 It is convenient to define the notes in a special file. For example,
758 suppose that the file @file{horn-music.ly} contains the following part
759 of a horn/@/bassoon duo
762 hornNotes = \relative c @{
769 Then, an individual part is made by putting the following in a file
772 \include "horn-music.ly"
774 instrument = "Horn in F"
778 \transpose f c' \hornNotes
785 \include "horn-music.ly"
789 substitutes the contents of @file{horn-music.ly} at this position in
790 the file, so @code{hornNotes} is defined afterwards. The command
791 @code{\transpose f@tie{}c'} indicates that the argument, being
792 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
793 @samp{f} is denoted by notated @code{c'}, which corresponds with the
794 tuning of a normal French Horn in@tie{}F. The transposition can be seen
795 in the following output
797 @lilypond[quote,ragged-right]
798 \transpose f c' \relative c {
804 In ensemble pieces, one of the voices often does not play for many
805 measures. This is denoted by a special rest, the multi-measure
806 rest. It is entered with a capital @samp{R} followed by a duration
807 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
808 etc.). By multiplying the
809 duration, longer rests can be constructed. For example, this rest
810 takes 3@tie{}measures in 2/4 time
816 When printing the part, multi-rests
817 must be condensed. This is done by setting a run-time variable
820 \set Score.skipBars = ##t
824 This command sets the property @code{skipBars} in the
825 @code{Score} context to true (@code{##t}). Prepending the rest and
826 this option to the music above, leads to the following result
828 @lilypond[quote,ragged-right]
829 \transpose f c' \relative c {
831 \set Score.skipBars = ##t
838 The score is made by combining all of the music together. Assuming
839 that the other voice is in @code{bassoonNotes} in the file
840 @file{bassoon-music.ly}, a score is made with
843 \include "bassoon-music.ly"
844 \include "horn-music.ly"
847 \new Staff \hornNotes
848 \new Staff \bassoonNotes
855 @lilypond[quote,ragged-right]
863 r4 d,8 f | gis4 c | b bes |
864 a8 e f4 | g d | gis f