Package: android.hardware.audio.effect@2.0

IEffect

interface IEffect

Methods

init

init ()
generates (Result retval)

Initialize effect engine--all configurations return to default.

Details
Generates
retval
operation completion status.
Annotations
entry
callflow
next= { "*" }

setConfig

setConfig (EffectConfig config, IEffectBufferProviderCallback inputBufferProvider, IEffectBufferProviderCallback outputBufferProvider)
generates (Result retval)

Apply new audio parameters configurations for input and output buffers.The provider callbacks may be empty, but in this case the buffer must be provided in the EffectConfig structure.

Details
Parameters
config
configuration descriptor.
inputBufferProvider
optional buffer provider reference.
outputBufferProvider
optional buffer provider reference.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

reset

reset ()
generates (Result retval)

Reset the effect engine.Keep configuration but resets state and buffer content.

Details
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

enable

enable ()
generates (Result retval)

Enable processing.

Details
Generates
retval
operation completion status.
Annotations
callflow
next= { "prepareForProcessing" }

disable

disable ()
generates (Result retval)

Disable processing.

Details
Generates
retval
operation completion status.
Annotations
callflow
next= { "close" }

setDevice

setDevice (AudioDevice device)
generates (Result retval)

Set the rendering device the audio output path is connected to.The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this command when the device changes.

Note:this method is only supported for effects inserted into the output chain.

Details
Parameters
device
output device specification.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

setAndGetVolume

setAndGetVolume (vec<uint32_t> volumes)
generates (Result retval, vec<uint32_t> result)

Set and get volume.Used by audio framework to delegate volume control to effect engine.The effect implementation must set EFFECT_FLAG_VOLUME_CTRL flag in its descriptor to receive this command.The effect engine must return the volume that should be applied before the effect is processed.The overall volume(the volume actually applied by the effect engine multiplied by the returned value)should match the value indicated in the command.

Details
Parameters
volumes
vector containing volume for each channel defined in EffectConfig for output buffer expressed in 8.24 fixed point format.
Generates
retval
operation completion status.
result
updated volume values.
Annotations
callflow
next= { "*" }

volumeChangeNotification

volumeChangeNotification (vec<uint32_t> volumes)
generates (Result retval)

Notify the effect of the volume change.The effect implementation must set EFFECT_FLAG_VOLUME_IND flag in its descriptor to receive this command.

Details
Parameters
volumes
vector containing volume for each channel defined in EffectConfig for output buffer expressed in 8.24 fixed point format.
Generates
retval
operation completion status.

setAudioMode

setAudioMode (AudioMode mode)
generates (Result retval)

Set the audio mode.The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its descriptor to receive this command when the audio mode changes.

Details
Parameters
mode
desired audio mode.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

setConfigReverse

setConfigReverse (EffectConfig config, IEffectBufferProviderCallback inputBufferProvider, IEffectBufferProviderCallback outputBufferProvider)
generates (Result retval)

Apply new audio parameters configurations for input and output buffers of reverse stream.An example of reverse stream is the echo reference supplied to an Acoustic Echo Canceler.

Details
Parameters
config
configuration descriptor.
inputBufferProvider
optional buffer provider reference.
outputBufferProvider
optional buffer provider reference.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

setInputDevice

setInputDevice (AudioDevice device)
generates (Result retval)

Set the capture device the audio input path is connected to.The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this command when the device changes.

Note:this method is only supported for effects inserted into the input chain.

Details
Parameters
device
input device specification.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

getConfig

getConfig ()
generates (Result retval, EffectConfig config)

Read audio parameters configurations for input and output buffers.

Details
Generates
retval
operation completion status.
config
configuration descriptor.
Annotations
callflow
next= { "*" }

getConfigReverse

getConfigReverse ()
generates (Result retval, EffectConfig config)

Read audio parameters configurations for input and output buffers of reverse stream.

Details
Generates
retval
operation completion status.
config
configuration descriptor.
Annotations
callflow
next= { "*" }

getSupportedAuxChannelsConfigs

getSupportedAuxChannelsConfigs (uint32_t maxConfigs)
generates (Result retval, vec<EffectAuxChannelsConfig> result)

Queries for supported combinations of main and auxiliary channels(e.g.for a multi-microphone noise suppressor).

Details
Parameters
maxConfigs
maximum number of the combinations to return.
Generates
retval
absence of the feature support is indicated using NOT_SUPPORTED code.RESULT_TOO_BIG is returned if the number of supported combinations exceeds 'maxConfigs'.
result
list of configuration descriptors.
Annotations
callflow
next= { "*" }

getAuxChannelsConfig

getAuxChannelsConfig ()
generates (Result retval, EffectAuxChannelsConfig result)

Retrieves the current configuration of main and auxiliary channels.

Details
Generates
retval
absence of the feature support is indicated using NOT_SUPPORTED code.
result
configuration descriptor.
Annotations
callflow
next= { "*" }

setAuxChannelsConfig

setAuxChannelsConfig (EffectAuxChannelsConfig config)
generates (Result retval)

Sets the current configuration of main and auxiliary channels.

Details
Parameters
config
Generates
retval
operation completion status;absence of the feature support is indicated using NOT_SUPPORTED code.
Annotations
callflow
next= { "*" }

setAudioSource

setAudioSource (AudioSource source)
generates (Result retval)

Set the audio source the capture path is configured for(Camcorder, voice recognition.. .).

Note:this method is only supported for effects inserted into the input chain.

Details
Parameters
source
source descriptor.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

offload

offload (EffectOffloadParameter param)
generates (Result retval)

This command indicates if the playback thread the effect is attached to is offloaded or not, and updates the I/O handle of the playback thread the effect is attached to.

Details
Parameters
param
effect offload descriptor.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

getDescriptor

getDescriptor ()
generates (Result retval, EffectDescriptor descriptor)

Returns the effect descriptor.

Details
Generates
retval
operation completion status.
descriptor
effect descriptor.
Annotations
callflow
next= { "*" }

prepareForProcessing

prepareForProcessing ()
generates (Result retval, fmq_sync<Result> statusMQ)

Set up required transports for passing audio buffers to the effect.

The transport consists of shared memory and a message queue for reporting effect processing operation status.The shared memory is set up separately using 'setProcessBuffers' method.

Processing is requested by setting 'REQUEST_PROCESS' or 'REQUEST_PROCESS_REVERSE' EventFlags associated with the status message queue.The result of processing may be one of the following:OK if there were no errors during processing;INVALID_ARGUMENTS if audio buffers are invalid;INVALID_STATE if the engine has finished the disable phase;NOT_INITIALIZED if the audio buffers were not set;NOT_SUPPORTED if the requested processing type is not supported by the effect.

Details
Generates
retval
OK if both message queues were created successfully.INVALID_STATE if the method was already called.INVALID_ARGUMENTS if there was a problem setting up the queue.
statusMQ
a message queue used for passing status from the effect.
Annotations
callflow
next= { "setProcessBuffers" }

setProcessBuffers

setProcessBuffers (AudioBuffer inBuffer, AudioBuffer outBuffer)
generates (Result retval)

Set up input and output buffers for processing audio data.The effect may modify both the input and the output buffer during the operation.Buffers may be set multiple times during effect lifetime.

The input and the output buffer may be reused between different effects, and the input buffer may be used as an output buffer.Buffers are distinguished using 'AudioBuffer.id' field.

Details
Parameters
inBuffer
input audio buffer.
outBuffer
output audio buffer.
Generates
retval
OK if both buffers were mapped successfully.INVALID_ARGUMENTS if there was a problem with mapping any of the buffers.
Annotations
callflow
next= { "*" }

command

command (uint32_t commandId, vec<uint8_t> data, uint32_t resultMaxSize)
generates (int32_t status, vec<uint8_t> result)

Execute a vendor specific command on the effect.The command code and data, as well as result data are not interpreted by Android Framework and are passed as-is between the application and the effect.

The effect must use standard POSIX.1-2001 error codes for the operation completion status.

Use this method only if the effect is provided by a third party, and there is no interface defined for it.This method only works for effects implemented in software.

Details
Parameters
commandId
the ID of the command.
data
command data.
resultMaxSize
maximum size in bytes of the result;can be 0.
Generates
status
command completion status.
result
result data.

setParameter

setParameter (vec<uint8_t> parameter, vec<uint8_t> value)
generates (Result retval)

Set a vendor-specific parameter and apply it immediately.The parameter code and data are not interpreted by Android Framework and are passed as-is between the application and the effect.

The effect must use INVALID_ARGUMENTS return code if the parameter ID is unknown or if provided parameter data is invalid.If the effect does not support setting vendor-specific parameters, it must return NOT_SUPPORTED.

Use this method only if the effect is provided by a third party, and there is no interface defined for it.This method only works for effects implemented in software.

Details
Parameters
parameter
identifying data of the parameter.
value
the value of the parameter.
Generates
retval
operation completion status.
Annotations
callflow
next= { "*" }

getParameter

getParameter (vec<uint8_t> parameter, uint32_t valueMaxSize)
generates (Result retval, vec<uint8_t> value)

Get a vendor-specific parameter value.The parameter code and returned data are not interpreted by Android Framework and are passed as-is between the application and the effect.

The effect must use INVALID_ARGUMENTS return code if the parameter ID is unknown.If the effect does not support setting vendor-specific parameters, it must return NOT_SUPPORTED.

Use this method only if the effect is provided by a third party, and there is no interface defined for it.This method only works for effects implemented in software.

Details
Parameters
parameter
identifying data of the parameter.
valueMaxSize
maximum size in bytes of the value.
Generates
retval
operation completion status.
value
Annotations
callflow
next= { "*" }

getSupportedConfigsForFeature

getSupportedConfigsForFeature (uint32_t featureId, uint32_t maxConfigs, uint32_t configSize)
generates (Result retval, uint32_t configsCount, vec<uint8_t> configsData)

Get supported configs for a vendor-specific feature.The configs returned are not interpreted by Android Framework and are passed as-is between the application and the effect.

The effect must use INVALID_ARGUMENTS return code if the feature ID is unknown.If the effect does not support getting vendor-specific feature configs, it must return NOT_SUPPORTED.If the feature is supported but the total number of supported configurations exceeds the maximum number indicated by the caller, the method must return RESULT_TOO_BIG.

Use this method only if the effect is provided by a third party, and there is no interface defined for it.This method only works for effects implemented in software.

Details
Parameters
featureId
feature identifier.
maxConfigs
maximum number of configs to return.
configSize
size of each config in bytes.
Generates
retval
operation completion status.
configsCount
number of configs returned.
configsData
data for all the configs returned.
Annotations
callflow
next= { "*" }

getCurrentConfigForFeature

getCurrentConfigForFeature (uint32_t featureId, uint32_t configSize)
generates (Result retval, vec<uint8_t> configData)

Get the current config for a vendor-specific feature.The config returned is not interpreted by Android Framework and is passed as-is between the application and the effect.

The effect must use INVALID_ARGUMENTS return code if the feature ID is unknown.If the effect does not support getting vendor-specific feature configs, it must return NOT_SUPPORTED.

Use this method only if the effect is provided by a third party, and there is no interface defined for it.This method only works for effects implemented in software.

Details
Parameters
featureId
feature identifier.
configSize
size of the config in bytes.
Generates
retval
operation completion status.
configData
config data.
Annotations
callflow
next= { "*" }

setCurrentConfigForFeature

setCurrentConfigForFeature (uint32_t featureId, vec<uint8_t> configData)
generates (Result retval)

Set the current config for a vendor-specific feature.The config data is not interpreted by Android Framework and is passed as-is between the application and the effect.

The effect must use INVALID_ARGUMENTS return code if the feature ID is unknown.If the effect does not support getting vendor-specific feature configs, it must return NOT_SUPPORTED.

Use this method only if the effect is provided by a third party, and there is no interface defined for it.This method only works for effects implemented in software.

Details
Parameters
featureId
feature identifier.
configData
config data.
Generates
retval
operation completion status.

close

close ()
generates (Result retval)

Called by the framework to deinitialize the effect and free up all the currently allocated resources.It is recommended to close the effect on the client side as soon as it is becomes unused.

Details
Generates
retval
OK in case the success.INVALID_STATE if the effect was already closed.
Annotations
exit