VoxaTrace/com.musicmuni.voxatrace.calibra/CalibraMelodyEval

CalibraMelodyEval

Offline melody/song evaluation for post-recording analysis.

What is Melody Evaluation?

Melody evaluation compares a complete recorded performance against a reference melody after the fact. Unlike live evaluation (real-time), this analyzes pre-recorded audio.

Use it for:

Post-recording feedback: Score a recording after the session ends
Batch processing: Analyze multiple recordings at once
Detailed analysis: More thorough analysis than real-time allows

When to Use

Scenario	Use This?	Why
Analyze recorded audio	Yes	Core use case
Real-time scoring	No	Use `CalibraLiveEval`
Evaluate scales/exercises	No	Use `CalibraNoteEval`
Just detect pitch	No	Use `PitchDetection`

Quick Start

Kotlin

val reference = LessonMaterial.fromAudio(
    samples = referenceAudio,
    sampleRate = 16000,
    segments = listOf(
        Segment(0, 0.0f, 3.5f, "First line"),
        Segment(1, 3.5f, 7.0f, "Second line")
    ),
    keyHz = 261.63f  // Middle C
)

val student = LessonMaterial.fromAudio(
    samples = studentAudio,
    sampleRate = 16000,
    segments = emptyList(),  // Uses reference segments
    keyHz = 261.63f
)

val extractor = PitchDetection.createContourExtractor(ContourExtractorConfig.SCORING)
val result = CalibraMelodyEval.evaluate(reference, student, extractor)
extractor.release()

println("Overall: ${result.overallScorePercent}%")
result.segmentResults.forEach { (index, attempts) ->
    println("Segment $index: ${attempts.last().scorePercent}%")
}

Swift

let reference = LessonMaterial.fromAudio(
    samples: referenceAudio,
    sampleRate: 16000,
    segments: [
        Segment.create(index: 0, startSeconds: 0.0, endSeconds: 3.5, lyrics: "First line"),
        Segment.create(index: 1, startSeconds: 3.5, endSeconds: 7.0, lyrics: "Second line")
    ],
    keyHz: 261.63
)

let student = LessonMaterial.fromAudio(
    samples: studentAudio,
    sampleRate: 16000,
    segments: [],
    keyHz: 261.63
)

let extractor = PitchDetection.createContourExtractor(
    config: .scoring
)
let result = CalibraMelodyEval.evaluate(
    reference: reference,
    student: student,
    contourExtractor: extractor
)
extractor.release()

print("Overall: \(result.overallScorePercent)%")

Platform Notes

iOS/Android

Audio can be at any sample rate — the contour extractor resamples to 16kHz internally (ADR-017). Use SonixDecoder for decoding.
Contour extractor must be released after use.

Common Pitfalls

Forgetting to release extractor: Call extractor.release() when done
Empty segments: If student.segments is empty, reference.segments is used
Key mismatch: Set studentKeyHz if student sings in different key
Mono input only: Audio must be single-channel; SonixDecoder auto-converts stereo

Functions

evaluate

@ShouldRefineInSwift

fun evaluate(reference: LessonMaterial, student: LessonMaterial, contourExtractor: PitchContourExtractor): SingingResult

Evaluate a melody performance against a reference.