Readers and Writers¶

TSM objects use Reader objects as input and Writer objects as output.

The audiotsm.io package provides Readers and Writers allowing to use numpy arrays or wav files as input or output of a TSM, to play the output in real-time, as well as base classes to implement your own Readers and Writers.

Numpy arrays¶

The audiotsm.io.array module provides a Reader and Writers allowing to use a numpy.ndarray as input or output of a TSM object.

class audiotsm.io.array.ArrayReader(data)¶

Bases: audiotsm.io.base.Reader

A Reader allowing to use numpy.ndarray as input of a TSM object.

Parameters:	data (`numpy.ndarray`) – a matrix of shape (`m`, `n`), with `m` the number of channels and `n` the length of the buffer, where the samples will be read.

class audiotsm.io.array.ArrayWriter(channels)¶

Bases: audiotsm.io.base.Writer

A Writer allowing to get the output of a TSM object as a numpy.ndarray.

Writing to an ArrayWriter will add the data at the end of the data attribute.

Parameters:	channels (int) – the number of channels of the signal.

data¶: A numpy.ndarray of shape (m, n), with m the number of channels and n the length of the data, where the samples have written.

class audiotsm.io.array.FixedArrayWriter(data)¶

Bases: audiotsm.io.base.Writer

A Writer allowing to use numpy.ndarray as output of a TSM object.

Contrary to an ArrayWriter, a FixedArrayWriter takes the buffer in which the data will be written as a parameter of its constructor. The buffer is of fixed size, and it will not be possible to write more samples to the FixedArrayWriter than the buffer can contain.

Parameters:	data (`numpy.ndarray`) – a matrix of shape (`m`, `n`), with `m` the number of channels and `n` the length of the buffer, where the samples will be written.

Wav files¶

The audiotsm.io.wav module provides a Reader and a Writer allowing to use wav files as input or output of a TSM object.

class audiotsm.io.wav.WavReader(filename)¶

Bases: audiotsm.io.base.Reader

A Reader allowing to use a wav file as input of a TSM object.

You should close the WavReader after using it with the close() method, or use it in a with statement as follow:

with WavReader(filename) as reader:
    # use reader...

Parameters:	filename (str) – the name of an existing wav file.

close()¶: Close the wav file.

samplerate¶: The samplerate of the wav file.

samplewidth¶: The sample width in bytes of the wav file.

class audiotsm.io.wav.WavWriter(filename, channels, samplerate)¶

Bases: audiotsm.io.base.Writer

A Writer allowing to use a wav file as output of a TSM object.

You should close the WavWriter after using it with the close() method, or use it in a with statement as follow:

with WavWriter(filename, 2, 44100) as writer:
    # use writer...

Parameters:	filename (str) – the name of the wav file (it will be overwritten if it already exists). channels (int) – the number of channels of the signal. samplerate (int) – the sampling rate of the signal.

close()¶: Close the wav file.

Play in real-time¶

The audiotsm.io.stream module provides a Writer allowing to play the output of a TSM object in real-time.

class audiotsm.io.stream.StreamWriter(channels, samplerate, **attrs)¶

Bases: audiotsm.io.base.Writer

A Writer allowing to play the output of a TSM object directly.

You should stop the StreamWriter after using it with the stop() method, or use it in a with statement as follow:

with WavWriter(2, 44100) as writer:
    # use writer...

Parameters:	channels (int) – the number of channels of the signal. samplerate (int) – the sampling rate of the signal. attrs – additional parameters used to create the `sounddevice.OutputStream` that is used by the `StreamWriter`.

stop()¶: Stop the stream.

Implementing your own¶

The audiotsm.io.base module provides base classes for the input and output of TSM objects.

class audiotsm.io.base.Reader¶

An abstract class for the input of a TSM object.

channels¶: The number of channels of the Reader.

empty¶: True if there is no more data to read.

read(buffer)¶

Reads as many samples from the Reader as possible, write them to buffer, and returns the number of samples that were read.

Parameters:	buffer (`numpy.ndarray`) – a matrix of shape (`m`, `n`), with `m` the number of channels and `n` the length of the buffer, where the samples will be written.
Returns:	the number of samples that were read. It should always be equal to the length of the buffer, except when there is no more values to be read.
Raises:	ValueError – if the `Reader` and the buffer do not have the same number of channels

skip(n)¶: Try to skip n samples, an returns the number of samples that were actually skipped.

class audiotsm.io.base.Writer¶

An abstract class for the output of a TSM object.

channels¶: The number of channels of the Writer.

write(buffer)¶

Write as many samples from the Writer as possible from buffer, and returns the number of samples that were written.

Parameters:	buffer (`numpy.ndarray`) – a matrix of shape (`m`, `n`), with `m` the number of channels and `n` the length of the buffer, where the samples will be read.
Returns:	the number of samples that were written. It should always be equal to the length of the buffer, except when there is no more space in the `Writer`.
Raises:	ValueError – if the `Writer` and the buffer do not have the same number of channels