Audio Tone Player Overview

Provides a simple interface for tone generation (synthesized sounds) that enables the playing of tone sequences and DTMF (Dual-Tone Multi-Frequency) strings. The tone player functionality is provided by the CMdaAudioToneUtility class and using this class you can play:

• Single tones of a specified duration and frequency.

• DTMF strings.

• Sequences of tones held in files or descriptors.

• Predefined (fixed) sequences of tones held in the mobile equipment.

How the tone player class interacts with other components of MMF is shown below.

The playing of sounds is handled by MMF (Multi-Media framework) and this, in turn, is responsible for managing the interface to audio hardware. On some devices, this may be implemented as a device driver; on others it may be implemented as a connection to a lower level hardware server.

Clients using this API must have an active scheduler running in their thread because the implementation of the API uses active objects and callbacks.

CMdaAudioToneUtility provides a simple interface to generate single and multiple tones. The tone data can be supplied in a number of ways depending on whether it is a single tone, a DTMF string or a string of non-DTMF tones. Once the tone utility object has been constructed, multiple tones and tone sequences can be played without having to create new instances of the object.

For the purposes of this description, the use of the tone utility has been broken down into the following sections.

• Construction and preparation - describes the options available for initially constructing the CMdaAudioToneUtility object, then the subsequent preparation commands to prepare the object for playing.

• Configuration - describes the various configuration settings such as volume and balance settings that can be queried or set.

• Playing - describes the controls available for playing tones.

The initial construction of the CMdaAudioToneUtility is performed using NewL(). There are two variants of this function, one creates the tone utility with default priority settings, the second enables you to specify your own settings. The two NewL() functions are shown below:

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

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

Both functions require that you specify an observer class to use to handle the callbacks issued by the prepare, play and cancel play methods.

Note: The CMdaServer* parameters are not used within v7.0s, they are only provided for binary compatibility with previous versions.

Following successful creation of the tone utility, use one of the following prepare methods:

• Use the following method if you want to play a single tone of a fixed frequency and duration.

  virtual void PrepareToPlayTone(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);

• Use the following method if you want to play a DTMF string stored in a descriptor.

  virtual void PrepareToPlayDTMFString(const TDesC& aDTMF);

• Use one of the following methods if you want to play a sequence of non-DTMF tones held within an file or descriptor.

  virtual void PrepareToPlayFileSequence(const TDesC& aFilename);

virtual void PrepareToPlayDesSequence(const TDesC8& aSequence);

• Use the following method if you want to play a sequence of non-DTMF tones that are pre-stored on the mobile equipment.

  virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber);

• Use the following method if you want to play a dual tone.

  void PrepareToPlayDualTone(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration);

All of the prepare methods are asynchronous. On completion of a prepare, the observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the prepare operation.

Any of the prepare operations can be cancelled by using CancelPrepare().

Following construction and preparation, configuration adjustments can be made using the methods described below.

• GetBalanceL() and SetBalanceL() - gets and sets the audio balance.

• Volume() and SetVolume() - gets and sets the volume settings of the audio device.

• MaxVolume() and SetVolumeRamp() - gets the maximum volume setting supported by the audio device and defines the period over which the volume level is to rise smoothly from nothing to the normal volume level.

• SetPriority() - sets the priority of the audio device. This priority setting is used to arbitrate between multiple objects trying to access a controller.

• SetDTMFLengths() - sets the duration of DTMF tones, the gaps between DTMF tones, and the pauses.

• FixedSequenceCount() - returns the number of available pre-defined tone sequences held in the mobile equipment.

• FixedSequenceName() - returns the name of the specified fixed tone sequence.

Once the tone utility object is created, any type of tone or sequence can be played by first issuing the correct prepare statement and then using Play(). To play another tone or sequence, either wait for MMdaAudioToneObserver::MatoPlayComplete() to be issued after completion of playing the previous tone or sequence, or use CancelPlay() and then issue the relevant prepare statement. Once the prepare has completed successfully, use Play().

The following methods are provided to enable playing of tones and sequences:

• Play() - plays the tone, DTMF or tone sequence specified by the previous prepare statement. This function is asynchronous; on completion, the observer callback function MMdaAudioToneObserver::MatoPlayComplete() is called, indicating the success or failure of the play operation.

• CancelPlay() - cancels the tone, DTMF or tone sequence currently playing. The observer callback function MMdaAudioToneObserver::MatoPlayComplete() is not called on completion of the cancel.

• CancelPrepare() - cancels the current prepare statement. The observer callback function MMdaAudioToneObserver::MatoPrepareComplete() is not called on completion of the cancel.

• SetRepeats() - sets the number of times the tone sequence is repeated during the play operation.

• State() - returns the current state of the tone utility.

• Multi Media Framework Client Overview - general overview of the various components of the MMF Client API and the functionality they provide.

• Audio Recording, Conversion and Playing - advanced audio file manipulation features; specifically, the ability to record, convert and playback sound clips as well as to manipulate meta data.

  • Audio Recording - introduction to the audio recording class.

  • Audio Conversion - introduction to the audio conversion class.

  • Audio Playing - introduction to the audio playing class.

• Audio Streaming - the interface to streaming sampled audio.

• Audio Tone Player - a simple interface for tone generation (synthesized sounds) that is supported on all audio-capable devices.

• Video Recording and Playing - video manipulation features; specifically, the ability to record and playback video clips as well as to manipulate meta data.

  • Video Recording - introduction to the video recording class.

  • Video Playing - introduction to the video playing class.