2 @c -*- coding: utf-8; mode: texinfo; -*-
3 @c This file is part of lilypond-learning.tely
5 @node Fundamental concepts
6 @chapter Fundamental concepts
9 * How LilyPond files work::
10 * Voices contain music::
11 * TODO new sec fundamental::
12 * Extending the templates::
17 @node How LilyPond files work
18 @section How LilyPond files work
20 The LilyPond input format is quite free-form, giving experienced
21 users a lot of flexibility to structure their files however they
22 wish. However, this flexibility can make things confusing for new
23 users. This section will explain some of this structure, but may
24 gloss over some details in favor of simplicity. For a complete
25 description of the input format, see @ruser{File structure}.
28 * Introduction to the LilyPond file structure::
29 * Score is a (single) compound musical expression::
32 @node Introduction to the LilyPond file structure
33 @subsection Introduction to the LilyPond file structure
35 A basic example of a lilypond input file is
40 @var{...compound music expression...} % all the music goes here!
48 There are many variations of this basic pattern, but this
49 example serves as a useful starting place.
51 At this point, you may be confused, since you have never seen a
52 @code{\score@{@}} before. This is because LilyPond automatically
53 adds the extra commands when you give it simple input. LilyPond
54 treats input like this:
63 as shorthand for this:
74 In other words, if the input contains a single music expression,
75 LilyPond will interpret the file as though the music expression
76 was wrapped up inside a @code{\score@{@}}.
80 A @code{\score} must begin with a compound music expression.
81 Remember that a music expression could be anything from a single
87 @var{...insert the whole score of a Wagner opera in here...}
93 Since everything is inside @code{@{ ... @}}, it counts
94 as one music expression.
96 As we saw previously, the @code{\score} can contain other things,
109 Some people put some of those commands outside the @code{\score}
110 block -- for example, @code{\header} is often placed above the
111 @code{\score}. That's just another shorthand that LilyPond
118 Another great shorthand is the ability to define variables. All
119 the templates use this
122 melody = \relative c' @{
131 When LilyPond looks at this file, it takes the value of
132 @code{melody} (everything after the equals sign) and inserts it
133 whenever it sees @code{\melody}. There's nothing special about
134 the names -- it could be @code{melody}, @code{global},
135 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
136 whatever variable names you want. For more details, see
137 @ruser{Saving typing with variables and functions}.
142 For a complete definition of the input format, see @ruser{File
146 @node Score is a (single) compound musical expression
147 @subsection Score is a (single) compound musical expression
149 @cindex Compound music expression
150 @cindex Music expression, compound
152 We saw the general organization of LilyPond input files in the
153 previous section, @ref{How LilyPond files work}. But we seemed to
154 skip over the most important part: how do we figure out what to
155 write after @code{\score}?
157 We didn't skip over it at all. The big mystery is simply that
158 there @emph{is} no mystery. This line explains it all:
161 @emph{A @code{\score} must begin with a compound music expression.}
165 You may find it useful to review @ruser{Music expressions
166 explained}. In that section, we saw how to build big music
167 expressions from small pieces -- we started from notes, then
168 chords, etc. Now we're going to start from a big music expression
169 and work our way down.
173 @{ % this brace begins the overall compound music expression
175 @var{...insert the whole score of a Wagner opera in here...}
177 @} % this brace ends the overall compound music expression
182 A whole Wagner opera would easily double the length of this
183 manual, so let's just add a singer and piano. We don't need a
184 @code{GrandStaff} for this ensemble, so we shall remove it. We
185 @emph{do} need a singer and a piano, though.
191 \new Staff = "singer" <<
193 \new PianoStaff = piano <<
201 Remember that we use @code{<<} and @code{>>} to show simultaneous
202 music. And we definitely want to show the vocal part and piano
203 part at the same time, not one after the other!
209 \new Staff = "singer" <<
210 \new Voice = "vocal" @{ @}
212 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
213 \new PianoStaff = "piano" <<
214 \new Staff = "upper" @{ @}
215 \new Staff = "lower" @{ @}
223 Now we have a lot more details. We have the singer's staff: it
224 contains a @code{Voice} (in LilyPond, this term refers to a set of
225 notes, not necessarily vocal notes -- for example, a violin
226 generally plays one voice) and some lyrics. We also have a piano
227 staff: it contains an upper staff (right hand) and a lower staff
230 At this stage, we could start filling in notes. Inside the curly
231 braces next to @code{\new Voice = vocal}, we could start writing
239 But if we did that, the @code{\score} section would get pretty
240 long, and it would be harder to understand what was happening. So
241 let's use variables instead.
251 \new Staff = "singer" <<
252 \new Voice = "vocal" @{ \melody @}
254 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
255 \new PianoStaff = "piano" <<
256 \new Staff = "upper" @{ \upper @}
257 \new Staff = "lower" @{ \lower @}
266 Remember that you can use almost any name you like. The
267 limitations on variable names are detailed in @ruser{File
270 When writing (or reading) a @code{\score} section, just take it
271 slowly and carefully. Start with the outer layer, then work on
272 each smaller layer. It also really helps to be strict with
273 indentation -- make sure that each item on the same layer starts
274 on the same horizontal position in your text editor.
277 @node Voices contain music
278 @section Voices contain music
280 TODO: something cheesy and vaguely witty about voices being the
281 fundamental thing that includes music in lilypond.
284 * I'm seeing Voices::
285 * Explicitly instantiating voices::
286 * Voices and vocals::
289 @c too cheesy? I'm not certain. -gp
290 @node I'm seeing Voices
291 @subsection I'm seeing Voices
295 TODO: add intro about voices vs. layers vs. whatever.
297 TODO: sex this up with colors and stuff. -gp
299 TODO: actually, a general rewrite is needed. -gp
302 The easiest way to enter fragments with more than one voice on a
303 staff is to enter each voice as a sequence (with @code{@{...@}}),
304 and combine them simultaneously, separating the voices with
309 @lilypond[quote,verbatim,fragment]
310 \new Staff \relative c' {
313 { g4 f e | d2 e2 } \\
314 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
322 The separator causes @internalsref{Voice}
323 contexts@footnote{Polyphonic voices are sometimes
324 called @q{layers} in other notation packages} to be instantiated.
325 They bear the names @code{"1"}, @code{"2"}, etc. In each of these
326 contexts, vertical direction of slurs, stems, etc., is set
329 These voices are all separate from the voice that contains the
330 notes just outside the @code{<< \\ >>} construct. This should be
331 noted when making changes at the voice level. This also means
332 that slurs and ties cannot go into or out of a @code{<< \\ >>}
333 construct. Conversely, parallel voices from separate @code{<< \\
334 >>} constructs on the same staff are the same voice. Here is the
335 same example, with different noteheads and colors for each voice.
336 Note that the change to the note-head style in the main voice does
337 not affect the inside of the @code{<< \\ >>} constructs. Also,
338 the change to the second voice in the first @code{<< \\ >>}
339 construct is effective in the second @code{<< \\ >>}, and the
340 voice is tied across the two constructs.
342 @cindex note heads, styles
344 @lilypond[quote,verbatim,fragment]
345 \new Staff \relative c' {
346 \override NoteHead #'style = #'cross
347 \override NoteHead #'color = #red
351 { \override NoteHead #'style = #'triangle
352 \override NoteHead #'color = #blue
357 { c8 b16 a b8 g ~ g2 } \\
358 { \override NoteHead #'style = #'slash
359 \override NoteHead #'color = #green
365 Polyphony does not change the relationship of notes within a
366 @code{\relative @{ @}} block. Each note is calculated relative to
367 the note immediately preceding it.
370 \relative @{ noteA << noteB \\ noteC >> noteD @}
373 @code{noteC} is relative to @code{noteB}, not @code{noteA};
374 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
378 @node Explicitly instantiating voices
379 @subsection Explicitly instantiating voices
381 TODO: more colors and stuff.
383 @internalsref{Voice} contexts can also be instantiated manually
384 inside a @code{<< >>} block to create polyphonic music, using
385 @code{\voiceOne}, up to @code{\voiceFour} to assign stem
386 directions and a horizontal shift for each part.
390 << \upper \\ \lower >>
398 \new Voice = "1" @{ \voiceOne \upper @}
399 \new Voice = "2" @{ \voiceTwo \lower @}
403 The @code{\voiceXXX} commands set the direction of stems, slurs,
404 ties, articulations, text annotations, augmentation dots of dotted
405 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
406 make these objects point upwards, while @code{\voiceTwo} and
407 @code{\voiceFour} make them point downwards. The command
408 @code{\oneVoice} will revert back to the normal setting.
410 An expression that appears directly inside a @code{<< >>} belongs
411 to the main voice. This is useful when extra voices appear while
412 the main voice is playing. Here is a more correct rendition of
413 the example from the previous section. The crossed colored
414 noteheads demonstrate that the main melody is now in a single
417 @lilypond[quote,ragged-right,verbatim]
418 \new Staff \relative c' {
419 \override NoteHead #'style = #'cross
420 \override NoteHead #'color = #red
425 \new Voice="1" { \voiceTwo
426 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
429 \new Voice { \voiceThree
438 The correct definition of the voices allows the melody to be
441 @lilypond[quote,ragged-right,verbatim]
442 \new Staff \relative c' {
447 \context Voice="1" { \voiceTwo
448 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
451 \new Voice { \voiceThree
460 Avoiding the @code{\\} separator also allows nesting polyphony
461 constructs, which in some case might be a more natural way to
464 @lilypond[quote,ragged-right,verbatim]
465 \new Staff \relative c' {
470 \context Voice="1" { \voiceTwo
474 \new Voice { \voiceThree
487 @node Voices and vocals
488 @subsection Voices and vocals
490 Vocal music presents a special difficulty: we need to combine two
491 expressions -- notes and lyrics.
493 You have already seen the @code{\lyricsAdd@{@}} command, which
494 handles simple cases for you. However, @code{\lyricsAdd@{@}} is
495 very limited. For most music, you must explicitly link the lyrics
496 to the notes with @code{\lyricsTo@{@}}
498 @lilypond[quote,verbatim,fragment]
500 \new Voice = "one" \relative c'' {
503 c4 b8. a16 g4. f8 e4 d c2
505 \new Lyrics \lyricsto "one" {
506 No more let sins and sor -- rows grow.
511 TODO: get some vocal person to write more.
514 @node TODO new sec fundamental
515 @section TODO new sec fundamental
521 * On the un-nestedness of brackets and ties::
523 * Distances and measurements::
526 @c my name start sucking the more docs I write. -gp
527 @node On the un-nestedness of brackets and ties
528 @subsection On the un-nestedness of brackets and ties
530 Different kinds of brackets and ties may be mixed freely,
532 TODO: improve this example
534 @lilypond[quote,verbatim,fragment,ragged-right]
536 r16[ g16 \times 2/3 {r16 e'8] }
537 g16( a \times 2/3 {b d e') }
538 g8[( a \times 2/3 {b d') e'~]}
539 \times 4/5 {e'32\( a b d' e'} a'4.\)
543 TODO... add more info? Fluff up the first sentence?
547 @subsection Up and down
551 By default, lilypnod does a pretty jazz'n job of picking
552 directions. But in some cases, it may be desirable to force a
561 @node Distances and measurements
562 @subsection Distances and measurements
566 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
570 @node Extending the templates
571 @section Extending the templates
573 You've read the tutorial, you know how to write music. But how can you
574 get the staves that you want? The templates are ok, but what if you
575 want something that isn't covered?
578 * Soprano and cello::
579 * TODO another example of extending templates::
582 @node Soprano and cello
583 @unnumberedsubsec Soprano and cello
585 Start off with the template that seems closest to what you want to end
586 up with. Let's say that you want to write something for soprano and
587 cello. In this case, we would start with @q{Notes and lyrics} (for the
592 melody = \relative c' @{
606 \new Voice = "one" @{
610 \new Lyrics \lyricsto "one" \text
617 Now we want to add a cello part. Let's look at the @q{Notes only} example:
621 melody = \relative c' @{
636 We don't need two @code{\version} commands. We'll need the @code{melody}
637 section. We don't want two @code{\score} sections -- if we had two
638 @code{\score}s, we'd get the two parts separately. We want them together,
639 as a duet. Within the @code{\score} section, we don't need two
640 @code{\layout} or @code{\midi}.
642 If we simply cut and paste the @code{melody} section, we would end up with
643 two @code{melody} sections. So let's rename them. We'll call the section
644 for the soprano @code{sopranoMusic} and the section for the cello
645 @code{celloMusic}. While we're doing this, let's rename @code{text}
646 to be @code{sopranoLyrics}. Remember to rename both instances of all
647 these names -- both the initial definition (the
648 @code{melody = relative c' @{ } part) and the name's use (in the
649 @code{\score} section).
651 While we're doing this, let's change the cello part's staff -- celli
652 normally use bass clef. We'll also give the cello some different
657 sopranoMusic = \relative c' @{
665 sopranoLyrics = \lyricmode @{
669 celloMusic = \relative c @{
679 \new Voice = "one" @{
683 \new Lyrics \lyricsto "one" \sopranoLyrics
690 This is looking promising, but the cello part won't appear in the
691 score -- we haven't used it in the @code{\score} section. If we
692 want the cello part to appear under the soprano part, we need to add
695 \new Staff \celloMusic
699 underneath the soprano stuff. We also need to add @code{<<} and
700 @code{>>} around the music -- that tells LilyPond that there's
701 more than one thing (in this case, @code{Staff}) happening at once. The
702 @code{\score} looks like this now
708 \new Voice = "one" @{
712 \new Lyrics \lyricsto "one" \sopranoLyrics
714 \new Staff \celloMusic
722 This looks a bit messy; the indentation is messed up now. That is
723 easily fixed. Here's the complete soprano and cello template.
725 @lilypond[quote,verbatim,ragged-right]
727 sopranoMusic = \relative c' {
735 sopranoLyrics = \lyricmode {
739 celloMusic = \relative c {
754 \new Lyrics \lyricsto "one" \sopranoLyrics
756 \new Staff \celloMusic
764 @node TODO another example of extending templates
765 @unnumberedsubsec TODO another example of extending templates
767 TODO: somebody else fill this in. You guys like vocal stuff,
768 right? Get to it. :) -gp
772 @node Scores and parts
773 @section Scores and parts
775 TODO: this is really old stuff from the really old tutorial.
776 Rewrite, fix, etc. -gp
778 In orchestral music, all notes are printed twice. Once in a part for
779 the musicians, and once in a full score for the conductor. Variables can
780 be used to avoid double work. The music is entered once, and stored in
781 a variable. The contents of that variable is then used to generate
782 both the part and the full score.
784 It is convenient to define the notes in a special file. For example,
785 suppose that the file @file{horn-music.ly} contains the following part
786 of a horn/@/bassoon duo
789 hornNotes = \relative c @{
796 Then, an individual part is made by putting the following in a file
799 \include "horn-music.ly"
801 instrument = "Horn in F"
805 \transpose f c' \hornNotes
812 \include "horn-music.ly"
816 substitutes the contents of @file{horn-music.ly} at this position in
817 the file, so @code{hornNotes} is defined afterwards. The command
818 @code{\transpose f@tie{}c'} indicates that the argument, being
819 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
820 @samp{f} is denoted by notated @code{c'}, which corresponds with the
821 tuning of a normal French Horn in@tie{}F. The transposition can be seen
822 in the following output
824 @lilypond[quote,ragged-right]
825 \transpose f c' \relative c {
831 In ensemble pieces, one of the voices often does not play for many
832 measures. This is denoted by a special rest, the multi-measure
833 rest. It is entered with a capital @samp{R} followed by a duration
834 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
835 etc.). By multiplying the
836 duration, longer rests can be constructed. For example, this rest
837 takes 3@tie{}measures in 2/4 time
843 When printing the part, multi-rests
844 must be condensed. This is done by setting a run-time variable
847 \set Score.skipBars = ##t
851 This command sets the property @code{skipBars} in the
852 @code{Score} context to true (@code{##t}). Prepending the rest and
853 this option to the music above, leads to the following result
855 @lilypond[quote,ragged-right]
856 \transpose f c' \relative c {
858 \set Score.skipBars = ##t
865 The score is made by combining all of the music together. Assuming
866 that the other voice is in @code{bassoonNotes} in the file
867 @file{bassoon-music.ly}, a score is made with
870 \include "bassoon-music.ly"
871 \include "horn-music.ly"
874 \new Staff \hornNotes
875 \new Staff \bassoonNotes
882 @lilypond[quote,ragged-right]
890 r4 d,8 f | gis4 c | b bes |
891 a8 e f4 | g d | gis f