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, duplicate_note_mode: str = 'fifo') → muspy.music.Music[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: 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', '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: music21.stream.base.Stream, resolution: int = 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, 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: music21.stream.base.Opus, resolution: int = 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, default: muspy.DEFAULT_RESOLUTION (24)) – Time steps per quarter note.
Returns:

Converted Music object.

Return type:

muspy.Music

muspy.inputs.from_music21_part(part: music21.stream.base.Part, resolution: int = 24) → Union[muspy.classes.Track, List[muspy.classes.Track]][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: music21.stream.base.Score, resolution: int = 24) → muspy.music.Music[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: 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.
  • 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: Union[music21.stream.base.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:
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 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: 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.
  • 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: pretty_midi.pretty_midi.PrettyMIDI, resolution: int = None) → muspy.music.Music[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: 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: 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: pypianoroll.track.Track, default_velocity: int = 64) → muspy.classes.Track[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: numpy.ndarray, kind: str, **kwargs) → muspy.music.Music[source]

Update with the given representation.

Parameters:
Returns:

Converted Music object.

Return type:

muspy.Music

muspy.inputs.load(path: Union[str, pathlib.Path, TextIO], kind: str = None, **kwargs) → muspy.music.Music[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: Union[str, pathlib.Path, TextIO], compressed: bool = None) → muspy.music.Music[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: Union[str, pathlib.Path, TextIO], compressed: bool = None) → muspy.music.Music[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: Union[str, pathlib.Path], kind: str = None, **kwargs) → Union[muspy.music.Music, List[muspy.music.Music]][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: Union[str, pathlib.Path], number: int = None, resolution=24) → Union[muspy.music.Music, 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, 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: str, number: int = None, resolution=24) → Union[muspy.music.Music, List[muspy.music.Music]][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: 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'}, 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: Union[str, pathlib.Path], resolution: int = None, compressed: 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.
  • 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.