jazz_model 0.1.0

data/lib/jazz_model/definitions/keys.rb

@@ -0,0 +1,48 @@
+JazzModel::Definition.define :keys do
+  JazzModel::Key.create!(:name => 'C', :long_name => 'C', :index => 0, :letter_index => 0, :cycle_index => 0)
+  JazzModel::Key.create!(:name => 'B#', :long_name => 'B Sharp', :index => 0, :letter_index => 6, :cycle_index => 0, :primary => false)
+  JazzModel::Key.create!(:name => 'Dbb', :long_name => 'D Double-Flat', :index => 0, :letter_index => 1, :cycle_index => 0, :primary => false)
+
+  JazzModel::Key.create!(:name => 'F', :long_name => 'F', :index => 5, :letter_index => 3, :cycle_index => 1)
+  JazzModel::Key.create!(:name => 'E#', :long_name => 'E Sharp', :index => 5, :letter_index => 2, :cycle_index => 1, :primary => false)
+  JazzModel::Key.create!(:name => 'Gbb', :long_name => 'G Double-Flat', :index => 5, :letter_index => 4, :cycle_index => 1, :primary => false)
+
+  JazzModel::Key.create!(:name => 'Bb', :long_name => 'B Flat', :index => 10, :letter_index => 6, :cycle_index => 2)
+  JazzModel::Key.create!(:name => 'A#', :long_name => 'A Sharp', :index => 10, :letter_index => 5, :cycle_index => 2, :primary => false)
+  JazzModel::Key.create!(:name => 'Cbb', :long_name => 'C Double-Flat', :index => 10, :letter_index => 0, :cycle_index => 2, :primary => false)
+
+  JazzModel::Key.create!(:name => 'Eb', :long_name => 'E Flat', :index => 3, :letter_index => 2, :cycle_index => 3)
+  JazzModel::Key.create!(:name => 'D#', :long_name => 'D Sharp', :index => 3, :letter_index => 1, :cycle_index => 3, :primary => false)
+  JazzModel::Key.create!(:name => 'Fbb', :long_name => 'F Double Flat', :index => 3, :letter_index => 3, :cycle_index => 3, :primary => false)
+
+  JazzModel::Key.create!(:name => 'Ab', :long_name => 'A Flat', :index => 8, :letter_index => 5, :cycle_index => 4)
+  JazzModel::Key.create!(:name => 'G#', :long_name => 'G Sharp', :index => 8, :letter_index => 4, :cycle_index => 4, :primary => false)
+
+  JazzModel::Key.create!(:name => 'Db', :long_name => 'D Flat', :index => 1, :letter_index => 1, :cycle_index => 5)
+  JazzModel::Key.create!(:name => 'C#', :long_name => 'C Sharp', :index => 1, :letter_index => 0, :cycle_index => 5, :primary => false)
+  JazzModel::Key.create!(:name => 'B##', :long_name => 'B Double-Sharp', :index => 1, :letter_index => 6, :cycle_index => 5, :primary => false)
+
+  JazzModel::Key.create!(:name => 'Gb', :long_name => 'G Flat', :index => 6, :letter_index => 4, :cycle_index => 6)
+  JazzModel::Key.create!(:name => 'F#', :long_name => 'F Sharp', :index => 6, :letter_index => 3, :cycle_index => 6, :primary => false)
+  JazzModel::Key.create!(:name => 'E##', :long_name => 'E Double-Sharp', :index => 6, :letter_index => 2, :cycle_index => 6, :primary => false)   
+
+  JazzModel::Key.create!(:name => 'B', :long_name => 'B', :index => 11, :letter_index => 6, :cycle_index => 7)
+  JazzModel::Key.create!(:name => 'Cb', :long_name => 'C Flat', :index => 11, :letter_index => 0, :cycle_index => 7, :primary => false)
+  JazzModel::Key.create!(:name => 'A##', :long_name => 'A Double-Sharp', :index => 11, :letter_index => 5, :cycle_index => 7, :primary => false)
+
+  JazzModel::Key.create!(:name => 'E', :long_name => 'E', :index => 4, :letter_index => 2, :cycle_index => 8)
+  JazzModel::Key.create!(:name => 'Fb', :long_name => 'F Flat', :index => 4, :letter_index => 3, :cycle_index => 8, :primary => false)
+  JazzModel::Key.create!(:name => 'D##', :long_name => 'D Double-Sharp', :index => 4, :letter_index => 1, :cycle_index => 8, :primary => false)
+
+  JazzModel::Key.create!(:name => 'A', :long_name => 'A', :index => 9, :letter_index => 5, :cycle_index => 9)
+  JazzModel::Key.create!(:name => 'Bbb', :long_name => 'B Double-Flat', :index => 9, :letter_index => 6, :cycle_index => 9, :primary => false)
+  JazzModel::Key.create!(:name => 'G##', :long_name => 'G Double-Sharp', :index => 9, :letter_index => 4, :cycle_index => 9, :primary => false)   
+
+  JazzModel::Key.create!(:name => 'D', :long_name => 'D', :index => 2, :letter_index => 1, :cycle_index => 10)
+  JazzModel::Key.create!(:name => 'C##', :long_name => 'C Double-Sharp', :index => 2, :letter_index => 0, :cycle_index => 10, :primary => false)
+  JazzModel::Key.create!(:name => 'Ebb', :long_name => 'E Double-Flat', :index => 2, :letter_index => 2, :cycle_index => 10, :primary => false)
+
+  JazzModel::Key.create!(:name => 'G', :long_name => 'G', :index => 7, :letter_index => 4, :cycle_index => 11)
+  JazzModel::Key.create!(:name => 'F##', :long_name => 'F Double-Sharp', :index => 7, :letter_index => 3, :cycle_index => 11, :primary => false)
+  JazzModel::Key.create!(:name => 'Abb', :long_name => 'A Double-Flat', :index => 7, :letter_index => 5, :cycle_index => 11, :primary => false)
+end

data/lib/jazz_model/key.rb

@@ -0,0 +1,49 @@
+module JazzModel
+  # A key represents a specific theoretic tone mapped to a pitch and a letter 
+  # index.  Keys are defined for all letters A-G and all sharp/flat values 
+  # within two semitons (e.g. Dbb, D Double-Flat enharmonic with C).
+  #
+  # Each key is associated an index between 0-11 to represent the actual pitch 
+  # within the chromatic scale.  
+  # Each key is also assigned a "letter index" which represents a relative letter 
+  # value.  This index is crucial as it disambiguates theoretical tone differences 
+  # such as Eb and D#.  Doing so also supports correct double-sharp and double-flat 
+  # interpretations which are rare but theoretically different from their enharmonic 
+  # counterparts.
+  # 
+  class Key < JazzModel::Base
+    Letters = ['C' => 0, 'D' => 1, 'E' => 2, 'F' => 3, 'G' => 4, 'A' => 5, 'B' => 6]
+  
+    # Finds a key given a tonal index 0-11 and a letter index (to disambiguate enharmonic keys)
+    def self.from_index(value, preferred_letter = nil)
+      self.all.find {|k| k.index == value && (preferred_letter.nil? || k.letter_index == preferred_letter)}
+    end
+  
+    # Finds a key object given the name (such as Eb)
+    def self.from_name(value)
+      self.all.find {|k| k.name == value}
+    end
+  
+    # Finds a key object based on the name:
+    # +Key['Eb']+
+    # 
+    def self.[](value)
+      self.from_name(value) || self.from_index(value)
+    end
+  
+    # Returns an array of the 12 primary keys (definitions around the cycle of fourths)
+    def self.primaries
+      self.find_all_by_primary(true)
+    end
+  
+    def self.default
+      self['C']
+    end
+  
+    # Tests whether the current key is enharmonic with +another_key+.
+    def enharmonic_with?(another_key)
+      self.index == another_key.index
+    end
+  
+  end
+end

data/lib/jazz_model/key_context.rb

@@ -0,0 +1,28 @@
+module JazzModel
+  # Key context is a module intended to be mixed in to classes requiring 
+  # the notion of "key context".  Concepts such as chords and scales exist 
+  # as mathematical relationships absent key, but can be put into key context.
+  # Adds a key instance variable to the including class and two new methods:
+  # 
+  # * +in_key_of+(new_key) - Sets the key context to the specified new_key.
+  # * +without_key+ - Removes key context.
+  # 
+  module KeyContext
+  	def self.included(klass)
+  		klass.class_eval do
+  			attr_accessor :key
+			
+  			def in_key_of(name)
+  				self.key = Key.find_by_name(name)
+  				self
+  			end
+  			alias_method :in, :in_key_of
+			
+  			def without_key
+  				self.key = nil
+  				self
+  			end
+  		end
+  	end
+  end
+end

data/lib/jazz_model/mode.rb

@@ -0,0 +1,47 @@
+module JazzModel
+  # In music theory a mode is essentially a slice of a scale with an offset. 
+  # For example second mode of the C major scale would begin and end on D 
+  # but otherwise have the exact same tones as the C major scale.
+  # 
+  # This class represents a mode within the context of a +Scale+.  
+  # 
+  # == Associations
+  # 
+  # * +scale+ - The related scale.
+  # * +chord_scales+ - +ChordScale+ relationships to this mode.
+  # * +chords+ - Direct access to a collection of chords through +chord_scales+.
+  # 
+  # == Tones and Mode Context
+  # 
+  # Tones are directly related to scales, not modes.  There is a +tones+ method 
+  # (and a +notes+ method that delegates to +tones+) here that simulates the tones for 
+  # the mode by setting the mode context of the scale tones, effectively returning 
+  # the tones shifted by X where X is the mode number.
+  # Therefore, you can access tones directly off of the mode because they are proxied 
+  # through scale with the correct offset. 
+  # 
+  # == Examples
+  # 
+  # Since modes should be accessed within the context of scales, mode-related examples are 
+  # actually in scale.  See +Scale+.
+  # 
+  class Mode < JazzModel::Base
+  	include KeyContext
+	
+  	belongs_to :scale
+	
+  	has_many :chord_scales
+  	has_many :chords, :through => :chord_scales, :extend => ChordCollection
+	
+  	delegate :notes, :to => :tones
+	
+  	def tones
+  		if self.key
+  			self.scale.tones.in_mode(self.mode).in_key_of(self.key)
+  		else
+  			self.scale.tones.in_mode(self.mode)
+  		end
+  	end
+	
+  end
+end

data/lib/jazz_model/mode_context.rb

@@ -0,0 +1,32 @@
+module JazzModel
+  # Mode context is a module intended to be mixed in to classes requiring 
+  # the notion of "mode context".  Right now the only class that uses this 
+  # is scale.  Mode context allows scales to take on a mode context which 
+  # effectively offsets tone sequences to retrieve tones in the given scale mode.
+  # 
+  # * +in_mode(new_mode)+ - Sets the mode context to the specified mode (integer).
+  # * +without_mode+ - Removes mode context.
+  #
+  module ModeContext
+  	def self.included(klass)
+  		klass.class_eval do
+  			attr_accessor :mode
+			
+  			def in_mode(value)
+  				if value.is_a?(String)
+  					mode_object = self.respond_to?(:modes) ? self.modes.find_by_name(value) : Mode.find_by_name(value)
+  					self.mode = mode_object.mode unless mode_object.nil?
+  				else
+  					self.mode = value
+  				end
+  				self
+  			end
+			
+  			def without_mode
+  				self.mode = nil
+  				self
+  			end
+  		end
+  	end
+  end
+end

data/lib/jazz_model/mode_sequence.rb

@@ -0,0 +1,15 @@
+module JazzModel
+  # Extends the Scale.modes association by allowing indexed access to modes. 
+  # Whn using it in this manner, key context is passed along.
+  # 
+  module ModeSequence
+  	def [](value)
+  		mode_object = self.find(:first, :conditions => ["name = ? OR mode = ?", value, value])
+  		return nil if mode_object.nil?
+		
+  		# Pass Along Key Information
+  		mode_object.key = proxy_owner.key if proxy_owner.respond_to?(:key) and !proxy_owner.key.nil?
+  		mode_object
+  	end
+  end
+end

data/lib/jazz_model/note_sequence.rb

@@ -0,0 +1,15 @@
+module JazzModel
+  # Mixins for a sequence of note represented as an array.
+  module NoteSequence
+  	def to_xml(options = {})
+  		options[:indent] ||= 2
+  		xml = options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
+  		xml.instruct! unless options[:skip_instruct]
+  		xml.notes do
+  			self.each do |note|
+  				xml.tag!(:note, note.to_s)
+  			end
+  		end
+  	end
+  end
+end

data/lib/jazz_model/notes_collection.rb

@@ -0,0 +1,89 @@
+require 'set'
+
+module JazzModel
+  # NotesCollection represents a collection of notes.  Using this collection,
+  # you can determine chord and scale/mode matches in specific or all keys. 
+  # This class is currently under heavily development and will eventually be home to heavy logic involved 
+  # in associating an arbitrary collection of notes with chords, given that 
+  # some scales tone may be "omitable", etc.
+  # 
+  # == Creating a NotesCollection object
+  # 
+  # Creating the collection of notes should be done by indexing 
+  # the Notes class directly with a comma-separated string of notes.
+  # 
+  # == Current Limitations
+  # 
+  # Will only do exact 100% match of notes given and notes in chords.  No fuzzyness
+  # such as the ability to omit the root and other non-important tones.  Does not yet 
+  # find supersets or subsets.
+  # 
+  # == Examples
+  # 
+  # === Finding All Associated Chords
+  # 
+  #   NotesCollection['C, E, G, A'].chords.symbols
+  #   # => "Amin7, Cmaj6"
+  #  
+  # === Finding Associated Chords in Given Key
+  #
+  #   NotesCollection['C, E, G, A'].in_key_of('A').chords.symbols
+  #   # => "Amin7"
+  # 
+  class NotesCollection
+  	include Enumerable
+  	include KeyContext
+	
+  	attr_accessor :keys
+  	attr_accessor :invalid_keys
+	
+  	def initialize(value = [])
+  		@value_as_given = value
+  		@keys = []
+  		@invalid_keys = []
+		
+  		value = value.split(/,| /).map(&:strip) if value.instance_of?(String)
+  		value.each do |key_name|
+  			key_object = Key[key_name]
+			
+  			if key_object.nil?
+  				@invalid_keys << key_name
+  			else
+  				@keys << key_object
+  			end
+  		end
+  	end
+	
+  	class << self
+  		alias_method :[], :new
+  	end
+	
+  	delegate :each, :to => :keys
+	
+  	# Chords associated with this collection of notes
+  	def chords
+  		if key
+  			chords_in_key(key)
+  		else
+  			Key.primaries.map do |in_key|
+  				chords_in_key(in_key)
+  			end.flatten
+  		end.extend(ChordCollection)
+  	end
+	
+  	# XML Representation
+  	def to_xml
+  		'<NotesCollection name="' + @value_as_given.to_s + '"></NotesCollection>'
+  	end
+	
+	
+  	private
+	
+  	def chords_in_key(in_key)
+  		Chord.all.select do |c|
+  			c.tones.map(&:tone).to_set == keys.map {|k| (k.index - (in_key ? in_key.index : 0)) % 12 }.to_set
+  		end.map {|c| c.key = in_key; c}
+  	end
+	
+  end
+end

data/lib/jazz_model/scale.rb

@@ -0,0 +1,136 @@
+module JazzModel
+  # A scale is an ordered collection of tones.
+  # 
+  # == Creating a Scale
+  # 
+  # Scale objects should be created by indexing the +Scale+ class directly:
+  # 
+  #   Scale['Major']
+  # 
+  # 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:
+  #
+  #   Scale.resolve(name)
+  #
+  # == Associations
+  # 
+  # * +modes+ - Associated modes.
+  # * +main_mode+ - Associated mode with a mode index of 1 (first mode).  This sometimes 
+  #     the only defined mode such as for the whole tone scale.
+  # * +tones+ - A collection of +ScaleTone+s.
+  # * +notes+ - An array of notes (delegated through +tones+)
+  # * +chords+ - A collection of associated chords with the first mode of this scale.
+  # 
+  # == Modes
+  # 
+  # Each scale can have one or many modes, which really define the relationship to chords. 
+  # Modes are accessible like so (all methods are equal):
+  # 
+  #   Scale['Major']['Dorian']
+  #   Scale['Major'][2]
+  #   Scale['Major'].modes['Dorian']
+  #   Scale['Major'].modes[2]
+  # 
+  # == Examples
+  # 
+  # === Listing Tones in Scales
+  # 
+  #   Scale['Major'].notes
+  #   # => ["C", "D", "E", "F", "G", "A", "B"]
+  #  
+  #   Scale['Major'].in_key_of('Eb').notes
+  #   Scale['Eb Major'].notes  # Same as above
+  #   # => ["Eb", "F", "G", "Ab", "Bb", "C", "D"]
+  # 
+  # === Correctly Interpets Theoretical Keys (not just pitches)
+  # 
+  #   Scale['Gb Major'].notes
+  #   # => ["Gb", "Ab", "Bb", "Cb", "Db", "Eb", "F"]
+  #   # Note the use of Cb which is theoretically correct over enharmonic B.
+  # 
+  # Also correctly interpet tones off of enharmonic base keys:
+  # 
+  #   Scale['Gb Major'].notes
+  #   # => ["Gb", "Ab", "Bb", "Cb", "Db", "Eb", "F"]
+  #   Scale['F# Major'].notes
+  #   # => ["F#", "G#", "A#", "B", "C#", "D#", "E#"]
+  # 
+  # === Listing Tones within the context of a mode
+  # 
+  #   Scale['Major'].modes['Dorian']
+  #   Scale['Major']['Dorian']  # Same as above
+  #   # => ["D", "E", "F", "G", "A", "B", "C"]
+  #  
+  #   Scale['Melodic Minor'].modes['Super Locrian'].notes
+  #   # => ["B", "C", "D", "Eb", "F", "G", "A"]  # aka. Altered Scale or Dim. Whole Tone
+  # 
+  # == Listing Related Chords
+  # 
+  #   Scale['Major'].chords.symbols
+  #   # => ['maj7', 'maj6', '6/9']
+  #   Scale['Major']['Dorian'].chords.symbols
+  #   # => ['min7', 'min6']
+  #  
+  class Scale < JazzModel::Base
+  	include KeyContext
+  	include ModeContext
+	  
+		has_many :modes, :extend => ModeSequence, :dependent => :destroy
+		has_many :tones, :class_name => 'ScaleTone', :extend => ToneSequence, :dependent => :destroy
+	
+  	delegate :notes, :to => :tones
+  	delegate :chords, :to => :main_mode
+	
+  	class << self
+  		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.gsub!(/^#{k.name}/, '').strip!
+  					break
+  				end
+  			end
+			
+  			scale = Scale.find_by_name(symbol)
+			
+  			# Perhaps the matched key was really part of the name of the chord, try that:
+  			if scale.nil? && !in_key.nil?
+  				symbol = in_key.name + symbol
+  				scale = Scale.all.detect {|s| s.name == symbol}
+  			end
+			
+  			# If still not found, must be invalid:
+  			return nil if scale.nil?
+			
+  			scale.key = in_key
+  			scale
+  		end
+  		alias_method :[], :resolve
+  	end
+	
+  	def [](name)
+  		name.is_a?(String) ? self.modes.find_by_name(name) : self.modes.find_by_mode(name)
+  	end
+	
+  	def main_mode
+  		self[1]
+  	end
+	
+  	def symmetric?
+  		!self.symmetry_index.nil?
+  	end
+	
+	
+  	def to_xml(options = {})
+  		super(options.merge(:skip_types => true))
+  	end
+	
+  end
+
+end