TesseraRangeSession

Guided vocal range detection session with observable state.

What is a Range Session?

A stateful, phase-driven workflow for detecting a singer's comfortable vocal range: countdown → detect low → transition → detect high → complete. Emits VocalRangeState via state (a StateFlow) so UI can track progress, current pitch, stability, and the final result.

Supports auto-flow (automatic phase progression) and manual control (caller drives transitions via startPhase / advancePhase).

When to Use

Quick Start

Kotlin

val session = TesseraRangeSession.create(
    detectorConfig = PitchDetectorConfig.BALANCED
)

// Observe state
session.state.collect { state -> updateUI(state) }

// Start auto-flow and feed audio
session.start()
recorder.audioBuffers.collect { buffer ->
    session.addAudio(buffer.samples, sampleRate = 16000)
}

// Lock a detected note, or cancel
session.confirmNote()
session.release()

Swift

let session = TesseraRangeSession.create(
    detectorConfig: PitchDetectorConfig.Builder().algorithm(.yin).enableProcessing().build()
)

// Observe state via AsyncSequence
for await state in session.state {
    updateUI(state)
}

session.start()
for await buffer in recorder.audioBuffers {
    session.addAudio(samples: buffer.samples, sampleRate: Int32(hwRate))
}

session.confirmNote()
session.release()

Common Pitfalls

1. start() is for auto-flow only: If config.autoFlow = false, call startPhase / advancePhase instead — start() throws.

2. Audio is only processed during detection phases: Samples sent outside DETECTING_LOW / DETECTING_HIGH (i.e., during IDLE, COUNTDOWN, TRANSITION, COMPLETE, or CANCELLED) are silently ignored.

3. Call release() when done: Holds native detector resources.

4. confirmNote() locks the current best: It's a user-confirmation action, not an auto-trigger. Returns false if no stable note yet.

See also