Harmony

A comprehensive music theory library for Elixir, ported from the popular tonal.js library. Harmony provides a complete set of tools for working with notes, intervals, chords, scales, and other music theory concepts.

Features

• Notes & Pitch Classes - Work with musical notes, MIDI numbers, frequencies, and enharmonic equivalents
• Intervals - Calculate and manipulate musical intervals with proper enharmonic spelling
• Chords - Chord recognition, generation, analysis, and compatible scale finding
• Scales - Scale generation, mode calculation, and chord compatibility
• Transposition - Transpose notes and musical structures by intervals
• Roman Numerals - Roman numeral analysis for functional harmony
• Circle of Fifths - Navigate the circle of fifths and key relationships

Installation

Add harmony to your list of dependencies in mix.exs:

def deps do
  [
    {:harmony, "~> 0.1.0"}
  ]
end

Quick Examples

Notes

# Get note information
note = Harmony.Note.get("C4")
note.midi    # => 60
note.freq    # => 261.63
note.pc      # => "C"

# Create from MIDI or frequency
Harmony.Note.from_midi(60)     # => %Note{name: "C4", ...}
Harmony.Note.from_freq(440.0)  # => %Note{name: "A4", ...}

# Simplify notes
Harmony.Note.simplify("B#4")   # => "C5"
Harmony.Note.simplify("C###")  # => "D#"

Intervals

# Get intervals
Harmony.Interval.get("5P")      # Perfect fifth
Harmony.Interval.get("5P").semitones  # => 7

# Calculate distance between notes
Harmony.Interval.distance("C", "G")   # => "5P"
Harmony.Interval.distance("C4", "E4") # => "3M"

# Operations
Harmony.Interval.invert("3M")   # => "6m"
Harmony.Interval.add("3M", "3m")  # => "5P"

Transposition

# Transpose notes
Harmony.Transpose.transpose("C4", "5P")   # => "G4"
Harmony.Transpose.transpose("D", "3M")    # => "F#"

# Create reusable transposers
up_fifth = Harmony.Transpose.transpose_by("5P")
["C", "D", "E"] |> Enum.map(up_fifth)
# => ["G", "A", "B"]

Chords

# Get chord information
chord = Harmony.Chord.get("Cmaj7")
chord.notes      # => ["C", "E", "G", "B"]
chord.intervals  # => ["1P", "3M", "5P", "7M"]

# Find compatible scales
Harmony.Chord.chord_scales("Cmaj7")
# => ["major", "lydian", "major pentatonic", ...]

# Transpose chords
Harmony.Chord.transpose("Dm7", "5P")  # => "Am7"

Scales

# Get scale information
scale = Harmony.Scale.get("C major")
scale.notes      # => ["C", "D", "E", "F", "G", "A", "B"]
scale.intervals  # => ["1P", "2M", "3M", "4P", "5P", "6M", "7M"]

# Get all modes
Harmony.Scale.modes("C major")
# => [["C", "major"], ["D", "dorian"], ["E", "phrygian"], ...]

# Find compatible chords
Harmony.Scale.chords("D dorian")
# => ["m", "m7", "m9", "m11", "sus4", "7sus4", ...]

# Generate scale ranges
range_fn = Harmony.Scale.range_of("C major")
range_fn.("C4", "C5")
# => ["C4", "D4", "E4", "F4", "G4", "A4", "B4", "C5"]

Roman Numerals

# Get Roman numeral information
rn = Harmony.RomanNumeral.get("V")
rn.interval  # => "5P"
rn.major     # => true

# Build progressions
["I", "IV", "V", "I"]
|> Enum.map(fn numeral ->
  Harmony.RomanNumeral.get(numeral).interval
  |> (&Harmony.Transpose.transpose("C", &1)).()
end)
# => ["C", "F", "G", "C"]

Documentation

Comprehensive documentation is available in the /docs folder:

• Getting Started - Installation and quick start guide
• Notes - Working with musical notes
• Intervals - Musical intervals and distances
• Transposition - Transposing notes and structures
• Chords - Chord recognition and analysis
• Scales - Scale generation and modes

Module Overview

Design Philosophy

Harmony is built with Elixir's functional programming paradigm in mind:

• Immutable Data - All operations return new values rather than modifying existing ones
• Pattern Matching - Extensive use of Elixir's pattern matching for clean, readable code
• Compile-Time Generation - Notes and intervals are generated at compile time using macros for optimal performance
• Composability - Functions support partial application and are designed to work well with Enum and Stream
• Type Safety - Comprehensive typespecs throughout the library

Performance

The library uses compile-time macros to generate all possible notes and intervals, resulting in:

• Zero runtime overhead for note/interval lookups
• Constant-time access to note properties
• Efficient pattern matching for all operations

Key Concepts

Empty Values

When invalid input is provided, functions return "empty" structs rather than raising errors:

Harmony.Note.get("invalid")  # => %Note{empty: true, ...}
Harmony.Chord.get("xyz")     # => %Chord{empty: true, ...}

Pitch Classes vs Notes with Octaves

Functions work with both pitch classes (no octave) and specific notes (with octave):

# Pitch classes
Harmony.Note.get("C").pc      # => "C"
Harmony.Chord.get("C").notes  # => ["C", "E", "G"]

# Notes with octaves
Harmony.Note.get("C4").oct      # => 4
Harmony.Chord.get("C4").notes   # => ["C4", "E4", "G4"]

Enharmonic Spelling

The library maintains proper enharmonic spelling based on context:

Harmony.Transpose.transpose("F#", "5P")  # => "C#" (not Db)
Harmony.Transpose.transpose("Gb", "5P")  # => "Db" (not C#)

Comparison to Tonal.js

This library is an Elixir port of the popular JavaScript library tonal.js. While maintaining the core algorithms and concepts, it adapts them to Elixir's strengths:

Development

# Get dependencies
mix deps.get

# Run tests
mix test

# Run dialyzer for type checking
mix dialyzer

# Generate documentation
mix docs

Examples & Use Cases

Chord Progression Transposition

progression = ["C", "Am", "F", "G"]
transpose_to_d = Harmony.Transpose.transpose_by("2M")

progression |> Enum.map(transpose_to_d)
# => ["D", "Bm", "G", "A"]

Finding Scale Degrees

scale = Harmony.Scale.get("C major")
scale.notes
|> Enum.with_index(1)
|> Enum.each(fn {note, degree} ->
  IO.puts("Degree #{degree}: #{note}")
end)
# Degree 1: C
# Degree 2: D
# ...

Circle of Fifths

Enum.map(0..11, fn n ->
  Harmony.Transpose.transpose_fifths("C", n)
end)
# => ["C", "G", "D", "A", "E", "B", "F#", "Db", "Ab", "Eb", "Bb", "F"]

Jazz Chord Analysis

# Find all scales that work over a ii-V-I progression
chords = ["Dm7", "G7", "Cmaj7"]

chords
|> Enum.map(&Harmony.Chord.chord_scales/1)
|> Enum.reduce(&MapSet.intersection(MapSet.new(&1), MapSet.new(&2)))
# => Common scales that work over all three chords

Contributing

Contributions are welcome! This library is being actively maintained and improved. Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

License

This project is licensed under the MIT License.

Credits

• Original tonal.js library by @danigb
• Elixir port and adaptation by Ryan Messner

Acknowledgments

Special thanks to the tonal.js community for creating such a comprehensive music theory library that inspired this Elixir port.