music_theory.hpp

/*
 * Copyright (C) 2025, Robert Patterson
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
 
 // Do not use `#pragma once` here, because the file may be included in multiple projects
#ifndef MUSIC_THEORY_HPP
#define MUSIC_THEORY_HPP
 
#include <array>
#include <vector>
#include <cmath>
#include <algorithm>
#include <optional>
#include <stdexcept>
#include <string>
 
/*
This header-only library has no dependencies and can be shared into any other library merely
by including it.
*/
 
namespace music_theory {
 
constexpr int STANDARD_NUMBER_OF_STAFFLINES = 5; 
constexpr int STANDARD_DIATONIC_STEPS = 7; 
constexpr int STANDARD_12EDO_STEPS = 12;   
 
constexpr std::array<int, STANDARD_DIATONIC_STEPS> MAJOR_KEYMAP = { 0, 2, 4, 5, 7, 9, 11 };     
constexpr std::array<int, STANDARD_DIATONIC_STEPS> MINOR_KEYMAP = { 0, 2, 3, 5, 7, 8, 10 };     
 
constexpr std::array<std::array<int, 2>, STANDARD_DIATONIC_STEPS> DIATONIC_INTERVAL_ADJUSTMENTS = { {
    { 0,  0 },  // unison
    { 2, -1 },  // second
    { 4, -2 },  // third
    {-1,  1 },  // fourth
    { 1,  0 },  // fifth
    { 3, -1 },  // sixth
    { 5, -2 }   // seventh
}};
 
enum class NoteName : int
{
    C = 0,
    D = 1,
    E = 2,
    F = 3,
    G = 4,
    A = 5,
    B = 6
};
 
struct Pitch
{
    constexpr Pitch() = default;
 
    constexpr Pitch(NoteName pitchName, int pitchOctave, int pitchAlteration = 0)
        : noteName(pitchName), octave(pitchOctave), alteration(pitchAlteration)
    {
    }
 
    NoteName noteName{}; 
    int octave{};        
    int alteration{};    
};
 
static constexpr std::array<music_theory::NoteName, music_theory::STANDARD_DIATONIC_STEPS> noteNames = {
    NoteName::C, NoteName::D, NoteName::E, NoteName::F, NoteName::G, NoteName::A, NoteName::B
};
 
enum class DiatonicMode : int
{
    Ionian = 0,         
    Dorian = 1,         
    Phrygian = 2,       
    Lydian = 3,         
    Mixolydian = 4,     
    Aeolian = 5,        
    Locrian = 6         
};
 
enum class ClefType
{
    Unknown,            
    G,                  
    C,                  
    F,                  
    Percussion1,        
    Percussion2,        
    Tab,                
    TabSerif            
};
 
constexpr int calcDisplacement(const Pitch& pitch)
{
    int pitchClassVal = int(pitch.noteName) % STANDARD_DIATONIC_STEPS;
    const int relativeOctave = pitch.octave - 4;
 
    return pitchClassVal + (STANDARD_DIATONIC_STEPS * relativeOctave);
}
 
template <typename T>
constexpr T sign(T n)
{
    static_assert(std::is_arithmetic_v<T>, "sign requires a numeric type");
    return n < T(0) ? T(-1) : T(1);
}
 
template <typename T>
constexpr T signedModulus(T n, T d)
{
    static_assert(std::is_integral_v<T>, "signedModulus requires an integer type");
    return n % d;
}
 
template <typename T>
constexpr T positiveModulus(T n, T d, T* q = nullptr)
{
    static_assert(std::is_integral_v<T>, "positiveModulus requires an integer type");
    if (q) *q = n / d;
    T result = signedModulus(n, d);
    if (result < 0) {
        result += d;
        if (q) --(*q);
    }
    return result;
}
 
constexpr int calcPitchClass(NoteName noteName, int alteration = 0,
    int numberOfEdoDivisions = STANDARD_12EDO_STEPS,
    const std::array<int, STANDARD_DIATONIC_STEPS>& keyMap = MAJOR_KEYMAP)
{
    const int natural = keyMap[positiveModulus(int(noteName), STANDARD_DIATONIC_STEPS)];
    return positiveModulus(natural + alteration, numberOfEdoDivisions);
}
 
constexpr int calcPitchClass(const Pitch& pitch,
    int numberOfEdoDivisions = STANDARD_12EDO_STEPS,
    const std::array<int, STANDARD_DIATONIC_STEPS>& keyMap = MAJOR_KEYMAP)
{
    return calcPitchClass(pitch.noteName, pitch.alteration, numberOfEdoDivisions, keyMap);
}
 
constexpr int calc12EdoHalfstepsInInterval(int interval, int chromaticAlteration)
{
    int octaves{};
    int diatonic = positiveModulus(interval, STANDARD_DIATONIC_STEPS, &octaves);
    return MAJOR_KEYMAP[diatonic] + (octaves * STANDARD_12EDO_STEPS) + chromaticAlteration;
}
 
constexpr int calcAlterationFrom12EdoHalfsteps(int interval, int halfsteps)
{
    int octaves{};
    int diatonic = positiveModulus(interval, STANDARD_DIATONIC_STEPS, &octaves);
    int expectedHalfsteps = MAJOR_KEYMAP[diatonic] + (octaves * STANDARD_12EDO_STEPS);
    return halfsteps - expectedHalfsteps;
}
 
constexpr int calcAlterationFromKeySigChange(int interval, int keySigChange)
{
    int diatonic = positiveModulus(interval, STANDARD_DIATONIC_STEPS);
    int expectedKeyChange = DIATONIC_INTERVAL_ADJUSTMENTS[diatonic][0];
    if (interval < 0) {
        if (std::abs(expectedKeyChange) > 1) { // imperfect intervals
            expectedKeyChange -= STANDARD_DIATONIC_STEPS;
        }
    }
    int alteration = (keySigChange - expectedKeyChange) / STANDARD_DIATONIC_STEPS;
    return alteration;
}
 
constexpr int calcKeySigChangeFromInterval(int interval, int chromaticAlteration)
{
    const int diatonic = positiveModulus(interval, STANDARD_DIATONIC_STEPS);
    int expectedKeyChange = DIATONIC_INTERVAL_ADJUSTMENTS[diatonic][0];
    if (interval < 0) {
        if (std::abs(expectedKeyChange) > 1) { // imperfect intervals
            expectedKeyChange -= STANDARD_DIATONIC_STEPS;
        }
    }
    return expectedKeyChange + (chromaticAlteration * STANDARD_DIATONIC_STEPS);
}
 
constexpr bool calcTranspositionIsOctave(int displacement, int alteration)
{
    return (displacement % STANDARD_DIATONIC_STEPS) == 0 && alteration == 0;
}
 
class Transposer
{
private:
    int m_displacement;
    int m_alteration;               // alteration from key signature
    int m_numberOfEdoDivisions;     // number of divisions in the EDO (default 12)
    std::vector<int> m_keyMap;      // step map for the EDO
 
public:
    explicit Transposer(const Pitch& pitch)
        : Transposer(calcDisplacement(pitch), pitch.alteration)
    {
    }
 
    Transposer(int displacement, int alteration,
        bool isMinor = false, int numberOfEdoDivisions = STANDARD_12EDO_STEPS,
        const std::optional <std::vector<int>>& keyMap = std::nullopt)
        : m_displacement(displacement), m_alteration(alteration), m_numberOfEdoDivisions(numberOfEdoDivisions)
    {
        if (keyMap) {
            if (keyMap.value().size() != STANDARD_DIATONIC_STEPS) {
                throw std::invalid_argument("The Transposer class only supports key map arrays of " + std::to_string(STANDARD_DIATONIC_STEPS) + " elements");
            }
            m_keyMap = keyMap.value();
        } else if (isMinor) {
            m_keyMap.assign(MINOR_KEYMAP.begin(), MINOR_KEYMAP.end());
        } else {
            m_keyMap.assign(MAJOR_KEYMAP.begin(), MAJOR_KEYMAP.end());
        }
    }
 
    int displacement() const { return m_displacement; }
 
    int alteration() const { return m_alteration; }
 
    void diatonicTranspose(int interval)
    {
        m_displacement += interval;
    }
 
    void enharmonicTranspose(int diatonicSteps)
    {
        const int stepSign = sign(diatonicSteps);
        for (int i = 0; i < std::abs(diatonicSteps); ++i) {
            const int keyStepEnharmonic = calcStepsBetweenScaleDegrees(m_displacement, m_displacement + stepSign);
            diatonicTranspose(stepSign);
            m_alteration -= stepSign * keyStepEnharmonic;
        }
    }
 
    void chromaticTranspose(int interval, int chromaticAlteration)
    {
        const int intervalNormalized = signedModulus(interval, STANDARD_DIATONIC_STEPS);
        const int stepsInAlteration = calcStepsInAlteration(interval, chromaticAlteration);
        const int stepsInInterval = calcStepsInNormalizedInterval(intervalNormalized);
        const int stepsInDiatonicInterval = calcStepsBetweenScaleDegrees(m_displacement, m_displacement + intervalNormalized);
 
        const int effectiveAlteration = stepsInAlteration + stepsInInterval - sign(interval) * stepsInDiatonicInterval;
 
        diatonicTranspose(interval);
        m_alteration += effectiveAlteration;
    }
 
    void simplifySpelling()
    {
        while (std::abs(m_alteration) > 0) {
            const int currSign = sign(m_alteration);
            const int currAbsDisp = std::abs(m_alteration);
            enharmonicTranspose(currSign);
            if (std::abs(m_alteration) >= currAbsDisp) {
                enharmonicTranspose(-currSign);
                return;
            }
            if (currSign != sign(m_alteration)) {
                break;
            }
        }
    }
 
    void stepwiseTranspose(int numberOfEdoDivisions)
    {
        m_alteration += numberOfEdoDivisions;
        simplifySpelling();
    }
 
    bool isEnharmonicEquivalent(int displacement, int alteration) const {
        return calcAbsoluteDivision(displacement, alteration) == calcAbsoluteDivision(m_displacement, m_alteration);
    }
 
private:
    int calcFifthSteps() const
    {
        // std::log(3.0 / 2.0) / std::log(2.0) is 0.5849625007211562.
        static constexpr double kFifthsMultiplier = 0.5849625007211562;
        return static_cast<int>(std::floor(m_numberOfEdoDivisions * kFifthsMultiplier) + 0.5);
    }
 
    int calcScaleDegree(int interval) const
    { return positiveModulus(interval, int(m_keyMap.size())); }
 
    int calcStepsBetweenScaleDegrees(int firstDisplacement, int secondDisplacement) const
    {
        const int firstScaleDegree = calcScaleDegree(firstDisplacement);
        const int secondScaleDegree = calcScaleDegree(secondDisplacement);
        int result = sign(secondDisplacement - firstDisplacement) * (m_keyMap[secondScaleDegree] - m_keyMap[firstScaleDegree]);
        if (result < 0) {
            result += m_numberOfEdoDivisions;
        }
        return result;
    }
 
    int calcStepsInAlteration(int interval, int alteration) const
    {
        const int fifthSteps = calcFifthSteps();
        const int plusFifths = sign(interval) * alteration * 7;     // number of fifths to add for a chromatic halfstep alteration (in any EDO)
        const int minusOctaves = sign(interval) * alteration * -4;  // number of octaves to subtract for a chromatic halfstep alteration (in any EDO)
        const int result = sign(interval) * ((plusFifths * fifthSteps) + (minusOctaves * m_numberOfEdoDivisions));
        return result;
    }
 
    int calcStepsInNormalizedInterval(int intervalNormalized) const
    {
        const int fifthSteps = calcFifthSteps();
        const int index = std::abs(intervalNormalized);
        const int plusFifths = DIATONIC_INTERVAL_ADJUSTMENTS[index][0];    // number of fifths
        const int minusOctaves = DIATONIC_INTERVAL_ADJUSTMENTS[index][1];  // number of octaves
 
        return sign(intervalNormalized) * ((plusFifths * fifthSteps) + (minusOctaves * m_numberOfEdoDivisions));
    }
 
    int calcAbsoluteDivision(int displacement, int alteration) const {
        const int scaleDegree = calcScaleDegree(displacement); // 0..6
        const int baseStep = m_keyMap[scaleDegree];
 
        const int octaveCount = (displacement < 0 && displacement % STANDARD_DIATONIC_STEPS != 0)
                              ? (displacement / STANDARD_DIATONIC_STEPS) - 1
                              : (displacement / STANDARD_DIATONIC_STEPS);
        const int octaveSteps = octaveCount * m_numberOfEdoDivisions;
        const int chromaticSteps = calcStepsInAlteration(/*interval=*/+1, alteration);
 
        return baseStep + chromaticSteps + octaveSteps;
    }
};
 
} // namespace music_theory
 
#endif // MUSIC_THEORY_HPP