NAME

Music::ScaleNote - Manipulate the position of a note in a scale

VERSION

version 0.0705

SYNOPSIS

  use Music::ScaleNote;

  my $msn = Music::ScaleNote->new(
    scale_note  => 'C',
    scale_name  => 'pminor',
    note_format => 'ISO',
    offset      => 1,
    verbose     => 1,
  );

  my $note = $msn->get_offset(note_name => 'C4');
  say $note->format('ISO'); # D#4

  $msn = Music::ScaleNote->new(
    scale_note => 'C',
    scale_name => 'major',
  );

  $note = $msn->get_offset(
    note_name   => 60,
    note_format => 'midinum',
    offset      => -1,
  );
  say $note->format('midinum'); # 58

  $note = $msn->step(
    note_name => 'D3',
    steps     => -1,
    flat      => 1,
  );
  say $note->format('ISO'); # Db3

DESCRIPTION

A Music::ScaleNote object manipulates the position of a note in a scale.

Given a scale_name, a scale_note, a starting note_name, the note_format, and a scale position offset, the new note is computed.

So for scale C D# F G A# (C pentatonic minor), note name C4 (in ISO format), and offset 1 (move one scale step to the right), the note D#4 is returned.

For an offset of -1, the note A#3 is returned.

This module also provides a step method that returns the new note a given number of half-steps away from a given note_name.

ATTRIBUTES

scale_note

This is the isobase name of the note (with no octave) that starts the scale.

Default: C

Examples: G#, Eb

scale_name

This is the name of the scale to use.

Please see "SCALES" in Music::Scales for the possibilities.

Default: major

If the scale_name is not recognized, the default is used.

note_format

The format as given by "STYLES" in Music::Note. If set in the constructor, this is used in the get_offset method.

Default: ISO

If the note_format is not recognized, the default is used.

This is used in conjunction with the note_name to determine the Music::Note in the get_offset method.

offset

The integer offset of a new scale position. If set in the constructor, this is used in the get_offset method.

Default: 1

flat

Boolean indicating that we want a sharp resulting note flat instead. This exchanges a sharp note for its enharmonic equivalent flat.

Default: 0

verbose

Show the progress of the get_offset method.

Default: 0

METHODS

new

  $msn = Music::ScaleNote->new;  # Use defaults

  $msn = Music::ScaleNote->new(  # Override defaults
    scale_note  => $scale_start_note,
    scale_name  => $scale_name,
    verbose     => $boolean,
    note_format => $format,
    offset      => $integer,
    flat        => $flat,
  );

Create a new Music::ScaleNote object.

get_offset

  $note = $msn->get_offset( note_name => $note_name );

  $note = $msn->get_offset(  # Override defaults
    note_name   => $note_name,
    note_format => $format,
    offset      => $integer,
    flat        => $flat,
  );

Return a new Music::Note object based on the required note_name, and optional note_format and offset parameters.

If the note_name is not recognized, a default of C is used.

For formats of isobase, ISO and midi, the note_name can be given as a "bare note name" or a note-octave name. But for the midinum format, the note_name must be given as a MIDI note number.

Be aware that if the note_name is given as a "bare note" (with no octave), and the format is ISO, the octave returned will be 4 by default. For format of midinum and the note_name being a letter, a nonsensical result will be returned. This mixing up of format and note name is not how to use this module.

step

  $note = $msn->step( note_name => $note_name );

  $note = $msn->step(
    note_name => $note_name,
    steps     => $halfsteps,
    flat      => $flat,
  );

Return a new Music::Note object based on the required note_name and number of half-steps - either a positive or negative integer.

Default steps: 1

SEE ALSO

The t/01-methods.t file in this distribution.

List::Util

Moo

Music::Note

Music::Scales

Example usage:

https://github.com/ology/Music/blob/master/hilbert-notes

https://github.com/ology/Music/blob/master/lindenmayer-midi

AUTHOR

Gene Boggs <gene@cpan.org>

COPYRIGHT AND LICENSE

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

cpanm Music::ScaleNote

perl -MCPAN -e shell
install Music::ScaleNote