DEV Community: Hanné B

Building a Music Theory API (and learning JavaScript along the way)

Hanné B — Wed, 28 Oct 2026 00:34:01 +0000

Building a Music Theory API (and learning JavaScript along the way)

Back when I was a grad student, I’ve always wanted a tool that could quickly spell out complex chords. In advanced music theory courses, verifying a chord spelling meant physically stacking thirds and writing them out on paper — a process that gets tedious fast when you’re working with augmented major sevenths in Ab harmonic minor at 11pm.

So I built one.

The API

The Music Theory Explorer is a REST API built with Python and Flask that encodes core music theory concepts as retrievable endpoints:

Scale spellings across major, natural minor, and harmonic minor
Interval identification and inversion
Triad and seventh chord spellings with inversions
Diatonic chord sets with Roman numerals

The data reflects the modern equal temperament tradition and what’s generally known as the common practice period.

The backend felt natural as I had built apps in Python/Flask before. Python’s readable syntax maps pretty well onto music theory logic; e.g. a scale is just a dictionary lookup, a chord is a list of notes derived from that scale.

The problem

When the API was complete, I realised something: music majors with no programming background can’t explore a REST API. Showing a fellow musician a JSON response and expecting them to find it useful is like handing someone a car engine and asking them to go for a drive.

I needed a frontend.

Learning JavaScript reactively

Here’s the honest part: I didn’t know JavaScript until now. I’d worked with Python and had a plan for the UI, but the actual JS was new territory.

Rather than sitting through tutorials, I wrote the frontend code with Claude and then walked through every change myself — one bug at a time. The approach was simple: make a change, understand why, move on. No change went in without me knowing what it did.

Some things that clicked quickly:

const is just a named box

js
const API = '/api';

A constant is a label for a value that won’t change.

Template literals are Python f-strings

js
const url =${API}/scales/${tonic}/${mode};

The backticks and ${} syntax does exactly what Python’s f-strings do; paste a value into a string. Once I saw that parallel it made sense.

data.field is dictionary lookup

js
const notes = data.scale;

When your API returns JSON, JavaScript reads it as an object. data.scale is the same idea as data["scale"] in Python.

The bug that taught me the most

The most instructive moment was a note conversion bug. My Flask API internally uses German notation (H for B natural, B for Bb -- see my first Blog Post for why!) but converts everything to English before responding. My JavaScript was then running those already-converted notes through a second German→English conversion — turning B into Bb, since Claude had given the initial template without looking at my existing code.

C major was showing as: C D E F G A Bb

The fix was luckily just one word: removing the conversion function call, and displaying the note directly.

What it looks like now

The finished frontend has four sections: Scales, Intervals, Chords, and Diatonic Chords. Each call the relevant API endpoint and display the results in a musician-friendly way. No JSON visible anywhere. Roman numerals, note spellings, interval names all presented cleanly for a non-technical musician.

The API URL is shown at the bottom of each result, though, for technically curious users who want to peek under the hood.

What’s next

Deploying to a platform like Render, so musicians can use it without cloning a repo
A chord progression analyser (/key/{tonic}/{mode}/analyze) that returns Roman numeral analysis
Historical tuning system support in a future version

Why Figured Bass Notation did not Make it into v1 of my Music Theory API

Hanné B — Tue, 27 Oct 2026 00:27:55 +0000

My initial plan when building the Music Theory API v1 was to include figured bass notation as a field in the chord endpoints.

The idea was straightforward: return the standard numeric figures alongside the chord notes so that the response would be useful for anyone working with Baroque-era notation or voice leading analysis.

The initial json implementation looked like this:

{ "root": "C", "quality": "minor", "name": "C minor", "inversion": "first inversion", "bass": "Eb", "notes": ["Eb", "G", "C"], "basso_continuo": "6/3" }

For root position, first inversion, and second inversion triads, the figures map cleanly to inversion number: root position is 5/3, first inversion is 6/3, second inversion is 6/4. For seventh chords the same logic applies: root position is 7/5/3, first inversion is 6/5/3, second inversion is 6/4/3, third inversion is 6/4/2. This works until you try a diminished triad in root position.

A diminished triad has a diminished fifth above the bass, not a perfect fifth. Returning 5/3 for a diminished triad in root position is technically incorrect: the five needs to be altered by accidental. In standard figured bass notation, a diminished fifth is written as b5, giving b5/3for a diminished triad in root position.

The figures need to carry interval quality information, not just interval numbers. That is solvable if I can extract the quality from the interval name and prepend the appropriate accidental symbol, but this is where the real problem appears.

In basso continuo practice, figures are always relative to the key signature. A major third in C major is written as 3: the key signature already implies the major third, so no extra accidental is needed. The same major third in C minor requires a sharp, i.e. #3, because the key signature has an Eb and the performer needs to be told to raise it. The same interval, the same note, different figures depending on context.

This means that correct figured bass notation cannot be derived from the chord spelling alone.The key must be known. Right now the API’s chord endpoints take a root and a quality — they have no key context. Adding a key parameter to the chord endpoints would conflate two separate concerns: what a chord is in isolation versus what function it serves in a key.

The right place for figured bass notation is therefore not the chord endpoint but a future key-aware endpoint; something that takes a tonic, a mode, and a chord, and returns the Roman numeral analysis alongside correct context-dependent figures. That endpoint is planned but not yet built.

For now, the basso_continuo field has been removed from the chord response entirely. For the moment a missing field is preferable to a field that returns correct-looking but context-independent figures that would be wrong in any key with accidentals in the signature.

Why F# Breaks OpenAPI rendering: Note Names, URL Encoding, and the Clash Between Music Notation and pre-existing Web Standards

Hanné B — Sat, 24 Oct 2026 23:52:29 +0000

I'm building a music theory API. I typed F# as root note into the "tonic" interface, which OpenAPI translated into a URL and I got a subsequent 404. Everything broke. Here's what happened and how I created a work-around.

What # means to a URL

The # character is reserved in URLs to signal a fragment identifier. Everything after the # character is interpreted by the browser as an anchor on the page, not part of the path. So something like /scales/F#/major is parsed as /scales/F with fragment major. The server never even sees the # and we get a 404 error response right away when trying to render in OpenAPI.

What the # symbol means to a musician

The sharp symbol in music applies to a note name to raise it by a semitone. In the context of naming scales, as for the API, the root note is the name given to the scale and so F# must be the root note for a scale beginning on the note F-sharp. This becomes a matching issue in pre-programmed interfaces like OpenAPI interfaces, which weren't designed for music first formats initially but the two now have to "talk to" each other.

The Solutions People have Reached for

URL encoding (F%23), query parameters, string substitution (Fs) are all potential solutions to the issue. Each one works technically, but breaks something musically or semantically, because it's clumsy to annotate to non-technical users, and string substitution like Fs doesn't make sense musically.

The German Naming Solution

German music notation uses the suffix "is" for sharps and "es" for flats i.e. Fis, Cis, Es, but notably B for Bb. Despite the workaround, no special characters are needed. Clean URLs. (Also, it's not a hack; it's a centuries-old naming convention used in some of the greatest musical traditions.)