How to use the audio convert utility

Overview

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 CMdaAudioConvertUtility class.

Description

Using a audio converter utility involves the following tasks:

Construct and open converter utility object
Configure conversion parameters
Convert audio clip
Change conversion position and crop audio data
Custom commands

Construct and open converter utility object

The MMF provides a utility class called CMdaAudioConverterUtility. Using this class, you can convert audio clips from one format to another. The CMdaAudioConverterUtility::NewL() function need to be used to construct an object of this utility class, with the following arguments:

An object of the class, which inherits the MMdaObjectStateChangeObserver class to receive state change notifications from the converter object.
Client's relative priority, which can be EMdaPriorityMin, EMdaPriorityNormal or EMdaPriorityMax.
An object of TMdaPriorityPreference specifying the behaviour, if a higher priority client takes over the device.

The following code shows how the client application CClientApp inherits the MMdaObjectStateChangeObserver and creates the audio converter utility object:

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);
}

Once the audio converter utility object is constructed, you can open an audio clip for conversion using the function CMdaAudioConverterUtility::OpenL(). You can use the following versions of this function:

To open an existing audio file and append the converted audio data to another file, use the following version:
```
OpenL(const TDesC& aPrimaryFile, const TdesC& aSecondaryFile);
```
Where, aPrimaryFile and aSecondaryFile are used to specify the source and destination audio file names.
To open existing audio file and store the converted audio data to either a file or a descriptor, use the following version:
```
OpenL(const TdesC& aPrimaryFile
        TMdaClipLocation* aLocation,
        TMdaClipFormat* aFormat,
        TMdaPackage* aArg1 = NULL,
        TMdaPackage* aArg2 = NULL);
```
Where, aPrimaryFile specifies the source audio file names. The aLocation, aFormat, aArg1 and aArg2 are used to specify the target location for the converted audio data, target audio format, codec for the target audio and target audio settings.
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:
```
OpenL(TmdaClipLocation* aPriLocation
        TMdaClipLocation* aSecLocation,
        TMdaClipFormat* aPriFormat,
        TMdaClipFormat* aSecFormat,
        TMdaPackage* aPriArg1 = NULL,
        TMdaPackage* aPriArg2 = NULL,
        TMdaPackage* aSecArg1 = NULL,
        TMdaPackage* aSecArg2 = NULL);
```
Where, aPriLocation and aPriLocation specifies the source and destination audio data locations. The aPriFormat and aSecFormat specifies the audio format of the source and target audio data. The aPriArg1 and aPriArg2 specifies codec and settings for the source audio data. Whereas, the aSecArg1 and aSecArg2 specifies the codec and settings for the target audio data.

Note: It is recommended to use the first version of OpenL to specify source and destination audio file location. The arguments for the other versions are deprecated.

The following code uses the first version of OpenL to specify source and destination audio location:

TFileName fromFilename = _L("C:\\rectest2.wav");
TFileName toFilename = _L("C:\\rectest2.wav");

iConverter-&gt;OpenL(&fromFilename, &toFilename);

Once the converter calls the CMdaAudioConverterUtility::OpenL() function, the callback function MMdaObjectStateChangeObserver::MoscoStateChangeEvent() will notify the client application about the change in state of the object.

Configure conversion parameters

The configuration parameters can be broadly classified into four categories as shown below:

Set recorded file length

You can control the size settings of a recorded file. This is handled by the SetMaxWriteLength() function that sets the maximum number of bytes that can be written to a recorded audio clip. The SetMaxWriteLength() 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.

The following code sets the maximum number of bytes to 800:

iConverter->SetMaxWriteLength(800);

Formats and Codecs

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.

Codec related actions:

To get the data type of the destination audio clip, use the DestinationDataTypeL() function.
To set the data type of the destination audio clip, use the SetDestinationDataTypeL() function.
To get a list of supported data types for the conversion destination, use the GetSupportedDestinationDataTypesL() function.
To get the data type of the source audio clip, use the SourceDataTypeL() function.

Data format related actions:

To get the format of the destination audio clip, use the DestinationFormatL() function.
To set the format of the destination audio clip, use the SetDestinationFormatL() function.
To get the format of the source audio clip, use the SourceFormatL() function.

Note: It is only possible to report the format and codec used by the source audio and cannot be changed.

Bit and sample rates

You can report and set bit and sample rates as required by specific codecs.

Methods to control the bit rate of audio data:

To get a list of supported bit rates to the conversion destination, use the GetSupportedConversionBitRatesL() function.
To get the bit rate of the destination audio clip, use the DestinationBitRateL() function.
To set the bit rate of the destination audio clip, use the SetDestinationBitRateL() function. The bit rate must be one of the supported bit rates of the audio target. Use the GetSupportedConversionBitRatesL() function to retrieve a list of supported bit rates.
To get the bit rate of the source audio clip, use the SourceBitRateL() function.

Note: 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.

Methods for controlling the sampling rate of audio data:

To get a list of supported conversion sample rates, use the GetSupportedConversionSampleRatesL() function. The list of sample rates is used by the conversion destination.
To get the sample rate of the conversion destination, use the DestinationSampleRateL() function.
To set the sample rate for the conversion destination, use the SetDestinationSampleRateL() function. The sample rate must be one of the supported sample rates of the audio target. Use the GetSupportedConversionSampleRatesL() function to retrieve a list of supported sample rates.
To get the sample rate of the source audio clip, use the SourceSampleRateL() function.

Note: It is only possible to report the bit rate or sample rate used by the source audio and cannot be changed.

Balance

You can report and set the audio mode (mono or stereo).

To get a list of the supported number of channels for conversion, use the GetSupportedConversionNumberOfChannelsL() function.
To get the number of channels the destination audio clip contains, use the DestinationNumberOfChannelsL() function.
To set the number of channels the destination audio clip contains, use the SetDestinationNumberOfChannelsL() function. The number of channels must be one of the values returned by GetSupportedConversionNumberOfChannelsL().
To get the number of channels used by the conversion source, use the SourceNumberOfChannelsL() function.

Note: It is only possible to report the number of supported channels for the source audio and cannot be changed.

Convert audio clip

Several methods are provided in CMdaAudioConvertUtility to enable the conversion of audio data. The specific functions to convert and perform related tasks are as follows:

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 ConvertL() function.
To stop audio conversion, use the Stop() function. The positions within the audio source and destination are maintained to handle subsequent ConvertL() statements.
To stop audio conversion and close all related controllers, use the Close() function.

Change conversion position and crop audio data

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:

To crop the current clip from the current position, use the CropL() 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.
To crop the audio clip from the start of the file to the current position, use the CropFromBeginningL() 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.

To retrieve the current position of the audio clip or move the position to the desired location use the following functions:

To get the current position in the audio clip, use the Position() function. The position is defined in terms of a time interval measured from the beginning of the audio sample data.
To set the current position in the audio clip, use the SetPosition() function. A subsequent call to the ConvertL() function starts conversion from this new position.

Custom commands

To send a raw custom command synchronously to the controller or to allow data to be returned from the controller, use the CustomCommandSync() function.
To send a raw custom command asynchronously to the controller or to allows data to be returned from the controller, use the CustomCommandAsync() function.

How to use the audio convert utility

Overview

Description

See Also