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

@node Percussion
@section Percussion

@menu
* Common notation for percussion::
@end menu

@node Common notation for percussion
@subsection Common notation for percussion

Rhythmic music is primarily used for percussion and drum notation, but it can
also be used to show the rhythms of melodies.

@menu
* References for percussion::
* Basic percussion notation::
* Percussion staves::
* Ghost notes::
@end menu

@node References for percussion
@subsubsection References for percussion

@c TODO Add refs
TBC


@seealso

Internals Reference: @internalsref{RhythmicStaff}.


@node Basic percussion notation
@subsubsection Basic percussion notation

@cindex percussion
@cindex drums


Percussion notes may be entered in @code{\drummode} mode, which is
similar to the standard mode for entering notes.  Each piece of
percussion has a full name and an abbreviated name, and both can
be used in input files.  The simplest way to enter percussion notes
is to use the @code{\drums} command, which creates the correct
context and entry mode for percussion:

@lilypond[quote,ragged-right,verbatim]
\drums {
  hihat hh bassdrum bd
}
@end lilypond

This is shorthand for

@lilypond[quote,ragged-right,verbatim]
\new DrumStaff
\drummode {
  hihat hh bassdrum bd
}
@end lilypond


The complete list of drum names is in the init file
@file{ly/@/drumpitch@/-init@/.ly}.
@c TODO: properly document this.

Drum rolls are indicated with three slashes across the stem.
For quarter notes or longer the three slashes are shown explicitly,
eighth notes are shown with two slashes (the beam being the third),
and drum rolls shorter than eighths have one stem slash to
supplement the beams.  This is achieved with the tremolo notation,
@code{:32}, see @ref{Tremolo repeats}.  Here's an example of
some snare rolls:

@lilypond[quote,ragged-right,verbatim]
\new DrumStaff
\drummode {
  \time 2/4
  sn16 sn8 sn16 sn8 sn8:32~ |
  sn8 sn8 sn4:32~ |
  sn4 sn8 sn16 sn16 |
  sn4 r4 |
}
@end lilypond

Sticking can be indicated by placing @code{^"R"} or @code{^"L"}
after the note.  The @code{staff-padding} property may be
overridden to achieve a pleasing baseline.

@c TODO Add example of sticking

@seealso

Internals Reference: @internalsref{note-event}.

@node Percussion staves
@subsubsection Percussion staves
@cindex percussion
@cindex drums

A percussion part for more than one instrument typically uses a
multiline staff where each position in the staff refers to one piece
of percussion.


To typeset the music, the notes must be interpreted in a
@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts

@lilypond[quote,ragged-right,verbatim]
up = \drummode { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
down = \drummode { bassdrum4 snare8 bd r bd sn4 }
  \new DrumStaff <<
    \new DrumVoice { \voiceOne \up }
    \new DrumVoice { \voiceTwo \down }
  >>
@end lilypond

The above example shows verbose polyphonic notation.  The short
polyphonic notation, described in @rlearning{I'm hearing Voices},
can also be used if the @internalsref{DrumVoice}s are instantiated
by hand first.  For example,

@lilypond[quote,ragged-right,fragment,verbatim]
\new DrumStaff <<
  \new DrumVoice = "1" { s1 *2 }
  \new DrumVoice = "2" { s1 *2 }
  \drummode {
    bd4 sn4 bd4 sn4
    <<
      { \repeat unfold 16 hh16 }
      \\
      { bd4 sn4 bd4 sn4 }
    >>
  }
>>
@end lilypond


There are also other layout possibilities.  To use these, set the
property @code{drumStyleTable} in context @internalsref{DrumVoice}.
The following variables have been predefined

@table @code
@item drums-style
This is the default.  It typesets a typical drum kit on a five-line staff

@lilypond[quote,line-width=10.0\cm]
nam = \lyricmode {
  cymc cyms cymr hh hhc hho hhho hhp
  cb hc bd sn ss tomh tommh tomml toml tomfh tomfl }
mus = \drummode {
  cymc cyms cymr hh hhc hho hhho hhp \break
  cb hc bd sn ss tomh tommh tomml toml tomfh tomfl s16 }
\score {
  << \new DrumStaff \with {
       \remove Bar_engraver
       \remove Time_signature_engraver
       \override Stem #'transparent = ##t
       \override Stem #'Y-extent-callback = ##f
       \override VerticalAxisGroup #'minimum-Y-extent = #'(-4.0 . 5.0)
     } \mus
     \new Lyrics \nam
  >>
  \layout {
    \context {
      \Score
      \override LyricText #'font-family = #'typewriter
      \override BarNumber #'transparent =##T
    }
  }
}
@end lilypond

The drum scheme supports six different toms.  When there are fewer toms,
simply select the toms that produce the desired result, i.e., to get toms
on the three middle lines you use @code{tommh}, @code{tomml}, and
@code{tomfh}.

@item timbales-style
This typesets timbales on a two line staff

@lilypond[quote,ragged-right]
nam = \lyricmode { timh ssh timl ssl cb }
mus = \drummode { timh ssh timl ssl cb s16 }

<<
  \new DrumStaff \with {
    \remove Bar_engraver
    \remove Time_signature_engraver
    \override Stem #'transparent = ##t
    \override Stem #'Y-extent-callback = ##f
    \override StaffSymbol #'line-count = #2
    \override StaffSymbol #'staff-space = #2
    \override VerticalAxisGroup #'minimum-Y-extent = #'(-3.0 . 4.0)
    drumStyleTable = #timbales-style
  } \mus
  \new Lyrics {
    \override LyricText #'font-family = #'typewriter
    \nam
  }
>>
@end lilypond

@item congas-style
This typesets congas on a two line staff

@lilypond[quote,ragged-right]
nam = \lyricmode { cgh cgho cghm ssh cgl cglo cglm ssl }
mus = \drummode { cgh cgho cghm ssh cgl cglo cglm ssl s16 }

<<
  \new DrumStaff \with {
    \remove Bar_engraver
    \remove Time_signature_engraver
    drumStyleTable = #congas-style
    \override StaffSymbol #'line-count = #2

    %% this sucks; it will lengthen stems.
    \override StaffSymbol #'staff-space = #2
    \override Stem #'transparent = ##t
    \override Stem #'Y-extent-callback = ##f
  } \mus
  \new Lyrics {
    \override LyricText #'font-family = #'typewriter
    \nam
  }
>>
@end lilypond

@item bongos-style
This typesets bongos on a two line staff

@lilypond[quote,ragged-right]
nam = \lyricmode { boh boho bohm ssh bol bolo bolm ssl }
mus = \drummode { boh boho bohm ssh bol bolo bolm ssl s16 }

<<
  \new DrumStaff \with {
    \remove Bar_engraver
    \remove Time_signature_engraver
    \override StaffSymbol #'line-count = #2
    drumStyleTable = #bongos-style

    %% this sucks; it will lengthen stems.
    \override StaffSymbol #'staff-space = #2
    \override Stem #'transparent = ##t
    \override Stem #'Y-extent-callback = ##f
  } \mus
  \new Lyrics {
    \override LyricText #'font-family = #'typewriter
    \nam
  }
>>
@end lilypond

@item percussion-style
To typeset all kinds of simple percussion on one line staves.

@lilypond[quote,ragged-right]
nam = \lyricmode { tri trio trim gui guis guil cb cl tamb cab mar hc }
mus = \drummode { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }

<<
  \new DrumStaff \with{
    \remove Bar_engraver
    drumStyleTable = #percussion-style
    \override StaffSymbol #'line-count = #1
    \remove Time_signature_engraver
    \override Stem #'transparent = ##t
    \override Stem #'Y-extent-callback = ##f
  } \mus
  \new Lyrics {
    \override LyricText #'font-family = #'typewriter
    \nam
  }
>>
@end lilypond
@end table

If you do not like any of the predefined lists you can define your own
list at the top of your file

@lilypond[quote,ragged-right,verbatim]
#(define mydrums '(
         (bassdrum     default   #f         -1)
         (snare        default   #f         0)
         (hihat        cross     #f         1)
         (pedalhihat   xcircle   "stopped"  2)
         (lowtom       diamond   #f         3)))
up = \drummode { hh8 hh hh hh hhp4 hhp }
down = \drummode { bd4 sn bd toml8 toml }

\new DrumStaff <<
  \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
  \new DrumVoice { \voiceOne \up }
  \new DrumVoice { \voiceTwo \down }
>>
@end lilypond


@seealso

Init files: @file{ly/@/drumpitch@/-init@/.ly}.

Internals Reference: @internalsref{DrumStaff}, @internalsref{DrumVoice}.

@knownissues

Because general MIDI does not contain rim shots, the sidestick is used
for this purpose instead.


@c TODO: check name -gp
@node Ghost notes
@subsubsection Ghost notes

Ghost notes for drums and percussion may be created using the
@code{\parenthesize} command detailed in @ref{Parentheses}.  However,
the default @code{\drummode} does
not include the @code{Parenthesis_engraver} plugin which allows
this.  You
must add the plugin explicitly in the context definition as
detailed in @ref{Changing context properties on the fly}.

@lilypond[quote,ragged-right,verbatim,fragment]
\new DrumStaff \with {
  \consists "Parenthesis_engraver"
} <<
  \context DrumVoice  = "1"  { s1 *2 }
  \context DrumVoice  = "2" { s1 *2 }
  \drummode {
    <<
      {
        hh8[ hh] <hh sn> hh16
        < \parenthesize sn > hh < \parenthesize
        sn > hh8 <hh sn> hh
      } \\ {
        bd4 r4 bd8 bd r8 bd
      }
    >>
  }
>>
@end lilypond

@noindent
Also note that you must add chords (@code{< >} brackets)
around each @code{\parenthesize} statement.