head_music 9.0.1 → 11.1.0

data/user_stories/{todo → done}/pitch-class-set-analysis.md

@@ -6,46 +6,6 @@ I want to analyze pitch class sets
 
 So that I can identify set relationships and transformations
 
-## Scenario: Get size of pitch class set
-
-Given I have a pitch class set
-
-When I call the size method
-
-Then it should return the number of unique pitch classes
-
-## Scenario: Check if monad
-
-Given I have a pitch class set with one pitch class
-
-When I call monad?
-
-Then it should return true
-
-## Scenario: Check if dyad
-
-Given I have a pitch class set with two pitch classes
-
-When I call dyad?
-
-Then it should return true
-
-## Scenario: Check if triad
-
-Given I have a pitch class set with three pitch classes
-
-When I call triad?
-
-Then it should return true only if they form stacked thirds
-
-## Scenario: Check if trichord
-
-Given I have a pitch class set with three pitch classes
-
-When I call trichord?
-
-Then it should return true for any 3-pitch class set
-
 ## Scenario: Find normal form
 
 Given I have a pitch class set

data/user_stories/done/sonority-identification.md

@@ -0,0 +1,37 @@
+# Sonority Identification
+
+As a music theorist or composer
+
+I want to identify and work with named sonorities
+
+So that I can analyze and create harmonic structures
+
+## Scenario: Get sonority by identifier
+
+Given I need a specific sonority
+
+When I call Sonority.get with an identifier like "major_triad"
+
+Then I should receive the corresponding sonority object
+
+And it should contain the correct interval structure
+
+## Scenario: Generate pitch collection from sonority
+
+Given I have a sonority identifier and a root pitch
+
+When I call a method to generate pitches
+
+Then I should receive the correct pitches for that sonority
+
+And they should be in the specified inversion
+
+## Scenario: Access sonority from pitch collection
+
+Given I have a PitchCollection object
+
+When I call the sonority method
+
+Then I should receive the corresponding Sonority object
+
+And it should correctly identify the harmonic content

data/user_stories/done/string-pitches.md

@@ -0,0 +1,41 @@
+# Instruments can have strings with pitches
+
+Instruments like violins and guitars have strings that are each tuned to a specific pitch.
+
+## Implementation Plan
+
+HeadMusic::Instruments::Instrument
+
+HeadMusic::Instruments::Stringing
+> instrument: Instrument
+>> stringing_courses: StringingCourse[]
+
+HeadMusic::Instruments::StringingCourse
+> stringing: Stringing
+> standard_pitch: HeadMusic::Rudiment::Pitch
+  for example, the lowest string of a guitar, "E2"
+- course_semitones: Integer[]
+  Examples:
+  a 6-string guitar would be []
+  a 12-string guitar would be [12] for the low strings and [0] for the high strings
+
+HeadMusic::Instruments::AlternateTuning
+> instrument: Instrument
+- name: string
+>> semitones: int[]
+   lowest to highest string courses in the strings
+
+
+## Answering questions
+
+> Would it make more sense for Stringing to be associated with InstrumentConfiguration (the variant) rather than Instrument directly?
+
+No, each instrument could have a Stringing object. If not, it would inherit from it's ancestry, just like most Instrument attributes.
+
+> Is the semitone offset approach intentional for simplicity, or would you prefer something more explicit?
+
+It is intentional. That way, the courses are independent of the specific tunings.
+
+> Overlap Between standard_pitch and StringingTuning
+
+The standard pitch is the unconfigured pitch of the string intrinsic to standard practice for that instrument. The Tuning objects configure alternative sets of pitches

data/user_stories/epics/notation-module.md

@@ -0,0 +1,135 @@
+# EPIC: Notation Module
+
+AS a developer
+
+I WANT to organize notation-related features in a dedicated HeadMusic::Notation module
+
+SO THAT I can clearly separate visual representation concerns from music theory, instrument properties, and musical content
+
+## Vision
+
+Music notation is about visual representation - how musical concepts appear on paper, screen, or other media. This is conceptually distinct from:
+- **Music theory** (abstract concepts like pitch, interval, harmony)
+- **Instrument properties** (range, transposition, acoustic characteristics)
+- **Musical content** (compositions, temporal organization)
+
+A dedicated Notation module provides a clear home for all visual representation concerns, making the codebase more organized and enabling future expansion into comprehensive music engraving capabilities.
+
+## Background
+
+Currently, notation-related code is scattered across multiple modules:
+- **HeadMusic::Instruments** contains `StaffPosition`, `Staff`, `StaffMapping`, and `StaffScheme`
+- **HeadMusic::Rudiment** contains `Clef`, `MusicalSymbol`, and notation aspects of `Alteration` and `RhythmicUnit`
+- **HeadMusic::Content** has its own minimal `Staff` class
+
+A TODO comment in `lib/head_music/instruments/staff_position.rb:5` suggests: "consider moving to a HeadMusic::Notation module"
+
+This scattered organization makes it unclear where new notation features should live and conflates distinct concerns.
+
+## Module Boundaries
+
+### HeadMusic::Notation (visual representation)
+- Staff positions, lines, spaces, ledger lines
+- Musical symbols (ASCII, Unicode, HTML entities)
+- Notehead shapes and placement on staff
+- Stem direction and flags
+- Clef symbols and their staff placement
+- Accidental symbol placement
+- Future: beaming, ties, slurs, articulations, dynamics
+
+### HeadMusic::Rudiment (music theory)
+- Abstract concepts: pitch, interval, scale, chord
+- Duration concepts (without visual representation)
+- Keys, meters (as musical concepts, not visual symbols)
+- Core theory that notation represents visually
+
+### HeadMusic::Instruments (instrument properties)
+- Instrument families and classification
+- Pitch ranges and transposition
+- Playing techniques
+- Score ordering
+- References to default clef (but doesn't own clef rendering)
+
+### HeadMusic::Content (musical content)
+- Compositions, voices, bars
+- Notes in context (pitch + duration + placement)
+- Temporal organization
+- Uses Notation for visual representation
+
+## Scope
+
+### Phase 1: Foundation & Core Moves (Current Focus)
+- Establish module infrastructure
+- Move `StaffPosition` from Instruments to Notation
+- Move `MusicalSymbol` from Rudiment to Notation
+- Move `StaffMapping` from Instruments to Notation
+
+**User Stories:**
+- [Notation Module Foundation](../backlog/notation-module-foundation.md)
+- [Move StaffPosition to Notation](../backlog/move-staff-position-to-notation.md)
+- [Move MusicalSymbol to Notation](../backlog/move-musical-symbol-to-notation.md)
+- [Move StaffMapping to Notation](../backlog/move-staff-mapping-to-notation.md)
+
+### Phase 2: Extract Notation Aspects (Future)
+- Create `ClefPlacement` - extract visual clef positioning from `Rudiment::Clef`
+- Create `AccidentalPlacement` - extract accidental display rules from `Rudiment::Alteration`
+- Create `RhythmicNotation` - extract notehead, stem, flag logic from `Rudiment::RhythmicUnit`
+- Refactor `StaffScheme` to `Notation::StaffSystem`
+
+### Phase 3: Advanced Notation Features (Long-term Vision)
+- Beaming (connecting note stems across beats)
+- Stems (direction and length calculation)
+- Ties (connecting same pitches across bars)
+- Slurs (phrase markings)
+- Articulations (staccato, accent, tenuto, etc.)
+- Dynamics (forte, piano, crescendo, etc.)
+- Tuplets (triplets, quintuplets, etc.)
+- Barlines (single, double, repeat)
+- Ornaments (trills, mordents, turns)
+- Fermatas (pause markings)
+
+### Beyond Western Staff Notation (Future Exploration)
+
+The Notation module could eventually support multiple notation systems:
+
+**Traditional notation systems:**
+- Western staff notation (current focus)
+- Tablature (tab) - finger positions for guitar, bass, lute
+- Shaped note notation - different note head shapes for scale degrees
+- Drum notation - modified staff notation for percussion
+
+**Alphanumeric and shorthand systems:**
+- Lead sheet notation - melody with chord symbols
+- Nashville Number System - scale degrees instead of chord names
+- Roman numeral analysis - functional harmony labels
+- ABC notation - text-based system for folk music
+- Figured bass - Baroque-era interval shorthand
+
+**Digital/computer formats:**
+- MIDI - note events with pitch, velocity, timing
+- MusicXML - XML-based interchange format
+- Lilypond - text-based music engraving
+- MEI (Music Encoding Initiative) - scholarly encoding
+
+## Success Criteria
+
+**Module Organization:**
+- Clear separation between theory (Rudiment), notation (Notation), instruments (Instruments), and content (Content)
+- All visual representation concerns organized under `HeadMusic::Notation`
+- Documentation clearly explains what belongs in each module
+
+**Code Quality:**
+- All moved classes maintain existing functionality
+- 90%+ test coverage maintained throughout
+- No breaking changes for internal usage
+- All TODO comments resolved
+
+**Extensibility:**
+- Module designed for future expansion (beams, ties, dynamics, etc.)
+- Support for multiple output formats (Unicode, MusicXML, SVG)
+- Clear patterns established for adding new notation features
+
+**Developer Experience:**
+- Clear guidance in CLAUDE.md about where notation features belong
+- Easy to find and use notation-related classes
+- Logical organization that matches mental model of music notation

data/user_stories/{todo → visioning}/agentic-daw.md

@@ -1,3 +1,2 @@
-
 agent-centric multimedia scoring
 (A/V DAW)

metadata

@@ -1,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 9.0.1
+  version: 11.1.0
 platform: ruby
 authors:
 - Rob Head
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-24 00:00:00.000000000 Z
+date: 2026-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
 - !ruby/object:Gem::Dependency
   name: humanize
   requirement: !ruby/object:Gem::Requirement
@@ -156,7 +162,6 @@ files:
 - bin/check_instrument_consistency.rb
 - bin/console
 - bin/setup
-- check_instrument_consistency.rb
 - head_music.gemspec
 - lib/head_music.rb
 - lib/head_music/analysis/circle.rb
@@ -166,30 +171,41 @@ files:
 - lib/head_music/analysis/diatonic_interval/parser.rb
 - lib/head_music/analysis/diatonic_interval/semitones.rb
 - lib/head_music/analysis/diatonic_interval/size.rb
+- lib/head_music/analysis/dyad.rb
 - lib/head_music/analysis/harmonic_interval.rb
 - lib/head_music/analysis/interval_consonance.rb
 - lib/head_music/analysis/interval_cycle.rb
 - lib/head_music/analysis/melodic_interval.rb
 - lib/head_music/analysis/motion.rb
 - lib/head_music/analysis/pitch_class_set.rb
-- lib/head_music/analysis/pitch_set.rb
+- lib/head_music/analysis/pitch_collection.rb
 - lib/head_music/analysis/sonority.rb
 - lib/head_music/content/bar.rb
+- lib/head_music/content/cantus_firmus_examples.rb
 - lib/head_music/content/composition.rb
 - lib/head_music/content/note.rb
 - lib/head_music/content/placement.rb
 - lib/head_music/content/position.rb
 - lib/head_music/content/staff.rb
 - lib/head_music/content/voice.rb
+- lib/head_music/instruments/alternate_tuning.rb
+- lib/head_music/instruments/alternate_tunings.yml
 - lib/head_music/instruments/instrument.rb
+- lib/head_music/instruments/instrument_configuration.rb
+- lib/head_music/instruments/instrument_configuration_option.rb
+- lib/head_music/instruments/instrument_configurations.yml
 - lib/head_music/instruments/instrument_families.yml
 - lib/head_music/instruments/instrument_family.rb
-- lib/head_music/instruments/instrument_type.rb
 - lib/head_music/instruments/instruments.yml
+- lib/head_music/instruments/playing_technique.rb
+- lib/head_music/instruments/playing_techniques.yml
 - lib/head_music/instruments/score_order.rb
 - lib/head_music/instruments/score_orders.yml
 - lib/head_music/instruments/staff.rb
 - lib/head_music/instruments/staff_scheme.rb
+- lib/head_music/instruments/stringing.rb
+- lib/head_music/instruments/stringing_course.rb
+- lib/head_music/instruments/stringings.yml
 - lib/head_music/instruments/variant.rb
 - lib/head_music/locales/de.yml
 - lib/head_music/locales/en.yml
@@ -199,7 +215,12 @@ files:
 - lib/head_music/locales/it.yml
 - lib/head_music/locales/ru.yml
 - lib/head_music/named.rb
+- lib/head_music/notation.rb
+- lib/head_music/notation/musical_symbol.rb
+- lib/head_music/notation/staff_mapping.rb
+- lib/head_music/notation/staff_position.rb
 - lib/head_music/rudiment/alteration.rb
+- lib/head_music/rudiment/alterations.yml
 - lib/head_music/rudiment/base.rb
 - lib/head_music/rudiment/chromatic_interval.rb
 - lib/head_music/rudiment/clef.rb
@@ -212,7 +233,6 @@ files:
 - lib/head_music/rudiment/letter_name.rb
 - lib/head_music/rudiment/meter.rb
 - lib/head_music/rudiment/mode.rb
-- lib/head_music/rudiment/musical_symbol.rb
 - lib/head_music/rudiment/note.rb
 - lib/head_music/rudiment/pitch.rb
 - lib/head_music/rudiment/pitch/enharmonic_equivalence.rb
@@ -287,26 +307,42 @@ files:
 - lib/head_music/style/modern_tradition.rb
 - lib/head_music/style/renaissance_tradition.rb
 - lib/head_music/style/tradition.rb
+- lib/head_music/time.rb
+- lib/head_music/time/clock_position.rb
+- lib/head_music/time/conductor.rb
+- lib/head_music/time/meter_event.rb
+- lib/head_music/time/meter_map.rb
+- lib/head_music/time/musical_position.rb
+- lib/head_music/time/smpte_timecode.rb
+- lib/head_music/time/tempo_event.rb
+- lib/head_music/time/tempo_map.rb
+- lib/head_music/utilities/case.rb
 - lib/head_music/utilities/hash_key.rb
 - lib/head_music/version.rb
-- test_translations.rb
-- user_stories/active/handle-time.md
-- user_stories/active/handle-time.rb
+- user_stories/backlog/notation-style.md
+- user_stories/backlog/organizing-content.md
+- user_stories/done/consonance-dissonance-classification.md
+- user_stories/done/dyad-analysis.md
 - user_stories/done/epic--score-order/PLAN.md
 - user_stories/done/epic--score-order/band-score-order.md
 - user_stories/done/epic--score-order/chamber-ensemble-score-order.md
 - user_stories/done/epic--score-order/orchestral-score-order.md
+- user_stories/done/expand-playing-techniques.md
+- user_stories/done/handle-time.md
+- user_stories/done/handle-time.rb
+- user_stories/done/instrument-architecture.md
 - user_stories/done/instrument-variant.md
+- user_stories/done/move-musical-symbol-to-notation.md
+- user_stories/done/move-staff-mapping-to-notation.md
+- user_stories/done/move-staff-position-to-notation.md
+- user_stories/done/notation-module-foundation.md
+- user_stories/done/percussion_set.md
+- user_stories/done/pitch-class-set-analysis.md
+- user_stories/done/sonority-identification.md
+- user_stories/done/string-pitches.md
 - user_stories/done/superclass-for-note.md
-- user_stories/todo/agentic-daw.md
-- user_stories/todo/consonance-dissonance-classification.md
-- user_stories/todo/dyad-analysis.md
-- user_stories/todo/material-and-scores.md
-- user_stories/todo/organizing-content.md
-- user_stories/todo/percussion_set.md
-- user_stories/todo/pitch-class-set-analysis.md
-- user_stories/todo/pitch-set-classification.md
-- user_stories/todo/sonority-identification.md
+- user_stories/epics/notation-module.md
+- user_stories/visioning/agentic-daw.md
 homepage: https://github.com/roberthead/head_music
 licenses:
 - MIT

data/lib/head_music/instruments/instrument_type.rb

@@ -1,188 +0,0 @@
-# Namespace for instrument definitions, categorization, and configuration
-module HeadMusic::Instruments; end
-
-# A musical instrument type representing a catalog entry.
-# An instrument type defines the base characteristics and available variants for an instrument.
-# Attributes:
-#   name_key: the name of the instrument type
-#   alias_name_keys: an array of alternative names for the instrument type
-#   orchestra_section_key: the section of the orchestra (e.g. "strings")
-#   family_key: the key for the family of the instrument (e.g. "saxophone")
-#   classification_keys: an array of classification_keys
-#   default_clefs: the default clef or system of clefs for the instrument type
-#     - [treble] for instruments that use the treble clef
-#     - [treble, bass] for instruments that use the grand staff
-#   variants:
-#     a hash of default and alternative pitch designations
-# Associations:
-#   family: the family of the instrument (e.g. "saxophone")
-#   orchestra_section: the section of the orchestra (e.g. "strings")
-class HeadMusic::Instruments::InstrumentType
-  include HeadMusic::Named
-
-  INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
-
-  def self.get(name)
-    get_by_name(name)
-  end
-
-  def self.all
-    HeadMusic::Instruments::InstrumentFamily.all
-    @all ||=
-      INSTRUMENTS.map { |key, _data| get(key) }.sort_by { |instrument| instrument.name.downcase }
-  end
-
-  attr_reader(
-    :name_key, :alias_name_keys,
-    :family_key, :orchestra_section_key,
-    :variants, :classification_keys
-  )
-
-  def ==(other)
-    to_s == other.to_s
-  end
-
-  def translation(locale = :en)
-    return name unless name_key
-
-    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
-  end
-
-  def family
-    return unless family_key
-
-    HeadMusic::Instruments::InstrumentFamily.get(family_key)
-  end
-
-  # Returns true if the instrument sounds at a different pitch than written.
-  def transposing?
-    default_sounding_transposition != 0
-  end
-
-  # Returns true if the instrument sounds at a different register than written.
-  def transposing_at_the_octave?
-    transposing? && default_sounding_transposition % 12 == 0
-  end
-
-  def single_staff?
-    default_staves.length == 1
-  end
-
-  def multiple_staves?
-    default_staves.length > 1
-  end
-
-  def pitched?
-    return false if default_clefs.compact.uniq == [HeadMusic::Rudiment::Clef.get("neutral_clef")]
-
-    default_clefs.any?
-  end
-
-  def default_variant
-    variants&.find(&:default?) || variants&.first
-  end
-
-  def default_instrument
-    @default_instrument ||= HeadMusic::Instruments::Instrument.new(self, default_variant)
-  end
-
-  def default_staff_scheme
-    default_variant&.default_staff_scheme
-  end
-
-  def default_staves
-    default_staff_scheme&.staves || []
-  end
-
-  def default_clefs
-    default_staves&.map(&:clef) || []
-  end
-
-  def default_sounding_transposition
-    default_staves&.first&.sounding_transposition || 0
-  end
-
-  private_class_method :new
-
-  private
-
-  def initialize(name)
-    record = record_for_name(name)
-    if record
-      initialize_data_from_record(record)
-    else
-      self.name = name.to_s
-    end
-  end
-
-  def record_for_name(name)
-    record_for_key(HeadMusic::Utilities::HashKey.for(name)) ||
-      record_for_key(key_for_name(name)) ||
-      record_for_alias(name)
-  end
-
-  def key_for_name(name)
-    INSTRUMENTS.each do |key, _data|
-      I18n.config.available_locales.each do |locale|
-        translation = I18n.t("head_music.instruments.#{key}", locale: locale)
-        return key if translation.downcase == name.downcase
-      end
-    end
-    nil
-  end
-
-  def record_for_key(key)
-    INSTRUMENTS.each do |name_key, data|
-      return data.merge!("name_key" => name_key) if name_key.to_s == key.to_s
-    end
-    nil
-  end
-
-  def record_for_alias(name)
-    normalized_name = HeadMusic::Utilities::HashKey.for(name).to_s
-    INSTRUMENTS.each do |name_key, data|
-      data["alias_name_keys"]&.each do |alias_key|
-        return data.merge!("name_key" => name_key) if HeadMusic::Utilities::HashKey.for(alias_key).to_s == normalized_name
-      end
-    end
-    nil
-  end
-
-  def initialize_data_from_record(record)
-    initialize_family(record)
-    inherit_family_attributes(record)
-    initialize_names(record)
-    initialize_attributes(record)
-  end
-
-  def initialize_family(record)
-    @family_key = record["family_key"]
-    @family = HeadMusic::Instruments::InstrumentFamily.get(family_key)
-  end
-
-  def inherit_family_attributes(record)
-    return unless family
-
-    @orchestra_section_key = family.orchestra_section_key
-    @classification_keys = family.classification_keys || []
-  end
-
-  def initialize_names(record)
-    @name_key = record["name_key"].to_sym
-    self.name = I18n.translate(name_key, scope: "head_music.instruments", locale: "en", default: inferred_name)
-    @alias_name_keys = record["alias_name_keys"] || []
-  end
-
-  def initialize_attributes(record)
-    @orchestra_section_key ||= record["orchestra_section_key"]
-    @classification_keys = [@classification_keys, record["classification_keys"]].flatten.compact.uniq
-    @variants =
-      (record["variants"] || {}).map do |key, attributes|
-        HeadMusic::Instruments::Variant.new(key, attributes)
-      end
-  end
-
-  def inferred_name
-    name_key.to_s.tr("_", " ")
-  end
-end

data/test_translations.rb

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-
-# Test the translation loading functionality
-
-# First test - German translation of solfege
-result = system('bundle exec ruby -e "require \'head_music\'; puts HeadMusic::Rudiment::Solmization.get(\'Solfège\')&.name || \'nil\'"')
-puts "German 'Solfège' test: #{result}"
-
-# Second test - Italian translation
-result = system('bundle exec ruby -e "require \'head_music\'; puts HeadMusic::Rudiment::Solmization.get(\'solfeggio\')&.name || \'nil\'"')
-puts "Italian 'solfeggio' test: #{result}"
-
-# Third test - Russian translation
-result = system('bundle exec ruby -e "require \'head_music\'; puts HeadMusic::Rudiment::Solmization.get(\'сольфеджио\')&.name || \'nil\'"')
-puts "Russian 'сольфеджио' test: #{result}"