sf::SoundBuffer Class Reference

Storage for audio samples defining a sound. More...

#include <SoundBuffer.hpp>

Public Member Functions
	SoundBuffer ()=default
	Default constructor.
	SoundBuffer (const SoundBuffer &copy)
	Copy constructor.
	SoundBuffer (const std::filesystem::path &filename)
	Construct the sound buffer from a file.
	SoundBuffer (const void *data, std::size_t sizeInBytes)
	Construct the sound buffer from a file in memory.
	SoundBuffer (InputStream &stream)
	Construct the sound buffer from a custom stream.
	SoundBuffer (const std::int16_t *samples, std::uint64_t sampleCount, unsigned int channelCount, unsigned int sampleRate, const std::vector< SoundChannel > &channelMap)
	Construct the sound buffer from an array of audio samples.
	~SoundBuffer ()
	Destructor.
bool	loadFromFile (const std::filesystem::path &filename)
	Load the sound buffer from a file.
bool	loadFromMemory (const void *data, std::size_t sizeInBytes)
	Load the sound buffer from a file in memory.
bool	loadFromStream (InputStream &stream)
	Load the sound buffer from a custom stream.
bool	loadFromSamples (const std::int16_t *samples, std::uint64_t sampleCount, unsigned int channelCount, unsigned int sampleRate, const std::vector< SoundChannel > &channelMap)
	Load the sound buffer from an array of audio samples.
bool	saveToFile (const std::filesystem::path &filename) const
	Save the sound buffer to an audio file.
const std::int16_t *	getSamples () const
	Get the array of audio samples stored in the buffer.
std::uint64_t	getSampleCount () const
	Get the number of samples stored in the buffer.
unsigned int	getSampleRate () const
	Get the sample rate of the sound.
unsigned int	getChannelCount () const
	Get the number of channels used by the sound.
std::vector< SoundChannel >	getChannelMap () const
	Get the map of position in sample frame to sound channel.
Time	getDuration () const
	Get the total duration of the sound.
SoundBuffer &	operator= (const SoundBuffer &right)
	Overload of assignment operator.

Friends
class	Sound

Detailed Description

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 bit 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 sf::SoundBuffer is similar to a sf::Texture.

A sound buffer can be loaded from a file, from memory, from a custom stream (see sf::InputStream) 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 sf::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 sf::SoundBuffer is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a sf::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 sf::Sound instances to the same sf::SoundBuffer.

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

Usage example:

// Load a new sound buffer from a file
const sf::SoundBuffer buffer("sound.wav");
 
// Create a sound source bound to the buffer
sf::Sound sound1(buffer);
 
// Play the sound
sound1.play();
 
// Create another sound source bound to the same buffer
sf::Sound sound2(buffer);
 
// Play it with a higher pitch -- the first sound remains unchanged
sound2.setPitch(2);
sound2.play();

See also

sf::Sound, sf::SoundBufferRecorder

Constructor & Destructor Documentation

SoundBuffer() [1/6]

sf::SoundBuffer::SoundBuffer ( )

default

Default constructor.

Construct an empty sound buffer that does not contain any samples.

SoundBuffer() [2/6]

sf::SoundBuffer::SoundBuffer

(

const SoundBuffer &

copy

)

Copy constructor.

Parameters

copy	Instance to copy

SoundBuffer() [3/6]

sf::SoundBuffer::SoundBuffer

(

const std::filesystem::path &

filename

)

Construct the sound buffer from a file.

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

Parameters

filename

Path of the sound file to load

Exceptions

`sf::Exception`

if loading was unsuccessful

See also

loadFromMemory, loadFromStream, loadFromSamples, saveToFile

SoundBuffer() [4/6]

sf::SoundBuffer::SoundBuffer	(	const void *	data,
		std::size_t	sizeInBytes )

Construct the sound buffer from a file in memory.

See the documentation of sf::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

Exceptions

`sf::Exception`

if loading was unsuccessful

See also

loadFromFile, loadFromStream, loadFromSamples

SoundBuffer() [5/6]

sf::SoundBuffer::SoundBuffer

(

InputStream &

stream

)

Construct the sound buffer from a custom stream.

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

Parameters

stream

Source stream to read from

Exceptions

`sf::Exception`

if loading was unsuccessful

See also

loadFromFile, loadFromMemory, loadFromSamples

SoundBuffer() [6/6]

sf::SoundBuffer::SoundBuffer	(	const std::int16_t *	samples,
		std::uint64_t	sampleCount,
		unsigned int	channelCount,
		unsigned int	sampleRate,
		const std::vector< SoundChannel > &	channelMap )

Construct the sound buffer from an array of audio samples.

The assumed format of the audio samples is 16 bit signed integer.

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)
channelMap	Map of position in sample frame to sound channel

Exceptions

`sf::Exception`

if loading was unsuccessful

See also

loadFromFile, loadFromMemory, saveToFile

~SoundBuffer()

sf::SoundBuffer::~SoundBuffer

(

)

Destructor.

Member Function Documentation

getChannelCount()

unsigned int sf::SoundBuffer::getChannelCount ( ) const

nodiscard

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, getChannelmap, getDuration

getChannelMap()

std::vector< SoundChannel > sf::SoundBuffer::getChannelMap ( ) const

nodiscard

Get the map of position in sample frame to sound channel.

This is used to map a sample in the sample stream to a position during spatialisation.

Returns

Map of position in sample frame to sound channel

See also

getSampleRate, getChannelCount, getDuration

getDuration()

Time sf::SoundBuffer::getDuration ( ) const

nodiscard

Get the total duration of the sound.

Returns

Sound duration

See also

getSampleRate, getChannelCount, getChannelmap

getSampleCount()

std::uint64_t sf::SoundBuffer::getSampleCount ( ) const

nodiscard

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

getSampleRate()

unsigned int sf::SoundBuffer::getSampleRate ( ) const

nodiscard

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, getChannelmap, getDuration

getSamples()

const std::int16_t * sf::SoundBuffer::getSamples ( ) const

nodiscard

Get the array of audio samples stored in the buffer.

The format of the returned samples is 16 bit signed integer. 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

loadFromFile()

bool sf::SoundBuffer::loadFromFile ( const std::filesystem::path & filename )

nodiscard

Load the sound buffer from a file.

See the documentation of sf::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

See also

loadFromMemory, loadFromStream, loadFromSamples, saveToFile

loadFromMemory()

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

nodiscard

Load the sound buffer from a file in memory.

See the documentation of sf::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

See also

loadFromFile, loadFromStream, loadFromSamples

loadFromSamples()

bool sf::SoundBuffer::loadFromSamples ( const std::int16_t * samples, std::uint64_t sampleCount, unsigned int channelCount, unsigned int sampleRate, const std::vector< SoundChannel > & channelMap )

nodiscard

Load the sound buffer from an array of audio samples.

The assumed format of the audio samples is 16 bit signed integer.

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)
channelMap	Map of position in sample frame to sound channel

Returns

True if loading succeeded, false if it failed

See also

loadFromFile, loadFromMemory, saveToFile

loadFromStream()

bool sf::SoundBuffer::loadFromStream ( InputStream & stream )

nodiscard

Load the sound buffer from a custom stream.

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

Parameters

stream

Source stream to read from

Returns

True if loading succeeded, false if it failed

See also

loadFromFile, loadFromMemory, loadFromSamples

operator=()

SoundBuffer & sf::SoundBuffer::operator=

(

const SoundBuffer &

right

)

Overload of assignment operator.

Parameters

right

Instance to assign

Returns

Reference to self

saveToFile()

bool sf::SoundBuffer::saveToFile ( const std::filesystem::path & filename ) const

nodiscard

Save the sound buffer to an audio file.

See the documentation of sf::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

Friends And Related Symbol Documentation

Sound

friend class Sound

friend

---

The documentation for this class was generated from the following file:

• SFML/Audio/SoundBuffer.hpp