How to use the DevSound API

The DevSound API provides a common interface to the audio hardware for all audio functionality. DevSound is responsible for providing access to available audio resources, initialization and configuration of hardware devices, and playing and recording audio.

DevSound's functionality is provided by the CMMFDevSound class.

Construction and initialization

Each client using audio resources must have an instance of the CMMFDevSound class associated with it. The CMMFDevSound::NewL() method is used to construct a new instance of DevSound.

static IMPORT_C CMMFDevSound *NewL();

Once created, the CMMFDevSound::InitializeL() method is used to initialize DevSound to play and record. There are three versions of the CMMFDevSound::InitializeL() method, differing in type and number of parameters. The three versions are:

• CMMFDevSound::InitializeL() - initializes CMMFDevSound object to play and record PCM16 raw audio data with sampling rate of 8 KHz.

  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TMMFState
aMode);

  This method has two parameters:

  • MDevSoundObserver - a reference to a DevSound Observer instance.

  • TMMFState - the mode for which this object is to be used, for example, EMMFStatePlaying.

• CMMFDevSound::InitializeL() - initializes DevSound object for the mode aMode for processing audio data with hardware device aHWDev.

  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TUid aHWDev,
TMMFState aMode);

  This method has three parameters:

  • MDevSoundObserver - a reference to a DevSound Observer instance.

  • TUid - the CMMFHwDevice implementation identifier.

  • TMMFState - the mode for which this object is to be used, for example, EMMFStatePlaying.

• CMMFDevSound::InitializeL() - initializes DevSound object for the mode aMode for processing audio data with hardware device supporting FourCC aDesiredFourCC.

  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TFourCC
aDesiredFourCC, TMMFState aMode);

  This method has three parameters:

  • MDevSoundObserver - a reference to a DevSound Observer instance.

  • TFourCC - the CMMFHwDevice implementation FourCC code.

  • TMMFState - the mode for which this object is to be used, for example, EMMFStatePlaying.

All versions of CMMFDevSound::InitializeL() require a reference to a DevSound Observer instance. As soon as initialization of DevSound has completed, successfully or otherwise, the callback function MDevSoundObserver::InitializeComplete() is called.

The DevSound Observer

Most methods in the CMMFDevSound class are asynchronous. Callbacks occur through the MDevSoundObserver class. MDevSoundObserver is an interface to a set of DevSound callback functions. It serves as the method of communication between the client and the DevSound. A class that uses DevSound will typically inherit from MDevSoundObserver.

MDevSoundObserver handles the MDevSoundObserver::InitializeComplete() initialization completion event.

Refer to the following sections for detailed information on how to use the main features of the DevSound API:

• How to play audio

• How to pause and continue while playing audio

• How to retrieve the number of samples played while playing audio

• How to stop while playing audio

• How to play a tone

• How to play a DTMF tone

• How to play a fixed tone sequence

• How to play a tone sequence

• How to record audio

• How to pause and continue while recording audio

• How to retrieve the number of samples recorded while recording audio

• How to stop while recording audio

These examples describe some different uses of the DevSound API:

In this example, a client application wants to record a WAV file. As WAV is a standard file format supported by the MMF controller framework, the CMdaAudioRecorderUtility client API is used to interact with DevSound.

The main steps in recording the WAV file are:

1. The client application gives a request to record to the MMF CMdaAudioRecorderUtility client API.

2. The MMF CMdaAudioRecorderUtility client API passes the command down through the controller framework to the MMF controller plug-in.

3. The MMF controller plug-in initializes DevSound for recording.

4. Recording starts and continues until the client stops the recording or the limit on the file size is reached.

5. Upon completion, the client gives a request to the MMF controller framework to stop the recording. The controller framework passes the command down to the MMF controller plug-in.

6. The MMF controller plug-in stops DevSound and sends the completion event back to the client via controller framework.

In this example, a client application wants to play a Dual-Tone Multi-Frequency (DTMF) tone. The MMF CMdaAudioToneUtility client API is used to play the DTMF tone. Unlike other MMF APIs, the CMdaAudioToneUtility does not require a controller plug-in. This is because the input and output of the API is already in a known data format and does not require encoding or decoding. The CMdaAudioToneUtility communicates directly with DevSound.

The main steps in playing the DTMF tone are:

1. The client application prepares the CMdaAudioToneUtility to play a DTMF tone.

2. The client application asks the CMdaAudioToneUtility to start playing the tone.

3. The CMdaAudioToneUtility asks DevSound to play the tone.

4. The CMdaAudioToneUtility informs the client application that the playing of the tone is complete.

In this example, a client application wants to play an Audio Video Interleaved (AVI) file; output is to a screen and speakers. The AVI file contains audio and video data, so the CVideoPlayerUtility class is used as it can manipulate both types of data.

The main steps in playing the AVI file are:

1. The client application gives a request to play an AVI file to the MMF CVideoPlayerUtility class.

2. The MMF CVideoPlayerUtility class passes the request to the MMF controller framework. The controller framework loads the AVI controller plug-in.

3. The AVI controller plug-in initializes both DevSound and DevVideo.

4. The AVI controller plug-in reads the data in the AVI file and sends the audio data to DevSound and the video data to DevVideo.

5. DevSound outputs the audio data to the speakers.

   DevVideo sends the video data to be decoded by a codec. The decoded video data is then displayed on the screen.

• DevSound Overview