treble_tsdk.scene.track

Functions

filter_audio_signal(audio_signal, ...)

Apply a list of filter definitions to an audio signal, if any are given.

resample_audio_signal(audio_signal, ...)

Resample an audio signal to sampling_rate, if it does not already match.

resample_filter_scale_speech(speech, ...[, ...])

Resample, filter, and level-scale a speech signal in sequence.

scale_audio_signal(audio_signal, ...)

Scale an audio signal so its overall RMS level matches a target free-field SPL.

scale_speech(speech, free_field_level_db_spl)

Scale the speech signal so its ITU-T P.56 active speech level matches free_field_level_db_spl.

Classes

AudioBlock

A single placed audio sample within an AudioTrack.

AudioTrack

A track composed of discrete, non-overlapping AudioBlock placements.

RepeatedAudioTrack

A track that loops a single audio sample, cross-fading repeats, to fill a duration.

StaticNoiseProfile

Frequency-shaped static noise profile.

StaticNoiseTrack

A track of synthesized static noise shaped by a StaticNoiseProfile.

StaticNoiseType

Kind of static noise profile to generate.

TrackType

Discriminator for the type field of a track's serialized struct.
class treble_tsdk.scene.track.AudioBlock

A single placed audio sample within an AudioTrack.

Parameters:

  • audio_data (AudioSampleReference) – Reference to the underlying audio sample.

  • start_time_s (float) – Placement offset, in seconds, from the start of the track.

  • free_field_level_db_spl (float) – Target free-field sound pressure level, in dB SPL, the sample is scaled to when rendered.

__init__(audio_data: AudioSampleReference, start_time_s: float, free_field_level_db_spl: float) → None
classmethod from_struct(struct: dict[str, Any]) → AudioBlock

Reconstruct an AudioBlock from a dict produced by to_struct().

overlaps(other: AudioBlock) → bool

Return True if this block’s time range overlaps other’s.

to_struct() → dict

Serialize to a plain dict.

audio_data: AudioSampleReference
free_field_level_db_spl: float
start_time_s: float
class treble_tsdk.scene.track.AudioTrack

A track composed of discrete, non-overlapping AudioBlock placements.

Parameters:

  • audio_blocks (list[AudioBlock] | None) – Initial blocks to populate the track with. Defaults to an empty list.

  • filter_definitions (list[FilterDefinition] | None) – Optional filters applied to every block’s audio when rendered.

__init__(audio_blocks: list[AudioBlock] | None = None, filter_definitions: list[FilterDefinition] | None = None)
add_audio_block(audio_data: AudioSampleReference, start_time_s: float, free_field_level_db_spl: float = 0.0)

Create and append an AudioBlock, keeping blocks sorted by start time.

Parameters:

  • audio_data (AudioSampleReference) – The sample to place.

  • start_time_s (float) – Placement offset, in seconds, from the start of the track; must be >= 0.0.

  • free_field_level_db_spl (float) – Target free-field SPL, in dB, the sample is scaled to when rendered. Defaults to 0.0.

Raises:

ValueError – If start_time_s is negative, or the new block’s time range overlaps an existing block already in the track.

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

Reconstruct an AudioTrack from a dict produced by to_struct().

render(sampling_rate: float) → AudioSignal

Render all audio blocks into a single signal, silent where no block is placed.

Each block’s sample is resampled, filtered, and scaled to its free_field_level_db_spl before being placed at its start_time_s.

Parameters:

sampling_rate (float) – Output sampling rate in Hz.

Return AudioSignal:

The rendered signal, of length duration_s (or a single sample of silence if the track has no blocks and zero duration).

to_struct() → dict[str, Any]

Serialize to a plain dict, including a type discriminator.

property duration_s: float

Total track length in seconds, i.e. the latest block’s end time (0 if empty).

property n_blocks: int

Number of audio blocks currently in the track.

class treble_tsdk.scene.track.RepeatedAudioTrack

A track that loops a single audio sample, cross-fading repeats, to fill a duration.

Parameters:

  • audio_sample (AudioSampleReference) – The sample to repeat.

  • free_field_level_db_spl (float) – Target free-field SPL, in dB, the rendered signal is scaled to. Defaults to 94.0.

  • start_time_s (float) – Offset, in seconds, from the start of the render at which looping begins; must be >= 0.0. Defaults to 0.0.

  • overlap_s (float) – Cross-fade duration, in seconds, between successive repeats of the sample; must be >= 0.0 and less than half the sample’s length. Defaults to 1.0.

  • duration_s (float | None) – Length, in seconds, of the looped playback (time to fill after start_time_s); default used by render() when called without an explicit duration_s. Must be > 0.0 if provided.

  • filter_definitions (list[FilterDefinition] | None) – Optional filters applied to the sample before looping.

__init__(audio_sample: AudioSampleReference, free_field_level_db_spl: float = 94.0, start_time_s: float = 0.0, overlap_s: float = 1.0, duration_s: float | None = None, filter_definitions: list[FilterDefinition] | None = None)
classmethod from_struct(struct: dict[str, Any]) → RepeatedAudioTrack

Reconstruct a RepeatedAudioTrack from a dict produced by to_struct().

Parameters:

struct (dict[str, Any]) – Serialized track data.

Return RepeatedAudioTrack:

The reconstructed track.

render(sampling_rate: float, duration_s: float | None = None) → AudioSignal

Render the looped, cross-faded, level-scaled signal.

Parameters:

  • sampling_rate (float) – Output sampling rate in Hz; must be > 0.

  • duration_s (float | None) – Absolute end time, in seconds, of the rendered signal (total length from time 0, not relative to start_time_s). If None, defaults to self.duration_s + self.start_time_s (the constructor’s duration_s, which is relative to start_time_s).

Return AudioSignal:

The rendered signal, silent before start_time_s.

to_struct() → dict

Convert to dict format for the UI.

Return dict:

Serialized representation, including a type discriminator.

property duration_s: float

Configured loop duration in seconds (relative to start_time_s), or None.

property free_field_level_db_spl: float

Target free-field sound pressure level, in dB SPL, the rendered signal is scaled to.

property start_time_s: float

Offset, in seconds, from the start of the render at which looping begins.

class treble_tsdk.scene.track.StaticNoiseProfile

Frequency-shaped static noise profile.

Parameters:

  • frequencies (list[float]) – Band center frequencies in Hz; must be strictly increasing, positive, and at least seven values long.

  • band_levels_db (list[float]) – Relative level, in dB, for each frequency band (same length as frequencies).

__init__(frequencies: list[float], band_levels_db: list[float]) → None
classmethod from_struct(struct: dict[str, Any]) → StaticNoiseProfile

Reconstruct a StaticNoiseProfile from a dict produced by to_struct().

static pink_noise() → StaticNoiseProfile

Build a pink-noise profile (level falls off as 1/frequency), normalized to 0 dB at the lowest band.

to_struct() → dict[str, Any]

Serialize to a plain dict of lists.

static white_noise() → StaticNoiseProfile

Build a flat-spectrum profile (0 dB at every third-octave band).

band_levels_db: list[float]
frequencies: list[float]
class treble_tsdk.scene.track.StaticNoiseTrack

A track of synthesized static noise shaped by a StaticNoiseProfile.

Parameters:

  • profile (StaticNoiseProfile) – Frequency shape to impose on the generated noise; must have strictly increasing, positive frequencies.

  • level_db_spl (float | None) – Absolute target level, in dB SPL, to scale the noise to. Mutually exclusive with microphone_snr_db.

  • microphone_snr_db (float | None) – Target SNR, in dB, relative to a microphone reference; scales the noise via A-weighting instead of an absolute SPL. Mutually exclusive with level_db_spl.

  • random_seed (int | None) – Seed for the noise generator, derived via treble_tsdk.collections.distributions._derive_seed(). If None, noise is non-reproducible.

  • filter_definitions (list[FilterDefinition] | None) – Optional filters applied to the generated noise when rendered.

  • noise_id (str | None) – Identifier for the track. If None, a UUID is generated.

  • start_time_s (float) – Offset, in seconds, from the start of the render at which noise begins; must be >= 0.0. Defaults to 0.0.

  • duration_s (float | None) – Length, in seconds, of the noise (relative to start_time_s); default used by render() when called without an explicit duration_s. Must be > 0.0 if provided.

__init__(profile: StaticNoiseProfile, level_db_spl: float | None = None, microphone_snr_db: float | None = None, random_seed: int | None = None, filter_definitions: list[FilterDefinition] | None = None, noise_id: str | None = None, start_time_s: float = 0.0, duration_s: float | None = None)
classmethod from_struct(struct: dict[str, Any]) → StaticNoiseTrack

Reconstruct a StaticNoiseTrack from a dict produced by to_struct().

render(sampling_rate: float, duration_s: float | None = None) → ConvolvedAudioSignal

Generate the shaped noise signal, scaled by level or SNR, and silent before start_time_s.

Noise is synthesized in the frequency domain from white noise shaped by the profile’s interpolated (log-frequency) band levels, then scaled either to level_db_spl directly or to achieve microphone_snr_db against an A-weighted reference (whichever was set on the track).

Parameters:

  • sampling_rate (float) – Output sampling rate in Hz; must be > 0.

  • duration_s (float | None) – Absolute end time, in seconds, of the rendered signal (total length from time 0, not relative to start_time_s). If None, defaults to self.duration_s + self.start_time_s (the constructor’s duration_s, which is relative to start_time_s).

Return ConvolvedAudioSignal:

The rendered noise signal.

to_struct() → dict[str, Any]

Serialize to a plain dict, including a type discriminator.

class treble_tsdk.scene.track.StaticNoiseType

Kind of static noise profile to generate.

mems_noise_profile = 'mems_noise_profile'

Self-noise floor of a typical MEMS microphone; see noise_profiles.

pink_noise = 'pink_noise'

Level falls off as 1/frequency, normalized to 0 dB at the lowest band.

white_noise = 'white_noise'

Flat spectrum (0 dB at every third-octave band).

class treble_tsdk.scene.track.TrackType

Discriminator for the type field of a track’s serialized struct.

audio = 'audio'

A AudioTrack of discrete, non-overlapping audio blocks.

repeated = 'repeated'

A RepeatedAudioTrack that loops a single sample.

static_noise = 'static_noise'

A StaticNoiseTrack of synthesized noise.

treble_tsdk.scene.track.filter_audio_signal(audio_signal: AudioSignal, filter_definitions: list[FilterDefinition]) → AudioSignal

Apply a list of filter definitions to an audio signal, if any are given.

Parameters:

  • audio_signal (AudioSignal) – The signal to filter.

  • filter_definitions (list[FilterDefinition]) – Filters to apply. If empty or falsy, the signal is returned unchanged.

Return AudioSignal:

The filtered signal (or the original signal if no filters were given).

treble_tsdk.scene.track.resample_audio_signal(audio_signal: AudioSignal, sampling_rate: float) → AudioSignal

Resample an audio signal to sampling_rate, if it does not already match.

Parameters:

  • audio_signal (AudioSignal) – The signal to resample.

  • sampling_rate (float) – The target sampling rate in Hz.

Return AudioSignal:

The resampled signal (or the original signal if the rate already matches).

treble_tsdk.scene.track.resample_filter_scale_speech(speech: AudioSignal, sampling_rate: float, free_field_level_db_spl: float, filter_definitions: list[FilterDefinition] | None = None) → AudioSignal

Resample, filter, and level-scale a speech signal in sequence.

Parameters:

  • speech (AudioSignal) – The speech signal to process.

  • sampling_rate (float) – The target sampling rate in Hz.

  • free_field_level_db_spl (float) – The target free-field sound pressure level in dB SPL, based on the active speech level (see scale_speech()).

  • filter_definitions (list[FilterDefinition] | None) – Optional filters to apply between resampling and scaling.

Return AudioSignal:

The resampled, filtered, and scaled speech signal.

treble_tsdk.scene.track.scale_audio_signal(audio_signal: AudioSignal, free_field_level_db_spl: float) → AudioSignal

Scale an audio signal so its overall RMS level matches a target free-field SPL.

Parameters:

  • audio_signal (AudioSignal) – The signal to scale.

  • free_field_level_db_spl (float) – The target free-field sound pressure level in dB SPL.

Return AudioSignal:

The scaled signal.

treble_tsdk.scene.track.scale_speech(speech: AudioSignal, free_field_level_db_spl: float) → AudioSignal

Scale the speech signal so its ITU-T P.56 active speech level matches free_field_level_db_spl.

Parameters:

  • speech (AudioSignal) – The speech signal to scale.

  • free_field_level_db_spl (float) – The target free-field sound pressure level in dB SPL.

Returns:

The scaled speech signal.