treble_tsdk.scene.scene_listener

Classes

Automation

Moving-listener automation: dynamic position and/or orientation for receiver motion rendering.

DeviceSpecs

Device microphone properties for static noise and frequency response.

ListenerRules

A group of listeners that are related to each other.

NoiseGenerator

Per-channel noise level specification.

OrientationRange

Per-angle sampling range that resolves to a static rotation per scene.

SceneListener

A single, fully-resolved listener within a scene (receiver + device + orientation + optional filtering/noise/automation), as opposed to ListenerRules, which describes rules shared across a group of listeners.
class treble_tsdk.scene.scene_listener.Automation

Moving-listener automation: dynamic position and/or orientation for receiver motion rendering.

Parameters:

  • position (DynamicPosition | None) – Optional dynamic position over time.

  • orientation (DynamicOrientation | None) – Optional dynamic orientation over time. When set on a SceneListener’s automation, this takes precedence over that listener’s own orientation field.

__init__(position: DynamicPosition | None = None, orientation: DynamicOrientation | None = None) → None
classmethod from_struct(struct: dict | None) → Automation | None

Reconstruct an Automation from its serialized struct.

Parameters:

struct (dict | None) – Struct as produced by to_struct().

Return Automation | None:

The reconstructed instance, or None if struct is None.

to_struct() → dict

Serialize to a plain dict.

Return dict:

Struct with position and orientation, each None or the nested object’s own to_struct() output.

orientation: DynamicOrientation | None = None
position: DynamicPosition | None = None
class treble_tsdk.scene.scene_listener.DeviceSpecs

Device microphone properties for static noise and frequency response.

Applies regardless of whether a device is set on the owning ListenerRules: with no device, the receiver renders as a single mono channel, and noise_rules/filter_definitions still apply to that one channel exactly as they would to a device’s channels. This is the receiver-side counterpart to TrackGenerator.filter_definitions (a source-side filter scoped to one source group’s own content): this one applies uniformly, once per track, inside AudioScene.render() to every track in the scene, regardless of which source group produced it.

Parameters:

  • noise_rules (StaticNoiseRules) – Noise profile and behavior for this device or microphone. See StaticNoiseRules for details.

  • filter_definitions (list[list[FilterDefinition]]) – One filter list per device/microphone channel. A bare (non-list) value is wrapped into a one-element list in __post_init__, but a flat list[FilterDefinition] is not re-nested into per-channel sublists — it applies that same chain uniformly across every channel. Nest explicitly ([[filter_a], [filter_b]]) for genuinely different filters per channel.

__init__(noise_rules: StaticNoiseRules = None, filter_definitions: list[list['FilterDefinition']] = None) → None
filter_definitions: list[list['FilterDefinition']] = None
noise_rules: StaticNoiseRules = None
class treble_tsdk.scene.scene_listener.ListenerRules

A group of listeners that are related to each other.

Parameters:

  • device (DeviceObj) – The device for the listener.

  • orientation (Rotation | DynamicOrientation | ActiveTalkerFollowOrientation | OrientationRange) – The listener orientation: a static rotation, a dynamic orientation, a dynamic rule that follows the active talker in a source group, or a per-angle sampling range that resolves to a static rotation per scene.

  • device_specs (DeviceSpecs) – Device specifications for static noise generation and microphone response.

  • receiver_selection (pl.Expr) – A polars expression to filter receivers (optional). Must be a polars.Expr if given.

  • automation (Automation) – Optional listener automation. Use this to provide moving-listener position and/or dynamic orientation for receiver motion rendering.

device and orientation must be set together — neither is allowed without the other. orientation cannot be an ActiveTalkerFollowOrientation or DynamicOrientation: this check is unconditional, rejecting both types regardless of whether the receiver actually moves (not only for moving receivers, as the error message implies) — it’s forward-looking code gated on general moving-receiver support landing, not on this specific case. automation is not yet supported for moving receivers and must be None.

__init__(device: DeviceObj | None = None, orientation: Rotation | DynamicOrientation | ActiveTalkerFollowOrientation | OrientationRange | None = None, device_specs: DeviceSpecs | None = None, receiver_selection: pl.Expr | None = None, automation: Automation | None = None) → None
automation: Automation | None = None
device: DeviceObj | None = None
device_specs: DeviceSpecs | None = None
orientation: Rotation | DynamicOrientation | ActiveTalkerFollowOrientation | OrientationRange | None = None
receiver_selection: pl.Expr | None = None
class treble_tsdk.scene.scene_listener.NoiseGenerator

Per-channel noise level specification.

Parameters:

  • noise_type (str) – Identifier for the kind of noise to generate.

  • noise_level_db_spl (float | list[float]) – Noise level in dB SPL, either a single value applied to all channels or a list with one value per channel.

  • n_channels (int) – Number of channels. Required to broadcast a scalar noise_level_db_spl or to validate a per-channel list.

  • seed (int | None) – Optional random seed.

__init__(noise_type: str, noise_level_db_spl: float | list[float], n_channels: int, seed: int | None = None)
class treble_tsdk.scene.scene_listener.OrientationRange

Per-angle sampling range that resolves to a static rotation per scene.

Each range is converted to a distribution (Uniform by default, or the given Uniform/ScaledBeta) in __post_init__ and validated against the physical bounds for that angle.

Parameters:
__init__(azimuth_range: tuple[float, float] | Uniform | ScaledBeta, elevation_range: tuple[float, float] | Uniform | ScaledBeta, roll_range: tuple[float, float] | Uniform | ScaledBeta) → None
classmethod from_struct(struct: dict | None) → OrientationRange | None

Reconstruct an OrientationRange from its serialized struct.

Parameters:

struct (dict | None) – Struct as produced by to_struct().

Return OrientationRange | None:

The reconstructed instance, or None if struct is not a dict or its mode is not "orientation_range".

to_dict() → dict

Alias for to_struct().

Return dict:

Same as to_struct().

to_struct() → dict

Serialize to a plain dict, tagged with mode: "orientation_range".

Return dict:

Struct with mode, azimuth_range, elevation_range, and roll_range as [low, high] lists.

azimuth_range: tuple[float, float] | Uniform | ScaledBeta
elevation_range: tuple[float, float] | Uniform | ScaledBeta
roll_range: tuple[float, float] | Uniform | ScaledBeta
class treble_tsdk.scene.scene_listener.SceneListener

A single, fully-resolved listener within a scene (receiver + device + orientation + optional filtering/noise/automation), as opposed to ListenerRules, which describes rules shared across a group of listeners.

Parameters:

  • receiver (Receiver) – The receiver this listener is attached to.

  • device (DeviceObj | None) – The device/microphone array used for rendering. If None, rendering is done in mono mode.

  • orientation (Rotation | DynamicOrientation | None) – Static or dynamic listener orientation. If automation.orientation is also set, it wins and overwrites this field in __post_init__ (with a warning if both were explicitly provided).

  • filter_definitions (list[FilterDefinition]) – Optional per-channel filters applied at rendering time.

  • noise_definitions (list[StaticNoiseTrack] | StaticNoiseTrack | None) – Static noise track(s) to add per microphone channel. A single track, or a list with one entry, is broadcast to all device channels. A list with more than one entry must have exactly one entry per device microphone; if device is None in that case, only the first noise definition is used (with a warning).

  • automation (Automation | None) – Optional moving-listener position and/or dynamic orientation for receiver motion rendering.

__init__(receiver: Receiver, device: DeviceObj | None = None, orientation: Rotation | DynamicOrientation | None = None, filter_definitions: list['FilterDefinition'] = None, noise_definitions: list[StaticNoiseTrack] | StaticNoiseTrack | None = None, automation: Automation | None = None) → None
classmethod from_struct(struct: dict, receiver=None, device=None) → SceneListener

Reconstruct a SceneListener from its serialized struct.

Parameters:

  • struct (dict) – Struct as produced by to_struct(). For backward compatibility, a legacy top-level position key (with no automation) is treated as automation.position.

  • receiver – Receiver to attach; if None, a lightweight stand-in object exposing id and label from the struct is used instead.

  • device – Device to attach. Not resolved from the struct; the caller must supply the actual device object.

Return SceneListener:

The reconstructed instance.

to_struct() → dict

Serialize this listener to a plain dict.

Return dict:

Struct with receiver, device (id/name/channel labels), orientation, filter_definitions, noise_definitions, and automation.

automation: Automation | None = None
device: DeviceObj | None = None
filter_definitions: list['FilterDefinition'] = None
noise_definitions: list[StaticNoiseTrack] | StaticNoiseTrack | None = None
orientation: Rotation | DynamicOrientation | None = None
receiver: Receiver