<?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 xml:lang="en" id="GUID-06A43E09-CC6D-5799-A0F7-68B5696F4ADB"><title>Audio Component Library Overview </title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document provides an overview of the Audio Component Library (ACL) API. </p> <section><title>Purpose</title> <p>The ACL API is an open-ended library of audio processing units. The ACL API is used to define the audio processing units which can be built into an audio stream. </p> <p><b>Audio Component Library API Library Details</b> </p> <p>The ACL API is implemented using a plugin pattern. </p> <p>The DLL that provides the functionality and the library to which your code must link is identified below. </p> <table id="GUID-F7967E7D-066E-5341-9660-D565319B83DC"><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 ACL 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 ACL API and the <xref href="GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita">Audio Component Framework (ACF) API</xref>. </p> </section> <section><title>Description</title> <p>Audio processing units are logical entities (not directly related to any specific audio hardware) that represent basic audio functions. The ACL API is an open-ended library of such logical audio processing units. The list of audio processing units in the ACL includes: </p> <ul><li id="GUID-8CC2DEB6-99AC-59AF-BE96-666B37B55824"><p>buffer source and sink </p> </li> <li id="GUID-ED8E27D5-C7E2-56CC-8486-6909408E317E"><p>audio device source and sink </p> </li> <li id="GUID-FAF60CA3-3C8D-55EC-A429-A91852EEB4DB"><p>audio codec. </p> </li> </ul> <p>An audio stream links together several audio processing units. The ACL API enables the client to specify an audio stream and the individual audio processing units that it contains. An audio stream represents a connection between: </p> <ul><li id="GUID-EFCC02B3-24C0-59A7-AD12-9BD6AFD5A676"><p>1 source </p> </li> <li id="GUID-9B840546-808A-5586-91B1-6298AFD3C2FD"><p>1 codec (either a decoder or an encoder) </p> </li> <li id="GUID-AE746B34-C3B9-58C4-BB5B-657937DC58C1"><p>0 or 1 gain control </p> </li> <li id="GUID-71FE34AD-B300-5307-8C7A-3125E17B4A67"><p>1 sink. </p> </li> </ul> <p>An audio stream is also responsible for executing audio processing states as requested by the client. The audio processing units contained in an audio stream adapt to state changes as required. The possible states of an audio stream are: </p> <ul><li id="GUID-848DE516-9A98-540F-B31B-7AF5E89B5BA6"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EUninitialized</apiname></xref> - the state an audio stream is in initially. </p> </li> <li id="GUID-2AF888AA-9478-567D-B28F-A403C0326753"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EInitialized</apiname></xref> - the state after a successful initialization request. </p> </li> <li id="GUID-3136A4AF-BFA5-52AA-BA3A-D72485F840DF"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EIdle</apiname></xref> - all resources have been allocated but use no CPU time (other than that expended to put the audio stream into the <codeph>EIdle</codeph> state) is consumed. </p> </li> <li id="GUID-6E0A30BB-CCE3-5FD4-AE22-74836A74B48D"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>EPrimed</apiname></xref> - as with <codeph>EIdle</codeph>, but the audio stream can consume CPU time by filling its buffers. Note that no sound can be played when the audio stream is in <codeph>EPrimed</codeph> state. </p> </li> <li id="GUID-2309CA33-E091-5FB2-BC6C-177F9B1839BC"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EActive</apiname></xref> - all resources have been allocated, as with EIdle and EPrimed, but the audio stream has also started to process the actions requested by the client. </p> </li> <li id="GUID-AB6EAC1B-C87D-5EA4-AE56-ED20CB72973C"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname> EDead</apiname></xref> - the audio stream can no longer function due to a fatal error. </p> </li> </ul> </section> <section><title>Key Audio Component Library API Classes</title> <p>The ACL API comprises the following key classes: </p> <ul><li id="GUID-D5A112BE-C36C-5BEE-B5C6-66670BCF5F7A"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>MAudioStream</apiname></xref> - the main control interface for the state of an audio stream. </p> </li> </ul> </section> <section><title>Using Audio Component Library API</title> <p>The ACL API can be used to: </p> <ul><li id="GUID-332A1636-54F0-57A9-92F1-4B5233D6D39D"><p>Request that the state of an audio stream is changed to another state. The main state transitions are requested using the following methods: </p> <ul><li id="GUID-21E351C1-6177-57F4-9989-8BCF7077C81F"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Initialize()</apiname></xref> - requests a transition to the <codeph>EInitialized</codeph> state. </p> </li> <li id="GUID-B49E5BA7-BE2C-5A08-B6B3-B848564C89BB"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Load()</apiname></xref> - requests a transition to the <codeph>EIdle</codeph> state. </p> </li> <li id="GUID-8336AC1A-0AE5-5984-888A-8BBFCD7BB559"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Activate()</apiname></xref> - starts the audio processing. </p> </li> <li id="GUID-05EDA606-DAE4-50C1-85BE-270E50B4107C"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Stop()</apiname></xref> - requests a transition to the <codeph>EIdle</codeph> state. </p> </li> <li id="GUID-515E479F-8FF9-5865-8DEA-110C1397AF36"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Unload()</apiname></xref> - prepares the audio stream for releasing the resources reserved for it. </p> </li> <li id="GUID-FF553EB2-D02F-5A2E-A21F-0205F41ABB62"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Uninitialize()</apiname></xref> - requests a transition to the <codeph>EUnitialized</codeph> state. </p> </li> <li id="GUID-5D84D8C6-50B6-56AE-A28C-1658B29F9B76"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>Prime()</apiname></xref> - requests a transition to the <codeph>EPrimed</codeph> state. </p> </li> </ul> </li> </ul> </section> <section><title>See Also</title> <p><xref href="GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita">Audio Component Framework Overview</xref>  </p> </section> </conbody></concept>