head_music 17.4.0 → 18.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d075fb623ea50351c7ac422f44be04c265867253312b6b27faffaf76bb3b397
-  data.tar.gz: 5649553e987c0a98cd9388d24d6e15155f88da4e59eaf62f7a2d9f988e656b36
+  metadata.gz: 8a16868734e2fac408461d2202fcbc84be2a796a68371a81a7d2ad5bbeef516b
+  data.tar.gz: 02becc93275629796177a72894d81cc10feca0819847496e60aa3ddc6f5aac00
 SHA512:
-  metadata.gz: a89a0dfc44c68e823e5c1eff6c48b950b759cdd059c504adacd8bd6b3d06dc0b23bc1a13b690e68086526a33ab3bebc1617825abecfc3ab108c89425a44d6f55
-  data.tar.gz: 921ce718ccc4b728ed57dce347fbce73ae7c120960931b32933a5893f52992b4aa40ec115e248421a3f53d3a66defff0b4d7eac15efaf34ae51fae23e5e2a328
+  metadata.gz: e3533678a1a2b58558080cad6c03f04fe4b5b205d4413456b728c5ae2e1a598e3a09ebc0329c9f6fde263e84f857eb4571918087afe23a083278facaea7aa460
+  data.tar.gz: 3d605bff3a0459e56cddd4911e7699d2b295bf337e7f468094d0f4cc19e55f9b3036c21e59c95263f3bf19c69dfffa99093a8564f036aa625b776199e959e8f4

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         activesupport-version: ['7.2', '8.0']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
@@ -43,7 +43,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -57,7 +57,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
       id-token: write
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/security.yml

@@ -8,13 +8,14 @@ on:
   schedule:
     # Run security checks daily at 9 AM UTC
     - cron: '0 9 * * *'
+  workflow_dispatch:
 
 jobs:
   security:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.rubocop.yml

@@ -31,6 +31,12 @@ RSpec/ContextWording:
 RSpec/MultipleExpectations:
   Enabled: false
 
+# Several data-driven specs build examples from collections resolved at
+# definition time (e.g. `legacy.each`, `melodic_guides.each`), which requires
+# those values to live as locals in the example-group scope.
+RSpec/LeakyLocalVariable:
+  Enabled: false
+
 RSpec/NestedGroups:
   Max: 5
 

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [18.0.0] - 2026-07-27
+
+### Added
+
+- `HeadMusic::Utilities::Accidentals` converts accidentals in a string between ASCII spellings and canonical unicode glyphs, replacing the hand-rolled `gsub` and `tr` chains that were scattered across the gem and disagreed with each other. `.to_unicode` converts whole chord symbols rather than bare pitch names — `Bbmaj7#11` becomes `B♭maj7♯11` — and `.to_ascii` converts back, emitting the spellings the gem's own parsers accept (`x` for a double sharp, never `##`). Both directions are idempotent, and conversion is all-or-nothing per accidental so a double never half-converts.
+- The forward direction is safe to run over prose. Conversion happens only inside a candidate chord token, an uppercase letter name that does not continue a longer word or number, so `Above`, `Bebop`, `1.0b2`, and `0x1B2F` are untouched while `Bb`, `Ab7`, `Bbm`, and `Ebmaj7` convert. A chord-quality allowlist rescues `Bbm` and `Ebmaj7` from the word-boundary guard that protects `Above`; the allowlist was measured against a full system word list and is pinned by a spec that sweeps it.
+- `##` is now accepted everywhere `bb` already was, ending the asymmetry between the two doubles. `Alteration.get("##")` resolves to `double_sharp` and `Spelling.get("C##")` returns `C𝄪`.
+- The utility is deliberately narrower than `Spelling` and `Pitch` in two ways, both consequences of being safe to run over prose. It is case-sensitive, because a case-insensitive rule reads the `B` of `B7` as a flat sign — so `to_unicode("eb")` is `"eb"` while `Spelling.get("eb")` is `E♭`. And a bare token is read as an accidental rather than a pitch name — `to_unicode("bb")` is `𝄫`, the double-flat sign, while `Spelling.get("bb")` is `B♭`. Parse with `Spelling` first when a pitch name may be lowercase. `to_ascii` preserves `♮` for the same reason: dropping it would turn the valid spelling `C♮` into the different spelling `C`.
+
+### Changed
+
+- **Breaking.** `Spelling.get("C##")` returns a `Spelling` instead of `nil`, and the same widening applies to `Pitch`, `Note`, `KeySignature`, and ABC `K:` fields. Code that treated that `nil` as a validation signal now silently accepts double sharps.
+- **Breaking.** `Alteration::PATTERN`, `Alteration::MATCHER`, and `Alteration::SYMBOLS` gain `##` and are now sorted longest-first so that a two-character spelling always matches before its one-character prefix. Code embedding these in its own regular expressions will see different matches.
+- **Breaking.** `Alteration.symbols` now returns `SYMBOLS` rather than a separately derived list that disagreed with it.
+- **Breaking.** `Utilities::HashKey` normalizes ASCII accidentals before mapping them to word suffixes, so ASCII and unicode spellings of the same accidental now produce the same key. Previously it handled ASCII `#` but not ASCII `b`, so `"C#"` keyed to `:c_sharp` while `"Bb"` keyed to `:bb`. Now `"Bb"` keys to `:b_flat`, `"Bbb"` to `:b_double_flat`, and `"Cx"` to `:c_double_sharp`. Words containing those letters are unaffected — `:bass_clarinet` and `:blues_major_pentatonic` are unchanged — because normalization goes through the prose-safe `Utilities::Accidentals` rather than a bare substitution. The glyph-to-word table is now derived from `Alteration` rather than hard-coded, leaving `alterations.yml` as the single inventory.
+- `Utilities::HashKey` is class-methods-only, matching `Utilities::Case`. `.new` and `#to_sym` are gone; `.for` was already the only entry point in use. The per-instance memo they wrapped could never be hit twice, since each instance was discarded after one call.
+- **Breaking.** `Analysis::Dyad` gains double sharps in its enharmonic universe, which were previously built as candidates and then silently discarded by the parser. Candidate spellings grow from 28 to 35, and a major third gains three respellings.
+- **Breaking.** `Rudiment::Scale::SCALE_REGEX` is removed. It was unreferenced, and its singles-only `[#b]?` was an instance of the asymmetry this release closes.
+- **Breaking.** `KeySignature` and `Scale` memoization keys change for identifiers containing accidentals. `Fx`, `C##`, and `F𝄪` now unify onto one cache entry, as they name the same key signature.
+- `Rudiment::Note::PITCH_PATTERN` no longer truncates a double sharp. `"C##4"` previously parsed as `["C", "#", nil]`, silently losing the register, because the optional quantifier bound to the pattern's final alternative rather than to the whole alternation.
+- `Alteration#representations` now spans every symbol record rather than only the primary one, so a double sharp reports `"##"` alongside `"x"` and `𝄪`. It also accepts a `locale_code:` keyword and memoizes per locale, since the list includes the localized `#name`.
+- An ABC `K:` field naming a double-altered tonic still raises `ParseError`, but with a message that says so — `Cannot express double-altered tonic Cx in an ABC K: field` rather than the incidental `Unrecognized mode` it produced when the narrower key pattern failed to match the accidental.
+
+### Removed
+
+- `Content::Staff` no longer prints to standard output when it cannot resolve a clef key. It previously wrote `Warning: Clef '...' not found.` and `Using instrument clef.` to stdout. The fallback behavior is unchanged — an unrecognized key still resolves to the instrument's clef when an instrument is present, and to the treble clef otherwise — it is simply no longer announced.
+
+## [17.5.0] - 2026-07-21
+
+### Added
+
+- Sung text (lyrics) can be attached to the notes of a voice. `HeadMusic::Content::Placement#sing(text, verse:, hyphen_after:)` assigns a syllable to a placement, keyed by verse so a note carries at most one syllable per verse and any number of verses (`glo` on verse 1, `peace` on verse 2 of the same note). A new immutable `HeadMusic::Content::Syllable` value object stores only the minimal linguistic fact — `text`, `verse`, and a `hyphen_after` boolean marking that the word continues onto the next sung note; the MusicXML `syllabic` value (`single`/`begin`/`middle`/`end`) is derived at render time rather than stored, and a melisma is represented by the absence of a syllable on the held notes rather than a stored flag. Syllables serialize through `Placement#to_h` and round-trip through the composition hash deserializer, validated at the import boundary by `Composition::SchemaValues` (non-empty text, a positive-integer verse, and no duplicate verse per placement).
+- The MusicXML writer emits a `<lyric number="N">` element as the last child of each `<note>`, on the lead note of a chord only and the attack of a tied chain only, deriving `<syllabic>` from the `hyphen_after` booleans of the syllable and its predecessor in the same verse and XML-escaping the text. Held notes of a melisma carry no `<lyric>`, matching MusicXML's continuation-by-absence. ABC `w:` lyric-line input and the MusicXML `<extend/>` melisma line remain out of scope for a future release.
+
 ## [17.4.0] - 2026-07-20
 
 ### Changed

data/CLAUDE.md

@@ -150,6 +150,26 @@ The gem supports multiple languages through the HeadMusic::Named mixin:
 - Shared examples in `spec/support/`
 - `composition_context.rb` provides test utilities
 
+**Never assert on console output.** Do not use `output(...).to_stdout` or `.to_stderr`. A library should not print to the console, so a spec that asserts it printed something is pinning behavior the gem should not have — and it makes the printing hard to remove later, because deleting the `puts` breaks a test that looks unrelated to the change.
+
+Test the behavior the message was describing instead. When a fallback or recovery path is worth pinning, assert what it produces and that it does not raise:
+
+```ruby
+# Not this
+it "prints a warning" do
+  expect { staff }.to output(/Warning: Clef 'foo' not found/).to_stdout
+end
+
+# This
+it "recovers from the unrecognized key instead of raising" do
+  expect { staff }.not_to raise_error
+end
+
+it "prefers the instrument's clef over the generic fallback" do
+  expect(staff.clef).not_to eq described_class.new("foo").clef
+end
+```
+
 ### Documentation Philosophy
 
 This project deliberately deprioritizes formal documentation in favor of clear, comprehensive tests.

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    head_music (17.4.0)
+    head_music (18.0.0)
       activesupport (>= 7.0, < 10)
-      humanize (~> 2.0)
+      humanize (>= 2, < 4)
       i18n (~> 1.8)
 
 GEM
@@ -30,98 +30,100 @@ GEM
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
     base64 (0.3.0)
-    bigdecimal (3.2.2)
-    bundler-audit (0.9.2)
-      bundler (>= 1.2.0, < 3)
+    bigdecimal (4.1.2)
+    bundler-audit (0.9.3)
+      bundler (>= 1.2.0)
       thor (~> 1.0)
     childprocess (5.1.0)
       logger (~> 1.5)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.3.7)
-    connection_pool (2.5.3)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.6.2)
-    docile (1.4.1)
     drb (2.2.3)
-    dry-configurable (1.3.0)
-      dry-core (~> 1.1)
+    dry-configurable (1.4.0)
+      dry-core (~> 1.0)
       zeitwerk (~> 2.6)
-    dry-core (1.1.0)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
-    dry-inflector (1.2.0)
+    dry-inflector (1.3.1)
     dry-initializer (3.2.0)
     dry-logic (1.6.0)
       bigdecimal
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-schema (1.14.1)
+    dry-schema (1.16.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 1.0, >= 1.0.1)
       dry-core (~> 1.1)
       dry-initializer (~> 3.2)
-      dry-logic (~> 1.5)
-      dry-types (~> 1.8)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.9, >= 1.9.1)
       zeitwerk (~> 2.6)
-    dry-types (1.8.3)
-      bigdecimal (~> 3.0)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
     erubi (1.13.1)
-    flay (2.13.3)
+    flay (2.14.4)
       erubi (~> 1.10)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.0)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.0)
-    flog (4.8.0)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.1, > 3.1.0)
+    flog (4.9.4)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.8)
-    humanize (2.5.1)
-    i18n (1.14.7)
+    humanize (3.1.0)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
     json (2.21.1)
-    kramdown (2.5.1)
-      rexml (>= 3.3.9)
-    language_server-protocol (3.17.0.5)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    language_server-protocol (3.17.0.6)
     launchy (3.1.1)
       addressable (~> 2.8)
       childprocess (~> 5.0)
       logger (~> 1.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
-    parallel (1.27.0)
-    parser (3.3.9.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    ostruct (0.6.3)
+    parallel (2.1.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    path_expander (1.1.3)
-    prism (1.4.0)
-    public_suffix (6.0.2)
+    path_expander (2.0.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.4.2)
     reek (6.5.0)
       dry-schema (~> 1.13)
       logger (~> 1.6)
       parser (~> 3.3.0)
       rainbow (>= 2.0, < 4.0)
       rexml (~> 3.1)
-    regexp_parser (2.10.0)
+    regexp_parser (2.12.0)
     rexml (3.4.4)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -129,43 +131,46 @@ GEM
     rspec-its (2.0.0)
       rspec-core (>= 3.13.0)
       rspec-expectations (>= 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.6.0)
+    rubocop-rspec (3.10.2)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
     ruby-progressbar (1.13.0)
-    ruby_parser (3.21.1)
+    ruby_parser (3.22.0)
       racc (~> 1.5)
       sexp_processor (~> 4.16)
-    rubycritic (4.11.0)
+    rubycritic (5.0.0)
       flay (~> 2.13)
       flog (~> 4.7)
       launchy (>= 2.5.2)
+      ostruct
       parser (>= 3.3.0.5)
+      prism (>= 1.6.0)
       rainbow (~> 3.1.1)
       reek (~> 6.5.0, < 7.0)
       rexml
@@ -174,40 +179,35 @@ GEM
       tty-which (~> 0.5.0)
       virtus (~> 2.0)
     securerandom (0.4.1)
-    sexp_processor (4.17.4)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    standard (1.50.0)
+    sexp_processor (4.17.5)
+    simplecov (1.0.2)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.88.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
-    thor (1.4.0)
+      rubocop-performance (~> 1.26.0)
+    thor (1.5.0)
     thread_safe (0.3.6)
     tty-which (0.5.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     uri (1.1.1)
     virtus (2.0.0)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
-    yard (0.9.44)
-    zeitwerk (2.7.3)
+    yard (0.9.45)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin-22

data/head_music.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.3.0"
 
   spec.add_runtime_dependency "activesupport", ">= 7.0", "< 10"
-  spec.add_runtime_dependency "humanize", "~> 2.0"
+  spec.add_runtime_dependency "humanize", ">= 2", "< 4"
   spec.add_runtime_dependency "i18n", "~> 1.8"
 
   spec.add_development_dependency "rake", "~> 13.0"

data/lib/head_music/analysis/pitch_collection.rb

@@ -82,11 +82,11 @@ class HeadMusic::Analysis::PitchCollection
   end
 
   def inspect
-    pitches.map(&:to_s).join(" ")
+    pitches.join(" ")
   end
 
   def to_s
-    pitches.map(&:to_s).join(" ")
+    pitches.join(" ")
   end
 
   def ==(other)

data/lib/head_music/content/composition/hash_deserializer.rb

@@ -78,6 +78,9 @@ class HeadMusic::Content::Composition
           sounds = values.placement_sounds(placement_hash, path)
           placement = voice.place(position, rhythmic_value, sounds)
           placement.beam_break_before = placement_hash["beam_break_before"] if placement_hash.key?("beam_break_before")
+          values.placement_syllables(placement_hash, path).each do |syllable|
+            placement.sing(syllable.text, verse: syllable.verse, hyphen_after: syllable.hyphen_after)
+          end
         end
       end
     end

data/lib/head_music/content/composition/schema_values.rb

@@ -71,6 +71,25 @@ class HeadMusic::Content::Composition
       end
     end
 
+    # "syllables" is an optional array of sung-text data, one entry per verse.
+    # Each entry is a {"text" => ..., "verse" => ..., "hyphen_after" => ...}
+    # hash; verse defaults to 1. Text must be a non-empty string, verse a
+    # positive integer, and no two entries may share a verse (a placement holds
+    # at most one syllable per verse).
+    def placement_syllables(placement_hash, path)
+      values = placement_hash["syllables"]
+      return [] if values.nil?
+
+      unless values.is_a?(Array)
+        raise ArgumentError, "#{path}: syllables must be an Array, got #{values.inspect}"
+      end
+
+      seen_verses = []
+      values.each_with_index.map do |value, index|
+        syllable(value, seen_verses, "#{path}.syllables[#{index}]")
+      end
+    end
+
     def bar_number(bar_hash, index)
       number = bar_hash["number"]
       unless number.is_a?(Integer) && number >= 0
@@ -101,6 +120,27 @@ class HeadMusic::Content::Composition
       pitch
     end
 
+    def syllable(value, seen_verses, path)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "#{path}: syllable must be a Hash, got #{value.inspect}"
+      end
+
+      text = value["text"]
+      unless text.is_a?(String) && !text.empty?
+        raise ArgumentError, "#{path}: syllable text must be a non-empty String, got #{text.inspect}"
+      end
+
+      verse = value.fetch("verse", 1)
+      unless verse.is_a?(Integer) && verse.positive?
+        raise ArgumentError, "#{path}: verse must be a positive Integer, got #{verse.inspect}"
+      end
+
+      raise ArgumentError, "#{path}: duplicate verse #{verse}" if seen_verses.include?(verse)
+      seen_verses << verse
+
+      HeadMusic::Content::Syllable.from_h(value)
+    end
+
     def sound(value, path)
       return pitch(value, path) if value.is_a?(String)
       return unpitched_sound(value, path) if value.is_a?(Hash)

data/lib/head_music/content/placement.rb

@@ -25,6 +25,32 @@ class HeadMusic::Content::Placement
     sounds.select(&:pitched?)
   end
 
+  # Authored sung text: at most one Syllable per verse, keyed by verse number.
+  # Empty for un-texted placements and rests. Set after construction, like
+  # beam_break_before. The MusicXML writer derives <syllabic> from these plus
+  # neighboring placements; melisma is the absence of a syllable here.
+  def syllables
+    @syllables ||= {}
+  end
+
+  # Assigns the syllable for a verse (default verse 1). Returns self so calls
+  # chain across verses. Keys by the Syllable's coerced verse (not the raw
+  # argument) so syllable(2) finds what sing(verse: "2") stored and mixed-type
+  # keys never make syllables.keys.sort raise.
+  def sing(text, verse: 1, hyphen_after: false)
+    syllable = HeadMusic::Content::Syllable.new(text, verse: verse, hyphen_after: hyphen_after)
+    syllables[syllable.verse] = syllable
+    self
+  end
+
+  def syllable(verse = 1)
+    syllables[verse]
+  end
+
+  def sung?
+    syllables.any?
+  end
+
   # The top pitch of a chord (or the only pitch of a note), which melodic
   # analysis treats as the melody note. Returns nil for rests and
   # unpitched-only placements; pitched? is the guard. Enharmonic ties
@@ -64,7 +90,9 @@ class HeadMusic::Content::Placement
 
   # Voice#place merges a same-position placement into the existing one, so a
   # position holds at most one placement. The sound union keeps the chord free
-  # of duplicates, making repeated placement of a sound idempotent.
+  # of duplicates, making repeated placement of a sound idempotent. Syllables
+  # are left untouched: a chord sings one syllable per verse, and the receiver
+  # (the placement already at this position) keeps its own.
   def merge(other)
     unless rhythmic_value == other.rhythmic_value
       raise ArgumentError,
@@ -98,6 +126,7 @@ class HeadMusic::Content::Placement
       "sounds" => sounds.map { |sound| sound_datum(sound) }
     }
     hash["beam_break_before"] = beam_break_before unless beam_break_before.nil?
+    hash["syllables"] = syllables.keys.sort.map { |verse| syllables[verse].to_h } unless syllables.empty?
     hash
   end
 

data/lib/head_music/content/staff.rb

@@ -12,12 +12,10 @@ class HeadMusic::Content::Staff
     begin
       @default_clef = HeadMusic::Rudiment::Clef.get(default_clef_key)
     rescue KeyError, NoMethodError
-      puts("Warning: Clef '#{default_clef_key}' not found.")
-      if @instrument
-        puts("Using instrument clef.")
-        @default_clef = @instrument.default_staves.first.clef
+      @default_clef = if @instrument
+        @instrument.default_staves.first.clef
       else
-        @default_clef = HeadMusic::Rudiment::Clef.get(:treble_clef)
+        HeadMusic::Rudiment::Clef.get(:treble_clef)
       end
     end
     @line_count = line_count || DEFAULT_LINE_COUNT

data/lib/head_music/content/syllable.rb

@@ -0,0 +1,38 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# A sung syllable attached to a Placement for one verse. Only the minimal
+# linguistic fact is stored: the text, its verse number, and whether the word
+# continues onto the next sung note (hyphen_after). The MusicXML `syllabic`
+# value (single/begin/middle/end) is derived from these at render time rather
+# than stored, and melisma is represented by the absence of a syllable on the
+# following placements, so nothing here encodes it.
+class HeadMusic::Content::Syllable
+  attr_reader :text, :verse, :hyphen_after
+
+  def initialize(text, verse: 1, hyphen_after: false)
+    @text = text.to_s
+    @verse = Integer(verse)
+    @hyphen_after = !!hyphen_after
+    freeze
+  end
+
+  def hyphen_after?
+    hyphen_after
+  end
+
+  def to_h
+    hash = {"text" => text}
+    hash["verse"] = verse unless verse == 1
+    hash["hyphen_after"] = true if hyphen_after
+    hash
+  end
+
+  def self.from_h(hash)
+    new(hash["text"], verse: hash.fetch("verse", 1), hyphen_after: hash.fetch("hyphen_after", false))
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && to_h == other.to_h
+  end
+end

data/lib/head_music/content/voice.rb

@@ -157,6 +157,6 @@ class HeadMusic::Content::Voice
   end
 
   def pitches_string
-    pitches.first(10).map(&:to_s).join(" ")
+    pitches.first(10).join(" ")
   end
 end

data/lib/head_music/instruments/instrument_name.rb

@@ -44,6 +44,6 @@ class HeadMusic::Instruments::InstrumentName
   end
 
   def format_pitch_name(pitch_designation)
-    pitch_designation.to_s.tr("b", "♭").tr("#", "♯")
+    HeadMusic::Utilities::Accidentals.to_unicode(pitch_designation)
   end
 end