How to use the audio tone player utility

The Audio Tone Player, provided by the class CMdaAudioToneUtility, has an interface for generating the following tones on all audio capable devices. Using this class you can play the following tones:

Single tone of a specified duration and frequency
Dual Tone Multi Frequency (DTMF) strings
Sequences of tones held in files or descriptors
Predefined (fixed) sequences of tones held in any mobile equipment

Client applications such as ringtone applications, use CMdaAudioToneUtility to generate the tones they produce. The tone player in turn uses MMF for playing sounds and is also credited for interfacing with the audio hardware. An active scheduler is needed for all the clients applications for the use of active objects and callbacks.

Using the tone player

The tone player provides a simple interface to generate single and multiple tones. Once the tone player object has been constructed, multiple tones and tone sequences can be played without having to create new instances of the object.

Using the tone player typically involves the following steps:

Figure: Tone Player Utility

Constructing a tone player

The CMdaAudioToneUtility object can be constructed using the NewL() member function. There are two versions of this constructor function:

create a tone player with default priority settings:

static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer=NULL);

create a tone player with your own settings:

static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer, TInt aPriority,
TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

Both functions pass a reference of the MMdaAudioToneObserver object to the tone player. The MMdaAudioToneObserver is an observer interface to notifications from the member functions Prepare, Play, and, CancelPlay callback functions.

Preparing a tone player

Once the tone player object is created, it has to be prepared to play a tone or a DTMF string. use one of the following prepare member functions to get it ready for playing the corresponding tone.

PrepareToPlayTone() - to play a single tone of a fixed frequency (Hz) and duration (microseconds). For example:
```
virtual void PrepareToPlayTone(TInt    aFrequency, const TTimeIntervalMicroSeconds& aDuration);
```
PrepareToPlayDTMFString() - to play a DTMF string held in a descriptor. For example:
```
virtual void PrepareToPlayDTMFString(const TDesC& aDTMF);
```
PrepareToPlayFileSequence() - to play a sequence of non-DTMF tones held in a file. For example:
```
virtual void PrepareToPlayFileSequence(const TDesC& aFilename);
```
PrepareToPlayDesSequence() - to play a sequence of non-DTMF tones held in a descriptor. For example:
```
virtual void PrepareToPlayDesSequence(const TDesC8& aSequence);
```
PrepareToPlayFixedSequence() - to play a sequence of non-DTMF tones stored on the mobile equipment. For example:
```
virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber); 
```
PrepareToPlayDualTone() - to play a dual tone. For example:
```
void PrepareToPlayDualTone(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration); 
```
The two tones, aFrequencyOne and aFrequencyTwo, are measured in Hz, and the duration of the tone, aDuration, is measured in microseconds.

All the prepare member functions are asynchronous. In response to each, CMdaAudioToneUtility creates a CMMFToneConfig derived object that stores the data for the type of tone to play.

On completion of a prepare, the observer function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the prepare operation. If successful you can play the tone.

You can cancel any prepare function using CancelPrepare() (the observer callback function is not called on completion of the cancel).

Playing a tone

Once the player is prepared successfully, certain configurations can be done before playing the tone as listed below:

Volume() and SetVolume() - This retrieves the current volume settings and sets to a new value specified by the user respectively.
GetBalanceL() and SetBalanceL() - This retrieves the current balance of the audio device and sets the audio balance specified by the user respectively..
SetPriority() - This sets the priority of the audio device. The priority is defined to arbitrate between multiple objects trying to access the controller at the same time.
SetVolumeRamp() - This defines the period over which the volume level is to rise (in microseconds) smoothly from zero to the specified volume level. A value of 0 causes the tone to be played at the SetVolume() level for the full duration of the playback. A value that is longer than the duration of the tone sequence means that the tone never reaches the specified volume.
```
virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds &aRampDuration);
```
SetDTMFLengths() - This alters the duration of DTMF tone, the gaps between two DTMF tones, and the pauses in microseconds.
FixedSequenceCount() - This returns the number of available pre-defined tone sequences, the number always being greater than zero.
FixedSequenceName() - This returns the name of the specified fixed tone sequence.

Upon successful configuration, the Play() can be called as shown below.

Play() - plays the tone, DTMF or tone sequence specified by the prepare statement. For example:

virtual void Play();

Here, the tone player uses the Play() from the audio player utility to play the tone.

This function is asynchronous. It retrieves the details of the type of tone to play from the previous Prepare statement. When the tone has been played to completion, the observer callback function MMdaAudioToneObserver::MatoPlayComplete() is called, indicating the success or failure of the play operation. The play operation can be cancelled by calling the CancelPlay() member function.

Playing the tone or DTMF string can be customised using the following member functions as mentioned below:

SetRepeats() - sets the number of times the tone sequence (plus an optional trailing silent period, measured in microseconds) is repeated during the play operation. For example:
```
virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds &aTrailingSilence);
```
You can repeat the tone sequence indefinitely by setting aRepeatNumberOfTimes to KMdaRepeatForever.
State() - returns the current state of the tone player (an enum):
- EMdaAudioToneUtilityNotReady - not prepared to play a tone
- EMdaAudioToneUtilityPrepared - prepared and ready to play a tone
- EMdaAudioToneUtilityPlaying - currently playing a tone
For example:
```
virtual TMdaAudioToneUtilityState State();
```

To play another tone or sequence, either wait for MMdaAudioToneObserver::MatoPlayComplete() callback to be issued when the current tone or DTMF string completes playing, or use CancelPlay() and then issue the relevant prepare statement. The Play() function following the prepare statement plays the tone or DTMF string based on the previously issued prepare statement.

Cancelling a tone

CancelPlay() - cancels the tone, DTMF, or tone sequence currently playing. For example:

virtual void CancelPlay();

The observer callback function is not called on completion of the cancel.

Retrieving a custom interface

To retrieve a custom interface to the underlying device, use the CustomInterface() member function. For example:

IMPORT_C TAny *CustomInterface(TUid aInterfaceId);

aInterfaceId is the UID of the interface function required.

The function returns a pointer to the interface implementation, or NULL if the device does not implement the interface requested. You must cast the return value to the correct type.

How to use the audio tone player utility

Using the tone player

See Also