Class OcsfmlAudio.sound_buffer

class sound_buffer : [ `Copy of < rep__sf_SoundBuffer : SoundBuffer.t; .. >
| `File of string
| `None
| `Samples of samples_type * int * int
| `Stream of OcsfmlSystem.input_stream ] ->
object .. end
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 restituted 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 OcsfmlAudio.sound_buffer is similar to a OcsfmlGraphics.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 OcsfmSystem.input_stream) 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 OcsfmlAudio.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 OcsfmlAudio.sound_buffer is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a OcsfmlAudio.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 OcsfmlAudio.sound instances to the same OcsfmlAudio.sound_buffer.

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

Usage example:

    (* Declare a new sound buffer *)
    let buffer = new sound_buffer in
    
    (* Load it from a file *)
    if not (buffer#load_from_file "sound.wav")
    then (* error... *)
    
    (* Create a sound source and bind it to the buffer *)
    let sound1 = new sound in
    sound1#set_buffer buffer ;
    
    (* Play the sound *)
    sound1#play ;
    
    (* Create another sound source bound to the same buffer *)
    let sound2 = new sound in
    sound2#set_buffer buffer ;
    
    (* Play it with a higher pitch -- the first sound remains
    unchanged *)

    sound2#set_pitch 2 ;
    sound2#play
    


method destroy : unit
method affect : 'a. (#const_sound_buffer as 'a) -> unit
method get_channel_count : int
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

method get_duration : OcsfmlSystem.Time.t
Get the total duration of the sound.
Returns Sound duration
method get_sample_count : int
Get the number of samples stored in the buffer.

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

method get_sample_rate : int
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)

method get_samples : samples_type
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 getSampleCount() function.
Returns Bigarray of sound samples

method load_from_file : string -> bool
Load the sound buffer from a file.

Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
Returns True if loading succeeded, false if it failed

method load_from_samples : samples_type -> int -> 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).
Returns True if loading succeeded, false if it failed

method load_from_stream : OcsfmlSystem.input_stream -> bool
Load the sound buffer from a custom stream.

Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
Returns True if loading succeeded, false if it failed

method save_to_file : string -> bool
Save the sound buffer to an audio file.

Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
Returns True if saving succeeded, false if it failed