pygame.sndarray
pygame module for accessing sound sample data

Functions to convert between Numeric or numpy arrays and Sound
objects. This module will only be available when pygame can use the
external numpy or Numeric package.

Sound data is made of thousands of samples per second, and each sample
is the amplitude of the wave at a particular moment in time. For
example, in 22-kHz format, element number 5 of the array is the
amplitude of the wave after 5/22000 seconds.

Each sample is an 8-bit or 16-bit integer, depending on the data format.
A stereo sound file has two values per sample, while a mono sound file
only has one.

Supported array systems are

  numpy
  numeric

The default will be numpy, if installed. Otherwise, Numeric will be set
as default if installed. If neither numpy nor Numeric are installed, the
module will raise an ImportError.

The array type to use can be changed at runtime using the use_arraytype()
method, which requires one of the above types as string.

Note: numpy and Numeric are not completely compatible. Certain array
manipulations, which work for one type, might behave differently or even
completely break for the other.

Additionally, in contrast to Numeric numpy can use unsigned 16-bit
integers. Sounds with 16-bit data will be treated as unsigned integers,
if the sound sample type requests this. Numeric instead always uses
signed integers for the representation, which is important to keep in
mind, if you use the module's functions and wonder about the values.
<SECTION>

array
copy Sound samples into an array
pygame.sndarray.array(Sound): return array

Creates a new array for the sound data and copies the samples. The array
will always be in the format returned from pygame.mixer.get_init().
<END>

samples
reference Sound samples into an array
pygame.sndarray.samples(Sound): return array

Creates a new array that directly references the samples in a Sound
object. Modifying the array will change the Sound. The array will always
be in the format returned from pygame.mixer.get_init().
<END>

make_sound
convert an array into a Sound object
pygame.sndarray.make_sound(array): return Sound

Create a new playable Sound object from an array. The mixer module must
be initialized and the array format must be similar to the mixer audio
format.
<END>

use_arraytype
Sets the array system to be used for sound arrays
pygame.sndarray.use_arraytype (arraytype): return None

Uses the requested array type for the module functions.
Currently supported array types are:

  numeric 
  numpy

If the requested type is not available, a ValueError will be raised.

New in pygame 1.8.
<END>

get_arraytype
Gets the currently active array type.
pygame.sndarray.get_arraytype (): return str

Returns the currently active array type. This will be a value of the
get_arraytypes() tuple and indicates which type of array module is used
for the array creation.

New in pygame 1.8
<END>

get_arraytypes
Gets the array system types currently supported.
pygame.sndarray.get_arraytypes (): return tuple

Checks, which array systems are available and returns them as a tuple of
strings. The values of the tuple can be used directly in the
pygame.sndarray.use_arraytype () method. If no supported array system
could be found, None will be returned.

New in pygame 1.8.
<END>
<END>