clef 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54756cf60de8a132c3b38667cd33fdd80f4bb856d87026b916aa4018b1d515e3
-  data.tar.gz: f78c5b688a8a28952a08d701c737c9b1929cebf6caf86451f9daa0e92ca7f84d
+  metadata.gz: e7370681782ef34e1aae62e5fa1c3ef85691ce5b24ef64ec9c7aa4ae7c330729
+  data.tar.gz: 93cb4ad4fb0ebfe17ce92d8c237bbf8b142b3ed6b8cf7b2280f5da6f382f2cd0
 SHA512:
-  metadata.gz: 2e82ac741da2cdf64fc828fe4664bb1d29bd7a118c0a4bd7095c8d189cafb72be12e8fa263500135d193a467c3728cb97a4fcca5f7ef2e459189f294ef8eddb0
-  data.tar.gz: 56655953b3b5b01289b38a4e08bf80ce07024cfd13208cc15bb57059e07e4e8a6be2ee6c31ebb2879fb4b379381cd8558d4524b673bc0b2ba3451daeb8ca4f8d
+  metadata.gz: 190106173db34b9c34d549354ad06b71a9b910cce0a6c39ed33365fb88d757e71517d2cd9135cd8b2b775ed5ed99c8c427f2372651d5762c8143aa7dd4907884
+  data.tar.gz: 252cb685567040363ccbf78db7071379ee5ae2c7a6ff46ea0ff4f6d3547687f8265383e8a9f87d036291a6ee59f6847de91ca30db67eefb0daa3ba003e1b7cc5

data/README.md

@@ -1,33 +1,36 @@
 # Clef
 
-Clef is a Ruby toolkit for building small scores with a Ruby DSL and exporting them to PDF, SVG, or MIDI.
+[![Ruby](https://github.com/ydah/clef/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/ydah/clef/actions/workflows/main.yml)
+[![Gem Version](https://img.shields.io/gem/v/clef.svg)](https://rubygems.org/gems/clef)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-## Current Feature Set
+Clef is a lightweight Ruby toolkit for building small music scores, parsing a practical LilyPond-style syntax subset, and exporting PDF, SVG, or MIDI.
 
-- Core score model for pitches, durations, notes, rests, chords, measures, staves, staff groups, and tempo
-- Ruby DSL via `Clef.score`
-- LilyPond-like shorthand through `play` and `notes`
-- Basic LilyPond import through `Clef::Parser::LilypondParser`
-- PDF rendering with Prawn
-- SVG rendering with Nokogiri
-- MIDI export with midilib
-- Plugin hooks around layout and rendering
+It is intended for concise notation workflows, examples, and application embedding. It is not a full replacement for LilyPond, MusicXML, or a publishing-grade engraving engine.
+
+## Requirements
+
+- Ruby 3.1 or newer
+- Bundler for development
+- Optional: `fonts/bravura/Bravura.otf` for higher quality PDF/SVG music glyphs
 
 ## Installation
 
-Clef requires Ruby 3.1 or newer.
+Add Clef to your application's Gemfile:
+
+```ruby
+gem "clef"
+```
 
 For local development:
 
-```bash
+```sh
 git clone https://github.com/ydah/clef.git
 cd clef
 bin/setup
 ```
 
-For PDF output with SMuFL glyphs, place `Bravura.otf` at `fonts/bravura/Bravura.otf`.
-If the font file is missing, Clef falls back to `Helvetica`.
-
 ## Quick Start
 
 ```ruby
@@ -36,11 +39,11 @@ require "clef"
 score = Clef.score do
   title "Twinkle Twinkle Little Star"
   composer "Traditional"
-  tempo beat_unit: :quarter, bpm: 100
 
-  staff :melody, clef: :treble do
+  staff :piano, clef: :treble do
     key :c, :major
     time 4, 4
+
     play "c'4 c'4 g'4 g'4 | a'4 a'4 g'2 | f'4 f'4 e'4 e'4 | d'4 d'4 c'2"
   end
 end
@@ -50,123 +53,107 @@ score.to_svg("twinkle.svg")
 score.to_midi("twinkle.mid")
 ```
 
-`title`, `composer`, and `tempo` are stored on the score. The current PDF and SVG renderers focus on staff content, while `tempo` is also used by MIDI export.
+`score.to_format("twinkle.svg")` chooses PDF, SVG, or MIDI from the file extension.
 
-## DSL Overview
+## DSL Essentials
 
-Clef's main entry point is `Clef.score`.
+Use `Clef.score` with one or more `staff` blocks. Inside a staff you can set notation state and add music with `play`:
 
-- `staff` creates a staff
-- `staff_group(:brace)` and `staff_group(:bracket)` group staves in the score model
-- `play` splits measures on `|`
-- `play` and `notes` accept LilyPond-like tokens such as `c'4`, `r8`, and `<c' e' g'>2.`
-- `voice` gives explicit control over notes, rests, and chords
-- `lyrics` attaches lyric data to a named voice
+```ruby
+score = Clef.score do
+  title "Example"
+  tempo beat_unit: :quarter, bpm: 96
 
-Example:
+  staff :violin, clef: :treble do
+    key :d, :major
+    time 3, 4
+    instrument 40
+
+    play "fis'4 g'4 a'4"
+    lyrics :default, "one two three"
+  end
+end
+```
+
+Common `play` tokens:
+
+- Notes: `c'4`, `fis'8`, `bes2`
+- Rests: `r4`, `r8`
+- Chords: `<c' e' g'>2`
+- Durations: `1`, `2`, `4`, `8`, `16`, with dotted values such as `4.`
+- Measure separators: `|`
+- Ties, slurs, articulations, and dynamics are supported in the lightweight DSL subset
+
+For multi-part scores, use multiple `staff` blocks or `staff_group`:
 
 ```ruby
 score = Clef.score do
+  title "Piano Sketch"
+
   staff_group :brace do
-    staff :piano_rh, clef: :treble do
+    staff :right, clef: :treble do
       key :c, :major
       time 4, 4
-      play "c'4 e'4 g'4 c''4"
+      play "c''4 e''4 g''4 c'''4"
     end
 
-    staff :piano_lh, clef: :bass do
+    staff :left, clef: :bass do
       key :c, :major
       time 4, 4
-
-      voice :main do
-        chord %w[c3 g3], :half
-        rest :half
-      end
+      play "c2 g,2"
     end
   end
 end
 ```
 
-Within a `voice` block, manual builders accept scientific pitch strings such as `C4`, `F#3`, and `Bb5`. The shorthand token parser used by `play` and `notes` expects LilyPond-style pitch tokens.
-
-## LilyPond Input
+## LilyPond-Style Input
 
-`Clef::Parser::LilypondParser` supports a small subset of LilyPond and turns it into a `Clef::Core::Score`.
+Clef can parse a practical subset of LilyPond-style input:
 
 ```ruby
 parser = Clef::Parser::LilypondParser.new
-
-score = parser.parse(<<~LY)
-  \clef treble
-  \key c \major
-  \time 4/4
-  { c'4 d'4 e'4 f'4 }
-LY
-
-score.to_svg("phrase.svg")
+score = parser.parse(<<~'LILYPOND')
+  \tempo 4 = 96
+  \new Staff {
+    \clef treble
+    \key c \major
+    \time 4/4
+    { c'4 d'4 e'4 f'4 | }
+  }
+LILYPOND
+
+warn parser.warnings.join("\n") unless parser.warnings.empty?
 ```
 
-The current parser recognizes:
-
-- `\clef`
-- `\key` with `\major` or `\minor`
-- `\time`
-- Note, rest, chord, and bar tokens inside `{ ... }`
+The importer supports tempo, staves, staff groups, clefs, key and time signatures, notes, rests, chords, a small relative pitch subset, simultaneous voices, dynamics, articulations, ties, slurs, beams, and measure splitting. Unsupported commands are skipped and reported as warnings with source locations.
 
 ## Plugins
 
-Clef exposes plugin hooks through `Clef.plugins`.
+Plugins can inspect or modify scores before rendering, and can observe rendering lifecycle events:
 
 ```ruby
-class MarkerPlugin < Clef::Plugins::Base
+class PreparedFlagPlugin < Clef::Plugins::Base
   def on_before_layout(score)
-    score.metadata[:prepared] = true
+    score.set_metadata(:prepared, true)
   end
 end
 
-Clef.plugins.register(MarkerPlugin)
+Clef.plugins.register(PreparedFlagPlugin)
 ```
 
-Available hooks:
-
-- `on_before_layout(score)`
-- `on_after_layout(layout_result)`
-- `on_before_render(renderer)`
-
-## Current Scope
-
-- PDF and SVG rendering currently cover clefs, key and time metadata, noteheads, rests, stems, accidentals, dots, chords, and simple articulation text.
-- PDF and SVG do not yet render score headers, lyric lines, ties, slurs, beams, or staff-group braces and brackets.
-- PDF, SVG, and MIDI export currently consume the first voice in each measure. The core model and IR can hold multiple voices, but full polyphonic engraving and playback are not wired into the output pipeline yet.
-- The compiler currently computes `Clef::Ir::MusicTree` and `Clef::Layout::Spacing` before rendering. `Clef::Layout::LineBreaker`, `PageBreaker`, and `BeamLayout` exist in the codebase as standalone building blocks and are covered by specs, but they are not yet integrated into PDF or SVG output.
+Common hooks are `on_before_layout`, `on_after_layout`, `on_before_render`, `on_after_render`, `on_after_parse`, `on_before_midi`, and `register_glyphs`.
 
 ## Development
 
-Install dependencies:
-
-```bash
+```sh
 bin/setup
-```
-
-Run the test suite:
-
-```bash
-bundle exec rspec
 bundle exec rake
-```
-
-Run an example:
-
-```bash
 bundle exec ruby examples/twinkle.rb
+bundle exec ruby exe/clef examples/twinkle.rb twinkle.svg
 ```
 
-Open a console:
-
-```bash
-bin/console
-```
+`bundle exec rake` runs specs, lint, syntax checks, and a gem build smoke test.
 
 ## License
 
-MIT License.
+Clef is available as open source under the terms of the MIT License.

data/Rakefile

@@ -2,9 +2,29 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rbconfig"
+require "tmpdir"
 
 RSpec::Core::RakeTask.new(:spec)
 
+desc "Run Standard Ruby lint"
+task :lint do
+  sh({"RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache"}, "bundle", "exec", "standardrb")
+end
+
+desc "Run Ruby syntax checks"
+task :syntax do
+  files = FileList["lib/**/*.rb", "spec/**/*.rb", "exe/*", "*.gemspec", "Rakefile"]
+  files.each { |file| sh RbConfig.ruby, "-c", file }
+end
+
+desc "Build the gem into a temporary directory"
+task :build_smoke do
+  Dir.mktmpdir do |dir|
+    sh "gem", "build", "clef.gemspec", "--output", File.join(dir, "clef.gem")
+  end
+end
+
 begin
   require "yard"
   YARD::Rake::YardocTask.new(:yard)
@@ -14,4 +34,4 @@ rescue LoadError
   end
 end
 
-task default: :spec
+task default: %i[spec lint syntax build_smoke]

data/exe/clef

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "clef"
+
+input, output = ARGV
+unless input && output
+  warn "usage: clef SCORE.rb OUTPUT.{pdf,svg,mid}"
+  exit 64
+end
+
+before = Clef.last_score
+load input, true
+score = Clef.last_score unless Clef.last_score.equal?(before)
+
+unless score.is_a?(Clef::Core::Score)
+  warn "input must build a Clef::Core::Score with Clef.score"
+  exit 65
+end
+
+score.to_format(output)

data/lib/clef/compiler.rb

@@ -16,8 +16,10 @@ module Clef
     def compile_to_pdf(path)
       layout = build_layout
       renderer = Clef::Renderer::PdfRenderer.new(style: @style)
+      @plugins.run_hook(:register_glyphs, renderer.glyph_table)
       @plugins.run_hook(:on_before_render, renderer)
-      renderer.render(@score, path, positions: layout[:positions])
+      renderer.render(@score, path, positions: layout[:positions], layout: layout)
+      @plugins.run_hook(:on_after_render, path)
       path
     end
 
@@ -26,8 +28,10 @@ module Clef
     def compile_to_svg(path)
       layout = build_layout
       renderer = Clef::Renderer::SvgRenderer.new(style: @style)
+      @plugins.run_hook(:register_glyphs, renderer.glyph_table)
       @plugins.run_hook(:on_before_render, renderer)
-      renderer.render(@score, path, positions: layout[:positions])
+      renderer.render(@score, path, positions: layout[:positions], layout: layout)
+      @plugins.run_hook(:on_after_render, path)
       path
     end
 
@@ -36,11 +40,110 @@ module Clef
     def build_layout
       @plugins.run_hook(:on_before_layout, @score)
       timeline = Clef::Ir::MusicTree.build(@score)
-      spacing = Clef::Layout::Spacing.new(timeline, @style)
+      timeline.sort!
+      layout_items = build_layout_items
+      plugin_items = @plugins.run_hook(:on_layout_items, layout_items).flatten.compact
+      layout_items.concat(plugin_items)
+      spacing = Clef::Layout::Spacing.new(timeline, @style, extra_moments: layout_items.map(&:moment))
+      spacing.stretch_to_fit(@style.line_width)
       positions = spacing.compute
-      layout = { timeline: timeline, spacing: spacing, positions: positions }
+      columns = build_columns(positions)
+      lines = Clef::Layout::LineBreaker.new.break_into_lines(columns, @style.line_width)
+      pages = Clef::Layout::PageBreaker.new.break_into_pages(
+        lines,
+        page_height: page_height,
+        line_height: @style.system_gap
+      )
+      layout = {
+        timeline: timeline,
+        spacing: spacing,
+        positions: positions,
+        columns: columns,
+        lines: lines,
+        pages: pages,
+        systems: Clef::Layout::SystemLayout.new(@score, pages: pages, positions: positions, style: @style).build,
+        items: layout_items,
+        beams: build_beams
+      }
       @plugins.run_hook(:on_after_layout, layout)
       layout
     end
+
+    def build_columns(positions)
+      sorted = positions.sort_by { |moment, _x| moment.value }
+      sorted.each_cons(2).map do |(moment, x), (_next_moment, next_x)|
+        {moment: moment, x: x, width: [next_x - x, @style.min_note_spacing].max, break_penalty: 0}
+      end + sorted.last(1).map do |moment, x|
+        {moment: moment, x: x, width: 0.0, break_penalty: 0}
+      end
+    end
+
+    def build_beams
+      @score.staves.to_h do |staff|
+        [staff.id, staff.measures.to_h { |measure| [measure.number, measure_beams(measure)] }]
+      end
+    end
+
+    def build_layout_items
+      @score.staves.flat_map do |staff|
+        current = Clef::Ir::Moment.new(0)
+        staff.measures.flat_map do |measure|
+          items = metadata_items(staff, measure, current)
+          current += measure_length_for(measure)
+          items << Clef::Layout::Item.new(type: :barline, moment: current, staff_id: staff.id,
+            measure_number: measure.number)
+          items
+        end
+      end
+    end
+
+    def metadata_items(staff, measure, moment)
+      [
+        Clef::Layout::Item.new(type: :clef, moment: moment, staff_id: staff.id,
+          measure_number: measure.number, payload: {clef: measure.clef || staff.clef}),
+        Clef::Layout::Item.new(type: :key_signature, moment: moment, staff_id: staff.id,
+          measure_number: measure.number, payload: {key_signature: measure.key_signature || staff.key_signature}),
+        Clef::Layout::Item.new(type: :time_signature, moment: moment, staff_id: staff.id,
+          measure_number: measure.number, payload: {time_signature: measure.time_signature || staff.time_signature})
+      ].reject { |item| item.payload.values.all?(&:nil?) }
+    end
+
+    def measure_length_for(measure)
+      return measure.time_signature.measure_length if measure.time_signature
+
+      measure.voices.values.map(&:total_length).max || Rational(0, 1)
+    end
+
+    def measure_beams(measure)
+      measure.voices.to_h do |voice_id, voice|
+        notes = beamable_notes(voice.elements)
+        groups = Clef::Layout::BeamLayout.auto_beam(notes, measure.time_signature || Clef::Core::TimeSignature.new(4, 4))
+        [voice_id, groups.select { |group| group.length > 1 }]
+      end
+    end
+
+    def beamable_notes(elements)
+      elements.flat_map do |element|
+        case element
+        when Clef::Core::Note
+          beamable_duration?(element.duration) ? [element] : []
+        when Clef::Core::Tuplet
+          beamable_notes(element.elements)
+        else
+          []
+        end
+      end
+    end
+
+    def beamable_duration?(duration)
+      %i[eighth sixteenth thirty_second sixty_fourth one_twenty_eighth two_fifty_sixth].include?(duration.base)
+    end
+
+    def page_height
+      case @style.page_size
+      when Array then @style.page_size.last.to_f - (@style.margin * 2)
+      else 760.0
+      end
+    end
   end
 end

data/lib/clef/core/chord.rb

@@ -11,7 +11,7 @@ module Clef
         validate_pitches!(pitches)
         raise ArgumentError, "duration must be a Clef::Core::Duration" unless duration.is_a?(Duration)
 
-        @pitches = pitches.sort
+        @pitches = Array(pitches).freeze
         @duration = duration
       end
 
@@ -20,14 +20,20 @@ module Clef
         duration.length
       end
 
+      # @return [Array<Pitch>]
+      def sorted_pitches
+        pitches.sort
+      end
+
       private
 
       def validate_pitches!(pitches)
         list = Array(pitches)
         raise ArgumentError, "pitches must not be empty" if list.empty?
-        return if list.all? { |pitch| pitch.is_a?(Pitch) }
+        raise ArgumentError, "all chord pitches must be Clef::Core::Pitch" unless list.all? { |pitch| pitch.is_a?(Pitch) }
+        return if list.map(&:semitones).uniq.length == list.length
 
-        raise ArgumentError, "all chord pitches must be Clef::Core::Pitch"
+        raise ArgumentError, "chord pitches must not contain duplicates"
       end
     end
   end

data/lib/clef/core/duration.rb

@@ -12,7 +12,9 @@ module Clef
         eighth: Rational(1, 8),
         sixteenth: Rational(1, 16),
         thirty_second: Rational(1, 32),
-        sixty_fourth: Rational(1, 64)
+        sixty_fourth: Rational(1, 64),
+        one_twenty_eighth: Rational(1, 128),
+        two_fifty_sixth: Rational(1, 256)
       }.freeze
       NUMBER_TO_BASE = {
         1 => :whole,
@@ -21,7 +23,9 @@ module Clef
         8 => :eighth,
         16 => :sixteenth,
         32 => :thirty_second,
-        64 => :sixty_fourth
+        64 => :sixty_fourth,
+        128 => :one_twenty_eighth,
+        256 => :two_fifty_sixth
       }.freeze
       BASE_TO_NUMBER = NUMBER_TO_BASE.invert.freeze
 
@@ -58,7 +62,7 @@ module Clef
 
       # @return [String]
       def to_lilypond
-        "#{BASE_TO_NUMBER.fetch(base)}#{'.' * dots}"
+        "#{BASE_TO_NUMBER.fetch(base)}#{"." * dots}"
       end
 
       # @param number [Integer]

data/lib/clef/core/key_signature.rb

@@ -4,43 +4,43 @@ module Clef
   module Core
     class KeySignature
       MAJOR_ACCIDENTALS = {
-        c: { count: 0, type: :natural },
-        g: { count: 1, type: :sharp },
-        d: { count: 2, type: :sharp },
-        a: { count: 3, type: :sharp },
-        e: { count: 4, type: :sharp },
-        b: { count: 5, type: :sharp },
-        fis: { count: 6, type: :sharp },
-        cis: { count: 7, type: :sharp },
-        f: { count: 1, type: :flat },
-        bes: { count: 2, type: :flat },
-        ees: { count: 3, type: :flat },
-        aes: { count: 4, type: :flat },
-        des: { count: 5, type: :flat },
-        ges: { count: 6, type: :flat },
-        ces: { count: 7, type: :flat }
+        c: {count: 0, type: :natural},
+        g: {count: 1, type: :sharp},
+        d: {count: 2, type: :sharp},
+        a: {count: 3, type: :sharp},
+        e: {count: 4, type: :sharp},
+        b: {count: 5, type: :sharp},
+        fis: {count: 6, type: :sharp},
+        cis: {count: 7, type: :sharp},
+        f: {count: 1, type: :flat},
+        bes: {count: 2, type: :flat},
+        ees: {count: 3, type: :flat},
+        aes: {count: 4, type: :flat},
+        des: {count: 5, type: :flat},
+        ges: {count: 6, type: :flat},
+        ces: {count: 7, type: :flat}
       }.freeze
       MINOR_ACCIDENTALS = {
-        a: { count: 0, type: :natural },
-        e: { count: 1, type: :sharp },
-        b: { count: 2, type: :sharp },
-        fis: { count: 3, type: :sharp },
-        cis: { count: 4, type: :sharp },
-        gis: { count: 5, type: :sharp },
-        dis: { count: 6, type: :sharp },
-        ais: { count: 7, type: :sharp },
-        d: { count: 1, type: :flat },
-        g: { count: 2, type: :flat },
-        c: { count: 3, type: :flat },
-        f: { count: 4, type: :flat },
-        bes: { count: 5, type: :flat },
-        ees: { count: 6, type: :flat },
-        aes: { count: 7, type: :flat }
+        a: {count: 0, type: :natural},
+        e: {count: 1, type: :sharp},
+        b: {count: 2, type: :sharp},
+        fis: {count: 3, type: :sharp},
+        cis: {count: 4, type: :sharp},
+        gis: {count: 5, type: :sharp},
+        dis: {count: 6, type: :sharp},
+        ais: {count: 7, type: :sharp},
+        d: {count: 1, type: :flat},
+        g: {count: 2, type: :flat},
+        c: {count: 3, type: :flat},
+        f: {count: 4, type: :flat},
+        bes: {count: 5, type: :flat},
+        ees: {count: 6, type: :flat},
+        aes: {count: 7, type: :flat}
       }.freeze
 
       attr_reader :tonic, :mode
 
-      # @param tonic [Pitch, Symbol]
+      # @param tonic [Pitch, Symbol, String]
       # @param mode [Symbol]
       def initialize(tonic, mode = :major)
         @tonic = normalize_tonic(tonic)
@@ -50,23 +50,30 @@ module Clef
 
       # @return [Hash]
       def accidentals
-        table = mode == :major ? MAJOR_ACCIDENTALS : MINOR_ACCIDENTALS
-        table.fetch(tonic_key) { { count: 0, type: :natural } }
+        table = (mode == :major) ? MAJOR_ACCIDENTALS : MINOR_ACCIDENTALS
+        table.fetch(tonic_key)
+      rescue KeyError
+        raise ArgumentError, "unsupported #{mode} key tonic: #{tonic.to_lilypond}"
+      end
+
+      # @return [Symbol]
+      def preferred_transpose_spelling
+        (accidentals[:type] == :flat) ? :flat : :sharp
       end
 
       private
 
       def normalize_tonic(tonic)
         return tonic if tonic.is_a?(Pitch)
-        return Pitch.new(tonic, 4) if tonic.is_a?(Symbol)
+        return Pitch.parse_any(tonic) if tonic.is_a?(Symbol) || tonic.is_a?(String)
 
-        raise ArgumentError, "tonic must be a Pitch or Symbol"
+        raise ArgumentError, "tonic must be a Pitch, Symbol, or String"
       end
 
       def tonic_key
         base = tonic.note_name.to_s
         suffix = tonic.alteration.positive? ? "is" * tonic.alteration : "es" * tonic.alteration.abs
-        "#{base}#{suffix}".to_sym
+        :"#{base}#{suffix}"
       end
 
       def validate_mode!(mode)

data/lib/clef/core/measure.rb

@@ -3,7 +3,7 @@
 module Clef
   module Core
     class Measure
-      attr_reader :number, :voices
+      attr_reader :number
       attr_accessor :key_signature, :time_signature, :clef
 
       # @param number [Integer]
@@ -20,26 +20,30 @@ module Clef
       # @yield [Voice]
       # @return [Voice]
       def voice(id = :default)
-        current = voices[id] ||= Voice.new(id: id)
+        current = @voices[id] ||= Voice.new(id: id)
         yield(current) if block_given?
-        warn_overflow_if_needed(id, current)
         current
       end
 
+      # @return [Hash<Symbol, Voice>]
+      def voices
+        @voices.dup.freeze
+      end
+
       # @return [Array<Symbol>]
       def overflowing_voice_ids
         return [] unless time_signature
 
-        voices.filter_map { |id, voice| id if voice.total_length > time_signature.measure_length }
+        @voices.filter_map { |id, voice| id if voice.total_length > time_signature.measure_length }
       end
 
-      private
-
-      def warn_overflow_if_needed(id, voice)
-        return unless time_signature
-        return unless voice.total_length > time_signature.measure_length
+      # @return [Array<Symbol>]
+      def underfull_voice_ids
+        return [] unless time_signature
 
-        warn("Measure #{number} voice #{id} exceeds time signature length")
+        @voices.filter_map do |id, voice|
+          id if voice.total_length.positive? && voice.total_length < time_signature.measure_length
+        end
       end
     end
   end