The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Music-Cadence-0.1507
River stage one • 1 direct dependent • 1 total dependent
++
/ Music::Cadence

NAME

Music::Cadence - Generate musical cadence chords

VERSION

version 0.1507

SYNOPSIS

  use Music::Cadence;

  my $mc = Music::Cadence->new;

  my $chords = $mc->cadence;
  # [G B D], [C E G C]

  $mc = Music::Cadence->new(octave => 4);

  $chords = $mc->cadence;
  # [G4 B4 D4], [C4 E4 G4 C5]

  $chords = $mc->cadence(
    type    => 'half',
    octave  => 0,
    leading => 2,
  );
  # [D F A], [G B D]

  $chords = $mc->cadence(
    type      => 'imperfect',
    inversion => { 1 => 1, 2 => 1 },
  );
  # [B4 D4 G5], [E4 G4 C5]

  $mc = Music::Cadence->new(
    key    => 'C#',
    octave => 5,
  );

  $chords = $mc->cadence;
  # [G#5 C5 D#5], [C#5 F5 G#5 C#6]

  $mc = Music::Cadence->new(
    key    => 'C#',
    octave => 5,
    format => 'midi',
  );

  $chords = $mc->cadence;
  # [Gs5 C5 Ds5], [Cs5 F5 Gs5 Cs6]

  $mc = Music::Cadence->new(format => 'midinum');

  $chords = $mc->cadence(octave => 4);
  # [67 71 62], [60 64 67 72]

  $chords = $mc->cadence(octave => -1);
  # [7 11 2], [0 4 7 12] <- pitch-classes!

  $mc = Music::Cadence->new(seven => 1);

  $chords = $mc->cadence;
  # [G B D F], [C E G A# C]

  $chords = $mc->cadence(
    type   => 'evaded',
    octave => 4,
  );
  # [F4 G5 B5 D5], [E4 G4 A#4 C5]

  my $altered = $mc->remove_notes([1,2], [qw(Gs5 C5 Ds5)]);
  # [Gs5]

DESCRIPTION

Music::Cadence generates a pair of musical cadence chords.

These chords are added to the end of a musical phrase, and are used to suggest a sense of anticipation, pause, finality, etc.

ATTRIBUTES

key

  $key = $mc->key;

The key or tonal center to use, in isobase format.

Default: C

Examples: G#, Eb

scale

  $scale = $mc->scale;

The modal scale to use.

Default: major

Supported scales are the diatonic modes:

  ionian / major
  dorian
  phrygian
  lydian
  mixolydian
  aeolian / minor
  locrian

octave

  $octave = $mc->octave;

The octave to either append to named chord notes, or to determine the correct midinum note number.

Default: 0

If the format is midi or the default, setting this to 0 means "do not append." Setting it to a positive integer renders the note in ISO format.

The midinum range for this attribute should an integer from -1 to 9 (giving note numbers 0 to 127).

format

  $format = $mc->format;

The output format to use.

Default: isobase (i.e. "bare note names")

If midi, convert sharp # to s and flat b to f after chord generation.

If midinum, convert notes to their numerical MIDI equivalents.

seven

  $seven = $mc->seven;

If set, use seventh chords of four notes instead of diatonic triads.

Default: 0

picardy

  $picardy = $mc->picardy;

If set, use the "Picardy third" for the final chord.

This effectively raises the second note of the final chord by one half-step.

Default: 0

METHODS

new

  $mc = Music::Cadence->new;  # Use defaults

  $mc = Music::Cadence->new(  # Override defaults
    key     => $key,
    scale   => $scale,
    octave  => $octave,
    format  => $format,
    seven   => $seven,
    picardy => $picardy,
  );

Create a new Music::Cadence object.

cadence

  $chords = $mc->cadence;     # Use defaults

  $chords = $mc->cadence(     # Override defaults
    key       => $key,        # See above
    scale     => $scale,      # "
    octave    => $octave,     # "
    picardy   => $picardy,    # "
    type      => $type,       # Default: perfect
    leading   => $leading,    # Default: 1
    variation => $variation,  # Default: 1
    inversion => $inversion,  # Default: 0
  );

Return an array reference of the chords of the cadence type based on the given key and scale name, etc.

Supported cadences are:

  deceptive
  evaded
  half
  imperfect
  perfect
  plagal

And "authentic" cadence is either perfect or imperfect.

The variation applies to the deceptive and imperfect cadences.

If the type is deceptive, the variation determines the final chord. If it is set to 1, the vi chord is used. For 2, the IV chord is used.

If the type is imperfect and there is no inversion, the variation determines the kind of perfect cadence generated. For 1, the highest voice is not the tonic. For 2, the fifth chord is replaced with the seventh. So in a major key, the V chord would be replaced with the vii diminished chord.

For an imperfect cadence, if the inversion is set to a hash reference of numbered keys, the values are the types of inversions to apply to the chords of the cadence. For example:

  inversion => { 1 => 2, 2 => 1 },

This means, "Apply the second inversion to the first chord of the cadence, and apply the first inversion to the second chord."

For seventh chords (of 4 notes), the third inversion can be applied.

To not apply an inversion to an inverted imperfect cadence chord, either do not include the numbered chord in the hash reference, or set its value to 0 zero.

The leading chord is a number (1-7) for the scale chord to use for the first half cadence chord. For the key of C major this is:

  1: C maj
  2: D min
  3: E min
  4: F maj
  5: G maj
  6: A min
  7: B dim

If an inversion is defined for the half cadence, the chords are inverted as described above for the imperfect cadence.

The evaded cadence applies inversions to seventh chords. The default is to invert the first chord by the third inversion and the second by the first inversion.

Handy Summary

 1. Deceptive -> V-vi or V-IV
    variation
        1: final chord = vi
        2: final chord = IV

 2. Evaded -> inverted V-I 7th chords
    inversion
        1: 1st, 2nd, or 3rd applied to first chord
        2: "                           second chord

 3. Half -> <leading>-V and possibly inverted
    leading: first chord = 1-7
    inversion
        as above (3rd inversion only for 7th chords)

 4. Imperfect -> V-I or vii-I or V-I inverted
    variation (no inversion)
        1: first chord = V
        2: first chord = vii
    inversion (variation ignored)
        as above (3rd inversion only for 7th chords)

 5. Perfect -> V-I + tonic added an octave above

 6. Plagal -> IV-I

remove_notes

  $altered = $mc->remove_notes(\@indices, \@chord);

Remove the given indices from the given chord.

SEE ALSO

The eg/* and t/* programs in this distribution

List::Util

Moo

Music::Chord::Note

Music::Chord::Positions

Music::Note

Music::Scales

Music::ToRoman

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

https://www.musictheoryacademy.com/how-to-read-sheet-music/cadences/

https://www.musictheory.net/lessons/55

AUTHOR

Gene Boggs <gene@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019-2023 by Gene Boggs.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.