Skip to main content

Calibra Overview

Calibra is the singing-evaluation module of VoxaTrace. It scores a singer's performance against a reference and runs voice-activity detection.

FacadePurpose
CalibraLiveEvalReal-time singing evaluation against a reference (segment-aware, observable state)
CalibraMelodyEvalOffline melody scoring of a complete recording
CalibraNoteEvalPer-note scoring for scales, arpeggios, svara patterns
CalibraVADVoice activity detection (multiple backends)
UtilitiesShared model types (Segment, SessionConfig, SegmentResult, …)

Calibra consumes but does not own (1.x → 2.0):

  • Pitch detection — tona.PitchDetection (1.x: CalibraPitch).
  • Voice metrics — tessera (1.x: CalibraBreath, CalibraVocalRange, CalibraSpeakingPitch; new in 2.0: TesseraAgility, multi-metric Tessera.analyze / TesseraSession, batch range + matching).
  • Music theory — common.MusicTheory (1.x: CalibraMusic; new in 2.0: MusicTheory.deriveUserShruti).
  • Intonation analysis & scoring — accura.Accura. New public facade in 2.0 — no 1.x equivalent.

The 1.x deprecation shells (CalibraPitch, CalibraBreath, CalibraVocalRange, VocalRangeSession, CalibraSpeakingPitch, CalibraMusic) were removed in 2.0.0 — there is no source-compat path. See CHANGELOG for the migration table.

Quick Start​

Real-time scoring (CalibraLiveEval)​

val detector = PitchDetection.createDetector()
val session = CalibraLiveEval.create(lessonMaterial, detector = detector)

session.prepareSession()
session.onSegmentComplete { result ->
    println("Segment ${result.segment.index}: ${(result.score * 100).toInt()}%")
}
session.startPracticingSegment(0)

recorder.audioBuffers.collect { buffer ->
    session.feedAudioSamples(
        samples = buffer.toFloatArray(),
        sampleRate = buffer.sampleRate,
        captureTimestampNanos = buffer.timestamp,
    )
}

session.closeSession()

Offline melody evaluation (CalibraMelodyEval)​

val extractor = PitchDetection.createContourExtractor(ContourExtractorConfig.SCORING)
val result = CalibraMelodyEval.evaluate(reference, student, extractor)
extractor.release()
println("Overall: ${result.overallScorePercent}%")

Voice activity detection (CalibraVAD)​

val vad = CalibraVAD.create(VADModelProvider.General)
val ratio = vad.getVADRatio(samples, sampleRate)
if (ratio > 0.5f) println("Voice present")
vad.release()

Two evaluation modes (Live Eval)​

  • Singalong: IDLE → SINGING → EVALUATED. Reference plays while the student sings; pitch is compared in real time.
  • Singafter: IDLE → LISTENING → SINGING → EVALUATED. Reference plays first, then the student sings the same phrase from memory.

Mode is determined per-segment by Segment.studentStartSeconds (see Utilities).

Failure semantics (ADR-022)​

KindHow it surfaces
Caller bug (uninitialized SDK, invalid config)Throws (VoxaTraceNotInitializedException, IllegalArgumentException)
Domain inconclusive (e.g. evaluator failed to extract any student data for a segment)finishPracticingSegment returns null

See also​