Audio derivatives

Description

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

Initialisation

AudioDerivative

class krajjat.classes.audio_derivatives.AudioDerivative(kind, path_or_samples, frequency, name=None, condition=None, verbosity=1): Parent class for the Envelope, Intensity, Pitch and Formant methods. Contains common methods for each of the subclasses.

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.

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 krajjat.classes.audio_derivatives.Envelope(samples, frequency=None, name=None, condition=None, verbosity=1)

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

New in version 2.0.

Parameters:

samples (list(float) or numpy.ndarray(float64)) – The envelope values.
frequency (int or float or None) – The frequency rate of the samples.
name (str or None, optional) – Defines the name of the Envelope instance.
condition (str or None, optional) – Optional field to represent in which experimental condition the original audio was clip recorded.

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

condition

Defines in which experimental condition the original audio was clip recorded.

Type:: str or None

Pitch

class krajjat.classes.audio_derivatives.Pitch(samples, frequency=None, name=None, condition=None, verbosity=1)

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

New in version 2.0.

Parameters:: samples (list(float) or numpy.ndarray(float64)) – The pitch values.

frequency: int or float: The frequency rate of the samples.
name: str or None, optional: Defines the name of the pitch. If set on None, the name will be the same as the original Audio instance, with the suffix "(PIT)".
condition: str or None, optional: Optional field to represent in which experimental condition the original audio was clip recorded.

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

condition

Defines in which experimental condition the original audio was clip recorded.

Type:: str or None

Intensity

class krajjat.classes.audio_derivatives.Intensity(samples, frequency=None, name=None, condition=None, verbosity=1)

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

New in version 2.0.

Parameters:

samples (list(float) or numpy.ndarray(float64)) – The intensity values.
frequency (int or float) – The frequency rate of the samples.
name (str or None, optional) – Defines the name of the Intensity instance.
condition (str or None, optional) – Optional field to represent in which experimental condition the original audio was clip recorded.

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

condition

Defines in which experimental condition the original audio was clip recorded.

Type:: str or None

Formant

class krajjat.classes.audio_derivatives.Formant(samples, frequency=None, formant_number=1, name=None, condition=None, verbosity=1)

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

New in version 2.0.

Parameters:

samples (list(float) or numpy.ndarray(float64)) – The formant values.
frequency (int or float) – The frequency rate of the samples.
formant_number (int) – The number of the formant to extract from the audio clip (default: 1 for f1).
name (str or None, optional) – Defines the name of the Formant instance.
condition (str or None, optional) – Optional field to represent in which experimental condition the original audio was clip recorded.

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

condition

Defines in which experimental condition the original audio was clip recorded.

Type:: str or None

formant_number

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

Type:: int

Magic methods

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

AudioDerivative.__repr__()

Returns the name attribute of the AudioDerivative.

Returns:: The attribute name of the AudioDerivative instance.
Return type:: str

AudioDerivative.__eq__(other)

Returns True if all the samples in the attribute samples have identical values between the two AudioDerivative objects, and if the frequency is identical.

New in version 2.0.

Parameters:: other (Audio) – Another Audio object.

Public methods

Setter functions

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.

Examples

>>> aud = Audio("Recordings/Ross/audio.wav")
>>> env = aud.get_envelope(filter_over=50)
>>> env.set_name("Envelope 001")

>>> pitch = Pitch("Recordings/Ross/pitch.tsv")
>>> pitch.set_name("Pitch 001")

AudioDerivative.set_condition(condition)

Sets the condition attribute of the AudioDerivative instance. This attribute can be used to save the experimental condition in which the AudioDerivative instance was recorded.

New in version 2.0.

Parameters:: condition (str) – The experimental condition in which the audio derivative was originally recorded.

Examples

>>> aud = Audio("Recordings/Rachel/audio.wav")
>>> env = aud.get_envelope(filter_over=50)
>>> env.set_condition("English")

>>> pitch = Pitch("Recordings/Rachel/pitch.tsv")
>>> pitch.set_condition("Spanish")

Getter functions

AudioDerivative.get_path()

Returns the attribute path of the AudioDerivative instance.

. versionadded:: 2.0

Returns:: The path of the AudioDerivative instance.
Return type:: str

Example

>>> envelope = Envelope("Recordings/Bob/envelope.xlsx")
>>> envelope.get_path()
Recordings/Bob/envelope.xlsx

AudioDerivative.get_name()

Returns the attribute name of the AudioDerivative instance.

. versionadded:: 2.0

Returns:: The name of the AudioDerivative instance.
Return type:: str

Example

>>> pitch = Pitch("Recordings/Charles/pitch_001.wav")
>>> pitch.get_name()
pitch_001
>>> pitch = Pitch("Recordings/Charles/pitch_002.wav", name="session 2")
>>> pitch.get_name()
session 2

AudioDerivative.get_condition()

Returns the attribute condition of the AudioDerivative instance.

. versionadded:: 2.0

Returns:

str – The condition of the AudioDerivative instance.
>>> intensity = Intensity(“Recordings/Chuck/recording_01.wav”)
>>> intensity.get_condition()
None
>>> intensity = Intensity(“Recordings/Chuck/recording_02.wav”, condition=”Basque”)
>>> intensity.get_condition()
Basque

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_sample(sample_index)

Returns the sample corresponding to the index passed as parameter.

New in version 2.0.

Parameters:: sample_index (int) – The index of the sample.
Returns:: A sample from the sequence.
Return type:: int

AudioDerivative.get_number_of_samples()

Returns the number of samples in the Audio derivative.

New in version 2.0.

Returns:: The amount of samples in the audio derivative.
Return type:: int

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_duration()

Returns the duration of the audio derivative, in seconds.

New in version 2.0.

Returns:: The duration of the audio derivative, in seconds.
Return type:: float

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_info(return_type='dict', include_path=True)

Returns information regarding the Audio derivative.

New in version 2.0.

Parameters:

return_type (bool, optional) – If set on "dict" (default), the info is returned as an OrderedDict. If set on "table", the info is returned as a two-dimensional list, ready to be exported as a table. If set on "str", a printable string is returned.
include_path (bool, optional) – If set on True, the path of the audio derivative is included in the returned info (default).

Returns:

An ordered dictionary where each descriptor is associated to its value. The included information fields are:

"Name": The name attribute of the audio derivative.

"Path": The path attribute of the audio derivative.

"Condition": The condition attribute of the audio derivative (if set).

"Frequency": Output of AudioDerivative.get_frequency().

"Number of samples": Output of AudioDerivative.get_number_of_samples().

"Duration": Output of AudioDerivative.get_duration().

Return type:

OrderedDict

Correction functions

AudioDerivative.filter_frequencies(filter_below=None, filter_over=None, padtype='constant', padlen=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.
padtype (str, optional) – What type of padding to use. See the documentation of scipy.signal.filtfilt for more information (default: "constant" - warning: this default is not scipy’s default ("odd").)
padlen (int, optional) –
The number of elements for the padding. See the documentation of scipy.signal.filtfilt for more information.
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, method='cubic', window_size=10000000.0, overlap_ratio=0.5, 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.
method (str, optional) – This parameter 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.
window_size (int, optional) – The size of the windows in which to cut the audio samples to perform the resampling. Cutting long arrays in windows allows to speed up the computation. If this parameter is set on None, the window size will be set on the number of samples. A good value for this parameter is generally 10 million (1e7). If this parameter is set on 0, on None or on a number of samples bigger than the amount of samples in the Audio instance, the window size is set on the length of the samples.
overlap_ratio (float, optional) – The ratio of samples overlapping between each window. If this parameter is not None, each window will overlap with the previous (and, logically, the next) for an amount of samples equal to the number of samples in a window times the overlap ratio. Then, only the central values of each window will be preserved and concatenated; this allows to discard any “edge” effect due to the windowing. If the parameter is set on None or 0, the windows will not overlap. By default, this parameter is set on 0.5, meaning that each window will overlap for half of their values with the previous, and half of their values with the next.
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.trim(start=None, end=None, name=None, error_if_out_of_bounds=False, verbosity=1, add_tabs=0)

Trims an audio derivative according to a starting and an ending timestamps. Timestamps must be provided in seconds.

New in version 2.0.

Parameters:

start (int or None, optional) – The timestamp after which the samples will be preserved. If set on None, the beginning of the audio derivative will be set as the timestamp of the first sample.
end (int or None, optional) – The timestamp before which the samples will be preserved. If set on None, the end of the audio derivative will be set as the timestamp of the last sample.
name (str or None, optional) – Defines the name of the output AudioDerivative instance. If set on None, the name will be the same as the original AudioDerivative instance, with the suffix "+TR".
error_if_out_of_bounds (bool, optional) – Defines if to return an error if the timestamps are out of bounds. If set on True, the function will raise an Exception if start is below 0, or if end is above the length of the audio.
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.
add_tabs (int, optional) – Adds the specified amount of tabulations to the verbosity outputs. This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them. In a normal use, it shouldn’t be set by the user.

Returns:

A new AudioDerivative instance containing a subset of the samples of the original.

Return type:

AudioDerivative

Conversion functions

AudioDerivative.to_table()

Returns a list of lists where each sublist contains a timestamp and a sample. The first sublist contains the headers of the table. The output then resembles the table found in Tabled formats.

New in version 2.0.

Returns:: A list of lists that can be interpreted as a table, containing headers, and with the timestamps and the sample value on each row.
Return type:: list(list)

AudioDerivative.to_json(include_metadata=True)

Returns a list ready to be exported in JSON. The returned JSON data is a dictionary with three keys: “Timestamp” is the key to the list of timestamps, “Sample” is the key to the list of samples, and “Frequency” is the key to the sampling frequency of the AudioDerivative.

New in version 2.0.

Parameters:: include_metadata (bool, optional) – Whether to include the metadata in the file (default: True).
Returns:: A dictionary containing the data of the audio derivative, ready to be exported in JSON.
Return type:: dict

AudioDerivative.to_dict(include_frequency=True)

Returns a dictionary containing the data of the AudioDerivative.

New in version 2.0.

Parameters:: include_frequency (bool, optional) – If set on True, includes the frequency of the AudioDerivative in the output dictionary.
Returns:: A dataframe containing the timestamps and samples of the AudioDerivative..
Return type:: dict

AudioDerivative.to_dataframe()

Returns a Pandas dataframe containing the data of the AudioDerivative.

New in version 2.0.

Returns:: A dataframe containing the timestamps and samples of the AudioDerivative.
Return type:: Pandas.dataframe

Saving function

AudioDerivative.save(folder_out, name=None, file_format='json', encoding='utf-8', individual=False, include_metadata=True, verbosity=1)

Saves an audio derivative in a file or a folder. The function saves the sequence under folder_out/name.file_format. All the non-existent subfolders present in the folder_out path will be created by the function. The function also updates the path attribute of the AudioDerivative.

New in version 2.0.

Parameters:

folder_out (str, optional) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them. If the string provided is empty (by default), the audio clip will be saved in the current working directory. If the string provided contains a file with an extension, the fields name and file_format will be ignored.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on the attribute name of the AudioDerivative; if that attribute is also set on None, the name will be set on "out". If individual is set on True, each sample will be saved as a different file, having the index of the pose as a suffix after the name (e.g. if the name is "sample" and the file format is "txt", the samples will be saved as sample_0.txt, sample_1.txt, sample_2.txt, etc.).
file_format (str or None, optional) –
The file format in which to save the AudioDerivative. The file format must be "json" (default), "xlsx", "txt", "csv", "tsv", "wav", or, if you are a masochist, "mat". Notes:
- "xls" will save the file with an .xlsx extension.
- Any string starting with a dot will be accepted (e.g. ".csv" instead of "csv").
- "csv;" will force the value separator on ;, while "csv," will force the separator on ,. By default, the function will detect which separator the system uses.
- "txt" and "tsv" both separate the values by a tabulation.
- Any other string will not return an error, but rather be used as a custom extension. The data will be saved as in a text file (using tabulations as values separators).
encoding (str, optional) – The encoding of the file to save (applicable for json and text-based files). By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats <https://docs.python.org/3/library/codecs.html#standard-encodings>`_.
individual (bool, optional) –
If set on False (default), the function will save the AudioDerivative in a unique file. If set on True, the function will save each sample of the AudioDerivative in an individual file, appending an underscore and the index of the sample (starting at 0) after the name. This option is not available and will be ignored if file_format is set on "wav".

Warning

It is not recommended to save each sample in a different file. This incredibly tedious way of handling audio files has only been implemented to follow the same logic as for the Sequence files, and should be avoided.
include_metadata (bool, optional) –
Whether to include the metadata in the file (default: True). This parameter does not apply to individually saved files.
- For json files, the metadata is saved at the top level. Metadata keys will be saved next to the "Poses" key.
- For mat files, the metadata is saved at the top level of the structure.
- For xlsx files, the metadata is saved in a second sheet.
- For pkl files, the metadata will always be saved as the object is saved as-is - this parameter is thus ignored.
- For wav files, the metadata is saved as tags in the file.
- For all the other formats, the metadata is saved at the beginning of the file.
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.save_json(folder_out, name=None, individual=False, include_metadata=True, encoding='utf-8', verbosity=1)

Saves an AudioDerivative as a json file or files. This function saves the AudioDerivative instance as folder_out/name.file_format.

New in version 2.0.

Parameters:

folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on "out" if individual is False, or on "sample" if individual is True.
individual (bool, optional) –
If set on False (default), the function will save the AudioDerivative in a unique file. If set on True, the function will save each sample of the AudioDerivative in an individual file, appending an underscore and the index of the sample (starting at 0) after the name.

Warning

It is not recommended to save each sample in a different file. This incredibly tedious way of handling audio files has only been implemented to follow the same logic as for the Sequence files, and should be avoided.
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True).
encoding (str, optional) – The encoding of the file to save. By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats.
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.save_mat(folder_out, name=None, individual=False, include_metadata=True, verbosity=1)

Saves an AudioDerivative as a Matlab .mat file or files. This function saves the AudioDerivative instance as folder_out/name.file_format.

New in version 2.0.

Important

This function is dependent of the module scipy.

Parameters:

folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on "out" if individual is False, or on "sample" if individual is True.
individual (bool, optional) –
If set on False (default), the function will save the AudioDerivative in a unique file. If set on True, the function will save each sample of the AudioDerivative in an individual file, appending an underscore and the index of the sample (starting at 0) after the name.

Warning

It is not recommended to save each sample in a different file. This incredibly tedious way of handling audio files has only been implemented to follow the same logic as for the Sequence files, and should be avoided.
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True).
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.save_excel(folder_out, name=None, individual=False, sheet_name='Data', include_metadata=True, metadata_sheet_name='Metadata', verbosity=1)

Saves an AudioDerivative as an Excel .xlsx file or files. This function saves the AudioDerivative instance as folder_out/name.file_format.

New in version 2.0.

Important

This function is dependent of the module openpyxl.

Parameters:

folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on "out" if individual is False, or on "sample" if individual is True.
individual (bool, optional) –
If set on False (default), the function will save the AudioDerivative in a unique file. If set on True, the function will save each sample of the AudioDerivative in an individual file, appending an underscore and the index of the sample (starting at 0) after the name.

Warning

It is not recommended to save each sample in a different file. This incredibly tedious way of handling audio files has only been implemented to follow the same logic as for the Sequence files, and should be avoided.
sheet_name (str|None, optional) – The name of the sheet containing the data. If None, a default name will be attributed to the sheet ("Sheet").
include_metadata (bool, optional) – Whether to include the metadata in the Excel file (default: True). The metadata is saved in a separate sheet in the same Excel file.
metadata_sheet_name (str|None, optional) – The name of the sheet containing the metadata. If None, a default name will be attributed to the sheet ("Metadata").
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.save_pickle(folder_out, name=None, individual=False, verbosity=1)

Saves an AudioDerivative by pickling it. This allows to reopen the content as an AudioDerivative object.

New in version 2.0.

Parameters:

folder_out (str) – The path to the folder where to save the file or files, or the complete path to the file. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on "out" if individual is False, or on "sample" if individual is True. This parameter is ignored if folder_out already contains the name of the file.
individual (bool, optional) – If set on False (default), the function will save the AudioDerivative in a unique file. If set on True, the function will save each sample of the AudioDerivative in an individual file, appending an underscore and the index of the sample (starting at 0) after the name.
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.save_wav(folder_out, name=None, include_metadata=True, verbosity=1)

Saves an AudioDerivative as a .wav file or files. This function saves the AudioDerivative instance as folder_out/name.file_format.

New in version 2.0.

Parameters:

folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on "out".
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True). The metadata is saved on the first lines of the file. Note: due to WAV tags limitations, the case of the metadata might be modified.
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.save_txt(folder_out, name=None, file_format='csv', encoding='utf-8', individual=False, include_metadata=True, verbosity=1)

Saves an AudioDerivative as a .txt, .csv, .tsv, or custom extension file or files. This function saves the AudioDerivative instance as folder_out/name.file_format.

New in version 2.0.

Parameters:

folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the AudioDerivative. If set on None, the name will be set on "out" if individual is False, or on "sample" if individual is True.
file_format (str, optional) – The file format in which to save the AudioDerivative clip. The file format can be "txt", "csv" (default) or "tsv". "csv;" will force the value separator on ";", while "csv," will force the separator on ",". By default, the function will detect which separator the system uses. "txt" and "tsv" both separate the values by a tabulation. Any other string will not return an error, but rather be used as a custom extension. The data will be saved as in a text file (using tabulations as values separators).
encoding (str, optional) –
The encoding of the file to save. By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats.
individual (bool, optional) –
If set on False (default), the function will save the AudioDerivative in a unique file. If set on True, the function will save each sample of the AudioDerivative in an individual file, appending an underscore and the index of the sample (starting at 0) after the name.

Warning

It is not recommended to save each sample in a different file. This incredibly tedious way of handling audio files has only been implemented to follow the same logic as for the Sequence files, and should be avoided.
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True). The metadata is saved on the first lines of the file.
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.

Copy function

AudioDerivative.copy()

Returns a deep copy of the AudioDerivative object.

New in version 2.0.

Returns:: A new AudioDerivative object, copy of the original.
Return type:: AudioDerivative

Private methods

Initialisation methods

AudioDerivative._load_from_path(verbosity=1)

Loads the AudioDerivative data from the path provided during the initialization.

New in version 2.0.

Parameters:

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._load_from_samples(samples, frequency, verbosity=1)

Loads the AudioDerivative data when samples and frequency have been provided upon initialisation.

New in version 2.0.

Parameters:

samples (list(int) or numpy.ndarray(int)) – A list containing the samples, in chronological order.
frequency (int or float) – The amount of samples per second.
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._load_samples(verbosity=1)

Loads the single sample files or the global file containing all the samples. Depending on the input, this function calls either AudioDerivative._load_single_sample_file() or AudioDerivative._load_audio_file().

New in version 2.0.

Parameters:

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._load_single_sample_file(sample_index, path, verbosity)

Loads the content of a single sample file into the AudioDerivative object. Depending on the file type, this function handles the content differently (see Audio formats).

New in version 2.0.

Parameters:

sample_index (int) – The index of the sample to load.
path (str) – The path of a file containing a single sample and timestamp.
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._load_audio_derivative_file(verbosity=1)

Loads the content of a file containing all the samples of the audio stream. Depending on the file type, this function handles the content differently (see Audio formats).

New in version 2.0.

Parameters:

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._load_json_metadata(data, verbosity=1)

Loads the data from the file apart from the samples, and saves it in the attribute metadata.

New in version 2.0.

Parameters:

data (dict) – The data from the file containing the full audio, or containing the first sample of the audio clip.
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._calculate_frequency(): Determines the frequency (number of samples per second) of the audio derivative by calculating the time elapsed between the two first timestamps. This function is automatically called when reading the timestamps and samples from a text file.

New in version 2.0.

AudioDerivative._calculate_timestamps(): Calculates the timestamps of the samples from the frequency and the number of samples. This function is automatically called when initializing the AudioDerivative.

New in version 2.0.

Special method

Formant._load_formant_number()