Timeseries¶

The timeseries module introduces classes for dealing with time as it relates to audio signals

Audio Samples¶

class zounds.timeseries.AudioSamples[source]¶

AudioSamples represents constant-rate samples of a continuous audio signal at common sampling rates.

It is a special case of an ArrayWithUnits whose first dimension is a TimeDimension that has a common audio sampling rate (e.g. SR44100).

Parameters:	array (np.ndarray) – The raw sample data samplerate (SampleRate) – The rate at which data was sampled
Raises:	`ValueError` – When array has a second dimension with size greater than 2 `TypeError` – When samplerate is not a `AudioSampleRate` (e.g. `SR22050`)

Examples::

>>> from zounds import AudioSamples, SR44100, TimeSlice, Seconds
>>> import numpy as np
>>> raw = np.random.normal(0, 1, 44100*10)
>>> samples = AudioSamples(raw, SR44100())
>>> samples.samples_per_second
44100
>>> samples.channels
1
>>> sliced = samples[TimeSlice(Seconds(2))]
>>> sliced.shape
(88200,)

classmethod from_example(arr, example)[source]¶: Produce a new ArrayWithUnits instance given some raw data and an example instance that has the desired dimensions

mono¶: Return this instance summed to mono. If the instance is already mono, this is a no-op.

encode(flo=None, fmt='WAV', subtype='PCM_16')[source]¶

Return audio samples encoded as bytes given a particular audio format

Parameters:

flo (file-like) – A file-like object to write the bytes to. If flo is not supplied, a new io.BytesIO instance will be created and returned
fmt (str) – A libsndfile-friendly identifier for an audio encoding (detailed here: http://www.mega-nerd.com/libsndfile/api.html)
subtype (str) – A libsndfile-friendly identifier for an audio encoding subtype (detailed here: http://www.mega-nerd.com/libsndfile/api.html)

Examples

>>> from zounds import SR11025, AudioSamples
>>> import numpy as np
>>> silence = np.zeros(11025*10)
>>> samples = AudioSamples(silence, SR11025())
>>> bio = samples.encode()
>>> bio.read(10)
'RIFFx]\x03\x00WA'

The Time Dimension¶

class zounds.timeseries.TimeDimension(frequency=None, duration=None, size=None)[source]¶

When applied to an axis of ArrayWithUnits, that axis can be viewed as representing a constant-rate time series sampled at a given SampleRate.

Parameters:	frequency (np.timedelta64) – The sampling frequency for this dimension duration (np.timedelta64) – The sampling duration for this dimension. When not provided it defaults to the sampling frequency size (int) – The size/length of the dimension
Raises:	`ValueError` – when frequency and/or duration are not `np.timedelta64` instances

Examples

>>> from zounds import ArrayWithUnits, TimeDimension, Seconds, TimeSlice
>>> import numpy as np
>>> raw = np.zeros(100)
>>> timeseries = ArrayWithUnits(raw, [TimeDimension(Seconds(1))])
>>> timeseries.dimensions[0]
TimeDimension(f=1.0, d=1.0)
>>> timeseries.dimensions[0].end_seconds
100.0
>>> sliced = timeseries[TimeSlice(Seconds(50))]
>>> sliced.shape
(50,)

metaslice(index, size)[source]¶: Produce a new instance of this dimension, given a custom slice

integer_based_slice(ts)[source]¶

Transform a TimeSlice into integer indices that numpy can work with

Parameters:	ts (slice, TimeSlice) – the time slice to translate into integer indices

class zounds.timeseries.TimeSlice(duration=None, start=None)[source]¶

A slice that can be applied to a TimeDimension to return a subset of samples.

Parameters:	duration (np.timedelta64) – The duration of the slice start (np.timedelta64) – A duration representing the start position of this slice, relative to zero or the beginning. If not provided, defaults to zero
Raises:	`ValueError` – when duration and/or start are not `numpy.timedelta64` instances

Examples

>>> from zounds import ArrayWithUnits, TimeDimension, TimeSlice, Seconds
>>> import numpy as np
>>> raw = np.zeros(100)
>>> ts = ArrayWithUnits(raw, [TimeDimension(Seconds(1))])
>>> sliced = ts[TimeSlice(duration=Seconds(5), start=Seconds(50))]
>>> sliced.shape
(5,)

Sample Rates¶

class zounds.timeseries.SR96000[source]¶

A SampleRate representing the common audio sampling rate 96kHz

Examples

>>> from zounds import SR96000
>>> sr = SR96000()
>>> sr.samples_per_second
96000
>>> int(sr)
96000
>>> sr.nyquist
48000

class zounds.timeseries.SR48000[source]¶

A SampleRate representing the common audio sampling rate 48kHz

Examples

>>> from zounds import SR48000
>>> sr = SR48000()
>>> sr.samples_per_second
48000
>>> int(sr)
48000
>>> sr.nyquist
24000

class zounds.timeseries.SR44100[source]¶

A SampleRate representing the common audio sampling rate 44.1kHz

Examples

>>> from zounds import SR44100
>>> sr = SR44100()
>>> sr.samples_per_second
44100
>>> int(sr)
44100
>>> sr.nyquist
22050

class zounds.timeseries.SR22050[source]¶

A SampleRate representing the common audio sampling rate 22.025kHz

Examples

>>> from zounds import SR22050
>>> sr = SR22050()
>>> sr.samples_per_second
22050
>>> int(sr)
22050
>>> sr.nyquist
11025

class zounds.timeseries.SR11025[source]¶

A SampleRate representing the common audio sampling rate 11.025kHz

Examples

>>> from zounds import SR11025
>>> sr = SR11025()
>>> sr.samples_per_second
11025
>>> int(sr)
11025
>>> sr.nyquist
5512

class zounds.timeseries.SampleRate(frequency, duration)[source]¶

SampleRate describes the constant frequency at which samples are taken from a continuous signal, and the duration of each sample.

Instances of this class could describe an audio sampling rate (e.g. 44.1kHz) or the strided windows often used in short-time fourier transforms

Parameters:	frequency (numpy.timedelta64) – The frequency at which the signal is sampled duration (numpy.timedelta64) – The duration of each sample
Raises:	`ValueError` – when frequency or duration are less than or equal to zero

Examples

>>> from zounds import Seconds, SampleRate
>>> sr = SampleRate(Seconds(1), Seconds(2))
>>> sr.frequency
numpy.timedelta64(1,'s')
>>> sr.duration
numpy.timedelta64(2,'s')
>>> sr.overlap
numpy.timedelta64(1,'s')
>>> sr.overlap_ratio
0.5

Durations¶

Zounds includes several convenience classes that make it possible to create time durations as numpy.timedelta64 instances without remembering or using magic strings to designate units.

class zounds.timeseries.Hours(*args, **kwargs)[source]¶

Convenience class for creating a duration in hours

Parameters:	hours (int) – duration in hours

Examples

>>> from zounds import Hours
>>> hours = Hours(3)
>>> hours
numpy.timedelta(3, 'h')

class zounds.timeseries.Minutes(*args, **kwargs)[source]¶

Convenience class for creating a duration in minutes

Parameters:	minutes (int) – duration in minutes

Examples

>>> from zounds import Minutes
>>> minutes = Minutes(3)
>>> minutes
numpy.timedelta(3, 'm')

class zounds.timeseries.Seconds(*args, **kwargs)[source]¶

Convenience class for creating a duration in seconds

Parameters:	seconds (int) – duration in seconds

Examples

>>> from zounds import Seconds
>>> seconds = Seconds(3)
>>> seconds
numpy.timedelta(3, 's')

class zounds.timeseries.Milliseconds(*args, **kwargs)[source]¶

Convenience class for creating a duration in milliseconds

Parameters:	milliseconds (int) – duration in milliseconds

Examples

>>> from zounds import Milliseconds
>>> ms = Milliseconds(3)
>>> ms
numpy.timedelta(3, 'ms')

class zounds.timeseries.Microseconds(*args, **kwargs)[source]¶

Convenience class for creating a duration in microseconds

Parameters:	microseconds (int) – duration in microseconds

Examples

>>> from zounds import Microseconds
>>> us = Microseconds(3)
>>> us
numpy.timedelta(3, 'us')

class zounds.timeseries.Nanoseconds(*args, **kwargs)[source]¶

Convenience class for creating a duration in nanoseconds

Parameters:	nanoseconds (int) – duration in nanoseconds

Examples

>>> from zounds import Nanoseconds
>>> ns = Nanoseconds(3)
>>> ns
numpy.timedelta(3, 'ns')

class zounds.timeseries.Picoseconds(*args, **kwargs)[source]¶

Convenience class for creating a duration in picoseconds

Parameters:	picoseconds (int) – duration in picoseconds

Examples

>>> from zounds import Picoseconds
>>> ps = Picoseconds(3)
>>> ps
numpy.timedelta(3, 'ps')