Package icyllis.modernui.audio

# Class FFT

java.lang.Object
icyllis.modernui.audio.FFT

public class FFT extends Object
Provides Fast Fourier Transform. It is an efficient way to calculate the Complex Discrete Fourier Transform, which is commonly used to analyze the spectrum of an audio buffer.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BARTLETT`
  `static final int`
  `BLACKMAN`
  `static final int`
  `HAMMING`
  `static final int`
  `HANN`
  `static final int`
  `NONE`
  Constants indicating which window should be used on sample buffers.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static FFT`
  `create(int timeSize, int sampleRate)`
  Creates an FFT that will accept sample buffers that are `timeSize` long and have been recorded with a sample rate of `sampleRate`.
  `void`
  `forward(float[] real, float[] imag, int offset)`
  Performs a forward transform on the passed buffers.
  `void`
  `forward(float[] samples, int offset)`
  Performs a forward transform on values in `samples`.
  `int`
  `freqToIndex(float freq)`
  Returns the index of the frequency band that contains the requested frequency.
  `float`
  `getAverage(float lowFreq, float hiFreq)`
  Calculate the average amplitude of the frequency band bounded by `lowFreq` and `hiFreq`, inclusive.
  `float`
  `getAverage(int i)`
  Gets the value of the `ith` average.
  `float`
  `getAverageCenterFrequency(int i)`
  Returns the center frequency of the ith average band.
  `int`
  `getAverageSize()`
  Returns the number of averages currently being calculated.
  `float`
  `getBand(int i)`
  Returns the amplitude of the requested frequency band.
  `int`
  `getBandSize()`
  Returns the size of the spectrum created by this transform.
  `float`
  `getBandWidth()`
  Returns the width of each frequency band in the spectrum (in Hz).
  `float`
  `getFrequency(float freq)`
  Gets the amplitude of the requested frequency in the spectrum.
  `int`
  `getSampleRate()`
  Returns the sample rate of signal samples expected by this transform.
  `int`
  `getTimeSize()`
  Returns the length of the time domain signal expected by this transform.
  `float`
  `indexToFreq(int i)`
  Returns the middle frequency of the ith band.
  `void`
  `scaleBand(int band, float scale)`
  Scales the amplitude of the `ith` frequency band by `s`.
  `void`
  `scaleFrequency(float freq, float scale)`
  Scales the amplitude of the requested frequency by `a`.
  `void`
  `setBand(int band, float amplitude)`
  Sets the amplitude of the `ith` frequency band to `a`.
  `void`
  `setFrequency(float freq, float amplitude)`
  Sets the amplitude of the requested frequency in the spectrum to `a`.
  `void`
  `setLinearAverages(int num)`
  Sets the number of averages used when computing the spectrum and spaces the averages in a linear manner.
  `void`
  `setLogAverages(int minBandwidth, int bandsPerOctave)`
  Sets the number of averages used when computing the spectrum based on the minimum bandwidth for an octave and the number of bands per octave.
  `void`
  `setNoAverages()`
  Sets the object to not compute averages.
  `void`
  `setWindowFunc(int func)`
  Sets the window to use on the samples before taking the forward transform.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### NONE

    public static final int NONE
    Constants indicating which window should be used on sample buffers.
    See Also:
      - `setWindowFunc(int)`
      - Constant Field Values

  - ### BARTLETT

    public static final int BARTLETT
    See Also:
      - Constant Field Values

  - ### HAMMING

    public static final int HAMMING
    See Also:
      - Constant Field Values

  - ### HANN

    public static final int HANN
    See Also:
      - Constant Field Values

  - ### BLACKMAN

    public static final int BLACKMAN
    See Also:
      - Constant Field Values

- ## Method Details

  - ### create

    @Nonnull public static FFT create(int timeSize, int sampleRate)
    Creates an FFT that will accept sample buffers that are `timeSize` long and have been recorded with a sample rate of `sampleRate`. `timeSize` must be a power of two.
    Parameters:
      `timeSize` - the length of the sample buffers you will be analyzing
      `sampleRate` - the sample rate of the audio you will be analyzing

  - ### forward

    public void forward(@Nonnull float[] samples, int offset)
    Performs a forward transform on values in `samples`.
    Parameters:
      `samples` - the buffer of samples
      `offset` - the offset to start at in the buffer, the exceeded part of next timeSize() samples from the starting index in the buffer will be filled with zeros.

  - ### forward

    public void forward(@Nonnull float[] real, @Nonnull float[] imag, int offset)
    Performs a forward transform on the passed buffers.
    Parameters:
      `real` - the real part of the time domain signal to transform
      `imag` - the imaginary part of the time domain signal to transform
      `offset` - the offset to start at in the buffer, the exceeded part of next timeSize() * samples from the starting index in the buffer will be filled with zeros.

  - ### setNoAverages

    public void setNoAverages()
    Sets the object to not compute averages.

  - ### setLinearAverages

    public void setLinearAverages(int num)
    Sets the number of averages used when computing the spectrum and spaces the averages in a linear manner. In other words, each average band will be `specSize() / numAvg` bands wide.
    Parameters:
      `num` - how many averages to compute

  - ### setLogAverages

    public void setLogAverages(int minBandwidth, int bandsPerOctave)
    Sets the number of averages used when computing the spectrum based on the minimum bandwidth for an octave and the number of bands per octave. For example, with audio that has a sample rate of 44100 Hz, `logAverages(11, 1)` will result in 12 averages, each corresponding to an octave, the first spanning 0 to 11 Hz. To ensure that each octave band is a full octave, the number of octaves is computed by dividing the Nyquist frequency by two, and then the result of that by two, and so on. This means that the actual bandwidth of the lowest octave may not be exactly the value specified.
    Parameters:
      `minBandwidth` - the minimum bandwidth used for an octave
      `bandsPerOctave` - how many bands to split each octave into

  - ### setWindowFunc

    public void setWindowFunc(int func)
    Sets the window to use on the samples before taking the forward transform. If an invalid window is asked for, an error will be reported and the current window will not be changed. `NONE` is the default, equivalent to the rectangular window.
    Parameters:
      `func` - window function, such as `HAMMING`
    Throws:
      `IllegalArgumentException` - invalid window function

  - ### getTimeSize

    public int getTimeSize()
    Returns the length of the time domain signal expected by this transform.
    Returns:
      the length of the time domain signal expected by this transform

  - ### getSampleRate

    public int getSampleRate()
    Returns the sample rate of signal samples expected by this transform.
    Returns:
      the sample rate of signal samples expected by this transform

  - ### getBandSize

    public int getBandSize()
    Returns the size of the spectrum created by this transform. In other words, the number of frequency bands produced by this transform. This is typically equal to `timeSize()/2 + 1`, see above for an explanation.
    Returns:
      the size of the spectrum

  - ### getBandWidth

    public float getBandWidth()
    Returns the width of each frequency band in the spectrum (in Hz). It should be noted that the bandwidth of the first and last frequency bands is half as large as the value returned by this function.
    Returns:
      the width of each frequency band in Hz.

  - ### getBand

    public float getBand(int i)
    Returns the amplitude of the requested frequency band.
    Parameters:
      `i` - the index of a frequency band
    Returns:
      the amplitude of the requested frequency band

  - ### setBand

    public void setBand(int band, float amplitude)
    Sets the amplitude of the `ith` frequency band to `a`. You can use this to shape the spectrum before using `inverse()`.
    Parameters:
      `band` - the frequency band to modify
      `amplitude` - the new amplitude

  - ### scaleBand

    public void scaleBand(int band, float scale)
    Scales the amplitude of the `ith` frequency band by `s`. You can use this to shape the spectrum before using `inverse()`.
    Parameters:
      `band` - the frequency band to modify
      `scale` - the scaling factor

  - ### freqToIndex

    public int freqToIndex(float freq)
    Returns the index of the frequency band that contains the requested frequency.
    Parameters:
      `freq` - the frequency you want the index for (in Hz)
    Returns:
      the index of the frequency band that contains freq

  - ### indexToFreq

    public float indexToFreq(int i)
    Returns the middle frequency of the ith band.
    Parameters:
      `i` - the index of the band you want to middle frequency of

  - ### getAverageCenterFrequency

    public float getAverageCenterFrequency(int i)
    Returns the center frequency of the ith average band.
    Parameters:
      `i` - which average band you want the center frequency of.

  - ### getFrequency

    public float getFrequency(float freq)
    Gets the amplitude of the requested frequency in the spectrum.
    Parameters:
      `freq` - the frequency in Hz
    Returns:
      the amplitude of the frequency in the spectrum

  - ### setFrequency

    public void setFrequency(float freq, float amplitude)
    Sets the amplitude of the requested frequency in the spectrum to `a`.
    Parameters:
      `freq` - the frequency in Hz
      `amplitude` - the new amplitude

  - ### scaleFrequency

    public void scaleFrequency(float freq, float scale)
    Scales the amplitude of the requested frequency by `a`.
    Parameters:
      `freq` - the frequency in Hz
      `scale` - the scaling factor

  - ### getAverageSize

    public int getAverageSize()
    Returns the number of averages currently being calculated.
    Returns:
      the length of the averages array

  - ### getAverage

    public float getAverage(int i)
    Gets the value of the `ith` average.
    Parameters:
      `i` - the average you want the value of
    Returns:
      the value of the requested average band

  - ### getAverage

    public float getAverage(float lowFreq, float hiFreq)
    Calculate the average amplitude of the frequency band bounded by `lowFreq` and `hiFreq`, inclusive.
    Parameters:
      `lowFreq` - the lower bound of the band
      `hiFreq` - the upper bound of the band
    Returns:
      the average of all spectrum values within the bounds