musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/music/scale_kinds/melodic_minor/lydian_dominant_scale_kind.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Lydian dominant scale kind (fourth mode of melodic minor).
+    #
+    # LydianDominantScaleKind defines the Lydian dominant scale (also called
+    # Lydian b7, Overtone scale, or Bartók scale), the fourth mode of the
+    # melodic minor scale. It combines the Lydian's raised fourth with a
+    # dominant seventh.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (uppercase for major quality):
+    #
+    # - **I** (tonic): Root (0 semitones)
+    # - **II** (supertonic): Major second (2 semitones)
+    # - **III** (mediant): Major third (4 semitones)
+    # - **IV** (subdominant): Augmented fourth (6 semitones) ← LYDIAN (#4)
+    # - **V** (dominant): Perfect fifth (7 semitones)
+    # - **VI** (submediant): Major sixth (9 semitones)
+    # - **VII** (subtonic): Minor seventh (10 semitones) ← DOMINANT (b7)
+    #
+    # ## Relationship to Other Modes
+    #
+    # - Lydian with lowered 7th
+    # - Mixolydian with raised 4th
+    # - 4th mode of melodic minor
+    # - Matches the harmonic series closely
+    #
+    # ## Musical Character
+    #
+    # The Lydian dominant scale:
+    #
+    # - Bright but with dominant tension
+    # - Used over 7#11 chords
+    # - Common in jazz, Béla Bartók's music
+    # - Creates sophisticated dominant sound
+    #
+    # ## Usage
+    #
+    #     f_lyd_dom = Scales[:et12][440.0][:lydian_dominant][65]
+    #     f_lyd_dom.tonic  # F (65)
+    #     f_lyd_dom.IV     # B (71) - augmented fourth
+    #     f_lyd_dom.VII    # Eb (75) - minor seventh
+    #
+    # @see ScaleKind Abstract base class
+    # @see LydianScaleKind Lydian mode (with major 7th)
+    # @see MixolydianScaleKind Mixolydian mode (with perfect 4th)
+    # @see MelodicMinorScaleKind Parent melodic minor scale
+    class LydianDominantScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: 1,
+        character: [:bright, :dominant, :fusion],
+        parent: { scale: :minor_melodic, degree: 4 }
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[I _1 tonic first],
+               pitch: 0 },
+             { functions: %i[II _2 supertonic second],
+               pitch: 2 },
+             { functions: %i[III _3 mediant third],
+               pitch: 4 },
+             { functions: %i[IV _4 subdominant fourth],
+               pitch: 6 },
+             { functions: %i[V _5 dominant fifth],
+               pitch: 7 },
+             { functions: %i[VI _6 submediant sixth],
+               pitch: 9 },
+             { functions: %i[VII _7 subtonic seventh],
+               pitch: 10 },
+             { functions: %i[VIII _8 eighth],
+               pitch: 12 },
+             { functions: %i[IX _9 ninth],
+               pitch: 12 + 2 },
+             { functions: %i[X _10 tenth],
+               pitch: 12 + 4 },
+             { functions: %i[XI _11 eleventh],
+               pitch: 12 + 6 },
+             { functions: %i[XII _12 twelfth],
+               pitch: 12 + 7 },
+             { functions: %i[XIII _13 thirteenth],
+               pitch: 12 + 9 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :lydian_dominant
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register LydianDominantScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/melodic_minor/melodic_minor_scale_kind.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Melodic minor scale kind (ascending form).
+    #
+    # MelodicMinorScaleKind defines the melodic minor scale in its ascending
+    # form (also called jazz minor). It has a minor third but major sixth and
+    # seventh, creating a unique hybrid between minor and major qualities.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (lowercase for minor quality):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Major second (2 semitones)
+    # - **iii** (mediant): Minor third (3 semitones) ← MINOR
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Perfect fifth (7 semitones)
+    # - **vi** (submediant): Major sixth (9 semitones) ← MAJOR
+    # - **vii** (leading): Major seventh (11 semitones) ← MAJOR
+    #
+    # ## Relationship to Other Scales
+    #
+    # - Minor third (like natural minor)
+    # - Major 6th and 7th (like major scale)
+    # - Parent scale for many jazz modes (Lydian Dominant, Altered, etc.)
+    #
+    # ## Musical Character
+    #
+    # The melodic minor scale:
+    #
+    # - Minor quality with major upper structure
+    # - Essential in jazz harmony
+    # - Less dark than harmonic minor (no augmented 2nd)
+    # - Smooth melodic contour
+    #
+    # ## Usage
+    #
+    #     c_mel_min = Scales[:et12][440.0][:minor_melodic][60]
+    #     c_mel_min.tonic    # C (60)
+    #     c_mel_min.mediant  # Eb (63) - minor third
+    #     c_mel_min.leading  # B (71) - major seventh
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor
+    # @see MinorHarmonicScaleKind Harmonic minor
+    # @see AlteredScaleKind Altered scale (7th mode of melodic minor)
+    class MelodicMinorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: -1,
+        character: [:minor, :ascending, :classical],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[ii _2 supertonic second],
+               pitch: 2 },
+             { functions: %i[iii _3 mediant third],
+               pitch: 3 },
+             { functions: %i[iv _4 subdominant fourth],
+               pitch: 5 },
+             { functions: %i[v _5 dominant fifth],
+               pitch: 7 },
+             { functions: %i[vi _6 submediant sixth],
+               pitch: 9 },
+             { functions: %i[vii _7 leading seventh],
+               pitch: 11 },
+             { functions: %i[viii _8 eighth],
+               pitch: 12 },
+             { functions: %i[ix _9 ninth],
+               pitch: 12 + 2 },
+             { functions: %i[x _10 tenth],
+               pitch: 12 + 3 },
+             { functions: %i[xi _11 eleventh],
+               pitch: 12 + 5 },
+             { functions: %i[xii _12 twelfth],
+               pitch: 12 + 7 },
+             { functions: %i[xiii _13 thirteenth],
+               pitch: 12 + 9 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :minor_melodic
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register MelodicMinorScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/melodic_minor/mixolydian_b6_scale_kind.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Mixolydian b6 scale kind (fifth mode of melodic minor).
+    #
+    # MixolydianB6ScaleKind defines the Mixolydian b6 scale (also called
+    # Melodic Major, Hindu scale, or Aeolian Dominant), the fifth mode of
+    # the melodic minor scale. It combines the Mixolydian's major quality
+    # with a minor sixth.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (uppercase for major quality):
+    #
+    # - **I** (tonic): Root (0 semitones)
+    # - **II** (supertonic): Major second (2 semitones)
+    # - **III** (mediant): Major third (4 semitones)
+    # - **IV** (subdominant): Perfect fourth (5 semitones)
+    # - **V** (dominant): Perfect fifth (7 semitones)
+    # - **VI** (submediant): Minor sixth (8 semitones) ← CHARACTERISTIC (b6)
+    # - **VII** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Relationship to Other Modes
+    #
+    # - Mixolydian with lowered 6th
+    # - Major scale with b6 and b7
+    # - 5th mode of melodic minor
+    #
+    # ## Musical Character
+    #
+    # The Mixolydian b6 scale:
+    #
+    # - Melancholic major quality
+    # - Used over dominant 7th with b13 (V7b13)
+    # - Creates a beautiful tension in the upper structure
+    # - Common in jazz and contemporary music
+    #
+    # ## Usage
+    #
+    #     g_mix_b6 = Scales[:et12][440.0][:mixolydian_b6][67]
+    #     g_mix_b6.tonic  # G (67)
+    #     g_mix_b6.VI     # Eb (75) - minor sixth
+    #
+    # @see ScaleKind Abstract base class
+    # @see MixolydianScaleKind Mixolydian mode (with major 6th)
+    # @see MelodicMinorScaleKind Parent melodic minor scale
+    class MixolydianB6ScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: 0,
+        character: [:hindu, :dominant, :melodic],
+        parent: { scale: :minor_melodic, degree: 5 }
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[I _1 tonic first],
+               pitch: 0 },
+             { functions: %i[II _2 supertonic second],
+               pitch: 2 },
+             { functions: %i[III _3 mediant third],
+               pitch: 4 },
+             { functions: %i[IV _4 subdominant fourth],
+               pitch: 5 },
+             { functions: %i[V _5 dominant fifth],
+               pitch: 7 },
+             { functions: %i[VI _6 submediant sixth],
+               pitch: 8 },
+             { functions: %i[VII _7 subtonic seventh],
+               pitch: 10 },
+             { functions: %i[VIII _8 eighth],
+               pitch: 12 },
+             { functions: %i[IX _9 ninth],
+               pitch: 12 + 2 },
+             { functions: %i[X _10 tenth],
+               pitch: 12 + 4 },
+             { functions: %i[XI _11 eleventh],
+               pitch: 12 + 5 },
+             { functions: %i[XII _12 twelfth],
+               pitch: 12 + 7 },
+             { functions: %i[XIII _13 thirteenth],
+               pitch: 12 + 8 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :mixolydian_b6
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register MixolydianB6ScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/minor_harmonic_scale_kind.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Harmonic minor scale kind.
+    #
+    # MinorHarmonicScaleKind defines the harmonic minor scale, a variation of
+    # the natural minor with a raised seventh degree. This creates a leading
+    # tone (major seventh) that resolves strongly to the tonic, giving the
+    # scale a more directed, dramatic character.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony (8th-13th):
+    #
+    # **Scale Degrees** (Roman numerals, lowercase for minor):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Major second (2 semitones)
+    # - **iii** (mediant): Minor third (3 semitones, relative major)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Perfect fifth (7 semitones)
+    # - **vi** (submediant): Minor sixth (8 semitones)
+    # - **vii** (leading): **Major seventh** (11 semitones) ← RAISED from natural minor
+    #
+    # **Extended degrees**: viii-xiii (compound intervals)
+    #
+    # ## Key Difference from Natural Minor
+    #
+    # The **vii** degree is raised from 10 semitones (minor seventh) to
+    # 11 semitones (major seventh), creating:
+    #
+    # - A **leading tone** that resolves strongly upward to the tonic
+    # - An **augmented second** interval between vi and vii (3 semitones)
+    # - A **dominant seventh chord** (v7) with strong resolution to i
+    #
+    # ## Musical Character
+    #
+    # The harmonic minor scale:
+    #
+    # - Maintains minor quality (minor third)
+    # - Provides strong dominant-to-tonic resolution
+    # - Creates exotic sound due to augmented second (vi-vii)
+    # - Common in classical, jazz, and Middle Eastern music
+    #
+    # ## Function Aliases
+    #
+    # Same as natural minor:
+    #
+    # - **Numeric**: _1, _2, _3, _4, _5, _6, _7
+    # - **Roman**: i, ii, iii, iv, v, vi, vii
+    # - **Function**: tonic, supertonic, mediant, subdominant, dominant,
+    #                 submediant, leading
+    # - **Special**: relative/relative_major for iii
+    #
+    # ## Usage
+    #
+    #     a_harmonic_minor = Scales[:et12][440.0][:minor_harmonic][69]
+    #     a_harmonic_minor.vii  # G# (80) - raised 7th, not G (79)
+    #     a_harmonic_minor.vi   # F (77)
+    #     # Augmented second: F to G# = 3 semitones
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor (with minor 7th)
+    # @see MajorScaleKind Major scale
+    class MinorHarmonicScaleKind < ScaleKind
+      @base_metadata = {
+        family: :diatonic,
+        brightness: -2,
+        character: [:dark, :exotic, :dramatic],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic],
+               pitch: 0 },
+             { functions: %i[ii _2 supertonic],
+               pitch: 2 },
+             { functions: %i[iii _3 mediant relative relative_major],
+               pitch: 3 },
+             { functions: %i[iv _4 subdominant],
+               pitch: 5 },
+             { functions: %i[v _5 dominant],
+               pitch: 7 },
+             { functions: %i[vi _6 submediant],
+               pitch: 8 },
+             { functions: %i[vii _7 leading],
+               pitch: 11 },
+             { functions: %i[viii _8],
+               pitch: 12 },
+             { functions: %i[ix _9],
+               pitch: 12 + 2 },
+             { functions: %i[x _10],
+               pitch: 12 + 3 },
+             { functions: %i[xi _11],
+               pitch: 12 + 5 },
+             { functions: %i[xii _12],
+               pitch: 12 + 7 },
+             { functions: %i[xiii _13],
+               pitch: 12 + 8 }].freeze
+
+        # Pitch structure.
+        # @return [Array<Hash>] pitch definitions with functions and offsets
+        def pitches
+          @@pitches
+        end
+
+        # Number of diatonic degrees.
+        # @return [Integer] 7
+        def grades
+          7
+        end
+
+        # Scale kind identifier.
+        # @return [Symbol] :minor_harmonic
+        def id
+          :minor_harmonic
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register MinorHarmonicScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/minor_natural_scale_kind.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Natural minor scale kind (Aeolian mode).
+    #
+    # MinorNaturalScaleKind defines the natural minor scale, parallel to the
+    # major scale but with a darker, melancholic character. It follows the
+    # pattern: W-H-W-W-H-W-W or intervals: M2-m2-M2-M2-m2-M2-M2 from the root.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony (8th-13th):
+    #
+    # **Scale Degrees** (Roman numerals, lowercase for minor):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Major second (2 semitones)
+    # - **iii** (mediant): Minor third (3 semitones, relative major)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Perfect fifth (7 semitones)
+    # - **vi** (submediant): Minor sixth (8 semitones)
+    # - **vii** (subtonic): Minor seventh (10 semitones, NOT leading tone)
+    #
+    # **Extended degrees**: viii-xiii (compound intervals)
+    #
+    # ## Differences from Major
+    #
+    # Compared to major scale (same tonic):
+    #
+    # - **iii**: Flatted third (minor third instead of major)
+    # - **vi**: Flatted sixth (minor sixth instead of major)
+    # - **vii**: Flatted seventh (minor seventh instead of major)
+    #
+    # ## Relative Major
+    #
+    # The **iii** degree is the root of the relative major scale (shares same
+    # notes but different tonic). For example:
+    #
+    # - A minor (natural) relative major: C major
+    # - C major relative minor: A minor
+    #
+    # ## Function Aliases
+    #
+    # Similar to major but with lowercase Roman numerals:
+    #
+    # - **Numeric**: _1, _2, _3, _4, _5, _6, _7
+    # - **Roman**: i, ii, iii, iv, v, vi, vii
+    # - **Function**: tonic, supertonic, mediant, subdominant, dominant, submediant
+    # - **Ordinal**: first, second, third, fourth, fifth, sixth, seventh
+    # - **Special**: relative/relative_major for iii
+    #
+    # ## Usage
+    #
+    #     a_minor = Scales[:et12][440.0][:minor][69]
+    #     a_minor.tonic        # A (69)
+    #     a_minor.dominant     # E (76)
+    #     a_minor.iii          # C (72) - relative major root
+    #     a_minor.relative_major.scale(:major)  # C major scale
+    #
+    # @see ScaleKind Abstract base class
+    # @see MajorScaleKind Major scale
+    # @see MinorHarmonicScaleKind Harmonic minor (with raised 7th)
+    class MinorNaturalScaleKind < ScaleKind
+      @base_metadata = {
+        family: :diatonic,
+        brightness: -3,
+        character: [:dark, :sad, :introspective],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[ii _2 supertonic second],
+               pitch: 2 },
+             { functions: %i[iii _3 mediant relative relative_major third],
+               pitch: 3 },
+             { functions: %i[iv _4 subdominant fourth],
+               pitch: 5 },
+             { functions: %i[v _5 dominant fifth],
+               pitch: 7 },
+             { functions: %i[vi _6 submediant sixth],
+               pitch: 8 },
+             { functions: %i[vii _7 seventh],
+               pitch: 10 },
+             { functions: %i[viii _8 eighth],
+               pitch: 12 },
+             { functions: %i[ix _9 ninth],
+               pitch: 12 + 2 },
+             { functions: %i[x _10 tenth],
+               pitch: 12 + 3 },
+             { functions: %i[xi _11 eleventh],
+               pitch: 12 + 5 },
+             { functions: %i[xii _12 twelfth],
+               pitch: 12 + 7 },
+             { functions: %i[xiii _13 thirteenth],
+               pitch: 12 + 8 }].freeze
+
+        # Pitch structure.
+        # @return [Array<Hash>] pitch definitions with functions and offsets
+        def pitches
+          @@pitches
+        end
+
+        # Number of diatonic degrees.
+        # @return [Integer] 7
+        def grades
+          7
+        end
+
+        # Scale kind identifier.
+        # @return [Symbol] :minor
+        def id
+          :minor
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register MinorNaturalScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/modes/dorian_scale_kind.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Dorian mode (second mode of major scale).
+    #
+    # DorianScaleKind defines the Dorian mode, a minor mode with a characteristic
+    # raised sixth degree. It's built on the second degree of the major scale
+    # and has a brighter, more hopeful quality than natural minor.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony (8th-13th):
+    #
+    # **Scale Degrees** (Roman numerals, lowercase for minor):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Major second (2 semitones)
+    # - **iii** (mediant): Minor third (3 semitones)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Perfect fifth (7 semitones)
+    # - **vi** (submediant): **Major sixth** (9 semitones) ← CHARACTERISTIC
+    # - **vii** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Key Difference from Natural Minor
+    #
+    # The **vi** degree is raised from 8 semitones (minor sixth) to
+    # 9 semitones (major sixth), creating:
+    #
+    # - A brighter, less melancholic minor quality
+    # - The characteristic "Dorian color"
+    # - Common in jazz, folk, and rock music
+    #
+    # ## Musical Character
+    #
+    # The Dorian mode:
+    #
+    # - Maintains minor quality (minor third)
+    # - Has a raised 6th that adds brightness
+    # - Common in jazz improvisation (ii-V-I progressions)
+    # - Used extensively in modal jazz and Celtic music
+    #
+    # ## Usage
+    #
+    #     d_dorian = Scales[:et12][440.0][:dorian][62]
+    #     d_dorian.tonic   # D (62)
+    #     d_dorian.vi      # B (71) - major sixth (characteristic)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor (with minor 6th)
+    # @see PhrygianScaleKind Phrygian mode
+    class DorianScaleKind < ScaleKind
+      @base_metadata = {
+        family: :greek_modes,
+        brightness: -1,
+        character: [:minor, :jazzy, :sophisticated],
+        parent: { scale: :major, degree: 2 }
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[ii _2 supertonic second],
+               pitch: 2 },
+             { functions: %i[iii _3 mediant third],
+               pitch: 3 },
+             { functions: %i[iv _4 subdominant fourth],
+               pitch: 5 },
+             { functions: %i[v _5 dominant fifth],
+               pitch: 7 },
+             { functions: %i[vi _6 submediant sixth],
+               pitch: 9 },
+             { functions: %i[vii _7 subtonic seventh],
+               pitch: 10 },
+             { functions: %i[viii _8 eighth],
+               pitch: 12 },
+             { functions: %i[ix _9 ninth],
+               pitch: 12 + 2 },
+             { functions: %i[x _10 tenth],
+               pitch: 12 + 3 },
+             { functions: %i[xi _11 eleventh],
+               pitch: 12 + 5 },
+             { functions: %i[xii _12 twelfth],
+               pitch: 12 + 7 },
+             { functions: %i[xiii _13 thirteenth],
+               pitch: 12 + 9 }].freeze
+
+        # Pitch structure.
+        # @return [Array<Hash>] pitch definitions with functions and offsets
+        def pitches
+          @@pitches
+        end
+
+        # Number of diatonic degrees.
+        # @return [Integer] 7
+        def grades
+          7
+        end
+
+        # Scale kind identifier.
+        # @return [Symbol] :dorian
+        def id
+          :dorian
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register DorianScaleKind
+    end
+  end
+end