jazz_model 0.1.0 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ae14c88e9a943a376b18425ad41afe9e0d849f49b2e5dcc41461deff3876776
+  data.tar.gz: 32efbd9b5965a81b914107eb98c3cf953c87a1b6ccdc96ca5d2c58882ad06568
+SHA512:
+  metadata.gz: 692112258b9f3e43c79baf63372ab00faf5e3ad97a52e720733ba83747b2b7534b3751b2b7b867215282b46c8f4e2fb65b8bb71ee622c5e6e06c71c04899a270
+  data.tar.gz: 37f10d76333e8bf5e10bf01b19d643487663d0aa33c0b4793c6e24c4c533a5252dbc12b7fd3d86e74a51d68974a2163836ee51bf53be98645ae99332c520fb85

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2008-2026 Ben Hughes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# Jazz Model
+
+[![CI](https://github.com/eigenben/jazz_model/actions/workflows/ci.yml/badge.svg)](https://github.com/eigenben/jazz_model/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/jazz_model.svg)](https://rubygems.org/gems/jazz_model)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+An ActiveRecord object model of jazz theory. Resolve chord symbols, spell chords and scales correctly in any key, and walk the relationships between chords, scales, and modes.
+
+```ruby
+Chord["Bmaj7#11"].notes
+# => ["B", "D#", "F#", "A#", "E#"]   # E#, not F: theoretically correct spelling
+
+Scale["Melodic Minor"]["Super Locrian"].notes
+# => ["B", "C", "D", "Eb", "F", "G", "A"]
+
+Scale["Major"]["Dorian"].chords.symbols
+# => ["min", "min7", "min6"]
+```
+
+## How it works
+
+Every chord, scale, and mode is defined as a mathematical system: a sequence of **semitone offsets** (0–11) paired with **letter offsets** (0–6). Transposing to a new key is modular arithmetic on both, and the letter offset is what lets Jazz Model tell `E#` from `F` and `Cb` from `B` rather than just naming pitches.
+
+All of the theory, such as which tones make up a C7 or which modes fit a min7 chord, lives in data rather than code. Definitions populate an in-memory SQLite database through ActiveRecord, so the whole model can be queried and traversed with familiar associations.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "jazz_model"
+```
+
+Then load the default definitions when your application boots:
+
+```ruby
+require "jazz_model"
+JazzModel::Base.load_definitions
+
+# or, equivalently
+require "jazz_model/definitions"
+```
+
+Requires Ruby 3.2+ and ActiveRecord 7.2 or 8.x.
+
+## Usage
+
+Everything lives under the `JazzModel` namespace. The examples below assume `include JazzModel`.
+
+### Chords
+
+```ruby
+Chord["maj7"]           # without key context (defaults to C)
+Chord["Bbmaj7"]         # with key context
+Chord["Abmaj7#11"].name
+# => "Major 7 #11"
+
+Chord["Ebmaj7"].notes
+# => ["Eb", "G", "Bb", "D"]
+
+Chord["maj7"].in_key_of("Eb").notes
+# => ["Eb", "G", "Bb", "D"]
+
+Chord["F7b9#9"].notes
+# => ["F", "A", "Eb", "Gb", "G#", "C#"]
+
+# Enharmonic keys are spelled from their own letter names
+Chord["Gbmaj7"].notes
+# => ["Gb", "Bb", "Db", "F"]
+Chord["F#maj7"].notes
+# => ["F#", "A#", "C#", "E#"]
+```
+
+### Scales and modes
+
+```ruby
+Scale["Major"].notes
+# => ["C", "D", "E", "F", "G", "A", "B"]
+
+Scale["Eb Major"].notes                  # same as Scale["Major"].in_key_of("Eb")
+# => ["Eb", "F", "G", "Ab", "Bb", "C", "D"]
+
+Scale["Whole Tone"].notes
+# => ["C", "D", "E", "F#", "G#", "Bb"]
+
+Scale["Bebop"].notes
+# => ["C", "D", "E", "F", "G", "A", "Bb", "B"]
+
+# Modes by name or number
+Scale["Major"]["Dorian"]                 # same as Scale["Major"].modes["Dorian"]
+Scale["Major"][2]
+
+Scale["Major"].in_key_of("Eb")["Dorian"].notes
+# => ["F", "G", "Ab", "Bb", "C", "D", "Eb"]
+
+Scale["Melodic Minor"]["Lydian Dominant"].notes
+# => ["F", "G", "A", "B", "C", "D", "Eb"]
+```
+
+### Chord–scale relationships
+
+```ruby
+Chord["min7"].modes.map(&:name)
+# => ["Dorian", "Aeolian"]
+
+Scale["Major"][4].chords.symbols
+# => ["maj7#11"]
+
+Scale["Major"].chords.map { |c| "#{c.name}: #{c.notes.join(", ")}" }
+# => ["Major Triad: C, E, G",
+#     "Major 7: C, E, G, B",
+#     "Major 6: C, E, G, A",
+#     "Dominant 6/9: C, E, G, Bb, D, A"]
+```
+
+### Identifying chords from notes
+
+```ruby
+NotesCollection["C E G A"].chords.symbols
+# => ["C6", "Amin7"]
+
+NotesCollection["C E G A"].in_key_of("A").chords.symbols
+# => ["Amin7"]
+```
+
+## Definitions
+
+Definitions are packaged sets of instructions that create the model's data. Two ship with the gem:
+
+- **`keys`**: the 12 pitch classes and their enharmonic spellings. Always load this for Western harmony.
+- **`default`**: scales, modes, chords, chord symbols, and chord–scale relationships. Depends on `keys`.
+
+`JazzModel::Base.load_definitions` loads `default` (and therefore `keys`). Pass a name to load something else:
+
+```ruby
+JazzModel::Base.load_definitions(:my_custom_set)
+```
+
+### Writing your own
+
+Definitions declare dependencies like Rake tasks:
+
+```ruby
+JazzModel::Definition.define my_definition: [:keys] do
+  JazzModel::Scale.create!(name: "Hirajoshi").tap do |s|
+    s.tones.create([
+      {tone: 0, letter_index: 0},
+      {tone: 2, letter_index: 1},
+      {tone: 3, letter_index: 2},
+      {tone: 7, letter_index: 4},
+      {tone: 8, letter_index: 5}
+    ])
+    s.modes.create!(mode: 1, name: "Hirajoshi")
+  end
+end
+```
+
+See [`lib/jazz_model/definitions`](lib/jazz_model/definitions) for complete examples.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake          # runs the specs and Standard
+```
+
+To run the specs against ActiveRecord 7.2:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/activerecord_7_2.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/activerecord_7_2.gemfile bundle exec rspec
+```
+
+## Ideas
+
+- Chord progression analysis
+- MIDI input and output
+- Melodic material and licks
+- Fuller voicing support
+
+## History
+
+Jazz Model began in 2008 as the engine behind a jazz theory web app and was extracted into a gem in 2010. In 2026 it was updated for current Ruby and ActiveRecord.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/db/schema.rb

@@ -0,0 +1,83 @@
+JazzModel::Base.with_connection do |c|
+  c.create_table :keys do |t|
+    t.string :name
+    t.string :long_name
+    t.boolean :primary, :default => true
+    t.integer :index
+    t.integer :letter_index
+    t.integer :cycle_index
+  end
+  
+  c.create_table :chord_qualities do |t|
+    t.string :name
+    t.string :code
+  end
+  
+  c.create_table :chords do |t|
+    t.belongs_to :chord_quality
+    t.integer :parent_id
+    t.string :name
+    t.text :synonyms
+    t.text :information
+  end
+  
+  c.create_table :chord_symbols do |t|
+    t.belongs_to :chord
+    t.string :name
+    t.boolean :case_sensitive, :default => false
+    t.integer :strength
+    t.boolean :primary, :default => false
+  end
+  
+  c.create_table :chord_tones do |t|
+    t.belongs_to :chord
+    t.integer :position
+    t.integer :tone
+    t.integer :letter_index
+    t.integer :strength
+    t.boolean :omitable, :default => false
+    t.text :information
+  end
+  
+  c.create_table :scales do |t|
+    t.string :name
+    t.string :information
+    t.integer :symmetry_index
+  end
+  
+  c.create_table :scale_tones do |t|
+    t.belongs_to :scale
+    t.integer :position
+    t.integer :tone
+    t.integer :letter_index
+  end
+  
+  c.create_table :modes do |t|
+    t.belongs_to :scale
+    t.integer :mode
+    t.string :name
+    t.text :synonyms
+    t.integer :dissonance
+  end
+  
+  c.create_table :chord_scales do |t|
+    t.belongs_to :chord
+    t.belongs_to :mode
+    t.integer :strength
+    t.text :information
+  end
+  
+  c.create_table :voicings do |t|
+    t.belongs_to :chord
+    t.string :name
+    t.text :information
+  end
+  
+  c.create_table :voicing_tones do |t|
+    t.belongs_to :voicing
+    t.integer :position
+    t.integer :tone
+    t.integer :tone_reference_offset, :default => 0
+    t.text :information
+  end
+end

data/lib/jazz_model/base.rb

@@ -1,15 +1,22 @@
 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")
-    
+
+    # A named, shared-cache in-memory database so every connection in the pool
+    # sees the same data. idle_timeout: 0 keeps the pool from closing idle
+    # connections, which would otherwise discard the in-memory database.
+    establish_connection(
+      adapter: "sqlite3",
+      database: "file:jazz_model?mode=memory&cache=shared",
+      idle_timeout: 0
+    )
+    load File.expand_path("../../db/schema.rb", __dir__)
+
     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
+end

data/lib/jazz_model/chord.rb

@@ -1,141 +1,121 @@
 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, 
+  #
+  # 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 
+  #
+  # 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 
+  # +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 ActsAsTree
     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 :symbols, class_name: "ChordSymbol", extend: ChordSymbolCollection
+    has_one :primary_symbol, -> { where(primary: true) }, class_name: "ChordSymbol"
+
     has_many :chord_scales
-    has_many :modes, :through => :chord_scales
-    has_many :tones, :class_name => 'ChordTone', :extend => ToneSequence
+    has_many :modes, through: :chord_scales
+    has_many :tones, class_name: "ChordTone", extend: ToneSequence
     has_many :voicings
-  
-    delegate :notes, :to => :tones
-  
+
+    delegate :notes, to: :tones
+
     def symbols_list
-      self.symbols.map {|s| s.name }.join(', ')
+      symbols.map(&: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.
+      # Resolves a chord symbol, optionally prefixed with a key, into a chord.
+      # Ambiguous prefixes are tried longest key first, so "Cbmaj7" is a C-flat
+      # major 7th while "Cb5" falls back to a C chord with a flat 5th.
       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]
+
+        KeyContext.each_split(symbol) do |in_key, rest|
+          chord_symbol = ChordSymbol[rest] or next
+          chord = chord_symbol.chord
+          chord.key = in_key
+          return chord
         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
+        nil
       end
       alias_method :[], :resolve
-    
     end
-  
   end
-end
+end

data/lib/jazz_model/chord_collection.rb

@@ -1,68 +1,44 @@
 module JazzModel
-  # Intended to be used as a dynamic object extension of an Array representing 
+  # 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(', ')
+      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}" }
+      map { |c| "#{c.key&.name}#{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 }
+      map { |c| "#{c.key&.name} #{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.
+
+    # Resolves a chord symbol, optionally prefixed with a key, into one of the
+    # chords in this collection.  See Chord.resolve.
     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
+
+      KeyContext.each_split(symbol) do |in_key, rest|
+        chord_symbol = flat_map { |c| c.symbols.to_a }.detect { |cs| cs.matches?(rest) } or next
+        chord = chord_symbol.chord
+        chord.key = in_key
+        return chord
       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
+      nil
     end
     alias_method :[], :resolve
-  
   end
-end
+end

data/lib/jazz_model/chord_quality.rb

@@ -1,19 +1,18 @@
 module JazzModel
-  # A basic chord quality such as major or minor.  This may be abandoned in the future in favor of a 
+  # A basic chord quality such as major or minor.  This may be abandoned in the future in favor of a
   # deep heirarchy based soley around chords.
-  # 
+  #
   # == Associations
   # * +chords+ - A collection of chords associated with the chord quality.
-  # 
+  #
   class ChordQuality < JazzModel::Base
     has_many :chords
 
     class << self
       def resolve(name)
-        self.find_by_name(name)
+        find_by_name(name)
       end
       alias_method :[], :resolve
     end
-
   end
-end
+end

data/lib/jazz_model/chord_scale.rb

@@ -1,30 +1,30 @@
 module JazzModel
-  # A relationship of one chord to one scale, with some other optional 
-  # information such as +strength+, representing the strength of the 
+  # A relationship of one chord to one scale, with some other optional
+  # information such as +strength+, representing the strength of the
   # relationships.
-  # 
+  #
   # == Associations
-  # 
+  #
   # * +chord+ - Associated chord.
   # * +mode+ - Associated scale mode.
-  # * +scale+ - Associated scale through mode. 
-  # 
+  # * +scale+ - Associated scale through mode.
+  #
   # == Key Context
   #
   # Delegates +key+ to the associated chord to access key context through this relationship.
-  # 
+  #
   class ChordScale < JazzModel::Base
     belongs_to :chord
     belongs_to :mode
-  
-    delegate :scale, :to => :mode
-    delegate :key, :to => :chord
-  
+
+    delegate :scale, to: :mode
+    delegate :key, to: :chord
+
     def self.specify(mode, strength = 1)
-      chord_scale = self.new
+      chord_scale = new
       chord_scale.mode = mode
       chord_scale.strength = strength
       chord_scale
     end
   end
-end
+end