musa-dsl 0.30.2 → 0.40.0

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
 

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

@@ -1,9 +1,47 @@
 require 'prime'
 
+# Time and duration processing for MusicXML export.
+#
+# This module provides helper methods for converting musical durations
+# to MusicXML note types, dots, and tuplet ratios. Handles the complex
+# mathematics of decomposing arbitrary rational durations into standard
+# notation elements.
+#
+# ## Duration Representation
+#
+# Durations are Rational numbers where 1 = one beat (typically quarter note).
+# - 1r = quarter note
+# - 1/2r = eighth note
+# - 3/2r = dotted quarter
+# - 1/3r = eighth note triplet
+#
+# ## Decomposition Process
+#
+# 1. **Decompose**: Break duration into sum of simple durations (powers of 2)
+# 2. **Integrate**: Combine consecutive halves into dotted notes
+# 3. **Type & Dots**: Determine note type and dot count
+# 4. **Tuplet Ratio**: Calculate tuplet modification if needed
+#
+# @api private
 module Musa::Datasets::Score::ToMXML
   private
 
+  # Decomposes duration into dotted note representation.
+  #
+  # Internal class representing the breakdown of an element's duration
+  # within a measure. Handles ties across bar lines and duration decomposition.
+  #
+  # @api private
   class ElementDurationDecomposition
+    # Creates duration decomposition for element.
+    #
+    # @param element [Hash] event with :start, :finish, :dataset keys
+    # @param bar [Integer] bar number (1-based)
+    # @param bar_size [Rational] bar duration (default: 1r)
+    #
+    # @note This method is experimental and currently unused. See TODO comment.
+    #
+    # @api private
     def initialize(element, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
       @continue_from_previous_bar = element[:start] < bar
       @continue_to_next_bar = element[:finish] >= bar + bar_size
@@ -17,7 +55,25 @@ module Musa::Datasets::Score::ToMXML
       @duration_decomposition = integrate_as_dotteable_durations(decompose_as_sum_of_simple_durations(@duration))
     end
 
-    attr_reader :continue_from_previous_bar, :continue_to_next_bar, :start, :duration, :duration_decomposition
+    # Whether note continues from previous bar (tied).
+    # @return [Boolean]
+    attr_reader :continue_from_previous_bar
+
+    # Whether note continues to next bar (tied).
+    # @return [Boolean]
+    attr_reader :continue_to_next_bar
+
+    # Start time within bar.
+    # @return [Rational]
+    attr_reader :start
+
+    # Total duration.
+    # @return [Rational]
+    attr_reader :duration
+
+    # Duration broken into dotteable components.
+    # @return [Array<Rational>]
+    attr_reader :duration_decomposition
 
     def to_s
       "ElementDurationDecomposition(#{@duration}) = [#{@duration_decomposition}]"
@@ -28,6 +84,21 @@ module Musa::Datasets::Score::ToMXML
 
   private_constant :ElementDurationDecomposition
 
+  # Optimizes time and tuplet representation (experimental).
+  #
+  # Attempts to find optimal tuplet grouping for elements in a bar.
+  # Currently unused due to incomplete implementation.
+  #
+  # @param elements [Array] PDV events
+  # @param bar [Integer] bar number
+  # @param bar_size [Rational] bar duration
+  #
+  # @return [nil] incomplete implementation
+  #
+  # @note This method is experimental and currently unused. See TODO comment.
+  #
+  # @api private
+  # @todo Complete or remove this experimental method
   def time_and_tuplet_optimize(elements, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
     decompositions = elements.collect { |pdv| ElementDurationDecomposition.new(pdv, bar, bar_size) }
 
@@ -46,6 +117,32 @@ module Musa::Datasets::Score::ToMXML
     nil
   end
 
+  # Decomposes duration into sum of simple durations.
+  #
+  # Breaks a rational duration into sum of fractions with power-of-2 denominators.
+  # This is the first step in converting arbitrary durations to standard notation.
+  #
+  # Uses greedy algorithm: repeatedly subtracts largest possible simple duration.
+  #
+  # @param duration [Rational] duration to decompose
+  #
+  # @return [Array<Rational>] simple durations that sum to input
+  #
+  # @raise [ArgumentError] if duration cannot be decomposed
+  #
+  # @example Quarter note
+  #   decompose_as_sum_of_simple_durations(1r)
+  #   # => [1r]
+  #
+  # @example Dotted quarter
+  #   decompose_as_sum_of_simple_durations(3/2r)
+  #   # => [1r, 1/2r]
+  #
+  # @example Complex duration
+  #   decompose_as_sum_of_simple_durations(5/8r)
+  #   # => [1/2r, 1/8r]
+  #
+  # @api private
   def decompose_as_sum_of_simple_durations(duration)
     return [] if duration.zero?
 
@@ -69,6 +166,17 @@ module Musa::Datasets::Score::ToMXML
     summands
   end
 
+  # Generates all combinations of array elements.
+  #
+  # @param numbers [Array] elements to combine
+  #
+  # @return [Array<Array>] all unique combinations (excluding empty)
+  #
+  # @example
+  #   all_combinations([2, 3])
+  #   # => [[2], [3], [2, 3]]
+  #
+  # @api private
   def all_combinations(numbers)
     all_combinations = []
     i = 1
@@ -80,6 +188,28 @@ module Musa::Datasets::Score::ToMXML
     all_combinations.uniq
   end
 
+  # Integrates consecutive halves into dotted durations.
+  #
+  # Combines simple durations where each is half the previous into
+  # single dotted duration. Example: [1r, 1/2r] → [3/2r] (dotted quarter).
+  #
+  # @param simple_durations [Array<Rational>] simple durations from decomposition
+  #
+  # @return [Array<Rational>] integrated dotted durations
+  #
+  # @example Dotted quarter
+  #   integrate_as_dotteable_durations([1r, 1/2r])
+  #   # => [3/2r]
+  #
+  # @example Double-dotted half
+  #   integrate_as_dotteable_durations([1/2r, 1/4r, 1/8r])
+  #   # => [7/8r]
+  #
+  # @example Non-dotteable
+  #   integrate_as_dotteable_durations([1r, 1/4r])
+  #   # => [1r, 1/4r]  (no integration possible)
+  #
+  # @api private
   def integrate_as_dotteable_durations(simple_durations)
     integrated_durations = []
     last = nil
@@ -94,6 +224,32 @@ module Musa::Datasets::Score::ToMXML
     integrated_durations
   end
 
+  # Calculates note type, dots, and tuplet ratio.
+  #
+  # Converts a dotteable duration into MusicXML note representation:
+  # - **type**: Base note type (quarter, eighth, etc.)
+  # - **dots**: Number of dots (0-3 typically)
+  # - **tuplet_ratio**: Tuplet modification (3:2 for triplets, etc.)
+  #
+  # @param noteable_duration [Rational] duration to convert
+  #
+  # @return [Array(String, Integer, Rational)] [type, dots, tuplet_ratio]
+  #
+  # @raise [ArgumentError] if duration cannot be represented with dots
+  #
+  # @example Quarter note
+  #   type_and_dots_and_tuplet_ratio(1r)
+  #   # => ["quarter", 0, 1r]
+  #
+  # @example Dotted quarter
+  #   type_and_dots_and_tuplet_ratio(3/2r)
+  #   # => ["quarter", 1, 1r]
+  #
+  # @example Eighth triplet
+  #   type_and_dots_and_tuplet_ratio(1/3r)
+  #   # => ["eighth", 0, 3/2r]
+  #
+  # @api private
   def type_and_dots_and_tuplet_ratio(noteable_duration)
     r = decompose_as_sum_of_simple_durations(noteable_duration)
     n = r.shift
@@ -117,6 +273,18 @@ module Musa::Datasets::Score::ToMXML
     return type, dots, tuplet_ratio
   end
 
+  # Finds nearest power of 2 greater than or equal to number.
+  #
+  # @param number [Numeric] number to round up
+  #
+  # @return [Integer] nearest upper power of 2
+  #
+  # @example
+  #   nearest_upper_power_of_2(5)  # => 8
+  #   nearest_upper_power_of_2(8)  # => 8
+  #   nearest_upper_power_of_2(9)  # => 16
+  #
+  # @api private
   def nearest_upper_power_of_2(number)
     return 0 if number.zero?
 
@@ -127,6 +295,18 @@ module Musa::Datasets::Score::ToMXML
     2 ** (exp_floor + plus)
   end
 
+  # Finds nearest power of 2 less than or equal to number.
+  #
+  # @param number [Numeric] number to round down
+  #
+  # @return [Integer] nearest lower power of 2
+  #
+  # @example
+  #   nearest_lower_power_of_2(5)  # => 4
+  #   nearest_lower_power_of_2(8)  # => 8
+  #   nearest_lower_power_of_2(15) # => 8
+  #
+  # @api private
   def nearest_lower_power_of_2(number)
     return 0 if number.zero?
 
@@ -135,6 +315,25 @@ module Musa::Datasets::Score::ToMXML
     2 ** exp_floor
   end
 
+  # Converts duration to MusicXML note type name.
+  #
+  # Maps inverse powers of 2 to standard note type names.
+  # Duration must be power of 2 between 1/1024 and maxima (8 whole notes).
+  #
+  # @param base_type_duration [Numeric] duration as power of 2
+  #
+  # @return [String] MusicXML note type name
+  #
+  # @raise [ArgumentError] if duration is not power of 2 or out of range
+  #
+  # @example Standard durations
+  #   type_of(1r)    # => "quarter"
+  #   type_of(1/2r)  # => "eighth"
+  #   type_of(1/4r)  # => "16th"
+  #   type_of(2r)    # => "half"
+  #   type_of(4r)    # => "whole"
+  #
+  # @api private
   def type_of(base_type_duration)
     duration_log2i = Math.log2(base_type_duration)