kiteplayer-audioviz/io.github.yuroyami.kiteplayer.audioviz/SpectrumTimeline

SpectrumTimeline

class SpectrumTimeline(val capacity: Int = 128)

Bounded analysis history aligned to the audible media clock.

One thread pushes; any thread reads or resets. Reset replaces the whole history, so work already publishing into the retired history cannot return to the new one. Each atomic slot carries its sequence number: a wrapped slot cannot be mistaken for the older entry a reader was examining.

Constructors

SpectrumTimeline

constructor(capacity: Int = 128)

Properties

capacity

val capacity: Int

eventStats

val eventStats: AudioEventHistoryStats

Bounded event retention and detection-completion diagnostics for the current history.

generation

val generation: Generation

The continuous audio timeline this history accepts.

historyStats

val historyStats: SpectrumHistoryStats

Current feature retention, including evictions by count, media time or payload size.

revision

val revision: Long

Local continuity identity. Also changes on a dropped visual block or an analysis reset.

structureEventStats

val structureEventStats: AudioEventHistoryStats

Structural event retention and the structural watermark for the current history.

Functions

ahead

fun ahead(ptsMicros: Long, seconds: Float): SpectrumFrame?

Actual, already analysed audio seconds ahead. Null beyond the available horizon or across a gap; a past frame never substitutes for an unavailable future. Invalid offsets return null.

asFuture

fun SpectrumTimeline.asFuture(positionMicros: () -> Long): VizFuture

Lets a drawing see the audio that has been analysed but has not been played yet.

fun at(ptsMicros: Long): SpectrumFrame?

Newest retained analysis at or before ptsMicros, expiring after 100 ms without new data.

availableAheadSeconds

fun availableAheadSeconds(ptsMicros: Long): Float

Contiguous ready media seconds ahead, stopping at missing data or a gap over 100 ms.

clear

fun clear()

eventCursor

fun eventCursor(): AudioEventCursor

A new independent consumer, initially discarding events at or before its first sample time.

interpolated

fun interpolated(ptsMicros: Long): SpectrumFrame?

Continuous interpolation within one generation; unavailable data expires after 100 ms.

newest

fun newest(): SpectrumFrame?

The newest retained analysis, without alignment.

nextEvent

fun nextEvent(ptsMicros: Long, kind: AudioEventKind): AudioEvent?

Next retained or mapped event of kind strictly after ptsMicros, from any source, preserving its original identity. Live structural confirmations lie in the past and rarely qualify.

nextOnsetSeconds

fun nextOnsetSeconds(ptsMicros: Long): Float

Seconds until the next retained onset, or -1 when none has been observed.

push

fun push(frame: SpectrumFrame)

Publishes only frames matching both generation and revision of this history.

reset

fun reset(generation: Generation)

Retires history and advances revision. An older audio generation is ignored.

sample

fun sample(ptsMicros: Long, previousPtsMicros: Long): SpectrumFrame?

Scalar event projection over (previousPtsMicros, ptsMicros]. Continuous features are interpolated. This compatibility projection retains the strongest hit of each kind and does not preserve event multiplicity. It must not be used to count events.