harmonex v0.5.0 Harmonex.Pitch View Source

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

Link to this section Summary

Types

The alteration of a pitch from its natural value

The name of a pitch whose accidental is ♮ (natural)

t()

An expression describing a pitch

An atom expression describing a pitch. Can be a natural_name/0, or a natural_name/0 joined by underscore with an accidental/0 (e.g., :a_flat)

A map expression describing a pitch

Functions

Computes the accidental of the specified pitch

Computes a pitch that is the sum of the specified pitch and the specified adjustment in semitones

Determines whether the specified pitch1 and pitch2 are enharmonically equivalent

Computes the enharmonic equivalents of the specified pitch

Computes the interval between the specified low_pitch and high_pitch. Equivalent to Harmonex.Interval.from_pitches/2

Computes the full name of the specified pitch, combining its natural name and its accidental

Computes the natural name of the specified pitch

Constructs a new pitch with the specified name

Constructs a new pitch with the specified natural_name and accidental

Computes the distance in half steps between the specified low_pitch and high_pitch

Link to this section Types

Link to this type accidental() View Source
accidental ::
  :natural |
  :flat |
  :sharp |
  :double_flat |
  :double_sharp

The alteration of a pitch from its natural value.

Link to this type natural_name() View Source
natural_name() :: :a | :b | :c | :d | :e | :f | :g

The name of a pitch whose accidental is ♮ (natural).

Link to this type pitch() View Source
pitch() :: %Harmonex.Pitch{accidental: accidental, natural_name: natural_name}

A Harmonex.Pitch struct.

An expression describing a pitch.

An atom expression describing a pitch. Can be a natural_name/0, or a natural_name/0 joined by underscore with an accidental/0 (e.g., :a_flat).

Link to this type t_map() View Source
t_map ::
  %{natural_name: natural_name, accidental: accidental} |
  %{natural_name: natural_name}

A map expression describing a pitch.

Link to this section Functions

Computes the accidental of the specified pitch.

Examples

iex> Harmonex.Pitch.accidental %{natural_name: :a, accidental: :flat}
:flat

iex> Harmonex.Pitch.accidental %{natural_name: :a}
:natural

iex> Harmonex.Pitch.accidental :a_flat
:flat

iex> Harmonex.Pitch.accidental :a
:natural
Link to this function adjust_by_semitones(pitch, adjustment) View Source
adjust_by_semitones(t_map, integer) :: pitch | Harmonex.error
adjust_by_semitones(t_atom, integer) ::
  t_atom |
  Harmonex.error

Computes a pitch that is the sum of the specified pitch and the specified adjustment in semitones.

Examples

iex> Harmonex.Pitch.adjust_by_semitones %{natural_name: :a, accidental: :sharp}, 14
%Harmonex.Pitch{natural_name: :c, accidental: :natural}

iex> Harmonex.Pitch.adjust_by_semitones :b_flat, -2
:g_sharp

iex> Harmonex.Pitch.adjust_by_semitones :c, 0
:c_natural
Link to this function enharmonic?(pitch1, pitch2) View Source
enharmonic?(t, t) :: boolean | Harmonex.error

Determines whether the specified pitch1 and pitch2 are enharmonically equivalent.

Examples

iex> Harmonex.Pitch.enharmonic? %{natural_name: :g, accidental: :sharp}, :a_flat
true

iex> Harmonex.Pitch.enharmonic? :c_flat, %{natural_name: :a, accidental: :double_sharp}
true

iex> Harmonex.Pitch.enharmonic? :b_sharp, :d_double_flat
true

iex> Harmonex.Pitch.enharmonic? :a_sharp, :a
false
Link to this function enharmonics(pitch) View Source
enharmonics(t_map) :: [pitch] | Harmonex.error
enharmonics(t_atom) :: [t_atom] | Harmonex.error

Computes the enharmonic equivalents of the specified pitch.

Examples

iex> Harmonex.Pitch.enharmonics %{natural_name: :g, accidental: :sharp}
[%Harmonex.Pitch{natural_name: :a, accidental: :flat}]

iex> Harmonex.Pitch.enharmonics :f_double_sharp
[:g_natural, :a_double_flat]

iex> Harmonex.Pitch.enharmonics :g
[:f_double_sharp, :a_double_flat]

iex> Harmonex.Pitch.enharmonics :c_flat
[:a_double_sharp, :b_natural]

iex> Harmonex.Pitch.enharmonics :b_sharp
[:c_natural, :d_double_flat]

iex> Harmonex.Pitch.enharmonics :a_sharp
[:b_flat, :c_double_flat]

Computes the interval between the specified low_pitch and high_pitch. Equivalent to Harmonex.Interval.from_pitches/2.

Examples

iex> Harmonex.Pitch.interval %{natural_name: :a, accidental: :sharp}, %{natural_name: :c}
%Harmonex.Interval{quality: :diminished, size: 3}

iex> Harmonex.Pitch.interval :b_flat, :c
%Harmonex.Interval{quality: :major, size: 2}

iex> Harmonex.Pitch.interval :d_double_sharp, :a_double_sharp
%Harmonex.Interval{quality: :perfect, size: 5}

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

iex> Harmonex.Pitch.interval :a_flat, :e_sharp
%Harmonex.Interval{quality: :doubly_augmented, size: 5}

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

Computes the full name of the specified pitch, combining its natural name and its accidental.

Examples

iex> Harmonex.Pitch.name %{natural_name: :a, accidental: :flat}
:a_flat

iex> Harmonex.Pitch.name %{natural_name: :a}
:a_natural

iex> Harmonex.Pitch.name :a_flat
:a_flat

iex> Harmonex.Pitch.name :a
:a_natural

Computes the natural name of the specified pitch.

Examples

iex> Harmonex.Pitch.natural_name %{natural_name: :a, accidental: :flat}
:a

iex> Harmonex.Pitch.natural_name %{natural_name: :a}
:a

iex> Harmonex.Pitch.natural_name :a_flat
:a

iex> Harmonex.Pitch.natural_name :a
:a

Constructs a new pitch with the specified name.

Examples

iex> Harmonex.Pitch.new %{natural_name: :a, accidental: :flat}
%Harmonex.Pitch{natural_name: :a, accidental: :flat}

iex> Harmonex.Pitch.new %{natural_name: :a}
%Harmonex.Pitch{natural_name: :a, accidental: :natural}

iex> Harmonex.Pitch.new :a_flat
%Harmonex.Pitch{natural_name: :a, accidental: :flat}

iex> Harmonex.Pitch.new :a
%Harmonex.Pitch{natural_name: :a, accidental: :natural}

iex> Harmonex.Pitch.new %{natural_name: :h}
{:error, "Invalid pitch name -- must be in [:a, :b, :c, :d, :e, :f, :g]"}

iex> Harmonex.Pitch.new :h
{:error, "Invalid pitch name -- must be in [:a, :b, :c, :d, :e, :f, :g]"}

iex> Harmonex.Pitch.new %{natural_name: :a, accidental: :out_of_tune}
{:error, "Invalid accidental -- must be in [:double_flat, :flat, :natural, :sharp, :double_sharp]"}

Constructs a new pitch with the specified natural_name and accidental.

Examples

iex> Harmonex.Pitch.new :a, :flat
%Harmonex.Pitch{natural_name: :a, accidental: :flat}

iex> Harmonex.Pitch.new :h, :flat
{:error, "Invalid pitch name -- must be in [:a, :b, :c, :d, :e, :f, :g]"}

iex> Harmonex.Pitch.new :a, :out_of_tune
{:error, "Invalid accidental -- must be in [:double_flat, :flat, :natural, :sharp, :double_sharp]"}
Link to this function semitones(low_pitch, high_pitch) View Source
semitones(t, t) :: 0..11 | Harmonex.error

Computes the distance in half steps between the specified low_pitch and high_pitch.

Examples

iex> Harmonex.Pitch.semitones %{natural_name: :a, accidental: :flat}, %{natural_name: :c, accidental: :sharp}
5

iex> Harmonex.Pitch.semitones :a_flat, :b_flat
2

iex> Harmonex.Pitch.semitones :d_double_sharp, :b_double_sharp
9