treble_tsdk.scene.scene_generator

Classes

GroupPriority	Priority of a SourceGroup when planning IR selection.
PlannedSceneConfig	A feasible receiver/simulation combination with a per-group IR plan.
SceneGenerationSettings	Everything a SceneGenerator.generate_scenes() call needed to produce a collection.
SceneGenerator	Generates AudioScene instances from an IR collection and SceneRules.
SceneRules	Top-level configuration describing how to generate a scene or scenes.
SourceGroup	A group of related audio sources.

class treble_tsdk.scene.scene_generator.GroupPriority

Priority of a SourceGroup when planning IR selection.

Source groups are sorted by priority (descending) before sources/IRs are assigned, so higher-priority groups get first pick of IRs and are less likely to be starved when groups compete for the same IR pool.

HIGH = 3

LOW = 1

MEDIUM = 2

NONE = 0

class treble_tsdk.scene.scene_generator.PlannedSceneConfig

A feasible receiver/simulation combination with a per-group IR plan.

Parameters:

• receiver_id – The id of the receiver used for this configuration.

• simulation_id – The id of the simulation used for this configuration.

• group_plans – The selected IR ids for each source group, keyed by group name.

__init__(receiver_id: str, simulation_id: str, group_plans: dict[str, list[str]]) → None

group_plans: dict[str, list[str]]

receiver_id: str

simulation_id: str

class treble_tsdk.scene.scene_generator.SceneGenerationSettings

Everything a SceneGenerator.generate_scenes() call needed to produce a collection.

Parameters:

• ir_collection (IRCollection) – The IR collection generation drew from.

• scene_rules (SceneRules) – The rules generation followed.

• max_n_scenes (int) – Target number of scenes, as requested by the caller.

• data_loader (IRDataLoader) – The data loader shared with the generated collection.

• max_attempts (int) – Maximum generation attempts, resolved to its effective value.

• random_seed (int) – The seed used.

• allow_config_reuse (bool) – Whether a scene configuration could be reused across scenes.

__init__(ir_collection: IRCollection, scene_rules: SceneRules, max_n_scenes: int, data_loader: IRDataLoader | None = None, max_attempts: int | None = None, random_seed: int | None = None, allow_config_reuse: bool = True) → None

generate() → SceneCollection

Run generation again with these settings.

Returns:

A newly generated SceneCollection, carrying these settings in turn.

with_listener_device(device: DeviceObj | None, orientation: Rotation | OrientationRange | None = None, device_specs: DeviceSpecs | None = None) → SceneGenerationSettings

Copy these settings with the listener device of the scene rules replaced.

Neither these settings nor their SceneRules are modified.

Parameters:

• device – The device the listener should use, or None to render it in mono.

• orientation – The listener orientation to pair with device. The current orientation is kept when None.

• device_specs – The microphone noise/filter specs to pair with device. The current specs are kept when None.

Returns:

A new SceneGenerationSettings with the new listener rules.

allow_config_reuse: bool = True

data_loader: IRDataLoader | None = None

ir_collection: IRCollection

max_attempts: int | None = None

max_n_scenes: int

random_seed: int | None = None

scene_rules: SceneRules

class treble_tsdk.scene.scene_generator.SceneGenerator

Generates AudioScene instances from an IR collection and SceneRules.

Given an IRCollection and scene rules (source groups, listener rules, duration), samples receivers, simulations, sources, IRs, tracks, and listener orientation to build one scene at a time (generate_scene()) or a batch (generate_scenes()).

__init__(ir_collection: IRCollection, scene_rules: SceneRules, data_loader: IRDataLoader | str | Path = None)

Parameters:

• ir_collection – The IR collection to draw sources/receivers from.

• scene_rules – The SceneRules describing source groups, listener configuration, and scene duration.

• data_loader – Data loader, or a root directory to build one.

generate_scene(duration_s: float | tuple | None = None, random_seed: int | None = None) → AudioScene

Generate a single scene according to the scene rules.

Parameters:

• duration_s – Scene duration in seconds. Sampled from the rules’ duration distribution when None.

• random_seed – Seed for reproducible sampling. A random seed is drawn when None.

Returns:

The generated AudioScene.

generate_scenes(max_n_scenes: int, max_attempts: int | None = None, random_seed: int | None = None, generate_logs: bool = False, allow_config_reuse: bool = True) → SceneCollection | tuple[SceneCollection, SceneGenerationLog]

Generate a collection of scenes according to the scene rules.

Parameters:

• max_n_scenes – Target number of scenes to generate.

• max_attempts – Maximum generation attempts before giving up. Defaults to 40 * max_n_scenes.

• random_seed – Seed for reproducible sampling. A random seed is drawn when None.

• generate_logs – If True, collect a SceneGenerationLog and return it alongside the collection.

• allow_config_reuse – If True, each scene randomly draws from the full pool of planned configurations, so a configuration may be reused across scenes. If False, planned configurations are consumed in order without reuse, and generation stops once they run out even if max_n_scenes has not been reached.

Returns:

The generated SceneCollection, or a (SceneCollection, SceneGenerationLog) tuple when generate_logs is True. May contain fewer than max_n_scenes scenes if max_attempts is exhausted first, or if allow_config_reuse is False and configs run out first.

class treble_tsdk.scene.scene_generator.SceneRules

Top-level configuration describing how to generate a scene or scenes.

Parameters:

• duration_s (float | tuple[float, float] | Uniform | ScaledBeta) – Scene duration in seconds. A tuple is converted to a Uniform (min, max) via tuple_to_distribution in __post_init__; a Uniform or ScaledBeta is used as-is. Sampled once per generated scene unless overridden.

• source_groups (list[SourceGroup]) – The source groups in the scene.

• listener_rules (ListenerRules) – Listener configuration (receiver selection, device, orientation) for the scene. Defaults to a default ListenerRules (mono rendering, no receiver filtering).

• target_snr (float | tuple[float, float] | Uniform | ScaledBeta) – Optional target SNR in dB. A tuple (min, max) or a distribution is sampled once per scene. The value is stored in the scene metadata as "target_snr" and applied by SceneCollection.render() or SceneCollection.render_to_disk() when a target_selection is given. When None, the SNR follows from the individual source levels.

• split_device_sources (bool) – If True, every source device in the IR collection is split into its source layers, and each layer is a separate source with its own IRs. Use the name of the source layer to group those sources e.g., pl.col("source_label").contains("woofer"). If False (default), a device source is a single source whose layers are summed into one IR.

__init__(duration_s: tuple[float, float] | ~treble_tsdk.collections.distributions.Uniform | ~treble_tsdk.collections.distributions.ScaledBeta, source_groups: list[~treble_tsdk.scene.scene_generator.SourceGroup] = <factory>, listener_rules: ~treble_tsdk.scene.scene_listener.ListenerRules = <factory>, target_snr: float | tuple[float, float] | ~treble_tsdk.collections.distributions.Uniform | ~treble_tsdk.collections.distributions.ScaledBeta | None = None, split_device_sources: bool = False) → None

add_source_group(source_group: SourceGroup) → None

Append a source group to the scene rules.

Parameters:

source_group – The SourceGroup to add.

set_listener(rules: ListenerRules) → None

Set the listener rules for the scene.

Parameters:

rules – The ListenerRules to use.

validate_required_fields() → None

Validate that the scene rules have the required fields set.

duration_s: tuple[float, float] | Uniform | ScaledBeta

listener_rules: ListenerRules

source_groups: list[SourceGroup]

split_device_sources: bool = False

target_snr: float | tuple[float, float] | Uniform | ScaledBeta | None = None

class treble_tsdk.scene.scene_generator.SourceGroup

A group of related audio sources.

Parameters:

• name (str) – The name of the group.

• tracks (TrackGenerator | list[AudioTrack] | list[RepeatedAudioTrack] | list[StaticNoiseTrack]) – The tracks generator or list of tracks to generate.

• source_selection (pl.Expr) – Polars expression filtering the IR collection (Optional).

• n_sources (int) – Number of sources to sample from the IR collection. If None, determined automatically from the number of available IRs (Optional).

• min_n_sources (int) – Minimum number of sources the group must get (Optional).

• duration_s (float | tuple[float, float]) – Duration of the group (Optional). If None, derived from the global duration_s passed to SceneGenerator.generate_scene().

• start_time_s (float | tuple[float, float] | Uniform | ScaledBeta) – Start time of the group, in seconds; defaults to 0.0. A tuple (min, max) or a distribution samples a random start time per generated scene.

• sample_ir_with_replacement (bool) – If False, each IR can be selected only once.

• priority_on_ir_collection (GroupPriority) – Prioritizes source groups on the IR collection, then by presence of an IR filter; higher priority wins.

• group_tag (GroupTag) – The tag of the group.

• automation (Automation) – Optional source automation applied to every TrackMap generated for this group.

__init__(name: str, tracks: TrackGenerator | list[AudioTrack] | list[RepeatedAudioTrack] | list[StaticNoiseTrack], source_selection: pl.Expr | None = None, n_sources: int = None, min_n_sources: int = 0, duration_s: tuple[float, float] | Uniform | ScaledBeta | None = None, start_time_s: tuple[float, float] | Uniform | ScaledBeta | None = None, sample_ir_with_replacement: bool = False, priority_on_ir_collection: GroupPriority = GroupPriority.NONE, group_tag: GroupTag | None = None, automation: Automation | None = None) → None

automation: Automation | None = None

duration_s: tuple[float, float] | Uniform | ScaledBeta | None = None

group_tag: GroupTag | None = None

min_n_sources: int = 0

n_sources: int = None

name: str

priority_on_ir_collection: GroupPriority = 0

sample_ir_with_replacement: bool = False

source_selection: pl.Expr | None = None

start_time_s: tuple[float, float] | Uniform | ScaledBeta | None = None

tracks: TrackGenerator | list[AudioTrack] | list[RepeatedAudioTrack] | list[StaticNoiseTrack]