pytakt.event module

This module defines a set of classes related to events. Most of these events are based on events defined in Standard MIDI files.

midimsg_size(status) → int

Finds the length of a MIDI message from the status byte of the message.

Parameters:

status (int) – MIDI status byte value

Returns:

Length of the message

message_to_event(msg, time, tk, encoding='utf-8', errhdr='') → Event

Takes a byte sequence in the format returned by the to_message method of each class and converts it to an event of the appropriate class (except LoopBackEvent).

Parameters:

  • msg (bytes, bytearray, or iterable of int) – Input byte sequence

  • time (ticks) – time of event

  • tk (int) – track number

  • encoding (str or None) – specifies how the string of the text event is encoded in the byte sequence; if this is None, the string is copied verbatimly from the byte sequence.

  • errhdr (str, optional) – header string for error and warning messages

Returns:

Event created

class Event(t, tk, dt=0, **kwargs)

Bases: object

Base class for all types of events.

Attributes

t

time of the event in ticks

Type:

ticks

tk

track number (starting from 0)

Type:

int

dt

the difference between the notated time and the played time; for performances, t plus this value (in ticks) is used for timing; the range of the dt value is limited (see pytakt.constants.MAX_DELTA_TIME).

Type:

ticks

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • tk (int) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event

Arithmetic Rules

  • The equivalence comparison (‘==’) between events results in true only if the classes match and all attribute values are equivalent.

  • If the ‘|’ operator is used with the left operand being a string and the right operand being an event, the left operand is ignored and the result is the value of the event itself. This is used in showtext() to ignore measure numbers, etc. to the left of the ‘|’.


copy() → Event

Returns a copied event (shallow copy).

update(**kwargs) → Event

Adds or changes attributes according to the assignment description in kwargs.

Returns:

self

tostr(timereprfunc=<function std_time_repr>) → str

Returns a string representation of the event.

Parameters:

timereprfunc (function) – Function to convert a value of time to a string. By default, it assumes a function that returns a representation rounded to 5 decimal places.

is_pitch_bend() → bool

Returns true for a Pitch Bend event.

is_key_pressure() → bool

Returns true for a Key Pressure event.

is_channel_pressure() → bool

Returns true for a Channel Pressure event.

is_program_change() → bool

Return true for a Program Change event.

is_all_notes_off() → bool

Returns true for an all-note-off event (#123 control change event with a value of 0).

is_marker() → bool

Returns true for a marker event (#6 meta event).

is_end_of_track() → bool

Returns true for a track-end event (#47 meta event).

is_text_event() → bool

Returns true for text events (#1 to #15 meta events).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

ptime() → Union[int, float, Fraction]

Returns the performance time (sum of the t and dt attribute values).

class NoteEventClass(*args, **kwargs)

Bases: Event

Base class of NoteEvent, NoteOnEvent, and NoteOffEvent.


class NoteEvent(t, n, L, v=80, nv=None, du=None, tk=1, ch=1, dt=0, **kwargs)

Bases: NoteEventClass

Class for note events. A note event corresponds to a pair of note-on and note-off.

Attributes

ch

MIDI channel number (starting from 1)

Type:

int

n

MIDI note number

Type:

int or Pitch

L

notated duration in ticks (note value)

Type:

ticks

v

MIDI velocity

Type:

int

nv

MIDI note-off velocity; if this is None, a note-on message with zero velocity is used when converted to a MIDI byte sequence.

Type:

int or None

du

playing duration in ticks (time difference between note-on and note-off in the performance). When this attribute is absent, it is assumed to have the same value as the L attribute.

Type:

ticks, optional

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • n (int or Pitch) – value of the n attribute

  • L (ticks) – value of the L attribute

  • v (int, optional) – value of the v attribute

  • nv (int or None, optional) – value of the nv attribute

  • du (ticks, optional) – value of the du attribute

  • tk (int, optional) – value of the tk attribute

  • ch (int, optional) – value of the ch attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

get_du() → Union[int, float, Fraction]

Returns the value of the du attribute (or the value of L if it is missing).

offtime() → Union[int, float, Fraction]

Returns the notated note-off time (sum of the t and L attribute values).

pofftime() → Union[int, float, Fraction]

Returns the played note-off time.

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

class NoteOnEvent(t, n, v=80, tk=1, ch=1, dt=0, **kwargs)

Bases: NoteEventClass

Class for note-on events.

Attributes

ch

MIDI channel number (starting from 1)

Type:

int

n

MIDI note number

Type:

int or Pitch

v

MIDI velocity

Type:

int

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • n (int or Pitch) – value of the n attribute

  • v (int, optional) – value of the v attribute

  • tk (int, optional) – value of the tk attribute

  • ch (int, optional) – value of the ch attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

class NoteOffEvent(t, n, nv=None, tk=1, ch=1, dt=0, **kwargs)

Bases: NoteEventClass

Class for note-off events.

Attributes

ch

MIDI channel number (starting from 1)

Type:

int

n

MIDI note number

Type:

int or Pitch

nv

MIDI note-off velocity; if this is None, a note-on message with zero velocity is used when converted to a MIDI byte sequence.

Type:

int or None

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • n (int or Pitch) – value of the n attribute

  • nv (int or None, optional) – value of the nv attribute

  • tk (int, optional) – value of the tk attribute

  • ch (int, optional) – value of the ch attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

class CtrlEvent(t, ctrlnum, value, tk=1, ch=1, dt=0, **kwargs)

Bases: Event

Class of control events with controller number and control value. This includes MIDI Control Change, Program Change, Pitch Bend, Channel Pressure, and Key Pressure. For Key Pressure, a dedicated subclass is provided, so use its constructor when instantiating.

Attributes

ch

MIDI channel number (starting from 1)

Type:

int

ctrlnum

controller number, with the following meaning

  • 0 to 127: MIDI control change (value is from 0 to 127)

  • 128(C_BEND): MIDI pitch bend (value is from -8192 to 8191)

  • 129(C_KPR): MIDI key pressure (see KeyPressureEvent)

  • 130(C_CPR): MIDI channel pressure (value is from 0 to 127)

  • 131(C_PROG): MIDI program change (value is from 1 to 128)

  • Other: For internal processing.

Type:

int

value

control value

Type:

int, etc.

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • ctrlnum (int) – value of ctrlnum attribute

  • value (int, etc.) – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • ch (int, optional) – value of the ch attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

class KeyPressureEvent(t, n, value, tk=1, ch=1, dt=0, **kwargs)

Bases: CtrlEvent

Class of Key Pressure events.

Attributes

n

MIDI note number

Type:

int or Pitch

value

control value (0-127)

Type:

int or float

Other Inherited Attributes

t, tk, dt, ch, ctrlnum

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • n (int or Pitch) – value of the n attribute

  • value (int, etc.) – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • ch (int, optional) – value of the ch attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

class SysExEvent(t, value, tk=1, dt=0, **kwargs)

Bases: Event

Class for system-exclusive message events.

Attributes

value

The contents of the message explicitly including the leading 0xf0 and trailing 0xf7. It is possible to split a single message into multiple SysExEvent’s, in which case 0xf0 is placed in the first event and 0xf7 in the last.

Type:

bytes, bytearray, or iterable of int

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • value (bytes, bytearray, or iterable of int) – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]
Convert the event to a byte sequence (sequence prefixed with an

additional 0xf0).

Parameters:

errhdr (str, optional) – header string for error and warning messages

class MetaEvent(t, mtype, value, tk=1, dt=0, **kwargs)

Bases: Event

Class for meta events defined in Standard MIDI files. This includes text events, key signature events, time signature events, tempo change events, and end-of-track events.

Attributes

mtype

type of meta event (0-127)

Type:

int

value

Data of the meta event. If mtype is from 1 to 15, this attribute should be of type str. If mtype is M_KEYSIG (key signature event), this attribute must be of type Key. If mtype is M_TEMPO (tempo change event), this attribute must be of type int or float. For other meta events, bytes, bytearray, or iterable of int is recommended.

Type:

bytes, bytearray, str, Key, int, float, or iterable of int

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • mtype (int) – value of the mtype attribute

  • value (bytes, bytearray, str, Key, int, float, or iterable of int) – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event

Notes

The key signature event, the time signature event, and the tempo change event have their own subclasses. When instantiating a tempo change event, use the dedicated subclass (TempoEvent). Although it is possible to create the key and time signature events using the constructor of this class, it is more convenient to use the constructor of each subclass.


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='', encoding='utf-8') → Union[bytes, bytearray]

Converts the event to a byte sequence (data in a standard MIDI file without length information).

Parameters:

  • errhdr (str, optional) – header string for error and warning messages

  • encoding (str) – specifies how the text event’s string should be encoded in the byte sequence.

class KeySignatureEvent(t, value, tk=0, dt=0, **kwargs)

Bases: MetaEvent

Class for key signature events.

Inherited Attributes

t, tk, dt, mtype, value

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • value (Key, int, or str) – first argument of the Key constructor

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attribute for the event


to_message(errhdr='', encoding='utf-8') → Union[bytes, bytearray]

Converts the event to a byte sequence (data in a standard MIDI file without length information).

Parameters:

  • errhdr (str, optional) – header string for error and warning messages

  • encoding (str) – specifies how the text event’s string should be encoded in the byte sequence.

class TimeSignatureEvent(t, num, den, cc=None, tk=0, dt=0, **kwargs)

Bases: MetaEvent

Class for time signature events.

Inherited Attributes

t, tk, dt, mtype, value

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • num (int) – value of the numerator

  • den (int) – value of the denominator

  • cc (int, optional) – interval between metronome clicks in units of 1/24 of a quarter note. By default, it is automatically guessed from num and den.

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event

Examples

TimeSignatureEvent(0, 3, 4) for 3/4 time and zero event time.


numerator() → int

Returns the value of the numerator.

denominator() → int

Returns the value of the denominator.

num_den() → Tuple[int, int]

Returns a 2-tuple consisting of the numerator and denominator.

get_cc() → int

Returns the interval between metronome clicks (in 1/24ths of a quarter note).

tostr(timereprfunc=<function std_time_repr>) → str

Returns a string representation of the event.

Parameters:

timereprfunc (function) – Function to convert a value of time to a string. By default, it assumes a function that returns a representation rounded to 5 decimal places.

beat_length() → Union[int, float, Fraction]

Returns the length of one beat in ticks.

measure_length() → Union[int, float, Fraction]

Returns the length of one measure in ticks.

class TempoEvent(t, value, tk=0, dt=0, **kwargs)

Bases: MetaEvent

Class for tempo change events.

Attributes

value

tempo value in quarter notes per minute (minimum value is 4)

Type:

int or float

Other Inherited Attributes

t, tk, dt, mtype, value

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • value (int or float) – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attributes for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='', encoding='utf-8') → Union[bytes, bytearray]

Converts the event to a byte sequence (data in a standard MIDI file without length information).

Parameters:

  • errhdr (str, optional) – header string for error and warning messages

  • encoding (str) – specifies how the text event’s string should be encoded in the byte sequence.

class LoopBackEvent(t, value, tk=0, dt=0, **kwargs)

Bases: Event

Class for loopback events.

Attributes

value

Arbitrary data to distinguish events

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of the t attribute

  • value (str) – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attribute for the event


copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages

class XmlEvent(t, xtype, value, tk=1, dt=0, **kwargs)

Bases: Event

A class of events describing additional information for staff notation.

Attributes

xtype

a string representing the type of information

Type:

str

value

Content data of information

Other Inherited Attributes

t, tk, dt

Constructor

Parameters:

  • t (ticks) – value of t attribute

  • xtype (str) – value of the xtype attribute

  • value – value of the value attribute

  • tk (int, optional) – value of the tk attribute

  • dt (ticks, optional) – value of the dt attribute

  • kwargs – additional attribute for the event

List of valid events

xtype

desc.

value

optional attrs.

‘clef’

clef

‘G’, ‘F’, ‘C’ ‘percussion’, ‘TAB’, ‘jianpu’, ‘none’

line(int), octave_change (int)

‘barline’

bar line

‘dashed’, ‘dotted’, ‘heavy’, ‘heavy-heavy’, ‘heavy-light’, ‘light-heavy’, ‘light-light’, ‘none’, ‘regular’, ‘short’, ‘tick’, ‘double’, ‘final’, ‘repeat-start’, ‘repeat-end’

‘chord’

chord symbol

Chord

‘text’

generic text

str

copy() → Event

Returns a copied event (shallow copy).

to_message(errhdr='') → Union[bytes, bytearray]

Convert an event to a byte sequence.

Parameters:

errhdr (str, optional) – header string for error and warning messages