Skip to main content

Tessera Overview

Tessera is the voice-metrics module. It analyzes a PitchContour (from PitchDetection) and produces structured measurements of the singer's voice.

FacadePurpose
TesseraMulti-metric batch — breath + agility + range from one contour
TesseraSessionStreaming multi-metric — feed audio incrementally
TesseraBreathBreath control, phrase structure, reference comparison
TesseraAgilityVocal agility (ornament speed and regularity)
TesseraRangeVocal range, search vector, song matching
TesseraRangeSessionGuided "find your range" flow with observable state
TesseraSpeakingPitchNatural speaking pitch detection

All facades operate on a tona.model.PitchContour. Get one via PitchDetection.createContourExtractor(...).extract(...) or accumulate it via PitchDetection.createDetector(...).feedContour(...).

When to Use​

ScenarioFacade
Profile a singer from one recording (one call)Tessera.analyze
Stream metrics liveTesseraSession
Score breath control / phrase structureTesseraBreath
Score vocal agilityTesseraAgility
Find a singer's lower / upper note (batch)TesseraRange
Interactive "find your range" flowTesseraRangeSession
Natural speaking pitch from speechTesseraSpeakingPitch
Voice/song matching by pitch distributionTesseraRange.computeMatch

Tessera.analyze (batch)​

val result = Tessera.analyze(contour)

println("Breath control: ${result.breath?.controlScore}")
println("Agility: ${result.agility?.scores?.firstOrNull()}")
println("Range: ${result.vocalRange?.range?.octaves} octaves")

// Specific metrics only
val breathOnly = Tessera.analyze(contour, setOf(TesseraMetric.BREATH))

Signature​

fun analyze(
    contour: PitchContour,
    metrics: Set<TesseraMetric> = TesseraMetric.ALL,
    breathConfig: BreathConfig = BreathConfig.DEFAULT,
    agilityConfig: AgilityConfig = AgilityConfig.DEFAULT,
    rangeConfig: SearchVectorConfig = SearchVectorConfig.DEFAULT,
): TesseraResult

TesseraMetric.ALL = { BREATH, AGILITY, VOCAL_RANGE }.

TesseraResult carries one nullable field per metric — null means the metric was not requested. (For range, null may also mean insufficient voiced data.)

data class TesseraResult(
    val breath: BreathMetrics?,
    val agility: AgilityScore?,
    val vocalRange: VocalRangeResult?,
)

Failure Semantics (ADR-022)​

KindHow it surfaces
Empty contour or < 2 samplesThrows IllegalArgumentException
Insufficient data for range estimation (valid input)vocalRange is null in the result

Per-facade pages document additional throws/null-returns.

See also​