music_theory Namespace Reference

A dependency-free, header-only collection of useful functions for music theory. More...

Classes
struct	Pitch
	A spelled pitch, expressed relative to C4. More...
class	Transposer
	Provides dependency-free transposition utilities that work with any scale that has 7 diatonic steps and an equal number of divisions of the octave (EDO). The most common Western scales use 12 divisions of the octave, .i.e., 12-EDO. More...

Enumerations
enum class	NoteName : int {   C = 0 , D = 1 , E = 2 , F = 3 ,   G = 4 , A = 5 , B = 6 }
	The available note names in array order.
enum class	DiatonicMode : int {   Ionian = 0 , Dorian = 1 , Phrygian = 2 , Lydian = 3 ,   Mixolydian = 4 , Aeolian = 5 , Locrian = 6 }
	Represents the seven standard diatonic musical modes. More...
enum class	ClefType {   Unknown , G , C , F ,   Percussion1 , Percussion2 , Tab , TabSerif }
	Represents the possible types of clef, irrespective of octave transposition. More...

Functions
constexpr int	calcDisplacement (const Pitch &pitch)
	Calculates the displacement value for a spelled pitch.
template<typename T >
constexpr T	sign (T n)
	Calculates the sign of an integer.
template<typename T >
constexpr T	signedModulus (T n, T d)
	Calculates the modulus of positive and negative numbers in a predictable manner.
template<typename T >
constexpr T	positiveModulus (T n, T d, T *q=nullptr)
	Calculates a positive modulus in the range [0, d-1], even for negative dividends.
constexpr int	calcPitchClass (NoteName noteName, int alteration=0, int numberOfEdoDivisions=STANDARD_12EDO_STEPS, const std::array< int, STANDARD_DIATONIC_STEPS > &keyMap=MAJOR_KEYMAP)
	Calculates the pitch class of a spelled note name.
constexpr int	calcPitchClass (const Pitch &pitch, int numberOfEdoDivisions=STANDARD_12EDO_STEPS, const std::array< int, STANDARD_DIATONIC_STEPS > &keyMap=MAJOR_KEYMAP)
	Calculates the pitch class of a spelled pitch, ignoring its octave.
constexpr int	calc12EdoHalfstepsInInterval (int interval, int chromaticAlteration)
	Calculates the number of 12-EDO chromatic halfsteps in the specified interval.
constexpr int	calcAlterationFrom12EdoHalfsteps (int interval, int halfsteps)
	Calculates the alteration in chromatic halfsteps for the specified interval/halfsteps combination.
constexpr int	calcAlterationFromKeySigChange (int interval, int keySigChange)
	Determines the chromatic alteration needed for a diatonic interval to produce a desired key signature change.
constexpr int	calcKeySigChangeFromInterval (int interval, int chromaticAlteration)
	Calculates the resulting key signature change (sharps/flats) produced by a diatonic interval and chromatic alteration.
constexpr bool	calcTranspositionIsOctave (int displacement, int alteration)
	Determines if the transposition values result in trasposing by one or more octaves.

Variables
constexpr int	STANDARD_NUMBER_OF_STAFFLINES = 5
	The standard number of lines on a staff.
constexpr int	STANDARD_DIATONIC_STEPS = 7
	currently this is the only supported number of diatonic steps.
constexpr int	STANDARD_12EDO_STEPS = 12
	this can be overriden when constructing a Transposer instance.
constexpr std::array< int, STANDARD_DIATONIC_STEPS >	MAJOR_KEYMAP = { 0, 2, 4, 5, 7, 9, 11 }
	keymap for 12-EDO major keys
constexpr std::array< int, STANDARD_DIATONIC_STEPS >	MINOR_KEYMAP = { 0, 2, 3, 5, 7, 8, 10 }
	keymap for 12-EDO minor keys
constexpr std::array< std::array< int, 2 >, STANDARD_DIATONIC_STEPS >	DIATONIC_INTERVAL_ADJUSTMENTS
	Array of chromatic intervals. Each member array contains.

Detailed Description

A dependency-free, header-only collection of useful functions for music theory.

Enumeration Type Documentation

ClefType

enum class music_theory::ClefType

strong

Represents the possible types of clef, irrespective of octave transposition.

Enumerator
Unknown	Unknown clef type (default value with {} initializer)
G	Treble clef.
C	C clef.
F	Bass clef.
Percussion1	2 thick vertical lines centered on middle staff line (corresponds to SMuFL glyph unpitchedPercussionClef1)
Percussion2	Narrow rectangle centered on middle staff line (corresponds to SMuFL glyph unpitchedPercussionClef2)
Tab	Tablature clef (TAB) with non-serif font.
TabSerif	Tablature clef (TAB) with serif font.

DiatonicMode

enum class music_theory::DiatonicMode : int

strong

Represents the seven standard diatonic musical modes.

Values correspond to their roots with no sharps or flats C (0) through B (6).

Enumerator
Ionian	major
Dorian	minor with raised 6
Phrygian	minor with flat 2
Lydian	major with raised 4
Mixolydian	major with flat 7
Aeolian	natural minor
Locrian	diminished with flat 2 and 5

Function Documentation

calc12EdoHalfstepsInInterval()

constexpr int music_theory::calc12EdoHalfstepsInInterval ( int  interval, int  chromaticAlteration  )

constexpr

Calculates the number of 12-EDO chromatic halfsteps in the specified interval.

Parameters

interval	The diatonic displacement (negative for downward intervals).
chromaticAlteration	The chromatic halfstep alteration that defines the chromatic interval.

Returns

The number of 12-EDO divisions (chromatic halfsteps) in the interval (negative means down)

calcAlterationFrom12EdoHalfsteps()

constexpr int music_theory::calcAlterationFrom12EdoHalfsteps ( int  interval, int  halfsteps  )

constexpr

Calculates the alteration in chromatic halfsteps for the specified interval/halfsteps combination.

Parameters

interval	The diatonic displacement (negative for downward transposition).
halfsteps	The number of 12-EDO chromatic halfsteps in the interval (negative means down).

Returns

The alteration value that, with interval, defines the chromatic interval. This return value can be used to initialize a Transposer.

calcAlterationFromKeySigChange()

constexpr int music_theory::calcAlterationFromKeySigChange ( int  interval, int  keySigChange  )

constexpr

Determines the chromatic alteration needed for a diatonic interval to produce a desired key signature change.

Parameters

interval	The diatonic interval (e.g. +3 for a perfect fourth up).
keySigChange	The desired change in key signature (positive for sharps added or flats removed, negative for flats added or sharps removed).

Returns

The chromatic alteration in halfsteps required to produce that key signature change with the given diatonic interval.

calcDisplacement()

constexpr int music_theory::calcDisplacement ( const Pitch &  pitch )

constexpr

Calculates the displacement value for a spelled pitch.

Parameters

pitch

The pitch to convert.

Returns

A displacement value that can be used to create a Transposer instance.

calcKeySigChangeFromInterval()

constexpr int music_theory::calcKeySigChangeFromInterval ( int  interval, int  chromaticAlteration  )

constexpr

Calculates the resulting key signature change (sharps/flats) produced by a diatonic interval and chromatic alteration.

Parameters

interval	The diatonic displacement (e.g. +3 for a perfect fourth up).
chromaticAlteration	The chromatic alteration in halfsteps that defines the chromatic interval.

Returns

The change in key signature (positive for sharps added or flats removed, negative for flats added or sharps removed).

calcPitchClass() [1/2]

constexpr int music_theory::calcPitchClass ( const Pitch &  pitch, int  numberOfEdoDivisions = STANDARD_12EDO_STEPS, const std::array< int, STANDARD_DIATONIC_STEPS > &  keyMap = MAJOR_KEYMAP  )

constexpr

Calculates the pitch class of a spelled pitch, ignoring its octave.

Parameters

pitch	The pitch to convert. Its alteration is relative to the natural note name.
numberOfEdoDivisions	The number of divisions in the EDO. (E.g., 31-EDO would pass 31.)
keyMap	A 7-element map giving the EDO division of each natural note name, C first.

Returns

The pitch class, in the range [0, numberOfEdoDivisions - 1].

calcPitchClass() [2/2]

constexpr int music_theory::calcPitchClass ( NoteName  noteName, int  alteration = 0, int  numberOfEdoDivisions = STANDARD_12EDO_STEPS, const std::array< int, STANDARD_DIATONIC_STEPS > &  keyMap = MAJOR_KEYMAP  )

constexpr

Calculates the pitch class of a spelled note name.

The pitch class is the note's chromatic position within one octave, counting from the natural note name and then applying the alteration. Enharmonics share a pitch class, so C♯ and D♭ both return 1 in 12-EDO.

keyMap gives the EDO division of each natural note name in C-first order, which is the same thing as the major scale rooted at C. It cannot be derived from numberOfEdoDivisions alone: 31-EDO places the naturals at { 0, 5, 10, 13, 18, 23, 28 }, so both values are needed, exactly as Transposer takes them. Note that a key signature's own key map is relative to its tonal center, so it suits Transposer rather than this function.

Parameters

noteName	The diatonic note name.
alteration	The alteration relative to the natural note name, in EDO divisions.
numberOfEdoDivisions	The number of divisions in the EDO. (E.g., 31-EDO would pass 31.)
keyMap	A 7-element map giving the EDO division of each natural note name, C first.

Returns

The pitch class, in the range [0, numberOfEdoDivisions - 1].

calcTranspositionIsOctave()

constexpr bool music_theory::calcTranspositionIsOctave ( int  displacement, int  alteration  )

constexpr

Determines if the transposition values result in trasposing by one or more octaves.

Parameters

displacement	The diatonic displacement.
alteration	The chromatic alteration.

positiveModulus()

template<typename T >

constexpr T music_theory::positiveModulus ( T  n, T  d, T *  q = nullptr  )

constexpr

Calculates a positive modulus in the range [0, d-1], even for negative dividends.

Template Parameters

T	An integer type.

Parameters

n	The dividend (may be negative).
d	The modulus base (must be positive).
q	Optional pointer to receive the quotient such that n = d * q + result.

Returns

The result of n modulo d in the range [0, d-1].

sign()

template<typename T >

constexpr T music_theory::sign ( T  n )

constexpr

Calculates the sign of an integer.

Parameters

n	The integer to process.

Returns

-1 for negative; 1 for non-negative.

signedModulus()

template<typename T >

constexpr T music_theory::signedModulus ( T  n, T  d  )

constexpr

Calculates the modulus of positive and negative numbers in a predictable manner.

Template Parameters

T	an integer type

Parameters

n	The number (positive or negative) for which to calculate the modulus
d	The base of the modulus. This must be a positive number.

Returns

For non-negative, the result is the same as %. For negative numbers, the result is -1 * (abs(n) % d).

Note

Since C++11 integer division is guaranteed to truncate toward zero, which makes % already carry the sign of n. Spelling this out with abs instead would defeat constant evaluation on any standard library that has not yet made std::abs constexpr, and is undefined for the most negative value of T.

Variable Documentation

DIATONIC_INTERVAL_ADJUSTMENTS

constexpr std::array<std::array<int, 2>, STANDARD_DIATONIC_STEPS> music_theory::DIATONIC_INTERVAL_ADJUSTMENTS

constexpr

Initial value:

= { {
    { 0,  0 },  
    { 2, -1 },  
    { 4, -2 },  
    {-1,  1 },  
    { 1,  0 },  
    { 3, -1 },  
    { 5, -2 }   
}}

Array of chromatic intervals. Each member array contains.

• the number of fifths to add, which is also the key signature adjustment for the interval
• the number of octaves to subtract