<?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-39B5850D-EAAD-56BC-B75A-2104033814E6" xml:lang="en"><title>Audio

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

<p>This document provides an overview of the Audio Component Framework (ACF)

API. </p>

<section><title>Purpose</title> <p>In the Advanced Audio Adaptation Framework

(A3F) architecture, the client defines the required audio functionality by

grouping several audio processing units together. Audio processing units are

logical entities, not directly related to any specific audio hardware, that

represent basic audio functions. Examples of audio processing units include: </p> <ul>

<li id="GUID-847A0149-C870-58CD-8E13-E5072E12A3E4"><p>Source - a source of

multimedia data. </p> </li>

<li id="GUID-E22F1EEC-4E5F-51BD-89FC-D066485CA144"><p>CODEC - an encoder or

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

<li id="GUID-782A83BA-A95A-55B7-955C-9F0440698D67"><p>Sink - a consumer of

multimedia data. </p> </li>

</ul> <p>ACF provides a collective notion for the audio processing units being

grouped together so that they can be considered as a single entity. Audio

processing units are grouped into audio streams. An audio stream consists

of at least a source, a codec and a sink. The audio stream allows control

of the audio processing units connected to the stream, for example, starting

or pausing, and also provides information about the state of the audio processing

units connected to it, for example, uninitialized or active. </p> <p>Furthermore,

one or more audio streams can be grouped into a logical unit called a context.

The following diagram shows a context which contains two audio streams: </p> <fig id="GUID-3E0CDA7E-7B25-5407-9276-8397C4FFEAFE">

<title>              Audio streams in a context            </title>

<image href="GUID-5673347B-DA7B-563A-AB2B-615BF7C19F92_d0e324956_href.png" placement="inline"/>

</fig> <p>Using a context means that, for the purposes of pre-emption, all

audio streams in the context can be controlled as a single unit. For example,

if an audio stream needs to be stopped because it uses a resource that is

required by another higher priority audio stream, then all the other audio

streams in the context can be stopped at the same time. </p></section>

<section><title>Audio Component Framework API Library Details</title><p>The

DLL that provides the functionality and the library to which your code must

link is identified below. </p><table id="GUID-254DCB0A-F62E-558C-97D2-1A9141AA4AB6">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>DLL</entry>

<entry>LIB</entry>

<entry>Short Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <filepath> audiocontextfactory.dll</filepath>  </p> </entry>

<entry><p> <filepath> audiocontextfactory.lib</filepath>  </p> </entry>

<entry><p>These files are used for implementing the ACF API. </p> </entry>

</row>

</tbody>

</tgroup>

</table></section>

<section><title>Architectural Relationship</title> <p>This API is part of

the Advanced Audio Adaptation Framework (A3F). A3F provides a new standardised

implementation of DevSound which is configured by default from Symbian OS

v9.5 onwards. A3F interacts with a specially customised DevSound (configured

as optional) through the <xref href="GUID-06A43E09-CC6D-5799-A0F7-68B5696F4ADB.dita">Audio

Component Library (ACL) API</xref> and the ACF API. </p> </section>

<section><title>Description</title> <p>ACF is responsible for delivering transactional

behaviour. This means ensuring that when a change is applied to one audio

processing unit in a context, the same change is applied to all the audio

processing units in the context and if any fail then no change is made. </p> <p>In

order to apply changes to the audio processing units in a context, the client

must call the asynchronous <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>Commit()</apiname></xref> method.

On success, event callbacks are sent to the client to state that the <codeph>Commit()</codeph> was

properly received and processed. If the <codeph>Commit()</codeph> fails, then

the implementation is "rolled-back". Alternatively, the client may receive

an event callback stating that audio resources were lost due to pre-emption

by a higher priority audio client. </p> </section>

<section><title>Key Audio Component Framework API Classes</title> <p>ACF comprises

the following key classes: </p> <ul>

<li id="GUID-4A037A0A-A46D-518F-99B3-AE3D92BCC871"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioSource</apiname></xref> -

generic interface for different types of audio sources. </p> </li>

<li id="GUID-8C469302-B029-52BB-A1F0-F1E1923DBE47"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioCodec</apiname></xref> -

the generic abstract interface for codecs. </p> </li>

<li id="GUID-2D73E73F-F3F4-5E5E-9A0D-ACEDD7B2572A"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname> MAudioSink</apiname></xref> -

generic interface for different types of audio sinks. </p> </li>

<li id="GUID-40072A7A-5964-5117-8664-866B03A31B90"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioStream</apiname></xref> -

the main control interface for the state of an audio stream. </p> </li>

<li id="GUID-253D92F4-5280-5A3A-8836-F4DA90394901"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioContext</apiname></xref> -

the interface to an audio context. The client can use <codeph>MAudioContext</codeph> to

manage the audio streams and audio processing units contained in a context. </p> </li>

</ul> </section>

<section><title>Using Audio Component Framework API</title> <p>ACF can be

used to: </p> <ul>

<li id="GUID-1A8CAC71-EB84-5DA6-8A0E-070207721372"><p>Apply changes made to

the audio processing units in a context. </p> <p>Pending changes are applied

using the asynchronous <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>Commit()</apiname></xref> call.

When a <codeph>Commit()</codeph> has been completed, the client is informed

by the appropriate <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>ContextEvent()</apiname></xref> callback

of <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioContextObserver</apiname></xref>. </p> </li>

</ul> </section>

<section><title>See Also</title> <p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita">Audio

Component Framework Tutorial</xref>  </p> <p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita">Audio

Processing Tutorial</xref>  </p> </section>