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
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
)
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
accidental :: :natural | :flat | :sharp | :double_flat | :double_sharp
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.
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
).
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
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
class(t_map) :: pitch | Harmonex.error
class(t_atom) :: t_atom | Harmonex.error
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
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
compare(t, t) :: Harmonex.comparison | Harmonex.error
Enharmonically compares the specified pitch1
and pitch2
.
It returns:
:eq
if they are identical or enharmonically equivalent:lt
ifpitch1
is enharmonically lower:gt
ifpitch1
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
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
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]
interval(t, t) :: Harmonex.Interval.interval | Harmonex.error
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
natural_name(t) :: natural_name | Harmonex.error
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"}
new(natural_name, accidental | octave) :: pitch | Harmonex.error
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"}
new(natural_name, accidental, octave) :: pitch | Harmonex.error
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
semitones(t, t) :: Harmonex.Interval.semitones | Harmonex.error
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