musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/datasets/score/queriable.rb

@@ -1,11 +1,71 @@
 module Musa::Datasets
   class Score
+    # Query extensions for Score result sets.
+    #
+    # Queriable provides mixins that extend query results from Score methods
+    # with convenient filtering, grouping, and sorting capabilities.
+    #
+    # Two result types are supported:
+    # - **Time slot queries**: Direct event arrays from {Score#at}
+    # - **Interval queries**: Result hashes from {Score#between} and {Score#changes_between}
+    #
+    # These modules are applied automatically to query results and provide
+    # chainable query methods for further filtering.
+    #
+    # @see Score Score class using these modules
     module Queriable
+      # Query methods for time slot arrays.
+      #
+      # QueryableByTimeSlot extends Arrays returned by {Score#at} with query methods.
+      # Each event in the array is a dataset (hash) with musical attributes.
+      #
+      # Methods access attributes directly on events.
+      #
+      # @example Group events by pitch
+      #   events = score.at(0r)  # Returns array extended with QueryableByTimeSlot
+      #   by_pitch = events.group_by_attribute(:pitch)
+      #   # => { 60 => [event1, event2], 64 => [event3] }
+      #
+      # @example Select events with attribute
+      #   staccato = events.select_by_attribute(:staccato)
+      #   # Returns events where :staccato is not nil
+      #
+      # @example Select by value
+      #   forte = events.select_by_attribute(:velocity, 1)
+      #   # Returns events where velocity == 1
+      #
+      # @api private
       module QueryableByTimeSlot
+        # Groups events by attribute value.
+        #
+        # @param attribute [Symbol] attribute to group by
+        #
+        # @return [Hash{Object => Array}] grouped events, values extended with QueryableByTimeSlot
+        #
+        # @example Group by grade
+        #   by_grade = events.group_by_attribute(:grade)
+        #   # => { 0 => [events with grade 0], 2 => [events with grade 2] }
         def group_by_attribute(attribute)
           group_by { |e| e[attribute] }.transform_values! { |e| e.extend(QueryableByTimeSlot) }
         end
 
+        # Selects events by attribute presence or value.
+        #
+        # Without value: selects events where attribute is not nil.
+        # With value: selects events where attribute equals value.
+        #
+        # @param attribute [Symbol] attribute to filter by
+        # @param value [Object, nil] optional value to match
+        #
+        # @return [Array] filtered events, extended with QueryableByTimeSlot
+        #
+        # @example Select with attribute present
+        #   events.select_by_attribute(:staccato)
+        #   # Events where :staccato is not nil
+        #
+        # @example Select by specific value
+        #   events.select_by_attribute(:pitch, 60)
+        #   # Events where pitch == 60
         def select_by_attribute(attribute, value = nil)
           if value.nil?
             select { |e| !e[attribute].nil? }
@@ -14,6 +74,17 @@ module Musa::Datasets
           end.extend(QueryableByTimeSlot)
         end
 
+        # Sorts events by attribute value.
+        #
+        # First filters to events with the attribute, then sorts by its value.
+        #
+        # @param attribute [Symbol] attribute to sort by
+        #
+        # @return [Array] sorted events, extended with QueryableByTimeSlot
+        #
+        # @example Sort by pitch
+        #   sorted = events.sort_by_attribute(:pitch)
+        #   # Events sorted by ascending pitch
         def sort_by_attribute(attribute)
           select_by_attribute(attribute).sort_by { |e| e[attribute] }.extend(QueryableByTimeSlot)
         end
@@ -21,11 +92,57 @@ module Musa::Datasets
 
       private_constant :QueryableByTimeSlot
 
+      # Query methods for interval query results.
+      #
+      # QueryableByDataset extends Arrays returned by {Score#between} and
+      # {Score#changes_between} with query methods. Each element is a hash
+      # containing timing info and a :dataset key with the event.
+      #
+      # Methods access attributes through the :dataset key.
+      #
+      # @example Interval query result structure
+      #   results = score.between(0r, 4r)
+      #   # Each result: { start: ..., finish: ..., dataset: event, ... }
+      #
+      # @example Group by pitch
+      #   by_pitch = results.group_by_attribute(:pitch)
+      #   # Groups by event[:dataset][:pitch]
+      #
+      # @example Select with custom condition
+      #   high = results.subset { |event| event[:pitch] > 60 }
+      #
+      # @api private
       module QueryableByDataset
+        # Groups results by dataset attribute value.
+        #
+        # @param attribute [Symbol] dataset attribute to group by
+        #
+        # @return [Hash{Object => Array}] grouped results, values extended with QueryableByDataset
+        #
+        # @example Group by velocity
+        #   by_velocity = results.group_by_attribute(:velocity)
+        #   # => { 0 => [results with velocity 0], 1 => [results with velocity 1] }
         def group_by_attribute(attribute)
           group_by { |e| e[:dataset][attribute] }.transform_values! { |e| e.extend(QueryableByDataset) }
         end
 
+        # Selects results by dataset attribute presence or value.
+        #
+        # Without value: selects where dataset attribute is not nil.
+        # With value: selects where dataset attribute equals value.
+        #
+        # @param attribute [Symbol] dataset attribute to filter by
+        # @param value [Object, nil] optional value to match
+        #
+        # @return [Array] filtered results, extended with QueryableByDataset
+        #
+        # @example Select with attribute
+        #   results.select_by_attribute(:staccato)
+        #   # Where dataset[:staccato] is not nil
+        #
+        # @example Select by value
+        #   results.select_by_attribute(:grade, 0)
+        #   # Where dataset[:grade] == 0
         def select_by_attribute(attribute, value = nil)
           if value.nil?
             select { |e| !e[:dataset][attribute].nil? }
@@ -34,11 +151,36 @@ module Musa::Datasets
           end.extend(QueryableByDataset)
         end
 
+        # Filters results by custom condition on dataset.
+        #
+        # @yieldparam dataset [Hash] event dataset
+        # @yieldreturn [Boolean] true to include result
+        #
+        # @return [Array] filtered results, extended with QueryableByDataset
+        #
+        # @raise [ArgumentError] if no block given
+        #
+        # @example Filter by pitch range
+        #   results.subset { |event| event[:pitch] > 60 && event[:pitch] < 72 }
+        #
+        # @example Filter by multiple conditions
+        #   results.subset { |event| event[:grade] == 0 && event[:velocity] > 0 }
         def subset
           raise ArgumentError, "subset needs a block with the inclusion condition on the dataset" unless block_given?
           select { |e| yield e[:dataset] }.extend(QueryableByDataset)
         end
 
+        # Sorts results by dataset attribute value.
+        #
+        # First filters to results with the attribute, then sorts by its value.
+        #
+        # @param attribute [Symbol] dataset attribute to sort by
+        #
+        # @return [Array] sorted results, extended with QueryableByDataset
+        #
+        # @example Sort by start time within interval
+        #   sorted = results.sort_by_attribute(:pitch)
+        #   # Results sorted by ascending pitch
         def sort_by_attribute(attribute)
           select_by_attribute(attribute).sort_by { |e| e[:dataset][attribute] }.extend(QueryableByDataset)
         end
@@ -46,4 +188,4 @@ module Musa::Datasets
 
       private_constant :QueryableByDataset
     end
-end; end
+  end; end

data/lib/musa-dsl/datasets/score/render.rb

@@ -4,7 +4,111 @@ require_relative '../../series'
 module Musa
   module Datasets
     class Score
+      # Real-time rendering of scores on sequencers.
+      #
+      # Render provides the {#render} method for playing back scores on a
+      # {Musa::Sequencer::Sequencer}. Events are scheduled at their score times
+      # relative to the sequencer's current position.
+      #
+      # ## Time Calculation
+      #
+      # Score times are 1-based (first beat is 1), but sequencer waits are
+      # 0-based. The conversion is:
+      #
+      #     effective_wait = score_time - 1
+      #
+      # So score time 1 becomes wait 0 (immediate), time 2 becomes wait 1, etc.
+      #
+      # ## Nested Scores
+      #
+      # Scores can contain other scores. When a nested score is encountered,
+      # it's rendered recursively at the appropriate time.
+      #
+      # @example Basic rendering
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(2r, add: { pitch: 64, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   seq = Musa::Sequencer::Sequencer.new(4, 24)
+      #   score.render(on: seq) do |event|
+      #     puts "Play #{event[:pitch]} at #{seq.position}"
+      #   end
+      #   seq.run
+      #
+      # @example Nested scores
+      #   inner = Musa::Datasets::Score.new
+      #   inner.at(1r, add: { pitch: 67 }.extend(Musa::Datasets::AbsD))
+      #   inner.at(2r, add: { pitch: 69 }.extend(Musa::Datasets::AbsD))
+      #
+      #   outer = Musa::Datasets::Score.new
+      #   outer.at(1r, add: { pitch: 60 }.extend(Musa::Datasets::AbsD))
+      #   outer.at(2r, add: inner)  # Nested score
+      #   # inner plays at sequencer time 2r
+      #
+      # @see Musa::Sequencer::Sequencer Sequencer for playback
+      # @see Score#at Adding events to scores
       module Render
+        # Renders score on sequencer.
+        #
+        # Schedules all events in the score on the sequencer, calling the block
+        # for each event at its scheduled time. Score times are converted to
+        # sequencer wait times (score_time - 1).
+        #
+        # Supports nested scores recursively.
+        #
+        # @param on [Musa::Sequencer::Sequencer] sequencer to render on
+        #
+        # @yieldparam event [Abs] each event to process
+        #   Block is called at the scheduled time with the event dataset
+        #
+        # @return [nil]
+        #
+        # @raise [ArgumentError] if element is not Abs or Score
+        #
+        # @example MIDI output
+        #   require 'midi-communications'
+        #
+        #   score = Musa::Datasets::Score.new
+        #   score.at(1r, add: { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PDV))
+        #
+        #   midi_out = MIDICommunications::Output.gets
+        #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+        #
+        #   score.render(on: sequencer) do |event|
+        #     if event[:pitch]
+        #       midi_out.puts(0x90, event[:pitch], event[:velocity] || 64)
+        #       sequencer.at event[:duration] do
+        #         midi_out.puts(0x80, event[:pitch], event[:velocity] || 64)
+        #       end
+        #     end
+        #   end
+        #
+        #   sequencer.run
+        #
+        # @example Console output
+        #   score = Musa::Datasets::Score.new
+        #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+        #
+        #   seq = Musa::Sequencer::Sequencer.new(4, 24)
+        #   score.render(on: seq) do |event|
+        #     puts "Time #{seq.position}: #{event.inspect}"
+        #   end
+        #   seq.run
+        #
+        # @example Nested score rendering
+        #   inner = Musa::Datasets::Score.new
+        #   inner.at(1r, add: { pitch: 67 }.extend(Musa::Datasets::PDV))
+        #
+        #   outer = Musa::Datasets::Score.new
+        #   outer.at(1r, add: { pitch: 60 }.extend(Musa::Datasets::PDV))
+        #   outer.at(2r, add: inner)
+        #
+        #   seq = Musa::Sequencer::Sequencer.new(4, 24)
+        #   outer.render(on: seq) do |event|
+        #     puts "Event: #{event[:pitch]}"
+        #   end
+        #   seq.run
+        #   # Inner scores automatically rendered at their scheduled times
         def render(on:, &block)
           @score.keys.each do |score_at|
             effective_wait = score_at - 1r
@@ -32,4 +136,4 @@ module Musa
       end
     end
   end
-end
+end

data/lib/musa-dsl/datasets/score/to-mxml/process-pdv.rb

@@ -1,8 +1,84 @@
 require 'prime'
 
+# PDV event processing for MusicXML export.
+#
+# Converts {PDV} (Pitch/Duration/Velocity) events to MusicXML notes and rests.
+# Handles pitch mapping, duration decomposition, ties, articulations, and
+# ornaments.
+#
+# ## Processing Steps
+#
+# 1. Extract pitch, octave, and accidentals from MIDI pitch
+# 2. Calculate effective duration within measure (may span bars)
+# 3. Decompose duration into MusicXML-compatible note values
+# 4. Add backup/forward if needed for voice positioning
+# 5. Create MusicXML note/rest elements with all attributes
+#
+# ## Articulations & Ornaments Supported
+#
+# - **:st** → staccato / staccatissimo (1 or > 1)
+# - **:tr** → trill
+# - **:mor** → mordent (:down/:low) or inverted mordent (:up/true)
+# - **:turn** → turn (:up/true) or inverted turn (:down/:low)
+# - **:grace** → grace note (with slur)
+# - **:graced** → note receiving grace note (with slur)
+# - **:voice** → voice number for polyphony
+#
+# ## Ties Across Measures
+#
+# Notes spanning bar lines are automatically tied. Duration is decomposed
+# and tie start/stop/continue markers added appropriately.
+#
+# @api private
 module Musa::Datasets::Score::ToMXML
   using Musa::Extension::InspectNice
 
+  # Processes PDV event to MusicXML note or rest.
+  #
+  # Converts a single PDV event to one or more MusicXML note/rest elements.
+  # Handles duration decomposition, ties, backup/forward for polyphony,
+  # and all articulations/ornaments.
+  #
+  # @param measure [Musa::MusicXML::Builder::Measure] target measure
+  # @param bar [Integer] bar number (1-based)
+  # @param divisions_per_bar [Integer] total divisions in bar
+  # @param element [Hash] event hash from score query
+  #   Contains :start, :finish, :dataset keys
+  # @param pointer [Rational] current position in bar (0-1)
+  # @param logger [Musa::Logger::Logger] logger for debugging
+  # @param do_log [Boolean] enable logging
+  #
+  # @return [Rational] updated pointer position
+  #
+  # @raise [NotImplementedError] if tuplet ratios found (not yet supported)
+  #
+  # @example Simple quarter note
+  #   element = {
+  #     start: 1r,
+  #     finish: 2r,
+  #     dataset: { pitch: 60, duration: 1r }.extend(Musa::Datasets::PDV)
+  #   }
+  #   pointer = process_pdv(measure, 1, 96, element, 0r, logger, false)
+  #   # Adds C4 quarter note, returns 1r
+  #
+  # @example Rest
+  #   element = {
+  #     start: 1r,
+  #     finish: 2r,
+  #     dataset: { pitch: :silence, duration: 1r }.extend(Musa::Datasets::PDV)
+  #   }
+  #   pointer = process_pdv(measure, 1, 96, element, 0r, logger, false)
+  #   # Adds quarter rest, returns 1r
+  #
+  # @example Note with articulation
+  #   dataset = { pitch: 64, duration: 1/2r, st: true }.extend(Musa::Datasets::PDV)
+  #   # Adds staccato eighth note
+  #
+  # @example Tied note across bar
+  #   element = { start: 1r, finish: 3r, dataset: { pitch: 60, duration: 2r } }
+  #   # Automatically tied: tie-start in bar 1, tie-stop in bar 2
+  #
+  # @api private
   private def process_pdv(measure, bar, divisions_per_bar, element, pointer, logger, do_log)
 
     pitch, octave, sharps = pitch_and_octave_and_sharps(element[:dataset])
@@ -127,6 +203,34 @@ module Musa::Datasets::Score::ToMXML
     pointer
   end
 
+  # Converts MIDI pitch to note name, octave, and accidental.
+  #
+  # Maps MIDI pitch number (0-127) to MusicXML pitch representation.
+  # Middle C (MIDI 60) = C4 in scientific pitch notation.
+  #
+  # @param pdv [Hash] PDV dataset with :pitch key
+  #
+  # @return [Array(String, Integer, Integer), Array(Symbol, nil, nil)]
+  #   - For pitches: [note_name, octave, sharps]
+  #   - For silence: [:silence, nil, nil]
+  #
+  # @example Middle C
+  #   pitch_and_octave_and_sharps({ pitch: 60 })
+  #   # => ["C", 4, 0]
+  #
+  # @example C#4
+  #   pitch_and_octave_and_sharps({ pitch: 61 })
+  #   # => ["C", 4, 1]
+  #
+  # @example A4 (440Hz)
+  #   pitch_and_octave_and_sharps({ pitch: 69 })
+  #   # => ["A", 4, 0]
+  #
+  # @example Rest
+  #   pitch_and_octave_and_sharps({ pitch: :silence })
+  #   # => [:silence, nil, nil]
+  #
+  # @api private
   private def pitch_and_octave_and_sharps(pdv)
     if pdv[:pitch] == :silence
       [:silence, nil, nil]
@@ -145,16 +249,49 @@ module Musa::Datasets::Score::ToMXML
     end
   end
 
+  # Converts MIDI velocity to dynamics index.
+  #
+  # Maps MIDI velocity (0-127) to dynamics marking index (0-10).
+  # Used for determining dynamics from velocity values.
+  #
+  # @param midi_velocity [Integer, nil] MIDI velocity value
+  #
+  # @return [Integer, nil] dynamics index (0-10), or nil if no velocity
+  #
+  # @example Pianissimo
+  #   dynamics_index_of(16)  # => 3 (ppp)
+  #
+  # @example Mezzo-forte
+  #   dynamics_index_of(64)  # => 6 (mf)
+  #
+  # @example Fortissimo
+  #   dynamics_index_of(100) # => 9 (ff)
+  #
+  # @api private
   private def dynamics_index_of(midi_velocity)
     return nil unless midi_velocity
 
     # ppp = midi 16 ... fff = midi 127
     # mp = dynamics index 6; dynamics = 0..10
     # TODO create a customizable MIDI velocity to score dynamics bidirectional conversor
-    [0..0, 1..1, 2..8, 9..16, 17..33, 34..49, 49..64, 65..80, 81..96, 97..112, 113..127]
+    [0..0, 1..1, 2..8, 9..16, 17..33, 34..48, 49..64, 65..80, 81..96, 97..112, 113..127]
        .index { |r| r.cover? midi_velocity.round.to_i }
   end
 
+  # Converts dynamics index to MusicXML dynamics string.
+  #
+  # Maps dynamics index (0-10) to standard dynamics marking string.
+  #
+  # @param dynamics_index [Integer, nil] dynamics index
+  #
+  # @return [String, nil] dynamics marking string, or nil if no index
+  #
+  # @example
+  #   dynamics_to_string(3)  # => "ppp"
+  #   dynamics_to_string(6)  # => "mp"
+  #   dynamics_to_string(9)  # => "ff"
+  #
+  # @api private
   private def dynamics_to_string(dynamics_index)
     return nil unless dynamics_index
     ['pppppp', 'ppppp', 'pppp', 'ppp', 'pp', 'p', 'mp', 'mf', 'f', 'ff', 'fff'][dynamics_index.round.to_i]

data/lib/musa-dsl/datasets/score/to-mxml/process-ps.rb

@@ -1,9 +1,120 @@
+# PS event processing for MusicXML export.
+#
+# Converts {PS} (Pitch Series) events to MusicXML dynamics markings.
+# Handles crescendo, diminuendo wedges (hairpins), and static dynamics markings.
+#
+# ## Processing Steps
+#
+# 1. Extract dynamics type (:crescendo, :diminuendo, or :dynamics)
+# 2. For wedges: determine if it's the start or end of the marking
+# 3. Add dynamics marking at wedge start/end if level changed
+# 4. Add wedge element with appropriate type and niente attribute
+# 5. Track last dynamics to avoid redundant markings
+#
+# ## Dynamics Types Supported
+#
+# - **:crescendo** → crescendo wedge (hairpin opening)
+#   - Uses :from attribute for starting dynamics level
+#   - Uses :to attribute for ending dynamics level
+#   - Supports niente (from silence) when :from == 0
+#
+# - **:diminuendo** → diminuendo wedge (hairpin closing)
+#   - Uses :from attribute for starting dynamics level
+#   - Uses :to attribute for ending dynamics level
+#   - Supports niente (to silence) when :to == 0
+#
+# - **:dynamics** → static dynamics marking (pp, mf, ff, etc.)
+#   - Uses :from attribute for dynamics level
+#   - No wedge created, only dynamics text
+#
+# ## Dynamics Levels
+#
+# Dynamics levels are numeric indices (0-10) converted to standard markings:
+# - 0: silence (niente)
+# - 1-3: ppp range
+# - 4-5: pp-p range
+# - 6: mp
+# - 7: mf
+# - 8-9: f-ff range
+# - 10: fff
+#
+# ## Context Tracking
+#
+# Uses DynamicsContext to track the last dynamics marking, preventing
+# duplicate markings when consecutive events have the same level.
+#
+# @api private
 module Musa::Datasets::Score::ToMXML
   using Musa::Extension::InspectNice
 
+  # Context for tracking dynamics state across events.
+  #
+  # @api private
   DynamicsContext = Struct.new(:last_dynamics)
   private_constant :DynamicsContext
 
+  # Processes PS event to MusicXML dynamics marking.
+  #
+  # Converts a single PS event to one or more MusicXML dynamics/wedge elements.
+  # Handles crescendo/diminuendo wedges and static dynamics markings. Tracks
+  # context to avoid redundant markings.
+  #
+  # @param measure [Musa::MusicXML::Builder::Measure] target measure
+  # @param element [Hash] event hash from score query
+  #   Contains :dataset (PS event), :change (:start/:finish for wedges)
+  # @param context [DynamicsContext, nil] dynamics tracking context
+  # @param logger [Musa::Logger::Logger] logger for debugging
+  # @param do_log [Boolean] enable logging
+  #
+  # @return [DynamicsContext] updated context with last dynamics
+  #
+  # @example Crescendo from pp to ff
+  #   element_start = {
+  #     dataset: { type: :crescendo, from: 4, to: 9, duration: 2r }.extend(Musa::Datasets::PS),
+  #     change: :start
+  #   }
+  #   context = process_ps(measure, element_start, nil, logger, false)
+  #   # Adds "pp" dynamics and crescendo wedge start
+  #
+  #   element_finish = {
+  #     dataset: { type: :crescendo, from: 4, to: 9, duration: 2r }.extend(Musa::Datasets::PS),
+  #     change: :finish
+  #   }
+  #   context = process_ps(measure, element_finish, context, logger, false)
+  #   # Adds wedge stop and "ff" dynamics
+  #
+  # @example Diminuendo to silence (niente)
+  #   element_start = {
+  #     dataset: { type: :diminuendo, from: 7, to: 0, duration: 1r }.extend(Musa::Datasets::PS),
+  #     change: :start
+  #   }
+  #   process_ps(measure, element_start, nil, logger, false)
+  #   # Adds "mf" dynamics and diminuendo wedge start
+  #
+  #   element_finish = {
+  #     dataset: { type: :diminuendo, from: 7, to: 0, duration: 1r }.extend(Musa::Datasets::PS),
+  #     change: :finish
+  #   }
+  #   process_ps(measure, element_finish, context, logger, false)
+  #   # Adds wedge stop with niente=true (diminuendo to silence)
+  #
+  # @example Crescendo from silence (niente)
+  #   element_start = {
+  #     dataset: { type: :crescendo, from: 0, to: 6, duration: 1r }.extend(Musa::Datasets::PS),
+  #     change: :start
+  #   }
+  #   process_ps(measure, element_start, nil, logger, false)
+  #   # Adds crescendo wedge with niente=true (from silence)
+  #
+  # @example Static dynamics marking
+  #   element = {
+  #     dataset: { type: :dynamics, from: 8, duration: 0r }.extend(Musa::Datasets::PS),
+  #     change: :start
+  #   }
+  #   process_ps(measure, element, nil, logger, false)
+  #   # Adds "f" dynamics marking only
+  #
+  # @api private
   private def process_ps(measure, element, context, logger, do_log)
     context ||= DynamicsContext.new