class EE::Audio::Music

Overview

Streamed music played from an audio file. More…

#include <music.hpp>

class Music: public EE::Audio::SoundStream {
public:
    // typedefs

    typedef Span<Time> TimeSpan;

    // structs

    template <typename T>
    struct Span;

    // construction

    ~Music();

    // methods

    static Music* New();
    bool openFromFile(const std::string& filename);
    bool openFromMemory(const void* data, std::size_t sizeInBytes);
    bool openFromStream(IOStream& stream);
    bool openFromPack(Pack* pack, const std::string& filePackPath);
    Time getDuration() const;
    TimeSpan getLoopPoints() const;
    void setLoopPoints(TimeSpan timePoints);
};

Inherited Members

public:
    // enums

    enum Status;

    // structs

    struct Chunk;

    // 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;
    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;

Detailed Documentation

Streamed music played from an audio file.

Musics are sounds that are streamed rather than completely loaded in memory. This is especially useful for compressed musics that usually take hundreds of MB when they are uncompressed: by streaming it instead of loading it entirely, you avoid saturating the memory and have almost no loading delay. This implies that the underlying resource (file, stream or memory buffer) must remain valid for the lifetime of the Music object.

Apart from that, a Music has almost the same features as the SoundBuffer / Sound pair: you can play/pause/stop it, request its parameters (channels, sample rate), change the way it is played (pitch, volume, 3D position, …), etc.

As a sound stream, a music is played in its own thread in order not to block the rest of the program. This means that you can leave the music alone after calling play(), it will manage itself very well.

Usage example:

// Declare a new music
Music music;

// Open it from an audio file
if (!music.openFromFile("music.ogg"))
{
 // error...
}

// Change some parameters
music.setPosition(0, 1, 10); // change its 3D position
music.setPitch(2);         // increase the pitch
music.setVolume(50);         // reduce the volume
music.setLoop(true);         // make it loop

// Play it
music.play();

See also:

Sound, SoundStream

Methods

bool openFromFile(const std::string& filename)

Open a music from an audio file.

This function doesn’t start playing the music (call play() to do so). See the documentation of InputSoundFile for the list of supported formats.

Warning

Since the music is not loaded at once but rather streamed continuously, the file must remain accessible until the Music object loads a new music or is destroyed.

Parameters:

filename

Path of the music file to open

Returns:

True if loading succeeded, false if it failed

See also:

openFromMemory, openFromStream

bool openFromMemory(const void* data, std::size_t sizeInBytes)

Open a music from an audio file in memory.

This function doesn’t start playing the music (call play() to do so). See the documentation of InputSoundFile for the list of supported formats.

Warning

Since the music is not loaded at once but rather streamed continuously, the data buffer must remain accessible until the Music object loads a new music or is destroyed. That is, you can’t deallocate the buffer right after calling this function.

Parameters:

data

Pointer to the file data in memory

sizeInBytes

Size of the data to load, in bytes

Returns:

True if loading succeeded, false if it failed

See also:

openFromFile, openFromStream

bool openFromStream(IOStream& stream)

Open a music from an audio file in a custom stream.

This function doesn’t start playing the music (call play() to do so). See the documentation of InputSoundFile for the list of supported formats.

Warning

Since the music is not loaded at once but rather streamed continuously, the stream must remain accessible until the Music object loads a new music or is destroyed.

Parameters:

stream

Source stream to read from

Returns:

True if loading succeeded, false if it failed

See also:

openFromFile, openFromMemory

Time getDuration() const

Get the total duration of the music.

Returns:

Music duration

TimeSpan getLoopPoints() const

Get the positions of the of the sound’s looping sequence.

Warning

Since setLoopPoints() performs some adjustments on the provided values and rounds them to internal samples, a call to getLoopPoints() is not guaranteed to return the same times passed into a previous call to setLoopPoints(). However, it is guaranteed to return times that will map to the valid internal samples of this Music if they are later passed to setLoopPoints().

Returns:

Loop Time position class.

See also:

setLoopPoints

void setLoopPoints(TimeSpan timePoints)

Sets the beginning and end of the sound’s looping sequence using Time.

Loop points allow one to specify a pair of positions such that, when the music is enabled for looping, it will seamlessly seek to the beginning whenever it encounters the end. Valid ranges for timePoints.offset and timePoints.length are [0, Dur) and (0, Dur-offset] respectively, where Dur is the value returned by getDuration(). Note that the EOF “loop point” from the end to the beginning of the stream is still honored, in case the caller seeks to a point after the end of the loop range. This function can be safely called at any point after a stream is opened, and will be applied to a playing sound without affecting the current playing offset.

Warning

Setting the loop points while the stream’s status is Paused will set its status to Stopped. The playing offset will be unaffected.

Parameters:

timePoints

The definition of the loop. Can be any time points within the sound’s length

See also:

getLoopPoints