Issue 5114/4: Document \voices

[lilypond.git] / Documentation / learning / fundamental.itely

@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.22"

@node Fundamental concepts
@chapter Fundamental concepts

You've seen in the Tutorial how to produce beautifully printed
music from a simple text file.  This section introduces the
concepts and techniques required to produce equally beautiful
but more complex scores.

@menu
* How LilyPond input files work::
* Voices contain music::
* Contexts and engravers::
* Extending the templates::
@end menu


@node How LilyPond input files work
@section How LilyPond input files work

The LilyPond input format is quite free-form, giving experienced
users a lot of flexibility to structure their files however they
wish.  But this flexibility can make things confusing for new
users.  This section will explain some of this structure, but may
gloss over some details in favor of simplicity.  For a complete
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::
@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{ @dots{} compound music expression @dots{} }  % all the music goes here!
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
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 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''4 a d c
@}
@end example

@noindent
as shorthand for this:

@example
\book @{
  \score @{
    \new Staff @{
      \new Voice @{
        \relative @{
          c''4 a b c
        @}
      @}
    @}
    \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 the commands shown above.

@cindex implicit contexts
@cindex contexts, implicit

@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 exactly one music
expression.  Remember that a music expression could be anything
from a single note to a huge compound expression like

@example
@{
  \new StaffGroup <<
    @var{ @dots{} insert the whole score of a Wagner opera in here @dots{} }
  >>
@}
@end example

@noindent
Since everything is inside @code{@{ @dots{} @}}, it counts
as one music expression.

As we saw previously, the @code{\score} block can contain other
things, such as

@example
\score @{
  @{ c'4 a b c' @}
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

@funindex \header
@funindex \layout
@funindex \midi
@cindex header
@cindex layout
@cindex midi

@noindent
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
@ruser{Creating MIDI output}.

@cindex scores, multiple
@cindex book block, implicit
@cindex implicit book block
@funindex \book

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
-- one will be implicitly created.  However, if you would like
separate output files from one @file{.ly} file then the
@code{\book} command should be used to separate the different
sections: each @code{\book} block will produce a
separate output file.

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
your entire input code in a @code{\book} block implicitly.

Every @code{\score} block is a separate chunk of music within a
@code{\book} block.

@cindex layout block, effect of location

Every @code{\layout} block affects the @code{\score} or
@code{\book} block in which it appears -- i.e., a @code{\layout}
block inside a @code{\score} block affects only that @code{\score}
block, but a @code{\layout} block outside of a @code{\score} block
(and thus in a @code{\book} block, either explicitly or
implicitly) will affect every @code{\score} in that @code{\book}.

For details see @ruser{Multiple scores in a book}.

@cindex variables

Another great shorthand is the ability to define variables, as
shown in @ref{Organizing pieces with variables}.  All the
templates use this:

@example
melody = \relative @{
  c'4 a b c
@}

\score @{
  \melody
@}
@end example

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 name -- it could be @code{melody}, @code{global},
@code{keyTime}, @code{pianorighthand}, or something else.
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.  For more details, see @ref{Saving typing with
variables and functions}.  The exact limitations on variable names
are detailed in @ruser{File structure}.


@seealso
For a complete definition of the input format, see
@ruser{File structure}.


@node Score is a (single) compound musical expression
@subsection Score is a (single) compound musical expression

@funindex \score
@cindex score
@cindex contents of a score block
@cindex score block, contents of
@cindex compound music expression
@cindex music expression, compound

We saw the general organization of LilyPond input files in the
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:

@quotation
@emph{A @code{\score} block must contain exactly one music expression.}
@end quotation

@noindent
To understand what is meant by a
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
music expression and work our way down.  For simplicity, we'll use
just a singer and piano in our example.  We don't need a
@code{StaffGroup} for this ensemble, which simply groups a number
of staves together with a bracket at the left, but we do need
staves for a singer and a piano, though.

@example
\score @{
  <<
    \new Staff = "singer" <<
    >>
    \new PianoStaff = "piano" <<
    >>
  >>
  \layout @{ @}
@}
@end example

Here we have given names to the staves -- @qq{singer} and
@qq{piano}.  This is not essential here, but it is a useful habit
to cultivate so that you can see at a glance what each stave is
for.

Remember that we use @code{<< @dots{} >>} instead of @code{@{ @dots{} @}} to
show simultaneous music.  This causes the vocal part and piano part
to appear one above the other in the score.  The @code{<< @dots{} >>}
construct would not be necessary for the Singer staff in the example
above if it were going to contain only one sequential music
expression, but @code{<< @dots{} >>} rather than braces is necessary if
the music in the Staff is to contain two or more simultaneous
expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
We're going to have a voice with lyrics, so angle brackets are
required.  We'll add some real music later; for now let's just put
in some dummy notes and lyrics.  If you've forgotten how to add lyrics
you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.

@lilypond[verbatim,quote,ragged-right]
\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { c'1 }
      \addlyrics { And }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { c'1 }
      \new Staff = "lower" { c'1 }
    >>
  >>
  \layout { }
}
@end lilypond

Now we have a lot more details.  We have the singer's staff: it
contains a @code{Voice} (in LilyPond, this term refers to a set of
notes, not necessarily vocal notes -- for example, a violin
generally plays one voice) and some lyrics.  We also have a piano
staff: it contains an upper staff (right hand) and a lower staff
(left hand), although the lower staff has yet to be given a bass
clef.

At this stage, we could start filling in notes.  Inside the curly
braces next to @code{\new Voice = "vocal"}, we could start writing

@example
\relative @{
  r4 d''8\noBeam g, c4 r
@}
@end example

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?  To ensure the contents of the
@code{text} variable are interpreted as lyrics we preface them with
@code{\lyricmode}.  Like @code{\addlyrics}, this switches the input
mode to lyrics.  Without that, LilyPond would try to interpret the
contents as notes, which would generate errors.  (Several other
input modes are available, see @ruser{Input modes}.)

So, adding a few notes and a bass clef for the left hand, we now
have a piece of real music:

@lilypond[verbatim,quote,ragged-right]
melody = \relative { r4 d''8\noBeam g, c4 r }
text   = \lyricmode { And God said, }
upper  = \relative { <g' d g,>2~ <g d g,> }
lower  = \relative { b,2 e }

\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { \melody }
      \addlyrics { \text }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { \upper }
      \new Staff = "lower" {
        \clef "bass"
        \lower
      }
    >>
  >>
  \layout { }
}
@end lilypond

When writing (or reading) a @code{\score} section, just take it
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

@cindex staves, temporary
@cindex temporary staves
@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 {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff {
        f8 f c
      }
    >>
    r4 |
  }
}
@end lilypond

@noindent
Note that the size of the clef is the same as a clef printed
following a clef change -- slightly smaller than the clef
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" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = #"main"
      } { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

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
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},
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
@cindex bracket types
@cindex brackets, enclosing vs. marking

You have already met a number of different types of bracket and
bracket-like constructs in writing the input file to LilyPond.
These obey different rules which can be confusing at first.
Let's first review the different types of brackets and bracket-like
constructs.

@c attempt to force this onto a new page
@need 50
@multitable @columnfractions .3 .7
@headitem Bracket Type
  @tab Function
@item @code{@{ @dots{} @}}
  @tab Encloses a sequential segment of music
@item @code{< @dots{} >}
  @tab Encloses the notes of a chord
@item @code{<< @dots{} >>}
  @tab Encloses simultaneous music expressions
@item @code{( @dots{} )}
  @tab Marks the start and end of a slur
@item @code{\( @dots{} \)}
  @tab Marks the start and end of a phrasing slur
@item @code{[ @dots{} ]}
  @tab Marks the start and end of a manual beam
@end multitable

To these we should add other constructs which generate lines
between or across notes: ties (marked by a tilde, @code{~}),
tuplets written as @code{\tuplet x/y @{ @dots{} @}}, and grace notes
written as @code{\grace @{ @dots{} @}}.

Outside LilyPond, the conventional use of brackets requires the
different types to be properly nested, like this, @code{<< [ @{ ( @dots{} )
@} ] >>}, 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 -- they must nest properly.  However,
the remaining bracket-like constructs, 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 or
bracket-like constructs.  In fact, these are not brackets in
the sense that 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
musical, perhaps, but possible:

@lilypond[quote,verbatim,ragged-right]
\relative { g'8\( a b[ c b\) a] g4 }
@end lilypond

In general, different kinds of brackets, bracket-like constructs,
and those implied by tuplets, ties and grace notes, may be mixed
freely.  This example shows a beam extending into a tuplet (line 1),
a slur extending into a tuplet (line 2), a beam and a slur
extending into a tuplet, a tie crossing two tuplets, and a
phrasing slur extending out of a tuplet (lines 3 and 4).

@lilypond[quote,verbatim,ragged-right]
\relative {
  r16[ g' \tuplet 3/2 { r16 e'8] }
  g,16( a \tuplet 3/2 { b16 d) e }
  g,8[( a \tuplet 3/2 { b8 d) e~] } |
  \tuplet 5/4 { e32\( a, b d e } a4.\)
}
@end lilypond


@node Voices contain music
@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
of all LilyPond's concepts.

@menu
* I'm hearing Voices::
* Explicitly instantiating voices::
* Voices and vocals::
@end menu

@node I'm hearing Voices
@subsection I'm hearing Voices

@cindex polyphony
@cindex layers
@cindex multiple voices
@cindex voices, multiple
@cindex Voice context
@cindex context, Voice
@cindex simultaneous music
@cindex music, simultaneous
@cindex concurrent music
@cindex music, concurrent
@cindex voices vs. chords
@cindex chords vs. voices

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
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 Oboe can play only one note at a time.  Music
written for such instruments 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.

A single voice can contain many notes in a chord, of course,
so when exactly are multiple voices needed?  Look first at
this example of four chords:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  <d' g>4 <d fis> <d a'> <d g>
}
@end lilypond

This can be expressed using just the single angle bracket chord
symbols, @code{< @dots{} >}, 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 sequential notes
as they need to start at the same time.  This is when two
voices are required.

Let us see how this is done in LilyPond input syntax.

@funindex << \\ >>
@funindex \\

The easiest way to enter fragments with more than one voice on a
staff is to enter each voice as a sequence (with @code{@{ @dots{} @}}),
and combine them simultaneously with angle brackets, @code{<< @dots{} >>}.
The fragments must also be separated with double backward slashes,
@code{\\}, to place them in separate voices.  Without these, the
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 homophonic with occasional short sections
of polyphony.

Here's how we split the chords above into two voices and add both
the passing note and a slur:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  %    Voice = "1"             Voice = "2"
  << { g'4 fis8( g) a4 g } \\ { d4 d d d }  >>
}
@end lilypond

Notice how the stems of the second voice now point down.

Here's another simple example:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key d \minor
  %    Voice = "1"           Voice = "2"
  << { r4 g' g4. a8 }   \\ { d,2 d4 g }       >> |
  << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
  << { a2. r4 }         \\ { fis2. s4 }       >> |
}
@end lilypond

It is not necessary to use a separate @code{<< \\ >>} construct
for each bar.  For music with few notes in each bar this layout
can help the legibility of the code, but if there are many
notes in each bar it may be better to split out each voice
separately, like this:

@lilypond[quote,verbatim,ragged-right]
<<
  \key d \minor
  \relative { % Voice = "1"
    r4 g' g4. a8 |
    bes4 bes c bes |
    a2. r4 |
  } \\
  \relative { % Voice = "2"
    d'2 d4 g |
    g4 g g8( a) g4 |
    fis2. s4 |
  }
>>
@end lilypond


@cindex voices, naming
@cindex voices crossing brackets
@cindex slurs crossing brackets
@cindex ties crossing brackets

This example has just two voices, but the same construct may be
used to encode three or more voices by adding more back-slash
separators.

The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
The first contexts set the @emph{outer} voices, the highest
voice in context @code{"1"} and the lowest voice in context
@code{"2"}.  The inner voices go in contexts @code{"3"} and
@code{"4"}.  In each of these contexts, the vertical direction
of slurs, stems, ties, dynamics etc., is set appropriately.

@lilypond[quote,verbatim]
\new Staff \relative {
  % Main voice
  c'16 d e f
  %  Voice = "1"   Voice = "2"             Voice = "3"
  << { g4 f e } \\ { r8 e4 d c8~ } >> |
  << { d2 e }   \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
}
@end lilypond

@funindex \voices
If you prefer entering the voices in a different order, like top
to bottom, you can specify the respective voice numbers in front
of one @code{<< @dots{} >>} construct using the @code{\voices}
command, like

@lilypond[quote,verbatim]
\new Staff \relative {
  % Main voice
  c'16 d e f
  %  Voice = "1"   Voice = "2"
  << { g4 f e } \\ { r8 e4 d c8~ } >> |
  \voices 1,3,2
  %  Voice = "1"   Voice = "3"    Voice = "2"
  << { d2 e }   \\ { s4 b c2 } \\ { c8 b16 a b8 g~ 2 } >> |
}
@end lilypond

These voices are all separate from the main voice that contains
the notes just outside the @code{<< @dots{} >>} construct.  Let's call
this the @emph{simultaneous construct}.  Slurs and ties may only
connect notes within the same voice, so slurs and ties cannot go
into or out of a simultaneous construct.  Conversely,
parallel voices from separate simultaneous constructs on the same
staff are the same voice.  Other voice-related properties also
carry across simultaneous constructs.  Here is the same example,
with different colors and note heads for each voice.  Note that
changes in one voice do not affect other voices, but they do
persist in the same voice later.  Note also that tied notes may be
split across the same voices in two constructs, shown here in the
blue triangle voice.

@lilypond[quote,verbatim]
\new Staff \relative {
  % Main voice
  c'16 d e f
  <<  % Bar 1
    {
      \voiceOneStyle
      g4 f e
    }
  \\
    {
      \voiceTwoStyle
      r8 e4 d c8~
    }
  >> |
  <<  % Bar 2
     % Voice 1 continues
    { d2 e }
  \\
     % Voice 2 continues
    { c8 b16 a b8 g~ 2 }
  \\
    {
      \voiceThreeStyle
      s4 b c2
    }
  >> |
}
@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;  @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 layout adjustments}.

@cindex polyphony and relative note entry
@cindex relative note entry and polyphony

Polyphony does not change the relationship of notes within a
@code{\relative} block.  Each note is still calculated relative to
the note immediately preceding it, or to the first note of the
preceding chord.  So in

@example
\relative @{ noteA << < noteB noteC > \\ noteD >> noteE @}
@end example

@noindent
@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}.

An alternative way, which may be clearer if the notes in the
voices are widely separated, is to place a @code{\relative}
command at the start of each voice:

@example
\relative @{ noteA @dots{} @}
<<
  \relative @{ < noteB noteC > @dots{} @}
\\
  \relative @{ noteD @dots{} @}
>>
\relative @{ noteE @dots{} @}
@end example

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 stages in
this and the next chapter to illustrate several techniques for
producing notation, so please ignore for now anything in the
underlying code which looks mysterious and concentrate just on the
music and the voices -- the complications will all be explained in
later sections.

@c The following should appear as music without code
@lilypond[quote,ragged-right]
\new Staff \relative {
  \key aes \major
  \voices 1,2,4    % No voice three
  <<  % Voice one
    { c''2 aes4. bes8 }
  \\  % Voice two
    {
      % Ignore these for now - they are explained in Ch 4
      \once \override NoteColumn.force-hshift = #0
      <ees, c>2
      \once \override NoteColumn.force-hshift = #0.5
      des2
    }
  \\  % Voice four
    {
      \override NoteColumn.force-hshift = #0
      aes'2 f4 fes
    }
  >> |
  <c ees aes c>1 |
}
@end lilypond

The direction of the stems is often used to indicate the continuity of
two simultaneous melodic lines.  Here the stems of the highest notes
are all pointing up and the stems of the lower notes are all pointing
down.  This is the first indication that more than one voice is
required.

But the real need for multiple voices arises when notes
which start at the same time have different durations.
Look at the notes which start at beat three in the first
bar.  The A-flat is a dotted quarter note, the F is a
quarter note and the D-flat is a half note.  These
cannot be written as a chord as all the notes in a chord
must have the same duration.  Neither can they be written
as sequential notes, as they must start at the same time.
This section of the bar requires three voices, and the
normal practice would be to write the whole bar as three
voices, as shown below, where we have used different note heads
and colors for the three voices.  Again, the code behind this
example will be explained later, so ignore anything you do
not understand.

@c The following should appear as music without code
@c The three voice styles should be defined in -init
@lilypond[quote,ragged-right]
\new Staff \relative {
  \key aes \major
  \voices 1,2,4  % No Voice three (we want stems down)
  <<
    {  % Voice one
      \voiceOneStyle
      c''2 aes4. bes8
    }
  \\  % Voice two
    { \voiceTwoStyle
      % Ignore these for now - they are explained in Ch 4
      \once \override NoteColumn.force-hshift = #0
      <ees, c>2
      \once \override NoteColumn.force-hshift = #0.5
      des2
    }
  \\  % Voice four
    { \voiceThreeStyle
      \override NoteColumn.force-hshift = #0
      aes'2 f4 fes
    }
  >> |
  <c ees aes c>1 |
}
@end lilypond


Let us try to encode this music from scratch.  As we
shall see, this encounters some difficulties.  We begin as
we have learnt, using the @code{<< \\  >>} construct to
enter the music of the first bar in three voices:

@lilypond[quote,verbatim,ragged-right]
\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@cindex stem down
@cindex voices and stem directions
@cindex stem directions and voices
@cindex stem up

The stem directions are automatically assigned with the
odd-numbered voices taking upward stems and the even-numbered
voices downward ones.  The stems for voices 1 and 2 are right,
but the stems in voice 3 should go down in this particular piece
of music.  We can correct this by skipping voice three
and placing the music in voice four.  This could be done by simply
adding another pair of @code{\\}, but we use the @code{\voices}
command instead (which would also allow us to enter the voices in
different order if we preferred doing that):

@lilypond[quote,verbatim,ragged-right]
\new Staff \relative {
  \key aes \major
  \voices 1,2,4   % Omit Voice three
  <<  % Voice one
    { c''2 aes4. bes8 }
  \\  % Voice two
    { <ees, c>2 des }
  \\  % Voice four
    { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@noindent
We see that this fixes the stem direction, but the horizontal
placement of notes is not what we want.  LilyPond shifts the
inner notes when they or their stems would collide with outer
voices, but this is not appropriate for piano music.  In other
situations, the shifts LilyPond applies might fail to clear
the collisions.  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}.

@warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
created @q{across} voices.}


@seealso
Notation Reference: @ruser{Multiple voices}.


@node Explicitly instantiating voices
@subsection Explicitly instantiating voices

@funindex \voiceOne
@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
@code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
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
\new Staff @{
  \relative @{
    << @{ e'4 f g a @} \\ @{ c,4 d e f @} >>
  @}
@}
@end example

@noindent
is equivalent to

@example
\new Staff <<
  \new Voice = "1" @{ \voiceOne \relative @{ e'4 f g a @} @}
  \new Voice = "2" @{ \voiceTwo \relative @{ c'4 d e f @} @}
>>
@end example

Both of the above would produce

@c The following example should not display the code
@lilypond[ragged-right,quote]
\new Staff <<
  \new Voice = "1" { \voiceOne \relative { e'4 f g a } }
  \new Voice = "2" { \voiceTwo \relative { c'4 d e f } }
>>
@end lilypond

@cindex voices, reverting to single
@cindex reverting to a single voice

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}
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}
reverts the settings back to the normal values for a single voice.

Let us see in some simple examples exactly what effect
@code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
markup, ties, slurs, and dynamics:

@lilypond[quote,ragged-right,verbatim]
\relative {
  % Default behavior or behavior after \oneVoice
  c'4 d8~ 8 e4( f | g4 a) b-> c |
}
@end lilypond

@lilypond[quote,ragged-right,verbatim]
\relative {
  \voiceOne
  c'4 d8~ 8 e4( f | g4 a) b-> c |
  \oneVoice
  c,4 d8~ 8 e4( f | g4 a) b-> c |
}
@end lilypond

@lilypond[quote,ragged-right,verbatim]
\relative {
  \voiceTwo
  c'4 d8~ 8 e4( f | g4 a) b-> c |
  \oneVoice
  c,4 d8~ 8 e4( f | g4 a) b-> c |
}
@end lilypond

Now let's look at four 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 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.

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative {
  \voiceOneStyle
  % This section is homophonic
  c'16^( d e f
  % Start simultaneous section of three voices
  <<
    % Continue the main voice in parallel
    { g4 f e | d2 e) | }
    % Initiate second voice
    \new Voice {
      % Set stems, etc., down
      \voiceTwo
      r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
    }
    % Initiate third voice
    \new Voice {
      % Set stems, etc, up
      \voiceThree
      s2. | s4 b c2 |
    }
  >>
}
@end lilypond

@cindex voices, continued
@funindex \voices

The @code{\voices} command can also be used for continuing a main
voice into the simultaneous construct:

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative {
  \new Voice = "main" {
    \voiceOneStyle
    % This section is homophonic
    c'16^( d e f
    % Start simultaneous section of three voices
    \voices "main",2,3
    <<
      % Continue the main voice in parallel
      { g4 f e | d2 e) | }
      % Initiate second voice
    \\
      % Set stems, etc., down
      { r8 e4 d c8~ | 8 b16 a b8 g~ 2 | }
    \\
      % Initiate third voice
      % Set stems, etc, up
      { s2. | s4 b c2 | }
    >>
  }
}
@end lilypond


@cindex nesting music expressions
@cindex nesting simultaneous constructs
@cindex nesting voices
@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:

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative {
  c'16^( d e f
  <<
    { g4 f e | d2 e) | }
    \new Voice {
      \voiceTwo
      r8 e4 d c8~ |
      <<
        { c8 b16 a b8 g~ 2 | }
        \new Voice {
          \voiceThree
          s4 b c2 |
        }
      >>
    }
  >>
}
@end lilypond

@cindex spacing notes

This method of nesting new voices briefly is useful
when only small sections of the music
are polyphonic, but when the whole staff is largely polyphonic
it can be clearer to use multiple voices throughout, using
spacing notes to step over sections where the voice is silent,
as here:

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative <<
  % Initiate first voice
  \new Voice {
    \voiceOne
    c'16^( d e f g4 f e | d2 e) |
  }
  % Initiate second voice
  \new Voice {
    % Set stems, etc, down
    \voiceTwo
    s4 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
  }
  % Initiate third voice
  \new Voice {
    % Set stems, etc, up
    \voiceThree
    s1 | s4 b c2 |
  }
>>
@end lilypond

@subsubheading Note columns

@cindex note column
@cindex note collisions
@cindex collisions, notes
@cindex shift commands
@funindex \shiftOff
@funindex \shiftOn
@funindex \shiftOnn
@funindex \shiftOnnn

Closely spaced notes in a chord, or notes occurring at the same
time in different voices, are arranged in two, occasionally more,
columns to prevent the note heads overlapping.  These are called
note columns.  There are separate columns for each voice, and
the currently specified voice-dependent shift is applied to the
note column if there would otherwise be a collision.  This can
be seen in the example above.  In bar 2 the C in voice two is
shifted to the right relative to the D in voice one, and in the
final chord the C in voice three is also shifted to the right
relative to the other notes.

The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
@code{\shiftOff} commands specify the degree to which notes and
chords of the voice should be shifted if a collision
would otherwise occur.  By default, the outer voices (normally
voices one and two) have @code{\shiftOff} specified, while the
inner voices (three and four) have @code{\shiftOn} specified.
When a shift is applied, voices one and three are shifted to
the right and voices two and four to the left.

@code{\shiftOnn} and @code{\shiftOnnn} define further shift
levels which may be specified temporarily to resolve collisions
in complex situations -- see @ref{Real music example}.

A note column can contain just one note (or chord) from a voice
with stems up and one note (or chord) from a voice with stems
down.  If notes from two voices which have their stems in the
same direction are placed at the same position and both voices
have no shift or the same shift specified, the error message
@qq{This voice needs a @code{@bs{}voiceXx} or @code{@bs{}shiftXx} setting}
will be produced.


@seealso
Learning Manual:
@ref{Moving objects}.

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
@funindex Lyrics
@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
lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
explicitly link
the lyrics to the notes with @code{\lyricsto@{@}}, using the
name assigned to the Voice.

@lilypond[quote,verbatim]
<<
  \new Voice = "one" {
    \relative {
      \autoBeamOff
      \time 2/4
      c''4 b8. a16 | g4. f8 | e4 d | c2 |
    }
  }
  \new Lyrics \lyricsto "one" {
    No more let | sins and | sor -- rows | grow. |
  }
>>
@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 ChoirStaff
@funindex \lyricmode
@cindex vocal score structure
@cindex choir staff

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
from the staff structure.  We also introduce a ChoirStaff
bracket.  The lyrics themselves must be introduced with
@code{\lyricmode} to ensure they are interpreted as lyrics
rather than music.

@lilypond[quote,verbatim]
global = { \key f \major \time 6/8 \partial 8 }

SopOneMusic = \relative {
  c''8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ 4
}
SopOneLyrics = \lyricmode {
  Let | flee -- cy flocks the | hills a -- dorn, __
}
SopTwoMusic = \relative {
  r8 | r4. r4 c'8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
}
SopTwoLyrics = \lyricmode {
  Let | flee -- cy flocks the | hills a -- dorn,
}

\score {
  \new ChoirStaff <<
    \new Staff <<
      \new Voice = "SopOne" {
        \global
        \SopOneMusic
      }
      \new Lyrics \lyricsto "SopOne" {
        \SopOneLyrics
      }
    >>
    \new Staff <<
      \new Voice = "SopTwo" {
        \global
        \SopTwoMusic
      }
      \new Lyrics \lyricsto "SopTwo" {
        \SopTwoLyrics
      }
    >>
  >>
}
@end lilypond

This is the basic structure of all vocal scores.  More staves may be
added as required, more voices may be added to the staves, more verses
may be added to the lyrics, and the variables containing the music can
easily be placed in separate files should they become too long.

@cindex hymn structure
@cindex SATB structure
@cindex vocal scores with multiple verses
@cindex multiple vocal verses
@cindex verses, multiple vocal

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.  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{keyTime}, is used
to hold several commands for use within the two staves.  In other
examples this is often called @q{global}.

@lilypond[quote,verbatim]
keyTime = { \key c \major \time 4/4 \partial 4 }

SopMusic   = \relative { c'4 | e4. e8 g4  g    | a4   a   g  }
AltoMusic  = \relative { c'4 | c4. c8 e4  e    | f4   f   e  }
TenorMusic = \relative {  e4 | g4. g8 c4.   b8 | a8 b c d e4 }
BassMusic  = \relative {  c4 | c4. c8 c4  c    | f8 g a b c4 }

VerseOne =
  \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
VerseTwo   =
  \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
VerseThree =
  \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
VerseFour  =
  \lyricmode { O | Tri -- ni -- ty of | love and pow'r }

\score {
  \new ChoirStaff <<
    \new Staff <<
      \clef "treble"
      \new Voice = "Sop"  { \voiceOne \keyTime \SopMusic }
      \new Voice = "Alto" { \voiceTwo \AltoMusic }
      \new Lyrics \lyricsto "Sop" { \VerseOne   }
      \new Lyrics \lyricsto "Sop" { \VerseTwo   }
      \new Lyrics \lyricsto "Sop" { \VerseThree }
      \new Lyrics \lyricsto "Sop" { \VerseFour  }
    >>
    \new Staff <<
      \clef "bass"
      \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
      \new Voice = "Bass"  { \voiceTwo \BassMusic }
    >>
  >>
}
@end lilypond


@seealso
Notation Reference: @ruser{Vocal music}.


@node Contexts and engravers
@section Contexts and engravers

Contexts and engravers have been mentioned informally
in earlier sections; we now must look at
these concepts in more detail, as they are important
in the fine-tuning of LilyPond output.


@menu
* Contexts explained::
* Creating contexts::
* Engravers explained::
* Modifying context properties::
* Adding and removing engravers::
@end menu

@node Contexts explained
@subsection Contexts explained

@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
following example:

@lilypond[quote,verbatim]
\relative { cis''4 cis2. | a4 a2. | }
@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 parsed from left to right, similar to the way a performer
reads the score.  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, an accidental affects only 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 introduced 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
@sourceimage{context-example,5cm,,}
@end quotation

Each context has the responsibility for enforcing some notation rules,
creating some notation objects and maintaining the associated
properties.  For example, the @code{Voice} context may introduce an
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,
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
@code{Score} and @code{Staff} contexts.

For very simple scores, contexts are created implicitly, and you need
not be aware of them.  For larger pieces, such as anything with more
than one staff, they must be
created explicitly to make sure that you get as many staves as you
need, and that they are in the correct order.  For typesetting pieces
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
@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
are also alternative staff and voice contexts, and contexts for
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.,
@code{GregorianTranscriptionStaff}.


@seealso
Notation Reference: @ruser{Contexts explained}.


@node Creating contexts
@subsection Creating contexts

@funindex \new
@cindex new contexts
@cindex creating contexts
@cindex contexts, creating

In an input file, a score block (introduced with a @code{\score}
command) contains a single music expression; but it can also contain
associated output definitions too -- either a @code{\layout} block, a
@code{\midi} block or both.  The @code{Score} context is usually left to
be created automatically when the interpretation of that music
expression starts.

For scores with only one voice and one staff, the @code{Voice} and
@code{Staff} contexts may also 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

@example
\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.

@warning{@bs{}@code{new Score} should not be used as the essential
top-level @code{Score} context is created automatically when the music
expression within the @bs{}@code{score} block is interpreted.  Score-wide
default values of context properties can be changed within the
@bs{}@code{layout} block.  See @ref{Modifying context properties}}

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:

@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
      \clef "treble"
      \key g \minor
      \new Voice {  % create voice for RH notes
        \relative {  % start of RH notes
          d''4 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
      \clef "bass"
      \key g \minor
      \new Voice {  % create LH voice one
        \voiceOne
        \relative {  % 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 {  % 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 an identifying name to the
context to distinguish it from other contexts of the same type,

@example
\new @var{type} = @var{id} @var{music-expression}
@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.  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 and referencing contexts}.


@node Engravers explained
@subsection Engravers explained

@cindex engravers

Every mark on the printed output of a score produced by LilyPond
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.

Engravers live and operate in Contexts.  Engravers such as the
@code{Metronome_mark_engraver}, whose 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 @code{Staff} Context, as different staves may require
different clefs and keys.

The @code{Note_heads_engraver} and @code{Stem_engraver} live
in every @code{Voice} context, the lowest level context of all.

Each engraver processes the particular objects associated
with its function, and maintains the properties that relate
to that function.  These properties, like the properties
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,
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 usually easy to guess the function
from the name, or vice versa.

@multitable @columnfractions .3 .7
@headitem Engraver
  @tab Function
@item Accidental_engraver
  @tab Makes accidentals, cautionary and suggested accidentals
@item Beam_engraver
  @tab Engraves beams
@item Clef_engraver
  @tab Engraves clefs
@item Completion_heads_engraver
  @tab Splits notes which cross bar lines
@item 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
  @tab Engraves metronome marking
@item Note_heads_engraver
  @tab Engraves note heads
@item Rest_engraver
  @tab Engraves rests
@item Staff_symbol_engraver
  @tab Engraves the five (by default) lines of the staff
@item Stem_engraver
  @tab Creates stems and single-stem tremolos
@item Time_signature_engraver
  @tab Creates time signatures
@end multitable

@smallspace

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
@code{\set} command.  This takes the form

@example
\set @emph{ContextName}.@emph{propertyName} = #@emph{value}
@end example

Where the @emph{ContextName} is usually @code{Score},
@code{Staff} or @code{Voice}.  It may be omitted,
in which case the current context (typically @code{Voice}) is assumed.

The names of context properties consist of words joined
together with no hyphens or underscores, all except the
first having a capital letter.  Here are a few examples
of some commonly used ones.  There are many more.

@c attempt to force this onto a new page
@need 50
@multitable @columnfractions .25 .15 .45 .15
@headitem propertyName
  @tab Type
  @tab Function
  @tab Example Value
@item extraNatural
  @tab Boolean
  @tab If true, set extra natural signs before accidentals
  @tab @code{#t}, @code{#f}
@item currentBarNumber
  @tab Integer
  @tab Set the current bar number
  @tab @code{50}
@item doubleSlurs
  @tab Boolean
  @tab If true, print slurs both above and below notes
  @tab @code{#t}, @code{#f}
@item instrumentName
  @tab Text
  @tab Set the name to be placed at the start of the staff
  @tab @code{"Cello I"}
@item fontSize
  @tab Real
  @tab Increase or decrease the font size
  @tab @code{2.4}
@item stanza
  @tab Text
  @tab Set the text to print before the start of a verse
  @tab @code{"2"}
@end multitable

@noindent
where a Boolean is either True (@code{#t}) or False (@code{#f}),
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
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}.

@cindex properties operating in contexts
@cindex setting properties within contexts

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{clefGlyph} clearly lives in the @code{Staff} context, since
it is the staff's clef glyph that is to be changed.
In this example the first staff's clef is printed correctly, but not the
second -- which prints the default treble clef instead of the
expected bass (or F) clef -- because we omitted the context name.

@lilypond[quote,verbatim,ragged-right]
<<
  \new Staff \relative {
    \set Staff.clefGlyph = "clefs.C"
    c''2 c
  }
  \new Staff \relative {
    \set clefGlyph = "clefs.F"  % Wrong!
    d'2 d
  }
>>
@end lilypond

Remember the default context name is @code{Voice}, so the second
@code{\set} command set the property @code{clefGlyph} in the
@code{Voice} context to @code{clefs.F}, 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.  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{clefGlyph} property will take effect only
if it is set in the @code{Staff} context, but
some properties can be set in more than one context.
For example, the property @code{extraNatural} is by
default set to ##t (true) for all staves.
If it is set to ##f (false) in one particular @code{Staff}
context it applies just to the accidentals on that staff.
If it is set to false in the @code{Score} context
it applies to all staves.

So this turns off extra naturals in one staff:

@lilypond[quote,verbatim,ragged-right]
<<
  \new Staff \relative {
    aeses'2 aes
  }
  \new Staff \relative {
    \set Staff.extraNatural = ##f
    aeses'2 aes
  }
>>
@end lilypond

@noindent
and this turns them off in all staves:

@lilypond[quote,verbatim,ragged-right]
<<
  \new Staff \relative {
    aeses'2 aes
  }
  \new Staff \relative {
    \set Score.extraNatural = ##f
    aeses'2 aes
  }
>>
@end lilypond

As another example, if @code{clefTransposition} is set in
the @code{Score} context this immediately changes the value
of the transposition 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
other things) several times.  The change is from the default
value, not the most recently set value.

@lilypond[quote,verbatim,ragged-right]
\relative {
  c'4 d
  % make note heads smaller
  \set fontSize = #-4
  e4 f |
  % make note heads larger
  \set fontSize = #2.5
  g4 a
  % return to default size
  \unset fontSize
  b4 c |
}
@end lilypond

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.

@subsubheading Setting context properties with @code{\with}

@funindex \with
@cindex context properties, setting with \with

The default value of context properties may be set at the time the
context is created.  Sometimes this is a clearer way of setting 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 @code{\with @{ @dots{} @}}
block in which the default 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:

@example
\new Staff \with @{ extraNatural = ##f @}
@end example

@noindent
like this:

@lilypond[quote,verbatim,ragged-right]
<<
  \new Staff {
    \relative {
      gisis'4 gis aeses aes
    }
  }
  \new Staff \with { extraNatural = ##f } {
    \relative {
      gisis'4 gis aeses aes
    }
  }
>>
@end lilypond

Properties set in this way may still be changed dynamically using
@code{\set} and returned to the default value set in the
@code{\with} block with @code{\unset}.

@cindex fontSize, default and setting

So if the @code{fontSize} property is set in a @code{\with} clause
it sets 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.

@subsubheading Setting context properties with @code{\context}

@cindex context properties, setting with \context
@funindex \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 an example to show the format:

@lilypond[verbatim,quote]
\score {
  \new Staff {
    \relative {
      cisis''4 e d cis
    }
  }
  \layout {
    \context {
      \Staff
      extraNatural = ##t
    }
  }
}
@end lilypond

If the property override is to be applied to all staves
within the score:

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \relative {
        gisis'4 gis aeses aes
      }
    }
    \new Staff {
      \relative {
        gisis'4 gis aeses aes
      }
    }
  >>
  \layout {
    \context {
      \Score extraNatural = ##f
    }
  }
}
@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}.
@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 adding engravers
@cindex engravers, removing
@cindex removing engravers

@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
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
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 @code{Staff_symbol_engraver}.

@lilypond[quote,verbatim,ragged-right]
\new Staff \with {
  \remove "Staff_symbol_engraver"
}
\relative {
  c'4 d
  \set fontSize = #-4  % make note heads smaller
  e4 f |
  \set fontSize = #2.5  % make note heads larger
  g4 a
  \unset fontSize  % return to default size
  b4 c |
}
@end lilypond

@cindex ambitus engraver

Engravers can also be added to individual contexts.
The command to do this is

@code{\consists @var{Engraver_name}},

@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 {
      \voiceOne
      c''4 a b g
    }
  }
  \new Voice {
    \relative {
      \voiceTwo
      c'4 e d f
    }
  }
>>
@end lilypond

@noindent
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 Staff \with {
  \consists "Ambitus_engraver"
}
<<
  \new Voice {
    \relative {
      \voiceOne
      c''4 a b g
    }
  }
  \new Voice {
    \relative {
      \voiceTwo
      c'4 e d f
    }
  }
>>
@end lilypond

@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
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

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new Staff {
      \relative {
        c''4 a b g
      }
    }
    \new Staff {
      \relative {
        c'4 a b g
      }
    }
    \new Staff {
      \clef "G_8"
      \relative {
        c'4 a b g
      }
    }
    \new Staff {
      \clef "bass"
      \relative {
        c4 a b g
      }
    }
  >>
  \layout {
    \context {
      \Staff
      \consists "Ambitus_engraver"
    }
  }
}
@end lilypond

@noindent
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}.

@knownissues
The @code{Stem_engraver} and @code{Beam_engraver} attach their
objects to note heads.  If the @code{Note_heads_engraver} is removed
no note heads are produced and therefore no stems or beams are created
either.


@node Extending the templates
@section Extending the templates

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.

@menu
* Soprano and cello::
* Four-part SATB vocal score::
* Building a score from scratch::
* Saving typing with variables and functions::
* Scores and parts::
@end menu

@node Soprano and cello
@subsection Soprano and cello

@cindex template, modifying
@cindex modifying templates

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 the
@q{Notes and lyrics} template (for the soprano part).

@example
\version @w{"@version{}"}

melody = \relative @{
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
@}

text = \lyricmode @{
  Aaa Bee Cee Dee
@}

\score @{
  <<
    \new Voice = "one" @{
      \autoBeamOff
      \melody
    @}
    \new Lyrics \lyricsto "one" \text
  >>
  \layout @{ @}
  \midi @{ @}
@}
@end example

Now we want to add a cello part.  Let's look at the @q{Notes only} example:

@example
\version @w{"@version{}"}

melody = \relative @{
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
@}

\score @{
  \new Staff \melody
  \layout @{ @}
  \midi @{ @}
@}
@end example

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}
section, we don't need two @code{\layout} or @code{\midi}.

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
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
instances of all these names -- both the initial definition (the
@code{melody = \relative @{ } 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
different notes.

@example
\version @w{"@version{}"}

sopranoMusic = \relative @{
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
@}

sopranoLyrics = \lyricmode @{
  Aaa Bee Cee Dee
@}

celloMusic = \relative @{
  \clef "bass"
  \key c \major
  \time 4/4
  d4 g fis8 e d4
@}

\score @{
  <<
    \new Voice = "one" @{
      \autoBeamOff
      \sopranoMusic
    @}
    \new Lyrics \lyricsto "one" \sopranoLyrics
  >>
  \layout @{ @}
  \midi @{ @}
@}
@end example

This is looking promising, but the cello part won't appear in the
score -- we haven't used it in the @code{\score} section.  If we
want the cello part to appear under the soprano part, we need to add

@example
\new Staff \celloMusic
@end 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:

@c Indentation in this example is deliberately poor
@example
\score @{
  <<
  <<
    \new Voice = "one" @{
      \autoBeamOff
      \sopranoMusic
    @}
    \new Lyrics \lyricsto "one" \sopranoLyrics
  >>
  \new Staff \celloMusic
  >>
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
This looks a bit messy; the indentation is messed up now.  That is
easily fixed.  Here's the complete soprano and cello template.

@lilypond[quote,verbatim,ragged-right,addversion]
sopranoMusic = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

sopranoLyrics = \lyricmode {
  Aaa Bee Cee Dee
}

celloMusic = \relative {
  \clef "bass"
  \key c \major
  \time 4/4
  d4 g fis8 e d4
}

\score {
  <<
    <<
      \new Voice = "one" {
        \autoBeamOff
        \sopranoMusic
      }
      \new Lyrics \lyricsto "one" \sopranoLyrics
    >>
    \new Staff \celloMusic
  >>
  \layout { }
  \midi { }
}
@end lilypond


@seealso
The starting templates can be found in the @q{Templates} appendix,
see @ref{Single staff templates}.


@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
staves, one for each of SATB, with a piano reduction of the
orchestral accompaniment underneath.  Here's an example
from Handel's Messiah:

@c The following should appear as music without code
@lilypond[quote,ragged-right]
global = { \key d \major \time 4/4 }

sopranoMusic = \relative {
  \clef "treble"
  r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
}
sopranoWords = \lyricmode {
  Wor -- thy | is the lamb | that was slain |
}

altoMusic = \relative {
  \clef "treble"
  r4 a'2 a4 | fis4. fis8 a2 | g4 fis e2 |
}
altoWords = \sopranoWords

tenorMusic = \relative {
  \clef "G_8"
  r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
}
tenorWords = \sopranoWords

bassMusic = \relative {
  \clef "bass"
  r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
}
bassWords = \sopranoWords

upper = \relative {
  \clef "treble"
  \global
  r4 <a' d fis>2 <a e' a>4 |
  <d fis d'>4. <d fis d'>8 <a d a'>2 |
  <g cis g'>4 <a d fis> <a cis e>2 |
}

lower = \relative {
  \clef "bass"
  \global
  <d, d'>4 <d d'>2 <cis cis'>4 |
  <b b'>4. <b' b'>8 <fis fis'>2 |
  <e e'>4 <d d'> <a' a'>2 |
}

\score {
  <<  % combine ChoirStaff and PianoStaff in parallel
    \new ChoirStaff <<
      \new Staff = "sopranos"
      \with { instrumentName = #"Soprano" }
      <<
        \new Voice = "sopranos" {
          \global
          \sopranoMusic
        }
      >>
      \new Lyrics \lyricsto "sopranos" {
        \sopranoWords
      }
      \new Staff = "altos"
      \with { instrumentName = #"Alto" }
      <<
        \new Voice = "altos" {
          \global
          \altoMusic
        }
      >>
      \new Lyrics \lyricsto "altos" {
        \altoWords
      }
      \new Staff = "tenors"
      \with { instrumentName = #"Tenor" }
      <<
        \new Voice = "tenors" {
          \global
          \tenorMusic
        }
      >>
      \new Lyrics \lyricsto "tenors" {
        \tenorWords
      }
      \new Staff = "basses"
      \with { instrumentName = #"Bass" }
      <<
        \new Voice = "basses" {
          \global
          \bassMusic
        }
      >>
      \new Lyrics \lyricsto "basses" {
        \bassWords
      }
    >>  % end ChoirStaff
    \new PianoStaff \with { instrumentName = #"Piano" }
    <<
      \new Staff = "upper" \upper
      \new Staff = "lower" \lower
    >>
  >>
}
@end lilypond

@warning{This layout can be achieved very easily using the built-in
template: @code{satb.ly}, see @ref{Built-in templates}.  But for ease
of use this template deliberately hides the necessary context
structure, instead providing it automatically.  So for purposes of
learning let us see how to build this up from scratch.  You may need
to do this if the built-in template does not meet your needs
adequately.}

The nearest copy-and-edit template to this layout is
@ref{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.

The order in which the contexts appear in the ChoirStaff of 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.  All the
voices should be @code{\voiceOne}, which is 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 familiar.  We should also add the names of
each staff.

Doing this gives for our ChoirStaff:

@example
\new ChoirStaff <<
  \new Staff = "sopranos"
  \with @{ instrumentName = #"Soprano" @}
  <<
    \new Voice = "sopranos" @{
      \global
      \sopranoMusic
    @}
  >>
  \new Lyrics \lyricsto "sopranos" @{
    \sopranoWords
  @}
  \new Staff = "altos"
  \with @{ instrumentName = #"Alto" @}
  <<
    \new Voice = "altos" @{
      \global
      \altoMusic
    @}
  >>
  \new Lyrics \lyricsto "altos" @{
    \altoWords
  @}
  \new Staff = "tenors"
  \with @{ instrumentName = #"Tenor" @}
  <<
    \new Voice = "tenors" @{
      \global
      \tenorMusic
    @}
  >>
  \new Lyrics \lyricsto "tenors" @{
    \tenorWords
  @}
  \new Staff = "basses"
  \with @{ instrumentName = #"Bass" @}
  <<
    \new Voice = "basses" @{
      \global
      \bassMusic
    @}
  >>
  \new Lyrics \lyricsto "basses" @{
    \bassWords
  @}
>>  % end ChoirStaff
@end example

Next we must work out the piano part.  This is
easy - we just pull out the piano part from the
@q{Solo piano} template:

@example
\new PianoStaff \with @{ instrumentName = #"Piano  " @}
<<
  \new Staff = "upper" \upper
  \new Staff = "lower" \lower
>>
@end example

and add the variable definitions for @code{upper}
and @code{lower}.

The ChoirStaff and PianoStaff must be combined
using angle brackets as we want them to be
stacked one above the other:

@example
<<  % combine ChoirStaff and PianoStaff one above the other
  \new ChoirStaff <<
    \new Staff = "sopranos" <<
      \new Voice = "sopranos" @{
        \global
        \sopranoMusic
      @}
    >>
    \new Lyrics \lyricsto "sopranos" @{
      \sopranoWords
     @}
    \new Staff = "altos" <<
      \new Voice = "altos" @{
        \global
        \altoMusic
      @}
    >>
    \new Lyrics \lyricsto "altos" @{
      \altoWords
    @}
    \new Staff = "tenors" <<
      \clef "G_8"  % tenor clef
      \new Voice = "tenors" @{
        \global
        \tenorMusic
      @}
    >>
    \new Lyrics \lyricsto "tenors" @{
      \tenorWords
    @}
    \new Staff = "basses" <<
      \clef "bass"
      \new Voice = "basses" @{
        \global
        \bassMusic
      @}
    >>
    \new Lyrics \lyricsto "basses" @{
      \bassWords
    @}
  >>  % end ChoirStaff

  \new PianoStaff \with @{ instrumentName = #"Piano" @}
  <<
    \new Staff = "upper" \upper
    \new Staff = "lower" \lower
  >>
>>
@end example

Combining all these together and adding the music
for the three bars of the example above gives:

@lilypond[quote,verbatim,ragged-right,addversion]
global = { \key d \major \time 4/4 }
sopranoMusic = \relative {
  \clef "treble"
  r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
}
sopranoWords = \lyricmode {
  Wor -- thy | is the lamb | that was slain |
}
altoMusic = \relative {
  \clef "treble"
  r4 a'2 a4 | fis4. fis8 a2 | g4 fis fis2 |
}
altoWords = \sopranoWords
tenorMusic = \relative {
  \clef "G_8"
  r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
}
tenorWords = \sopranoWords
bassMusic = \relative {
  \clef "bass"
  r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
}
bassWords = \sopranoWords
upper = \relative {
  \clef "treble"
  \global
  r4 <a' d fis>2 <a e' a>4 |
  <d fis d'>4. <d fis d'>8 <a d a'>2 |
  <g cis g'>4 <a d fis> <a cis e>2 |
}
lower = \relative {
  \clef "bass"
  \global
  <d, d'>4 <d d'>2 <cis cis'>4 |
  <b b'>4. <b' b'>8 <fis fis'>2 |
  <e e'>4 <d d'> <a' a'>2 |
}

\score {
  <<  % combine ChoirStaff and PianoStaff in parallel
    \new ChoirStaff <<
      \new Staff = "sopranos"
      \with { instrumentName = #"Soprano" }
      <<
        \new Voice = "sopranos" {
          \global
          \sopranoMusic
        }
      >>
      \new Lyrics \lyricsto "sopranos" {
        \sopranoWords
      }
      \new Staff = "altos"
      \with { instrumentName = #"Alto" }
      <<
        \new Voice = "altos" {
          \global
          \altoMusic
        }
      >>
      \new Lyrics \lyricsto "altos" {
        \altoWords
      }
      \new Staff = "tenors"
      \with { instrumentName = #"Tenor" }
      <<
        \new Voice = "tenors" {
          \global
          \tenorMusic
        }
      >>
      \new Lyrics \lyricsto "tenors" {
        \tenorWords
      }
      \new Staff = "basses"
      \with { instrumentName = #"Bass" }
      <<
        \new Voice = "basses" {
          \global
          \bassMusic
        }
      >>
      \new Lyrics \lyricsto "basses" {
        \bassWords
      }
    >>  % end ChoirStaff

    \new PianoStaff
    \with { instrumentName = #"Piano  " }
    <<
      \new Staff = "upper" \upper
      \new Staff = "lower" \lower
    >>
  >>
}
@end lilypond


@node Building a score from scratch
@subsection Building a score from scratch

@cindex template, writing your own
@cindex example of writing a score
@cindex writing a score, example
@cindex score, example of writing

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
prelude as an example.

We begin with a header section.  Here go the title, name
of composer, etc, then come any variable definitions, and
finally the score block.  Let's start with these in outline
and fill in the details later.

We'll use the first two bars of Bach's prelude
based on @emph{Jesu, meine Freude} which is written for two
manuals and pedal organ.  You can see these two bars of music
at the bottom of this section.  The top manual part has two voices,
the lower and pedal organ one each.  So we need four
music definitions and one to define the time signature
and key:

@example
\version @w{"@version{}"}
\header @{
  title = "Jesu, meine Freude"
  composer = "J S Bach"
@}
keyTime = @{ \key c \minor \time 4/4 @}
ManualOneVoiceOneMusic = @{ s1 @}
ManualOneVoiceTwoMusic = @{ s1 @}
ManualTwoMusic = @{ s1 @}
PedalOrganMusic = @{ s1 @}

\score @{
@}
@end example

For now we've just used a spacer note, @code{s1},
instead of the real music.  We'll add that later.

Next let's see what should go in the score block.
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
need to use a PianoStaff for them.  The first
manual part needs two voices and the second manual
part just one.

@example
\new PianoStaff <<
  \new Staff = "ManualOne" <<
    \new Voice @{
      \ManualOneVoiceOneMusic
    @}
    \new Voice @{
      \ManualOneVoiceTwoMusic
    @}
  >>  % end ManualOne Staff context
  \new Staff = "ManualTwo" <<
    \new Voice @{
      \ManualTwoMusic
    @}
  >>  % end ManualTwo Staff context
>>  % end PianoStaff context
@end example

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
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
see what errors it generates.

@example
<<  % PianoStaff and Pedal Staff must be simultaneous
  \new PianoStaff <<
    \new Staff = "ManualOne" <<
      \new Voice @{
        \ManualOneVoiceOneMusic
      @}
      \new Voice @{
        \ManualOneVoiceTwoMusic
      @}
    >>  % end ManualOne Staff context
    \new Staff = "ManualTwo" <<
      \new Voice @{
        \ManualTwoMusic
      @}
    >>  % end ManualTwo Staff context
  >>  % end PianoStaff context
  \new Staff = "PedalOrgan" <<
    \new Voice @{
      \PedalOrganMusic
    @}
  >>
>>
@end example

It is not necessary to use the simultaneous construct
@code{<< @dots{} >>} 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.  The opposite
is true for Voices: these should habitually be followed by braces
@code{@{ @dots{} @}} 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 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 key and time
signature to each staff using our predefined variable, @code{\keyTime}.

@example
\score @{
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice @{
          \voiceOne
          \ManualOneVoiceOneMusic
        @}
        \new Voice @{
          \voiceTwo
          \ManualOneVoiceTwoMusic
        @}
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" <<
        \keyTime
        \clef "bass"
        \new Voice @{
          \ManualTwoMusic
        @}
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice @{
        \PedalOrganMusic
      @}
    >>  % end PedalOrgan Staff
  >>
@}  % end Score context
@end example

@cindex stretchability of staves
@cindex staves, stretchability

The above layout of the organ staves is almost perfect; however,
there is a slight defect which is not visible by looking at just a
single system: The distance of the pedal staff to the left hand staff
should behave approximately the same as the right hand staff to the
left hand staff.  In particular, the stretchability of staves in a
@code{PianoStaff} context is limited (so that the distance between
the staves for the left and right hand can't become too large), and
the pedal staff should behave similarly.

@cindex sub-properties
@cindex properties, sub-properties
@cindex graphical objects
@cindex objects, graphical
@cindex grobs

Stretchability of staves can be controlled with the
@code{staff-staff-spacing} property of the
@code{VerticalAxisGroup} @q{graphical object} (commonly called
@q{grob}s within the lilypond documentation) -- don't worry about
the details right now; this is fully explained later.  For the
curious, have a look at @ruser{Overview of modifying properties}.
In this case, we want to modify the @code{stretchability}
sub-property only. Again, for the curious, you can find the
default values for the staff-staff-spacing property
in file @file{scm/define-grobs.scm} by looking up the definition
of the @code{VerticalAxisGroup} grob.  The value for
@code{stretchability} is taken from the definition of the
@code{PianoStaff} context (in file @file{ly/engraver-init.ly})
so that the values are identical.

@example
\score @{
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice @{
          \voiceOne
          \ManualOneVoiceOneMusic
        @}
        \new Voice @{
          \voiceTwo
          \ManualOneVoiceTwoMusic
        @}
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" \with @{
        \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
      @} <<
        \keyTime
        \clef "bass"
        \new Voice @{
          \ManualTwoMusic
        @}
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice @{
        \PedalOrganMusic
      @}
    >>  % end PedalOrgan Staff
  >>
@}  % end Score context
@end example
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
is to add the music, and combine all the parts together.

@lilypond[quote,verbatim,ragged-right,addversion]
\header {
  title = "Jesu, meine Freude"
  composer = "J S Bach"
}
keyTime = { \key c \minor \time 4/4 }
ManualOneVoiceOneMusic = \relative {
  g'4 g f ees |
  d2 c |
}
ManualOneVoiceTwoMusic = \relative {
  ees'16 d ees8~ 16 f ees d c8 d~ d c~ |
  8 c4 b8 c8. g16 c b c d |
}
ManualTwoMusic = \relative {
  c'16 b c8~ 16 b c g a8 g~ 16 g aes ees |
  f16 ees f d g aes g f ees d ees8~ 16 f ees d |
}
PedalOrganMusic = \relative {
  r8 c16 d ees d ees8~ 16 a, b g c b c8 |
  r16 g ees f g f g8 c,2 |
}

\score {
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice {
          \voiceOne
          \ManualOneVoiceOneMusic
        }
        \new Voice {
          \voiceTwo
          \ManualOneVoiceTwoMusic
        }
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" \with {
        \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
      } <<
        \keyTime
        \clef "bass"
        \new Voice {
          \ManualTwoMusic
        }
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice {
        \PedalOrganMusic
      }
    >>  % end PedalOrgan Staff context
  >>
}  % end Score context
@end lilypond

@seealso
Music Glossary:
@rglos{system}.

@node Saving typing with variables and functions
@subsection Saving typing with variables and functions

@cindex variables
@cindex variables

By this point, you've seen this kind of thing:

@lilypond[quote,verbatim,ragged-right]
hornNotes = \relative { c''4 b dis c }

\score {
  {
    \hornNotes
  }
}
@end lilypond

You may even realize that this could be useful in minimalist music:

@lilypond[quote,verbatim,ragged-right]
fragmentA = \relative { a'4 a8. b16 }
fragmentB = \relative { a'8. gis16 ees4 }

violin = \new Staff {
  \fragmentA \fragmentA |
  \fragmentB \fragmentA |
}

\score {
  {
    \violin
  }
}
@end lilypond

However, you can also use these variables (also known as
macros, or user-defined commands) for tweaks:

@lilypond[quote,verbatim,ragged-right]
dolce = \markup { \italic \bold dolce }

centreText = { \once \override TextScript.self-alignment-X = #CENTER }

fthenp =_\markup {
  \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
}

violin = \relative {
  \repeat volta 2 {
    c''4._\dolce b8 a8 g a b |
    \centreText
    c4.^"hi there!" d8 e f g d |
    c4.\fthenp b8 c4 c-. |
  }
}

\score {
  {
    \violin
  }
}
@end lilypond

These variables are obviously useful for saving
typing.  But they're worth considering even if you
only use them once -- they reduce complexity.  Let's
look at the previous example without any
variables.  It's a lot harder to read, especially
the last line.

@example
violin = \relative @{
  \repeat volta 2 @{
    c''4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
    \once \override TextScript.self-alignment-X = #CENTER
    c4.^"hi there!" d8 e f g d |
    c4._\markup @{
      \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
    @}
    b8 c4 c-. |
  @}
@}
@end example

So far we've seen static substitution -- when LilyPond
sees @code{\centreText}, it replaces it with the stuff that
we've defined it to be (ie the stuff to the right of
@code{centreText=}).

LilyPond can handle non-static substitution, too (you
can think of these as functions).

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function
     (padding)
     (number?)
   #{
     \once \override TextScript.padding = #padding
   #})

\relative {
  c''4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" b a b
  \padText #2.6
  c4^"piu mosso" b a b
}
@end lilypond

Using variables is also a good way to reduce work if the
LilyPond input syntax changes (see
@rprogram{Updating files with convert-ly}).  If
you have a single definition (such as @code{\dolce}) for all your
input files (see @ref{Style sheets}), then if the syntax changes, you
only need to update your single @code{\dolce} definition,
instead of making changes throughout every @file{.ly} file.


@node Scores and parts
@subsection Scores and parts

In orchestral music, all notes are printed twice.  Once in a part for
the musicians, and once in a full score for the conductor.  Variables can
be used to avoid double work.  The music is entered once, and stored in
a variable.  The contents of that variable is then used to generate
both the part and the full score.

It is convenient to define the notes in a special file.  For example,
suppose that the file @file{horn-music.ly} contains the following part
of a horn/@/bassoon duo

@example
hornNotes = \relative @{
  \time 2/4
  r4 f8 a | cis4 f | e4 d |
@}
@end example

@noindent
Then, an individual part is made by putting the following in a file

@example
\include "horn-music.ly"

\header @{
  instrument = "Horn in F"
@}

@{
 \transpose f c' \hornNotes
@}
@end example

The line

@example
\include "horn-music.ly"
@end example

@noindent
substitutes the contents of @file{horn-music.ly} at this position in
the file, so @code{hornNotes} is defined afterwards.  The command
@code{\transpose f@tie{}c'} indicates that the argument, being
@code{\hornNotes}, should be transposed by a fifth upwards.  Sounding
@code{f} is denoted by notated @code{c'}, which corresponds with the
tuning of a normal French Horn in@tie{}F.  The transposition can be seen
in the following output

@lilypond[quote,ragged-right]
\transpose f c' \relative {
  \time 2/4
  r4 f8 a | cis4 f | e4 d |
}
@end lilypond

In ensemble pieces, one of the voices often does not play for many
measures.  This is denoted by a special rest, the multi-measure
rest.  It is entered with a capital @code{R} followed by a duration
(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
etc.).  By multiplying the
duration, longer rests can be constructed.  For example, this rest
takes 3@tie{}measures in 2/4 time

@example
R2*3
@end example

When printing the part, multi-measure rests must be compressed.  There
is a music function available to do this:

@example
\compressMMRests @{ ... @}
@end example

Applying this to @code{hornNotes} gives:

@lilypond[quote,ragged-right]
\compressMMRests \transpose f c' \relative {
  \time 2/4
  R2*3 |
  r4 f8 a | cis4 f | e4 d |
}
@end lilypond


The score is made by combining all of the music together.  Assuming
that the other voice is in @code{bassoonNotes} in the file
@file{bassoon-music.ly}, a score is made with

@example
\include "bassoon-music.ly"
\include "horn-music.ly"

<<
  \new Staff \hornNotes
  \new Staff \bassoonNotes
>>
@end example

@noindent
leading to

@lilypond[quote,ragged-right]
\relative <<
  \new Staff {
    \clef "treble"
    \time 2/4
    R2*3 |
    r4 f8 a | cis4 f | e4 d |
  }
  \new Staff {
    \clef "bass"
    \time 2/4
    r4 d,8 f | gis4 c | b4 bes |
    a8 e f4 | g4 d | gis4 f |
  }
>>
@end lilypond

@seealso
Learning Manual:
@ref{Organizing pieces with variables}.

Notation Reference:
@ruser{Transpose},
@ruser{Writing parts},
@ruser{Full measure rests},
@ruser{Including LilyPond files}.