PlayByKey Theory Engine

PlayByKey Theory Engine is a TypeScript library that computes music theory in code. Published on npm as @playbykey/theory, it gives developers a typed API for scales, modes, keys, and intervals, so an application can work out these relationships programmatically instead of hard-coding note tables and hoping they are right. It is the theory core that powers PlayByKey, a free interactive music education platform built by DigitalBrew LLC.

The problem it addresses shows up in any project that touches music. Working out which notes belong to a given scale, resolving a mode against its parent key, finding the relative minor, ordering keys around the Circle of Fifths, or measuring the interval between two notes is fiddly, easy to get subtly wrong, and tedious to reimplement in every codebase. The engine packages that logic once, tested and typed, so the rest of an application can simply ask for an answer and trust it instead of maintaining its own note math. It also keeps the same rules in one place, so a fix to how a mode resolves benefits every screen or feature that leans on the engine rather than being patched in five separate spots.

On capability it covers a lot of ground for keys and modes. It resolves the seven diatonic modes, Ionian through Locrian, identifies the parent scale behind a mode, navigates between relative major and minor, orders keys around the Circle of Fifths, and calculates modal roots. That covers most of the relationships a learning tool or a composition helper needs to reason about when it moves between keys or explains why a particular mode sounds the way it does, which is exactly the kind of logic that is easy to fumble by hand. It can also chain those operations, so a tool can go from a key to its modes to the notes of a chosen mode without ever leaving the library.

Scales and intervals are handled with the same care. For scales it supports standard shapes such as blues, harmonic minor, and pentatonic, along with degree calculation, scale membership testing, and derived scale computation. Intervals come with a catalog of semitone lookups and endpoint resolution between note pairs, and the library is careful to keep a clear distinction between scale motion measured in half and whole steps and root-relative intervals, which are two things beginners often conflate. There are also smaller utilities for semitone distance and note display mapping. That mix of coverage and precision is what separates a real theory engine from a lookup table, since it can answer questions about relationships the author never enumerated ahead of time.

A handful of design choices make it easy to drop in. It ships with zero external dependencies and is written in strict TypeScript with fully typed exports, so types like Note and ModeName can be imported directly into your own code. Note parsing is case-insensitive, so it does not matter how a user capitalizes their input, and it uses a sharps-only internal notation, writing C sharp rather than D flat, so the internal model stays consistent and predictable no matter how a note was entered. For a library other developers build on, that kind of predictability matters more than clever shortcuts.

The part that stands out in 2026 is the companion MCP server, published separately as @playbykey/theory-mcp. It exposes the same theory functions as native tools to an AI assistant like Claude, so a model can compute scales, chords, and intervals directly instead of guessing at them or asking the user to paste in code. For anyone building music tooling around an assistant, that turns a plain library into something the AI can call on its own, which is a real upgrade over hoping a language model gets the theory right from memory. It also lets a chat-based practice tool hand the exact computation to the engine and keep the model focused on explanation, which tends to produce answers a music teacher would actually sign off on.

Access is straightforward. Both packages install from npm, and the docs also show pnpm, yarn, and bun as alternatives, so the engine slots into most JavaScript and TypeScript toolchains without fuss. The docs site is the main reference for the API surface, and the intended users are music education tools, composition software, interactive learning platforms, and AI assistants that need real theory computation rather than a rough approximation. Because it already powers a shipping education product, the logic has been exercised against actual lessons rather than living only in tests.