spplugin module

A python module for plugin-based audio file I/O based on spPlugin which supports several sound formats including WAV, AIFF, MP3, Ogg Vorbis, FLAC, ALAC, raw, and more.

Example

The following is the example plotting the waveform of an input audio file.

import os
import sys
import spplugin
import numpy as np
import matplotlib.pyplot as plt


def plotfilebyplugin(filename):
    with spplugin.open(filename, 'r') as pf:
        nchannels = pf.getnchannels()
        samprate = pf.getsamprate()
        sampbit = pf.getsampbit()
        nframes = pf.getnframes()
        duration = nframes / samprate

        y = pf.createndarray(nframes * nchannels)
        nread = pf.read(y)
        print('nread = %d' % nread)

        y.resize((nframes, nchannels))

        x = np.linspace(0.0, duration, nframes)
        for i in range(nchannels):
            plt.plot(x, y[:,i])
        plt.xlim(0.0, duration)
        plt.xlabel('Time [s]')
        plt.ylabel('Amplitude (normalized)')
        plt.show()


if __name__ == '__main__':
    if len(sys.argv) <= 1:
        print('usage: %s filename'
              % os.path.basename(sys.argv[0]), file=sys.stderr)
        quit()

    plotfilebyplugin(sys.argv[1])

The following is the another example using a high-level function of audioread() which is similar to MATLAB’s one (version 0.7.16+).

import os
import sys
import spplugin
import spaudio


def audioreadexample(filename):
    data, samprate, params = spplugin.audioread(filename)
    print('samprate = ' + str(samprate) + ', params =\n' + str(params))

    with spaudio.open('wo', params=params) as a:
        nwframes = a.writeframes(data)
        print('write frames = %d' % nwframes)


if __name__ == '__main__':
    if len(sys.argv) <= 1:
        print('usage: %s filename'
              % os.path.basename(sys.argv[0]), file=sys.stderr)
        quit()

    audioreadexample(sys.argv[1])

The following is the ‘write’ version of above example using a high-level function of audiowrite() which is similar to MATLAB’s one (version 0.7.16+).

import os
import sys
import spplugin
import spaudio


def audiowriteexample(filename):
    duration = 2.0
    with spaudio.open('ro', nchannels=2, samprate=44100) as a:
        nframes = round(duration * a.getsamprate())
        data = a.readframes(nframes, channelwise=True)
        print('nread = %d' % len(data))

        nwframes = spplugin.audiowrite(filename, data, a.getsamprate())
        print('write frames = %d' % nwframes)


if __name__ == '__main__':
    if len(sys.argv) <= 1:
        print('usage: %s filename'
              % os.path.basename(sys.argv[0]), file=sys.stderr)
        quit()

    audiowriteexample(sys.argv[1])

exception spplugin.BogusFileError

Bases: Error

Exception raised if the audio file is bogus.

exception spplugin.Error

Bases: Exception

Base exception class for spplugin.

exception spplugin.FileError

Bases: Error

Exception raised by audio file problems.

exception spplugin.FileTypeError

Bases: Error

Exception raised if the specified file type is not accepted.

exception spplugin.NChannelsError

Bases: Error

Exception raised if the specified number of channels is not accepted.

exception spplugin.NFramesRequiredError

Bases: Error

Exception raised if the total number of frames is required to use the plugin.

exception spplugin.SampleBitError

Bases: Error

Exception raised if the specified bits/sample is not accepted.

exception spplugin.SampleRateError

Bases: Error

Exception raised if the specified sample rate is not accepted.

class spplugin.SpFilePlugin

Bases: object

A class for audio file I/O. This class is similar to one provided by the standard libraries such as aifc, wave, or sunau. The important difference is that set*() functions must be called before open() in this class. You can set parameters by using optional arguments of open() function.

appendsonginfo(songinfo)

Appends song information to the current internal information.

close()

Closes the current audio file.

copyarray2raw(inarray, sampwidth, bigendian_or_signed8bit=False)

Copies raw array (array.array) contents to a new raw bytes (bytearray) data.

Parameters:

• inarray (array.array) – Input array object.

• sampwidth (int) – bytes/sample of output data.

• bigendian_or_signed8bit (bool, optional) – Specify True if endianness of output data is big endian (16- or 32-bit case) or data type of output data is signed 8-bit (8-bit case).

Returns:

A bytearray class object which contains converted data.

Return type:

bytearray

copyraw2array(rawdata, sampwidth, bigendian_or_signed8bit=False)

Copies raw bytes (bytearray) data contents to a new raw array (array.array).

Parameters:

• rawdata (bytes or bytearray) – Input bytes or bytearray object.

• sampwidth (int) – bytes/sample of rawdata

• bigendian_or_signed8bit (bool, optional) – Specify True if endianness of rawdata is big endian (16- or 32-bit case) or data type of rawdata (8-bit case) is signed 8-bit.

Returns:

An array class object which contains converted data.

Return type:

array.array

createarray(length, nframesflag=False)

Creates a double-precision array for the current file 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 file settings.

Return type:

array.array

createndarray(length, nframesflag=False, channelwise=False)

Creates a numpy double-precision array for the current file 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 file settings.

Return type:

numpy.ndarray

createrawarray(length, nframesflag=False)

Creates a raw array for the current file 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 file settings.

Return type:

array.array

createrawndarray(length, nframesflag=False, channelwise=False)

Creates a raw numpy ndarray for the current file 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 file settings.

Return type:

numpy.ndarray

getarraytypecode()

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

getcompname(decodebytes=False)

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

getcomptype(decodebytes=False)

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

getfiledesc()

Gets file description of the current file. For example, 'Microsoft PCM' for a WAV file in PCM format.

getfilefilter()

Gets file filter (e.g. '*.wav') of the current file.

getfiletype()

Gets file type of the current file.

getframerate()

Gets sample rate of the current file.

getmark(id)

Does nothing (for compatibility with standard libraries such as aifc, wave, and sunau).

getmarkers()

Does nothing (for compatibility with standard libraries such as aifc, wave, and sunau).

getnchannels()

Gets the number of channels of the current file.

getndarraydtype()

Gets the dtype string for numpy ndarray to store double-precision data.

Returns:

A dtype string for the current settings.

Return type:

string

getnframes()

Gets the total number of frames of the current file.

getparams()

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

Returns:

A dict object including all parameters of the current file whose keys are 'nchannels', 'sampbit', 'samprate', 'nframes', 'filetype', and 'songinfo'.

Return type:

dict

getparamstuple(decodebytes=False)

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

Parameters:

decodebytes (bool, optional) – True decodes bytes objects into string objects obtained by getcomptype() and getcompname() . The standard libraries of wave and sunau expect a decoded string object while the standard aifc library expects a bytes object.

Returns:

A namedtuple object including all parameters of the current file 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

getplugindesc()

Gets the short description of the plugin currently used.

getpluginid()

Gets the ID of the plugin currently used.

getplugininfo()

Gets the detailed information of the plugin currently used.

getpluginname()

Gets the name of the plugin currently used.

getpluginversion()

Gets the version of the plugin currently used.

getrawarraytypecode()

Gets the type code for python array to store raw data.

Returns:

A type code for the current settings.

Return type:

char

getrawndarraydtype()

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

Returns:

A dtype string for the current settings.

Return type:

string

getrawsampbit()

Gets the bits/sample for a raw array.

getrawsampwidth()

Gets the bytes/sample for a raw array.

getsampbit()

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

getsamprate()

Gets sample rate of the current file.

getsampwidth()

Gets bytes/sample of the current file.

getsonginfo()

Gets song information of the current file.

open(filename, mode, *, pluginname=None, samprate=0, sampbit=0, nchannels=0, filetype=None, songinfo=None, params=None)

Opens the file associated with the filename by using a plugin.

Parameters:

• filename (str) – The name of the file to open.

• mode (str) – The opening mode. 'r' means read mode, 'w' means write mode.

• pluginname (str, optional) – The name of the plugin used when this function cannot find the suitable plugin. Otherwise, SuitableNotFoundError exception will be raised. If you want to read a raw file, specify 'input_raw' .

• samprate (double, optional) – Sample rate.

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

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

• filetype (str, optional) – File type string.

• songinfo (dict, optional) – Song information.

• params (dict, optional) – All acceptable parameters in dict format.

Raises:

SuitableNotFoundError – If no suitable plugin is found.

read(data, weight=1.0, offset=0, length=0)

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

Parameters:

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

• 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)

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

Parameters:

• nframes (int) – The number of frames to read. A negative value means the total number of frames.

• 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)

Reads raw data from the audio file.

Parameters:

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

• 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)

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

Parameters:

• nframes (int) – The number of frames to read. A negative value means the total number of frames.

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

rewind()

Rewinds to the beginning of the file.

setcomptype(encodestr=True)

Sets compression type. Currently, this parameter is ignored.

setfiletype(filetype)

Sets file type to the file.

setframerate(samprate)

Sets sample rate to the file.

setmark(id, pos, name)

Does nothing (for compatibility with standard libraries such as aifc, wave, and sunau).

setnchannels(nchannels)

Sets the number of channels to the file.

setnframes(nframes)

Sets the total number of frames of the current file.

setparams(params)

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

Parameters:

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

setpos(pos)

Seeks to the specified position.

Parameters:

pos – a position to seek.

setsampbit(sampbit)

Sets bits/sample to the file. sampbit = 33 means 32bit float.

setsamprate(samprate)

Sets sample rate to the file.

setsampwidth(sampwidth, floatflag=False)

Sets bytes/sample of the current file.

setsonginfo(songinfo)

Sets song information to the file.

tell()

Gets the current position in the file.

write(data, weight=1.0, offset=0, length=0)

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

Parameters:

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

• 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)

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

Parameters:

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

• 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)

Writes data of a raw array to the audio file.

Parameters:

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

• 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)

Writes data of a raw array to the audio file.

Parameters:

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

Returns:

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

Return type:

int

Note

This function was introduced in Version 0.7.16.

exception spplugin.SuitableNotFoundError

Bases: Error

Exception raised if no suitable plugin is found.

exception spplugin.WrongPluginError

Bases: Error

Exception raised by a wrong plugin.

spplugin.audioread(filename, samples=(0, - 1), datatype='double', *, weight=1.0, arraytype='ndarray', channelwise=True, getparamstuple=False, decodebytes=False, pluginname=None, samprate=0, sampbit=0, nchannels=0, filetype=None, params=None)

Reads contents of an audio file by using a plugin.

Parameters:

• filename (str) – The name of the file to open.

• samples (tuple, optional) – The audio sample (frame) range which has the form (start, finish) . If finish is negative, it means the end of the file.

• datatype (str, optional) – The format of the output data. 'double' case makes readframes() method used and 'raw' case makes readrawframes() method used internally. Note that 'raw' case ignores weight argument.

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

• getparamstuple (bool, optional) – True makes getparamstuple() used internally.

• decodebytes (bool, optional) – True decodes bytes objects into string objects in calling getparamstuple() method. This argument is valid only in getparamstuple=True case.

• pluginname (str, optional) – The name of the plugin used when this function cannot find the suitable plugin. Otherwise, SuitableNotFoundError exception will be raised. If you want to read a raw file, specify 'input_raw' .

• samprate (double, optional) – Sample rate.

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

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

• filetype (str, optional) – File type string.

• songinfo (dict, optional) – Song information.

• params (dict, optional) – All acceptable parameters in dict format.

Returns:

The output tuple whose elements are the following.

• numpy.ndarray, array.array or bytearray – The output array object containing read data.

• double – Sample rate of the audio file.

• dict or namedtuple – If getparamstuple=False , A dict object same as that obtained by getparams() method will be returned. If getparamstuple=True , A namedtuple object same as that obtained by getparamstuple() method will be returned.

Return type:

tuple

Raises:

SuitableNotFoundError – If no suitable plugin is found.

Note

This function was introduced in Version 0.7.16.

spplugin.audiowrite(filename, data, samprate=0, nchannels=0, sampbit=0, *, datatype=None, weight=1.0, offset=0, length=0, pluginname=None, filetype=None, songinfo=None, params=None)

Writes data to an audio file by using a plugin.

Parameters:

• filename (str) – The name of the file to open.

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

• samprate (double, optional) – Sample rate.

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

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

• datatype (str, optional) – The format of the input data. 'double' case makes write() method used and 'raw' case makes writeraw() method used internally. Note that 'raw' case ignores weight argument. In some array types, this parameter can be detected automatically.

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

• pluginname (str, optional) – The name of the plugin used when this function cannot find the suitable plugin. Otherwise, SuitableNotFoundError exception will be raised. If you want to write data to a raw file, specify 'output_raw' .

• filetype (str, optional) – File type string.

• songinfo (dict, optional) – Song information.

• params (dict, optional) – All acceptable parameters in dict format.

Returns:

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

Return type:

int

Raises:

SuitableNotFoundError – If no suitable plugin is found.

Note

This function was introduced in Version 0.7.16.

spplugin.getplugindesc(name)

Gets short description of the plugin which has a name specified.

spplugin.getplugininfo(name)

Gets detailed information of the plugin which has a name specified.

spplugin.open(filename, mode, *, pluginname=None, samprate=0, sampbit=0, nchannels=0, filetype=None, songinfo=None, params=None)

Opens the file associated with the filename by using a plugin. This function may be used in a with statement.

Parameters:

• filename (str) – The name of the file to open.

• mode (str) – The opening mode. 'r' means read mode, 'w' means write mode.

• pluginname (str, optional) – The name of the plugin used when this function cannot find the suitable plugin. Otherwise, SuitableNotFoundError exception will be raised. If you want to read a raw file, specify 'input_raw' .

• samprate (double, optional) – Sample rate.

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

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

• filetype (str, optional) – File type string.

• songinfo (dict, optional) – Song information.

• params (dict, optional) – All acceptable parameters in dict format.

Returns:

A new instance of SpFilePlugin class.

Return type:

SpFilePlugin

Raises:

SuitableNotFoundError – If no suitable plugin is found.