HeadMusic

The head_music Ruby gem provides a toolkit for working with Western music theory. Model and manipulate the fundamental elements of music including pitches, scales, key signatures, intervals, and chords.

• Western Music Theory Fundamentals: Work with pitches, scales, intervals, chords, and key signatures
• Musical Analysis: Analyze harmonic progressions, voice leading, and counterpoint
• Style Analysis: Rules for species counterpoint and voice leading
• Internationalization: Support for multiple languages (English, French, German, Italian, Russian, Spanish)
• Instrument Modeling: Extensive database of musical instruments with ranges and properties

Add this line to your application's Gemfile:

gem 'head_music'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install head_music

require 'head_music'

# Work with pitches and intervals
pitch = HeadMusic::Rudiment::Pitch.get('C4')
higher_pitch = HeadMusic::Rudiment::Pitch.get('E4')
interval = HeadMusic::Analysis::DiatonicInterval.new(pitch, higher_pitch)
puts interval.name  # => "major third"

# Create scales
scale = HeadMusic::Rudiment::Scale.get('C', :major)
puts scale.pitches.map(&:to_s)  # => ["C4", "D4", "E4", "F4", "G4", "A4", "B4"]

# Analyze chords
pitches = %w[C4 E4 G4].map { |p| HeadMusic::Rudiment::Pitch.get(p) }
chord = HeadMusic::Analysis::PitchSet.new(pitches)
puts chord.major_triad?  # => true

• API Documentation: rubydoc.info/gems/head_music
• Contributing Guide: CONTRIBUTING.md
• Changelog: CHANGELOG.md

• Ruby 3.3.0 or higher
• ActiveSupport 7.0+

After checking out the repo, run bin/setup to install dependencies.

# Run all tests
bundle exec rspec

# Run tests with coverage
bundle exec rake

# Run quality checks (tests + linting + security)
bundle exec rake quality

# Run linting
bundle exec rubocop

# Run security audit
bundle exec rake bundle:audit:check

# Generate documentation
bundle exec rake doc

• rake spec - Run tests
• rake quality - Run tests, linting, and security audit
• rake doc - Generate YARD documentation
• rake doc_stats - Show documentation coverage statistics
• rake coverage - Open coverage report in browser

We welcome contributions! Please see our Contributing Guide for details.

lib/head_music/
├── analysis/          # Musical analysis tools (intervals, chords, etc.)
├── content/           # Musical content (compositions, voices, notes)
├── instruments/       # Instrument definitions and properties
├── rudiment/          # Basic music theory elements (pitches, scales, etc.)
└── style/             # Style analysis and composition rules

This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to our Code of Conduct.

The gem is available as open source under the terms of the MIT License.

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: For security issues, please email robert.head@gmail.com