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::
14 @node How LilyPond files work
15 @section How LilyPond files work
17 The LilyPond input format is quite free-form, giving experienced
18 users a lot of flexibility to structure their files however they
19 wish. However, this flexibility can make things confusing for new
20 users. This section will explain some of this structure, but may
21 gloss over some details in favor of simplicity. For a complete
22 description of the input format, see @ruser{File structure}.
25 * Introduction to the LilyPond file structure::
26 * Score is a (single) compound musical expression::
29 @node Introduction to the LilyPond file structure
30 @subsection Introduction to the LilyPond file structure
32 A basic example of a lilypond input file is
37 @var{...compound music expression...} % all the music goes here!
45 There are many variations of this basic pattern, but this
46 example serves as a useful starting place.
48 At this point, you may be confused, since you have never seen a
49 @code{\score@{@}} before. This is because LilyPond automatically
50 adds the extra commands when you give it simple input. LilyPond
51 treats input like this:
60 as shorthand for this:
71 In other words, if the input contains a single music expression,
72 LilyPond will interpret the file as though the music expression
73 was wrapped up inside a @code{\score@{@}}.
77 A @code{\score} must begin with a compound music expression.
78 Remember that a music expression could be anything from a single
84 @var{...insert the whole score of a Wagner opera in here...}
90 Since everything is inside @code{@{ ... @}}, it counts
91 as one music expression.
93 As we saw previously, the @code{\score} can contain other things,
106 Some people put some of those commands outside the @code{\score}
107 block -- for example, @code{\header} is often placed above the
108 @code{\score}. That's just another shorthand that LilyPond
115 Another great shorthand is the ability to define variables. All
116 the templates use this
119 melody = \relative c' @{
128 When LilyPond looks at this file, it takes the value of
129 @code{melody} (everything after the equals sign) and inserts it
130 whenever it sees @code{\melody}. There's nothing special about
131 the names -- it could be @code{melody}, @code{global},
132 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
133 whatever variable names you want. For more details, see
134 @ruser{Saving typing with variables and functions}.
139 For a complete definition of the input format, see @ruser{File
143 @node Score is a (single) compound musical expression
144 @subsection Score is a (single) compound musical expression
146 @cindex Compound music expression
147 @cindex Music expression, compound
149 We saw the general organization of LilyPond input files in the
150 previous section, @ref{How LilyPond files work}. But we seemed to
151 skip over the most important part: how do we figure out what to
152 write after @code{\score}?
154 We didn't skip over it at all. The big mystery is simply that
155 there @emph{is} no mystery. This line explains it all:
158 @emph{A @code{\score} must begin with a compound music expression.}
162 You may find it useful to review @ruser{Music expressions
163 explained}. In that section, we saw how to build big music
164 expressions from small pieces -- we started from notes, then
165 chords, etc. Now we're going to start from a big music expression
166 and work our way down.
170 @{ % this brace begins the overall compound music expression
172 @var{...insert the whole score of a Wagner opera in here...}
174 @} % this brace ends the overall compound music expression
179 A whole Wagner opera would easily double the length of this
180 manual, so let's just add a singer and piano. We don't need a
181 @code{GrandStaff} for this ensemble, so we shall remove it. We
182 @emph{do} need a singer and a piano, though.
188 \new Staff = "singer" <<
190 \new PianoStaff = piano <<
198 Remember that we use @code{<<} and @code{>>} to show simultaneous
199 music. And we definitely want to show the vocal part and piano
200 part at the same time, not one after the other!
206 \new Staff = "singer" <<
207 \new Voice = "vocal" @{ @}
209 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
210 \new PianoStaff = "piano" <<
211 \new Staff = "upper" @{ @}
212 \new Staff = "lower" @{ @}
220 Now we have a lot more details. We have the singer's staff: it
221 contains a @code{Voice} (in LilyPond, this term refers to a set of
222 notes, not necessarily vocal notes -- for example, a violin
223 generally plays one voice) and some lyrics. We also have a piano
224 staff: it contains an upper staff (right hand) and a lower staff
227 At this stage, we could start filling in notes. Inside the curly
228 braces next to @code{\new Voice = vocal}, we could start writing
236 But if we did that, the @code{\score} section would get pretty
237 long, and it would be harder to understand what was happening. So
238 let's use variables instead.
248 \new Staff = "singer" <<
249 \new Voice = "vocal" @{ \melody @}
251 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
252 \new PianoStaff = "piano" <<
253 \new Staff = "upper" @{ \upper @}
254 \new Staff = "lower" @{ \lower @}
263 Remember that you can use almost any name you like. The
264 limitations on variable names are detailed in @ruser{File
267 When writing (or reading) a @code{\score} section, just take it
268 slowly and carefully. Start with the outer layer, then work on
269 each smaller layer. It also really helps to be strict with
270 indentation -- make sure that each item on the same layer starts
271 on the same horizontal position in your text editor.
274 @node Voices contain music
275 @section Voices contain music
277 TODO: something cheesy and vaguely witty about voices being the
278 fundamental thing that includes music in lilypond.
281 * I'm seeing Voices::
282 * Explicitly instantiating voices::
283 * Voices and vocals::
286 @c too cheesy? I'm not certain. -gp
287 @node I'm seeing Voices
288 @subsection I'm seeing Voices
292 TODO: add intro about voices vs. layers vs. whatever.
294 TODO: sex this up with colors and stuff. -gp
296 TODO: actually, a general rewrite is needed. -gp
299 The easiest way to enter fragments with more than one voice on a
300 staff is to enter each voice as a sequence (with @code{@{...@}}),
301 and combine them simultaneously, separating the voices with
306 @lilypond[quote,verbatim,fragment]
307 \new Staff \relative c' {
310 { g4 f e | d2 e2 } \\
311 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
319 The separator causes @internalsref{Voice}
320 contexts@footnote{Polyphonic voices are sometimes
321 called @q{layers} in other notation packages} to be instantiated.
322 They bear the names @code{"1"}, @code{"2"}, etc. In each of these
323 contexts, vertical direction of slurs, stems, etc., is set
326 These voices are all separate from the voice that contains the
327 notes just outside the @code{<< \\ >>} construct. This should be
328 noted when making changes at the voice level. This also means
329 that slurs and ties cannot go into or out of a @code{<< \\ >>}
330 construct. Conversely, parallel voices from separate @code{<< \\
331 >>} constructs on the same staff are the same voice. Here is the
332 same example, with different noteheads and colors for each voice.
333 Note that the change to the note-head style in the main voice does
334 not affect the inside of the @code{<< \\ >>} constructs. Also,
335 the change to the second voice in the first @code{<< \\ >>}
336 construct is effective in the second @code{<< \\ >>}, and the
337 voice is tied across the two constructs.
339 @cindex note heads, styles
341 @lilypond[quote,verbatim,fragment]
342 \new Staff \relative c' {
343 \override NoteHead #'style = #'cross
344 \override NoteHead #'color = #red
348 { \override NoteHead #'style = #'triangle
349 \override NoteHead #'color = #blue
354 { c8 b16 a b8 g ~ g2 } \\
355 { \override NoteHead #'style = #'slash
356 \override NoteHead #'color = #green
362 Polyphony does not change the relationship of notes within a
363 @code{\relative @{ @}} block. Each note is calculated relative to
364 the note immediately preceding it.
367 \relative @{ noteA << noteB \\ noteC >> noteD @}
370 @code{noteC} is relative to @code{noteB}, not @code{noteA};
371 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
375 @node Explicitly instantiating voices
376 @subsection Explicitly instantiating voices
378 TODO: more colors and stuff.
380 @internalsref{Voice} contexts can also be instantiated manually
381 inside a @code{<< >>} block to create polyphonic music, using
382 @code{\voiceOne}, up to @code{\voiceFour} to assign stem
383 directions and a horizontal shift for each part.
387 << \upper \\ \lower >>
395 \new Voice = "1" @{ \voiceOne \upper @}
396 \new Voice = "2" @{ \voiceTwo \lower @}
400 The @code{\voiceXXX} commands set the direction of stems, slurs,
401 ties, articulations, text annotations, augmentation dots of dotted
402 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
403 make these objects point upwards, while @code{\voiceTwo} and
404 @code{\voiceFour} make them point downwards. The command
405 @code{\oneVoice} will revert back to the normal setting.
407 An expression that appears directly inside a @code{<< >>} belongs
408 to the main voice. This is useful when extra voices appear while
409 the main voice is playing. Here is a more correct rendition of
410 the example from the previous section. The crossed colored
411 noteheads demonstrate that the main melody is now in a single
414 @lilypond[quote,ragged-right,verbatim]
415 \new Staff \relative c' {
416 \override NoteHead #'style = #'cross
417 \override NoteHead #'color = #red
422 \new Voice="1" { \voiceTwo
423 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
426 \new Voice { \voiceThree
435 The correct definition of the voices allows the melody to be
438 @lilypond[quote,ragged-right,verbatim]
439 \new Staff \relative c' {
444 \context Voice="1" { \voiceTwo
445 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
448 \new Voice { \voiceThree
457 Avoiding the @code{\\} separator also allows nesting polyphony
458 constructs, which in some case might be a more natural way to
461 @lilypond[quote,ragged-right,verbatim]
462 \new Staff \relative c' {
467 \context Voice="1" { \voiceTwo
471 \new Voice { \voiceThree
484 @node Voices and vocals
485 @subsection Voices and vocals
487 Vocal music presents a special difficulty: we need to combine two
488 expressions -- notes and lyrics.
490 You have already seen the @code{\lyricsAdd@{@}} command, which
491 handles simple cases for you. However, @code{\lyricsAdd@{@}} is
492 very limited. For most music, you must explicitly link the lyrics
493 to the notes with @code{\lyricsTo@{@}}
495 @lilypond[quote,verbatim,fragment]
497 \new Voice = "one" \relative c'' {
500 c4 b8. a16 g4. f8 e4 d c2
502 \new Lyrics \lyricsto "one" {
503 No more let sins and sor -- rows grow.
508 TODO: get some vocal person to write more.
511 @node TODO new sec fundamental
512 @section TODO new sec fundamental
518 * On the un-nestedness of brackets and ties::
521 @c my name start sucking the more docs I write. -gp
522 @node On the un-nestedness of brackets and ties
523 @subsection On the un-nestedness of brackets and ties
525 Different kinds of brackets and ties may be mixed freely,
527 TODO: improve this example
529 @lilypond[quote,verbatim,fragment,ragged-right]
531 r16[ g16 \times 2/3 {r16 e'8] }
532 g16( a \times 2/3 {b d e') }
533 g8[( a \times 2/3 {b d') e'~]}
534 \times 4/5 {e'32\( a b d' e'} a'4.\)
538 TODO... add more info? Fluff up the first sentence?