muspy.processors

Representation processors.

This module defines the processors for commonly used representations.

Classes

  • NoteRepresentationProcessor
  • EventRepresentationProcessor
  • PianoRollRepresentationProcessor
  • PitchRepresentationProcessor
class muspy.processors.NoteRepresentationProcessor(use_start_end: bool = False, encode_velocity: bool = True, dtype: Union[numpy.dtype, type, str] = <class 'int'>, default_velocity: int = 64)[source]

Note-based representation processor.

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 L * D, where L is th 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).

use_start_end

Whether to use ‘start’ and ‘end’ to encode the timing rather than ‘time’ and ‘duration’.

Type:bool, default: False
encode_velocity

Whether to encode note velocities.

Type:bool, default: True
dtype

Data type of the return array.

Type:dtype, type or str, default: int
default_velocity

Default velocity value to use when decoding if encode_velocity is False.

Type:int, default: 64
decode(array: numpy.ndarray) → muspy.music.Music[source]

Decode note-based representation into a Music object.

Parameters:array (ndarray) – Array in note-based representation to decode. Cast to integer if not of integer type.
Returns:Decoded Music object.
Return type:muspy.Music object

See also

muspy.from_note_representation()
Return a Music object converted from note-based representation.
encode(music: muspy.music.Music) → numpy.ndarray[source]

Encode a Music object into note-based representation.

Parameters:music (muspy.Music object) – Music object to encode.
Returns:Encoded array in note-based representation.
Return type:ndarray (np.uint8)

See also

muspy.to_note_representation()
Convert a Music object into note-based representation.
class muspy.processors.EventRepresentationProcessor(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, default_velocity: int = 64)[source]

Event-based representation processor.

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.

use_single_note_off_event

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.

Type:bool, default: False
use_end_of_sequence_event

Whether to append an end-of-sequence event to the encoded sequence.

Type:bool, default: False
encode_velocity

Whether to encode velocities.

Type:bool, default: False
force_velocity_event

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).

Type:bool, default: True
max_time_shift

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.

Type:int, default: 100
velocity_bins

Number of velocity bins to use.

Type:int, default: 32
default_velocity

Default velocity value to use when decoding.

Type:int, default: 64
decode(array: numpy.ndarray) → muspy.music.Music[source]

Decode event-based representation into a Music object.

Parameters:array (ndarray) – Array in event-based representation to decode. Cast to integer if not of integer type.
Returns:Decoded Music object.
Return type:muspy.Music object

See also

muspy.from_event_representation()
Return a Music object converted from event-based representation.
encode(music: muspy.music.Music) → numpy.ndarray[source]

Encode a Music object into event-based representation.

Parameters:music (muspy.Music object) – Music object to encode.
Returns:Encoded array in event-based representation.
Return type:ndarray (np.uint16)

See also

muspy.to_event_representation()
Convert a Music object into event-based representation.
class muspy.processors.PianoRollRepresentationProcessor(encode_velocity: bool = True, default_velocity: int = 64)[source]

Piano-roll representation processor.

The piano-roll represetantion represents music as a time-pitch matrix, where the columns are the time steps and the rows are the pitches. The values indicate the presence of pitches at different time steps. The output shape is T x 128, where T is the number of time steps.

encode_velocity

Whether to encode velocities. If True, a binary-valued array will be return. Otherwise, an integer array will be return.

Type:bool, default: True
default_velocity

Default velocity value to use when decoding if encode_velocity is False.

Type:int, default: 64
decode(array: numpy.ndarray) → muspy.music.Music[source]

Decode piano-roll representation into a Music object.

Parameters:array (ndarray) – Array in piano-roll representation to decode. Cast to integer if not of integer type. If encode_velocity is True, casted to boolean if not of boolean type.
Returns:Decoded Music object.
Return type:muspy.Music object

See also

muspy.from_pianoroll_representation()
Return a Music object converted from piano-roll representation.
encode(music: muspy.music.Music) → numpy.ndarray[source]

Encode a Music object into piano-roll representation.

Parameters:music (muspy.Music object) – Music object to encode.
Returns:Encoded array in piano-roll representation.
Return type:ndarray (np.uint8)

See also

muspy.to_pianoroll_representation()
Convert a Music object into piano-roll representation.
class muspy.processors.PitchRepresentationProcessor(use_hold_state: bool = False, default_velocity: int = 64)[source]

Pitch-based representation processor.

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).

use_hold_state

Whether to use a special state for holds.

Type:bool, default: False
default_velocity

Default velocity value to use when decoding.

Type:int, default: 64
decode(array: numpy.ndarray) → muspy.music.Music[source]

Decode pitch-based representation into a Music object.

Parameters:array (ndarray) – Array in pitch-based representation to decode. Cast to integer if not of integer type.
Returns:Decoded Music object.
Return type:muspy.Music object

See also

muspy.from_pitch_representation()
Return a Music object converted from pitch-based representation.
encode(music: muspy.music.Music) → numpy.ndarray[source]

Encode a Music object into pitch-based representation.

Parameters:music (muspy.Music object) – Music object to encode.
Returns:Encoded array in pitch-based representation.
Return type:ndarray (np.uint8)

See also

muspy.to_pitch_representation()
Convert a Music object into pitch-based representation.