|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-39B5850D-EAAD-56BC-B75A-2104033814E6" xml:lang="en"><title>Audio |
|
13 Component Framework Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This document provides an overview of the Audio Component Framework (ACF) |
|
15 API. </p> |
|
16 <section><title>Purpose</title> <p>In the Advanced Audio Adaptation Framework |
|
17 (A3F) architecture, the client defines the required audio functionality by |
|
18 grouping several audio processing units together. Audio processing units are |
|
19 logical entities, not directly related to any specific audio hardware, that |
|
20 represent basic audio functions. Examples of audio processing units include: </p> <ul> |
|
21 <li id="GUID-847A0149-C870-58CD-8E13-E5072E12A3E4"><p>Source - a source of |
|
22 multimedia data. </p> </li> |
|
23 <li id="GUID-E22F1EEC-4E5F-51BD-89FC-D066485CA144"><p>CODEC - an encoder or |
|
24 decoder of multimedia data. </p> </li> |
|
25 <li id="GUID-782A83BA-A95A-55B7-955C-9F0440698D67"><p>Sink - a consumer of |
|
26 multimedia data. </p> </li> |
|
27 </ul> <p>ACF provides a collective notion for the audio processing units being |
|
28 grouped together so that they can be considered as a single entity. Audio |
|
29 processing units are grouped into audio streams. An audio stream consists |
|
30 of at least a source, a codec and a sink. The audio stream allows control |
|
31 of the audio processing units connected to the stream, for example, starting |
|
32 or pausing, and also provides information about the state of the audio processing |
|
33 units connected to it, for example, uninitialized or active. </p> <p>Furthermore, |
|
34 one or more audio streams can be grouped into a logical unit called a context. |
|
35 The following diagram shows a context which contains two audio streams: </p> <fig id="GUID-3E0CDA7E-7B25-5407-9276-8397C4FFEAFE"> |
|
36 <title> Audio streams in a context </title> |
|
37 <image href="GUID-5673347B-DA7B-563A-AB2B-615BF7C19F92_d0e331113_href.png" placement="inline"/> |
|
38 </fig> <p>Using a context means that, for the purposes of pre-emption, all |
|
39 audio streams in the context can be controlled as a single unit. For example, |
|
40 if an audio stream needs to be stopped because it uses a resource that is |
|
41 required by another higher priority audio stream, then all the other audio |
|
42 streams in the context can be stopped at the same time. </p></section> |
|
43 <section><title>Audio Component Framework API Library Details</title><p>The |
|
44 DLL that provides the functionality and the library to which your code must |
|
45 link is identified below. </p><table id="GUID-254DCB0A-F62E-558C-97D2-1A9141AA4AB6"> |
|
46 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
47 <thead> |
|
48 <row> |
|
49 <entry>DLL</entry> |
|
50 <entry>LIB</entry> |
|
51 <entry>Short Description</entry> |
|
52 </row> |
|
53 </thead> |
|
54 <tbody> |
|
55 <row> |
|
56 <entry><p> <filepath> audiocontextfactory.dll</filepath> </p> </entry> |
|
57 <entry><p> <filepath> audiocontextfactory.lib</filepath> </p> </entry> |
|
58 <entry><p>These files are used for implementing the ACF API. </p> </entry> |
|
59 </row> |
|
60 </tbody> |
|
61 </tgroup> |
|
62 </table></section> |
|
63 <section><title>Architectural Relationship</title> <p>This API is part of |
|
64 the Advanced Audio Adaptation Framework (A3F). A3F provides a new standardised |
|
65 implementation of DevSound which is configured by default from Symbian OS |
|
66 v9.5 onwards. A3F interacts with a specially customised DevSound (configured |
|
67 as optional) through the <xref href="GUID-06A43E09-CC6D-5799-A0F7-68B5696F4ADB.dita">Audio |
|
68 Component Library (ACL) API</xref> and the ACF API. </p> </section> |
|
69 <section><title>Description</title> <p>ACF is responsible for delivering transactional |
|
70 behaviour. This means ensuring that when a change is applied to one audio |
|
71 processing unit in a context, the same change is applied to all the audio |
|
72 processing units in the context and if any fail then no change is made. </p> <p>In |
|
73 order to apply changes to the audio processing units in a context, the client |
|
74 must call the asynchronous <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>Commit()</apiname></xref> method. |
|
75 On success, event callbacks are sent to the client to state that the <codeph>Commit()</codeph> was |
|
76 properly received and processed. If the <codeph>Commit()</codeph> fails, then |
|
77 the implementation is "rolled-back". Alternatively, the client may receive |
|
78 an event callback stating that audio resources were lost due to pre-emption |
|
79 by a higher priority audio client. </p> </section> |
|
80 <section><title>Key Audio Component Framework API Classes</title> <p>ACF comprises |
|
81 the following key classes: </p> <ul> |
|
82 <li id="GUID-4A037A0A-A46D-518F-99B3-AE3D92BCC871"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioSource</apiname></xref> - |
|
83 generic interface for different types of audio sources. </p> </li> |
|
84 <li id="GUID-8C469302-B029-52BB-A1F0-F1E1923DBE47"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioCodec</apiname></xref> - |
|
85 the generic abstract interface for codecs. </p> </li> |
|
86 <li id="GUID-2D73E73F-F3F4-5E5E-9A0D-ACEDD7B2572A"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname> MAudioSink</apiname></xref> - |
|
87 generic interface for different types of audio sinks. </p> </li> |
|
88 <li id="GUID-40072A7A-5964-5117-8664-866B03A31B90"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioStream</apiname></xref> - |
|
89 the main control interface for the state of an audio stream. </p> </li> |
|
90 <li id="GUID-253D92F4-5280-5A3A-8836-F4DA90394901"><p> <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioContext</apiname></xref> - |
|
91 the interface to an audio context. The client can use <codeph>MAudioContext</codeph> to |
|
92 manage the audio streams and audio processing units contained in a context. </p> </li> |
|
93 </ul> </section> |
|
94 <section><title>Using Audio Component Framework API</title> <p>ACF can be |
|
95 used to: </p> <ul> |
|
96 <li id="GUID-1A8CAC71-EB84-5DA6-8A0E-070207721372"><p>Apply changes made to |
|
97 the audio processing units in a context. </p> <p>Pending changes are applied |
|
98 using the asynchronous <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>Commit()</apiname></xref> call. |
|
99 When a <codeph>Commit()</codeph> has been completed, the client is informed |
|
100 by the appropriate <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>ContextEvent()</apiname></xref> callback |
|
101 of <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioContextObserver</apiname></xref>. </p> </li> |
|
102 </ul> </section> |
|
103 <section><title>See Also</title> <p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita">Audio |
|
104 Component Framework Tutorial</xref> </p> <p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita">Audio |
|
105 Processing Tutorial</xref> </p> </section> |
|
106 </conbody></concept> |