muspy.inputs

Input interfaces.

This module provides input interfaces for common symbolic music formats, MusPy’s native JSON and YAML formats, other symbolic music libraries and commonly-used representations in music generation.

Functions

• from_event_representation

• from_mido

• from_music21

• from_music21_opus

• from_note_representation

• from_object

• from_pianoroll_representation

• from_pitch_representation

• from_pretty_midi

• from_pypianoroll

• from_representation

• load

• load_json

• load_yaml

• read

• read_abc

• read_abc_string

• read_midi

• read_musescore

• read_musicxml

Errors

• MIDIError

• MusicXMLError

exception muspy.inputs.MIDIError

An error class for MIDI related exceptions.

exception muspy.inputs.MuseScoreError

A class for MuseScore related errors.

exception muspy.inputs.MusicXMLError

An error class for MusicXML related exceptions.

muspy.inputs.from_event_representation(array, resolution=24, program=0, is_drum=False, use_single_note_off_event=False, use_end_of_sequence_event=False, max_time_shift=100, velocity_bins=32, default_velocity=64, duplicate_note_mode='fifo')

Decode event-based representation into a Music object.

Parameters

• array (ndarray) – Array in event-based representation to decode.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

• program (int, default: 0 (Acoustic Grand Piano)) – Program number, according to General MIDI specification [1]. Valid values are 0 to 127.

• is_drum (bool, default: False) – Whether it is a percussion track.

• use_single_note_off_event (bool, default: False) – Whether to use a single note-off event for all the pitches. If True, a note-off event will close all active notes, which can lead to lossy conversion for polyphonic music.

• use_end_of_sequence_event (bool, default: False) – Whether to append an end-of-sequence event to the encoded sequence.

• max_time_shift (int, default: 100) – Maximum time shift (in ticks) to be encoded as an separate event. Time shifts larger than max_time_shift will be decomposed into two or more time-shift events.

• velocity_bins (int, default: 32) – Number of velocity bins to use.

• default_velocity (int, default: muspy.DEFAULT_VELOCITY (64)) – Default velocity value to use when decoding.

• duplicate_note_mode ({'fifo', 'lifo', 'all'}, default: 'fifo') –

  Policy for dealing with duplicate notes. When a note off event is presetned while there are multiple correspoding note on events that have not yet been closed, we need a policy to decide which note on messages to close. This is only effective when use_single_note_off_event is False.

  • ’fifo’ (first in first out): close the earliest note on

  • ’lifo’ (first in first out): close the latest note on

  • ’all’: close all note on messages

Returns

Decoded Music object.

Return type

muspy.Music

References

[1] https://www.midi.org/specifications/item/gm-level-1-sound-set

muspy.inputs.from_mido(midi, duplicate_note_mode='fifo')

Return a mido MidiFile object as a Music object.

Parameters

• midi (mido.MidiFile) – Mido MidiFile object to convert.

• duplicate_note_mode ({'fifo', 'lifo', 'all'}, default: 'fifo') –

  Policy for dealing with duplicate notes. When a note off message is presetned while there are multiple correspoding note on messages that have not yet been closed, we need a policy to decide which note on messages to close.

  • ’fifo’ (first in first out): close the earliest note on

  • ’lifo’ (first in first out): close the latest note on

  • ’all’: close all note on messages

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.from_music21(stream, resolution=24)

Return a music21 Stream object as Music or Track object(s).

Parameters

• stream (music21.stream.Stream) – Stream object to convert.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Converted Music or Track object(s).

Return type

muspy.Music or muspy.Track

muspy.inputs.from_music21_opus(opus, resolution=24)

Return a music21 Opus object as a list of Music objects.

Parameters

• opus (music21.stream.Opus) – Opus object to convert.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.from_music21_part(part, resolution=24)

Return a music21 Part object as Track object(s).

Parameters

• part (music21.stream.Part) – Part object to parse.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Parsed track(s).

Return type

muspy.Track or list of muspy.Track

muspy.inputs.from_music21_score(score, resolution=24)

Return a music21 Stream object as a Music object.

Parameters

• score (music21.stream.Score) – Score object to convert.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.from_note_representation(array, resolution=24, program=0, is_drum=False, use_start_end=False, encode_velocity=True, default_velocity=64)

Decode note-based representation into a Music object.

Parameters

• array (ndarray) – Array in note-based representation to decode.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

• program (int, default: 0 (Acoustic Grand Piano)) – Program number, according to General MIDI specification [1]. Valid values are 0 to 127.

• is_drum (bool, default: False) – Whether it is a percussion track.

• use_start_end (bool, default: False) – Whether to use ‘start’ and ‘end’ to encode the timing rather than ‘time’ and ‘duration’.

• encode_velocity (bool, default: True) – Whether to encode note velocities.

• default_velocity (int, default: muspy.DEFAULT_VELOCITY (64)) – Default velocity value to use when decoding. Only used when encode_velocity is True.

Returns

Decoded Music object.

Return type

muspy.Music

References

[1] https://www.midi.org/specifications/item/gm-level-1-sound-set

muspy.inputs.from_object(obj, **kwargs)

Return an outside object as a Music object.

Parameters

• obj – Object to convert. Supported objects are music21.Stream, mido.MidiTrack, pretty_midi.PrettyMIDI, and pypianoroll.Multitrack objects.

• **kwargs – Keyword arguments to pass to muspy.from_music21(), muspy.from_mido(), from_pretty_midi() or from_pypianoroll().

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.from_pianoroll_representation(array, resolution=24, program=0, is_drum=False, encode_velocity=True, default_velocity=64)

Decode piano-roll representation into a Music object.

Parameters

• array (ndarray) – Array in piano-roll representation to decode.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

• program (int, default: 0 (Acoustic Grand Piano)) – Program number, according to General MIDI specification [1]. Valid values are 0 to 127.

• is_drum (bool, default: False) – Whether it is a percussion track.

• encode_velocity (bool, default: True) – Whether to encode velocities.

• default_velocity (int, default: muspy.DEFAULT_VELOCITY (64)) – Default velocity value to use when decoding. Only used when encode_velocity is True.

Returns

Decoded Music object.

Return type

muspy.Music

References

[1] https://www.midi.org/specifications/item/gm-level-1-sound-set

muspy.inputs.from_pitch_representation(array, resolution=24, program=0, is_drum=False, use_hold_state=False, default_velocity=64)

Decode pitch-based representation into a Music object.

Parameters

• array (ndarray) – Array in pitch-based representation to decode.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

• program (int, default: 0 (Acoustic Grand Piano)) – Program number, according to General MIDI specification [1]. Valid values are 0 to 127.

• is_drum (bool, default: False) – Whether it is a percussion track.

• use_hold_state (bool, default: False) – Whether to use a special state for holds.

• default_velocity (int, default: muspy.DEFAULT_VELOCITY (64)) – Default velocity value to use when decoding.

Returns

Decoded Music object.

Return type

muspy.Music

References

[1] https://www.midi.org/specifications/item/gm-level-1-sound-set

muspy.inputs.from_pretty_midi(midi, resolution=None)

Return a pretty_midi PrettyMIDI object as a Music object.

Parameters

• midi (pretty_midi.PrettyMIDI) – PrettyMIDI object to convert.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.from_pypianoroll(multitrack, default_velocity=64)

Return a Pypianoroll Multitrack object as a Music object.

Parameters

• multitrack (pypianoroll.Multitrack) – Pypianoroll Multitrack object to convert.

• default_velocity (int, default: muspy.DEFAULT_VELOCITY (64)) – Default velocity value to use when decoding.

Returns

music – Converted MusPy Music object.

Return type

muspy.Music

muspy.inputs.from_pypianoroll_track(track, default_velocity=64)

Return a Pypianoroll Track object as a Track object.

Parameters

• track (pypianoroll.Track) – Pypianoroll Track object to convert.

• default_velocity (int, default: muspy.DEFAULT_VELOCITY (64)) – Default velocity value to use when decoding.

Returns

Converted track.

Return type

muspy.Track

muspy.inputs.from_representation(array, kind, **kwargs)

Update with the given representation.

Parameters

• array (numpy.ndarray) – Array in a supported representation.

• kind (str, {'pitch', 'pianoroll', 'event', 'note'}) – Data representation.

• **kwargs – Keyword arguments to pass to muspy.from_pitch_representation(), muspy.from_pianoroll_representation(), from_event_representation() or from_note_representation().

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.load(path, kind=None, **kwargs)

Load a JSON or a YAML file into a Music object.

This is a wrapper function for muspy.load_json() and muspy.load_yaml().

Parameters

• path (str, Path or TextIO) – Path to the file or the file to to load.

• kind ({'json', 'yaml'}, optional) – Format to save. Defaults to infer from the extension.

• **kwargs – Keyword arguments to pass to muspy.load_json() or muspy.load_yaml().

Returns

Loaded Music object.

Return type

muspy.Music

See also

muspy.load_json()

Load a JSON file into a Music object.

muspy.load_yaml()

Load a YAML file into a Music object.

muspy.read()

Read a MIDI/MusicXML/ABC file into a Music object.

muspy.inputs.load_json(path, compressed=None)

Load a JSON file into a Music object.

Parameters

• path (str, Path or TextIO) – Path to the file or the file to load.

• compressed (bool, optional) – Whether the file is a compressed JSON file (.json.gz). Has no effect when path is a file object. Defaults to infer from the extension (.gz).

Returns

Loaded Music object.

Return type

muspy.Music

Notes

When a path is given, assume UTF-8 encoding and gzip compression if compressed=True.

muspy.inputs.load_yaml(path, compressed=None)

Load a YAML file into a Music object.

Parameters

• path (str, Path or TextIO) – Path to the file or the file to load.

• compressed (bool, optional) – Whether the file is a compressed YAML file (.yaml.gz). Has no effect when path is a file object. Defaults to infer from the extension (.gz).

Returns

Loaded Music object.

Return type

muspy.Music

Notes

When a path is given, assume UTF-8 encoding and gzip compression if compressed=True.

muspy.inputs.read(path, kind=None, **kwargs)

Read a MIDI/MusicXML/ABC file into a Music object.

Parameters

• path (str or Path) – Path to the file to read.

• kind ({'midi', 'musicxml', 'abc'}, optional) – Format to save. Defaults to infer from the extension.

• **kwargs – Keyword arguments to pass to muspy.read_midi(), muspy.read_musicxml() or read_abc().

Returns

Converted Music object(s).

Return type

muspy.Music or list of muspy.Music

See also

muspy.load()

Load a JSON or a YAML file into a Music object.

muspy.inputs.read_abc(path, number=None, resolution=24)

Return an ABC file into Music object(s) using music21 backend.

Parameters

• path (str or Path) – Path to the ABC file to read.

• number (int, optional) – Reference number of a specific tune to read (i.e., the ‘X:’ field). Defaults to read all tunes.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Converted Music object(s).

Return type

list of muspy.Music

muspy.inputs.read_abc_string(data_str, number=None, resolution=24)

Read ABC data into Music object(s) using music21 backend.

Parameters

• data_str (str) – ABC data to parse.

• number (int, optional) – Reference number of a specific tune to read (i.e., the ‘X:’ field). Defaults to read all tunes.

• resolution (int, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.

Returns

Converted Music object(s).

Return type

muspy.Music

muspy.inputs.read_midi(path, backend='mido', duplicate_note_mode='fifo')

Read a MIDI file into a Music object.

Parameters

• path (str or Path) – Path to the MIDI file to read.

• backend ({'mido', 'pretty_midi'}, default: 'mido') – Backend to use.

• duplicate_note_mode ({'fifo', 'lifo, 'all'}, default: 'fifo') –

  Policy for dealing with duplicate notes. When a note off message is presetned while there are multiple correspoding note on messages that have not yet been closed, we need a policy to decide which note on messages to close. Only used when backend is ‘mido’.

  • ’fifo’ (first in first out): close the earliest note on

  • ’lifo’ (first in first out):close the latest note on

  • ’all’: close all note on messages

Returns

Converted Music object.

Return type

muspy.Music

muspy.inputs.read_musescore(path, resolution=None, compressed=None)

Read a MuseScore file into a Music object.

Parameters

• path (str or Path) – Path to the MuseScore file to read.

• resolution (int, optional) – Time steps per quarter note. Defaults to the least common multiple of all divisions.

• compressed (bool, optional) – Whether it is a compressed MuseScore file. Defaults to infer from the filename.

Returns

Converted Music object.

Return type

muspy.Music

Note

This function is based on MuseScore 3. Files created by an earlier version of MuseScore might not be read correctly.

muspy.inputs.read_musicxml(path, resolution=None, compressed=None)

Read a MusicXML file into a Music object.

Parameters

• path (str or Path) – Path to the MusicXML file to read.

• resolution (int, optional) – Time steps per quarter note. Defaults to the least common multiple of all divisions.

• compressed (bool, optional) – Whether it is a compressed MusicXML file. Defaults to infer from the filename.

Returns

Converted Music object.

Return type

muspy.Music