VoxaTrace/com.musicmuni.voxatrace.accura.model/IntonationAnalysisResult

IntonationAnalysisResult

data class IntonationAnalysisResult(val intonationSystem: IntonationSystem, val tonicHz: Float, val shrutiLabel: String, val analysisParameters: Map<String, Any>, val notes: List<NoteAnalysis>, val offScaleNotes: List<OffScaleNote> = emptyList(), val error: String? = null)

Complete result of intonation analysis for a performance.

Returned by com.musicmuni.voxatrace.accura.Accura.analyzePitching. Always check error before interpreting notes or passing to com.musicmuni.voxatrace.accura.Accura.calculateScore — when error is non-null, analysis was inconclusive and notes will be empty.

notes and offScaleNotes together are everything the singer dwelled on: notes are the scale degrees graded against their targets, offScaleNotes are prominent peaks that landed outside the requested scale.

Example

val result = Accura.analyzePitching(contour, tonicHz, IntonationSystem.EQ)
if (result.error == null) {
    for (note in result.notes) {
        println("${note.label}: ${note.deviationCents} cents (${note.tier})")
    }
    for (off in result.offScaleNotes) {
        println("off-scale: ${off.label}, near ${off.nearestInScaleLabel}")
    }
    println("Tuning offset applied: ${result.analysisParameters["tuning_offset_cents"]} cents")
} else {
    println("Analysis failed: ${result.error}")
}

Constructors

IntonationAnalysisResult

constructor(intonationSystem: IntonationSystem, tonicHz: Float, shrutiLabel: String, analysisParameters: Map<String, Any>, notes: List<NoteAnalysis>, offScaleNotes: List<OffScaleNote> = emptyList(), error: String? = null)

Properties

analysisParameters

val analysisParameters: Map<String, Any>

Analysis parameters recorded for reproducibility. Keys currently populated:

error

val error: String?

Error message if analysis was inconclusive (e.g., too few peaks detected); null on success. When non-null, notes is empty and passing this result to com.musicmuni.voxatrace.accura.Accura.calculateScore throws IllegalArgumentException (ADR-022).

intonationSystem

val intonationSystem: IntonationSystem

Which intonation system was used for analysis.

notes

val notes: List<NoteAnalysis>

Per-note analysis for the requested scale. Empty when error is non-null.

offScaleNotes

val offScaleNotes: List<OffScaleNote>

Prominent peaks that landed on a chromatic degree outside the requested scale — notes the singer dwelled on by mistake.

shrutiLabel

val shrutiLabel: String

Tonic note label derived from tonicHz (e.g., "C3", "D#4").