Audio derivatives

Description

Classes for time series derived from audio clips: Envelope, Intensity, Pitch and Formants.

AudioDerivative

Note

This class is a parent class for Envelope, Pitch, Intensity and Formant. This class should not be called directly: instead, the methods should be called through the child classes when an object is created by one of the instances of the class Audio.

Initialisation

class classes.audio_derivatives.AudioDerivative(samples, timestamps, frequency, kind, name=None)

Parent class for the Envelope, Intensity, Pitch and Formant methods. Contains common methods for each of the subclasses.

New in version 2.0.

Parameters:
  • samples (list(float) or numpy.ndarray(float64)) – An array containing the values for the audio derivative.

  • timestamps (list(float) or numpy.ndarray(float64)) – An array of equal length to samples, containing the timestamps for each sample.

  • frequency (int or float) – The frequency, in Hertz, of the timestamps.

  • kind (str or None) – The kind of audio derivative: "Envelope", "Pitch", "Intensity", "Formant", or None.

  • name (str or None, optional) – The name of the audio derivative. By default, this field is used to store the name of the audio clip the derivative comes from, with a suffix indicating the type of the audio derivative.

samples

An array containing the values for the audio derivative.

Type:

list(float) or numpy.ndarray(float64)

timestamps

An array of equal length to samples, containing the timestamps for each sample.

Type:

list(float) or numpy.ndarray(float64)

frequency

The frequency, in Hertz, at which the values in attr:samples are sampled.

Type:

int or float

kind

The kind of audio derivative: "Envelope", "Pitch", "Intensity", "Formant", or None.

Type:

str or None

name

The name of the audio derivative. By default, this field is used to store the name of the audio clip the derivative comes from, with a suffix indicating the type of the audio derivative.

Type:

str or None, optional

Methods

AudioDerivative.set_name(name)

Sets the name attribute of the AudioDerivative instance. This name can be used as a way to identify the original Audio instance from which the AudioDerivative has been created.

New in version 2.0.

Parameters:

name (str) – A name to describe the audio derivative.

AudioDerivative.get_samples()

Returns the attribute samples of the audio derivative.

New in version 2.0.

Returns:

An array containing the values for the audio derivative.

Return type:

list(float) or numpy.ndarray(float64)

AudioDerivative.get_timestamps()

Returns the attribute samples of the audio derivative.

New in version 2.0.

Returns:

An array containing the timestamps for each sample.

Return type:

list(float) or numpy.ndarray(float64)

AudioDerivative.get_frequency()

Returns the attribute frequency of the audio derivative.

New in version 2.0.

Returns:

The frequency, in Hertz, at which the values in attr:samples are sampled.

Return type:

int or float

AudioDerivative.get_name()

Returns the attribute name of the audio derivative. Unless modified, the value of this attribute should be the same as the value of the original Audio.name attribute.

New in version 2.0.

Returns:

The value of the attribute name of the audio derivative.

Return type:

str

AudioDerivative.get_number_of_samples()

Returns the length of the attribute samples.

New in version 2.0.

Returns:

The number of samples in the audio derivative.

Return type:

int

AudioDerivative.filter_frequencies(filter_below=None, filter_over=None, name=None, verbosity=1)

Applies a low-pass, high-pass or band-pass filter to the data in the attribute samples.

Parameters:
  • filter_below (float or None, optional) – The value below which you want to filter the data. If set on None or 0, this parameter will be ignored. If this parameter is the only one provided, a high-pass filter will be applied to the samples; if filter_over is also provided, a band-pass filter will be applied to the samples.

  • filter_over (float or None, optional) – The value over which you want to filter the data. If set on None or 0, this parameter will be ignored. If this parameter is the only one provided, a low-pass filter will be applied to the samples; if filter_below is also provided, a band-pass filter will be applied to the samples.

  • name (str or None, optional) – Defines the name of the output audio derivative. If set on None, the name will be the same as the original audio derivative, with the suffix "+FF".

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

Returns:

The AudioDerivative instance, with filtered values.

Return type:

AudioDerivative

AudioDerivative.resample(frequency, mode='cubic', name=None, verbosity=1)

Resamples an audio derivative to the frequency parameter. This function first creates a new set of timestamps at the desired frequency, and then interpolates the original data to the new timestamps.

New in version 2.0.

Parameters:
  • frequency (float) – The frequency, in hertz, at which you want to resample the audio derivative. A frequency of 4 will return samples at 0.25 s intervals.

  • mode (str, optional) – This parameter also allows for all the values accepted for the kind parameter in the function scipy.interpolate.interp1d(): "linear", "nearest", "nearest-up", "zero", "slinear", "quadratic", "cubic" (default), "previous", and "next". See the documentation for this Python module for more.

  • name (str or None, optional) – Defines the name of the output audio derivative. If set on None, the name will be the same as the original audio derivative, with the suffix "+RS".

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

AudioDerivative.__len__()

Returns the number of samples in the audio derivative (i.e., the length of the attribute samples).

New in version 2.0.

Returns:

The number of samples in the audio derivative.

Return type:

int

AudioDerivative.__getitem__(index)

Returns the sample of index specified by the parameter index.

Parameters:

index (int) – The index of the sample to return.

Returns:

A sample from the attribute samples.

Return type:

float

All of the following classes inherit from AudioDerivative: all the methods described above can then be used for any object from the classes below.

Envelope

class classes.audio_derivatives.Envelope(audio_or_samples, timestamps=None, frequency=None, name=None, verbosity=1)

This class contains the samples from the envelope of an audio clip.

New in version 2.0.

Parameters:
  • audio_or_samples (Audio or list(float) or numpy.ndarray(float64)) – An Audio instance, or an array containing the samples of an audio file. In the case where this parameter is an array, at least one of the parameters timestamps and frequency must be provided.

  • timestamps (list(float) or numpy.ndarray(float64) or None, optional) – The timestamps of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • frequency (int or float or None, optional) – The frequency rate of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • name (str or None, optional) – Defines the name of the envelope. If set on None, the name will be the same as the original Audio instance, with the suffix "(ENV)".

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

samples

An array containing the samples of the envelope.

Type:

list(float) or numpy.ndarray(float64)

timestamps

An array of equal length to samples, containing the timestamps for each sample.

Type:

list(float) or numpy.ndarray(float64)

frequency

The frequency, in Hertz, at which the values in attr:samples are sampled.

Type:

int or float

name

A name to describe the envelope object.

Type:

str or None

Pitch

class classes.audio_derivatives.Pitch(audio_or_samples, timestamps=None, frequency=None, name=None, zeros_as_nan=False, verbosity=1)

This class contains the values of the pitch of an audio clip.

New in version 2.0.

Parameters:
  • audio_or_samples (Audio or list(float) or numpy.ndarray(float64)) – An Audio instance, or an array containing the samples of an audio file. In the case where this parameter is an array, at least one of the parameters timestamps and frequency must be provided.

  • timestamps (list(float) or numpy.ndarray(float64) or None, optional) – The timestamps of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • frequency (int or float or None, optional) – The frequency rate of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • name (str or None, optional) – Defines the name of the envelope. If set on None, the name will be the same as the original Audio instance, with the suffix "(PIT)".

  • zeros_as_nan (bool, optional) – If set on True, the values where the pitch is equal to 0 will be replaced by numpy.nan objects.

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

samples

An array containing the values of the pitch.

Type:

list(float) or numpy.ndarray(float64)

timestamps

An array of equal length to samples, containing the timestamps for each sample.

Type:

list(float) or numpy.ndarray(float64)

frequency

The frequency, in Hertz, at which the values in attr:samples are sampled.

Type:

int or float

name

A name to describe the pitch object.

Type:

str or None

Intensity

class classes.audio_derivatives.Intensity(audio_or_samples, timestamps=None, frequency=None, name=None, verbosity=1)

This class contains the values of the intensity of an audio clip.

New in version 2.0.

Parameters:
  • audio_or_samples (Audio or list(float) or numpy.ndarray(float64)) – An Audio instance, or an array containing the samples of an audio file. In the case where this parameter is an array, at least one of the parameters timestamps and frequency must be provided.

  • timestamps (list(float) or numpy.ndarray(float64) or None, optional) – The timestamps of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • frequency (int or float or None, optional) – The frequency rate of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • name (str or None, optional) – Defines the name of the envelope. If set on None, the name will be the same as the original Audio instance, with the suffix "(INT)".

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

samples

An array containing the values of the intensity.

Type:

list(float) or numpy.ndarray(float64)

timestamps

An array of equal length to samples, containing the timestamps for each sample.

Type:

list(float) or numpy.ndarray(float64)

frequency

The frequency, in Hertz, at which the values in attr:samples are sampled.

Type:

int or float

name

A name to describe the intensity object.

Type:

str or None

Formant

class classes.audio_derivatives.Formant(audio_or_samples, timestamps=None, frequency=None, name=None, formant_number=1, verbosity=1)

This class contains the values of one of the formants of an audio clip.

New in version 2.0.

Parameters:
  • audio_or_samples (Audio or list(float) or numpy.ndarray(float64)) – An Audio instance, or an array containing the samples of an audio file. In the case where this parameter is an array, at least one of the parameters timestamps and frequency must be provided.

  • timestamps (list(float) or numpy.ndarray(float64) or None, optional) – The timestamps of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • frequency (int or float or None, optional) – The frequency rate of the samples. This parameter is ignored if audio_or_samples is an instance of Audio.

  • name (str or None, optional) – Defines the name of the envelope. If set on None, the name will be the same as the original Audio instance, with the suffix "(INT)".

  • formant_number (int, optional) – The number of the formant to extract from the audio clip (default: 1 for f1).

samples

An array containing the values of the formant.

Type:

list(float) or numpy.ndarray(float64)

timestamps

An array of equal length to samples, containing the timestamps for each sample.

Type:

list(float) or numpy.ndarray(float64)

frequency

The frequency, in Hertz, at which the values in attr:samples are sampled.

Type:

int or float

name

A name to describe the intensity object.

Type:

str or None

formant_number

The number of the formant (e.g., 1).

Type:

int