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
Functions
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.
...
|