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 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{...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 single music
78 expression. Remember that a music expression could
79 be anything from a single note to a huge
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
116 Another great shorthand is the ability to define identifiers. All
117 the templates use this
120 melody = \relative c' @{
129 When LilyPond looks at this file, it takes the value of
130 @code{melody} (everything after the equals sign) and inserts it
131 whenever it sees @code{\melody}. There's nothing special about
132 the names -- it could be @code{melody}, @code{global},
133 @code{pianorighthand}, or @code{foofoobarbaz}. You can use
134 whatever variable names you want. For more details, see
135 @ruser{Saving typing with identifiers and functions}.
140 For a complete definition of the input format, see @ruser{File
144 @node Score is a single musical expression
145 @subsection Score is a single musical expression
147 We saw the general organization of LilyPond input files in the
148 previous section, @ref{How LilyPond files work}. But we seemed to
149 skip over the most important part: how do we figure out what to
150 write after @code{\score}?
152 We didn't skip over it at all. The big mystery is simply that
153 there @emph{is} no mystery. This line explains it all:
156 @emph{A @code{\score} must begin with a single music expression.}
160 You may find it useful to review @ruser{Music expressions
161 explained}. In that section, we saw how to build big music
162 expressions from small pieces -- we started from notes, then
163 chords, etc. Now we're going to start from a big music expression
164 and work our way down.
168 @{ % this brace begins the overall music expression
170 @var{...insert the whole score of a Wagner opera in here...}
172 @} % this brace ends the overall music expression
177 A whole Wagner opera would easily double the length of this
178 manual, so let's just add a singer and piano. We don't need a
179 @code{GrandStaff} for this ensemble, so we shall remove it. We
180 @emph{do} need a singer and a piano, though.
186 \new Staff = "singer" <<
188 \new PianoStaff = piano <<
196 Remember that we use @code{<<} and @code{>>} to show simultaneous
197 music. And we definitely want to show the vocal part and piano
198 part at the same time, not one after the other!
204 \new Staff = "singer" <<
205 \new Voice = "vocal" @{ @}
207 \new Lyrics \lyricsto vocal \new Lyrics @{ @}
208 \new PianoStaff = "piano" <<
209 \new Staff = "upper" @{ @}
210 \new Staff = "lower" @{ @}
218 Now we have a lot more details. We have the singer's staff: it
219 contains a @code{Voice} (in LilyPond, this term refers to a set of
220 notes, not necessarily vocal notes -- for example, a violin
221 generally plays one voice) and some lyrics. We also have a piano
222 staff: it contains an upper staff (right hand) and a lower staff
225 At this stage, we could start filling in notes. Inside the curly
226 braces next to @code{\new Voice = vocal}, we could start writing
234 But if we did that, the @code{\score} section would get pretty
235 long, and it would be harder to understand what was happening. So
236 let's use identifiers (or variables) instead.
246 \new Staff = "singer" <<
247 \new Voice = "vocal" @{ \melody @}
249 \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
250 \new PianoStaff = "piano" <<
251 \new Staff = "upper" @{ \upper @}
252 \new Staff = "lower" @{ \lower @}
261 Remember that you can use almost any name you like. The
262 limitations on identifier names are detailed in @ruser{File
265 When writing (or reading) a @code{\score} section, just take it
266 slowly and carefully. Start with the outer layer, then work on
267 each smaller layer. It also really helps to be strict with
268 indentation -- make sure that each item on the same layer starts
269 on the same horizontal position in your text editor.
272 @node Voices contain music
273 @section Voices contain music
275 TODO: something cheesy and vaguely witty about voices being the
276 fundamental thing that includes music in lilypond.
279 * I'm seeing Voices::
280 * Explicitly instantiating voices::
281 * Voices and vocals::
284 @c too cheesy? I'm not certain. -gp
285 @node I'm seeing Voices
286 @subsection I'm seeing Voices
290 TODO: add intro about voices vs. layers vs. whatever.
292 TODO: sex this up with colors and stuff. -gp
294 TODO: actually, a general rewrite is needed. -gp
297 The easiest way to enter fragments with more than one voice on a
298 staff is to enter each voice as a sequence (with @code{@{...@}}),
299 and combine them simultaneously, separating the voices with
304 @lilypond[quote,verbatim,fragment]
305 \new Staff \relative c' {
308 { g4 f e | d2 e2 } \\
309 { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
317 The separator causes @internalsref{Voice}
318 contexts@footnote{Polyphonic voices are sometimes
319 called @q{layers} in other notation packages} to be instantiated.
320 They bear the names @code{"1"}, @code{"2"}, etc. In each of these
321 contexts, vertical direction of slurs, stems, etc., is set
324 These voices are all separate from the voice that contains the
325 notes just outside the @code{<< \\ >>} construct. This should be
326 noted when making changes at the voice level. This also means
327 that slurs and ties cannot go into or out of a @code{<< \\ >>}
328 construct. Conversely, parallel voices from separate @code{<< \\
329 >>} constructs on the same staff are the same voice. Here is the
330 same example, with different noteheads and colors for each voice.
331 Note that the change to the note-head style in the main voice does
332 not affect the inside of the @code{<< \\ >>} constructs. Also,
333 the change to the second voice in the first @code{<< \\ >>}
334 construct is effective in the second @code{<< \\ >>}, and the
335 voice is tied across the two constructs.
337 @cindex note heads, styles
339 @lilypond[quote,verbatim,fragment]
340 \new Staff \relative c' {
341 \override NoteHead #'style = #'cross
342 \override NoteHead #'color = #red
346 { \override NoteHead #'style = #'triangle
347 \override NoteHead #'color = #blue
352 { c8 b16 a b8 g ~ g2 } \\
353 { \override NoteHead #'style = #'slash
354 \override NoteHead #'color = #green
360 Polyphony does not change the relationship of notes within a
361 @code{\relative @{ @}} block. Each note is calculated relative to
362 the note immediately preceding it.
365 \relative @{ noteA << noteB \\ noteC >> noteD @}
368 @code{noteC} is relative to @code{noteB}, not @code{noteA};
369 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
373 @node Explicitly instantiating voices
374 @subsection Explicitly instantiating voices
376 TODO: more colors and stuff.
378 @internalsref{Voice} contexts can also be instantiated manually
379 inside a @code{<< >>} block to create polyphonic music, using
380 @code{\voiceOne}, up to @code{\voiceFour} to assign stem
381 directions and a horizontal shift for each part.
385 << \upper \\ \lower >>
393 \new Voice = "1" @{ \voiceOne \upper @}
394 \new Voice = "2" @{ \voiceTwo \lower @}
398 The @code{\voiceXXX} commands set the direction of stems, slurs,
399 ties, articulations, text annotations, augmentation dots of dotted
400 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
401 make these objects point upwards, while @code{\voiceTwo} and
402 @code{\voiceFour} make them point downwards. The command
403 @code{\oneVoice} will revert back to the normal setting.
405 An expression that appears directly inside a @code{<< >>} belongs
406 to the main voice. This is useful when extra voices appear while
407 the main voice is playing. Here is a more correct rendition of
408 the example from the previous section. The crossed colored
409 noteheads demonstrate that the main melody is now in a single
412 @lilypond[quote,ragged-right,verbatim]
413 \new Staff \relative c' {
414 \override NoteHead #'style = #'cross
415 \override NoteHead #'color = #red
420 \new Voice="1" { \voiceTwo
421 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
424 \new Voice { \voiceThree
433 The correct definition of the voices allows the melody to be
436 @lilypond[quote,ragged-right,verbatim]
437 \new Staff \relative c' {
442 \context Voice="1" { \voiceTwo
443 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
446 \new Voice { \voiceThree
455 Avoiding the @code{\\} separator also allows nesting polyphony
456 constructs, which in some case might be a more natural way to
459 @lilypond[quote,ragged-right,verbatim]
460 \new Staff \relative c' {
465 \context Voice="1" { \voiceTwo
469 \new Voice { \voiceThree
482 @node Voices and vocals
483 @subsection Voices and vocals
485 Vocal music presents a special difficulty: we need to combine two
486 expressions -- notes and lyrics.
488 You have already seen the @code{\lyricsAdd@{@}} command, which
489 handles simple cases for you. However, @code{\lyricsAdd@{@}} is
490 very limited. For most music, you must explicitly link the lyrics
491 to the notes with @code{\lyricsTo@{@}}
493 @lilypond[quote,verbatim,fragment]
495 \new Voice = "one" \relative c'' {
498 c4 b8. a16 g4. f8 e4 d c2
500 \new Lyrics \lyricsto "one" {
501 No more let sins and sor -- rows grow.
506 TODO: get some vocal person to write more.
509 @node TODO new sec fundamental
510 @section TODO new sec fundamental
516 * On the un-nestedness of brackets and ties::
519 @c my name start sucking the more docs I write. -gp
520 @node On the un-nestedness of brackets and ties
521 @subsection On the un-nestedness of brackets and ties
523 Different kinds of brackets and ties may be mixed freely,
525 TODO: improve this example
527 @lilypond[quote,verbatim,fragment,ragged-right]
529 r16[ g16 \times 2/3 {r16 e'8] }
530 g16( a \times 2/3 {b d e') }
531 g8[( a \times 2/3 {b d') e'~]}
532 \times 4/5 {e'32\( a b d' e'} a'4.\)
536 TODO... add more info? Fluff up the first sentence?