Tonality

This page details all the functions that create TonalContext objects, query Pitch vectors against them, or manipulate Pitch vectors diatonically with respect to a governing key or mode.

Creating a TonalContext

In order to define a TonalContext, you need a way to specify the tonic, along with the mode.

context_from_str

int context_from_str(char *s, enum Mode mode, TonalContext *out);

This function allows you to initialise a TonalContext from a note name as a string, and a Mode enum value. The created context is returned via an out-param (you must pass in a pointer to a TonalContext). Returns 1 if there is a parsing error.

Safe usage if the string is being passed in dynamically:

TonalContext key;
if (int context_from_str(str, &key)) {
    // handle parsing error
}

context_from_chroma

TonalContext context_from_chroma(int chroma, enum Mode mode);

This function allows you to initialise a TonalContext from a chroma number (signed distance from C measured in 5ths), and a Mode enum value.

context_from_pitch

TonalContext context_from_pitch(Pitch p, enum Mode mode);

This function allows you to initialise a TonalContext from a Pitch vector and a Mode enum value.

Common Queries

The essential thing a TonalContext allows you to query is the scale degree represented by a Pitch, and its alteration with respect to the key signature.

degree_number

int degree_number(Pitch p, TonalContext k);

Reconciles a Pitch against a TonalContext and returns the scale degree it represents there. Result is 0-indexed, so the tonic is 0 rather than 1.

degree_alteration

enum Alteration degree_alteration(Pitch p, TonalContext k);

Reconciles a Pitch against a TonalContext and returns its alteration.

Compare return values against the enum Alteration.

Caution

Remember to check for both FOREIGN_DEG_SHARP and FOREIGN_DEG_FLAT returns from this function: a Pitch can lie outside the governing key/mode in both directions.

degree_chroma

static inline int degree_chroma(enum Degree degree, TonalContext key);

Produces the chroma (signed distance from C measured in 5ths) of the diatonic version of the specified degree in the passed-in TonalContext.

Transformations

snap_diatonic

Pitch snap_diatonic(Pitch p, TonalContext key);

Adjusts a Pitch to its diatonic version in the passed in TonalContext.

transpose_diatonic

Pitch transpose_diatonic(Pitch p, int interval, TonalContext key);

Transposes a Pitch by a generic interval. The resulting Pitch will always be diatonic in the passed in TonalContext.