musa-dsl 0.40.0 → 0.41.0

data/lib/musa-dsl/music/scale_kinds/ethnic/neapolitan_major_scale_kind.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Neapolitan major scale kind.
+    #
+    # NeapolitanMajorScaleKind defines the Neapolitan major scale, a
+    # major scale with a lowered second degree, combining the Neapolitan
+    # coloring with a brighter major upper structure.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (uppercase for major quality):
+    #
+    # - **I** (tonic): Root (0 semitones)
+    # - **II** (supertonic): Minor second (1 semitone) ← NEAPOLITAN (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)
+    # - **VII** (leading): Major seventh (11 semitones)
+    #
+    # ## Relationship to Melodic Minor
+    #
+    # Neapolitan major = Melodic minor with lowered 2nd
+    #
+    # ## Musical Character
+    #
+    # The Neapolitan major scale:
+    #
+    # - Exotic but brighter than Neapolitan minor
+    # - Combines Phrygian darkness with major brightness
+    # - Used in classical and contemporary music
+    # - Unique harmonic possibilities
+    #
+    # ## Usage
+    #
+    #     c_neap_maj = Scales[:et12][440.0][:neapolitan_major][60]
+    #     c_neap_maj.tonic  # C (60)
+    #     c_neap_maj.II     # Db (61) - minor second (Neapolitan)
+    #     c_neap_maj.VI     # A (69) - major sixth
+    #     c_neap_maj.VII    # B (71) - leading tone
+    #
+    # @see ScaleKind Abstract base class
+    # @see MelodicMinorScaleKind Melodic minor (with major 2nd)
+    # @see NeapolitanMinorScaleKind Neapolitan minor
+    class NeapolitanMajorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :ethnic,
+        brightness: -1,
+        character: [:neapolitan, :classical, :bright_dark],
+        parent: nil
+      }.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 leading seventh],
+               pitch: 11 },
+             { 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
+          :neapolitan_major
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register NeapolitanMajorScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/ethnic/neapolitan_minor_scale_kind.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Neapolitan minor scale kind.
+    #
+    # NeapolitanMinorScaleKind defines the Neapolitan minor scale, a
+    # harmonic minor scale with a lowered second degree, named after
+    # the Neapolitan school of opera in the 18th century.
+    #
+    # ## 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) ← NEAPOLITAN (b2)
+    # - **iii** (mediant): Minor third (3 semitones)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Perfect fifth (7 semitones)
+    # - **vi** (submediant): Minor sixth (8 semitones)
+    # - **vii** (leading): Major seventh (11 semitones)
+    #
+    # ## Relationship to Harmonic Minor
+    #
+    # Neapolitan minor = Harmonic minor with lowered 2nd
+    #
+    # ## Musical Character
+    #
+    # The Neapolitan minor scale:
+    #
+    # - Dark, dramatic, operatic
+    # - The Neapolitan sixth chord (bII) is characteristic
+    # - Used in classical and film music
+    # - Strong resolution tendency to tonic
+    #
+    # ## Usage
+    #
+    #     a_neap_min = Scales[:et12][440.0][:neapolitan_minor][69]
+    #     a_neap_min.tonic  # A (69)
+    #     a_neap_min.ii     # Bb (70) - minor second (Neapolitan)
+    #     a_neap_min.vii    # G# (80) - leading tone
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorHarmonicScaleKind Harmonic minor (with major 2nd)
+    # @see NeapolitanMajorScaleKind Neapolitan major
+    class NeapolitanMinorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :ethnic,
+        brightness: -2,
+        character: [:neapolitan, :classical, :dark],
+        parent: nil
+      }.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: 8 },
+             { functions: %i[vii _7 leading seventh],
+               pitch: 11 },
+             { 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 + 8 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          7
+        end
+
+        def id
+          :neapolitan_minor
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register NeapolitanMinorScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/ethnic/phrygian_dominant_scale_kind.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Phrygian dominant scale kind (Spanish Phrygian).
+    #
+    # PhrygianDominantScaleKind defines the Phrygian dominant scale (also called
+    # Spanish Phrygian, Freygish, or Spanish Gypsy scale), the fifth mode of
+    # harmonic minor. It's the quintessential flamenco scale.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony:
+    #
+    # **Scale Degrees** (uppercase for major 3rd quality):
+    #
+    # - **I** (tonic): Root (0 semitones)
+    # - **II** (supertonic): Minor second (1 semitone) ← PHRYGIAN
+    # - **III** (mediant): Major third (4 semitones) ← DOMINANT
+    # - **IV** (subdominant): Perfect fourth (5 semitones)
+    # - **V** (dominant): Perfect fifth (7 semitones)
+    # - **VI** (submediant): Minor sixth (8 semitones)
+    # - **VII** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Key Features
+    #
+    # - Phrygian's minor second (exotic)
+    # - Dominant's major third (strong harmonic character)
+    # - Creates the characteristic flamenco sound
+    #
+    # ## Musical Character
+    #
+    # The Phrygian dominant scale:
+    #
+    # - The sound of flamenco and Spanish guitar
+    # - Works over dominant chords resolving to minor
+    # - Common in klezmer and Middle Eastern music too
+    # - Intensely expressive and dramatic
+    #
+    # ## Usage
+    #
+    #     e_phry_dom = Scales[:et12][440.0][:phrygian_dominant][64]
+    #     e_phry_dom.tonic  # E (64)
+    #     e_phry_dom.II     # F (65) - minor second (Phrygian)
+    #     e_phry_dom.III    # G# (68) - major third (Dominant)
+    #
+    # @see ScaleKind Abstract base class
+    # @see PhrygianScaleKind Phrygian mode (with minor 3rd)
+    # @see MinorHarmonicScaleKind Parent harmonic minor scale
+    class PhrygianDominantScaleKind < ScaleKind
+      @base_metadata = {
+        family: :ethnic,
+        brightness: -1,
+        character: [:spanish, :flamenco, :jewish],
+        parent: { scale: :minor_harmonic, degree: 5 }
+      }.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: 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 + 1 },
+             { 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
+          :phrygian_dominant
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register PhrygianDominantScaleKind
+    end
+  end
+end

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