Jazz Model - A data model for Jazz theory and other cool stuff.
Latest commit 58cd08d Dec 29, 2012 @rubiety Specifying more specific gem dependencies, this doesn't seem to work …
…with active_record 3.2 quite yet.


Jazz Model

Jazz Model is full ActiveRecord model of concepts in Jazz theory, establishing relationships between chords and scales, and much more. Aside from representing jazz theory relationships in the database, jazz model can do key conversions and other operations on these jazz “objects”. By default it uses an in-memory sqlite3 database, but it could be persisted elsewhere.


NOTE: This project is no longer under active development. All work is now devoted to Jazzity, the public interface inspired by this project: www.jazzity.com. Sign up there if you're interested in the potential for mathematical analysis of Jazz theory.

Architecture Overview

The core of Jazz Toolbox is a full Ruby object model representing concepts of Jazz theory, distilled to their most basic concepts and architected in a very abstract manner. The system is data-centric and all “rules” (for example, the tones in a C7 chord) in theory are self-contained in the database.

All chord/scale/mode/etc. definitions are stored as a mathematical system (sequences of numbers) which are then used to perform calculations. For example, putting some chord in a different key is a matter of adding a semitone delta and doing modulo 12.

While there are currently many chord calculators in existence, to my knowledge this project is the first one that attempts to fully represent the entirety of Jazz theory as a mathematical/computational system exposed through an elegant object model.

Note: the current database consists entirely of my own personal knowledge of Jazz theory. I haven't yet scoured through the Jazz theory literature to formalize and expand the current database of chords, scales, and chord-scales. There's still a lot of work to do and I have lots of ideas for how to expand this.

Core Features

  • Scale & Mode Enumeration

  • Handles Variety of Notations

  • ChordTone Enumeration

  • Traversing ScaleChord Relationships with Strength Metric

  • Full Understanding of Theoretic Tones (vs. only Pitches)


Simply include the gem in your Gemfile:

gem "jazz_model"

From here you can begin using the classes under JazzModel directly, but it won't be much use until you load the definitions:


Examples using Default Definitions

Everything is under the JazzModel namespace, so first do this if you want to use these classes directly:

include JazzModel

Getting a Chord object:

Chord['Bbmaj7']  # <- With Key Context

Getting a Scale object:

Scale['Melodic Minor']

Getting a particular mode of a scale:

Scale['Major'].modes['Dorian']  # By Mode Name
Scale['Major'].modes[2]  # By Mode Index

# Or directly index the scale object (same as above):

Enumerate notes of a Chord:

Chord['maj'].notes   # Defaults to C without specified key context
# => ['C', 'E', 'G']

# => ['Eb', 'G', 'Bb', 'D']

# Or specify key context with chained methods like this...

# => ['B', 'D#', 'F#', 'A#', 'E#']
# Note E# - Correct theoretic value for this chord, not F

# => ['F', 'A', 'Eb', 'Gb', 'G#', 'C#']

# => ['Gb', 'Bb', 'Db', 'F']

# But...

# => ['F#', 'A#', 'C#', 'E#']

Enumerate notes of a Scale:

Scale['Major'].notes  # Defaults to C without specified key context
# => ['C', 'D', 'E', 'F', 'G', 'A', 'B']

Scale['Eb Major'].notes
# => ['Eb', 'F', 'G', 'Ab', 'Bb', 'C', 'D']

# Or specify key context with chained methods like this:

Scale['Whole Tone'].notes
# => ['C', 'D', 'E', 'F#', 'G#', 'Bb']

# => ['C', 'D', 'E', 'F', 'G', 'A', 'Bb', 'B']

Enumerate notes from a Scale Mode:

# => ['F', 'G', 'Ab', 'Bb', 'C', 'D', 'Eb']

Scale['Melodic Minor']['Lydian Dominant'].notes
# => ['F', 'G', 'A', 'B', 'C', 'D', 'Eb']

Enumerate scale modes associated with a chord:

Chord['min7'].modes.names  # .names == .map(&:name)
# => ['Dorian']
# => "Major"

# => ['A Dorian']

Enumerate chords associated with a scale mode:

# => ['min7', 'min6']

# => ['maj7#11']

Ruby Example Problem:

Find all chords associated with the Major (Ionian) scale and print 
each on a new line with the chord tones.

Scale['Major'].chords.map {|c| c.name + ': ' + c.notes.join(', ')} * "\n"
# => Major 7: C, E, G, B
     Major 6: C, E, G, A
     Dominant 6/9: C, E, G, Bb, D, A

These examples should show that with the power of Ruby and the elegant nature of this API, extracting Jazz data from the system is a breeze (even fun!).

Definitions Available

The default definition is just named “default” and is loaded when you run JazzModel::Base.load_definitions without argument, though you can give a custom argument to this to load a different definition:


Currently there are two definitions available:

  • Keys - Creates the basic 12 keys. This definition should always be loaded so long as you are dealing with Western harmony.

  • Default - The default set of data for jazz models, including many scales and chords. Any other definitions will probably want to build upon this instead of start from scratch.

Creating Definitions

The gem has a distinction between classes such as Chord and the actual definitions such as “C Major Chord”. Definitions are simply packaged set of instructions for initializing the objects with data (which get put in the database). Since by default jazz model uses an in-memory sqlite3 database, definitions need to be loaded when your application loads.

To create a definition, simply do this:

JazzModel::Definition.define :my_definition => [:keys] do


Within the block you'll want to create whatever data is necessary to comprise your definitions. For examples of definitions, see lib/jazz_model/definitions in the project. The argument to define acts like rake tasks - use the hash value to define which dependencies your definition has. In the above case defining “my_definition” will first ensure the “keys” definition is already defined.

Anticipated Future Features

  • Chord Progression Analysis

  • MIDI Integration

  • User Comments & Contributions (such as Chord-Scale recommendations)

  • Melodic Components & Licks

  • Voicings Associated with Chords