<?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 id="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0" xml:lang="en"><title>How to use the audio convert utility</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-06F005A3-F80A-5428-9AFE-0BF1B567BE6D"><title>Overview</title> <p>Audio convert utility is used to convert audio clips contained
in files or descriptors to other formats using the default codecs
provided by MMF. This functionality is implemented by the <xref href="GUID-810D29DA-8332-3E63-8A63-5B8A04EC9688.dita"><apiname>CMdaAudioConvertUtility</apiname></xref> class. </p> </section>
<section id="GUID-598B8280-09AB-4A60-9400-0AAE88A8DE4B"><title>Description</title> <p>Using a audio converter utility
involves the following tasks: </p> <ul>
<li id="GUID-707AF876-DBB4-5AE0-8610-A9E6B5A7D543"><p> <xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita#GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0/GUID-8E3F0FF4-48D5-58E3-9F6B-643D7401EF47">Construct and open converter utility object</xref>  </p> </li>
<li id="GUID-0E4A77DB-0E03-5918-9EB1-8AF6F589490B"><p> <xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita#GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0/GUID-F46111C2-E670-5A1D-A091-48B2BB959C1F">Configure conversion parameters</xref>  </p> </li>
<li id="GUID-CDCA30C1-7474-554F-A81E-5B13D36B7652"><p> <xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita#GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0/GUID-5B8C4F5B-104E-58F8-A705-A3FD1E2B82FA">Convert audio clip</xref>  </p> </li>
<li id="GUID-07128D98-31E5-5090-B9CC-12FA2696A356"><p> <xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita#GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0/GUID-785AFDB4-527A-5AEA-88F3-91F8E348E049">Change conversion position and crop audio data </xref>  </p> </li>
<li id="GUID-58C88A02-7CB2-541C-AE59-CB92511D0C1C"><p> <xref href="GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0.dita#GUID-F46E4F89-B9ED-5A4A-B812-B605B925D0C0/GUID-E79175EB-EBAE-52FB-A594-04F2275A9A5F">Custom commands</xref>  </p> </li>
</ul> <p id="GUID-8E3F0FF4-48D5-58E3-9F6B-643D7401EF47"><b>Construct and open
converter utility object</b> </p> <p>The MMF provides a utility class
called <xref href="GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5.dita"><apiname>CMdaAudioConverterUtility</apiname></xref>. Using this class,
you can convert audio clips from one format to another. The <xref href="GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5.dita#GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5/GUID-751B7E8A-4464-3DF0-96C0-B5BDA1200E57"><apiname>CMdaAudioConverterUtility::NewL()</apiname></xref> function need to be used
to construct an object of this utility class, with the following arguments: </p> <ul>
<li id="GUID-11759C41-FAE9-59C5-89DA-131537795AED"><p>An object of
the class, which inherits the <xref href="GUID-C18F29E7-6A66-320A-8F19-988BA1E4EAB9.dita"><apiname>MMdaObjectStateChangeObserver</apiname></xref> class to receive state change notifications from the converter object. </p> </li>
<li id="GUID-577C3B7C-30A4-5ECC-A38D-DCE762F8AA80"><p>Client's relative
priority, which can be <codeph>EMdaPriorityMin</codeph>, <codeph>EMdaPriorityNormal</codeph> or <codeph>EMdaPriorityMax</codeph>. </p> </li>
<li id="GUID-1639A961-D674-525A-8B59-C1837441BD3B"><p>An object of <xref href="GUID-0C8D114E-EE63-3A33-83AE-AB75B23E4E71.dita"><apiname>TMdaPriorityPreference</apiname></xref> specifying the behaviour, if a higher
priority client takes over the device. </p> </li>
</ul> <p>The following code shows how the client application <codeph>CClientApp</codeph> inherits the <xref href="GUID-C18F29E7-6A66-320A-8F19-988BA1E4EAB9.dita"><apiname>MMdaObjectStateChangeObserver</apiname></xref> and creates the audio converter utility object: </p> <codeblock id="GUID-0DD27445-881B-5A95-8E06-BE066206B429" xml:space="preserve">class CClientApp : public CBase, MMdaObjectStateChangeObserver
    {
public:
   void CClientApp();
protected:

    // from MMdaObjectStateChangeObserver
    virtual void MoscoStateChangeEvent(CBase *aObject, TInt aPreviousState, TInt aCurrentState, TInt aErrorCode);
    
protected:
    CMdaAudioConverterUtility*    iConverter;   
    };

void CClientApp()
{    
    iConverter = CMdaAudioConverterUtility::NewL(*this, EMdaPriorityNormal,
                   EMdaPriorityPreferenceTimeAndQuality);
}
</codeblock> <p>Once the audio converter utility object is constructed,
you can open an audio clip for conversion using the function <xref href="GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5.dita#GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5/GUID-B6F6968B-3731-3FD3-AE85-003786EFCBF9"><apiname>CMdaAudioConverterUtility::OpenL()</apiname></xref>. You can use the following
versions of this function: </p> <ul>
<li id="GUID-4AAA0055-3EC1-5B47-8ED9-8A1562F45292"><p>To open an existing
audio file and append the converted audio data to another file, use
the following version: </p> <codeblock id="GUID-32DB2AEF-251A-5C2A-AE73-6BCCB4DEAC48" xml:space="preserve">OpenL(const TDesC&amp; aPrimaryFile, const TdesC&amp; aSecondaryFile);</codeblock> <p>Where, <codeph>aPrimaryFile</codeph> and <codeph>aSecondaryFile</codeph> are used to specify the source and destination audio file names. </p> </li>
<li id="GUID-403A3496-1B71-5DE0-AF6D-56453E7FC349"><p>To open existing
audio file and store the converted audio data to either a file or
a descriptor, use the following version: </p> <codeblock id="GUID-E5DCD0F0-BB3E-5AE4-AA6F-2D9D3A43B9B9" xml:space="preserve">OpenL(const TdesC&amp; aPrimaryFile
        TMdaClipLocation* aLocation,
        TMdaClipFormat* aFormat,
        TMdaPackage* aArg1 = NULL,
        TMdaPackage* aArg2 = NULL);
</codeblock> <p>Where, <codeph>aPrimaryFile</codeph> specifies the
source audio file names. The <codeph>aLocation</codeph>, <codeph>aFormat</codeph>, <codeph>aArg1</codeph> and <codeph>aArg2</codeph> are used to specify
the target location for the converted audio data, target audio format,
codec for the target audio and target audio settings. </p> </li>
<li id="GUID-0A3D5957-920F-5232-85A0-F5137A6E9759"><p>To open audio
data either from a file or a descriptor source and store the resulting
data to either a file or descriptor, use the following version: </p> <codeblock id="GUID-51904005-0194-587B-BBAE-5DD14FF09593" xml:space="preserve">OpenL(TmdaClipLocation* aPriLocation
        TMdaClipLocation* aSecLocation,
        TMdaClipFormat* aPriFormat,
        TMdaClipFormat* aSecFormat,
        TMdaPackage* aPriArg1 = NULL,
        TMdaPackage* aPriArg2 = NULL,
        TMdaPackage* aSecArg1 = NULL,
        TMdaPackage* aSecArg2 = NULL);
</codeblock> <p>Where, <codeph>aPriLocation</codeph> and <codeph>aPriLocation</codeph> specifies the source and destination audio data locations. The <codeph>aPriFormat</codeph> and <codeph>aSecFormat</codeph> specifies the
audio format of the source and target audio data. The <codeph>aPriArg1</codeph> and <codeph>aPriArg2</codeph> specifies codec and settings for the
source audio data. Whereas, the <codeph>aSecArg1</codeph> and <codeph>aSecArg2</codeph> specifies the codec and settings for the target
audio data. </p> </li>
</ul> <p> <b>Note</b>: It is recommended to use the first version
of <codeph>OpenL</codeph> to specify source and destination audio
file location. The arguments for the other versions are deprecated. </p> <p>The following code uses the first version of OpenL to specify
source and destination audio location: </p> <codeblock id="GUID-AEAF18F8-C228-581A-ADBF-48B67E72E8B2" xml:space="preserve">TFileName fromFilename = _L("C:\\rectest2.wav");
TFileName toFilename = _L("C:\\rectest2.wav");

iConverter-&amp;gt;OpenL(&amp;fromFilename, &amp;toFilename);
</codeblock> <p>Once the converter calls the <xref href="GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5.dita#GUID-30F792FF-577D-36F3-9905-6AAAC53B25D5/GUID-B6F6968B-3731-3FD3-AE85-003786EFCBF9"><apiname>CMdaAudioConverterUtility::OpenL()</apiname></xref> function, the callback function <xref href="GUID-C18F29E7-6A66-320A-8F19-988BA1E4EAB9.dita#GUID-C18F29E7-6A66-320A-8F19-988BA1E4EAB9/GUID-4FD38520-962C-3FA3-9F29-012695B1841B"><apiname>MMdaObjectStateChangeObserver::MoscoStateChangeEvent()</apiname></xref> will notify the client application about the change in state of
the object. </p> <p id="GUID-F46111C2-E670-5A1D-A091-48B2BB959C1F"><b>Configure conversion
parameters</b> </p> <p>The configuration parameters can be broadly
classified into four categories as shown below: </p> <p><b>Set recorded file length </b> </p> <p>You can control the size
settings of a recorded file. This is handled by the <xref href="GUID-123B2967-5B45-3FE3-9FDB-937D254DBAC7.dita"><apiname>SetMaxWriteLength()</apiname></xref> function that sets the maximum number of bytes that can be written
to a recorded audio clip. The <xref href="GUID-123B2967-5B45-3FE3-9FDB-937D254DBAC7.dita"><apiname>SetMaxWriteLength()</apiname></xref> function is provided so that converters can limit the amount of
file storage or memory that should be allocated. If the maximum limit
is reached, MMF stops recording and notifies the client application. </p> <p>The following code sets the maximum number of bytes to 800: </p> <codeblock id="GUID-D472EA81-8859-573A-BEB1-36B5C12577B4" xml:space="preserve">iConverter-&gt;SetMaxWriteLength(800);</codeblock> <p><b>Formats and Codecs </b> </p> <p>You can report and set formats
and codecs for audio data that is already open. The four methods related
to DataTypes (codecs) enable you to retrieve a list of supported codecs
for the current data format, set a new codec to use or determine which
codec is currently in use. A further three methods are provided to
query and set the audio format to use. </p> <p>Codec related actions: </p> <ul>
<li id="GUID-BEFE741E-42F8-5A2A-A045-9DEED5351AF8"><p>To get the data
type of the destination audio clip, use the <xref href="GUID-DE1B22B0-EA40-3400-8880-B8D02FEA53AE.dita"><apiname>DestinationDataTypeL()</apiname></xref> function. </p> </li>
<li id="GUID-88543928-F6EA-5D88-A470-383203E328C5"><p>To set the data
type of the destination audio clip, use the <xref href="GUID-C63D3BEC-50E2-39F3-9F72-E5FC1E7EDBC3.dita"><apiname>SetDestinationDataTypeL()</apiname></xref> function. </p> </li>
<li id="GUID-11EC06F6-E79D-53CA-8A55-E5E2A709695A"><p>To get a list
of supported data types for the conversion destination, use the <xref href="GUID-C2183CDC-E0E9-3324-BF38-5CC970F8E465.dita"><apiname>GetSupportedDestinationDataTypesL()</apiname></xref> function. </p> </li>
<li id="GUID-FC20AD49-B7F3-55AE-9DC9-96751497FF70"><p>To get the data
type of the source audio clip, use the <xref href="GUID-7B7BB5C5-2435-3AA8-B320-46E7BB308F16.dita"><apiname>SourceDataTypeL()</apiname></xref> function. </p> </li>
</ul> <p>Data format related actions: </p> <ul>
<li id="GUID-63B22181-DCE4-5CF4-AACE-52F92F529821"><p>To get the format
of the destination audio clip, use the <xref href="GUID-E0245ACC-E3AE-36EB-9126-8D8325CA23AA.dita"><apiname>DestinationFormatL()</apiname></xref> function. </p> </li>
<li id="GUID-E3224695-C58D-5986-819B-E7178ADF7537"><p>To set the format
of the destination audio clip, use the <xref href="GUID-730E4D19-96E7-373D-BC5C-981866923767.dita"><apiname>SetDestinationFormatL()</apiname></xref> function. </p> </li>
<li id="GUID-C4A10676-7A39-50B1-807D-1F91B8CC3743"><p>To get the format
of the source audio clip, use the <xref href="GUID-37E7132D-6E48-38FE-9C00-77E4AE4320B9.dita"><apiname>SourceFormatL()</apiname></xref> function. </p> </li>
</ul> <p> <b>Note</b>: It is only possible to report the format and
codec used by the source audio and cannot be changed. </p> <p><b>Bit and sample rates </b> </p> <p>You can report and set bit and
sample rates as required by specific codecs. </p> <p>Methods to control
the bit rate of audio data: </p> <ul>
<li id="GUID-6F218910-6BDD-5553-9648-1F62305F3589"><p>To get a list
of supported bit rates to the conversion destination, use the <xref href="GUID-5777E279-44DB-3256-A2FC-A1E7056EA7C0.dita"><apiname>GetSupportedConversionBitRatesL()</apiname></xref> function. </p> </li>
<li id="GUID-6ED4056A-AFAC-5051-B77F-DB094C6470CD"><p>To get the bit
rate of the destination audio clip, use the <xref href="GUID-2701C3DD-5E86-34EB-BF46-1B7E59B35CE6.dita"><apiname>DestinationBitRateL()</apiname></xref> function. </p> </li>
<li id="GUID-7B6C2AF7-E5BA-548C-BB91-182C4285D0D3"><p>To set the bit
rate of the destination audio clip, use the <xref href="GUID-CD9399AE-0525-3E6F-8D1D-69F7DD9C3774.dita"><apiname>SetDestinationBitRateL()</apiname></xref> function. The bit rate must be one of the supported bit rates of
the audio target. Use the <xref href="GUID-5777E279-44DB-3256-A2FC-A1E7056EA7C0.dita"><apiname>GetSupportedConversionBitRatesL()</apiname></xref> function to retrieve a list of supported bit rates. </p> </li>
<li id="GUID-0D644C39-21EF-57DB-B1C3-EA6109E05AF0"><p>To get the bit
rate of the source audio clip, use the <xref href="GUID-A3511295-70AE-38D6-A362-334CD3722D26.dita"><apiname>SourceBitRateL()</apiname></xref> function. </p> </li>
</ul> <p> <b>Note</b>: None of the default codecs provided in the
MMF support the use of bit rates. These methods are provided to enable
the creation of additional codecs that might require bit rate information,
such as the audio format MP3. </p> <p>Methods for controlling the
sampling rate of audio data: </p> <ul>
<li id="GUID-C59895FE-BAF7-54E3-B5C9-8BC559EF1B32"><p>To get a list
of supported conversion sample rates, use the <xref href="GUID-1F8A204E-D666-37AA-8591-FC325684EF3E.dita"><apiname>GetSupportedConversionSampleRatesL()</apiname></xref> function. The list of sample rates is used by the conversion destination. </p> </li>
<li id="GUID-CB4C78D7-827D-5247-8832-8A7271087CAC"><p>To get the sample
rate of the conversion destination, use the <xref href="GUID-67DF026D-A62F-37F7-A581-388CF65B4E5A.dita"><apiname>DestinationSampleRateL()</apiname></xref> function. </p> </li>
<li id="GUID-390679E1-CB13-5722-B090-8E5001142FE3"><p>To set the sample
rate for the conversion destination, use the <xref href="GUID-71A4BDE9-4785-35E4-95CE-0AECF929C7D9.dita"><apiname>SetDestinationSampleRateL()</apiname></xref> function. The sample rate must be one of the supported sample rates
of the audio target. Use the <xref href="GUID-1F8A204E-D666-37AA-8591-FC325684EF3E.dita"><apiname>GetSupportedConversionSampleRatesL()</apiname></xref> function to retrieve a list of supported sample rates. </p> </li>
<li id="GUID-5A4D9803-D3FA-5C3E-A110-4B910A675B26"><p>To get the sample
rate of the source audio clip, use the <xref href="GUID-FBC478AB-D28C-3BB2-B4C7-6FD2111B00CC.dita"><apiname>SourceSampleRateL()</apiname></xref> function. </p> </li>
</ul> <p> <b>Note</b>: It is only possible to report the bit rate
or sample rate used by the source audio and cannot be changed. </p> <p><b>Balance </b> </p> <p>You can report and set the audio mode (mono
or stereo). </p> <ul>
<li id="GUID-AE349537-63C5-500A-96BC-FFD62CA6FA16"><p>To get a list
of the supported number of channels for conversion, use the <xref href="GUID-C5418287-E4F4-3E4A-B91C-64D814B8BA60.dita"><apiname>GetSupportedConversionNumberOfChannelsL()</apiname></xref> function. </p> </li>
<li id="GUID-36B76579-0DA0-5514-9E5F-3B7AAA31F16B"><p>To get the number
of channels the destination audio clip contains, use the <xref href="GUID-C954863D-701A-3A9A-AC60-00F3CB48F46F.dita"><apiname>DestinationNumberOfChannelsL()</apiname></xref> function. </p> </li>
<li id="GUID-B6CC8F43-C44F-5C1B-909F-4517C31844CF"><p>To set the number
of channels the destination audio clip contains, use the <xref href="GUID-87973927-F58D-3961-9777-E9E2A7C7DF22.dita"><apiname>SetDestinationNumberOfChannelsL()</apiname></xref> function. The number
of channels must be one of the values returned by <xref href="GUID-C5418287-E4F4-3E4A-B91C-64D814B8BA60.dita"><apiname>GetSupportedConversionNumberOfChannelsL()</apiname></xref>. </p> </li>
<li id="GUID-7C522973-402E-5231-9A51-76C640C13568"><p>To get the number
of channels used by the conversion source, use the <xref href="GUID-D74F993C-E4AA-3645-88FC-14C699423110.dita"><apiname>SourceNumberOfChannelsL()</apiname></xref> function. </p> </li>
</ul> <p> <b>Note</b>: It is only possible to report the number of
supported channels for the source audio and cannot be changed. </p> <p id="GUID-5B8C4F5B-104E-58F8-A705-A3FD1E2B82FA"><b> Convert audio clip</b> </p> <p>Several methods are provided in <xref href="GUID-810D29DA-8332-3E63-8A63-5B8A04EC9688.dita"><apiname>CMdaAudioConvertUtility</apiname></xref> to enable the conversion of audio data. The specific functions to
convert and perform related tasks are as follows: </p> <ul>
<li id="GUID-ED4D516E-EDD0-59D4-86C9-06E61189D2A5"><p>To start converting
audio data from the current position within the audio source and writing
the converted data to a play window within the destination file, use
the <xref href="GUID-F25BDC34-C955-312A-838E-09CA2EBAB418.dita"><apiname>ConvertL()</apiname></xref> function. </p> </li>
<li id="GUID-41EF4109-6406-5777-A696-72421DF6E4C4"><p>To stop audio
conversion, use the <xref href="GUID-7CBDCF0D-1D11-34D1-BF5C-1E5B50DA75B5.dita"><apiname>Stop()</apiname></xref> function. The positions
within the audio source and destination are maintained to handle subsequent <xref href="GUID-F25BDC34-C955-312A-838E-09CA2EBAB418.dita"><apiname>ConvertL()</apiname></xref> statements. </p> </li>
<li id="GUID-F1C55C8A-F965-5857-A488-4C029CFC6D07"><p>To stop audio
conversion and close all related controllers, use the <xref href="GUID-01D2AF56-21E1-3FF3-BF86-0C356A1658EF.dita"><apiname>Close()</apiname></xref> function. </p> </li>
</ul> <p id="GUID-785AFDB4-527A-5AEA-88F3-91F8E348E049"><b>Change conversion
position and crop audio data</b> </p> <p>It is possible to crop the
audio clip from the current position to the end of the clip or from
the begging to the current position as illustrated below: </p> <ul>
<li id="GUID-31CF2D85-4ACD-5B37-A4F9-67F435BE302C"><p>To crop the
current clip from the current position, use the <xref href="GUID-55FA7E3D-0137-3B74-8911-0D21D3038B85.dita"><apiname>CropL()</apiname></xref> function. The remainder of the clip is discarded. The effects of
the function cannot be undone. The function is synchronous and can
leave if there is a problem. The leave code depends on the configuration
settings. </p> </li>
<li id="GUID-70B87D7E-D4C2-5A26-B1D2-44315A404D4A"><p>To crop the
audio clip from the start of the file to the current position, use
the <xref href="GUID-EFB452A7-07A7-3AA8-988A-BD3EB2E1EF0A.dita"><apiname>CropFromBeginningL()</apiname></xref> function. The audio data
prior to the current position is discarded. The effects of the function
cannot be undone. The function is synchronous and can leave if there
is a problem. The leave code depends on the configuration settings. </p> </li>
</ul> <p>To retrieve the current position of the audio clip or move
the position to the desired location use the following functions: </p> <ul>
<li id="GUID-4764FACE-A6E6-58DE-81A2-B6DF19647673"><p>To get the current
position in the audio clip, use the <xref href="GUID-663106A9-3FA5-3471-A9C6-9D2FFD94FB7B.dita"><apiname>Position()</apiname></xref> function.
The position is defined in terms of a time interval measured from
the beginning of the audio sample data. </p> </li>
<li id="GUID-431A1E59-15CC-5463-83D5-64FE363369FA"><p>To set the current
position in the audio clip, use the <xref href="GUID-2C54E7FC-7C61-35FA-B129-1B15FFAC8F69.dita"><apiname>SetPosition()</apiname></xref> function. A subsequent call to the <xref href="GUID-F25BDC34-C955-312A-838E-09CA2EBAB418.dita"><apiname>ConvertL()</apiname></xref> function starts conversion from this new position. </p> </li>
</ul> <p id="GUID-E79175EB-EBAE-52FB-A594-04F2275A9A5F"><b> Custom commands</b> </p> <ul>
<li id="GUID-403EADC5-2D41-54F5-A97B-3484B754109B"><p>To send a raw
custom command synchronously to the controller or to allow data to
be returned from the controller, use the <xref href="GUID-8B88A239-C622-3952-9737-A7BEEA99AC9B.dita"><apiname>CustomCommandSync() </apiname></xref> function. </p> </li>
<li id="GUID-8958B82D-B1C5-5D27-B931-D957735955E4"><p>To send a raw
custom command asynchronously to the controller or to allows data
to be returned from the controller, use the <xref href="GUID-601DC50C-CD58-3604-98B2-35A7B5E6EBD8.dita"><apiname>CustomCommandAsync() </apiname></xref> function. </p> </li>
</ul> </section>
<section id="GUID-1AEF4A81-2898-46F5-AC26-E5DDA3E64061"><title>See Also</title> <p> <xref href="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita">How to use the audio
tone player utility</xref>  </p> </section>
</conbody></concept>