harmonex v0.6.0 Harmonex.Interval View Source

Provides functions for working with intervals between pitches on the Western dodecaphonic scale.

Link to this section Summary

Types

The qualified variation of an interval’s size

The distance in half steps across an interval

The number of staff lines and spaces spanned by an interval

t()

An expression describing an interval

Functions

Enharmonically compares the specified interval1 and interval2

Computes the interval between the specified pitch1 and pitch2

Constructs a new interval with the specified definition

Constructs a new interval with the specified quality and size

Computes the distance in half steps across the specified interval

Determines if the specified interval cannot be simplified (see simplify/1)

Computes the simple interval that corresponds to the specified interval

Link to this section Types

Link to this type interval() View Source
interval() :: %Harmonex.Interval{quality: quality, size: size}

A Harmonex.Interval struct.

Link to this type quality() View Source
quality ::
  :perfect |
  :minor |
  :major |
  :diminished |
  :augmented |
  :doubly_diminished |
  :doubly_augmented

The qualified variation of an interval’s size.

Link to this type semitones() View Source
semitones() :: non_neg_integer

The distance in half steps across an interval.

Link to this type size() View Source
size() :: pos_integer

The number of staff lines and spaces spanned by an interval.

Link to this type t() View Source
t() :: %{quality: quality, size: size} | interval

An expression describing an interval.

Link to this section Functions

Link to this function compare(interval1, interval2) View Source

Enharmonically compares the specified interval1 and interval2.

Enharmonic comparison is made on the basis of semitones/1.

It returns:

  • :eq if they are identical or enharmonically equivalent
  • :lt if interval1 is enharmonically narrower
  • :gt if interval1 is enharmonically wider

Examples

iex> Harmonex.Interval.compare %{quality: :perfect, size: 4}, %{quality: :perfect, size: 4}
:eq

iex> Harmonex.Interval.compare %{quality: :major, size: 3}, %{quality: :diminished, size: 4}
:eq

iex> Harmonex.Interval.compare %{quality: :doubly_diminished, size: 6}, %{quality: :doubly_augmented, size: 4}
:lt

iex> Harmonex.Interval.compare %{quality: :minor, size: 10}, %{quality: :major, size: 9}
:gt

Computes the interval between the specified pitch1 and pitch2.

Examples

iex> Harmonex.Interval.from_pitches %{natural_name: :a, accidental: :sharp, octave: 4}, %{natural_name: :c, octave: 6}
%Harmonex.Interval{quality: :diminished, size: 10}

iex> Harmonex.Interval.from_pitches :a_sharp, :c
%Harmonex.Interval{quality: :diminished, size: 3}

iex> Harmonex.Interval.from_pitches :d_double_sharp, :a_double_sharp
%Harmonex.Interval{quality: :perfect, size: 4}

iex> Harmonex.Interval.from_pitches :c_flat, :c_natural
%Harmonex.Interval{quality: :augmented, size: 1}

iex> Harmonex.Interval.from_pitches :a_flat, :e_sharp
%Harmonex.Interval{quality: :doubly_diminished, size: 4}

iex> Harmonex.Interval.from_pitches :a_flat, :e_double_sharp
{:error, "Invalid interval"}

Constructs a new interval with the specified definition.

Examples

iex> Harmonex.Interval.new %{quality: :perfect, size: 1}
%Harmonex.Interval{quality: :perfect, size: 1}

iex> Harmonex.Interval.new %{quality: :augmented, size: 17}
%Harmonex.Interval{quality: :augmented, size: 17}

iex> Harmonex.Interval.new %{quality: :minor, size: 1}
{:error, "Quality of unison must be in [:perfect, :augmented, :doubly_augmented]"}

iex> Harmonex.Interval.new %{quality: :major, size: 8}
{:error, "Quality of octave must be in [:perfect, :diminished, :augmented, :doubly_diminished, :doubly_augmented]"}

iex> Harmonex.Interval.new %{quality: :perfect, size: 0}
{:error, "Size must be a positive integer"}

iex> Harmonex.Interval.new %{quality: :minor, size: -3}
{:error, "Size must be a positive integer"}

iex> Harmonex.Interval.new %{quality: :minor}
{:error, "Size must be a positive integer"}

Constructs a new interval with the specified quality and size.

Examples

iex> Harmonex.Interval.new :perfect, 1
%Harmonex.Interval{quality: :perfect, size: 1}

iex> Harmonex.Interval.new :augmented, 17
%Harmonex.Interval{quality: :augmented, size: 17}

iex> Harmonex.Interval.new :minor, 1
{:error, "Quality of unison must be in [:perfect, :augmented, :doubly_augmented]"}

iex> Harmonex.Interval.new :major, 8
{:error, "Quality of octave must be in [:perfect, :diminished, :augmented, :doubly_diminished, :doubly_augmented]"}

iex> Harmonex.Interval.new :imperfect, 1
{:error, "Invalid quality -- must be in [:perfect, :minor, :major, :diminished, :augmented, :doubly_diminished, :doubly_augmented]"}

iex> Harmonex.Interval.new :perfect, 0
{:error, "Size must be a positive integer"}

iex> Harmonex.Interval.new :minor, -3
{:error, "Size must be a positive integer"}

iex> Harmonex.Interval.new :minor, nil
{:error, "Size must be a positive integer"}

Computes the distance in half steps across the specified interval.

Examples

iex> Harmonex.Interval.semitones %{quality: :major, size: 3}
4

iex> Harmonex.Interval.semitones %{quality: :doubly_diminished, size: 9}
11

iex> Harmonex.Interval.semitones %{quality: :doubly_diminished, size: 16}
23

iex> Harmonex.Interval.semitones %{quality: :augmented, size: 300}
514
Link to this function simple?(interval) View Source
simple?(t) :: boolean | Harmonex.error

Determines if the specified interval cannot be simplified (see simplify/1).

Simple intervals are no more than 11 semitones across (see semitones/1).

Examples

iex> Harmonex.Interval.simple? %{quality: :major, size: 10}
false

iex> Harmonex.Interval.simple? %{quality: :major, size: 3}
true

iex> Harmonex.Interval.simple? %{quality: :augmented, size: 8}
false

iex> Harmonex.Interval.simple? %{quality: :diminished, size: 8}
true

Computes the simple interval that corresponds to the specified interval.

Simple intervals are no more than 11 semitones across (see semitones/1).

Examples

iex> Harmonex.Interval.simplify %{quality: :major, size: 10}
%Harmonex.Interval{quality: :major, size: 3}

iex> Harmonex.Interval.simplify %{quality: :major, size: 3}
%Harmonex.Interval{quality: :major, size: 3}

iex> Harmonex.Interval.simplify %{quality: :augmented, size: 8}
%Harmonex.Interval{quality: :augmented, size: 1}

iex> Harmonex.Interval.simplify %{quality: :diminished, size: 8}
%Harmonex.Interval{quality: :diminished, size: 8}