audiblelight.event.Event

audiblelight.event.Event#

class audiblelight.event.Event(filepath, alias, emitters=None, augmentations=None, image_filepath=None, scene_start=None, event_start=None, duration=None, snr=None, sample_rate=44100, class_id=None, class_label=None, spatial_resolution=None, spatial_velocity=None, shape=None, class_mapping=None, ref_ir_channel=None, direct_path_time_ms=None)#

Bases: object

Represents a single audio event taking place inside a Scene.

Parameters:

  • filepath (str | Path)

  • alias (str)

  • emitters (list[Emitter] | Emitter | list[dict] | None)

  • augmentations (Iterable[Type[EventAugmentation]] | Type[EventAugmentation] | None)

  • image_filepath (str | Path | None)

  • scene_start (float | None)

  • event_start (float | None)

  • duration (float | None)

  • snr (float | None)

  • sample_rate (int | None)

  • class_id (int | None)

  • class_label (str | None)

  • spatial_resolution (int | float | None)

  • spatial_velocity (int | float | None)

  • shape (str | None)

  • class_mapping (TClassMapping | dict | str | None)

  • ref_ir_channel (int | None)

  • direct_path_time_ms (Iterable | None)

__init__(filepath, alias, emitters=None, augmentations=None, image_filepath=None, scene_start=None, event_start=None, duration=None, snr=None, sample_rate=44100, class_id=None, class_label=None, spatial_resolution=None, spatial_velocity=None, shape=None, class_mapping=None, ref_ir_channel=None, direct_path_time_ms=None)#

Initializes the Event object, representing a single audio event taking place inside a Scene.

Parameters:

  • filepath (str | Path) – Path to the audio file.

  • alias (str) – Label to refer to this Event by inside the Scene

  • emitters (list[Emitter] | Emitter | list[dict] | None) – List of Emitter objects associated with this Event. If not provided, register_emitters must be called prior to rendering any Scene this Event is in.

  • augmentations (Iterable[Type[EventAugmentation]] | Type[EventAugmentation] | None) – Iterable of EventAugmentation objects associated with this Event. If not provided, EventAugmentations can be registered later by calling register_augmentations.

  • image_filepath (str | Path | None) – A path to an image file, used when generating visual representations of a scene. Must be provided in order to generate videos from a Scene.

  • scene_start (float | None) – Time to start the Event within the Scene, in seconds. Must be a positive number. If not provided, defaults to the beginning of the Scene (i.e., 0 seconds).

  • event_start (float | None) – Time to start the Event audio from, in seconds. Must be a positive number. If not provided, defaults to starting the audio at the very beginning (i.e., 0 seconds).

  • duration (float | None) – Time the Event audio lasts in seconds. Must be a positive number. If None or greater than the duration of the audio, defaults to using the full duration of the audio.

  • snr (float | None) – Signal to noise ratio for the audio file with respect to the noise floor

  • sample_rate (int | None) – If not None, the audio will be resampled to the given sample rate.

  • class_label (str | None) – Optional label to use for sound event class. If not provided, the label will attempt to be inferred from the ID using the DCASE sound event classes.

  • class_id (int | None) – Optional ID to use for sound event class. If not provided, the ID will attempt to be inferred from the label using the DCASE sound event classes.

  • shape (str | None) – the shape of the trajectory defined by emitters. Can be any string, only used in metadata.

  • class_mapping (TClassMapping | dict | str | None) – a mapping used to map class names to indices, and vice versa. Can be a subclass of audiblelight.class_mapping.ClassMapping, dict, or str.

  • ref_ir_channel (int | None) – reference IR channel to use when computing “dry” source, incorporating direct path & early reflections. If None, “dry” source will not be computed (default behaviour).

  • direct_path_time_ms (Iterable | None) – minimum and maximum time (in milliseconds) used to compute direct path for “dry” source. If None, “dry” source will not be computed (default behaviour).

  • spatial_resolution (int | float | None)

  • spatial_velocity (int | float | None)

Methods

__init__(filepath, alias[, emitters, ...])

Initializes the Event object, representing a single audio event taking place inside a Scene.

clear_augmentation(idx)

Clears an augmentation at a given index

clear_augmentations()

Removes all augmentations associated with this Event.

clear_emitter(idx)

Tries to remove an Emitter by its integer index

clear_emitters()

Removes all current emitters.

from_dict(input_dict)

Instantiate a Event from a dictionary.

get_augmentation(idx)

Gets a single augmentation associated with this Event by its integer index.

get_augmentations()

Gets all augmentations associated with this Event.

get_emitter(idx)

Gets a single Emitter associated with this Event by its integer index

get_emitters()

Gets all emitters associated with this Event.

load_audio([ignore_cache, normalize])

Returns the audio array of the Event.

load_image([ignore_cache])

Returns the image array of the Event.

register_augmentations(augmentations)

Register augmentations associated with this Event.

register_emitters(emitters)

Registers emitters associated with this event.

to_dict()

Returns metadata for this Event as a dictionary.

Attributes

has_emitters

Returns True if Event has valid emitters associated with it, False otherwise

is_audio_loaded

Returns True if audio is loaded and valid (see librosa.util.valid_audio for more detail).

is_image_loaded

Returns True if image is loaded and valid
__eq__(other)#

Compare two Event objects for equality.

Returns:

True if two Event objects are equal, False otherwise

Return type:

bool

Parameters:

other (Any)

__len__()#

Get the number of Emitters registered to this Event, alias for len(Event.emitters).

Return type:

int

__repr__()#

Returns representation of the scene as a JSON

Return type:

str

__str__()#

Returns a string representation of the scene

Return type:

str

clear_augmentation(idx)#

Clears an augmentation at a given index

Parameters:

idx (int)

Return type:

None

clear_augmentations()#

Removes all augmentations associated with this Event.

Return type:

None

clear_emitter(idx)#

Tries to remove an Emitter by its integer index

Parameters:

idx (int)

Return type:

None

clear_emitters()#

Removes all current emitters.

Return type:

None

classmethod from_dict(input_dict)#

Instantiate a Event from a dictionary.

Parameters:

input_dict (dict[str, Any]) – Dictionary that will be used to instantiate the Event.

Returns:

Event instance.

get_augmentation(idx)#

Gets a single augmentation associated with this Event by its integer index.

Parameters:

idx (int)

Return type:

Type[EventAugmentation]

get_augmentations()#

Gets all augmentations associated with this Event.

Return type:

list[Type[EventAugmentation]]

get_emitter(idx)#

Gets a single Emitter associated with this Event by its integer index

Parameters:

idx (int)

Return type:

Emitter

get_emitters()#

Gets all emitters associated with this Event.

Return type:

list[Emitter]

property has_emitters: bool#

Returns True if Event has valid emitters associated with it, False otherwise

property is_audio_loaded: bool#

Returns True if audio is loaded and valid (see librosa.util.valid_audio for more detail).

property is_image_loaded: bool#

Returns True if image is loaded and valid

load_audio(ignore_cache=False, normalize=True)#

Returns the audio array of the Event.

The audio will be loaded, resampled to the desired sample rate, converted to mono, and then truncated to match the event start time and duration. If normalize (defaults to True), audio will also be normalized to have a maximum absolute peak of 1.

After calling this function once, audio is cached as an attribute of this Event instance, and this attribute will be returned on successive calls unless ignore_cache is True.

Returns:

the audio array.

Return type:

np.ndarray

Parameters:

  • ignore_cache (bool | None)

  • normalize (bool | None)

load_image(ignore_cache=False)#

Returns the image array of the Event.

The image will be loaded and converted to RGB.

After calling this function once, audio is cached as an attribute of this Event instance, and this attribute will be returned on successive calls unless ignore_cache is True.

Returns:

the image array.

Return type:

np.ndarray

Parameters:

ignore_cache (bool | None)

register_augmentations(augmentations)#

Register augmentations associated with this Event.

Parameters:

augmentations (Iterable[Type[EventAugmentation]] | Type[EventAugmentation]) – Iterable of augmentations to register, or a single EventAugmentation type

Returns:

None

Return type:

None

register_emitters(emitters)#

Registers emitters associated with this event.

Parameters:

emitters (list[Emitter] | Emitter | list[dict]) – List of Emitter objects associated with this event.

Returns:

None

Return type:

None

to_dict()#

Returns metadata for this Event as a dictionary.

Return type:

dict

Contents