jazz_model 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,14 @@
+== 0.1.0 [2010-10-20] Modernization
+* Upgraded to RSpec 2.0
+* Ditched Controllers/Rails Application
+* Reworked all models to use in-memory ActiveModel instead of ActiveRecord
+* Internal Refactoring
+* Released as a Gem
+
+== 2008-08-24:
+* Upgraded to Rails 2.1
+* Refactored models to use new Rails 2.1 features.
+
+== Old:
+* Implemented REST Interface
+* Added RSpec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+gem "activemodel", "~> 3.0.0"
+gem "activesupport", "~> 3.0.0"

data/README.rdoc

@@ -0,0 +1,186 @@
+= 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

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+
+desc "Generate documentation for the plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "message_block"
+  rdoc.options << "--line-numbers" << "--inline-source"
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Dir["#{File.dirname(__FILE__)}/lib/tasks/*.rake"].sort.each { |ext| load ext }

data/lib/jazz_model.rb

@@ -0,0 +1,34 @@
+module JazzModel
+  require "rubygems"
+  require "active_support"
+  require "active_record"
+  require "acts_as_tree"
+  require "acts_as_list"
+  
+  extend ActiveSupport::Autoload
+  
+  autoload :Base
+  autoload :Chord
+  autoload :ChordCollection
+  autoload :ChordQuality
+  autoload :ChordScale
+  autoload :ChordSymbol
+  autoload :ChordSymbolCollection
+  autoload :ChordTone
+  autoload :Key
+  autoload :KeyContext
+  autoload :Mode
+  autoload :ModeContext
+  autoload :ModeSequence
+  autoload :NoteSequence
+  autoload :NotesCollection
+  autoload :Scale
+  autoload :ScaleTone
+  autoload :Tone
+  autoload :ToneSequence
+  autoload :Voicing
+  autoload :VoicingTone
+  
+  autoload :Definition
+  
+end

data/lib/jazz_model/base.rb

@@ -0,0 +1,15 @@
+module JazzModel
+  class Base < ActiveRecord::Base
+    self.abstract_class = true
+    
+    establish_connection :adapter => "sqlite3", :database => ":memory:"
+    load File.join(File.dirname(__FILE__), "../../db/schema.rb")
+    
+    def self.load_definitions(definition_name = :default)
+      definition = JazzModel::Definition[definition_name]
+      raise ArgumentError, "Definition #{definition_name} not found." unless definition
+      
+      definition.load
+    end
+  end
+end

data/lib/jazz_model/chord.rb

@@ -0,0 +1,141 @@
+module JazzModel
+  # A chord object represents a chord defined as an unordered collection of tones (non-octaval).
+  # Mixes in the +KeyContext+ module to provide optional key context on the chord.
+  # 
+  # == Creating a Chord
+  # 
+  # Chords should be created by indexing the +Chord+ class like an array, like so:
+  # 
+  #   Chord[symbol]
+  # 
+  # An alternative method of resolving a chord is to use the +resolve+ method, 
+  # though this is likely to become deprecated in the future when chord progression
+  # support/representation is added:
+  #
+  #   Chord.resolve(symbol)
+  # 
+  # This resolves a specified chord symbol into a new chord object using 
+  # data regarding chord symbol-to-chord relationships.
+  # +symbol+ can be any standard jazz chord symbol representable as 
+  # plain ASCII (unicode support for other symbols such as full-diminished circle
+  # in the works). Can be prefixed with a key.
+  # 
+  # == Object Relationships
+  # 
+  # A chord object has the following associations, exposed by methods:
+  # 
+  # * +symbols+ - Associated chord symbols.
+  # * +primary_symbol+ - Primary chord symbol.
+  # * +chord_scales+ - Chord-scale relationship objects.  See ChordScale.
+  # * +modes+ - Direct access to associated scale modes through +chord_scales+.
+  # * +tones+ - Sequence of tones associated with the chord.  See +ToneSequence+.
+  # * +voicings+ - Voicings associated with this chord.#
+  # 
+  # == Example Usage
+  # 
+  # === Creating Chords Without Key Context
+  # 
+  #   Chord['maj']
+  #   Chord['min7'
+  #   Chord['maj7#11']
+  #   Chord['7#9']
+  #
+  # === Creating Chords With Key Context
+  # 
+  #   Chord['C7']
+  #   Chord['Bbalt']
+  #   Chord['Gbmaj7']
+  # 
+  # === Getting Chord Notes
+  # Use +notes+ to retrieve a collection of notes, which actually delegates to +tones.notes+:
+  #
+  #   Chord['C7'].notes
+  #   # => ['C', 'E', 'G', 'Bb']
+  #  
+  #   Chord['Cmaj7#11'].notes
+  #   # => ["C", "E", "G", "B", "F#"]
+  # 
+  # === Correctly Interpets Theoretical Keys (not just pitches)
+  # Note the #11 is correctly interpreted as E# and not enharmonic F here:
+  # 
+  #   Chord['Bmaj7#11'].notes
+  #   # => ["B", "D#", "F#", "A#", "E#"]
+  # 
+  # Also correctly interpet tones off of enharmonic base keys:
+  # 
+  #   Chord['Gbmaj7'].notes
+  #   # => ["Gb", "Bb", "Db", "F"]
+  #   Chord['F#maj7'].notes
+  #   # => ["F#", "A#", "C#", "E#"]
+  # 
+  # === See Related Scales
+  #  
+  #   Chord['min7'].modes.names  # .names == .map(&:name)
+  #   # => ['Dorian']
+  #   Chord['min7'].modes[0].scale.name
+  #   # => "Major"
+  # 
+  #   Chord['Amin7'].modes.names
+  #   # => ['A Dorian']
+  # 
+  class Chord < JazzModel::Base
+    include KeyContext
+    
+    acts_as_tree
+    
+    belongs_to :chord_quality
+  
+    has_many :symbols, :class_name => 'ChordSymbol', :extend => ChordSymbolCollection
+    has_one :primary_symbol, :class_name => 'ChordSymbol', :conditions => {:primary => true}
+  
+    has_many :chord_scales
+    has_many :modes, :through => :chord_scales
+    has_many :tones, :class_name => 'ChordTone', :extend => ToneSequence
+    has_many :voicings
+  
+    delegate :notes, :to => :tones
+  
+    def symbols_list
+      self.symbols.map {|s| s.name }.join(', ')
+    end
+  
+    class << self
+    
+      # Resolves a chord symbol into a chord.
+      # Implementation is somewhat flakey due to the potential ambiguities arising 
+      # from specifying key and symbols together.
+      def resolve(symbol)
+        in_key = nil
+      
+        return nil if symbol.nil?
+        symbol = symbol.dup
+      
+        Key.all.each do |k|
+          if symbol.starts_with?(k.name)
+            in_key = k
+            symbol.sub!(k.name, '').strip
+            break
+          end
+        end
+      
+        chord_symbol = ChordSymbol[symbol]
+      
+        # Perhaps the matched key was really part of the name of the chord, try that:
+        if chord_symbol.nil? && !in_key.nil?
+          symbol = in_key.name + symbol
+          chord_symbol = ChordSymbol[symbol]
+        end
+      
+        # If still not found, must be invalid:
+        return nil if chord_symbol.nil?
+      
+        chord = chord_symbol.chord
+        chord.key = in_key unless in_key.nil?
+        chord
+      end
+      alias_method :[], :resolve
+    
+    end
+  
+  end
+end

data/lib/jazz_model/chord_collection.rb

@@ -0,0 +1,68 @@
+module JazzModel
+  # Intended to be used as a dynamic object extension of an Array representing 
+  # a collection of chords for some added convenience.
+  # 
+  # For example, even though the base class is an Array, we can write:
+  # 
+  # * +scale.chords.symbols+ - For an array of symbols.
+  # * +scale.chords.names+ - For an array of full names.
+  # 
+  module ChordCollection
+  
+    # Formats chord collection
+    def to_s(format = :symbols)
+      case format
+      when :symbols then symbols.join(', ')
+      when :names then names.join(', ')
+      end
+    end
+  
+    # Returns array of chord symbols only
+    def symbols
+      self.map {|c| "#{c.key.name if c.key}#{c.primary_symbol.name}" }
+    end
+  
+    # Returns array of chord names only
+    def names
+      self.map {|c| "#{c.key.name if c.key} #{c.name}".strip }
+    end
+  
+  
+    # WARNING: This is basically duplicated from Chord
+    # Try to make this DRY!
+    # 
+    # Resolves a chord symbol into a chord.
+    # Implementation is somewhat flakey due to the potential ambiguities arising 
+    # from specifying key and symbols together.
+    def resolve(symbol)
+      in_key = nil
+    
+      return nil if symbol.nil?
+    
+      Key.all.each do |k|
+        if symbol.starts_with?(k.name)
+          in_key = k
+          symbol.sub!(k.name, '').strip
+          break
+        end
+      end
+    
+      chord_symbol = self.map {|c| c.symbols.to_a}.flatten.detect {|cs| cs.name == symbol}
+    
+      # Perhaps the matched key was really part of the name of the chord, try that:
+      if chord_symbol.nil? && !in_key.nil?
+        symbol = in_key.name + symbol
+        chord_symbol = self.symbols[symbol]
+      end
+    
+      # If still not found, must be invalid:
+      return nil if chord_symbol.nil?
+    
+      chord = chord_symbol.chord
+      chord.key = in_key unless in_key.nil?
+      chord
+    end
+    alias_method :[], :resolve
+  
+  end
+end