Change predefines for arpeggio, sustain, and sostenuto; convert-ly on docs

[lilypond.git] / Documentation / user / keyboards.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.11.51"

@node Keyboard instruments
@section Keyboard instruments

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

This section discusses several aspects of music notation that are unique
to keyboard instruments.

@menu
* Common notation for keyboards::
* Piano::
* Accordion::
@end menu

@node Common notation for keyboards
@subsection Common notation for keyboards

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

@menu
* References for keyboards::
* Changing staff manually::
* Changing staff automatically::
* Staff-change lines::
* Cross-staff stems::
@end menu

@node References for keyboards
@subsubsection References for keyboards

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 harps and 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.  In this
section we discuss some 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 Fingerings are indicated with @ref{Fingering instructions}.

@item Organ pedal indications are inserted as articulations, see
@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 tremelos, 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

@seealso

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

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

Internals Reference:
@rinternals{PianoStaff}.

Snippets:
@rlsr{Keyboards}.

@knownissues

Dynamics are not automatically centered, but workarounds do exist.  One
option is the @q{piano centered dynamics} template under
@rlearning{Piano templates}; another option is to increase the
@code{staff-padding} of dynamics as discussed in @rlearning{Moving
objects}.

@node Changing staff manually
@subsubsection Changing staff manually

@cindex changing staff manually
@cindex manual staff changes
@cindex staff changes, manual
@cindex cross-staff notes
@cindex notes, cross-staff
@cindex cross-staff beams
@cindex beams, 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"}.

Cross-staff notes are beamed automatically:

@lilypond[verbatim,quote,ragged-right]
\new PianoStaff <<
  \new Staff = "up" {
    <e' c'>8
    \change Staff = down
    g fis g
    \change Staff = up
    <g'' c''>8
    \change Staff = down
    e dis e
    \change Staff = up
  }
  \new Staff = "down" {
    \clef bass
    s1 % keep staff alive
  }
>>
@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}.

@seealso

Learning Manual:
@rlearning{Fixing overlapping notation}.

Notation Reference:
@ruser{Stems},
@ruser{Automatic beams}.

Snippets:
@rlsr{Keyboards}.

Internals Reference:
@rinternals{Beam}.


@node Changing staff automatically
@subsubsection Changing staff automatically

@cindex changing staff automatically
@cindex automatic staff changes
@cindex staff changes, automatic
@funindex \autochange

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 bass clef by default.
The autochanger switches on basis of the pitch (middle C is the
turning point), and it looks ahead skipping over rests to switch
in advance.

@lilypond[quote,verbatim,ragged-right]
\new PianoStaff {
  \autochange {
    g4 a b c' d' r4 a g
  }
}
@end lilypond

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.  For example, this is
necessary to place a key signature in the lower staff:

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

@seealso

Notation Reference:
@ref{Changing staff manually}.

Snippets:
@rlsr{Keyboards}.

Internals Reference:
@rinternals{AutoChangeMusic}.

@knownissues

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
@subsubsection Staff-change lines

@cindex staff-change lines
@cindex cross-staff lines
@cindex lines, staff-change follower
@cindex follow voice
@cindex staff switching
@cindex cross-staff
@funindex followVoice

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

@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
\new PianoStaff <<
  \new Staff = "one" {
    \showStaffSwitch
    c1
    \change Staff=two
    b2 a
  }
  \new Staff = "two" { \clef bass s1*2 }
>>
@end lilypond

@predefined

@funindex \showStaffSwitch
@funindex \hideStaffSwitch
@code{\showStaffSwitch}, @code{\hideStaffSwitch}.

@seealso

Snippets:
@rlsr{Keyboards}.

Internals Reference:
@rinternals{VoiceFollower}.


@node Cross-staff stems
@subsubsection Cross-staff stems

@cindex cross-staff notes
@cindex notes, cross-staff
@cindex cross-staff stems
@cindex stems, cross-staff

Chords that cross staves may be produced by increasing the length
of the stem in the lower staff, so it reaches the stem in the upper
staff, or vice versa.

@lilypond[ragged-right,verbatim,quote]
\new PianoStaff <<
  \new Staff \relative c' {
    f8 e4 d8 <f bes,>2
  }
  \new Staff \relative c' {
    << {
      \clef bass
      \stemUp
      \override Stem #'length = #12
      \override Stem #'cross-staff = ##t
      \override Stem #'flag-style = #'no-flag
      a8 g4 f8
    } \\
    { f,2 d' }
    >>
  }
>>
@end lilypond

@snippets
@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
{indicating-cross-staff-chords-with-arpeggio-bracket.ly}

@seealso

Snippets:
@rlsr{Keyboards}.

Internals Reference:
@rinternals{Stem}

@node Piano
@subsection Piano

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

@menu
* Piano pedals::
@end menu

@node Piano pedals
@subsubsection Piano pedals
@cindex piano pedals
@cindex pedals, piano
@cindex sustain pedal
@cindex sostenuto pedal
@cindex una corde
@cindex tre corde
@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 corde} (@notation{U.C.}).
Sustain pedals are also found on vibraphones and celestas.

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
c4\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

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,ragged-right,fragment,verbatim,relative=2]
c4\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.  Pedalling to the final bar line
is indicated by omitting the final pedal up command.

@seealso

Notation Reference:
@ref{Ties}.

Snippets:
@rlsr{Keyboards}.

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

@node Accordion
@subsection Accordion

This section discusses notation that is unique to the accordion.

@menu
* Discant symbols::
@end menu

@node Discant symbols
@subsubsection Discant symbols
@cindex accordion discant symbols
@cindex discant symbols, accordion
@cindex accordion shifts

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.

@snippets

@c This snippet should work once it's been tagged for the docs.
@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
@c {accordion-discant-symbols.ly}

@seealso

Snippets:
@rlsr{Keyboards}.