analyze_pitch
Idempotent
Measure pitch accuracy of sung audio by comparing notes to a reference MIDI melody or chosen key, reporting cents deviation, vibrato, note accuracy, and timing alignment.
Instructions
Measures the pitch accuracy of sung audio (solo voice, one melodic line).
Args:
audio: audio path (wav/flac/mp3/m4a) or a name returned by record_audio.
reference_midi: optional path to a .mid with the expected melody. Tolerates singing an
octave up/down, starting at another moment and a somewhat different tempo.
key: optional when there is no MIDI, e.g. "A minor", "G major", "F#" (Spanish names such as
"La menor" also work): each note is compared with the nearest note of that scale.
Without it, with the nearest equal-tempered note.
midi_track: index of the MIDI track to use (default: the non-drum track with most notes).
Returns `summary` (notes, range, pct_within_25_cents, signed mean_deviation_cents,
tendency flat/sharp/centered, drift_cents between 1st and 2nd half, stability counts; with
MIDI also missed, extra_notes, wrong_notes, onsets on_time/late/early, octave_shift,
start_offset_ms and relative_tempo >1 = slower) and `notes`: t (s), dur, note or
expected/sung, cents (+ = sharp), stability (stable | vibrato with vibrato_hz and
vibrato_pp_cents | unstable with std_cents), drift_cents within the note and, with MIDI,
onset_ms/onset; reference notes not sung have status=missed and unmatched sung notes
status=extra. If the list does not fit, the most problematic notes are shown and the rest
is in `full_details`.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | ||
| audio | Yes | ||
| midi_track | No | ||
| reference_midi | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |