musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/datasets/gdv.rb

@@ -5,6 +5,136 @@ require_relative 'pdv'
 require_relative 'helper'
 
 module Musa::Datasets
+  # Score-style musical events with scale degrees.
+  #
+  # GDV (Grade/Duration/Velocity) represents musical events using score notation
+  # with scale degrees, octaves, and dynamics. Extends {AbsD} for duration support.
+  #
+  # ## Purpose
+  #
+  # GDV is the score representation layer of the dataset framework:
+  #
+  # - Uses scale degrees (grade) instead of absolute pitches
+  # - Uses dynamics markings (velocity -5 to +4) instead of MIDI velocity
+  # - Human-readable and musically meaningful
+  # - Independent of specific tuning or scale
+  #
+  # Contrast with {PDV} which uses MIDI absolute pitches and velocities.
+  #
+  # ## Natural Keys
+  #
+  # - **:grade**: Scale degree (integer, 0-based)
+  # - **:sharps**: Chromatic alteration (integer, positive = sharp, negative = flat)
+  # - **:octave**: Octave offset (integer, 0 = base octave)
+  # - **:velocity**: Dynamics (-3 to +4, where 0 = mp, 1 = mf)
+  # - **:silence**: Indicates rest (boolean or symbol)
+  # - **:duration**: Event duration (from {AbsD})
+  # - **:note_duration**, **:forward_duration**: Additional duration keys (from {AbsD})
+  #
+  # ## Pitch Representation
+  #
+  # Pitches are specified as:
+  #
+  # - **grade**: Position in scale (0 = first note, 1 = second note, etc.)
+  # - **octave**: Octave offset (0 = base, 1 = up one octave, -1 = down one octave)
+  # - **sharps**: Chromatic alteration (1 = sharp, -1 = flat, 2 = double sharp, etc.)
+  #
+  # Example in C major scale:
+  #
+  # - C4 = { grade: 0, octave: 0 }
+  # - D4 = { grade: 1, octave: 0 }
+  # - C5 = { grade: 0, octave: 1 }
+  # - C#4 = { grade: 0, octave: 0, sharps: 1 }
+  #
+  # ## Velocity (Dynamics)
+  #
+  # Velocity represents musical dynamics in range -3 to +4:
+  #
+  #     -3: ppp (pianississimo)
+  #     -2: pp  (pianissimo)
+  #     -1: p   (piano)
+  #      0: mp  (mezzo-piano)
+  #     +1: mf  (mezzo-forte)
+  #     +2: f   (forte)
+  #     +3: ff  (fortissimo)
+  #     +4: fff (fortississimo)
+  #
+  # ## Conversions
+  #
+  # ### To PDV (MIDI)
+  #
+  # Converts score notation to MIDI using a scale:
+  #
+  #     gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #     pdv = gdv.to_pdv(scale)
+  #     # => { pitch: 60, duration: 1.0, velocity: 64 }
+  #
+  # ### To GDVd (Delta Encoding)
+  #
+  # Converts to delta encoding for efficient storage:
+  #
+  #     gdv1 = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     gdv2 = { grade: 2, octave: 0, duration: 1.0, velocity: 1 }.extend(GDV)
+  #     gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+  #     # => { delta_grade: 2, delta_velocity: 1 }
+  #
+  # ### To Neuma Notation
+  #
+  # Converts to Neuma string format for serialization:
+  #
+  #     gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     gdv.base_duration = 1/4r
+  #     gdv.to_neuma  # => "(0 4 mp)"
+  #
+  # ## MIDI Velocity Mapping
+  #
+  # Dynamics are mapped to MIDI velocities using interpolation:
+  #
+  #     -3 (ppp) →  16
+  #     -2 (pp)  →  33
+  #     -1 (p)   →  49
+  #      0 (mp)  →  64
+  #     +1 (mf)  →  80
+  #     +2 (f)   →  96
+  #     +3 (ff)  → 112
+  #     +4 (fff) → 127
+  #
+  # @example Basic score event
+  #   gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(Musa::Datasets::GDV)
+  #   gdv.base_duration = 1/4r
+  #   # First scale degree, base octave, 1 beat, mp dynamics
+  #
+  # @example Chromatic alteration
+  #   gdv = { grade: 0, octave: 0, sharps: 1, duration: 1.0 }.extend(GDV)
+  #   # First scale degree sharp (C# in C major)
+  #
+  # @example Silence (rest)
+  #   gdv = { grade: :silence, duration: 1.0 }.extend(GDV)
+  #   # Rest for 1 beat
+  #
+  # @example Convert to MIDI
+  #   gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   pdv = gdv.to_pdv(scale)
+  #   # => { pitch: 60, duration: 1.0, velocity: 64 }
+  #
+  # @example Convert to delta encoding
+  #   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #   gdv2 = { grade: 2, duration: 1.0, velocity: 1 }.extend(GDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+  #   # => { delta_grade: 2, delta_velocity: 1 }
+  #
+  # @example Convert to Neuma notation
+  #   gdv = { grade: 0, octave: 1, duration: 1.0, velocity: 2 }.extend(GDV)
+  #   gdv.base_duration = 1/4r
+  #   gdv.to_neuma  # => "(0 o1 4 ff)"
+  #
+  # @see PDV MIDI-style representation
+  # @see GDVd Delta encoding
+  # @see AbsD Absolute duration events
+  # @see Helper String formatting utilities
   module GDV
     using Musa::Extension::InspectNice
 
@@ -12,14 +142,60 @@ module Musa::Datasets
 
     include Helper
 
+    # Natural keys for score events.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:grade, :sharps, :octave, :velocity, :silence]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_accessor :base_duration
 
+    # MIDI velocity mapping for dynamics.
+    #
+    # Maps dynamics values (-5 to +4) to MIDI velocities (0-127).
+    # Used for interpolation in {#to_pdv}.
+    #
+    # @return [Array<Integer>] MIDI velocity breakpoints
+    # @api private
     # TODO create a customizable MIDI velocity to score dynamics bidirectional conversor
     # ppp = 16 ... fff = 127 (-5 ... 4) the standard used by Musescore 3 and others starts at ppp = 16
     VELOCITY_MAP = [1, 8, 16, 33, 49, 64, 80, 96, 112, 127].freeze
 
+    # Converts to PDV (MIDI representation).
+    #
+    # Translates score notation to MIDI using a scale:
+    # - Scale degree → MIDI pitch (via scale lookup)
+    # - Dynamics → MIDI velocity (via interpolation)
+    # - Duration values copied
+    # - Additional keys preserved
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for pitch conversion
+    #
+    # @return [PDV] MIDI representation dataset
+    #
+    # @example Basic conversion
+    #   gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # => { pitch: 60, duration: 1.0, velocity: 64 }
+    #
+    # @example Chromatic note
+    #   gdv = { grade: 0, octave: 0, sharps: 1, duration: 1.0 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # => { pitch: 61, duration: 1.0 }
+    #
+    # @example Silence
+    #   gdv = { grade: :silence, duration: 1.0 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # => { pitch: :silence, duration: 1.0 }
+    #
+    # @example Dynamics interpolation
+    #   gdv = { grade: 0, velocity: 0.5 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # velocity 0.5 interpolates between mf (64) and f (80)
     def to_pdv(scale)
       pdv = {}.extend PDV
       pdv.base_duration = @base_duration
@@ -50,7 +226,7 @@ module Musa::Datasets
                 else
                   self[:velocity] < -5 ? -5 : 4
                 end
-        
+
         index_min = index.floor
         index_max = index.ceil
 
@@ -65,6 +241,51 @@ module Musa::Datasets
       pdv
     end
 
+    # Converts to Neuma notation string.
+    #
+    # Neuma is a compact text format for score notation. Format:
+    #
+    #     (grade[sharps] [octave] [duration] [velocity] [modifiers...])
+    #
+    # - **grade**: Scale degree number (0, 1, 2...) or 'silence' for rests
+    # - **sharps**: '#' for sharp, '_' for flat (e.g., "0#" = first degree sharp)
+    # - **octave**: 'o' + number (e.g., "o1" = up one octave, "o-1" = down one)
+    # - **duration**: Number of base_duration units
+    # - **velocity**: Dynamics string (ppp, pp, p, mp, mf, f, ff, fff)
+    # - **modifiers**: Additional key-value pairs (e.g., "staccato")
+    #
+    # @return [String] Neuma notation
+    #
+    # @example Basic note
+    #   gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(0 4 mf)"
+    #   # grade 0, duration 4 quarters, mf dynamics
+    #
+    # @example With octave
+    #   gdv = { grade: 2, octave: 1, duration: 0.5, velocity: 2 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(2 o1 2 ff)"
+    #
+    # @example Sharp note
+    #   gdv = { grade: 0, sharps: 1, duration: 1.0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(0# 4)"
+    #
+    # @example Flat note
+    #   gdv = { grade: 1, sharps: -1, duration: 1.0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(1_ 4)"
+    #
+    # @example Silence
+    #   gdv = { grade: :silence, duration: 1.0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(silence 4)"
+    #
+    # @example With modifiers
+    #   gdv = { grade: 0, duration: 1.0, staccato: true }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(0 4 staccato)"
     def to_neuma
       @base_duration ||= Rational(1, 4)
 
@@ -80,7 +301,7 @@ module Musa::Datasets
           if self[:sharps] > 0
             attributes[c] += '#' * self[:sharps]
           elsif self[:sharps] < 0
-            attributes[c] += '_' * self[:sharps]
+            attributes[c] += '_' * self[:sharps].abs
           end
         end
       end
@@ -98,12 +319,68 @@ module Musa::Datasets
       '(' + attributes.join(' ') + ')'
     end
 
+    # Converts velocity number to dynamics string.
+    #
+    # Maps numeric velocity (-3 to +4) to standard dynamics markings.
+    #
+    # @param x [Integer] velocity value
+    # @return [String] dynamics marking
+    #
+    # @example
+    #   velocity_of(-3)  # => "ppp"
+    #   velocity_of(0)   # => "mp"
+    #   velocity_of(1)   # => "mf"
+    #   velocity_of(4)   # => "fff"
+    #
+    # @api private
     def velocity_of(x)
       %w[ppp pp p mp mf f ff fff][x + 3]
     end
 
     private :velocity_of
 
+    # Converts to GDVd (delta encoding).
+    #
+    # Creates delta-encoded representation relative to a previous event.
+    # Only changed values are included, making the representation compact.
+    #
+    # Without previous event (first in sequence):
+    # - Uses abs_ keys for all values
+    #
+    # With previous event:
+    # - Uses delta_ keys for changed values
+    # - Omits unchanged values
+    # - Uses abs_ keys when changing from nil to value
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for grade calculation
+    # @param previous [GDV, nil] previous event for delta calculation
+    #
+    # @return [GDVd] delta-encoded dataset
+    #
+    # @example First event (no previous)
+    #   gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdvd = gdv.to_gdvd(scale)
+    #   # => { abs_grade: 0, abs_duration: 1.0, abs_velocity: 0 }
+    #
+    # @example Changed values
+    #   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdv2 = { grade: 2, duration: 1.0, velocity: 1 }.extend(GDV)
+    #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+    #   # => { delta_grade: 2, delta_velocity: 1 }
+    #   # duration unchanged, so omitted
+    #
+    # @example Unchanged values
+    #   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdv2 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+    #   # => {}
+    #   # Everything unchanged
+    #
+    # @example Chromatic alteration
+    #   gdv1 = { grade: 0, octave: 0 }.extend(GDV)
+    #   gdv2 = { grade: 0, octave: 0, sharps: 1 }.extend(GDV)
+    #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+    #   # => { delta_sharps: 1 }
     def to_gdvd(scale, previous: nil)
       gdvd = {}.extend GDVd
       gdvd.base_duration = @base_duration

data/lib/musa-dsl/datasets/gdvd.rb

@@ -5,6 +5,117 @@ require_relative 'helper'
 
 
 module Musa::Datasets
+  # Delta-encoded score events for efficient compression.
+  #
+  # GDVd (Grade/Duration/Velocity delta) represents musical events using
+  # delta encoding - storing only changes from previous events.
+  # Extends {DeltaD} for flexible duration encoding and {DeltaI} for indexed deltas.
+  #
+  # ## Purpose
+  #
+  # GDVd provides efficient delta encoding for musical sequences:
+  #
+  # - **Compact storage**: Only changed values are stored
+  # - **Efficient serialization**: Neuma format uses delta notation
+  # - **Lossless compression**: Full reconstruction via {#to_gdv}
+  # - **Musical patterns**: Captures relative motion (intervals, velocity changes)
+  #
+  # ## Encoding Types
+  #
+  # Each parameter can be encoded as absolute or delta:
+  #
+  # ### Pitch Encoding
+  #
+  # **Absolute**:
+  #
+  # - **abs_grade**: Set grade to specific value
+  # - **abs_sharps**: Set chromatic alteration
+  # - **abs_octave**: Set octave to specific value
+  #
+  # **Delta**:
+  #
+  # - **delta_grade**: Change grade by semitones
+  # - **delta_sharps**: Change chromatic alteration
+  # - **delta_interval**: Change by scale interval (with delta_interval_sign)
+  # - **delta_octave**: Change octave
+  #
+  # ### Duration Encoding (from {DeltaD})
+  #
+  # - **abs_duration**: Set duration
+  # - **delta_duration**: Add to duration
+  # - **factor_duration**: Multiply duration
+  #
+  # ### Velocity Encoding
+  #
+  # - **abs_velocity**: Set velocity
+  # - **delta_velocity**: Add to velocity
+  #
+  # ## Natural Keys
+  #
+  # - **:abs_grade**, **:abs_sharps**, **:abs_octave**: Absolute pitch
+  # - **:delta_grade**, **:delta_sharps**, **:delta_interval**, **:delta_interval_sign**, **:delta_octave**: Delta pitch
+  # - **:abs_velocity**, **:delta_velocity**: Velocity encoding
+  # - **:abs_duration**, **:delta_duration**, **:factor_duration**: Duration encoding
+  # - **:modifiers**: Hash of additional modifiers
+  #
+  # ## Reconstruction
+  #
+  # Delta events require a previous event for reconstruction:
+  #
+  #     gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+  #     previous = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     gdv = gdvd.to_gdv(scale, previous: previous)
+  #     # => { grade: 2, octave: 0, duration: 1.0, velocity: 1 }
+  #
+  # ## Neuma Delta Notation
+  #
+  # Delta events use special notation in Neuma format:
+  #
+  # - **Delta grade**: "+2" or "-2" (semitone change)
+  # - **Delta sharps**: "+#" or "-_" (chromatic change)
+  # - **Delta octave**: "+o1" or "-o1" (octave change)
+  # - **Delta duration**: "+0.5" or "-0.5" (duration change)
+  # - **Factor duration**: "*2" or "*0.5" (duration multiply)
+  # - **Delta velocity**: "+f" or "-f" (dynamics change)
+  #
+  # @example First event (absolute encoding)
+  #   gdvd = { abs_grade: 0, abs_duration: 1.0, abs_velocity: 0 }.extend(GDVd)
+  #   gdvd.base_duration = 1/4r
+  #   gdvd.to_neuma  # => "(0 4 mp)"
+  #
+  # @example Delta encoding (unchanged duration)
+  #   gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+  #   gdvd.base_duration = 1/4r
+  #   gdvd.to_neuma  # => "(+2 +f)"
+  #   # Grade +2 semitones, velocity +1 (one f louder)
+  #
+  # @example Chromatic change
+  #   gdvd = { delta_sharps: 1 }.extend(GDVd)
+  #   gdvd.to_neuma  # => "(+#)"
+  #   # Add one sharp
+  #
+  # @example Duration multiplication
+  #   gdvd = { factor_duration: 2 }.extend(GDVd)
+  #   gdvd.base_duration = 1/4r
+  #   gdvd.to_neuma  # => "(. *2)"
+  #   # Double duration
+  #
+  # @example Reconstruction from delta
+  #   previous = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #   gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = gdvd.to_gdv(scale, previous: previous)
+  #   # => { grade: 2, octave: 0, duration: 1.0, velocity: 1 }
+  #
+  # @example Octave change
+  #   gdvd = { delta_grade: -2, delta_octave: 1 }.extend(GDVd)
+  #   gdvd.to_neuma  # => "(-2 +o1)"
+  #   # Down 2 semitones, up one octave
+  #
+  # @see GDV Absolute score notation
+  # @see DeltaD Delta duration encoding
+  # @see DeltaI Delta indexed encoding
+  # @see Helper String formatting utilities
   module GDVd
     include DeltaD
     include DeltaI
@@ -13,14 +124,28 @@ module Musa::Datasets
 
     using Musa::Extension::InspectNice
 
+    # Natural keys for delta encoding.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys +
                     [:abs_grade, :abs_sharps, :abs_octave,
                      :delta_grade, :delta_sharps, :delta_interval_sign, :delta_interval, :delta_octave,
                      :abs_velocity, :delta_velocity,
                      :modifiers]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_reader :base_duration
 
+    # Sets base duration, adjusting existing duration values.
+    #
+    # When base_duration changes, existing abs_duration and delta_duration
+    # are scaled proportionally to maintain actual time values.
+    #
+    # @param value [Rational] new base duration
+    #
+    # @example
+    #   gdvd[:abs_duration] = 1.0
+    #   gdvd.base_duration = 1/4r  # abs_duration scaled by factor
     def base_duration=(value)
       factor = value / (@base_duration || 1)
       @base_duration = value
@@ -29,6 +154,33 @@ module Musa::Datasets
       self[:delta_duration] *= factor if has_key?(:delta_duration)
     end
 
+    # Reconstructs absolute GDV from delta encoding.
+    #
+    # Applies delta changes to previous event to create new absolute event.
+    # Handles all encoding types (abs_, delta_, factor_) appropriately.
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for pitch calculations
+    # @param previous [GDV] previous absolute event (required for reconstruction)
+    #
+    # @return [GDV] reconstructed absolute event
+    #
+    # @example Basic delta reconstruction
+    #   previous = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+    #   gdv = gdvd.to_gdv(scale, previous: previous)
+    #   # => { grade: 2, octave: 0, duration: 1.0, velocity: 1 }
+    #
+    # @example Absolute override
+    #   previous = { grade: 0, duration: 1.0 }.extend(GDV)
+    #   gdvd = { abs_grade: 5, abs_duration: 2.0 }.extend(GDVd)
+    #   gdv = gdvd.to_gdv(scale, previous: previous)
+    #   # => { grade: 5, duration: 2.0 }
+    #
+    # @example Duration factor
+    #   previous = { grade: 0, duration: 1.0 }.extend(GDV)
+    #   gdvd = { factor_duration: 2 }.extend(GDVd)
+    #   gdv = gdvd.to_gdv(scale, previous: previous)
+    #   # => { grade: 0, duration: 2.0 }
     def to_gdv(scale, previous:)
       r = previous.clone.delete_if {|k,_| !GDV::NaturalKeys.include?(k)}.extend GDV
 
@@ -109,6 +261,18 @@ module Musa::Datasets
       r
     end
 
+    # Normalizes chromatic pitch to scale note.
+    #
+    # Converts arbitrary grade + sharps to closest scale note representation.
+    # If chromatic, returns background note + chromatic alteration.
+    #
+    # @param scale [Musa::Scales::Scale] reference scale
+    # @param grade [Integer] scale degree (wide grade)
+    # @param sharps [Integer] chromatic alteration
+    #
+    # @return [Array(Integer, Integer)] [normalized_grade, normalized_sharps]
+    #
+    # @api private
     private def normalize_to_scale(scale, grade, sharps)
       note = scale[grade].sharp(sharps)
       background = note.background_note
@@ -120,6 +284,43 @@ module Musa::Datasets
       end
     end
 
+    # Converts to Neuma delta notation string.
+    #
+    # Neuma delta format uses special notation for changes:
+    #
+    #     ([grade_delta] [octave_delta] [duration_delta] [velocity_delta] [modifiers...])
+    #
+    # - **Grade delta**: "+2" or "-2" (semitone change)
+    # - **Sharp delta**: "+#" or "-_" (chromatic change)
+    # - **Octave delta**: "+o1" or "-o1" (octave change)
+    # - **Duration delta**: "+0.5", "-0.5", or "*2" (duration change)
+    # - **Velocity delta**: "+f" or "-f" (dynamics change by f's)
+    #
+    # @return [String] Neuma delta notation
+    #
+    # @example Delta grade
+    #   gdvd = { delta_grade: 2 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(+2)"
+    #
+    # @example Multiple deltas
+    #   gdvd = { delta_grade: -2, delta_velocity: 1 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(-2 +f)"
+    #
+    # @example Duration factor
+    #   gdvd = { factor_duration: 2 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(. *2)"
+    #
+    # @example Chromatic change
+    #   gdvd = { delta_sharps: 1 }.extend(GDVd)
+    #   gdvd.to_neuma  # => "(+#)"
+    #
+    # @example Absolute values
+    #   gdvd = { abs_grade: 0, abs_duration: 1.0 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(0 4)"
     def to_neuma
       @base_duration ||= Rational(1,4)
 

data/lib/musa-dsl/datasets/helper.rb

@@ -1,19 +1,86 @@
 module Musa::Datasets
+  # Helper utilities for dataset formatting and string generation.
+  #
+  # Helper provides utility methods for converting datasets to string
+  # representations, particularly for the Neuma notation format.
+  #
+  # These methods handle:
+  #
+  # - Sign formatting (+/-)
+  # - Velocity to dynamics conversion
+  # - Modifier parameter formatting
+  #
+  # @api private
   module Helper
     private
 
+    # Returns '+' for non-negative numbers, empty string for negative.
+    #
+    # Used for formatting delta values in Neuma notation.
+    #
+    # @param x [Numeric] number to check
+    # @return [String] '+' or ''
+    #
+    # @example
+    #   positive_sign_of(5)   # => '+'
+    #   positive_sign_of(-3)  # => ''
+    #
+    # @api private
     def positive_sign_of(x)
       x >= 0 ? '+' : ''
     end
 
+    # Returns '+', '+', or '-' based on number's sign.
+    #
+    # @param x [Numeric] number to check
+    # @return [String] '+' (positive), '+' (zero), or '-' (negative)
+    #
+    # @example
+    #   sign_of(5)   # => '+'
+    #   sign_of(0)   # => '+'
+    #   sign_of(-3)  # => '-'
+    #
+    # @api private
     def sign_of(x)
       '++-'[x <=> 0]
     end
 
+    # Converts numeric velocity to dynamics marking.
+    #
+    # Maps velocity values (-5 to +4) to standard dynamics markings.
+    # Range: ppp (-5) to fff (+4), centered at mf (0).
+    #
+    # @param x [Integer] velocity value
+    # @return [String] dynamics marking
+    #
+    # @example
+    #   velocity_of(-5)  # => 'ppp'
+    #   velocity_of(0)   # => 'mf'
+    #   velocity_of(4)   # => 'fff'
+    #
+    # @api private
     def velocity_of(x)
       %w[ppp pp p mp mf f ff fff][x + 3]
     end
 
+    # Formats modifier with parameters for Neuma notation.
+    #
+    # Converts modifier keys and their parameters into Neuma string format.
+    #
+    # @param modificator [Symbol] modifier key name
+    # @param parameter_or_parameters [Boolean, Array, Object] modifier parameters
+    # @return [String] formatted modifier string
+    #
+    # @example Boolean modifier (flag)
+    #   modificator_string(:staccato, true)  # => 'staccato'
+    #
+    # @example Single parameter
+    #   modificator_string(:pedal, 'down')  # => 'pedal("down")'
+    #
+    # @example Multiple parameters
+    #   modificator_string(:bend, [2, 'up'])  # => 'bend(2, "up")'
+    #
+    # @api private
     def modificator_string(modificator, parameter_or_parameters)
       case parameter_or_parameters
       when true
@@ -27,6 +94,14 @@ module Musa::Datasets
 
     private
 
+    # Converts parameter to string representation.
+    #
+    # Handles different parameter types for Neuma notation.
+    #
+    # @param parameter [String, Numeric, Symbol] parameter value
+    # @return [String] formatted parameter
+    #
+    # @api private
     def parameter_to_string(parameter)
       case parameter
       when String