<?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-8CCA6352-DC3D-5BFE-9AAF-B70173DF2558"><title>Starting Audio Play </title><shortdesc>This document describes how to play audio using DevSound. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-9C12E745-3DAB-58A0-A6B2-4403CD43BCBE"><title>Introduction</title> <p>To play audio data, you have to do the following: </p> <ul><li id="GUID-46E837E9-CF86-507A-ADC4-C18EF9E4682E"><p><xref href="GUID-8CCA6352-DC3D-5BFE-9AAF-B70173DF2558.dita#GUID-8CCA6352-DC3D-5BFE-9AAF-B70173DF2558/GUID-C66399BB-F588-5831-A7FC-B62240E699CF">Constructing and initializing</xref>  </p> </li> <li id="GUID-823BBD55-CB56-5716-9632-DF7DD8F5DA63"><p><xref href="GUID-8CCA6352-DC3D-5BFE-9AAF-B70173DF2558.dita#GUID-8CCA6352-DC3D-5BFE-9AAF-B70173DF2558/GUID-EC56C43B-D3C3-5956-A1C6-4E60C00552D4">Configuring</xref> </p> </li> </ul> </section> <section id="GUID-C66399BB-F588-5831-A7FC-B62240E699CF"><title>Constructing and initializing</title> <p>Use 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 to construct a new instance of DevSound. </p> <p>After construction, use an <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 to initialize DevSound to play audio. This method requires that you specify the DevSound observer class to handle callbacks. </p> <p>Once initialization has completed, successfully or otherwise, DevSound calls 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> function. </p> </section> <section id="GUID-EC56C43B-D3C3-5956-A1C6-4E60C00552D4"><title>Configuring</title> <p>The following settings can be configured before or during audio play: </p> <ul><li id="GUID-E02E3AC5-8012-5384-AA3E-64551853E35D"><p>To change the volume of the audio device to a specific value, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-C93E8531-F569-3F6B-AE65-A36749FCE7DF"><apiname>CMMFDevSound::SetVolume()</apiname></xref> function. The volume can be set to any value from 0 to <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-1BFCB3CB-17C7-399B-9089-3ADFF43044BA"><apiname>CMMFDevSound::MaxVolume()</apiname></xref>. </p> </li> <li id="GUID-7F1F62F9-138C-59B8-A9FF-D97C4C442CBB"><p>To set the speaker balance, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-0D55BCC4-9882-3F49-B1AD-922B48264F79"><apiname>CMMFDevSound::SetPlayBalanceL()</apiname></xref> function. This function has two parameters: </p> <ul><li id="GUID-122CEEB3-E33F-5AF2-8F11-0CCA336D6308"><p> <codeph>aLeftPercentage</codeph> - the left speaker volume percentage. </p> </li> <li id="GUID-97867944-B2EB-59C1-903C-6E4549F36D4F"><p> <codeph>aRightPercentage</codeph> - the right speaker volume percentage. </p> </li> </ul> </li> <li id="GUID-00D6AC47-CAF7-51E4-B715-B1FDE633EA9D"><p>To set the priority setting for this instance of DevSound to access the audio device, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-1B3B1694-EED8-3B33-B424-C48DDAFBE75A"><apiname>CMMFDevSound::SetPrioritySettings()</apiname></xref> method. Priority settings are used by the Audio Policy component to resolve multiple requests to access the audio hardware. </p> </li> </ul> </section> <section><title>Procedure</title> <ul id="GUID-42C84711-FE87-5A6F-85B6-89669C41EE95"><li id="GUID-CD623297-23B2-5A63-BDA0-4DF4D5625302"><p>To start the play process, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-83CD0A0C-535B-31D2-946F-537BCB4D26A6"><apiname>CMMFDevSound::PlayInitL()</apiname></xref> method: </p> <p>Once started, audio data is played incrementally from a buffer. When there is data in the buffer, use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-30349572-DFF6-380B-97A1-3549E00B8259"><apiname>CMMFDevSound::PlayData()</apiname></xref> method to play the data. </p> <p>When more data is needed for playing, DevSound calls the <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita#GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD/GUID-FBB7A51D-771C-3820-80A6-1297F98CDCFF"><apiname>MDevSoundObserver::BufferToBeFilled()</apiname></xref> function. When the new data has been read into the buffer, again use the <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-30349572-DFF6-380B-97A1-3549E00B8259"><apiname>CMMFDevSound::PlayData()</apiname></xref> method. The client must supply audio data through the buffers at a sufficient rate to avoid buffer underflow. </p> <p> Note: The <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-83CD0A0C-535B-31D2-946F-537BCB4D26A6"><apiname>CMMFDevSound::PlayInitL()</apiname></xref> and <xref href="GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD.dita#GUID-B3E9B015-1413-35A6-A316-D1C01C1001AD/GUID-30349572-DFF6-380B-97A1-3549E00B8259"><apiname>CMMFDevSound::PlayData()</apiname></xref> methods are pseudo-asynchronous. They result in an <xref href="GUID-D0F3F385-68C9-331D-865F-DA36589BE9FD.dita"><apiname>MDevSoundObserver</apiname></xref> callback that can occur in context (before the method has returned) or out of context (after the method has returned). </p> </li> </ul> </section> </conbody><related-links><link href="GUID-609A4E83-F074-5A5D-A0DF-A95A7CDC8D2C.dita"><linktext>Pausing and

                Resuming Playing</linktext> </link> <link href="GUID-A5B74E5C-A26F-5699-8885-3C7F3121FAD6.dita"><linktext>Stopping Audio

                Play</linktext> </link> <link href="GUID-57412030-6B02-592A-81D5-54D2767ED131.dita"><linktext>Retrieving Audio Play