pytimbre.audio.Waveform

class pytimbre.audio.Waveform(pressures, sample_rate, start_time, remove_dc_offset: bool = True, is_continuous_wfm: bool = True, is_steady_state: bool = True, header=None)

Bases: object

|Description: This is a generic base class that contains the start time, samples and sample rate for a waveform. Some limited operations exist within this class for manipulation of the base data within the class.

# TODO: Add convolution function # TODO: Add filter array function Remarks 2022-05-11 - FSM - added the function to determine whether the waveform is a calibration signal or not.

__init__(pressures, sample_rate, start_time, remove_dc_offset: bool = True, is_continuous_wfm: bool = True, is_steady_state: bool = True, header=None)

Default constructor :param pressures:

float, array-like - the list of pressure values

Parameters:

• sample_rate – float - the number of samples per second

• start_time – float or datetime - the time of the first sample

• remove_dc_offset – bool, default = True - remove a DC offset from the samples

• is_continuous_wfm – bool - flag to determine whether this waveform is continuous or impulsive in nature. Default is True

• is_steady_state – bool - flag to determine whether this waveform is steady-state or transient in nature. Default is True

• header – Dictionary - the collection of information regarding the StandardBinaryFile’s properties.

Methods

__init__(pressures, sample_rate, start_time)	Default constructor :param pressures: float, array-like - the list of pressure values :param sample_rate: float - the number of samples per second :param start_time: float or datetime - the time of the first sample :param remove_dc_offset: bool, default = True - remove a DC offset from the samples :param is_continuous_wfm: bool - flag to determine whether this waveform is continuous or impulsive in nature. Default is True :param is_steady_state: bool - flag to determine whether this waveform is steady-state or transient in nature. Default is True :param header: Dictionary - the collection of information regarding the StandardBinaryFile's properties.
concatenate(wfm)	This will create a new audio file that contains the data from the current Waveform and adds the samples from the new Waveform to the list and then returns a new object.
cross_correlation(b[, mode, lag_limit])	This function determines the cross correlation between the current waveform and the waveform passed to the function.
detect_local_extrema(input_v, lag_n)	This will detect the local maxima of the vector on the interval [n-lag_n:n+lag_n]
determine_calibration_scale_factor([level, ...])	This function will take the information within the current Waveform and determine the scaling factor that can be applied to this, or any other file, to ensure that the acoustic reference is obtained.
from_standard_binary_file(path[, ...])	This will create a waveform object from a Standard Binary File formatted file.
from_wave_file(path[, s0, s1, header_only])	This function employs the functions within this file to read the data and metadata from a Wav file object and returns it as a Waveform object.
pad(pad_size, pad_value)	This function will insert values into the sample array according to the information in the pad_size object.
resample(new_sample_rate)	This function resamples the waveform and returns a new object with the correct sample rate and sample count.
scale_signal([factor, inplace, scale_type])	This method will call the sub-function to scale the values of the waveform in linear fashion.
split_by_time([frame_duration])	This will create a numpy array of waveform objects that have been split into segments controlled by the time window.
to_standard_binary_file([output_filename])	This function writes the current data within the Waveform into a StandardBinaryFile.
to_wav_file(path[, normalize])	This function will write the information from the Waveform into a properly formatted Wave file with associated information put into the List chunk for later retrieval.
trim([s0, s1, method])	This function will remove the samples before s0 and after s1 and adjust the start time :param s0: float - the sample index or time of the new beginning of the waveform :param s1: float - the sample index or time of the end of the new waveform :param method: trimming_methods - the method to trim the waveform :return: generic_time_waveform object

Attributes

channel_count
channels	This property creates a set of Waveform objects that represent the individual channels within the audio file.
duration	Determine the duration of the waveform by examining the number of samples and the sample rate :return: float - the total number of seconds within the waveform
end_time	Determine the end time - if the start time was a datetime, then this returns a datetime.
fundamental_frequency
header
is_calibration	This function examines the samples and determines whether the single contains a single pure tone.
is_clipped	This function attempts to determine whether there is clipping in the acoustic data represented in this waveform.
is_continuous
is_impulsive
is_mono	This function examines the size of the samples array within the function.
is_reverberant	This function classifies the audio file as either not sounding reverberant.
is_steady_state
is_transient
peak_level
peak_pressure
peak_time
sample_rate	The number of samples per second to define the waveform.
samples	The actual pressure waveform :return: float, array-like - the collection of waveform data
start_time	The time of the first sample :return: float or datetime - the time of the first sample
times	This determines the time past midnight for the start of the audio and returns a series of times for each sample :return: float, array-like - the sample times for each element of the samples array

property channels: ndarray

This property creates a set of Waveform objects that represent the individual channels within the audio file.

concatenate(wfm)

This will create a new audio file that contains the data from the current Waveform and adds the samples from the new Waveform to the list and then returns a new object.

:param : :type : param wfm: This is the Waveform that we want to concatenate with the current samples

Returns:

• A new waveform that contains the audio from the argument tacked onto the end of the samples from the current

• waveform.

cross_correlation(b, mode=CorrelationModes.valid, lag_limit=None)

This function determines the cross correlation between the current waveform and the waveform passed to the function.

Parameters:

• b (Waveform - the signal to compare to the current waveform's samples)

• mode (correlation_mode - the mode of the correlation that we want to execute for the correlation methods)

• lag_limit

Returns:

• value of the maximum correlation

• sample lag of the maximum correlation

• Remarks

• 2022-12-01 - FSM - Added completed enumeration usage for different correlation modes

static detect_local_extrema(input_v, lag_n)

This will detect the local maxima of the vector on the interval [n-lag_n:n+lag_n]

Parameters:

• input_v (double array-like) – This is the input vector that we are examining to determine the local maxima

• lag_n (double, integer) – This is the number of samples that we are examining within the input_v to determine the local maximum

Returns:

pos_max_v – The locations of the local maxima

Return type:

double, array-like

determine_calibration_scale_factor(level: float = 114, frequency: float = 1000, frequency_tolerance: float = 25)

This function will take the information within the current Waveform and determine the scaling factor that can be applied to this, or any other file, to ensure that the acoustic reference is obtained.

:paramdefault = 114 dB, this is the acoustic level at the specified frequency that we expect the calibration tone

to generate

:type : param level: float :param : default = 1000 Hz, this is the acoustic frequency of the calibration device :type : param frequency: float :param : The distance from the provided frequency that we are willing to go to ensure that this is a calibration tone :type : param frequency_tolerance:

property duration

Determine the duration of the waveform by examining the number of samples and the sample rate :return: float - the total number of seconds within the waveform

property end_time

Determine the end time - if the start time was a datetime, then this returns a datetime. Otherwise a floating point value is returned :return: float or datetime - the end of the file

static from_standard_binary_file(path: str, sample_rate_key: str = 'SAMPLE RATE (HZ)', start_time_key: str = 'TIME (UTC ZULU)', sample_format_key: str = 'SAMPLE FORMAT', data_format_key: str = 'DATA FORMAT', sample_count_key: str = 'SAMPLES TOTAL', s0=None, s1=None, header_only: bool = False)

This will create a waveform object from a Standard Binary File formatted file. :param s1: The end sample to read from the file. If it is None, then the last sample is read :type s1: int :param s0: The first or start sample to read from the file. If it is None, then the data is read from the first :type s0: int :param sample_count_key: The name of the header field that defines the sample count :type sample_count_key: string :param data_format_key: The name of the header field that defines the data format :type data_format_key: string :param sample_format_key: The name of the header field that defines the sample format :type sample_format_key: string :param start_time_key: The name of the header field that defines the start time of the first sample :type start_time_key: string :param sample_rate_key: The name of the header field that defines the number of samples per second :type sample_rate_key: string :param path: The full path to the file to read :type path: string :param header_only: Flag to return the header of the file without reading the remainder of the file :type header_only: bool :return: the contents of the file :rtype: Waveform

static from_wave_file(path: str, s0: int = None, s1: int = None, header_only: bool = False)

This function employs the functions within this file to read the data and metadata from a Wav file object and returns it as a Waveform object. :param header_only: Do not take the time to read the entire data from the file, just return the header :param s1: Ending point index :type s1: int :param s0: starting point index :type s0: int :param path: the location of the file to read :type path: str :return: The audio data from the Wave File :rtype: Waveform

property is_calibration

This function examines the samples and determines whether the single contains a single pure tone. If it does the function returns the approximate frequency of the tone. This will examine every channel and determine whether each channel is a calibration tone

Returns:

bool - flag determining whether the signal was pure tone float - the approximate frequency of the pure tone

property is_clipped

This function attempts to determine whether there is clipping in the acoustic data represented in this waveform.

property is_mono

This function examines the size of the samples array within the function. If there is a second dimension then this function returns false. It is true otherwise.

property is_reverberant

This function classifies the audio file as either not sounding reverberant.

This is based on the RT60 estimation algorithm documented in: Jan, T., and Wang, W., 2012: “Blind reverberation time estimation based on Laplace distribution”, EUSIPCO. pp. 2050-2054, Bucharest, Romania.

Version 0.4

Copyright 2019 Andy Pearce, Institute of Sound Recording, University of Surrey, UK.

Refactored from timbral_models.timbral_reverb function by Dr. Frank Mobley, 2023

pad(pad_size, pad_value)

This function will insert values into the sample array according to the information in the pad_size object. The value that is inserted is defined by the value in pad_value (default = 0). If pad_value is an integer, then all values are inserted at the front of the sample array. If pad_value is a list or an array, the first entry is the pad size for the front; the second entry is the pad value for the back of the array.

Parameters:

• pad_size (int or list/np.ndarray of ints) – The number of elements to add to the sample array. If the value is an integer, the points are added to the front of the sample array. Otherwise, the first entry is the front pad size, and the second entry is the rear pad size.

• pad_value (float or list/np.ndarray of floats) – The value to insert into the sample array based on the pad_size object

Return type:

A new waveform with the increased size.

resample(new_sample_rate: int)

This function resamples the waveform and returns a new object with the correct sample rate and sample count. This function employs the resample function within scipy.signal to conduct the resampling.

Parameters:

new_sample_rate (int - the new sample rate that we want to create a signal for)

Return type:

Waveform - the new waveform object that contains the resampled data with the new sample rate.

property sample_rate

The number of samples per second to define the waveform. :return: float - the number of samples per second

property samples

The actual pressure waveform :return: float, array-like - the collection of waveform data

scale_signal(factor: float = 1.0, inplace: bool = False, scale_type: ScalingMethods = ScalingMethods.linear)

This method will call the sub-function to scale the values of the waveform in linear fashion. If the scale factor is provided in logarithmic form, it will be converted to a linear value and sent to the sub-function.

:param : multiplied by the unscaled signal (e.g. 1 divided by the sensitivity of a microphone in V/Pa) :type : param factor: float - the scale factor that needs to be passed to the scaling sub-function, which will be :param : :type : param inplace: bool - whether to manipulate the data within the current class, or return a new instance :param : :type : param scale_type: scaling_method - how to apply the scaling to the signal

Return type:

returns: output of sub-function

split_by_time(frame_duration: float = 0.25)

This will create a numpy array of waveform objects that have been split into segments controlled by the time window.

:param : :type : param frame_duration: The amount of time in each new waveform segment - float, defaults to 0.25 seconds.

Return type:

A new waveform numpy array of waveform objects broken into segments equal to the window size.

property start_time

The time of the first sample :return: float or datetime - the time of the first sample

property times

This determines the time past midnight for the start of the audio and returns a series of times for each sample :return: float, array-like - the sample times for each element of the samples array

to_standard_binary_file(output_filename: str = '')

This function writes the current data within the Waveform into a StandardBinaryFile. :param output_filename: the location to write the data to :type output_filename: str

to_wav_file(path, normalize: bool = True)

This function will write the information from the Waveform into a properly formatted Wave file with associated information put into the List chunk for later retrieval. :param path: the location to write the file :type path: str :param normalize: whether to normalize the data and create a Peak chunk :type normalize: bool

trim(s0: float = 0.0, s1: float = None, method: TrimmingMethods = TrimmingMethods.samples)

This function will remove the samples before s0 and after s1 and adjust the start time :param s0: float - the sample index or time of the new beginning of the waveform :param s1: float - the sample index or time of the end of the new waveform :param method: trimming_methods - the method to trim the waveform :return: generic_time_waveform object