music_theory::Transposer Class Reference

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...

#include <music_theory.hpp>

Public Member Functions
	Transposer (int displacement, int alteration, bool isMinor=false, int numberOfEdoDivisions=STANDARD_12EDO_STEPS, const std::optional< std::vector< int > > &keyMap=std::nullopt)
	Constructor function.
int	displacement () const
	Return the current displacement value.
int	alteration () const
	Return the current chromatic alteration value.
void	diatonicTranspose (int interval)
	Transposes the displacement by the specified interval.
void	enharmonicTranspose (int direction)
	Transposes enharmonically relative to the current values.
void	chromaticTranspose (int interval, int chromaticAlteration)
	Chromatically transposes by a specified chromatic interval.
void	simplifySpelling ()
	Simplifies the spelling by reducing its alteration while preserving pitch.
void	stepwiseTranspose (int numberOfEdoDivisions)
	Transposes by the given number of EDO divisions and simplifies the spelling.
bool	isEnharmonicEquivalent (int displacement, int alteration) const
	Determines if the given displacement and alteration refer to the same pitch as the current state.

Detailed Description

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.

The way to use this class is to intialize it in the constructor, run one or more transposition functions, then extract the modified displacement and alteration values.

Constructor & Destructor Documentation

Transposer()

music_theory::Transposer::Transposer ( int  displacement, int  alteration, bool  isMinor = false, int  numberOfEdoDivisions = STANDARD_12EDO_STEPS, const std::optional< std::vector< int > > &  keyMap = std::nullopt  )

inline

Constructor function.

Parameters

displacement	the scale step displacement value. 0 signifies the tonic in the C4 (middle-C) octave. With the default values isMinor = false and keyMap = std::nullopt, 0 is C4.
alteration	the number of EDO divisions by which the pitch is altered. This corresponds to the accidental on a note. 0 signifies that the note has no accidental in the key signature.
isMinor	true if you wish to use the default keymap for minor mode. (Ignored if keyMap is provided.)
numberOfEdoDivisions	the number of divisions in the EDO. (E.g., 31-EDO would pass 31.)
keyMap	a 7-element map specifying the starting EDO division of each diatonic step. 12-EDO Major (the default) is { 0, 2, 4, 5, 7, 9, 11 }.

Member Function Documentation

chromaticTranspose()

void music_theory::Transposer::chromaticTranspose ( int  interval, int  chromaticAlteration  )

inline

Chromatically transposes by a specified chromatic interval.

This function transposes the note chromatically in any EDO. The chromatic interval is defined by a diatonic displacement (e.g., 0 = unison, 1 = second, 2 = third, etc.) plus a chromatic alteration.

Note

Chromatic alterations have the same values in any EDO. That is, the inputs to this functions are the same regardless of EDO number. This function calculates the correct number of EDO divisions in a chromatic half-step using the key map provided when the Transposer instance was created.

A chromatic alteration of 0 corresponds to major or perfect intervals. For example:

• {1, 0} is a major second up
• {2, -1} is a minor third up
• {3, 0} is a perfect fourth up
• {5, 1} is an augmented sixth up

Reversing the signs of both interval and alteration allows for downward transposition.

Parameters

interval	The diatonic displacement (negative for downward transposition).
chromaticAlteration	The chromatic half-step alteration that defines the chromatic interval.

diatonicTranspose()

void music_theory::Transposer::diatonicTranspose ( int  interval )

inline

Transposes the displacement by the specified interval.

Parameters

interval

0 = unison, 1 = second, 2 = third, etc. The interval may be any size, and it can be negative for downward transposition.

enharmonicTranspose()

void music_theory::Transposer::enharmonicTranspose ( int  direction )

inline

Transposes enharmonically relative to the current values.

Parameters

direction

negative or non-negative (usually -1 or 1)

isEnharmonicEquivalent()

bool music_theory::Transposer::isEnharmonicEquivalent ( int  displacement, int  alteration  ) const

inline

Determines if the given displacement and alteration refer to the same pitch as the current state.

This compares the total EDO division position derived from the current displacement and alteration with that of the input values. It accounts for microtonal tuning via the custom key map and EDO size.

Parameters

displacement	The scale step displacement to compare.
alteration	The alteration (accidental specified in EDO divisions) to compare.

Returns

true if the given values are enharmonically equivalent to the current values.

simplifySpelling()

void music_theory::Transposer::simplifySpelling ( )

inline

Simplifies the spelling by reducing its alteration while preserving pitch.

This is typically used after a chromatic or enharmonic transposition to improve a note’s readability. It performs enharmonic transpositions in the appropriate direction until the absolute alteration is minimized.

stepwiseTranspose()

void music_theory::Transposer::stepwiseTranspose ( int  numberOfEdoDivisions )

inline

Transposes by the given number of EDO divisions and simplifies the spelling.

In standard key signatures, each division corresponds to a half-step.

After transposition, the note's spelling is simplified to reduce the alteration while preserving pitch.

Parameters

numberOfEdoDivisions

The number of EDO divisions to transpose (positive for up, negative for down).