The CMdaAudioPlayerUtility class provides an interface to open, play, and obtain information from sampled audio data. The audio data can be supplied either in a file, descriptor, or an URL.

The sequence of the audio play process is shown in the sequence diagram below:

To play an audio clip do the following:

• Constructing and opening audio source

• Play and related functions

• Controlling the volume, balance, and audio priority

• Audio clip properties

• Metadata properties

• Plug-in control

The CMdaAudioPlayerUtility accepts filename, descriptor, or URL to play an audio clip in a variety of ways. This class can automatically detect the file format and codec of most audio clips with the exception of raw audio. To play raw audio, it is necessary to first create the player object using NewL() and then use OpenUrlL().

The player object can be initialised as shown below:

Use NewL() if you want to instantiate the player object without having to specify an audio clip.

static CMdaAudioPlayerUtility* NewL(MMdaAudioPlayerCallback& aCallback, TInt aPriority=EMdaPriorityNormal, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

playerUtility=NewL(callback, EMdaPriorityNormal, EMdaPriorityPreferenceTimeAndQuality);

As soon as initialisation of the audio player utility is complete, successfully or otherwise, the callback function MMdaAudioPlayerCallback::MapcInitComplete() is called. A sample implementation is shown below:

void CPlayAudio::MapcInitComplete(TInt aError, const TTimeIntervalMicroSeconds& /*aDuration*/)
    {
    // initialisation phase has finished. If error, report back to caller,
    // if OK then call Play()
    if (aError!=KErrNone)
        {
        iObserver->PlayComplete(aError);
        }
    else
        {
        iUtility->Play();
        }
    }

Note: Additional audio clips can be played using the same instance of the player utility by using any of the open statements described.

To open an audio clip after the player object has been created, use one 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);

playerUtility->OpenFileL(aFilename);

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 containing the audio track. The audio track is expected to be in the supported format[WAV or AU]. If the user tries to open an audio track when a previous open statement is awaiting notification of completion, it leaves with KErrInUse error.

This sections explains various functions involved in the audio play process. After initializing the CMdaAudioPlayerUtility object, the Play() function is called for the audio clip to be played. If the user wishes to pause the play for a few seconds, it is achieved by calling the Pause() function. The play can be resumed by calling the Play()function again. In this case the play resumes from the point where it was paused.

The CMdaAudioPlayerUtility class is intended for playing audio data only.

void CPlayAudio::Play(const TDesC& aFileName)
    {
    iUtility->OpenFileL(aFileName); 
    }

If the play needs to be halted before it naturally ends itself, a Stop()function is called. As a result of this, a callback function MMdaAudioPlayerCallback::MapcPlayComplete() is invoked. If playback is already complete, the function Stop() has no effect.

CPlayAudio::~CPlayAudio()
    {
    if (iUtility)
        {
        // if it exists, always stop the utility - null action if not running
        iUtility->Stop();
        delete iUtility;
        }
    }

void CPlayAudio::MapcPlayComplete(TInt aError)
    {
    // play has completed
    iObserver->PlayComplete(aError);
    }

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

While the audio clip is been played, certain properties as listed below may be configured for better audio quality :

• To get the current playback volume, use GetVolume().

  To configure volume settings of the audio device use SetVolume(). This changes the current playback volume to a specified value. The volume can be set before or during the playback and takes immediate effect. The value set can be anywhere between zero to the maximum permissible value. If a value greater than the maximum value is entered the value is scaled down to the maximum value.

  The maximum permissible playback volume is obtained by MaxVolume() function.

  TheSetVolumeRamp()function defines the period over which the volume level is expected to rise smoothly to the normal volume level.

• To control the balance of audio channels, use the methods GetBalance() and SetBalance(). The value can be anywhere between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. The default value is KMMFBalanceCenter.

• To set the priority for the playback to access the audio device, use the method SetPriority(). This is used to arbitrate between multiple clients trying to access a single sound device. The client with the highest priority cannot be interrupted by any other clients whereas the client with least priority can be overridden by all other clients. The normal priority client can only be interrupted by the high priority clients.

To get audio clip properties such as bit rate and current playback position use the following methods:

• To get bit rate of the audio clip opened, use the method GetBitRate().

• To retrieve the current playback position of the audio clip, use GetPosition().

Some audio formats support meta data, enabling the player of an audio clip to retrieve 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 following are the two meta data methods provided by the CMdaAudioPlayerUtility:

• To get the number of meta data entries in an audio clip use GetNumberOfMetaDataEntries(). This information is normally stored in the header.

• To get a specific meta data entry in an audio clip useGetMetaDataEntryL(). It returns with an error if a metadata entry do not exist or an unsupported metadata entry is requested for.

Note:It is not possible to set meta data using this class. If you need to set meta data, use CMdaAudioConvertUtility instead.

The relationship with an audio controller can be studied by the use of the following function:

To allow applications to query implementation information about the controller plugin in action, use ControllerImplementationInformationL(). This returns the controller implementation information associated with the current controller.