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: numpy.ndarray, resolution: int = 24, program: int = 0, is_drum: bool = False, use_single_note_off_event: bool = False, use_end_of_sequence_event: bool = False, max_time_shift: int = 100, velocity_bins: int = 32, default_velocity: int = 64) → muspy.music.Music[source]

Decode event-based representation into a Music object.

Parameters:
  • array (ndarray) – Array in event-based representation to decode. Will be casted to integer if not of integer type.
  • resolution (int) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
  • program (int, optional) – Program number according to General MIDI specification [1]. Acceptable values are 0 to 127. Defaults to 0 (Acoustic Grand Piano).
  • is_drum (bool, optional) – A boolean indicating if it is a percussion track. Defaults to False.
  • use_single_note_off_event (bool) – 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. Defaults to False.
  • use_end_of_sequence_event (bool) – Whether to append an end-of-sequence event to the encoded sequence. Defaults to False.
  • max_time_shift (int) – 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. Defaults to 100.
  • velocity_bins (int) – Number of velocity bins to use. Defaults to 32.
  • default_velocity (int) – Default velocity value to use when decoding. Defaults to 64.
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: mido.midifiles.midifiles.MidiFile, duplicate_note_mode: str = 'fifo') → muspy.music.Music[source]

Return a mido MidiFile object as a Music object.

Parameters:
  • midi (mido.MidiFile) – Mido MidiFile object to convert.
  • duplicate_note_mode ({'fifo', 'lifo, 'close_all'}) –

    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. Defaults to ‘fifo’.

    • ’fifo’ (first in first out): close the earliest note on
    • ’lifo’ (first in first out):close the latest note on
    • ’close_all’: close all note on messages
Returns:

Converted Music object.
Return type:

muspy.Music
muspy.inputs.from_music21(stream: music21.stream.Stream, resolution=24) → Union[muspy.music.Music, List[muspy.music.Music], muspy.classes.Track, List[muspy.classes.Track]][source]

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

Parameters:
  • stream (music21.stream.Stream) – Stream object to convert.
  • resolution (int, optional) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
Returns:

Converted Music or Track object(s).
Return type:

muspy.Music or muspy.Track
muspy.inputs.from_music21_opus(opus: music21.stream.Opus, resolution=24) → List[muspy.music.Music][source]

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

Parameters:
  • opus (music21.stream.Opus) – Opus object to convert.
  • resolution (int, optional) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
Returns:

Converted Music object.
Return type:

muspy.Music
muspy.inputs.from_note_representation(array: numpy.ndarray, resolution: int = 24, program: int = 0, is_drum: bool = False, use_start_end: bool = False, encode_velocity: bool = True, default_velocity: int = 64) → muspy.music.Music[source]

Decode note-based representation into a Music object.

Parameters:
  • array (ndarray) – Array in note-based representation to decode. Will be casted to integer if not of integer type.
  • resolution (int) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
  • program (int, optional) – Program number according to General MIDI specification [1]. Acceptable values are 0 to 127. Defaults to 0 (Acoustic Grand Piano).
  • is_drum (bool, optional) – A boolean indicating if it is a percussion track. Defaults to False.
  • use_start_end (bool) – Whether to use ‘start’ and ‘end’ to encode the timing rather than ‘time’ and ‘duration’. Defaults to False.
  • encode_velocity (bool) – Whether to encode note velocities. Defaults to True.
  • default_velocity (int) – Default velocity value to use when decoding if encode_velocity is False. Defaults to 64.
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: Union[music21.stream.Stream, mido.midifiles.midifiles.MidiFile, pretty_midi.pretty_midi.PrettyMIDI, pypianoroll.multitrack.Multitrack], **kwargs) → Union[muspy.music.Music, List[muspy.music.Music], muspy.classes.Track, List[muspy.classes.Track]][source]

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.
Returns:Converted Music object.
Return type:muspy.Music
muspy.inputs.from_pianoroll_representation(array: numpy.ndarray, resolution: int = 24, program: int = 0, is_drum: bool = False, encode_velocity: bool = True, default_velocity: int = 64) → muspy.music.Music[source]

Decode pitch-based representation into a Music object.

Parameters:
  • array (ndarray) – Array in piano-roll representation to decode. Will be casted to integer if not of integer type. If encode_velocity is True, will be casted to boolean if not of boolean type.
  • resolution (int) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
  • program (int, optional) – Program number according to General MIDI specification [1]. Acceptable values are 0 to 127. Defaults to 0 (Acoustic Grand Piano).
  • is_drum (bool, optional) – A boolean indicating if it is a percussion track. Defaults to False.
  • encode_velocity (bool) – Whether to encode velocities. Defaults to True.
  • default_velocity (int) – Default velocity value to use when decoding. Defaults to 64.
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: numpy.ndarray, resolution: int = 24, program: int = 0, is_drum: bool = False, use_hold_state: bool = False, default_velocity: int = 64) → muspy.music.Music[source]

Decode pitch-based representation into a Music object.

Parameters:
  • array (ndarray) – Array in pitch-based representation to decode. Will be casted to integer if not of integer type.
  • resolution (int) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
  • program (int, optional) – Program number according to General MIDI specification [1]. Acceptable values are 0 to 127. Defaults to 0 (Acoustic Grand Piano).
  • is_drum (bool, optional) – A boolean indicating if it is a percussion track. Defaults to False.
  • use_hold_state (bool) – Whether to use a special state for holds. Defaults to False.
  • default_velocity (int) – Default velocity value to use when decoding. Defaults to 64.
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: pretty_midi.pretty_midi.PrettyMIDI) → muspy.music.Music[source]

Return a pretty_midi PrettyMIDI object as a Music object.

Parameters:midi (pretty_midi.PrettyMIDI) – PrettyMIDI object to convert.
Returns:Converted Music object.
Return type:muspy.Music
muspy.inputs.from_pypianoroll(multitrack: pypianoroll.multitrack.Multitrack, default_velocity: int = 64) → muspy.music.Music[source]

Return a Pypianoroll Multitrack object as a Music object.

Parameters:
  • multitrack (pypianoroll.Multitrack) – Pypianoroll Multitrack object to convert.
  • default_velocity (int) – Default velocity value to use when decoding. Defaults to 64.
Returns:

music – Converted MusPy Music object.
Return type:

muspy.Music
muspy.inputs.from_representation(array: numpy.ndarray, kind: str, **kwargs) → muspy.music.Music[source]

Update with the given representation.

Parameters:
  • array (numpy.ndarray) – Array in a supported representation.
  • kind (str, {'pitch', 'pianoroll', 'event', 'note'}) – Data representation type (case-insensitive).
Returns:

Converted Music object.
Return type:

muspy.Music
muspy.inputs.load(path: Union[str, pathlib.Path], kind: Optional[str] = None, **kwargs) → muspy.music.Music[source]

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

Parameters:
  • path (str or Path) – Path to the file to load.
  • kind ({'json', 'yaml'}, optional) – Format to save (case-insensitive). Defaults to infer the format from the extension.
  • **kwargs (dict) – Keyword arguments to pass to the target function. See muspy.load_json() or muspy.load_yaml() for available arguments.
Returns:

Loaded Music object.
Return type:

muspy.Music

See also

muspy.read()
Read a MIDI/MusicXML/ABC file into a Music object.
muspy.inputs.load_json(path: Union[str, pathlib.Path]) → muspy.music.Music[source]

Load a JSON file into a Music object.

Parameters:path (str or Path) – Path to the file to load.
Returns:Loaded Music object.
Return type:muspy.Music
muspy.inputs.load_yaml(path: Union[str, pathlib.Path]) → muspy.music.Music[source]

Load a YAML file into a Music object.

Parameters:path (str or Path) – Path to the file to load.
Returns:Loaded Music object.
Return type:muspy.Music
muspy.inputs.read(path: Union[str, pathlib.Path], kind: Optional[str] = None, **kwargs) → Union[muspy.music.Music, List[muspy.music.Music]][source]

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 (case-insensitive). Defaults to infer the format from the extension.
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: Union[str, pathlib.Path], number: Optional[int] = None, resolution=24) → List[muspy.music.Music][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) – Reference number of a specific tune to read (i.e., the ‘X:’ field).
  • resolution (int, optional) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
Returns:

Converted Music object(s).
Return type:

list of muspy.Music
muspy.inputs.read_abc_string(data_str: str, number: Optional[int] = None, resolution=24)[source]

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

Parameters:
  • data_str (str) – ABC data to parse.
  • number (int) – Reference number of a specific tune to read (i.e., the ‘X:’ field).
  • resolution (int, optional) – Time steps per quarter note. Defaults to muspy.DEFAULT_RESOLUTION.
Returns:

Converted Music object(s).
Return type:

muspy.Music
muspy.inputs.read_midi(path: Union[str, pathlib.Path], backend: str = 'mido', duplicate_note_mode: str = 'fifo') → muspy.music.Music[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'}) – Backend to use.
  • duplicate_note_mode ({'fifo', 'lifo, 'close_all'}) –

    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. Defaults to ‘fifo’. Only used when backend=’mido’.

    • ’fifo’ (first in first out): close the earliest note on
    • ’lifo’ (first in first out):close the latest note on
    • ’close_all’: close all note on messages
Returns:

Converted Music object.
Return type:

muspy.Music
muspy.inputs.read_musicxml(path: Union[str, pathlib.Path], compressed: Optional[bool] = None) → muspy.music.Music[source]

Read a MusicXML file into a Music object.

Parameters:path (str or Path) – Path to the MusicXML file to read.
Returns:Converted Music object.
Return type:muspy.Music

Notes

Grace notes and unpitched notes are not supported.