Playing
The Series 60 Platform includes three player classes for different purposes: one for playing sinewave tones, one for playing WAV sound clips and other supported formats, and one for streaming audio. The support for additional audio formats is done by media server plugins. Currently, in Series 60 there is a plug-in for polyphonic MIDI songs.
- Figure 13.1 Audio class diagram
13.1.1 Priorities
All playing requests have to have a priority. Through the priority value, Media Server chooses the client that has the highest priority to play and gives the playing shift for that. The priority value range is from -100 to 100. The default priority value is zero.
The priority value also has a priority preference. By that value, the audio driver decides what to do to the playing process in the lower-priority player. This decision is made when another client makes a playing request with a higher priority. The priority values and preferences are described in Avkon.hrh. It is very important to set a priority value and preference to every playing request. If such values are not set, the player client's request will receive the previous request's priority and preference.
13.1.2 Sinewave Tones
Sinewave tones are used, for instance, in basic monophonic ringing tones, information notes, and so on. The class for playing sinewave tones supports playing just one tone containing a note frequency and duration, playing a number of notes from the descriptor or a file, and playing a dual-tone multifrequency (DTMF) from a descriptor. These DTMF tones can be used during a phone call to simulate phone number key presses, every number, star, and pound mark has its own multifrequency tone.
class CMdaAudioToneUtility : public CBase {
public:
IMPORT_C static CMdaAudioToneUtility* NewL( MMdaAudioToneObserver& aObserver, CMdaServer* aServer=NULL);
virtual TMdaAudioToneUtilityState State()=0;
virtual Tint MaxVolume()=0; virtual Tint Volume()=0;
virtual void SetVolume(TInt aVolume)=0; virtual void SetPriority(TInt aPriority,
TMdaPriorityPreference aPref)=0; virtual void SetDTMFLengths(
TTimeIntervalMicroSeconds3 2 aToneOnLength, TTimeIntervalMicroSeconds3 2aToneOffLength, TTimeIntervalMicroSeconds32aPauseLength)=0; virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence)=0; virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds&
aRampDuration)=0; virtual TInt FixedSequenceCount()=0;
virtual const TDesC& FixedSequenceName(TInt aSequenceNumber)=0;
virtual void PrepareToPlayTone(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)=0; virtual void PrepareToPlayDTMFString(const TDesC& aDTMF)=0; virtual void PrepareToPlayDesSequence(const TDesC8& aSequence)=0; virtual void PrepareToPlayFileSequence(const TDesC& aFilename)=0; virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber)=0; virtual void CancelPrepare()=0; //
virtual void Play()=0; virtual void CancelPlay()=0; };
class MMdaAudioToneObserver {
public:
virtual void MatoPrepareComplete(TInt aError)=0;
virtual void MatoPlayComplete(TInt aError)=0; };
When adding a sinewave player to your own application, there has to be an observer class derived from the appropriate M class. The observer class also has to have implementations for methods described in the M class. Calling NewL() method creates an instance of the player class. This method takes a reference to an observer as a parameter. The observer's methods are called when the preparation is completed or when the playing has ended. Both of those methods could be called with an error value. If everything has gone fine, the parameter has KErrNone as a value. If there is an error it should be handled by the player class developer.
Below, we present an example implementation of initializing the player utility and starting playback. The CMyTonePlayer class is derived from MMdaAudioToneObserver, so it also implements the callback methods. In this case, the audio utility is prepared to play a file-based ringing tone. The format of the file sequence is described in the Smart messaging specification (Nokia, 2000). The playing volume and the priority of the utility can only be set when the player has been prepared successfully, otherwise a panic is raised. The implementation is as follows:
Void CMyTonePlayer::ConstructL() {
iMyToneUtility = CMdaAudioToneUtility::NewL(*this);
// KFile has complete path and filename of a ringing tone.
iMyToneUtility->PrepareToPlayFileSequence(KFile); }
void CMyTonePlayer::Play() {
iMyToneUtility->Play(); }
void CMyTonePlayer::MatoPrepareComplete(TInt aError) {
// If error occurred things below cannot be done.
iMyToneUtility->SetVolume(iMdaAudioToneUtility->MaxVolume());
iMyToneUtility->SetPriority(0, EMdaPriorityPreferenceTime); }
else
void CMyTonePlayer::MatoPlayComplete (TInt aError) {
Post a comment