treble_tsdk.results.spatial_ir

Spatial impulse response handling and device rendering.

Provides the SpatialIR class for working with ambisonics spatial audio data and rendering device-specific impulse responses.

Functions

batch_render_device_ir(devices, spatial_irs)

Batch render a list of spatial impulse responses for a given device.

Classes

SpatialIR

Spatial impulse response with ambisonics channels.
class treble_tsdk.results.spatial_ir.SpatialIR

Spatial impulse response with ambisonics channels.

Represents multi-channel spatial audio data and provides methods for device rendering and analysis.

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

An object containing the data for a spatial IR and methods associated with such an impulse response.

Parameters:

  • data (np.ndarray) – Time series data with the shape (channel, time)

  • sampling_rate (float) – sampling rate of the time series

  • normalization_coefficient (float | None) – Normalization coefficient for correct amplitude of wavfile

  • time (np.ndarray | None) – Time vector for the time series

  • source (SourceDto | None) – The source associated with the IR

  • receiver (ReceiverDto | None) – The receiver associated with the IR

  • normalization_coefficient – The coefficient used to normalize the data

convolve_with_audio_signal(audio: AudioSignal) → ConvolvedAudioSignal

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

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

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(channel_range: tuple[int, int] = (0, 8))

Plot the spatial impulse response

render_device_ir(device: DeviceObj, orientation: Rotation = Rotation(azimuth=0.0, elevation=0.0, roll=0.0), ignore_max_frequency: bool = False, skip_print_cost: bool = False) → DeviceIR

Take a spatial impulse response and render a new device with it.

Parameters:

  • device (DeviceObj) – An object representing a device/head related transfer function

  • orientation (Rotation) – The orientation of the device

  • ignore_max_frequency (bool) – Whether to ignore the maximum frequency of the device (if it contains a maximum valid frequency)

Return DeviceIR:

The resulting impulse response object for the device

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

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.

treble_tsdk.results.spatial_ir.batch_render_device_ir(devices: 'DeviceObj' | list['DeviceObj'], spatial_irs: list[SpatialIR] | list[tuple[np.ndarray, float]], orientations: Rotation | list[Rotation] = [Rotation(azimuth=0.0, elevation=0.0, roll=0.0)], orientation_application: Literal['zipped', 'cartesian'] = 'cartesian', ignore_max_frequency: bool = False, output_mode: utils.ProgressOutputMode = ProgressOutputMode.TQDM_OUTPUT) → dict[int, list[list['DeviceIR']]]

Batch render a list of spatial impulse responses for a given device.

Parameters:

  • devices – list of devices or single device

  • spatial_irs – list of spatial impulse responses or list of tuples (data, sampling_rate)

  • orientations – list of orientations or single orientation

  • orientation_application – The application of the orientations. “cartesian” means all combinations are rendered, “zipped” pairs orientations and spatial irs one to one. Defaults to “cartesian”.

  • ignore_max_frequency – Whether to ignore the maximum frequency of the device (if it contains a maximum valid frequency)

  • output_mode – Progress output mode for the operation

Returns:

A dictionary mapping device index (int) to a list of lists of DeviceIR objects. Each outer list corresponds to a spatial IR, and each inner list contains the DeviceIR results for each orientation. For “cartesian” mode, inner lists contain len(orientations) DeviceIRs. For “zipped” mode, inner lists contain 1 DeviceIR each.

Return type:

dict[int, list[list[DeviceIR]]]