Tracks

class TrackTick(name: str = '', program: int = 0, is_drum: bool = False)

Bases: object

Container for per-channel events (notes, controllers, pedals, pitch bends, metadata) tied to a MIDI program. Tracks emulate Python lists: copy, compare, repr, and pickling propagate through the shared pointer. This variant stores timestamps as discrete MIDI ticks so round-trips remain lossless.

Parameters:

  • name – Human-friendly identifier used when printing or exporting.

  • program – MIDI program number (0-127). Defaults to acoustic grand piano.

  • is_drum – Flag drum/percussion channels. Useful when writing to SMF channel 10.

Note

  • 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 and controller timestamps share the same tick units

Examples

from symusic import TrackTick, NoteTick
track = TrackTick(name=\"Piano\")
track.notes.append(NoteTick(0, 120, 60, 90))
adjust_time(self, original_times: Iterable[int], new_times: Iterable[int], inplace: bool = False) → TrackTick

Remap timestamps using two aligned lists of original/new time values.

clip(self, start: int, end: int, clip_end: bool = False, inplace: bool = False) → TrackTick

Return a track clipped to [start, end). When inplace is False operate on a deep copy.

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

Return a shallow or deep copy depending on deep.

empty(self, /) → bool

Return True when the track has no notes.

end(self, /) → int

Return the exclusive end of the track.

note_num(self, /) → int

Return the number of notes on the track.

pianoroll(self, modes: Iterable[str] = ('frame', 'onset'), pitch_range: Tuple[int, int] = (0, 128), encode_velocity: bool = False) → numpy.ndarray

Export a tick-based track as a pianoroll NumPy tensor. Modes control channels, pitch_range bounds the vertical axis, and encode_velocity switches from binary to velocity encoding.

shift_pitch(self, offset: int, inplace: bool = False) → TrackTick

Shift every note’s pitch by offset. Operates in place unless inplace is False.

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

Shift every timestamp by offset. Operates in place unless inplace is False.

shift_velocity(self, offset: int, inplace: bool = False) → TrackTick

Shift every note’s velocity by offset. Operates in place unless inplace is False.

sort(self, reverse: bool = False, inplace: bool = True) → TrackTick

Sort notes chronologically. When inplace is False the result is a cloned track.

start(self, /) → int

Return the earliest event time (or max if empty).

trim(self, start: int, end: int, min_overlap: int = 0, start_mode: str = 'remove', end_mode: str = 'remove', inplace: bool = False) → TrackTick

Trim notes to fall within [start, end) using overlap/window strategies. Optionally mutate in place.

property controls: symusic.core.ControlChangeTickList

List of ControlChange events

property is_drum: bool

Flag drum/percussion channel (GM channel 10)

property lyrics: symusic.core.TextMetaTickList

List of TextMeta events (lyrics/markers)

property name: str

Human-friendly track name

property notes: symusic.core.NoteTickList

List of Note events on this track

property pedals: symusic.core.PedalTickList

List of Pedal events

property pitch_bends: symusic.core.PitchBendTickList

List of PitchBend events

property program: int

MIDI program number (0–127)

property ttype: symusic.core.Tick

Time unit type — Tick/Quarter/Second

class TrackQuarter(name: str = '', program: int = 0, is_drum: bool = False)

Bases: object

Container for per-channel events (notes, controllers, pedals, pitch bends, metadata) tied to a MIDI program. Tracks emulate Python lists: copy, compare, repr, and pickling propagate through the shared pointer. This variant stores timestamps as floating-point quarter-note counts (1.0 equals one beat).

Parameters:

  • name – Human-friendly identifier used when printing or exporting.

  • program – MIDI program number (0-127). Defaults to acoustic grand piano.

  • is_drum – Flag drum/percussion channels. Useful when writing to SMF channel 10.

Note

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

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

  • Durations and controller timestamps share the same quarter note units

Examples

from symusic import TrackQuarter, NoteQuarter
track = TrackQuarter(name=\"Piano\")
track.notes.append(NoteQuarter(0, 120, 60, 90))
adjust_time(self, original_times: Iterable[float], new_times: Iterable[float], inplace: bool = False) → TrackQuarter

Remap timestamps using two aligned lists of original/new time values.

clip(self, start: float, end: float, clip_end: bool = False, inplace: bool = False) → TrackQuarter

Return a track clipped to [start, end). When inplace is False operate on a deep copy.

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

Return a shallow or deep copy depending on deep.

empty(self, /) → bool

Return True when the track has no notes.

end(self, /) → float

Return the exclusive end of the track.

note_num(self, /) → int

Return the number of notes on the track.

shift_pitch(self, offset: int, inplace: bool = False) → TrackQuarter

Shift every note’s pitch by offset. Operates in place unless inplace is False.

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

Shift every timestamp by offset. Operates in place unless inplace is False.

shift_velocity(self, offset: int, inplace: bool = False) → TrackQuarter

Shift every note’s velocity by offset. Operates in place unless inplace is False.

sort(self, reverse: bool = False, inplace: bool = True) → TrackQuarter

Sort notes chronologically. When inplace is False the result is a cloned track.

start(self, /) → float

Return the earliest event time (or max if empty).

trim(self, start: float, end: float, min_overlap: float = 0, start_mode: str = 'remove', end_mode: str = 'remove', inplace: bool = False) → TrackQuarter

Trim notes to fall within [start, end) using overlap/window strategies. Optionally mutate in place.

property controls: symusic.core.ControlChangeQuarterList

List of ControlChange events

property is_drum: bool

Flag drum/percussion channel (GM channel 10)

property lyrics: symusic.core.TextMetaQuarterList

List of TextMeta events (lyrics/markers)

property name: str

Human-friendly track name

property notes: symusic.core.NoteQuarterList

List of Note events on this track

property pedals: symusic.core.PedalQuarterList

List of Pedal events

property pitch_bends: symusic.core.PitchBendQuarterList

List of PitchBend events

property program: int

MIDI program number (0–127)

property ttype: symusic.core.Quarter

Time unit type — Tick/Quarter/Second

class TrackSecond(name: str = '', program: int = 0, is_drum: bool = False)

Bases: object

Container for per-channel events (notes, controllers, pedals, pitch bends, metadata) tied to a MIDI program. Tracks emulate Python lists: copy, compare, repr, and pickling propagate through the shared pointer. This variant stores timestamps as floating-point seconds aligned with the tempo map.

Parameters:

  • name – Human-friendly identifier used when printing or exporting.

  • program – MIDI program number (0-127). Defaults to acoustic grand piano.

  • is_drum – Flag drum/percussion channels. Useful when writing to SMF channel 10.

Note

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

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

  • Durations and controller timestamps share the same second units

Examples

from symusic import TrackSecond, NoteSecond
track = TrackSecond(name=\"Piano\")
track.notes.append(NoteSecond(0, 120, 60, 90))
adjust_time(self, original_times: Iterable[float], new_times: Iterable[float], inplace: bool = False) → TrackSecond

Remap timestamps using two aligned lists of original/new time values.

clip(self, start: float, end: float, clip_end: bool = False, inplace: bool = False) → TrackSecond

Return a track clipped to [start, end). When inplace is False operate on a deep copy.

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

Return a shallow or deep copy depending on deep.

empty(self, /) → bool

Return True when the track has no notes.

end(self, /) → float

Return the exclusive end of the track.

note_num(self, /) → int

Return the number of notes on the track.

shift_pitch(self, offset: int, inplace: bool = False) → TrackSecond

Shift every note’s pitch by offset. Operates in place unless inplace is False.

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

Shift every timestamp by offset. Operates in place unless inplace is False.

shift_velocity(self, offset: int, inplace: bool = False) → TrackSecond

Shift every note’s velocity by offset. Operates in place unless inplace is False.

sort(self, reverse: bool = False, inplace: bool = True) → TrackSecond

Sort notes chronologically. When inplace is False the result is a cloned track.

start(self, /) → float

Return the earliest event time (or max if empty).

trim(self, start: float, end: float, min_overlap: float = 0, start_mode: str = 'remove', end_mode: str = 'remove', inplace: bool = False) → TrackSecond

Trim notes to fall within [start, end) using overlap/window strategies. Optionally mutate in place.

property controls: symusic.core.ControlChangeSecondList

List of ControlChange events

property is_drum: bool

Flag drum/percussion channel (GM channel 10)

property lyrics: symusic.core.TextMetaSecondList

List of TextMeta events (lyrics/markers)

property name: str

Human-friendly track name

property notes: symusic.core.NoteSecondList

List of Note events on this track

property pedals: symusic.core.PedalSecondList

List of Pedal events

property pitch_bends: symusic.core.PitchBendSecondList

List of PitchBend events

property program: int

MIDI program number (0–127)

property ttype: symusic.core.Second

Time unit type — Tick/Quarter/Second