wave-roll/dist/lib/evaluation/transcription/metrics.d.ts

JavaScript Library for Comparative MIDI Piano-Roll Visualization

/**
 * Note and velocity-level evaluation metrics.
 *
 * The functions in this module follow the intent of mir_eval's transcription
 * metrics: match notes under onset/pitch/offset tolerances with a unique
 * assignment and compute PRF-style measures. Velocity-aware diagnostics are
 * integrated as a first-class feature while keeping backward-compatible APIs.
 *
 * Reference: https://github.com/mir-evaluation/mir_eval
 */
import { NoteMatchResult } from "./matchNotes";
import { ParsedMidi } from "@/lib/midi/types";
import { TranscriptionToleranceOptions, VelocityToleranceOptions } from "./constants";
export interface NoteMetrics {
    precision: number;
    recall: number;
    f1: number;
    f_measure: number;
    avgOverlapRatio: number;
    numCorrect: number;
    numRef: number;
    numEst: number;
    /** Detailed match pairs between reference and estimated notes */
    matches: NoteMatchResult["matches"];
    /** Unmatched reference indices */
    falseNegatives?: number[];
    /** Unmatched estimated indices */
    falsePositives?: number[];
}
export declare function computeNoteMetrics(reference: ParsedMidi, estimated: ParsedMidi, options?: Partial<TranscriptionToleranceOptions>): NoteMetrics;
export declare function precision_recall_f1_overlap(reference: ParsedMidi, estimated: ParsedMidi, options?: Partial<TranscriptionToleranceOptions>): {
    precision: number;
    recall: number;
    f1: number;
    f_measure: number;
    avgOverlapRatio: number;
};
/**
 * Compute velocity-aware metrics on top of note matching.
 *
 * Two modes are supported:
 * - 'threshold': a match is velocity-correct if |dv| <= tol (normalized or MIDI)
 * - 'weighted': per-pair score = max(0, 1 - |dv|/tol) averaged across matches
 *
 * By default, velocity is NOT used to determine matches (unique assignment is
 * computed using onset/pitch/offset only). Set `velocity.includeInMatching=true`
 * to add a velocity gate in the matching graph.
 */
export declare function computeVelocityMetrics(reference: ParsedMidi, estimated: ParsedMidi, options?: Partial<TranscriptionToleranceOptions>, velocity?: Partial<VelocityToleranceOptions>): NoteMetrics & {
    velocity: {
        mode: VelocityToleranceOptions["mode"];
        toleranceNormalized: number;
        toleranceMidi: number;
        numVelocityCorrect: number;
        accuracyOnMatches: number;
        weightedScoreOnMatches: number;
    };
};
/**
 * Unified evaluation helper that returns both note-level PRF/overlap and
 * velocity-aware diagnostics suitable for visualization.
 */
export declare function evaluateTranscription(reference: ParsedMidi, estimated: ParsedMidi, options?: Partial<TranscriptionToleranceOptions>, velocity?: Partial<VelocityToleranceOptions>): ReturnType<typeof computeVelocityMetrics>;
/**
 * mir_eval-style PRF: onset+pitch only.
 */
export declare function precision_recall_f1(reference_intervals: [number, number][], reference_pitches: number[], estimated_intervals: [number, number][], estimated_pitches: number[], onset_tolerance: number, pitch_tolerance: number): {
    precision: number;
    recall: number;
    f1: number;
    f_measure: number;
};
/**
 * mir_eval-style PRF + average overlap ratio (onset+pitch+offset matching).
 */
export declare function precision_recall_f1_overlap_arrays(reference_intervals: [number, number][], reference_pitches: number[], estimated_intervals: [number, number][], estimated_pitches: number[], onset_tolerance: number, pitch_tolerance: number, offset_ratio_tolerance: number, offset_min_tolerance: number): {
    precision: number;
    recall: number;
    f1: number;
    f_measure: number;
    avgOverlapRatio: number;
};
/**
 * Chroma PRF (onset+chroma pitch only).
 */
export declare function chroma_precision_recall_f1(reference_intervals: [number, number][], reference_pitches: number[], estimated_intervals: [number, number][], estimated_pitches: number[], onset_tolerance: number, pitch_tolerance: number): {
    precision: number;
    recall: number;
    f1: number;
    f_measure: number;
};
/**
 * Chroma PRF + overlap ratio (onset+chroma pitch+offset matching).
 */
export declare function chroma_precision_recall_f1_overlap(reference_intervals: [number, number][], reference_pitches: number[], estimated_intervals: [number, number][], estimated_pitches: number[], onset_tolerance: number, pitch_tolerance: number, offset_ratio_tolerance: number, offset_min_tolerance: number): {
    precision: number;
    recall: number;
    f1: number;
    f_measure: number;
    avgOverlapRatio: number;
};
//# sourceMappingURL=metrics.d.ts.map