HeadMusic

CI Security Gem Version Documentation

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.

Features

  • 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

Installation

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

Quick Start

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

Documentation

Requirements

  • Ruby 3.3.0 or higher
  • ActiveSupport 7.0+

Development

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

Running Tests

# Run all tests
bundle exec rspec

# Run tests with coverage
bundle exec rake

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

Code Quality

# Run linting
bundle exec rubocop

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

# Generate documentation
bundle exec rake doc

Available Rake Tasks

  • 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

Contributing

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

Project Structure

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

Code of Conduct

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

License

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

Support