Class CMdaAudioPlayerUtility

CMdaAudioPlayerUtility

Support

Supported from 5.0

Description

Plays sampled audio data.

The class offers a simple interface to open, play and obtain information from, sampled audio data. The audio data can supplied either in a file (file-based) or as a descriptor (descriptor-based).

While this class is abstract, the three static functions construct, initialise and return pointers to instances of concrete classes derived from this abstract class. This concrete class is part of the Media Server implementation and is private.

Derivation

CBase Base class for all classes to be instantiated on the heap CMdaAudioPlayerUtility Plays sampled audio data

Defined in CMdaAudioPlayerUtility:
Duration(), MaxVolume(), NewDesPlayerL(), NewDesPlayerReadOnlyL(), NewFilePlayerL(), Play(), SetRepeats(), SetVolume(), SetVolumeRamp(), Stop()

Inherited from CBase:
operator new()

static CMdaAudioPlayerUtility* NewFilePlayerL(const TDesC& aFileName, MMdaAudioPlayerCallback& aCallback, TInt aPriority=EMdaPriorityNormal, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

Description

Constructs and initialises a new instance of the audio player utility for playing sampled audio data from a file. The audio data must be in a supported format (e.g. WAV and AU).

The function leaves if the audio player utility object cannot be created.

When initialisation of the audio player utility is complete, successfully or otherwise, the callback function MMdaAudioPlayerCallback::MapcInitComplete() is called.

Parameters

const TDesC& aFileName The full path name of the file containing the audio data. MMdaAudioPlayerCallback& aCallback The audio player observer interface. Tint aPriority=EMdaPriorityNormal This client's relative priority. This is a value between -100 and +100 and represents a relative priority. A higher value indicates a more important request. The absolute priority at which a client application runs depends on the EPOC platform. TMdaPriorityPreference aPref=EmdaPriorityPreferenceTimeAndQuality The required behaviour if a higher priority client takes over the sound output device.

Return value

CMdaAudioPlayerUtility* Pointer to the new audio player utility object.

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

Description

Constructs and initialises a new instance of the audio player utility for playing sampled audio data from a descriptor. The audio data must be in a supported format (e.g. WAV and AU).

The function leaves if the audio player utility object cannot be created.

When initialisation of the audio player utility is complete, successfully or otherwise, the callback function MMdaAudioPlayerCallback::MapcInitComplete() is called.

Parameters

TDes8& aData A descriptor containing the audio data. This descriptor must remain in existence for the lifetime of this audio player utility object. MMdaAudioPlayerCallback& aCallback The audio player observer interface. TInt aPriority=EmdaPriorityNormal This client's relative priority. This is a value between -100 and +100 and represents a relative priority. A higher value indicates a more important request. The absolute priority at which a client application runs depends on the EPOC platform. TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality The required behaviour if a higher priority client takes over the sound output device.

Return value

CMdaAudioPlayerUtility* Pointer to a new audio player utility object.

static CMdaAudioPlayerUtility* NewDesPlayerReadOnlyL(const TDesC8& aData, MMdaAudioPlayerCallback& aCallback, TInt aPriority=EMdaPriorityNormal, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

Description

Constructs and initialises a new instance of the audio player utility for playing sampled audio data from a read only descriptor. The audio data must be in a supported format (e.g. WAV and AU).

The function leaves if the audio player utility object cannot be created.

When initialisation of the audio player utility is complete, successfully or otherwise, the callback function MMdaAudioPlayerCallback::MapcInitComplete() is called.

Parameters

const TDesC8& aData A read only descriptor containing the audio data. This descriptor must remain in existence for the lifetime of this audio player utility object. MMdaAudioPlayerCallback& aCallback The audio player observer interface. Tint aPriority=EmdaPriorityNormal This client's relative priority. This is a value between -100 and +100 and represents a relative priority. A higher value indicates a more important request. The absolute priority at which a client application runs depends on the EPOC platform. TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality The required behaviour if a higher priority client takes over the sound output device.

Return value

CMdaAudioPlayerUtility* Pointer to a new audio player utility object.

virtual void Play() = 0;

Description

Begins playback of the initialised audio sample at the current volume and priority levels.

When playing of the audio sample is complete, successfully or otherwise, the callback function MMdaAudioPlayerCallback::MapcPlayComplete() is called.

This function raises a CMdaAudioPlayerUtility 1 panic if the audio player utility is not initialised.

virtual void SetVolume(TInt aVolume) = 0;

Description

Changes the current playback volume to a specified value.

The volume can be changed before or during playback and is effective immediately.

The function raises a CMdaAudioPlayerUtility 1 panic if the audio player utility is not initialised.

Parameters

TInt aVolume The volume setting. This can be any value from zero to the value returned by a call to CMdaAudioPlayerUtility::MaxVolume(). Setting a zero value mutes the sound. Setting the maximum value results in the loudest possible sound.

virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence) = 0;

Description

Sets the number of times the audio sample is to be repeated during the playback operation.

A period of silence can follow each playing of the sample. The audio sample can be repeated indefinitely.

Parameters

TInt aRepeatNumberOfTimes The number of times the audio sample, together with the trailing silence, is to be repeated. If this is set to KMdaRepeatForever, then the audio sample, together with the trailing silence, is repeated indefinitely or until Stop() is called. If this is set to zero, then the audio sample is not repeated. const TTimeIntervalMicroSeconds& aTrailingSilence The time interval of the training silence.

virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration) = 0;

Description

Defines the period over which the volume level is to rise smoothly from nothing to the normal volume level.

Parameters

const TTimeIntervalMicroSeconds& aRampDuration The period over which the volume is to rise. A zero value causes the audio sample to be played at the normal level for the full duration of the playback. A value which is longer than the duration of the audio sample means that the sample never reaches its normal volume level.

virtual void Stop() = 0;

Description

Stops playback of the audio sample as soon as possible.

If the audio sample is playing, playback is stopped as soon as possible. If playback is already complete, nothing further happens as a result of calling this function.

The callback function MMdaAudioPlayerCallback::MapcPlayComplete() is not called.

The function raises a CMdaAudioPlayerUtility 1 panic if the audio player utility is not initialised.

virtual const TTimeIntervalMicroSeconds& Duration() = 0;

Description

Returns the duration of the audio sample.

The function raises a CMdaAudioPlayerUtility 1 panic if the audio player utility is not initialised.

Return value

TTimeIntervalMicroSeconds& The duration in microseconds

virtual TInt MaxVolume() = 0;

Description

Returns an integer representing the maximum volume. This is the maximum value which can be passed to CMdaAudioPlayerUtility::SetVolume().

The function raises a CMdaAudioPlayerUtility 1 panic if the audio player utility is not initialised.

Return value

TInt The maximum volume. This value is platform dependent but is always greater than or equal to one.