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::
524 @c my name start sucking the more docs I write. -gp
525 @node On the un-nestedness of brackets and ties
526 @subsection On the un-nestedness of brackets and ties
528 Different kinds of brackets and ties may be mixed freely,
530 TODO: improve this example
532 @lilypond[quote,verbatim,fragment,ragged-right]
534 r16[ g16 \times 2/3 {r16 e'8] }
535 g16( a \times 2/3 {b d e') }
536 g8[( a \times 2/3 {b d') e'~]}
537 \times 4/5 {e'32\( a b d' e'} a'4.\)
541 TODO... add more info? Fluff up the first sentence?
545 @subsection Up and down
549 By default, lilypnod does a pretty jazz'n job of picking
550 directions. But in some cases, it may be desirable to force a
561 @node Extending the templates
562 @section Extending the templates
564 You've read the tutorial, you know how to write music. But how can you
565 get the staves that you want? The templates are ok, but what if you
566 want something that isn't covered?
569 * Soprano and cello::
570 * TODO another example of extending templates::
573 @node Soprano and cello
574 @unnumberedsubsec Soprano and cello
576 Start off with the template that seems closest to what you want to end
577 up with. Let's say that you want to write something for soprano and
578 cello. In this case, we would start with @q{Notes and lyrics} (for the
583 melody = \relative c' @{
597 \new Voice = "one" @{
601 \new Lyrics \lyricsto "one" \text
608 Now we want to add a cello part. Let's look at the @q{Notes only} example:
612 melody = \relative c' @{
627 We don't need two @code{\version} commands. We'll need the @code{melody}
628 section. We don't want two @code{\score} sections -- if we had two
629 @code{\score}s, we'd get the two parts separately. We want them together,
630 as a duet. Within the @code{\score} section, we don't need two
631 @code{\layout} or @code{\midi}.
633 If we simply cut and paste the @code{melody} section, we would end up with
634 two @code{melody} sections. So let's rename them. We'll call the section
635 for the soprano @code{sopranoMusic} and the section for the cello
636 @code{celloMusic}. While we're doing this, let's rename @code{text}
637 to be @code{sopranoLyrics}. Remember to rename both instances of all
638 these names -- both the initial definition (the
639 @code{melody = relative c' @{ } part) and the name's use (in the
640 @code{\score} section).
642 While we're doing this, let's change the cello part's staff -- celli
643 normally use bass clef. We'll also give the cello some different
648 sopranoMusic = \relative c' @{
656 sopranoLyrics = \lyricmode @{
660 celloMusic = \relative c @{
670 \new Voice = "one" @{
674 \new Lyrics \lyricsto "one" \sopranoLyrics
681 This is looking promising, but the cello part won't appear in the
682 score -- we haven't used it in the @code{\score} section. If we
683 want the cello part to appear under the soprano part, we need to add
686 \new Staff \celloMusic
690 underneath the soprano stuff. We also need to add @code{<<} and
691 @code{>>} around the music -- that tells LilyPond that there's
692 more than one thing (in this case, @code{Staff}) happening at once. The
693 @code{\score} looks like this now
699 \new Voice = "one" @{
703 \new Lyrics \lyricsto "one" \sopranoLyrics
705 \new Staff \celloMusic
713 This looks a bit messy; the indentation is messed up now. That is
714 easily fixed. Here's the complete soprano and cello template.
716 @lilypond[quote,verbatim,ragged-right]
718 sopranoMusic = \relative c' {
726 sopranoLyrics = \lyricmode {
730 celloMusic = \relative c {
745 \new Lyrics \lyricsto "one" \sopranoLyrics
747 \new Staff \celloMusic
755 @node TODO another example of extending templates
756 @unnumberedsubsec TODO another example of extending templates
758 TODO: somebody else fill this in. You guys like vocal stuff,
759 right? Get to it. :) -gp
763 @node Scores and parts
764 @section Scores and parts
766 TODO: this is really old stuff from the really old tutorial.
767 Rewrite, fix, etc. -gp
769 In orchestral music, all notes are printed twice. Once in a part for
770 the musicians, and once in a full score for the conductor. Variables can
771 be used to avoid double work. The music is entered once, and stored in
772 a variable. The contents of that variable is then used to generate
773 both the part and the full score.
775 It is convenient to define the notes in a special file. For example,
776 suppose that the file @file{horn-music.ly} contains the following part
777 of a horn/@/bassoon duo
780 hornNotes = \relative c @{
787 Then, an individual part is made by putting the following in a file
790 \include "horn-music.ly"
792 instrument = "Horn in F"
796 \transpose f c' \hornNotes
803 \include "horn-music.ly"
807 substitutes the contents of @file{horn-music.ly} at this position in
808 the file, so @code{hornNotes} is defined afterwards. The command
809 @code{\transpose f@tie{}c'} indicates that the argument, being
810 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
811 @samp{f} is denoted by notated @code{c'}, which corresponds with the
812 tuning of a normal French Horn in@tie{}F. The transposition can be seen
813 in the following output
815 @lilypond[quote,ragged-right]
816 \transpose f c' \relative c {
822 In ensemble pieces, one of the voices often does not play for many
823 measures. This is denoted by a special rest, the multi-measure
824 rest. It is entered with a capital @samp{R} followed by a duration
825 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
826 etc.). By multiplying the
827 duration, longer rests can be constructed. For example, this rest
828 takes 3@tie{}measures in 2/4 time
834 When printing the part, multi-rests
835 must be condensed. This is done by setting a run-time variable
838 \set Score.skipBars = ##t
842 This command sets the property @code{skipBars} in the
843 @code{Score} context to true (@code{##t}). Prepending the rest and
844 this option to the music above, leads to the following result
846 @lilypond[quote,ragged-right]
847 \transpose f c' \relative c {
849 \set Score.skipBars = ##t
856 The score is made by combining all of the music together. Assuming
857 that the other voice is in @code{bassoonNotes} in the file
858 @file{bassoon-music.ly}, a score is made with
861 \include "bassoon-music.ly"
862 \include "horn-music.ly"
865 \new Staff \hornNotes
866 \new Staff \bassoonNotes
873 @lilypond[quote,ragged-right]
881 r4 d,8 f | gis4 c | b bes |
882 a8 e f4 | g d | gis f