Audio Component Framework Tutorial

This tutorial describes how to use the Audio Component Framework (ACF).

Purpose

The purpose of this tutorial is to show you how to create an audio processing group containing a context, an audio stream and three audio processing units.

Required Background

The following entities, specific to the Advanced Audio Adaptation Framework (A3F), are used to create an audio processing group:

Context - one or more audio streams.
Audio stream - a source, a codec and a sink.
Source - a source of multimedia data.
Codec - an encoder or decoder of multimedia data.
Gain control - a controller of gain balance.
Sink - a consumer of multimedia data.

Introduction

To define audio functionality, the client must group the required audio processing units into an audio processing group. The starting point for the group is the context. Once a context has been created, an audio stream can be added to it. Once the audio stream has been added, the necessary audio processing units can be added.

Using ACF

The framework described in this document allows you to manage and manipulate an audio processing group.

Basic Procedure

The high level steps to create a context are shown here:

Creating an ACF Factory

The steps to create an ACF Factory are shown here:

Construct a new instance of CAudioContextFactory using the CAudioContextFactory::NewL() factory function.
```
IMPORT_C static CAudioContextFactory* NewL();
```

Creating and Configure the Context

The steps to create and configure the context are shown here:

Call CAudioContextFactory::CreateAudioContext() to create the new context.
```
IMPORT_C TInt CreateAudioContext(MAudioContext*& aContext);
```
Set the client information for the new context by calling MAudioContext::SetClientSettings(). Client settings contain information about the client application utilising the audio functionality.
```
virtual TInt SetClientSettings(const TClientContextSettings& aSettings)=0;
```
Note: This must be called before any call to MAudioContext::Commit().

virtual TInt RegisterAudioContextObserver(MAudioContextObserver& aObserver) = 0;

Creating and Configuring an Audio Stream

The steps to create and configure an audio stream are shown here:

Call MAudioContext::CreateAudioStream() to add a new audio stream to the existing context.
```
virtual TInt CreateAudioStream(MAudioStream*& aStream)=0;
```
Set the type of audio being processed in the audio stream by calling MAudioStream::SetAudioType().
```
virtual TInt SetAudioType(const TAudioTypeSettings& aAudioTypeSettings)=0;
```
Register an audio stream observer by calling MAudioStream::RegisterAudioStreamObserver().
```
virtual TInt RegisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;
```

Set the audio configuration using MAudioStream::SetConfiguration().

virtual TInt SetConfiguration(const TAudioConfiguration&  aConfig)=0;

Adding a Source

The audio stream cannot operate until a source, a codec and a sink have been added. To add a source:

Create a new audio processing unit by calling MAudioContext::CreateAudioProcessingUnit().

virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*& aProcessingUnit)=0;

Call MAudioStream::AddSource() to add a source for the audio stream.
```
virtual TInt AddSource(MAudioProcessingUnit* aSource)=0;
```
Note: This call is asynchronous, if KErrNone is returned, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().

Adding a Codec

To add a codec:

Create another new audio processing unit by calling MAudioContext::CreateAudioProcessingUnit().

virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*& aProcessingUnit)=0;

Call MAudioStream::AddAudioCodec() to add the codec.
```
virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec)=0;
```
Note: This call is asynchronous, if KErrNone is returned, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().

Adding a Sink

To add a sink:

Create another audio processing unit by calling MAudioContext::CreateAudioProcessingUnit().

virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*& aProcessingUnit)=0;

Call MAudioStream::AddSink() to add the sink for the audio stream.
```
virtual TInt AddSink(MAudioProcessingUnit* aSink)=0;
```
Note: This call is asynchronous, if KErrNone is returned, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().

Committing the Changes

To apply the changes made to the audio processing group, the client must call a Commit(). The Commit() call is the mechanism for implementing requested changes and all changes are considered to be pending until successfully committed.

On success, the client is informed by the appropriate ContextEvent() callback. KUidA3FContextUpdateComplete signals that all changes have been completed and Commit() can now be called again, if required.

Note: The A3F Commit() cycle is transactional, that is, if a Commit() fails, then all changes are rolled back.

The steps to commit the context are shown here:

Call MAudioContext::Commit() to apply the changes to the audio processing group.
```
virtual TInt Commit()=0;
```

Initializing the Audio Stream

During construction, the audio stream is in the EUninitialized state. In order to relate the audio stream to a physical adaptation, it must be transitioned to the EInitialized state.

The steps to initialize the audio stream are shown here:

To request a transition to EInitialized, call MAudioStream::Initialize().
```
virtual TInt Initialize()=0;
```
Call MAudioContext::Commit() to apply the state change.
```
virtual TInt Commit()=0;
```

Note: This is one example of a state change to an audio stream. There are other state changes, for example, the transition from the EPrimed to EActive state which starts the audio processing. For more information, see Stream States in the Advanced Audio Adaptation Framework Technology Guide.

Audio Component Framework Tutorial

Purpose

Using ACF

See Also