Tessera

Multi-metric batch analysis facade — breath, agility, and vocal range from a single PitchContour.

What is Multi-Metric Analysis?

Given a pitch contour from a vocal performance, Tessera computes all requested voice metrics in one pass, sharing the contour data across metrics instead of re-extracting it. The result bundles nullable fields for each metric — null means "not requested" or "insufficient data".

When to Use

Quick Start

Kotlin

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))

Swift

let result = Tessera.analyze(contour: contour)
print("Breath control: \(result.breath?.controlScore ?? 0)")
print("Agility: \(result.agility?.scores.first ?? 0)")
print("Range: \(result.vocalRange?.range.octaves ?? 0) octaves")

Common Pitfalls

1. Contour must have ≥ 2 samples: Throws IllegalArgumentException per ADR-022 on empty or single-sample contours.

2. Null metric meanings differ by type: A null breath or agility means the metric was not requested (they never return null for insufficient data — the ≥ 2 samples guard fires first). A null vocalRange means not requested OR insufficient voiced data for range estimation.

3. For streaming, use TesseraSession: This facade processes the entire contour in one call. Feeding it incrementally rebuilds from scratch each time.

See also