pymatchmaker 0.1.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. pymatchmaker-0.5.0/MANIFEST.in +3 -0
  2. pymatchmaker-0.5.0/PKG-INFO +549 -0
  3. pymatchmaker-0.5.0/README.md +497 -0
  4. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/docs/source/conf.py +1 -4
  5. pymatchmaker-0.5.0/matchmaker/__init__.py +44 -0
  6. pymatchmaker-0.5.0/matchmaker/assets/Bach-fugue_bwv_858.match +1556 -0
  7. pymatchmaker-0.5.0/matchmaker/assets/Bach-fugue_bwv_858.mid +0 -0
  8. pymatchmaker-0.5.0/matchmaker/assets/Bach-fugue_bwv_858.mp3 +0 -0
  9. pymatchmaker-0.5.0/matchmaker/assets/Bach-fugue_bwv_858.musicxml +14490 -0
  10. pymatchmaker-0.5.0/matchmaker/assets/Bach-fugue_bwv_858_beat_annotations.txt +136 -0
  11. pymatchmaker-0.5.0/matchmaker/assets/Bach-fugue_bwv_858_note_annotations.txt +522 -0
  12. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1.match +302 -0
  13. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1.mid +0 -0
  14. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1.mp3 +0 -0
  15. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1.musicxml +3120 -0
  16. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1_annotations.txt +48 -0
  17. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1_annotations_trim.txt +17 -0
  18. pymatchmaker-0.5.0/matchmaker/assets/mozart_k265_var1_short_trim.mp3 +0 -0
  19. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_first_two_measures.png +0 -0
  20. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1.match +99 -0
  21. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1.mei +256 -0
  22. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1.mid +0 -0
  23. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1.mp3 +0 -0
  24. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1.musicxml +1126 -0
  25. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1_annotations.txt +16 -0
  26. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1_beat_annotations.txt +16 -0
  27. pymatchmaker-0.5.0/matchmaker/assets/simple_mozart_k265_var1_note_annotations.txt +54 -0
  28. pymatchmaker-0.5.0/matchmaker/base.py +158 -0
  29. pymatchmaker-0.5.0/matchmaker/dp/__init__.py +22 -0
  30. pymatchmaker-0.5.0/matchmaker/dp/dannenberg.py +261 -0
  31. pymatchmaker-0.5.0/matchmaker/dp/direction.py +12 -0
  32. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/dp/dtw_loop.pyx +34 -11
  33. pymatchmaker-0.5.0/matchmaker/dp/oltw_arzt.py +759 -0
  34. pymatchmaker-0.5.0/matchmaker/dp/oltw_arzt_multi_fold.py +386 -0
  35. pymatchmaker-0.5.0/matchmaker/dp/oltw_dixon.py +575 -0
  36. pymatchmaker-0.5.0/matchmaker/external/__init__.py +176 -0
  37. pymatchmaker-0.5.0/matchmaker/features/audio.py +590 -0
  38. pymatchmaker-0.5.0/matchmaker/features/midi.py +622 -0
  39. pymatchmaker-0.5.0/matchmaker/features/processor.py +455 -0
  40. pymatchmaker-0.5.0/matchmaker/io/audio.py +452 -0
  41. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/io/mediator.py +7 -7
  42. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/io/midi.py +192 -17
  43. pymatchmaker-0.5.0/matchmaker/io/queue.py +31 -0
  44. {pymatchmaker-0.1.0/matchmaker/utils → pymatchmaker-0.5.0/matchmaker/io}/stream.py +12 -6
  45. pymatchmaker-0.5.0/matchmaker/matchmaker.py +554 -0
  46. pymatchmaker-0.5.0/matchmaker/methods.yaml +419 -0
  47. pymatchmaker-0.5.0/matchmaker/prob/__init__.py +9 -0
  48. pymatchmaker-0.5.0/matchmaker/prob/hmm.py +2065 -0
  49. pymatchmaker-0.5.0/matchmaker/prob/outer_product_hmm.py +499 -0
  50. pymatchmaker-0.5.0/matchmaker/prob/outer_product_hmm_audio.py +606 -0
  51. pymatchmaker-0.5.0/matchmaker/prob/particle_filter_korzeniowski.py +882 -0
  52. pymatchmaker-0.5.0/matchmaker/prob/skf.py +631 -0
  53. pymatchmaker-0.5.0/matchmaker/prob/templates/pitch_templates_16000_640.npz +0 -0
  54. pymatchmaker-0.5.0/matchmaker/prob/viterbi_step.pyx +63 -0
  55. pymatchmaker-0.5.0/matchmaker/registry.py +628 -0
  56. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/utils/audio.py +28 -11
  57. pymatchmaker-0.5.0/matchmaker/utils/distances.pxd +11 -0
  58. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/utils/distances.pyx +3 -3
  59. pymatchmaker-0.5.0/matchmaker/utils/errors.py +46 -0
  60. pymatchmaker-0.5.0/matchmaker/utils/eval.py +587 -0
  61. pymatchmaker-0.5.0/matchmaker/utils/math.py +46 -0
  62. pymatchmaker-0.5.0/matchmaker/utils/misc.py +406 -0
  63. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/utils/symbolic.py +58 -7
  64. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/utils/tempo_models.py +353 -13
  65. pymatchmaker-0.5.0/matchmaker/utils/typing.py +51 -0
  66. pymatchmaker-0.5.0/pymatchmaker.egg-info/PKG-INFO +549 -0
  67. pymatchmaker-0.5.0/pymatchmaker.egg-info/SOURCES.txt +102 -0
  68. pymatchmaker-0.5.0/pymatchmaker.egg-info/requires.txt +28 -0
  69. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/pymatchmaker.egg-info/top_level.txt +0 -1
  70. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/pyproject.toml +34 -18
  71. pymatchmaker-0.5.0/setup.py +34 -0
  72. pymatchmaker-0.5.0/tests/test_alignment_path.py +64 -0
  73. pymatchmaker-0.5.0/tests/test_base.py +105 -0
  74. pymatchmaker-0.5.0/tests/test_dannenberg.py +292 -0
  75. pymatchmaker-0.5.0/tests/test_external_parangonar.py +57 -0
  76. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_features_audio.py +24 -48
  77. pymatchmaker-0.5.0/tests/test_features_midi.py +320 -0
  78. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_init.py +1 -0
  79. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_io_audio.py +25 -23
  80. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_io_mediator.py +1 -0
  81. pymatchmaker-0.5.0/tests/test_matchmaker_audio.py +90 -0
  82. pymatchmaker-0.5.0/tests/test_matchmaker_midi.py +88 -0
  83. pymatchmaker-0.5.0/tests/test_oltw_arzt.py +409 -0
  84. pymatchmaker-0.5.0/tests/test_oltw_dixon.py +163 -0
  85. pymatchmaker-0.5.0/tests/test_particle_filter_korzeniowski.py +112 -0
  86. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_prob_hmm.py +40 -29
  87. pymatchmaker-0.5.0/tests/test_prob_outer_product_hmm.py +98 -0
  88. pymatchmaker-0.5.0/tests/test_prob_skf.py +129 -0
  89. pymatchmaker-0.5.0/tests/test_register_method.py +152 -0
  90. pymatchmaker-0.5.0/tests/test_registry.py +281 -0
  91. pymatchmaker-0.5.0/tests/test_tempo_models.py +192 -0
  92. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_utils_audio.py +32 -19
  93. pymatchmaker-0.5.0/tests/test_utils_eval_gt.py +41 -0
  94. pymatchmaker-0.5.0/tests/test_utils_eval_sparc.py +175 -0
  95. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_utils_misc.py +3 -3
  96. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_utils_processor.py +3 -2
  97. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_utils_stream.py +3 -3
  98. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/tests/test_utils_symbolic.py +6 -6
  99. pymatchmaker-0.1.0/PKG-INFO +0 -244
  100. pymatchmaker-0.1.0/README.md +0 -203
  101. pymatchmaker-0.1.0/matchmaker/__init__.py +0 -38
  102. pymatchmaker-0.1.0/matchmaker/base.py +0 -26
  103. pymatchmaker-0.1.0/matchmaker/dp/__init__.py +0 -11
  104. pymatchmaker-0.1.0/matchmaker/dp/oltw_arzt.py +0 -295
  105. pymatchmaker-0.1.0/matchmaker/dp/oltw_dixon.py +0 -410
  106. pymatchmaker-0.1.0/matchmaker/features/audio.py +0 -260
  107. pymatchmaker-0.1.0/matchmaker/features/midi.py +0 -350
  108. pymatchmaker-0.1.0/matchmaker/io/audio.py +0 -278
  109. pymatchmaker-0.1.0/matchmaker/matchmaker.py +0 -213
  110. pymatchmaker-0.1.0/matchmaker/prob/__init__.py +0 -6
  111. pymatchmaker-0.1.0/matchmaker/prob/hmm.py +0 -1055
  112. pymatchmaker-0.1.0/matchmaker/utils/misc.py +0 -170
  113. pymatchmaker-0.1.0/matchmaker/utils/processor.py +0 -89
  114. pymatchmaker-0.1.0/matchmaker/utils/typing.py +0 -21
  115. pymatchmaker-0.1.0/pymatchmaker.egg-info/PKG-INFO +0 -244
  116. pymatchmaker-0.1.0/pymatchmaker.egg-info/SOURCES.txt +0 -50
  117. pymatchmaker-0.1.0/pymatchmaker.egg-info/requires.txt +0 -22
  118. pymatchmaker-0.1.0/setup.py +0 -24
  119. pymatchmaker-0.1.0/tests/test_base.py +0 -31
  120. pymatchmaker-0.1.0/tests/test_features_midi.py +0 -486
  121. pymatchmaker-0.1.0/tests/test_io_midi.py +0 -438
  122. pymatchmaker-0.1.0/tests/test_matchmaker.py +0 -149
  123. pymatchmaker-0.1.0/tests/test_oltw_arzt.py +0 -162
  124. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/LICENSE +0 -0
  125. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/features/__init__.py +0 -0
  126. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/io/__init__.py +0 -0
  127. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/matchmaker/utils/__init__.py +0 -0
  128. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/pymatchmaker.egg-info/dependency_links.txt +0 -0
  129. {pymatchmaker-0.1.0 → pymatchmaker-0.5.0}/setup.cfg +0 -0
@@ -0,0 +1,3 @@
1
+ # Cython sources for building from the sdist. setuptools picks up the .pyx
2
+ # files from setup.py, but not the .pxd declarations next to them.
3
+ recursive-include matchmaker *.pyx *.pxd
@@ -0,0 +1,549 @@
1
+ Metadata-Version: 2.4
2
+ Name: pymatchmaker
3
+ Version: 0.5.0
4
+ Summary: A package for real-time music alignment
5
+ Author-email: Matchmaker Development Team <carloscancinochacon@gmail.com>
6
+ License: Apache 2.0
7
+ Project-URL: Homepage, https://github.com/pymatchmaker/matchmaker
8
+ Keywords: music,alignment,midi,audio
9
+ Classifier: License :: OSI Approved :: Apache Software License
10
+ Classifier: Programming Language :: Python
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Cython
17
+ Classifier: Programming Language :: Python :: Implementation :: CPython
18
+ Classifier: Programming Language :: Python :: Implementation :: PyPy
19
+ Classifier: Topic :: Multimedia :: Sound/Audio
20
+ Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Requires-Python: <3.14,>=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: cython>=3.0.10
26
+ Requires-Dist: numpy>=1.26.3
27
+ Requires-Dist: scipy>=1.11.4
28
+ Requires-Dist: librosa>=0.10.1
29
+ Requires-Dist: pandas>=2.0.0
30
+ Requires-Dist: partitura>=1.9.0
31
+ Requires-Dist: progressbar2>=4.2.0
32
+ Requires-Dist: python-hiddenmarkov>=0.1.4
33
+ Requires-Dist: matplotlib>=3.9.4
34
+ Requires-Dist: parangonar[accelerated]>=3.4.1
35
+ Requires-Dist: mido>=1.3.2
36
+ Requires-Dist: pyfluidsynth>=1.3.3
37
+ Requires-Dist: pyyaml>=6.0
38
+ Provides-Extra: devices
39
+ Requires-Dist: pyaudio>=0.2.14; extra == "devices"
40
+ Requires-Dist: python-rtmidi>=1.5.8; extra == "devices"
41
+ Provides-Extra: dev
42
+ Requires-Dist: pymatchmaker[devices]; extra == "dev"
43
+ Requires-Dist: pytest>=7.0; extra == "dev"
44
+ Requires-Dist: pytest-timeout>=2.0; extra == "dev"
45
+ Requires-Dist: black>=23.12.1; extra == "dev"
46
+ Requires-Dist: isort>=5.13.2; extra == "dev"
47
+ Requires-Dist: pre-commit>=3.6.0; extra == "dev"
48
+ Requires-Dist: ipython>=8.12.0; extra == "dev"
49
+ Requires-Dist: pyclean>=3.0.0; extra == "dev"
50
+ Requires-Dist: ruff>=0.8.2; extra == "dev"
51
+ Dynamic: license-file
52
+
53
+ # Matchmaker
54
+
55
+ [![GitHub release](https://img.shields.io/github/v/release/pymatchmaker/matchmaker)](https://github.com/pymatchmaker/matchmaker/releases)
56
+ [![PyPI version](https://img.shields.io/pypi/v/pymatchmaker)](https://pypi.org/project/pymatchmaker/)
57
+ [![Unit Tests](https://github.com/pymatchmaker/matchmaker/actions/workflows/unittest.yml/badge.svg)](https://github.com/pymatchmaker/matchmaker/actions/workflows/unittest.yml)
58
+
59
+ Matchmaker is a Python library for real-time music alignment.
60
+
61
+ Music alignment is a fundamental MIR task, and real-time music alignment is a necessary component of many interactive applications (e.g., automatic accompaniment systems, automatic page turning).
62
+
63
+ Unlike offline alignment methods, for which state-of-the-art implementations are publicly available, real-time (online) methods have no standard implementation, forcing researchers and developers to build them from scratch for their projects.
64
+
65
+ We aim to provide efficient reference implementations of score followers for use in real-time applications which can be easily integrated into existing projects.
66
+
67
+ The full documentation for matchmaker is available online at [readthedocs.org](https://pymatchmaker.readthedocs.io/).
68
+
69
+ ## Setup
70
+
71
+ **Python version:** 3.10, 3.11, 3.12, 3.13
72
+
73
+ Choose the installation that fits your use case:
74
+
75
+ | I want to... | Install |
76
+ |---|---|
77
+ | Get started quickly — test with recorded audio or MIDI files | `pip install pymatchmaker` |
78
+ | Use a locally connected microphone or MIDI keyboard | `pip install pymatchmaker[devices]` |
79
+ | Develop or contribute to matchmaker | `pip install -e ".[dev]"` (see below) |
80
+
81
+ ### Option 1: Base install
82
+
83
+ ```bash
84
+ pip install pymatchmaker
85
+ ```
86
+
87
+ Supports **simulation mode**: run online alignment against recorded audio or MIDI performance files.
88
+
89
+ > **Note:** Requires [Fluidsynth](https://www.fluidsynth.org/) to be installed on your system:
90
+ > ```bash
91
+ > conda install -c conda-forge fluidsynth
92
+ > ```
93
+ >
94
+ > conda-forge has no Fluidsynth package for Windows; see [Installing Fluidsynth on Windows](#installing-fluidsynth-on-windows).
95
+
96
+ ### Option 2: Live device support
97
+
98
+ ```bash
99
+ pip install pymatchmaker[devices]
100
+ ```
101
+
102
+ Adds [PyAudio](https://pypi.org/project/PyAudio/) and [python-rtmidi](https://pypi.org/project/python-rtmidi/) for real-time input from a locally connected microphone or MIDI keyboard.
103
+
104
+ > **Note:** `pyaudio` requires [PortAudio](http://www.portaudio.com/) to be installed on your system:
105
+ > ```bash
106
+ > conda install -c conda-forge fluidsynth portaudio
107
+ > ```
108
+ >
109
+ > On Windows, the `pyaudio` wheels already include PortAudio, so only Fluidsynth is needed.
110
+
111
+ ### Option 3: Development install (from source)
112
+
113
+ For contributors or anyone who wants to modify the source code. Requires [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).
114
+
115
+ ```bash
116
+ # Clone the repository
117
+ git clone https://github.com/pymatchmaker/matchmaker.git
118
+ cd matchmaker
119
+
120
+ # Create and activate a conda environment
121
+ conda create -n matchmaker python=3.12
122
+ conda activate matchmaker
123
+
124
+ # Install system dependencies (Linux and macOS; on Windows, see below)
125
+ conda install -c conda-forge gcc=12.1.0 glib fluidsynth portaudio
126
+
127
+ # Install matchmaker in editable mode with all dev dependencies (includes [devices])
128
+ pip install -e ".[dev]"
129
+ ```
130
+
131
+ On Windows, skip the system dependencies step: conda-forge has neither `gcc=12.1.0` nor Fluidsynth for Windows, and none of these packages are needed there. Instead, install the [Visual C++ build tools](#missing-visual-c-build-tools-on-windows) to compile the Cython extensions and [install Fluidsynth from its release ZIP](#installing-fluidsynth-on-windows). The rest of the steps are the same, in a conda environment or a plain `venv`.
132
+
133
+ > **Note:** `partitura` will download `MuseScore_General.sf3` (a free soundfont) on first use. This may take a moment.
134
+
135
+ ### Known Setup Issues
136
+
137
+ #### Missing Visual C++ build tools (on Windows)
138
+
139
+ Building from source (`pip install -e .`, or the sdist) fails with `Microsoft Visual C++ 14.0 or greater is required` if no C++ compiler is installed. Having Visual Studio installed is not enough; it also needs the C++ workload. Install the build tools with winget:
140
+
141
+ ```bash
142
+ winget install --id Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
143
+ ```
144
+
145
+ Or download `vs_BuildTools.exe` from <https://visualstudio.microsoft.com/visual-cpp-build-tools/> and run:
146
+
147
+ ```bash
148
+ vs_buildtools.exe --norestart --passive --downloadThenInstall --includeRecommended --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Workload.MSBuildTools
149
+ ```
150
+
151
+ #### Installing Fluidsynth on Windows
152
+
153
+ Without Fluidsynth, `import fluidsynth` raises `ImportError("Couldn't find the FluidSynth library.")`. pyfluidsynth looks for `libfluidsynth-3.dll` in `C:\tools\fluidsynth\bin` and on `PATH`:
154
+
155
+ 1. Download the ZIP for your architecture (e.g. `fluidsynth-v2.6.1-win10-x64-cpp11.zip`) from <https://github.com/FluidSynth/fluidsynth/releases/latest>.
156
+ 2. Extract it and rename the extracted folder (e.g. `fluidsynth-v2.6.1-win10-x64-cpp11`) to `C:\tools\fluidsynth`, so that the DLL is at `C:\tools\fluidsynth\bin\libfluidsynth-3.dll`. Alternatively, put the folder anywhere and add its `bin` directory to `PATH`.
157
+ 3. Check with `python -c "import fluidsynth"`.
158
+
159
+ With [Chocolatey](https://chocolatey.org/), `choco install fluidsynth` installs it to `C:\tools\fluidsynth` as well.
160
+
161
+ #### Using Fluidsynth installed from Homebrew on macOS
162
+
163
+ We recommend installing Fluidsynth via conda in a dedicated environment. If you use the Homebrew-installed Fluidsynth instead, you may encounter `ImportError("Couldn't find the FluidSynth library.")` with `pyfluidsynth`. See this [Stack Overflow answer](https://stackoverflow.com/a/75339618) for a fix.
164
+
165
+ ## Usage Examples
166
+
167
+ ### Quickstart (simulation mode)
168
+
169
+ You can test the alignment with a score and a performance file. No extra dependencies needed beyond the base install.
170
+
171
+ ```python
172
+ from matchmaker import Matchmaker
173
+
174
+ mm = Matchmaker(
175
+ score_file="path/to/score.musicxml",
176
+ performance_file="path/to/performance.wav",
177
+ input_type="audio",
178
+ )
179
+ for current_position in mm.run():
180
+ print(current_position) # beat position in the score
181
+ ```
182
+
183
+ The returned value is the current position in the score, represented in beats defined by `partitura` library's note array system.
184
+ Specifically, each position is calculated for every frame input and interpolated within the score's `onset_beat` array.
185
+ Please refer to [here](https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html) for more information about the `onset_beat` concept.
186
+
187
+ ### Live streaming (requires `[devices]`)
188
+
189
+ To run with a live audio or MIDI input, install with `pip install pymatchmaker[devices]`.
190
+
191
+ ```python
192
+ mm = Matchmaker(
193
+ score_file="path/to/score.musicxml",
194
+ input_type="audio",
195
+ device_name_or_index="MacBookPro Microphone",
196
+ )
197
+ for current_position in mm.run():
198
+ print(current_position)
199
+ ```
200
+
201
+ If no device is specified, the system default is used.
202
+
203
+ ```python
204
+ from matchmaker import Matchmaker
205
+
206
+ # Audio input
207
+ mm = Matchmaker(
208
+ score_file="path/to/score.musicxml",
209
+ input_type="audio",
210
+ )
211
+
212
+ # MIDI input
213
+ mm = Matchmaker(
214
+ score_file="path/to/score.musicxml",
215
+ input_type="midi",
216
+ )
217
+ ```
218
+
219
+
220
+ ### Streaming from a non-device source (`BytesAudioStream` / `BytesMidiStream`)
221
+
222
+ For input that does not come from a local audio / MIDI device (a WebSocket
223
+ handler forwarding browser data, a subprocess, an IPC pipe, etc.), use the
224
+ built-in `BytesAudioStream` and `BytesMidiStream` classes. Both pull raw
225
+ `bytes` chunks from a `queue.Queue` you control and feed them through the
226
+ same processor pipeline as the device-backed streams. No `pyaudio` or
227
+ `python-rtmidi` install is required.
228
+
229
+ **Audio.** The producer pushes raw `float32` PCM bytes (one `hop_length`
230
+ chunk per item), followed by `None` to end the stream:
231
+
232
+ ```python
233
+ import queue
234
+ from matchmaker import Matchmaker
235
+ from matchmaker.io.audio import BytesAudioStream
236
+ from matchmaker.features.audio import ChromagramProcessor
237
+
238
+ data_queue = queue.Queue()
239
+
240
+ # In a producer thread (e.g. WebSocket handler):
241
+ # data_queue.put(pcm_chunk_bytes) # float32 PCM, hop_length samples
242
+ # ...
243
+ # data_queue.put(None) # end of stream
244
+
245
+ stream = BytesAudioStream(
246
+ processor=ChromagramProcessor(sample_rate=22050, hop_length=441),
247
+ sample_rate=22050,
248
+ hop_length=441,
249
+ data_queue=data_queue,
250
+ )
251
+ mm = Matchmaker(
252
+ score_file="path/to/score.musicxml",
253
+ input_type="audio",
254
+ stream=stream,
255
+ )
256
+ for current_position in mm.run():
257
+ print(current_position)
258
+ ```
259
+
260
+ **MIDI.** The producer pushes raw MIDI bytes (e.g. 3 bytes per `note_on` /
261
+ `note_off`, exactly what the Web MIDI API gives you):
262
+
263
+ ```python
264
+ import queue
265
+ from matchmaker import Matchmaker
266
+ from matchmaker.io.midi import BytesMidiStream
267
+ from matchmaker.features.midi import PitchProcessor
268
+
269
+ data_queue = queue.Queue()
270
+
271
+ # In a producer thread:
272
+ # data_queue.put(midi_bytes) # e.g. bytes([0x90, 60, 100])
273
+ # ...
274
+ # data_queue.put(None)
275
+
276
+ stream = BytesMidiStream(processor=PitchProcessor(), data_queue=data_queue)
277
+ mm = Matchmaker(
278
+ score_file="path/to/score.musicxml",
279
+ input_type="midi",
280
+ stream=stream,
281
+ )
282
+ for current_position in mm.run():
283
+ print(current_position)
284
+ ```
285
+
286
+ The browser side just forwards what Web MIDI API hands it:
287
+
288
+ ```javascript
289
+ const midiAccess = await navigator.requestMIDIAccess();
290
+ midiAccess.inputs.forEach((input) => {
291
+ input.onmidimessage = (event) => {
292
+ // event.data is a Uint8Array (typically 3 bytes for note_on / note_off)
293
+ ws.send(event.data); // forward as a binary WebSocket frame
294
+ };
295
+ });
296
+ ```
297
+
298
+ The Python WebSocket handler reads the binary frame and calls
299
+ `data_queue.put(message_bytes)`. No JSON / dict / base64 conversion is
300
+ needed at any layer.
301
+
302
+
303
+ ### Running Examples
304
+
305
+ The repository includes a ready-to-use example script that demonstrates the complete workflow:
306
+
307
+ ```bash
308
+ # Run with input type (uses default method by each input)
309
+ python run_examples.py --audio
310
+
311
+ # Run with specific method
312
+ python run_examples.py --midi --method hmm
313
+ ```
314
+
315
+ This script runs a complete example with score following and evaluation, saving results to the `results/` directory.
316
+
317
+ #### Evaluation output
318
+
319
+ | Field | Meaning |
320
+ | --- | --- |
321
+ | `mean_b`, `median_b`, `std_b` | Mean, median, and standard deviation of the absolute score-position error, in beats. |
322
+ | `accuracy_0.05b`, `accuracy_0.1b`, `accuracy_0.3b`, `accuracy_0.5b`, `accuracy_1b`, `accuracy_2b` | Fraction of annotated onsets within each beat-error tolerance. |
323
+ | `skewness`, `kurtosis` | Unitless statistics describing the asymmetry and tail weight of the signed score-position error distribution. |
324
+ | `smoothness` | Trajectory smoothness measured with SPARC. Higher (less negative) values indicate smoother motion. |
325
+ | `rtf` | Alignment runtime divided by the annotated performance span. Lower values mean faster processing. |
326
+ | `feature_latency_ms`, `inference_latency_ms` | Mean feature-extraction and inference time per frame, in milliseconds; reported for audio input. |
327
+
328
+ `matchmaker.utils.eval.evaluate_alignment()` returns the accuracy and smoothness fields directly; the example script adds runtime and latency measurements.
329
+
330
+ `smoothness` measures the smoothness of the alignment path using [SPARC (Spectral Arc Length)](https://pmc.ncbi.nlm.nih.gov/articles/PMC4674971/), with higher (less negative) values indicating smoother tracking.
331
+ Smoothness depends on how positions are reported; compare values only within the same input type (audio or MIDI).
332
+
333
+ ### Testing with Different Methods or Features
334
+
335
+ You can specify the alignment method and feature processor as follows:
336
+
337
+ ```python
338
+ from matchmaker import Matchmaker
339
+
340
+ mm = Matchmaker(
341
+ score_file="path/to/score",
342
+ input_type="audio",
343
+ method="arzt", # see Alignment Methods section
344
+ processor="chroma", # see Features section
345
+ )
346
+ for current_position in mm.run():
347
+ print(current_position)
348
+ ```
349
+
350
+ For options regarding the `method`, please refer to the [Alignment Methods](#alignment-methods) section.
351
+ For options regarding the `processor`, please refer to the [Features](#features) section.
352
+
353
+
354
+ ## Package Overview
355
+
356
+ Matchmaker has the following pipeline:
357
+
358
+ ```
359
+ input source Stream Processor OnlineAlignment
360
+ (audio/MIDI (chroma, (e.g.,
361
+ file or live) ─► AudioStream ─► pitch, ─► PitchHMM, ─► alignment_path
362
+ MidiStream ...) OLTWArzt, ...) (2, T) array
363
+ ```
364
+
365
+ ### Component signatures
366
+
367
+ - **`Stream`** (`AudioStream`, `MidiStream`) reads from a file or live
368
+ device, hands each frame to its Processor, and pushes the result to a
369
+ `RECVQueue`, followed by a `STREAM_END` sentinel when the source is
370
+ exhausted.
371
+
372
+ - **`Processor`** (e.g., `ChromagramProcessor`, `PitchProcessor`) takes
373
+ a `(data, frame_time)` tuple and returns either a `(features, perf_time)`
374
+ tuple or `None` while buffering. `data` is `np.ndarray` for audio or
375
+ `List[(mido.Message, m_time)]` for MIDI; `perf_time` is the timestamp the
376
+ feature corresponds to (most processors pass `frame_time` through; MIDI
377
+ processors that emit note or chord observations, such as `PitchProcessor`
378
+ and `ChordOnsetProcessor`, stamp it with the first note-on time).
379
+
380
+ - **`OnlineAlignment`** (the score follower base class; e.g.,
381
+ `OnlineTimeWarpingArzt`, `PitchIOIHMM`) consumes `(features, perf_time)`
382
+ observations from the queue (or directly via `__call__`), updates its
383
+ score position per step, and yields the current beat. On stream end it
384
+ returns the final `alignment_path` — a `(2, T)` `np.ndarray` of
385
+ `(perf_time, score_beat)` pairs.
386
+
387
+ `STREAM_END` is a module-level sentinel (not a tuple); `OnlineAlignment.run()`
388
+ checks for it and exits the read loop.
389
+
390
+ ### Score representation
391
+
392
+ The example score `matchmaker/assets/simple_mozart_k265_var1.musicxml` is
393
+ used in tests and the contribution guide. The first two measures:
394
+
395
+ <p align="center">
396
+ <img src="./matchmaker/assets/simple_mozart_first_two_measures.png" width="60%">
397
+ </p>
398
+
399
+ Beat positions follow the `onset_beat` field of partitura's `note_array()`,
400
+ whose unit is the score's denominator (the quarter note for this 2/4 piece).
401
+ Notes start at beats `0.00, 0.25, 0.50, 0.75, 1.00, ...`.
402
+
403
+ ```python
404
+ import numpy as np
405
+ import partitura as pt
406
+
407
+ score = pt.load_score("matchmaker/assets/simple_mozart_k265_var1.musicxml")
408
+ note_array = score[0].note_array()
409
+ score_positions = np.unique(note_array["onset_beat"])
410
+ # array([0. , 0.25, 0.5 , 0.75, 1. , ..., 13.25, 13.5 ]) shape (54,)
411
+ ```
412
+
413
+ If a score follower reaches the third unique onset:
414
+ ```python
415
+ follower.current_index # 2
416
+ follower.current_position # 0.5 (= score_positions[2])
417
+ ```
418
+
419
+ ## Alignment Methods
420
+
421
+ Methods and processors are declared in
422
+ [`matchmaker/methods.yaml`](matchmaker/methods.yaml) — the authoritative list is
423
+ `matchmaker.AVAILABLE_METHODS`. Adding one is described in
424
+ [HOW_TO_MAKE_CUSTOM_SCORE_FOLLOWERS.md](HOW_TO_MAKE_CUSTOM_SCORE_FOLLOWERS.md).
425
+
426
+ ### Audio (`input_type="audio"`)
427
+
428
+ Default method: `"arzt"`
429
+
430
+ | Method | Description |
431
+ |---|---|
432
+ | `"arzt"` | On-line time warping by Arzt et al. (2008), extending Dixon (2005) |
433
+ | `"dixon"` | On-line time warping by Dixon (2005) |
434
+ | `"outerhmm"` | Two-level HMM with repeats and skips by Nakamura et al. (2016) |
435
+ | `"skf"` | Switching Kalman Filter with hidden tempo by Jiang and Raphael (2020) |
436
+ | `"arzt_tempo"` | On-line time warping by Arzt with a tempo model (Arzt and Widmer, 2010) |
437
+ | `"arzt_multi_fold"` | Arzt OLTW tracking several unfolded score variants in parallel |
438
+ | `"pfkorz"` | Particle filter score follower by Korzeniowski et al. (2013) |
439
+
440
+ ### MIDI (`input_type="midi"`)
441
+
442
+ Default method: `"pthmm"`
443
+
444
+ | Method | Description |
445
+ |---|---|
446
+ | `"arzt"` | On-line time warping by Arzt et al. (2008), extending Dixon (2005) |
447
+ | `"dixon"` | On-line time warping by Dixon (2005) |
448
+ | `"outerhmm"` | Outer-product HMM score follower by Nakamura et al. (2014) |
449
+ | `"hmm"` | HMM score follower by Cancino-Chacón et al. (2023) |
450
+ | `"pthmm"` | Pitch-based HMM score follower |
451
+ | `"pfkorz"` | Particle filter score follower by Korzeniowski et al. (2013) |
452
+ | `"SL_OLTW"` | Symbolic-level OLTW note matcher from [parangonar](https://github.com/sildater/parangonar) (Peter et al., 2025) |
453
+ | `"SLT_OLTW"` | Symbolic-level OLTW note matcher with tempo, from parangonar (Peter et al., 2025) |
454
+ | `"OTM"` | Online transformer note matcher from parangonar (Peter, 2023) |
455
+ | `"OPTM"` | Online pure-transformer note matcher from parangonar (Peter, 2023) |
456
+
457
+ The parangonar methods match one performed note at a time, so they always run
458
+ event-based (no MIDI polling).
459
+
460
+ ## Features
461
+
462
+ ### Audio (`input_type="audio"`)
463
+
464
+ Default processor: `"chroma"`. Some methods default to their own processor
465
+ (e.g. `"dixon"` → `"lse"`); see `default_kwargs` in `methods.yaml`.
466
+
467
+ | Processor | Description |
468
+ |---|---|
469
+ | `"chroma"` | Chroma features |
470
+ | `"mfcc"` | Mel-frequency cepstral coefficients |
471
+ | `"cqt"` | Constant-Q transform |
472
+ | `"mel"` | Mel-spectrogram |
473
+ | `"lse"` | Log-spectral energy features used in Dixon (2005) |
474
+ | `"cqt_spectral_flux"` | CQT-based spectral flux used in Nakamura et al. (2016) |
475
+ | `"raw_spectrum"` | Raw power spectrum used in Jiang and Raphael (2020) |
476
+ | `"korzeniowski"` | Spectral observations for the Korzeniowski et al. (2013) particle filter |
477
+
478
+ ### MIDI (`input_type="midi"`)
479
+
480
+ Default processor: `"pitch"`. Some methods default to their own processor
481
+ (e.g. MIDI `"arzt"` / `"dixon"` → `"chord_onset"`).
482
+
483
+ | Processor | Description |
484
+ |---|---|
485
+ | `"pitch"` | Binary pitch vector of the note-ons in each MIDI frame (a chord when MIDI polling groups notes) |
486
+ | `"chord_onset"` | Binary pitch vector per chord, merging note-ons that arrive within 35 ms |
487
+ | `"pianoroll"` | Piano-roll of the notes held in each frame |
488
+ | `"pitchclass"` | Pitch-class (12-bin) piano-roll |
489
+ | `"korzeniowski"` | Note observations for the Korzeniowski et al. (2013) particle filter |
490
+ | `"parangonar"` | One partitura note-array row per performed note, for the parangonar methods |
491
+
492
+ ## Configurations
493
+
494
+ Initialization parameters for the `Matchmaker` class:
495
+
496
+ | Parameter | Type | Default | Description |
497
+ |---|---|---|---|
498
+ | `score_file` | str | | Path to the score file (`.musicxml`, `.mid`, etc.) |
499
+ | `performance_file` | str or None | `None` | Path to a recorded performance file for simulation mode. If `None`, live device input is used. |
500
+ | `input_type` | str | `"audio"` | Input modality. Options: `"audio"`, `"midi"`. |
501
+ | `method` | str or None | `None` | Alignment method. Defaults to `"arzt"` for audio, `"pthmm"` for MIDI. See [Alignment Methods](#alignment-methods). |
502
+ | `processor` | str or None | `None` | Feature processor. Defaults to the method's own processor, else `"chroma"` for audio and `"pitch"` for MIDI. See [Features](#features). |
503
+ | `kwargs` | dict or None | `None` | Method-specific parameters (e.g., `window_size`, `sample_rate`, `frame_rate`). If `None`, built-in defaults for the chosen method are used. |
504
+ | `stream` | Stream or None | `None` | Custom `Stream` instance for external input sources (e.g., WebSocket). If `None`, the stream is built automatically from `input_type`. |
505
+ | `device_name_or_index` | str or int or None | `None` | Audio/MIDI device name or index for live input. Requires `pymatchmaker[devices]`. |
506
+ | `tempo` | float or None | `None` | Initial tempo in BPM for score rendering. If `None`, inferred from the score. |
507
+ | `wait` | bool | `False` | Audio simulation mode only. If `True`, the performance file is streamed at real-time speed instead of as fast as possible. |
508
+ | `unfold_score` | bool | `True` | If `True`, unfold repeat signs in the score before alignment. |
509
+
510
+ ## Contributing
511
+
512
+ For issues, branches and pull requests, see [CONTRIBUTING.md](CONTRIBUTING.md).
513
+ If you want to add a new score follower, please refer to [HOW_TO_MAKE_CUSTOM_SCORE_FOLLOWERS.md](HOW_TO_MAKE_CUSTOM_SCORE_FOLLOWERS.md)
514
+ for the `OnlineAlignment` interface, boilerplate, and audio/MIDI tips.
515
+ The same guide is also available in the [online docs](https://pymatchmaker.readthedocs.io/en/latest/contribute.html).
516
+
517
+ ## Citing Matchmaker
518
+
519
+ If you find Matchmaker useful, we would appreciate if you could cite us!
520
+
521
+ ```bibtex
522
+ @inproceedings{park_matchmaker_2025,
523
+ title = {{Matchmaker}: An Open-Source Library for Real-Time Piano Score Following and Systematic Evaluation},
524
+ booktitle = {Proceedings of the 26th International Society for Music Information Retrieval Conference ({ISMIR})},
525
+ author = {Park, Jiyun and Cancino-Chac{\'o}n, Carlos and Chiruthapudi, Suhit and Nam, Juhan},
526
+ address = {Daejeon, South Korea},
527
+ year = {2025}
528
+ }
529
+ ```
530
+
531
+ ```bibtex
532
+ @inproceedings{matchmaker_lbd,
533
+ title = {{Matchmaker}: A {Python} Library for Real-Time Music Alignment},
534
+ booktitle = {Proceedings of the Late Breaking/Demo Session at the 25th International Society for Music Information Retrieval Conference ({ISMIR})},
535
+ author = {Park, Jiyun and Cancino-Chac{\'o}n, Carlos and Kwon, Taegyun and Nam, Juhan},
536
+ address = {San Francisco, USA},
537
+ year = {2024}
538
+ }
539
+ ```
540
+
541
+
542
+
543
+ ## Acknowledgments
544
+
545
+ This work has been supported by the Austrian Science Fund (FWF), grant agreement PAT 8820923 (Rach3: A Computational Approach to Study Piano Rehearsals) and PIN 1347924 (AURA: Augmenting musical interaction via EVAs), as well as by the European Research Council (ERC) under the EU’s Horizon 2020 research & innovation programme, grant agreement No.101019375 (Whither Music?), and by the National Research Foundation of Korea (NRF) grant funded by the Korea government (MSIT) under Grant RS-2023-NR077289.
546
+
547
+ ## License
548
+
549
+ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.