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
Constructors#
.from_file(*args, **kwargs) : self#
Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_file(...); sound_buffer
Raises InitError on failure
.from_memory(*args, **kwargs) : self#
Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_memory(...); sound_buffer
Raises InitError on failure
.from_samples(*args, **kwargs) : self#
Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_samples(...); sound_buffer
Raises InitError on failure
.from_stream(*args, **kwargs) : self#
Shorthand for sound_buffer = SoundBuffer.new; sound_buffer.load_from_stream(...); sound_buffer
Raises InitError on failure
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
#duration : Time#
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
#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
#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
#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
#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
#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
#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
#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