Scores¶

Tick

class ScoreTick(tpq: int = 480)¶

Bases: object

Container for a full MIDI score consisting of named tracks, tempo/key/time metadata, and helper methods for serialization and transformations. This variant stores timestamps as discrete MIDI ticks so round-trips remain lossless.

Parameters:: tpq – Ticks-per-quarter resolution that defines how many integer steps make a quarter note (usually 480 or 960).

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
Score objects expose Pythonic semantics such as slicing, repr/eq, and pickling.
tpq travels with the tempo map so conversions remain lossless.

Examples

from symusic import ScoreTick
score = ScoreTick(960)
dump_path = "example.mid"
score.dump_midi(dump_path)

static from_abc(abc: str) → symusic.core.ScoreTick¶: Parse an ABC notation string into a score. Requires the SYMUSIC_ABC2MIDI environment variable to point to the abc2midi executable.

static from_file(path: str | os.PathLike, format: str | None = None, sanitize_data: bool = False) → symusic.core.ScoreTick¶: Read a score from disk by auto-detecting a MIDI or ABC file. Use format ("midi" or "abc") when the extension is ambiguous.

static from_midi(data: bytes, sanitize_data: bool = False) → symusic.core.ScoreTick¶: Parse raw MIDI bytes into a score. When sanitize_data is True, controller/pitch values are clamped into the MIDI-safe range.

adjust_time(self, original_times: collections.abc.Sequence[int], new_times: collections.abc.Sequence[int], inplace: bool = False) → symusic.core.ScoreTick¶: Remap timestamps across all tracks using aligned original/new time arrays. Operates in place unless specified.

clip(self, start: int, end: int, clip_end: bool = False, inplace: bool = False) → symusic.core.ScoreTick¶: Clip the score to [start, end). When inplace is False returns a new score.

copy(self, deep: bool = True, /) → ScoreTick¶: Return a shallow or deep copy depending on deep.

dump_abc(self, path: str | os.PathLike, warn: bool = False) → None¶: Dump the score to an ABC file via midi2abc. Temporary MIDI files are cleaned up automatically.

dump_midi(self, path: str | os.PathLike) → None¶: Write the score to a MIDI file using the current ticks-per-quarter resolution.

dumps_abc(self, warn: bool = False) → str¶: Return the score as an ABC notation string. Set warn to False to silence stderr.

dumps_midi(self) → bytes¶: Serialize the score into MIDI bytes for in-memory workflows.

empty(self) → bool¶: Return True when the score contains no notes.

end(self) → int¶: Return the exclusive end timestamp across all tracks.

get_beats(self, start_time: int = 0) → numpy.ndarray[dtype=int32]¶: Return beat locations as a NumPy array in the score’s current time unit. Compound meters follow the PrettyMIDI heuristic of grouping every three denominator notes into one beat.

get_downbeats(self, start_time: int = 0) → numpy.ndarray[dtype=int32]¶: Return downbeat locations as a NumPy array in the score’s current time unit. When no time signature is available at start_time, a 4/4 sentinel is assumed.

note_num(self) → int¶: Return the total number of notes across all tracks.

pianoroll(self, modes: collections.abc.Sequence[str] = ['frame', 'onset'], pitch_range: tuple[int, int] = (0, 128), encode_velocity: bool = False) → numpy.ndarray[dtype=uint8]¶: Export a tick-based score as a pianoroll NumPy tensor. mode controls aggregation, pitch_range bounds the vertical axis, and encode_velocity switches from binary to velocity encoding.

resample(self, tpq: int, min_dur: int | None = None) → symusic.core.ScoreTick¶: Resample the score to a new ticks-per-quarter resolution. min_dur controls rounding behaviour when reducing resolution.

shift_pitch(self, offset: int, inplace: bool = False) → symusic.core.ScoreTick¶: Shift every note by offset semitones. When inplace is False operate on a copy.

shift_time(self, offset: int, inplace: bool = False) → symusic.core.ScoreTick¶: Shift every event timestamp by offset. When inplace is False operate on a copy.

shift_velocity(self, offset: int, inplace: bool = False) → symusic.core.ScoreTick¶: Shift every note velocity by offset. When inplace is False operate on a copy.

sort(self, reverse: bool = False, inplace: bool = True) → symusic.core.ScoreTick¶: Sort tracks chronologically. When inplace is False the operation occurs on a copy.

start(self) → int¶: Return the earliest timestamp across all tracks.

to(self, ttype: object, min_dur: object | None = None) → object¶: Convert the score to another time unit (Tick, Quarter, Second). ttype may be a class object or "tick"/"quarter"/"second". min_dur snaps durations when downsampling.

property key_signatures: symusic.core.KeySignatureTickList¶: List of key signature events

property markers: symusic.core.TextMetaTickList¶: List of text/marker events

property tempos: symusic.core.TempoTickList¶: List of tempo events

property ticks_per_quarter: int¶: Ticks per quarter note

property time_signatures: symusic.core.TimeSignatureTickList¶: List of time signature events

property tpq: int¶: Alias of ticks_per_quarter

property tracks: symusic.core.TrackTickList¶: List of tracks

property ttype: symusic.core.Tick¶: Time unit type — Tick/Quarter/Second

Quarter

class ScoreQuarter(tpq: int = 480)¶

Bases: object

Container for a full MIDI score consisting of named tracks, tempo/key/time metadata, and helper methods for serialization and transformations. This variant stores timestamps as floating-point quarter-note counts (1.0 equals one beat).

Parameters:: tpq – Reference ticks-per-quarter carried from the source score so conversions to ticks stay deterministic.

Note

Time values are 32-bit floats measured in musical quarter notes.
Optimized for beat-aware editing, tuplets, swing adjustments, or tempo-relative transforms
Score objects expose Pythonic semantics such as slicing, repr/eq, and pickling.
tpq travels with the tempo map so conversions remain lossless.

Examples

from symusic import ScoreQuarter
score = ScoreQuarter(960)
dump_path = "example.mid"
score.dump_midi(dump_path)

static from_abc(abc: str) → symusic.core.ScoreQuarter¶: Parse an ABC notation string into a score. Requires the SYMUSIC_ABC2MIDI environment variable to point to the abc2midi executable.

static from_file(path: str | os.PathLike, format: str | None = None, sanitize_data: bool = False) → symusic.core.ScoreQuarter¶: Read a score from disk by auto-detecting a MIDI or ABC file. Use format ("midi" or "abc") when the extension is ambiguous.

static from_midi(data: bytes, sanitize_data: bool = False) → symusic.core.ScoreQuarter¶: Parse raw MIDI bytes into a score. When sanitize_data is True, controller/pitch values are clamped into the MIDI-safe range.

adjust_time(self, original_times: collections.abc.Sequence[float], new_times: collections.abc.Sequence[float], inplace: bool = False) → symusic.core.ScoreQuarter¶: Remap timestamps across all tracks using aligned original/new time arrays. Operates in place unless specified.

clip(self, start: float, end: float, clip_end: bool = False, inplace: bool = False) → symusic.core.ScoreQuarter¶: Clip the score to [start, end). When inplace is False returns a new score.

copy(self, deep: bool = True, /) → ScoreQuarter¶: Return a shallow or deep copy depending on deep.

dump_abc(self, path: str | os.PathLike, warn: bool = False) → None¶: Dump the score to an ABC file via midi2abc. Temporary MIDI files are cleaned up automatically.

dump_midi(self, path: str | os.PathLike) → None¶: Write the score to a MIDI file using the current ticks-per-quarter resolution.

dumps_abc(self, warn: bool = False) → str¶: Return the score as an ABC notation string. Set warn to False to silence stderr.

dumps_midi(self) → bytes¶: Serialize the score into MIDI bytes for in-memory workflows.

empty(self) → bool¶: Return True when the score contains no notes.

end(self) → float¶: Return the exclusive end timestamp across all tracks.

get_beats(self, start_time: float = 0.0) → numpy.ndarray[dtype=float32]¶: Return beat locations as a NumPy array in the score’s current time unit. Compound meters follow the PrettyMIDI heuristic of grouping every three denominator notes into one beat.

get_downbeats(self, start_time: float = 0.0) → numpy.ndarray[dtype=float32]¶: Return downbeat locations as a NumPy array in the score’s current time unit. When no time signature is available at start_time, a 4/4 sentinel is assumed.

note_num(self) → int¶: Return the total number of notes across all tracks.

resample(self, tpq: int, min_dur: float | None = None) → symusic.core.ScoreTick¶: Resample the score to a new ticks-per-quarter resolution. min_dur controls rounding behaviour when reducing resolution.

shift_pitch(self, offset: int, inplace: bool = False) → symusic.core.ScoreQuarter¶: Shift every note by offset semitones. When inplace is False operate on a copy.

shift_time(self, offset: float, inplace: bool = False) → symusic.core.ScoreQuarter¶: Shift every event timestamp by offset. When inplace is False operate on a copy.

shift_velocity(self, offset: int, inplace: bool = False) → symusic.core.ScoreQuarter¶: Shift every note velocity by offset. When inplace is False operate on a copy.

sort(self, reverse: bool = False, inplace: bool = True) → symusic.core.ScoreQuarter¶: Sort tracks chronologically. When inplace is False the operation occurs on a copy.

start(self) → float¶: Return the earliest timestamp across all tracks.

to(self, ttype: object, min_dur: object | None = None) → object¶: Convert the score to another time unit (Tick, Quarter, Second). ttype may be a class object or "tick"/"quarter"/"second". min_dur snaps durations when downsampling.

property key_signatures: symusic.core.KeySignatureQuarterList¶: List of key signature events

property markers: symusic.core.TextMetaQuarterList¶: List of text/marker events

property tempos: symusic.core.TempoQuarterList¶: List of tempo events

property ticks_per_quarter: int¶: Ticks per quarter note

property time_signatures: symusic.core.TimeSignatureQuarterList¶: List of time signature events

property tpq: int¶: Alias of ticks_per_quarter

property tracks: symusic.core.TrackQuarterList¶: List of tracks

property ttype: symusic.core.Quarter¶: Time unit type — Tick/Quarter/Second

Second

class ScoreSecond(tpq: int = 480)¶

Bases: object

Parameters:: tpq – Reference ticks-per-quarter retained for precise conversion back to tick or beat timelines.

Note

Time values are 32-bit floats measured in seconds.
Optimized for audio alignment, wall-clock automation, or duration-based editing
Score objects expose Pythonic semantics such as slicing, repr/eq, and pickling.
tpq travels with the tempo map so conversions remain lossless.

Examples

from symusic import ScoreSecond
score = ScoreSecond(960)
dump_path = "example.mid"
score.dump_midi(dump_path)

static from_abc(abc: str) → symusic.core.ScoreSecond¶: Parse an ABC notation string into a score. Requires the SYMUSIC_ABC2MIDI environment variable to point to the abc2midi executable.

static from_file(path: str | os.PathLike, format: str | None = None, sanitize_data: bool = False) → symusic.core.ScoreSecond¶: Read a score from disk by auto-detecting a MIDI or ABC file. Use format ("midi" or "abc") when the extension is ambiguous.

static from_midi(data: bytes, sanitize_data: bool = False) → symusic.core.ScoreSecond¶: Parse raw MIDI bytes into a score. When sanitize_data is True, controller/pitch values are clamped into the MIDI-safe range.

adjust_time(self, original_times: collections.abc.Sequence[float], new_times: collections.abc.Sequence[float], inplace: bool = False) → symusic.core.ScoreSecond¶: Remap timestamps across all tracks using aligned original/new time arrays. Operates in place unless specified.

clip(self, start: float, end: float, clip_end: bool = False, inplace: bool = False) → symusic.core.ScoreSecond¶: Clip the score to [start, end). When inplace is False returns a new score.

copy(self, deep: bool = True, /) → ScoreSecond¶: Return a shallow or deep copy depending on deep.

dump_abc(self, path: str | os.PathLike, warn: bool = False) → None¶: Dump the score to an ABC file via midi2abc. Temporary MIDI files are cleaned up automatically.

dump_midi(self, path: str | os.PathLike) → None¶: Write the score to a MIDI file using the current ticks-per-quarter resolution.

dumps_abc(self, warn: bool = False) → str¶: Return the score as an ABC notation string. Set warn to False to silence stderr.

dumps_midi(self) → bytes¶: Serialize the score into MIDI bytes for in-memory workflows.

empty(self) → bool¶: Return True when the score contains no notes.

end(self) → float¶: Return the exclusive end timestamp across all tracks.

get_beats(self, start_time: float = 0.0) → numpy.ndarray[dtype=float32]¶: Return beat locations as a NumPy array in the score’s current time unit. Compound meters follow the PrettyMIDI heuristic of grouping every three denominator notes into one beat.

get_downbeats(self, start_time: float = 0.0) → numpy.ndarray[dtype=float32]¶: Return downbeat locations as a NumPy array in the score’s current time unit. When no time signature is available at start_time, a 4/4 sentinel is assumed.

note_num(self) → int¶: Return the total number of notes across all tracks.

resample(self, tpq: int, min_dur: float | None = None) → symusic.core.ScoreTick¶: Resample the score to a new ticks-per-quarter resolution. min_dur controls rounding behaviour when reducing resolution.

shift_pitch(self, offset: int, inplace: bool = False) → symusic.core.ScoreSecond¶: Shift every note by offset semitones. When inplace is False operate on a copy.

shift_time(self, offset: float, inplace: bool = False) → symusic.core.ScoreSecond¶: Shift every event timestamp by offset. When inplace is False operate on a copy.

shift_velocity(self, offset: int, inplace: bool = False) → symusic.core.ScoreSecond¶: Shift every note velocity by offset. When inplace is False operate on a copy.

sort(self, reverse: bool = False, inplace: bool = True) → symusic.core.ScoreSecond¶: Sort tracks chronologically. When inplace is False the operation occurs on a copy.

start(self) → float¶: Return the earliest timestamp across all tracks.

to(self, ttype: object, min_dur: object | None = None) → object¶: Convert the score to another time unit (Tick, Quarter, Second). ttype may be a class object or "tick"/"quarter"/"second". min_dur snaps durations when downsampling.

property key_signatures: symusic.core.KeySignatureSecondList¶: List of key signature events

property markers: symusic.core.TextMetaSecondList¶: List of text/marker events

property tempos: symusic.core.TempoSecondList¶: List of tempo events

property ticks_per_quarter: int¶: Ticks per quarter note

property time_signatures: symusic.core.TimeSignatureSecondList¶: List of time signature events

property tpq: int¶: Alias of ticks_per_quarter

property tracks: symusic.core.TrackSecondList¶: List of tracks

property ttype: symusic.core.Second¶: Time unit type — Tick/Quarter/Second