Audio Effects API Specification

Contents 1 Overview 1.1 Description 1.2 Changes 1.3 Class Structure 2 Using The API 2.1 Required steps to start using the API 2.2 Using the equalizer effect 2.3 Memory and Performance Considerations 2.4 Extensions to the API 2.5 Error handling 3 Glossary 3.1 Abbreviations 3.2 Definitions 4 References

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 category	public
API type	c++
API libraries	AudioEqualizerEffect.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
Location	/sf/os/mmaudio/mmaudio_pub/audio_effects_api
Buildfiles	/sf/os/mmaudio/mmaudio_pub/audio_effects_api/group/bld.inf

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

Classes	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:

• MDA Client Utility APIs are defined by CMdaAudioConvertUtility , CMdaAudioInputStream , CMdaAudioOutputStream , CMdaAudioPlayerUtility , and CMdaAudioRecorderUtility . These utilities are application-level APIs that offer audio client applications the ability to play, record, or convert audio.
• Custom Command API is a generic interface that encapsulates the Custom Command APIs provided by the MDA Client Utility API. A custom command is a custom message sent from the client to the controller through the Custom Command API.
• Custom Interface API is a generic mechanism for clients to retrieve an interface object by specifying the interface UID. Once retrieved, the client uses the interface as a normal API.
• MMF DevSound API is an interface to the adaptation layer of the audio subsystem.

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.

• Create the effect. The equalizer effect is created using the usual NewL() method. The client may register an observer with the effect. The effect is then ready to be used.

• Change the effect settings. After the creation, the equalizer object assumes an initial state. The initial equalizer value varies and is set by the underlying audio system. Settings are made using one of the available set methods on the object. In this example, the preset values in the equalizer are checked and the values are then changed. Before the equalizer preset is applied, it is possible to change the value many times.

• Apply the effect settings. Effect settings are applied using Enable() or ApplyL(). Initially, all effects are disabled. The Enable() method must be used to enable the effect if it is disabled. Enabling causes the effect settings to be applied. After the effect is enabled, new settings are applied by using the ApplyL() method. The following diagram shows a new setting being applied after the effect is enabled.

• Report spontaneous events. Events may occur spontaneously during the lifetime of the effect. These events are reported to the client through the EffectChange() callback. Clients receive event notifications after successful registration. Refer to the Create the effect section above for the registration sequence. If clients do not want to receive further event notifications, use the UnregisterObserver() method. It is recommended to monitor the events if the effect is enabled. In the following diagram the effect cannot be applied when the client attempts to apply the effect on the stream. In such a case, the effect does not have update rights. In addition, because the client indicates that the effect must be enforced, the stream is pre-empted.

• Disable and remove the effect. An effect can be disabled using the DisableL() method. After an effect is disabled, the effect can be removed by deleting the object. The client can also delete the effect without disabling it first.

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:

• KErrAccessDenied - Attempting to apply effect settings when the effect has lost update rights.
• KErrArgument - Attempting to set an effect setting to an invalid value.
• KErrNoMemory - Insufficient amount of memory available to carry out the operation.
• KErrNotSupported - The specified effect is not supported during the effect creation process.

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 -

http://www.symbian.com/