The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Music-AtonalUtil-0.18
River stage one • 4 direct dependents • 6 total dependents
3 ++
/ Music::AtonalUtil

NAME

Music::AtonalUtil - Perl extension for atonal music analysis and composition

SYNOPSIS

  use Music::AtonalUtil;
  my $atu = Music::AtonalUtil->new;

Then see below for methods.

DESCRIPTION

This module contains a variety of routines suitable for atonal music composition and analysis. See the methods below, the test suite, and the eg/atonal-util command line interface for ideas on how to use these routines. "SEE ALSO" has links to documentation on atonal analysis.

Warning! There may be errors due to misunderstanding of atonal theory by the autodidactic author. If in doubt, compare the results of this code with other material available.

Warning! The interface may change in the future (e.g. more OOish, so can do things like ->foo->bar->as_string and the like).

METHODS

By default, a 12-tone system is assumed. Input values are (often) not checked whether they reside inside this space. Most methods accept a pitch set (an array reference consisting of a list of pitch numbers), and most return new array references containing the results of the operation. Some basic sanity checking is done on the input, which may cause the code to croak if something is awry. Elements of the pitch sets are not checked whether they reside inside the 12-tone basis (pitch numbers through 11), so input data may need to be first reduced as follows:

  my $atu = Music::AtonalUtil->new;

  my $pitch_set = [25,18,42,5];
  for my $p (@$pitch_set) { $p %= $atu->scale_degrees }

  say "Result: @$pitch_set";      # Result: 1 6 6 5

Results from the various methods should reside within the scale_degrees, unless the method returns something else.

new parameter_pairs ...

Constructor. The degrees in the scale can be adjusted via:

  Music::AtonalUtil->new(DEG_IN_SCALE => 17);

or some other positive integer greater than one, to use a non-12-tone basis for subsequent method calls. This value can be set or inspected via the scale_degrees call.

The pitches2notes style can also be set here:

  Music::AtonalUtil->new(P2N_STYLE => 'flats');

or via the pitch2note_style method.

circular_permute pitch_set

Takes a pitch set, returns an array reference of pitch set references:

  $atu->circular_permute([1,2,3]);   # [[1,2,3],[2,3,1],[3,1,2]]

This is used by the normal_form method, internally. This permutation is identical to inversions in tonal theory, but different from the invert method offered by this module. See also rotate to rotate a pitch set by a particular amount.

complement pitch_set

Returns the pitches of the scale degrees not set in the passed pitch set.

  $atu->complement([1,2,3]);    # [0,4,5,6,7,8,9,10,11]

Calling prime_form on the result will find the abstract complement of the original set.

forte2pcs forte_number

Given a Forte Number (such as 6-z44 or 6-Z44), returns the corresponding pitch set as an array reference, or nothing if an unknown Forte Number is supplied.

interval_class_content pitch_set

Given a pitch set with at least two elements, returns an array reference (and in list context also a hash reference) representing the interval- class vector information. Pitch sets with similar ic content tend to sound the same (see also zrelation).

This vector is also known as a pitch-class interval (PIC) vector or absolute pitch-class interval (APIC) vector:

https://en.wikipedia.org/wiki/Interval_vector

Uses include an indication of invarience under transposition; see the invariants mode of eg/atonal-util for the display of invariant pitches.

invariance_matrix pitch_set

Returns reference to an array of references that comprise the invarience under Transpose(N)Inversion operations on the given pitch set. Probably easier to use the invariants mode of eg/atonal-util or use equivalent code.

invert pitch_set optional_axis

Inverts the given pitch set, by default around the 0 axis, within the degrees in scale. Returns resulting pitch set as an array reference. Some examples or styles assume rotation with an axis of 6, for example:

https://en.wikipedia.org/wiki/Set_%28music%29#Serial

Has the "retrograde-inverse transposition" of 0 11 3 becomming 4 8 7. This can be reproduced via:

  my $p = $atu->retrograde([0,11,3]);
  $p = $atu->invert($p, 6);
  $p = $atu->transpose($p, 1);
multiply pitch_set factor

Multiplies the supplied pitch set by the given factor, modulates the results by the scale_degrees, and returns the results as an array reference.

normal_form pitch_set

Returns the normal form of the passed pitch set, via a "packed from the right" method outlined in the www.mta.ca link, below, so may return different normal forms than the Allen Forte method. There is stub code for the Allen Forte method in this module, though I lack enough information to verify if that code is correct.

notes2pitches note_set optional_conversion_hashref

Utility method that converts (by default lilypond) note names to pitch numbers, and returns an arrary reference of the resulting pitch set:

  $atu->notes2pitches([qw/c ees g/]);  # returns [0,3,7]
  $atu->notes2pitches('d');            # returns 2

An optional hash reference can also be supplied, this should contain note name keys to pitch number value mappings (note names are lowercased in the code prior to lookup). See pitches2notes for the reverse operation.

pcs2forte pitch_set

Given a pitch set, returns the Forte Number of that set.

  $atu->pcs2forte([qw/0 1 2 5 6 9/]);  # array ref form

  $atu->pcs2forte('[0,1,2,5,6,9]');    # string forms are okay
  $atu->pcs2forte('0,1,2,5,6,9');      # as well

The Forte Numbers use lowercase z, for example 6-z44. An undefined value will be returned if no Forte Number exists for the pitch set.

pitch2intervalclass pitch

Returns the interval class a given pitch belongs to (0 is 0, 11 maps down to 1, 10 down to 2, ... and 6 is 6 for the standard 12 tone system). Used internally by the interval_class_content method.

pitch2note_style style

Returns (or with argument also sets) the default pitches2notes style, currently either sharps or flats, to emit chromatics as either all sharps or flats.

pitches2notes pitch_set

Converts pitch numbers to lilypond note names. See notes2pitches for the reverse operation.

prime_form pitch_set

Returns the prime form of a given pitch set (via normal_form and various other operations on the passed pitch set).

retrograde pitch_set

Fancy term for the reverse of a list. Returns reference to array of said reversed data.

rotate pitch_set rotate_by

Rotates the members given pitch set by the given integer. Returns array reference of the resulting pitch set. circular_permute performs all the possible rotations for a pitch set.

scale_degrees optional_integer

Without arguments, returns the number of scale degrees (12 by default). If passed a positive integer greater than two, sets the scale degrees to that. Note that changing this will change the results from almost all the methods this module offers, and would only be used for calculations involving a subset of the Western 12 tone system, or some exotic scale with more than 12 tones.

set_complex pitch_set

Creates the set complex, or a 2D array with the pitch set as the column headers, pitch set inversion as the row headers, and the combination of those two for the intersection of the row and column headers. Returns reference to the resulting array of arrays.

Ideally the first pitch of the input pitch set should be 0 (so the input may need reduction to prime_form first).

subsets pitch_set optional_length

Returns the subsets of a given pitch set, of default length one minus the magnitude of the input pitch set (that is, whatever two element pitch sets exist for a given three element pitch set). The custom length allows subsets of 1 <= len <= magnitude_of_pitch_set results to be returned, for example three element pitch subsets of a given five element pitch set.

The underlying permutation library might sort or otherwise return the results in arbitrary orderings. Sorry about that.

tcs pitch_set

Returns array reference consisting of the transposition common-tone structure (TCS) for the given pitch set, that is, for each of the possible transposition operations under the scale_degrees in question, how many common tones there are with the original set.

tcis pitch_set

Like tcs, except uses transpose_invert instead of just transpose.

transpose pitch_set integer

Transposes the given pitch set by the given integer value, returns that result as an array reference.

transpose_invert pitch_set integer

Performs invert on given pitch set, then transposition as per transpose, returning the resulting array reference.

variances pitch_set1 pitch_set2

Given two pitch sets, in scalar context returns the shared notes of those two pitch sets as an array reference. In list context, returns the shared notes (intersection), difference, and union all as array references.

zrelation pitch_set1 pitch_set2

Given two pitch sets, returns true if the two sets share the same interval_class_content, false if not.

BUGS

Reporting Bugs

If the bug is in the latest version, send a report to the author. Patches that fix problems or add new features are welcome.

http://github.com/thrig/Music-AtonalUtil

Known Issues

Poor naming conventions and standards of underlying music theory and any associated mistakes in understanding thereof by the author.

SEE ALSO

Reference and learning material:

  • The perlreftut, perldsc, and perllol perldocs to learn more about perl references, as the pitch sets utilize array references and arrays of array references.

  • http://www.mta.ca/faculty/arts-letters/music/pc-set_project/pc-set_new/

  • Musimathics, Vol. 1, p.311-317

  • "The Structure of Atonal Music" by Allen Forte.

  • http://en.wikipedia.org/wiki/Forte_number

  • Music::Chord::Positions for a more tonal module.

  • http://lilypond.org/ for documentation on the default note name syntax used by various routines.

AUTHOR

Jeremy Mates, <jmates@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Jeremy Mates

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.