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