The CMdaAudioRecorderUtility provides an interface to record audio clips to files, descriptors, or URLs. It also provides methods for creating and manipulating meta data entries in the newly recorded clips. Though this class is intended primarily for recording audio data, the playback methods have been included for convenience sake. If you just need to play back an audio clip it is recommended that you use CMdaAudioPlayerUtility instead, as it gives more control over playing and does not include the overheads that are necessary to support recording functionality.

The sequence of the audio recording and playback process is shown in the sequence diagram below:

To record an audio clip and playback do the following:

• Opening the target device for recording

• Configuring the recording parameters

• Recording audio data

• Edit audio data

• Meta data.

• Plug-in control.

When using CMdaAudioRecorderUtility you can specify the name of the file, descriptor, or URL to record/play in a variety of ways. The MMF can automatically detect the file format and codec of most audio clips with the exception of raw audio. When opening a raw audio file, the codec and the audio settings must be specified. This is reflected in the range of open statements available in CMdaAudioRecorderUtilityclass.

The recorder object can be initialised by choosing a default recording and playback device or by specifying the format and codec of the recording and playback device as shown below:

With default recording and playback device

To open an audio file for record with default audio device, after the creation of the recorder object, use one of the following methods depending on the type of the clip say file, descriptor, or URL:

OpenFileL(const TDesC& aFileName);

OpenDesL(const TDesC8& aDescriptor);

OpenUrlL(const TDesC& aUrl, TInt aIapId = KUseDefaultIap, const TDesC8& aMimeType=KNullDesC8);

With specific format and codec of the recording and playback device

To open an audio file for record with a specific device by giving specified format and codec, use one of the following methods depending on the type of the clip say file, descriptor, or URL:

void OpenFileL(const TDesC& aFileName, TUid aRecordControllerUid, TUid aPlaybackControllerUid=KNullUid, TUid aFormatUid=KNullUid, TFourCC aCodec=NULL);

void OpenDesL(TDesC8& aDescriptor, TUid aControllerUid, TUid aPlaybackControllerUid=KNullUid, TUid aFormatUid=KNullUid, TFourCC aCodec=NULL);

void OpenUrlL(const TDesC& aUrl, TInt aIapId, TUid aControllerUid, TUid aPlaybackControllerUid=KNullUid, TUid aFormatUid=KNullUid, TFourCC aCodec=NULL);

Use these open statements to open a specified medium (file, descriptor, or URL) so that it can be used for recording/play back. These methods come handy when MMF cannot automatically determine the format and codec to use from the audio data. For example, when using raw audio.

Note: There is also another method to open and audio clip from a file. It is strongly recommended to use this method.

OpenFileL(const TMMSource& aSource);

Where aSource is a filename or an open handle to a file which is a source of existing audio sample data.

Upon opening a file, descriptor, or URL to play or record audio data, configuration adjustments can be made using the methods described below. The configuration methods can be categorised into the following three parts that can be used to retrieve and set configuration parameters when playing back or recording audio data.

General

This category covers the setting of modes for the playing/recording devices, setting the maximum size of a recorded file, and playback priorities in relation to other applications that may be running. The methods are:

• To set the mode of the audio recording device, use SetAudioDeviceMode(). This function does not have effect from v7.0 onwards and is provided for binary compatibility only.

• To set the maximum size for a file, use SetMaxWriteLength(). This function sets the maximum size of the file in bytes to which the recording is to be done.

  If this limit is reached, MMF stops recording and notifies the client application. The Notification is caused by MMdaObjectStateChangeObserver::MoscoStateChangeEvent() with the error code KErrEof.

• To set the recording priority, use SetPriority(). The priority is used to arbitrate between multiple objects simultaneously trying to access the sound hardware.

Formats and Codecs

This category covers the reporting and setting of formats and codecs for audio data that is already open. The three methods relating 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.

The codec related methods are:

• DestinationDataTypeL():This function returns the codec that is currently set for the destination audio clip.

• SetDestinationDataTypeL(): This sets the codec to use with the record controller.

• GetSupportedDestinationDataTypesL(): This returns a list of the supported codecs for the conversion destination.

The data format related methods are:

• DestinationFormatL(): This function returns the UID of the destination audio clip.

• SetDestinationFormatL(): This function sets the format or UID of the audio clip. This can only be done if the audio clip does not exist.

Bit and Sample rates

This section covers the reporting and setting of bit rates for audio sinks, such as the internal speaker and the sample rates used to sample data that is to be saved to a file or descriptor.

Methods for controlling the bit rate of audio sinks are:

• GetSupportedBitRatesL():This function returns a list of the supported bit rates for recording to the data sink.

• DestinationBitRateL(): This function returns the bit rate in bits per second that the data sink is currently set to.

• SetDestinationBitRateL(): This function sets the bit rate of the data sink in bits per second. The bit rate must be one of the supported bit rates of the data sink. To get a list of supported bit rates, use GetSupportedBitRatesL().

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. For example, the audio format, MP3.

Methods for controlling the sampling rate of audio data are:

• GetSupportedSampleRatesL(): This function returns a list of supported recording sample rates.

• DestinationSampleRateL(): This function returns the sample rate in samples/second that the destination data sink is currently set to.

• SetDestinationSampleRateL(): This function sets the sample rate for the conversion destination data sink. The sample rate must be one of the supported bit rates of the data sink. To retreive a list of supported samples rates for the data sink, use GetSupportedSampleRatesL().

Adding to the above configuration settings, the gain, volume, and the balance features needs to be set. To set the gain see "setting the gain factor" section under Recording audio data. For more details on volume and balance settings see How to use CMdAAudioPlayerUtility

To record an audio data, do the following:

• Setting the gain factor

  To control gain settings for recording devices, use the following functions:

  • GetGain(): Returns the current gain settings of the audio device. The value can be anywhere between zero and the MaxGain().

  • MaxGain(): Returns the maximum value for the gain.

  • SetGain(): Sets the gain for the audio device to a specified value. If the value entered is more than the maximum permissible value, then the value is scaled down to the MaxGain() value. Before commencing the recording, it is recommended that the gain has to be set, as the initial gain is not defined or it may have been modified by other clients.

• Recording audio data

  To start recording audio data from the current position within the audio clip, use RecordL(). The new sample data is appended to the existing audio sample data in the same format as the existing one. If the data has to be overwritten, then the data must be cropped to the appropriate length before appending the new data.

  Note: Before starting to record, make sure the gain is set by calling SetGain(), as the initial gain is not defined.

  void CRecordAudio::RecordL(const TDesC& aFileName)
    {
    // Note: in this scenario, the calling code can handle the leave here
    // but alternatively we would have to trap and (using one-shot AO) arrange
    // for the callback to be subsequently called.
    
    iUtility->OpenFileL(aFileName); 
    }

• Stop audio recording

  To stop any ongoing recording session, use Stop(). The position within the audio clip is maintained for any subsequent RecordL() calls.

• Resume recording

  To resume a stopped recording use RecordL() after having used Stop().

For more details on how to play the recorded sample data, see How to use CMDAAudioPlayerUtility.

To close all related controllers, use Close() before opening a new clip.

The CMdaAudioRecorderUtility class allows you to set the start and end positions for playing and also permits the deletion of the recorded sample or overwrite it by cropping the recorded sample from the start or end of file. To retrieve or set the playing/recording position use the following methods:

• Position(): This function retrieves the current playing or recording position within the audio clip. The head position is defined in terms of a time interval measured from the beginning of the audio sample data.

• SetPosition(): This function sets the head position for the audio clip. The playback head is moved to a position which is defined in terms of a time interval measured from the beginning of the audio sample data. A subsequent call to PlayL() starts the play from this new position.

To delete the existing audio sample, use the following methods:

• CropL(): This functions deletes all the audio sample data after the current head location. This action cannot be undone.

• CropFromBeginningL(): This function deletes all the audio sample data from the beginning to the current head location. This action cannot be undone.

Some audio formats allow the use of meta data, enabling the creator or player of an audio clip to retrieve or set information that is held within the clip itself. This meta data is usually used to store information such as copyright information, creator, creation date and so on. The CMdaAudioRecorderUtility class allows to add, retrieve, and delete meta data details.

• To retrieve meta data use the methods:

  • To get the number of meta data entries in an audio clip use GetNumberOfMetaDataEntries().

  • To get a specific meta data entry in an audio clip useGetMetaDataEntryL().

• To add or replace entries use AddMetaDataEntryL() or ReplaceMetaDataEntryL() respectively.

• To delete specific meta data entries use RemoveMetaDataEntry().

• To get the progress of audio clip loading/rebuffering use GetAudioLoadingProgressL().

• To send a raw custom command synchronously to the controller use CustomCommandSync().

• To send a raw custom command asynchronously to the controller use CustomCommandAsync().