matchmaker

class matchmaker.Matchmaker(score_file: str | bytes | PathLike, performance_file: str | bytes | PathLike | None = None, input_type: str = 'audio', method: str = None, *, stream=None, processor: str = None, device_name_or_index: str | int = None, tempo: float | None = None, wait: bool = False, unfold_score=True, kwargs=None)[source]

Bases: object

A class to perform online score following with I/O support for audio and MIDI

Parameters

score_fileUnion[str, bytes, os.PathLike]

Path to the score file.

performance_fileUnion[str, bytes, os.PathLike, None]

Path to the performance file. If None, live input is used.

input_typestr

Type of input to use: "audio" or "midi".

methodstr

Score following method to use.

streamStream, optional

Custom input stream (e.g. AudioStream / MidiStream or a user subclass). If None, one is built from method defaults.

processorstr, optional

Registered processor name (looked up in the built-in processor registry, overrides kwargs["processor"]). If None, defaults are used based on method.

device_name_or_indexUnion[str, int]

Name or index of the audio/MIDI device. Ignored if performance_file is given.

tempofloat, optional

Tempo in BPM. If None, reads from score; if score has no tempo marking, defaults to 120 BPM.

waitbool (default: False)

Offline mode only. If True, simulates real-time playback speed.

unfold_scorebool (default: True)

If True, unfolds score repeats maximally before processing.

kwargsdict, optional

Method-specific configuration dict. If None, uses built-in defaults for the given input_type and method.

audio keys

  • processor (str): Feature type. Default: "chroma". Choices: "chroma", "mfcc", "cqt", "mel", "lse", "cqt_spectral_flux", "raw_spectrum".

  • sample_rate (int): Sample rate in Hz. Default: 22050.

  • frame_rate (int): Frames per second. Default: 50. Ignored if hop_length is set.

  • hop_length (int): Hop length in samples. Overrides frame_rate.

midi keys

  • processor (str): Feature type. Default: "pitch". Choices: "pitch", "pianoroll", "chord_onset", "pitchclass".

  • piano_range (bool): Restrict pitch to 88-key piano range (MIDI 21-108). Default: True.

  • polling_period (float or None): Window size in seconds for frame-based MIDI accumulation. None = event-based (one note per frame). When set, all note-ons within each window are emitted as one chord observation.

Notes

Matchmaker is a convenience class for the common case of running a registered method (one of AVAILABLE_METHODS). For full control — e.g. a novel score follower, a custom stream, or audio-to-audio alignment without a score — compose Stream + Processor + OnlineAlignment directly. See HOW_TO_MAKE_CUSTOM_SCORE_FOLLOWERS.md.

__init__(score_file: str | bytes | PathLike, performance_file: str | bytes | PathLike | None = None, input_type: str = 'audio', method: str = None, *, stream=None, processor: str = None, device_name_or_index: str | int = None, tempo: float | None = None, wait: bool = False, unfold_score=True, kwargs=None)[source]
run(verbose: bool = True)[source]

Run the score following process.

Yields

float

Beat position in the score (interpolated)

Returns

np.ndarray

Alignment path (2, T): row 0 score beat, row 1 perf time (sec).