head_music 15.1.0 → 17.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd3edd30892b4392257993e45de98e7c27645b61480c6f478b464005f89b10a7
-  data.tar.gz: 9755bd71aae10839f15d9a7f73cd6f2526265672c03907e2e2b9db75d6fd4bb0
+  metadata.gz: 032e67bcfe59e2efb864f17ebce9fd7e5134c216c5274f96ef7f9cae1d45442a
+  data.tar.gz: fa73331c0868598885695e1fffc53e76824f1498549f82ac68d2c98276a887fc
 SHA512:
-  metadata.gz: 45706fe9753a6907b79378a7b5334c76fb6cc55f282fe16b77940fe0d8dbe01197c111a452e0974ff2ebe9d5536255858e81da7fb15141a8540ad2600148f817
-  data.tar.gz: e97830d0f4d8f102ebae608701d5db6a1bdaaa905545a6b14143d2a36f7273ba0398e960b0986d2a05bf5aa704273abea31f89b08db59875ddb059e150b2753b
+  metadata.gz: 363dde634782a8bf79e53bd62ac376515611711d839deb4258088ec197dd6f3f5e199321c8d347c66b42756a7872511a4b680c022a1106fcb3c4b0ba88513a88
+  data.tar.gz: 37eb0b6df32586566a21603549df3fbbdfa01858b1ec66da3af0c76d3a8a7d276cd939a987ba36990b359c6bebca20f713c137935d095f3ee2debb9130d29c8f

data/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.0.0] - 2026-07-18
+
+### Added
+
+- `HeadMusic::Rudiment::UnpitchedSound` — an unpitched sound (a drum hit, a clap, a percussive knock), backed by the instruments catalog. `.get(nil)` returns the generic instrument-less sound; `.get(name_or_alias_or_instrument)` resolves through the catalog (aliases canonicalize to the instrument's name key), and pitched instruments are valid hit surfaces — a knock on a violin body is unpitched.
+- Placements hold sounds: `HeadMusic::Content::Placement#sounds` is the source of truth (pitched and unpitched, mixed within one placement allowed), with `#pitches` as the pitched subset. `Voice#place` accepts pitches, unpitched sounds, instruments, or mixed arrays.
+- New placement predicates: `sounded?` (any sound), `pitched?` (any pitched sound), `pitched_note?`, and `unpitched_note?`.
+
+### Changed
+
+- **Breaking**: serialization schema is now version 3. Placement hashes carry a `"sounds"` array instead of the `"pitches"` key — pitched sounds serialize as pitch strings (unchanged), unpitched sounds as `{"unpitched" => name_key}` objects (`null` name key for the generic sound) — and `Composition.from_h` no longer accepts schema version 2 hashes. Persisted v2 data (e.g. in a jsonb column) must be migrated by renaming each placement's `"pitches"` key to `"sounds"`; the pitch strings themselves are unchanged.
+- **Breaking**: `Placement#note?` now means exactly one sound of any kind, so chords are no longer `note?`; `Placement#chord?` counts pitched sounds (two or more).
+- **Breaking**: `Voice#place` raises `ArgumentError` on an unparseable value instead of quietly placing a rest.
+- The ABC and MusicXML writers raise `RenderError` when asked to render an unpitched sound (unpitched rendering lands in a future release).
+
+## [16.0.0] - 2026-07-17
+
+### Added
+
+- Chords in the content model: `HeadMusic::Content::Placement` holds a `pitches` array (empty for a rest, two or more for a chord) and derives `#pitch` as the highest pitch, so melodic analysis follows the top line. `Placement#chord?` distinguishes chords. `Voice#place` accepts a single pitch or an array of pitches; a chord is one rhythmic event.
+- `Voice#place` merges a placement at an already-occupied position into the existing placement when the rhythmic value matches (the pitch union is duplicate-free, so re-placing a pitch is idempotent), and raises `ArgumentError` when it does not. A position within a voice holds at most one placement, enforcing structurally that simultaneous pitches with distinct durations belong in separate voices.
+
+### Changed
+
+- **Breaking**: serialization schema is now version 2. Placement hashes carry a `"pitches"` array instead of the singular `"pitch"` key (rests serialize as `"pitches" => []`), and `Composition.from_h` no longer accepts schema version 1 hashes.
+- **Breaking**: `Placement#pitch` is a derived reader (highest of `pitches`, `nil` for a rest) rather than a stored attribute, and `Placement#note?` returns a boolean rather than the pitch object.
+- The ABC and MusicXML writers raise `RenderError` when asked to render a chord placement (chord rendering lands in a future release) rather than silently emitting only the top pitch.
+
+## [15.2.0] - 2026-07-16
+
+### Added
+
+- `HeadMusic::Content::Composition#to_h` / `.from_h` — lossless, JSON-safe hash serialization of a composition (schema_version 1). The hash captures name, key signature, meter, composer, origin, voices with roles and ordered placements (tick-precise positions, rhythmic values including ties, exact pitch spellings, rests as `null`), sparse per-bar state (mid-piece key and meter changes, repeat and volta structure), and comments. `from_h` rebuilds through the public builder API and raises `ArgumentError` with path context on malformed input; unknown keys are ignored so the format can evolve additively.
+- `HeadMusic::Content::Composition#to_json` / `.from_json` — thin delegates over `to_h`/`from_h`.
+- `#to_h` on `Content::Voice`, `Content::Placement`, `Content::Bar`, and `Content::Comment`.
+
+**Schema v1 is a compatibility surface**: hashes persisted by downstream apps (e.g. in a jsonb column) must keep loading. Additive optional keys are fine within version 1; any change to existing keys' shape or meaning requires a `schema_version` bump.
+
+### Fixed
+
+- `RhythmicValue.get` now parses tied value strings ("half tied to eighth", including chained ties), so tied durations round-trip through `#to_s`.
+- `Bar#key_signature=` and `Bar#meter=` coerce strings via `KeySignature.get` / `Meter.get`, so `change_meter(4, "6/8")` no longer stores a raw String.
+- `Voice` placement ordering is now stable: notes placed at the same position (chords) keep their insertion order.
+- `Composition#change_key_signature` / `#change_meter` no longer raise for a bar earlier than the first placement (e.g. a pickup bar).
+
 ## [15.1.0] - 2026-07-07
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (15.1.0)
+    head_music (17.0.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)

data/lib/head_music/content/bar.rb

@@ -5,19 +5,26 @@ module HeadMusic::Content; end
 # Encapsulates meter and key signature changes
 # and repeat structure (repeat barlines and volta brackets) as content semantics
 class HeadMusic::Content::Bar
-  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes
-  attr_accessor :key_signature, :meter
+  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes, :key_signature, :meter
   attr_writer :starts_repeat
 
   def initialize(composition, key_signature: nil, meter: nil)
     @composition = composition
-    @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature) if key_signature
-    @meter = HeadMusic::Rudiment::Meter.get(meter) if meter
+    self.key_signature = key_signature
+    self.meter = meter
     @starts_repeat = false
     @ends_repeat_after_num_plays = nil
     @plays_on_passes = nil
   end
 
+  def key_signature=(value)
+    @key_signature = value ? HeadMusic::Rudiment::KeySignature.get(value) : nil
+  end
+
+  def meter=(value)
+    @meter = value ? HeadMusic::Rudiment::Meter.get(value) : nil
+  end
+
   def starts_repeat?
     @starts_repeat
   end
@@ -48,6 +55,19 @@ class HeadMusic::Content::Bar
     ["Bar", key_signature, meter, repeat_summary].compact.join(" ")
   end
 
+  # Sparse serialization: only non-default state, so a default bar is {}.
+  # KeySignature serializes via #name ("F♯ minor") because #to_s ("3 sharps")
+  # cannot be parsed back by KeySignature.get.
+  def to_h
+    hash = {}
+    hash["key_signature"] = key_signature.name if key_signature
+    hash["meter"] = meter.to_s if meter
+    hash["starts_repeat"] = true if starts_repeat?
+    hash["ends_repeat_after_num_plays"] = ends_repeat_after_num_plays if ends_repeat?
+    hash["plays_on_passes"] = plays_on_passes.dup if plays_on_passes
+    hash
+  end
+
   private
 
   def valid_ends_repeat_after_num_plays?(value)

data/lib/head_music/content/comment.rb

@@ -15,6 +15,10 @@ class HeadMusic::Content::Comment
     text
   end
 
+  def to_h
+    {"text" => text, "position" => position&.to_s}
+  end
+
   private
 
   def ensure_position(position)

data/lib/head_music/content/composition.rb

@@ -3,8 +3,18 @@ module HeadMusic::Content; end
 
 # A composition is musical content.
 class HeadMusic::Content::Composition
+  SCHEMA_VERSION = 3
+
   attr_reader :name, :key_signature, :meter, :voices, :composer, :origin, :comments
 
+  def self.from_h(hash)
+    HashDeserializer.new(hash).composition
+  end
+
+  def self.from_json(json)
+    from_h(JSON.parse(json))
+  end
+
   def initialize(name: nil, key_signature: nil, meter: nil, composer: nil, origin: nil, comments: nil)
     ensure_attributes(name, key_signature, meter)
     @composer = composer
@@ -35,10 +45,11 @@ class HeadMusic::Content::Composition
 
   def bars(last = latest_bar_number)
     @bars ||= []
-    (earliest_bar_number..last).each do |bar_number|
+    first = [earliest_bar_number, last].min
+    (first..last).each do |bar_number|
       @bars[bar_number] ||= HeadMusic::Content::Bar.new(self)
     end
-    @bars[earliest_bar_number..last]
+    @bars[first..last]
   end
 
   def change_key_signature(bar_number, key_signature)
@@ -50,7 +61,7 @@ class HeadMusic::Content::Composition
   end
 
   def earliest_bar_number
-    [voices.map(&:earliest_bar_number), 1].flatten.min
+    [voices.map(&:earliest_bar_number), first_allocated_bar_number, 1].flatten.compact.min
   end
 
   def latest_bar_number
@@ -77,8 +88,32 @@ class HeadMusic::Content::Composition
     HeadMusic::Notation::MusicXML.render(self)
   end
 
+  def to_h
+    {
+      "schema_version" => SCHEMA_VERSION,
+      "name" => name,
+      "key_signature" => key_signature.name,
+      "meter" => meter.to_s,
+      "composer" => composer&.to_s,
+      "origin" => origin&.to_s,
+      "voices" => voices.map(&:to_h),
+      "bars" => bars_to_h,
+      "comments" => comments.map(&:to_h)
+    }
+  end
+
+  def to_json(*_args)
+    to_h.to_json
+  end
+
   private
 
+  # Bars can be allocated below the voices' earliest bar (e.g. a key or meter
+  # change in a pickup bar), so the earliest bar reflects those allocations too.
+  def first_allocated_bar_number
+    (@bars || []).index { |bar| !bar.nil? }
+  end
+
   def ensure_attributes(name, key_signature, meter)
     @name = name || "Composition"
     @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature) if key_signature
@@ -94,4 +129,232 @@ class HeadMusic::Content::Composition
   def last_key_signature_change(bar_number)
     bars(bar_number)[earliest_bar_number..bar_number].reverse.detect(&:key_signature)
   end
+
+  # Iterates the raw sparse array (not the public #bars slice, which loses the
+  # number offset), pairing each non-default bar with its number.
+  def bars_to_h
+    (@bars || []).each_with_index.filter_map do |bar, number|
+      next if bar.nil?
+
+      bar_hash = bar.to_h
+      next if bar_hash.empty?
+
+      {"number" => number}.merge(bar_hash)
+    end
+  end
+
+  # Rebuilds a composition from a schema v3 hash by replaying the public
+  # builder API in dependency order: meter and key changes first (position
+  # strings roll counts and ticks over via the meter map), then placements,
+  # then repeat flags (a pickup-bar flag needs its bar allocated), then
+  # comments. Validates values at the boundary so corrupted input raises
+  # ArgumentError with path context instead of silently deserializing wrong.
+  class HashDeserializer
+    def initialize(hash)
+      raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      @hash = hash.deep_transform_keys(&:to_s)
+      validate_schema_version
+    end
+
+    def composition
+      @composition ||= build_base_composition.tap do |composition|
+        apply_bar_changes(composition)
+        build_voices(composition)
+        apply_repeat_flags(composition)
+        add_comments(composition)
+      end
+    end
+
+    private
+
+    attr_reader :hash
+
+    def validate_schema_version
+      version = hash["schema_version"]
+      return if version.is_a?(Integer) && version == SCHEMA_VERSION
+
+      message = "unsupported schema_version: #{version.inspect} (supported: #{SCHEMA_VERSION})"
+      if version == 2
+        message += "; migrate v2 \"pitches\" arrays to v3 \"sounds\" arrays " \
+          "(pitch strings unchanged; unpitched sounds are {\"unpitched\" => name_key} objects)"
+      end
+      raise ArgumentError, message
+    end
+
+    def build_base_composition
+      HeadMusic::Content::Composition.new(
+        name: hash["name"],
+        key_signature: parsed_key_signature(hash["key_signature"], "key_signature"),
+        meter: parsed_meter(hash["meter"], "meter"),
+        composer: hash["composer"],
+        origin: hash["origin"]
+      )
+    end
+
+    def bar_hashes
+      @bar_hashes ||= Array(hash["bars"])
+    end
+
+    def apply_bar_changes(composition)
+      bar_hashes.each_with_index do |bar_hash, index|
+        number = validated_bar_number(bar_hash, index)
+        path = "bars[#{index}]"
+        key_signature = parsed_key_signature(bar_hash["key_signature"], path)
+        meter = parsed_meter(bar_hash["meter"], path)
+        composition.change_key_signature(number, key_signature) if key_signature
+        composition.change_meter(number, meter) if meter
+      end
+    end
+
+    def build_voices(composition)
+      Array(hash["voices"]).each_with_index do |voice_hash, voice_index|
+        voice = composition.add_voice(role: voice_hash["role"])
+        Array(voice_hash["placements"]).each_with_index do |placement_hash, placement_index|
+          path = "voices[#{voice_index}].placements[#{placement_index}]"
+          position = parsed_position(placement_hash["position"], path)
+          rhythmic_value = parsed_rhythmic_value(placement_hash["rhythmic_value"], path)
+          sounds = parsed_placement_sounds(placement_hash, path)
+          voice.place(position, rhythmic_value, sounds)
+        end
+      end
+    end
+
+    def apply_repeat_flags(composition)
+      bar_hashes.each_with_index do |bar_hash, index|
+        next unless repeat_state?(bar_hash)
+
+        bar = composition.bars(validated_bar_number(bar_hash, index)).last
+        bar.starts_repeat = true if bar_hash["starts_repeat"]
+        bar.ends_repeat_after_num_plays = bar_hash["ends_repeat_after_num_plays"] if bar_hash["ends_repeat_after_num_plays"]
+        bar.plays_on_passes = bar_hash["plays_on_passes"] if bar_hash["plays_on_passes"]
+      end
+    end
+
+    def add_comments(composition)
+      Array(hash["comments"]).each_with_index do |comment_hash, index|
+        position = parsed_position(comment_hash["position"], "comments[#{index}]") if comment_hash["position"]
+        composition.add_comment(comment_hash["text"], position)
+      end
+    end
+
+    def repeat_state?(bar_hash)
+      bar_hash["starts_repeat"] || bar_hash["ends_repeat_after_num_plays"] || bar_hash["plays_on_passes"]
+    end
+
+    def validated_bar_number(bar_hash, index)
+      number = bar_hash["number"]
+      unless number.is_a?(Integer) && number >= 0
+        raise ArgumentError, "bars[#{index}]: bar number must be an Integer of at least 0, got #{number.inspect}"
+      end
+      number
+    end
+
+    # Position silently coerces garbage strings to "0:1:000", which would
+    # mislocate content with no error, so the shape is validated up front.
+    # Accepts "bar", "bar:count", or "bar:count:tick" with non-negative parts.
+    def parsed_position(value, path)
+      return nil if value.nil?
+
+      unless value.is_a?(String) && value.match?(/\A\d+(:\d+){0,2}\z/)
+        raise ArgumentError, "#{path}: unknown position #{value.inspect}"
+      end
+      value
+    end
+
+    # KeySignature.get returns a hollow object (nil tonic_spelling) for
+    # garbage rather than nil, so presence of the tonic is the real check.
+    def parsed_key_signature(value, path)
+      return nil if value.nil?
+
+      key_signature = begin
+        HeadMusic::Rudiment::KeySignature.get(value)
+      rescue
+        nil
+      end
+      unless key_signature&.tonic_spelling
+        raise ArgumentError, "#{path}: unknown key signature #{value.inspect}"
+      end
+      key_signature
+    end
+
+    def parsed_meter(value, path)
+      return nil if value.nil?
+
+      meter = begin
+        HeadMusic::Rudiment::Meter.get(value)
+      rescue
+        nil
+      end
+      unless meter&.top_number&.positive? && meter.bottom_number.positive?
+        raise ArgumentError, "#{path}: unknown meter #{value.inspect}"
+      end
+      meter
+    end
+
+    def parsed_rhythmic_value(value, path)
+      rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(value)
+      unless valid_rhythmic_value?(rhythmic_value)
+        raise ArgumentError, "#{path}: unknown rhythmic value #{value.inspect}"
+      end
+      rhythmic_value
+    end
+
+    # RhythmicValue.get returns a hollow object (nil unit) for garbage rather
+    # than nil, and a tied tail can be hollow while the head parses, so the
+    # whole tie chain is checked.
+    def valid_rhythmic_value?(rhythmic_value)
+      return false unless rhythmic_value.is_a?(HeadMusic::Rudiment::RhythmicValue)
+      return false unless rhythmic_value.unit
+
+      rhythmic_value.tied_value.nil? || valid_rhythmic_value?(rhythmic_value.tied_value)
+    end
+
+    # A value that fails to parse would otherwise silently deserialize as
+    # a rest.
+    def parsed_pitch(value, path)
+      pitch = HeadMusic::Rudiment::Pitch.get(value)
+      raise ArgumentError, "#{path}: unknown pitch #{value.inspect}" unless pitch
+
+      pitch
+    end
+
+    # "sounds" is an array of sound data, empty for a rest. A pitched sound
+    # is a pitch string; an unpitched sound is a one-key
+    # {"unpitched" => name_key} hash. A nil element is never a rest, so it
+    # fails like any other unknown sound.
+    def parsed_placement_sounds(placement_hash, path)
+      values = placement_hash["sounds"]
+      unless values.is_a?(Array)
+        raise ArgumentError, "#{path}: sounds must be an Array, got #{values.inspect}"
+      end
+
+      values.each_with_index.map do |value, index|
+        parsed_sound(value, "#{path}.sounds[#{index}]")
+      end
+    end
+
+    def parsed_sound(value, path)
+      return parsed_pitch(value, path) if value.is_a?(String)
+      return parsed_unpitched_sound(value, path) if value.is_a?(Hash)
+
+      raise ArgumentError, "#{path}: unknown sound #{value.inspect}"
+    end
+
+    # A nil name_key is the generic unpitched sound. A pitched instrument is
+    # a valid hit surface (a knock on a violin body is unpitched), so any
+    # catalog name or alias resolves.
+    def parsed_unpitched_sound(value, path)
+      unless value.keys == ["unpitched"]
+        raise ArgumentError, "#{path}: unknown sound #{value.inspect}"
+      end
+
+      name = value["unpitched"]
+      valid_name = name.nil? || (name.is_a?(String) && !name.empty?)
+      sound = HeadMusic::Rudiment::UnpitchedSound.get(name) if valid_name
+      raise ArgumentError, "#{path}: unknown instrument #{name.inspect}" unless sound
+
+      sound
+    end
+  end
 end

data/lib/head_music/content/placement.rb

@@ -1,25 +1,71 @@
 # A module for musical content
 module HeadMusic::Content; end
 
-# A placement is a note or rest at a position within a voice in a composition
+# A placement is a note, chord, or rest at a position within a voice in a composition
 class HeadMusic::Content::Placement
   include Comparable
 
-  attr_reader :voice, :position, :rhythmic_value, :pitch
+  attr_reader :voice, :position, :rhythmic_value, :sounds
 
   delegate :composition, to: :voice
   delegate :spelling, to: :pitch, allow_nil: true
 
-  def initialize(voice, position, rhythmic_value, pitch = nil)
-    ensure_attributes(voice, position, rhythmic_value, pitch)
+  def initialize(voice, position, rhythmic_value, sound_or_sounds = nil)
+    ensure_attributes(voice, position, rhythmic_value, sound_or_sounds)
   end
 
-  def note?
-    pitch
+  def pitches
+    sounds.select(&:pitched?)
+  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
+  # resolve to the first-listed pitch (MRI's max keeps the earliest of
+  # equals; a spec pins the behavior).
+  def pitch
+    pitches.max
   end
 
   def rest?
-    !note?
+    sounds.empty?
+  end
+
+  def sounded?
+    sounds.any?
+  end
+
+  def note?
+    sounds.length == 1
+  end
+
+  def pitched_note?
+    note? && pitched?
+  end
+
+  def unpitched_note?
+    note? && !pitched?
+  end
+
+  def chord?
+    pitches.length > 1
+  end
+
+  def pitched?
+    sounds.any?(&:pitched?)
+  end
+
+  # 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.
+  def merge(other)
+    unless rhythmic_value == other.rhythmic_value
+      raise ArgumentError,
+        "cannot place a #{other.rhythmic_value} at #{position}: position occupied by a #{rhythmic_value}"
+    end
+
+    @sounds = (sounds + other.sounds).uniq.freeze
+    self
   end
 
   def next_position
@@ -35,11 +81,29 @@ class HeadMusic::Content::Placement
   end
 
   def to_s
-    "#{rhythmic_value} #{pitch || "rest"} at #{position}"
+    "#{rhythmic_value} #{sounds.any? ? sounds.map { |sound| sound_label(sound) }.join(" ") : "rest"} at #{position}"
+  end
+
+  def to_h
+    {
+      "position" => position.to_s,
+      "rhythmic_value" => rhythmic_value.to_s,
+      "sounds" => sounds.map { |sound| sound_datum(sound) }
+    }
   end
 
   private
 
+  # Unpitched names may be multi-word, so they are bracketed to keep the
+  # space-delimited sound list unambiguous.
+  def sound_label(sound)
+    sound.pitched? ? sound.to_s : "[#{sound}]"
+  end
+
+  def sound_datum(sound)
+    sound.pitched? ? sound.to_s : {"unpitched" => sound.name_key&.to_s}
+  end
+
   def starts_during?(other_placement)
     position >= other_placement.position && position < other_placement.next_position
   end
@@ -52,11 +116,51 @@ class HeadMusic::Content::Placement
     position <= other_placement.position && next_position >= other_placement.next_position
   end
 
-  def ensure_attributes(voice, position, rhythmic_value, pitch)
+  def ensure_attributes(voice, position, rhythmic_value, sound_or_sounds)
     @voice = voice
     ensure_position(position)
     @rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
-    @pitch = HeadMusic::Rudiment::Pitch.get(pitch)
+    @sounds = ensure_sounds(sound_or_sounds)
+  end
+
+  def ensure_sounds(sound_or_sounds)
+    return [].freeze if sound_or_sounds.nil?
+
+    values = sound_or_sounds.is_a?(Array) ? sound_or_sounds : [sound_or_sounds]
+    values.map { |value| resolve_sound(value) }.uniq.freeze
+  end
+
+  def resolve_sound(value)
+    return value if value.is_a?(HeadMusic::Rudiment::UnpitchedSound)
+    return HeadMusic::Rudiment::UnpitchedSound.get(value) if value.is_a?(HeadMusic::Instruments::Instrument)
+
+    pitch = HeadMusic::Rudiment::Pitch.get(value)
+    return pitch if pitch
+
+    unpitched_sound(value) || raise(ArgumentError, unknown_sound_message(value))
+  end
+
+  # A bare name resolves to a percussive hit only on an unpitched instrument;
+  # naming a pitched instrument is ambiguous, so it raises instead.
+  # UnpitchedSound.get(nil) is the generic sound, so nil is excluded here to
+  # preserve nil-as-rest at the argument level and nil-raises inside arrays.
+  def unpitched_sound(value)
+    return nil if value.nil?
+
+    sound = HeadMusic::Rudiment::UnpitchedSound.get(value)
+    return nil unless sound&.instrument
+    return nil if sound.instrument.pitched?
+
+    sound
+  end
+
+  def unknown_sound_message(value)
+    if HeadMusic::Instruments::Instrument.get(value)&.pitched?
+      "#{value.inspect} is a pitched instrument; place a pitch such as \"D4\", " \
+        "or pass HeadMusic::Rudiment::UnpitchedSound.get(#{value.inspect}) for a percussive hit"
+    else
+      "unknown sound: #{value.inspect}"
+    end
   end
 
   def ensure_position(position)

data/lib/head_music/content/voice.rb

@@ -16,14 +16,17 @@ class HeadMusic::Content::Voice
     @placements = []
   end
 
-  def place(position, rhythmic_value, pitch = nil)
-    HeadMusic::Content::Placement.new(self, position, rhythmic_value, pitch).tap do |placement|
-      insert_into_placements(placement)
-    end
+  def place(position, rhythmic_value, sound_or_sounds = nil)
+    placement = HeadMusic::Content::Placement.new(self, position, rhythmic_value, sound_or_sounds)
+    existing = placement_at(placement.position)
+    return existing.merge(placement) if existing
+
+    insert_into_placements(placement)
+    placement
   end
 
   def notes
-    @placements.select(&:note?).sort_by(&:position)
+    @placements.select(&:pitched?).sort_by(&:position)
   end
 
   def notes_not_in_key
@@ -140,15 +143,28 @@ class HeadMusic::Content::Voice
     [role, pitches_string].join(": ")
   end
 
+  def to_h
+    {
+      "role" => role&.to_s,
+      "placements" => placements.map(&:to_h)
+    }
+  end
+
   private
 
   def bar_start_position(placement)
     HeadMusic::Content::Position.new(composition, placement.position.bar_number, 1, 0)
   end
 
+  def placement_at(position)
+    @placements.find { |placement| placement.position == position }
+  end
+
+  # Positions are unique within a voice (place merges same-position
+  # placements), so insertion order is simply position order.
   def insert_into_placements(placement)
-    @placements << placement
-    @placements = @placements.sort
+    index = @placements.index { |existing| existing > placement } || @placements.length
+    @placements.insert(index, placement)
   end
 
   def pitches_string