Input/Output¶

This section contains the documentation for two classes: source, to read audio samples from files, and sink, to write audio samples to disk.

class aubio.source(path, samplerate=0, hop_size=512, channels=0)¶

Read audio samples from a media file.

source open the file specified in path and creates a callable returning hop_size new audio samples at each invocation.

If samplerate=0 (default), the original sampling rate of path will be used. Otherwise, the output audio samples will be resampled at the desired sampling-rate.

If channels=0 (default), the original number of channels in path will be used. Otherwise, the output audio samples will be down-mixed or up-mixed to the desired number of channels.

If path is a URL, a remote connection will be attempted to open the resource and stream data from it.

The parameter hop_size determines how many samples should be read at each consecutive calls.

Parameters:	path (str) – pathname (or URL) of the file to be opened for reading samplerate (int, optional) – sampling rate of the file hop_size (int, optional) – number of samples to be read per iteration channels (int, optional) – number of channels of the file

Examples

By default, when only path is given, the file will be opened with its original sampling rate and channel:

>>> src = aubio.source('stereo.wav')
>>> src.uri, src.samplerate, src.channels, src.duration
('stereo.wav', 48000, 2, 86833)

A typical loop to read all samples from a local file could look like this:

>>> src = aubio.source('stereo.wav')
>>> total_read = 0
>>> while True:
...     samples, read = src()
...     # do something with samples
...     total_read += read
...     if read < src.hop_size:
...         break
...

In a more Pythonic way, it can also look like this:

>>> total_read = 0
>>> with aubio.source('stereo.wav') as src:
...     for frames in src:
...         total_read += samples.shape[-1]
...

Basic interface

source is a callable; its __call__() method returns a tuple containing:

a vector of shape (hop_size,), filled with the read next samples available, zero-padded if read < hop_size
read, an integer indicating the number of samples read

To read the first hop_size samples from the source, simply call the instance itself, with no argument:

>>> src = aubio.source('song.ogg')
>>> samples, read = src()
>>> samples.shape, read, src.hop_size
((512,), 512, 512)

The first call returned the slice of samples [0 : hop_size]. The next call will return samples [hop_size: 2*hop_size].

After several invocations of __call__(), when reaching the end of the opened stream, read might become less than hop_size:

>>> samples, read = src()
>>> samples.shape, read
((512,), 354)

The end of the vector samples is filled with zeros.

After the end of the stream, read will be 0 since no more samples are available:

>>> samples, read = src()
>>> samples.shape, read
((512,), 0)

Note: when the source has more than one channels, they are be down-mixed to mono when invoking __call__(). To read from each individual channel, see __next__().

for statements

The source objects are iterables. This allows using them directly in a for loop, which calls __next__() until the end of the stream is reached:

>>> src = aubio.source('stereo.wav')
>>> for frames in src:
>>>     print (frames.shape)
...
(2, 512)
(2, 512)
(2, 230)

Note: When next(self) is called on a source with multiple channels, an array of shape (channels, read) is returned, unlike with __call__() which always returns the down-mixed channels.

If the file is opened with a single channel, next(self) returns an array of shape (read,):

>>> src = aubio.source('stereo.wav', channels=1)
>>> next(src).shape
(512,)

with statements

The source objects are context managers, which allows using them in with statements:

>>> with aubio.source('audiotrack.wav') as source:
...     n_frames=0
...     for samples in source:
...         n_frames += len(samples)
...     print('read', n_frames, 'samples in', samples.shape[0], 'channels',
...         'from file "%%s"' %% source.uri)
...
read 239334 samples in 2 channels from file "audiotrack.wav"

The file will be closed before exiting the statement.

See also the methods implementing the context manager, __enter__() and __exit__().

Seeking and closing

At any time, seek() can be used to move to any position in the file. For instance, to rewind to the start of the stream:

>>> src.seek(0)

The opened file will be automatically closed when the object falls out of scope and is scheduled for garbage collection.

In some cases, it is useful to manually close() a given source, for instance to limit the number of simultaneously opened files:

>>> src.close()

Input formats

Depending on how aubio was compiled, source may or may not open certain files format. Below are some examples that assume support for compressed files and remote urls was compiled in:

open a local file using its original sampling rate and channels, and with the default hop size:

>>> s = aubio.source('sample.wav')
>>> s.uri, s.samplerate, s.channels, s.hop_size
('sample.wav', 44100, 2, 512)

open a local compressed audio file, resampling to 32000Hz if needed:

>>> s = aubio.source('song.mp3', samplerate=32000)
>>> s.uri, s.samplerate, s.channels, s.hop_size
('song.mp3', 32000, 2, 512)

open a local video file, down-mixing and resampling it to 16kHz:

>>> s = aubio.source('movie.mp4', samplerate=16000, channels=1)
>>> s.uri, s.samplerate, s.channels, s.hop_size
('movie.mp4', 16000, 1, 512)

open a remote resource, with hop_size = 1024:

>>> s = aubio.source('https://aubio.org/drum.ogg', hop_size=1024)
>>> s.uri, s.samplerate, s.channels, s.hop_size
('https://aubio.org/drum.ogg', 48000, 2, 1024)

See also

sink: write audio samples to a file.

__call__()¶

Read at most hop_size new samples from self, return them in a tuple with the number of samples actually read.

The returned tuple contains:

a vector of shape (hop_size,), filled with the read next samples available, zero-padded if read < hop_size
read, an integer indicating the number of samples read

If opened with more than one channel, the frames will be down-mixed to produce the new samples.

Returns:	A tuple of one array of samples and one integer.
Return type:	(array, int)

See also

__next__()

Example

>>> src = aubio.source('stereo.wav')
>>> while True:
...     samples, read = src()
...     if read < src.hop_size:
...         break

__next__()¶

Read at most hop_size new frames from self, return them in an array.

If source was opened with one channel, next(self) returns an array of shape (read,), where read is the actual number of frames read (0 <= read <= hop_size).

If source was opened with more then one channel, the returned arrays will be of shape (channels, read), where read is the actual number of frames read (0 <= read <= hop_size).

Returns:	A tuple of one array of frames and one integer.
Return type:	(array, int)

See also

__call__()

Example

>>> for frames in aubio.source('song.flac')
...     print(samples.shape)

__iter__()¶: Implement iter(self).

See also

__next__()

__enter__()¶

Implement context manager interface. The file will be opened upon entering the context. See with statement.

Example

>>> with aubio.source('loop.ogg') as src:
...     src.uri, src.samplerate, src.channels

__exit__()¶: Implement context manager interface. The file will be closed before exiting the context. See with statement.

See also

__enter__()

close()¶: Close this source now.

Note

Closing twice a source will not raise any exception.

do()¶

Read vector of audio samples.

If the audio stream in the source has more than one channel, the channels will be down-mixed.

Returns:	samples (numpy.ndarray) – fvec of size hop_size containing the new samples. read (int) – Number of samples read from the source, equals to hop_size before the end-of-file is reached, less when it is reached, and 0 after.

See also

do_multi()

Examples

>>> src = aubio.source('sample.wav', hop_size=1024)
>>> src.do()
(array([-0.00123001, -0.00036685,  0.00097106, ..., -0.2031033 ,
       -0.2025854 , -0.20221856], dtype=float32), 1024)

do_multi()¶

Read multiple channels of audio samples.

If the source was opened with the same number of channels found in the stream, each channel will be read individually.

If the source was opened with less channels than the number of channels in the stream, only the first channels will be read.

If the source was opened with more channels than the number of channel in the original stream, the first channels will be duplicated on the additional output channel.

Returns:	samples (numpy.ndarray) – NumPy array of shape (hop_size, channels) containing the new audio samples. read (int) – Number of samples read from the source, equals to hop_size before the end-of-file is reached, less when it is reached, and 0 after.

See also

do()

Examples

>>> src = aubio.source('sample.wav')
>>> src.do_multi()
(array([[ 0.00668335,  0.0067749 ,  0.00714111, ..., -0.05737305,
        -0.05856323, -0.06018066],
       [-0.00842285, -0.0072937 , -0.00576782, ..., -0.09405518,
        -0.09558105, -0.09725952]], dtype=float32), 512)

get_channels()¶

Get number of channels in source.

Returns:	Number of channels.
Return type:	int

get_samplerate()¶

Get sampling rate of source.

Returns:	Sampling rate, in Hz.
Return type:	int

seek(position)¶

Seek to position in file.

If the source was not opened with its original sampling-rate, position corresponds to the position in the re-sampled file.

Parameters:	position (str) – position to seek to, in samples

channels¶

number of channels

Type:	int (read-only)

duration¶

total number of frames in the source

Can be estimated, for instance if the opened stream is a compressed media or a remote resource.

Example

>>> n = 0
>>> src = aubio.source('track1.mp3')
>>> for samples in src:
...     n += samples.shape[-1]
...
>>> n, src.duration
(9638784, 9616561)

Type:	int (read-only)

hop_size¶

number of samples read per iteration

Type:	int (read-only)

samplerate¶

sampling rate

Type:	int (read-only)

uri¶

pathname or URL

Type:	str (read-only)

class aubio.sink(path, samplerate=44100, channels=1)¶

Write audio samples to file.

Parameters:	path (str) – Pathname of the file to be opened for writing. samplerate (int) – Sampling rate of the file, in Hz. channels (int) – Number of channels to create the file with.

Examples

Create a new sink at 44100Hz, mono:

>>> snk = aubio.sink('out.wav')

Create a new sink at 32000Hz, stereo, write 100 samples into it:

>>> snk = aubio.sink('out.wav', samplerate=16000, channels=3)
>>> snk(aubio.fvec(100), 100)

Open a new sink at 48000Hz, stereo, write 1234 samples into it:

>>> with aubio.sink('out.wav', samplerate=48000, channels=2) as src:
...     snk(aubio.fvec(1024), 1024)
...     snk(aubio.fvec(210), 210)
...

See also

source: read audio samples from a file.

__call__(vec, length)¶

Write length samples from vec.

Parameters:	vec (array) – input vector to write from length (int) – number of samples to write
Example:

>>> with aubio.sink('foo.wav') as snk:
...     snk(aubio.fvec(1025), 1025)

close()¶

Close this sink now.

By default, the sink will be closed before being deleted. Explicitely closing a sink can be useful to control the number of files simultaneously opened.

do(vec, write)¶

Write a single channel vector to sink.

Parameters:	vec (fvec) – input vector (n,) where n >= 0. write (int) – Number of samples to write.

do_multi(mat, write)¶

Write a matrix containing vectors from multiple channels to sink.

Parameters:	mat (numpy.ndarray) – input matrix of shape (channels, n), where n >= 0. write (int) – Number of frames to write.

channels¶

Number of channels with which the sink was created.

Type:	int (read-only)

samplerate¶

Samplerate at which the sink was created.

Type:	int (read-only)

uri¶

Path at which the sink was created.

Type:	str (read-only)

Input/Output¶

Previous topic

Next topic

This Page