Track Class

Pypianoroll provides three classes (pypianoroll.Track, pypianoroll.BinaryTrack and pypianoroll.StandardTrack) for handling single-track piano rolls.

class pypianoroll.Track(name: Optional[str] = None, program: Optional[int] = None, is_drum: Optional[bool] = None, pianoroll: Optional[numpy.ndarray] = None)[source]

A generic container for single-track piano rolls.

name

Track name.

Type

str, optional

program

Program number according to General MIDI specification [1]. Defaults to 0 (Acoustic Grand Piano).

Type

int, 0-127, optional

is_drum

Whether it is a percussion track. Defaults to False.

Type

bool, optional

pianoroll

Piano-roll matrix. The first dimension represents time, and the second dimension represents pitch.

Type

ndarray, shape=(?, 128), optional

References

  1. https://www.midi.org/specifications/item/gm-level-1-sound-set

copy()[source]

Return a copy of the track.

Returns

Return type

A copy of the object itself.

Notes

The piano-roll array is copied using numpy.copy().

get_length() → int[source]

Return the active length of the piano roll.

Returns

Length (in time steps) of the piano roll without trailing silence.

Return type

int

is_valid(attr: Optional[str] = None) → bool[source]

Return True if an attribute is valid.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Whether the attribute has a valid type and value.

Return type

bool

is_valid_type(attr: Optional[str] = None) → bool[source]

Return True if an attribute is of a valid type.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Whether the attribute is of a valid type.

Return type

bool

pad(pad_length: int) → _Track[source]

Pad the piano roll.

Parameters

pad_length (int) – Length to pad along the time axis.

Returns

Return type

Object itself.

See also

pypianoroll.Track.pad_to_multiple()

Pad the piano roll so that its length is some multiple.

pad_to_multiple(factor: int) → _Track[source]

Pad the piano roll so that its length is some multiple.

Pad the piano roll at the end along the time axis of the minimum length that makes the length of the resulting piano roll a multiple of factor.

Parameters

factor (int) – The value which the length of the resulting piano roll will be a multiple of.

Returns

Return type

Object itself.

See also

pypianoroll.Track.pad()

Pad the piano roll.

plot(ax: Optional[matplotlib.axes._axes.Axes] = None, **kwargs) → matplotlib.axes._axes.Axes[source]

Plot the piano roll.

Refer to pypianoroll.plot_track() for full documentation.

standardize() → pypianoroll.track.StandardTrack[source]

Standardize the track.

Returns

Return type

Converted StandardTrack object.

transpose(semitone: int) → _Track[source]

Transpose the piano roll by a number of semitones.

Parameters

semitone (int) – Number of semitones to transpose. A positive value raises the pitches, while a negative value lowers the pitches.

Returns

Return type

Object itself.

trim(start: Optional[int] = None, end: Optional[int] = None) → _Track[source]

Trim the piano roll.

Parameters
  • start (int, optional) – Start time. Defaults to 0.

  • end (int, optional) – End time. Defaults to active length.

Returns

Return type

Object itself.

validate(attr=None)[source]

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

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Return type

Object itself.

validate_type(attr=None)[source]

Raise an error if an attribute has an invalid type.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Return type

Object itself.

class pypianoroll.BinaryTrack(name: Optional[str] = None, program: Optional[int] = None, is_drum: Optional[bool] = None, pianoroll: Optional[numpy.ndarray] = None)[source]

A container for single-track, binary piano rolls.

name

Track name.

Type

str, optional

program

Program number according to General MIDI specification [1]. Defaults to 0 (Acoustic Grand Piano).

Type

int, 0-127, optional

is_drum

Whether it is a percussion track. Defaults to False.

Type

bool, optional

pianoroll

Piano-roll matrix. The first dimension represents time, and the second dimension represents pitch. Cast to bool if not of data type bool.

Type

ndarray, dtype=bool, shape=(?, 128), optional

References

  1. https://www.midi.org/specifications/item/gm-level-1-sound-set

copy()

Return a copy of the track.

Returns

Return type

A copy of the object itself.

Notes

The piano-roll array is copied using numpy.copy().

get_length() → int

Return the active length of the piano roll.

Returns

Length (in time steps) of the piano roll without trailing silence.

Return type

int

is_valid(attr: Optional[str] = None) → bool

Return True if an attribute is valid.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Whether the attribute has a valid type and value.

Return type

bool

is_valid_type(attr: Optional[str] = None) → bool

Return True if an attribute is of a valid type.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Whether the attribute is of a valid type.

Return type

bool

pad(pad_length: int) → _Track

Pad the piano roll.

Parameters

pad_length (int) – Length to pad along the time axis.

Returns

Return type

Object itself.

See also

pypianoroll.Track.pad_to_multiple()

Pad the piano roll so that its length is some multiple.

pad_to_multiple(factor: int) → _Track

Pad the piano roll so that its length is some multiple.

Pad the piano roll at the end along the time axis of the minimum length that makes the length of the resulting piano roll a multiple of factor.

Parameters

factor (int) – The value which the length of the resulting piano roll will be a multiple of.

Returns

Return type

Object itself.

See also

pypianoroll.Track.pad()

Pad the piano roll.

plot(ax: Optional[matplotlib.axes._axes.Axes] = None, **kwargs) → matplotlib.axes._axes.Axes

Plot the piano roll.

Refer to pypianoroll.plot_track() for full documentation.

set_nonzeros(value: int) → pypianoroll.track.StandardTrack[source]

Assign a constant value to all nonzeros entries.

Parameters

value (int) – Value to assign.

Returns

Return type

Converted StandardTrack object.

standardize() → pypianoroll.track.StandardTrack

Standardize the track.

Returns

Return type

Converted StandardTrack object.

transpose(semitone: int) → _Track

Transpose the piano roll by a number of semitones.

Parameters

semitone (int) – Number of semitones to transpose. A positive value raises the pitches, while a negative value lowers the pitches.

Returns

Return type

Object itself.

trim(start: Optional[int] = None, end: Optional[int] = None) → _Track

Trim the piano roll.

Parameters
  • start (int, optional) – Start time. Defaults to 0.

  • end (int, optional) – End time. Defaults to active length.

Returns

Return type

Object itself.

validate(attr=None)

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

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Return type

Object itself.

validate_type(attr=None)

Raise an error if an attribute has an invalid type.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Return type

Object itself.

class pypianoroll.StandardTrack(name: Optional[str] = None, program: Optional[int] = None, is_drum: Optional[bool] = None, pianoroll: Optional[numpy.ndarray] = None)[source]

A container for single-track piano rolls with velocities.

name

Track name.

Type

str, optional

program

Program number according to General MIDI specification [1]. Defaults to 0 (Acoustic Grand Piano).

Type

int, 0-127, optional

is_drum

Whether it is a percussion track. Defaults to False.

Type

bool, optional

pianoroll

Piano-roll matrix. The first dimension represents time, and the second dimension represents pitch. Cast to uint8 if not of data type uint8.

Type

ndarray, dtype=uint8, shape=(?, 128), optional

References

  1. https://www.midi.org/specifications/item/gm-level-1-sound-set

binarize(threshold: float = 0) → pypianoroll.track.BinaryTrack[source]

Binarize the piano roll.

Parameters

threshold (int or float) – Threshold. Defaults to 0.

Returns

Return type

Converted Binary object.

clip(lower: int = 0, upper: int = 127) → _StandardTrack[source]

Clip (limit) the the piano roll into [lower, upper].

Parameters
  • lower (int) – Lower bound. Defaults to 0.

  • upper (int) – Upper bound. Defaults to 127.

Returns

Return type

Object itself.

copy()

Return a copy of the track.

Returns

Return type

A copy of the object itself.

Notes

The piano-roll array is copied using numpy.copy().

get_length() → int

Return the active length of the piano roll.

Returns

Length (in time steps) of the piano roll without trailing silence.

Return type

int

is_valid(attr: Optional[str] = None) → bool

Return True if an attribute is valid.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Whether the attribute has a valid type and value.

Return type

bool

is_valid_type(attr: Optional[str] = None) → bool

Return True if an attribute is of a valid type.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Whether the attribute is of a valid type.

Return type

bool

pad(pad_length: int) → _Track

Pad the piano roll.

Parameters

pad_length (int) – Length to pad along the time axis.

Returns

Return type

Object itself.

See also

pypianoroll.Track.pad_to_multiple()

Pad the piano roll so that its length is some multiple.

pad_to_multiple(factor: int) → _Track

Pad the piano roll so that its length is some multiple.

Pad the piano roll at the end along the time axis of the minimum length that makes the length of the resulting piano roll a multiple of factor.

Parameters

factor (int) – The value which the length of the resulting piano roll will be a multiple of.

Returns

Return type

Object itself.

See also

pypianoroll.Track.pad()

Pad the piano roll.

plot(ax: Optional[matplotlib.axes._axes.Axes] = None, **kwargs) → matplotlib.axes._axes.Axes

Plot the piano roll.

Refer to pypianoroll.plot_track() for full documentation.

set_nonzeros(value: int) → _StandardTrack[source]

Assign a constant value to all nonzeros entries.

Parameters

value (int) – Value to assign.

Returns

Return type

Object itself.

standardize() → pypianoroll.track.StandardTrack

Standardize the track.

Returns

Return type

Converted StandardTrack object.

transpose(semitone: int) → _Track

Transpose the piano roll by a number of semitones.

Parameters

semitone (int) – Number of semitones to transpose. A positive value raises the pitches, while a negative value lowers the pitches.

Returns

Return type

Object itself.

trim(start: Optional[int] = None, end: Optional[int] = None) → _Track

Trim the piano roll.

Parameters
  • start (int, optional) – Start time. Defaults to 0.

  • end (int, optional) – End time. Defaults to active length.

Returns

Return type

Object itself.

validate(attr=None)

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

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Return type

Object itself.

validate_type(attr=None)

Raise an error if an attribute has an invalid type.

Parameters

attr (str) – Attribute to validate. Defaults to validate all attributes.

Returns

Return type

Object itself.