class EE::Audio::SoundBuffer¶

Overview¶

Storage for audio samples defining a sound. More…

#include <soundbuffer.hpp>

class SoundBuffer: private EE::Audio::AlResource {
public:
    // construction

    SoundBuffer();
    SoundBuffer(const SoundBuffer& copy);
    ~SoundBuffer();

    // methods

    bool loadFromFile(const std::string& filename);
    bool loadFromMemory(const void* data, std::size_t sizeInBytes);
    bool loadFromStream(IOStream& stream);
    bool loadFromSamples(const Int16* samples, Uint64 sampleCount, unsigned int channelCount, unsigned int sampleRate);
    bool loadFromPack(Pack* pack, std::string filePackPath);
    bool saveToFile(const std::string& filename) const;
    const Int16* getSamples() const;
    Uint64 getSampleCount() const;
    unsigned int getSampleRate() const;
    unsigned int getChannelCount() const;
    Time getDuration() const;
    SoundBuffer& operator=(const SoundBuffer& right);
};

Detailed Documentation¶

Storage for audio samples defining a sound.

A sound buffer holds the data of a sound, which is an array of audio samples. A sample is a 16 bits signed integer that defines the amplitude of the sound at a given time. The sound is then reconstituted by playing these samples at a high rate (for example, 44100 samples per second is the standard rate used for playing CDs). In short, audio samples are like texture pixels, and a SoundBuffer is similar to a Texture.

A sound buffer can be loaded from a file (see loadFromFile() for the complete list of supported formats), from memory, from a custom stream (see IOStream) or directly from an array of samples. It can also be saved back to a file.

Sound buffers alone are not very useful: they hold the audio data but cannot be played. To do so, you need to use the Sound class, which provides functions to play/pause/stop the sound as well as changing the way it is outputted (volume, pitch, 3D position, …). This separation allows more flexibility and better performances: indeed a SoundBuffer is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a Sound is a lightweight object, which can use the audio data of a sound buffer and change the way it is played without actually modifying that data. Note that it is also possible to bind several Sound instances to the same SoundBuffer.

It is important to note that the Sound instance doesn’t copy the buffer that it uses, it only keeps a reference to it. Thus, a SoundBuffer must not be destructed while it is used by a Sound (i.e. never write a function that uses a local SoundBuffer instance for loading a sound).

Usage example:

// Declare a new sound buffer
SoundBuffer buffer;

// Load it from a file
if (!buffer.loadFromFile("sound.wav"))
{
 // error...
}

// Create a sound source and bind it to the buffer
Sound sound1;
sound1.setBuffer(buffer);

// Play the sound
sound1.play();

// Create another sound source bound to the same buffer
Sound sound2;
sound2.setBuffer(buffer);

// Play it with a higher pitch -- the first sound remains unchanged
sound2.setPitch(2);
sound2.play();

See also:

Sound, SoundBufferRecorder

Construction¶

SoundBuffer(const SoundBuffer& copy)

Copy constructor.

Parameters:

copy	Instance to copy

Methods¶

bool loadFromFile(const std::string& filename)

Load the sound buffer from a file.

See the documentation of InputSoundFile for the list of supported formats.

Parameters:

filename

Path of the sound file to load

Returns:

True if loading succeeded, false if it failed

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

Load the sound buffer from a file in memory.

See the documentation of InputSoundFile for the list of supported formats.

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

bool loadFromStream(IOStream& stream)

Load the sound buffer from a custom stream.

See the documentation of InputSoundFile for the list of supported formats.

Parameters:

stream

Source stream to read from

Returns:

True if loading succeeded, false if it failed

bool loadFromSamples(const Int16* samples, Uint64 sampleCount, unsigned int channelCount, unsigned int sampleRate)

Load the sound buffer from an array of audio samples.

The assumed format of the audio samples is 16 bits signed integer (Int16).

Parameters:

samples	Pointer to the array of samples in memory
sampleCount	Number of samples in the array
channelCount	Number of channels (1 = mono, 2 = stereo, …)
sampleRate	Sample rate (number of samples to play per second)

Returns:

True if loading succeeded, false if it failed

bool saveToFile(const std::string& filename) const

Save the sound buffer to an audio file.

See the documentation of OutputSoundFile for the list of supported formats.

Parameters:

filename

Path of the sound file to write

Returns:

True if saving succeeded, false if it failed

const Int16* getSamples() const

Get the array of audio samples stored in the buffer.

The format of the returned samples is 16 bits signed integer (Int16). The total number of samples in this array is given by the getSampleCount() function.

Returns:

Read-only pointer to the array of sound samples

See also:

getSampleCount

Uint64 getSampleCount() const

Get the number of samples stored in the buffer.

The array of samples can be accessed with the getSamples() function.

Returns:

Number of samples

See also:

getSamples

unsigned int getSampleRate() const

Get the sample rate of the sound.

The sample rate is the number of samples played per second. The higher, the better the quality (for example, 44100 samples/s is CD quality).

Returns:

Sample rate (number of samples per second)

See also:

getChannelCount, getDuration

unsigned int getChannelCount() const

Get the number of channels used by the sound.

If the sound is mono then the number of channels will be 1, 2 for stereo, etc.

Returns:

Number of channels

See also:

getSampleRate, getDuration

Time getDuration() const

Get the total duration of the sound.

Returns:

Sound duration

See also:

getSampleRate, getChannelCount

SoundBuffer& operator=(const SoundBuffer& right)

Overload of assignment operator.

Parameters:

right

Instance to assign

Returns:

Reference to self