treble_tsdk.results.audio_signal

Audio signal and convolved audio handling.

Provides AudioSignal and ConvolvedAudioSignal classes for working with audio waveforms and convolved impulse response data.

Classes

AudioSignal

Audio signal class for handling audio data

ConvolvedAudioSignal

Audio signal produced by convolving an impulse response with an input waveform.
class treble_tsdk.results.audio_signal.AudioSignal

Audio signal class for handling audio data

__init__(data: numpy.ndarray, sampling_rate: float, time: numpy.ndarray | None = None, source: list[SourceResults] | None = None, receiver: list[ReceiverResults] | None = None, zero_pad_samples: int = 0, normalization_coefficient: float | None = None)

A Class handling all mono impulse response related actions

Parameters:

  • data (np.ndarray) – The time domain impulse response

  • sampling_rate (float) – The sampling rate of the impulse response

  • source (Source | None) – Information on source, defaults to None

  • receiver (Receiver | None) – Information on receiver, defaults to None

  • zero_pad_samples (int) – The number of samples that have been zero padded in the beginning, defaults to 0

  • normalization_coefficient (float | None) – The coefficient used to normalize the data

add_silence(silence_start_s: float = 0, silence_end_s: float = 0) → AudioSignal' | 'ConvolvedAudioSignal

Add silence to the audio signal

Parameters:

  • silence_start_s (float) – the duration of the silence to add at the beginning

  • silence_end_s (float) – the duration of the silence to add at the end

Returns AudioSignal | ConvolvedAudioSignal:

A new audio signal with the added silence

append_signal(signal: AudioSignal' | 'ConvolvedAudioSignal, time_start: float = None) → AudioSignal' | 'ConvolvedAudioSignal

Add an audio signal to the audio track

Parameters:
Returns AudioSignal | ConvolvedAudioSignal:

the new audio track

convolve_with_audio_signal(audio: AudioSignal) → AudioSignal

Convolve the impulse response with an audio signal to get a convolved audio signal

Parameters:

audio (AudioSignal) – signal to be convolved with the IR

Return AudioSignal:

The convolved audio signal

crop(time_start: float, time_end: float, fadein_s: float = 0.005, fadeout_s: float = 0.005) → AudioSignal' | 'ConvolvedAudioSignal

Crop the audio signal to a specified segment

Parameters:

  • time_start (float) – the start time of the segment

  • time_end (float) – the end time of the segment

  • fadein_s (float) – length of fadein in seconds, defaults to 0.005

  • fadeout_s (float) – length of fadeout in seconds, defaults to 0.005

Return AudioSignal:

A new cropped audio signal

filter(filter_definition: FilterDefinition | list[FilterDefinition] | Callable[[np.ndarray, int], np.ndarray] | list[Callable[[np.ndarray, int], np.ndarray]]) → MonoIR | SpatialIR | DeviceIR | AudioSignal | ConvolvedAudioSignal
Parameters:

filter_definition – The filter definition to use. Either a class inheriting from FilterDefinition, or a callable that accepts (numpy.ndarray, int) and returns a numpy.ndarray. A single value or a list of either type is accepted.

Returns:

The filtered impulse response.

classmethod from_file(filepath: str | Path, channel: int = None, zero_pad_samples: int = 0) → AudioSignal

Create from a wav file

Parameters:

  • filepath (str | Path) – path to the wav file

  • channel (int) – if the input is multichannel, choose the channel to load, defaults to None

Return AudioSignal:

the audio signal loaded from file

pad_to_duration(duration_seconds: float) → AudioSignal' | 'ConvolvedAudioSignal

Pad the audio signal to a specified duration

Parameters:

duration_seconds (float) – the requested duration in seconds

Return AudioSignal:

A new audio signal with the padded duration

playback(channel: int | None = None) → IPython.display.Audio

Play back the audio using the ipython display module

Parameters:

channel (int | None) – select the channel you want to play back, if None is selected stereo will be played back if there are two channels, defaults to None

Return ipd.Audio:

IPython audio object

plot(title: str = 'Audio data')

Plot the audio signal

repeat_to_duration(duration_seconds: float, full_repeat: bool = False, fadeout_samples: int = 1024) → AudioSignal' | 'ConvolvedAudioSignal

Repeat the audio audio signal to a specified duration

Parameters:

  • duration_seconds (float) – requested duration in seconds

  • full_repeat (bool) – set to true if the signal only should be repeated in full length, i.e. not cut the last repeat of the signal, defaults to False

  • fadeout_samples (int) – number of samples to fade the signal out with, defaults to 1024

Return AudioSignal:

the new audio signal

resample(requested_sampling_rate: float = 32000) → MonoIR | SpatialIR | DeviceIR | AudioSignal | ConvolvedAudioSignal

Resample the data to a new sampling rate

Parameters:

requested_sampling_rate (int) – The new sampling rate

Return “MonoIR | SpatialIR | DeviceIR | AudioSignal | ConvolvedAudioSignal”:

The returned audio signal

strip_first_samples(n_samples: int) → numpy.ndarray

Returns an array with the first n_samples removed

trim_to_duration(duration_seconds: float, fadeout_samples: int = 1024) → AudioSignal' | 'ConvolvedAudioSignal

Trim the audio signal to a specified duration

Parameters:

  • duration_seconds (float) – the requested duration in seconds

  • fadeout_samples (int) – number of samples of fadeout, defaults to 1024

Return AudioSignal:

A new audio signal with the trimmed duration

unpadded_data() → numpy.ndarray

Returns the impulse response without zero padding

Return np.ndarray:

The impulse response without zero padding

unpadded_time() → numpy.ndarray

Returns the time vector without zero padding

Return np.ndarray:

The time vector without zero padding

write_to_file(file_path: str | Path) → None

Write the impulse response to an HDF5 file

Parameters:

file_path (str | Path) – The path to the HDF5 file

write_to_wav(path_to_file: str | Path, normalize: bool = True, unpad_data: bool = True) → float

Write the data out to a .wav file

Parameters:

  • path_to_file (str | Path) – Where to store the file (the directory needs to exist)

  • normalize (bool) – Whether to normalize the data before writing to .wav if the impulse response object contains a normalization coefficient this one will be used otherwise it will be the absolute maximum of the data times two, defaults to True

  • unpad_data (bool) – Whether to unpad the data before writing to .wav, defaults to True

Return float:

The normalization coefficient used

property frequency: numpy.ndarray

Frequency vector for the frequency domain representation.

Returns np.ndarray:

Frequency values in Hz.

property frequency_response: numpy.ndarray

Frequency domain representation of the impulse response.

Returns np.ndarray:

Complex frequency response.

class treble_tsdk.results.audio_signal.ConvolvedAudioSignal

Audio signal produced by convolving an impulse response with an input waveform.

Provides utilities to access individual channels, plot, normalize, resample, and manipulate the convolved audio signal.

__init__(data: numpy.ndarray, sampling_rate: float, time: numpy.ndarray | None = None, source: list[SourceResults] | None = None, receiver: list[ReceiverResults] | None = None, zero_pad_samples: int = 0, normalization_coefficient: float | None = None)

A Class handling all mono impulse response related actions

Parameters:

  • data (np.ndarray) – The time domain impulse response

  • sampling_rate (float) – The sampling rate of the impulse response

  • source (Source | None) – Information on source, defaults to None

  • receiver (Receiver | None) – Information on receiver, defaults to None

  • zero_pad_samples (int) – The number of samples that have been zero padded in the beginning, defaults to 0

  • normalization_coefficient (float | None) – The coefficient used to normalize the data

add_silence(silence_start_s: float = 0, silence_end_s: float = 0) → AudioSignal' | 'ConvolvedAudioSignal

Add silence to the audio signal

Parameters:

  • silence_start_s (float) – the duration of the silence to add at the beginning

  • silence_end_s (float) – the duration of the silence to add at the end

Returns AudioSignal | ConvolvedAudioSignal:

A new audio signal with the added silence

append_signal(signal: AudioSignal' | 'ConvolvedAudioSignal, time_start: float = None) → AudioSignal' | 'ConvolvedAudioSignal

Add an audio signal to the audio track

Parameters:
Returns AudioSignal | ConvolvedAudioSignal:

the new audio track

convolve_with_audio_signal(audio: AudioSignal) → AudioSignal

Convolve the impulse response with an audio signal to get a convolved audio signal

Parameters:

audio (AudioSignal) – signal to be convolved with the IR

Return AudioSignal:

The convolved audio signal

crop(time_start: float, time_end: float, fadein_s: float = 0.005, fadeout_s: float = 0.005) → AudioSignal' | 'ConvolvedAudioSignal

Crop the audio signal to a specified segment

Parameters:

  • time_start (float) – the start time of the segment

  • time_end (float) – the end time of the segment

  • fadein_s (float) – length of fadein in seconds, defaults to 0.005

  • fadeout_s (float) – length of fadeout in seconds, defaults to 0.005

Return AudioSignal:

A new cropped audio signal

filter(filter_definition: FilterDefinition | list[FilterDefinition] | Callable[[np.ndarray, int], np.ndarray] | list[Callable[[np.ndarray, int], np.ndarray]]) → MonoIR | SpatialIR | DeviceIR | AudioSignal | ConvolvedAudioSignal
Parameters:

filter_definition – The filter definition to use. Either a class inheriting from FilterDefinition, or a callable that accepts (numpy.ndarray, int) and returns a numpy.ndarray. A single value or a list of either type is accepted.

Returns:

The filtered impulse response.

classmethod from_file(filepath: str | Path, channel: int = None, zero_pad_samples: int = 0) → AudioSignal

Create from a wav file

Parameters:

  • filepath (str | Path) – path to the wav file

  • channel (int) – if the input is multichannel, choose the channel to load, defaults to None

Return AudioSignal:

the audio signal loaded from file

pad_to_duration(duration_seconds: float) → AudioSignal' | 'ConvolvedAudioSignal

Pad the audio signal to a specified duration

Parameters:

duration_seconds (float) – the requested duration in seconds

Return AudioSignal:

A new audio signal with the padded duration

playback(channel: int | None = None) → IPython.display.Audio

Play back the audio using the ipython display module

Parameters:

channel (int | None) – select the channel you want to play back, if None is selected stereo will be played back if there are two channels, defaults to None

Return ipd.Audio:

IPython audio object

plot(title: str = 'Convolved audio data')

Plot the convolved audio signal

repeat_to_duration(duration_seconds: float, full_repeat: bool = False, fadeout_samples: int = 1024) → AudioSignal' | 'ConvolvedAudioSignal

Repeat the audio audio signal to a specified duration

Parameters:

  • duration_seconds (float) – requested duration in seconds

  • full_repeat (bool) – set to true if the signal only should be repeated in full length, i.e. not cut the last repeat of the signal, defaults to False

  • fadeout_samples (int) – number of samples to fade the signal out with, defaults to 1024

Return AudioSignal:

the new audio signal

resample(requested_sampling_rate: float = 32000) → MonoIR | SpatialIR | DeviceIR | AudioSignal | ConvolvedAudioSignal

Resample the data to a new sampling rate

Parameters:

requested_sampling_rate (int) – The new sampling rate

Return “MonoIR | SpatialIR | DeviceIR | AudioSignal | ConvolvedAudioSignal”:

The returned audio signal

strip_first_samples(n_samples: int) → numpy.ndarray

Returns an array with the first n_samples removed

trim_to_duration(duration_seconds: float, fadeout_samples: int = 1024) → AudioSignal' | 'ConvolvedAudioSignal

Trim the audio signal to a specified duration

Parameters:

  • duration_seconds (float) – the requested duration in seconds

  • fadeout_samples (int) – number of samples of fadeout, defaults to 1024

Return AudioSignal:

A new audio signal with the trimmed duration

unpadded_data() → numpy.ndarray

Returns the impulse response without zero padding

Return np.ndarray:

The impulse response without zero padding

unpadded_time() → numpy.ndarray

Returns the time vector without zero padding

Return np.ndarray:

The time vector without zero padding

write_to_file(file_path: str | Path) → None

Write the impulse response to an HDF5 file

Parameters:

file_path (str | Path) – The path to the HDF5 file

write_to_wav(path_to_file: str | Path, normalize: bool = True, unpad_data: bool = True) → float

Write the data out to a .wav file

Parameters:

  • path_to_file (str | Path) – Where to store the file (the directory needs to exist)

  • normalize (bool) – Whether to normalize the data before writing to .wav if the impulse response object contains a normalization coefficient this one will be used otherwise it will be the absolute maximum of the data times two, defaults to True

  • unpad_data (bool) – Whether to unpad the data before writing to .wav, defaults to True

Return float:

The normalization coefficient used

property frequency: numpy.ndarray

Frequency vector for the frequency domain representation.

Returns np.ndarray:

Frequency values in Hz.

property frequency_response: numpy.ndarray

Frequency domain representation of the impulse response.

Returns np.ndarray:

Complex frequency response.