musa-dsl 0.30.2 → 0.40.0

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

@@ -4,15 +4,150 @@ require_relative 'gdv'
 require_relative 'helper'
 
 module Musa::Datasets
+  # MIDI-style musical events with absolute pitches.
+  #
+  # PDV (Pitch/Duration/Velocity) represents musical events using MIDI-like
+  # absolute pitch numbers. Extends {AbsD} for duration support.
+  #
+  # ## Purpose
+  #
+  # PDV is the MIDI representation layer of the dataset framework:
+  #
+  # - Uses absolute MIDI pitch numbers (0-127)
+  # - Uses MIDI velocity values (0-127)
+  # - Direct mapping to MIDI messages
+  # - Machine-oriented (not human-readable)
+  #
+  # Contrast with {GDV} which uses score notation (scale degrees, dynamics).
+  #
+  # ## Natural Keys
+  #
+  # - **:pitch**: MIDI pitch number (0-127) or :silence for rests
+  # - **:velocity**: MIDI velocity (0-127)
+  # - **:duration**: Event duration (from {AbsD})
+  # - **:note_duration**, **:forward_duration**: Additional duration keys (from {AbsD})
+  #
+  # ## Conversions
+  #
+  # ### To GDV (Score Notation)
+  #
+  # Converts MIDI pitches to scale degrees using a scale reference:
+  #
+  #     pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(PDV)
+  #     scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #     gdv = pdv.to_gdv(scale)
+  #     # => { grade: 0, octave: 0, duration: 1.0, velocity: 0 }
+  #
+  # - **Pitch → Grade**: Finds closest scale degree
+  # - **Chromatic notes**: Represented as grade + sharps
+  # - **Velocity**: Maps MIDI 0-127 to dynamics -5 to +4 (ppp to fff)
+  #
+  # ### Velocity Mapping
+  #
+  # MIDI velocities are mapped to musical dynamics:
+  #
+  #     MIDI 1-1    → velocity -5 (ppp)
+  #     MIDI 2-8    → velocity -4 (pp)
+  #     MIDI 9-16   → velocity -3 (p)
+  #     MIDI 17-33  → velocity -2 (mp)
+  #     MIDI 34-48  → velocity -1 (mf-)
+  #     MIDI 49-64  → velocity  0 (mf)
+  #     MIDI 65-80  → velocity +1 (f)
+  #     MIDI 81-96  → velocity +2 (ff)
+  #     MIDI 97-112 → velocity +3 (fff-)
+  #     MIDI 113-127 → velocity +4 (fff)
+  #
+  # ## Base Duration
+  #
+  # The `base_duration` attribute defines the unit for duration values,
+  # typically 1/4r (quarter note).
+  #
+  # @example Basic MIDI event
+  #   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PDV)
+  #   pdv.base_duration = 1/4r
+  #   # C4 (middle C) for 1 beat at mf dynamics
+  #
+  # @example Silence (rest)
+  #   pdv = { pitch: :silence, duration: 1.0 }.extend(PDV)
+  #   # Rest for 1 beat
+  #
+  # @example With articulation
+  #   pdv = {
+  #     pitch: 64,
+  #     duration: 1.0,
+  #     note_duration: 0.5,  # Staccato
+  #     velocity: 80
+  #   }.extend(PDV)
+  #
+  # @example Convert to score notation
+  #   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(PDV)
+  #   pdv.base_duration = 1/4r
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = pdv.to_gdv(scale)
+  #   # => { grade: 0, octave: 0, duration: 1.0, velocity: 0 }
+  #
+  # @example Chromatic pitch
+  #   pdv = { pitch: 61, duration: 1.0, velocity: 64 }.extend(PDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = pdv.to_gdv(scale)
+  #   # => { grade: 0, octave: 0, sharps: 1, duration: 1.0, velocity: 0 }
+  #   # C# represented as C (grade 0) + 1 sharp
+  #
+  # @example Preserve additional keys
+  #   pdv = {
+  #     pitch: 60,
+  #     duration: 1.0,
+  #     velocity: 64,
+  #     custom_key: :value
+  #   }.extend(PDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = pdv.to_gdv(scale)
+  #   # custom_key copied to GDV (not a natural key)
+  #
+  # @see GDV Score-style representation
+  # @see AbsD Absolute duration events
+  # @see Helper String formatting utilities
   module PDV
     include AbsD
 
     include Helper
 
+    # Natural keys for MIDI events.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:pitch, :velocity]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_accessor :base_duration
 
+    # Converts to GDV (score notation).
+    #
+    # Translates MIDI representation to score notation using a scale:
+    # - MIDI pitch → scale degree (grade + octave + sharps)
+    # - MIDI velocity → dynamics (-5 to +4)
+    # - Duration values copied
+    # - Additional keys preserved
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for pitch conversion
+    #
+    # @return [GDV] score notation dataset
+    #
+    # @example Basic conversion
+    #   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(PDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   gdv = pdv.to_gdv(scale)
+    #
+    # @example Chromatic note
+    #   pdv = { pitch: 61, duration: 1.0 }.extend(PDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   gdv = pdv.to_gdv(scale)
+    #   # => { grade: 0, octave: 0, sharps: 1, duration: 1.0 }
+    #
+    # @example Silence
+    #   pdv = { pitch: :silence, duration: 1.0 }.extend(PDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   gdv = pdv.to_gdv(scale)
+    #   # => { grade: :silence, duration: 1.0 }
     def to_gdv(scale)
       gdv = {}.extend GDV
       gdv.base_duration = @base_duration
@@ -39,7 +174,7 @@ module Musa::Datasets
       if self[:velocity]
         # ppp = 16 ... fff = 127
         # TODO create a customizable MIDI velocity to score dynamics bidirectional conversor
-        gdv[:velocity] = [1..1, 2..8, 9..16, 17..33, 34..49, 49..64, 65..80, 81..96, 97..112, 113..127].index { |r| r.cover? self[:velocity] } - 5
+        gdv[:velocity] = [1..1, 2..8, 9..16, 17..33, 34..48, 49..64, 65..80, 81..96, 97..112, 113..127].index { |r| r.cover? self[:velocity] } - 5
       end
 
       (keys - NaturalKeys).each { |k| gdv[k] = self[k] }

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

@@ -4,31 +4,161 @@ require_relative 'score'
 require_relative '../sequencer'
 
 module Musa::Datasets
+  # Parameter segments for continuous changes between multidimensional points.
+  #
+  # PS (Parameter Segment) represents a continuous change from one point
+  # to another over a duration. Extends {AbsD} for duration support.
+  #
+  # ## Purpose
+  #
+  # PS is used to represent:
+  #
+  # - **Glissandi**: Continuous pitch slides (portamento)
+  # - **Parameter sweeps**: Gradual changes in any sonic parameter
+  # - **Interpolations**: Smooth transitions between multidimensional states
+  #
+  # Unlike discrete events that jump from one value to another, PS represents
+  # the continuous path between values.
+  #
+  # ## Natural Keys
+  #
+  # - **:from**: Starting value (number, array, or hash)
+  # - **:to**: Ending value (must match :from type and structure)
+  # - **:right_open**: Whether endpoint is included (true = open interval)
+  # - **:duration**: Duration of the change (from {AbsD})
+  # - **:note_duration**, **:forward_duration**: Additional duration keys (from {AbsD})
+  #
+  # ## Value Types
+  #
+  # ### Single Values
+  #
+  #     { from: 60, to: 72, duration: 1.0 }
+  #     # Single value glissando
+  #
+  # ### Arrays (parallel interpolation)
+  #
+  #     { from: [60, 64], to: [72, 76], duration: 1.0 }
+  #     # Both values interpolate in parallel
+  #     # Arrays must be same size
+  #
+  # ### Hashes (named parameters)
+  #
+  #     { from: { pitch: 60, velocity: 64 },
+  #       to: { pitch: 72, velocity: 80 },
+  #       duration: 1.0 }
+  #     # Multiple parameters interpolate together
+  #     # Hashes must have same keys
+  #
+  # ## Right Open Intervals
+  #
+  # The :right_open flag determines if the ending value is reached:
+  #
+  # - **false** (closed): Interpolation reaches :to value
+  # - **true** (open): Interpolation stops just before :to value
+  #
+  # This is important for consecutive segments where you don't want
+  # discontinuities at the boundaries.
+  #
+  # @example Basic parameter segment (pitch glissando)
+  #   ps = { from: 60, to: 72, duration: 2.0 }.extend(Musa::Datasets::PS)
+  #   # Continuous slide from C4 to C5 over 2 beats
+  #
+  # @example Parallel interpolation (multidimensional)
+  #   ps = {
+  #     from: [60, 64],  # C4 and E4
+  #     to: [72, 76],    # C5 and E5
+  #     duration: 1.0
+  #   }.extend(PS)
+  #   # Both parameters move in parallel
+  #
+  # @example Multiple parameters (sonic gesture)
+  #   ps = {
+  #     from: { pitch: 60, velocity: 64, pan: -1.0 },
+  #     to: { pitch: 72, velocity: 80, pan: 1.0 },
+  #     duration: 2.0
+  #   }.extend(PS)
+  #   # Pitch, velocity, and pan all change smoothly
+  #
+  # @example Right open interval
+  #   ps1 = { from: 60, to: 64, duration: 1.0, right_open: true }.extend(PS)
+  #   ps2 = { from: 64, to: 67, duration: 1.0, right_open: false }.extend(PS)
+  #   # ps1 stops just before 64, ps2 starts at 64 - no discontinuity
+  #
+  # @example Created from P point series
+  #   p = [60, 4, 64, 8, 67].extend(P)
+  #   serie = p.to_ps_serie
+  #   ps1 = serie.next_value
+  #   # => { from: 60, to: 64, duration: 1.0, right_open: true }
+  #
+  # @see AbsD Parent absolute duration module
+  # @see P Point series (source of PS)
+  # @see Helper String formatting utilities
   module PS
     include AbsD
 
     include Helper
 
+    # Natural keys including segment endpoints.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:from, :to, :right_open]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_accessor :base_duration
 
+    # Converts to Neuma notation string.
+    #
+    # @return [String] Neuma notation
+    # @todo Not yet implemented
     def to_neuma
-      # TODO ???????
+      raise NotImplementedError, 'PS to_neuma conversion is not yet implemented'
     end
 
+    # Converts to PDV (Pitch/Duration/Velocity).
+    #
+    # @return [PDV] PDV dataset
+    # @todo Not yet implemented
     def to_pdv
-      # TODO ??????
+      raise NotImplementedError, 'PS to_pdv conversion is not yet implemented'
     end
 
+    # Converts to GDV (Grade/Duration/Velocity).
+    #
+    # @return [GDV] GDV dataset
+    # @todo Not yet implemented
     def to_gdv
-      # TODO ?????
+      raise NotImplementedError, 'PS to_gdv conversion is not yet implemented'
     end
 
+    # Converts to absolute indexed format.
+    #
+    # @return [AbsI] indexed dataset
+    # @todo Not yet implemented
     def to_absI
-      # TODO ?????
+      raise NotImplementedError, 'PS to_absI conversion is not yet implemented'
     end
 
+    # Validates PS structure.
+    #
+    # Checks that:
+    # - :from and :to have compatible types
+    # - Arrays have same size
+    # - Hashes have same keys
+    # - Duration is positive numeric
+    #
+    # @return [Boolean] true if valid
+    #
+    # @example Valid array segment
+    #   ps = { from: [60, 64], to: [72, 76], duration: 1.0 }.extend(PS)
+    #   ps.valid?  # => true
+    #
+    # @example Invalid - mismatched array sizes
+    #   ps = { from: [60, 64], to: [72], duration: 1.0 }.extend(PS)
+    #   ps.valid?  # => false
+    #
+    # @example Invalid - mismatched hash keys
+    #   ps = { from: { a: 1 }, to: { b: 2 }, duration: 1.0 }.extend(PS)
+    #   ps.valid?  # => false
     def valid?
       case self[:from]
       when Array

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