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_musicxml

Errors

  • MIDIError

  • MusicXMLError

exception muspy.inputs.MIDIError[source]

An error class for MIDI related exceptions.

exception muspy.inputs.MusicXMLError[source]

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')[source]

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')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Return an outside object as a Music object.

Parameters
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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Update with the given representation.

Parameters
Returns

Converted Music object.

Return type

muspy.Music

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

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)[source]

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)[source]

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)[source]

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

Parameters
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)[source]

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)[source]

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')[source]

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_musicxml(path, resolution=None, compressed=None)[source]

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

Notes

Grace notes and unpitched notes are not supported.