/ 
Music-PitchNum-0.09
River stage two • 10 direct dependents • 11 total dependents
/ Music::PitchNum

NAME

Music::PitchNum - note name and pitch number utility roles

SYNOPSIS

package MyCleverModule;
use Moo;
with('Music::PitchNum');
...

Then elsewhere:

use MyCleverModule;
my $x = MyCleverModule->new;

$x->pitchname(69);    # A4
$x->pitchnum('A4');   # 69

$x->pitchname(69, ignore_octave => 1);    # A

Or, to dynamically select what module is used at object construction time, consider:

package MyCleverModule;
use Moo;

sub BUILD {
  my ( $self, $param ) = @_;
  with( exists $param->{pitchstyle} ?
    $param->{pitchstyle} : 'Music::PitchNum' );
}

package main;

my $x = MyCleverModule->new( pitchstyle => 'Music::PitchNum::ABC' );
print $x->pitchname(69);

See also the eg/ and t/ directories of the distribution of this module for example code, or look on metacpan for modules that depend on this module.

DESCRIPTION

    "One need but glance at the various notations for a single tone to be convinced that there is a sorrowful lack of agreement in usage." -- R. W. Young. "Terminology for Logarithmic Frequency Units"

This module provides utility music pitch name and number routines; that is, an easy way to obtain pitch numbers from various pitch name formats (Helmholtz, or in particular what lilypond uses, what MIDI::Simple accepts, and the American Standard Pitch Notation (ASPN)). The resulting pitch numbers are integers (as used by the MIDI standard), though this module does not restrict the range of the pitch numbers as MIDI does (support for black hole pressure waves was a design goal).

This module is somewhat catholic in what it accepts; alternatives are the variety of sub-modules that support only the named notation system; the Music::PitchNum::German implementation, in particular, is Helmholtz- based, though with "H" representing B natural and "B" as B flat as is necessary for BACH motif support. Not supported by this particular module include the ABC notation, solfege note names, and various other International formats. There is also no microtonal support, and the traditional Western 12-tone chromatic scale is used as the basis for the resulting pitch numbers. Also, the parsing of the notes is limited to just the note name, octave indication, and accidental, and in no way supports rhythmic elements or the like.

This module is expected to be used as a Role from some other module; Moo::Role may be informative.

METHODS

pitchname pitchnumber

Returns a pitch name for the pitch number provided in the ASPN format. Will die if passed something that does not look like a number.

->pitchname(59);       # B3
->pitchname(60);       # C4
->pitchname(61);       # C#4

This method accepts an optional ignore_octave parameter that if true will strip the octave information from the pitch name.

->pitchname(59, ignore_octave => 1); # B
pitchnum pitchname

Returns the pitch number for the given pitch, or undef if nothing was parsed from the input. Anything that already looks like a number will be returned by way of a trip through the int function.

->pitchnum(q{D4b});    # 61
->pitchnum(q{Db4});    # 61
->pitchnum(q{cis'});   # 61
->pitchnum(q{bisis});  # 61

The accidentals supported are quite varied, and may be doubled to produce the corresponding doubleflat or doublesharp. The allowed list includes the flats b, es, ess, f, or flat or the sharps s, is, iss, sharp, #, d, or k. These can be mixed with the note names A through G, and either the ASPN octave number (4 for middle C) or the Helmholtz-derived , or ' indicators as used in lilypond.

English multiple C notation is supported with upper case note names for the octaves below the C below middle C:

->pitchnum('C');       # 48
->pitchnum('CC');      # 36
->pitchnum('CCC');     # 24

In general, the first matching element wins, so if something silly like CCC''4 were specified, the English match happens first (as that occurs while matching the note name) and then the other octave indicators are ignored. Other implementations may desire a tighter match or to throw errors on such absurdities.

BUGS

Reporting Bugs

Please report any bugs or feature requests to bug-music-pitchnum at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Music-PitchNum.

Patches might best be applied towards:

https://github.com/thrig/Music-PitchNum

Known Issues

Matching the fancy flat symbol (or the double-flat, or double-sharp) is not yet supported. Use ## or b or bb for those in the meantime, or the various other ASCII forms allowed. Doubtless other things besides.

SEE ALSO

How the resulting pitch names or numbers are used is of no concern to this module, though see MIDI::Simple or Music::Scala or Music::LilyPondUtil for means to convert the numbers into MIDI events, frequencies, or a form suitable to pass to lilypond.

Moo and Moo::Role would be good reads for programmers using this module.

Music::PitchNum::ABC, Music::PitchNum::ASPN, Music::PitchNum::Dutch, Music::PitchNum::German

REFERENCES

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) <jmates at cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2014-2016 by Jeremy Mates

This module is free software; you can redistribute it and/or modify it under the Artistic License (2.0).