muspy.outputs

Output interfaces.

This module provides output 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

  • save
  • save_json
  • save_yaml
  • to_event_representation
  • to_mido
  • to_music21
  • to_note_representation
  • to_object
  • to_pianoroll_representation
  • to_pitch_representation
  • to_pretty_midi
  • to_pypianoroll
  • to_representation
  • write
  • write_abc
  • write_audio
  • write_midi
  • write_musicxml
muspy.outputs.save(path: Union[str, pathlib.Path], music: Music, kind: Optional[str] = None, **kwargs)[source]

Save a Music object loselessly to a JSON or a YAML file.

Parameters:
  • path (str or Path) – Path to save the file.
  • music (muspy.Music) – Music object to save.
  • kind ({'json', 'yaml'}, optional) – Format to save (case-insensitive). Defaults to infer the format from the extension.

See also

muspy.write()
Write a Music object to a MIDI/MusicXML/ABC/audio file.

Notes

The conversion can be lossy if any nonserializable object is used (for example, an Annotation object, which can store data of any type).

muspy.outputs.save_json(path: Union[str, pathlib.Path], music: Music)[source]

Save a Music object to a JSON file.

Parameters:
  • path (str or Path) – Path to save the JSON file.
  • music (muspy.Music) – Music object to save.
muspy.outputs.save_yaml(path: Union[str, pathlib.Path], music: Music)[source]

Save a Music object to a YAML file.

Parameters:
  • path (str or Path) – Path to save the YAML file.
  • music (muspy.Music) – Music object to save.
muspy.outputs.to_event_representation(music: Music, use_single_note_off_event: bool = False, use_end_of_sequence_event: bool = False, encode_velocity: bool = False, force_velocity_event: bool = True, max_time_shift: int = 100, velocity_bins: int = 32) → numpy.ndarray[source]

Encode a Music object into event-based representation.

The event-based represetantion represents music as a sequence of events, including note-on, note-off, time-shift and velocity events. The output shape is M x 1, where M is the number of events. The values encode the events. The default configuration uses 0-127 to encode note-one events, 128-255 for note-off events, 256-355 for time-shift events, and 356 to 387 for velocity events.

Parameters:
  • music (muspy.Music) – Music object to encode.
  • use_single_note_off_event (bool) – Whether to use a single note-off event for all the pitches. If True, the 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.
  • encode_velocity (bool) – Whether to encode velocities.
  • force_velocity_event (bool) – Whether to add a velocity event before every note-on event. If False, velocity events are only used when the note velocity is changed (i.e., different from the previous one). Defaults to True.
  • 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.
Returns:

Encoded array in event-based representation.

Return type:

ndarray, dtype=uint16, shape=(?, 1)

muspy.outputs.to_mido(music: Music, use_note_on_as_note_off: bool = True)[source]

Return a Music object as a MidiFile object.

Parameters:
  • music (muspy.Music object) – Music object to convert.
  • use_note_on_as_note_off (bool) – Whether to use a note on message with zero velocity instead of a note off message.
Returns:

Converted MidiFile object.

Return type:

mido.MidiFile

muspy.outputs.to_music21(music: Music) → music21.stream.Score[source]

Return a Music object as a music21 Score object.

Parameters:music (muspy.Music) – Music object to convert.
Returns:Converted music21 Score object.
Return type:music21.stream.Score
muspy.outputs.to_note_representation(music: Music, use_start_end: bool = False, encode_velocity: bool = True, dtype: Union[numpy.dtype, type, str] = <class 'int'>) → numpy.ndarray[source]

Encode a Music object into note-based representation.

The note-based represetantion represents music as a sequence of (time, pitch, duration, velocity) tuples. For example, a note Note(time=0, duration=4, pitch=60, velocity=64) will be encoded as a tuple (0, 60, 4, 64). The output shape is N * D, where N is the number of notes and D is 4 when encode_velocity is True, otherwise D is 3. The values of the second dimension represent time, pitch, duration and velocity (discarded when encode_velocity is False).

Parameters:
  • music (muspy.Music) – Music object to encode.
  • 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.
  • dtype (dtype, type or str) – Data type of the return array. Defaults to int.
Returns:

Encoded array in note-based representation.

Return type:

ndarray, shape=(?, 3 or 4)

muspy.outputs.to_object(music: Music, kind: str, **kwargs) → Union[music21.stream.Stream, mido.midifiles.midifiles.MidiFile, pretty_midi.pretty_midi.PrettyMIDI, pypianoroll.multitrack.Multitrack][source]

Return a Music object as an object in other libraries.

Supported classes are music21.Stream, mido.MidiTrack, pretty_midi.PrettyMIDI and pypianoroll.Multitrack.

Parameters:
  • music (muspy.Music) – Music object to convert.
  • kind (str, {'music21', 'mido', 'pretty_midi', 'pypianoroll'}) – Target class (case-insensitive).
Returns:

Converted object.

Return type:

music21.Stream, mido.MidiTrack, pretty_midi.PrettyMIDI or pypianoroll.Multitrack

muspy.outputs.to_pianoroll_representation(music: Music, encode_velocity: bool = True) → numpy.ndarray[source]

Encode notes into piano-roll representation.

Parameters:
  • music (muspy.Music) – Music object to encode.
  • encode_velocity (bool) – Whether to encode velocities. If True, a binary-valued array will be return. Otherwise, an integer array will be return. Defaults to True.
Returns:

Encoded array in piano-roll representation.

Return type:

ndarray, dtype=uint8 or bool, shape=(?, 128)

muspy.outputs.to_pitch_representation(music: Music, use_hold_state: bool = False) → numpy.ndarray[source]

Encode a Music object into pitch-based representation.

The pitch-based represetantion represents music as a sequence of pitch, rest and (optional) hold tokens. Only monophonic melodies are compatible with this representation. The output shape is T x 1, where T is the number of time steps. The values indicate whether the current time step is a pitch (0-127), a rest (128) or (optionally) a hold (129).

Parameters:
  • music (muspy.Music) – Music object to encode.
  • use_hold_state (bool) – Whether to use a special state for holds. Defaults to False.
Returns:

Encoded array in pitch-based representation.

Return type:

ndarray, dtype=uint8, shape=(?, 1)

muspy.outputs.to_pretty_midi(music: Music) → pretty_midi.pretty_midi.PrettyMIDI[source]

Return a Music object as a PrettyMIDI object.

Tempo changes are not supported yet.

Parameters:music (muspy.Music object) – Music object to convert.
Returns:Converted PrettyMIDI object.
Return type:pretty_midi.PrettyMIDI
muspy.outputs.to_pypianoroll(music: Music) → pypianoroll.multitrack.Multitrack[source]

Return a Music object as a Multitrack object.

Parameters:music (muspy.Music) – Music object to convert.
Returns:multitrack – Converted Multitrack object.
Return type:pypianoroll.Multitrack
muspy.outputs.to_representation(music: Music, kind: str, **kwargs) → numpy.ndarray[source]

Return a Music object in a specific representation.

Parameters:
  • music (muspy.Music) – Music object to convert.
  • kind (str, {'pitch', 'piano-roll', 'event', 'note'}) – Target representation (case-insensitive).
Returns:

array – Converted representation.

Return type:

ndarray

muspy.outputs.synthesize(music: Music, soundfont_path: Union[str, pathlib.Path, None] = None, rate: int = 44100) → numpy.ndarray[source]

Synthesize a Music object to raw audio.

Parameters:
  • music (muspy.Music) – Music object to write.
  • soundfont_path (str or Path, optional) – Path to the soundfount file. Defaults to the path to the downloaded MuseScore General soundfont.
  • rate (int) – Sample rate (in samples per sec). Defaults to 44100.
Returns:

Synthesized waveform.

Return type:

ndarray, dtype=int16, shape=(?, 2)

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

Write a Music object to a MIDI/MusicXML/ABC/audio file.

Parameters:
  • path (str or Path) – Path to write the file.
  • music (muspy.Music) – Music object to convert.
  • kind ({'midi', 'musicxml', 'abc', 'audio'}, optional) – Format to save (case-insensitive). Defaults to infer the format from the extension.

See also

muspy.save()
Save a Music object loselessly to a JSON or a YAML file.
muspy.outputs.write_abc(path: Union[str, pathlib.Path], music: Music)[source]

Write a Music object to a ABC file.

Parameters:
  • path (str or Path) – Path to write the ABC file.
  • music (muspy.Music) – Music object to write.
muspy.outputs.write_audio(path: Union[str, pathlib.Path], music: Music, soundfont_path: Union[str, pathlib.Path, None] = None, rate: int = 44100, audio_format: Optional[str] = None)[source]

Write a Music object to an audio file.

Supported formats include WAV, AIFF, FLAC and OGA.

Parameters:
  • path (str or Path) – Path to write the audio file.
  • music (muspy.Music) – Music object to write.
  • soundfont_path (str or Path, optional) – Path to the soundfount file. Defaults to the path to the downloaded MuseScore General soundfont.
  • rate (int) – Sample rate (in samples per sec). Defaults to 44100.
  • audio_format (str, {'wav', 'aiff', 'flac', 'oga'}, optional) – File format to write. If None, infer it from the extension.
muspy.outputs.write_midi(path: Union[str, pathlib.Path], music: Music, backend: str = 'mido', **kwargs)[source]

Write a Music object to a MIDI file.

Parameters:
  • path (str or Path) – Path to write the MIDI file.
  • music (muspy.Music) – Music object to write.
  • backend ({'mido', 'pretty_midi'}) – Backend to use. Defaults to ‘mido’.
muspy.outputs.write_musicxml(path: Union[str, pathlib.Path], music: Music, compressed: Optional[bool] = None)[source]

Write a Music object to a MusicXML file.

Parameters:
  • path (str or Path) – Path to write the MusicXML file.
  • music (muspy.Music) – Music object to write.
  • compressed (bool, optional) – Whether to write to a compressed MusicXML file. If None, infer from the extension of the filename (‘.xml’ and ‘.musicxml’ for an uncompressed file, ‘.mxl’ for a compressed file).