<?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-1C499E7D-8099-5BE4-AE46-6143388E6ACB"><title>Audio Input Streaming Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to use Audio Input Streaming. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to open, read and then close an audio input stream. </p> <p><b>Required Background</b> </p> <p>The <xref href="GUID-715E0EA4-8B3D-5DDF-B773-922E367B114F.dita">Audio Input Streaming Overview</xref> provides an introduction to Audio Input Streaming. </p> <p><b>Introduction</b> </p> <p>The audio input stream interface class, <xref href="GUID-92BDB3AF-D9DB-35E2-AC6F-6435D3D1A4D8.dita"><apiname>CMdaAudioInputStream</apiname></xref>, enables MMF client applications to: </p> <ul><li id="GUID-577E976A-11CC-5054-ABDE-522A30B5FDCF"><p>stream audio data from the low level audio controller (which has collected it from a hardware device, such as a microphone) to specified buffers (record audio). </p> </li> <li id="GUID-71E21858-E184-5B07-AE02-EFBE8F823B6E"><p>specify the priority of the audio stream relative to other clients trying to use the same audio hardware </p> </li> <li id="GUID-BA394ADC-BC3F-5896-BAD0-EB24759DBD36"><p>set the sample rate and the number of channels to use for recording. </p> </li> <li id="GUID-1CEAC638-A49F-5A21-91FC-90B6B56522EA"><p>change the gain and channel balance of the input stream. </p> </li> </ul> <p>The low level audio controller stores the audio data in buffers. <xref href="GUID-92BDB3AF-D9DB-35E2-AC6F-6435D3D1A4D8.dita"><apiname>CMdaAudioInputStream</apiname></xref> reads these buffers incrementally and does not have to wait until capture is complete. </p> </section> <section><title>Using Audio Input Streaming </title> <p>Typically, using an audio input stream involves the following steps as shown in the sequence diagram below: </p> <fig id="GUID-FC960A5D-EDE5-5245-A736-6A6C00A0AC33"><image href="GUID-65885916-0242-5DDB-9D88-EB214096C4DF_d0e529071_href.png" placement="inline"/></fig> <p>The following tasks will be covered in this tutorial: </p> <ul><li id="GUID-1E1A247E-3740-5CAB-AEB7-171F455EE429"><p><xref href="GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita#GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB/GUID-196AFBAE-8264-5DE2-994D-F2F06CF5CF3A"> Constructing an audio input stream</xref>  </p> </li> <li id="GUID-2744A8AE-A82C-5DAC-8C12-87D9B5ADCA6F"><p><xref href="GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita#GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB/GUID-51B28404-61E7-54E8-9F4E-730315308EA2">Opening an audio input stream</xref>  </p> </li> <li id="GUID-98480431-5F02-57D0-9564-7F0FFF2782C8"><p><xref href="GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita#GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB/GUID-4EAC65E0-E108-5BAA-B338-5B19B82D5057"> Getting and setting the stream properties</xref>  </p> </li> <li id="GUID-C03B920D-396F-5A44-9A76-77709CE45D2B"><p><xref href="GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita#GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB/GUID-BD91C4E9-9BBA-5442-A72E-01B42160DBDA"> Reading an audio input stream</xref>  </p> </li> <li id="GUID-91F3BEEE-52D7-504C-B74D-5C2FB8D59004"><p><xref href="GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita#GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB/GUID-5811A2A0-5793-5FBB-B01A-AD94590955A8">Stopping an audio input stream</xref>  </p> </li> </ul> <p id="GUID-196AFBAE-8264-5DE2-994D-F2F06CF5CF3A"><b>Basic Procedure to Construct an Audio Input Stream</b> </p> <p>The high level step to construct an audio input stream is shown here: </p> <ul><li id="GUID-DDD98263-FD3A-5057-8E35-72D237807343"><p>The client application creates an audio input stream object using the static function <xref href="GUID-92BDB3AF-D9DB-35E2-AC6F-6435D3D1A4D8.dita#GUID-92BDB3AF-D9DB-35E2-AC6F-6435D3D1A4D8/GUID-D534A585-D2B7-3906-AD82-E14A5FC1D501"><apiname>CMdaAudioInputStream::NewL()</apiname></xref>. The input stream class provides two versions of the constructor: one with the default priority and preferences, and another with specified priority and preferences. The client application must also implement the observer class <xref href="GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0.dita"><apiname>MMdaAudioInputStreamCallback</apiname></xref> to notify it about audio input streaming progress. </p> <p>The following code constructs an audio input stream: </p> <codeblock id="GUID-0749EB33-33FA-5B58-856B-99F96AB9E3A2" xml:space="preserve">CMdaAudioInputStream* aInputStream;

aInputStream = CMdaAudioInputStream::NewL(aCallback, EMdaPriorityNormal, EMdaPriorityPreferenceTimeAndQuality);</codeblock> <p>where, <codeph>aCallback</codeph> is an <xref href="GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0.dita"><apiname>MMdaAudioInputStreamCallback</apiname></xref> object. </p> </li> </ul> <p id="GUID-51B28404-61E7-54E8-9F4E-730315308EA2"><b>Basic Procedure to Open an Audio Input Stream</b> </p> <p>The high level steps to open an audio input stream are shown here: </p> <ol id="GUID-67E0F7C7-E2E3-5882-A21F-254CB2EEBDA3"><li id="GUID-B3AE7481-9750-5352-B10B-D51D1A220F97"><p>To open an input stream, use the <xref href="GUID-20D0D10F-3401-3F72-8AF6-DC35F6025DC2.dita"><apiname>Open()</apiname></xref> member function, which provides a pointer to the <xref href="GUID-06892E22-2EAC-305A-9D3A-F24E7F903427.dita"><apiname>TMdaPackage</apiname></xref> object with the required audio settings. You can also open the stream without the audio settings. For example: </p> <codeblock id="GUID-96065C5F-54F6-59D7-B6F1-BDE71EF46303" xml:space="preserve">aInputStream-&gt;Open(NULL);</codeblock> </li> <li id="GUID-8D443EF2-2FD1-5DBD-BEB3-21C5B7855978"><p>Once the stream is open, a <xref href="GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0.dita#GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0/GUID-1F9A4EAF-EE58-3FA4-8707-D8C5EDFC0664"><apiname>MMdaAudioInputStreamCallback::MaiscOpenComplete()</apiname></xref> is issued to indicate that the stream is ready for use. </p> <codeblock id="GUID-20F93B48-6662-59F1-A61B-374565A2FCB2" xml:space="preserve">void CIOStreamAudio::MaiscOpenComplete(TInt aError)

    {

    ASSERT(iState==EStateOpeningInput);

    if (aError!=KErrNone)

        {

        Complete(aError);

        }

    else

        {

        iMainBuffer.Zero();

        iState = EStateReading;

        ReadNextBlock(KNullDesC8); // kick off a new read - KNullDesC8 for first buffer

        }

    }</codeblock> </li> </ol> <p id="GUID-4EAC65E0-E108-5BAA-B338-5B19B82D5057"><b>Basic Procedure to Get and Set Stream Properties </b> </p> <p>The high level steps to get and set stream properties are shown here: </p> <ol id="GUID-98A49133-59B7-5681-9EC0-C19B1D71E9DD"><li id="GUID-DD84E50F-B44A-5ADC-ADF5-5DDE561D9AFD"><p>To set the sampling rate and number of audio channels, use the <xref href="GUID-38034819-8999-3EBE-9833-479D96D5DAB6.dita"><apiname>SetAudioPropertiesL()</apiname></xref> member function. You can do this only if the stream is open and if data is not being streamed. Values must be specified as enum values. 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> and not <codeph>8000</codeph> (Hz). The following code sets the sampling rate to 8000Hz and audio channel to mono: </p> <codeblock id="GUID-EBC071A0-A461-5000-80E5-D3579E690D18" xml:space="preserve">aInputStream-&gt;SetAudioPropertiesL(TMdaAudioDataSettings::ESampleRate8000Hz,TMdaAudioDataSettings::EChannelsMono));</codeblock> </li> <li id="GUID-EE508886-465A-581D-9FAF-76B5C522433F"><p>The <xref href="GUID-F4CC52C5-414A-3CA9-8472-A5C5298AC412.dita"><apiname>Gain()</apiname></xref> and <xref href="GUID-C2B76645-A50F-3DFF-943B-4F3D5A33ED31.dita"><apiname>GetBalanceL()</apiname></xref> member functions let you determine the current gain and balance settings. </p> </li> <li id="GUID-AEABCD16-7828-5DA1-B234-58BF44FB9C0E"><p>The <xref href="GUID-54851704-F44B-3C2C-B3C9-2B4537AD1472.dita"><apiname>SetGain()</apiname></xref> and <xref href="GUID-D1856981-6A17-3CD9-80B5-65781A803BA4.dita"><apiname>SetBalanceL()</apiname></xref> member functions let you set the gain 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-BD91C4E9-9BBA-5442-A72E-01B42160DBDA"><b>Basic Procedure to Read an Audio Input Stream</b> </p> <p>The high level steps to read an audio input stream are shown here: </p> <ol id="GUID-D78033B0-4918-51B8-8DC0-8B55F0172AC3"><li id="GUID-47C7BE03-0EAA-5C19-8FBB-7723B2AA9DEC"><p>To record the audio stream, use the <xref href="GUID-D7A48ABE-33F7-333E-8F57-0E673DA4B6F5.dita"><apiname>ReadL()</apiname></xref> member function, specifying the buffer to use. The first <xref href="GUID-D7A48ABE-33F7-333E-8F57-0E673DA4B6F5.dita"><apiname>ReadL()</apiname></xref> after a successful <xref href="GUID-20D0D10F-3401-3F72-8AF6-DC35F6025DC2.dita"><apiname>Open()</apiname></xref>, starts audio recording. Once the buffer is successfully recorded, a pointer to it is returned by <xref href="GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0.dita#GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0/GUID-FB4EC66A-4B6D-331B-B5A1-4605084343B0"><apiname>MMdaAudioInputStreamCallback::MaiscBufferCopied()</apiname></xref> callback. </p> <codeblock id="GUID-362E4E39-294E-57B9-912D-D0EB2C7B0B9B" xml:space="preserve">void CIOStreamAudio::MaiscBufferCopied(TInt aError, const TDesC8&amp; aBuffer)

    {

    ASSERT(iState==EStateReading);

    if (aError!=KErrNone)

        {

        if (aError!=KErrAbort) // aborts happen on Stop as buffers are recovered, need to ignore

            {

            Complete(aError);

            }

        }

    else

        {

        ReadNextBlock(aBuffer);

        }

    }</codeblock> </li> <li id="GUID-CD08610E-0AFE-5730-BC3A-8F112FF54EE5"><p>The following code reads the next audio block into the buffer in an array of descriptors: </p> <codeblock id="GUID-7E4D79D2-34DC-5691-865A-6C472B766BF8" xml:space="preserve">void CIOStreamAudio::ReadNextBlock(const TDesC8&amp; aBuffer)

    {

    ASSERT(iState==EStateReading);

    // buffer will be tail of iMainBuffer. Shift latter's length and get the next bit

    TInt lengthRecorded = iMainBuffer.Length()+aBuffer.Length();

    iMainBuffer.SetLength(lengthRecorded);

    iBufferPtr.Set(const_cast<TUint8*>(iMainBuffer.Ptr())+lengthRecorded, 0, iMainBuffer.MaxLength()-lengthRecorded);

    TRAPD(error, iInputStream->ReadL(iBufferPtr));

    if (error!=KErrNone)

        {

        Complete(error);

        }

    }</codeblock> </li> </ol> <p id="GUID-5811A2A0-5793-5FBB-B01A-AD94590955A8"><b>Basic Procedure to Stop an Audio Input Stream</b> </p> <p>The high level steps to stop an audio input stream are shown here: </p> <ul><li id="GUID-43677A50-198B-59D5-8F58-39C96CFAC5A4"><p>To stop recording the audio stream, use the <xref href="GUID-7CBDCF0D-1D11-34D1-BF5C-1E5B50DA75B5.dita"><apiname>Stop()</apiname></xref> member function. Two callbacks are issued after a <codeph>Stop()</codeph>. </p> <ol id="GUID-591B7B4E-899D-5D28-B33D-3EFC2DE1B4D6"><li id="GUID-EE9F9106-E0E8-5C20-8D8E-CB2A9FCCD0C4"><p>An <xref href="GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0.dita#GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0/GUID-FB4EC66A-4B6D-331B-B5A1-4605084343B0"><apiname>MMdaAudioInputStreamCallback::MaiscBufferCopied()</apiname></xref> pointing to a buffer that contains the last of the recorded audio data (and an <codeph>aError</codeph> value of <codeph>KErrAbort</codeph>). </p> </li> <li id="GUID-E3EBC7BE-C12C-527C-BF33-3EF787D8F9F4"><p>An <xref href="GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0.dita#GUID-6A1EAD31-95CA-3CAC-8897-791E9D522DF0/GUID-23F823E5-46A4-34D1-A7DD-DF6B18C37445"><apiname>MMdaAudioInputStreamCallback::MaiscRecordComplete()</apiname></xref>, indicating successful closure of the audio stream. </p> <codeblock id="GUID-A9CE4580-E981-56E8-B98B-05C84E3C746E" xml:space="preserve">void CIOStreamAudio::MaiscRecordComplete(TInt aError)

    {

    ASSERT(iState==EStateReading && aError!=KErrNone);

    Complete(aError);