musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/transcription/from-gdv-to-midi.rb

@@ -2,7 +2,96 @@ require_relative 'from-gdv'
 
 module Musa::Transcriptors
   module FromGDV
+    # MIDI-specific GDV transcriptors for playback output.
+    #
+    # Transcribes GDV events to MIDI playback format by expanding ornaments and
+    # articulations into explicit note sequences. Unlike MusicXML transcription,
+    # MIDI transcription generates the actual notes to be played.
+    #
+    # ## MIDI vs MusicXML Approach
+    #
+    # MIDI transcription expands ornaments for playback:
+    #
+    # - **MIDI**: Ornaments become explicit note sequences with calculated durations
+    # - **MusicXML**: Ornaments preserved as notation symbols
+    #
+    # ## Supported Ornaments & Articulations
+    #
+    # - **Appogiatura** (`:appogiatura`): Grace note before main note
+    # - **Mordent** (`.mor`): Quick alternation with adjacent note
+    # - **Turn** (`.turn`): Four-note figure circling main note
+    # - **Trill** (`.tr`): Rapid alternation with upper note
+    # - **Staccato** (`.st`): Shortened note duration
+    #
+    # ## Duration Factor
+    #
+    # Many ornaments use a configurable `duration_factor` (default 1/4) to determine
+    # ornament note durations relative to `base_duration`:
+    # ```ruby
+    # ornament_duration = base_duration * duration_factor
+    # ```
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # transcriptor = Musa::Transcription::Transcriptor.new(
+    #   Musa::Transcriptors::FromGDV::ToMIDI.transcription_set(duration_factor: 1/8r),
+    #   base_duration: 1/4r,
+    #   tick_duration: 1/96r
+    # )
+    # result = transcriptor.transcript(gdv_event)
+    # ```
+    #
+    # ## Transcription Set
+    #
+    # The `transcription_set` returns transcriptors applied in order:
+    #
+    # 1. `Appogiatura` - Expand appogiatura grace notes
+    # 2. `Mordent` - Expand mordent ornaments
+    # 3. `Turn` - Expand turn ornaments
+    # 4. `Trill` - Expand trill ornaments
+    # 5. `Staccato` - Apply staccato articulation
+    # 6. `Base` - Process base/rest markers
+    #
+    # @example MIDI trill expansion
+    #   gdv = { grade: 0, duration: 1r, tr: true }
+    #   transcriptor = Musa::Transcriptors::FromGDV::ToMIDI::Trill.new
+    #   result = transcriptor.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+    #   # => [
+    #   #   { grade: 1, duration: 1/16r },  # Upper neighbor
+    #   #   { grade: 0, duration: 1/16r },  # Main note
+    #   #   { grade: 1, duration: 1/16r },  # Upper neighbor
+    #   #   ...
+    #   # ]
+    #
+    # @see ToMusicXML Notation-preserving transcription
+    # @see Musa::MIDIVoices MIDI output system
+    #
+    # @api public
     module ToMIDI
+      # Returns standard transcription set for MIDI output.
+      #
+      # Creates array of transcriptors for processing GDV to MIDI playback format,
+      # expanding all ornaments to explicit note sequences.
+      #
+      # @param duration_factor [Rational] factor for ornament note durations
+      #   relative to base_duration (default: 1/4)
+      #
+      # @return [Array<FeatureTranscriptor>] transcriptor chain
+      #
+      # @example Create MIDI transcription chain with default factor
+      #   transcriptors = Musa::Transcriptors::FromGDV::ToMIDI.transcription_set
+      #   transcriptor = Musa::Transcription::Transcriptor.new(
+      #     transcriptors,
+      #     base_duration: 1/4r
+      #   )
+      #
+      # @example Custom duration factor for faster ornaments
+      #   transcriptors = Musa::Transcriptors::FromGDV::ToMIDI.transcription_set(
+      #     duration_factor: 1/8r
+      #   )
+      #
+      # @api public
       def self.transcription_set(duration_factor: nil)
         [ Appogiatura.new,
           Mordent.new(duration_factor: duration_factor),
@@ -12,8 +101,60 @@ module Musa::Transcriptors
           Base.new ]
       end
 
+      # Appogiatura transcriptor for MIDI playback.
+      #
+      # Expands appogiatura ornaments into two sequential notes for MIDI playback.
+      # The grace note (appogiatura) is played first, followed by the main note
+      # with reduced duration.
+      #
+      # ## Processing
+      #
+      # Given an appogiatura marking:
+      # ```ruby
+      # {
+      #   grade: 0,
+      #   duration: 1r,
+      #   appogiatura: { grade: -1, duration: 1/8r }
+      # }
+      # ```
+      #
+      # Expands to two notes:
+      # ```ruby
+      # [
+      #   { grade: -1, duration: 1/8r },      # Grace note
+      #   { grade: 0, duration: 7/8r }        # Main note (reduced)
+      # ]
+      # ```
+      #
+      # The main note's duration is reduced by the appogiatura duration to maintain
+      # total duration.
+      #
+      # @example Appogiatura expansion
+      #   app = Appogiatura.new
+      #   gdv = {
+      #     grade: 0,
+      #     duration: 1r,
+      #     appogiatura: { grade: -1, duration: 1/8r }
+      #   }
+      #   result = app.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+      #   # => [
+      #   #   { grade: -1, duration: 1/8r },
+      #   #   { grade: 0, duration: 7/8r }
+      #   # ]
+      #
+      # @api public
       # Process: appogiatura (neuma)neuma
       class Appogiatura < Musa::Transcription::FeatureTranscriptor
+        # Transcribes appogiatura to two-note sequence.
+        #
+        # @param gdv [Hash] GDV event possibly containing `:appogiatura`
+        # @param base_duration [Rational] base duration unit
+        # @param tick_duration [Rational] minimum tick duration
+        #
+        # @return [Array<Hash>, Hash] array with grace note and main note, or
+        #   unchanged event if no appogiatura
+        #
+        # @api public
         def transcript(gdv, base_duration:, tick_duration:)
           gdv_appogiatura = gdv.delete :appogiatura
 
@@ -31,12 +172,74 @@ module Musa::Transcriptors
         end
       end
 
+      # Mordent transcriptor for MIDI playback.
+      #
+      # Expands mordent ornaments into a three-note sequence: main note, adjacent
+      # note (upper or lower), then main note. The mordent is a quick ornament
+      # typically used to emphasize a note.
+      #
+      # ## Mordent Types
+      #
+      # - `.mor` or `.mor(:up)` - Upper mordent (main, upper neighbor, main)
+      # - `.mor(:down)` or `.mor(:low)` - Lower mordent (main, lower neighbor, main)
+      #
+      # ## Processing
+      #
+      # Given `.mor` on a note:
+      # ```ruby
+      # { grade: 0, duration: 1r, mor: true }
+      # ```
+      #
+      # Expands to three notes:
+      # ```ruby
+      # [
+      #   { grade: 0, duration: 1/16r },    # Main note (short)
+      #   { grade: 1, duration: 1/16r },    # Upper neighbor (short)
+      #   { grade: 0, duration: 7/8r }      # Main note (remaining duration)
+      # ]
+      # ```
+      #
+      # ## Duration Calculation
+      #
+      # Short notes duration: `base_duration * duration_factor` (default 1/4)
+      # Final note gets remaining duration: `original - 2 * short_duration`
+      #
+      # @example Upper mordent
+      #   mor = Mordent.new(duration_factor: 1/4r)
+      #   gdv = { grade: 0, duration: 1r, mor: true }
+      #   result = mor.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+      #   # => [
+      #   #   { grade: 0, duration: 1/16r },
+      #   #   { grade: 1, duration: 1/16r },
+      #   #   { grade: 0, duration: 7/8r }
+      #   # ]
+      #
+      # @example Lower mordent
+      #   gdv = { grade: 0, duration: 1r, mor: :down }
+      #   # Uses lower neighbor (grade: -1)
+      #
+      # @api public
       # Process: .mor
       class Mordent < Musa::Transcription::FeatureTranscriptor
+        # Creates mordent transcriptor.
+        #
+        # @param duration_factor [Rational] factor for ornament note duration
+        #   relative to base_duration (default: 1/4)
+        #
+        # @api public
         def initialize(duration_factor: nil)
           @duration_factor = duration_factor || 1/4r
         end
 
+        # Transcribes mordent to three-note sequence.
+        #
+        # @param gdv [Hash] GDV event possibly containing `:mor`
+        # @param base_duration [Rational] base duration unit
+        # @param tick_duration [Rational] minimum tick duration
+        #
+        # @return [Array<Hash>, Hash] array with mordent notes, or unchanged event
+        #
+        # @api public
         def transcript(gdv, base_duration:, tick_duration:)
           mor = gdv.delete :mor
 
@@ -74,8 +277,68 @@ module Musa::Transcriptors
         end
       end
 
+      # Turn transcriptor for MIDI playback.
+      #
+      # Expands turn ornaments into a four-note figure that circles around the
+      # main note. A turn is a melodic embellishment consisting of the note above,
+      # the principal note, the note below, and the principal note again.
+      #
+      # ## Turn Types
+      #
+      # - `.turn` or `.turn(:up)` - Start with upper neighbor (upper, main, lower, main)
+      # - `.turn(:down)` or `.turn(:low)` - Start with lower neighbor (lower, main, upper, main)
+      #
+      # ## Processing
+      #
+      # Given `.turn` on a note:
+      # ```ruby
+      # { grade: 0, duration: 1r, turn: true }
+      # ```
+      #
+      # Expands to four equal notes:
+      # ```ruby
+      # [
+      #   { grade: 1, duration: 1/4r },    # Upper neighbor
+      #   { grade: 0, duration: 1/4r },    # Main note
+      #   { grade: -1, duration: 1/4r },   # Lower neighbor
+      #   { grade: 0, duration: 1/4r }     # Main note
+      # ]
+      # ```
+      #
+      # Each note gets 1/4 of the original duration.
+      #
+      # @example Upper turn
+      #   turn = Turn.new
+      #   gdv = { grade: 0, duration: 1r, turn: true }
+      #   result = turn.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+      #   # => [
+      #   #   { grade: 1, duration: 1/4r },   # +1
+      #   #   { grade: 0, duration: 1/4r },   # 0
+      #   #   { grade: -1, duration: 1/4r },  # -1
+      #   #   { grade: 0, duration: 1/4r }    # 0
+      #   # ]
+      #
+      # @example Lower turn
+      #   gdv = { grade: 0, duration: 1r, turn: :down }
+      #   # => [
+      #   #   { grade: -1, duration: 1/4r },  # -1
+      #   #   { grade: 0, duration: 1/4r },   # 0
+      #   #   { grade: 1, duration: 1/4r },   # +1
+      #   #   { grade: 0, duration: 1/4r }    # 0
+      #   # ]
+      #
+      # @api public
       # Process: .turn
       class Turn < Musa::Transcription::FeatureTranscriptor
+        # Transcribes turn to four-note sequence.
+        #
+        # @param gdv [Hash] GDV event possibly containing `:turn`
+        # @param base_duration [Rational] base duration unit
+        # @param tick_duration [Rational] minimum tick duration
+        #
+        # @return [Array<Hash>, Hash] array with turn notes, or unchanged event
+        #
+        # @api public
         def transcript(gdv, base_duration:, tick_duration:)
           turn = gdv.delete :turn
 
@@ -84,7 +347,7 @@ module Musa::Transcriptors
 
             check(turn) do |turn|
               case turn
-              when :true, :up
+              when true, :up
                 start = :up
               when :down, :low
                 start = :down
@@ -115,12 +378,85 @@ module Musa::Transcriptors
         end
       end
 
+      # Trill transcriptor for MIDI playback.
+      #
+      # Expands trill ornaments into a rapid alternation between the main note and
+      # its upper neighbor. The trill fills the entire note duration with alternating
+      # notes, with sophisticated duration management including acceleration.
+      #
+      # ## Trill Options
+      #
+      # - `.tr` or `.tr(true)` - Standard trill starting with upper neighbor
+      # - `.tr(:low)` - Start with lower neighbor first (2 notes)
+      # - `.tr(:low2)` - Start with upper but include lower neighbor (4 notes)
+      # - `.tr(:same)` - Start with main note
+      # - `.tr(factor)` - Custom duration factor (e.g., `.tr(1/8r)`)
+      #
+      # ## Duration Algorithm
+      #
+      # The trill uses a sophisticated multi-phase duration algorithm:
+      #
+      # 1. **Initial pattern**: Based on trill options (:low, :low2, :same)
+      # 2. **Regular pattern**: Two cycles at full `note_duration`
+      # 3. **Accelerando**: Cycles at 2/3 `note_duration` (faster)
+      # 4. **Final notes**: Distribute remaining duration
+      #
+      # ## Processing
+      #
+      # Given `.tr` on a note:
+      # ```ruby
+      # { grade: 0, duration: 1r, tr: true }
+      # ```
+      #
+      # Expands to alternating sequence:
+      # ```ruby
+      # [
+      #   { grade: 1, duration: 1/16r },    # Upper (initial)
+      #   { grade: 0, duration: 1/16r },    # Main
+      #   { grade: 1, duration: 1/16r },    # Upper (regular)
+      #   { grade: 0, duration: 1/16r },    # Main
+      #   { grade: 1, duration: ~1/24r },   # Upper (accelerando)
+      #   { grade: 0, duration: ~1/24r },   # Main
+      #   ...
+      # ]
+      # ```
+      #
+      # @example Standard trill
+      #   trill = Trill.new(duration_factor: 1/4r)
+      #   gdv = { grade: 0, duration: 1r, tr: true }
+      #   result = trill.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+      #   # Generates alternating upper/main notes filling duration
+      #
+      # @example Trill starting low
+      #   gdv = { grade: 0, duration: 1r, tr: :low }
+      #   # Starts with lower neighbor, then alternates upper/main
+      #
+      # @example Custom duration factor
+      #   gdv = { grade: 0, duration: 1r, tr: 1/8r }
+      #   # Faster trill with shorter note durations
+      #
+      # @api public
       # Process: .tr
       class Trill < Musa::Transcription::FeatureTranscriptor
+        # Creates trill transcriptor.
+        #
+        # @param duration_factor [Rational] factor for trill note duration
+        #   relative to base_duration (default: 1/4)
+        #
+        # @api public
         def initialize(duration_factor: nil)
           @duration_factor = duration_factor || 1/4r
         end
 
+        # Transcribes trill to alternating note sequence.
+        #
+        # @param gdv [Hash] GDV event possibly containing `:tr`
+        # @param base_duration [Rational] base duration unit
+        # @param tick_duration [Rational] minimum tick duration
+        #
+        # @return [Array<Hash>, Hash] array with trill notes, or unchanged event
+        #
+        # @api public
         def transcript(gdv, base_duration:, tick_duration:)
           tr = gdv.delete :tr
 
@@ -192,12 +528,79 @@ module Musa::Transcriptors
         end
       end
 
+      # Staccato transcriptor for MIDI playback.
+      #
+      # Applies staccato articulation by shortening note duration. Instead of
+      # creating multiple notes, staccato modifies the `:note_duration` attribute
+      # to create a gap between note-off and the next note-on.
+      #
+      # ## Staccato Levels
+      #
+      # - `.st` or `.st(true)` - Half duration (1/2)
+      # - `.st(1)` - Half duration (1/2)
+      # - `.st(2)` - Quarter duration (1/4)
+      # - `.st(3)` - Eighth duration (1/8)
+      # - `.st(n)` - Duration divided by 2^n
+      #
+      # ## Processing
+      #
+      # Staccato sets `:note_duration` attribute (actual sounding duration)
+      # while preserving `:duration` (rhythmic position duration). The gap
+      # between these creates the staccato articulation.
+      #
+      # Given `.st` on a note:
+      # ```ruby
+      # { grade: 0, duration: 1r, st: true }
+      # ```
+      #
+      # Results in:
+      # ```ruby
+      # { grade: 0, duration: 1r, note_duration: 1/2r }
+      # ```
+      # - `duration: 1r` - Next note starts after 1 beat
+      # - `note_duration: 1/2r` - Note sounds for 1/2 beat (staccato gap)
+      #
+      # ## Minimum Duration
+      #
+      # A minimum duration (`base_duration * min_duration_factor`, default 1/8)
+      # prevents extremely short notes that might sound like clicks.
+      #
+      # @example Basic staccato
+      #   staccato = Staccato.new
+      #   gdv = { grade: 0, duration: 1r, st: true }
+      #   result = staccato.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+      #   # => { grade: 0, duration: 1r, note_duration: 1/2r }
+      #
+      # @example Staccato level 2
+      #   gdv = { grade: 0, duration: 1r, st: 2 }
+      #   # => { grade: 0, duration: 1r, note_duration: 1/4r }
+      #
+      # @example Very short note (minimum enforced)
+      #   gdv = { grade: 0, duration: 1/16r, st: true }
+      #   # note_duration clamped to base_duration * 1/8 (minimum)
+      #
+      # @api public
       # Process: .st .st(1) .st(2) .st(3): staccato level 1 2 3
       class Staccato < Musa::Transcription::FeatureTranscriptor
+        # Creates staccato transcriptor.
+        #
+        # @param min_duration_factor [Rational] minimum duration factor relative
+        #   to base_duration to prevent click-like short notes (default: 1/8)
+        #
+        # @api public
         def initialize(min_duration_factor: nil)
           @min_duration_factor = min_duration_factor || 1/8r
         end
 
+        # Transcribes staccato by setting note_duration.
+        #
+        # @param gdv [Hash] GDV event possibly containing `:st`
+        # @param base_duration [Rational] base duration unit
+        # @param tick_duration [Rational] minimum tick duration
+        #
+        # @return [Hash] event with `:note_duration` set if staccato, or unchanged
+        #
+        # @api public
         def transcript(gdv, base_duration:, tick_duration:)
           st = gdv.delete :st
 

data/lib/musa-dsl/transcription/from-gdv-to-musicxml.rb

@@ -2,14 +2,132 @@ require_relative 'from-gdv'
 
 module Musa::Transcriptors
   module FromGDV
+    # MusicXML-specific GDV transcriptors for music notation output.
+    #
+    # Transcribes GDV events to MusicXML format, handling ornaments and articulations
+    # as notation metadata rather than expanded note sequences. MusicXML is an XML-based
+    # standard for representing Western music notation.
+    #
+    # ## MusicXML vs MIDI Approach
+    #
+    # MusicXML transcription differs from MIDI transcription:
+    #
+    # - **MusicXML**: Preserves ornaments as notation symbols (grace notes, trills, etc.)
+    # - **MIDI**: Expands ornaments to explicit note sequences for playback
+    #
+    # ## Supported Features
+    #
+    # - **Appogiatura**: Grace note ornaments marked with `:grace` attribute
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # transcriptor = Musa::Transcription::Transcriptor.new(
+    #   Musa::Transcriptors::FromGDV::ToMusicXML.transcription_set,
+    #   base_duration: 1/4r,
+    #   tick_duration: 1/96r
+    # )
+    # result = transcriptor.transcript(gdv_event)
+    # ```
+    #
+    # ## Transcription Set
+    #
+    # The `transcription_set` method returns an array of transcriptors applied
+    # in order:
+    #
+    # 1. `Appogiatura` - Process appogiatura ornaments
+    # 2. `Base` - Process base/rest markers
+    #
+    # @example MusicXML appogiatura
+    #   gdv = {
+    #     grade: 0,
+    #     duration: 1r,
+    #     appogiatura: { grade: -1, duration: 1/8r }
+    #   }
+    #   transcriptor = Musa::Transcriptors::FromGDV::ToMusicXML::Appogiatura.new
+    #   result = transcriptor.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+    #   # => [
+    #   #   { grade: -1, duration: 1/8r, grace: true },
+    #   #   { grade: 0, duration: 1r, graced: true, graced_by: {...} }
+    #   # ]
+    #
+    # @see Musa::MusicXML MusicXML output system
+    # @see ToMIDI Playback-oriented transcription
     module ToMusicXML
+      # Returns standard transcription set for MusicXML output.
+      #
+      # Creates array of transcriptors for processing GDV to MusicXML format.
+      #
+      # @return [Array<FeatureTranscriptor>] transcriptor chain
+      #
+      # @example Create MusicXML transcription chain
+      #   transcriptors = Musa::Transcriptors::FromGDV::ToMusicXML.transcription_set
+      #   transcriptor = Musa::Transcription::Transcriptor.new(
+      #     transcriptors,
+      #     base_duration: 1/4r
+      #   )
+      #
+      # @api public
       def self.transcription_set
         [ Appogiatura.new,
           Base.new ]
       end
 
+      # Appogiatura transcriptor for MusicXML notation.
+      #
+      # Processes appogiatura ornaments, marking them as grace notes for MusicXML
+      # output rather than expanding to explicit note sequences. The grace note
+      # relationship is preserved through `:grace`, `:graced`, and `:graced_by`
+      # attributes.
+      #
+      # ## Appogiatura Format
+      #
+      # Input GDV with `:appogiatura` key:
+      # ```ruby
+      # {
+      #   grade: 0,
+      #   duration: 1r,
+      #   appogiatura: { grade: -1, duration: 1/8r }
+      # }
+      # ```
+      #
+      # Output (array of two events):
+      # ```ruby
+      # [
+      #   { grade: -1, duration: 1/8r, grace: true },           # Grace note
+      #   { grade: 0, duration: 1r, graced: true, graced_by: ... } # Main note
+      # ]
+      # ```
+      #
+      # ## MusicXML Representation
+      #
+      # The `:grace` attribute indicates the note should be rendered as a grace
+      # note in the score. The `:graced_by` reference allows the notation engine
+      # to properly link the grace note to its principal note.
+      #
+      # @example Process appogiatura
+      #   app = Appogiatura.new
+      #   gdv = {
+      #     grade: 0,
+      #     duration: 1r,
+      #     appogiatura: { grade: -1, duration: 1/8r }
+      #   }
+      #   result = app.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+      #   # => [grace_note, main_note]
+      #
+      # @api public
       # Process: appogiatura (neuma)neuma
       class Appogiatura < Musa::Transcription::FeatureTranscriptor
+        # Transcribes GDV appogiatura to grace note representation.
+        #
+        # @param gdv [Hash] GDV event possibly containing `:appogiatura`
+        # @param base_duration [Rational] base duration unit
+        # @param tick_duration [Rational] minimum tick duration
+        #
+        # @return [Array<Hash>, Hash] array with grace note and main note, or
+        #   unchanged event if no appogiatura
+        #
+        # @api public
         def transcript(gdv, base_duration:, tick_duration:)
           if gdv_appogiatura = gdv[:appogiatura]
             gdv.delete :appogiatura

data/lib/musa-dsl/transcription/from-gdv.rb

@@ -1,9 +1,92 @@
+#
+#
+# @api public
 require_relative 'transcription'
 
 module Musa::Transcriptors
+  # GDV (Grade-Duration-Velocity) base transcriptor for processing fundamental features.
+  #
+  # Provides the foundational transcriptor for handling base/rest events in GDV notation.
+  # GDV is Musa-DSL's internal representation for musical events with grade (pitch),
+  # duration, and velocity information.
+  #
+  # ## GDV Format
+  #
+  # GDV events are hashes with musical attributes:
+  # ```ruby
+  # {
+  #   grade: 0,          # Scale degree
+  #   duration: 1r,      # Rational duration
+  #   velocity: 0.8,     # Note velocity (0.0-1.0)
+  #   base: true         # Mark as base/rest (zero duration)
+  # }
+  # ```
+  #
+  # This module contains the base transcriptor (`Base`) for handling base/rest
+  # markers in GDV events, converting them to zero-duration structural markers.
+  #
+  # Format-specific transcriptors are in submodules:
+  # - {ToMIDI} - MIDI playback transcription (expands ornaments)
+  # - {ToMusicXML} - MusicXML notation transcription (preserves ornaments)
+  #
+  # ## Base/Rest Processing
+  #
+  # The `.base` (or `.b`) attribute marks an event as a base or rest, which is
+  # converted to a zero-duration event. This is useful for representing rests
+  # or structural markers in the musical timeline.
+  #
+  # ## Transcriptor Pattern
+  #
+  # All transcriptors follow the same pattern:
+  #
+  # 1. Extract specific features from GDV hash
+  # 2. Process/transform the event based on those features
+  # 3. Return modified event(s) or array of events
+  #
+  # @example Basic base event
+  #   gdv = { grade: 0, duration: 1r, base: true }
+  #   transcriptor = Musa::Transcriptors::FromGDV::Base.new
+  #   result = transcriptor.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+  #   # => { duration: 0 } (marked as AbsD)
+  #   
+  # @see Musa::Transcription::Transcriptor Main transcription orchestrator
+  # @see Musa::Transcription::FeatureTranscriptor
+  # @see ToMIDI MIDI-specific transcriptors
+  # @see ToMusicXML MusicXML-specific transcriptors
   module FromGDV
-    # Process: .base .b
+    # Base transcriptor for processing `.base` or `.b` attributes.
+    #
+    # Converts GDV events marked with `:base` or `:b` to zero-duration events,
+    # useful for representing rests or structural markers.
+    #
+    # ## Processing
+    #
+    # - Checks for `:base` or `:b` attribute
+    # - If found, replaces event with `{duration: 0}` marked as `AbsD`
+    # - If not found, passes through unchanged
+    #
+    # @example Process base event
+    #   base = Base.new
+    #   gdv = { grade: 0, duration: 1r, base: true }
+    #   result = base.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+    #   # => { duration: 0 }
+    #
+    # @example Normal event (unchanged)
+    #   gdv = { grade: 0, duration: 1r }
+    #   result = base.transcript(gdv, base_duration: 1/4r, tick_duration: 1/96r)
+    #   # => { grade: 0, duration: 1r }
+    #
+    # @api public
     class Base < Musa::Transcription::FeatureTranscriptor
+      # Transcribes GDV event, converting base markers to zero-duration events.
+      #
+      # @param gdv [Hash] GDV event with musical attributes
+      # @param base_duration [Rational] base duration unit (e.g., quarter note)
+      # @param tick_duration [Rational] minimum tick duration (e.g., 1/96)
+      #
+      # @return [Hash] transcribed event (zero-duration if base, unchanged otherwise)
+      #
+      # @api public
       def transcript(gdv, base_duration:, tick_duration:)
         base = gdv.delete :base
         base ||= gdv.delete :b