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 AudioTrack#getAudioSessionId() and MediaPlayer#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 MediaPlayer.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

Added in API level 28
public static final int VARIANT_FAVOR_FREQUENCY_RESOLUTION

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

Constant Value: 0 (0x00000000)

VARIANT_FAVOR_TIME_RESOLUTION

Added in API level 28
public static final int VARIANT_FAVOR_TIME_RESOLUTION

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

Constant Value: 1 (0x00000001)

Public constructors

DynamicsProcessing

Added in API level 28
public 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

Added in API level 28
public 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

Added in API level 28
public DynamicsProcessing.Channel getChannelByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Channel

getChannelCount

Added in API level 28
public int getChannelCount ()

Gets the number of channels in the effect engine

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

getConfig

Added in API level 28
public 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

Added in API level 28
public float getInputGainByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
float

getLimiterByChannelIndex

Added in API level 28
public DynamicsProcessing.Limiter getLimiterByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Limiter

getMbcBandByChannelIndex

Added in API level 28
public DynamicsProcessing.MbcBand getMbcBandByChannelIndex (int channelIndex, 
                int band)

Parameters
channelIndex int

band int

Returns
DynamicsProcessing.MbcBand

getMbcByChannelIndex

Added in API level 28
public DynamicsProcessing.Mbc getMbcByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Mbc

getPostEqBandByChannelIndex

Added in API level 28
public DynamicsProcessing.EqBand getPostEqBandByChannelIndex (int channelIndex, 
                int band)

Parameters
channelIndex int

band int

Returns
DynamicsProcessing.EqBand

getPostEqByChannelIndex

Added in API level 28
public DynamicsProcessing.Eq getPostEqByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Eq

getPreEqBandByChannelIndex

Added in API level 28
public DynamicsProcessing.EqBand getPreEqBandByChannelIndex (int channelIndex, 
                int band)

Parameters
channelIndex int

band int

Returns
DynamicsProcessing.EqBand

getPreEqByChannelIndex

Added in API level 28
public DynamicsProcessing.Eq getPreEqByChannelIndex (int channelIndex)

Parameters
channelIndex int

Returns
DynamicsProcessing.Eq

setAllChannelsTo

Added in API level 28
public void setAllChannelsTo (DynamicsProcessing.Channel channel)

Parameters
channel DynamicsProcessing.Channel

setChannelTo

Added in API level 28
public void setChannelTo (int channelIndex, 
                DynamicsProcessing.Channel channel)

Parameters
channelIndex int

channel DynamicsProcessing.Channel

setInputGainAllChannelsTo

Added in API level 28
public void setInputGainAllChannelsTo (float inputGain)

Parameters
inputGain float

setInputGainbyChannel

Added in API level 28
public void setInputGainbyChannel (int channelIndex, 
                float inputGain)

Parameters
channelIndex int

inputGain float

setLimiterAllChannelsTo

Added in API level 28
public void setLimiterAllChannelsTo (DynamicsProcessing.Limiter limiter)

Parameters
limiter DynamicsProcessing.Limiter

setLimiterByChannelIndex

Added in API level 28
public void setLimiterByChannelIndex (int channelIndex, 
                DynamicsProcessing.Limiter limiter)

Parameters
channelIndex int

limiter DynamicsProcessing.Limiter

setMbcAllChannelsTo

Added in API level 28
public void setMbcAllChannelsTo (DynamicsProcessing.Mbc mbc)

Parameters
mbc DynamicsProcessing.Mbc

setMbcBandAllChannelsTo

Added in API level 28
public void setMbcBandAllChannelsTo (int band, 
                DynamicsProcessing.MbcBand mbcBand)

Parameters
band int

mbcBand DynamicsProcessing.MbcBand

setMbcBandByChannelIndex

Added in API level 28
public void setMbcBandByChannelIndex (int channelIndex, 
                int band, 
                DynamicsProcessing.MbcBand mbcBand)

Parameters
channelIndex int

band int

mbcBand DynamicsProcessing.MbcBand

setMbcByChannelIndex

Added in API level 28
public void setMbcByChannelIndex (int channelIndex, 
                DynamicsProcessing.Mbc mbc)

Parameters
channelIndex int

mbc DynamicsProcessing.Mbc

setPostEqAllChannelsTo

Added in API level 28
public void setPostEqAllChannelsTo (DynamicsProcessing.Eq postEq)

Parameters
postEq DynamicsProcessing.Eq

setPostEqBandAllChannelsTo

Added in API level 28
public void setPostEqBandAllChannelsTo (int band, 
                DynamicsProcessing.EqBand postEqBand)

Parameters
band int

postEqBand DynamicsProcessing.EqBand

setPostEqBandByChannelIndex

Added in API level 28
public void setPostEqBandByChannelIndex (int channelIndex, 
                int band, 
                DynamicsProcessing.EqBand postEqBand)

Parameters
channelIndex int

band int

postEqBand DynamicsProcessing.EqBand

setPostEqByChannelIndex

Added in API level 28
public void setPostEqByChannelIndex (int channelIndex, 
                DynamicsProcessing.Eq postEq)

Parameters
channelIndex int

postEq DynamicsProcessing.Eq

setPreEqAllChannelsTo

Added in API level 28
public void setPreEqAllChannelsTo (DynamicsProcessing.Eq preEq)

Parameters
preEq DynamicsProcessing.Eq

setPreEqBandAllChannelsTo

Added in API level 28
public void setPreEqBandAllChannelsTo (int band, 
                DynamicsProcessing.EqBand preEqBand)

Parameters
band int

preEqBand DynamicsProcessing.EqBand

setPreEqBandByChannelIndex

Added in API level 28
public void setPreEqBandByChannelIndex (int channelIndex, 
                int band, 
                DynamicsProcessing.EqBand preEqBand)

Parameters
channelIndex int

band int

preEqBand DynamicsProcessing.EqBand

setPreEqByChannelIndex

Added in API level 28
public void setPreEqByChannelIndex (int channelIndex, 
                DynamicsProcessing.Eq preEq)

Parameters
channelIndex int

preEq DynamicsProcessing.Eq