class EE::Audio::SoundStream

Overview

Abstract base class for streamed audio sources. More…

#include <soundstream.hpp>

class SoundStream: public EE::Audio::SoundSource {
public:
    // structs

    struct Chunk;

    // construction

    virtual ~SoundStream();

    // methods

    virtual void play();
    virtual void pause();
    virtual void stop();
    unsigned int getChannelCount() const;
    unsigned int getSampleRate() const;
    virtual Status getStatus() const;
    void setPlayingOffset(Time timeOffset);
    Time getPlayingOffset() const;
    void setLoop(bool loop);
    bool getLoop() const;
};

Inherited Members

public:
    // enums

    enum Status;

    // methods

    void setPitch(float pitch);
    void setVolume(float volume);
    void setPosition(float x, float y, float z);
    void setPosition(const Vector3f& position);
    void setRelativeToListener(bool relative);
    void setMinDistance(float distance);
    void setAttenuation(float attenuation);
    float getPitch() const;
    float getVolume() const;
    Vector3f getPosition() const;
    bool isRelativeToListener() const;
    float getMinDistance() const;
    float getAttenuation() const;
    SoundSource& operator=(const SoundSource& right);
    virtual void play() = 0;
    virtual void pause() = 0;
    virtual void stop() = 0;
    virtual Status getStatus() const;

Detailed Documentation

Abstract base class for streamed audio sources.

Unlike audio buffers (see SoundBuffer), audio streams are never completely loaded in memory. Instead, the audio data is acquired continuously while the stream is playing. This behavior allows to play a sound with no loading delay, and keeps the memory consumption very low.

Sound sources that need to be streamed are usually big files (compressed audio musics that would eat hundreds of MB in memory) or files that would take a lot of time to be received (sounds played over the network).

SoundStream is a base class that doesn’t care about the stream source, which is left to the derived class. EEPP provides a built-in specialization for big files (see Music). No network stream source is provided, but you can write your own by combining this class with the network module.

A derived class has to override two virtual functions:

• onGetData fills a new chunk of audio data to be played

• onSeek changes the current playing position in the source

It is important to note that each SoundStream is played in its own separate thread, so that the streaming loop doesn’t block the rest of the program. In particular, the OnGetData and OnSeek virtual functions may sometimes be called from this separate thread. It is important to keep this in mind, because you may have to take care of synchronization issues if you share data between threads.

Usage example:

class CustomStream : public SoundStream
{
public:

 bool open(const std::string& location)
 {
     // Open the source and get audio settings
     ...
     unsigned int channelCount = ...;
     unsigned int sampleRate = ...;

     // Initialize the stream -- important!
     initialize(channelCount, sampleRate);
 }

private:

 virtual bool onGetData(Chunk& data)
 {
     // Fill the chunk with audio data from the stream source
     // (note: must not be empty if you want to continue playing)
     data.samples = ...;
     data.sampleCount = ...;

     // Return true to continue playing
     return true;
 }

 virtual void onSeek(Uint32 timeOffset)
 {
     // Change the current position in the stream source
     ...
 }
}

// Usage
CustomStream stream;
stream.open("path/to/stream");
stream.play();

See also:

Music

Methods

virtual void play()

Start or resume playing the audio stream.

This function starts the stream if it was stopped, resumes it if it was paused, and restarts it from the beginning if it was already playing. This function uses its own thread so that it doesn’t block the rest of the program while the stream is played.

See also:

pause, stop

virtual void pause()

Pause the audio stream.

This function pauses the stream if it was playing, otherwise (stream already paused or stopped) it has no effect.

See also:

play, stop

virtual void stop()

Stop playing the audio stream.

This function stops the stream if it was playing or paused, and does nothing if it was already stopped. It also resets the playing position (unlike pause()).

See also:

play, pause

unsigned int getChannelCount() const

Return the number of channels of the stream.

1 channel means a mono sound, 2 means stereo, etc.

Returns:

Number of channels

unsigned int getSampleRate() const

Get the stream sample rate of the stream.

The sample rate is the number of audio samples played per second. The higher, the better the quality.

Returns:

Sample rate, in number of samples per second

virtual Status getStatus() const

Get the current status of the stream (stopped, paused, playing)

Returns:

Current status

void setPlayingOffset(Time timeOffset)

Change the current playing position of the stream.

The playing position can be changed when the stream is either paused or playing. Changing the playing position when the stream is stopped has no effect, since playing the stream would reset its position.

Parameters:

timeOffset

New playing position, from the beginning of the stream

See also:

getPlayingOffset

Time getPlayingOffset() const

Get the current playing position of the stream.

Returns:

Current playing position, from the beginning of the stream

See also:

setPlayingOffset

void setLoop(bool loop)

Set whether or not the stream should loop after reaching the end.

If set, the stream will restart from beginning after reaching the end and so on, until it is stopped or setLoop(false) is called. The default looping state for streams is false.

Parameters:

loop	True to play in loop, false to play once

See also:

getLoop

bool getLoop() const

Tell whether or not the stream is in loop mode.

Returns:

True if the stream is looping, false otherwise

See also:

setLoop