alignShruti

Compute the practice shruti (tonic) for a student given their natural shruti and the reference lesson key.

Works in pitch class space (mod 12 semitones), so octave differences between student and reference are handled implicitly. Gender is not needed. The algorithm finds the shortest pitch class path between the two frequencies and caps the shift at ±maxFineTuneSemitones.

• If the pitch class difference is within ±maxFineTuneSemitones, the student sings at their own natural shruti.

• If outside the cap, the student's practice shruti is shifted toward the reference pitch class by the maximum allowed amount.

Use the returned ShrutiAlignmentResult.practiceShrutiHz for:

• com.musicmuni.voxatrace.calibra.CalibraLiveEval.setStudentKeyHz — evaluation alignment

• Student pitch visualization (Hz → cents conversion tonic)

The reference contour should still use the original lesson key for its own Hz → cents conversion.

Parameters