Symbolic
A toolkit for computational symbolic music data and its notations. Work with notes, intervals, pitch classes, sets, progressions, and rhythms as structures you can inspect, transform, and sequence.
Keep a point or set independent of root and register, then add a key, voicing, and rhythm to realize MIDI notes. Symbolic focuses on twelve-tone equal temperament and MIDI-style playback; recorded audio, synthesis, and signal processing are outside its scope.
Libraries for music tools
The JavaScript and TypeScript package powers this catalog. A Python library is planned. We aim to release both as open source so others can build analysis, visualization, composition, and instrument tools.
Try it in the Code Sequencer
Playable examples become MIDI notes scheduled through a connected instrument. The sequencer's Symbolic Cycle language writes these structures as code: sets, Roman numerals, keys, drums and seeded generators, in songs that can import each other's layers. It is also a testbed for generative scripting; analytical concepts may have no direct note realization.
Research directions
Symbolic is an active research project. These are possible uses, not features promised by the current library.
Analyze and visualize
Inspect patterns, compare notations, and make musical relationships visible.
Build generative systems
Use structured data in analysis and generative models, and explore mathematical approaches to composition.
Design expressive tools
Give instrument designers theory-aware building blocks that help creators express ideas. Musicians need not become coders to benefit.
Explore 60 concepts
Harmony
Single Elements
One concrete MIDI pitch with an octave. Its pitch class keeps the note name while discarding that register.
A relative pitch position measured in semitone steps. Anchor it to a note to obtain an absolute pitch; keep it unanchored to compare transposed shapes.
One of the twelve pitches from C to B, independent of octave. Transposition rotates its position around the chromatic circle.
A signed semitone distance between two pitches. Moving both endpoints together preserves the interval.
Sets
A group of concrete MIDI pitches with octaves. It specifies one voicing and can be reduced to pitch classes or a rootless point shape.
A rootless arrangement of semitone offsets from the lowest note. Its shape stays the same when a MIDI voicing is transposed.
A selection of the twelve pitch classes, independent of octave and order. It says which pitches are present without choosing a chord root or voicing.
The span between a lowest and highest MIDI note. It describes a register boundary, not every note inside it.
Analytical measures and properties of a pitch class set
Collections & Patterns
An unordered collection of unique note sets
A collection of interval patterns (point sets) that are transposition-invariant
An unordered collection of unique pitch class sets
An ordered sequence of note sets (chords) that may contain duplicates
An ordered sequence of pitch class sets that may contain duplicates
An ordered sequence of point-sets that may contain duplicates
An unordered collection of chord progressions — e.g. a songbook of changes or a library of progressions. A meta-group: a group of groups, whose `groupOf` is note-set-sequence (one level up from a note-set-collection).
An unordered, octave-free collection of pc-set progressions. The pitch-class abstraction of a note-set-sequence collection; its `groupOf` is pc-set-sequence.
An unordered, transposition-invariant collection of point-set progressions — a library of progression shapes independent of key. Its `groupOf` is point-set-sequence.
Song Forms
A chord progression arranged by labeled section (intro, verse, chorus, bridge…) — the harmonic skeleton of a lead sheet or guitar-chord chart. An ordered, named sequence whose sections are chord progressions (its `groupOf` is note-set-sequence). Forget the labels/order and it becomes a collection of progressions; forget pitch and it becomes a point-song-form (a key-independent structural shape for comparing songs).
A song form whose section progressions are octave-free (pitch-class) — the octaveless abstraction of a song-form. Keeps section labels, order, and harmony but drops register. Its `groupOf` is pc-set-sequence.
A song form reduced to non-pitch-specific shapes — section labels and order are kept, but each chord is a point-set (offsets, no key). This is the transposition-invariant structural fingerprint of a song: two songs in different keys with the same form land on the same point-song-form, so it is the natural representation for song-to-song similarity. Its `groupOf` is point-set-sequence.
Polyphony & Scores
A polyphonic texture — several voices (temporalized lines / tracks) sounding at once over a shared timeline. The simultaneous counterpart of a note-set: where a note-set stacks single notes into a chord, a score stacks whole lines. Its `groupOf` is note-sequence. Collapse the voices at each instant and you get a chord progression (note-set-sequence) — the resulting chord qualities of the simultaneous notes; conversely, a chord progression can be voice-led into a score. Strip pitch and it becomes a point-score (key-independent counterpoint).
An octave-free polyphonic texture — simultaneous pc-sequences (lines of pitch classes). The octaveless abstraction of a score; keeps voice independence and harmony but drops register. Its `groupOf` is pc-sequence.
A key-independent polyphonic shape — simultaneous point-sequences (offset lines). The transposition-invariant fingerprint of a counterpoint: two passages in different keys with the same voice motion land on the same point-score, so it is the natural representation for contrapuntal similarity. Its `groupOf` is point-sequence.
Tonal Context
A tonic pitch class and mode that give scale degrees and Roman chord functions their context.
A named pattern of pitch classes organized around a tonic, such as C major or D dorian.
A named harmony with a root and quality, such as Cmaj7. Its symbol can be realized in different MIDI voicings.
A progression described by Roman numerals relative to a key. The key turns each function into a concrete chord; changing keys reinterprets the same progression.
A time-ordered map of keys and modulations. It keeps track of where a piece changes tonal center instead of assigning one key to the whole piece.
Spaces
A 128-bin distribution over MIDI notes. Counts or weights retain register and repeated occurrences.
A twelve-bin distribution of pitch-class weights. It combines matching pitches across octaves while retaining their counts.
A distribution over relative semitone positions from an anchor. It retains weighted shape while discarding absolute MIDI register.
Melody
Lines & Sequences
An ordered line of notes and optional rests. Adding durations makes its rhythmic placement explicit.
An ordered line of pitch classes without fixed octaves. Choose registers to turn it into MIDI notes.
An ordered, rootless pitch contour. An anchor note turns its relative positions into a concrete line.
Form & Motif
A short recurring melodic unit — an interval / contour cell that repeats across a line. Modeled transposition-invariantly as an interval pattern (successive semitone steps), so the same shape at a different pitch level is the same motif. The structural seed a theme is spun from: it abstracts a melody (note-sequence) down to its most salient repeating fragment. Discovered by scanning the line's intervals for sub-sequences that recur.
A melodic segment — a unit of melodic 'breath'. The span between two breath points (a rest or a sustained note), one level below the whole line and above the individual note. Found by segmenting a melody (note-sequence) at long notes / rests via a simple gap heuristic; the members of a phrase are its notes.
A harmonic closing formula — the two-chord gesture that ends a phrase or section: authentic (V→I), plagal (IV→I), half (…→V), or deceptive (V→vi). The functional reading of a progression's final motion: it labels the closing two chords of a note-set-sequence by their roman-numeral degrees within a key.
Interfaces
Instrument Layouts
A 2D interval grid system design where vertical and horizontal movements represent specific semitone intervals. Used as the foundation for grid-based music interfaces.
Mapping of computer keyboard keys to MIDI notes for playing music through typing
Hexagonal note layout.
Instrument Positions
A specific fingering position for a chord or note set on a stringed instrument
A chord or scale position on a 2D interval grid system, where vertical and horizontal movements represent specific semitone intervals
A collection of chord/scale positions on a 2D interval grid, presented as a bank of positions without temporal ordering
Data & Analysis
Data Formats
A single instrumental or vocal line with timing information
A complete musical file with multiple tracks and possibly metadata
A musical work, identified through various catalog systems
Symbolic representation of a song, arranged for guitar
Minimal symbolic representation of a song, at least, it's chord structure. Mainly used in Jazz.
Symbolic representations
A 2-D pitch×time grid — the canonical symbolic ML tensor. Each cell marks whether a pitch sounds at a time step; the spatial layout of a score / note-sequence laid out on a grid. A representation, not a new structural object: it renders existing symbolic music for models and editors.
A symbolic tokenization of music for transformer models — REMI / MIDI-like / compound vocabularies that flatten notes, timing and structure into a discrete token stream. An encoding of a score / MIDI track, not a new musical object.
Rhythm
Rhythm Patterns
Meter & Tempo
The meter: how beats group into a bar, written as a ratio (4/4, 6/8, 7/8). The top number counts notated units per bar, the bottom names the unit (4 = quarter, 8 = eighth). Simple meters feel one beat per numerator unit; compound meters (6/8, 9/8, 12/8) group their eighths in threes into dotted-quarter beats. Off-axis: a meter is not a structural object but the interpretive frame that tells a rhythm where the bar lines and downbeats fall.
How fast a beat is, in beats-per-minute. Tempo is what turns tempo-free musical durations (beats) into wall-clock time: a beat lasts 60000 / bpm milliseconds. Off-axis: like a meter, a tempo is not a structural object but the interpretive context that maps the beats of a rhythm / metric-grid onto absolute milliseconds (it reuses the beats↔ms convention of duration-utils).
The beat/subdivision scaffold a rhythm snaps onto: the ordered points of one bar, each marked downbeat, beat, or subdivision. A grid is built from a meter + a tempo — the meter sets how many beats and where the downbeat falls, the tempo sets how fast they go by. A rhythm is placed on a metric grid (quantized) when given a meter + tempo; groove then nudges the grid points off their exact positions.
Small timing offsets that give a repeated metric grid its feel, such as swing or a pushed beat. A groove can be applied to a symbolic rhythm without changing its note order.
Further concepts
Adapted from Codex Music Mono’s original concept JSON and typed catalog.