Audio Output Streaming Tutorial

This tutorial describes how to use Audio Output Streaming.

Purpose

The purpose of this tutorial is to show you how to open, play and then close an audio output stream.

Required Background

The user needs to maintain the data packets in a queue before starting to send it to the server. There is no need for the entire sound clip to arrive to be able to pass on to the low level audio controller. They can be forwarded as they arrive. If the server tends to receive data more than it can read or process, then a separate queue is maintained in the client side whose elements are references to the buffers passed to it. Once the server is free to receive more data the client sends the data in the queue and receives a notification from the server by means of a callback. As a result of this, the client deletes the data fragments from the queue.

Upon receiving the data packets the audio controller maintains them in the received buffers. A read function is instantiated to read the data into the destination descriptors.

Introduction

The Audio streaming API is the interface providing the functionalities for playing, stopping, and recording the audio stream to and from the audio buffers. The audio output stream interface class, CMdaAudioOutputStream, enables client applications to:

Stream raw audio data from specified buffers to audio devices.
Specify the priority of the audio stream relative to other clients trying to use the same hardware.
Set the sample rate and the number of audio channels before playback.
Adjust the volume and channel balance during playback.

Using Audio Output Streaming

Typically, using an audio output stream involves the following steps as shown in the sequence diagram below:

The following tasks will be covered in this tutorial:

Basic Procedure for Constructing an Audio Output Stream

The high level step to construct an audio output stream is shown here:

The client application creates an audio output stream object using the static function CMdaAudioOutputStream::NewL(). Optionally, it also sets the audio priorities to be able to access the audio hardware in relation to the other clients trying to access the same device.
```
static IMPORT_C CMdaAudioOutputStream *NewL(MMdaAudioOutputStreamCallback &aCallBack, 
TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);
```

Basic Procedure for Opening an Audio Output Stream

The high level steps to open an audio output stream are shown here:

To open the output stream, use the Open() member function. For example:
```
virtual void Open(TMdaPackage* aSettings);
```

Once the stream is open MMdaAudioOutputStreamCallback::MaoscOpenComplete() is invoked to indicate that the stream is ready to use.

void CIOStreamAudio::MaoscOpenComplete(TInt aError)
    {
    ASSERT(iState==EStateOpeningOutput);
    TInt error = aError;
    if (error==KErrNone)
        {
        iState = EStateWriting;    
        iOutputStream->SetVolume(iOutputStream->MaxVolume()/2);
        TRAP(error, iOutputStream->WriteL(iMainBuffer));
        }
    if (error!=KErrNone)
        {
        Complete(aError);    
        }
    }

Basic Procedure for Getting and Setting the Stream Properties

The high level steps to get and set stream properties are shown here:

To set the sampling rate and number of audio channels use SetAudioPropertiesL(). For example:
```
virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);
```
You cannot set these values while playing the stream. Also, you must specify them as enums; for example, TMdaAudioDataSettings::ESampleRate8000Hz rather than 8000 (Hz).
The Volume() and GetbalanceL() member functions let you determine current volume and balance settings. For example:
- ```
IMPORT_C TInt GetBalanceL() const;
```
- ```
virtual TInt Volume();
```
The SetVolume() and SetBalanceL() member functions let you set the volume and balance respectively. You can use them while the stream is open, with the new settings taking immediate effect.

Basic Procedure for Playing an Audio Output Stream

The high level steps to play an audio output stream are shown here:

To play an audio stream from the current position use the WriteL() member function. For example:

virtual void WriteL(const TDesC8& aData);

This function is asynchronous.

When aData is received, the client is notified by a call to MdaAudioOutputStreamCallback::MaoscBufferCopied().

void CIOStreamAudio::MaoscBufferCopied(TInt aError, const TDesC8& IFDEBUG(aBuffer))
    {
    ASSERT(iState==EStateWriting);
    if (aError!=KErrNone)
        {
        // ignore any KErrAbort returns - this would happen during a Stop() call
        // if we were playing 
        if (aError!=KErrAbort)
            {
            Complete(aError);    
            }
        }
    else
        {
        ASSERT(aBuffer.Length()==iMainBuffer.Length());
        // output almost complete - have been asked for more data
        iState = EStateWritingPostBuffer;
        }
    }

The WriteL() can be called again before this notification is triggered because the buffers are held in a client-side queue until they have been sent.

When the audio stream has completed playing, the callback function MMdaAudioOutputStreamCallback::MaoscPlayComplete() is invoked.

void CIOStreamAudio::MaoscPlayComplete(TInt aError)
    {
    ASSERT(iState==EStateWriting || iState==EStateWritingPostBuffer);
    TInt error = aError;
    if (aError==KErrUnderflow && iState==EStateWritingPostBuffer)
        {
        error = KErrNone; // normal termination is underflow following buffer request    
        }
    Complete(error);
    }

This closes the stream and sets the callback aError to KErrUnderFlow.

Basic Procedure for Stopping an Audio Output Stream

The high level step to stop an audio output stream is shown here:

To stop audio playback (stop data being sent to the stream) use the Stop() member function.

For example:
```
virtual void Stop();
```
This invokes MMdaAudioOutputStreamCallback::MaoscPlayComplete() to notify successful closure of the stream.

Audio Output Streaming Tutorial

Purpose

Using Audio Output Streaming

See Also