|
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-CADAFAF2-24E9-5007-9C2F-5453E8062074" xml:lang="en"><title>Initializing |
|
13 DevSound Functionality Tutorial</title><shortdesc>DevSound provides a common interface to the audio hardware for |
|
14 all audio functionality. DevSound is responsible for providing access to available |
|
15 audio resources, initialization and configuration of hardware devices, and |
|
16 playing and recording audio. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 |
|
18 <section id="GUID-5364D394-21F7-5327-BCD3-8F91DB5EEC8D-GENID-1-8-1-18-1-1-11-1-5-1-4-1-5-1-4-1-3-1"><title>Required background</title> <p>Before |
|
19 you start, you must: </p> <ul> |
|
20 <li id="GUID-67BD381F-4B0B-5B87-9439-7B72DBF29AFD"><p>Understand the <xref href="GUID-170A1D9C-12CB-502A-BCB3-9E2AEBB207FA.dita">A3F DevSound Component</xref> to |
|
21 which the DevSound library belongs. </p> </li> |
|
22 <li id="GUID-1E1F544F-06EF-5EFD-981B-8B179E37136E"><p>Understand the architectural |
|
23 relationship of the DevSound. For information see <xref href="GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita">DevSound |
|
24 Overview</xref>. </p> </li> |
|
25 </ul> </section> |
|
26 <section><title>Introduction</title> <p>DevSound's functionality is provided |
|
27 by the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita"><apiname>CMMFDevSound</apiname></xref> class. </p> <p><b>Construction |
|
28 and initialization</b> </p> <p>Each client using audio resources must have |
|
29 an instance of the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita"><apiname>CMMFDevSound</apiname></xref> class associated with it. |
|
30 The <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-088CC167-C46D-3A2B-BE00-D7AEB98254AE"><apiname>CMMFDevSound::NewL()</apiname></xref> method is used to construct a |
|
31 new instance of DevSound. </p> <codeblock id="GUID-7E5C8C3A-B09B-5CC3-870E-1A28C75C50CF" xml:space="preserve">static IMPORT_C CMMFDevSound *NewL();</codeblock> <p>Once |
|
32 created, the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> method is used |
|
33 to initialize DevSound to play and record. There are three versions of the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> method, |
|
34 differing in type and number of parameters. The three versions are: </p> <ul> |
|
35 <li id="GUID-5492383B-33F4-5884-A926-567B49C44948"><p> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> - |
|
36 initializes CMMFDevSound object to play and record PCM16 raw audio data with |
|
37 sampling rate of 8 KHz. </p> <codeblock id="GUID-3FC67F03-CE07-5174-B70A-82C3AC55AC4C" xml:space="preserve">IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TMMFState |
|
38 aMode);</codeblock> <p>This method has two parameters: </p> <ul> |
|
39 <li id="GUID-84931A64-8268-5E15-9FD1-0D8F33CD243B"><p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> - |
|
40 a reference to a DevSound Observer instance. </p> </li> |
|
41 <li id="GUID-AE152880-C8E8-5923-97C6-A3D44B65515B"><p> <xref href="GUID-66044171-C6DA-305C-97D2-181311F9D839.dita"><apiname>TMMFState</apiname></xref> - |
|
42 the mode for which this object is to be used, for example, <codeph>EMMFStatePlaying</codeph>. </p> </li> |
|
43 </ul> </li> |
|
44 <li id="GUID-67B42425-FBD1-5FFA-8382-68E0CD4D2EA8"><p> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> - |
|
45 initializes DevSound object for the mode <codeph>aMode</codeph> for processing |
|
46 audio data with hardware device <codeph>aHWDev</codeph>. </p> <codeblock id="GUID-168BD108-045C-52E9-BB97-BDA05643022F" xml:space="preserve">IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TUid aHWDev, |
|
47 TMMFState aMode);</codeblock> <p>This method has three parameters: </p> <ul> |
|
48 <li id="GUID-917DF4D4-FD55-59EA-B0E8-64A7B5F5F35B"><p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> - |
|
49 a reference to a DevSound Observer instance. </p> </li> |
|
50 <li id="GUID-760E73CF-E957-57B2-9F7B-9C2AACA7B3F3"><p> <xref href="GUID-530281E6-29FC-33F2-BC9B-610FBA389444.dita"><apiname>TUid</apiname></xref> - |
|
51 the <xref href="GUID-E18CF25C-82DE-3C69-BD86-5DF67579C1A6.dita"><apiname>CMMFHwDevice</apiname></xref> implementation identifier. </p> </li> |
|
52 <li id="GUID-33E8A5C9-4609-5B4B-8050-438DF9317BAA"><p> <xref href="GUID-66044171-C6DA-305C-97D2-181311F9D839.dita"><apiname>TMMFState</apiname></xref> - |
|
53 the mode for which this object is to be used, for example, <codeph>EMMFStatePlaying</codeph>. </p> </li> |
|
54 </ul> </li> |
|
55 <li id="GUID-A88F2138-5F4E-527D-8BEA-B27F2D330B83"><p> <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> - |
|
56 initializes DevSound object for the mode <codeph>aMode</codeph> for processing |
|
57 audio data with hardware device supporting FourCC <codeph>aDesiredFourCC</codeph>. </p> <codeblock id="GUID-415E6B82-08A9-5CB8-BA49-F4FA6005E529" xml:space="preserve">IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TFourCC |
|
58 aDesiredFourCC, TMMFState aMode);</codeblock> <p>This method has three parameters: </p> <ul> |
|
59 <li id="GUID-6C1B960C-4455-504A-B115-7FB416D7A288"><p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> - |
|
60 a reference to a DevSound Observer instance. </p> </li> |
|
61 <li id="GUID-7D427CCC-6248-5C79-BB21-8D0E2C43C633"><p> <xref href="GUID-691F7FFC-D026-30D5-B08D-A06915272C92.dita"><apiname>TFourCC</apiname></xref> - |
|
62 the <xref href="GUID-E18CF25C-82DE-3C69-BD86-5DF67579C1A6.dita"><apiname>CMMFHwDevice</apiname></xref> implementation FourCC code. </p> </li> |
|
63 <li id="GUID-D459814C-4892-5A30-B86A-AC125BC9B0F7"><p> <xref href="GUID-66044171-C6DA-305C-97D2-181311F9D839.dita"><apiname>TMMFState</apiname></xref> - |
|
64 the mode for which this object is to be used, for example, <codeph>EMMFStatePlaying</codeph>. </p> </li> |
|
65 </ul> </li> |
|
66 </ul> <p>All versions of <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-CBBB4A4E-0705-37E2-9832-A55861ACF299"><apiname>CMMFDevSound::InitializeL()</apiname></xref> require |
|
67 a reference to a DevSound Observer instance. As soon as initialization of |
|
68 DevSound has completed, successfully or otherwise, the callback function <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita#GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD/GUID-089CF9C1-92EF-3F40-8669-A5EF5C064AD4"><apiname>MDevSoundObserver::InitializeComplete()</apiname></xref> is |
|
69 called. </p> <p><b>The |
|
70 DevSound Observer</b> </p> <p>Most methods in the CMMFDevSound class are asynchronous. |
|
71 Callbacks occur through the <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> class. <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> is |
|
72 an interface to a set of DevSound callback functions. It serves as the method |
|
73 of communication between the client and the DevSound. A class that uses DevSound |
|
74 will typically inherit from <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref>. </p> <p> <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> handles |
|
75 the <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita#GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD/GUID-089CF9C1-92EF-3F40-8669-A5EF5C064AD4"><apiname>MDevSoundObserver::InitializeComplete()</apiname></xref> initialization |
|
76 completion event. </p> </section> |
|
77 <section><title>Purpose</title> <p>Refer to the following sections for detailed |
|
78 information on how to use the main features of DevSound: </p> <ul> |
|
79 <li id="GUID-5FC7D66B-50C0-5229-A343-80FA4E865828"><p><xref href="GUID-53A5AC8D-8A43-505F-A0B6-9E34F3CF23BE.dita">Playing |
|
80 Audio</xref> </p> </li> |
|
81 <li id="GUID-E5B271E4-F39B-5E75-BEEA-34AF087B8DDF"><p><xref href="GUID-3FC6342D-D09C-5C7F-8E03-3DA7B29D2CC8.dita">Recording |
|
82 Audio</xref> </p> </li> |
|
83 <li id="GUID-BCC46964-D281-50B3-82E6-1A3CDC025455"><p><xref href="GUID-14BAAB7C-35CD-5A43-B362-79F88C7712DE.dita">Playing |
|
84 Tones</xref> </p> </li> |
|
85 </ul> </section> |
|
86 <section><title>Example uses</title> <p>These examples describe some different |
|
87 uses of DevSound: </p> <p><b>Recording |
|
88 a WAV file</b> </p> <p>In this example, a client application wants to record |
|
89 a WAV file. As WAV is a standard file format supported by the MMF controller |
|
90 framework, the <xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref> client API is used |
|
91 to interact with DevSound. </p> <p>The main steps in recording the WAV file |
|
92 are: </p> <ol id="GUID-24DBEAE0-D054-53CD-965E-A89B7F66410C"> |
|
93 <li id="GUID-0A785BE2-5896-5490-9C6D-7C66BB575BF5"><p>The client application |
|
94 gives a request to record to the MMF <xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref> client |
|
95 API. </p> </li> |
|
96 <li id="GUID-14622FA3-A7FD-5DDD-9BD6-AD7B4CB9F04C"><p>The MMF <xref href="GUID-29FB1DE6-D00C-3E6B-A8AA-476FAFD7F26C.dita"><apiname>CMdaAudioRecorderUtility</apiname></xref> client |
|
97 API passes the command down through the controller framework to the MMF controller |
|
98 plug-in. </p> </li> |
|
99 <li id="GUID-F0400FAB-4644-5764-B806-FC4F9B3A42DF"><p>The MMF controller plug-in |
|
100 initializes DevSound for recording. </p> </li> |
|
101 <li id="GUID-692A4C69-6E04-52CE-9835-FD4E2B59D498"><p>Recording starts and |
|
102 continues until the client stops the recording or the limit on the file size |
|
103 is reached. </p> </li> |
|
104 <li id="GUID-579CFF58-4C6D-51F1-9249-CB1BCCC7D08F"><p>Upon completion, the |
|
105 client gives a request to the MMF controller framework to stop the recording. |
|
106 The controller framework passes the command down to the MMF controller plug-in. </p> </li> |
|
107 <li id="GUID-8F3214E6-DFA0-533A-BE7F-86657BFE82E0"><p>The MMF controller plug-in |
|
108 stops DevSound and sends the completion event back to the client via controller |
|
109 framework. </p> </li> |
|
110 </ol> <p><b>Playing |
|
111 a DTMF tone</b> </p> <p>In this example, a client application wants to play |
|
112 a Dual-Tone Multi-Frequency (DTMF) tone. The MMF <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> client |
|
113 API is used to play the DTMF tone. Unlike other MMF APIs, the <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> does |
|
114 not require a controller plug-in. This is because the input and output of |
|
115 the API is already in a known data format and does not require encoding or |
|
116 decoding. The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> communicates directly |
|
117 with DevSound. </p> <p>The main steps in playing the DTMF tone are: </p> <ol id="GUID-653E4665-1469-5EDA-B83E-94DB580ECFB0"> |
|
118 <li id="GUID-5B600730-C908-5D5E-9C7E-05B8FAE685AA"><p>The client application |
|
119 prepares the <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> to play a DTMF tone. </p> </li> |
|
120 <li id="GUID-EA9E73E1-AACE-52E8-BF8A-B11FE2117D2C"><p>The client application |
|
121 asks the <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> to start playing the tone. </p> </li> |
|
122 <li id="GUID-4DE7CB4B-3873-5B5E-ADCF-2AC712ADB2C0"><p>The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> asks |
|
123 DevSound to play the tone. </p> </li> |
|
124 <li id="GUID-016EA63D-DF56-5ACC-9A8A-536092EE145F"><p>The <xref href="GUID-D728A286-A202-3915-9643-8FD70646F78A.dita"><apiname>CMdaAudioToneUtility</apiname></xref> informs |
|
125 the client application that the playing of the tone is complete. </p> </li> |
|
126 </ol> <p><b>Playing |
|
127 an AVI file</b> </p> <p>In this example, a client application wants to play |
|
128 an Audio Video Interleaved (AVI) file; output is to a screen and speakers. |
|
129 The AVI file contains audio and video data, so the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita"><apiname>CVideoPlayerUtility</apiname></xref> class |
|
130 that can manipulate both types of data is used. </p> <p>The main steps in |
|
131 playing the AVI file are: </p> <ol id="GUID-D1F0C730-45BF-5B58-BBCE-3483C951BD72"> |
|
132 <li id="GUID-83EF3725-22BE-5140-96C6-8F530DC7AAA3"><p>The client application |
|
133 requests to play an AVI file to the MMF CVideoPlayerUtility class. </p> </li> |
|
134 <li id="GUID-C8C8E7D2-982F-5561-A707-BCC5131E7C8D"><p>The MMF CVideoPlayerUtility |
|
135 class passes the request to the MMF controller framework. The controller framework |
|
136 loads the AVI controller </p> </li> |
|
137 <li id="GUID-980A38CF-CAA3-5A54-8888-A54AACF538B6"><p>The AVI controller plug-in |
|
138 initializes the DevSound and DevVideo. </p> </li> |
|
139 <li id="GUID-46DD25A9-62C1-5B6F-8BC8-21E57BB706F2"><p>The AVI controller plug-in |
|
140 reads the data in the AVI file and sends the audio data to DevSound and the |
|
141 video data to DevVideo. </p> </li> |
|
142 <li id="GUID-CFDEDC57-E5BD-5680-AC20-1A8F10A6328D"><p>DevSound outputs the |
|
143 audio data.</p> </li> |
|
144 <li id="GUID-AB78F54C-76B8-419A-AC24-F22371AFB506"><p>DevVideo sends the video |
|
145 data to be decoded to the corresponding codec. The decoded video data is then |
|
146 displayed on the screen. </p></li> |
|
147 </ol><note> AVI files support Dolby audio also. The client application requests |
|
148 for Dolby play back are processed in the similar way.</note></section> |
|
149 </conbody><related-links> |
|
150 <link href="GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita"><linktext>DevSound |
|
151 Overview</linktext></link> |
|
152 </related-links></concept> |