SFML 3.0.0

- Main Page
- Topics
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
sf::SoundBuffer Class Reference
Audio module

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

`#include <SFML/Audio/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).

When loading sound samples from an array, a channel map needs to be provided, which specifies the mapping of the position in the sample frame to the sound channel. For example when you have six samples in a frame and a 5.1 sound system, the channel map defines how each of those samples map to which speaker channel.

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();
// Load samples with a channel map
auto samples = std::vector<std::int16_t>();
// ...
auto channelMap = std::vector<sf::SoundChannel>{
sf::SoundChannel::FrontLeft,
sf::SoundChannel::FrontCenter,
sf::SoundChannel::FrontRight,
sf::SoundChannel::BackRight,
sf::SoundChannel::BackLeft,
sf::SoundChannel::LowFrequencyEffects
};
auto soundBuffer = sf::SoundBuffer(samples.data(), samples.size(), channelMap.size(), 44100, channelMap);
auto sound = sf::Sound(soundBuffer);
sf::SoundBuffer
Storage for audio samples defining a sound.
Definition SoundBuffer.hpp:55
sf::Sound
Regular sound that can be played in the audio environment.
Definition Sound.hpp:48
sf::SoundChannel::FrontRight
@ FrontRight
sf::SoundChannel::FrontLeft
@ FrontLeft
sf::SoundChannel::BackRight
@ BackRight
sf::SoundChannel::LowFrequencyEffects
@ LowFrequencyEffects
sf::SoundChannel::BackLeft
@ BackLeft
sf::SoundChannel::FrontCenter
@ FrontCenter

See also
  `sf::Sound`, `sf::SoundBufferRecorder`

Definition at line 54 of file SoundBuffer.hpp.

## 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 | ) |
| explicit

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 | ) |
| explicit

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 spatialization.

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

Definition at line 317 of file SoundBuffer.hpp.

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

- SoundBuffer.hpp