VoxaTrace/com.musicmuni.voxatrace.calibra/CalibraBreath

CalibraBreath

object CalibraBreath

Breath capacity and control analysis for vocal performance assessment.

What is Breath Analysis?

Breath analysis measures how well a singer manages their breathing:

Breath capacity: Maximum duration of sustained notes without breathing
Breath control: How well breath is managed during phrases

These metrics help identify:

Singers who run out of breath mid-phrase
Progress in building breath support
Comparison with reference performances

When to Use

Scenario	Use This?	Why
Analyze sustained note ability	Yes	Core use case
Track breath improvement	Yes	Compare over time
Real-time breath feedback	No	Use pitch contour length
Detect breathing moments	Partially	Use unvoiced gaps

Quick Start

Kotlin

// Extract pitch contour first
val contour = pitchExtractor.extract(audio, sampleRate = 16000)
val times = contour.toTimesArray()
val pitches = contour.toPitchesArray()

// Check if enough data (needs 5+ seconds of voiced audio)
if (CalibraBreath.hasEnoughData(times, pitches)) {
    val capacity = CalibraBreath.computeCapacity(times, pitches)
    println("Breath capacity: $capacity seconds")
}

// Get total voiced time
val voicedTime = CalibraBreath.getCumulativeVoicedTime(times, pitches)
println("Total sung time: $voicedTime seconds")

Swift

// Extract pitch contour first
let contour = pitchExtractor.extract(audio: audio, sampleRate: 16000)
let times = contour.toTimesArray()
let pitches = contour.toPitchesArray()

// Check if enough data (needs 5+ seconds of voiced audio)
if CalibraBreath.hasEnoughData(times: times, pitchesHz: pitches) {
    let capacity = CalibraBreath.computeCapacity(times: times, pitchesHz: pitches)
    print("Breath capacity: \(capacity) seconds")
}

// Get total voiced time
let voicedTime = CalibraBreath.getCumulativeVoicedTime(times: times, pitchesHz: pitches)
print("Total sung time: \(voicedTime) seconds")

Understanding Breath Capacity

Breath capacity represents the longest sustained phrase:

< 3 seconds: Short breath support, needs work
3-5 seconds: Average, typical for beginners
5-8 seconds: Good breath control
> 8 seconds: Excellent, trained singer level

Platform Notes

iOS/Android

Audio must be 16kHz mono
Requires at least 5 seconds of voiced audio for meaningful analysis
Works with pitch contours from any CalibraPitch extractor

Common Pitfalls

Not enough data: Need 5+ seconds of actual singing (not silence)
Wrong pitch format: Use -1 for unvoiced frames (not 0)
Timestamps must match: times and pitchesHz must be same length

Functions

computeCapacity

fun computeCapacity(times: FloatArray, pitchesHz: FloatArray): Float

Compute breath capacity from pitch contour.

computeMetrics

fun computeMetrics(refTimes: FloatArray, refPitchesHz: FloatArray, studentTimes: FloatArray, studentPitchesHz: FloatArray, feedbackSegmentIndices: IntArray, feedbackStartTimes: FloatArray, feedbackEndTimes: FloatArray, refSegmentStarts: FloatArray, refSegmentEnds: FloatArray): BreathMetrics

Compute comprehensive breath metrics comparing student to reference.

getCumulativeVoicedTime