audiblelight.core.Scene

audiblelight.core.Scene#

class audiblelight.core.Scene(duration, mesh_path, fg_path=None, bg_path=None, allow_duplicate_audios=True, ref_db=-65, scene_start_dist=None, event_start_dist=None, event_duration_dist=None, event_velocity_dist=None, event_resolution_dist=None, snr_dist=None, max_overlap=2, event_augmentations=None, scene_augmentations=None, state_kwargs=None)#

Bases: object

Initializes a Scene.

The Scene object is the highest level object within AudibleLight. It holds information relating to the current WorldState (including a 3D mesh, alongside listeners and sound sources) and any sound Event objects within it.

Parameters:

  • duration (int | float | complex | integer | floating)

  • mesh_path (str | Path)

  • fg_path (str | Path | None)

  • bg_path (str | Path | None)

  • allow_duplicate_audios (bool)

  • ref_db (int | float | complex | integer | floating | None)

  • scene_start_dist (DistributionLike | None)

  • event_start_dist (DistributionLike | None)

  • event_duration_dist (DistributionLike | None)

  • event_velocity_dist (DistributionLike | None)

  • event_resolution_dist (DistributionLike | None)

  • snr_dist (DistributionLike | None)

  • max_overlap (int | float | complex | integer | floating | None)

  • event_augmentations (Iterable[Type[EventAugmentation]] | Iterable[tuple[Type[EventAugmentation], dict]] | Type[EventAugmentation] | None)

  • scene_augmentations (Type[SceneAugmentation] | Iterable[Type[SceneAugmentation]] | None)

  • state_kwargs (dict | None)

__init__(duration, mesh_path, fg_path=None, bg_path=None, allow_duplicate_audios=True, ref_db=-65, scene_start_dist=None, event_start_dist=None, event_duration_dist=None, event_velocity_dist=None, event_resolution_dist=None, snr_dist=None, max_overlap=2, event_augmentations=None, scene_augmentations=None, state_kwargs=None)#

Initializes the Scene with a given duration and mesh.

Parameters:

  • duration (int | float | complex | integer | floating) – the length of time the scene audio should last for.

  • mesh_path (str | Path) – the name of the mesh file. Units will be coerced to meters when loading.

  • fg_path (str | Path | None) – a directory (or list of directories) pointing to foreground audio. Note that directories will be introspected recursively, such that audio files within any subdirectories will be detected also.

  • bg_path (str | Path | None) – a directory (or list of directories pointing to background audio. Note that directories will be introspected recursively, such that audio files within any subdirectories will be detected also.

  • allow_duplicate_audios (bool) – if True (default), the same audio file can appear multiple times in the Scene.

  • ref_db (int | float | complex | integer | floating | None) – reference decibel level for scene noise floor, defaults to -65 dB

  • scene_start_dist (DistributionLike | None) – distribution-like object or callable used to sample starting times for any Event objects applied to the scene. If not provided, will be a uniform distribution between 0 and duration

  • event_start_dist (DistributionLike | None) – distribution-like object used to sample starting (offset) times for Event audio files. If not provided, Event audio files will always start at 0 seconds. Note that this can be overridden by passing a value into Scene.add_event(event_start=…)

  • event_duration_dist (DistributionLike | None) – distribution-like object used to sample Event audio duration times. If not provided, Event audio files will always use their full duration. Note that this can be overridden by passing a value into Scene.add_event(duration=…)

  • event_velocity_dist (DistributionLike | None) – distribution-like object used to sample Event spatial velocities. If not provided, a uniform distribution between 0.5 and 2.0 metres-per-second will be used.

  • event_resolution_dist (DistributionLike | None) – distribution-like object used to sample Event spatial resolutions. If not provided, a uniform distribution between 1.0 and 4.0 Hz (i.e., IRs-per-second) will be used.

  • snr_dist (DistributionLike | None) – distribution-like object used to sample Event signal-to-noise ratios. If not provided, a uniform distribution between 5 and 30 will be used.

  • max_overlap (int | float | complex | integer | floating | None) – the maximum number of overlapping audio Events allowed in the Scene, defaults to 2.

  • event_augmentations (Iterable[Type[EventAugmentation]] | Iterable[tuple[Type[EventAugmentation], dict]] | Type[EventAugmentation] | None) – an iterable of audiblelight.EventAugmentation objects that can be applied to Event objects. The number of augmentations sampled from this list can be controlled by setting the value of augmentations when calling Scene.add_event, i.e. Scene.add_event(augmentations=3) will sample 3 random augmentations from event_augmentations and apply them to the Event.

  • scene_augmentations (Type[SceneAugmentation] | Iterable[Type[SceneAugmentation]] | None) – an iterable of audiblelight.SceneAugmentation objects that will be applied to the entire Scene.

  • state_kwargs (dict | None) – keyword arguments passed to audiblelight.WorldState.

Methods

__init__(duration, mesh_path[, fg_path, ...])

Initializes the Scene with a given duration and mesh.

add_ambience([filepath, noise, channels, ...])

Add ambient noise to the WorldState.

add_emitter(**kwargs)

Add an emitter to the WorldState.

add_emitters(**kwargs)

Add emitters to the WorldState.

add_event([event_type, filepath, alias, ...])

Add an event to the foreground, either "static" or "moving".

add_event_moving([filepath, alias, ...])

Add a moving event to the foreground with optional overrides.

add_event_static([filepath, alias, ...])

Add a static event to the foreground with optional overrides.

add_microphone(**kwargs)

Add a microphone to the WorldState.

add_microphone_and_emitter(**kwargs)

Add both a microphone and emitter with specified relationship.

add_microphones(**kwargs)

Add microphones to the WorldState.

clear_ambience()

Removes all current ambience events.

clear_augmentation(idx)

Clears an augmentation at a given index from the Scene

clear_augmentations()

Removes all augmentations associated with this Scene.

clear_emitter(alias)

Alias for WorldState.clear_emitter.

clear_emitters()

Alias for WorldState.clear_emitters.

clear_event(alias)

Given an alias for an event, clears the event and updates the state.

clear_events()

Removes all current events and emitters from the state

clear_microphone(alias)

Alias for WorldState.clear_microphone.

clear_microphones()

Alias for WorldState.clear_microphones.

from_dict(input_dict)

Instantiate a Scene from a dictionary.

from_json(json_fpath)

Instantiate a Scene from a JSON file.

generate([output_dir, audio, metadata_json, ...])

Render scene to disk.

get_ambience(alias)

Given a valid alias, get an associated ambience event, as in self.ambience[alias]

get_ambiences()

Get all ambience objects, as in self.ambience.values()

get_augmentation(idx)

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

get_augmentations()

Gets all augmentations associated with this Scene.

get_emitter(alias[, emitter_idx])

Alias for WorldState.get_emitter

get_emitters(alias)

Alias for WorldState.get_emitters

get_event(alias_or_idx)

Given a valid alias, get an associated event either by alias (string) or idx (int).

get_events()

Return a list of all events for this scene, as in self.events.values()

get_microphone(alias)

Alias for WorldState.get_microphone

register_augmentation(augmentation)

Alias for Scene.register_augmentations([augmentation]).

register_augmentations(augmentations)

Register augmentations associated with this Scene.

to_dict()

Returns metadata for this object as a dictionary
__eq__(other)#

Compare two Scene objects for equality.

Internally, we convert both objects to a dictionary, and then use the deepdiff package to compare them, with some additional logic to account e.g. for significant digits and values that will always be different (e.g., creation time).

Parameters:

other (Any) – the object to compare the current Scene object against

Returns:

True if the Scene objects are equivalent, False otherwise

Return type:

bool

__getitem__(alias_or_idx)#

An alternative for self.get_event(alias) or `self.events[alias]

Parameters:

alias_or_idx (str | int)

Return type:

Event

__iter__()#

Yields an iterator of Event objects from the current scene

Examples

>>> test_scene = Scene(...)
>>> for n in range(9):
>>>     test_scene.add_event_static(...)
>>> for ev in test_scene:
>>>     assert isinstance(ev, Event)
Return type:

Iterator[Event]

__len__()#

Returns the number of events in the scene

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

add_ambience(filepath=None, noise=None, channels=None, ref_db=None, alias=None, **kwargs)#

Add ambient noise to the WorldState.

The ambience can be either a file on the disk (in which case filepath must not be None) or a type of noise “color” such as white, red, or blue (in which case noise must not be None). The number of channels can be provided directly or will be inferred from the microphones added to the state, when this is possible.

Parameters:

  • channels (int) – the number of channels to generate noise for. If None, will be inferred from available mics.

  • filepath (str or Path) – a path to an audio file on the disk. If None (and noise is None), will try and sample a random audio file from Scene.bg_audios.

  • noise (str) – either the type of noise to generate, e.g. “white”, “red”, or an arbitrary numeric exponent to use when generating noise with powerlaw_psd_gaussian.

  • ref_db (Numeric) – the noise floor, in decibels

  • alias (str) – string reference to refer to this Ambience object inside Scene.ambience

  • kwargs – additional keyword arguments passed to audiblelight.ambience.powerlaw_psd_gaussian

add_emitter(**kwargs)#

Add an emitter to the WorldState.

An alias for WorldState.add_emitter: see that method for a full description.

add_emitters(**kwargs)#

Add emitters to the WorldState.

An alias for WorldState.add_emitters: see that method for a full description.

add_event(event_type='static', filepath=None, alias=None, augmentations=None, position=None, mic=None, polar=False, ensure_direct_path=False, scene_start=None, event_start=None, duration=None, snr=None, class_id=None, class_label=None, shape=None, spatial_resolution=None, spatial_velocity=None)#

Add an event to the foreground, either “static” or “moving”.

Note that the arguments “scene_start”, “event_start”, “duration”, “snr”, “spatial_velocity”, & “spatial_resolution” will (by default) sample from their respective distributions, provided in Scene.__init__. If a numeric value is provided, this will be treated as an override and used instead of random sampling.

Parameters:

  • event_type (str) – the type of event to add, must be either “static” or “moving”

  • filepath (str | Path | None) – a path to a foreground event to use. If not provided, a foreground event will be sampled from fg_category_paths, if this is provided inside __init__; otherwise, an error will be raised.

  • alias (str | None) – the string alias used to index this event inside the events dictionary

  • augmentations (Iterable[Type[EventAugmentation]] | Type[EventAugmentation] | int | float | complex | integer | floating | None) – augmentation objects to associate with the Event. If a list of EventAugmentation objects or a single EventAugmentation object, these will be passed directly. If a number, this many augmentations will be sampled from either Scene.event_augmentations, or a master list of valid augmentations (defined inside audiblelight.augmentations) If not provided, EventAugmentations can be registered later by calling register_augmentations on the Event.

  • position (list | ndarray | None) – Location to add the event. When event_type==”static”, this will be the position of the Event. When event_type==”moving”, this will be the starting position of the Event. When not provided, a random point inside the mesh will be chosen.

  • mic (str | None) – String reference to a microphone inside self.state.microphones; when provided, position is interpreted as RELATIVE to the center of this microphone

  • polar (bool | None) – When True, expects position to be provided in [azimuth, elevation, radius] form; otherwise, units are [x, y, z] in absolute, cartesian terms.

  • ensure_direct_path (bool | list | str | None) – Whether to ensure a direct line exists between the emitter and given microphone(s). If True, will ensure a direct line exists between the emitter and ALL microphone objects. If a list of strings, these should correspond to microphone aliases inside microphones; a direct line will be ensured with all of these microphones. If False, no direct line is required for a emitter.

  • scene_start (int | float | complex | integer | floating | None) – Time to start the Event within the Scene, in seconds. Must be a positive number.

  • event_start (int | float | complex | integer | floating | None) – Time to start the Event audio from, in seconds. Must be a positive number.

  • duration (int | float | complex | integer | floating | None) – Time the Event audio lasts in seconds. Must be a positive number.

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

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

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

  • spatial_velocity (int | float | complex | integer | floating | None) – Speed of a moving sound event in metres-per-second

  • spatial_resolution (int | float | complex | integer | floating | None) – Resolution of a moving sound event in Hz (i.e., number of IRs created per second)

  • shape (str | None) – the shape of a moving event trajectory; must be one of “linear”, “circular”, “random”.

Returns:

the Event object added to the Scene

Return type:

Event

Examples

Creating an event with random sampling of parameters. Here, note that “scene_start”, “event_start”, “duration”, “snr” will be sampled at random from the distributions defined when initialising the Scene.

>>> scene = Scene(...)
>>> scene.add_event(
>>>     event_type="static",
>>>     filepath="some/path.wav"
>>> )

Creating an event with a predefined position:

>>> scene = Scene(...)
>>> scene.add_event(
...     event_type="static",
...     filepath="some/path.wav",
...     alias="tester",
...     position=[-0.5, -0.5, 0.5],
...     polar=False,
...     ensure_direct_path=False
... )

Creating an event with overrides:

>>> scene = Scene(...)
>>> scene.add_event(
...     event_type="moving",
...     filepath="some/path.wav",
...     alias="tester",
...     event_start=5.0,
...     duration=5.0,
...     snr=0.0,
... )
add_event_moving(filepath=None, alias=None, augmentations=None, position=None, mic=None, polar=False, shape=None, scene_start=None, event_start=None, duration=None, snr=None, class_id=None, class_label=None, spatial_resolution=None, spatial_velocity=None)#

Add a moving event to the foreground with optional overrides.

Note that the arguments “scene_start”, “event_start”, “duration”, “snr”, “spatial_velocity”, & “spatial_resolution” will (by default) sample from their respective distributions, provided in Scene.__init__. If a numeric value is provided, this will be treated as an override and used instead of random sampling.

Parameters:

  • filepath (str | Path | None) – a path to a foreground event to use. If not provided, a foreground event will be sampled from fg_category_paths, if this is provided inside __init__; otherwise, an error will be raised.

  • alias (str | None) – the string alias used to index this event inside the events dictionary

  • augmentations (Iterable[Type[EventAugmentation]] | Type[EventAugmentation] | int | float | complex | integer | floating | None) – augmentation objects to associate with the Event. If a list of EventAugmentation objects or a single EventAugmentation object, these will be passed directly. If a number, this many augmentations will be sampled from either Scene.event_augmentations, or a master list of valid augmentations (defined inside audiblelight.augmentations) If not provided, EventAugmentations can be registered later by calling register_augmentations on the Event.

  • position (list | ndarray | None) – Starting point for the event. When not provided, a random point inside the mesh will be chosen.

  • mic (str | None) – String reference to a microphone inside self.state.microphones; when provided, position is interpreted as RELATIVE to the center of this microphone

  • polar (bool | None) – When True, expects position to be provided in [azimuth, elevation, radius] form; otherwise, units are [x, y, z] in absolute, cartesian terms.

  • scene_start (int | float | complex | integer | floating | None) – Time to start the Event within the Scene, in seconds. Must be a positive number.

  • event_start (int | float | complex | integer | floating | None) – Time to start the Event audio from, in seconds. Must be a positive number.

  • duration (int | float | complex | integer | floating | None) – Time the Event audio lasts in seconds. Must be a positive number.

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

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

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

  • spatial_velocity (int | float | complex | integer | floating | None) – Speed of a moving sound event in metres-per-second

  • spatial_resolution (int | float | complex | integer | floating | None) – Resolution of a moving sound event in Hz (i.e., number of IRs created per second)

  • shape (str | None) – the shape of a moving event trajectory; must be one of “linear”, “circular”, “random”.

Returns:

the Event object added to the Scene

Return type:

Event

add_event_static(filepath=None, alias=None, augmentations=None, position=None, mic=None, polar=False, ensure_direct_path=False, scene_start=None, event_start=None, duration=None, snr=None, class_id=None, class_label=None)#

Add a static event to the foreground with optional overrides.

Note that the arguments “scene_start”, “event_start”, “duration”, & “snr” will (by default) sample from their respective distributions, provided in Scene.__init__. If a numeric value is provided, this will be treated as an override and used instead of random sampling.

Parameters:

  • filepath (str | Path | None) – a path to a foreground event to use. If not provided, a foreground event will be sampled from fg_category_paths, if this is provided inside __init__; otherwise, an error will be raised.

  • alias (str | None) – the string alias used to index this event inside the events dictionary

  • augmentations (Iterable[Type[EventAugmentation]] | Type[EventAugmentation] | int | float | complex | integer | floating | None) – augmentation objects to associate with the Event. If a list of EventAugmentation objects or a single EventAugmentation object, these will be passed directly. If a number, this many augmentations will be sampled from either Scene.event_augmentations, or a master list of valid augmentations (defined inside audiblelight.augmentations) If not provided, EventAugmentations can be registered later by calling register_augmentations on the Event.

  • position (list | ndarray | None) – Location to add the event. When not provided, a random point inside the mesh will be chosen.

  • mic (str | None) – String reference to a microphone inside self.state.microphones; when provided, position is interpreted as RELATIVE to the center of this microphone

  • polar (bool | None) – When True, expects position to be provided in [azimuth, elevation, radius] form; otherwise, units are [x, y, z] in absolute, cartesian terms.

  • ensure_direct_path (bool | list | str | None) – Whether to ensure a direct line exists between the emitter and given microphone(s). If True, will ensure a direct line exists between the emitter and ALL microphone objects. If a list of strings, these should correspond to microphone aliases inside microphones; a direct line will be ensured with all of these microphones. If False, no direct line is required for a emitter.

  • scene_start (int | float | complex | integer | floating | None) – Time to start the Event within the Scene, in seconds. Must be a positive number.

  • event_start (int | float | complex | integer | floating | None) – Time to start the Event audio from, in seconds. Must be a positive number.

  • duration (int | float | complex | integer | floating | None) – Time the Event audio lasts in seconds. Must be a positive number.

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

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

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

Returns:

the Event object added to the Scene

Return type:

Event

add_microphone(**kwargs)#

Add a microphone to the WorldState.

An alias for WorldState.add_microphone: see that method for a full description.

Return type:

None

add_microphone_and_emitter(**kwargs)#

Add both a microphone and emitter with specified relationship.

An alias for WorldState.add_microphone_and_emitter: see that method for a full description.

Return type:

None

add_microphones(**kwargs)#

Add microphones to the WorldState.

An alias for WorldState.add_microphones: see that method for a full description.

Return type:

None

clear_ambience()#

Removes all current ambience events.

Return type:

None

clear_augmentation(idx)#

Clears an augmentation at a given index from the Scene

Parameters:

idx (int)

Return type:

None

clear_augmentations()#

Removes all augmentations associated with this Scene.

Return type:

None

clear_emitter(alias)#

Alias for WorldState.clear_emitter.

Parameters:

alias (str)

Return type:

None

clear_emitters()#

Alias for WorldState.clear_emitters.

Return type:

None

clear_event(alias)#

Given an alias for an event, clears the event and updates the state.

Note: simply calling del self.events[alias] is not enough; we also need to remove the source from the ray-tracing engine by updating the state.emitters dictionary and calling state._update.

Parameters:

alias (str)

Return type:

None

clear_events()#

Removes all current events and emitters from the state

Return type:

None

clear_microphone(alias)#

Alias for WorldState.clear_microphone.

Parameters:

alias (str)

Return type:

None

clear_microphones()#

Alias for WorldState.clear_microphones.

Return type:

None

classmethod from_dict(input_dict)#

Instantiate a Scene from a dictionary.

The new Scene will have the same WorldState, Emitters, Events, and Microphones as the original, serialised dictionary created from to_dict. Ensure that any necessary files (e.g. meshes, audio files) are located in the same places as specified in the dictionary.

Note that, currently, distribution objects (e.g., Scene.event_start_dist) cannot be loaded from a dictionary.

Parameters:

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

Returns:

Scene instance.

classmethod from_json(json_fpath)#

Instantiate a Scene from a JSON file.

Parameters:

json_fpath (str | Path) – Path to the JSON file to load.

Returns:

Scene instance.

generate(output_dir=None, audio=True, metadata_json=True, metadata_dcase=True, audio_fname='audio_out', metadata_fname='metadata_out')#

Render scene to disk. Currently only audio and metadata are rendered.

Parameters:

  • output_dir (str | Path | None) – directory to save the output, defaults to a temp directory inside AudibleLight/spatial_scenes

  • audio (bool) – whether to save audio as an output, default to True

  • metadata_json (bool) – whether to save metadata JSON file, default to True

  • metadata_dcase (bool) – whether to save metadata CSVs in DCASE format, default to True

  • audio_fname (str | Path | None) – name to use for the output audio file, default to “audio_out”

  • metadata_fname (str | Path | None) – name to use for the output metadata, default to “metadata_out”

Returns:

None

Return type:

None

get_ambience(alias)#

Given a valid alias, get an associated ambience event, as in self.ambience[alias]

Return type:

Ambience

get_ambiences()#

Get all ambience objects, as in self.ambience.values()

Return type:

list[Ambience]

get_augmentation(idx)#

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

Parameters:

idx (int)

Return type:

Type[SceneAugmentation]

get_augmentations()#

Gets all augmentations associated with this Scene.

Return type:

list[Type[EventAugmentation]]

get_emitter(alias, emitter_idx=0)#

Alias for WorldState.get_emitter

Parameters:

  • alias (str)

  • emitter_idx (int)

Return type:

Emitter

get_emitters(alias)#

Alias for WorldState.get_emitters

Parameters:

alias (str)

Return type:

list[Emitter]

get_event(alias_or_idx)#

Given a valid alias, get an associated event either by alias (string) or idx (int).

Parameters:

alias_or_idx (str | int)

Return type:

Event

get_events()#

Return a list of all events for this scene, as in self.events.values()

Return type:

list[Event]

get_microphone(alias)#

Alias for WorldState.get_microphone

Parameters:

alias (str)

Return type:

Type[MicArray]

register_augmentation(augmentation)#

Alias for Scene.register_augmentations([augmentation]).

Parameters:

augmentation (Type[SceneAugmentation])

Return type:

None

register_augmentations(augmentations)#

Register augmentations associated with this Scene.

Parameters:

augmentations (Iterable[Type[SceneAugmentation]]) – Iterable of augmentations to register

Returns:

None

Return type:

None

to_dict()#

Returns metadata for this object as a dictionary

Return type:

dict

Contents