Types

Primitive Types

The most fundamental types in Meantonal are Pitch and Interval, both of which represent 2d vectors.

Pitch

A Pitch is a struct with two members, w and h.

typedef struct {
    int w; // whole steps
    int h; // half steps
} Pitch;

• w holds the number of whole steps from $\sf{C}_{-1}$.
• h holds the number of half steps from $\sf{C}_{-1}$.

Interval

An Interval is a struct with two members, w and h. Strictly speaking, it’s just an alias of Pitch.

typedef Pitch Interval;

• w holds the number of whole steps from the unison.
• h holds the number of half steps from the unison.

Since the Pitch and Interval type are identical, they can be cast between each other. They are distinct because they generally represent different things. An Interval describes the distance between two Pitch vectors.

Note

Check the Pitches and Intervals pages in the Learn category for an explanation of what these representations mean mathematically, and how they’re constructed.

Tonal types

These types encode the information needed to represent a governing “key” or “mode”, and perform diatonic operations and queries within that context.

enum Mode

Used when defining a TonalContext. Numbered in descending fifths, starting with Lydian as 0.

enum Mode {
    LYDIAN,
    IONIAN,
    MIXOLYDIAN,
    DORIAN,
    AEOLIAN,
    PHRYGIAN,
    LOCRIAN,

    MAJOR = IONIAN,
    MINOR = AEOLIAN
};

TonalContext

A TonalContext is a struct holding data about the governing “key” or “mode”.

typedef struct {
    struct {
        int letter;
        int accidental;
    } tonic;
    enum Mode mode;
    int chroma_offset; // offset used by internal functions to reconcile notes.
} TonalContext;

enum Degree

This enum allows scale degrees (0-indexed so TONIC is 0) to be specified by their functional names. Used by degree_number and degree_chroma.

enum Degree {
    TONIC,
    SUPERTONIC,
    MEDIANT,
    SUBDOMINANT,
    DOMINANT,
    SUBMEDIANT,
    SUBTONIC
};

enum Alteration

This enum communicates the alteration of scale degrees within a key, used with degree_alteration.

enum Alteration {
    FOREIGN_DEG_FLAT = -2,
    LOWERED_DEG,
    DIATONIC_DEG,
    RAISED_DEG,
    FOREIGN_DEG_SHARP
};

FOREIGN_DEG_FLAT and FOREIGN_DEG_SHARP indicate notes that do not lie within the window of 17 perfect fifths Meantonal uses to define a TonalContext (that is, the note could not resolve by diatonic semitone to a natural degree within the key or mode).

Set Types

PitchClassSet

The PitchClassSet is an abstract data type used by functions beginning with pc_set_ to store, query and manipulate arbitrary sets of pitch classes. Classes are stored in terms of “chroma”, the signed distance of a note from C in fifths.

typedef struct tnode *PitchClassSet;

Caution

You are responsible for calling pc_set_destroy to free up any memory allocated to a PitchClassSet when you are finished with it.

Map Types

These types include mapping matrices for linear mapping operations and a special vector type to store the result of applying 2-dimensional maps.

Map1d

The Map1d type represents a $1\times2$ matrix. Its members are labelled m0 and m1 to reinforce this.

typedef struct {
    double m0, m1;
} Map1d;

Multiplying a Map1d matrix with a MapVec via map_to_1d produces a single integer as the result.

Multiplying a $1\times2$ matrix with a 2d vector is equivalent to taking the dot product between two 2d vectors, so they can also be thought of as 2d vectors if you prefer.

Map2d

The Map2d type represents a $2\times2$ matrix. Its members are labelled row-first, then column.

typedef struct {
    double m00, m01;
    double m10, m11;
} Map2d;

Multiplying a Map2d matrix with a MapVec via map_to_2d produces another MapVec.

MapVec

The MapVec type exists to store the vectors used with a Map1d by map_to_1d and Map2d by map_to_2d. Unlike Pitch and Interval, MapVec’s fields are doubles, not integers.

typedef struct {
    double x, y;
} MapVec;

TuningMap

The TuningMap type holds the data needed for functions like to_hz and to_cents to operate on Pitch and Interval vectors. To that end, it holds a reference Pitch and the frequency it will be tuned to (e.g. A4 = 440Hz for concert pitch), along with a Map1D specifying the width of the fifth in cents, and the octave (the octave is always set as 1200 cents).

typedef struct {
    Pitch ref_pitch;
    double ref_freq;
    Map1D centmap;
} TuningMap;

EDOMap

The EDOMap type represents a $1\times2$ matrix specifically used to map Pitch vectors onto well-ordered integer representations witnin a given EDO tuning system. For 12TET, this mapping is exactly equivalent to the standard MIDI representation, and for other EDO tunings it provides an analogous well-ordered numbering.

typedef struct {
    int m0, m1;
} EDOMap;

Created by create_edo_map. Used with pitch_to_number and pitches_compare.

MirrorAxis

The MirrorAxis type is to do with a different kind of mapping operation: pitch inversion about a fixed axis. Like Interval and MapVec, it is an alias of the Pitch struct type.

typedef Pitch MirrorAxis;

Created by axis_create or axis_from_spn. Used with pitch_invert.

Alternative Representations

The following types store alternative representations of pitch data. They correspond more closely with natural language, and can therefore potentially be useful as:

• An intermediate type on the way to pretty printing information about a group of musical objects to the end user.
• An intermediate type on the way to rendering standard notation.
• An intermediate parsing target from plaintext before converting into Pitch or Interval vectors.

StandardPitch

The StandardPitch type stores pitches in effectively the same fashion as Scientific Pitch Notation: as a triple of letter, accidental, and octave.

typedef struct {
    int letter;
    int accidental;
    int octave;
} StandardPitch;

Created with pitch_to_standard from a regular Pitch. More rarely parsed into a Pitch using pitch_from_standard.