Module cocos.audio.SDL.sound

An abstract sound format decoding API.

The latest version of SDL_sound can be found at: http://icculus.org/SDL_sound/

The basic gist of SDL_sound is that you use an SDL_RWops to get sound data into this library, and SDL_sound will take that data, in one of several popular formats, and decode it into raw waveform data in the format of your choice. This gives you a nice abstraction for getting sound into your game or application; just feed it to SDL_sound, and it will handle decoding and converting, so you can just pass it to your SDL audio callback (or whatever). Since it gets data from an SDL_RWops, you can get the initial sound data from any number of sources: file, memory buffer, network connection, etc.

As the name implies, this library depends on SDL: Simple Directmedia Layer, which is a powerful, free, and cross-platform multimedia library. It can be found at http://www.libsdl.org/

Support is in place or planned for the following sound formats: - .WAV (Microsoft WAVfile RIFF data, internal.) - .VOC (Creative Labs' Voice format, internal.) - .MP3 (MPEG-1 Layer 3 support, via the SMPEG and mpglib libraries.) - .MID (MIDI music converted to Waveform data, internal.) - .MOD (MOD files, via MikMod and ModPlug.) - .OGG (Ogg files, via Ogg Vorbis libraries.) - .SPX (Speex files, via libspeex.) - .SHN (Shorten files, internal.) - .RAW (Raw sound data in any format, internal.) - .AU (Sun's Audio format, internal.) - .AIFF (Audio Interchange format, internal.) - .FLAC (Lossless audio compression, via libFLAC.)

Classes

  Sound_Version
Version structure.
  Sound_AudioInfo
Information about an existing sample's format.
  Sound_DecoderInfo
Information about a sound decoder.
  Sound_Sample
Represents sound data in the process of being decoded.

Functions

Sound_Version Sound_GetLinkedVersion()
Get the version of the dynamically linked SDL_sound library
list of Sound_DecoderInfo Sound_AvailableDecoders()
Get a list of sound formats supported by this version of SDL_sound.
Sound_Sample Sound_NewSampleFromMem(data, ext, desired, bufferSize)
Start decoding a new sound sample from a buffer.

Variables

  Sound_Init = _dll.function('Sound_Init', '''Initialize SDL_sou...
  Sound_Quit = _dll.function('Sound_Quit', '''Shutdown SDL_sou...
  Sound_GetError = _dll.function('Sound_GetError', '''Get the la...
  Sound_ClearError = _dll.function('Sound_ClearError', '''Clear ...
  Sound_NewSample = _dll.function('Sound_NewSample', '''Start de...
  Sound_NewSampleFromFile = _dll.function('Sound_NewSampleFromFi...
  Sound_FreeSample = _dll.function('Sound_FreeSample', '''Dispos...
  Sound_GetDuration = _dll.function('Sound_GetDuration', '''Retr...
  Sound_SetBufferSize = _dll.function('Sound_SetBufferSize', '''...
  Sound_Decode = _dll.function('Sound_Decode', '''Decode more of...
  Sound_DecodeAll = _dll.function('Sound_DecodeAll', '''Decode t...
  Sound_Rewind = _dll.function('Sound_Rewind', '''Rewind a sampl...
  Sound_Seek = _dll.function('Sound_Seek', '''Seek to a differen...

Function Details

Sound_AvailableDecoders

Sound_AvailableDecoders()

Get a list of sound formats supported by this version of SDL_sound.

This is for informational purposes only. Note that the extension listed is merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio file with an extension of "XYZ", if you like. The file extensions are informational, and only required as a hint to choosing the correct decoder, since the sound data may not be coming from a file at all, thanks to the abstraction that an SDL_RWops provides.

Returns: list of Sound_DecoderInfo

Sound_NewSampleFromMem

Sound_NewSampleFromMem(data, ext, desired, bufferSize)

Start decoding a new sound sample from a buffer.

This is identical to Sound_NewSample, but it creates an SDL_RWops for you from the buffer.

Parameters:
data : SDL_array or sequence
Buffer holding encoded byte sound data
ext : str
File extension normally associated with a data format. Can usually be None.
desired : Sound_AudioInfo
Format to convert sound data into. Can usually be None if you don't need conversion.
bufferSize : int
Size, in bytes, to allocate for the decoding buffer
Returns: Sound_Sample

Since: Not yet released in SDL_sound


Variables Details

Sound_Init

Value:
_dll.function('Sound_Init', '''Initialize SDL_sound.

    This must be called before any other SDL_sound function (except pe\
rhaps
    `Sound_GetLinkedVersion`). You should call `SDL_Init` before calli\
ng
    this.  `Sound_Init` will attempt to call ``SDL_Init(SDL_INIT_AUDIO\
)``,
...

Sound_Quit

Value:
_dll.function('Sound_Quit', '''Shutdown SDL_sound.

    This closes any SDL_RWops that were being used as sound sources, a\
nd
    frees any resources in use by SDL_sound.

    All Sound_Sample structures existing will become invalid.

...

Sound_GetError

Value:
_dll.function('Sound_GetError', '''Get the last SDL_sound error messag\
e.

    This will be None if there's been no error since the last call to \
this
    function.  Each thread has a unique error state associated with it\
, but
    each time a new error message is set, it will overwrite the previo\
...

Sound_ClearError

Value:
_dll.function('Sound_ClearError', '''Clear the current error message.

    The next call to `Sound_GetError` after `Sound_ClearError` will re\
turn
    None.
    ''', args= [], arg_types= [], return_type= None)

Sound_NewSample

Value:
_dll.function('Sound_NewSample', '''Start decoding a new sound sample.

    The data is read via an SDL_RWops structure, so it may be coming f\
rom
    memory, disk, network stream, etc. The `ext` parameter is merely a\
 hint
    to determining the correct decoder; if you specify, for example, "\
mp3"
...

Sound_NewSampleFromFile

Value:
_dll.function('Sound_NewSampleFromFile', '''Start decoding a new sound\
 sample from a file on disk.

    This is identical to `Sound_NewSample`, but it creates an `SDL_RWo\
ps
    for you from the file located at `filename`.
    ''', args= ['filename', 'desired', 'bufferSize'], arg_types= [c_ch\
ar_p, POINTER(Sound_AudioInfo), c_uint], return_type= POINTER(Sound_Sa\
...

Sound_FreeSample

Value:
_dll.function('Sound_FreeSample', '''Dispose of a `Sound_Sample`.

    This will also close/dispose of the `SDL_RWops` that was used at
    creation time.  The `Sound_Sample` structure is invalid after this
    call.

    :Parameters:
        `sample` : `Sound_Sample`
...

Sound_GetDuration

Value:
_dll.function('Sound_GetDuration', '''Retrieve the total play time of \
a sample, in milliseconds.

    Report total time length of sample, in milliseconds.  This is a fa\
st
    call.  Duration is calculated during `Sound_NewSample`, so this is\
 just
    an accessor into otherwise opaque data.
...

Sound_SetBufferSize

Value:
_dll.function('Sound_SetBufferSize', '''Change the current buffer size\
 for a sample.

    If the buffer size could be changed, then the ``sample.buffer`` an\
d
    ``sample.buffer_size`` fields will reflect that. If they could not\
 be
    changed, then your original sample state is preserved. If the buff\
...

Sound_Decode

Value:
_dll.function('Sound_Decode', '''Decode more of the sound data in a `S\
ound_Sample`.

    It will decode at most sample->buffer_size bytes into ``sample.buf\
fer``
    in the desired format, and return the number of decoded bytes.

    If ``sample.buffer_size`` bytes could not be decoded, then refer t\
...

Sound_DecodeAll

Value:
_dll.function('Sound_DecodeAll', '''Decode the remainder of the sound \
data in a `Sound_Sample`.

    This will dynamically allocate memory for the entire remaining sam\
ple.
    ``sample.buffer_size`` and ``sample.buffer`` will be updated to re\
flect
    the new buffer.  Refer to ``sample.flags`` to determine if the
...

Sound_Rewind

Value:
_dll.function('Sound_Rewind', '''Rewind a sample to the start.

    Restart a sample at the start of its waveform data, as if newly
    created with `Sound_NewSample`. If successful, the next call to
    `Sound_Decode` will give audio data from the earliest point in the
    stream.

    Beware that this function will fail if the SDL_RWops that feeds th\
...

Sound_Seek

Value:
_dll.function('Sound_Seek', '''Seek to a different point in a sample.

    Reposition a sample's stream. If successful, the next call to
    `Sound_Decode` or `Sound_DecodeAll` will give audio data from the
    offset you specified.

    The offset is specified in milliseconds from the start of the
    sample.
...