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
-
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: 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: - midi (
-
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.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.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 ofmuspy.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.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: 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: - obj – Object to convert. Supported objects are music21.Stream,
mido.MidiTrack
,pretty_midi.PrettyMIDI
, andpypianoroll.Multitrack
objects. - **kwargs – Keyword arguments to pass to
muspy.from_music21()
,muspy.from_mido()
,from_pretty_midi()
orfrom_pypianoroll()
.
Returns: Converted Music object.
Return type: - obj – Object to convert. Supported objects are music21.Stream,
-
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: 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: 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: - midi (
-
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: - multitrack (
-
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: - track (
-
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.
- **kwargs – Keyword arguments to pass to
muspy.from_pitch_representation()
,muspy.from_pianoroll_representation()
,from_event_representation()
orfrom_note_representation()
.
Returns: Converted Music object.
Return type: - array (
-
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()
andmuspy.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()
ormuspy.load_yaml()
.
Returns: Loaded Music object.
Return type: 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: Returns: Loaded Music object.
Return type: 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: Returns: Loaded Music object.
Return type: 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: - 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()
orread_abc()
.
Returns: Converted Music object(s).
Return type: muspy.Music
or list ofmuspy.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: 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: Returns: Converted Music object(s).
Return type:
-
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: