The Harmonic Algorithm

"My music of today is so much based on the new musical technology. We use the technology as a material for our musical art" — Igor Stravinsky, 1957

Header

Welcome to The Harmonic Algorithm :)

this is an expression of my musical mind — it feels kind of like an 'LLM' (but there's no AI here, just old school counting and music theory) for navigating through and interacting with musical harmonic state in real time, while experiencing it.

The Harmonic Algorithm, written in Haskell, using Neo4j as a backend and integrated highly with TidalCycles, generates musical domain specific data inside user defined constraints then filters it down and probabilistically ranks it using a tailored Markov Chain model trained on ingested musical data from the Yale Classical Archives Corpus. This presents a unique tool in the hands of the composer or performer which can be used as a writing aid, analysis device, for instrumental study or even in live performance.

This open-source project is based on a long term research agenda that I've pursued for many years, originating from an interest as an electric bass player in performance and composition, utilising the overtones of the instrument.

The Harmonic Algorithm takes the underpinning theoretical ideas from this research and realises them as a Haskell library with deep TidalCycles integration for live coding. Under the hood, harmonic transitions from over 80 composers are stored in a Neo4j graph database. The system learns how harmony moves — not just what chords exist, but how they lead into one another — and uses this knowledge to generate progressions that feel musically coherent while remaining endlessly surprising.

The core idea draws on Geraint Wiggins' Creative Systems Framework: define the rules of what's harmonically possible, evaluate the quality of each option using voice leading and dissonance scoring, then traverse the space probabilistically — balancing between the familiar and the unexpected.

[video: 60-second overview — generating a progression from a single chord, hearing it come to life through TidalCycles and SuperCollider, the harmony unfolding in real time as patterns evolve and layer]

Research

The original 2016 research documents on which The Harmonic Algorithm draws influence can be accessed at the following links:

Core document: original core document (2016)

Reflective document: original reflective document (2016)

The accompanying document for this project which discusses The Harmonic Algorithm as a creative system can be accessed here: creative system document (2018)

What It Sounds Like

The same starting chord can lead to radically different musical outcomes. A single parameter — entropy — controls the balance between familiar harmonic motion and surprising, exploratory leaps:

[audio: a progression generated with low entropy (0.2) — smooth, conventional voice leading, the kind of movement Bach would recognise]

[audio: the same starting chord with high entropy (0.8) — unexpected turns, distant modulations, the algorithm venturing into unfamiliar harmonic territory]

The system also lets you blend the harmonic sensibilities of different composers. These aren't presets — they're weighted combinations of learned transition probabilities:

[audio: a progression weighted "bach" — strong functional harmony, clear cadential motion]

[audio: the same starting point weighted "debussy" — more colourful, less predictable, modal inflections creeping in]

[audio: a weighted blend "bach:30 debussy:70" — functional foundations with impressionistic colour, a stylistic fusion that neither composer would have written alone]

[video: a live coding session — building a piece from scratch in TidalCycles, generating progressions on the fly, layering rhythm and melody over algorithmically generated harmony, the music evolving in real time]

What It Looks Like

Let's start simple. Here's what it looks like to generate your first progression — just a starting chord, a length, and an entropy value:

[gif: launching stack ghci, creating a harmonic context, generating an 8-chord progression from C major — watching the output appear, each chord following naturally from the last]

Now let's apply some constraints. The Harmonic Algorithm lets you filter by key signature, overtone series, and root motion — narrowing the harmonic possibilities to match your musical context:

[gif: applying a key filter and an overtone filter based on bass guitar tuning (E A D G), watching the available harmonic choices narrow to structures that ring naturally on the instrument]

Things get interesting when you bring this into TidalCycles. The library integrates directly — generated progressions become patterns you can manipulate, voice, and perform live:

[gif: TidalCycles in action — using arrange and voiceBy to transform a generated progression into layered patterns, bass notes separated from upper voicings, everything cycling and evolving]

You don't always need the algorithm to generate for you. Sometimes you want to build progressions by hand — the changes to a standard, a specific harmonic idea — and use the library's voicing and arrangement tools to bring them to life:

[gif: constructing the chord changes to a jazz standard explicitly using note names, then arranging and voicing them through TidalCycles, hearing the piece take shape]

And here's the composer blending in action — switching between learned styles and hearing how the same harmonic starting point leads to completely different musical journeys:

[gif: generating progressions with "bach", then "debussy", then a weighted blend — the terminal output side by side with the sound, the character of each composer's harmonic language audible in the generated movement]

Installation

Dependencies

Haskell Stack
Docker (for the Neo4j graph database)
TidalCycles (optional — for live coding integration)

Once dependencies have been installed, the following steps can be used to build and run:

Setup

# Clone the repository
git clone https://github.com/OscarSouth/theHarmonicAlgorithm
cd theHarmonicAlgorithm

# Build the library
stack build

# Start the Neo4j database
docker compose up -d neo4j

# Populate the database with the YCACL corpus
stack run

# Verify everything works
stack test

You can now start exploring with stack ghci or integrate with TidalCycles using the boot file in live/BootTidal.hs.

Going Deeper

Once you're up and running, there's plenty to explore:

Interactive User Guide — a hands-on tutorial that walks through everything from your first chord to live performance, with examples you can run directly in TidalCycles.

Worked Examples — complete pieces you can play with immediately, including a jazz standard arrangement and a traditional tune with form transformation.

Architecture Guide — the technical deep dive into how the system works: the four-layer architecture, the R→E→T pipeline, zero-form cadence storage, and the graph database model.

Contributor Guidelines — for anyone who'd like to contribute: the vertical slice workflow, mandatory verification steps, and layer boundary rules.

Acknowledgments

This project wouldn't exist without the work of:

Geraint A. Wiggins — the Creative Systems Framework that underpins the algorithm's architecture
Alex McLean — TidalCycles, which gave this project its voice
Paul Hindemith — interval dissonance theory from The Craft of Musical Composition (1937), which informs the evaluation scoring
UCI Machine Learning Repository — the Yale Classical Archives Corpus that trains the model

Let me know if you have any feature suggestions or comments in general and feel free to get in touch through this repository's Issues section.

Alternatively, use the contact form for my main performance project UDAGAN: https://UDAGANuniverse.com/contact

Oscar

MIT License — see LICENSE for details.

TheHarmonicAlgorithm

Install / Use

README