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

String ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION

Intent to signal to the effect control application or service that an audio session is closed and that effects should not be applied anymore.

String ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL

Intent to launch an audio effect control panel UI.

String ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION

Intent to signal to the effect control application or service that a new audio session is opened and requires audio effects to be applied.

int ALREADY_EXISTS

Internal operation status.

int CONTENT_TYPE_GAME

Value for EXTRA_CONTENT_TYPE when the type of content played is game audio

int CONTENT_TYPE_MOVIE

Value for EXTRA_CONTENT_TYPE when the type of content played is video or movie

int CONTENT_TYPE_MUSIC

Value for EXTRA_CONTENT_TYPE when the type of content played is music

int CONTENT_TYPE_VOICE

Value for EXTRA_CONTENT_TYPE when the type of content played is voice audio

String EFFECT_AUXILIARY

Effect connection mode is auxiliary.

String EFFECT_INSERT

Effect connection mode is insert.

String EFFECT_POST_PROCESSING

Effect connection mode is post processing.

String EFFECT_PRE_PROCESSING

Effect connection mode is pre processing.

int ERROR

Unspecified error.

int ERROR_BAD_VALUE

Operation failed due to bad parameter value.

int ERROR_DEAD_OBJECT

Operation failed due to dead remote object.

int ERROR_INVALID_OPERATION

Operation failed because it was requested in wrong state.

int ERROR_NO_INIT

Operation failed due to bad object initialization.

int ERROR_NO_MEMORY

Operation failed due to lack of memory.

String EXTRA_AUDIO_SESSION

Contains the ID of the audio session the effects should be applied to.

String EXTRA_CONTENT_TYPE

Indicates which type of content is played by the application.

String EXTRA_PACKAGE_NAME

Contains the package name of the calling application.

int SUCCESS

Successful operation.

Inherited fields

public static final UUID EFFECT_TYPE_AEC

UUID for Acoustic Echo Canceler (AEC)

public static final UUID EFFECT_TYPE_AGC

UUID for Automatic Gain Control (AGC)

public static final UUID EFFECT_TYPE_BASS_BOOST

UUID for bass boost effect

public static final UUID EFFECT_TYPE_DYNAMICS_PROCESSING

UUID for Dynamics Processing

public static final UUID EFFECT_TYPE_ENV_REVERB

UUID for environmental reverberation effect

public static final UUID EFFECT_TYPE_EQUALIZER

UUID for equalizer effect

public static final UUID EFFECT_TYPE_HAPTIC_GENERATOR

UUID for Haptic Generator.

public static final UUID EFFECT_TYPE_LOUDNESS_ENHANCER

UUID for Loudness Enhancer

public static final UUID EFFECT_TYPE_NS

UUID for Noise Suppressor (NS)

public static final UUID EFFECT_TYPE_PRESET_REVERB

UUID for preset reverberation effect

public static final UUID EFFECT_TYPE_VIRTUALIZER

UUID for virtualizer effect

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

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

AudioEffect.Descriptor getDescriptor()

Get the effect descriptor.

boolean getEnabled()

Returns effect enabled state

int getId()

Returns effect unique identifier.

boolean hasControl()

Checks if this AudioEffect object is controlling the effect engine.

static Descriptor[] queryEffects()

Query all effects available on the platform.

void release()

Releases the native AudioEffect resources.

void setControlStatusListener(AudioEffect.OnControlStatusChangeListener listener)

Sets the listener AudioEffect notifies when the effect engine control is taken or returned.

void setEnableStatusListener(AudioEffect.OnEnableStatusChangeListener listener)

Sets the listener AudioEffect notifies when the effect engine is enabled or disabled.

int setEnabled(boolean enabled)

Enable or disable the effect.

Object clone()

Creates and returns a copy of this object.

boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

final Class<?> getClass()

Returns the runtime class of this Object.

int hashCode()

Returns a hash code value for the object.

final void notify()

Wakes up a single thread that is waiting on this object's monitor.

final void notifyAll()

Wakes up all threads that are waiting on this object's monitor.

String toString()

Returns a string representation of the object.

final void wait(long timeoutMillis, int nanos)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait(long timeoutMillis)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait()

Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

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

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

getMbcBandByChannelIndex

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

Parameters
channelIndex int

band int

getMbcByChannelIndex

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

Parameters
channelIndex int

getPostEqBandByChannelIndex

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

Parameters
channelIndex int

band int

getPostEqByChannelIndex

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

Parameters
channelIndex int

getPreEqBandByChannelIndex

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

Parameters
channelIndex int

band int

getPreEqByChannelIndex

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

Parameters
channelIndex int

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