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

@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::
* Drum rolls::
* Pitched percussion::
* Percussion staves::
* Custom percussion staves::
* Ghost notes::
@end menu

@node References for percussion
@unnumberedsubsubsec References for percussion

@c TODO add more references.

@itemize

@item Some percussion may be notated on a rhythmic staff; this is
discussed in @ref{Showing melody rhythms}, and
@ref{Instantiating new staves}.

@item MIDI output is discussed in a separate section; please see
@ref{Creating MIDI output}.

@end itemize

@seealso
Notation Reference:
@ref{Showing melody rhythms},
@ref{Instantiating new staves}.
@ref{Creating MIDI output}.

Snippets:
@rlsr{Percussion}.


@node Basic percussion notation
@unnumberedsubsubsec Basic percussion notation

@cindex percussion
@cindex drum

@funindex \drummode
@funindex \drums

Percussion notes may be entered in @code{\drummode} mode, which is
similar to the standard mode for entering notes.  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,verbatim]
\drums {
  hihat4 hh bassdrum bd
}
@end lilypond

This is shorthand for:

@lilypond[quote,verbatim]
\new DrumStaff \drummode {
  hihat4 hh bassdrum bd
}
@end lilypond

Each piece of percussion has a full name and an abbreviated name,
and both can be used in input files.  The full list of percussion
note names may be found in @ref{Percussion notes}.

@cindex clef, percussion
@cindex percussion clef

Note that the normal notation of pitches (such as @code{cis4}) in a
@code{DrumStaff} context will cause an error message.  Percussion clefs
are added automatically to a @code{DrumStaff} context but they can also
be set explicitly.  Other clefs may be used as well.

@lilypond[quote,ragged-right,verbatim]
\drums {
  \clef percussion
  bd4 4 4 4
  \clef treble
  hh4 4 4 4
}
@end lilypond


There are a few issues concerning MIDI support for percussion
instruments; for details please see @ref{Creating MIDI output}.

@seealso
Notation Reference:
@ref{Creating MIDI output},
@ref{Percussion notes}.

Installed Files:
@file{ly/drumpitch-init.ly}.

Snippets:
@rlsr{Percussion}.


@node Drum rolls
@unnumberedsubsubsec Drum rolls

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,
as described in @ref{Tremolo repeats}.

@lilypond[quote,verbatim]
\drums {
  \time 2/4
  sn16 8 16 8 8:32 ~
  8 8 4:32 ~
  4 8 16 16
  4 r4
}
@end lilypond

Sticking can be indicated by placing a markup for @code{"R"}
or @code{"L"} above or below notes, as discussed in
@ref{Direction and placement}.  The @code{staff-padding} property
may be overridden to achieve a pleasing baseline.

@lilypond[quote,verbatim]
\drums {
  \repeat unfold 2 {
    sn16^"L" 16^"R" 16^"L" 16^"L" 16^"R" 16^"L" 16^"R" 16^"R"
    \stemUp
    sn16_"L" 16_"R" 16_"L" 16_"L" 16_"R" 16_"L" 16_"R" 16_"R"
  }
}
@end lilypond

@seealso
Notation Reference:
@ref{Tremolo repeats}.

Snippets:
@rlsr{Percussion}.


@node Pitched percussion
@unnumberedsubsubsec Pitched percussion

Certain pitched percussion instruments (e.g., xylophone,
vibraphone, and timpani) are written using normal staves.
This is covered in other sections of the manual.

@seealso
Notation Reference:
@ref{Creating MIDI output}.

Snippets:
@rlsr{Percussion}.


@node Percussion staves
@unnumberedsubsubsec Percussion staves

@cindex percussion
@cindex drum

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 @code{DrumStaff} and @code{DrumVoice} context.

@lilypond[quote,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.
For example,

@lilypond[quote,verbatim]
\new DrumStaff <<
  \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 @code{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"
       \hide Stem
       \override Stem.Y-extent = ##f
     } \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.  For
example, to get toms on the three middle lines you use
@code{tommh}, @code{tomml}, and @code{tomfh}.

@item agostini-drums-style
Invented by the French percussionist Dante Agostini in 1965, this notation is
commonly employed in France but also elsewhere.

@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"
       \hide Stem
       \override Stem.Y-extent = ##f
       drumStyleTable = #agostini-drums-style
     } \mus
     \new Lyrics \nam
  >>
  \layout {
    \context {
      \Score
      \override LyricText.font-family = #'typewriter
      \override BarNumber.transparent =##T
    }
  }
}
@end lilypond

@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"
    \hide Stem
    \override Stem.Y-extent = ##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
    \hide Stem
    \override Stem.Y-extent = ##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
    \hide Stem
    \override Stem.Y-extent = ##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"
    \hide Stem
    \override Stem.Y-extent = ##f
  } \mus
  \new Lyrics {
    \override LyricText.font-family = #'typewriter
    \nam
  }
>>
@end lilypond
@end table

Custom percussion styles may also be defined,
as explained in @ref{Custom percussion staves}.

@seealso
Learning Manual:
@rlearning{I'm hearing Voices}.

Notation Reference:
@ref{Custom percussion staves}.

Installed Files:
@file{ly/drumpitch-init.ly}.

Snippets:
@rlsr{Percussion}.


@node Custom percussion staves
@unnumberedsubsubsec Custom percussion staves

@cindex percussion, custom
@funindex drumStyleTable

Custom percussion styles may be defined, to which the
@code{drumStyleTable} property may then be set.
Existing notations may be redefined as an association list
where each entry has to be comprised of four items:
a name, the note head style (or @code{default}), an
articulation sign if needed (or @code{#f} if not), and
the note head’s position on the staff.  That list must then
be converted into a Scheme hash table, using the
@code{alist->hash-table} function.

@lilypond[quote,verbatim]
#(define mydrums '(
         (bassdrum        default   #f           -1)
         (snare           default   #f           0)
         (hihat           cross     #f           1)
         (halfopenhihat   cross     "halfopen"   1)
         (pedalhihat      xcircle   "stopped"    2)
         (lowtom          diamond   #f           3)))

up = \drummode { hh8 hh hhho hhho 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

@funindex drumPitchNames

New names may also be added to these custom notations through
the @code{drumPitchNames} variable, that may be redefined as
an association list (or augmented by @code{append}ing a new list
to its existing value, as demonstrated below), but also through
its individual entries.  This also makes it possible to define
aliases: alternate input shorthand for some notations.

@lilypond[quote,verbatim]
drumPitchNames =
  #(append
    '((leftsnap . sidestick)
      (rightsnap . ridecymbal))
    drumPitchNames)

drumPitchNames.ls = #'sidestick
drumPitchNames.rs = #'ridecymbal

\drums {
  leftsnap4. rightsnap8 leftsnap4 rightsnap
  ls8 rs ls rs ls4 rs
}
@end lilypond

@funindex midiDrumPitches
@funindex drumPitchTable

In a similar manner, the @code{drumPitchTable} property
associates a specific pitch (meaning a different instrument
sound, as provided by available MIDI soundfonts) to each
notation.  That property needs to be defined as a hash table,
which is again converted from an association list (stored by
default as the @code{midiDrumPitches} variable).  Redefining
these associations is achieved as explained above, either by
defining an entire association list or through individual entries.
The following example demonstrates how to create a whole
notation set with its own input syntax, custom notations and
corresponding MIDI output.

@lilypond[quote,verbatim]
drumPitchNames.dbass      = #'dbass
drumPitchNames.dba        = #'dbass  % 'db is in use already
drumPitchNames.dbassmute  = #'dbassmute
drumPitchNames.dbm        = #'dbassmute
drumPitchNames.do         = #'dopen
drumPitchNames.dopenmute  = #'dopenmute
drumPitchNames.dom        = #'dopenmute
drumPitchNames.dslap      = #'dslap
drumPitchNames.ds         = #'dslap
drumPitchNames.dslapmute  = #'dslapmute
drumPitchNames.dsm        = #'dslapmute

#(define djembe-style
  '((dbass      default  #f         -2)
    (dbassmute  default  "stopped"  -2)
    (dopen      default  #f          0)
    (dopenmute  default  "stopped"   0)
    (dslap      default  #f          2)
    (dslapmute  default  "stopped"   2)))

midiDrumPitches.dbass     = g
midiDrumPitches.dbassmute = fis
midiDrumPitches.dopen     = a
midiDrumPitches.dopenmute = gis
midiDrumPitches.dslap     = b
midiDrumPitches.dslapmute = ais

test = \drummode { dba4 do ds dbm dom dsm }

\score {
  \new DrumStaff \with {
    \override StaffSymbol.line-count = #3
    instrumentName = "Djembé "
    drumStyleTable = #(alist->hash-table djembe-style)
    drumPitchTable = #(alist->hash-table midiDrumPitches)
  } {
    \time 3/4
    \test
  }
  \layout {}
  \midi {}
}
@end lilypond

@seealso
Installed Files:
@file{ly/drumpitch-init.ly}.

Snippets:
@rlsr{Percussion}.

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


@node Ghost notes
@unnumberedsubsubsec Ghost notes

@cindex ghost note, percussion
@cindex dead note, percussion
@cindex muted note, percussion
@cindex silenced note, percussion
@cindex false note, percussion
@cindex percussion, ghost note
@cindex percussion, dead note
@cindex percussion, muted note
@cindex percussion, silenced note
@cindex percussion, false note

Also known as dead, muted, silenced or false notes; ghost notes can be
created using the @code{\parenthesize} command, see @ref{Parentheses}.

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

@seealso
Notation Reference:
@ref{Parentheses}.

Snippets:
@rlsr{Percussion}.
