head_music 20.0.0 → 20.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8a5d592c5994e59585e09db272d554d2aefcef0f337287ee0fd0206cbab498c
-  data.tar.gz: '0964c0d8e7ec6a753886ab34131705daacb51eefffc79f48d281ca6663099a4d'
+  metadata.gz: b3714d51858bd368308d14a5f12544e6f4fb9dbecf0f0eacc1ad795c5e4b3d1e
+  data.tar.gz: 99345ffa2b44dfbdc27836b7b7350a38af1665770a74490f52e22bd1a0aa3602
 SHA512:
-  metadata.gz: dafb4e6534d8985a4563a650e141f61d652b40a76e7adf2d3ce7d8820ce5f41038dc1754f893b18756a2f30192813b8e752899656b6abab5bc5dd073a732abad
-  data.tar.gz: cdd300bd23ca8bbe011f7712385d7b7d80cebb99eae61281bc24049c01f535069116eff46a46fe296acf0c846f3a7e4a36d59562d5c03cb29a4ed4c7d5930ede
+  metadata.gz: d95aa74479fe498564dc7e1bc5427660b9687e286a31a4b5cbbb1c0a274bebe9413ae18e2176dbbf38c351e4b1517275d5bf8dce590642c88c2301ea83f038b6
+  data.tar.gz: 4446808775faf30ef42dceca7de10248a88d8c8265ab4faa3c11589bd6ddb7dd60ff9c10ce2cb34a68f9e039061bc3633484e01b2002f649bb3f885bd5d7e968

data/.github/workflows/ci.yml

@@ -6,14 +6,39 @@ on:
   pull_request:
     branches: [ main ]
 
+permissions:
+  contents: read
+
+# A rebase flow means force-pushes are routine; without this, each one leaves
+# the superseded run burning minutes alongside its replacement.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   test:
+    name: test (ruby ${{ matrix.ruby-version }}, activesupport ${{ matrix.activesupport-version || 'latest' }})
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.3', '3.4']
-        activesupport-version: ['7.2', '8.0']
+        # The corners of the supported range rather than a full cross product.
+        # An empty activesupport-version installs from the lockfile, covering
+        # the newest release the gemspec allows; ActiveSupport 7.2 is not
+        # paired with Ruby 4.0, which it predates.
+        include:
+          - ruby-version: '3.3'
+            activesupport-version: '7.2'
+          - ruby-version: '3.3'
+            activesupport-version: ''
+            coverage: true
+          - ruby-version: '3.4'
+            activesupport-version: '7.2'
+          - ruby-version: '3.4'
+            activesupport-version: '8.0'
+          - ruby-version: '4.0'
+            activesupport-version: ''
 
     steps:
     - uses: actions/checkout@v7
@@ -24,31 +49,90 @@ jobs:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: false
 
-    - name: Install dependencies with ActiveSupport ${{ matrix.activesupport-version }}
+    - name: Install dependencies with ActiveSupport ${{ matrix.activesupport-version || 'latest' }}
+      env:
+        ACTIVESUPPORT_VERSION: ${{ matrix.activesupport-version }}
       run: |
         bundle config set --local path vendor/bundle
-        ACTIVESUPPORT_VERSION="${{ matrix.activesupport-version }}" bundle install
+        bundle install
 
     - name: Run tests
       run: bundle exec rspec
 
     - name: Upload coverage to Codecov
-      if: matrix.ruby-version == '3.3' && matrix.activesupport-version == '8.0'
+      if: matrix.coverage
       uses: codecov/codecov-action@v7
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         fail_ci_if_error: false
         verbose: true
 
+  # Months of warning about upcoming Ruby releases, without a red check that
+  # blocks a merge.
+  test-ruby-head:
+    name: test (ruby-head, advisory)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    env:
+      # Bundler otherwise switches to the lockfile's BUNDLED WITH, and 2.7.2
+      # raises "uninitialized constant Pathname::SEPARATOR_PAT" on a Ruby this
+      # new. A bundler bug is not the breakage this job exists to find.
+      BUNDLE_VERSION: system
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Set up Ruby head
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: head
+        bundler: latest
+        bundler-cache: false
+
+    - name: Install dependencies
+      run: |
+        bundle config set --local path vendor/bundle
+        bundle install
+
+    - name: Run tests
+      run: bundle exec rspec
+
+  # The LilyPond specs treat the real binary as an oracle and skip when none is
+  # installed, so without this job nothing proves the rendered documents
+  # actually compile. Runs the whole suite because SimpleCov's minimum applies
+  # to any rspec invocation.
+  test-lilypond:
+    name: test (with the lilypond toolchain)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install LilyPond
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y lilypond
+        lilypond --version
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: .ruby-version
+        bundler-cache: true
+
+    - name: Run tests
+      run: bundle exec rspec
+
   lint:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
     - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
     - name: Run RuboCop
@@ -56,13 +140,14 @@ jobs:
 
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
     - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
     - name: Build gem
@@ -71,4 +156,4 @@ jobs:
     - name: Check gem
       run: |
         gem install *.gem
-        gem specification *.gem
+        gem specification *.gem

data/.github/workflows/release.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     permissions:
       contents: write
       id-token: write
@@ -18,7 +19,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
     - name: Run tests
@@ -38,12 +39,12 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+    # Trusted publishing: RubyGems exchanges this job's OIDC token for a
+    # short-lived credential, so there is no API key to store or rotate.
+    # Requires head_music to have this workflow registered as a trusted
+    # publisher at rubygems.org/gems/head_music/trusted_publishers.
+    - name: Configure RubyGems credentials
+      uses: rubygems/configure-rubygems-credentials@v2
+
     - name: Publish to RubyGems
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem push *.gem
-      env:
-        GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+      run: gem push *.gem

data/.github/workflows/security.yml

@@ -10,9 +10,17 @@ on:
     - cron: '0 9 * * *'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   security:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
 
     steps:
     - uses: actions/checkout@v7
@@ -20,14 +28,8 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
-    - name: Install bundler-audit
-      run: gem install bundler-audit
-
     - name: Run bundler-audit
-      run: bundle-audit check --update
-
-    - name: Run RuboCop Security
-      run: bundle exec rubocop --only Security
+      run: bundle exec bundle-audit check --update

data/.rubocop.yml

@@ -15,6 +15,14 @@ AllCops:
     - vendor/**/*
   TargetRubyVersion: 3.3.0
 
+# Off in standard's config, so the lint job missed them; the security
+# workflow's "--only Security" pass was the only thing covering them.
+Security/IoMethods:
+  Enabled: true
+
+Security/MarshalLoad:
+  Enabled: true
+
 RSpec:
   Enabled: true
 

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [20.1.0] - 2026-09-05
+
+The other half of the LilyPond export released in 20.0.0. A document written by the writer, or by hand, now reads back into a composition, so `parse(render(composition))` reproduces the music. Nothing in 20.0.0 changed shape; a consumer upgrades by upgrading.
+
+### Added
+
+- **LilyPond import.** `HeadMusic::Notation::LilyPond.parse(string)` reads a LilyPond document, or a bare music expression, into a `Content::Composition`: absolute and `\relative` pitches with `is`/`es` accidentals and Dutch contractions, durations with dots and carry-over, rests and whole-bar rests, chords, intra-bar ties, `\key`, `\time` (including mid-piece changes), `\clef`, bar checks, `\header` title and composer, and `\new Staff` / `\new Voice` contexts with `instrumentName` as the voice role. Everything the LilyPond writer emits reads back, so `parse(render(composition))` reproduces the music. `\version`, `\layout`, and `\midi` blocks are skipped whole, as are the header fields the reader does not use, so the Scheme in an everyday engraving preamble costs nothing. A bar-check mismatch raises `LilyPond::ParseError`; constructs outside the subset raise `LilyPond::UnsupportedFeatureError` rather than being skipped.
+- `HeadMusic::Notation::DottedDuration.rhythmic_value_for(fraction)`, the inverse of `dotted_unit_fraction`, shared by the ABC and LilyPond readers.
+
+### Changed
+
+- **Placing a note no longer costs time linear in the voice's length.** `Content::Voice#place` scanned its placements from the front twice — once for a placement already at the position, once for the insertion point — so filling a long voice was quadratic in its length. Both are now binary searches over the position order the list already keeps. Reading a 28KB LilyPond score went from 76 seconds to under 9; the remaining time is in `Content::Position` arithmetic rather than here.
+
 ## [20.0.0] - 2026-08-30
 
 The [style assessment model](https://github.com/roberthead/head_music/tree/main/user-stories/epics/style-assessment-model.md) epic, released together. Five stories reshaped how a guide is declared, how it grades, what it says, and what a consumer asks for — so the breaking changes below are one migration rather than five. Two notation stories ride along: LilyPond export, and note values named in each reader's own language.
@@ -716,7 +731,8 @@ note = HeadMusic::Rudiment::Note.get("F#4 dotted-quarter")
 
 For changes in versions prior to 0.28.0, please refer to the git history.
 
-[Unreleased]: https://github.com/roberthead/head_music/compare/v20.0.0...HEAD
+[Unreleased]: https://github.com/roberthead/head_music/compare/v20.1.0...HEAD
+[20.1.0]: https://github.com/roberthead/head_music/compare/v20.0.0...v20.1.0
 [20.0.0]: https://github.com/roberthead/head_music/compare/v19.0.0...v20.0.0
 [19.0.0]: https://github.com/roberthead/head_music/compare/v18.0.0...v19.0.0
 [18.0.0]: https://github.com/roberthead/head_music/compare/v17.5.0...v18.0.0
@@ -764,4 +780,4 @@ For changes in versions prior to 0.28.0, please refer to the git history.
 [2.0.0]: https://github.com/roberthead/head_music/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/roberthead/head_music/compare/v0.29.0...v1.0.0
 [0.29.0]: https://github.com/roberthead/head_music/compare/v0.28.0...v0.29.0
-[0.28.0]: https://github.com/roberthead/head_music/releases/tag/v0.28.0
+[0.28.0]: https://github.com/roberthead/head_music/releases/tag/v0.28.0

data/Gemfile

@@ -5,10 +5,11 @@ ruby ">= 3.3.0"
 # Specify your gem's dependencies in head_music.gemspec
 gemspec
 
-# Allow CI to test against specific ActiveSupport versions
-if ENV["ACTIVESUPPORT_VERSION"]
-  gem "activesupport", "~> #{ENV["ACTIVESUPPORT_VERSION"]}.0"
-end
+# Allow CI to test against specific ActiveSupport versions. An unset or empty
+# value leaves the gemspec range alone -- empty is truthy in Ruby, so a matrix
+# cell that sets the key to "" would otherwise resolve against "~> .0".
+activesupport_version = ENV["ACTIVESUPPORT_VERSION"].to_s
+gem "activesupport", "~> #{activesupport_version}.0" unless activesupport_version.empty?
 
 gem "standard", require: false
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (20.0.0)
+    head_music (20.1.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)
@@ -216,7 +216,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  bundler-audit
+  bundler-audit (~> 0.9, >= 0)
   head_music!
   kramdown
   rake (~> 13.0)
@@ -228,10 +228,10 @@ DEPENDENCIES
   rubycritic
   simplecov (< 1.1)
   standard
-  yard
+  yard (~> 0.9, >= 0)
 
 RUBY VERSION
-   ruby 3.3.0p0
+  ruby 3.3.0p0
 
 BUNDLED WITH
-   2.4.12
+  4.0.20

data/README.md

@@ -14,6 +14,7 @@ The **head_music** Ruby gem provides a toolkit for working with Western music th
 - **Style Analysis**: Rules for species counterpoint and voice leading
 - **Internationalization**: Support for multiple languages (English, French, German, Italian, Russian, Spanish)
 - **Instrument Modeling**: Extensive database of musical instruments with ranges and properties
+- **Notation Formats**: Read ABC and LilyPond into compositions; write compositions as ABC, LilyPond, and MusicXML
 
 ## Installation
 
@@ -50,8 +51,21 @@ puts scale.pitches.map(&:to_s)  # => ["C4", "D4", "E4", "F4", "G4", "A4", "B4"]
 pitches = %w[C4 E4 G4].map { |p| HeadMusic::Rudiment::Pitch.get(p) }
 chord = HeadMusic::Analysis::PitchSet.new(pitches)
 puts chord.major_triad?  # => true
+
+# Import a LilyPond excerpt as a composition
+composition = HeadMusic::Notation::LilyPond.parse(<<~'LILY')
+  \relative c' {
+    \key g \major
+    \time 4/4
+    g8 a b c d c b g |
+  }
+LILY
+puts composition.voices.first.pitches.map(&:to_s)  # => ["G3", "A3", "B3", "C4", "D4", "C4", "B3", "G3"]
+puts composition.to_lilypond                        # => a complete LilyPond document
 ```
 
+The LilyPond reader covers absolute and `\relative` pitches, durations and dots, rests and whole-bar rests, chords, intra-bar ties, `\key`, `\time`, `\clef`, bar checks, `\header` title and composer, and `\new Staff` / `\new Voice` contexts. Constructs outside that subset (tuplets, lyrics, variables, articulations, and so on) raise an `UnsupportedFeatureError` rather than being skipped.
+
 ## Style Analysis
 
 Look up a style guide by key and analyze a voice against it. `Style::Guide.get` returns `nil` for an

data/lib/head_music/content/voice.rb

@@ -95,14 +95,21 @@ class HeadMusic::Content::Voice
   end
 
   def placement_at(position)
-    placements.find { |placement| placement.position == position }
+    candidate = placements.bsearch { |placement| placement.position >= position }
+    candidate if candidate&.position == position
   end
 
   # Positions are unique within a voice (place merges same-position
-  # placements), so insertion order is simply position order.
+  # placements), so insertion order is simply position order. Both the
+  # lookup and the insertion point are binary searches over that order,
+  # which keeps placing a long voice linear in its length rather than
+  # quadratic.
+  def insertion_index(placement)
+    placements.bsearch_index { |existing| existing > placement } || placements.length
+  end
+
   def insert_into_placements(placement)
-    index = placements.index { |existing| existing > placement } || placements.length
-    placements.insert(index, placement)
+    placements.insert(insertion_index(placement), placement)
   end
 
   def pitches_string

data/lib/head_music/notation/abc/duration_resolver.rb

@@ -3,14 +3,7 @@ module HeadMusic::Notation::ABC
   # Converts the tune's unit note length and a per-note multiplier string
   # (e.g. "2", "3/2", "/", "//") into a HeadMusic::Rudiment::RhythmicValue.
   class DurationResolver
-    # Longest supported duration: a maxima (8 whole notes).
-    MAX_FRACTION = Rational(8)
-
-    # A reduced binary fraction's odd factor determines the dot count:
-    # 1 -> plain, 3 -> dotted, 7 -> double-dotted, 15 -> triple-dotted.
-    DOTS_BY_ODD_FACTOR = {1 => 0, 3 => 1, 7 => 2, 15 => 3}.freeze
-
-    UNIT_NAMES_BY_MULTIPLE = {1 => "whole", 2 => "double whole", 4 => "longa", 8 => "maxima"}.freeze
+    MAX_FRACTION = HeadMusic::Notation::DottedDuration::MAX_FRACTION
 
     MULTIPLIER_PATTERN = %r{\A(\d+)?(?:(/+)(\d+)?)?\z}
 
@@ -25,7 +18,8 @@ module HeadMusic::Notation::ABC
     def rhythmic_value(multiplier_string, scale: Rational(1))
       fraction = unit_note_length * multiplier(multiplier_string) * scale
       validate_fraction!(fraction, multiplier_string)
-      build_rhythmic_value(fraction, multiplier_string)
+      HeadMusic::Notation::DottedDuration.rhythmic_value_for(fraction) ||
+        raise_error("no rhythmic unit for a note length of #{fraction}", multiplier_string)
     end
 
     # The bare fraction a length string denotes (e.g. "2" -> 2, "/2" -> 1/2,
@@ -61,65 +55,11 @@ module HeadMusic::Notation::ABC
     def validate_fraction!(fraction, source)
       raise_error("note length must be positive", source) if fraction <= 0
       raise_error("note length exceeds #{MAX_FRACTION.to_i} whole notes", source) if fraction > MAX_FRACTION
-      return if power_of_two?(fraction.denominator)
+      return if HeadMusic::Notation::DottedDuration.power_of_two?(fraction.denominator)
 
       raise_error("note length #{fraction} is not expressible in binary note values", source)
     end
 
-    # Fractions whose odd factor is one less than a power of two map onto a
-    # single (possibly dotted) note; anything else becomes a chain of tied notes,
-    # peeling off the largest dotted-expressible head each pass.
-    def build_rhythmic_value(fraction, source)
-      dots = DOTS_BY_ODD_FACTOR[odd_factor(fraction.numerator)]
-      return single_value(fraction, dots, source) if dots
-
-      head = greedy_head(fraction)
-      tail = build_rhythmic_value(fraction - head, source)
-      single_value(head, DOTS_BY_ODD_FACTOR.fetch(odd_factor(head.numerator)), source, tied_value: tail)
-    end
-
-    def single_value(fraction, dots, source, tied_value: nil)
-      # A value with d dots spans (2^(d+1) - 1) / 2^d of its unit.
-      unit_fraction = fraction * Rational(2**dots, (2**(dots + 1)) - 1)
-      HeadMusic::Rudiment::RhythmicValue.new(unit_for(unit_fraction, source), dots: dots, tied_value: tied_value)
-    end
-
-    # The largest leading run of set bits (capped at four, i.e. triple-dotted)
-    # forms a dotted-expressible head for the tied-value decomposition.
-    def greedy_head(fraction)
-      numerator = fraction.numerator
-      bits = numerator.bit_length
-      run = leading_set_bits(numerator, bits)
-      Rational(((1 << run) - 1) << (bits - run), fraction.denominator)
-    end
-
-    # Length of the leading run of set bits, capped at four (triple-dotted).
-    def leading_set_bits(numerator, bits)
-      run = 0
-      run += 1 while run < 4 && run < bits && numerator[bits - 1 - run] == 1
-      run
-    end
-
-    def unit_for(unit_fraction, source)
-      unit = if unit_fraction >= 1
-        name = UNIT_NAMES_BY_MULTIPLE[unit_fraction.numerator]
-        name && HeadMusic::Rudiment::RhythmicUnit.get(name)
-      else
-        HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(unit_fraction.denominator)
-      end
-      raise_error("no rhythmic unit for a note length of #{unit_fraction}", source) unless unit
-      unit
-    end
-
-    def odd_factor(integer)
-      integer >>= 1 while integer.even?
-      integer
-    end
-
-    def power_of_two?(integer)
-      (integer & (integer - 1)).zero?
-    end
-
     def raise_error(message, source)
       raise HeadMusic::Notation::ABC::ParseError.new(message, snippet: source)
     end

data/lib/head_music/notation/abc/voice_state.rb

@@ -146,16 +146,7 @@ module HeadMusic::Notation::ABC
     def pending_rhythmic_value(pending)
       own = @duration_resolver.rhythmic_value(pending.length, scale: pending.scale)
       prefix = pending.tied_prefix
-      prefix ? append_tied(prefix, own) : own
-    end
-
-    # Attaches `tail` at the deep end of `head`'s tied chain, rebuilding
-    # each link (RhythmicValue exposes no setter) so a chain like
-    # "half tied to eighth" gains a further "tied to quarter".
-    def append_tied(head, tail)
-      tied = head.tied_value
-      inner = tied ? append_tied(tied, tail) : tail
-      HeadMusic::Rudiment::RhythmicValue.new(head.unit, dots: head.dots, tied_value: inner)
+      prefix ? prefix.append_tied(own) : own
     end
   end
 end

data/lib/head_music/notation/dotted_duration.rb

@@ -1,11 +1,21 @@
 module HeadMusic
   module Notation
     # The exact fractional length of a (possibly dotted) rhythmic value in
-    # terms of its own unit. RhythmicValue's own value methods return Floats,
+    # terms of its own unit, and the inverse: the rhythmic value a fraction of
+    # a whole note denotes. RhythmicValue's own value methods return Floats,
     # so the fraction is rebuilt here from the unit's integer numerator and
     # denominator to keep downstream arithmetic (ABC multipliers, MusicXML
-    # divisions) exact.
+    # divisions, LilyPond bar sums) exact.
     module DottedDuration
+      # Longest supported duration: a maxima (8 whole notes).
+      MAX_FRACTION = Rational(8)
+
+      # A reduced binary fraction's odd factor determines the dot count:
+      # 1 -> plain, 3 -> dotted, 7 -> double-dotted, 15 -> triple-dotted.
+      DOTS_BY_ODD_FACTOR = {1 => 0, 3 => 1, 7 => 2, 15 => 3}.freeze
+
+      UNIT_NAMES_BY_MULTIPLE = {1 => "whole", 2 => "double whole", 4 => "longa", 8 => "maxima"}.freeze
+
       module_function
 
       def dotted_unit_fraction(rhythmic_value)
@@ -14,6 +24,75 @@ module HeadMusic
         # A value with d dots spans (2^(d+1) - 1) / 2^d of its own unit.
         Rational(unit.numerator, unit.denominator) * Rational((2**(dots + 1)) - 1, 2**dots)
       end
+
+      # The rhythmic value spanning a fraction of a whole note, or nil when no
+      # binary note value (or tied chain of them) can express it.
+      def rhythmic_value_for(fraction)
+        fraction = Rational(fraction)
+        return unless expressible?(fraction)
+
+        build_rhythmic_value(fraction)
+      end
+
+      def expressible?(fraction)
+        fraction.positive? && fraction <= MAX_FRACTION && power_of_two?(fraction.denominator)
+      end
+
+      # Fractions whose odd factor is one less than a power of two map onto a
+      # single (possibly dotted) note; anything else becomes a chain of tied notes,
+      # peeling off the largest dotted-expressible head each pass.
+      def build_rhythmic_value(fraction)
+        dots = DOTS_BY_ODD_FACTOR[odd_factor(fraction.numerator)]
+        return single_value(fraction, dots) if dots
+
+        head = greedy_head(fraction)
+        tail = build_rhythmic_value(fraction - head)
+        return unless tail
+
+        single_value(head, DOTS_BY_ODD_FACTOR.fetch(odd_factor(head.numerator)), tied_value: tail)
+      end
+
+      def single_value(fraction, dots, tied_value: nil)
+        # A value with d dots spans (2^(d+1) - 1) / 2^d of its unit.
+        unit = unit_for(fraction * Rational(2**dots, (2**(dots + 1)) - 1))
+        return unless unit
+
+        HeadMusic::Rudiment::RhythmicValue.new(unit, dots: dots, tied_value: tied_value)
+      end
+
+      # The largest leading run of set bits (capped at four, i.e. triple-dotted)
+      # forms a dotted-expressible head for the tied-value decomposition.
+      def greedy_head(fraction)
+        numerator = fraction.numerator
+        bits = numerator.bit_length
+        run = leading_set_bits(numerator, bits)
+        Rational(((1 << run) - 1) << (bits - run), fraction.denominator)
+      end
+
+      # Length of the leading run of set bits, capped at four (triple-dotted).
+      def leading_set_bits(numerator, bits)
+        run = 0
+        run += 1 while run < 4 && run < bits && numerator[bits - 1 - run] == 1
+        run
+      end
+
+      def unit_for(unit_fraction)
+        if unit_fraction >= 1
+          name = UNIT_NAMES_BY_MULTIPLE[unit_fraction.numerator]
+          name && HeadMusic::Rudiment::RhythmicUnit.get(name)
+        else
+          HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(unit_fraction.denominator)
+        end
+      end
+
+      def odd_factor(integer)
+        integer >>= 1 while integer.even?
+        integer
+      end
+
+      def power_of_two?(integer)
+        (integer & (integer - 1)).zero?
+      end
     end
   end
 end