VoxaTrace/com.musicmuni.voxatrace.calibra/CalibraLiveEval

CalibraLiveEval

Real-time singing evaluation session with segment support.

What is Live Evaluation?

Live evaluation scores a singer's performance in real-time by comparing their pitch to a reference melody. Use it for:

Karaoke apps: Score singing as users perform
Music education: Provide instant feedback on pitch accuracy
Practice apps: Track improvement across attempts

The session breaks a song into segments (phrases or sections), evaluates each one, and tracks the user's progress.

When to Use

Scenario	Use This?	Why
Score singing against reference	Yes	Core use case
Just detect pitch (no scoring)	No	Use `CalibraPitch.createDetector()`
Analyze recorded audio (not live)	No	Use `CalibraMelodyEval`
Voice activity detection only	No	Use `CalibraVAD`

Quick Start

Kotlin

// 1. Create detector and session
val detector = CalibraPitch.createDetector()
val session = CalibraLiveEval.create(lessonMaterial, detector = detector)

// 2. Prepare (loads reference, extracts features)
session.prepareSession()

// 3. Start segment and feed audio
session.startPracticingSegment(0)
recorder.audioBuffers.collect { buffer ->
    session.feedAudioSamples(buffer.toFloatArray(), sampleRate = 48000)
}

// 4. Get result
val result = session.finishPracticingSegment()
println("Score: ${result?.score}")

// 5. Cleanup
session.closeSession()

Swift

// 1. Create detector and session
let detector = CalibraPitch.createDetector()
let session = CalibraLiveEval.create(
    reference: lessonMaterial,
    detector: detector
)

// 2. Prepare (loads reference, extracts features)
try await session.prepareSession()

// 3. Start segment and feed audio
session.startPracticingSegment(index: 0)
for await buffer in recorder.audioBuffers {
    session.feedAudioSamples(samples: buffer.toFloatArray(), sampleRate: 48000)
}

// 4. Get result
if let result = session.finishPracticingSegment() {
    print("Score: \(result.score)")
}

// 5. Cleanup
session.closeSession()

Usage Tiers

Tier 1: Convenience API (80% of users)

Pass player and recorder handles; the session coordinates everything.

val session = CalibraLiveEval.create(
    reference = lessonMaterial,
    detector = CalibraPitch.createDetector(),
    player = player,
    recorder = recorder
)
session.prepareSession()
session.onSegmentComplete { result -> showScore(result) }
session.startPracticingSegment(0)  // Seeks, plays, records, scores automatically

Tier 2: Low-Level API (15% of users)

Manually manage audio; full control over timing.

val session = CalibraLiveEval.create(reference, detector = detector)
session.prepareSession()
session.startPracticingSegment(0)
recorder.audioBuffers.collect { buffer ->
    session.feedAudioSamples(buffer.toFloatArray(), buffer.sampleRate)
}
val result = session.finishPracticingSegment()

Phase Progressions

Singalong: IDLE → SINGING → EVALUATED
Singafter: IDLE → LISTENING → SINGING → EVALUATED

Observe phase StateFlow for UI updates.

State Machine

IDLE ──prepareSession()──► READY
READY ──startPracticingSegment()──► PRACTICING
PRACTICING ──finishPracticingSegment()──► BETWEEN (or COMPLETED if last)
PRACTICING ──discardCurrentSegment()──► BETWEEN
PRACTICING ──seekToSegment()──► PRACTICING (new segment)
BETWEEN ──startPracticingSegment()──► PRACTICING
BETWEEN ──advanceToNextSegment()──► PRACTICING (or COMPLETED if last)
BETWEEN ──finishSession()──► COMPLETED
* ──closeSession()──► (released)

Ownership Model

Dependency	Ownership	Rationale
`detector`	Owned - session closes it	Created specifically for this session
`player`	Borrowed - caller manages	Shared resource, UI may need direct access
`recorder`	Borrowed - caller manages	Shared resource, may be reused