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)
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
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
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).
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
).
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
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
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
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]
interval(t, t) :: Harmonex.Interval.interval | Harmonex.error
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
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
.
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]"}
new(natural_name, accidental) :: pitch | Harmonex.error
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]"}
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