Skip to content

class SF::SoundBuffer
inherits Reference #

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

A sound buffer can be loaded from a file (see load_from_file() for the complete list of supported formats), 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
buffer = SF::SoundBuffer.from_file("sound.wav")

# Create a sound source and bind it to the buffer
sound1 = SF::Sound.new
sound1.buffer = buffer

# Play the sound
sound1.play()

# Create another sound source bound to the same buffer
sound2 = SF::Sound.new
sound2.buffer = buffer

# Play it with a higher pitch -- the first sound remains unchanged
sound2.pitch = 2
sound2.play()

See also: SF::Sound, SF::SoundBufferRecorder

Included modules

SF::AlResource

Class methods#

.from_file(*args, **kwargs) : self #

Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_file(...); sound_buffer

Raises InitError on failure

View source

.from_memory(*args, **kwargs) : self #

Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_memory(...); sound_buffer

Raises InitError on failure

View source

.from_samples(*args, **kwargs) : self #

Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_samples(...); sound_buffer

Raises InitError on failure

View source

.from_stream(*args, **kwargs) : self #

Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_stream(...); sound_buffer

Raises InitError on failure

View source

.new #

Default constructor

View source

Methods#

#channel_count : Int32 #

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: sample_rate, duration

View source

#duration : Time #

Get the total duration of the sound

Returns: Sound duration

See also: sample_rate, channel_count

View source

#finalize #

Destructor

View source

#load_from_file(filename : String) : Bool #

Load the sound buffer from a file

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

  • filename - Path of the sound file to load

Returns: True if loading succeeded, false if it failed

See also: load_from_memory, load_from_stream, load_from_samples, save_to_file

View source

#load_from_memory(data : Slice) : Bool #

Load the sound buffer from a file in memory

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

  • data - Slice containing the file data in memory

Returns: True if loading succeeded, false if it failed

See also: load_from_file, load_from_stream, load_from_samples

View source

#load_from_samples(samples : Array(Int16) | Slice(Int16), channel_count : Int, sample_rate : Int) : Bool #

Load the sound buffer from an array of audio samples

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

  • samples - Pointer to the array of samples in memory
  • sample_count - Number of samples in the array
  • channel_count - Number of channels (1 = mono, 2 = stereo, ...)
  • sample_rate - Sample rate (number of samples to play per second)

Returns: True if loading succeeded, false if it failed

See also: load_from_file, load_from_memory, save_to_file

View source

#load_from_stream(stream : InputStream) : Bool #

Load the sound buffer from a custom stream

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

  • stream - Source stream to read from

Returns: True if loading succeeded, false if it failed

See also: load_from_file, load_from_memory, load_from_samples

View source

#sample_count : UInt64 #

Get the number of samples stored in the buffer

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

Returns: Number of samples

See also: samples

View source

#sample_rate : Int32 #

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: channel_count, duration

View source

#samples : Pointer(Int16) #

Get the array of audio samples stored in the buffer

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

Returns: Read-only pointer to the array of sound samples

See also: sample_count

View source

#save_to_file(filename : String) : Bool #

Save the sound buffer to an audio file

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

  • filename - Path of the sound file to write

Returns: True if saving succeeded, false if it failed

See also: load_from_file, load_from_memory, load_from_samples

View source