musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/music/scale_kinds/symmetric/diminished_hw_scale_kind.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Diminished half-whole scale kind.
+    #
+    # DiminishedHWScaleKind defines the half-whole diminished scale (also called
+    # octatonic scale), an eight-note symmetric scale alternating half steps and
+    # whole steps. It's commonly used over diminished 7th chords.
+    #
+    # ## Pitch Structure
+    #
+    # 8 degrees plus extended:
+    #
+    # **Scale Degrees** (pattern: H-W-H-W-H-W-H-W):
+    #
+    # - **i** (_1): Root (0 semitones)
+    # - **ii** (_2): Minor second (1 semitone)
+    # - **iii** (_3): Minor third (3 semitones)
+    # - **iv** (_4): Major third (4 semitones)
+    # - **v** (_5): Diminished fifth (6 semitones)
+    # - **vi** (_6): Perfect fifth (7 semitones)
+    # - **vii** (_7): Major sixth (9 semitones)
+    # - **viii** (_8): Minor seventh (10 semitones)
+    #
+    # ## Symmetric Properties
+    #
+    # - Only 3 distinct diminished scales exist
+    # - Repeats every minor third (3 semitones)
+    # - Contains 4 minor thirds, 4 major thirds, 2 tritones
+    # - Every diminished 7th chord is contained within
+    #
+    # ## Musical Character
+    #
+    # The half-whole diminished scale:
+    #
+    # - Tense, dark, unstable quality
+    # - Used over diminished 7th chords
+    # - Common in jazz, film scores, classical
+    # - Creates strong chromatic tension
+    #
+    # ## Usage
+    #
+    #     c_dim = Scales[:et12][440.0][:diminished_hw][60]
+    #     c_dim[0].pitch  # C (60)
+    #     c_dim[1].pitch  # Db (61)
+    #
+    # @see ScaleKind Abstract base class
+    # @see DiminishedWHScaleKind Whole-half diminished (dominant diminished)
+    # @see WholeToneScaleKind Whole tone scale
+    class DiminishedHWScaleKind < ScaleKind
+      @base_metadata = {
+        family: :symmetric,
+        brightness: nil,
+        character: [:diminished, :tense, :jazz],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[ii _2 second],
+               pitch: 1 },
+             { functions: %i[iii _3 third],
+               pitch: 3 },
+             { functions: %i[iv _4 fourth],
+               pitch: 4 },
+             { functions: %i[v _5 fifth],
+               pitch: 6 },
+             { functions: %i[vi _6 sixth],
+               pitch: 7 },
+             { functions: %i[vii _7 seventh],
+               pitch: 9 },
+             { functions: %i[viii _8 eighth],
+               pitch: 10 },
+             { functions: %i[ix _9 ninth],
+               pitch: 12 },
+             { functions: %i[x _10 tenth],
+               pitch: 12 + 1 },
+             { functions: %i[xi _11 eleventh],
+               pitch: 12 + 3 },
+             { functions: %i[xii _12 twelfth],
+               pitch: 12 + 4 },
+             { functions: %i[xiii _13 thirteenth],
+               pitch: 12 + 6 },
+             { functions: %i[xiv _14 fourteenth],
+               pitch: 12 + 7 },
+             { functions: %i[xv _15 fifteenth],
+               pitch: 12 + 9 },
+             { functions: %i[xvi _16 sixteenth],
+               pitch: 12 + 10 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          8
+        end
+
+        def id
+          :diminished_hw
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register DiminishedHWScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/symmetric/diminished_wh_scale_kind.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Diminished whole-half scale kind.
+    #
+    # DiminishedWHScaleKind defines the whole-half diminished scale (also called
+    # dominant diminished), an eight-note symmetric scale alternating whole steps
+    # and half steps. It's commonly used over dominant 7th chords with altered tensions.
+    #
+    # ## Pitch Structure
+    #
+    # 8 degrees plus extended:
+    #
+    # **Scale Degrees** (pattern: W-H-W-H-W-H-W-H):
+    #
+    # - **I** (_1): Root (0 semitones)
+    # - **II** (_2): Major second (2 semitones)
+    # - **III** (_3): Minor third (3 semitones)
+    # - **IV** (_4): Perfect fourth (5 semitones)
+    # - **V** (_5): Diminished fifth (6 semitones)
+    # - **VI** (_6): Augmented fifth (8 semitones)
+    # - **VII** (_7): Major sixth (9 semitones)
+    # - **VIII** (_8): Major seventh (11 semitones)
+    #
+    # ## Symmetric Properties
+    #
+    # - Only 3 distinct diminished scales exist
+    # - Repeats every minor third (3 semitones)
+    # - Same notes as half-whole, but different starting point
+    # - Contains natural 9, #9, #11, 13 over dominant chord
+    #
+    # ## Musical Character
+    #
+    # The whole-half diminished scale:
+    #
+    # - Used over dominant 7th chords (hence "dominant diminished")
+    # - Provides b9, #9, #11, and natural 13 tensions
+    # - Common in bebop and modern jazz
+    # - Creates sophisticated altered dominant sound
+    #
+    # ## Usage
+    #
+    #     g_dom_dim = Scales[:et12][440.0][:diminished_wh][67]
+    #     g_dom_dim[0].pitch  # G (67)
+    #     g_dom_dim[1].pitch  # A (69)
+    #
+    # @see ScaleKind Abstract base class
+    # @see DiminishedHWScaleKind Half-whole diminished
+    # @see AlteredScaleKind Altered scale (another dominant scale)
+    class DiminishedWHScaleKind < ScaleKind
+      @base_metadata = {
+        family: :symmetric,
+        brightness: nil,
+        character: [:diminished, :dominant, :jazz],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[I _1 tonic first],
+               pitch: 0 },
+             { functions: %i[II _2 second],
+               pitch: 2 },
+             { functions: %i[III _3 third],
+               pitch: 3 },
+             { functions: %i[IV _4 fourth],
+               pitch: 5 },
+             { functions: %i[V _5 fifth],
+               pitch: 6 },
+             { functions: %i[VI _6 sixth],
+               pitch: 8 },
+             { functions: %i[VII _7 seventh],
+               pitch: 9 },
+             { functions: %i[VIII _8 eighth],
+               pitch: 11 },
+             { functions: %i[IX _9 ninth],
+               pitch: 12 },
+             { functions: %i[X _10 tenth],
+               pitch: 12 + 2 },
+             { functions: %i[XI _11 eleventh],
+               pitch: 12 + 3 },
+             { functions: %i[XII _12 twelfth],
+               pitch: 12 + 5 },
+             { functions: %i[XIII _13 thirteenth],
+               pitch: 12 + 6 },
+             { functions: %i[XIV _14 fourteenth],
+               pitch: 12 + 8 },
+             { functions: %i[XV _15 fifteenth],
+               pitch: 12 + 9 },
+             { functions: %i[XVI _16 sixteenth],
+               pitch: 12 + 11 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          8
+        end
+
+        def id
+          :diminished_wh
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register DiminishedWHScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/symmetric/whole_tone_scale_kind.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Whole tone scale kind.
+    #
+    # WholeToneScaleKind defines the whole tone scale, a six-note symmetric
+    # scale where every interval is a whole step (major second). It has a
+    # dreamy, ambiguous quality with no clear tonal center.
+    #
+    # ## Pitch Structure
+    #
+    # 6 degrees plus extended:
+    #
+    # **Scale Degrees**:
+    #
+    # - **I** (_1): Root (0 semitones)
+    # - **II** (_2): Major second (2 semitones)
+    # - **III** (_3): Major third (4 semitones)
+    # - **IV#** (_4): Augmented fourth (6 semitones)
+    # - **V#** (_5): Augmented fifth (8 semitones)
+    # - **VII** (_6): Minor seventh (10 semitones)
+    #
+    # ## Symmetric Properties
+    #
+    # - Only 2 distinct whole tone scales exist (C and C#)
+    # - Every note can function as the root
+    # - Divides the octave into 6 equal parts
+    # - No perfect fifths = no strong harmonic function
+    #
+    # ## Musical Character
+    #
+    # The whole tone scale:
+    #
+    # - Dreamy, floating, ambiguous quality
+    # - No leading tones or tendency tones
+    # - Associated with impressionism (Debussy)
+    # - Used over augmented and dominant 7#5 chords
+    #
+    # ## Usage
+    #
+    #     c_whole = Scales[:et12][440.0][:whole_tone][60]
+    #     c_whole[0].pitch  # C (60)
+    #     c_whole[3].pitch  # F# (66)
+    #
+    # @see ScaleKind Abstract base class
+    # @see DiminishedHWScaleKind Diminished scale (another symmetric scale)
+    class WholeToneScaleKind < ScaleKind
+      @base_metadata = {
+        family: :symmetric,
+        brightness: nil,
+        character: [:floating, :impressionist, :ambiguous],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[I _1 tonic first],
+               pitch: 0 },
+             { functions: %i[II _2 second],
+               pitch: 2 },
+             { functions: %i[III _3 third],
+               pitch: 4 },
+             { functions: %i[IV _4 fourth],
+               pitch: 6 },
+             { functions: %i[V _5 fifth],
+               pitch: 8 },
+             { functions: %i[VI _6 sixth],
+               pitch: 10 },
+             { functions: %i[VII _7 seventh],
+               pitch: 12 },
+             { functions: %i[VIII _8 eighth],
+               pitch: 12 + 2 },
+             { functions: %i[IX _9 ninth],
+               pitch: 12 + 4 },
+             { functions: %i[X _10 tenth],
+               pitch: 12 + 6 },
+             { functions: %i[XI _11 eleventh],
+               pitch: 12 + 8 },
+             { functions: %i[XII _12 twelfth],
+               pitch: 12 + 10 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          6
+        end
+
+        def id
+          :whole_tone
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register WholeToneScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_systems/equally_tempered_12_tone_scale_system.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'twelve_semitones_scale_system'
+
+module Musa
+  module Scales
+    # Equal temperament 12-tone scale system.
+    #
+    # EquallyTempered12ToneScaleSystem implements the standard equal temperament
+    # tuning where each semitone has exactly the same frequency ratio: 2^(1/12).
+    # This is the most common tuning system in modern Western music.
+    #
+    # ## Frequency Calculation
+    #
+    # Uses the equal temperament formula based on A440 concert pitch:
+    #
+    #     frequency = a_frequency × 2^((pitch - 69) / 12)
+    #
+    # Where:
+    #
+    # - **a_frequency**: Reference A frequency (typically 440 Hz)
+    # - **pitch**: MIDI pitch number (69 = A4)
+    #
+    # ## Historical Pitch Standards
+    #
+    # Different A frequencies represent different historical standards:
+    #
+    # - **440 Hz**: Modern concert pitch (ISO 16)
+    # - **442 Hz**: Used by some orchestras (brighter sound)
+    # - **415 Hz**: Baroque pitch (approximately A=415)
+    # - **432 Hz**: Alternative tuning (some claim harmonic benefits)
+    #
+    # ## Registration
+    #
+    # This system is registered as the default scale system, accessible via:
+    #
+    #     Scales[:et12]                    # By ID
+    #     Scales.default_system            # As default
+    #
+    # ## Usage
+    #
+    #     # Get system with standard A440 tuning
+    #     system = Scales[:et12][440.0]
+    #
+    #     # Get system with baroque tuning
+    #     baroque = Scales[:et12][415.0]
+    #
+    #     # Access scale kinds
+    #     c_major = system[:major][60]
+    #     a_minor = system[:minor][69]
+    #
+    # @see TwelveSemitonesScaleSystem Abstract base class
+    # @see ScaleSystem#frequency_of_pitch Abstract method implemented here
+    class EquallyTempered12ToneScaleSystem < TwelveSemitonesScaleSystem
+      class << self
+        # Calculates frequency for a pitch using equal temperament.
+        #
+        # Implements the equal temperament tuning formula where each semitone
+        # has a frequency ratio of 2^(1/12) ≈ 1.059463.
+        #
+        # @param pitch [Integer] MIDI pitch number
+        # @param _root_pitch [Integer] unused (required by interface)
+        # @param a_frequency [Numeric] reference A4 frequency in Hz
+        # @return [Float] frequency in Hz
+        #
+        # @example Standard A440 tuning
+        #   frequency_of_pitch(69, nil, 440.0)  # => 440.0 (A4)
+        #   frequency_of_pitch(60, nil, 440.0)  # => 261.63 (C4, middle C)
+        #
+        # @example Baroque tuning
+        #   frequency_of_pitch(69, nil, 415.0)  # => 415.0 (A4)
+        def frequency_of_pitch(pitch, _root_pitch, a_frequency)
+          (a_frequency * Rational(2)**Rational(pitch - 69, 12)).to_f
+        end
+      end
+
+      Scales.register EquallyTempered12ToneScaleSystem, default: true
+    end
+  end
+end

data/lib/musa-dsl/music/scale_systems/twelve_semitones_scale_system.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Base class for 12-semitone scale systems.
+    #
+    # TwelveSemitonesScaleSystem provides the foundation for any scale system
+    # using 12 semitones per octave. It defines intervals and structure but
+    # doesn't specify tuning (frequency calculation).
+    #
+    # Concrete subclasses must implement frequency calculation:
+    #
+    # - {EquallyTempered12ToneScaleSystem}: Equal temperament (12-TET)
+    # - Other temperaments could be added (e.g., meantone, just intonation)
+    #
+    # ## Intervals
+    #
+    # Defines standard interval names using semitone distances:
+    #
+    #     { P0: 0, m2: 1, M2: 2, m3: 3, M3: 4, P4: 5, TT: 6,
+    #       P5: 7, m6: 8, M6: 9, m7: 10, M7: 11, P8: 12 }
+    #
+    # @abstract Subclasses must implement {frequency_of_pitch}
+    # @see EquallyTempered12ToneScaleSystem Concrete equal temperament implementation
+    class TwelveSemitonesScaleSystem < ScaleSystem
+      class << self
+        @@intervals = { P0: 0, m2: 1, M2: 2, m3: 3, M3: 4, P4: 5, TT: 6, P5: 7, m6: 8, M6: 9, m7: 10, M7: 11, P8: 12 }
+
+        # System identifier.
+        # @return [Symbol] :et12
+        def id
+          :et12
+        end
+
+        # Number of distinct notes per octave.
+        # @return [Integer] 12
+        def notes_in_octave
+          12
+        end
+
+        # Size of smallest pitch division.
+        # @return [Integer] 1 (semitone)
+        def part_of_tone_size
+          1
+        end
+
+        # Interval definitions.
+        #
+        # @return [Hash{Symbol => Integer}] interval name to semitones mapping
+        #
+        # @example
+        #   intervals[:P5]  # => 7 (perfect fifth)
+        #   intervals[:M3]  # => 4 (major third)
+        def intervals
+          @@intervals
+        end
+      end
+    end
+  end
+end