[lilypond.git] / Documentation / user / percussion.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 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
@subsubsection References for percussion

TODO add more.

@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{Percussion in MIDI}.

@end itemize

@seealso

Notation Reference:
@ref{Showing melody rhythms},
@ref{Instantiating new staves}.
@ref{Percussion in MIDI}.

Snippets: @rlsr{Percussion}.


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

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}
contex, but other clefs may also be used.

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

@seealso

Notation Reference: @ref{Percussion in MIDI}, @ref{Percussion notes}.

File: @file{ly/@/drumpitch@/-init@/.ly}

Snippets: @rlsr{Percussion}.


@node Drum rolls
@subsubsection 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,
@code{:32}, as described in @ref{Tremolo repeats}.  Here is an
example of some snare rolls:

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

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

@seealso

Snippets: @rlsr{Percussion}.


@node Pitched percussion
@subsubsection Pitched percussion

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

@seealso

@c TODO: possibly link to an alternate section of NR 3.5, if
@c "percussion in MIDI" gets a separate subsubsection for
@c pitched percussion sounds.  -gp
Notation Reference: @ref{Percussion in MIDI}.

Snippets: @rlsr{Percussion}.


@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 @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 if the voices are instantiated by hand first.
For example,

@lilypond[quote,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 @code{DrumVoice}.  The
following variables have been predefined:

@c FIXME: decide what to do about this table.  (ie verbatim or not)
@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.  For
example, 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


@node Custom percussion staves
@subsubsection Custom percussion staves

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

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


@snippets

FIXME: MOVE ALL THESE TO LSR!  -gp

Here are some examples:

Two Woodblocks, entered with wbh (high woodblock) and wbl (low woodblock)

@lilypond[quote,verbatim]
#(define mydrums '(
         (hiwoodblock     default   #t        3)
         (lowoodblock       default   #t        -2)))
         %% These lines define the position of the woodblocks in the stave, if You like, You can change it 
         % or You can use  special note heads for the woodblocks.
         woodstaff = { \override Staff.StaffSymbol #'line-positions = #'(-2 3)  
% this defines a staff with only two lines. It also defines the positions of the two lines
         \override Staff.BarLine #'bar-size  = #3 }
         %% this is neccessary. If not entered, the barline wuld be too short!
 
 \new DrumStaff  {
         \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) 
         %% with this You load Your new drum style table
         \woodstaff 
         \drummode {
        \time 2/4
        wbl8 wbl16 wbl wbh 8 -> wbl |
        wbl 8 wbl16  wbh ~ -> wbh wbl 16 r8 |
         }
}
@end lilypond

@seealso

Note that in this special case the length of the barline must
altered with @code{\override Staff.BarLine #'bar-size #number}.
Otherwise it would be too short. And You have also to define the
positions of the to stafflines.  For more information about these
delicate things have a look at @ref{Staff symbol}.


A tambourine, entered with "tamb":

@lilypond[quote,verbatim]
 % tambourine-music is entered with "tamb"
        tambustaff = { \override Staff.StaffSymbol #'line-positions = #'( 0 )   
                \override Staff.BarLine #'bar-size  = #3 
        \set DrumStaff.instrumentName="Tambourine"}
 \new DrumStaff {
         \tambustaff 
% broken
%        \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) 
         \drummode { \time 6/8
                \repeat "unfold" 2 { tamb8. tamb16 tamb8 tamb tamb tamb | }
                tamb4. tamb8 tamb tamb | tamb2.*5/6 \startTrillSpan s8 \stopTrillSpan |
                %% the trick with the scaled duration and the shorter rest is neccessary for the correct ending of the trill-span!
                                 }
                                         }

@end lilypond 
Music for Tam-Tam (entered with "tt"):

@lilypond[quote,verbatim]
 #(define mydrums '(
         (tamtam     default   #t      0) ) )
        tamtamstaff = { \override Staff.StaffSymbol #'line-positions = #'( 0 )   
                \override Staff.BarLine #'bar-size  = #3 
        \set DrumStaff.instrumentName="Tamtam"}
 \new DrumStaff {
         \tamtamstaff
         \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) 
         \drummode { tt 1 \pp \laissezVibrer 
                                 } 
                                         }
@end lilypond

Two different bells, entered with "cb" (cowbell) and "rb" (ridebell)" 

@lilypond[quote,verbatim]
%% bells are enterd with:
% "cb" (cowbell) and "rb" (ridebell)" 
 #(define mydrums '(
         (ridebell     default   #t        3 )
         (cowbell       default   #t        -2)))
        
         bellstaff = { \override DrumStaff.StaffSymbol #'line-positions = #'(-2 3)  
                 \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) 
         \override Staff.BarLine #'bar-size  = #3   
         \set DrumStaff.instrumentName="Different Bells"}
 
 \new DrumStaff  {
         \bellstaff
         \drummode {
        \time 2/4
        \repeat "unfold" 2 { rb 8 rb cb cb16  rb ~ -> | rb16  rb 8 rb 16 cb 8 cb | }
         }
}
@end lilypond

Here an short example by maestro Stravinsky (from "L'hostire du Soldat")

@lilypond[quote,verbatim]
 #(define mydrums '(
          (bassdrum         default #t 4 ) 
         (snare              default #t -4 )
         (tambourine     default   #t      0) ) )
         
 global = { \time 3/8 s 4. \time 2/4 s 2 *2 \time 3/8 s 4. \time 2/4 s 2 }
         
drumsA = { \context DrumVoice << {  \global }
        {\drummode { 
  \autoBeamOff 
\stemDown sn 8 \stemUp tamb s8 |
                 sn4 \stemDown sn4  |
\stemUp tamb 8 \stemDown sn8 \stemUp sn16 \stemDown sn \stemUp sn8   |
\stemDown sn 8 \stemUp tamb s8 |
\stemUp sn4 s8 \stemUp tamb |
        } } >> }
drumsB = { \drummode { s 4 bd 8 s 2*2 s 4 bd8 s 4 bd8 s 8 } }
         
\layout {
                indent = #40
} 

 \score { 
 \new StaffGroup
 <<
 \new DrumStaff 
 {  \set DrumStaff.instrumentName= \markup { \column { "Tambourine" "et" "caisse claire s. timbre" } }
 \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) \drumsA } 
 \new DrumStaff 
 { \set DrumStaff.instrumentName= "Grosse Caisse"
 \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) \drumsB } 
 >> 

 }
@end lilypond

@seealso

Snippets: @rlsr{Percussion}.

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



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

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

@seealso

Snippets: @rlsr{Percussion}.