musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/music/scale_kinds/harmonic_major/harmonic_major_scale_kind.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Harmonic major scale kind.
+    #
+    # HarmonicMajorScaleKind defines the harmonic major scale, a major scale
+    # with a lowered sixth degree. It creates an augmented second between
+    # the sixth and seventh degrees, similar to harmonic minor but in a
+    # major context.
+    #
+    # ## 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** (leading): Major seventh (11 semitones)
+    #
+    # ## Key Feature
+    #
+    # The augmented second between b6 and natural 7 creates an exotic
+    # interval similar to harmonic minor, but in a major key context.
+    #
+    # ## Musical Character
+    #
+    # The harmonic major scale:
+    #
+    # - Major quality with exotic coloring
+    # - Augmented second (b6 to 7) adds drama
+    # - Used in classical, jazz, and film music
+    # - Creates unique diminished chord on bVI
+    #
+    # ## Usage
+    #
+    #     c_harm_maj = Scales[:et12][440.0][:major_harmonic][60]
+    #     c_harm_maj.tonic    # C (60)
+    #     c_harm_maj.VI       # Ab (68) - minor sixth
+    #     c_harm_maj.leading  # B (71) - major seventh
+    #     # Ab to B = augmented second (3 semitones)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MajorScaleKind Major scale (with major 6th)
+    # @see MinorHarmonicScaleKind Harmonic minor (similar augmented second)
+    class HarmonicMajorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :diatonic,
+        brightness: -1,
+        character: [:major_minor, :dramatic, :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: 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 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 + 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
+          :major_harmonic
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register HarmonicMajorScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Major scale kind (Ionian mode).
+    #
+    # MajorScaleKind defines the major scale, the fundamental scale of Western
+    # tonal music. It follows the pattern: W-W-H-W-W-W-H (whole-half steps)
+    # 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, uppercase for major):
+    #
+    # - **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): Major sixth (9 semitones, relative minor)
+    # - **VII** (leading): Major seventh (11 semitones)
+    #
+    # **Extended degrees** (for extended harmony):
+    #
+    # - VIII-XIII: Compound intervals (8th, 9th, 10th, 11th, 12th, 13th)
+    #
+    # ## Function Aliases
+    #
+    # Each degree has multiple function names:
+    #
+    # - **Numeric**: _1, _2, _3, _4, _5, _6, _7 (ordinal)
+    # - **Roman**: I, II, III, IV, V, VI, VII (harmonic analysis)
+    # - **Function**: tonic, supertonic, mediant, subdominant, dominant,
+    #                 submediant, leading
+    # - **Ordinal**: first, second, third, fourth, fifth, sixth, seventh
+    # - **Special**: relative/relative_minor for VI (relative minor root)
+    #
+    # ## Usage
+    #
+    #     c_major = Scales[:et12][440.0][:major][60]
+    #     c_major.tonic      # C (60)
+    #     c_major.dominant   # G (67)
+    #     c_major.VI         # A (69) - relative minor root
+    #     c_major.relative_minor.scale(:minor)  # A minor scale
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor scale
+    # @see ChromaticScaleKind Chromatic scale
+    class MajorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :diatonic,
+        brightness: 0,
+        character: [:bright, :stable, :resolved],
+        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: 4 },
+             { functions: %i[IV _4 subdominant fourth],
+               pitch: 5 },
+             { functions: %i[V _5 dominant fifth],
+               pitch: 7 },
+             { functions: %i[VI _6 submediant relative relative_minor 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 + 4 },
+             { 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] :major
+        def id
+          :major
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register MajorScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Altered scale kind (seventh mode of melodic minor).
+    #
+    # AlteredScaleKind defines the Altered scale (also called Super Locrian,
+    # Diminished Whole Tone, or Altered Dominant), the seventh mode of the
+    # melodic minor scale. It's the quintessential scale for altered dominant
+    # chords in jazz.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (lowercase for diminished quality):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Minor second (1 semitone) ← b9
+    # - **iii** (mediant): Minor third (3 semitones) ← #9 (enharmonic)
+    # - **iv** (subdominant): Major third (4 semitones) ← b11 (3rd of chord)
+    # - **v** (dominant): Diminished fifth (6 semitones) ← b5/#11
+    # - **vi** (submediant): Minor sixth (8 semitones) ← #5/b13
+    # - **vii** (subtonic): Minor seventh (10 semitones) ← b7
+    #
+    # ## All Alterations Present
+    #
+    # Contains all possible alterations of a dominant chord:
+    # - b9, #9 (altered 9ths)
+    # - #11/b5 (altered 11th/5th)
+    # - b13/#5 (altered 13th/5th)
+    #
+    # ## Musical Character
+    #
+    # The Altered scale:
+    #
+    # - Maximum tension for dominant chords
+    # - Used over 7alt, 7#9, 7b9#11, etc.
+    # - Essential in bebop and modern jazz
+    # - Creates strong resolution to tonic
+    #
+    # ## Usage
+    #
+    #     g_alt = Scales[:et12][440.0][:altered][67]
+    #     g_alt.tonic  # G (67)
+    #     g_alt.ii     # Ab (68) - b9
+    #     g_alt.iii    # Bb (70) - #9
+    #     g_alt.v      # Db (73) - b5
+    #
+    # @see ScaleKind Abstract base class
+    # @see MelodicMinorScaleKind Parent melodic minor scale
+    # @see DiminishedWHScaleKind Another altered dominant scale option
+    class AlteredScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: -3,
+        character: [:altered_dominant, :jazz, :tension],
+        parent: { scale: :minor_melodic, degree: 7 }
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[ii _2 supertonic second],
+               pitch: 1 },
+             { functions: %i[iii _3 mediant third],
+               pitch: 3 },
+             { functions: %i[iv _4 subdominant fourth],
+               pitch: 4 },
+             { functions: %i[v _5 dominant fifth],
+               pitch: 6 },
+             { 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 + 1 },
+             { functions: %i[x _10 tenth],
+               pitch: 12 + 3 },
+             { functions: %i[xi _11 eleventh],
+               pitch: 12 + 4 },
+             { functions: %i[xii _12 twelfth],
+               pitch: 12 + 6 },
+             { functions: %i[xiii _13 thirteenth],
+               pitch: 12 + 8 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :altered
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register AlteredScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Dorian b2 scale kind (second mode of melodic minor).
+    #
+    # DorianB2ScaleKind defines the Dorian b2 scale (also called Phrygian #6
+    # or Javanese scale), the second mode of the melodic minor scale.
+    # It combines the Phrygian's lowered second with the Dorian's raised sixth.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (lowercase for minor quality):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Minor second (1 semitone) ← CHARACTERISTIC (b2)
+    # - **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 (#6)
+    # - **vii** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Relationship to Other Modes
+    #
+    # - Dorian with lowered 2nd
+    # - Phrygian with raised 6th
+    # - 2nd mode of melodic minor
+    #
+    # ## Musical Character
+    #
+    # The Dorian b2 scale:
+    #
+    # - Exotic, Eastern quality
+    # - Minor with both Phrygian darkness and Dorian brightness
+    # - Used over sus4(b9) chords in jazz
+    # - Common in contemporary jazz and fusion
+    #
+    # ## Usage
+    #
+    #     d_dor_b2 = Scales[:et12][440.0][:dorian_b2][62]
+    #     d_dor_b2.tonic  # D (62)
+    #     d_dor_b2.ii     # Eb (63) - minor second
+    #     d_dor_b2.vi     # B (71) - major sixth
+    #
+    # @see ScaleKind Abstract base class
+    # @see DorianScaleKind Dorian mode
+    # @see PhrygianScaleKind Phrygian mode
+    # @see MelodicMinorScaleKind Parent melodic minor scale
+    class DorianB2ScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: -2,
+        character: [:exotic, :phrygian_dorian],
+        parent: { scale: :minor_melodic, degree: 2 }
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[ii _2 supertonic second],
+               pitch: 1 },
+             { 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 + 1 },
+             { 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
+          :dorian_b2
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register DorianB2ScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Locrian #2 scale kind (sixth mode of melodic minor).
+    #
+    # LocrianSharp2ScaleKind defines the Locrian #2 scale (also called
+    # Aeolian b5 or Half-Diminished scale), the sixth mode of the
+    # melodic minor scale. It's the primary scale for half-diminished chords.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (lowercase for diminished quality):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): Major second (2 semitones) ← #2 vs Locrian
+    # - **iii** (mediant): Minor third (3 semitones)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Diminished fifth (6 semitones) ← DIMINISHED
+    # - **vi** (submediant): Minor sixth (8 semitones)
+    # - **vii** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Relationship to Other Modes
+    #
+    # - Locrian with raised 2nd (natural 9)
+    # - Aeolian with lowered 5th
+    # - 6th mode of melodic minor
+    #
+    # ## Musical Character
+    #
+    # The Locrian #2 scale:
+    #
+    # - Primary scale for m7b5 (half-diminished) chords
+    # - More usable than pure Locrian (has natural 9)
+    # - Essential in jazz ii-V-I in minor keys
+    # - Dark but functional
+    #
+    # ## Usage
+    #
+    #     a_loc2 = Scales[:et12][440.0][:locrian_sharp2][69]
+    #     a_loc2.tonic  # A (69)
+    #     a_loc2.ii     # B (71) - major second (raised)
+    #     a_loc2.v      # Eb (75) - diminished fifth
+    #
+    # @see ScaleKind Abstract base class
+    # @see LocrianScaleKind Locrian mode (with minor 2nd)
+    # @see MelodicMinorScaleKind Parent melodic minor scale
+    class LocrianSharp2ScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: -2,
+        character: [:half_diminished, :jazz],
+        parent: { scale: :minor_melodic, degree: 6 }
+      }.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: 6 },
+             { 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 + 3 },
+             { functions: %i[xi _11 eleventh],
+               pitch: 12 + 5 },
+             { functions: %i[xii _12 twelfth],
+               pitch: 12 + 6 },
+             { functions: %i[xiii _13 thirteenth],
+               pitch: 12 + 8 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :locrian_sharp2
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register LocrianSharp2ScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Lydian augmented scale kind (third mode of melodic minor).
+    #
+    # LydianAugmentedScaleKind defines the Lydian augmented scale, the third
+    # mode of the melodic minor scale. It combines the Lydian's raised fourth
+    # with an augmented (raised) fifth.
+    #
+    # ## 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
+    # - **V** (dominant): Augmented fifth (8 semitones) ← AUGMENTED
+    # - **VI** (submediant): Major sixth (9 semitones)
+    # - **VII** (leading): Major seventh (11 semitones)
+    #
+    # ## Relationship to Other Modes
+    #
+    # - Lydian with augmented 5th
+    # - 3rd mode of melodic minor
+    # - Contains both #4 and #5
+    #
+    # ## Musical Character
+    #
+    # The Lydian augmented scale:
+    #
+    # - Extremely bright and ethereal
+    # - Used over maj7#5 and maj7#11 chords
+    # - Dreamy, floating quality
+    # - Common in contemporary jazz and film music
+    #
+    # ## Usage
+    #
+    #     eb_lyd_aug = Scales[:et12][440.0][:lydian_augmented][63]
+    #     eb_lyd_aug.tonic  # Eb (63)
+    #     eb_lyd_aug.IV     # A (69) - augmented fourth
+    #     eb_lyd_aug.V      # B (71) - augmented fifth
+    #
+    # @see ScaleKind Abstract base class
+    # @see LydianScaleKind Lydian mode
+    # @see MelodicMinorScaleKind Parent melodic minor scale
+    class LydianAugmentedScaleKind < ScaleKind
+      @base_metadata = {
+        family: :melodic_minor_modes,
+        brightness: 3,
+        character: [:very_bright, :augmented, :ethereal],
+        parent: { scale: :minor_melodic, degree: 3 }
+      }.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: 8 },
+             { 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 + 4 },
+             { functions: %i[XI _11 eleventh],
+               pitch: 12 + 6 },
+             { functions: %i[XII _12 twelfth],
+               pitch: 12 + 8 },
+             { functions: %i[XIII _13 thirteenth],
+               pitch: 12 + 9 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :lydian_augmented
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register LydianAugmentedScaleKind
+    end
+  end
+end