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.15+).

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-precision 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, optional) – 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, channelwise=False)[source]

Creates a numpy double-precision 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, optional) – True makes the first argument be treated as the number of frames.

  • channelwise (bool, optional) – True resizes the returned array into (nframes, nchannels) matrix. This argument is introduced in Version 0.7.16.

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, optional) – 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, channelwise=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, optional) – True makes the first argument be treated as the number of frames.

  • channelwise (bool, optional) – True resizes the returned array into (nframes, nchannels) matrix. This argument is introduced in Version 0.7.16.

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-precision data.

Returns

A type code of a double-precision 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-precision data.

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, optional) – 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, optional) – 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 to store raw data.

Returns

A type code for the current settings.

Return type

char

getrawndarraydtype()[source]

Gets the dtype string for numpy ndarray to store raw data.

Returns

A dtype string for the current settings.

Return type

string

getrawsampbit()[source]

Gets the bits/sample for a raw array.

getrawsampwidth()[source]

Gets the bytes/sample for a raw array.

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, optional) – The callback function included in tuple which contains all arguments for setcallback() method.

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

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

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

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

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

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

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

  • params (dict, optional) – 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.15.

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

Reads data to a double-precision array from the audio device.

Parameters

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

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

  • offset (int, optional) – Optional offset location for the array.

  • length (int, optional) – Optional read length for the array.

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

readframes(nframes, weight=1.0, arraytype='ndarray', channelwise=False)[source]

Reads and returns the next nframes data of a double-precision array.

Parameters

  • nframes (int) – The number of frames to read.

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

  • arraytype (str, optional) – The type of output array. The value must be 'ndarray' (default), 'array', or 'bytearray'.

  • channelwise (bool, optional) – True resizes the returned ndarray into (nframes, nchannels) matrix. This argument is valid only in arraytype='ndarray' case.

Returns

The output array object containing read data.

Return type

numpy.ndarray, array.array or bytearray

Note

This function was introduced in Version 0.7.16.

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

Reads raw data from the audio device.

Parameters

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

  • offset (int, optional) – Optional offset location for the array.

  • length (int, optional) – Optional read length for the array.

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

readrawframes(nframes, arraytype='ndarray', channelwise=False)[source]

Reads and returns the next nframes data of a raw array.

Parameters

  • nframes (int) – The number of frames to read.

  • arraytype (str, optional) – The type of output array. The value must be 'ndarray' (default), 'array', or 'bytearray'.

  • channelwise (bool, optional) – True resizes the returned ndarray into (nframes, nchannels) matrix. This argument is valid only in arraytype='ndarray' case.

Returns

The output array object containing read data.

Return type

numpy.ndarray, array.array or bytearray

Note

This function was introduced in Version 0.7.16.

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 a double-precision array to the audio device.

Parameters

  • data (bytearray, array.array or numpy.ndarray) – A double-precision array to send data to the audio device.

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

  • offset (int, optional) – Optional offset location for the array.

  • length (int, optional) – Optional write length for the array.

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

writeframes(data, weight=1.0)[source]

Writes data of a double-precision array to the audio device.

Parameters

  • data (bytearray, array.array or numpy.ndarray) – A double-precision array to send data to the audio device.

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

Returns

The written number of frames if successful, -1 otherwise.

Return type

int

Note

This function was introduced in Version 0.7.16.

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

Writes data of a raw array to the audio device.

Parameters

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

  • offset (int, optional) – Optional offset location for the array.

  • length (int, optional) – Optional write length for the array.

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

writerawframes(data)[source]

Writes data of a raw array to the audio device.

Parameters

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

Returns

The written number of frames if successful, -1 otherwise.

Return type

int

Note

This function was introduced in Version 0.7.16.

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, optional) – The driver name to initialize.

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

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

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

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

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

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

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

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

  • params (dict, optional) – 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.15.