version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.11.51"
@node Fundamental concepts
@chapter Fundamental concepts
but more complex scores.
@menu
-* How LilyPond input files work::
-* Voices contain music::
-* Contexts and engravers::
-* Extending the templates::
+* How LilyPond input files work::
+* Voices contain music::
+* Contexts and engravers::
+* Extending the templates::
@end menu
description of the input format, see @ruser{File structure}.
@menu
-* Introduction to the LilyPond file structure::
-* Score is a (single) compound musical expression::
-* Nesting music expressions::
-* On the un-nestedness of brackets and ties::
+* Introduction to the LilyPond file structure::
+* Score is a (single) compound musical expression::
+* Nesting music expressions::
+* On the un-nestedness of brackets and ties::
@end menu
@node Introduction to the LilyPond file structure
@subsection Introduction to the LilyPond file structure
+@cindex input format
+@cindex file structure
+
A basic example of a LilyPond input file is
@example
\version @w{"@version{}"}
+\header @{ @}
\score @{
@var{...compound music expression...} % all the music goes here!
- \header @{ @}
\layout @{ @}
\midi @{ @}
@}
There are many variations of this basic pattern, but this
example serves as a useful starting place.
+@funindex \book
+@funindex \score
+@cindex book
+@cindex score
+
Up to this point none of the examples you have seen has used a
@code{\score@{@}} command. This is because LilyPond automatically
-adds the extra commands which are needed when you give it simple
+adds the extra commands which are needed when you give it simple
input. LilyPond treats input like this:
@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 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.
+was wrapped up inside the commands shown above.
+
+@cindex implicit contexts
+
+@strong{A word of warning!} Many of the examples in the LilyPond
+documentation will omit the @code{\new Staff} and @code{\new Voice}
+commands, leaving them to be created implicitly. For simple
+examples this works well, but for more complex examples, especially
+when additional commands are used, the implicit creation of contexts
+can give surprising results, maybe creating extra unwanted staves.
+The way to create contexts explicitly is explained in
+@ref{Contexts and engravers}.
+
+@warning{When entering more than a few lines of music it is
+advisable to always create staves and voices explicitly.}
+
+For now, though, let us return to the first example and examine the
+@code{\score} command, leaving the others to default.
-A @code{\score} block must always contain just one music
-expression, and
-this must appear immediately after the @code{\score} command.
+A @code{\score} block must always contain just one music expression,
+and this must appear immediately after the @code{\score} command.
Remember that a music expression could be anything from a single
note to a huge compound expression like
Since everything is inside @code{@{ ... @}}, it counts
as one music expression.
-As we saw previously, the @code{\score} block can contain other
+As we saw previously, the @code{\score} block can contain other
things, such as
@example
@}
@end example
+@funindex \header
+@funindex \layout
+@funindex \midi
+@cindex header
+@cindex layout
+@cindex midi
+
@noindent
-Some people put some of those commands outside the @code{\score}
-block -- for example, @code{\header} is often placed above the
-@code{\score} command. That's just another shorthand that LilyPond
-accepts.
+Note that these three commands -- @code{\header}, @code{\layout} and
+@code{\midi} -- are special: unlike many other commands which begin
+with a backward slash (@code{\}) they are @emph{not} music expressions
+and are not part of any music expression. So they may be placed
+inside a @code{\score} block or outside it. In fact, these commands
+are commonly placed outside the @code{\score} block -- for example,
+@code{\header} is often placed above the @code{\score} command, as the
+example at the beginning of this section shows.
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 output respectively. They are described fully in the
-Notation Reference -- @ruser{Score layout} and
+Notation Reference -- @ruser{Score layout}, and
@ruser{Creating MIDI files}.
+@cindex scores, multiple
+
You may code multiple @code{\score} blocks. Each will be
treated as a separate score, but they will be all combined into
a single output file. A @code{\book} command is not necessary
In summary:
Every @code{\book} block creates a separate output file (e.g., a
-pdf file). If you haven't explicitly added one, LilyPond wraps
+PDF file). If you haven't explicitly added one, LilyPond wraps
your entire input code in a @code{\book} block implicitly.
Every @code{\score} block is a separate chunk of music within a
(and thus in a @code{\book} block, either explicitly or
implicitly) will affect every @code{\score} in that @code{\book}.
-Every @code{\context} block will affect the named context (e.g.,
-@code{\StaffGroup}) throughout the block (@code{\score} or
-@code{\book}) in which it appears.
-
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},
+the names -- it could be @code{melody}, @code{global},
@code{TimeKey},
@code{pianorighthand}, or @code{foofoobarbaz}. For more details,
see @ref{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
+limitations on variable names are detailed in
@ruser{File structure}.
@node Score is a (single) compound musical expression
@subsection Score is a (single) compound musical expression
+@funindex \score
+@cindex score
@cindex Compound music expression
@cindex Music expression, compound
We saw the general organization of LilyPond input files in the
-previous section, @ref{How LilyPond input files work}. But we seemed to
-skip over the most important part: how do we figure out what to
-write after @code{\score}?
+previous section, @ref{Introduction to the LilyPond file structure}.
+But we seemed to skip over the most important part: how do we figure
+out what to write after @code{\score}?
We didn't skip over it at all. The big mystery is simply that
there @emph{is} no mystery. This line explains it all:
@end quotation
@noindent
-You may find it useful to review
+To understand what is meant by a music expression and a compound
+music expression, you may find it useful to review the tutorial,
@ref{Music expressions explained}. In that section, we saw how to
build big music expressions from small pieces -- we started from
notes, then chords, etc. Now we're going to start from a big
A whole Wagner opera would easily double the length of this
manual, so let's just add a singer and piano. We don't need a
@code{GrandStaff} for this ensemble, which simply groups a number
-of staves together with a brace at the left, so we shall remove
+of staves together with a brace at the left, so we shall remove
it. We @emph{do} need a singer and a piano, though.
@example
@}
@end example
-Remember that we use @code{<< ... >>} instead of
-@code{@{ ... @}} to show simultaneous
-music. And we definitely want to show the vocal part and piano
-part at the same time, not one after the other! However, the
-@code{<< ... >>} construct is not really necessary for the Singer
-staff, as it contains only one music expression, but Staves often
-do require simultaneous Voices within them, so using
-@code{<< ... >>}
-rather than braces is a good habit to adopt. We'll add some real
-music later; for now let's just put in some dummy notes and lyrics.
+Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
+show simultaneous music. And we definitely want to show the vocal
+part and piano part at the same time, not one after the other! Note
+that the @code{<< ... >>} construct is not really necessary for the
+Singer staff, as it contains only one sequential music expression;
+however, using @code{<< ... >>} instead of braces is still necessary
+if the music in the Staff is made of two simultaneous expressions,
+e.g. two simultaneous Voices, or a Voice with lyrics. We'll add some
+real music later; for now let's just put in some dummy notes and
+lyrics.
@lilypond[verbatim,quote,ragged-right]
\score {
But if we did that, the @code{\score} section would get pretty
long, and it would be harder to understand what was happening. So
let's use variables instead. These were introduced at the end
-of the previous section, remember? So, adding a few notes, we
+of the previous section, remember? So, adding a few notes, we
now have a piece of real music:
@lilypond[verbatim,quote,ragged-right]
Be careful about the difference between notes, which are introduced
-with @code{\relative}, and lyrics, which are introduced with
+with @code{\relative} or which are directly included in a music
+expression, and lyrics, which are introduced with
@code{\lyricmode}. These are essential to tell LilyPond
to interpret the following content as music and text
respectively.
When writing (or reading) a @code{\score} section, just take it
-slowly and carefully. Start with the outer layer, then work on
-each smaller layer. It also really helps to be strict with
-indentation -- make sure that each item on the same layer starts
+slowly and carefully. Start with the outer level, then work on
+each smaller level. It also really helps to be strict with
+indentation -- make sure that each item on the same level starts
on the same horizontal position in your text editor.
+@seealso
+
+Notation Reference: @ruser{Structure of a score}.
@node Nesting music expressions
@subsection Nesting music expressions
-It is not essential to declare all staves at the beginning;
-they may be introduced temporarily at any point. This is
-particularly useful for creating ossia sections
-(see @rglos{ossia}). Here is a simple example showing how
-to introduce a new staff temporarily for the duration of
-three notes:
+@cindex staves, temporary
+@cindex ossias
+
+It is not essential to declare all staves at the beginning; they may
+be introduced temporarily at any point. This is particularly useful
+for creating ossia sections -- see @rglos{ossia}. Here is a simple
+example showing how to introduce a new staff temporarily for the
+duration of three notes:
@lilypond[verbatim,quote,ragged-right]
\new Staff {
\relative g' {
r4 g8 g c4 c8 d |
- e4 r8
+ e4 r8
<<
{ f c c }
\new Staff {
at the beginning of the line. This is usual for clefs printed
in the middle of a line.
+@cindex staff, positioning
+
The ossia section may be placed above the staff
as follows:
@lilypond[verbatim,quote,ragged-right]
-\new Staff ="main" {
+\new Staff = "main" {
\relative g' {
r4 g8 g c4 c8 d |
e4 r8
}
@end lilypond
-This example uses @code{\with}, which will be explained more
+This example uses @code{\with}, which will be explained more
fully later. It is a means of modifying the default behavior
-of a single Staff. Here it says that the new staff should be
-placed above the staff called @qq{main} instead of the default
+of a single Staff. Here it says that the new staff should be
+placed above the staff called @qq{main} instead of the default
position which is below.
+@seealso
+
Ossia are often written without clef and without
time signature and are usually in a smaller font.
These require further commands which
-have not yet been introduced. See @ref{Size of objects}
+have not yet been introduced. See @ref{Size of objects},
+and @ruser{Ossia staves}.
+
@node On the un-nestedness of brackets and ties
@subsection On the un-nestedness of brackets and ties
+@cindex brackets, nesting
+
You have already met a number of different types of bracket in
writing the input file to LilyPond. These obey different rules
-which can be confusing at first. Before we explain the rules
+which can be confusing at first. Before we explain the rules
let's first review the different types of bracket.
@c attempt to force this onto a new page
@item @code{< .. >}
@tab Encloses the notes of a chord
@item @code{<< .. >>}
- @tab Encloses concurrent or simultaneous sections
+ @tab Encloses simultaneous music expressions
@item @code{( .. )}
@tab Marks the start and end of a slur
@item @code{\( .. \)}
- @tab Marks the start and end of a phrase mark
+ @tab Marks the start and end of a phrasing slur
@item @code{[ .. ]}
@tab Marks the start and end of a manual beam
@end multitable
@section Voices contain music
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
+The actual music for all instruments in a score
+is contained in Voices -- the most fundamental
of all LilyPond's concepts.
@menu
-* I'm hearing Voices::
-* Explicitly instantiating voices::
-* Voices and vocals::
+* I'm hearing Voices::
+* Explicitly instantiating voices::
+* Voices and vocals::
@end menu
@node I'm hearing Voices
@cindex polyphony
@cindex layers
+@cindex multiple voices
@cindex Voice context
+@cindex context, Voice
+@cindex simultaneous music
+@cindex concurrent music
-The lowest, most fundamental or innermost layers in a LilyPond
+The lowest, most fundamental or innermost layers in a LilyPond
score are called @q{Voice contexts} or just @q{Voices} for short.
-Voices are sometimes called @q{layers} in other notation
+Voices are sometimes called @q{layers} in other notation
packages.
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, as we saw at the beginning of
-this chapter. Some instruments such as an
+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
time like the piano will often require multiple voices to
encode the different concurrent notes and rhythms they are
-capable of playing.
+capable of playing.
A single voice can contain many notes in a chord, of course,
so when exactly are multiple voices needed? Look first at
<d g>4 <d fis> <d a'> <d g>
@end lilypond
-This can be expressed using just the single angle bracket chord
-symbols, @code{< ... >}, and for this just a single voice is
+This can be expressed using just the single angle bracket chord
+symbols, @code{< ... >}, and for this just a single voice is
needed. But suppose the F-sharp were actually an eighth-note
followed by an eighth-note G, a passing note on the way to the A?
Now we have two notes which start at the same time but have
different durations: the quarter-note D and the eighth-note
F-sharp. How are these to be coded? They cannot be written as
a chord because all the notes in a chord must have the same
-duration. And they cannot be written as two separate notes
+duration. And they cannot be written as two sequential notes
as they need to start at the same time. This is when two
voices are required.
notes would be entered into a single voice, which would usually
cause errors. This technique is particularly suited to pieces of
music which are largely monophonic with occasional short sections
-of polyphony.
+of polyphony.
Here's how we split the chords above into two voices and add both
the passing note and a slur:
}
@end lilypond
+@funindex \voiceOneStyle
+@funindex \voiceTwoStyle
+@funindex \voiceThreeStyle
+@funindex \voiceFourStyle
+@funindex \voiceNeutralStyle
+
The commands @code{\voiceXXXStyle} are mainly intended for use in
educational documents such as this one. They modify the color
of the note head, the stem and the beams, and the style of the
note head, so that the voices may be easily distinguished.
Voice one is set to red diamonds, voice two to blue triangles,
voice three to green crossed circles, and voice four (not used
-here) to magenta crosses. We shall see later how commands like
-these may be created by the user.
-See @ref{Visibility and color of objects}
-TODO Add link to using variables for tweaks
+here) to magenta crosses; @code{\voiceNeutralStyle} (also not
+used here) reverts the style back to the default.
+We shall see later how commands like these may be created by the
+user.
+See @ref{Visibility and color of objects} and
+@ref{Using variables for tweaks}.
Polyphony does not change the relationship of notes within a
@code{\relative @{ @}} block. Each note is still calculated
@code{noteB} is relative to @code{noteA} @*
@code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
@code{noteD} is relative to @code{noteB}, not @code{noteA} or
-@code{noteC}. @*
-@code{noteE} is relative to @code{noteD}, not @code{noteA}
+@code{noteC}; @*
+@code{noteE} is relative to @code{noteD}, not @code{noteA}.
An alternative way, which may be clearer if the notes in the
voices are widely separated, is to place a @code{\relative}
\relative c' @{ noteE ... @}
@end example
-Let us finally analyze the voices in a more complex piece of
+Let us finally analyze the voices in a more complex piece of
music. Here are
the notes from the first two bars of the second of Chopin's
Deux Nocturnes, Op 32. This example will be used at later
<<
{ % Voice one
\voiceOneStyle
- c2 aes4. bes8
+ c2 aes4. bes8
}
\\ % Voice two
{ \voiceTwoStyle
- aes2 f4 fes
+ aes2 f4 fes
}
\\ % No Voice three (we want stems down)
\\ % Voice four
\once \override NoteColumn #'force-hshift = #0
<ees c>2
\once \override NoteColumn #'force-hshift = #0.5
- des2
+ des2
}
>> |
<c ees aes c>1 |
@end lilypond
@noindent
-We see that this fixes the stem direction, but exposes a
-problem sometimes encountered with multiple voices -- the
-stems of the notes in one voice can collide with the note heads
-in other voices. In laying out the notes, LilyPond allows the
-notes or chords from two voices to occupy the same vertical
-note column provided the stems are in opposite directions, but
-the notes from the third and fourth voices are displaced to if
-necessary to avoid the note heads
-colliding. This usually works well, but in this example the
-notes of the lowest voice are clearly not well placed by default.
-LilyPond provides several ways to adjust the horizontal placing
-of notes. We are not quite ready yet to see how to correct this,
-so we shall leave this problem until a later section
-(see the force-hshift property in @ref{Fixing overlapping
-notation} )
+We see that this fixes the stem direction, but exposes a problem
+sometimes encountered with multiple voices -- the stems of the notes
+in one voice can collide with the note heads in other voices. In
+laying out the notes, LilyPond allows the notes or chords from two
+voices to occupy the same vertical note column provided the stems are
+in opposite directions, but the notes from the third and fourth voices
+are displaced, if necessary, to avoid the note heads colliding. This
+usually works well, but in this example the notes of the lowest voice
+are clearly not well placed by default. LilyPond provides several ways
+to adjust the horizontal placing of notes. We are not quite ready yet
+to see how to correct this, so we shall leave this problem until a
+later section --- see the @code{force-hshift} property in @ref{Fixing
+overlapping notation}.
+
+@seealso
+
+Notation Reference: @ruser{Multiple voices}.
+
@node Explicitly instantiating voices
@subsection Explicitly instantiating voices
@funindex \voiceTwo
@funindex \voiceThree
@funindex \voiceFour
+@funindex \oneVoice
+@funindex \new Voice
+@cindex Voice contexts, creating
Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
@end example
@noindent
-is equivalent to
+is equivalent to
@example
\new Staff <<
notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
make these objects point upwards, while @code{\voiceTwo} and
@code{\voiceFour} make them point downwards. These commands also
-generate a horizontal shift for each voice when this is required
-to avoid clashes of note heads. The command @code{\oneVoice}
+generate a horizontal shift for each voice when this is required
+to avoid clashes of note heads. The command @code{\oneVoice}
reverts the settings back to the normal values for a single voice.
-Let us see in some simple examples exactly what effect
+Let us see in some simple examples exactly what effect
@code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
markup, ties, slurs, and dynamics:
}
@end lilypond
+Now let's look at three different ways to notate the same passage
+of polyphonic music, each of which is advantageous in different
+circumstances, using the example from the previous section.
+
An expression that appears directly inside a @code{<< >>} belongs
to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
construct). This is useful when extra voices appear while the
-main voice is playing. Here is a more correct rendition of the
-example from the previous section. The red diamond-shaped notes
+main voice is playing. Here is a more correct rendition of our
+example. The red diamond-shaped notes
demonstrate that the main melody is now in a single voice context,
permitting a phrasing slur to be drawn over them.
@cindex nesting music expressions
@cindex nesting simultaneous constructs
+@cindex voices, temporary
+@cindex voices, nesting
+
More deeply nested polyphony constructs are possible, and if a
voice appears only briefly this might be a more natural way to
-typeset the music.
+typeset the music:
@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' {
}
@end lilypond
+@cindex spacing notes
This method of nesting new voices briefly is useful
when only small sections of the music
}
% Initiate second voice
\new Voice {
- % set stems, etc down
+ % Set stems, etc, down
\voiceTwo
s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
}
% Initiate third voice
\new Voice {
- % set stems, etc up
+ % Set stems, etc, up
\voiceThree
s1 | s4 b4 c2 |
}
>>
@end lilypond
+@subsubheading Note columns
+
@cindex note column
@cindex shift commands
@funindex \shiftOff
have no shift or the same shift specified, the error message
@qq{Too many clashing note columns} will be produced.
+@seealso
+
+Notation Reference: @ruser{Multiple voices}.
+
+
@node Voices and vocals
@subsection Voices and vocals
Vocal music presents a special difficulty: we need to combine two
expressions -- notes and lyrics.
+@funindex \new Lyrics
+@funindex \lyricsto
+@cindex Lyrics context, creating
+@cindex lyrics, linking to voice
+
You have already seen the @code{\addlyrics@{@}} command, which
handles simple scores well. However, this technique is
quite limited. For more complex music, you must introduce the
>>
@end lilypond
+Note that the lyrics must be linked to a @code{Voice} context,
+@emph{not} a @code{Staff} context. This is a case where it is
+necessary to create @code{Staff} and @code{Voice} contexts
+explicitly.
+
+@cindex lyrics and beaming
+@cindex beaming and lyrics
+@funindex \autoBeamOff
+
The automatic beaming which LilyPond uses by default works well
for instrumental music, but not so well for music with lyrics,
where beaming is either not required at all or is used to indicate
melismata in the lyrics. In the example above we use the command
@code{\autoBeamOff} to turn off the automatic beaming.
+@funindex \new ChoirStaff
+@funindex \lyricmode
+@cindex vocal score structure
+
Let us reuse the earlier example from Judas Maccabæus to
illustrate this more flexible technique. We first recast
it to use variables so the music and lyrics can be separated
and the variables containing the music can easily be placed
in separate files should they become too long.
-Here is a example of the first line of a hymn with four
+@cindex hymn structure
+
+Here is an example of the first line of a hymn with four
verses, set for SATB. In this case the words for all four
-parts are the same.
+parts are the same. Note how we use variables to separate the
+music notation and words from the staff structure. See too
+how a variable, which we have chosen to call @q{TimeKey}, is used
+to hold several commands for use within the two staves. In other
+examples this is often called @q{global}.
@lilypond[quote,verbatim]
TimeKey = { \time 4/4 \partial 4 \key c \major}
}
@end lilypond
+@cindex verse and refrain
+
We end with an example to show how we might code a solo verse which
continues into a two-part refrain in two staves. The
positioning of the sequential and simultaneous sections to achieve
\score {
\new ChoirStaff {
\new Staff <<
- \context Voice = "verse" {
+ \new Voice = "verse" {
\versenotes \break
<<
\refrainnotesA
However, although this is an interesting and useful exercise to
help you to understand how sequential and simultaneous blocks work,
-in practice one would perhaps choose to code this as two
+in practice one would perhaps choose to code this as two
@code{\score} blocks within an implicit @code{\book} block, as
follows:
}
@end lilypond
+@seealso
+
+Notation Reference: @ruser{Vocal music}.
+
+
@node Contexts and engravers
@section Contexts and engravers
@node Contexts explained
@subsection Contexts explained
-When music is printed, many notational elements which do not
+@cindex contexts explained
+
+When music is printed, many notational elements which do not
appear explicitly in the input file must be added to the
-output. For example, compare the input and output of the
+output. For example, compare the input and output of the
following example:
@lilypond[quote,verbatim,relative=2,fragment]
cis4 cis2. g4
@end lilypond
-The input is rather sparse, but in the output, bar lines,
-accidentals, clef, and time signature have been added. When
-LilyPond @emph{interprets} the input the musical information
-is inspected in time order, similar to reading a score from left
-to right. While reading the input, the program remembers where
-measure boundaries are, and which pitches require explicit
-accidentals. This information must be held on several levels.
+The input is rather sparse, but in the output, bar lines,
+accidentals, clef, and time signature have been added. When
+LilyPond @emph{interprets} the input the musical information
+is inspected in time order, similar to reading a score from left
+to right. While reading the input, the program remembers where
+measure boundaries are, and which pitches require explicit
+accidentals. This information must be held on several levels.
For example, the effect of an accidental is limited
-to a single staff, while a bar line must be synchronized across
+to a single staff, while a bar line must be synchronized across
the entire score.
Within LilyPond, these rules and bits of information are grouped
-in @emph{Contexts}. We have already met the
-@code{Voice} context.
-Others are the @code{Staff} and @code{Score} contexts.
-Contexts are hierarchical to reflect the hierarchical nature of
-a musical score.
-For example: a @code{Staff} context can contain many
-@code{Voice} contexts, and a @code{Score} context can
+in @emph{Contexts}. We have already met the
+@code{Voice} context.
+Others are the @code{Staff} and @code{Score} contexts.
+Contexts are hierarchical to reflect the hierarchical nature of
+a musical score.
+For example: a @code{Staff} context can contain many
+@code{Voice} contexts, and a @code{Score} context can
contain many @code{Staff} contexts.
@quotation
accidental and then the @code{Staff} context maintains the rule to
show or suppress the accidental for the remainder of the measure.
-As another example, the synchronization of bar lines is, by default,
+As another example, the synchronization of bar lines is, by default,
handled in the @code{Score} context.
However, in some music we may not want the bar lines to be
synchronized -- consider a polymetric score in 4/4 and 3/4 time.
-In such cases, we must modify the default settings of the
+In such cases, we must modify the default settings of the
@code{Score} and @code{Staff} contexts.
For very simple scores, contexts are created implicitly, and you need
with specialized notation, it is usual to modify existing, or
even to define totally new, contexts.
-In addition to the @code{Score,} @code{Staff} and
+In addition to the @code{Score,} @code{Staff} and
@code{Voice} contexts there are contexts which fit between
the score and staff levels to control staff groups, such as the
@code{PianoStaff} and @code{ChoirStaff} contexts. There
lyrics, percussion, fret boards, figured bass, etc.
The names of all context types are formed from one or more
-words, each word being capitalized and joined immediately to the
-preceding word with no hyphen or underscore, e.g.,
+words, each word being capitalized and joined immediately to the
+preceding word with no hyphen or underscore, e.g.,
@code{GregorianTranscriptionStaff}.
+@seealso
+
+Notation Reference: @ruser{Contexts explained}.
+
+
@node Creating contexts
@subsection Creating contexts
-There can be only one top level context: the
-@code{Score}
-context. This is created with the @code{\score} command,
+@funindex \new
+@cindex new contexts
+@cindex creating contexts
+@cindex contexts, creating
+
+There can be only one top level context: the
+@code{Score}
+context. This is created with the @code{\score} command,
or, in simple scores, it is created automatically.
-For scores with only one voice and one staff, the
-@code{Voice} and @code{Staff} contexts may be left to be
-created automatically, but for more complex scores it is
-necessary to create them by hand.
-The simplest command that does this is @code{\new}.
+For scores with only one voice and one staff, the
+@code{Voice} and @code{Staff} contexts may be left to be
+created automatically, but for more complex scores it is
+necessary to create them by hand.
+The simplest command that does this is @code{\new}.
It is prepended to a music expression, for example
-@funindex \new
-@cindex new contexts
-@cindex Context, creating
-
@example
\new @var{type} @var{music-expression}
@end example
interpreting the @var{music-expression} within that context.
Note that there is no @code{\new Score} command;
-the single top-level @code{Score} context is introduced
-with @code{\score}.
+the single top-level @code{Score} context is introduced
+with @code{\score}.
+
+You have seen many practical examples which created new
+@code{Staff} and @code{Voice} contexts in earlier sections, but
+to remind you how these commands are used in practice, here's an
+annotated real-music example:
-The @code{\new} command may also give a identifying name to the
+@lilypond[quote,verbatim,ragged-right]
+\score { % start of single compound music expression
+ << % start of simultaneous staves section
+ \time 2/4
+ \new Staff { % create RH staff
+ \key g \minor
+ \clef "treble"
+ \new Voice { % create voice for RH notes
+ \relative c'' { % start of RH notes
+ d4 ees16 c8. |
+ d4 ees16 c8. |
+ } % end of RH notes
+ } % end of RH voice
+ } % end of RH staff
+ \new Staff << % create LH staff; needs two simultaneous voices
+ \key g \minor
+ \clef "bass"
+ \new Voice { % create LH voice one
+ \voiceOne
+ \relative g { % start of LH voice one notes
+ g8 <bes d> ees, <g c> |
+ g8 <bes d> ees, <g c> |
+ } % end of LH voice one notes
+ } % end of LH voice one
+ \new Voice { % create LH voice two
+ \voiceTwo
+ \relative g { % start of LH voice two notes
+ g4 ees |
+ g4 ees |
+ } % end of LH voice two notes
+ } % end of LH voice two
+ >> % end of LH staff
+ >> % end of simultaneous staves section
+} % end of single compound music expression
+@end lilypond
+
+(Note how all the statements which open a block with either a
+curly bracket, @code{@{}, or double angle brackets, @code{<<},
+are indented by two further spaces, and the corresponding
+closing bracket is indented by exactly the same amount. While
+this is not required, following this practice will greatly
+reduce the number of @q{unmatched bracket} errors, and is
+strongly recommended. It enables the structure of the music to
+be seen at a glance, and any unmatched brackets will be obvious.
+Note too how the LH staff is created using double angle brackets
+because it requires two voices for its music, whereas the RH staff
+is created with a single music expression surrounded by curly
+brackets because it requires only one voice.)
+
+@cindex contexts, naming
+@cindex naming contexts
+
+The @code{\new} command may also give a identifying name to the
context to distinguish it from other contexts of the same type,
@example
@end example
Note the distinction between the name of the context type,
-@code{Staff}, @code{Voice}, etc, and
-the identifying name of a particular instance of that type,
-which can be any sequence of letters invented by the user.
-The identifying name is used to refer back to that particular
-instance of a context. We saw this in use in the section on
-lyrics in @ref{Voices and vocals}.
+@code{Staff}, @code{Voice}, etc, and the identifying name of a
+particular instance of that type, which can be any sequence of letters
+invented by the user. Digits and spaces can also be used in the
+identifying name, but then it has to be placed in quotes,
+i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
+The identifying name is used to
+refer back to that particular instance of a context. We saw this in
+use in the section on lyrics, see @ref{Voices and vocals}.
+
+@seealso
+
+Notation Reference: @ruser{Creating contexts}.
@node Engravers explained
is produced by an @code{Engraver}. Thus there is an engraver
to print staves, one to print note heads, one for stems, one for
beams, etc, etc. In total there are over 120 such engravers!
-Fortunately, for most scores it is not necessary to know about
-more than a few, and for simple scores you do not need to know
-about any.
+Fortunately, for most scores it is not necessary to know about
+more than a few, and for simple scores you do not need to know
+about any.
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
+action and output apply to the score as a whole, operate in
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
+found in every @code{Staff} Context, as different staves may require
different clefs and keys.
The @code{Note_heads_engraver} and @code{Stem_engraver} live
associated with contexts, may be modified to change the
operation of the engraver or the appearance of those elements
in the printed score.
-
+
Engravers all have compound names formed from words which
-describe their function. Just the first word is capitalized,
+describe their function. Just the first word is capitalized,
and the remainder are joined to it with underscores. Thus
the @code{Staff_symbol_engraver} is responsible for creating the
lines of the staff, the @code{Clef_engraver} determines and sets
the pitch reference point on the staff by drawing a clef symbol.
Here are some of the most common engravers together with their
-function. You will see it is easy to guess the function from
-the name, or vice versa.
+function. You will see it is usually easy to guess the function
+from the name, or vice versa.
-@multitable @columnfractions .3 .7
+@multitable @columnfractions .3 .7
@headitem Engraver
@tab Function
@item Accidental_engraver
@tab Engraves beams
@item Clef_engraver
@tab Engraves clefs
-@item Dynamic_engraver
+@item Completion_heads_engraver
+ @tab Splits notes which cross bar lines
+@c The old Dynamic_engraver is deprecated. -jm
+@item New_dynamic_engraver
@tab Creates hairpins and dynamic texts
+@item Forbid_line_break_engraver
+ @tab Prevents line breaks if a musical element is still active
@item Key_engraver
@tab Creates the key signature
@item Metronome_mark_engraver
We shall see later how the output of LilyPond can be changed
by modifying the action of Engravers.
-
+
+@seealso
+
+Internals reference: @rinternals{Engravers and Performers}.
+
@node Modifying context properties
@subsection Modifying context properties
@cindex context properties
+@cindex context properties, modifying
+@cindex modifying context properties
@funindex \set
@funindex \unset
Contexts are responsible for holding the values of a number of
context @emph{properties}. Many of them can be changed to
influence the interpretation of the input and so change the
-appearance of the output. They are changed by the
+appearance of the output. They are changed by the
@code{\set} command. This takes the form
@example
an Integer is a positive whole number, a Real is a positive
or negative decimal number, and text is enclosed in double
apostrophes. Note the occurrence of hash signs,
-(@code{#}), in two different places -- as part of the Boolean
+(@code{#}), in two different places -- as part of the Boolean
value before the @code{t} or @code{f}, and before @emph{value}
-in the @code{\set} statement. So when a Boolean is being
-entered you need to code two hash signs, e.g., @code{##t}.
+in the @code{\set} statement. So when a Boolean is being
+entered you need to code two hash signs, e.g., @code{##t}.
Before we can set any of these properties we need to know
in which context they operate. Sometimes this is obvious,
but occasionally it can be tricky. If the wrong context
is specified, no error message is produced, but the expected
action will not take place. For example, the
-@code{instrumentName} clearly lives in the Staff context, since
+@code{instrumentName} clearly lives in the @code{Staff} context, since
it is the staff that is to be named.
In this example the first staff is labelled, but not the second,
because we omitted the context name.
}
\new Staff \relative c' {
\set instrumentName = #"Alto" % Wrong!
- d4 d
+ d4 d
}
>>
@end lilypond
-Remember the default context name is Voice, so the second
+Remember the default context name is @code{Voice}, so the second
@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
+@code{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
message is logged in the log file.
-Similarly, if the property name is mis-spelt no error message
-is produced, and clearly the expected action cannot be performed.
-If fact, you can set any (fictitious) @q{property} using any
-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 input files, such as Vim, Jedit, ConTEXT or Emacs,
-since unknown property names will be highlighted differently.
+Similarly, if the property name is mis-spelt no error message is
+produced, and clearly the expected action cannot be performed. In
+fact, you can set any (fictitious) @q{property} using any 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. Some text editors with special support for LilyPond input
+files document property names with bullets when you hover them with
+the mouse, like JEdit with LilyPondTool, or highlight unknown property
+names differently, like ConTEXT. If you do not use an editor with
+such features, it is recommended to check the property name in the
+Internals Reference: see @rinternals{Tunable context properties}, or
+@rinternals{Contexts}.
The @code{instrumentName} property will take effect only
if it is set in the @code{Staff} context, but
>>
@end lilypond
-The value of every property set in this way can be reset
-to its original value with the @code{\unset} command.
-
+As another example, if @code{clefOctavation} is set in
+the @code{Score} context this immediately changes the value
+of the octavation in all current staves and sets a new default
+value which will be applied to all staves.
+
+The opposite command, @code{\unset}, effectively removes the
+property from the context, which causes most properties to
+revert to their default value. Usually @code{\unset} is not
+required as a new @code{\set} command will achieve what is
+wanted.
+
The @code{\set} and @code{\unset} commands can appear anywhere
in the input file and will take effect from the time they are
-encountered until the end of the score or until the property is
-@code{\set} or @code{\unset} again. Let's try changing the
-font size, which affects the size of the note heads (among
+encountered until the end of the score or until the property is
+@code{\set} or @code{\unset} again. Let's try changing the
+font size, which affects the size of the note heads (among
other things) several times. The change is from the default
-value, not the current value.
+value, not the most recently set value.
@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
-c4
+c4
% make note heads smaller
\set fontSize = #-4
d e
% make note heads larger
\set fontSize = #2.5
f g
-% return to original size
+% return to default size
\unset fontSize
a b
@end lilypond
-We have now seen how to set the values of several different
-types of property. Note that integers and numbers are alway
-preceded by a hash sign, @code{#}, while a true or false value
-is specified by ##t and ##f, with two hash signs. A text
-property should be enclosed in double quotation signs, as above,
-although we shall see later that text can actually be specified
-in a much more general way by using the very powerful
-@code{markup} command.
+We have now seen how to set the values of several different types of
+property. Note that integers and numbers are always preceded by a
+hash sign, @code{#}, while a true or false value is specified by
+@code{##t} and @code{##f}, with two hash signs. A text property
+should be enclosed in double quotation signs, as above, although we
+shall see later that text can actually be specified in a much more
+general way by using the very powerful @code{markup} command.
+@unnumberedsubsubsec Setting context properties with @code{\with}
@funindex \with
+@cindex context properties, setting with \with
Context properties may also be set at the time the context is
-created. Sometimes this is a clearer way of specifying a
+created. Sometimes this is a clearer way of specifying a
property value if it is to remain fixed for the duration of
the context. When a context is created with a @code{\new}
-command it may be followed immediately by a
+command it may be followed immediately by a
@code{\with @{ .. @}} block in which the property values are
set. For example, if we wish to suppress the printing of
extra naturals for the duration of a staff we would write:
>>
@end lilypond
-In effect this overrides the default value of the property. It
-may still be changed dynamically using @code{\set} and returned
-to its (new) default value with @code{\unset}.
+Properties set in this way may still be changed dynamically using
+@code{\set} and returned to their default value with @code{\unset}.
+
+The @code{fontSize} property is treated differently. If this is
+set in a @code{\with} clause it effectively resets the default
+value of the font size. If it is later changed with @code{\set},
+this new default value may be restored with the
+@code{\unset fontSize} command.
+
+@unnumberedsubsubsec Setting context properties with @code{\context}
+
+The values of context properties may be set in @emph{all} contexts
+of a particular type, such as all @code{Staff} contexts, with a single
+command. The context type is identified by using its
+type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
+The statement which sets the property value is the same as that in a
+@code{\with} block, introduced above. It is placed in a
+@code{\context} block within a @code{\layout} block. Each
+@code{\context} block will affect all contexts of the type specified
+throughout the @code{\score} or @code{\book} block in which the
+@code{\layout} block appears. Here is a example to show the format:
+
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ \relative c'' {
+ cis4 e d ces
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ extraNatural = ##t
+ }
+ }
+}
+@end lilypond
+
+@noindent
+Context properties set in this way may be overridden for particular
+instances of contexts by statements in a @code{\with} block, and by
+@code{\set} commands embedded in music statements.
+
+@seealso
+
+Notation Reference:
+@ruser{Changing context default settings}.
+@c FIXME
+@c uncomment when backslash-node-name issue is resolved -pm
+@c @ruser{The set command}.
+
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{Tunable context properties}.
+
@node Adding and removing engravers
@subsection Adding and removing engravers
-@cindex Engravers, adding
-@cindex Engravers, removing
+@cindex engravers, adding
+@cindex engravers, removing
@funindex \consists
@funindex \remove
We have seen that contexts each contain several engravers, each
of which is responsible for producing a particular part of the
output, like bar lines, staves, note heads, stems, etc. If an
-engraver is removed from a context it can no longer produce its
+engraver is removed from a context, it can no longer produce its
output. This is a crude way of modifying the output, but it
can sometimes be useful.
@subsubheading Changing a single context
To remove an engraver from a single context we use the
-@code{\with} command placed immediately after the context creation
+@code{\with} command placed immediately after the context creation
command, as in the previous section.
-As an
-illustration let's repeat an example from the previous
-section with the staff lines removed. Remember that the
-staff lines are produced by the Staff_symbol_engraver.
+As an illustration, let's repeat an example from the previous section
+with the staff lines removed. Remember that the staff lines are
+produced by the @code{Staff_symbol_engraver}.
@lilypond[quote,verbatim,ragged-right]
\new Staff \with {
\remove Staff_symbol_engraver
}
\relative c' {
- c4
+ c4
\set fontSize = #-4 % make note heads smaller
d e
\set fontSize = #2.5 % make note heads larger
f g
- \unset fontSize % return to original size
+ \unset fontSize % return to default size
a b
}
@end lilypond
@cindex ambitus engraver
-Engravers can also be added to individual contexts.
+Engravers can also be added to individual contexts.
The command to do this is
-@code{\consists @emph{Engraver_name}},
+@code{\consists @var{Engraver_name}},
-placed inside a @code{\with} block. Some vocal scores
-have an @rglos{ambitus} placed at the beginning of a
-staff to indicate the range of notes in that staff.
-The ambitus is produced by the @code{Ambitus_engraver},
-which is not normally included in any context. If
-we add it to the @code{Voice} context it calculates
-the range from that voice only:
+@noindent
+placed inside a @code{\with} block. Some vocal scores have an ambitus
+placed at the beginning of a staff to indicate the range of notes in
+that staff -- see @rglos{ambitus}. The ambitus is produced by the
+@code{Ambitus_engraver}, which is not normally included in any
+context. If we add it to the @code{Voice} context, it calculates the
+range from that voice only:
@lilypond[quote,verbatim,ragged-right]
\new Staff <<
\new Voice \with {
\consists Ambitus_engraver
}
- \relative c'' {
+ \relative c'' {
\voiceOne
- c a b g
+ c a b g
}
\new Voice
\relative c' {
@end lilypond
@noindent
-but if we add the Ambitus engraver to the
-@code{Staff} context it calculates the range from all
+but if we add the ambitus engraver to the
+@code{Staff} context, it calculates the range from all
the notes in all the voices on that staff:
@lilypond[quote,verbatim,ragged-right]
}
<<
\new Voice
- \relative c'' {
+ \relative c'' {
\voiceOne
- c a b g
+ c a b g
}
\new Voice
\relative c' {
@subsubheading Changing all contexts of the same type
+@funindex \layout
+
The examples above show how to remove or add engravers to
-individual contexts. It is also possible to remove or add
+individual contexts. It is also possible to remove or add
engravers to every context of a specific type by placing the
commands in the appropriate context in a @code{\layout}
block. For example, if we wanted to show an ambitus for every
-staff in a four-staff score we could write
+staff in a four-staff score, we could write
@lilypond[quote,verbatim,ragged-right]
\score {
@end lilypond
@noindent
-The default values of context properties may also be set
+The values of context properties may also be set
for all contexts of a particular type by including the
@code{\set} command in a @code{\context} block in the
same way.
+@seealso
+
+Notation Reference: @ruser{Modifying context plug-ins},
+@ruser{Changing context default settings}.
+
+
@node Extending the templates
@section Extending the templates
-You've read the tutorial, you know how to write music, you
+You've read the tutorial, you know how to write music, you
understand the fundamental concepts. But how can you
-get the staves that you want? Well, you can find lots of
-templates (see @ref{Templates}) which may give you a start.
-But what
-if you want something that isn't covered there? Read on.
-
-TODO Add links to templates after they have been moved to LSR
+get the staves that you want? Well, you can find lots of
+templates (see @ref{Templates}) which may give you a start.
+But what if you want something that isn't covered there? Read on.
@menu
-* Soprano and cello::
-* Four-part SATB vocal score::
-* Building a score from scratch::
+* Soprano and cello::
+* Four-part SATB vocal score::
+* Building a score from scratch::
@end menu
@node Soprano and cello
@subsection Soprano and cello
+@cindex template, modifying
+
Start off with the template that seems closest to what you want to end
up with. Let's say that you want to write something for soprano and
cello. In this case, we would start with @q{Notes and lyrics} (for the
@}
@end example
-We don't need two @code{\version} commands. We'll need the
+We don't need two @code{\version} commands. We'll need the
@code{melody} section. We don't want two @code{\score} sections
-- if we had two @code{\score}s, we'd get the two parts separately.
-We want them together, as a duet. Within the @code{\score}
+We want them together, as a duet. Within the @code{\score}
section, we don't need two @code{\layout} or @code{\midi}.
-If we simply cut and paste the @code{melody} section, we would
+If we simply cut and paste the @code{melody} section, we would
end up with two @code{melody} definitions. This would not generate
an error, but the second one would be used for both melodies.
-So let's rename them to make them distinct. We'll call the
+So let's rename them to make them distinct. We'll call the
section for the soprano @code{sopranoMusic} and the section for
the cello @code{celloMusic}. While we're doing this, let's rename
@code{text} to be @code{sopranoLyrics}. Remember to rename both
@code{melody = \relative c' @{ } part) and the name's use (in the
@code{\score} section).
-While we're doing this, let's change the cello part's staff --
-celli normally use bass clef. We'll also give the cello some
+While we're doing this, let's change the cello part's staff --
+celli normally use bass clef. We'll also give the cello some
different notes.
@example
@noindent
underneath the soprano stuff. We also need to add @code{<<} and
@code{>>} around the music -- that tells LilyPond that there's
-more than one thing (in this case, two @code{Staves}) happening
-at once. The @code{\score} looks like this now
+more than one thing (in this case, two @code{Staves}) happening
+at once. The @code{\score} looks like this now:
@c Indentation in this example is deliberately poor
@example
}
@end lilypond
+@seealso
+
+The starting templates can be found in the @q{Templates} appendix,
+see @ref{Single staff}.
+
@node Four-part SATB vocal score
@subsection Four-part SATB vocal score
+@cindex template, SATB
+@cindex SATB template
+
Most vocal scores of music written for four-part mixed choir
with orchestral accompaniment such as Mendelssohn's Elijah or
Handel's Messiah have the choral music and words on four
@c The following should appear as music without code
@lilypond[quote,ragged-right]
global = { \key d \major \time 4/4 }
-sopMusic = \relative c'' {
+sopranoMusic = \relative c'' {
\clef "treble"
r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
}
-sopWords = \lyricmode {
+sopranoWords = \lyricmode {
Wor -- thy is the lamb that was slain
}
altoMusic = \relative a' {
\clef "treble"
r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
}
-altoWords = \sopWords
+altoWords = \sopranoWords
tenorMusic = \relative c' {
\clef "G_8"
r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
}
-tenorWords = \sopWords
+tenorWords = \sopranoWords
bassMusic = \relative c' {
\clef "bass"
r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
}
-bassWords = \sopWords
+bassWords = \sopranoWords
upper = \relative a' {
\clef "treble"
\global
\new ChoirStaff <<
\new Staff = "sopranos" <<
\set Staff.instrumentName = "Soprano"
- \new Voice = "sopranos" { \global \sopMusic }
+ \new Voice = "sopranos" { \global \sopranoMusic }
>>
- \new Lyrics \lyricsto "sopranos" { \sopWords }
+ \new Lyrics \lyricsto "sopranos" { \sopranoWords }
\new Staff = "altos" <<
\set Staff.instrumentName = "Alto"
\new Voice = "altos" { \global \altoMusic }
>> % end ChoirStaff
\new PianoStaff <<
- \set PianoStaff.instrumentName = "Piano "
+ \set PianoStaff.instrumentName = "Piano"
\new Staff = "upper" \upper
\new Staff = "lower" \lower
>>
}
@end lilypond
-None of the templates provides this layout exactly. The
-nearest is @q{SATB vocal score and automatic piano reduction},
-but we need to change the layout and add a piano
-accompaniment which is not derived automatically from the
-vocal parts. The variables holding the music and words for
-the vocal parts are fine, but we shall need to add variables for
-the piano reduction.
+None of the templates provides this layout exactly. The nearest is
+@q{SATB vocal score and automatic piano reduction} -- see @ref{Vocal
+ensembles} -- but we need to change the layout and add a piano
+accompaniment which is not derived automatically from the vocal parts.
+The variables holding the music and words for the vocal parts are
+fine, but we shall need to add variables for the piano reduction.
The order in which the contexts appear in the ChoirStaff of
-the template do not correspond with the order in the vocal
+the template do not correspond with the order in the vocal
score shown above. We need to rearrange them so there are
four staves with the words written directly underneath the
notes for each part.
the default, so the @code{\voiceXXX} commands should be removed.
We also need to specify the tenor clef for the tenors.
The way in which lyrics are specified in the template has not yet
-been encountered so we need to use the method with which we are
+been encountered so we need to use the method with which we are
familiar. We should also add the names of each staff.
Doing this gives for our ChoirStaff:
\new ChoirStaff <<
\new Staff = "sopranos" <<
\set Staff.instrumentName = "Soprano"
- \new Voice = "sopranos" @{ \global \sopMusic @}
+ \new Voice = "sopranos" @{ \global \sopranoMusic @}
>>
- \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
+ \new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
\new Staff = "altos" <<
\set Staff.instrumentName = "Alto"
\new Voice = "altos" @{ \global \altoMusic @}
stacked one above the other:
@example
-<< % combine ChoirStaff and PianoStaff one above the other
+<< % combine ChoirStaff and PianoStaff one above the other
\new ChoirStaff <<
\new Staff = "sopranos" <<
- \new Voice = "sopranos" @{ \global \sopMusic @}
+ \new Voice = "sopranos" @{ \global \sopranoMusic @}
>>
- \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
+ \new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
\new Staff = "altos" <<
\new Voice = "altos" @{ \global \altoMusic @}
>>
>> % end ChoirStaff
\new PianoStaff <<
- \set PianoStaff.instrumentName = "Piano "
+ \set PianoStaff.instrumentName = "Piano"
\new Staff = "upper" \upper
\new Staff = "lower" \lower
>>
@lilypond[quote,verbatim,ragged-right,addversion]
global = { \key d \major \time 4/4 }
-sopMusic = \relative c'' {
+sopranoMusic = \relative c'' {
\clef "treble"
r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
}
-sopWords = \lyricmode {
+sopranoWords = \lyricmode {
Wor -- thy is the lamb that was slain
}
altoMusic = \relative a' {
\clef "treble"
r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
}
-altoWords = \sopWords
+altoWords = \sopranoWords
tenorMusic = \relative c' {
\clef "G_8"
r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
}
-tenorWords = \sopWords
+tenorWords = \sopranoWords
bassMusic = \relative c' {
\clef "bass"
r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
}
-bassWords = \sopWords
+bassWords = \sopranoWords
upper = \relative a' {
\clef "treble"
\global
\new ChoirStaff <<
\new Staff = "sopranos" <<
\set Staff.instrumentName = "Soprano"
- \new Voice = "sopranos" { \global \sopMusic }
+ \new Voice = "sopranos" { \global \sopranoMusic }
>>
- \new Lyrics \lyricsto "sopranos" { \sopWords }
+ \new Lyrics \lyricsto "sopranos" { \sopranoWords }
\new Staff = "altos" <<
\set Staff.instrumentName = "Alto"
\new Voice = "altos" { \global \altoMusic }
>>
}
@end lilypond
-
+
@node Building a score from scratch
@subsection Building a score from scratch
-After gaining some facility with writing LilyPond code you
+@cindex template, writing your own
+
+After gaining some facility with writing LilyPond code, you
may find that it is easier to build a score from scratch
rather than modifying one of the templates. You can also
develop your own style this way to suit the sort of music you
-like. Let's see how to put together the score for an organ
+like. Let's see how to put together the score for an organ
prelude as an example.
We begin with a header section. Here go the title, name
We simply mirror the staff structure we want.
Organ music is usually written on three staves,
one for each manual and one for the pedals. The
-manual staves should be bracketed together so we
+manual staves should be bracketed together, so we
need to use a PianoStaff for them. The first
manual part needs two voices and the second manual
part just one.
Next we need to add a staff for the pedal organ.
This goes underneath the PianoStaff, but it must
be simultaneous with it, so we need angle brackets
-round the two. Missing these out would generate
-an error in the log file. It's a common mistake
+around the two. Missing these out would generate
+an error in the log file. It's a common mistake
which you'll make sooner or later! Try copying
the final example at the end of this section,
remove these angle brackets, and compile it to
>>
@end example
-It is not strictly necessary to use the simultaneous construct
-@code{<< >>} for the manual two staff and the pedal organ staff,
-since they contain only one music expression, but it does no harm
+It is not necessary to use the simultaneous construct
+@code{<< .. >>} for the manual two staff and the pedal organ staff,
+since they contain only one music expression, but it does no harm,
and always using angle brackets after @code{\new Staff} is a good
-habit to cultivate in case there are multiple voices.
+habit to cultivate in case there are multiple voices. The opposite
+is true for Voices: these should habitually be followed by braces
+@code{@{ .. @}} in case your music is coded in several variables
+which need to run consecutively.
-Let's add this structure to the score block, and adjust the
-indenting. We also add the appropriate clefs, ensure the
-second voice stems point down with @code{\voiceTwo} and
-enter the time signature and key to each staff using our
-predefined variable, @code{\TimeKey}.
+Let's add this structure to the score block, and adjust the indenting.
+We also add the appropriate clefs, ensure stems, ties and slurs in
+each voice on the upper staff point to the right direction with
+@code{\voiceOne} and @code{\voiceTwo}, and enter the time signature
+and key to each staff using our predefined variable, @code{\TimeKey}.
@example
\score @{
\new Staff = "ManualOne" <<
\TimeKey % set time signature and key
\clef "treble"
- \new Voice @{ \ManualOneVoiceOneMusic @}
+ \new Voice @{ \voiceOne \ManualOneVoiceOneMusic @}
\new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
>> % end ManualOne Staff context
\new Staff = "ManualTwo" <<
That completes the structure. Any three-staff organ music
will have a similar structure, although the number of voices
-may vary. All that remains now
+may vary. All that remains now
is to add the music, and combine all the parts together.
@lilypond[quote,verbatim,ragged-right,addversion]
g4 g f ees | d2 c2 |
}
ManualOneVoiceTwoMusic = \relative c' {
- ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
+ ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
c c4 b8 c8. g16 c b c d |
}
ManualTwoMusic = \relative c' {
\new Staff = "ManualOne" <<
\TimeKey % set time signature and key
\clef "treble"
- \new Voice { \ManualOneVoiceOneMusic }
+ \new Voice { \voiceOne \ManualOneVoiceOneMusic }
\new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
>> % end ManualOne Staff context
\new Staff = "ManualTwo" <<
\TimeKey
\clef "bass"
\new Voice { \PedalOrganMusic }
- >> % end PedalOrgan Staff
+ >> % end PedalOrgan Staff context
>>
} % end Score context
@end lilypond
-
-
-
-
-
projects / lilypond.git / blobdiff