@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.21.0"

@node Keyboard and other multi-staff instruments
@chapter Keyboard and other multi-staff instruments

@lilypondfile[quote]{snippets/keyboard-headword.ly}

This section discusses several aspects of music notation that are
unique to keyboard instruments and other instruments notated on
many staves, such as harps and vibraphones.  For the purposes of
this section this entire group of multi-staff instruments is called
@qq{keyboards} for short, even though some of them do not have a
keyboard.


@node Common notation for keyboards
@section Common notation for keyboards

This section discusses notation issues that may arise for most
keyboard instruments.


@node References for keyboards
@subsection References for keyboards

@cindex piano staff
@cindex staff, piano
@cindex staff, keyboard instruments
@cindex staff, keyed instruments
@cindex keyboard instrument staff
@cindex keyed instrument staff
@cindex keyboard music, centering dynamics
@cindex dynamics, centered in keyboard music
@cindex piano music, centering dynamics
@cindex centered dynamics in piano music

@funindex PianoStaff

Keyboard instruments are usually notated with Piano staves.  These
are two or more normal staves coupled with a brace.  The same
notation is also used for other keyed instruments.
Organ music is normally written with two staves inside a
@code{PianoStaff} group and third, normal staff for the pedals.

The staves in keyboard music are largely independent, but
sometimes voices can cross between the two staves.  This
section discusses notation techniques particular to keyboard
music.

Several common issues in keyboard music are covered elsewhere:

@itemize

@item Keyboard music usually contains multiple voices and the
number of voices may change regularly; this is described in
@ref{Collision resolution}.

@item Keyboard music can be written in parallel, as described in
@ref{Writing music in parallel}.

@item Dynamics may be placed in a @code{Dynamics} context,
between the two @code{Staff} contexts
to align the dynamic marks on a horizontal line
centered between the staves; see @ref{Dynamics}.

@item Fingerings are indicated with @ref{Fingering instructions}.

@item Organ pedal indications are inserted as articulations,
@pxref{Organ pedal marks} and @ref{List of articulations}.

@item Vertical grid lines can be shown with @ref{Grid lines}.

@item Keyboard music often contains @notation{Laissez vibrer} ties
as well as ties on arpeggios and tremolos, described in
@ref{Ties}.

@item Placing arpeggios across multiple voices and staves is
covered in @ref{Arpeggio}.

@item Tremolo marks are described in @ref{Tremolo repeats}.

@item Several of the tweaks that can occur in keyboard music are
demonstrated in @rlearning{Real music example}.

@item Hidden notes can be used to produce ties that cross voices,
as shown in @rlearning{Other uses for tweaks}.

@end itemize

@morerefs
Learning Manual:
@rlearning{Real music example},
@rlearning{Other uses for tweaks}.

Notation Reference:
@ref{Grouping staves},
@ref{Instrument names},
@ref{Collision resolution},
@ref{Writing music in parallel},
@ref{Fingering instructions},
@ref{List of articulations},
@ref{Grid lines},
@ref{Ties},
@ref{Arpeggio},
@ref{Tremolo repeats}.

Internals Reference:
@rinternals{PianoStaff}.

Snippets:
@rlsr{Keyboard and other multi-staff instruments}.
@endmorerefs


@node Changing staff manually
@subsection Changing staff manually

@cindex changing staff manually
@cindex manual staff change
@cindex staff change, manual
@cindex cross-staff note
@cindex note, cross-staff
@cindex cross-staff beam
@cindex beam, cross-staff

@funindex \change

Voices can be switched between staves manually, using the command

@example
\change Staff = @var{staffname}
@end example

@noindent
The string @var{staffname} is the name of the staff.  It switches
the current voice from its current staff to the staff called
@var{staffname}.  Typical values for @var{staffname} are
@code{"up"} and @code{"down"}, or @code{"RH"} and @code{"LH"}.

@cindex empty chord
@cindex chord, empty
@funindex <>

The staff to which the voice is being switched must exist at the
time of the switch.  If necessary, staves should be @qq{kept
alive}, see @ref{Keeping contexts alive}, or explicitly
instantiated, for example by using the empty chord, @code{<>}, see
@ref{Chorded notes}.

@lilypond[verbatim, quote]
\new PianoStaff <<
  \new Staff = "up" {
    % enforce creation of all contexts at this point of time
    <>
    \change Staff = "down" c2
    \change Staff = "up" c'2
  }
  \new Staff = "down" {
    \clef bass
    % keep staff alive
    s1
  }
>>
@end lilypond

Cross-staff notes are beamed automatically:

@lilypond[verbatim,quote]
\new PianoStaff <<
  \new Staff = "up" {
    <e' c'>8
    \change Staff = "down"
    g8 fis g
    \change Staff = "up"
    <g'' c''>8
    \change Staff = "down"
    e8 dis e
    \change Staff = "up"
  }
  \new Staff = "down" {
    \clef bass
    % keep staff alive
    s1
  }
>>
@end lilypond

If the beaming needs to be tweaked, make any changes to the stem
directions first.  The beam positions are then measured from the
center of the staff that is closest to the beam.  For a simple
example of beam tweaking, see @rlearning{Fixing overlapping
notation}.

@cindex cross-staff collision
@cindex collision, cross-staff voices

Overlapping notation can result when voices cross staves:

@lilypond[verbatim,quote]
\new PianoStaff <<
  \new Staff = "up" {
    \voiceOne
    % Make space for fingering in the cross-staff voice
    \once\override DynamicLineSpanner.staff-padding = 4
    e''2\p\< d''\>
    c''1\!
  }
  \new Staff = "down" <<
    {
      \clef bass
      s4. e,8\rest g,2\rest
      c1
    } \\ {
      c8\( g c'
      \change Staff = "up"
      e' g' b'-3 a' g'\)
      f'1
    }
  >>
>>
@end lilypond

The stem and slur overlap the intervening line of dynamics
because automatic collision resolution is suspended for beams, slurs
and other spanners that connect notes on different staves,
as well as for stems and articulations if their placement is
affected by a cross-staff spanner.
The resulting collisions must be resolved manually, where necessary,
using the methods in @rlearning{Fixing overlapping notation}.

@morerefs
Learning Manual:
@rlearning{Fixing overlapping notation}.

Notation Reference:
@ref{Stems},
@ref{Automatic beams},
@ref{Keeping contexts alive}.

Snippets:
@rlsr{Keyboard and other multi-staff instruments}.

Internals Reference:
@rinternals{Beam},
@rinternals{ContextChange}.
@endmorerefs

@knownissues
Beam collision avoidance does not work for automatic beams that end
right before a change in staff.  In this case use manual beams.


@node Changing staff automatically
@subsection Changing staff automatically

@cindex changing staff automatically
@cindex automatic staff change
@cindex staff change, automatic

@funindex \autoChange
@funindex PianoStaff

Voices can be made to switch automatically between the top and the
bottom staff.  The syntax for this is

@example
\autoChange @dots{}@var{music}@dots{}
@end example

@noindent
This will create two staves inside the current staff group
(usually a @code{PianoStaff}), called @code{"up"} and
@code{"down"}.  The lower staff will be in the bass clef by default.
The auto-changer switches on the basis of the pitch (middle@tie{}C is the
turning point), and it looks ahead skipping over rests to switch
in advance.

@lilypond[quote,verbatim]
\new PianoStaff {
  \autoChange {
    g4 a b c'
    d'4 r a g
  }
}
@end lilypond

@noindent
It is possible to specify other pitches for the turning point.
If the staves are not instantiated explicitly, other clefs may be used.

@lilypond[quote,verbatim]
music = {
  g8 b a c' b8 d' c'8 e'
  d'8 r f' g' a'2
}

\autoChange d' \music
\autoChange b \with { \clef soprano } \music
\autoChange d' \with { \clef alto } \with { \clef tenor } \music
@end lilypond

@cindex relative music, and @code{\autoChange}
@cindex @code{\autoChange}, and relative music

@funindex \relative

A @code{\relative} section that is outside of @code{\autoChange}
has no effect on the pitches of the music, so if necessary, put
@code{\relative} inside @code{\autoChange}.

If additional control is needed over the individual staves, they
can be created manually with the names @code{"up"} and
@code{"down"}.  The @code{\autoChange} command will then switch
its voice between the existing staves.

@warning{If staves are created manually, they @emph{must} be named
@code{"up"} and @code{"down"}.}

For example, staves must be created manually in order to place a
key signature in the lower staff:

@lilypond[quote,verbatim]
\new PianoStaff <<
  \new Staff = "up" {
    \new Voice = "melOne" {
      \key g \major
      \autoChange \relative {
        g8 b a c b d c e
        d8 r fis, g a2
      }
    }
  }
  \new Staff = "down" {
    \key g \major
    \clef bass
  }
>>
@end lilypond

@morerefs
Notation Reference:
@ref{Changing staff manually}.

Snippets:
@rlsr{Keyboard and other multi-staff instruments}.
@endmorerefs


@knownissues
@cindex chord, splitting across staves with @code{\autoChange}

The staff switches may not end up in optimal places.  For high
quality output, staff switches should be specified manually.

Chords will not be split across the staves; they will be assigned to a
staff based on the first note named in the chord construct.


@node Staff-change lines
@subsection Staff-change lines

@cindex staff-change line
@cindex cross-staff line
@cindex line, staff-change follower
@cindex line, cross-staff
@cindex line, staff-change
@cindex follow voice
@cindex voice, following
@cindex staff, switching

@funindex followVoice
@funindex \showStaffSwitch
@funindex \hideStaffSwitch

Whenever a voice switches to another staff, a line connecting the
notes can be printed automatically:

@lilypond[quote,verbatim]
\new PianoStaff <<
  \new Staff = "one" {
    \showStaffSwitch
    c'1
    \change Staff = "two"
    b2 a
  }
  \new Staff = "two" {
    \clef bass
    s1*2
  }
>>
@end lilypond

A staff-change line between chords connects the chords' @qq{last notes} as
written in the source file; this can be used to quickly adjust the line's
vertical start and end positions.

@lilypond[quote,verbatim]
\new PianoStaff <<
  \new Staff = "one" {
    <c' e' g'>1
    \showStaffSwitch
    \change Staff = "two"
    <a c' f>1
    \hideStaffSwitch
    \change Staff = "one"
    <e' g' c'>1
    \showStaffSwitch
    \change Staff = "two"
    <f a c'>1
  }
  \new Staff = "two" {
    \clef bass
    s1*4
  }
>>
@end lilypond

@predefined
@code{\showStaffSwitch},
@code{\hideStaffSwitch}.
@endpredefined

@morerefs
Snippets:
@rlsr{Keyboard and other multi-staff instruments}.

Internals Reference:
@rinternals{Note_head_line_engraver},
@rinternals{VoiceFollower}.
@endmorerefs


@snippets

@cindex cross-staff note
@cindex note, cross-staff
@cindex cross-staff stem
@cindex stem, cross-staff
@cindex chord, cross-staff
@cindex cross-staff chord
@funindex \crossStaff
@funindex \autoBeamOff
@funindex Span_stem_engraver
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/cross-staff-stems.ly}

@anchor{Cross-staff chord brackets}
@cindex cross-staff chord bracket
@cindex chord bracket, cross-staff
@cindex bracket, cross-staff
@funindex \nonArpeggiato
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/indicating-cross-staff-chords-with-a-bracket.ly}


@morerefs
Snippets:
@rlsr{Keyboard and other multi-staff instruments}.

Internals Reference:
@rinternals{Stem}.
@endmorerefs


@node Piano
@section Piano

This section discusses notation issues that relate most directly to the
piano.


@node Piano pedals
@subsection Piano pedals

@cindex piano pedal
@cindex pedal, piano
@cindex sustain pedal
@cindex pedal, sustain
@cindex sostenuto pedal
@cindex pedal, sostenuto
@cindex una corda
@cindex tre corde
@cindex sos.
@cindex U.C.

@funindex \sustainOn
@funindex \sustainOff
@funindex \sostenutoOn
@funindex \sostenutoOff
@funindex \unaCorda
@funindex \treCorde

Pianos generally have three pedals that alter the way sound is
produced: @notation{sustain}, @notation{sostenuto}
(@notation{sos.}), and @notation{una corda} (@notation{U.C.}).
Sustain pedals are also found on vibraphones and celestas.

@lilypond[quote,verbatim]
\relative {
  c''4\sustainOn d e g
  <c, f a>1\sustainOff
  c4\sostenutoOn e g c,
  <bes d f>1\sostenutoOff
  c4\unaCorda d e g
  <d fis a>1\treCorde
}
@end lilypond

@cindex pedal indication, style
@cindex pedal indication, text
@cindex pedal indication, bracket
@cindex pedal indication, mixed
@cindex pedal sustain, style
@cindex sustain pedal, style

@funindex pedalSustainStyle

There are three styles of pedal indications: text, bracket, and mixed.
The sustain pedal and the una corda pedal use the text style by default
while the sostenuto pedal uses mixed by default.

@lilypond[quote,verbatim]
\relative {
  c''4\sustainOn g c2\sustainOff
  \set Staff.pedalSustainStyle = #'mixed
  c4\sustainOn g c d
  d\sustainOff\sustainOn g, c2\sustainOff
  \set Staff.pedalSustainStyle = #'bracket
  c4\sustainOn g c d
  d\sustainOff\sustainOn g, c2
  \bar "|."
}
@end lilypond

The placement of the pedal commands matches the physical movement of the
sustain pedal during piano performance.  Pedaling to the final bar line
is indicated by omitting the final pedal off command.

Pedal indications may be placed in a @code{Dynamics} context,
which aligns them on a horizontal line.

@morerefs
Notation Reference:
@ref{Ties}.

Snippets:
@rlsr{Keyboard and other multi-staff instruments}.

Internals Reference:
@rinternals{SustainPedal},
@rinternals{SustainPedalLineSpanner},
@rinternals{SustainEvent},
@rinternals{SostenutoPedal},
@rinternals{SostenutoPedalLineSpanner},
@rinternals{SostenutoEvent},
@rinternals{UnaCordaPedal},
@rinternals{UnaCordaPedalLineSpanner},
@rinternals{UnaCordaEvent},
@rinternals{PianoPedalBracket},
@rinternals{Piano_pedal_engraver}.
@endmorerefs


@node Organ
@section Organ

@cindex organ

This section discusses notation issues that relate to the (church)
organ.


@node Organ pedal marks
@subsection Organ pedal marks

@cindex organ pedal mark
@cindex @q{toe} pedal mark
@cindex @q{heel} pedal mark

@cindex pedal mark, organ
@cindex pedal mark, toe
@cindex pedal mark, heel

@funindex \rtoe
@funindex \ltoe
@funindex \rheel
@funindex \lheel
@funindex toeHeelStyle

Mostly in organ method books you can find marks that indicate how
to use the toe and heel of the left and right foot while playing
the pedal.  Depending on the style of the book, different glyphs
are used for such marks.  In almost all cases, however, the pedal
marks above the staff are for the right foot, and the marks below
the staff are for the left foot.

The main commands to print such marks are @code{\rtoe},
@code{\ltoe}, @code{\rheel}, and @code{\lheel}.  Use
@code{toeHeelStyle} context property to select the pedal mark
style.  Available options are as follows.

@indentedblock
@table @code
@item default
The default at start-up, mainly for backward compatibility.
@item standard
The most common scheme in use today; the shapes are identical
above and below the staff.
@item reversed
The glyph @q{tips} point to the staff.
@item circleheels
Use a circle glyph for the heel.
@item below
This is for the rare cases where the pedal is notated in the same
staff as the left hand, which makes it necessary that marks for
both the left and right foot are below the staff.
@end table
@end indentedblock

@funindex \rtoeheel
@funindex \ltoeheel
@funindex \rheeltoe
@funindex \lheeltoe

For toe-heel and heel-toe substitutions the commands
@code{\rtoeheel}, @code{\ltoeheel}, @code{\rheeltoe}, and
@code{\lheeltoe} are provided.

@lilypond[verbatim,quote]
music = { g'4_\rtoe g'\rheel g'\rtoeheel g'\rheeltoe |
          e'4\ltoe e'\lheel e'\ltoeheel e'\lheeltoe \bar "||" }

{
  \music            % #'default
  \set toeHeelStyle = #'standard \music
  \set toeHeelStyle = #'reversed \music
  \set toeHeelStyle = #'circleheels \music
  \set toeHeelStyle = #'below \music
}
@end lilypond

@code{\rtoe} and siblings look similar to other articulation
commands like @code{\flageolet} or @code{\prall}, and they are
indeed @code{Script} grobs.  However, they ignore direction
changes (i.e., @samp{^}, @samp{_}, and @code{\tweak direction} are
ignored).  This is due to the @code{Toe_heel_engraver}, which is
enabled by default.  The idea behind this decision is separation
of content and representation, letting a style control the
position of the marks.

@funindex \toe
@funindex \vartoe
@funindex \heel
@funindex \varheel
@funindex \heelcircle

If the need arises to position pedal marks individually above or
below the staff, use the standard articulation commands
@code{\toe}, @code{\vartoe}, @code{\heel}, @code{\varheel}, and
@code{\heelcircle}.

@lilypond[verbatim,quote]
{
  f'2\toe f'2\vartoe |
  f'2\heel f'2\varheel |
  f'1\heelcircle
}
@end lilypond


@node Accordion
@section Accordion

@cindex accordion

This section discusses notation that is unique to the accordion.


@node Discant symbols
@subsection Discant symbols

@cindex accordion discant symbol
@cindex discant symbol, accordion
@cindex accordion shift symbol
@cindex shift symbol, accordion
@cindex accordion register symbol
@cindex register symbol, accordion

Accordions are often built with more than one set of reeds that may be
in unison with, an octave above, or an octave below the written pitch.
Each accordion maker has different names for the @notation{shifts} that
select the various reed combinations, such as @notation{oboe},
@notation{musette}, or @notation{bandonium}, so a system of symbols has
come into use to simplify the performance instructions.

A complete list of all available accordion registers can be found in
@ref{Accordion registers}.


@snippets

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/accordion-register-symbols.ly}


@morerefs
Snippets:
@rlsr{Keyboard and other multi-staff instruments}.
@endmorerefs


@node Harp
@section Harp

This section discusses notation issues that are unique to the harp.


@node References for harps
@subsection References for harps
@cindex harp
@cindex bisbigliando

Some common characteristics of harp music are covered elsewhere:

@itemize

@item The glissando is the most characteristic harp technique,
@ref{Glissando}.

@item A @notation{bisbigliando} is written as a tremolo @ref{Tremolo
repeats}.

@item Natural harmonics are covered under @ref{Harmonics}.

@item For directional arpeggios and non-arpeggios, see @ref{Arpeggio}.

@end itemize

@morerefs
Notation Reference:
@ref{Tremolo repeats},
@ref{Glissando},
@ref{Arpeggio},
@ref{Harmonics}.
@endmorerefs


@node Harp pedals
@subsection Harp pedals

@cindex harp, pedal
@cindex harp, pedal diagram
@cindex pedal, harp
@cindex pedal diagram, harp

Harps have seven strings per octave that may be sounded at the natural,
flattened, or sharpened pitch.  In lever harps, each string is adjusted
individually, but in pedal harps every string with the same pitch name
is controlled by a single pedal.  From the player's left to right, the
pedals are D, C, and B on the left and E, F, G, and A on the right.
The position of the pedals may be indicated with text marks:

@lilypond[quote,verbatim,fragment]
\textLengthOn
cis''1_\markup \concat \vcenter {
  [D \flat C \sharp B|E \sharp F \sharp G A \flat] }
c''!1_\markup \concat \vcenter {
  [ C \natural ] }
@end lilypond

@funindex \harp-pedal

or pedal diagrams:

@lilypond[quote,verbatim,fragment]
\textLengthOn
cis''1_\markup { \harp-pedal "^v-|vv-^" }
c''!1_\markup { \harp-pedal "^o--|vv-^" }
@end lilypond

The @code{\harp-pedal} command accepts a string of characters, where
@code{^} is the highest pedal position (flattened pitch), @code{-} is
the middle pedal position (natural pitch), @code{v} is the lowest pedal
position (sharpened pitch), and @code{|} is the divider.  A prefixed
@code{o} will circle the following pedal symbol.

@morerefs
Notation Reference:
@ref{Text scripts},
@ref{Instrument-specific markup}.
@endmorerefs
