Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## ddf.minim.analysis
Class BeatDetect

    java.lang.Object
      ddf.minim.analysis.BeatDetect

    public class BeatDetect

extends java.lang.Object

The BeatDetect class allows you to analyze an audio stream for beats (rhythmic onsets). Beat Detection Algorithms by Fr�d�ric Patin describes beats in the following way:

> The human listening system determines the rhythm of music by detecting a pseudo � periodical succession of beats. The signal which is intercepted by the ear contains a certain energy, this energy is converted into an electrical signal which the brain interprets. Obviously, The more energy the sound transports, the louder the sound will seem. But a sound will be heard as a beat only if his energy is largely superior to the sound's energy history, that is to say if the brain detects a brutal variation in sound energy. Therefore if the ear intercepts a monotonous sound with sometimes big energy peaks it will detect beats, however, if you play a continuous loud sound you will not perceive any beats. Thus, the beats are big variations of sound energy.

In fact, the two algorithms in this class are based on two algorithms described in that paper.

To use this class, inside of `draw()` you must first call `detect()`, passing the `AudioBuffer` you want to analyze. You may then use the `isXXX` functions to find out what beats have occurred in that frame. For example, you might use `isKick()` to cause a circle to pulse.

BeatDetect has two modes: sound energy tracking and frequency energy tracking. In sound energy mode, the level of the buffer, as returned by `level()`, is used as the instant energy in each frame. Beats, then, are spikes in this value, relative to the previous one second of sound. In frequency energy mode, the same process is used but instead of tracking the level of the buffer, an FFT is used to obtain a spectrum, which is then divided into average bands using `logAverages()`, and each of these bands is tracked individually. The result is that it is possible to track sounds that occur in different parts of the frequency spectrum independently (like the kick drum and snare drum).

In sound energy mode you use `isOnset()` to query the algorithm and in frequency energy mode you use `isOnset(int i)`, `isKick()`, `isSnare()`, and `isRange()` to query particular frequnecy bands or ranges of frequency bands. It should be noted that `isKick()`, `isSnare()`, and `isHat()` merely call `isRange()` with values determined by testing the algorithm against music with a heavy beat and they may not be appropriate for all kinds of music. If you find they are performing poorly with your music, you should use `isRange()` directly to locate the bands that provide the most meaningful information for you.

Author:
  Damien Di Fede

Field Summary
`static int` | `FREQ_ENERGY` Constant used to request frequency energy tracking mode.
`static int` | `SOUND_ENERGY` Constant used to request sound energy tracking mode.

Constructor Summary
`BeatDetect()` Create a BeatDetect object that is in SOUND_ENERGY mode.
`BeatDetect(int timeSize, float sampleRate)` Create a BeatDetect object that is in FREQ_ENERGY mode and expects a sample buffer with the requested attributes.

Method Summary
`void` | `detect(AudioBuffer ab)` Analyze the samples in `ab`.
`void` | `detect(float[] buffer)` Analyze the samples in `buffer`.
`void` | `detectMode(int algo)` Set the object to use the requested algorithm.
`void` | `drawGraph(processing.core.PApplet p)` Draws some debugging visuals in the passed PApplet.
`boolean` | `isHat()` In frequency energy mode this returns true if a beat corresponding to the frequency range of a hi hat has been detected.
`boolean` | `isKick()` In frequency energy mode this returns true if a beat corresponding to the frequency range of a kick drum has been detected.
`boolean` | `isOnset()` In sound energy mode this returns true when a beat has been detected.
`boolean` | `isOnset(int i)` In frequency energy mode this returns true when a beat has been detect in the `ith` frequency band.
`boolean` | `isRange(int low, int high, int threshold)` In frequency energy mode this returns true if at least `threshold` bands of the bands included in the range `[low, high]` have registered a beat.
`boolean` | `isSnare()` In frequency energy mode this returns true if a beat corresponding to the frequency range of a snare drum has been detected.
`void` | `setSensitivity(int s)` Sets the sensitivity of the algorithm.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### FREQ_ENERGY

    public static final int FREQ_ENERGY

  Constant used to request frequency energy tracking mode.

  See Also:
    Constant Field Values

### SOUND_ENERGY

    public static final int SOUND_ENERGY

  Constant used to request sound energy tracking mode.

  See Also:
    Constant Field Values

Constructor Detail

### BeatDetect

    public BeatDetect()

  Create a BeatDetect object that is in SOUND_ENERGY mode. `timeSize` and `sampleRate` will be set to 1024 and 44100, respectively, so that it is possible to switch into FREQ_ENERGY mode with meaningful values.

### BeatDetect

    public BeatDetect(int timeSize,
                      float sampleRate)

  Create a BeatDetect object that is in FREQ_ENERGY mode and expects a sample buffer with the requested attributes.

  Parameters:
    `timeSize` - the size of the buffer
    `sampleRate` - the sample rate of the samples in the buffer

Method Detail

### detectMode

    public void detectMode(int algo)

  Set the object to use the requested algorithm. If an invalid value is passed, the function will report and error and default to BeatDetect.SOUND_ENERGY

  Parameters:
    `algo` - either BeatDetect.SOUND_ENERGY or BeatDetect.FREQ_ENERGY

### detect

    public void detect(AudioBuffer ab)

  Analyze the samples in `ab`. This is a cumulative process, so you must call this function every frame.

  Parameters:
    `ab` - the AudioBuffer to analyze.

### detect

    public void detect(float[] buffer)

  Analyze the samples in `buffer`. This is a cumulative process, so you must call this function every frame.

  Parameters:
    `buffer` - the buffer to analyze

### isOnset

    public boolean isOnset()

  In sound energy mode this returns true when a beat has been detected. In frequency energy mode this always returns false.

  Returns:
    true if a beat has been detected.

### isOnset

    public boolean isOnset(int i)

  In frequency energy mode this returns true when a beat has been detect in the `ith` frequency band. In sound energy mode this always returns false.

  Parameters:
    `i` - the frequency band to query
  Returns:
    true if a beat has been detected in the requested band

### isKick

    public boolean isKick()

  In frequency energy mode this returns true if a beat corresponding to the frequency range of a kick drum has been detected. This has been tuned to work well with dance / techno music and may not perform well with other styles of music. In sound energy mode this always returns false.

  Returns:
    true if a kick drum beat has been detected

### isSnare

    public boolean isSnare()

  In frequency energy mode this returns true if a beat corresponding to the frequency range of a snare drum has been detected. This has been tuned to work well with dance / techno music and may not perform well with other styles of music. In sound energy mode this always returns false.

  Returns:
    true if a snare drum beat has been detected

### isHat

    public boolean isHat()

  In frequency energy mode this returns true if a beat corresponding to the frequency range of a hi hat has been detected. This has been tuned to work well with dance / techno music and may not perform well with other styles of music. In sound energy mode this always returns false.

  Returns:
    true if a hi hat beat has been detected

### isRange

    public boolean isRange(int low,
                           int high,
                           int threshold)

  In frequency energy mode this returns true if at least `threshold` bands of the bands included in the range `[low, high]` have registered a beat. In sound energy mode this always returns false.

  Parameters:
    `low` - the index of the lower band
    `high` - the index of the higher band
    `threshold` - the smallest number of bands in the range `[low, high]` that need to have registered a beat for this to return true
  Returns:
    true if at least `threshold` bands of the bands included in the range `[low, high]` have registered a beat

### setSensitivity

    public void setSensitivity(int s)

  Sets the sensitivity of the algorithm. After a beat has been detected, the algorithm will wait for `s` milliseconds before allowing another beat to be reported. You can use this to dampen the algorithm if it is giving too many false-positives. The default value is 10, which is essentially no damping. If you try to set the sensitivity to a negative value, an error will be reported and it will be set to 10 instead.

  Parameters:
    `s` - the sensitivity in milliseconds

### drawGraph

    public void drawGraph(processing.core.PApplet p)

  Draws some debugging visuals in the passed PApplet. The visuals drawn when in frequency energy mode are a good way to determine what values to use with `inRange()` if the provided drum detecting functions aren't what you need or aren't working well.

  Parameters:
    `p` - the PApplet to draw in

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD