head_music 15.0.0 → 15.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c29fa7f976d16091512b8bdc9eb8befcb4766c4bb70d387a67991e9b9897a5c
-  data.tar.gz: b43c0fed22c3ed7c79a7a0195847740ba7b3bea608a24921893a329f0c66ba7f
+  metadata.gz: cd3edd30892b4392257993e45de98e7c27645b61480c6f478b464005f89b10a7
+  data.tar.gz: 9755bd71aae10839f15d9a7f73cd6f2526265672c03907e2e2b9db75d6fd4bb0
 SHA512:
-  metadata.gz: 47d395cc1709167182e0810c7383120395e927629a2e5e5076e197bdacfd377445546a842a032fecabd9865f62e878f969fec301535758072b45db229c80e8e4
-  data.tar.gz: '0950f0d5a6a2b830a1733d8d0a7d19eb9fcb87815e25d3e562dc6aa94bc95c16a2d7710ca31890e23d1dcc07fc64247030565741d2edf38da6cb177f7e091fb9'
+  metadata.gz: 45706fe9753a6907b79378a7b5334c76fb6cc55f282fe16b77940fe0d8dbe01197c111a452e0974ff2ebe9d5536255858e81da7fb15141a8540ad2600148f817
+  data.tar.gz: e97830d0f4d8f102ebae608701d5db6a1bdaaa905545a6b14143d2a36f7273ba0398e960b0986d2a05bf5aa704273abea31f89b08db59875ddb059e150b2753b

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [15.1.0] - 2026-07-07
+
+### Added
+
+- `HeadMusic::Content::Composition.to_musicxml` for MusicXML export
+- `HeadMusic::Content::Composition.to_abc` for ABC Notation export. ABC can round-trip to and from Composition.
+
 ## [15.0.0] - 2026-07-06
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (15.0.0)
+    head_music (15.1.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -220,6 +220,7 @@ DEPENDENCIES
   head_music!
   kramdown
   rake (~> 13.0)
+  rexml (~> 3.4)
   rspec (~> 3.0)
   rspec-its (~> 2.0)
   rubocop

data/head_music.gemspec

@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "i18n", "~> 1.8"
 
   spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rexml", "~> 3.4"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-its", "~> 2.0"
   spec.add_development_dependency "bundler-audit", "~> 0.9"

data/lib/head_music/content/composition.rb

@@ -69,6 +69,14 @@ class HeadMusic::Content::Composition
     "#{name} — #{voices.count} #{(voices.count == 1) ? "voice" : "voices"}"
   end
 
+  def to_abc(**options)
+    HeadMusic::Notation::ABC.render(self, **options)
+  end
+
+  def to_musicxml
+    HeadMusic::Notation::MusicXML.render(self)
+  end
+
   private
 
   def ensure_attributes(name, key_signature, meter)

data/lib/head_music/content/voice.rb

@@ -118,6 +118,22 @@ class HeadMusic::Content::Voice
     last_placement ? last_placement.next_position : HeadMusic::Content::Position.new(composition, 1, 1, 0)
   end
 
+  # Returns nil if placements are contiguous, or [expected_position, found_placement]
+  # for the first gap: either the first placement not starting its bar, or the
+  # first pair of consecutive placements where the second doesn't begin where
+  # the first one ends.
+  def first_gap
+    first = placements.first
+    return unless first
+
+    return [bar_start_position(first), first] unless first.position.count == 1 && first.position.tick.zero?
+
+    placements.each_cons(2) do |previous, current|
+      return [previous.next_position, current] unless current.position == previous.next_position
+    end
+    nil
+  end
+
   def to_s
     return pitches_string if role.to_s.strip == ""
 
@@ -126,6 +142,10 @@ class HeadMusic::Content::Voice
 
   private
 
+  def bar_start_position(placement)
+    HeadMusic::Content::Position.new(composition, placement.position.bar_number, 1, 0)
+  end
+
   def insert_into_placements(placement)
     @placements << placement
     @placements = @placements.sort

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

@@ -0,0 +1,63 @@
+# Parses and renders ABC notation as HeadMusic::Content compositions
+module HeadMusic::Notation::ABC
+  # Converts a HeadMusic::Rudiment::RhythmicValue back into the ABC note-length
+  # multiplier string relative to the tune's unit note length — the inverse of
+  # DurationResolver.
+  class DurationWriter
+    attr_reader :unit_note_length
+
+    def initialize(unit_note_length)
+      @unit_note_length = Rational(unit_note_length)
+    end
+
+    def multiplier_string(rhythmic_value)
+      fraction = total_fraction(rhythmic_value)
+      validate_fraction!(fraction, rhythmic_value)
+      format_multiplier(fraction / unit_note_length)
+    end
+
+    private
+
+    # RhythmicValue's own value methods return Floats; rebuild the fraction
+    # from integer parts so the multiplier arithmetic stays exact. A tied
+    # chain collapses to one multiplier, round-tripping tokens like "A5".
+    def total_fraction(rhythmic_value)
+      fraction = single_fraction(rhythmic_value)
+      tied_value = rhythmic_value.tied_value
+      fraction += total_fraction(tied_value) if tied_value
+      fraction
+    end
+
+    def single_fraction(rhythmic_value)
+      unit = rhythmic_value.unit
+      dots = rhythmic_value.dots
+      # A value with d dots spans (2^(d+1) - 1) / 2^d of its unit.
+      Rational(unit.numerator, unit.denominator) * Rational((2**(dots + 1)) - 1, 2**dots)
+    end
+
+    def validate_fraction!(fraction, rhythmic_value)
+      max_fraction = DurationResolver::MAX_FRACTION
+      if fraction > max_fraction
+        raise_error("note length exceeds #{max_fraction.to_i} whole notes", rhythmic_value)
+      end
+      return if power_of_two?(fraction.denominator)
+
+      raise_error("note length #{fraction} is not expressible in binary note values", rhythmic_value)
+    end
+
+    def format_multiplier(multiplier)
+      return "" if multiplier == 1
+      return multiplier.numerator.to_s if multiplier.denominator == 1
+
+      "#{multiplier.numerator}/#{multiplier.denominator}"
+    end
+
+    def power_of_two?(integer)
+      (integer & (integer - 1)).zero?
+    end
+
+    def raise_error(message, rhythmic_value)
+      raise HeadMusic::Notation::ABC::RenderError, "#{message}: #{rhythmic_value}"
+    end
+  end
+end

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

@@ -20,6 +20,51 @@ class HeadMusic::Notation::ABC::KeyMapper
     "loc" => "locrian"
   }.freeze
 
+  # MODE_NAMES_BY_PREFIX is many-to-one, so rendering uses this explicit
+  # inverse map. Every suffix here parses back to an equal key signature
+  # (ionian/aeolian differ from major/minor only in name, not alterations).
+  ABC_SUFFIXES_BY_MODE = {
+    "major" => "",
+    "ionian" => "",
+    "minor" => "m",
+    "aeolian" => "m",
+    "dorian" => "dor",
+    "phrygian" => "phr",
+    "lydian" => "lyd",
+    "mixolydian" => "mix",
+    "locrian" => "loc"
+  }.freeze
+
+  # Returns the ABC K: field value for a key signature.
+  def self.abc_value(key_signature)
+    key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature)
+    "#{tonic_string(key_signature)}#{mode_suffix(key_signature)}"
+  end
+
+  def self.tonic_string(key_signature)
+    spelling = key_signature.tonic_spelling
+    alteration = spelling.alteration
+    if alteration && (alteration.double_sharp? || alteration.double_flat?)
+      raise_render_error("Cannot render double-altered tonic #{spelling} in an ABC K: field")
+    end
+
+    # ABC convention uses ASCII "#"/"b" rather than the unicode signs
+    # that Spelling#to_s produces.
+    "#{spelling.letter_name}#{alteration&.ascii}"
+  end
+  private_class_method :tonic_string
+
+  def self.mode_suffix(key_signature)
+    ABC_SUFFIXES_BY_MODE[key_signature.scale_type.name.to_s] ||
+      raise_render_error("Cannot render scale type #{key_signature.scale_type} in an ABC K: field")
+  end
+  private_class_method :mode_suffix
+
+  def self.raise_render_error(message)
+    raise HeadMusic::Notation::ABC::RenderError, message
+  end
+  private_class_method :raise_render_error
+
   attr_reader :value, :line_number
 
   def initialize(value, line_number: nil)

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

@@ -0,0 +1,72 @@
+# A namespace for ABC-notation parsing helpers
+module HeadMusic::Notation::ABC
+  # Converts pitches into ABC note tokens, emitting the minimal accidental
+  # marks required under the key signature and ABC's bar-persistent rules.
+  #
+  # A live PitchBuilder acts as an oracle: if an unmarked token would already
+  # parse back to the target pitch, no accidental is written. Emitted tokens
+  # are fed back through the oracle so its bar state matches what a parser
+  # will accumulate when re-reading the output.
+  class PitchWriter
+    attr_reader :key_signature
+
+    def initialize(key_signature)
+      @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature)
+      @oracle = PitchBuilder.new(@key_signature)
+    end
+
+    # Returns the ABC note token for the pitch, without any duration multiplier.
+    def token(pitch)
+      pitch = HeadMusic::Rudiment::Pitch.get(pitch)
+      letter = letter_token(pitch)
+      octave_marks = octave_marks(pitch)
+      return "#{letter}#{octave_marks}" if oracle.pitch(letter, octave_marks) == pitch
+
+      marks = accidental_marks(pitch)
+      commit_and_verify(pitch, letter, octave_marks, marks)
+      "#{marks}#{letter}#{octave_marks}"
+    end
+
+    # In ABC, accidentals persist only to the end of the bar.
+    def start_new_bar
+      oracle.start_new_bar
+    end
+
+    private
+
+    attr_reader :oracle
+
+    def letter_token(pitch)
+      letter = pitch.letter_name.to_s
+      (pitch.register >= 5) ? letter.downcase : letter
+    end
+
+    def octave_marks(pitch)
+      if pitch.register >= 5
+        "'" * (pitch.register - 5)
+      else
+        "," * (4 - pitch.register)
+      end
+    end
+
+    def accidental_marks(pitch)
+      fragment = pitch.alteration&.ascii.to_s
+      accidental_marks_by_fragment.fetch(fragment) do
+        raise RenderError, "cannot express #{pitch} in ABC notation"
+      end
+    end
+
+    def accidental_marks_by_fragment
+      @accidental_marks_by_fragment ||= PitchBuilder::ACCIDENTAL_FRAGMENTS.invert
+    end
+
+    # Feeding the marked token through the oracle updates its bar state
+    # exactly as a parser reading the output would — this call is load-bearing,
+    # not just a verification; later unmarked notes depend on the state it writes.
+    def commit_and_verify(pitch, letter, octave_marks, marks)
+      return if oracle.pitch(letter, octave_marks, marks) == pitch
+
+      raise RenderError, "cannot express #{pitch} in ABC notation"
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# Parses and renders ABC notation as HeadMusic::Content compositions
+module HeadMusic::Notation::ABC
+  # Renders a HeadMusic::Content::Composition as an ABC tune string.
+  #
+  # Whole-composition problems (multiple voices, mid-piece meter or key
+  # changes, positional gaps) raise before any string assembly, and #to_s
+  # only returns a fully assembled document, so callers never receive a
+  # truncated tune.
+  #
+  # Repeat barlines and voltas are deliberately not rendered; bars carrying
+  # repeat flags degrade to plain bar lines.
+  class Writer
+    # A fixed unit note length keeps the L: field and the duration
+    # multiplier arithmetic in sync.
+    UNIT_NOTE_LENGTH = Rational(1, 8)
+    BARS_PER_LINE = 4
+
+    attr_reader :composition, :reference_number
+
+    def initialize(composition, reference_number: 1)
+      @composition = composition
+      @reference_number = reference_number
+    end
+
+    def to_s
+      validate!
+      (header_lines + body_lines).join("\n") + "\n"
+    end
+
+    private
+
+    def validate!
+      ensure_single_voice
+      ensure_no_mid_piece_changes
+      ensure_contiguous_placements
+    end
+
+    def ensure_single_voice
+      return if composition.voices.length <= 1
+
+      raise RenderError, "multi-voice ABC output is not supported"
+    end
+
+    def ensure_no_mid_piece_changes
+      composition.bars.each_with_index do |bar, index|
+        bar_number = composition.earliest_bar_number + index
+        if bar.meter
+          raise RenderError, "cannot render the meter change at bar #{bar_number} in ABC output"
+        end
+        next unless bar.key_signature
+
+        raise RenderError, "cannot render the key signature change at bar #{bar_number} in ABC output"
+      end
+    end
+
+    def ensure_contiguous_placements
+      first = placements.first
+      return unless first
+
+      ensure_placement_starts_bar(first)
+      placements.each_cons(2) do |previous, current|
+        next if current.position == previous.next_position
+
+        raise RenderError, "expected a placement at #{previous.next_position}, " \
+          "found one at #{current.position}; insert explicit rests to fill gaps"
+      end
+    end
+
+    def ensure_placement_starts_bar(placement)
+      position = placement.position
+      return if position.count == 1 && position.tick.zero?
+
+      raise RenderError, "the first placement must start its bar " \
+        "(found #{position}); insert explicit rests to fill the gap"
+    end
+
+    def placements
+      voice = composition.voices.first
+      voice ? voice.placements : []
+    end
+
+    def header_lines
+      [
+        "X:#{reference_number}",
+        "T:#{composition.name}",
+        composition.composer && "C:#{composition.composer}",
+        composition.origin && "O:#{composition.origin}",
+        "M:#{composition.meter}",
+        "L:#{UNIT_NOTE_LENGTH.numerator}/#{UNIT_NOTE_LENGTH.denominator}",
+        # The parser requires K: to terminate the header.
+        "K:#{KeyMapper.abc_value(composition.key_signature)}"
+      ].compact
+    end
+
+    def body_lines
+      return [] if bar_strings.empty?
+
+      lines = bar_strings.each_slice(BARS_PER_LINE).map do |line_bars|
+        line_bars.join("|") + "|"
+      end
+      lines[-1] = lines[-1].sub(/\|\z/, "|]")
+      lines
+    end
+
+    def bar_strings
+      @bar_strings ||= build_bar_strings
+    end
+
+    def build_bar_strings
+      pitch_writer = PitchWriter.new(composition.key_signature)
+      duration_writer = DurationWriter.new(UNIT_NOTE_LENGTH)
+      bar_groups = placements.chunk_while do |previous, current|
+        previous.position.bar_number == current.position.bar_number
+      end
+      bar_groups.each_with_index.map do |bar_placements, index|
+        # Accidental state must mirror what a re-parse accumulates bar by bar.
+        pitch_writer.start_new_bar if index.positive?
+        bar_placements.map { |placement| token(placement, pitch_writer, duration_writer) }.join(" ")
+      end
+    end
+
+    def token(placement, pitch_writer, duration_writer)
+      multiplier = duration_writer.multiplier_string(placement.rhythmic_value)
+      return "z#{multiplier}" if placement.rest?
+
+      "#{pitch_writer.token(placement.pitch)}#{multiplier}"
+    end
+  end
+end

data/lib/head_music/notation/abc.rb

@@ -1,4 +1,4 @@
-# Parses ABC notation into HeadMusic::Content compositions
+# Parses and renders ABC notation as HeadMusic::Content compositions
 module HeadMusic::Notation::ABC
   # Parses exactly one tune. Raises when the input holds more than one.
   def self.parse(abc_string)
@@ -10,6 +10,11 @@ module HeadMusic::Notation::ABC
     BookParser.new(abc_string).compositions
   end
 
+  # Renders a composition as an ABC tune string.
+  def self.render(composition, **options)
+    Writer.new(composition, **options).to_s
+  end
+
   # Raised when an ABC string cannot be interpreted
   class ParseError < HeadMusic::Notation::ParseError
     attr_reader :line_number, :snippet
@@ -24,6 +29,9 @@ module HeadMusic::Notation::ABC
 
   # Raised for valid ABC constructs that this parser does not support
   class UnsupportedFeatureError < ParseError; end
+
+  # Raised when a composition cannot be expressed in the supported ABC subset
+  class RenderError < HeadMusic::Notation::RenderError; end
 end
 
 # Helper classes load in name order; they reference one another only at runtime.

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

@@ -0,0 +1,26 @@
+# A namespace for MusicXML-notation rendering helpers
+module HeadMusic::Notation::MusicXML
+  # Chooses a clef for a voice based on the midpoint of its pitch range.
+  class ClefSelector
+    MIDDLE_C_MIDI_NOTE_NUMBER = 60
+
+    # Returns the treble clef for a voice with no notes (rest-only or empty),
+    # and otherwise the clef whose side of middle C matches the midpoint of
+    # the voice's lowest and highest pitches. A midpoint exactly on middle C
+    # is treated as treble.
+    def self.for(voice)
+      return HeadMusic::Rudiment::Clef.get(:treble_clef) unless voice.lowest_pitch
+
+      if midpoint(voice) < MIDDLE_C_MIDI_NOTE_NUMBER
+        HeadMusic::Rudiment::Clef.get(:bass_clef)
+      else
+        HeadMusic::Rudiment::Clef.get(:treble_clef)
+      end
+    end
+
+    def self.midpoint(voice)
+      (voice.lowest_pitch.midi_note_number + voice.highest_pitch.midi_note_number) / 2.0
+    end
+    private_class_method :midpoint
+  end
+end

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

@@ -0,0 +1,43 @@
+# A namespace for MusicXML-notation rendering helpers
+module HeadMusic::Notation::MusicXML
+  # Computes the smallest MusicXML <divisions> value (subdivisions of a
+  # quarter note) that lets every note, rest, and whole-measure duration
+  # in a composition be expressed as an exact integer.
+  class Divisions
+    def self.for(composition)
+      denominators(composition).reduce(1) { |lcm, denominator| lcm.lcm(denominator) }
+    end
+
+    def self.denominators(composition)
+      meter_denominators(composition) + note_denominators(composition)
+    end
+    private_class_method :denominators
+
+    # A whole measure of rest must also be expressible as an integer, so the
+    # base meter and every meter change's quarter-note-equivalent duration
+    # contributes a denominator too (e.g. 3/8 needs divisions divisible by 2).
+    # Bar#meter is a plain attr_accessor, so a bar's meter is normalized
+    # through Meter.get here in case a caller assigned it a bare string.
+    def self.meter_denominators(composition)
+      meters = [composition.meter] + composition.bars.map(&:meter).compact
+      meters.map { |meter| HeadMusic::Rudiment::Meter.get(meter) }
+        .map { |meter| Rational(4 * meter.top_number, meter.bottom_number).denominator }
+    end
+    private_class_method :meter_denominators
+
+    def self.note_denominators(composition)
+      composition.voices.flat_map do |voice|
+        voice.placements.flat_map { |placement| chain_denominators(placement.rhythmic_value) }
+      end
+    end
+    private_class_method :note_denominators
+
+    def self.chain_denominators(rhythmic_value)
+      denominators = [DurationWriter.single_quarter_fraction(rhythmic_value).denominator]
+      tied_value = rhythmic_value.tied_value
+      denominators += chain_denominators(tied_value) if tied_value
+      denominators
+    end
+    private_class_method :chain_denominators
+  end
+end

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

@@ -0,0 +1,82 @@
+# A namespace for MusicXML-notation rendering helpers
+module HeadMusic::Notation::MusicXML
+  # Converts a HeadMusic::Rudiment::RhythmicValue into the <duration>,
+  # <type>, dot count, and tie flags MusicXML needs for each link of a
+  # tied chain. A value with no tied chain yields a single component.
+  class DurationWriter
+    Component = Struct.new(:duration, :type, :dots, :tie_start, :tie_stop, keyword_init: true)
+
+    # MusicXML's <type> element uses these fixed names rather than the
+    # gem's American duration names.
+    TYPES_BY_UNIT_NAME = {
+      "maxima" => "maxima",
+      "longa" => "long",
+      "double whole" => "breve",
+      "whole" => "whole",
+      "half" => "half",
+      "quarter" => "quarter",
+      "eighth" => "eighth",
+      "sixteenth" => "16th",
+      "thirty-second" => "32nd",
+      "sixty-fourth" => "64th",
+      "hundred twenty-eighth" => "128th",
+      "two hundred fifty-sixth" => "256th"
+    }.freeze
+
+    attr_reader :divisions
+
+    def initialize(divisions)
+      @divisions = divisions
+    end
+
+    # A rhythmic value's own duration in quarter notes, ignoring any tied
+    # chain. RhythmicValue's own methods (relative_value, total_value,
+    # ticks) return Floats, so the fraction is rebuilt here from the
+    # unit's integer numerator and denominator to keep the divisions
+    # arithmetic exact.
+    def self.single_quarter_fraction(rhythmic_value)
+      unit = rhythmic_value.unit
+      dots = rhythmic_value.dots
+      # 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) * 4
+    end
+
+    def components(rhythmic_value)
+      links = chain(rhythmic_value)
+      links.each_with_index.map { |link, index| build_component(link, index, links.length) }
+    end
+
+    private
+
+    def chain(rhythmic_value)
+      links = [rhythmic_value]
+      links << links.last.tied_value while links.last.tied_value
+      links
+    end
+
+    def build_component(link, index, length)
+      Component.new(
+        duration: integer_duration(link),
+        type: type_for(link),
+        dots: link.dots,
+        tie_start: index != length - 1,
+        tie_stop: index != 0
+      )
+    end
+
+    def integer_duration(link)
+      fraction = self.class.single_quarter_fraction(link) * divisions
+      unless fraction.denominator == 1
+        raise HeadMusic::Notation::MusicXML::RenderError,
+          "cannot express #{link} as an integer duration at #{divisions} divisions per quarter note"
+      end
+      fraction.numerator
+    end
+
+    def type_for(link)
+      TYPES_BY_UNIT_NAME.fetch(link.unit_name) do
+        raise HeadMusic::Notation::MusicXML::RenderError, "no MusicXML note type is known for #{link.unit_name}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# A namespace for MusicXML-notation rendering helpers
+module HeadMusic::Notation::MusicXML
+  # Converts a key signature into the fifths/mode pair MusicXML's
+  # <key> element needs.
+  class KeyMapper
+    # MusicXML's <mode> element only names these seven modes, so scale
+    # types outside this set (harmonic minor, whole tone, etc.) cannot
+    # be rendered as a <key> element and must raise instead.
+    MODE_NAMES_BY_SCALE_TYPE = {
+      "major" => "major",
+      "ionian" => "major",
+      "minor" => "minor",
+      "aeolian" => "minor",
+      "dorian" => "dorian",
+      "phrygian" => "phrygian",
+      "lydian" => "lydian",
+      "mixolydian" => "mixolydian",
+      "locrian" => "locrian"
+    }.freeze
+
+    # Returns the number of sharps (positive) or flats (negative) for the
+    # <fifths> element. Theoretical keys with double accidentals (e.g. G#
+    # major) count each double accidental twice, which is correct here.
+    def self.fifths(key_signature)
+      key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature)
+      key_signature.num_sharps - key_signature.num_flats
+    end
+
+    # Returns the <mode> element value for a key signature.
+    def self.mode(key_signature)
+      key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature)
+      MODE_NAMES_BY_SCALE_TYPE[key_signature.scale_type.name.to_s] ||
+        raise_render_error("Cannot render scale type #{key_signature.scale_type} in a MusicXML <key> element")
+    end
+
+    def self.raise_render_error(message)
+      raise HeadMusic::Notation::MusicXML::RenderError, message
+    end
+    private_class_method :raise_render_error
+  end
+end

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

@@ -0,0 +1,21 @@
+# A namespace for MusicXML-notation rendering helpers
+module HeadMusic::Notation::MusicXML
+  # Converts pitches into the trio of values MusicXML's <pitch> element needs.
+  #
+  # Unlike ABC, MusicXML's <alter> is absolute rather than bar-persistent, so
+  # no oracle or mutable state is required: each pitch maps to its attributes
+  # independent of any other pitch that came before it.
+  class PitchWriter
+    # Returns a Hash of the step, alter, and octave for the pitch's
+    # <pitch> element. Alter is nil when the pitch is natural, in which
+    # case the caller should omit the <alter> element entirely.
+    def self.attributes(pitch)
+      pitch = HeadMusic::Rudiment::Pitch.get(pitch)
+      {
+        step: pitch.letter_name.to_s,
+        alter: pitch.alteration_semitones,
+        octave: pitch.register
+      }
+    end
+  end
+end