@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::
@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
Two more commands you have not previously seen are
@code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
shown they will cause LilyPond to produce a printed output and a
-MIDI out respectively. They are described fully in the
-Notation Reference -- @ruser{Score layout} and
+MIDI output respectively. They are described fully in the
+Notation Reference -- @ruser{Score layout} and
@ruser{Creating MIDI files}.
The @code{\book} command allows
the names -- it could be @code{melody}, @code{global},
@code{TimeKey},
@code{pianorighthand}, or @code{foofoobarbaz}. For more details,
-see @ruser{Saving typing with variables and functions}.
+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
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
It is not essential to declare all staves at the beginning;
they may be introduced temporarily at any point. This is
}
@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:
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.
+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
@c attempt to force this onto a new page
@need 50
-@multitable @columnfractions .3 .7
+@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{\( .. \)}
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,
+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
+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
where something starts and ends.
@end lilypond
It is not necessary to use a separate @code{<< \\ >>} construct
-for each bar, but it does help the legibility of the code. TODO
+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
@lilypond[quote,verbatim]
\new Staff \relative c' {
- \voiceOneStyle
+ % Main voice
c16 d e f
<< % Bar 1
- { g4 f e } \\
- {
+ {
+ \voiceOneStyle
+ g4 f e
+ }
+ \\
+ {
\voiceTwoStyle
r8 e4 d c8 ~
}
- >> |
+ >>
<< % Bar 2
- { d2 e2 } \\
- { c8 b16 a b8 g ~ g2 } \\
+ { d2 e2 } % Voice 1 continues
+ \\
+ { c8 b16 a b8 g ~ g2 } % Voice 2 continues
+ \\
{
\voiceThreeStyle
s4 b4 c2
- }
+ }
>>
}
@end lilypond
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.
-TODO: add ref to appropriate section in Tweaks
+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 still calculated
\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
notes of the third 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 ... )
-
-TODO link.
+so we shall leave this problem until a later section
+(see @ref{Fixing overlapping notation} )
@node Explicitly instantiating voices
@subsection Explicitly instantiating voices
markup, ties, slurs, and dynamics:
@lilypond[quote,ragged-right,verbatim]
-\relative c'{
- c-"default" d8 ~ d e4 ( f g a ) b-> c
+\relative c'{
+ % Default behaviour or behaviour after \oneVoice
+ c d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
@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 noteheads 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
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
+the lyrics to the notes with @code{\lyricsto@{@}}, using the
name assigned to the Voice.
@lilypond[quote,verbatim,fragment]
@menu
* Contexts explained::
* Creating contexts::
-* Engravers explained::
-* Modifying context properties::
-* Adding and removing engravers::
+* Engravers explained::
+* Modifying context properties::
+* Adding and removing engravers::
@end menu
@node Contexts explained
@node Engravers explained
@subsection Engravers explained
-cindex engravers
+@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
different clefs and keys.
The @code{Note_heads_engraver} and @code{Stem_engraver} live
-in each @code{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 maintains the properties that relate
@code{\set} command. This takes the form
@example
-\set @emph{ContextName}.@emph{propertyName} = @emph{value}
+\set @emph{ContextName}.@emph{propertyName} = #@emph{value}
@end example
Where the @emph{ContextName} is usually @code{Score},
@c attempt to force this onto a new page
@need 50
-@multitable @columnfractions .2 .2 .6
+@multitable @columnfractions .25 .15 .45 .15
@headitem propertyName
- @tab Value
+ @tab Type
@tab Function
+ @tab Example Value
@item extraNatural
- @tab ##t or ##f
- @tab If true (##t), set extra natural signs before accidentals
+ @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 ##t or ##f
- @tab If true (##t), print slurs both above and below notes
+ @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 Number
+ @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
-@smallspace
+@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 be taken. For example, the
+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,
@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
c4
-\set fontSize = #-4 % make noteheads smaller
+% make noteheads smaller
+\set fontSize = #-4
d e
-\set fontSize = #2.5 % make noteheads larger
+% make noteheads larger
+\set fontSize = #2.5
f g
-\unset fontSize % return to original size
+% return to original size
+\unset fontSize
a b
@end lilypond
@end lilypond
In effect this overrides the default value of the property. It
-may still be changed dynamically using @code{\set} and
-@code{\unset}.
+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
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::
* Four-part SATB vocal score::
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
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.
+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:
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. The top manual part has two voices,
+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:
@end lilypond
+
projects / lilypond.git / blobdiff