musa-dsl 0.30.2 → 0.41.0

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Locrian mode (seventh mode of major scale).
+    #
+    # LocrianScaleKind defines the Locrian mode, a diminished mode with a
+    # characteristic lowered second and fifth degrees. It's built on the
+    # seventh degree of the major scale and has an unstable, dissonant quality.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony (8th-13th):
+    #
+    # **Scale Degrees** (Roman numerals, lowercase for diminished):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): **Minor second** (1 semitone) ← CHARACTERISTIC
+    # - **iii** (mediant): Minor third (3 semitones)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): **Diminished fifth** (6 semitones) ← CHARACTERISTIC
+    # - **vi** (submediant): Minor sixth (8 semitones)
+    # - **vii** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Key Differences from Natural Minor
+    #
+    # Two degrees are altered:
+    # - **ii** lowered from 2 to 1 semitone (minor second)
+    # - **v** lowered from 7 to 6 semitones (diminished fifth/tritone)
+    #
+    # This creates:
+    # - A highly unstable, dissonant quality
+    # - No stable perfect fifth above the tonic
+    # - Rarely used as a tonal center
+    #
+    # ## Musical Character
+    #
+    # The Locrian mode:
+    #
+    # - Has diminished quality (minor third + diminished fifth)
+    # - The most unstable of the seven modes
+    # - Used sparingly, often for tension or dissonance
+    # - Common over half-diminished (m7b5) chords in jazz
+    #
+    # ## Usage
+    #
+    #     b_locrian = Scales[:et12][440.0][:locrian][71]
+    #     b_locrian.tonic  # B (71)
+    #     b_locrian.ii     # C (72) - minor second (characteristic)
+    #     b_locrian.v      # F (77) - diminished fifth (characteristic)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor
+    # @see PhrygianScaleKind Phrygian mode (also has minor 2nd)
+    class LocrianScaleKind < ScaleKind
+      @base_metadata = {
+        family: :greek_modes,
+        brightness: -3,
+        character: [:unstable, :diminished, :tense],
+        parent: { scale: :major, 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: 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 + 1 },
+             { 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
+
+        # 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] :locrian
+        def id
+          :locrian
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register LocrianScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Lydian mode (fourth mode of major scale).
+    #
+    # LydianScaleKind defines the Lydian mode, a major mode with a characteristic
+    # raised fourth degree. It's built on the fourth degree of the major scale
+    # and has a bright, dreamy, floating quality.
+    #
+    # ## 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): **Augmented fourth** (6 semitones) ← CHARACTERISTIC
+    # - **V** (dominant): Perfect fifth (7 semitones)
+    # - **VI** (submediant): Major sixth (9 semitones)
+    # - **VII** (leading): Major seventh (11 semitones)
+    #
+    # ## Key Difference from Major
+    #
+    # The **IV** degree is raised from 5 semitones (perfect fourth) to
+    # 6 semitones (augmented fourth/tritone), creating:
+    #
+    # - A bright, ethereal quality
+    # - The characteristic "Lydian color"
+    # - A sense of floating or suspension
+    #
+    # ## Musical Character
+    #
+    # The Lydian mode:
+    #
+    # - Maintains major quality (major third)
+    # - Has a raised 4th that adds brightness and tension
+    # - Common in film scores and jazz (especially over maj7#11 chords)
+    # - Creates a dreamy, otherworldly atmosphere
+    #
+    # ## Usage
+    #
+    #     f_lydian = Scales[:et12][440.0][:lydian][65]
+    #     f_lydian.tonic  # F (65)
+    #     f_lydian.IV     # B (71) - augmented fourth (characteristic)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MajorScaleKind Major scale (with perfect 4th)
+    # @see MixolydianScaleKind Mixolydian mode
+    class LydianScaleKind < ScaleKind
+      @base_metadata = {
+        family: :greek_modes,
+        brightness: 2,
+        character: [:bright, :dreamy, :floating],
+        parent: { scale: :major, 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 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 + 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] :lydian
+        def id
+          :lydian
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register LydianScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Mixolydian mode (fifth mode of major scale).
+    #
+    # MixolydianScaleKind defines the Mixolydian mode, a major mode with a
+    # characteristic lowered seventh degree. It's built on the fifth degree
+    # of the major scale and has a bluesy, rock quality.
+    #
+    # ## 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)
+    # - **VII** (subtonic): **Minor seventh** (10 semitones) ← CHARACTERISTIC
+    #
+    # ## Key Difference from Major
+    #
+    # The **VII** degree is lowered from 11 semitones (major seventh) to
+    # 10 semitones (minor seventh), creating:
+    #
+    # - A bluesy, rock quality
+    # - The characteristic "Mixolydian color"
+    # - Natural dominant seventh sound
+    #
+    # ## Musical Character
+    #
+    # The Mixolydian mode:
+    #
+    # - Maintains major quality (major third)
+    # - Has a lowered 7th that removes the leading tone tension
+    # - Common in rock, blues, funk, and folk music
+    # - Natural mode for dominant seventh chords
+    #
+    # ## Usage
+    #
+    #     g_mixolydian = Scales[:et12][440.0][:mixolydian][67]
+    #     g_mixolydian.tonic  # G (67)
+    #     g_mixolydian.VII    # F (77) - minor seventh (characteristic)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MajorScaleKind Major scale (with major 7th)
+    # @see LydianScaleKind Lydian mode
+    class MixolydianScaleKind < ScaleKind
+      @base_metadata = {
+        family: :greek_modes,
+        brightness: 1,
+        character: [:bluesy, :rock, :dominant],
+        parent: { scale: :major, 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: 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 + 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] :mixolydian
+        def id
+          :mixolydian
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register MixolydianScaleKind
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Phrygian mode (third mode of major scale).
+    #
+    # PhrygianScaleKind defines the Phrygian mode, a minor mode with a characteristic
+    # lowered second degree. It's built on the third degree of the major scale
+    # and has a dark, exotic, Spanish/Middle Eastern quality.
+    #
+    # ## Pitch Structure
+    #
+    # 7 diatonic degrees plus extended harmony (8th-13th):
+    #
+    # **Scale Degrees** (Roman numerals, lowercase for minor):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **ii** (supertonic): **Minor second** (1 semitone) ← CHARACTERISTIC
+    # - **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** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Key Difference from Natural Minor
+    #
+    # The **ii** degree is lowered from 2 semitones (major second) to
+    # 1 semitone (minor second), creating:
+    #
+    # - A dark, exotic quality
+    # - The characteristic "Phrygian color"
+    # - Strong association with Spanish/Flamenco music
+    #
+    # ## Musical Character
+    #
+    # The Phrygian mode:
+    #
+    # - Maintains minor quality (minor third)
+    # - Has a lowered 2nd that creates tension
+    # - Common in flamenco, metal, and Middle Eastern music
+    # - The half-step from ii to i creates strong resolution
+    #
+    # ## Usage
+    #
+    #     e_phrygian = Scales[:et12][440.0][:phrygian][64]
+    #     e_phrygian.tonic  # E (64)
+    #     e_phrygian.ii     # F (65) - minor second (characteristic)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor (with major 2nd)
+    # @see DorianScaleKind Dorian mode
+    class PhrygianScaleKind < ScaleKind
+      @base_metadata = {
+        family: :greek_modes,
+        brightness: -2,
+        character: [:dark, :spanish, :exotic],
+        parent: { scale: :major, degree: 3 }
+      }.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 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 + 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] :phrygian
+        def id
+          :phrygian
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register PhrygianScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/pentatonic/pentatonic_major_scale_kind.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Major pentatonic scale kind.
+    #
+    # PentatonicMajorScaleKind defines the major pentatonic scale, a five-note
+    # scale derived from the major scale by omitting the 4th and 7th degrees.
+    # It has a bright, open sound and is extremely common in folk, rock, and blues.
+    #
+    # ## Pitch Structure
+    #
+    # 5 diatonic degrees plus extended (6th-10th):
+    #
+    # **Scale Degrees** (Roman numerals, uppercase for major):
+    #
+    # - **I** (tonic): Root (0 semitones)
+    # - **II** (supertonic): Major second (2 semitones)
+    # - **III** (mediant): Major third (4 semitones)
+    # - **V** (dominant): Perfect fifth (7 semitones)
+    # - **VI** (submediant): Major sixth (9 semitones)
+    #
+    # ## Relationship to Major Scale
+    #
+    # Major pentatonic = Major scale minus 4th and 7th degrees.
+    # This removes all semitone intervals, creating a scale with no dissonance.
+    #
+    # ## Musical Character
+    #
+    # The major pentatonic:
+    #
+    # - Has a bright, happy, open quality
+    # - No semitones = no tension or dissonance
+    # - Universal across cultures (found in music worldwide)
+    # - Common in folk, country, rock, pop, and blues
+    #
+    # ## Usage
+    #
+    #     c_pent = Scales[:et12][440.0][:pentatonic_major][60]
+    #     c_pent.tonic     # C (60)
+    #     c_pent.dominant  # G (67)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MajorScaleKind Major scale
+    # @see PentatonicMinorScaleKind Minor pentatonic
+    class PentatonicMajorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :pentatonic,
+        brightness: 1,
+        character: [:bright, :simple, :folk],
+        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[V _4 dominant fourth],
+               pitch: 7 },
+             { functions: %i[VI _5 submediant fifth],
+               pitch: 9 },
+             { functions: %i[VIII _6 sixth],
+               pitch: 12 },
+             { functions: %i[IX _7 seventh],
+               pitch: 12 + 2 },
+             { functions: %i[X _8 eighth],
+               pitch: 12 + 4 },
+             { functions: %i[XII _9 ninth],
+               pitch: 12 + 7 },
+             { functions: %i[XIII _10 tenth],
+               pitch: 12 + 9 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          5
+        end
+
+        def id
+          :pentatonic_major
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register PentatonicMajorScaleKind
+    end
+  end
+end

data/lib/musa-dsl/music/scale_kinds/pentatonic/pentatonic_minor_scale_kind.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Musa
+  module Scales
+    # Minor pentatonic scale kind.
+    #
+    # PentatonicMinorScaleKind defines the minor pentatonic scale, a five-note
+    # scale derived from the natural minor scale by omitting the 2nd and 6th degrees.
+    # It's the foundation of blues and rock improvisation.
+    #
+    # ## Pitch Structure
+    #
+    # 5 diatonic degrees plus extended (6th-10th):
+    #
+    # **Scale Degrees** (Roman numerals, lowercase for minor):
+    #
+    # - **i** (tonic): Root (0 semitones)
+    # - **iii** (mediant): Minor third (3 semitones)
+    # - **iv** (subdominant): Perfect fourth (5 semitones)
+    # - **v** (dominant): Perfect fifth (7 semitones)
+    # - **vii** (subtonic): Minor seventh (10 semitones)
+    #
+    # ## Relationship to Natural Minor
+    #
+    # Minor pentatonic = Natural minor minus 2nd and 6th degrees.
+    # This removes all semitone intervals, creating a scale with no dissonance.
+    #
+    # ## Relative Major Pentatonic
+    #
+    # A minor pentatonic shares the same notes as C major pentatonic.
+    # They are relative scales.
+    #
+    # ## Musical Character
+    #
+    # The minor pentatonic:
+    #
+    # - Has a bluesy, soulful quality
+    # - Foundation of blues and rock guitar solos
+    # - Works over both minor and dominant 7th chords
+    # - Easy to improvise with (no "wrong" notes)
+    #
+    # ## Usage
+    #
+    #     a_pent = Scales[:et12][440.0][:pentatonic_minor][69]
+    #     a_pent.tonic     # A (69)
+    #     a_pent.dominant  # E (76)
+    #
+    # @see ScaleKind Abstract base class
+    # @see MinorNaturalScaleKind Natural minor scale
+    # @see PentatonicMajorScaleKind Major pentatonic
+    # @see BluesScaleKind Blues scale (pentatonic + blue note)
+    class PentatonicMinorScaleKind < ScaleKind
+      @base_metadata = {
+        family: :pentatonic,
+        brightness: -1,
+        character: [:bluesy, :simple, :rock],
+        parent: nil
+      }.freeze
+
+      class << self
+        @@pitches =
+            [{ functions: %i[i _1 tonic first],
+               pitch: 0 },
+             { functions: %i[iii _2 mediant second],
+               pitch: 3 },
+             { functions: %i[iv _3 subdominant third],
+               pitch: 5 },
+             { functions: %i[v _4 dominant fourth],
+               pitch: 7 },
+             { functions: %i[vii _5 subtonic fifth],
+               pitch: 10 },
+             { functions: %i[viii _6 sixth],
+               pitch: 12 },
+             { functions: %i[x _7 seventh],
+               pitch: 12 + 3 },
+             { functions: %i[xi _8 eighth],
+               pitch: 12 + 5 },
+             { functions: %i[xii _9 ninth],
+               pitch: 12 + 7 },
+             { functions: %i[xiv _10 tenth],
+               pitch: 12 + 10 }].freeze
+
+        def pitches
+          @@pitches
+        end
+
+        def grades
+          5
+        end
+
+        def id
+          :pentatonic_minor
+        end
+      end
+
+      EquallyTempered12ToneScaleSystem.register PentatonicMinorScaleKind
+    end
+  end
+end