TesseraRange

Public facade for batch vocal range analysis, search vector creation, and song matching.

What is Vocal Range Analysis?

Given a pitch contour, this facade:

1. Estimates the singer's comfortable range (lower/upper pitch, octaves).

2. Creates a 13-dim search vector — a sigmoid-normalized histogram of pitch distribution in 4-semitone bins — used for matching singers to songs.

3. Matches singer vs song vectors via inner-product similarity with a gender-based octave offset.

When to Use

Quick Start

Kotlin

val rangeResult = TesseraRange.computeVocalRange(contour)
if (rangeResult != null) {
    println("${rangeResult.range.lower.noteLabel} to ${rangeResult.range.upper.noteLabel}")
    val match = TesseraRange.computeMatch(rangeResult.searchVector, songVec, Gender.MALE)
    println("Difficulty: ${match.difficulty}/5")
}

Swift

if let result = TesseraRange.computeVocalRange(contour: contour) {
    print("\(result.range.lower.noteLabel) to \(result.range.upper.noteLabel)")
    let match = TesseraRange.computeMatch(
        singerVector: result.searchVector, songVector: songVec, singerGender: .male
    )
    print("Difficulty: \(match.difficulty)/5")
}

Common Pitfalls

1. computeVocalRange returns null for insufficient data: Not enough voiced frames to estimate a range. Not an error — domain outcome per ADR-022.

2. Singer vector: normalize = false; song vector: normalize = true: The asymmetry is by design — singer vectors are raw magnitude, song vectors are L1-normalized for inner-product comparison.

3. Contour must have ≥ 2 samples: Throws per ADR-022.

See also