@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 files work::
* Voices contain music::
* Contexts and engravers::
* Extending the templates::
-* Scores and parts::
@end menu
The LilyPond input format is quite free-form, giving experienced
users a lot of flexibility to structure their files however they
-wish. However, this flexibility can make things confusing for new
+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::
+* Nesting music expressions::
+* On the un-nestedness of brackets and ties::
@end menu
@node Introduction to the LilyPond file structure
A basic example of a lilypond input file is
@example
-\version "2.11.23"
+\version @w{"@version{}"}
\score @{
@var{...compound music expression...} % all the music goes here!
\header @{ @}
There are many variations of this basic pattern, but this
example serves as a useful starting place.
-At this point, you may be confused, since you have never seen a
-@code{\score@{@}} before. This is because LilyPond automatically
-adds the extra commands when you give it simple input. LilyPond
-treats input like this:
+Up to this point none of the examples you have seen has used a
+@code{\score@{@}} command. This is because LilyPond automatically
+adds the extra commands which are needed when you give it simple
+input. LilyPond treats input like this:
@example
\relative c'' @{
as shorthand for this:
@example
-\score @{
- \relative c'' @{
- c4 a b c
+\book @{
+ \score @{
+ \new Staff @{
+ \new Voice @{
+ \relative c'' @{
+ c4 a b c
+ @}
+ @}
+ @}
+ \layout @{ @}
@}
- \layout @{ @}
@}
@end example
In other words, if the input contains a single music expression,
LilyPond will interpret the file as though the music expression
-was wrapped up inside a @code{\score@{@}}.
+was wrapped up inside the commands shown above. For now, though,
+let us return to the first example and examine the @code{\score}
+command, leaving the others to default.
-@smallspace
-
-A @code{\score} must begin with a compound music expression.
+A @code{\score} block must always contain just one music
+expression, and
+this must appear immediately after the @code{\score} command.
Remember that a music expression could be anything from a single
-note to a huge
+note to a huge compound expression like
@example
@{
Since everything is inside @code{@{ ... @}}, it counts
as one music expression.
-As we saw previously, the @code{\score} can contain other things,
-such as
+As we saw previously, the @code{\score} block can contain other
+things, such as
@example
\score @{
@noindent
Some people put some of those commands outside the @code{\score}
block -- for example, @code{\header} is often placed above the
-@code{\score}. That's just another shorthand that LilyPond
+@code{\score} command. That's just another shorthand that LilyPond
accepts.
-@smallspace
+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 files}.
+
+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 @code{.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. For details see @ruser{Multiple scores
+in a book}.
@cindex variables
When LilyPond looks at this file, it takes the value of
@code{melody} (everything after the equals sign) and inserts it
whenever it sees @code{\melody}. There's nothing special about
-the names -- it could be @code{melody}, @code{global},
-@code{pianorighthand}, or @code{foofoobarbaz}. You can use
-whatever variable names you want as along as they contain just
-alphabetic characters. For more details, see
-@ruser{Saving typing with variables and functions}.
+the names -- it could be @code{melody}, @code{global},
+@code{TimeKey},
+@code{pianorighthand}, or @code{foofoobarbaz}. For more details,
+see @ref{Saving typing with variables and functions}.
+Remember that you can use almost any name you like as long
+as it contains just alphabetic characters and is distinct from
+LilyPond command names. The exact
+limitations on variable names are detailed in
+@ruser{File structure}.
+
@seealso
there @emph{is} no mystery. This line explains it all:
@quotation
-@emph{A @code{\score} must begin with a compound music expression.}
+@emph{A @code{\score} block must begin with a compound music expression.}
@end quotation
@noindent
A whole Wagner opera would easily double the length of this
manual, so let's just add a singer and piano. We don't need a
-@code{GrandStaff} for this ensemble, so we shall remove it. We
-@emph{do} need a singer and a piano, though.
+@code{GrandStaff} for this ensemble, which simply groups a number
+of staves together with a brace at the left, so we shall remove
+it. We @emph{do} need a singer and a piano, though.
@example
\score @{
- @{
- <<
- \new Staff = "singer" <<
- >>
- \new PianoStaff = piano <<
- >>
+ <<
+ \new Staff = "singer" <<
>>
- @}
+ \new PianoStaff = piano <<
+ >>
+ >>
\layout @{ @}
@}
@end example
-Remember that we use @code{<<} and @code{>>} to show simultaneous
+Remember that we use @code{<< ... >>} instead of
+@code{@{ ... @}} to show simultaneous
music. And we definitely want to show the vocal part and piano
part at the same time, not one after the other! However, the
-@code{<< .. >>} construct is not really necessary for the Singer
+@code{<< ... >>} construct is not really necessary for the Singer
staff, as it contains only one music expression, but Staves often
-do require simultaneous Voices within them, so using @code{<< .. >>}
-rather than braces is a good habit to adopt.
+do require simultaneous Voices within them, so using
+@code{<< ... >>}
+rather than braces is a good habit to adopt. We'll add some real
+music later; for now let's just put in some dummy notes and lyrics.
-@example
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- \new Voice = "vocal" @{ @}
- >>
- \new Lyrics \lyricsto vocal \new Lyrics @{ @}
- \new PianoStaff = "piano" <<
- \new Staff = "upper" @{ @}
- \new Staff = "lower" @{ @}
- >>
+@lilypond[verbatim,quote,ragged-right]
+\score {
+ <<
+ \new Staff = "singer" <<
+ \new Voice = "vocal" { c'1 }
+ \addlyrics { And }
>>
- @}
- \layout @{ @}
-@}
-@end example
+ \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
@example
\relative c'' @{
- a4 b c d
+ r4 d8\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.
+let's use variables instead. These were introduced at the end
+of the previous section, remember? So, adding a few notes, we
+now have a piece of real music:
-@example
-melody = @{ @}
-text = @{ @}
-upper = @{ @}
-lower = @{ @}
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- \new Voice = "vocal" @{ \melody @}
- >>
- \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
- \new PianoStaff = "piano" <<
- \new Staff = "upper" @{ \upper @}
- \new Staff = "lower" @{ \lower @}
- >>
+@lilypond[verbatim,quote,ragged-right]
+melody = \relative c'' { r4 d8\noBeam g, c4 r }
+text = \lyricmode { And God said, }
+upper = \relative c'' { <g d g,>2~ <g d g,> }
+lower = \relative c { b2 e2 }
+
+\score {
+ <<
+ \new Staff = "singer" <<
+ \new Voice = "vocal" { \melody }
+ \addlyrics { \text }
>>
- @}
- \layout @{ @}
-@}
-@end example
+ \new PianoStaff = "piano" <<
+ \new Staff = "upper" { \upper }
+ \new Staff = "lower" {
+ \clef "bass"
+ \lower
+ }
+ >>
+ >>
+ \layout { }
+}
+@end lilypond
-@noindent
-Remember that you can use almost any name you like as long
-as it contains just alphabetic characters. The exact
-limitations on variable names are detailed in
-@ruser{File structure}.
+
+Be careful about the difference between notes, which are introduced
+with @code{\relative}, and lyrics, which are introduced with
+@code{\lyricmode}. These are essential to tell LilyPond
+to interpret the following content as music and text
+respectively.
When writing (or reading) a @code{\score} section, just take it
slowly and carefully. Start with the outer layer, then work on
on the same horizontal position in your text editor.
-@node Nesting Music Expressions
-@subsection Nesting Music Expressions
+@node Nesting music expressions
+@subsection Nesting music expressions
-New staves do not have to all be declared at the beginning;
+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's a simple example showing how
+(see @rglos{ossia}). Here is a simple example showing how
to introduce a new staff temporarily for the duration of
three notes:
}
@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 begining of the line. This is usual for clefs printed
+in the middle of a line.
+
The ossia section may be placed above the staff
as follows:
This example uses @code{\with}, which will be explained more
fully later. It is a means of modifying the default behaviour
-of a 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.
+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.
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 ...
-TODO Add ref to tweaks section where this example should
-be placed and explained.
-
-@lilypond[verbatim,quote,ragged-right]
-\new Staff = "main" {
- \relative g' {
- r4 g8 g c4 c8 d |
- e4
- << % Start main and ossia in parallel
- { r8 f c c } % Main music
- \new Staff \with { % Start ossia staff
- \remove "Clef_engraver"
- \remove "Time_signature_engraver"
- % Reduce size of notes and staff
- fontSize = #-2
- \override StaffSymbol #'staff-space = #(magstep -2)
- alignAboveContext = "main" % Place above main staff
- }
- { s8 f f c } % Ossia music
- >> % End parallel music
- r4 |
- }
-}
-@end lilypond
+have not yet been introduced. See @ref{Size of objects}
+@node On the un-nestedness of brackets and ties
+@subsection On the un-nestedness of brackets and ties
You have already met a number of different types of bracket in
writing the input file to LilyPond. These obey different rules
which can be confusing at first. Before we explain the rules
let's first review the different types of bracket.
-@multitable @columnfractions .3 .7
+@c attempt to force this onto a new page
+@need 50
+@multitable @columnfractions .3 .7
@headitem Bracket Type
@tab Function
@item @code{@{ .. @}}
@item @code{< .. >}
@tab Encloses the notes of a chord
@item @code{<< .. >>}
- @tab Encloses concurrent or simultaneous sections
+ @tab Encloses concurrent or simultaneous sections
@item @code{( .. )}
@tab Marks the start and end of a slur
@item @code{\( .. \)}
To these we should add other constructs which generate lines
between or across notes: ties (marked by a tilde, @code{~}),
-tuplets written as @code{\times x/y @{ .. @}}, and grace notes
-written as @code{\grace@{ .. @}}.
-
-Outside LilyPond, the conventional use of brackets requires
-the different types to be properly nested, like this,
-@code{<< @{ ( .. ) @} >>}, with the closing brackets being
-encountered in exactly the opposite order to the opening
-brackets. This @strong{is} a requirement for the three types of
-bracket described by the word @q{Encloses} in the table above -
+tuplets written as @code{\times x/y @{..@}}, and grace notes
+written as @code{\grace@{..@}}.
+
+Outside LilyPond, the conventional use of brackets requires
+the different types to be properly nested, like this,
+@code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
+encountered in exactly the opposite order to the opening
+brackets. This @strong{is} a requirement for the three types of
+bracket described by the word @q{Encloses} in the table above --
they must nest properly.
-However, the remaining brackets, described with the word
+However, the remaining brackets, described with the word
@q{Marks} in the table above together with ties and tuplets,
do @strong{not} have to nest
-properly with any of the brackets. In fact, these are not
+properly with any of the brackets. In fact, these are not
brackets in the sense that
-they enclose something - they are simply markers to indicate
+they enclose something -- they are simply markers to indicate
where something starts and ends.
So, for example, a phrasing slur can start before a manually
-inserted beam and end before the end of the beam - not very
+inserted beam and end before the end of the beam -- not very
musical, perhaps, but possible:
@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
Singers need voices to sing, and so does LilyPond.
The actual music for all instruments in a score
-is contained in Voices - the most fundamental
+is contained in Voices -- the most fundamental
of all LilyPond's concepts.
@menu
In fact, a Voice layer or context is the only one which can
contain music. If a Voice context is not explicitly declared
-one is created automatically. Some instruments such as an
+one is created automatically, as we saw at the beginning of
+this chapter. Some instruments such as an
Oboe can play only one note at a time. Music written for
such instruments is monophonic and requires just a single
voice. Instruments which can play more than one note at a
capable of playing.
A single voice can contain many notes in a chord, of course,
-so when exactly are multiple voices needed?
-Let us analyse a short piece of music to see how many voices
-are required. Here are the notes from the first two bars
-of the second of Chopin's Deux Nocturnes, Op 32.
+so when exactly are multiple voices needed? Look first at
+this example of four chords:
-@c The following should appear as music without code
-@lilypond[quote,ragged-right]
-\new Staff \relative c'' {
- \key aes \major
- <<
- { \voiceOne
- c2 aes4. bes8 } \\
- { \voiceTwo
- aes2 f4 fes } \\
- { \voiceFour
- \once \override NoteColumn #'force-hshift = #0 <ees c>2
- \once \override NoteColumn #'force-hshift = #0.5 des2 }
- >> |
- <c ees aes c>1 |
-}
+@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
+\key g \major
+<d g>4 <d fis> <d a'> <d g>
@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 here, where we have used different noteheads
-and colors for the three voices.
-
-@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 c'' {
- \key aes \major
- <<
- { \voiceOne
- \voiceOneStyle
- c2 aes4. bes8 } \\
- { \voiceTwo
- \voiceTwoStyle
- aes2 f4 fes } \\
- { \voiceFour
- \voiceThreeStyle
- \once \override NoteColumn #'force-hshift = #0 <ees c>2
- \once \override NoteColumn #'force-hshift = #0.5 des2 }
- >> |
- <c ees aes c>1 |
-}
-@end lilypond
-
-Let us see how this is done.
-
+This can be expressed using just the single angle bracket chord
+symbols, @code{< ... >}, and for this just a single voice is
+needed. But suppose the F-sharp were actually an eighth-note
+followed by an eighth-note G, a passing note on the way to the A?
+Now we have two notes which start at the same time but have
+different durations: the quarter-note D and the eighth-note
+F-sharp. How are these to be coded? They cannot be written as
+a chord because all the notes in a chord must have the same
+duration. And they cannot be written as two separate notes
+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{@{...@}}),
and combine them simultaneously with angle brackets, @code{<<...>>}.
-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
+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 monophonic with occasional short sections
-of polyphony. Here's a simple example:
+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,fragment,ragged-right,relative=2]
+\key g \major
+% Voice "1" Voice "2"
+<< { g4 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,fragment,ragged-right,relative=2]
\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 } >>
+<< { 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,fragment,ragged-right,relative=2]
+\key d \minor
+<< {
+ % Voice "1"
+ r4 g g4. a8 |
+ bes4 bes c bes |
+ a2. r4 |
+} \\ {
+ % Voice "2"
+ d,2 d4 g |
+ g4 g g8( a) g4 |
+ fis2. s4 |
+} >>
@end lilypond
+
This example has just two voices, but the same contruct may be
used to encode three or more voices by adding more back-slash
separators.
-The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
-In each of these contexts, vertical direction of slurs, stems, ties,
-dynamics etc., is set appropriately.
+The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
+In each of these contexts, the vertical direction of slurs,
+stems, ties, dynamics etc., is set appropriately.
@lilypond[quote,verbatim,fragment]
\new Staff \relative c' {
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 noteheads 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
+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 c' {
- \voiceOneStyle
+ % Main voice
c16 d e f
<< % Bar 1
- { g4 f e } \\
- { \voiceTwoStyle
- r8 e4 d c8 ~ }
- >> |
+ {
+ \voiceOneStyle
+ g4 f e
+ }
+ \\
+ {
+ \voiceTwoStyle
+ r8 e4 d c8 ~
+ }
+ >>
<< % Bar 2
- { d2 e2 } \\
- { c8 b16 a b8 g ~ g2 } \\
- { \voiceThreeStyle
- s4 b4 c2 }
+ % Voice 1 continues
+ { d2 e2 }
+ \\
+ % Voice 2 continues
+ { c8 b16 a b8 g ~ g2 }
+ \\
+ {
+ \voiceThreeStyle
+ s4 b4 c2
+ }
>>
}
@end lilypond
+The commands @code{\voiceXXXStyle} are mainly intended for use in
+educational documents such as this one. They modify the color
+of the note head, the stem and the beams, and the style of the
+note head, so that the voices may be easily distinguished.
+Voice one is set to red diamonds, voice two to blue triangles,
+voice three to green crossed circles, and voice four (not used
+here) to magenta crosses. We shall see later how commands like
+these may be created by the user.
+See @ref{Visibility and color of objects}
+TODO Add link to using variables for tweaks
+
Polyphony does not change the relationship of notes within a
-@code{\relative @{ @}} block. Each note is calculated relative to
-the note immediately preceding it, or to the first note of the
-preceding chord.
+@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 c' @{ noteA << <noteB noteC> \\ noteD >> noteE @}
+\relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
@end example
-@code{noteB} is relative to @code{noteA}
+@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}
-@code{noteC} is relative to @code{noteB}, 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:
-@code{noteD} is relative to @code{noteB}, not @code{noteA} or
-@code{noteC}.
+@example
+\relative c' @{ noteA ... @}
+<<
+ \relative c'' @{ < noteB noteC > ... @}
+\\
+ \relative g' @{ noteD ... @}
+>>
+\relative c' @{ noteE ... @}
+@end example
+
+Let us finally analyse 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 c'' {
+ \key aes \major
+ << % Voice one
+ { c2 aes4. bes8 }
+ \\ % Voice two
+ { aes2 f4 fes }
+ \\ % No voice three
+ \\ % Voice four
+ {
+ % 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
+ }
+ >> |
+ <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 c'' {
+ \key aes \major
+ <<
+ { % Voice one
+ \voiceOneStyle
+ c2 aes4. bes8
+ }
+ \\ % Voice two
+ { \voiceTwoStyle
+ aes2 f4 fes
+ }
+ \\ % No Voice three (we want stems down)
+ \\ % Voice four
+ { \voiceThreeStyle
+ % 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
+ }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
-@code{noteE} is relative to @code{noteD}, not @code{noteA}
-We are now in a position to return to the first example from
-the Chopin Nocturne to see how this might be encoded. As we
+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
+we have learnt, using the @code{<< \\ >>} construct to
enter the music of the first bar in three voices:
@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative c'' {
\key aes \major
- <<
+ <<
{ c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
- >> |
- <c ees aes c>1 |
+ >>
+ <c ees aes c>1
}
@end lilypond
@cindex stem down
@cindex stem up
-@funindex \voiceOne
-@funindex \voiceTwo
-@funindex \voiceThree
-@funindex \voiceFour
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 telling LilyPond that this third voice is really a fourth
-voice, with stems going down, using the @code{\voiceFour}
-command. There are also corresponding @code{\voiceOne},
-@code{\voiceTwo}, @code{voiceThree} and @code{voiceFour}
-commands. This results in the following:
+of music. We can correct this simply by missing out voice three
+and placing the music in voice four:
@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative c'' {
\key aes \major
- <<
- { c2 aes4. bes8 } \\
- { aes2 f4 fes } \\
- { \voiceFour <ees c>2 des2 }
+ << % Voice one
+ { c2 aes4. bes8 }
+ \\ % Voice two
+ { aes2 f4 fes }
+ \\ % Omit Voice three
+ \\ % Voice four
+ { <ees c>2 des2 }
>> |
<c ees aes c>1 |
}
@end lilypond
@noindent
-and exposes a problem commonly encountered with multiple
-voices: the stems of notes can collide with noteheads
+We see that this fixes the stem direction, but exposes a
+problem sometimes encountered with multiple voices -- the
+stems of the notes in one voice can collide with the note heads
in other voices. In laying out the notes, LilyPond allows the
notes or chords from two voices to occupy the same vertical
note column provided the stems are in opposite directions, but
-the notes from a third voice are displaced to avoid the stems
-colliding. This often works well, but in this example the
-notes of the third voice are clearly not well placed by default.
+the notes from the third and fourth voices are displaced to if
+necessary to avoid the note heads
+colliding. This usually works well, but in this example the
+notes of the lowest voice are clearly not well placed by default.
LilyPond provides several ways to adjust the horizontal placing
of notes. We are not quite ready yet to see how to correct this,
-so we shall leave this problem until a later section (see ... )
-
-FIXME: Move the following words and example into Tweaks or
-somewhere more suitable, leaving just a ref here. -td
-
-Ways of correcting horizontal placings are described fully
-in the Notation Reference.
-We introduce just one here, the @code{force-hshift} property of
-@code{NoteColumn}. The lower two notes of the first chord (i.e,
-those in the third voice) should not be shifted away from the
-note column of the higher two notes. To correct this we set
-@code{force-hshift} of these notes to zero.
-The lower note of the second chord is best placed just to the
-right of the higher notes. We achieve this by setting
-@code{force-hshift} of this note to 0.5, ie half a notehead's
-width to the right of the note column of the higher notes.
-
-Here's the final result:
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
- \key aes \major
- <<
- { c2 aes4. bes8 } \\
- { aes2 f4 fes } \\
- { \voiceFour
- \once \override NoteColumn #'force-hshift = #0 <ees c>2
- \once \override NoteColumn #'force-hshift = #0.5 des2
- }
- >> |
- <c ees aes c>1 |
-}
-@end lilypond
+so we shall leave this problem until a later section
+(see the force-hshift property in @ref{Fixing overlapping
+notation} )
@node Explicitly instantiating voices
@subsection Explicitly instantiating voices
+@funindex \voiceOne
+@funindex \voiceTwo
+@funindex \voiceThree
+@funindex \voiceFour
+
Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
@code{\voiceOne} ... @code{\voiceFour} to indicate the required
-directions of stems, slurs, etc.
+directions of stems, slurs, etc. In longer scores this method
+is clearer, as it permits the voices to be separated and to be
+given more descriptive names.
Specifically, the construct @code{<< \\ >>} which we used in
the previous section:
@example
-<< \upper \\ \lower >>
+\new Staff @{
+ \relative c' @{
+ << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
+ @}
+@}
@end example
@noindent
-where @code{upper} and @code{lower} are user-defined variables
-containing the music for the two voices, is equivalent to
+is equivalent to
@example
-<<
- \new Voice = "1" @{ \voiceOne \upper @}
- \new Voice = "2" @{ \voiceTwo \lower @}
+\new Staff <<
+ \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
+ \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
>>
@end example
+Both of the above would produce
+
+@c The following example should not display the code
+@lilypond[ragged-right,quote]
+\new Staff <<
+ \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
+ \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
+>>
+@end lilypond
+
The @code{\voiceXXX} commands set the direction of stems, slurs,
ties, articulations, text annotations, augmentation dots of dotted
notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
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 a simple example exactly what effect
+Let us see in some simple examples exactly what effect
@code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
markup, ties, slurs, and dynamics:
@lilypond[quote,ragged-right,verbatim]
\relative c'{
-c-"default" d8 ~ d e4 ( f g a ) b-> c \break
-\voiceOne
-c,-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c \break
-\oneVoice
-c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c \break
-\voiceTwo
-c,-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c \break
+ % Default behaviour or behaviour after \oneVoice
+ c d8 ~ d e4 ( f g a ) b-> c
+}
+@end lilypond
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'{
+ \voiceOne
+ c d8 ~ d e4 ( f g a ) b-> c
+ \oneVoice
+ c, d8 ~ d e4 ( f g a ) b-> c
+}
+@end lilypond
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'{
+ \voiceTwo
+ c d8 ~ d e4 ( f g a ) b-> c
+ \oneVoice
+ c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
An expression that appears directly inside a @code{<< >>} belongs
-to the main voice. This is useful when extra voices appear while
-the main voice is playing. Here is a more correct rendition of
-the example from the previous section. The red diamond-shaped
-notes demonstrate that the main melody is now in a single
-voice context, permitting a phrasing slur to be drawn over them.
+to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
+construct). This is useful when extra voices appear while the
+main voice is playing. Here is a more correct rendition of the
+example from the previous section. The red diamond-shaped notes
+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 c' {
\voiceOneStyle
- c16^( d e f % These notes are monophonic
- << % Start simultaneous section of three voices
- { g4 f e | d2 e2) } % Continue the main voice in parallel
- \new Voice { % Initiate second voice
- \voiceTwo % Set stems, etc, down
+ % The following notes are monophonic
+ c16^( d e f
+ % Start simultaneous section of three voices
+ <<
+ % Continue the main voice in parallel
+ { g4 f e | d2 e2) }
+ % Initiate second voice
+ \new Voice {
+ % Set stems, etc, down
+ \voiceTwo
r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
}
- \new Voice { % Initiate third voice
- \voiceThree % Set stems, etc, up
- s2. | s4 b4 c2
+ % Initiate third voice
+ \new Voice {
+ % Set stems, etc, up
+ \voiceThree
+ s2. | s4 b4 c2
}
>>
}
r8 e4 d c8 ~ |
<<
{c8 b16 a b8 g ~ g2}
- \new Voice {
+ \new Voice {
\voiceThree
s4 b4 c2
}
@end lilypond
-This method of nesting new voices briefly is useful
+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,
+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 c' <<
- \new Voice { % Initiate first voice
+ % Initiate first voice
+ \new Voice {
\voiceOne
c16^( d e f g4 f e | d2 e2) |
}
- \new Voice { % Initiate second voice
- \voiceTwo % set stems, etc down
+ % Initiate second voice
+ \new Voice {
+ % set stems, etc down
+ \voiceTwo
s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
}
- \new Voice { % Initiate third voice
- \voiceThree % set stems, etc up
+ % Initiate third voice
+ \new Voice {
+ % set stems, etc up
+ \voiceThree
s1 | s4 b4 c2 |
}
>>
@end lilypond
+@cindex note column
+@cindex shift commands
+@funindex \shiftOff
+@funindex \shiftOn
+@funindex \shiftOnn
+@funindex \shiftOnnn
+
+Closely spaced notes in a chord, or notes occuring 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{Too many clashing note columns} will be produced.
@node Voices and vocals
@subsection Voices and vocals
Vocal music presents a special difficulty: we need to combine two
expressions -- notes and lyrics.
-You have already seen the @code{\lyricsAdd@{@}} command, which
-handles simple cases for you. However, this technique is
-very limited. For most music, you must explicitly link the lyrics
-to the notes with @code{\lyricsto@{@}}, using the name assigned
-to the 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,fragment]
<<
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
+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.
>>
\new Staff <<
\new Voice = "SopTwo" {
+ \global
\SopTwoMusic
}
\new Lyrics \lyricsto "SopTwo" {
parts are the same.
@lilypond[quote,verbatim]
-global = { \time 4/4 \partial 4 \key c \major}
+TimeKey = { \time 4/4 \partial 4 \key c \major}
SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
\new ChoirStaff <<
\new Staff <<
\clef "treble"
- \new Voice = "Sop" { \voiceOne \global \SopMusic }
+ \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
\new Voice = "Alto" { \voiceTwo \AltoMusic }
\new Lyrics \lyricsto "Sop" { \VerseOne }
\new Lyrics \lyricsto "Sop" { \VerseTwo }
>>
\new Staff <<
\clef "bass"
- \new Voice = "Tenor" { \voiceOne \TenorMusic }
+ \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
\new Voice = "Bass" { \voiceTwo \BassMusic }
>>
>>
@menu
* Contexts explained::
* Creating contexts::
-* Engravers::
-* Modifying Contexts::
-* On the un-nestedness of brackets and ties::
+* Engravers explained::
+* Modifying context properties::
+* Adding and removing engravers::
@end menu
@node Contexts explained
the entire score.
Within LilyPond, these rules and bits of information are grouped
-in @emph{Contexts}. We have already met the @context{Voice}
-context.
-Others are the @context{Staff} and @context{Score} contexts.
+in @emph{Contexts}. We have already met the
+@code{Voice} context.
+Others are the @code{Staff} and @code{Score} contexts.
Contexts are hierarchical to reflect the heirarchical nature of
a musical score.
-For example: a @context{Staff} context can contain many
-@context{Voice} contexts, and a @context{Score} context can
-contain many @context{Staff} contexts.
+For example: a @code{Staff} context can contain many
+@code{Voice} contexts, and a @code{Score} context can
+contain many @code{Staff} contexts.
@quotation
-@image{context-example,5cm,,}
+@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 @context{Voice} context may introduce an
-accidental and then the @context{Staff} context maintains the rule to
+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 @context{Score} context.
+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
-@context{Score} and @context{Staff} contexts.
+@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.
+with specialized notation, it is usual to modify existing, or
+even to define totally new, contexts.
-In addition to the @context{Score,} @context{Staff} and
-@context{Voice} contexts there are contexts which fit between
+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
-@context{PianoStaff} and @context{ChoirStaff} contexts. There
+@code{PianoStaff} and @code{ChoirStaff} contexts. There
are also alternative staff and voice contexts, and contexts for
-lyrics, percussion, fret boards, figured bass, etc. A complete
-list is shown in the Notation Reference.
-TODO: Add link
+lyrics, percussion, fret boards, figured bass, etc.
-The names of all context types are formed from one or more
+The names of all context types are formed from one or more
words, each word being capitalised and joined immediately to the
preceding word with no hyphen or underscore, e.g.,
-@context{GregorianTranscriptionStaff}.
+@code{GregorianTranscriptionStaff}.
@node Creating contexts
@subsection Creating contexts
-There can be only one top level context, the @context{Score}
+There can be only one top level context: the
+@code{Score}
context. This is created with the @code{\score} command,
or, in simple scores, it is created automatically.
For scores with only one voice and one staff, the
-@context{Voice} and @context{Staff} contexts may be left to be
+@code{Voice} and @code{Staff} contexts may be left to be
created automatically, but for more complex scores it is
necessary to create them by hand.
The simplest command that does this is @code{\new}.
@cindex Context, creating
@example
-\new @var{type} @var{music expression}
+\new @var{type} @var{music-expression}
@end example
@noindent
where @var{type} is a context name (like @code{Staff} or
@code{Voice}). This command creates a new context, and starts
-interpreting the @var{music expression} within that context.
+interpreting the @var{music-expression} within that context.
-Note that there is no @code{\new Score % Invalid!} command;
-the single top-level @context{Score} context is introduced
-with @code{\score}. This is because there can be only one
-@context{Score} context, whereas there may be multiple
-@context{Staff} and @context{Voice} contexts - each created
-by @code{\new}.
-
-So a practical application of @code{\new} is a score with many
-staves. Each part that should be on its own staff is preceded
-with @code{\new Staff}.
-
-@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
-<<
- \new Staff { c4 c }
- \new Staff { d4 d }
->>
-@end lilypond
+Note that there is no @code{\new Score} command;
+the single top-level @code{Score} context is introduced
+with @code{\score}.
The @code{\new} command may also give a identifying name to the
context to distinguish it from other contexts of the same type,
@example
-\new @var{type} = @var{id} @var{music}
+\new @var{type} = @var{id} @var{music-expression}
@end example
Note the distinction between the name of the context type,
-@context{Staff}, @context{Voice}, etc, and
+@code{Staff}, @code{Voice}, etc, and
the identifying name of a particular instance of that type,
which can be any sequence of letters invented by the user.
The identifying name is used to refer back to that particular
lyrics in @ref{Voices and vocals}.
-@node Engravers
-@subsection Engravers
+@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 noteheads, one for stems, one for
+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.
-A musical score can be viewed heirarchically. At the top level
-is the whole score. This consists of one or more staves.
-Each staff contains one or more voices. As we have seen, there
-are contexts which correspond to each of these levels and it
-is in these contexts that the Engravers operate.
-
+Engravers live and operate in Contexts.
Engravers such as the @code{Metronome_mark_engraver}, whose
-action and output applies to the score as a whole, live in
-the highest level context - the @context{Score} context. There
-can be only one of these engravers as there can be only one tempo
-at any particular point in the score.
+action and output applies 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 the Staff Context, as different staves may require
+found in every Staff Context, as different staves may require
different clefs and keys.
The @code{Note_heads_engraver} and @code{Stem_engraver} live
-in a @context{Voice} context, the lowest level context of all.
+in every @code{Voice} context, the lowest level context of all.
Each engraver processes the particular objects associated
-with its function, and contains the properties that relate
+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
@item Metronome_mark_engraver
@tab Engraves metronome marking
@item Note_heads_engraver
- @tab Engraves noteheads
+ @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 tremulos
+@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.
-@node Modifying Contexts
-@subsection Modifying Contexts
+@node Modifying context properties
+@subsection Modifying context properties
-TODO: write section, including \with, \remove, \consists
+@cindex 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 @code{Voice} is assumed.
-@c my name start sucking the more docs I write. -gp
-@node On the un-nestedness of brackets and ties
-@subsection On the un-nestedness of brackets and ties
+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.
-Different kinds of brackets and ties may be mixed freely,
+@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
-TODO: improve this example
+@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}.
+
+Before we can set any of these properties we need to know
+in which context they operate. Sometimes this is obvious,
+but occasionally it can be tricky. If the wrong context
+is specified, no error message is produced, but the expected
+action will not take place. For example, the
+@code{instrumentName} clearly lives in the Staff context, since
+it is the staff that is to be named.
+In this example the first staff is labelled, but not the second,
+because we omitted the context name.
-@lilypond[quote,verbatim,fragment,ragged-right]
-{
- r16[ g16 \times 2/3 {r16 e'8] }
- g16( a \times 2/3 {b d e') }
- g8[( a \times 2/3 {b d') e'~]}
- \times 4/5 {e'32\( a b d' e'} a'4.\)
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff \relative c'' {
+ \set Staff.instrumentName = #"Soprano"
+ c4 c
+ }
+ \new Staff \relative c' {
+ \set instrumentName = #"Alto" % Wrong!
+ d4 d
+ }
+>>
+@end lilypond
+
+Remember the default context name is Voice, so the second
+@code{\set} command set the property @code{instrumentName} in the
+Voice context to @qq{Alto}, but as LilyPond does not look
+for any such property in the @code{Voice} context, no
+further action took place. This is not an error, and no error
+message is logged in the log file.
+
+Similarly, if the property name is mis-spelt no error message
+is produced, and clearly the expected action cannot be performed.
+If fact, you can set any (fictitious) @q{property} using any
+name you like in any context that exists by using the
+@code{\set} command. But if the name is not
+known to LilyPond it will not cause any action to be taken.
+This is one of the reasons why it is highly recommended to
+use a context-sensitive editor with syntax highlighting for
+editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
+since unknown property names will be highlighted differently.
+
+The @code{instrumentName} property will take effect only
+if it is set in the @code{Staff} context, but
+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 c'' {
+ ais4 aes
+ }
+ \new Staff \relative c'' {
+ \set Staff.extraNatural = ##f
+ ais4 aes
+ }
+>>
+@end lilypond
+
+@noindent
+and this turns them off in all staves:
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff \relative c'' {
+ ais4 aes
+ }
+ \new Staff \relative c'' {
+ \set Score.extraNatural = ##f
+ ais4 aes
+ }
+>>
+@end lilypond
+
+The value of every property set in this way can be reset
+to its original value with the @code{\unset} command.
+
+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 current value.
+
+@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+c4
+% make note heads smaller
+\set fontSize = #-4
+d e
+% make note heads larger
+\set fontSize = #2.5
+f g
+% return to original size
+\unset fontSize
+a b
+@end lilypond
+
+We have now seen how to set the values of several different
+types of property. Note that integers and numbers are alway
+preceded by a hash sign, @code{#}, while a true or false value
+is specified by ##t and ##f, with two hash signs. A text
+property should be enclosed in double quotation signs, as above,
+although we shall see later that text can actually be specified
+in a much more general way by using the very powerful
+@code{markup} command.
+
+
+@funindex \with
+
+Context properties may also be set at the time the context is
+created. Sometimes this is a clearer way of specifying a
+property value if it is to remain fixed for the duration of
+the context. When a context is created with a @code{\new}
+command it may be followed immediately by a
+@code{\with @{ .. @}} block in which the property values are
+set. For example, if we wish to suppress the printing of
+extra naturals for the duration of a staff we would write:
+
+@example
+\new Staff \with @{ extraNatural = ##f @}
+@end example
+
+@noindent
+like this:
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff
+ \relative c'' {
+ gis ges aes ais
+ }
+ \new Staff \with { extraNatural = ##f }
+ \relative c'' {
+ gis ges aes ais
+ }
+>>
+@end lilypond
+
+In effect this overrides the default value of the property. It
+may still be changed dynamically using @code{\set} and returned
+to its (new) default value with @code{\unset}.
+
+@node Adding and removing engravers
+@subsection Adding and removing engravers
+
+@cindex Engravers, adding
+@cindex Engravers, removing
+
+@funindex \consists
+@funindex \remove
+
+We have seen that contexts each contain several engravers, each
+of which is responsible for producing a particular part of the
+output, like bar lines, staves, note heads, stems, etc. If an
+engraver is removed from a context it can no longer produce its
+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 Staff_symbol_engraver.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff \with {
+ \remove Staff_symbol_engraver
+}
+\relative c' {
+ c4
+ \set fontSize = #-4 % make note heads smaller
+ d e
+ \set fontSize = #2.5 % make note heads larger
+ f g
+ \unset fontSize % return to original size
+ a b
}
@end lilypond
-TODO... add more info? Fluff up the first sentence?
+@cindex ambitus engraver
+
+Engravers can also be added to individual contexts.
+The command to do this is
+@code{\consists @emph{Engraver_name}},
+
+placed inside a @code{\with} block. Some vocal scores
+have an @rglos{ambitus} placed at the beginning of a
+staff to indicate the range of notes in that staff.
+The ambitus is produced by the @code{Ambitus_engraver},
+which is not normally included in any context. If
+we add it to the @code{Voice} context it calculates
+the range from that voice only:
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff <<
+ \new Voice \with {
+ \consists Ambitus_engraver
+ }
+ \relative c'' {
+ \voiceOne
+ c a b g
+ }
+ \new Voice
+ \relative c' {
+ \voiceTwo
+ c 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 c'' {
+ \voiceOne
+ c a b g
+ }
+ \new Voice
+ \relative c' {
+ \voiceTwo
+ c e d f
+ }
+>>
+@end lilypond
+
+@subsubheading Changing all contexts of the same type
+
+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 ambiti for every
+staff in a four-staff score we could write
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+ <<
+ \new Staff <<
+ \relative c'' { c a b g }
+ >>
+ \new Staff <<
+ \relative c' { c a b g }
+ >>
+ \new Staff <<
+ \clef "G_8"
+ \relative c' { c a b g }
+ >>
+ \new Staff <<
+ \clef "bass"
+ \relative c { c a b g }
+ >>
+ >>
+ \layout {
+ \context {
+ \Staff
+ \consists Ambitus_engraver
+ }
+ }
+}
+@end lilypond
+
+@noindent
+The default 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.
@node Extending the templates
@section Extending the templates
-You've read the tutorial, you know how to write music. But how can you
-get the staves that you want? The templates are ok, but what if you
-want something that isn't covered?
+You've read the tutorial, you know how to write music, you
+understand the fundamental concepts. But how can you
+get the staves that you want? Well, you can find lots of
+templates (see @ref{Templates}) which may give you a start.
+But what
+if you want something that isn't covered there? Read on.
+
+TODO Add links to templates after they have been moved to LSR
@menu
* Soprano and cello::
soprano part).
@example
-\version "2.11.23"
+\version @w{"@version{}"}
melody = \relative c' @{
\clef treble
\key c \major
\time 4/4
-
a4 b c d
@}
Now we want to add a cello part. Let's look at the @q{Notes only} example:
@example
-\version "2.11.23"
+\version @w{"@version{}"}
melody = \relative c' @{
\clef treble
\key c \major
\time 4/4
-
a4 b c d
@}
@}
@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} sections. So let's rename them. 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 c' @{ } part) and the name's use (in the
+We don't need two @code{\version} commands. We'll need the
+@code{melody} section. We don't want two @code{\score} sections
+-- if we had two @code{\score}s, we'd get the two parts separately.
+We want them together, as a duet. Within the @code{\score}
+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 c' @{ } part) and the name's use (in the
@code{\score} section).
-While we're doing this, let's change the cello part's staff -- celli
-normally use bass clef. We'll also give the cello some different
-notes.
+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 "2.11.23"
+\version @w{"@version{}"}
sopranoMusic = \relative c' @{
\clef treble
\key c \major
\time 4/4
-
a4 b c d
@}
\clef bass
\key c \major
\time 4/4
-
d4 g fis8 e d4
@}
@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, @code{Staff}) happening at once. The
-@code{\score} looks like this now
+more than one thing (in this case, two @code{Staves}) happening
+at once. The @code{\score} looks like this now
@c Indentation in this example is deliberately poor
@example
easily fixed. Here's the complete soprano and cello template.
@lilypond[quote,verbatim,ragged-right]
-\version "2.11.23"
+\version "2.11.38"
sopranoMusic = \relative c' {
\clef treble
\key c \major
\time 4/4
-
a4 b c d
}
\clef bass
\key c \major
\time 4/4
-
d4 g fis8 e d4
}
@node Four-part SATB vocal score
@subsection Four-part SATB vocal score
-Most vocal scores of music written for four-part mixed choir
+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
@c The following should appear as music without code
@lilypond[quote,ragged-right]
-\version "2.11.23"
global = { \key d \major \time 4/4 }
sopMusic = \relative c'' {
\clef "treble"
}
altoMusic = \relative a' {
\clef "treble"
- r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
+ r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
}
altoWords = \sopWords
tenorMusic = \relative c' {
None of the templates provides this layout exactly. The
nearest is @q{SATB vocal score and automatic piano reduction},
-but we shall need to change the layout and add a piano
+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
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 can be removed.
+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 has also been simplified
-as we have not yet encountered the method used in the template.
-We've also added the names of each staff.
+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:
for the three bars of the example above gives:
@lilypond[quote,verbatim,ragged-right]
-\version "2.11.23"
+\version "2.11.38"
global = { \key d \major \time 4/4 }
sopMusic = \relative c'' {
\clef "treble"
prelude as an example.
We begin with a header section. Here go the title, name
-of composer, etc followed by the variable definitions
-and ending with the score block. Let's start with these and
-fill in the details later.
+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 set in two
-manuals and pedal organ. The top manual has two voices,
+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 "2.11.23"
+\version @w{"@version{}"}
\header @{
title = "Jesu, meine Freude"
composer = "J S Bach"
>>
@end example
-It is not strictly necessary to use the simultaneous contruct
+It is not strictly necessary to use the simultaneous construct
@code{<< >>} for the manual two staff and the pedal organ staff,
since they contain only one music expression, but it does no harm
and always using angle brackets after @code{\new Staff} is a good
is to add the music, and combine all the parts together.
@lilypond[quote,verbatim,ragged-right]
-\version "2.11.23"
+\version "2.11.38"
\header {
title = "Jesu, meine Freude"
composer = "J S Bach"
} % end Score context
@end lilypond
-@node Scores and parts
-@section Scores and parts
-
-TODO: this is really old stuff from the really old tutorial.
-Rewrite, fix, etc. Or maybe delete entirely. -gp
-Include section on tags -td
-and then move to section 5. Working ... -td
-
-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 c @{
- \time 2/4
- r4 f8 a cis4 f e 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 c {
- \time 2/4
- r4 f8 a cis4 f e 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-rests
-must be condensed. This is done by setting a run-time variable
-@example
-\set Score.skipBars = ##t
-@end example
-@noindent
-This command sets the property @code{skipBars} in the
-@code{Score} context to true (@code{##t}). Prepending the rest and
-this option to the music above, leads to the following result
-
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- \set Score.skipBars = ##t
- R2*3
- r4 f8 a cis4 f e 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 c <<
- \new Staff {
- \time 2/4 R2*3
- r4 f8 a cis4 f e d
- }
- \new Staff {
- \clef bass
- r4 d,8 f | gis4 c | b bes |
- a8 e f4 | g d | gis f
- }
->>
-@end lilypond
projects / lilypond.git / blobdiff