spaudio module

A python module for audio I/O based on spAudio.

Example

The following is the example to realize fullduplex audio I/O (version 0.7.5+).

import spaudio

with spaudio.open('rw', nchannels=2, samprate=44100, buffersize=2048) as a:
    nloop = 500
    b = bytearray(4096)

    for i in range(nloop):
        a.readraw(b)
        a.writeraw(b)
exception spaudio.DeviceError[source]

Bases: spaudio.Error

Exception raised by audio device problems.

exception spaudio.DriverError[source]

Bases: spaudio.Error

Exception raised by audio driver problems.

exception spaudio.Error[source]

Bases: Exception

Base exception class for spaudio.

class spaudio.SpAudio(drivername=None)[source]

Bases: object

A class for audio I/O.

Parameters

drivername (str) – the driver name to initialize.

close()[source]

Closes the current audio device.

createarray(length, nframesflag=False)[source]

Creates a double array for the current device settings.

Parameters
  • length – A length of the array. Note that this length is not identical to the number of frames (length = nframes * nchannels). If you want to specify the number of frames, the second argument must be True.

  • nframesflag (bool) – True makes the first argument be treated as the number of frames.

Returns

An array class object for the current device settings.

Return type

array.array

createndarray(length, nframesflag=False)[source]

Creates a numpy double array for the current device settings.

Parameters
  • length – A length of the array. Note that this length is not identical to the number of frames (length = nframes * nchannels). If you want to specify the number of frames, the second argument must be True.

  • nframesflag (bool) – True makes the first argument be treated as the number of frames.

Returns

An ndarray class object for the current device settings.

Return type

numpy.ndarray

createrawarray(length, nframesflag=False)[source]

Creates a raw array for the current device settings.

Parameters
  • length – A length of the array. Note that this length is not identical to the number of frames (length = nframes * nchannels). If you want to specify the number of frames, the second argument must be True.

  • nframesflag (bool) – True makes the first argument be treated as the number of frames.

Returns

An array class object for the current device settings.

Return type

array.array

createrawndarray(length, nframesflag=False)[source]

Creates a raw numpy ndarray for the current device settings.

Parameters
  • length – A length of the array. Note that this length is not identical to the number of frames (length = nframes * nchannels). If you want to specify the number of frames, the second argument must be True.

  • nframesflag (bool) – True makes the first argument be treated as the number of frames.

Returns

An ndarray class object for the current device settings.

Return type

numpy.ndarray

getarraytypecode()[source]

Gets the type code for python array to store double array.

Returns

A type code of double array for the current settings.

Return type

char

getblockingmode()[source]

Gets the blocking mode of the current device.

Returns

0 = blocking mode (default), 1 = nonblocking mode.

Return type

int

getbuffersize()[source]

Gets the buffer size of the current device.

getcompname(decodebytes=False)[source]

Returns human-readable name of compression type. Currently, 'not compressed' (decodebytes = True) or b'not compressed' (decodebytes = False) will be returned.

getcomptype(decodebytes=False)[source]

Returns compression type. Currently, 'NONE' (decodebytes = True) or b'NONE' (decodebytes = False) will be returned.

getdevicelist()[source]

Gets the list of audio devices.

getdevicename(deviceindex)[source]

Gets the name of the audio device.

getframerate()[source]

Gets sample rate of the current device.

getnbuffers()[source]

Gets the number of buffers of the current device.

getnchannels()[source]

Gets the number of channels of the current device.

getndarraydtype()[source]

Gets the dtype string for numpy ndarray to store double array.

Returns

A dtype string for the current settings.

Return type

string

getndevices()[source]

Gets the number of audio devices.

getparams()[source]

Gets supported all parameters of the current device in dict object.

Returns

A dict object including all parameters of the current device whose keys are 'nchannels', 'sampbit', 'samprate', 'blockingmode', 'buffersize', and 'nbuffers'.

Return type

dict

getparamstuple(decodebytes=False, nframes=0)[source]

Gets supported all parameters of the current device in namedtuple object.

Parameters
  • decodebytes (bool) – True decodes bytes objects into string objects for 'comptype' and 'compname'. The standard libraries of wave and sunau expect a decoded string object while the standard aifc library expects a bytes object.

  • nframes (int) – Specify the number of frames of an audio file, otherwise 4th element of the output tuple will be 0.

Returns

A namedtuple object including all parameters of the current device whose entries are (nchannels, sampwidth, framerate, nframes, comptype, compname) . This object is compatible with the argument of setparams() of standard libraries such as aifc, wave, or sunau.

Return type

namedtuple

getrawarraytypecode()[source]

Gets the type code for python array.

Returns

A type code for the current settings.

Return type

char

getrawndarraydtype()[source]

Gets the dtype string for numpy ndarray.

Returns

A dtype string for the current settings.

Return type

string

getrawsampbit()[source]

Gets the bits/sample for a raw buffer.

getrawsampwidth()[source]

Gets the bytes/sample for a raw buffer.

getsampbit()[source]

Gets bits/sample of the current device. sampbit = 33 means 32bit float.

getsamprate()[source]

Gets sample rate of the current device.

getsampwidth()[source]

Gets bytes/sample of the current device.

open(mode, *, callback=None, deviceindex=-1, samprate=0, sampbit=0, nchannels=0, blockingmode=-1, buffersize=0, nbuffers=0, params=None)[source]

Opens the current audio device.

Parameters
  • mode (str) – Device opening mode. 'r' means read mode, 'w' means write mode. 'ro' and 'wo' which mean read only and write only modes are also supported. Although these modes validate only the specified mode, some environments recieve a benefit that the processing becomes faster.

  • callback (tuple) – The callback function included in tuple which contains all arguments for setcallback() method.

  • deviceindex (int) – The index of the audio device.

  • samprate (double) – Sample rate of the device.

  • sampbit (int) – Bits/sample of the device.

  • nchannels (int) – The number of channels of the device.

  • blockingmode (int) – 0 = blocking mode (default), 1 = nonblocking mode.

  • buffersize (int) – The buffer size of the device.

  • nbuffers (int) – The number of buffers of the device.

  • params (dict) – A dict object which can contain any above parameters from samprate to nbuffers.

Note

Support for the keyword arguments was added in Version 0.7.5.

read(data, weight=1.0, offset=0, length=0)[source]

Reads data to double array from the audio device.

Parameters
  • data (bytearray, array.array or numpy.ndarray) – A buffer of double array to receive data from the audio device.

  • weight (double) – A weighting factor multiplied to data after reading.

  • offset (int) – Optional offset location for the buffer.

  • length (int) – Optional read length for the buffer.

Returns

The read size if successful, -1 otherwise.

Return type

int

Note

The keyword arguments of offset and length were introduced in Version 0.7.5.

readraw(data, offset=0, length=0)[source]

Reads raw data from the audio device.

Parameters
  • data (bytearray, array.array or numpy.ndarray) – A buffer to receive raw data from the audio device.

  • offset (int) – Optional offset location for the buffer.

  • length (int) – Optional read length for the buffer.

Returns

The read size if successful, -1 otherwise.

Return type

int

Note

The keyword arguments of offset and length were introduced in Version 0.7.5.

reload(drivername=None)[source]

Reloads a new audio driver.

selectdevice(deviceindex)[source]

Selects an audio device which has the index specified.

Parameters

deviceindex (int) – The index associated with an audio device.

Raises
  • ValueError – If deviceindex is greater than or equal to the number of devices.

  • DriverError – If the audio device cannot be selected.

setblockingmode(mode)[source]

Sets the blocking mode of the current device.

Parameters

mode (int) – 0 = blocking mode (default), 1 = nonblocking mode.

setbuffersize(buffersize)[source]

Sets the buffer size of the current device.

setcallback(calltype, func, *args)[source]

Sets a callback function.

Parameters
  • calltype (int) – A combination of callback types. OUTPUT_POSITION_CALLBACK and OUTPUT_BUFFER_CALLBACK are supported currently.

  • func (callable) – Callback function. The callback must have a signature in the callbacksignature() document.

  • *args – Variable length argument list.

Raises

DriverError – If the callback function cannot be set.

setcomptype(encodestr=True)[source]

Sets compression type. This parameter is ignored.

setframerate(samprate)[source]

Sets sample rate of the current device.

setnbuffers(nbuffers)[source]

Sets the number of buffers of the current device.

setnchannels(nchannels)[source]

Sets the number of channels of the current device.

setparams(params)[source]

Sets supported all parameters described in dict or namedtuple object to the device.

Parameters

params (dict) – a dict object of parameters whose keys are 'nchannels', 'sampbit', 'samprate', 'blockingmode', 'buffersize', or 'nbuffers'. The namedtuple generated by standard libraries such as aifc, wave, or sunau is also acceptable.

setsampbit(sampbit)[source]

Sets bits/sample of the current device. sampbit = 33 means 32bit float.

setsamprate(samprate)[source]

Sets sample rate of the current device.

setsampwidth(sampwidth, floatflag=False)[source]

Sets bytes/sample of the current device.

stop()[source]

Stops audio I/O.

sync()[source]

Synchronizes audio I/O.

terminate()[source]

Terminates the current audio driver.

write(data, weight=1.0, offset=0, length=0)[source]

Writes data of double array to the audio device.

Parameters
  • data (bytearray, array.array or numpy.ndarray) – A buffer of double array to send data to the audio device.

  • weight (double) – A weighting factor multiplied to data before writing.

  • offset (int) – Optional offset location for the buffer.

  • length (int) – Optional write length for the buffer.

Returns

The written size if successful, -1 otherwise.

Return type

int

Note

The keyword arguments of offset and length were introduced in Version 0.7.5.

writeraw(data, offset=0, length=0)[source]

Writes raw data to the audio device.

Parameters
  • data (bytearray, array.array or numpy.ndarray) – A buffer to send raw data to the audio device.

  • offset (int) – Optional offset location for the buffer.

  • length (int) – Optional write length for the buffer.

Returns

The written size if successful, -1 otherwise.

Return type

int

Note

The keyword arguments of offset and length were introduced in Version 0.7.5.

spaudio.callbacksignature(audio, calltype, cbdata, args)[source]

Signature of the callback function for setcallback() method.

Parameters
  • audio (SpAudio) – An instance of SpAudio class.

  • calltype (int) – The callback type. OUTPUT_POSITION_CALLBACK or OUTPUT_BUFFER_CALLBACK.

  • cbdata – Callback-depend data. A position (int) on OUTPUT_POSITION_CALLBACK or a buffer (bytes) on OUTPUT_BUFFER_CALLBACK.

  • args – Variable length argument list specified at setcallback(). Note that this args variable does not require the prefix *.

Returns

False if you don’t want to fire callbacks anymore.

Return type

bool

spaudio.getdriverdevicename(index, drivername=None)[source]

Gets the name of the device in the driver.

Parameters
  • index (int) – The index associated with the audio device.

  • drivername (str) – Optional driver name.

Returns

A string containing the device name.

Return type

string

Raises

ValueError – If index is greater than or equal to the number of devices.

spaudio.getdriverlist()[source]

Gets a list of driver names.

spaudio.getdrivername(index)[source]

Gets the name of the driver which has the index specified.

Parameters

index (int) – The index associated with the audio driver.

Returns

A string containing the driver name.

Return type

string

Raises

ValueError – If index is greater than or equal to the number of drivers.

spaudio.getndriverdevices(drivername=None)[source]

Gets the number of devices in the driver.

spaudio.getndrivers()[source]

Gets the number of drivers.

spaudio.open(mode, *, drivername=None, callback=None, deviceindex=-1, samprate=0, sampbit=0, nchannels=0, blockingmode=-1, buffersize=0, nbuffers=0, params=None)[source]

Opens an audio device. This function may be used in a with statement.

Parameters
  • mode (str) – Device opening mode. 'r' means read mode, 'w' means write mode. 'ro' and 'wo' which mean read only and write only modes are also supported. Although these modes validate only the specified mode, some environments recieve a benefit that the processing becomes faster. In this function, 'rw' which means open with 'w' after 'r' is also supported.

  • drivername (str) – The driver name to initialize.

  • callback (tuple) – The callback function included in tuple which contains all arguments for setcallback() method.

  • deviceindex (int) – The index of the audio device.

  • samprate (double) – Sample rate of the device.

  • sampbit (int) – Bits/sample of the device.

  • nchannels (int) – The number of channels of the device.

  • blockingmode (int) – 0 = blocking mode (default), 1 = nonblocking mode.

  • buffersize (int) – The buffer size of the device.

  • nbuffers (int) – The number of buffers of the device.

  • params (dict) – A dict object which can contain any above parameters from samprate to nbuffers.

Returns

A new instance of SpAudio class.

Return type

SpAudio

Note

This function was introduced in Version 0.7.5.