treble_tsdk.scene.scene

Functions

`is_moving`(ir_info)	Check if the IR info represents a moving source or receiver.
`is_moving_receiver`(ir_info)	Check if the IR info has a moving receiver.
`is_moving_source`(ir_info)	Check if the IR info has a moving source.
`is_processed_ir`(ir_info)	Check if the IR info is processed.

Classes

`AudioScene`	A renderable audio scene: tracks mapped to impulse responses, plus a scene listener and duration.
`GroupTag`	Predefined track tags for categorizing audio sources.
`IRSegment`	An impulse response paired with the time range it applies to.
`RenderMode`	How to obtain the impulse response used to render a track in `AudioScene.render()`.
`TargetRenderMode`	How to render a single isolated track in `AudioScene.render_target()`.
`TrackMap`	Pairs an audio track with the impulse response and metadata used to render it.
`TrackSummary`	Lightweight, read-only summary of a track in an `AudioScene`.
`WetDeviceWindowed`	Render wet device IR with onset-based windowing to crop late reverb.
`WetMonoWindowed`	Render wet mono IR with onset-based windowing to crop late reverb.

class treble_tsdk.scene.scene.AudioScene

A renderable audio scene: tracks mapped to impulse responses, plus a scene listener and duration.

Each entry in track_map pairs a dry audio track with the impulse response (and automation/tag/group metadata) used to render it into the scene. Use render() to render and mix all tracks (plus any listener device noise) into the final scene signal, or render_target() to render/isolate one or more specific tracks (e.g. a clean target signal for SNR estimation).

Parameters:

track_map – The tracks making up the scene. Defaults to an empty list.
scene_listener – The listener (position, orientation, device, noise, filters) through which the scene is rendered.
duration_s – Explicit scene duration in seconds. If None, derived from the tracks when needed (see _get_duration_s()).
data_loader – Loader used to fetch IR data on demand.
metadata – Arbitrary metadata to store alongside the scene.

add_track(track_map: TrackMap)

Append a track to the scene.

Parameters:: track_map – The track (and its IR/tag/automation/group) to add.

get_model() → ModelObj | None

Get the model shared by all tracks’ simulations.

Returns:: The single distinct ModelObj used across all tracks’ IRs, or None if no track has an associated simulation.

get_simulation() → Simulation | None

Get the simulation shared by all tracks.

Returns:: The single distinct Simulation used across all tracks’ IRs, or None if no track has an associated simulation.

get_source_group_names() → list[str]

Get the distinct source group names used in the scene.

Returns:: The (possibly duplicated, in track order) group names of all tracks that have one set.

get_track_indices_by_group_name(group_name: str) → list[int]

Get the indices of tracks belonging to the given source group.

Parameters:: group_name – The source group name to filter by.
Returns:: Indices into track_map of matching tracks.

get_track_indices_by_tag(tag: GroupTag) → list[int]

Get the indices of tracks with the given tag.

Parameters:: tag – The GroupTag to filter by.
Returns:: Indices into track_map of matching tracks (possibly empty).

plot(height: int = 650)

Display an interactive visualization of the audio scene.

Parameters:: height – Height of the visualization in pixels. Defaults to 650.

predict_snr(target_selection: int | str | list[int]) → float | None

Estimate the SNR of this scene for a given target.

Fast, metadata-only prediction computed from per-band octave SPL values already attached to the source samples and IRs, without rendering or convolving any audio. Not a substitute for measuring SNR from actually rendered audio (see estimate_snr(), used when calculate_snr=True is passed to a render call); documented accuracy against that measured ground truth is roughly -0.2 dB mean error with a 1.5 dB standard deviation. Device noise is taken from the scene listener, when one is set.

Further accuracy limits: computed for a single (mono) channel only, never the true multi-channel signal an actual device would capture; does not model the device’s own transfer function/HRTF at all (it does fold in SceneListener.filter_definitions, but only as one uniform per-band gain applied equally to every track, not a real per-channel response); and when the listener has more than one device microphone, each microphone’s noise profile/level is averaged into a single channel before being added as noise power.

Requires per-band SPL metadata to already be attached: call enrich_with_acoustic_parameters() once on the IR collection this scene’s tracks were built from, and enrich_with_spl() on every AudioDataset feeding a track in the scene (the target’s and any noise track’s alike) before generating those tracks — not merely before calling this method. Each track’s samples are frozen AudioSampleReference snapshots captured at generation time, so enriching the dataset afterward does not retroactively add the spl metadata this estimate needs.

Parameters:: target_selection – Track index, source group name, or list of track indices designating the target.
Returns:: The SNR of the scene in dB, or None when it cannot be estimated.

predict_snr_breakdown(target_selection: int | str | list[int]) → SNRBreakdown | None

Estimate the SNR of this scene together with the target and noise levels.

Same computation as predict_snr() (and same prerequisites/accuracy caveats — see there), but also returns the predicted target and noise levels (in dB) alongside the SNR. Device noise is taken from the scene listener, when one is set.

Parameters:: target_selection – Track index, source group name, or list of track indices designating the target.
Returns:: An SNRBreakdown, or None when SNR cannot be estimated.

render(sampling_rate: float, render_mode: RenderMode = RenderMode.AUTO, output_separated_tracks: bool = False, show_progress: bool = True) → tuple['AudioSignal', dict[str, 'AudioSignal']] | 'AudioSignal'

Render and mix all tracks in the scene into the final scene signal.

Renders each track in track_map (convolving with its IR per render_mode, applying listener filters when not already baked into the IR), mixes in listener device noise when scene_listener.noise_definitions is set, broadcasts mono signals up to the maximum channel count found across tracks (e.g. mixing dry mono tracks with device-rendered multi-channel tracks), and sums everything into a single output signal.

Parameters:

sampling_rate – The sampling rate to render at, in Hz.
render_mode – How to obtain the IR for each track. See RenderMode.
output_separated_tracks – If True, also return a dict mapping each track’s (source label, track index) (source label is "" when the track has no IR) to its individually rendered signal, plus "listener_noise" when device noise was mixed in.
show_progress – Whether to show progress bars while rendering.

Returns:

The mixed scene signal, or a (mixed_signal, separated_tracks) tuple when output_separated_tracks is True.

render_target(target_selection: int | str | list[int], sampling_rate: float, render_mode: TargetRenderMode | WetMonoWindowed | WetDeviceWindowed = TargetRenderMode.WET_MONO, show_progress: bool = True) → AudioSignal

Render target track/s by track index or group name.

Parameters:

target_selection – Which track(s) to render: a track index, a list of track indices, or a source group name. For a group name or index list, each matching track is rendered and the results are summed.
sampling_rate – The sampling rate to render the track at.
render_mode – The render mode to use.
show_progress – Whether to show a progress bar.

Returns:

The rendered target track/s.

set_data_loader(data_loader: IRDataLoader)

Set the loader used to fetch IR data on demand.

Parameters:: data_loader – The data loader to use.

to_struct() → dict

Serialize this scene to a plain-dict representation.

Returns:: A JSON-serializable dictionary with the track map, listener, duration, metadata, and id.

transcript(target_selection: int | str | list[int] | None = None) → list[str]

Build a time-ordered transcript of spoken audio blocks in the scene.

Only AudioTrack blocks contribute transcript entries; RepeatedAudioTrack and StaticNoiseTrack tracks have no transcript blocks and are silently skipped.

Parameters:: target_selection – If given, restrict the transcript to these tracks: a track index, a source group name, or a list of track indices; otherwise include all tracks.
Returns:: One line per audio block, of the form "{start_time}s: Track: {track.id}: {transcript}", sorted by start time with ties broken by track id. Blocks sharing a start time each get their own line.

property track_info: list[TrackSummary]: A read-only summary (TrackSummary) of every track in the scene.

property track_map: tuple[TrackMap, ...]: The tracks making up the scene, in render order.

class treble_tsdk.scene.scene.GroupTag

Predefined track tags for categorizing audio sources.

static resolve_track_tag(tag: GroupTag | str) → str: Convert GroupTag enum or string to string value.

BACKGROUND = 'background'

DISTRACTOR = 'distractor'

JAMMER = 'jammer'

NOISE = 'noise'

TARGET = 'target'

class treble_tsdk.scene.scene.IRSegment

An impulse response paired with the time range it applies to.

Parameters:

time_range – (t_start, t_end) in seconds describing the window during which this IR applies.
ir – The impulse response to convolve with the audio in this segment.

__init__(time_range: tuple[float, float], ir: DeviceIR | SpatialIR | MonoIR) → None

ir: DeviceIR | SpatialIR | MonoIR

time_range: tuple[float, float]

class treble_tsdk.scene.scene.RenderMode

How to obtain the impulse response used to render a track in AudioScene.render().

AUTO: Device IR if the scene listener has a device set, otherwise mono.
NONE: No IR rendering; the track’s dry signal is used as-is.
MONO: Convolve with the simulated mono IR.
SPATIAL: Convolve with the simulated spatial IR.
DEVICE: Convolve with the simulated device IR; requires a device on the scene listener.

AUTO = 'auto'

DEVICE = 'device'

MONO = 'mono'

NONE = 'none'

SPATIAL = 'spatial'

class treble_tsdk.scene.scene.TargetRenderMode

How to render a single isolated track in AudioScene.render_target().

DRY_MONO: Raw track audio, no impulse response applied.
FREE_FIELD_DEVICE: Synthetic monopole IR from device geometry only (free-field propagation and microphone layout), no room acoustics.
WET_MONO: Convolved with the simulated mono impulse response.
WET_DEVICE: Convolved with the simulated device impulse response.

DRY_MONO = 'dry_mono'

FREE_FIELD_DEVICE = 'dry_device'

WET_DEVICE = 'wet_device'

WET_MONO = 'wet_mono'

class treble_tsdk.scene.scene.TrackMap

Pairs an audio track with the impulse response and metadata used to render it.

Parameters:

track – The audio track providing the dry signal to render.
ir – The IR info describing the simulated source/receiver pair to convolve the track with, or None to render the track dry.
tag – Optional GroupTag used to categorize the track (e.g. target, jammer, noise).
automation – Optional position automation for a moving source or receiver associated with this track. Orientation automation is not supported here.
group_name – Optional name grouping this track with others under a common source group.

For post-analysis of a generated scene, ir/track carry everything needed to answer “what was actually in this scene” without re-deriving it from rendered audio. ir.dataframe_row is the full IR-collection row (including any custom add_column()/ add_column() enrichment) as it stood when the scene was built; ir.source/ir.receiver/ir.simulation give the underlying geometry and simulation objects. track’s available fields depend on its concrete type: AudioTrack holds a list of AudioBlock (iterate .audio_blocks; don’t assume one block per track), while RepeatedAudioTrack/ StaticNoiseTrack are single-occurrence. Branch with isinstance, not hasattr: the three types don’t share an attribute surface.

__init__(track: AudioTrack | RepeatedAudioTrack | StaticNoiseTrack, ir: IRInfo | tuple | None, tag: GroupTag | None, automation: Automation | None = None, group_name: str | None = None) → None

classmethod from_struct(struct: dict[str, Any], ir: IRInfo | None = None) → TrackMap

Deserialize a TrackMap from the dict produced by to_struct().

Parameters:

struct – The serialized track map dictionary (as returned by to_struct()).
ir – The IR info to associate with the resulting track map, since IR info is not fully reconstructed from the serialized struct.

Returns:

The reconstructed TrackMap.

to_struct(track_index: int) → dict

Serialize this track map to a plain-dict representation.

Serializes the track, IR reference, tag, automation, and group name. Special case: when the IR’s source is a moving directive source, the position automation’s per-position distances are used to interpolate azimuth/elevation/roll into a baked orientation track (via interpolate_angles()), since directive source orientation must follow the trajectory rather than being set independently.

Parameters:: track_index – This track’s position within the owning scene’s track_map list. Used to build a track_id that stays unique even when multiple tracks share the same source.
Returns:: A JSON-serializable dictionary representation.

automation: Automation | None = None

group_name: str | None = None

ir: IRInfo | tuple | None

tag: GroupTag | None

track: AudioTrack | RepeatedAudioTrack | StaticNoiseTrack

class treble_tsdk.scene.scene.TrackSummary

Lightweight, read-only summary of a track in an AudioScene.

Parameters:

index – The track’s index within AudioScene.track_map.
tag – The track’s GroupTag, if any.
group_name – The track’s source group name, if any.
track_type – The class name of the underlying track, e.g. "AudioTrack" or "RepeatedAudioTrack".

__init__(index: int, tag: GroupTag | None, group_name: str | None, track_type: str) → None

group_name: str | None

tag: GroupTag | None

track_type: str

class treble_tsdk.scene.scene.WetDeviceWindowed

Render wet device IR with onset-based windowing to crop late reverb.

Parameters:

onset_threshold_db – Level, in dB below the IR peak, used to detect the onset sample.
window_duration – Seconds of signal to keep after the detected onset.
fadeout_duration – Seconds over which a Hanning fadeout is applied at the end of the window.

__init__(onset_threshold_db: float = -20, window_duration: float = 0.05, fadeout_duration: float = 0.01) → None

fadeout_duration: float = 0.01

onset_threshold_db: float = -20

property value: str: String key identifying this render recipe, including the windowing parameters.

window_duration: float = 0.05

class treble_tsdk.scene.scene.WetMonoWindowed

Render wet mono IR with onset-based windowing to crop late reverb.

Parameters:

onset_threshold_db – Level, in dB below the IR peak, used to detect the onset sample.
window_duration – Seconds of signal to keep after the detected onset.
fadeout_duration – Seconds over which a Hanning fadeout is applied at the end of the window.

__init__(onset_threshold_db: float = -20, window_duration: float = 0.05, fadeout_duration: float = 0.01) → None

fadeout_duration: float = 0.01

onset_threshold_db: float = -20

property value: str: String key identifying this render recipe, including the windowing parameters.

window_duration: float = 0.05

treble_tsdk.scene.scene.is_moving(ir_info: IRInfo) → bool

Check if the IR info represents a moving source or receiver.

Parameters:: ir_info – The IR info to check.
Returns:: True if either the source or the receiver is moving.

treble_tsdk.scene.scene.is_moving_receiver(ir_info: IRInfo) → bool

Check if the IR info has a moving receiver.

Parameters:: ir_info – The IR info to check.
Returns:: True if the receiver type is moving.

treble_tsdk.scene.scene.is_moving_source(ir_info: IRInfo) → bool

Check if the IR info has a moving source.

Parameters:: ir_info – The IR info to check.
Returns:: True if the source type is moving.

treble_tsdk.scene.scene.is_processed_ir(ir_info: IRInfo) → bool

Check if the IR info is processed.

Parameters:: ir_info – The IR info to check.
Returns:: True if the IR has valid processing info.