Music Class

The muspy.Music class is the core element of MusPy. It is a universal container for symbolic music.

Attributes	Description	Type	Default
metadata	Metadata	`muspy.Metadata`	`muspy.Metadata()`
resolution	Time steps per beat	int	`muspy.DEFAULT_RESOLUTION`
tempos	Tempo changes	list of `muspy.Tempo`	[]
key_signatures	Key signature changes	list of `muspy.KeySignature`	[]
time_signatures	Time signature changes	list of `muspy.TimeSignature`	[]
barlines	Barlines	list of `muspy.Barline`	[]
beats	Beats	list of `muspy.Beat`	[]
lyrics	Lyrics	list of `muspy.Lyric`	[]
annotations	Annotations	list of `muspy.Annotation`	[]
tracks	Music tracks	list of `muspy.Track`	[]
real_time	Whether times are in real time (seconds)	bool	False

Hint

An example of a MusPy Music object as a YAML file is available here.

class muspy.Music(metadata=None, resolution=None, tempos=None, key_signatures=None, time_signatures=None, barlines=None, beats=None, lyrics=None, annotations=None, tracks=None, real_time=False)[source]

A universal container for symbolic music.

This is the core class of MusPy. A Music object can be constructed in the following ways.

muspy.Music(): Construct by setting values for attributes
muspy.Music.from_dict(): Construct from a dictionary that stores the attributes and their values as key-value pairs
muspy.read(): Read from a MIDI, a MusicXML or an ABC file
muspy.load(): Load from a JSON or a YAML file saved by muspy.save()
muspy.from_object(): Convert from a music21.Stream, mido.MidiFile, pretty_midi.PrettyMIDI or pypianoroll.Multitrack object

metadata

Metadata.

Type:: muspy.Metadata, default: Metadata()

resolution

Time steps per quarter note.

Type:: int, default: muspy.DEFAULT_RESOLUTION (24)

tempos

Tempo changes.

Type:: list of muspy.Tempo, default: []

key_signatures

Key signatures changes.

Type:: list of muspy.KeySignature, default: []

time_signatures

Time signature changes.

Type:: list of muspy.TimeSignature, default: []

barlines

Barlines.

Type:: list of muspy.Barline, default: []

beats

Beats.

Type:: list of muspy.Beat, default: []

lyrics

Lyrics.

Type:: list of muspy.Lyric, default: []

annotations

Annotations.

Type:: list of muspy.Annotation, default: []

tracks

Music tracks.

Type:: list of muspy.Track, default: []

real_time

Are the times of different objects in real time (seconds)?

Type:: bool, default: False

Note

Indexing a Music object returns the track of a certain index. That is, music[idx] returns music.tracks[idx]. Length of a Music object is the number of tracks. That is, len(music) returns len(music.tracks).

get_real_time(time)[source]

Return the given time in real time (seconds).

This includes tempos, key signatures, time signatures, note offsets, lyrics and annotations. Assume 120 qpm (quarter notes per minute) if no tempo information is available.

Parameters:: time (int) – The time (in metrical time steps) to be converted into real time (seconds).

get_end_time(is_sorted=False)[source]

Return the time of the last event across all the tracks.

This includes tempos, key signatures, time signatures, barlines, beats, lyrics, annotations, note offsets and chord offsets.

Parameters:: is_sorted (bool, default: False) – Whether all the list attributes are sorted.

get_real_end_time(is_sorted=False)[source]

Return the end time in real time (seconds).

This includes tempos, key signatures, time signatures, note offsets, lyrics and annotations. Assume 120 qpm (quarter notes per minute) if no tempo information is available.

Parameters:: is_sorted (bool, default: False) – Whether all the list attributes are sorted.

infer_barlines(overwrite=False)[source]

Infer barlines from the time signatures.

This assumes that there is a barline at each time signature change.

Parameters:: overwrite (bool, default: False) – Whether to overwrite existing barlines.
Return type:: Object itself.
Raises:: ValueError – If no time signature is found.

infer_barlines_and_beats(overwrite=False)[source]

Infer barlines and beats from the time signature changes.

This assumes that there is a downbeat at each time signature change (this is not always true, e.g., for a pickup measure). Return an empty list if no time signature is found.

Parameters:: overwrite (bool, default: False) – Whether to overwrite existing barlines or beats.
Return type:: Object itself.
Raises:: ValueError – If no time signature is found.

adjust_resolution(target=None, factor=None, rounding='round')[source]

Adjust resolution and timing of all time-stamped objects.

Parameters:

target (int, optional) – Target resolution.
factor (int or float, optional) – Factor used to adjust the resolution based on the formula: new_resolution = old_resolution * factor. For example, a factor of 2 double the resolution, and a factor of 0.5 halve the resolution.
rounding ({'round', 'ceil', 'floor'} or callable, default:) –
'round' – Rounding mode.

Return type:

Object itself.

clip(lower=0, upper=127)[source]

Clip the velocity of each note for each track.

Parameters:

lower (int, default: 0) – Lower bound.
upper (int, default: 127) – Upper bound.

Return type:

Object itself.

convert_to_real_time()[source]

Convert all times and durations in this object into real time (seconds). Returns a new muspy.Music object.

Return type:: New muspy.Music object with altered times and durations.

realize_annotations()[source]

Realize all annotations through note velocities and durations. Returns a new muspy.Music object.

Return type:: New muspy.Music object with altered notes and chords (via their velocities and durations).

transpose(semitone)[source]

Transpose all the notes by a number of semitones.

Parameters:: semitone (int) – Number of semitones to transpose the notes. A positive value raises the pitches, while a negative value lowers the pitches.
Return type:: Object itself.

Notes

Drum tracks are skipped.

trim(end)[source]

Trim the track.

Parameters:: end (int) – End time, excluding (i.e, the max time will be end - 1).
Return type:: Object itself.

save(path, kind=None, **kwargs)[source]

Save loselessly to a JSON or a YAML file.

Refer to muspy.save() for full documentation.

save_json(path, **kwargs)[source]

Save loselessly to a JSON file.

Refer to muspy.save_json() for full documentation.

save_yaml(path)[source]

Save loselessly to a YAML file.

Refer to muspy.save_yaml() for full documentation.

write(path, kind=None, **kwargs)[source]

Write to a MIDI, a MusicXML, an ABC or an audio file.

Refer to muspy.write() for full documentation.

write_midi(path, **kwargs)[source]

Write to a MIDI file.

Refer to muspy.write_midi() for full documentation.

write_musicxml(path, **kwargs)[source]

Write to a MusicXML file.

Refer to muspy.write_musicxml() for full documentation.

write_abc(path, **kwargs)[source]

Write to an ABC file.

Refer to muspy.write_abc() for full documentation.

write_audio(path, **kwargs)[source]

Write to an audio file.

Refer to muspy.write_audio() for full documentation.

to_object(kind, **kwargs)[source]

Return as an object in other libraries.

Refer to muspy.to_object() for full documentation.

to_music21(**kwargs)[source]

Return as a Stream object.

Refer to muspy.to_music21() for full documentation.

to_mido(**kwargs)[source]

Return as a MidiFile object.

Refer to muspy.to_mido() for full documentation.

to_pretty_midi(**kwargs)[source]

Return as a PrettyMIDI object.

Refer to muspy.to_pretty_midi() for full documentation.

to_pypianoroll(**kwargs)[source]

Return as a Multitrack object.

Refer to muspy.to_pypianoroll() for full documentation.

to_representation(kind, **kwargs)[source]

Return in a specific representation.

Refer to muspy.to_representation() for full documentation.

to_pitch_representation(**kwargs)[source]

Return in pitch-based representation.

Refer to muspy.to_pitch_representation() for full documentation.

to_pianoroll_representation(**kwargs)[source]

Return in piano-roll representation.

Refer to muspy.to_pianoroll_representation() for full documentation.

to_event_representation(**kwargs)[source]

Return in event-based representation.

Refer to muspy.to_event_representation() for full documentation.

to_note_representation(**kwargs)[source]

Return in note-based representation.

Refer to muspy.to_note_representation() for full documentation.

show(kind, **kwargs)[source]

Show visualization.

Refer to muspy.show() for full documentation.

show_score(**kwargs)[source]

Show score visualization.

Refer to muspy.show_score() for full documentation.

show_pianoroll(**kwargs)[source]

Show pianoroll visualization.

Refer to muspy.show_pianoroll() for full documentation.

synthesize(**kwargs)[source]

Synthesize a Music object to raw audio.

Refer to muspy.synthesize() for full documentation.

adjust_time(func, attr=None, recursive=True)

Adjust the timing of time-stamped objects.

Parameters:

func (callable) – The function used to compute the new timing from the old timing, i.e., new_time = func(old_time).
attr (str, optional) – Attribute to adjust. Defaults to adjust all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

append(obj)

Append an object to the corresponding list.

This will automatically determine the list attributes to append based on the type of the object.

Parameters:: obj – Object to append.

copy()

Return a shallow copy of the object.

This is equivalent to copy.copy(self)().

Return type:: Shallow copy of the object.

deepcopy()

Return a deep copy of the object.

This is equivalent to copy.deepcopy(self)()

Return type:: Deep copy of the object.

extend(other, deepcopy=False)

Extend the list(s) with another object or iterable.

Parameters:

other (muspy.ComplexBase or iterable) – If an object of the same type is given, extend the list attributes with the corresponding list attributes of the other object. If an iterable is given, call muspy.ComplexBase.append() for each item.
deepcopy (bool, default: False) – Whether to make deep copies of the appended objects.

Return type:

Object itself.

fix_type(attr=None, recursive=True)

Fix the types of attributes.

Parameters:

attr (str, optional) – Attribute to adjust. Defaults to adjust all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

classmethod from_dict(dict_, strict=False, cast=False)

Return an instance constructed from a dictionary.

Instantiate an object whose attributes and the corresponding values are given as a dictionary.

Parameters:

dict (dict or mapping) – A dictionary that stores the attributes and their values as key-value pairs, e.g., {“attr1”: value1, “attr2”: value2}.
strict (bool, default: False) – Whether to raise errors for invalid input types.
cast (bool, default: False) – Whether to cast types.

Return type:

Constructed object.

is_valid(attr=None, recursive=True)

Return True if an attribute has a valid type and value.

This will recursively apply to an attribute’s attributes.

Parameters:

attr (str, optional) – Attribute to validate. Defaults to validate all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Returns:

Whether the attribute has a valid type and value.

Return type:

bool

See also

muspy.Base.validate(): Raise an error if an attribute has an invalid type or value.
muspy.Base.is_valid_type(): Return True if an attribute is of a valid type.

is_valid_type(attr=None, recursive=True)

Return True if an attribute is of a valid type.

This will apply recursively to an attribute’s attributes.

Parameters:

attr (str, optional) – Attribute to validate. Defaults to validate all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Returns:

Whether the attribute is of a valid type.

Return type:

bool

See also

muspy.Base.validate_type(): Raise an error if a certain attribute is of an invalid type.
muspy.Base.is_valid(): Return True if an attribute has a valid type and value.

pretty_str(skip_missing=True)

Return the attributes as a string in a YAML-like format.

Parameters:: skip_missing (bool, default: True) – Whether to skip attributes with value None or those that are empty lists.
Returns:: Stored data as a string in a YAML-like format.
Return type:: str

See also

muspy.Base.print(): Print the attributes in a YAML-like format.

print(skip_missing=True)

Print the attributes in a YAML-like format.

Parameters:: skip_missing (bool, default: True) – Whether to skip attributes with value None or those that are empty lists.

See also

muspy.Base.pretty_str(): Return the the attributes as a string in a YAML-like format.

remove_duplicate(attr=None, recursive=True)

Remove duplicate items from a list attribute.

Parameters:

attr (str, optional) – Attribute to check. Defaults to check all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

remove_invalid(attr=None, recursive=True)

Remove invalid items from a list attribute.

Parameters:

attr (str, optional) – Attribute to validate. Defaults to validate all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

sort(attr=None, recursive=True)

Sort a list attribute.

Parameters:

attr (str, optional) – Attribute to sort. Defaults to sort all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

to_ordered_dict(skip_missing=True, deepcopy=True)

Return the object as an OrderedDict.

Return an ordered dictionary that stores the attributes and their values as key-value pairs.

Parameters:

skip_missing (bool, default: True) – Whether to skip attributes with value None or those that are empty lists.
deepcopy (bool, default: True) – Whether to make deep copies of the attributes.

Returns:

A dictionary that stores the attributes and their values as key-value pairs, e.g., {“attr1”: value1, “attr2”: value2}.

Return type:

OrderedDict

validate(attr=None, recursive=True)

Raise an error if an attribute has an invalid type or value.

This will apply recursively to an attribute’s attributes.

Parameters:

attr (str, optional) – Attribute to validate. Defaults to validate all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

See also

muspy.Base.is_valid(): Return True if an attribute has a valid type and value.
muspy.Base.validate_type(): Raise an error if an attribute is of an invalid type.

validate_type(attr=None, recursive=True)

Raise an error if an attribute is of an invalid type.

This will apply recursively to an attribute’s attributes.

Parameters:

attr (str, optional) – Attribute to validate. Defaults to validate all attributes.
recursive (bool, default: True) – Whether to apply recursively.

Return type:

Object itself.

See also

muspy.Base.is_valid_type(): Return True if an attribute is of a valid type.
muspy.Base.validate(): Raise an error if an attribute has an invalid type or value.