musa-dsl 0.41.0 → 0.42.0

data/lib/musa-dsl/music/chords.rb

@@ -47,13 +47,15 @@ module Musa
     #
     # ### Move - Relocate specific chord tones to different octaves:
     #
-    #     chord.move(root: -1, seventh: 1)
+    #     chord.with_move(root: -1, seventh: 1)
     #     # Root down one octave, seventh up one octave
+    #     chord.move  # => { root: -1, seventh: 1 } (current settings)
     #
     # ### Duplicate - Add copies of chord tones in other octaves:
     #
-    #     chord.duplicate(root: -2, third: [-1, 1])
+    #     chord.with_duplicate(root: -2, third: [-1, 1])
     #     # Add root 2 octaves down, third 1 octave down and 1 up
+    #     chord.duplicate  # => { root: -2, third: [-1, 1] } (current settings)
     #
     # ### Octave - Transpose entire chord:
     #
@@ -90,8 +92,8 @@ module Musa
     # @example Voicing with move and duplicate
     #   scale = Scales::Scales.default_system.default_tuning.major[60]
     #   chord = scale.dominant.chord(:seventh)
-    #     .move(root: -1, third: -1)
-    #     .duplicate(fifth: [0, 1])
+    #     .with_move(root: -1, third: -1)
+    #     .with_duplicate(fifth: [0, 1])
     #
     # @example Feature navigation
     #   scale = Scales::Scales.default_system.default_tuning.major[60]
@@ -194,9 +196,9 @@ module Musa
         # Maps each chord position (root, third, fifth, etc.) to its corresponding
         # note in the scale or chromatic scale.
         #
-        # @param root [NoteInScale] chord root note
+        # @param root [Scales::NoteInScale] chord root note
         # @param chord_definition [ChordDefinition] chord structure
-        # @param scale [Scale] scale context
+        # @param scale [Scales::Scale] scale context
         # @return [Hash{Symbol => Array<NoteInScale>}] position to notes mapping
         #
         # @api private
@@ -214,7 +216,7 @@ module Musa
         #
         # @param root_pitch [Integer] MIDI pitch of chord root
         # @param features [Hash] desired chord features (quality:, size:, etc.)
-        # @param scale [Scale] scale context for diatonic filtering
+        # @param scale [Scales::Scale] scale context for diatonic filtering
         # @param allow_chromatic [Boolean] allow non-diatonic chords
         # @return [ChordDefinition, nil] matching definition or nil
         #
@@ -242,7 +244,7 @@ module Musa
       # @!attribute grade
       #   @return [Symbol] position name (:root, :third, :fifth, etc.)
       # @!attribute note
-      #   @return [NoteInScale] the note at this position
+      #   @return [Scales::NoteInScale] the note at this position
       #
       # @api private
       ChordGradeNote = Struct.new(:grade, :note, keyword_init: true)
@@ -253,8 +255,8 @@ module Musa
       #
       # Use {with_root} or create chords from scale notes instead.
       #
-      # @param root [NoteInScale] chord root note
-      # @param scale [Scale, nil] scale context (nil if chromatic notes present)
+      # @param root [Scales::NoteInScale] chord root note
+      # @param scale [Scales::Scale, nil] scale context (nil if chromatic notes present)
       # @param chord_definition [ChordDefinition] chord structure
       # @param move [Hash, nil] octave moves for positions
       # @param duplicate [Hash, nil] octave duplications for positions
@@ -423,62 +425,48 @@ module Musa
       #   chord.octave(2)
       def octave(octave)
         source_notes_map = @source_notes_map.transform_values do |notes|
-          notes.collect { |note| note.octave(octave) }.freeze
+          notes.collect { |note| note.at_octave(octave) }.freeze
         end.freeze
 
-        Chord.new(@root.octave(octave), @scale, chord_definition, @move, @duplicate, source_notes_map)
+        Chord.new(@root.at_octave(octave), @scale, chord_definition, @move, @duplicate, source_notes_map)
       end
 
-      # Creates new chord with positions moved to different octaves, or returns current move settings.
+      # Creates new chord with positions moved to different octaves.
       #
-      # When called with arguments, relocates specific chord positions to different
-      # octaves while keeping other positions unchanged. Multiple positions can be
-      # moved at once. Merges with existing moves.
-      #
-      # When called without arguments, returns the current move settings hash.
+      # Relocates specific chord positions to different octaves while keeping
+      # other positions unchanged. Multiple positions can be moved at once.
+      # Merges with existing moves.
       #
       # @param octaves [Hash{Symbol => Integer}] position to octave offset mapping
-      # @return [Chord, Hash] new chord with moved positions, or current move settings if no arguments
+      # @return [Chord] new chord with moved positions
       #
       # @example Move root down, seventh up
-      #   chord.move(root: -1, seventh: 1)
+      #   chord.with_move(root: -1, seventh: 1)
       #
       # @example Drop voicing (move third and seventh down)
-      #   chord.move(third: -1, seventh: -1)
-      #
-      # @example Get current move settings
-      #   chord.move  # => { root: -1 }
-      def move(**octaves)
-        return @move if octaves.empty?
-
+      #   chord.with_move(third: -1, seventh: -1)
+      def with_move(**octaves)
         Chord.new(@root, @scale, @chord_definition, @move.merge(octaves), @duplicate, @source_notes_map)
       end
 
-      # Creates new chord with positions duplicated in other octaves, or returns current duplicate settings.
+      # Creates new chord with positions duplicated in other octaves.
       #
-      # When called with arguments, adds copies of specific chord positions in
-      # different octaves. Original positions remain at their current octave.
+      # Adds copies of specific chord positions in different octaves.
+      # Original positions remain at their current octave.
       # Merges with existing duplications.
       #
-      # When called without arguments, returns the current duplicate settings hash.
-      #
       # @param octaves [Hash{Symbol => Integer, Array<Integer>}] position to octave(s)
-      # @return [Chord, Hash] new chord with duplicated positions, or current duplicate settings if no arguments
+      # @return [Chord] new chord with duplicated positions
       #
       # @example Duplicate root two octaves down
-      #   chord.duplicate(root: -2)
+      #   chord.with_duplicate(root: -2)
       #
       # @example Duplicate third in multiple octaves
-      #   chord.duplicate(third: [-1, 1])
+      #   chord.with_duplicate(third: [-1, 1])
       #
       # @example Duplicate multiple positions
-      #   chord.duplicate(root: -1, fifth: 1)
-      #
-      # @example Get current duplicate settings
-      #   chord.duplicate  # => { root: -1 }
-      def duplicate(**octaves)
-        return @duplicate if octaves.empty?
-
+      #   chord.with_duplicate(root: -1, fifth: 1)
+      def with_duplicate(**octaves)
         Chord.new(@root, @scale, @chord_definition, @move, @duplicate.merge(octaves), @source_notes_map)
       end
 
@@ -507,10 +495,44 @@ module Musa
       #   end
       #
       # @see Musa::Scales::Scale#chord_on
-      # @see Musa::Scales::ScaleSystemTuning#chords_of
-      def in_scales(roots: nil, **metadata)
+      # @see Musa::Scales::ScaleSystemTuning#search_chord_in_scales
+      def search_in_scales(roots: nil, **metadata)
         tuning = @scale&.kind&.tuning || @root.scale.kind.tuning
-        tuning.chords_of(self, roots: roots, **metadata)
+        tuning.search_chord_in_scales(self, roots: roots, **metadata)
+      end
+
+      # Creates an equivalent chord with the given scale as its context.
+      #
+      # Returns a new Chord object representing the same chord but with
+      # the specified scale as its harmonic context. Returns nil if the
+      # chord is not contained in the scale.
+      #
+      # @param scale [Musa::Scales::Scale] the target scale
+      # @return [Chord, nil] new chord with target scale, or nil if not contained
+      #
+      # @example
+      #   c_major = Scales.et12[440.0].major[60]
+      #   g7 = c_major.dominant.chord :seventh
+      #
+      #   g_mixolydian = Scales.et12[440.0].mixolydian[67]
+      #   g7_in_mixolydian = g7.as_chord_in_scale(g_mixolydian)
+      #   g7_in_mixolydian.scale  # => G Mixolydian scale
+      #
+      # @see #search_in_scales
+      # @see Musa::Scales::Scale#contains_chord?
+      def as_chord_in_scale(scale)
+        return nil unless scale.contains_chord?(self)
+
+        root_note = scale.note_of_pitch(@root.pitch, allow_chromatic: false)
+        return nil unless root_note
+
+        Chord.with_root(
+          root_note,
+          scale: scale,
+          name: @chord_definition.name,
+          move: @move.empty? ? nil : @move,
+          duplicate: @duplicate.empty? ? nil : @duplicate
+        )
       end
 
       # Checks chord equality.
@@ -549,12 +571,12 @@ module Musa
         notes_map = notes_map.transform_values(&:dup)
 
         moved&.each do |position, octave|
-          notes_map[position][0] = notes_map[position][0].octave(octave)
+          notes_map[position][0] = notes_map[position][0].at_octave(octave)
         end
 
         duplicated&.each do |position, octave|
           octave.arrayfy.each do |octave|
-            notes_map[position] << notes_map[position][0].octave(octave)
+            notes_map[position] << notes_map[position][0].at_octave(octave)
           end
         end
 

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

@@ -43,7 +43,7 @@ module Musa
     #     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
+    #     c_major.relative_minor.as_root_of(:minor)  # A minor scale
     #
     # @see ScaleKind Abstract base class
     # @see MinorNaturalScaleKind Natural minor scale

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

@@ -56,7 +56,7 @@ module Musa
     #     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
+    #     a_minor.relative_major.as_root_of(:major)  # C major scale
     #
     # @see ScaleKind Abstract base class
     # @see MajorScaleKind Major scale