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 object) – 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 to other formats such as MIDI and MusicXML.

Notes

The conversion can be lossy if any nonserializable object is used (for example, in 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 object) – 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 object) – 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, 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 object) – 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.
  • 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]

Convert a Music object to a music21 Score object.

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

Encode a Music object into note-based representation.

The note-based represetantion represents music as a sequence of (pitch, time, duration, velocity) tuples. For example, a note Note(time=0, duration=4, pitch=60, velocity=64) will be encoded as a tuple (0, 4, 60, 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 pitch, time, duration and velocity (discarded when encode_velocity is False).

Parameters:
  • music (muspy.Music object) – 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.
Returns:

Encoded array in note-based representation.
Return type:

ndarray, dtype=uint8, shape=(?, 3 or 4)
muspy.outputs.to_object(music: Music, target: str, **kwargs) → Union[music21.stream.Stream, mido.midifiles.midifiles.MidiFile, pretty_midi.pretty_midi.PrettyMIDI, pypianoroll.multitrack.Multitrack][source]

Return a Music object as a PrettyMIDI or a Multitrack object.

Parameters:
  • music (muspy.Music object) – Music object to convert.
  • target (str, {'music21', 'mido', 'pretty_midi', 'pypianoroll'}) – Target class (case-insensitive).
Returns:
muspy.outputs.to_pianoroll_representation(music: Music, encode_velocity: bool = True) → numpy.ndarray[source]

Encode notes into piano-roll representation.

Parameters:
  • music (muspy.Music object) – 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 object) – 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) – MusPy Music object to convert.
Returns:multitrack – Converted Multitrack object.
Return type:pypianoroll.Multitrack object
muspy.outputs.to_representation(music: Music, kind: str, **kwargs) → numpy.ndarray[source]

Return a Music object in a specific representation.

Parameters:
  • music (muspy.Music object) – 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 object) – 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, a MusicXML, an ABC or an audio file.

Parameters:
  • path (str or Path) – Path to write the file.
  • music (muspy.Music object) – 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()
Losslessly save 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 object) – 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 object) – 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 object) – 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 object) – 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).