<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD" xml:lang="en"><title>Audio

Component Framework Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This tutorial describes how to use the Audio Component Framework (ACF). </p>

<section><title>Purpose</title> <p>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. </p> <p><b>Required

Background</b> </p> <p>The following entities, specific to the Advanced Audio

Adaptation Framework (A3F), are used to create an audio processing group: </p> <ul>

<li id="GUID-437689C6-7501-5BBA-BC9C-CE35B6A104C7"><p>Context - one or more

audio streams. </p> </li>

<li id="GUID-D9B2967A-6BED-54DD-B1CF-90E9BCC60A79"><p>Audio stream - a source,

a codec and a sink. </p> </li>

<li id="GUID-18329FD1-5363-57E4-BA69-4B737F58879D"><p>Source - a source of

multimedia data. </p> </li>

<li id="GUID-B1158E48-D25E-5B54-BF27-435C4C6059C7"><p>Codec - an encoder or

decoder of multimedia data. </p> </li>

<li id="GUID-7BB58E22-E16A-5916-9A42-C2244904217C"><p>Gain control - a controller

of gain balance. </p> </li>

<li id="GUID-58F62DBD-7F05-59CD-8FCD-20095A4D10F8"><p>Sink - a consumer of

multimedia data. </p> </li>

</ul> <p><b>Introduction</b> </p> <p>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. </p> </section>

<section><title>Using ACF </title> <p>The framework described in this document

allows you to manage and manipulate an audio processing group. </p> <p><b>Basic

Procedure</b> </p> <p>The high level steps to create a context are shown here: </p> <ol id="GUID-269C487C-3778-586C-8B4D-6FA44FC14B65">

<li id="GUID-153626D8-0BE8-520A-9309-EEF8F588872F"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-DD660782-09C6-5F45-9E1B-F9F1BAF48759">Create an ACF Factory</xref>  </p> </li>

<li id="GUID-2DC88104-A404-5AAA-9293-77AD3CA3029C"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-9027F6F9-F8AB-5A87-A1D3-9A554C014296">Create and Configure the Context</xref>  </p> </li>

<li id="GUID-2F225F37-F1D5-55B3-A3D6-CEC6F9ED4D61"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-97F42EDA-96C6-53DC-926D-20EE32660730"> Create and Configure the Audio Stream</xref>  </p> </li>

<li id="GUID-0371A58A-47A6-5004-BC47-B844B16588F8"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-72F15689-BF39-5B01-BF77-5E3AA5258992">Add the Audio Source</xref>  </p> </li>

<li id="GUID-217A1FBF-11AA-5F34-9597-9DBA8B3418D3"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-CB8D6E17-4977-590C-8153-0D0403370583"> Add the Audio Codec</xref>  </p> </li>

<li id="GUID-0D6331F7-153D-5DB0-AF5A-7848C7A9B4B4"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-A2B536EF-3188-55FA-965A-F648742A94F8">Add the Audio Sink</xref>  </p> </li>

<li id="GUID-78ED0513-F30E-5A2C-B65B-0F07BD10491F"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-F4E5DAD7-74D0-5946-98E5-D13C3FDF0F0D"> Commit the Changes</xref>  </p> </li>

<li id="GUID-90BE6318-8993-5B60-86DC-81B810388990"><p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita#GUID-931207BE-3561-562D-8F67-0FB52CFF83CD/GUID-A09373E4-877F-5738-89CC-8D3F2CE52FC2">Initialize the Audio Stream</xref>  </p> </li>

</ol> <p id="GUID-DD660782-09C6-5F45-9E1B-F9F1BAF48759"><b>Creating an ACF Factory</b> </p> <p>The

steps to create an ACF Factory are shown here: </p> <ul>

<li id="GUID-AD1CAAA7-6E8F-578D-9968-C9338C0FBAD8"><p>Construct a new instance

of <codeph>CAudioContextFactory</codeph> using the <xref href="GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73.dita#GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73/GUID-D8C563D4-34AC-3460-BE6F-A19D3B1D5D23"><apiname>CAudioContextFactory::NewL()</apiname></xref> factory

function. </p> <codeblock id="GUID-6BB8B93D-9506-507C-A946-C410CF69B711" xml:space="preserve">IMPORT_C static CAudioContextFactory* NewL();</codeblock> </li>

</ul> <p id="GUID-9027F6F9-F8AB-5A87-A1D3-9A554C014296"><b>Creating and Configure the

Context</b> </p> <p>The steps to create and configure the context are shown

here: </p> <ol id="GUID-5462F1CE-8F88-5403-A8A9-764A46886553">

<li id="GUID-6EB47771-E421-5220-9521-A9D082096233"><p>Call <xref href="GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73.dita#GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73/GUID-59496D3F-A541-35AA-BADB-28E487503955"><apiname>CAudioContextFactory::CreateAudioContext()</apiname></xref> to

create the new context. </p> <codeblock id="GUID-480E8697-ACA4-56E6-97B9-756B45F4D7EF" xml:space="preserve">IMPORT_C TInt CreateAudioContext(MAudioContext*&amp; aContext);</codeblock> </li>

<li id="GUID-6BC71F5F-51BD-5ED6-90A7-263566856518"><p>Set the client information

for the new context by calling <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-AC784D04-E300-3295-9FA0-7D4E3F7BC768"><apiname>MAudioContext::SetClientSettings()</apiname></xref>.

Client settings contain information about the client application utilising

the audio functionality. </p> <codeblock id="GUID-22A53038-3363-5AC7-AA58-B6C9B015FC9D" xml:space="preserve">virtual TInt SetClientSettings(const TClientContextSettings&amp; aSettings)=0;</codeblock> <p> <b>Note:</b> This must be called before any call to <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref>. </p> </li>

<li id="GUID-0C3D2D9C-3211-50E6-A581-A85207E8F3A2"><p>Register a context observer

using <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-AE870243-CC91-3259-9525-8BB6A5BECEDA"><apiname>MAudioContext::RegisterAudioContextObserver()</apiname></xref>. </p> <codeblock id="GUID-AF678CDA-D78A-58D2-B123-BD04A2C1538A" xml:space="preserve">virtual TInt RegisterAudioContextObserver(MAudioContextObserver&amp; aObserver) = 0;</codeblock> </li>

</ol> <p id="GUID-97F42EDA-96C6-53DC-926D-20EE32660730"><b>Creating and Configuring

an Audio Stream</b> </p> <p>The steps to create and configure an audio stream

are shown here: </p> <ol id="GUID-8638DCAA-226E-5344-9371-6E804D9E53F0">

<li id="GUID-6783138A-BDD3-5F71-983C-C734C23CE847"><p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-E05FA869-2B49-319C-9172-2A7F40338F92"><apiname>MAudioContext::CreateAudioStream()</apiname></xref> to

add a new audio stream to the existing context. </p> <codeblock id="GUID-2B99714B-E38A-5913-B2B0-7CB1252CCFE3" xml:space="preserve">virtual TInt CreateAudioStream(MAudioStream*&amp; aStream)=0;</codeblock> </li>

<li id="GUID-191EE083-1AA1-5665-8F01-E4AB738D114B"><p>Set the type of audio

being processed in the audio stream by calling <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-DB79EE0B-128D-3F54-8220-F0860085BF20"><apiname>MAudioStream::SetAudioType()</apiname></xref>. </p> <codeblock id="GUID-E37BCB2A-1E37-5178-A01E-387D6C74C9F7" xml:space="preserve">virtual TInt SetAudioType(const TAudioTypeSettings&amp; aAudioTypeSettings)=0;</codeblock> </li>

<li id="GUID-81E11C16-7D5C-501B-8C97-C3CBB9FA62D7"><p>Register an audio stream

observer by calling <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-7A67C317-826C-33B2-B586-3F295B700A28"><apiname>MAudioStream::RegisterAudioStreamObserver()</apiname></xref>. </p> <codeblock id="GUID-EAC5AE8D-4684-5864-9D5C-3A4F7F5C10B9" xml:space="preserve">virtual TInt RegisterAudioStreamObserver(MAudioStreamObserver&amp; aObserver)=0;</codeblock> </li>

<li id="GUID-4EB3CA79-3800-545B-B1ED-4983119F8837"><p>Set the audio configuration

using <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-79DB5B64-9289-3033-A55B-AF9E66D9C8FE"><apiname>MAudioStream::SetConfiguration()</apiname></xref>. </p> <codeblock id="GUID-13BB80D5-772C-5911-96AF-1E6368B0481A" xml:space="preserve">virtual TInt SetConfiguration(const TAudioConfiguration&amp;  aConfig)=0;</codeblock> </li>

</ol> <p id="GUID-72F15689-BF39-5B01-BF77-5E3AA5258992"><b>Adding a Source</b> </p> <p>The

audio stream cannot operate until a source, a codec and a sink have been added.

To add a source: </p> <ol id="GUID-2AF428FA-EEAC-5A7B-A889-873BF1FF56D3">

<li id="GUID-9F966F71-069C-590B-8198-FB23390486A1"><p>Create a new audio processing

unit by calling <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-989C9D1A-C208-3515-BD71-E578365B5996"><apiname>MAudioContext::CreateAudioProcessingUnit()</apiname></xref>. </p> <codeblock id="GUID-F1E16AA9-40E3-5B48-87C2-93456DF0B32E" xml:space="preserve">virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*&amp; aProcessingUnit)=0;</codeblock> </li>

<li id="GUID-E5A75B70-B2F3-5E1D-B054-A9C103918E08"><p>Call <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-7EEDFC7D-338B-320E-9F5D-86A87ED9C75E"><apiname>MAudioStream::AddSource()</apiname></xref> to

add a source for the audio stream. </p> <codeblock id="GUID-15FDCAC5-0F0F-5853-94CB-D929268505B3" xml:space="preserve">virtual TInt AddSource(MAudioProcessingUnit* aSource)=0;</codeblock> <p> <b>Note:</b> This call is asynchronous, if <codeph>KErrNone</codeph> is

returned, there will be a subsequent callback on <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-3D1B6F92-0363-3101-90F7-792B597A90CD"><apiname>MAudioStreamObserver::AddProcessingUnitComplete()</apiname></xref>. </p> </li>

</ol> <p id="GUID-CB8D6E17-4977-590C-8153-0D0403370583"><b>Adding a Codec</b> </p> <p>To

add a codec: </p> <ol id="GUID-2287DB65-C53F-5453-8681-18463392040D">

<li id="GUID-AC11195A-4760-5416-A270-42D45592AF57"><p>Create another new audio

processing unit by calling <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-989C9D1A-C208-3515-BD71-E578365B5996"><apiname>MAudioContext::CreateAudioProcessingUnit()</apiname></xref>. </p> <codeblock id="GUID-4819B6BF-AD60-50D5-A176-FAA905DEDC8E" xml:space="preserve">virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*&amp; aProcessingUnit)=0;</codeblock> </li>

<li id="GUID-AF4A8DA1-2540-5C6D-B905-006B2702E964"><p>Call <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-FF7925E4-4E7D-3996-A1EB-64B8C0F5AE81"><apiname>MAudioStream::AddAudioCodec()</apiname></xref> to

add the codec. </p> <codeblock id="GUID-9E587B45-5F65-5DD6-82D0-4BE5D3757A54" xml:space="preserve">virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec)=0;</codeblock> <p> <b>Note:</b> This call is asynchronous, if <codeph>KErrNone</codeph> is

returned, there will be a subsequent callback on <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-3D1B6F92-0363-3101-90F7-792B597A90CD"><apiname>MAudioStreamObserver::AddProcessingUnitComplete()</apiname></xref>. </p> </li>

</ol> <p id="GUID-A2B536EF-3188-55FA-965A-F648742A94F8"><b>Adding a Sink</b> </p> <p>To

add a sink: </p> <ol id="GUID-4BD12D1E-5230-5A60-9552-E02C5CB0F089">

<li id="GUID-BE2E694B-1E7A-573E-9399-74A51493AD43"><p>Create another audio

processing unit by calling <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-989C9D1A-C208-3515-BD71-E578365B5996"><apiname>MAudioContext::CreateAudioProcessingUnit()</apiname></xref>. </p> <codeblock id="GUID-A41B7B0A-A221-55D3-A12D-9FA67075CA38" xml:space="preserve">virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*&amp; aProcessingUnit)=0;</codeblock> </li>

<li id="GUID-C42682A9-D9D0-59CB-8F69-311ED51ACD82"><p>Call <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-643AD421-6C4B-3B72-A59B-E54CA85B43B3"><apiname>MAudioStream::AddSink()</apiname></xref> to

add the sink for the audio stream. </p> <codeblock id="GUID-A5DE284E-8938-501E-BF6E-742E57C9AD18" xml:space="preserve">virtual TInt AddSink(MAudioProcessingUnit* aSink)=0;</codeblock> <p> <b>Note:</b> This call is asynchronous, if <codeph>KErrNone</codeph> is

returned, there will be a subsequent callback on <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-3D1B6F92-0363-3101-90F7-792B597A90CD"><apiname>MAudioStreamObserver::AddProcessingUnitComplete()</apiname></xref>. </p> </li>

</ol> <p id="GUID-F4E5DAD7-74D0-5946-98E5-D13C3FDF0F0D"><b>Committing the Changes</b> </p> <p>To

apply the changes made to the audio processing group, the client must call

a <xref href="GUID-8330AA6E-8FA1-3F72-8AA6-6C24E9764B4B.dita"><apiname>Commit()</apiname></xref>. The <codeph>Commit()</codeph> call is the mechanism

for implementing requested changes and all changes are considered to be pending

until successfully committed. </p> <p>On success, the client is informed by

the appropriate <xref href="GUID-67CA5D62-BCAA-393B-8452-FB2210859FDA.dita"><apiname>ContextEvent()</apiname></xref> callback. <xref href="GUID-570E513B-55CB-31B0-A325-C910D58C3F2C.dita"><apiname>KUidA3FContextUpdateComplete</apiname></xref> signals

that all changes have been completed and <codeph>Commit()</codeph> can now

be called again, if required. </p> <p> <b>Note:</b> The A3F <codeph>Commit()</codeph> cycle

is transactional, that is, if a <codeph>Commit()</codeph> fails, then all

changes are rolled back. </p> <p>The steps to commit the context are shown

here: </p> <ul>

<li id="GUID-19A12981-9F8D-5B7E-AE85-7E7DA447C7F7"><p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> to

apply the changes to the audio processing group. </p> <codeblock id="GUID-73021763-BBD6-5A4D-B104-CBB048821028" xml:space="preserve">virtual TInt Commit()=0;</codeblock> </li>

</ul> <p id="GUID-A09373E4-877F-5738-89CC-8D3F2CE52FC2"><b>Initializing the Audio Stream</b> </p> <p>During

construction, the audio stream is in the <xref href="GUID-1C3D1D45-FCC4-36DE-A9E8-994AA3987D35.dita"><apiname>EUninitialized</apiname></xref> state.

In order to relate the audio stream to a physical adaptation, it must be transitioned

to the <xref href="GUID-9BC5AFA4-5C7A-3908-9CAB-9BC362D6494A.dita"><apiname>EInitialized</apiname></xref> state.</p> <p>The steps

to initialize the audio stream are shown here: </p> <ol id="GUID-56EF988D-387A-5C7C-A0C2-162695B323B2">

<li id="GUID-C537C9CA-8CD4-55DB-9EF9-E57FB25F07D4"><p>To request a transition

to <codeph>EInitialized</codeph>, call <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-1DFCCA16-7AD0-3AAF-87B8-96F0546DF488"><apiname>MAudioStream::Initialize()</apiname></xref>. </p> <codeblock id="GUID-BA552930-6A5A-57B0-829F-67D681716273" xml:space="preserve">virtual TInt Initialize()=0;</codeblock> </li>

<li id="GUID-12EF44BC-FFD5-5517-86B6-84F63FB2340E"><p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> to

apply the state change. </p> <codeblock id="GUID-B438156F-FBA6-5555-B6C7-440424275BE9" xml:space="preserve">virtual TInt Commit()=0;</codeblock> </li>

</ol> <p> <b>Note:</b> This is one example of a state change to an audio stream.

There are other state changes, for example, the transition from the <xref href="GUID-F424EEAA-C98B-39B2-B19A-FE2A665B02B8.dita"><apiname>EPrimed</apiname></xref> to <xref href="GUID-5DC87A99-1993-34BE-A1AA-84FF98B2ED24.dita"><apiname>EActive</apiname></xref> state

which starts the audio processing. For more information, see <xref href="GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita#GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2/GUID-28D6AB9C-8F4F-573A-853D-726138249390">Stream States</xref> in the <xref href="GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita">Advanced

Audio Adaptation Framework Technology Guide</xref>. </p> </section>

<section><title>See Also</title> <p><xref href="GUID-06A43E09-CC6D-5799-A0F7-68B5696F4ADB.dita">Audio

Component Library Overview</xref>  </p> </section>