jazz_model

= 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.

== 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)

== Installation

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:

JazzModel::Base.load_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['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!).

== 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:

JazzModel::Base.load_definitions(:my_custom_set)

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

end

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