NAME

Music::Chord::Positions - generate various chord inversions and voicings

SYNOPSIS

use Music::Chord::Positions;
my $mcp = Music::Chord::Positions->new;

my $inversions = $mcp->chord_inv( [0, 3, 7]);
my $i6         = $mcp->chord_inv( [0, 3, 7], inv_num => 1 );
my $positions  = $mcp->chord_pos( [0, 3, 7]);

my $voices     = $mcp->chords2voices($positions);

$mcp->scale_degrees;  # returns 12 by default

Interface may be subject to change without notice! (And did between version 0.08 and subsequent for lightweight OOification.)

DESCRIPTION

Utility methods for generating tonal inversions or chord voicing variations of a given pitch set. A pitch set is an array reference consisting of semitone intervals:

[0, 4, 7]      # Major      C  E  G
[0, 3, 7]      # minor      C  D# G
[0, 4, 7, 11]  # Major 7th  C  E  G  B

The pitch set may be specified manually, or the chord_num method of Music::Chord::Note used to derive a pitch set from a named chord.

use Music::Chord::Note;
use Music::Chord::Positions;

# These both result in the same output from chord_inv()
my $i1 = chord_inv([ 0,3,7                                   ]);
my $i2 = chord_inv([ Music::Chord::Note->new->chord_num('m') ]);

This module pays attention to the vertical spacing of notes. Pitches are integers from 0 up, a semitone per integer, and the octave at 12 semitones (unless scale_degrees is customized to some non-12-tone system).

Consult the eg directory for example scripts.

METHODS

Methods may croak or die, depending on whether there is a problem with the input or internal code; use Try::Tiny if this is an issue.

new( parameter_pairs ... )

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

Music::Chord::Positions->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 method. (Non-12-tone scale degrees have not been tested for correctness!)

chord_inv( pitch_set, optional key value parameters, ... )

Generates all inversions. Returns a reference to a list of pitch sets. The order will be 1st inversion, 2nd inversion, etc. No transposition is performed, so inversions of 9ths or larger may result in a chord in a register above the original. As alternatives, consider the circular_permute or rotate methods of Music::AtonalUtil.

Parameters accepted:

inv_num => positive integer

Returns a specific inversion by number (1 for first inversion, 2 for second, etc.) as a pitch set. Will croak if an invalid index is supplied.

pitch_norm => boolean

If set and true, transposes the inversions down if the lowest pitch is greater than scale_degrees.

chord_pos( pitch set reference, list of optional parameters ... )

Generate different voicings of the same chord, by default between the root pitch and two registers above that. Returns a reference to a list of pitch sets. Only voicings where the root remains the root will be considered; chords that do not represent all pitches in the pitch set or that double non-root pitches will also be excluded. Chords with intervals greater than 19 semitones (octave+fifth) between adjacent pitches will be excluded, as will transpositions of the same voicing into higher registers.

The default settings for chord_pos() generate more voicings than may be permitted by music theory; a set more in line with what Schoenberg outlines in his chord positions chapter (in Theory of Harmony) would require something like:

my $chords = $mcp->chord_pos(
  [qw/0 4 7/],
  allow_transpositions =>  1, # as SATB can transpose up
  no_partial_closed    =>  1, # exclude half open/closed positions
  pitch_max            => -1, # avoids 36 (c''') in Soprano
);

Though Schoenberg later on uses voicings the above would exclude when dealing with sevenths, so restrictions might be best done after reviewing the full list of resulting chords for the desired qualities.

The chord_pos method can be influenced by the following parameters (default values are shown). Beware that removing restrictions may result in many, many, many different voicings for larger pitch sets.

allow_transpositions => 0

If set and true, allows transpositions of identical pitch sets into higher registers. That is, permit both 0 4 7 and 12 16 19.

interval_adj_max => 19

Largest interval allowed between two adjacent voices, in semitones.

no_limit_doublings => 0

If set and true, allows doublings on all pitches, not just the default of the root pitch.

no_limit_uniq => 0

If set and true, disables the unique pitch check. That is, voicings will be allowed with fewer pitches than in the original pitch set.

no_partial_closed => 0

If set and true, disallows vocings somewhere between close position and open position. See t/Schoenberg.t and the source for what is being done.

octave_count => 2

How far above the register of the chord to generate voicings in. If set to a large value, the interval_adj_max value may also need to be increased. The pitch_max parameter can be used to fine-tune the maximum pitch generated inside the set generated by this option.

pitch_max => inf

Maximum pitch to allow, in semitones. For fine-grained control below the span generated by the octave_count parameter. If positive, counts in semitones up from the lowest pitch to determine the maximum. If zero or negative, counts down from the octave_count + 1 interval instead.

root_any => 0

If set and true, allows the root pitch of the voicing to be any member of the original pitch set, not just the lowest of that set. Pointless if root_lock set.

root_lock => 0

Prevent the root pitch from changing in the generated positions. Defeats root_any option.

voice_count => depends on pitch set passed

Use this to customize the number of voices in the different chord voicings. At present, only one extra voice above the number of voices in the pitch set is implemented. Mostly to support SATB for three- pitch chords, in which case the root pitch will be doubled:

$mcp->chord_pos([0,4,7], voice_count => 4);

The chord voicings allowed by the default options may still not suit certain musical styles; for example, in SATB chorales, the bass alone is allowed to drift far from the other voices, but not both the bass and tenor from the upper voices. Voicings are not restricted by the limits of the human voice or for other instruments.

chords2voices( [ pitch set list ] )

Accepts a pitch set list (such as returned by chord_pos), transposes vertical chords into horizontal voices. Returns list of voices, highest to lowest. Returns the original pitch set list if nothing to transpose.

scale_degrees [ positiveintegergreaterthanone ]

Returns the number of degrees in the scale. By default, 12. Pass an integer greater than one to set a custom number of scale degrees.

SEE ALSO

• Music::Chord::Note - get pitch list from chord name.

• Music::AtonalUtil - Atonal musical utilities, some of which have use for tonal purposes, such as the rotate method. Music::NeoRiemannianTonnetz may also be of interest.

• Theory of Harmony by Arnold Schoenberg (ISBN 978-0-520-26608-7). Whose simple chord voicing exercise prompted this not so simple diversion in coding.

AUTHOR

Jeremy Mates <jmates@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011-2013 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.16 or, at your option, any later version of Perl 5 you may have available.