Install & Compatibility
Where this runs
tested against v0.8.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 2.765s · 231.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.3s · import 2.624s · 223MB
231MB installed
● package 231MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mir_eval
✓ import mir_eval
The primary import for accessing submodules and evaluation functions.
mir_eval.beat
✓ import mir_eval.beat
Commonly imported submodule for beat tracking evaluation.
mir_eval.onset.evaluate
✓ from mir_eval import onset
scores = onset.evaluate(reference_onsets, estimated_onsets)
✗ from mir_eval.onset import evaluate
scores = evaluate(reference_onsets, estimated_onsets)
While direct import `from mir_eval.onset import evaluate` works, it's generally recommended to import the submodule `onset` and call `onset.evaluate` for consistency and clarity, especially when multiple metrics from the same submodule might be used.
This quickstart demonstrates how to compute beat tracking evaluation metrics using `mir_eval.beat`. It initializes synthetic reference and estimated beat times and then calculates common metrics like F-measure, alternate period accuracy, and the Cemgil metric.
import numpy as np
import mir_eval.beat
# Reference beat times (ground truth)
reference_beats = np.array([0.5, 1.0, 1.5, 2.0, 2.5, 3.0])
# Estimated beat times from an algorithm
estimated_beats = np.array([0.51, 1.02, 1.48, 2.03, 2.55, 3.01])
# Calculate F-measure for beat tracking
f_measure = mir_eval.beat.f_measure(reference_beats, estimated_beats)
# Calculate other beat metrics
alternate_accuracy = mir_eval.beat.alternate_period_accuracy(reference_beats, estimated_beats)
cml_t = mir_eval.beat.cemgil_metric(reference_beats, estimated_beats)
print(f"Beat F-measure: {f_measure:.4f}")
print(f"Alternate Period Accuracy: {alternate_accuracy:.4f}")
print(f"Cemgil Metric (T): {cml_t:.4f}")
Debug
Known issues
breakingOlder versions of `mir_eval` (pre-0.8.0) used deprecated NumPy type aliases like `np.int` and `np.float`. These aliases were deprecated in NumPy 1.20 and removed entirely in NumPy 1.24+ and NumPy 2.0+.fixUpgrade `mir_eval` to version 0.8.0 or newer. If you are stuck on an older `mir_eval` version, you may need to downgrade NumPy to <1.24. Otherwise, update your custom code to use Python built-in types (`int`, `float`) or specific NumPy dtypes (e.g., `np.int64`, `np.float64`) instead of the deprecated aliases.
affects: <0.8.0
gotchaNumPy 2.0 introduced significant changes to its numeric promotion rules, which can affect the precision of results when combining scalars of different types (e.g., `float32` with Python `float`). This could lead to unexpected lower precision or integer overflows in some edge cases.fixReview any operations where `mir_eval` outputs are combined with other NumPy arrays or Python scalars, especially if precision is critical. Explicitly cast to desired dtypes (e.g., `np.float64`) or convert to Python scalars (`int()`, `float()`) before operations to ensure consistent behavior.
affects: All versions when used with NumPy 2.0+
gotchaThe `mir_eval.display` submodule, used for plotting, has had compatibility updates (e.g., in version 0.5, it updated to use Matplotlib 2). Using older `mir_eval` versions with newer Matplotlib or vice versa might lead to plotting errors or unexpected visual outputs.fixEnsure `mir_eval` and `matplotlib` versions are reasonably aligned. For best compatibility, use `mir_eval` 0.5 or newer with `matplotlib` 2.0 or newer. If issues persist, check the `mir_eval` documentation for specific `matplotlib` version requirements if you rely heavily on `mir_eval.display`.
affects: <0.5
Errors
Common errors & fixes
AttributeError: module 'numpy' has no attribute 'int'
This error occurs when using an older version of mir-eval (prior to 0.8.0) with a newer version of NumPy (1.24+ or 2.0+), because NumPy deprecated and removed type aliases like `np.int` and `np.float`.
fixUpgrade `mir-eval` to version 0.8.0 or newer: `pip install --upgrade mir-eval`. Alternatively, downgrade NumPy to a version older than 1.24 (e.g., `pip install numpy==1.23.5`).
ValueError: Reference intervals and pitches have different lengths.
This error arises during transcription evaluation when the provided reference intervals and reference pitches (or estimated intervals and estimated pitches) do not have the same number of entries, indicating a mismatch in the input data's structure.
fixEnsure that the input NumPy arrays for reference/estimated intervals and pitches have matching lengths. For example, if `ref_intervals` has shape `(N, 2)`, then `ref_pitches` must have shape `(N,)`.
ModuleNotFoundError: No module named 'mir_eval'
This error indicates that the `mir-eval` library is not installed in your Python environment or is not accessible via the Python path.
fixInstall the library using pip: `pip install mir-eval` or `python -m pip install mir-eval`.
AttributeError: module 'mir_eval.display' has no attribute 'events'
This error typically occurs due to version incompatibilities between `mir-eval` and `matplotlib`, or if the `events` function within the `mir_eval.display` submodule was moved, renamed, or not available in the installed `mir-eval` version.
fixEnsure both `mir-eval` and `matplotlib` are up-to-date and compatible. Try upgrading `mir-eval` (`pip install --upgrade mir-eval`) and `matplotlib` (`pip install --upgrade matplotlib`). Consult the `mir-eval` documentation for specific `matplotlib` version requirements.
Upgrade
Version history
0.8.2latest on PyPI · released Feb 25, 2025
Audit
Dependencies
numpyrequiredFundamental numerical computing library for array operations.
scipyrequiredScientific computing tools, often used in signal processing and numerical algorithms.
scikit-learnrequiredMachine learning utilities, particularly for clustering or classification tasks used in some metrics.