<?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-2A543E1C-F3DE-59EF-8A43-1B655F367FBC"><title>Audio Processing Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to use the Advanced Audio Adaptation Framework for audio processing. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to play and record audio using the Advanced Audio Adaptation Framework (A3F). </p> <p><b>Required Background</b> </p> <p>To understand this document, you need to be familiar with A3F. For more information, see: </p> <ul><li id="GUID-DFEF3900-032F-5DF6-AB8F-F5C697F41A5E"><p><xref href="GUID-4AAABD77-C08E-5EE2-A02A-3B412EA6D23F.dita">Advanced Audio Adaptation Framework Overview</xref> </p> </li> <li id="GUID-76EA5B9D-DF81-5191-A78D-9419E64F4E67"><p><xref href="GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita"> Advanced Audio Adaptation Framework Technology Guide </xref>  </p> </li> </ul> <p><b>Introduction</b> </p> <p>To start using A3F for audio processing, you must: </p> <ol id="GUID-B9F4198E-7322-5AB2-B361-5DC83D6B2D10"><li id="GUID-25A4D909-A969-5879-897A-883639DD3DBB"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-5E3EBCF5-7906-5573-BB8F-39444DAF54DE"> Construct a new Audio Context Factory</xref>. </p> </li> <li id="GUID-EA23F2DA-9D37-5958-9EDC-409FB02A83A4"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-9AB74084-14A1-5470-BB1E-799BD4765DF1"> Initialize an audio stream</xref>. </p> </li> </ol> <p id="GUID-5E3EBCF5-7906-5573-BB8F-39444DAF54DE"><b>Construction</b> </p> <p>Each client that wants to use audio resources must have an instance of <xref href="GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73.dita"><apiname>CAudioContextFactory</apiname></xref> associated with it. To construct a new instance, use the <xref href="GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73.dita#GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73/GUID-D8C563D4-34AC-3460-BE6F-A19D3B1D5D23"><apiname>CAudioContextFactory::NewL()</apiname></xref> function: </p> <codeblock id="GUID-C69564C1-54CD-5797-94BD-06DF9F4BAE8F" xml:space="preserve">static IMPORT_C CAudioContextFactory* NewL();</codeblock> <p>Once created, you can use <xref href="GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73.dita"><apiname>CAudioContextFactory</apiname></xref> to create a reference to an <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioContext</apiname></xref> pointer. To create the reference, call <xref href="GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73.dita#GUID-C4AD7B75-9027-3F62-889C-ADEF5E6DBC73/GUID-59496D3F-A541-35AA-BADB-28E487503955"><apiname>CAudioContextFactory::CreateAudioContext()</apiname></xref>: </p> <codeblock id="GUID-215B3B74-5339-5B82-9431-6D3DE84C2C25" xml:space="preserve">IMPORT_C TInt CreateAudioContext(MAudioContext*&amp; aContext);</codeblock> <p>To observe the commit cycle, you must register an audio context observer using the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-AE870243-CC91-3259-9525-8BB6A5BECEDA"><apiname>MAudioContext::RegisterAudioContextObserver()</apiname></xref> function: </p> <codeblock id="GUID-5FC122B3-769D-5801-9160-8D9B6E5C0B6E" xml:space="preserve">virtual Tint RegisterAudioContextObserver(MAudioContextObserver&amp; aObserver);</codeblock> <p>For more information about the commit cycle, see <xref href="GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita#GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2/GUID-C13977B1-D855-5D46-913C-15059421C225">The Commit Cycle</xref> in the <xref href="GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita">Advanced Audio Adaptation Framework Technology Guide</xref>. </p> <p>You use the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita"><apiname>MAudioContext</apiname></xref> class to create references to all of the audio components you require. To create an <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita"><apiname>MAudioStream</apiname></xref> reference, call the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-E05FA869-2B49-319C-9172-2A7F40338F92"><apiname>MAudioContext::CreateAudioStream()</apiname></xref> function: </p> <codeblock id="GUID-CFEEAD67-FF15-5C5E-A8CD-E8D55783E50E" xml:space="preserve">virtual Tint CreateAudioStream(MAudioStream*&amp; aAudioStream);</codeblock> <p>You can create other audio components by calling the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-989C9D1A-C208-3515-BD71-E578365B5996"><apiname>MAudioContext::CreateAudioProcessingUnit()</apiname></xref> function: </p> <codeblock id="GUID-B3FEA557-C59B-516E-998D-7C604173FB0A" xml:space="preserve">virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*&amp; aProcessingUnit);</codeblock> <p>The supported audio processing unit TypeIDs are defined in <filepath>audioprocessingunittypeuids.h</filepath>. The supported TypeIDs are as follows: </p> <ul><li id="GUID-FF1ED2C4-97CC-50E0-9180-A118C35DD45D"><p> <xref href="GUID-ED0C5B7A-3EBA-3D1D-BA9C-BBB9BB7A2BC1.dita"><apiname>KUidAudioStream</apiname></xref>  </p> </li> <li id="GUID-8E72BEF8-9935-50A6-9969-AA2E52DD4BD6"><p> <xref href="GUID-D8C317BF-A107-3941-9322-14BA06CD9D2E.dita"><apiname>KUidMmfBufferSource</apiname></xref>  </p> </li> <li id="GUID-BE3C9DEB-4F89-5466-8EC7-06F7FA5DABF1"><p> <xref href="GUID-0C9C7FDA-B9AC-3B0A-853B-BA2AD1836C74.dita"><apiname>KUidAudioDeviceSource</apiname></xref>  </p> </li> <li id="GUID-00DA5671-E7B9-5B34-ACF3-6527FFCAF667"><p> <xref href="GUID-430A9FC1-E17A-32C9-8F3D-772A8B1F678F.dita"><apiname>KUidAudioCodec</apiname></xref>  </p> </li> <li id="GUID-FD67D84F-A9E2-57AA-A89B-3AC4B2DB6E5B"><p> <xref href="GUID-F53B4801-B222-3064-89D8-8C14804585B3.dita"><apiname>KUidAudioDecoder</apiname></xref>  </p> </li> <li id="GUID-1ED7CFB2-769A-5474-9A3C-56D31281D438"><p> <xref href="GUID-9160FFFF-4864-35C7-8876-EF3DFF7F4D1C.dita"><apiname>KUidAudioEncoder</apiname></xref>  </p> </li> <li id="GUID-60C2AE00-CF45-541C-BEDD-380FEAB21C70"><p> <xref href="GUID-61D5783B-31F8-3931-9F59-4778033FA28F.dita"><apiname>KUidMmfBufferSink</apiname></xref>  </p> </li> <li id="GUID-2121172B-637A-55F8-8AC5-49459D75C671"><p> <xref href="GUID-7F26E1FD-5094-398C-9E4B-55FBECA8D555.dita"><apiname>KUidAudioDeviceSink</apiname></xref>  </p> </li> <li id="GUID-DF916501-3577-5B6A-A1D3-60B2848C9D40"><p> <xref href="GUID-D4AD30D5-E290-3866-9BEC-37C5F96D28BF.dita"><apiname>KUidAudioGainControl</apiname></xref>  </p> </li> </ul> <p>Before making changes to a stream and committing them, you must set the Process ID that identifies the client. Note that you must do this before making any calls to <codeph>Commit()</codeph>. To set the client information, call the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-AC784D04-E300-3295-9FA0-7D4E3F7BC768"><apiname>MAudioContext::SetClientSettings()</apiname></xref> function: </p> <codeblock id="GUID-2EA5B1A7-3B35-5DEB-BB74-95F4F0FF2E7D" xml:space="preserve">virtual TInt SetClientSettings(const TClientContextSettings&amp; aSettings);</codeblock> <p>Depending on the codec type, you set either the data supplier to be informed about <xref href="GUID-11595177-B5B0-3EEC-8064-0D79F4BF3D2C.dita#GUID-11595177-B5B0-3EEC-8064-0D79F4BF3D2C/GUID-D8819B8E-8EFA-36DA-A6EA-6D534225BC7F"><apiname>MMMFDataSupplier::BufferToBeFilled</apiname></xref> notifications, or the data consumer to be informed about <xref href="GUID-BC675A52-D3B5-3F97-B986-8643A8FEFE59.dita#GUID-BC675A52-D3B5-3F97-B986-8643A8FEFE59/GUID-171DCE0F-2999-3151-8B7F-010C4E1F97AB"><apiname>MMMFAudioDataConsumer::BufferToBeEmptied</apiname></xref> notifications. You must do this before you add the data source or data sink to the audio stream. For a buffer source, using codec type <xref href="GUID-F53B4801-B222-3064-89D8-8C14804585B3.dita"><apiname>KUidAudioDecoder</apiname></xref>, you can set the data supplier by obtaining the <xref href="GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803.dita"><apiname>MMMFBufferSource</apiname></xref> extension interface for the audio source. Once you have the extension interface, use the <xref href="GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803.dita#GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803/GUID-79FB5506-C63C-3672-A25D-21F748237326"><apiname>MMMFBufferSource::SetDataSupplier()</apiname></xref> function for registration: </p> <codeblock id="GUID-1221AC2C-BF14-5405-B9AA-BC9D4D336296" xml:space="preserve">virtual Tint SetDataSupplier(MMMFAudioDataSupplier&amp; aSupplier);</codeblock> <p>For a buffer sink, using codec type <xref href="GUID-9160FFFF-4864-35C7-8876-EF3DFF7F4D1C.dita"><apiname>KUidAudioEncoder</apiname></xref>, you can set the data consumer by obtaining the <xref href="GUID-72D6CC6A-D119-3A88-BADD-106B1D1EE1AA.dita"><apiname>MMMFBufferSink</apiname></xref> extension interface for the audio sink. Once you have the extension interface, use the <xref href="GUID-72D6CC6A-D119-3A88-BADD-106B1D1EE1AA.dita#GUID-72D6CC6A-D119-3A88-BADD-106B1D1EE1AA/GUID-29D1297E-3B8E-39D9-B15B-6019619CCB82"><apiname>MMMFBufferSink::SetDataConsumer()</apiname></xref> function for registration: </p> <codeblock id="GUID-11FD86AE-F27E-5DE9-9B67-9F267EEA7EE2" xml:space="preserve">virtual Tint SetDataConsumer(MMMFAudioDataConsumer&amp; aConsumer);</codeblock> <p>After you have created your audio processing units, you must then add them to an audio stream in order to control them. The following Audio Stream API functions are available for adding audio processing units: </p> <ul><li id="GUID-80F508D6-1BB9-5321-B769-70A35295785E"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-7EEDFC7D-338B-320E-9F5D-86A87ED9C75E"><apiname>MAudioStream::AddSource()</apiname></xref>  </p> <codeblock id="GUID-2EB5A95F-4B35-577C-AE30-5C1C260FBBB5" xml:space="preserve">virtual TInt AddSource(MAudioProcessingUnit* aSource);</codeblock> </li> <li id="GUID-46614A7E-0DC3-5531-8C73-7553A1342034"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-643AD421-6C4B-3B72-A59B-E54CA85B43B3"><apiname>MAudioStream::AddSink()</apiname></xref>  </p> <codeblock id="GUID-B038C60A-A0F9-50B1-843C-275D7858D87C" xml:space="preserve">virtual TInt AddSink(MAudioProcessingUnit* aSink);</codeblock> </li> <li id="GUID-394C930A-5523-5B53-82EA-F3628847D352"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-FF7925E4-4E7D-3996-A1EB-64B8C0F5AE81"><apiname>MAudioStream::AddAudioCodec()</apiname></xref>  </p> <codeblock id="GUID-5C019254-CC30-55E4-835C-3E28849BE2D3" xml:space="preserve">virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec);</codeblock> </li> <li id="GUID-9BD8DE4B-2303-5F4A-AB26-C7D90D525A3C"><p> <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-34CE5337-61A9-35B7-BCB4-5BB6B2BD6E5B"><apiname>MAudioStream::AddGainControl()</apiname></xref>  </p> <codeblock id="GUID-0B9F11B5-C98B-5706-8677-54D28A0C34C8" xml:space="preserve">virtual TInt AddGainControl(MAudioProcessingUnit* aGainControl);</codeblock> </li> </ul> <p>Before transferring the audio stream to the <codeph>Initialized</codeph> state, you must define the audio format that the codec should use. This requires Audio Processing Unit API functions to fetch the codec extension interface. The TypeID to fetch this interface is <xref href="GUID-430A9FC1-E17A-32C9-8F3D-772A8B1F678F.dita"><apiname>KUidAudioCodec</apiname></xref> and the function for this is <codeph>TAny*

                Interface(TUid aType);</codeph>. </p> <codeblock id="GUID-09EEE69E-56CD-59CA-8354-0F1592786643" xml:space="preserve">virtual TAny* Interface(TUid aType);</codeblock> <p>You must cast the returned interface to the corresponding extension interface, that is, <xref href="GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8.dita"><apiname>MAudioCodec</apiname></xref>. The <xref href="GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8.dita"><apiname>MAudioCodec</apiname></xref> extension interface allows codec-specific functions like <xref href="GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8.dita#GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8/GUID-B466E6D5-DC68-3E4A-810A-5000954DF767"><apiname>MAudioCodec::SetFormat()</apiname></xref> to be called: </p> <codeblock id="GUID-17DECCDC-0424-5178-9AC8-223DA9A37FFF" xml:space="preserve">virtual TInt SetFormat(TUid aFormat);</codeblock> <p>The audio format UIDs are defined in <filepath>audioformatuids.h</filepath>. </p> <p id="GUID-9AB74084-14A1-5470-BB1E-799BD4765DF1"><b>Initialization</b> </p> <p>When you have finished configuring the required settings for your audio components, you can request that the audio stream be transitioned to the <codeph>Initialized</codeph> state. You use the Audio Stream API <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-1DFCCA16-7AD0-3AAF-87B8-96F0546DF488"><apiname>MAudioStream::Initialize()</apiname></xref> function to prepare the stream to transition from <codeph>EUninitialized</codeph> to <codeph>EInitialized</codeph>: </p> <codeblock id="GUID-02DC6FE2-9528-5AF5-99C1-BAA0A2E76BE9" xml:space="preserve">virtual TInt Initialize();</codeblock> <p>After the required changes have been made to the stream, you must make a call to the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> function. Your request for audio resources is dependent on a successful commit cycle. A successful commit cycle means that you have changed the stream state to <codeph>EInitialized</codeph>. </p> <p>Once <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-1DFCCA16-7AD0-3AAF-87B8-96F0546DF488"><apiname>MAudioStream::Initialize()</apiname></xref> has been successfully committed, A3F calls <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-1EFF05A7-AEF2-3CAB-A899-CA3B8CD3EEA8"><apiname>MAudioStreamObserver::StateEvent()</apiname></xref>: </p> <codeblock id="GUID-093C7E9D-B500-527E-B8BD-EF43CD1F45F6" xml:space="preserve">virtual void StateEvent(MAudioStream&amp; aStream , TInt aReason, TAudioState aNewState)=0;</codeblock> <p>If <xref href="GUID-D80EC952-D551-346A-B115-BD617ECAB8B9.dita"><apiname>aNewState</apiname></xref> is <codeph>EInitialized</codeph>, and <xref href="GUID-3336EC2B-4FB8-3FD0-A702-0CB50DE059B4.dita#GUID-3336EC2B-4FB8-3FD0-A702-0CB50DE059B4/GUID-576DD504-B977-37ED-8EA3-2100685D070A"><apiname>MAudioContextObserver::ContextEvent()</apiname></xref> is called on the <xref href="GUID-3336EC2B-4FB8-3FD0-A702-0CB50DE059B4.dita"><apiname>MAudioContextObserver</apiname></xref> with event <xref href="GUID-570E513B-55CB-31B0-A325-C910D58C3F2C.dita"><apiname>KUidA3FContextUpdateComplete</apiname></xref>, then the process of initialization is complete. Otherwise one of the system wide error codes is returned. </p> <p> <b>Note</b>: <codeph>ContextEvent()</codeph> is a callback in the same thread context as the A3F client. </p> <p>If the transition to <codeph>EInitialized</codeph> fails, it may be caused by one of the following: </p> <ul><li id="GUID-7FCDC39D-469F-503C-B9E4-736A5C06B284"><p>The <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-1EFF05A7-AEF2-3CAB-A899-CA3B8CD3EEA8"><apiname>MAudioStreamObserver::StateEvent()</apiname></xref> callback gives an error code <codeph>KErrNotReady</codeph> if, for example, the codec format is not set when committing the transition to <codeph>EInitialized</codeph>. </p> <p>The <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-1EFF05A7-AEF2-3CAB-A899-CA3B8CD3EEA8"><apiname>MAudioStreamObserver::StateEvent()</apiname></xref> callback provides information about the new state of stream, if the state change was involved with the commit cycle, and an error code if there were any problems with the state change. </p> </li> <li id="GUID-2384281D-D4C9-52F5-B0E3-980733C5B044"><p>The commit cycle can also fail, for example, because of pre-emption. </p> <p>The <xref href="GUID-3336EC2B-4FB8-3FD0-A702-0CB50DE059B4.dita#GUID-3336EC2B-4FB8-3FD0-A702-0CB50DE059B4/GUID-576DD504-B977-37ED-8EA3-2100685D070A"><apiname>MAudioContextObserver::ContextEvent()</apiname></xref> callback indicates the event and an error code if there were any problems with the commit cycle. </p> </li> </ul> </section> <section><title>Using A3F </title> <p>The following sections describe how to manage and manipulate audio streams for audio playing and recording. </p> <p><b>Basic Procedure</b> </p> <p>The high level steps involved in processing audio are shown here: </p> <ol id="GUID-AED76DEC-7246-5A92-B81F-8BC426B56032"><li id="GUID-C355F9D4-CEF0-5A31-AA6C-86DCA277EEDB"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-14D6294E-64FB-58D9-85F8-FAE2A14367B1"> Configuring</xref>  </p> </li> <li id="GUID-4272405E-96AB-5A31-AF5A-E3E1E780EA9C"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-F6BC242F-E977-5A57-B90D-00D8A6AF5BF8"> Playing</xref>  </p> </li> <li id="GUID-00999D8E-8C01-54DC-95EA-06C68EBEC735"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-C91CCA5D-2E5B-58D0-9EEE-B5F6C0095E2A">Recording</xref>  </p> </li> <li id="GUID-D7A791C3-C155-5F22-A483-C3E07FB23450"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-E2FC5EC6-57C0-53BB-9A5F-DC8BDA12E725"> Pausing and Continuing</xref>  </p> </li> <li id="GUID-6B39D2C0-0874-50C7-8213-83252A198801"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-495DC719-47C6-50B0-9A2D-9B00BEBA0E38"> Stopping While Playing</xref>  </p> </li> <li id="GUID-D9D2E80F-5791-5788-A476-43E569D20C49"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-93CB9072-728A-598E-AD61-141D7FC9257E">Stopping While Recording</xref>  </p> </li> <li id="GUID-CF413CE3-A4FD-56BB-9967-A8D4616E791C"><p><xref href="GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC.dita#GUID-2A543E1C-F3DE-59EF-8A43-1B655F367FBC/GUID-CBD49226-AC35-5890-81F7-885E97A14E30"> Retrieving the Time Streamed</xref>. </p> </li> </ol> <p id="GUID-14D6294E-64FB-58D9-85F8-FAE2A14367B1"><b> Configuring</b> </p> <p>You can configure the following settings while the stream is in the <codeph>EInitialized</codeph> state: </p> <ul><li id="GUID-1CE3E5CC-472C-5444-B98A-08512C4599E3"><p>To change the channels used for audio processing, use the <xref href="GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8.dita#GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8/GUID-ECD29200-00F9-328D-B301-8281BCD5CDCE"><apiname>MAudioCodec::SetMode()</apiname></xref> function to set the mode: </p> <codeblock id="GUID-32134EBA-B023-5391-BB17-1FF185DCA8C7" xml:space="preserve">virtual Tint SetMode(TUid aMode);</codeblock> </li> <li id="GUID-C8922EA4-E4AB-5928-8C39-C413C7DB5A69"><p>To set the sampling rate, use the <xref href="GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8.dita#GUID-863B02CA-CE78-3F63-AC42-E94D3226FDA8/GUID-54C1EEC1-05D6-31BD-91DB-62AFEA903704"><apiname>MAudioCodec::SetSampleRate()</apiname></xref> function: </p> <codeblock id="GUID-1CFE1C46-E71A-56B6-92D9-575F892042F4" xml:space="preserve">virtual Tint SetSampleRate(Tint aSampleRate);</codeblock> </li> </ul> <p>You can configure the following settings before or during audio processing: </p> <ul><li id="GUID-57842993-925D-524D-9F65-7F08A9B08605"><p>To set the audio priority and preference-related settings for the implementation, use the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-DB79EE0B-128D-3F54-8220-F0860085BF20"><apiname>MAudioStream::SetAudioType()</apiname></xref> function: </p> <codeblock id="GUID-E6C08570-F0D1-5F69-BDD3-E2EA35839B3D" xml:space="preserve">virtual Tint SetAudioType(TAudioTypeSettings&amp; aAudioTypeSettings) const;</codeblock> </li> <li id="GUID-4926C991-1653-5644-91AF-C042315CC858"><p>To change gain settings, fetch the <xref href="GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23.dita"><apiname>MAudioGainControl</apiname></xref> extension interface and use <xref href="GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23.dita#GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23/GUID-A4EA6112-1395-3B57-BFB0-E63D851ECDE8"><apiname>MAudioGainControl::SetGain()</apiname></xref>: </p> <codeblock id="GUID-6A4B7541-BE21-512F-A6F0-0DF8C0CD6682" xml:space="preserve">virtual Tint SetGain(RArray&lt;TAudioChannelGain&gt;&amp; aChannels);</codeblock> <p>The <xref href="GUID-DAF4E3A2-90EC-3DDA-A7C9-4A5C8A7FED7C.dita"><apiname>aRampDuration</apiname></xref> parameter defines the period over which to raise the gain. The <xref href="GUID-577B3EEB-C87A-39DD-BADB-9D5975AC45EF.dita"><apiname>aGain</apiname></xref> value can be any value between zero and <xref href="GUID-1C455D65-DA40-305D-A59D-972626F4ECEC.dita"><apiname>aMaxGain</apiname></xref> (the maximum gain). To obtain <xref href="GUID-1C455D65-DA40-305D-A59D-972626F4ECEC.dita"><apiname>aMaxGain</apiname></xref>, use the <xref href="GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23.dita#GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23/GUID-CE1B2FA0-6DC7-3DCA-842F-6756A48FF70C"><apiname>MAudioGainControl::GetMaxGain()</apiname></xref> function: </p> <codeblock id="GUID-25097B9A-1841-5614-B0B4-7BEF29F2E307" xml:space="preserve">virtual Tint GetMaxGain(TInt&amp; aMaxGain) const</codeblock> <p>Alternatively you can set the gain on a channel-by-channel basis. Setting the gain this way also allows you to define a gain ramp. To set the channel gain with a ramp, use <xref href="GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23.dita#GUID-BA791F19-78BC-3995-BB1E-7F272B7A1A23/GUID-A4EA6112-1395-3B57-BFB0-E63D851ECDE8"><apiname>MAudioGainControl::SetGain()</apiname></xref>: </p> <codeblock id="GUID-950EE839-955B-5E90-97FB-F2490897C545" xml:space="preserve">virtual Tint SetGain(RArray&lt;TAudioChannelGain&gt;&amp; aChannels, TUid aRampOperation, const TTimeIntervalMicroSeconds&amp; aRampDuration);</codeblock> <p>The UID determines how the ramp is interpreted. The following table describes the different ramps: </p> <table id="GUID-72DCEEC7-FE40-5CAB-8F0A-0BC8A5554D60"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p> <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref>  </p> </entry> <entry><p>The value of <codeph>aRampDuration</codeph> is ignored and the gain changes immediately. </p> </entry> </row> <row><entry><p> <xref href="GUID-CA54ED0F-6B37-32FF-AA70-2033EC3472BB.dita"><apiname>KGainSawTooth</apiname></xref>  </p> </entry> <entry><p>An explicit 0 to <codeph>aGain</codeph> sweep, rising linearly. If the channel is active, the effective gain drops to 0, as soon as possible, after the request. If <codeph>KGainSawTooth</codeph> is used when the stream is not in the <codeph>EActive</codeph> state, then it acts as a fade-in during the subsequent <codeph>Activate()</codeph> transition. </p> </entry> </row> <row><entry><p> <xref href="GUID-010E9327-CD26-3910-B30D-86DB0982B125.dita"><apiname>KGainFadeOut</apiname></xref>  </p> </entry> <entry><p>A drop from the current gain to 0, dropping linearly over the <codeph>aRampDuration</codeph> period. </p> </entry> </row> <row><entry><p> <xref href="GUID-86875DD9-437B-3757-B744-C51274281D52.dita"><apiname>KGainRamped</apiname></xref>  </p> </entry> <entry><p>A gradual change from the current gain value to <codeph>aGain</codeph> over the <codeph>aRampDuration</codeph> period </p> </entry> </row> <row><entry><p> <xref href="GUID-2EFB7E8D-DC62-39E5-A282-819013060B6C.dita"><apiname>KGainContinue</apiname></xref>  </p> </entry> <entry><p>If a previous ramp operation is in progress, then this continues but the concept of “target gain” is updated using the new values. The value of <codeph>aRampDuration</codeph> is ignored and the previous ramp duration is re-used, minus the time already spent ramping. The smoothness of this operation depends on the implementation. If no ramp operation is in progress, then this is the same as <codeph>KNullUid</codeph>. Note that this option is intended as a way of changing gain values without stopping an ongoing ramp operation. </p> </entry> </row> </tbody> </tgroup> </table> </li> </ul> <p>Once you have finished setting configuration values, you must apply them using the <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> function: </p> <codeblock id="GUID-74265309-6B3F-5DCF-AE59-BDD53B765D0A" xml:space="preserve">virtual Tint Commit();</codeblock> <p id="GUID-F6BC242F-E977-5A57-B90D-00D8A6AF5BF8"><b>Playing</b> </p> <p>Playing audio starts with the stream in the <codeph>EInitialized</codeph> state. The steps to play audio are shown here: </p> <ol id="GUID-C7587083-F8C2-5D16-A5AE-8FC3845C0BA4"><li id="GUID-0CA63DE5-3065-5952-962C-BF72D1A363DC"><p>Request a transition from <codeph>EInitialized</codeph> to <codeph>EIdle</codeph> using the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-023F6F3A-8ABB-31C6-84C8-AB06CCDC7C3D"><apiname>MAudioStream::Load()</apiname></xref> function: </p> <codeblock id="GUID-8084A363-2B4B-57B2-AFEE-BB3108764692" xml:space="preserve">virtual TInt MAudioStream::Load();</codeblock> <p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> to commit the state change. </p> </li> <li id="GUID-9E2C9B01-78FA-58F1-A2EC-A46DC96F9DAD"><p>Once the commit cycle is complete and <codeph>StateEvent</codeph> is informed about the new state, request a transition to the <codeph>EActive</codeph> state by calling <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-44094278-9D86-3FCE-BB2B-3CD88606BE19"><apiname>MAudioStream::Activate()</apiname></xref>: </p> <codeblock id="GUID-33E76BF5-CDE7-59AE-B86D-269FBF8147CA" xml:space="preserve">virtual TInt Activate();</codeblock> <p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> to commit the state change. The state transition and audio playing take effect once the commit cycle has successfully completed. </p> </li> <li id="GUID-11BA8048-DAA4-512C-A31B-92154ED8FE19"><p>When the first buffer is ready to be filled with audio data, an <xref href="GUID-11595177-B5B0-3EEC-8064-0D79F4BF3D2C.dita#GUID-11595177-B5B0-3EEC-8064-0D79F4BF3D2C/GUID-A029B562-5EB8-3795-B88C-CA8D90E60991"><apiname>MMMFDataSupplier::BufferToBeFilled()</apiname></xref> notification is received: </p> <codeblock id="GUID-82372A29-3565-5970-98B1-432A873162DD" xml:space="preserve">virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0;</codeblock> </li> <li id="GUID-EF520B84-1BBD-5941-9B26-CFD0D4012802"><p>After filling the buffer, respond by using the <xref href="GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803.dita#GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803/GUID-9E3C1A38-ED76-3954-8B6E-A88286FC841C"><apiname>MMMFBufferSource::BufferFilled()</apiname></xref> extension interface function: </p> <codeblock id="GUID-78AA9109-04CE-5124-84B4-6C1663B97043" xml:space="preserve">virtual Tint BufferFilled(CMMFBuffer* aBuffer);</codeblock> <p>This is similar to the existing <xref href="GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita">DevSound</xref> behaviour. For more information, see <xref href="GUID-53A5AC8D-8A43-505F-A0B6-9E34F3CF23BE.dita">Playing audio</xref>. </p> </li> </ol> <p id="GUID-C91CCA5D-2E5B-58D0-9EEE-B5F6C0095E2A"><b> Recording</b> </p> <p>Recording audio starts with the steam in the <codeph>EInitialized</codeph> state. The steps to record audio are shown here: </p> <ol id="GUID-09916C95-AE95-55A9-B899-A8F208723766"><li id="GUID-4FCE3888-94D3-5EBE-B340-2CB4CD0FC246"><p>Request a transition from <codeph>EInitialized</codeph> to <codeph>EIdle</codeph> using the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-023F6F3A-8ABB-31C6-84C8-AB06CCDC7C3D"><apiname>MAudioStream::Load()</apiname></xref> function: </p> <codeblock id="GUID-CD7F335F-E73F-5035-8F63-9CDD602C20CD" xml:space="preserve">virtual TInt MAudioStream::Load();</codeblock> <p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> to commit the state change. </p> </li> <li id="GUID-8DDCE8FB-6B08-5AE1-B7A2-D1EAFF9E1B5E"><p>Once the commit cycle is complete and <codeph>StateEvent</codeph> is informed about the new state, request a transition to the <codeph>EActive</codeph> state by calling <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-44094278-9D86-3FCE-BB2B-3CD88606BE19"><apiname>MAudioStream::Activate()</apiname></xref>: </p> <codeblock id="GUID-E5D9F936-6193-5551-8F13-F1CF58FC36F7" xml:space="preserve">virtual TInt Activate();</codeblock> <p>Call <xref href="GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3.dita#GUID-67BE95B2-BE4A-32AF-8BDF-92FD8FBE6DC3/GUID-7011BDC1-C4D8-3BB5-9B7C-8729FADCE67E"><apiname>MAudioContext::Commit()</apiname></xref> to commit the state change. The state transition and audio recording take effect once the commit cycle has successfully completed. </p> </li> <li id="GUID-6E35385A-718E-5F0E-97E0-EDFD44B93708"><p>When the first buffer is ready to be emptied of audio data, an <xref href="GUID-7752B59D-9E3A-357B-B5DD-C4C89FEE7D5A.dita#GUID-7752B59D-9E3A-357B-B5DD-C4C89FEE7D5A/GUID-36C036D8-B0D9-3439-B009-9684C261DE64"><apiname>MMMFDataConsumer::BufferToBeEmptied()</apiname></xref> notification is received: </p> <codeblock id="GUID-4BF5B98C-F496-5AD9-9C0A-BA6B92FB2CA1" xml:space="preserve">virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0;</codeblock> </li> <li id="GUID-3A914F79-837D-5ADD-B8B1-70ACBAB7D2D1"><p>After emptying the buffer, respond by using the <xref href="GUID-72D6CC6A-D119-3A88-BADD-106B1D1EE1AA.dita#GUID-72D6CC6A-D119-3A88-BADD-106B1D1EE1AA/GUID-6724D6C0-AA02-3181-B6D0-6DF40728A257"><apiname>MMMFBufferSink::BufferEmptied()</apiname></xref> extension interface function: </p> <codeblock id="GUID-B3342CF3-0AEA-5356-8076-4DB3A8A53F30" xml:space="preserve">virtual Tint BufferEmptied(CMMFBuffer* aBuffer);</codeblock> <p>This is similar to the existing <xref href="GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita">DevSound</xref> behaviour. For more information, see <xref href="GUID-3FC6342D-D09C-5C7F-8E03-3DA7B29D2CC8.dita">Recording Audio</xref>. </p> </li> </ol> <p id="GUID-E2FC5EC6-57C0-53BB-9A5F-DC8BDA12E725"><b> Pausing and Continuing</b> </p> <p>To pause the audio currently being processed, use the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-19E9A726-DB06-3080-B685-35ACE8C48ED6"><apiname>MAudioStream::Prime()</apiname></xref> function: </p> <codeblock id="GUID-0E1999ED-FD4C-5632-AE99-0E2B741503B6" xml:space="preserve">virtual Tint Prime();</codeblock> <p>Calling <codeph>Prime()</codeph> requests a transition to the <codeph>EPrimed</codeph> state. After calling <codeph>Prime()</codeph>, the state change must be committed. </p> <p> <codeph>Prime()</codeph> temporarily stops the audio process. To continue audio processing from the <codeph>EPrimed</codeph> state, use the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-44094278-9D86-3FCE-BB2B-3CD88606BE19"><apiname>MAudioStream::Activate()</apiname></xref> function: </p> <codeblock id="GUID-167DD5B0-EF69-50B0-9564-E47BFF615C5A" xml:space="preserve">virtual Tint Activate();</codeblock> <p>After a successful commit cycle, the stream is transitioned to the <codeph>EActive</codeph> state, and processing resumes from the pause point. </p> <p id="GUID-495DC719-47C6-50B0-9A2D-9B00BEBA0E38"><b>Stopping While Playing</b> </p> <p>To stop audio processing while playing audio, use the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-338A5254-F6C0-3F9D-8635-CECF3B18AE26"><apiname>MAudioStream::Stop()</apiname></xref> function: </p> <codeblock id="GUID-AB5032AA-5B2C-5BE5-A7E7-CD77227DE7A9" xml:space="preserve">Virtual Tint Stop();</codeblock> <p> <codeph>Stop()</codeph> can be called while the stream state is <codeph>EActive</codeph> or <codeph>EPrimed</codeph>. </p> <p> <b>Note:</b> After calling <codeph>Stop()</codeph>, do not call <xref href="GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803.dita#GUID-4429668D-1F6F-3C0A-AEFA-45449D80D803/GUID-9E3C1A38-ED76-3954-8B6E-A88286FC841C"><apiname>MMMFBufferSource::BufferFilled()</apiname></xref> for any outstanding <xref href="GUID-11595177-B5B0-3EEC-8064-0D79F4BF3D2C.dita#GUID-11595177-B5B0-3EEC-8064-0D79F4BF3D2C/GUID-A029B562-5EB8-3795-B88C-CA8D90E60991"><apiname>MMMFDataSupplier::BufferToBeFilled()</apiname></xref> callbacks, as the buffer may not be valid anymore. </p> <p id="GUID-93CB9072-728A-598E-AD61-141D7FC9257E"><b>Stopping While Recording</b> </p> <p>To stop audio processing while recording audio, use the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-338A5254-F6C0-3F9D-8635-CECF3B18AE26"><apiname>MAudioStream::Stop()</apiname></xref> function: </p> <codeblock id="GUID-752F4CF7-E84D-52AF-9ED3-2899C639E43F" xml:space="preserve">Virtual Tint Stop();</codeblock> <p> <codeph>Stop()</codeph> can be called while the stream state is <codeph>EActive</codeph> or <codeph>EPrimed</codeph>. </p> <p> <b>Note:</b> Calling <codeph>Stop()</codeph> breaks the recording cycle and some buffers of audio data may be lost. To guarantee that no recorded data is lost when stopping, transition the stream from <codeph>EActive</codeph> to <codeph>EPrimed</codeph>, and wait for <xref href="GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C.dita#GUID-D2075F61-F6FA-3FAE-9FBB-20CEFE81334C/GUID-1B9E88D3-ACB0-3A50-A18D-217B8F9E4B82"><apiname>MAudioStreamObserver::ProcessingFinished()</apiname></xref> to return. Upon receiving the callback, transition the stream from: </p> <ol id="GUID-21113168-7523-5D39-BBA6-945665B53739"><li id="GUID-C3F11D6B-7F02-507B-A9BB-F850491C8C93"><p> <codeph>EPrimed</codeph> to <codeph>EIdle</codeph>  </p> </li> <li id="GUID-351D09AB-D078-5E55-9B70-193FA9867D76"><p> <codeph>EIdle</codeph> to <codeph>EInitialized</codeph>  </p> </li> <li id="GUID-C32D2D9B-1A15-53A3-BBBC-AF897267E635"><p> <codeph>EInitialized</codeph> to <codeph>EUninitialized</codeph>  </p> </li> </ol> <p id="GUID-CBD49226-AC35-5890-81F7-885E97A14E30"><b>Retrieving the Time Streamed</b> </p> <p>To retrieve the duration of the audio that has been processed, use the <xref href="GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6.dita#GUID-C5B1FE01-DCFC-3CA5-931B-E371AEC918A6/GUID-0C4DBDDA-BE83-35DD-B14E-BF0F3D78EB3B"><apiname>MAudioStream::GetStreamTime()</apiname></xref> function: </p> <codeblock id="GUID-9D927CE5-1646-5A40-A745-E4252C6F458E" xml:space="preserve">virtual TInt GetStreamTime(TTimeIntervalMicroSeconds&amp; aStreamTime);</codeblock> <p>The result returned is the microseconds processed since the last <codeph>EIdle</codeph> state. <codeph>GetStreamTime()</codeph> returns a zero value until audio processing starts. The function returns the time processed when the stream is in the <codeph>EPrimed</codeph> and <codeph>EActive</codeph> states. </p> </section> <section><title>See Also</title> <p><xref href="GUID-931207BE-3561-562D-8F67-0FB52CFF83CD.dita">Audio Component Framework Tutorial</xref>  </p> <p><xref href="GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita">Advanced Audio Adaptation Framework Technology Guide</xref>  </p> </section> </conbody></concept>