Update from Andrew.

[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.38"

@c Andrew's TODO List
@c references - started
@c piano staff - deleted, material moved to 'references'
@c manual changes - started
@c automatic changes
@c staff-chagne lines
@c cross-staff stems
@c pedals
@c discant symbols

@node Keyboard instruments
@section Keyboard instruments

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

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

@menu
* References for keyboards::
* The piano staff::
* 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 can be written in parallel with @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 Arpeggios can be placed across multiple voices and staves with
@ref{Arpeggios}.
@item Tremelo marks are created with @ref{Tremelo 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

@snippets
@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
@c {creating-slurs-across-voices.ly}

@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{Arpeggios},
@ref{Tremelo repeats},
@ref{List of articulations}.

Internals Reference:
@rinternals{PianoStaff}.

Snippets:
@rlsr{Keyboards}.

@knownissues
Dynamics are not centered, but workarounds do exist.  See the
@q{piano centered dynamics} template in @rlearning{Piano templates}.

@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 automatic staff changes
@cindex staff changes, automatic

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

@quotation
@example
\autochange @dots{}@var{music}@dots{}
@end example
@end quotation

@noindent
This will create two staves inside the current PianoStaff, called
@code{up} and @code{down}.  The lower staff will be in bass clef by
default.

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

@quotation
@example
\autochange \relative @dots{} @dots{}
@end example
@end quotation


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.  Here is a practical example

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


@seealso

Notation Reference: @ref{Changing staff manually}.

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.


@code{\autochange} cannot be inside @code{\times}.

@node Staff-change lines
@subsubsection Staff-change lines


@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.  This is switched on by setting
@code{followVoice} to true

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

@seealso

Internals Reference: @rinternals{VoiceFollower}.

@predefined

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

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

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]
stemExtend = {
  \once \override Stem #'length = #10
  \once \override Stem #'cross-staff = ##t
}
noFlag = \once \override Stem #'flag-style = #'no-flag
\new PianoStaff <<
  \new Staff {
    \stemDown \stemExtend
    f'4
    \stemExtend \noFlag
    f'8
  }
  \new Staff {
    \clef bass
    a4 a8
  }
>>
@end lilypond

@node Piano
@subsection Piano

@menu
* Piano pedals::
@end menu

@node Piano pedals
@subsubsection Piano pedals
@cindex Pedals

Pianos have pedals that alter the way sound is produced.  Generally, a
piano has three pedals, sustain, una corda, and sostenuto.


Piano pedal instruction can be expressed by attaching
@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
note or chord

@lilypond[quote,ragged-right,fragment,verbatim]
c'4\sustainDown c'4\sustainUp
@end lilypond

What is printed can be modified by setting @code{pedal@var{X}Strings},
where @var{X} is one of the pedal types: @code{Sustain},
@code{Sostenuto} or @code{UnaCorda}.  Refer to
@rinternals{SustainPedal} in the program reference for more
information.

Pedals can also be indicated by a sequence of brackets, by setting the
@code{pedalSustainStyle} property to bracket objects

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\set Staff.pedalSustainStyle = #'bracket
c\sustainDown d e
b\sustainUp\sustainDown
b g \sustainUp a \sustainDown \bar "|."
@end lilypond

A third style of pedal notation is a mixture of text and brackets,
obtained by setting the @code{pedalSustainStyle} property to
@code{mixed}

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\set Staff.pedalSustainStyle = #'mixed
c\sustainDown d e
b\sustainUp\sustainDown
b g \sustainUp a \sustainDown \bar "|."
@end lilypond

The default @q{*Ped.} style for sustain and damper pedals corresponds to
style @code{#'text}.  The sostenuto pedal uses @code{mixed} style by
default.

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
c\sostenutoDown d e c, f g a\sostenutoUp
@end lilypond

For fine-tuning the appearance of a pedal bracket, the properties
@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
@code{PianoPedalBracket} objects (see
@rinternals{PianoPedalBracket} in the Internals Reference) can be
modified.  For example, the bracket may be extended to the right edge
of the note head

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
c\sostenutoDown d e c, f g a\sostenutoUp
@end lilypond

@noindent
Note that overrides must be placed before the note at which the 
pedal bracket starts.

@c TODO Check relative positions of the sustain pedal and
@c      dynamics are correct (they collided in 2.11.44).
@c      Give example showing this.

@seealso

Notation Reference: @ref{Ties} (laissez vibrer).

@node Accordion
@subsection Accordion

@menu
* Discant symbols::
@end menu

@node Discant symbols
@subsubsection Discant symbols

@c TODO Add text from -user and lsr 194
TBC