harmonex v0.6.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)

The numeric element of scientific pitch notation

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

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

Computes the pitch class corresponding to the specified pitch

Determines if the specified pitch represents a pitch class

Enharmonically compares the specified pitch1 and pitch2

Determines whether the specified pitch1 and pitch2 are enharmonically equivalent

Computes the enharmonic equivalents of the specified pitch

Computes the interval between the specified pitch1 and pitch2. 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_or_definition

Constructs a new pitch with the specified name and accidental_or_octave

Constructs a new pitch with the specified natural_name, accidental, and octave

Computes the octave of the specified pitch. Pitch values having an octave of nil represent pitch classes

Computes the distance in half steps between the specified pitch1 and pitch2

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 octave() View Source
octave() :: integer | nil

The numeric element of scientific pitch notation.

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

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, octave: octave} |
  %{natural_name: natural_name, accidental: accidental} |
  %{natural_name: natural_name, octave: octave} |
  %{natural_name: natural_name} |
  pitch

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, octave: 6}
: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

(DEPRECATED) 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

Computes the pitch class corresponding to the specified pitch.

Examples

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

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

iex> Harmonex.Pitch.class :a_flat
:a_flat

iex> Harmonex.Pitch.class :a
:a_natural
Link to this function class?(pitch) View Source
class?(t) :: boolean | Harmonex.error

Determines if the specified pitch represents a pitch class.

Examples

iex> Harmonex.Pitch.class? %{natural_name: :a, accidental: :flat, octave: 6}
false

iex> Harmonex.Pitch.class? %{natural_name: :a}
true

iex> Harmonex.Pitch.class? :a_flat
true

iex> Harmonex.Pitch.class? :a
true

Enharmonically compares the specified pitch1 and pitch2.

It returns:

  • :eq if they are identical or enharmonically equivalent
  • :lt if pitch1 is enharmonically lower
  • :gt if pitch1 is enharmonically higher

If either specified pitch has an octave (see Harmonex.Pitch.octave/1) of nil then the pitches are assumed to be in the same octave.

Examples

iex> Harmonex.Pitch.compare %{natural_name: :a, octave: 4}, %{natural_name: :a, octave: 4}
:eq

iex> Harmonex.Pitch.compare %{natural_name: :b, accidental: :sharp, octave: 5}, %{natural_name: :c, octave: 6}
:eq

iex> Harmonex.Pitch.compare %{natural_name: :b, accidental: :sharp, octave: 5}, %{natural_name: :c, octave: 5}
:gt

iex> Harmonex.Pitch.compare %{natural_name: :g, accidental: :sharp}, :a_flat
:eq

iex> Harmonex.Pitch.compare :c_flat, %{natural_name: :a, accidental: :double_sharp, octave: 2}
:eq

iex> Harmonex.Pitch.compare :a, :a_sharp
:lt

iex> Harmonex.Pitch.compare :a, :a
:eq
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.

If either specified pitch has an octave (see Harmonex.Pitch.octave/1) of nil then the pitches are assumed to be in the same octave.

Examples

iex> Harmonex.Pitch.enharmonic? %{natural_name: :a, octave: 4}, %{natural_name: :a, octave: 4}
true

iex> Harmonex.Pitch.enharmonic? %{natural_name: :b, accidental: :sharp, octave: 5}, %{natural_name: :c, octave: 6}
true

iex> Harmonex.Pitch.enharmonic? %{natural_name: :b, accidental: :sharp, octave: 5}, %{natural_name: :c, octave: 5}
false

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

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

iex> Harmonex.Pitch.enharmonic? :a, :a_sharp
false

iex> Harmonex.Pitch.enharmonic? :a, :a
true
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, octave: 6}
[%Harmonex.Pitch{natural_name: :a, accidental: :flat, octave: 6}]

iex> Harmonex.Pitch.enharmonics %{natural_name: :a, accidental: :double_sharp, octave: 5}
[%Harmonex.Pitch{natural_name: :b, accidental: :natural, octave: 5}, %Harmonex.Pitch{natural_name: :c, accidental: :flat, octave: 6}]

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

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

Computes the interval between the specified pitch1 and pitch2. Equivalent to Harmonex.Interval.from_pitches/2.

Examples

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

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

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

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_diminished, size: 4}

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

Examples

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

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

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

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]"}

iex> Harmonex.Pitch.new %{natural_name: :a, accidental: :flat, octave: :not_an_octave}
{:error, "Invalid octave -- must be an integer"}

Constructs a new pitch with the specified name and accidental_or_octave.

Examples

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

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

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 or octave -- must be in [:double_flat, :flat, :natural, :sharp, :double_sharp] or be an integer"}

Constructs a new pitch with the specified natural_name, accidental, and octave.

Examples

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

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

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

iex> Harmonex.Pitch.new :a, :flat, :not_an_octave
{:error, "Invalid octave -- must be an integer"}

Computes the octave of the specified pitch. Pitch values having an octave of nil represent pitch classes.

Examples

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

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

iex> Harmonex.Pitch.octave :a_flat
nil

Computes the distance in half steps between the specified pitch1 and pitch2.

Examples

iex> Harmonex.Pitch.semitones %{natural_name: :a, accidental: :flat, octave: 4}, %{natural_name: :c, accidental: :sharp, octave: 6}
17

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

iex> Harmonex.Pitch.semitones :c, :c
0