head_music 15.2.0 → 17.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2446af0205d6b751566da4a2cc132032151d5c9b41732938552d12d3f07d05e
-  data.tar.gz: ed75fb7cea9e3a2ea50543bad21d28d0c66b8996cb5d57b4757aa9ef211eb67b
+  metadata.gz: 032e67bcfe59e2efb864f17ebce9fd7e5134c216c5274f96ef7f9cae1d45442a
+  data.tar.gz: fa73331c0868598885695e1fffc53e76824f1498549f82ac68d2c98276a887fc
 SHA512:
-  metadata.gz: fda48134cdaea328ddcdc1e2e072ea9c94d7a354e99178428969834cab6db36882667f21f7860ba427561d7a70e40eace071a1d4e9a7228e42c6cb92f2749e01
-  data.tar.gz: d2d1bfd02a1b1101932acd435836006e1deaa6e81102f233b9b339dfb56c01effc94691ce30063334e7c61eafffee214075c516ff0d831395a8c91b861cfffb0
+  metadata.gz: 363dde634782a8bf79e53bd62ac376515611711d839deb4258088ec197dd6f3f5e199321c8d347c66b42756a7872511a4b680c022a1106fcb3c4b0ba88513a88
+  data.tar.gz: 37eb0b6df32586566a21603549df3fbbdfa01858b1ec66da3af0c76d3a8a7d276cd939a987ba36990b359c6bebca20f713c137935d095f3ee2debb9130d29c8f

data/CHANGELOG.md

@@ -7,6 +7,34 @@ 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

data/Gemfile.lock

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

data/lib/head_music/content/composition.rb

@@ -3,7 +3,7 @@ module HeadMusic::Content; end
 
 # A composition is musical content.
 class HeadMusic::Content::Composition
-  SCHEMA_VERSION = 1
+  SCHEMA_VERSION = 3
 
   attr_reader :name, :key_signature, :meter, :voices, :composer, :origin, :comments
 
@@ -143,7 +143,7 @@ class HeadMusic::Content::Composition
     end
   end
 
-  # Rebuilds a composition from a schema v1 hash by replaying the public
+  # 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
@@ -174,7 +174,12 @@ class HeadMusic::Content::Composition
       version = hash["schema_version"]
       return if version.is_a?(Integer) && version == SCHEMA_VERSION
 
-      raise ArgumentError, "unsupported schema_version: #{version.inspect} (supported: #{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
@@ -209,8 +214,8 @@ class HeadMusic::Content::Composition
           path = "voices[#{voice_index}].placements[#{placement_index}]"
           position = parsed_position(placement_hash["position"], path)
           rhythmic_value = parsed_rhythmic_value(placement_hash["rhythmic_value"], path)
-          pitch = parsed_pitch(placement_hash["pitch"], path)
-          voice.place(position, rhythmic_value, pitch)
+          sounds = parsed_placement_sounds(placement_hash, path)
+          voice.place(position, rhythmic_value, sounds)
         end
       end
     end
@@ -305,15 +310,51 @@ class HeadMusic::Content::Composition
       rhythmic_value.tied_value.nil? || valid_rhythmic_value?(rhythmic_value.tied_value)
     end
 
-    # A nil pitch is a rest; a non-nil string that fails to parse would
-    # otherwise silently deserialize as a rest.
+    # A value that fails to parse would otherwise silently deserialize as
+    # a rest.
     def parsed_pitch(value, path)
-      return nil if value.nil?
-
       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,19 +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,
-      "pitch" => pitch&.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
@@ -60,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
@@ -153,8 +156,12 @@ class HeadMusic::Content::Voice
     HeadMusic::Content::Position.new(composition, placement.position.bar_number, 1, 0)
   end
 
-  # Stable insertion: co-positioned placements (chords) keep their insertion order,
-  # which serialization round-trips depend on.
+  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)
     index = @placements.index { |existing| existing > placement } || @placements.length
     @placements.insert(index, placement)

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

@@ -12,17 +12,23 @@ class HeadMusic::Notation::ABC::BodyLexer
   Token = Data.define(
     :type, :line, :column,
     :letter, :accidental, :octave_marks, :length,
-    :style, :passes, :direction, :voice_id, :lexeme
+    :style, :passes, :direction, :voice_id, :lexeme, :notes
   ) do
     def initialize(
       type:, line:, column:,
       letter: nil, accidental: nil, octave_marks: nil, length: nil,
-      style: nil, passes: nil, direction: nil, voice_id: nil, lexeme: nil
+      style: nil, passes: nil, direction: nil, voice_id: nil, lexeme: nil,
+      notes: nil
     )
       super
     end
   end
 
+  # One note inside a bracket chord. Each note may carry its own length;
+  # the parser enforces that they are uniform and multiplies the shared
+  # inner length with any outer length on the token (ABC 2.1 sec. 4.17).
+  ChordNote = Data.define(:accidental, :letter, :octave_marks, :length)
+
   # Alternatives are ordered longest-first so the scanner never takes a
   # short match when a longer bar line is present (e.g. "|]" before "|").
   BAR_LINE_PATTERN = /:\|\|:|:\|:|::|:\||\|:|\|\||\|\]|\[\||\|/
@@ -31,6 +37,8 @@ class HeadMusic::Notation::ABC::BodyLexer
   NORMALIZED_BAR_STYLES = {":||:" => "::", ":|:" => "::"}.freeze
 
   NOTE_PATTERN = %r{(\^\^|\^|__|_|=)?([A-Ga-g])([',]*)([\d/]*)}
+  CHORD_START_PATTERN = /\[(\^\^|\^|__|_|=)?[A-Ga-g]/
+  CHORD_NOTE_PATTERN = %r{(\^\^|\^|__|_|=)?([A-Ga-g])([',]*)([\d/]*)}
   REST_PATTERN = %r{z([\d/]*)}
   VOLTA_DIGITS_PATTERN = /\d[\d,-]*/
 
@@ -171,15 +179,49 @@ class HeadMusic::Notation::ABC::BodyLexer
       return true
     end
 
-    if scanner.check(/\[[A-Ga-g]/)
-      chord = scanner.scan(/\[[^\]]*\]/) || scanner.scan(/\[[^\]]*/)
-      tokens << unsupported_token(chord, line_number, column)
-      return true
-    end
+    return scan_chord(scanner, line_number, column, tokens) if scanner.check(CHORD_START_PATTERN)
 
     raise_unexpected_character(scanner, line_number, column)
   end
 
+  def scan_chord(scanner, line_number, column, tokens)
+    start_pos = scanner.pos
+    scanner.skip(/\[/)
+    notes = []
+    until scanner.skip(/\]/)
+      unless scanner.scan(CHORD_NOTE_PATTERN)
+        return chord_fallback(scanner, start_pos, line_number, column, tokens)
+      end
+      notes << ChordNote.new(
+        accidental: scanner[1], letter: scanner[2],
+        octave_marks: scanner[3], length: scanner[4]
+      )
+    end
+    length = scanner.scan(%r{[\d/]*})
+    tokens << Token.new(type: :chord, line: line_number, column: column, notes: notes, length: length)
+    true
+  end
+
+  # Non-note content inside the brackets (ties, rests, spaces,
+  # decorations) makes the whole group one unsupported token, matching
+  # how those constructs surface outside a chord.
+  def chord_fallback(scanner, start_pos, line_number, column, tokens)
+    if scanner.eos?
+      raise HeadMusic::Notation::ABC::ParseError.new(
+        'Unterminated chord; expected "]"',
+        line_number: line_number, snippet: chord_snippet(scanner, start_pos)
+      )
+    end
+    scanner.pos = start_pos
+    lexeme = scanner.scan(/\[[^\]]*\]/) || scanner.scan(/\[[^\]]*/)
+    tokens << unsupported_token(lexeme, line_number, column)
+    true
+  end
+
+  def chord_snippet(scanner, start_pos)
+    scanner.string[start_pos, SNIPPET_LENGTH]
+  end
+
   def volta_token(digits, line_number, column)
     passes = volta_passes(digits)
     unless passes.uniq.length == passes.length

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

@@ -28,6 +28,13 @@ module HeadMusic::Notation::ABC
       build_rhythmic_value(fraction, multiplier_string)
     end
 
+    # The bare fraction a length string denotes (e.g. "2" -> 2, "/2" -> 1/2,
+    # "" -> 1), without the unit note length applied. Used to compare a
+    # chord's per-note lengths for uniformity.
+    def length_fraction(multiplier_string)
+      multiplier(multiplier_string)
+    end
+
     private
 
     def multiplier(multiplier_string)

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

@@ -34,10 +34,10 @@ module HeadMusic::Notation::ABC
 
     attr_reader :header, :duration_resolver
 
-    # A note whose placement is deferred until we know whether a
-    # broken-rhythm mark follows it. The pitch is computed eagerly so
-    # bar-line accidental resets cannot corrupt it.
-    PendingNote = Data.define(:pitch, :length, :scale)
+    # A note or chord whose placement is deferred until we know whether
+    # a broken-rhythm mark follows it. The pitches are computed eagerly
+    # so bar-line accidental resets cannot corrupt them.
+    PendingNote = Data.define(:pitches, :length, :scale)
 
     # Per-voice interpretation state. Accidentals, the deferred note,
     # and volta tracking are all independent between voices.
@@ -146,6 +146,7 @@ module HeadMusic::Notation::ABC
     def handle(token)
       case token.type
       when :note then handle_note(token)
+      when :chord then handle_chord(token)
       when :rest then handle_rest(token)
       when :broken_rhythm then handle_broken_rhythm(token)
       when :bar_line then handle_bar_line(token)
@@ -157,10 +158,57 @@ module HeadMusic::Notation::ABC
     def handle_note(token)
       state = current_state
       pitch = state.pitch_builder.pitch(token.letter, token.octave_marks, token.accidental)
-      scale = state.awaiting_scale || Rational(1)
+      defer_placement(state, [pitch], token.length)
+    end
+
+    # Chord pitches resolve in bracket order, so an explicit accidental
+    # inside a chord persists for the rest of the bar like any other.
+    def handle_chord(token)
+      state = current_state
+      pitches = token.notes.map do |note|
+        state.pitch_builder.pitch(note.letter, note.octave_marks, note.accidental)
+      end
+      ensure_unique_chord_pitches(pitches, token)
+      inner_length = uniform_chord_length(token)
+      defer_placement(state, pitches, token.length, inner_length)
+    end
+
+    def ensure_unique_chord_pitches(pitches, token)
+      return if pitches.uniq.length == pitches.length
+
+      raise ParseError.new(
+        "Chord pitches must be unique",
+        line_number: token.line, snippet: chord_snippet(token)
+      )
+    end
+
+    # ABC 2.1 sec. 4.17 allows per-note lengths only when they agree; the
+    # shared inner length then multiplies with any outer length. Unequal
+    # lengths (whose ABC meaning is "the duration of the first note") would
+    # need silent reinterpretation to fit one rhythmic value, so we reject.
+    def uniform_chord_length(token)
+      fractions = token.notes.map { |note| duration_resolver.length_fraction(note.length) }
+      return fractions.first if fractions.uniq.length == 1
+
+      raise ParseError.new(
+        'Chord notes must share one length; write it after the bracket ("[CEG]2") ' \
+        'or repeat it on every note ("[C2E2G2]")',
+        line_number: token.line, snippet: chord_snippet(token)
+      )
+    end
+
+    def chord_snippet(token)
+      inner = token.notes.map do |note|
+        "#{note.accidental}#{note.letter}#{note.octave_marks}#{note.length}"
+      end.join
+      "[#{inner}]"
+    end
+
+    def defer_placement(state, pitches, length, inner_scale = Rational(1))
+      scale = (state.awaiting_scale || Rational(1)) * inner_scale
       state.awaiting_scale = nil
       flush_pending_note(state)
-      state.pending_note = PendingNote.new(pitch: pitch, length: token.length, scale: scale)
+      state.pending_note = PendingNote.new(pitches: pitches, length: length, scale: scale)
     end
 
     def handle_rest(token)
@@ -236,12 +284,12 @@ module HeadMusic::Notation::ABC
       return unless pending
 
       state.pending_note = nil
-      place(state, pending.length, pending.pitch, scale: pending.scale)
+      place(state, pending.length, pending.pitches, scale: pending.scale)
     end
 
-    def place(state, length, pitch, scale: Rational(1))
+    def place(state, length, pitches, scale: Rational(1))
       rhythmic_value = duration_resolver.rhythmic_value(length, scale: scale)
-      state.voice.place(state.voice.next_position, rhythmic_value, pitch)
+      state.voice.place(state.voice.next_position, rhythmic_value, pitches)
     end
 
     def apply_repeat_flags(state, style)

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

@@ -120,10 +120,29 @@ module HeadMusic::Notation::ABC
     end
 
     def token(placement, pitch_writer, duration_writer)
+      ensure_pitched_sounds(placement)
+
       multiplier = duration_writer.multiplier_string(placement.rhythmic_value)
       return "z#{multiplier}" if placement.rest?
+      return chord_token(placement, pitch_writer, multiplier) if placement.chord?
 
       "#{pitch_writer.token(placement.pitch)}#{multiplier}"
     end
+
+    def chord_token(placement, pitch_writer, multiplier)
+      # Pitches are emitted low-to-high, and the oracle sees them in that
+      # same order, so the writer's bar-accidental state cannot diverge from
+      # what a re-parse of the emitted brackets accumulates.
+      pitch_tokens = placement.pitches.sort.map { |pitch| pitch_writer.token(pitch) }
+      "[#{pitch_tokens.join}]#{multiplier}"
+    end
+
+    def ensure_pitched_sounds(placement)
+      unpitched = placement.sounds.find { |sound| !sound.pitched? }
+      return unless unpitched
+
+      raise RenderError, "cannot render unpitched sound \"#{unpitched}\" at #{placement.position}: " \
+        "percussion rendering is not yet supported"
+    end
   end
 end

data/lib/head_music/notation/music_xml/writer.rb

@@ -311,15 +311,26 @@ module HeadMusic::Notation::MusicXML
     end
 
     def note_lines(placement)
+      ensure_pitched_sounds(placement)
+      raise RenderError, "chords are not yet supported by the MusicXML writer" if placement.chord?
+
       components_by_placement[placement].flat_map do |component|
         component_lines(placement, component)
       end
     end
 
+    def ensure_pitched_sounds(placement)
+      unpitched = placement.sounds.find { |sound| !sound.pitched? }
+      return unless unpitched
+
+      raise RenderError, "cannot render unpitched sound \"#{unpitched}\" at #{placement.position}: " \
+        "percussion rendering is not yet supported"
+    end
+
     def component_lines(placement, component)
       [
         "#{INDENT * 3}<note>",
-        *(placement.note? ? pitch_lines(placement.pitch) : ["#{INDENT * 4}<rest/>"]),
+        *(placement.pitched? ? pitch_lines(placement.pitch) : ["#{INDENT * 4}<rest/>"]),
         "#{INDENT * 4}<duration>#{component.duration}</duration>",
         *tie_lines(placement, component),
         "#{INDENT * 4}<type>#{component.type}</type>",

data/lib/head_music/rudiment/pitch.rb

@@ -56,6 +56,8 @@ class HeadMusic::Rudiment::Pitch < HeadMusic::Rudiment::Base
   end
 
   def self.from_number(number)
+    return nil unless number.respond_to?(:to_i)
+
     number_int = number.to_i
     return nil unless number == number_int
 
@@ -108,6 +110,10 @@ class HeadMusic::Rudiment::Pitch < HeadMusic::Rudiment::Base
     name
   end
 
+  def pitched?
+    true
+  end
+
   def to_i
     midi_note_number
   end

data/lib/head_music/rudiment/unpitched_note.rb

@@ -3,6 +3,7 @@ module HeadMusic::Rudiment; end
 
 # An UnpitchedNote represents a percussion note with rhythm but no specific pitch.
 # It inherits from RhythmicElement and can optionally have an instrument name.
+# Intended future composition: UnpitchedNote ≈ UnpitchedSound + rhythmic value.
 class HeadMusic::Rudiment::UnpitchedNote < HeadMusic::Rudiment::RhythmicElement
   include HeadMusic::Named