symusic (Symbolic Music)

Symusic is a cross-platform symbolic music toolkit designed for high-performance note-level MIDI and ABC workflows. Key capabilities include:

• File I/O: Load MIDI and ABC files using Score("path.mid") or Score("path.abc", fmt="abc"). Export using dump_midi, dump_abc, or dumps_abc.
• Time Conversions: Convert scores between tick, quarter, and second time units.
• Analysis: Compute beats, downbeats, and piano rolls.
• Transformations: Apply vectorized operations on Score and Track objects, including shift_pitch, shift_velocity, shift_time, sort, and filter.
• Serialization: Efficiently serialize containers using pickle or structured NumPy exports.
• Audio Synthesis: Render audio via SoundFonts using Synthesizer, BuiltInSF2, BuiltInSF3, and dump_wav.

The symusic Python package provides high-level factories that mirror the core functionality of the library. Most user-facing surfaces are thin wrappers around nanobind classes defined in symusic.core.

To work with music data, you should primarily use the high-level factories available in the symusic namespace rather than interacting with the low-level core directly, unless you require specific tick-based specializations.

A Score is the root container in Symusic that represents a complete musical piece. It acts as a global context (similar to a DAW session) that aggregates all tracks and global musical events.

Key responsibilities of a Score include:

• Aggregation: Holds all Track objects and global events like tempos, time signatures, and key signatures.
• Global Metadata: Stores ticks_per_quarter (TPQ), which defines the mapping between tick-based time and musical durations.
• Global Transformations: Provides methods to perform operations across the entire piece, such as clip, trim, sort, resample, and time/pitch/velocity shifts.
• Exporting: Serves as the entry point for exporting data to MIDI, ABC, piano rolls, or synthesizing audio.

A Track represents a single musical part within a Score. It acts as a container that groups instrument-specific events and metadata, allowing you to perform part-specific operations like transposing only string instruments or quantizing drum tracks without affecting the rest of the score.

A Track contains:

• Notes: A NoteList of note-on/off events (pitch, duration, velocity).
• Control changes: MIDI CC data (volume, pan, modulation, etc.).
• Pitch bends: High-resolution pitch deviations.
• Pedals: Representations of sustain pedal regions.
• Lyrics/Text: A TextMetaList for annotations or lyrics.

All event lists within a track support list-like methods and helpers such as .start(), .end(), .empty(), .sort(), .filter(), .adjust_time(), and .numpy().

Symusic uses nanobind to generate stubs (symusic/core.pyi) and the py.typed marker automatically during the build process (pip install . or pip install -e .).

The typing surface mirrors the specializations (tick, quarter, second) exposed by the compiled extension. When writing explicit type annotations, use the generic helpers provided in symusic.types and symusic.core.

import symusic.core as core
import symusic.types as smt

score: smt.Score[core.Tick] = core.ScoreTick(480)
notes: core.PyVec[core.Note[core.Tick]] = core.NoteTickList()

A Score is composed of several specialized lists, all backed by high-performance C++ pyvec objects to ensure fast slicing, copying, and filtering. The structure follows this hierarchy:

• ticks_per_quarter: An integer defining the temporal resolution.
• tracks: A TrackList containing Track<T> objects (per-instrument containers).
• tempos: A TempoList for global tempo changes.
• time_signatures: A TimeSignatureList for global meter changes.
• key_signatures: A KeySignatureList for global key changes.
• markers: A TextMetaList for free-form text metadata events.

In symusic.core, events are categorized by the type of musical information they carry and the temporal unit used to position them.

Event Types

• Notes: Musical notes.
• Control Changes: MIDI-style control change messages.
• Tempo: Changes to the musical tempo.
• Pedals: Sustain or pedal state changes.
• Pitch Bend: Pitch modulation events.
• Key Signatures: Changes to the musical key.
• Time Signatures: Changes to the meter/time signature.
• Text Meta: Metadata or text-based annotations.

Timing Modes

Every event type is available in three distinct timing modes, allowing you to specify exactly when an event occurs based on the desired precision:

1. Tick: Positioned using MIDI-style ticks (resolution depends on the file's PPQ).
2. Quarter: Positioned using quarter-note units.
3. Second: Positioned using absolute time in seconds.

A Score object contains global events and a list of Track objects.

Global Events: tempos, time_signatures, key_signatures, and markers.

Track Structure: Each Track contains several list-like containers:

• NoteList
• ControlChangeList
• PitchBendList
• PedalList
• TextMetaList

These containers support list-like APIs and helpers such as .start(), .end(), .empty(), .copy(), .sort(), and .filter().

from symusic import Score

score = Score("example.mid")
print(score.ticks_per_quarter)
print(len(score.tracks))

first_track = score.tracks[0]
print(first_track.name, first_track.program, "drum" if first_track.is_drum else "melodic")
print(len(first_track.notes), len(first_track.controls))

Events are the fundamental units of time-stamped information in Symusic. They represent occurrences such as note starts, tempo changes, or lyric appearances.

All events share these core characteristics:

• time: The timestamp of the event relative to the start of the score, expressed in the score's current time unit.
• Time-aware types: Events are specialized by time unit (e.g., NoteTick, TempoQuarter, NoteSecond). In Python, factories automatically dispatch to the correct specialization based on the ttype.
• Typed Containers: Events are stored in specialized lists (e.g., NoteList, TempoList, ControlChangeList) that support slicing, iteration, sorting, filtering, copying, and SoA (Structure of Arrays) exports.

Symusic operates in three distinct time domains: tick, quarter, and second. Mixing these accidentally can cause incorrect durations or densities.

Best Practices:

• Choose one time unit for your workflow and stick to it.
• Use Score(..., ttype="second") when calculating rates or densities based on wall-clock time.
• Use explicit conversion methods before performing heavy analysis.

Conversion Methods:

• score.to("second")
• score.to("quarter")