treble_tsdk.scene.track_generator

Classes

`ConversationRules`	Rules controlling conversational timing/overlap when generating tracks.
`NoiseSourceRules`	Rules controlling repeated-noise track generation.
`SamplesPerTalker`	Per-talker sampling mode once a talker's candidate samples are exhausted.
`StaticNoiseRules`	Rules controlling static device/mic noise generation.
`TrackGenerator`	Generates audio tracks for a scene from an AudioDataset, driven by a set of rules.
`TransientNoiseRules`	Rules controlling transient/one-shot noise-event track generation (e.g. a car passing, a bird call, a door slam): each generated track is assigned a single sample from the dataset, which is then placed at one or more non-overlapping, randomly chosen moments within the scene duration.

class treble_tsdk.scene.track_generator.ConversationRules

Rules controlling conversational timing/overlap when generating tracks.

Requires the driving AudioDataset to have a length_s column: candidate-sample filtering against block_duration_range queries that column directly, rather than decoding audio to measure duration. Works best with short clips (seconds, not minutes): each candidate sample becomes one block on a talker’s timeline, so a dataset of long recordings still loads and generates without error, but yields only one or two blocks per talker for the whole scene, leaving little room for the turn-taking/overlap mechanics below to do anything.

Parameters:

block_duration_range (tuple[float, float]) – (min_s, max_s) duration range for candidate audio blocks.
in_track_level_range_db_spl (tuple[float, float] | Uniform | ScaledBeta) –
Level range of the audio blocks within the same talker/track, in dB SPL. Pass a tuple for uniform sampling, or ScaledBeta for shaped sampling over a custom range, e.g.:
- (60, 65) -> uniform level in [60, 65]
- ScaledBeta(low=60, high=65, a=4.0, b=2.0, step=1) -> biased toward higher levels, 1 dB steps.
overlap_range (tuple[float, float] | Uniform | ScaledBeta) – Fractional overlap between consecutive blocks, in [0, 1].
overlap_probability (float) – Probability of overlapping consecutive blocks, in [0, 1].
max_simultaneous_blocks (int | None) – Maximum number of simultaneously-active blocks across all talkers. If None, it is resolved to n_tracks during track generation.
samples_per_talker (SamplesPerTalker) – Per-talker sampling mode when candidate samples are exhausted.
allow_overlap (bool) – Derived; True only when overlap_range implies nonzero overlap AND overlap_probability > 0.

__init__(block_duration_range: tuple[float, float] = (0.0, numpy.inf), in_track_level_range_db_spl: tuple[float, float] | Uniform | ScaledBeta = (65.0, 65.0), overlap_range: tuple[float, float] | Uniform | ScaledBeta = (0.0, 0.0), overlap_probability: float = 0.5, max_simultaneous_blocks: int | None = None, samples_per_talker: SamplesPerTalker = SamplesPerTalker.reshuffle) → None

classmethod available_presets() → list[str]

List the names of all available presets.

Return list[str]:: Names of the presets defined in ConversationRulesPresets.

classmethod from_preset(preset: str | ConversationRulesPresets, **overrides: Any) → ConversationRules

Create a ConversationRules instance from a named preset.

Parameters:

preset (str | ConversationRulesPresets) – The preset to use. If a string, it is normalized (lower-cased, with spaces/hyphens replaced by underscores) before being matched against available_presets().
overrides (Any) – Keyword arguments overriding individual preset fields; these take precedence over the preset’s defaults.

Return ConversationRules:

The instance built from the preset merged with overrides.

classmethod from_struct(struct: dict[str, Any]) → ConversationRules

Reconstruct a ConversationRules instance from a dict produced by to_struct().

Any overlap_range or in_track_level_range_db_spl entry tagged with “distribution”: “uniform” or “distribution”: “beta” is converted back into the corresponding Uniform/ScaledBeta instance; other values pass through unchanged.

Parameters:: struct (dict[str, Any]) – A dict as produced by to_struct() (or an equivalent structure).
Return ConversationRules:: The reconstructed instance.

to_struct() → dict[str, Any]

Serialize this instance to a plain, JSON-friendly dict.

Drops the derived allow_overlap field, and converts overlap_range and in_track_level_range_db_spl from Uniform/ScaledBeta objects into dicts tagged with a “distribution” key (“uniform” or “beta”) plus their constructor arguments, so the result round-trips through from_struct().

Return dict[str, Any]:: A serializable representation of this instance.

allow_overlap: bool

block_duration_range: tuple[float, float] = (0.0, numpy.inf)

in_track_level_range_db_spl: tuple[float, float] | Uniform | ScaledBeta = (65.0, 65.0)

max_simultaneous_blocks: int | None = None

overlap_probability: float = 0.5

overlap_range: tuple[float, float] | Uniform | ScaledBeta = (0.0, 0.0)

samples_per_talker: SamplesPerTalker = 'reshuffle'

class treble_tsdk.scene.track_generator.NoiseSourceRules

Rules controlling repeated-noise track generation.

Parameters:

free_field_level_db_spl (float | tuple[float, float]) – Fixed level or (min, max) range in dB SPL.
overlap_s (float) – Overlap in seconds for repeated noise.
unique_samples (bool) – If true, avoid repeating samples when selecting tracks. If there aren’t enough distinct samples for the requested track count (and reuse_single_sample is False), the track count is silently capped down to the number available rather than raising — contrast with TransientNoiseRules.unique_samples, which raises in the equivalent situation. A warning is recorded only if a scene_generation_log is passed to TrackGenerator.generate_tracks(); with the default None this is silent.
reuse_single_sample (bool) – If true, select one sample and reuse for all tracks.

__init__(free_field_level_db_spl: tuple[float, float] | Uniform | ScaledBeta = (65.0, 65.0), overlap_s: float = 0.0, unique_samples: bool = True, reuse_single_sample: bool = False) → None

free_field_level_db_spl: tuple[float, float] | Uniform | ScaledBeta = (65.0, 65.0)

overlap_s: float = 0.0

reuse_single_sample: bool = False

unique_samples: bool = True

class treble_tsdk.scene.track_generator.SamplesPerTalker

Per-talker sampling mode once a talker’s candidate samples are exhausted.

force_unique: use each sample at most once; raise when exhausted.
reshuffle: re-shuffle and continue.
recycle: reuse the same initial shuffled order.
random: sample uniformly with replacement for every block.

force_unique = 'force_unique'

random = 'random'

recycle = 'recycle'

reshuffle = 'reshuffle'

class treble_tsdk.scene.track_generator.StaticNoiseRules

Rules controlling static device/mic noise generation.

For noise levels, provide either level_db_spl or microphone_snr_db, but not both. Providing both raises immediately in __post_init__; providing neither does not raise at construction time — it only raises later, the first time track generation runs. Prefer one of the from_profile_and_…/from_noise_type_and_… classmethods below over the bare constructor to avoid building an instance that looks valid but fails at generation time.

To add per-band jitter to the noise profile, set profile_band_jitter_db_range (a (min, max) tuple in dB); this also requires profile to be set.

Tuple parameters (ranges or dB values) are always size 2: (min, max).

profile_band_jitter_db_range and level_db_spl/microphone_snr_db are resampled independently for every track, not once per group — two tracks from the same StaticNoiseRules can end up with different jittered profiles and different levels/SNRs.

Parameters:

profile (StaticNoiseProfile | None) – Base profile for frequency-shaped noise.
level_db_spl (tuple[float, float] | Uniform | ScaledBeta | None) – Fixed level or (min, max) range in dB SPL.
microphone_snr_db (tuple[float, float] | Uniform | ScaledBeta | None) – Fixed microphone SNR or (min, max) range in dB, per microphone-datasheet convention: the noise is scaled so a 94 dB SPL, 1 kHz reference tone sits this many dB above the noise floor after A-weighting — i.e. the dBA figure straight off a microphone spec sheet, not a flat-band SNR.
profile_band_jitter_db_range (tuple[float, float] | Uniform | ScaledBeta | None) – (min, max) jitter in dB.

__init__(profile: StaticNoiseProfile | None = None, level_db_spl: tuple[float, float] | Uniform | ScaledBeta | None = None, microphone_snr_db: tuple[float, float] | Uniform | ScaledBeta | None = None, profile_band_jitter_db_range: tuple[float, float] | Uniform | ScaledBeta | None = None) → None

Build static noise rules from a named noise type and a fixed noise level.

Builds a StaticNoiseProfile for the given noise_type (mems_noise_profile, white_noise, or pink_noise) and delegates to from_profile_and_level().

Parameters:

noise_type (StaticNoiseType) – The noise type to generate a profile for.
level_db_spl (tuple[float, float] | Uniform | ScaledBeta) – Fixed level or (min, max) range in dB SPL.
profile_band_jitter_db_range (tuple[float, float] | Uniform | ScaledBeta | None) – Optional (min, max) per-band jitter in dB.

Return StaticNoiseRules:

The constructed rules, with level_db_spl set (and microphone_snr_db left unset).

Build static noise rules from a named noise type and a target microphone SNR.

Builds a StaticNoiseProfile for the given noise_type (mems_noise_profile, white_noise, or pink_noise) and delegates to from_profile_and_microphone_snr().

Parameters:

noise_type (StaticNoiseType) – The noise type to generate a profile for.
microphone_snr_db (tuple[float, float] | Uniform | ScaledBeta) – Fixed microphone SNR or (min, max) range in dB, per the datasheet convention documented on StaticNoiseRules (a 94 dB SPL, 1 kHz reference tone this many dB above the A-weighted noise floor).
profile_band_jitter_db_range (tuple[float, float] | Uniform | ScaledBeta | None) – Optional (min, max) per-band jitter in dB.

Return StaticNoiseRules:

The constructed rules, with microphone_snr_db set (and level_db_spl left unset).

Build static noise rules from an explicit profile and a fixed noise level.

Parameters:

profile (StaticNoiseProfile) – Base frequency-shaped noise profile.
level_db_spl (tuple[float, float] | Uniform | ScaledBeta) – Fixed level or (min, max) range in dB SPL.
profile_band_jitter_db_range (tuple[float, float] | Uniform | ScaledBeta | None) – Optional (min, max) per-band jitter in dB.

Return StaticNoiseRules:

The constructed rules, with level_db_spl set (and microphone_snr_db left unset).

Build static noise rules from an explicit profile and a target microphone SNR.

Parameters:

profile (StaticNoiseProfile) – Base frequency-shaped noise profile.
microphone_snr_db (tuple[float, float] | Uniform | ScaledBeta) – Fixed microphone SNR or (min, max) range in dB, per the datasheet convention documented on StaticNoiseRules (a 94 dB SPL, 1 kHz reference tone this many dB above the A-weighted noise floor).
profile_band_jitter_db_range (tuple[float, float] | Uniform | ScaledBeta | None) – Optional (min, max) per-band jitter in dB.

Return StaticNoiseRules:

The constructed rules, with microphone_snr_db set (and level_db_spl left unset).

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

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

profile: StaticNoiseProfile | None = None

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

class treble_tsdk.scene.track_generator.TrackGenerator

Generates audio tracks for a scene from an AudioDataset, driven by a set of rules.

Depending on the rules type passed to the constructor, generate_tracks produces conversational talker tracks (ConversationRules -> list[AudioTrack]), repeated background noise tracks (NoiseSourceRules -> list[RepeatedAudioTrack]), transient/one-shot noise-event tracks (TransientNoiseRules -> list[AudioTrack]), or static device/microphone noise tracks (StaticNoiseRules -> list[StaticNoiseTrack]).

Generate audio tracks from an audio dataset based on conversation or noise rules.

Parameters:

audio_dataset (AudioDataset | None) – The audio dataset to generate tracks from.
rules (ConversationRules | NoiseSourceRules | TransientNoiseRules | StaticNoiseRules) – The rules to use for generating tracks.
talker_identifier (str | None) – The identifier column in the audio dataset that contains the talker IDs. Only meaningful (and required) when rules is ConversationRules; harmlessly ignored for the other three rules types.
filter_definitions (list[FilterDefinition] | None) – Source-side filters copied onto every track this generator produces, applied to that track’s dry signal before/independent of any IR convolution, scoped to this generator’s own tracks only. Contrast with the receiver-side filter_definitions, applied uniformly to every track in the scene at render time regardless of which generator produced it.

generate_tracks(n_tracks: int, duration_s: float, start_time_s: float = 0.0, seed: int | None = None, rnc: SobolRandomContext | None = None, scene_generation_log: SceneGenerationLog | None = None, exclude_talker_ids: set[Any] | None = None, rng_prefix: str | None = None) → list[AudioTrack] | list[RepeatedAudioTrack] | list[StaticNoiseTrack]

Generate audio tracks from the audio dataset based on the provided rules.

The return type depends on the rules passed to the constructor: ConversationRules yields conversational talker tracks, NoiseSourceRules yields repeated background noise tracks, TransientNoiseRules yields one-shot/transient noise-event tracks (as AudioTrack instances), and StaticNoiseRules yields static device/microphone noise tracks.

Parameters:

n_tracks (int) – The number of tracks to generate.
duration_s (float) – The duration of the tracks to generate.
seed (int | None) – The random seed to use for the random number generator.

Returns list[AudioTrack] | list[RepeatedAudioTrack] | list[StaticNoiseTrack]:

A list of generated tracks.

property available_talkers

Talker IDs eligible for conversation track generation.

Filters the dataset’s distinct talker identifiers down to those with at least one sample whose length_s falls within rules.block_duration_range; talkers with no matching samples are excluded.

Return list[Any]:: Eligible talker identifiers, in first-seen order.

property dataset_identity: str | None

A stable identity hash for the underlying audio dataset.

Computed as the SHA-256 hex digest of the dataset’s parquet URLs, sorted and JSON-serialized. Two TrackGenerator instances backed by the same set of parquet files (regardless of order) will have the same identity, which callers can use to key cross-instance/group state (e.g. to deduplicate talkers across scene groups sharing the same dataset).

Return str | None:: The dataset identity hash, or None if no audio dataset is set.

property selected_talker_ids: set[Any]

Talker IDs that were assigned at least one audio block in the most recent generate_tracks call.

Return set[Any]:: Talker identifiers with at least one generated block, empty before the first call.

property talker_identifier: str | None

The dataset column name used to identify talkers.

Return str | None:: The talker identifier column name, or None if not set.

property uses_conversation_rules: bool

Whether this generator was configured with ConversationRules.

Return bool:: True if the rules passed to the constructor are a ConversationRules instance.

class treble_tsdk.scene.track_generator.TransientNoiseRules

Rules controlling transient/one-shot noise-event track generation (e.g. a car passing, a bird call, a door slam): each generated track is assigned a single sample from the dataset, which is then placed at one or more non-overlapping, randomly chosen moments within the scene duration.

Parameters:

free_field_level_db_spl (float | tuple[float, float]) – Fixed level or (min, max) range in dB SPL, sampled independently for each event placement.
n_events_range (tuple[int, int]) – (min, max) number of times a track’s sample occurs; (1, 1) places the sample exactly once.
min_gap_s (float) – Minimum silence, in seconds, enforced between consecutive event placements. If the requested n_events_range can’t all fit non-overlapping within the duration given this gap, fewer events are placed for that track (not an error); a track left with zero placed events is dropped from the returned list entirely, so the result can be shorter than n_tracks. A warning is recorded only if a scene_generation_log is passed to TrackGenerator.generate_tracks(); with the default None this is silent.
unique_samples (bool) – If true, avoid assigning the same sample to more than one track when enough distinct samples are available. Unlike NoiseSourceRules.unique_samples, this raises (rather than silently capping the track count) when there aren’t enough distinct samples for the requested track count.

__init__(free_field_level_db_spl: tuple[float, float] | Uniform | ScaledBeta = (65.0, 65.0), n_events_range: tuple[int, int] = (1, 1), min_gap_s: float = 0.0, unique_samples: bool = True) → None

free_field_level_db_spl: tuple[float, float] | Uniform | ScaledBeta = (65.0, 65.0)

min_gap_s: float = 0.0

n_events_range: tuple[int, int] = (1, 1)

unique_samples: bool = True