There are many variations of this basic pattern, but this
example serves as a useful starting place.
-At this point, you may be confused, since you have never seen a
-@code{\score@{@}} before. This is because LilyPond automatically
-adds the extra commands when you give it simple input. LilyPond
-treats input like this:
+Up to this point none of the examples you have seen have used a
+@code{\score@{@}} command. This is because LilyPond automatically
+adds the extra commands which are needed when you give it simple
+input. LilyPond treats input like this:
@example
\relative c'' @{
as shorthand for this:
@example
-\score @{
- \relative c'' @{
- c4 a b c
+\book @{
+ \score @{
+ \new Staff @{
+ \new Voice @{
+ \relative c'' @{
+ c4 a b c
+ @}
+ @}
+ @}
+ \layout @{ @}
@}
- \layout @{ @}
@}
@end example
In other words, if the input contains a single music expression,
LilyPond will interpret the file as though the music expression
-was wrapped up inside a @code{\score@{@}}.
+was wrapped up inside the commands shown above. For now, though,
+let us return to the first example and examine the @code{\score}
+command, leaving the others to default.
-A @code{\score} must begin with a compound music expression.
+A @code{\score} block must always contain just one music
+expression, and
+this must appear first within the @code{\score @{..@}} block.
Remember that a music expression could be anything from a single
-note to a huge
+note to a huge compound expression like
@example
@{
Some people put some of those commands outside the @code{\score}
block -- for example, @code{\header} is often placed above the
@code{\score}. That's just another shorthand that LilyPond
-accepts. Two more commands you have not previously seen are
+accepts.
+
+Two more commands you have not previously seen are
@code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
shown they will cause LilyPond to produce a printed output and a
MIDI out respectively. They are described fully in the
-Notation Reference - @ruser{Score layout} and
-@ruser{Creating MIDI files}.
+Notation Reference -- @ruser{Score layout} and
+@ruser{Creating MIDI files}.
+
+The @code{\book} command allows
+several @code{\score} blocks to be combined into one output.
+If there are several @code{\book} blocks each one produces a
+separate output file. For details see @ruser{Multiple scores
+in a book}.
@cindex variables
When LilyPond looks at this file, it takes the value of
@code{melody} (everything after the equals sign) and inserts it
whenever it sees @code{\melody}. There's nothing special about
-the names -- it could be @code{melody}, @code{global},
-@code{pianorighthand}, or @code{foofoobarbaz}. You can use
-whatever variable names you want as along as they contain just
-alphabetic characters. For more details, see
-@ruser{Saving typing with variables and functions}.
+the names -- it could be @code{melody}, @code{global},
+@code{TimeKey},
+@code{pianorighthand}, or @code{foofoobarbaz}. For more details,
+see @ruser{Saving typing with variables and functions}.
+Remember that you can use almost any name you like as long
+as it contains just alphabetic characters and is distinct from
+LilyPond command names. The exact
+limitations on variable names are detailed in
+@ruser{File structure}.
+
@seealso
@}
@end example
-@noindent
-Remember that you can use almost any name you like as long
-as it contains just alphabetic characters. The exact
-limitations on variable names are detailed in
-@ruser{File structure}.
-
Be careful about the difference between notes, which are introduced
with @code{\relative}, and lyrics, which are introduced with
@code{\lyricmode}. These are essential to tell LilyPond
@code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
encountered in exactly the opposite order to the opening
brackets. This @strong{is} a requirement for the three types of
-bracket described by the word @q{Encloses} in the table above -
+bracket described by the word @q{Encloses} in the table above --
they must nest properly.
However, the remaining brackets, described with the word
@q{Marks} in the table above together with ties and tuplets,
do @strong{not} have to nest
properly with any of the brackets. In fact, these are not
brackets in the sense that
-they enclose something - they are simply markers to indicate
+they enclose something -- they are simply markers to indicate
where something starts and ends.
So, for example, a phrasing slur can start before a manually
-inserted beam and end before the end of the beam - not very
+inserted beam and end before the end of the beam -- not very
musical, perhaps, but possible:
@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
Singers need voices to sing, and so does LilyPond.
The actual music for all instruments in a score
-is contained in Voices - the most fundamental
+is contained in Voices -- the most fundamental
of all LilyPond's concepts.
@menu
In fact, a Voice layer or context is the only one which can
contain music. If a Voice context is not explicitly declared
-one is created automatically. Some instruments such as an
+one is created automatically, as we saw at the beginning of
+this chapter. Some instruments such as an
Oboe can play only one note at a time. Music written for
such instruments is monophonic and requires just a single
voice. Instruments which can play more than one note at a
<< { a2. r4 } \\ { fis2. s4 } >>
@end lilypond
+It is not necessary to use a separate @code{<< \\ >>} construct
+for each bar, but it does help the legibility of the code. TODO
+
This example has just two voices, but the same contruct may be
used to encode three or more voices by adding more back-slash
separators.
c16 d e f
<< % Bar 1
{ g4 f e } \\
- { \voiceTwoStyle
- r8 e4 d c8 ~ }
+ {
+ \voiceTwoStyle
+ r8 e4 d c8 ~
+ }
>> |
<< % Bar 2
{ d2 e2 } \\
{ c8 b16 a b8 g ~ g2 } \\
- { \voiceThreeStyle
- s4 b4 c2 }
+ {
+ \voiceThreeStyle
+ s4 b4 c2
+ }
>>
}
@end lilypond
by telling LilyPond that this third voice is really a fourth
voice, with stems going down, using the @code{\voiceFour}
command. There are also corresponding @code{\voiceOne},
-@code{\voiceTwo}, and @code{voiceThree}
+@code{\voiceTwo}, and @code{\voiceThree}
commands. This results in the following:
@lilypond[quote,verbatim,fragment,ragged-right]
Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
@code{\voiceOne} ... @code{\voiceFour} to indicate the required
-directions of stems, slurs, etc.
+directions of stems, slurs, etc. In longer scores this method
+is clearer, as it permits the voices to be separated and to be
+given more descriptive names.
Specifically, the construct @code{<< \\ >>} which we used in
the previous section:
@example
-<< \upper \\ \lower >>
+\new Staff @{
+ \relative c' @{
+ << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
+ @}
+@}
@end example
@noindent
-where @code{upper} and @code{lower} are user-defined variables
-containing the music for the two voices, is equivalent to
+is equivalent to
@example
-<<
- \new Voice = "1" @{ \voiceOne \upper @}
- \new Voice = "2" @{ \voiceTwo \lower @}
+\new Staff <<
+ \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
+ \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
>>
@end example
+Both of the above would produce
+
+@c The following example should not display the code
+FIXME: weird compiling bug! Leave for gp.
+@c @lilypond{ragged-right,quote]
+@c \relative c' {
+@c % << { e4 f g a } \\ { c,4 d e f } >>
+@c }
+@c @end lilypond
+
The @code{\voiceXXX} commands set the direction of stems, slurs,
ties, articulations, text annotations, augmentation dots of dotted
notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
@lilypond[quote,ragged-right,verbatim]
\relative c'{
\voiceOne
- c-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c
+ c d8 ~ d e4 ( f g a ) b-> c
\oneVoice
- c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
+ c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
@lilypond[quote,ragged-right,verbatim]
\relative c'{
\voiceTwo
- c-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c
+ c d8 ~ d e4 ( f g a ) b-> c
\oneVoice
- c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
+ c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
parts are the same.
@lilypond[quote,verbatim]
-global = { \time 4/4 \partial 4 \key c \major}
+TimeKey = { \time 4/4 \partial 4 \key c \major}
SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
\new ChoirStaff <<
\new Staff <<
\clef "treble"
- \new Voice = "Sop" { \voiceOne \global \SopMusic }
+ \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
\new Voice = "Alto" { \voiceTwo \AltoMusic }
\new Lyrics \lyricsto "Sop" { \VerseOne }
\new Lyrics \lyricsto "Sop" { \VerseTwo }
@cindex Context, creating
@example
-\new @var{type} @var{music expression}
+\new @var{type} @var{music-expression}
@end example
@noindent
where @var{type} is a context name (like @code{Staff} or
@code{Voice}). This command creates a new context, and starts
-interpreting the @var{music expression} within that context.
+interpreting the @var{music-expression} within that context.
-Note that there is no @code{\new Score % Invalid!} command;
+Note that there is no @code{\new Score} command;
the single top-level @code{Score} context is introduced
-with @code{\score}. This is because there can be only one
-@code{Score} context, whereas there may be multiple
-@code{Staff} and @code{Voice} contexts - each created
-by @code{\new}.
+with @code{\score}.
The @code{\new} command may also give a identifying name to the
context to distinguish it from other contexts of the same type,
@example
-\new @var{type} = @var{id} @var{music}
+\new @var{type} = @var{id} @var{music-expression}
@end example
Note the distinction between the name of the context type,
Engravers live and operate in Contexts.
Engravers such as the @code{Metronome_mark_engraver}, whose
action and output applies to the score as a whole, operate in
-the highest level context - the @code{Score} context.
+the highest level context -- the @code{Score} context.
The @code{Clef_engraver} and @code{Key_engraver} are to be
found in every Staff Context, as different staves may require
@tab Engraves the five (by default) lines of the staff
@item Stem_engraver
@tab Creates stems and single-stem tremulos
+@item Time_signature_engraver
+ @tab Creates time signatures
@end multitable
@smallspace
@code{\set} command set the property @code{instrumentName} in the
Voice context to @qq{Alto}, but as LilyPond does not look
for any such property in the @code{Voice} context, no
-further action took place. this is not an error, and no error
+further action took place. This is not an error, and no error
message is logged in the log file.
Similarly, if the property name is mis-spelt no error message
name you like in any context that exists by using the
@code{\set} command. But if the name is not
known to LilyPond it will not cause any action to be taken.
+This is one of the reasons why it is highly recommended to
+use a context-sensitive editor with syntax highlighting for
+editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
+since unknown property names will be highlighted differently.
The @code{instrumentName} property will take effect only
if it is set in the @code{Staff} context, but
score shown above. We need to rearrange them so there are
four staves with the words written directly underneath the
notes for each part.
-All the voices should be @code{voiceOne}, which is
+All the voices should be @code{\voiceOne}, which is
the default, so the @code{\voiceXXX} commands can be removed.
We also need to specify the tenor clef for the tenors.
The way in which lyrics are specified has also been simplified