Audio Effects API Specification


1 Overview

The Audio Effects API supports audio related effects such as equalizer and reverb. These APIs provide the mechanism of passing requests over the DevSound process boundary. The adaptation components implement these APIs.

API categorypublic
API typec++
API librariesAudioEqualizerEffect.lib, BassBoostEffect.lib, DistanceAttenuationEffect.lib, DopplerBase.lib, EffectBase.lib, EnvironmentalReverbEffect.lib, ListenerDopplerEffect.lib, ListenerLocationEffect.lib, ListenerOrientationEffect.lib, LocationBase.lib, LoudnessEffect.lib, OrientationBase.lib, RoomLevelEffect.lib, SourceDopplerEffect.lib, SourceLocationEffect.lib, SourceOrientationEffect.lib, StereoWideningEffect.lib

1.1 Description

The Effect API gives audio applications the ability to control audio effects. Audio effects are abstractions of audio processing that apply artificial sounds or enhancements to audio. The Audio Effect API relies on the Effects Framework to communicate with software or hardware entities that handle audio effects processing.

1.2 Changes

The Effect API is introduced in Symbian OS, S60 3.0. The Effects Framework makes extensive use of the custom command facility that requires a controller plug-in capable of supporting custom commands defined for the Effects Framework. These custom commands are supported in Symbian OS, S60 3.0 or higher.

1.3 Class Structure

Summary of API classes and header files
CAudioEffect /epoc32/include/AudioEffectBase.h CAudioEqualizer /epoc32/include/AudioEqualizerBase.h CBassBoost /epoc32/include/BassBoostBase.h CDistanceAttenuation /epoc32/include/DistanceAttenuationBase.h CDoppler /epoc32/include/DopplerBase.h CEnvironmentalReverb /epoc32/include/EnvironmentalReverbBase.h CListenerDoppler /epoc32/include/ListenerDopplerBase.h CListenerLocation /epoc32/include/ListenerLocationBase.h CListenerOrientation /epoc32/include/ListenerOrientationBase.h CLocation /epoc32/include/LocationBase.h CLoudness /epoc32/include/LoudnessBase.h COrientation /epoc32/include/OrientationBase.h CRoomLevel /epoc32/include/RoomLevelBase.h CSourceDoppler /epoc32/include/SourceDopplerBase.h CSourceLocation /epoc32/include/SourceLocationBase.h CSourceOrientation /epoc32/include/SourceOrientationBase.h CStereoWidening /epoc32/include/StereoWideningBase.h MAudioEffectObserver /epoc32/include/MAudioEffectObserver.h MAudioEqualizerObserver /epoc32/include/MAudioEqualizerObserver.h MBassBoostObserver /epoc32/include/MBassBoostObserver.h MDistanceAttenuationObserver /epoc32/include/MDistanceAttenuationObserver.h MDopplerObserver /epoc32/include/MDopplerObserver.h MEnvironmentalReverbObserver /epoc32/include/MEnvironmentalReverbObserver.h MLocationObserver /epoc32/include/MLocationObserver.h MOrientationObserver /epoc32/include/MOrientationObserver.h MRoomLevelObserver /epoc32/include/MRoomLevelObserver.h MStereoWideningObserver /epoc32/include/MStereoWideningObserver.h TEfAudioEqualizer /epoc32/include/AudioEqualizerData.h TEfAudioEqualizerBand /epoc32/include/AudioEqualizerData.h TEfAudioEqualizerCombined /epoc32/include/AudioEqualizerData.h TEfBassBoostData /epoc32/include/BassBoostData.h TEfCommon /epoc32/include/AudioEffectData.h TEfDistanceAttenuation /epoc32/include/DistanceAttenuationData.h TEfDoppler /epoc32/include/DopplerData.h TEfEnvironmentalReverb /epoc32/include/EnvironmentalReverbData.h TEfLocation /epoc32/include/LocationData.h TEfLoudnessData /epoc32/include/LoudnessData.h TEfOrientation /epoc32/include/OrientationData.h TEfRoomLevel /epoc32/include/RoomLevelData.h TEfStereoWidening /epoc32/include/StereoWideningData.h No classes/epoc32/include/MListenerDopplerObserver.h, /epoc32/include/MListenerLocationObserver.h, /epoc32/include/MListenerOrientationObserver.h, /epoc32/include/MLoudnessObserver.h, /epoc32/include/MSourceDopplerObserver.h, /epoc32/include/MSourceLocationObserver.h, /epoc32/include/MSourceOrientationObserver.h

The Audio Effects API includes one or more of following interfaces:


All the Effect interfaces are method calls. However, the Effects Framework relies on the MMF Controller Framework, which has a client-server boundary. When a client issues requests, the requests and data are encapsulated into messages that can be passed across the client-server boundary. Synchronous method calls block the client thread until they return. However, most of the client method calls do not require a message to be sent. The methods that do generate a message are completed immediately when possible.

2 Using The API

2.1 Required steps to start using the API

  • Each effect is associated with an audio stream. This association with the audio stream is made when the effect is created by passing in the MDA utility that controls the audio stream in the effect's NewL method. A client application creates the effect after the application initializes the MDA audio utility but before the application starts playing the audio. On the contrary, the effect is deleted before the MDA utility is deleted.
  • By default, an effect is disabled when it is created. After it is created, the application can configure the effect and then enable it. Some effects can be configured and enabled when they are constructed.
  • To configure an effect, the application calls the appropriate set methods on the effect. After the effect is configured, the application then calls the ApplyL() method on the effect to apply the new settings. Settings are automatically applied when they are enabled or disabled.
  • Effect processing is started by calling the EnableL() method on the effect. Enabling an effect that is already enabled does nothing. To stop processing an effect, the DisableL() method on the effect is called. Disabling an effect that is already disabled does nothing.
  • It is possible for an application to update the settings of an effect when the audio is playing, but it depends on the specific hardware and drivers of a device whether these changes will have an effect.
  • Due to hardware limitations, it is possible that some hardware platforms can only support a limited number of instances of a specific effect. In this case, the effect is not applied to the lowest priority audio streams. By default, the audio drivers continues playing the audio streams without the effect applied. However, if the application does not want the audio to play without the effect applied, it can call the Enforce method on the effect. In this case, the audio pre-empts the audio stream through the utility that controls that audio stream with the KErrEnforcedEffectPreempted error.
  • Depending on hardware capability, it is also possible to have one setting for an effect type that is being applied to multiple streams. In this case, only the highest-priority audio stream is allowed to modify the effect parameters. When the priorities of the audio streams are the same, the application that sets up the effect last is the one that is allowed to modify the effect parameters. Applications that lose the right to update the effect are notified through the observer interface with the KLostUpdateRights event. When an application regains the right to control the effects settings, it is notified through the observer interface with the KGaindUpdateRights event. By default, all effects initially have the update rights.
  • Effect processing is optional. When it is not supported, the NewL() methods for the effects leaves with KErrNotSupported. Even if effect processing is supported, it is not guaranteed that every method of an effect is implemented. In this case, unsupported operations on the effect are ignored by the audio system.
  • Currently, Tone and Stream Utilities do not support custom interfaces. NewLs with custom interfaces as arguments leaves with KErrNotSupported.
  • All the x, y and z coordinates that used in those 3D Effect (Doppler, Orientation and Location) follow the right-handed coordinate system.

2.2 Using the equalizer effect

This example shows how a client audio application uses the equalizer effect. Note that an MDA Player utility must be created first and must not be deleted before the equalizer effect is deleted. The following steps and diagrams illustrate the stages of the equalizer effect lifecycle. All effects have similar sequences while their operations and events may be different.


2.3 Memory and Performance Considerations

For each effect interface object created, there are two additional support objects and an adaption custom interface effect object created. The size of the support object depends on the effect type. Some effects have larger data structures than others. However, in general, each effect object requires an estimated 2-KB RAM.

2.4 Extensions to the API

The basic functionality of an Effect API can be extended, but this may introduce binary compatibility issues if the interface class is changed. However, new effect classes with additional functionality can be created through derivation.

2.5 Error handling

The leave mechanism of the Symbian platform is used to handle exception situations. Each leaving method has a list of possible leave codes and the meaning of the code. Clients are required to TRAP the leaving methods and handle them appropriately or leave it up to a higher-level TRAP harness.

A number of error conditions can occur when the Effect APIs are used. Each Effect API has different error conditions. The errors common to all effects are listed as follows:

3 Glossary

3.1 Abbreviations

  • API - Application Program Interface
  • DLL - Dynamic Link Library
  • HW - Hardware
  • ID - Identifier
  • mB - Millibel
  • MMF - Multimedia Framework

3.2 Definitions

  • Adaptation Layer - The software layer closer to the hardware platform. This requires implementation and adapts to hardware peculiarities. In the context of the Effects Framework, the software below the MMFDevSound API is considered adaptation.
  • Audio Effects - Artificially created or enhanced sounds.
  • Custom Command - A mechanism for the controller plug-in to extend the basic API. It allows clients to send custom messages to the controller.
  • Custom Interface - A mechanism for the controller plug-in to extend the basic API. It allows clients to retrieve an interface by specifying the interface UID.
  • Effects Framework - Made up of a set of client-level APIs and callback interfaces that enable audio effects to be realized within the Multimedia Framework.

4 References

  • SGL.GT0137.504 How to use the Client MMF API -