@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
* Percussion sections::         
@end menu

@node Percussion sections
@subsection Percussion sections

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

@menu
* Showing melody rhythms::      
* Entering percussion::         
* Percussion staves::           
* Ghost notes::                 
@end menu


@node Showing melody rhythms
@subsubsection Showing melody rhythms

Sometimes you might want to show only the rhythm of a melody.  This
can be done with the rhythmic staff.  All pitches of notes on such a
staff are squashed, and the staff itself has a single line

@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
\new RhythmicStaff {
  \time 4/4
  c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
}
@end lilypond

@seealso

Internals Reference: @internalsref{RhythmicStaff}.


@node Entering percussion
@subsubsection Entering percussion

@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

@lilypond[quote,ragged-right,verbatim]
\drums {
  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.

@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 seeing 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.



