class SF::SoundBuffer

• SF::SoundBuffer
• Reference
• Object

Overview

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

Defined in:

audio/obj.cr

Constructors

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

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

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

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

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

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

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

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

• .new

  Default constructor

Instance Method Summary

• #channel_count : Int32

  Get the number of channels used by the sound

• #duration : Time

  Get the total duration of the sound

• #finalize

  Destructor

• #load_from_file(filename : String) : Bool

  Load the sound buffer from a file

• #load_from_memory(data : Slice) : Bool

  Load the sound buffer from a file in memory

• #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

• #load_from_stream(stream : InputStream) : Bool

  Load the sound buffer from a custom stream

• #sample_count : UInt64

  Get the number of samples stored in the buffer

• #sample_rate : Int32

  Get the sample rate of the sound

• #samples : Pointer(Int16)

  Get the array of audio samples stored in the buffer

• #save_to_file(filename : String) : Bool

  Save the sound buffer to an audio file

Constructor Detail

Instance Method Detail