DynamicsProcessing

public final class DynamicsProcessing
extends AudioEffect

java.lang.Object
   ↳ android.media.audiofx.AudioEffect
     ↳ android.media.audiofx.DynamicsProcessing


DynamicsProcessing is an audio effect for equalizing and changing dynamic range properties of the sound. It is composed of multiple stages including equalization, multi-band compression and limiter.

The number of bands and active stages is configurable, and most parameters can be controlled in realtime, such as gains, attack/release times, thresholds, etc.

The effect is instantiated and controlled by channels. Each channel has the same basic architecture, but all of their parameters are independent from other channels.

The basic channel configuration is:


    Channel 0          Channel 1       ....       Channel N-1
      Input              Input                       Input
        |                  |                           |
   +----v----+        +----v----+                 +----v----+
   |inputGain|        |inputGain|                 |inputGain|
   +---------+        +---------+                 +---------+
        |                  |                           |
  +-----v-----+      +-----v-----+               +-----v-----+
  |   PreEQ   |      |   PreEQ   |               |   PreEQ   |
  +-----------+      +-----------+               +-----------+
        |                  |                           |
  +-----v-----+      +-----v-----+               +-----v-----+
  |    MBC    |      |    MBC    |               |    MBC    |
  +-----------+      +-----------+               +-----------+
        |                  |                           |
  +-----v-----+      +-----v-----+               +-----v-----+
  |  PostEQ   |      |  PostEQ   |               |  PostEQ   |
  +-----------+      +-----------+               +-----------+
        |                  |                           |
  +-----v-----+      +-----v-----+               +-----v-----+
  |  Limiter  |      |  Limiter  |               |  Limiter  |
  +-----------+      +-----------+               +-----------+
        |                  |                           |
     Output             Output                      Output
 

Where the stages are: inputGain: input gain factor in decibels (dB). 0 dB means no change in level. PreEQ: Multi-band Equalizer. MBC: Multi-band Compressor PostEQ: Multi-band Equalizer Limiter: Single band compressor/limiter.

An application creates a DynamicsProcessing object to instantiate and control this audio effect in the audio framework. A DynamicsProcessor.Config and DynamicsProcessor.Config.Builder are available to help configure the multiple stages and each band parameters if desired.

See each stage documentation for further details.

If no Config is specified during creation, a default configuration is chosen.

To attach the DynamicsProcessing to a particular AudioTrack or MediaPlayer, specify the audio session ID of this AudioTrack or MediaPlayer when constructing the effect (see getAudioSessionId() and getAudioSessionId()).

To attach the DynamicsProcessing to a particular AudioTrack or MediaPlayer, specify the audio session ID of this AudioTrack or MediaPlayer when constructing the DynamicsProcessing.

See getAudioSessionId() for details on audio sessions.

See AudioEffect class for more details on controlling audio effects.

Summary

Nested classes

class DynamicsProcessing.BandBase

Base class for bands  

class DynamicsProcessing.BandStage

Base class for stages that hold bands  

class DynamicsProcessing.Channel

Class for Channel configuration parameters. 

class DynamicsProcessing.Config

Class for Config object, used by DynamicsProcessing to configure and update the audio effect. 

class DynamicsProcessing.Eq

Class for Equalizer stage  

class DynamicsProcessing.EqBand

Class for Equalizer Bands Equalizer bands have three controllable parameters: enabled/disabled, cutoffFrequency and gain  

class DynamicsProcessing.Limiter

Class for Limiter Stage Limiter is a single band compressor at the end of the processing chain, commonly used to protect the signal from overloading and distortion. 

class DynamicsProcessing.Mbc

Class for Multi-Band Compressor (MBC) stage  

class DynamicsProcessing.MbcBand

Class for Multi-Band compressor bands MBC bands have multiple controllable parameters: enabled/disabled, cutoffFrequency, attackTime, releaseTime, ratio, threshold, kneeWidth, noiseGateThreshold, expanderRatio, preGain and postGain. 

class DynamicsProcessing.Stage

base class for the different stages. 

Constants

int VARIANT_FAVOR_FREQUENCY_RESOLUTION

Index of variant that favors frequency resolution.

int VARIANT_FAVOR_TIME_RESOLUTION

Index of variant that favors time resolution resolution.

Inherited constants

Inherited fields

Public constructors

DynamicsProcessing(int audioSession)

Class constructor.

DynamicsProcessing(int priority, int audioSession, DynamicsProcessing.Config cfg)

Class constructor for the DynamicsProcessing audio effect

Public methods

DynamicsProcessing.Channel getChannelByChannelIndex(int channelIndex)
int getChannelCount()

Gets the number of channels in the effect engine

DynamicsProcessing.Config getConfig()

Returns the Config object used to setup this effect.

float getInputGainByChannelIndex(int channelIndex)
DynamicsProcessing.Limiter getLimiterByChannelIndex(int channelIndex)
DynamicsProcessing.MbcBand getMbcBandByChannelIndex(int channelIndex, int band)
DynamicsProcessing.Mbc getMbcByChannelIndex(int channelIndex)
DynamicsProcessing.EqBand getPostEqBandByChannelIndex(int channelIndex, int band)
DynamicsProcessing.Eq getPostEqByChannelIndex(int channelIndex)
DynamicsProcessing.EqBand getPreEqBandByChannelIndex(int channelIndex, int band)
DynamicsProcessing.Eq getPreEqByChannelIndex(int channelIndex)
void setAllChannelsTo(DynamicsProcessing.Channel channel)
void setChannelTo(int channelIndex, DynamicsProcessing.Channel channel)
void setInputGainAllChannelsTo(float inputGain)
void setInputGainbyChannel(int channelIndex, float inputGain)
void setLimiterAllChannelsTo(DynamicsProcessing.Limiter limiter)
void setLimiterByChannelIndex(int channelIndex, DynamicsProcessing.Limiter limiter)
void setMbcAllChannelsTo(DynamicsProcessing.Mbc mbc)
void setMbcBandAllChannelsTo(int band, DynamicsProcessing.MbcBand mbcBand)
void setMbcBandByChannelIndex(int channelIndex, int band, DynamicsProcessing.MbcBand mbcBand)
void setMbcByChannelIndex(int channelIndex, DynamicsProcessing.Mbc mbc)
void setPostEqAllChannelsTo(DynamicsProcessing.Eq postEq)
void setPostEqBandAllChannelsTo(int band, DynamicsProcessing.EqBand postEqBand)
void setPostEqBandByChannelIndex(int channelIndex, int band, DynamicsProcessing.EqBand postEqBand)
void setPostEqByChannelIndex(int channelIndex, DynamicsProcessing.Eq postEq)
void setPreEqAllChannelsTo(DynamicsProcessing.Eq preEq)
void setPreEqBandAllChannelsTo(int band, DynamicsProcessing.EqBand preEqBand)
void setPreEqBandByChannelIndex(int channelIndex, int band, DynamicsProcessing.EqBand preEqBand)
void setPreEqByChannelIndex(int channelIndex, DynamicsProcessing.Eq preEq)

Inherited methods

Constants

VARIANT_FAVOR_FREQUENCY_RESOLUTION

int VARIANT_FAVOR_FREQUENCY_RESOLUTION

Index of variant that favors frequency resolution. Frequency domain based implementation.

Constant Value: 0 (0x00000000)

VARIANT_FAVOR_TIME_RESOLUTION

int VARIANT_FAVOR_TIME_RESOLUTION

Index of variant that favors time resolution resolution. Time domain based implementation.

Constant Value: 1 (0x00000001)

Public constructors

DynamicsProcessing

DynamicsProcessing (int audioSession)

Class constructor.

Parameters
audioSession int: system-wide unique audio session identifier. The DynamicsProcessing will be attached to the MediaPlayer or AudioTrack in the same audio session.

DynamicsProcessing

DynamicsProcessing (int priority, 
                int audioSession, 
                DynamicsProcessing.Config cfg)

Class constructor for the DynamicsProcessing audio effect

Parameters
priority int: the priority level requested by the application for controlling the DynamicsProcessing engine. As the same engine can be shared by several applications, this parameter indicates how much the requesting application needs control of effect parameters. The normal priority is 0, above normal is a positive number, below normal a negative number.

audioSession int: system-wide unique audio session identifier. The DynamicsProcessing will be attached to the MediaPlayer or AudioTrack in the same audio session.

cfg DynamicsProcessing.Config: Config object used to setup the audio effect, including bands per stage, and specific parameters for each stage/band. Use DynamicsProcessing.Config.Builder to create a Config object that suits your needs. A null cfg parameter will create and use a default configuration for the effect

Public methods

getChannelByChannelIndex

DynamicsProcessing.Channel getChannelByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Channel

getChannelCount

int getChannelCount ()

Gets the number of channels in the effect engine

Returns
int number of channels currently in use by the effect engine

getConfig

DynamicsProcessing.Config getConfig ()

Returns the Config object used to setup this effect.

Returns
DynamicsProcessing.Config Config Current Config object used to setup this DynamicsProcessing effect.

getInputGainByChannelIndex

float getInputGainByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
float

getLimiterByChannelIndex

DynamicsProcessing.Limiter getLimiterByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Limiter

getMbcBandByChannelIndex

DynamicsProcessing.MbcBand getMbcBandByChannelIndex (int channelIndex, 
                int band)

Parameters
channelIndex int

band int

Returns
DynamicsProcessing.MbcBand

getMbcByChannelIndex

DynamicsProcessing.Mbc getMbcByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Mbc

getPostEqBandByChannelIndex

DynamicsProcessing.EqBand getPostEqBandByChannelIndex (int channelIndex, 
                int band)

Parameters
channelIndex int

band int

Returns
DynamicsProcessing.EqBand

getPostEqByChannelIndex

DynamicsProcessing.Eq getPostEqByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Eq

getPreEqBandByChannelIndex

DynamicsProcessing.EqBand getPreEqBandByChannelIndex (int channelIndex, 
                int band)

Parameters
channelIndex int

band int

Returns
DynamicsProcessing.EqBand

getPreEqByChannelIndex

DynamicsProcessing.Eq getPreEqByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Eq

setAllChannelsTo

void setAllChannelsTo (DynamicsProcessing.Channel channel)

Parameters
channel DynamicsProcessing.Channel

setChannelTo

void setChannelTo (int channelIndex, 
                DynamicsProcessing.Channel channel)

Parameters
channelIndex int

channel DynamicsProcessing.Channel

setInputGainAllChannelsTo

void setInputGainAllChannelsTo (float inputGain)

Parameters
inputGain float

setInputGainbyChannel

void setInputGainbyChannel (int channelIndex, 
                float inputGain)

Parameters
channelIndex int

inputGain float

setLimiterAllChannelsTo

void setLimiterAllChannelsTo (DynamicsProcessing.Limiter limiter)

Parameters
limiter DynamicsProcessing.Limiter

setLimiterByChannelIndex

void setLimiterByChannelIndex (int channelIndex, 
                DynamicsProcessing.Limiter limiter)

Parameters
channelIndex int

limiter DynamicsProcessing.Limiter

setMbcAllChannelsTo

void setMbcAllChannelsTo (DynamicsProcessing.Mbc mbc)

Parameters
mbc DynamicsProcessing.Mbc

setMbcBandAllChannelsTo

void setMbcBandAllChannelsTo (int band, 
                DynamicsProcessing.MbcBand mbcBand)

Parameters
band int

mbcBand DynamicsProcessing.MbcBand

setMbcBandByChannelIndex

void setMbcBandByChannelIndex (int channelIndex, 
                int band, 
                DynamicsProcessing.MbcBand mbcBand)

Parameters
channelIndex int

band int

mbcBand DynamicsProcessing.MbcBand

setMbcByChannelIndex

void setMbcByChannelIndex (int channelIndex, 
                DynamicsProcessing.Mbc mbc)

Parameters
channelIndex int

mbc DynamicsProcessing.Mbc

setPostEqAllChannelsTo

void setPostEqAllChannelsTo (DynamicsProcessing.Eq postEq)

Parameters
postEq DynamicsProcessing.Eq

setPostEqBandAllChannelsTo

void setPostEqBandAllChannelsTo (int band, 
                DynamicsProcessing.EqBand postEqBand)

Parameters
band int

postEqBand DynamicsProcessing.EqBand

setPostEqBandByChannelIndex

void setPostEqBandByChannelIndex (int channelIndex, 
                int band, 
                DynamicsProcessing.EqBand postEqBand)

Parameters
channelIndex int

band int

postEqBand DynamicsProcessing.EqBand

setPostEqByChannelIndex

void setPostEqByChannelIndex (int channelIndex, 
                DynamicsProcessing.Eq postEq)

Parameters
channelIndex int

postEq DynamicsProcessing.Eq

setPreEqAllChannelsTo

void setPreEqAllChannelsTo (DynamicsProcessing.Eq preEq)

Parameters
preEq DynamicsProcessing.Eq

setPreEqBandAllChannelsTo

void setPreEqBandAllChannelsTo (int band, 
                DynamicsProcessing.EqBand preEqBand)

Parameters
band int

preEqBand DynamicsProcessing.EqBand

setPreEqBandByChannelIndex

void setPreEqBandByChannelIndex (int channelIndex, 
                int band, 
                DynamicsProcessing.EqBand preEqBand)

Parameters
channelIndex int

band int

preEqBand DynamicsProcessing.EqBand

setPreEqByChannelIndex

void setPreEqByChannelIndex (int channelIndex, 
                DynamicsProcessing.Eq preEq)

Parameters
channelIndex int

preEq DynamicsProcessing.Eq