Jazz Toolbox

Jazz Toolbox is an online Jazz utility driven by a full object-relational and REST model of concepts in Jazz theory, establishing relationships between chords and scales, and much more. The web interface is a fully Ajaxified Web 2.0 interface towards exploring these relationships and answering questions about the jazz science. The REST interface exposes the underlying data model and relationships to other developers wishing to use Jazz Toolbox as a source for their own web applications.

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 existance, to my knowledge this project is the first one that attempts to fully represent the entirety of Jazz theory as a mathmetical/computational system exposed through an elegant object model.

Current State

Currently Jazz Toolbox is only a Ruby object model but will eventually be coupled with a nice front-end at JazzToolbox.com. The object model is built using ActiveRecord (ORM for Rails) and makes extensive use of powerful features in ActiveRecord such as Module mixins on AssociationProxy. Dispite being backed by a database, almost the entire database is cached into memory for fast calculation and performance, as the data representation and calculations are somewhat more complex than what can be afforded using only SQL. A Data Mapper ORM implementation may be in the works, if I can figure out a substitute for ActiveRecord Association Extensions.

Also, 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.

Core Features

Very Clean API
Scale & Mode Enumeration
Handles Variety of Notations
ChordTone Enumeration
Traversing ScaleChord Relationships with Strength Metric
Full Understanding of Theoretic Tones (vs. only Pitches)
Voicings Associated with Chords

Anticipated Future Features

Chord Progression Analysis
MIDI Integration
User Comments & Contributions (such as Chord-Scale recommendations)
Melodic Components & Licks

Ruby API Examples

Getting a Chord object:

 Chord['maj7']
 Chord['Bbmaj7']  # <- With Key Context
 Chord['Abmaj7#11']
 ...

Getting a Scale object:

 Scale['Major']
 Scale['Melodic Minor']
 Scale['Diminished']
 ...

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):
 Scale['Major']['Dorian']
 Scale['Major'][2]

Enumerate notes of a Chord:

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

 Chord['Ebmaj7'].notes
 # => ['Eb', 'G', 'Bb', 'D']

 # Or specify key context with chained methods like this...
 Chord['maj7'].in_key_of('Eb').notes

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

 Chord['Falt'].notes
 Chord['F7b9#9'].notes
 # => ['F', 'A', 'Eb', 'Gb', 'G#', 'C#']

 Chord['Gbmaj7'].notes
 # => ['Gb', 'Bb', 'Db', 'F']

 # But...

 Chord['F#maj7'].notes
 # => ['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['Major'].in_key_of('Eb').notes

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

 Scale['Bebop'].notes
 # => ['C', 'D', 'E', 'F', 'G', 'A', 'Bb', 'B']

Enumerate notes from a Scale Mode:

 Scale['Major'].in_key_of('Eb').modes['Dorian'].notes
 # => ['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']
 Chord['min7'].modes[0].scale.name
 # => "Major"

 Chord['Amin7'].modes.names
 # => ['A Dorian']

Enumerate chords associated with a scale mode:

 Scale['Major']['Dorian'].chords.symbols
 # => ['min7', 'min6']

 Scale['Major'][4].chords.symbols
       # => ['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!).

REST API

The REST API provides a simple XML web service interface to the underlying Jazz object model. Most of the examples are very straightforward since the URLs are simple resources. XML and JSON outputs are supported. For Rails developers, the best way to learn about the REST API is to examine the routes file, which is here:

Routes File

  map.resources :chord_qualities do |chord_qualities|
                chord_qualities.resources :chords do |chords|
                        chords.resources :notes
                end
        end

  map.resources :scales do |scales|
                scales.resources :modes do |modes|
                        modes.resources :chords
                end

                scales.resources :chords
                scales.resources :tones
                scales.resources :notes
        end

  map.resources :chords do |chords|
                chords.resources :symbols
                chords.resources :voicings
                chords.resources :modes
                chords.resources :tones
                chords.resources :notes
        end

        map.resources :notes_collection do |notes_collection|
                notes_collection.resources :chords
        end

REST API Examples

List all chords:

 GET /chords.xml
 # => <chords>
        <chord name="Minor 7">
          <symbols>
            <symbol name="min7" />
            <symbol name="m7" />
          <symbols>
        </chord>
        ...
      </chords>

Show Chord (Without Key Context):
```
 GET /chords/min7.xml
```
Show Chord (With Key Context):
```
 GET /chords/Bbmin7.xml
```

Enumerate notes in a given chord:

 GET /chords/Cmin7/notes.xml
 # => <notes>
        <note name="C" />
        <note name="D" />
        <note name="Eb" />
        ...
      </notes>

List all scales:

 GET /scales.xml
 # => <scales>
        <scale name="Major">
          <modes>
            <mode name="Ionian" mode="1" />
            <mode name="Dorian" mode="2" />
            ...
          </modes>
        </scale>
      </scales>

Show Scale:
```
 GET /scales/major.xml
```
Show Mode:
```
 GET /scales/major/modes/dorian.xml
```

Enumerate notes in a given scale:

 GET /scales/major/modes/ionian/notes.xml
 # OR:
 GET /scales/major/notes.xml  # Defaults to 1st Mode

 # => <notes>
        <note name="C" />
        <note name="D" />
        <note name="E" />
        ...
      </notes>