analyze
Analyze intonation of a vocal performance.
Computes a pitch histogram, detects scale peaks, maps them to target intervals in the requested tuning system, and measures per-note deviation in cents. Optionally estimates and corrects a global tuning offset before analysis.
Always returns a non-null result. If the analysis itself was inconclusive (fewer than minNotes histogram peaks, or no target intervals matched the requested scale), the returned result carries a non-null IntonationAnalysisResult.error and an empty IntonationAnalysisResult.notes. Passing that result to calculateScore throws; check result.error first.
Return
Non-null IntonationAnalysisResult. Inspect IntonationAnalysisResult.error before using IntonationAnalysisResult.notes or passing to calculateScore.
Parameters
Pitch contour from pitch detection. Must be non-empty.
Tonic frequency in Hz. Must be > 0.
Tuning system to grade against (EQ or JI). Used for tuning-offset alignment and the chromatic neighbor lookup in the deviation% calculation. When scaleIntervals is null, this also selects the multi-octave fallback grid.
Optional explicit list of (cents, label) targets the user is grading against. Multi-octave allowed; labels are used verbatim in the per-note result. null means analyze against the full 12-TET / JI multi-octave grid in the chosen intonationSystem, with chromatic labels derived from noteLabelTradition and tonicHz. If provided, must be non-empty.
Naming tradition for chromatic-fallback note labels (only consulted when scaleIntervals == null). Default NoteLabelTradition.CARNATIC.
If true, estimate and correct a global tuning offset (concert-pitch drift) before analysis. The tonic itself is never modified; only histogram bin centers are shifted. Default true.
Minimum number of histogram peaks (≈ distinct held notes) the contour must contain for the analysis to be considered conclusive. Below this, an inconclusive result is returned with an error set. Default 3 — appropriate for general intonation / melodic-pattern grading. Lower it (down to 1) for sustained-note contexts like tanpura tuning where a single held note is the intended input. Must be ≥ 1.
Throws
if contour is empty, tonicHz <= 0, scaleIntervals is a non-null empty list, or minNotes < 1.