--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,54 @@
+<?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-ECBA6331-2187-52C9-A5DF-20CD1EEFE781"><title>Audio Output Streaming Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to use Audio Output Streaming. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to open, play and then close an audio output stream. </p> <p><b>Required Background</b> </p> <p>The user needs to maintain the data packets in a queue before starting to send it to the server. There is no need for the entire sound clip to arrive to be able to pass on to the low level audio controller. They can be forwarded as they arrive. If the server tends to receive data more than it can read or process, then a separate queue is maintained in the client side whose elements are references to the buffers passed to it. Once the server is free to receive more data the client sends the data in the queue and receives a notification from the server by means of a callback. As a result of this, the client deletes the data fragments from the queue. </p> <p>Upon receiving the data packets the audio controller maintains them in the received buffers. A read function is instantiated to read the data into the destination descriptors. </p> <p><b>Introduction</b> </p> <p>The Audio streaming API is the interface providing the functionalities for playing, stopping, and recording the audio stream to and from the audio buffers. The audio output stream interface class, <xref href="GUID-B87C8F92-9737-3636-9800-BA267A1DCA6D.dita"><apiname>CMdaAudioOutputStream</apiname></xref>, enables client applications to: </p> <ul><li id="GUID-542B9854-AF72-5A00-B05C-AF7DE8C56916"><p>Stream raw audio data from specified buffers to audio devices. </p> </li> <li id="GUID-C4F56B32-661A-5160-AE11-C11BCCDA856E"><p>Specify the priority of the audio stream relative to other clients trying to use the same hardware. </p> </li> <li id="GUID-40790849-788F-56A1-8116-90AA755698DE"><p>Set the sample rate and the number of audio channels before playback. </p> </li> <li id="GUID-3664365E-FB62-5EB6-B396-B83655ECC49C"><p>Adjust the volume and channel balance during playback. </p> </li> </ul> </section> <section><title>Using Audio Output Streaming </title> <p>Typically, using an audio output stream involves the following steps as shown in the sequence diagram below: </p> <fig id="GUID-2D2AAE41-55E6-5BB6-B572-0A8C8015054C"><image href="GUID-534C1D1A-9450-5A1B-933F-5157039BF069_d0e315546_href.png" placement="inline"/></fig> <p>The following tasks will be covered in this tutorial: </p> <ul><li id="GUID-C498F32D-D466-5C10-893D-71B8168E6C1D"><p><xref href="GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita#GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781/GUID-7435C237-DB6C-516E-BB4D-C31BF96470B0"> Constructing an audio output stream</xref>  </p> </li> <li id="GUID-F66078F3-9125-5277-BEAF-2740869354ED"><p><xref href="GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita#GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781/GUID-A48822BE-E726-5892-A83D-CDD224C27EA0"> Opening an audio output stream</xref>  </p> </li> <li id="GUID-F3A82F27-5406-5937-BC5E-E83D9C7A6F6B"><p><xref href="GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita#GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781/GUID-E21EE5D7-42ED-5D7C-AB8F-000D6BBE88A9">Getting and setting the stream properties</xref>  </p> </li> <li id="GUID-5F166776-8C9C-5C00-8A39-E77C9157DF59"><p><xref href="GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita#GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781/GUID-CD886111-BE51-523D-A782-FA35A3889A0B"> Playing an audio output stream</xref>  </p> </li> <li id="GUID-7F60C260-A0B3-51C7-A1B1-4BE5A3F7E03A"><p><xref href="GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita#GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781/GUID-B18F568C-E82B-5D46-A225-96816258E8AB">Stopping an audio output stream</xref>  </p> </li> </ul> <p id="GUID-7435C237-DB6C-516E-BB4D-C31BF96470B0"><b>Basic Procedure for Constructing an Audio Output Stream</b> </p> <p>The high level step to construct an audio output stream is shown here: </p> <ul><li id="GUID-8314E401-E900-587A-A7DD-2899214AB883"><p>The client application creates an audio output stream object using the static function <xref href="GUID-B87C8F92-9737-3636-9800-BA267A1DCA6D.dita#GUID-B87C8F92-9737-3636-9800-BA267A1DCA6D/GUID-B4D44672-C628-304A-B36E-8AF0ACAA8A80"><apiname>CMdaAudioOutputStream::NewL()</apiname></xref>. Optionally, it also sets the audio priorities to be able to access the audio hardware in relation to the other clients trying to access the same device. </p> <codeblock id="GUID-ACD5FF96-44F1-5DC8-8A89-CD3C193EAACE" xml:space="preserve">static IMPORT_C CMdaAudioOutputStream *NewL(MMdaAudioOutputStreamCallback &amp;aCallBack, 
+TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);</codeblock> </li> </ul> <p id="GUID-A48822BE-E726-5892-A83D-CDD224C27EA0"><b>Basic Procedure for Opening an Audio Output Stream </b> </p> <p>The high level steps to open an audio output stream are shown here: </p> <ol id="GUID-B7CF17BD-41ED-5B34-8801-7101170D43C9"><li id="GUID-074798AB-3B28-52FA-9082-0B34DBB6118C"><p>To open the output stream, use the <xref href="GUID-20D0D10F-3401-3F72-8AF6-DC35F6025DC2.dita"><apiname>Open()</apiname></xref> member function. For example: </p> <codeblock id="GUID-7EA3B237-91BB-5933-AAEE-1A59375BF004" xml:space="preserve">virtual void Open(TMdaPackage* aSettings);</codeblock> </li> <li id="GUID-2D96C7A5-A81C-5B6A-A977-5A897B357FEE"><p>Once the stream is open <xref href="GUID-A35C1D9B-DC43-39FB-9FF1-39CD01D981B8.dita#GUID-A35C1D9B-DC43-39FB-9FF1-39CD01D981B8/GUID-148F9A5D-883E-3E9E-A3F4-FBACFACC2CB4"><apiname>MMdaAudioOutputStreamCallback::MaoscOpenComplete()</apiname></xref> is invoked to indicate that the stream is ready to use. </p> <codeblock id="GUID-6F18FC40-E21D-58D9-8703-0BDA17E69F0A" xml:space="preserve">void CIOStreamAudio::MaoscOpenComplete(TInt aError)
+    {
+    ASSERT(iState==EStateOpeningOutput);
+    TInt error = aError;
+    if (error==KErrNone)
+        {
+        iState = EStateWriting;    
+        iOutputStream-&gt;SetVolume(iOutputStream-&gt;MaxVolume()/2);
+        TRAP(error, iOutputStream-&gt;WriteL(iMainBuffer));
+        }
+    if (error!=KErrNone)
+        {
+        Complete(aError);    
+        }
+    }</codeblock> </li> </ol> <p id="GUID-E21EE5D7-42ED-5D7C-AB8F-000D6BBE88A9"><b>Basic Procedure for Getting and Setting the Stream Properties</b> </p> <p>The high level steps to get and set stream properties are shown here: </p> <ol id="GUID-A7DF8DD3-B3CC-56AB-B900-5FA1AB5D7E89"><li id="GUID-D300515F-450D-52E2-A7A3-5AB02A642143"><p>To set the sampling rate and number of audio channels use <xref href="GUID-38034819-8999-3EBE-9833-479D96D5DAB6.dita"><apiname>SetAudioPropertiesL()</apiname></xref>. For example: </p> <codeblock id="GUID-C36320C7-403B-50B2-868E-F8B23C3F921C" xml:space="preserve">virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);</codeblock> <p>You cannot set these values while playing the stream. Also, you must specify them as enums; for example, <xref href="GUID-CF54F882-E290-3C68-9352-79C6B7303FDF.dita#GUID-CF54F882-E290-3C68-9352-79C6B7303FDF/GUID-681C1220-0CDD-34BF-848F-9DC82CB001DB"><apiname>TMdaAudioDataSettings::ESampleRate8000Hz</apiname></xref> rather than <codeph>8000</codeph> (Hz). </p> </li> <li id="GUID-77B3670A-0DC3-52BE-B245-58AF9852AF66"><p>The <xref href="GUID-657CDF11-EA74-3074-9872-412D2C26F3E6.dita"><apiname>Volume()</apiname></xref> and <xref href="GUID-DDE4193C-AB52-3FE9-8AD5-2DB344BD3404.dita"><apiname>GetbalanceL()</apiname></xref> member functions let you determine current volume and balance settings. For example: </p> <ul><li id="GUID-581B588C-5F23-57F6-9113-A34B2B796AE1"><codeblock id="GUID-07B29807-340D-5C6E-89F5-F0522F3CD611" xml:space="preserve">IMPORT_C TInt GetBalanceL() const;</codeblock> </li> <li id="GUID-550C5E9C-4073-5F54-937F-2FD6E0A0F684"><codeblock id="GUID-6C5293FE-EB1B-52B2-BE07-2E0D0393B863" xml:space="preserve">virtual TInt Volume();</codeblock> </li> </ul> </li> <li id="GUID-23A18BCE-75EB-5B7D-8812-A7D883061B1B"><p>The <xref href="GUID-171667CD-06F4-3DF5-A4E1-360422F362D2.dita"><apiname>SetVolume()</apiname></xref> and <xref href="GUID-D1856981-6A17-3CD9-80B5-65781A803BA4.dita"><apiname>SetBalanceL()</apiname></xref> member functions let you set the volume and balance respectively. You can use them while the stream is open, with the new settings taking immediate effect. </p> </li> </ol> <p id="GUID-CD886111-BE51-523D-A782-FA35A3889A0B"><b>Basic Procedure for Playing an Audio Output Stream</b> </p> <p>The high level steps to play an audio output stream are shown here: </p> <ol id="GUID-EABB52B7-5B85-5E65-9BA5-58168A0331AA"><li id="GUID-C2D6E0ED-85F3-5FF5-BA6A-67EAEB039CE2"><p>To play an audio stream from the current position use the <xref href="GUID-60E583FD-35E0-349A-B2A9-B28C8B8B4AE1.dita"><apiname>WriteL()</apiname></xref> member function. For example: </p> <codeblock id="GUID-2BAD8EF3-AA4D-564A-816F-5ABC69863153" xml:space="preserve">virtual void WriteL(const TDesC8&amp; aData);</codeblock> <p>This function is asynchronous. </p> <p>When <codeph>aData</codeph> is received, the client is notified by a call to <xref href="GUID-EF3C442E-03C4-3630-98A8-C2ABD94D1A3F.dita#GUID-EF3C442E-03C4-3630-98A8-C2ABD94D1A3F/GUID-D4E0CAA0-9FF3-3E02-BC0B-CCC9F91E8E66"><apiname>MdaAudioOutputStreamCallback::MaoscBufferCopied()</apiname></xref>. </p> <codeblock id="GUID-BF75B2F0-9A63-5249-BF37-007A817D8C0A" xml:space="preserve">void CIOStreamAudio::MaoscBufferCopied(TInt aError, const TDesC8&amp; IFDEBUG(aBuffer))
+    {
+    ASSERT(iState==EStateWriting);
+    if (aError!=KErrNone)
+        {
+        // ignore any KErrAbort returns - this would happen during a Stop() call
+        // if we were playing 
+        if (aError!=KErrAbort)
+            {
+            Complete(aError);    
+            }
+        }
+    else
+        {
+        ASSERT(aBuffer.Length()==iMainBuffer.Length());
+        // output almost complete - have been asked for more data
+        iState = EStateWritingPostBuffer;
+        }
+    }</codeblock> <p>The <xref href="GUID-60E583FD-35E0-349A-B2A9-B28C8B8B4AE1.dita"><apiname>WriteL()</apiname></xref> can be called again before this notification is triggered because the buffers are held in a client-side queue until they have been sent. </p> </li> <li id="GUID-1671B229-D248-56E6-9CBA-6F2A674B3ED9"><p>When the audio stream has completed playing, the callback function <xref href="GUID-A35C1D9B-DC43-39FB-9FF1-39CD01D981B8.dita#GUID-A35C1D9B-DC43-39FB-9FF1-39CD01D981B8/GUID-93577BCB-6063-3BC4-A051-38A5BE5C6A8C"><apiname>MMdaAudioOutputStreamCallback::MaoscPlayComplete()</apiname></xref> is invoked. </p> <codeblock id="GUID-033737CB-294F-5B55-A5BF-C66245B172DE" xml:space="preserve">void CIOStreamAudio::MaoscPlayComplete(TInt aError)
+    {
+    ASSERT(iState==EStateWriting || iState==EStateWritingPostBuffer);
+    TInt error = aError;
+    if (aError==KErrUnderflow &amp;&amp; iState==EStateWritingPostBuffer)
+        {
+        error = KErrNone; // normal termination is underflow following buffer request    
+        }
+    Complete(error);
+    }</codeblock> <p>This closes the stream and sets the callback <xref href="GUID-DA707A8F-7006-3193-B8E5-3197BB471B4F.dita"><apiname>aError</apiname></xref> to <xref href="GUID-F9B50A12-0CDE-3D5F-89B2-E2864B00E156.dita"><apiname>KErrUnderFlow</apiname></xref>. </p> </li> </ol> <p id="GUID-B18F568C-E82B-5D46-A225-96816258E8AB"><b>Basic Procedure for Stopping an Audio Output Stream</b> </p> <p>The high level step to stop an audio output stream is shown here: </p> <ul><li id="GUID-453E8330-16E2-5A6A-B2B4-E1D08E80AC12"><p>To stop audio playback (stop data being sent to the stream) use the <xref href="GUID-7CBDCF0D-1D11-34D1-BF5C-1E5B50DA75B5.dita"><apiname>Stop()</apiname></xref> member function. </p> <p>For example: </p> <codeblock id="GUID-084898F1-DB72-5DB4-9FCA-581F1AA96F6F" xml:space="preserve">virtual void Stop();</codeblock> <p>This invokes <xref href="GUID-A35C1D9B-DC43-39FB-9FF1-39CD01D981B8.dita#GUID-A35C1D9B-DC43-39FB-9FF1-39CD01D981B8/GUID-93577BCB-6063-3BC4-A051-38A5BE5C6A8C"><apiname>MMdaAudioOutputStreamCallback::MaoscPlayComplete()</apiname></xref> to notify successful closure of the stream. </p> </li> </ul> </section> <section><title>See Also</title> <p><xref href="GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita"> Audio Input Streaming Tutorial</xref>  </p> </section> </conbody></concept>
\ No newline at end of file