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.

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.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).

__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>) → 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]
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]