Event Primitives

Notes

class NoteTick(time: int, duration: int, pitch: int, velocity: int = 0)

Bases: object

Pitched event anchored to a tick timestamp with editable duration and velocity.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

  • Durations use the same tick units

copy(self, deep: bool = True, /) → NoteTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

empty(self) → bool

Return True when the note duration is zero.

ent_time(self) → int

Read or set the exclusive end time. Setting the value adjusts the duration.

shift_pitch(self, offset: int, inplace: bool = False) → symusic.core.NoteTick

Shift the MIDI pitch by offset. Returns a new note unless inplace is True.

shift_time(self, offset: int, inplace: bool = False) → NoteTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

shift_velocity(self, offset: int, inplace: bool = False) → symusic.core.NoteTick

Offset the MIDI velocity by offset. Returns a new note unless inplace is True.

property duration: int

(self) -> int

property end: int

Read or set the exclusive end time. Setting the value adjusts the duration.

property pitch: int

(self) -> int

property start: int

(self) -> int

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

property velocity: int

(self) -> int

class NoteQuarter(time: float, duration: float, pitch: int, velocity: int = 0)

Bases: object

Pitched event anchored to a quarter note timestamp with editable duration and velocity.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

  • Durations use the same quarter note units

copy(self, deep: bool = True, /) → NoteQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

empty(self) → bool

Return True when the note duration is zero.

ent_time(self) → float

Read or set the exclusive end time. Setting the value adjusts the duration.

shift_pitch(self, offset: int, inplace: bool = False) → symusic.core.NoteQuarter

Shift the MIDI pitch by offset. Returns a new note unless inplace is True.

shift_time(self, offset: float, inplace: bool = False) → NoteQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

shift_velocity(self, offset: int, inplace: bool = False) → symusic.core.NoteQuarter

Offset the MIDI velocity by offset. Returns a new note unless inplace is True.

property duration: float

(self) -> float

property end: float

Read or set the exclusive end time. Setting the value adjusts the duration.

property pitch: int

(self) -> int

property start: float

(self) -> float

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

property velocity: int

(self) -> int

class NoteSecond(time: float, duration: float, pitch: int, velocity: int = 0)

Bases: object

Pitched event anchored to a second timestamp with editable duration and velocity.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

  • Durations use the same second units

copy(self, deep: bool = True, /) → NoteSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

empty(self) → bool

Return True when the note duration is zero.

ent_time(self) → float

Read or set the exclusive end time. Setting the value adjusts the duration.

shift_pitch(self, offset: int, inplace: bool = False) → symusic.core.NoteSecond

Shift the MIDI pitch by offset. Returns a new note unless inplace is True.

shift_time(self, offset: float, inplace: bool = False) → NoteSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

shift_velocity(self, offset: int, inplace: bool = False) → symusic.core.NoteSecond

Offset the MIDI velocity by offset. Returns a new note unless inplace is True.

property duration: float

(self) -> float

property end: float

Read or set the exclusive end time. Setting the value adjusts the duration.

property pitch: int

(self) -> int

property start: float

(self) -> float

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

property velocity: int

(self) -> int

Control Changes

class ControlChangeTick(time: int, number: int, value: int)

Bases: object

Standard MIDI controller event carrying a controller number/value pair on the tick timeline.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

copy(self, deep: bool = True, /) → ControlChangeTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → ControlChangeTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property number: int

(self) -> int

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

property value: int

(self) -> int

class ControlChangeQuarter(time: float, number: int, value: int)

Bases: object

Standard MIDI controller event carrying a controller number/value pair on the quarter note timeline.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

copy(self, deep: bool = True, /) → ControlChangeQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → ControlChangeQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property number: int

(self) -> int

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

property value: int

(self) -> int

class ControlChangeSecond(time: float, number: int, value: int)

Bases: object

Standard MIDI controller event carrying a controller number/value pair on the second timeline.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

copy(self, deep: bool = True, /) → ControlChangeSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → ControlChangeSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property number: int

(self) -> int

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

property value: int

(self) -> int

Tempo

class TempoTick(time: int, mspq: int)

Bases: object

Tempo change stored as microseconds-per-quarter note at a tick timestamp. The qpm property mirrors beats-per-minute and mutating it updates mspq accordingly.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

copy(self, deep: bool = True, /) → TempoTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → TempoTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property mspq: int

(self) -> int

property qpm: float

Read or set the tempo in quarter-notes per minute. Setting recalculates the stored MSPQ value.

property tempo: float

Read or set the tempo in quarter-notes per minute. Setting recalculates the stored MSPQ value.

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

class TempoQuarter(time: float, mspq: int)

Bases: object

Tempo change stored as microseconds-per-quarter note at a quarter note timestamp. The qpm property mirrors beats-per-minute and mutating it updates mspq accordingly.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

copy(self, deep: bool = True, /) → TempoQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → TempoQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property mspq: int

(self) -> int

property qpm: float

Read or set the tempo in quarter-notes per minute. Setting recalculates the stored MSPQ value.

property tempo: float

Read or set the tempo in quarter-notes per minute. Setting recalculates the stored MSPQ value.

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

class TempoSecond(time: float, mspq: int)

Bases: object

Tempo change stored as microseconds-per-quarter note at a second timestamp. The qpm property mirrors beats-per-minute and mutating it updates mspq accordingly.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

copy(self, deep: bool = True, /) → TempoSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → TempoSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property mspq: int

(self) -> int

property qpm: float

Read or set the tempo in quarter-notes per minute. Setting recalculates the stored MSPQ value.

property tempo: float

Read or set the tempo in quarter-notes per minute. Setting recalculates the stored MSPQ value.

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

Pedals

class PedalTick(time: int, duration: int)

Bases: object

Sustain or soft pedal gesture represented as a timed range on the tick timeline.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

  • Durations use the same tick units

copy(self, deep: bool = True, /) → PedalTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → PedalTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property duration: int

(self) -> int

property end: int

(self) -> int

property start: int

(self) -> int

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

class PedalQuarter(time: float, duration: float)

Bases: object

Sustain or soft pedal gesture represented as a timed range on the quarter note timeline.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

  • Durations use the same quarter note units

copy(self, deep: bool = True, /) → PedalQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → PedalQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property duration: float

(self) -> float

property end: float

(self) -> float

property start: float

(self) -> float

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

class PedalSecond(time: float, duration: float)

Bases: object

Sustain or soft pedal gesture represented as a timed range on the second timeline.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

  • Durations use the same second units

copy(self, deep: bool = True, /) → PedalSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → PedalSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property duration: float

(self) -> float

property end: float

(self) -> float

property start: float

(self) -> float

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

Pitch Bend

class PitchBendTick(time: int, value: int)

Bases: object

Pitch-bend wheel value applied on the tick timeline. The raw 14-bit value matches the MIDI encoding.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

copy(self, deep: bool = True, /) → PitchBendTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → PitchBendTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

property value: int

(self) -> int

class PitchBendQuarter(time: float, value: int)

Bases: object

Pitch-bend wheel value applied on the quarter note timeline. The raw 14-bit value matches the MIDI encoding.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

copy(self, deep: bool = True, /) → PitchBendQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → PitchBendQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

property value: int

(self) -> int

class PitchBendSecond(time: float, value: int)

Bases: object

Pitch-bend wheel value applied on the second timeline. The raw 14-bit value matches the MIDI encoding.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

copy(self, deep: bool = True, /) → PitchBendSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → PitchBendSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

property value: int

(self) -> int

Key Signatures

class KeySignatureTick(time: int, key: int, tonality: int)

Bases: object

Key signature change scheduled on the tick timeline. key is the number of sharps/flats relative to C and tonality is 0 for major, 1 for minor.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

copy(self, deep: bool = True, /) → KeySignatureTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → KeySignatureTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property key: int

(self) -> int

property time: int

Event timestamp in chosen time unit

property tonality: int

(self) -> int

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

class KeySignatureQuarter(time: float, key: int, tonality: int)

Bases: object

Key signature change scheduled on the quarter note timeline. key is the number of sharps/flats relative to C and tonality is 0 for major, 1 for minor.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

copy(self, deep: bool = True, /) → KeySignatureQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → KeySignatureQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property key: int

(self) -> int

property time: float

Event timestamp in chosen time unit

property tonality: int

(self) -> int

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

class KeySignatureSecond(time: float, key: int, tonality: int)

Bases: object

Key signature change scheduled on the second timeline. key is the number of sharps/flats relative to C and tonality is 0 for major, 1 for minor.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

copy(self, deep: bool = True, /) → KeySignatureSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → KeySignatureSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property key: int

(self) -> int

property time: float

Event timestamp in chosen time unit

property tonality: int

(self) -> int

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

Time Signatures

class TimeSignatureTick(time: int, numerator: int, denominator: int)

Bases: object

Meter change storing beats-per-bar and subdivision (e.g., 3/4) on the tick timeline. The denominator must be a power of two because it represents note lengths.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

copy(self, deep: bool = True, /) → TimeSignatureTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → TimeSignatureTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property denominator: int

(self) -> int

property numerator: int

(self) -> int

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

class TimeSignatureQuarter(time: float, numerator: int, denominator: int)

Bases: object

Meter change storing beats-per-bar and subdivision (e.g., 3/4) on the quarter note timeline. The denominator must be a power of two because it represents note lengths.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

copy(self, deep: bool = True, /) → TimeSignatureQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → TimeSignatureQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property denominator: int

(self) -> int

property numerator: int

(self) -> int

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

class TimeSignatureSecond(time: float, numerator: int, denominator: int)

Bases: object

Meter change storing beats-per-bar and subdivision (e.g., 3/4) on the second timeline. The denominator must be a power of two because it represents note lengths.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

copy(self, deep: bool = True, /) → TimeSignatureSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → TimeSignatureSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property denominator: int

(self) -> int

property numerator: int

(self) -> int

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second

Text Meta

class TextMetaTick(time: int, text: str)

Bases: object

Free-form metadata event used for lyrics, markers, or comments on the tick timeline.

  • Time values are signed 32-bit tick offsets based on the score’s ticks-per-quarter.

  • Optimized for lossless MIDI editing or workflows that must match the original resolution

copy(self, deep: bool = True, /) → TextMetaTick

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: int, inplace: bool = False) → TextMetaTick

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property text: str

(self) -> str

property time: int

Event timestamp in chosen time unit

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

class TextMetaQuarter(time: float, text: str)

Bases: object

Free-form metadata event used for lyrics, markers, or comments on the quarter note timeline.

  • Time values are 32-bit floats measured in musical quarter notes.

  • Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms

copy(self, deep: bool = True, /) → TextMetaQuarter

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → TextMetaQuarter

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property text: str

(self) -> str

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

class TextMetaSecond(time: float, text: str)

Bases: object

Free-form metadata event used for lyrics, markers, or comments on the second timeline.

  • Time values are 32-bit floats measured in seconds.

  • Optimized for audio alignment, wall-clock automation, or duration-based editing

copy(self, deep: bool = True, /) → TextMetaSecond

Return a shallow or deep copy depending on deep. Deep copies duplicate underlying storage.

shift_time(self, offset: float, inplace: bool = False) → TextMetaSecond

Shift the event’s timestamp by offset. When inplace is False a cloned event is returned.

property text: str

(self) -> str

property time: float

Event timestamp in chosen time unit

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second