NAME

MIDI::Praxis::Variation - Variation techniques used in music composition

VERSION

version 0.0600

SYNOPSIS

  use MIDI::Praxis::Variation ':all';

  my @notes = qw(C5 E5 G5);
  my @dura = qw(qn qn);

  my @x = augmentation(@dura);
  @x = diminution(@dura);
  my $x = dur('qn');
  @x = inversion('B4', @notes);
  $x = note_name_to_number('C5');
  $x = note2num('C5'); # Alias for note_name_to_number()
  @x = ntup(2, @notes);
  @x = original(@notes);
  @x = notes2nums(@notes); # Alias for original()
  $x = raugmentation(1.5, @dura);
  $x = rdiminution(1.5, @dura);
  @x = retrograde(@notes);
  @x = retrograde_inversion('B4', @notes);
  @x = transposition(@notes);
  $x = tye(@dura);
  $x = tie_durations(@dura); # Alias for tye()

DESCRIPTION

Melodic variation techniques, as implemented here, expect MIDI::Simple style note names or durations as input. They return an array of MIDI note numbers or duration values.

FUNCTIONS

note_name_to_number, note2num

  $x = note_name_to_number($note_name);
  $x = note2num($note_name);

Map a single note name to a MIDI note number.

Returns: An equivalent MIDI note number or -1 if not known.

original, notes2nums

  @x = original(@array);
  @x = notes2nums(@array);

Map note names to MIDI note numbers.

Returns: An equivalent array of MIDI note numbers.

Argument:

  @array - An array of note names.

retrograde

  @x = retrograde(@array);

Form the retrograde of an array of note names.

Returns: The retrograde equivalent array as MIDI note numbers.

Argument:

  @array - An array of note names.

transposition

  @x = transposition($distance, @array);

Form the transposition of an array of notes.

Returns: MIDI note numbers equivalent by transposition from an array of note names OR MIDI note numbers.

Arguments:

  $distance - An integer giving distance and direction.
  @array    - An array of note names OR MIDI note numbers.

Expects to see an integer followed an array of MIDI::Simple style note names OR MIDI note numbers. The integer specifies the direction and distance of transposition. For example, 8 indicates 8 semitones up while -7 asks for 7 semitones down. The array argument specifies the notes to be transposed.

inversion

  @x = inversion($axis, @array);

Form the inversion of an array of notes.

Returns: MIDI note numbers equivalent by inversion to an array of note names.

Arguments:

  $axis  - A note to use as the axis of this inversion.
  @array - An array of note names.

Expects to see a MIDI::Simple style note name followed by an array of such names. These give the axis of inversion and the notes to be inverted.

retrograde_inversion

  @x = retrograde_inversion($axis, @array);

Form the retrograde inversion of an array of notes.

Returns: MIDI note numbers equivalent by retrograde inversion to an array of note names.

Argument:

  @array - An array of note names.

Inverts about the supplied $axis.

dur

  $x = dur($dur_or_len);

Compute duration of a note.

Returns: Duration as an integer.

Argument:

  $dur_or_len - A string consisting of a MIDI::Simple style numeric
  duration spec (e.g. d48, or d60) or length spec (e.g. qn or dhn)

Note that string input is expected and integer output is returned.

tye, tie_durations

  $x = tye(@dur_or_len);
  $x = tie_durations(@dur_or_len);

Compute the sum of the durations of notes. As with a tie in music notation. This odd spelling is used to avoid conflict with the perl reserved word tie.

Returns: Duration as an integer.

Argument:

  @dur_or_len - A list of strings consisting of MIDI::Simple style
  numeric duration specs (e.g. d48, or d60) or length specs (e.g. qn
  or dhn)

raugmentation

  $x = raugmentation($ratio, @dur_or_len);

Augment duration of notes, multiplying them by $ratio.

Returns: Duration as an integer.

Argument:

  $ratio - An integer multiplier

  @dur_or_len - A list of MIDI::Simple style numeric duration specs
  (e.g. d48, or d60) or length specs (e.g. qn or dhn)

rdiminution

  $x = rdiminution($ratio, @dur_or_len);

Diminish duration of notes, dividing them by $ratio.

Returns: Duration as an integer.

Argument:

  $ratio - An integer divisor

  @dur_or_len - A list of MIDI::Simple style numeric duration specs
  (e.g. d48, or d60) or length specs (e.g. qn or dhn)

augmentation

  @x = augmentation(@dur_or_len);

Augment duration of notes multiplying them by 2, (i.e. double).

Returns: Duration as an integer.

Argument:

  @dur_or_len - A list of strings consisting of MIDI::Simple style
  numeric duration specs (e.g. d48, or d60) or length specs (e.g. qn
  or dhn)

diminution

  @x = diminution(@dur_or_len);

Diminish durations of notes dividing them by 2, (i.e. halve).

Returns: Duration as an integer.

Argument:

  @dur_or_len - A list of strings consisting of MIDI::Simple style
  numeric duration specs (e.g. d48, or d60) or length specs (e.g. qn
  or dhn)

The returned integer is the approximate result of dividing the original durations by 2.

ntup

  @x = ntup($nelem, @subject);

Catalog tuples of length $nelem in @subject.

Returns: An array of tuples of length $nelem.

Argument:

  $nelem   - Number of elements in each tuple
  @subject - Subject array to be scanned for tuples

Scan begins with the 0th element of @subject looking for a tuple of length $nelem. Scan advances by one until it has found all tuples of length $nelem. For example: given the array @ar = qw(1 2 3 4) and $nelem = 2, then ntup(2, @ar) would return qw(1 2 2 3 3 4). Note that if $nelem equals -1, 0, or a value greater than the size of @subject, this function will return ();

SEE ALSO

The eg/* and t/01-functions.t files in this distribution

MIDI::Simple

MAINTAINER

Gene Boggs <gene@cpan.org>

AUTHOR

Craig Bourne <cbourne@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 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.

cpanm MIDI::Praxis::Variation

perl -MCPAN -e shell
install MIDI::Praxis::Variation