/ 
Music-ScaleNote-0.0905
/ Music::ScaleNote

NAME

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

VERSION

version 0.0905

SYNOPSIS

use Music::ScaleNote;

my $msn = Music::ScaleNote->new(
  scale_note  => 'C',
  scale_name  => 'major',
  note_format => 'isobase',
);
my $note = $msn->get_offset; # using defaults
print $note->format('ISO'), "\n"; # D4

$msn = Music::ScaleNote->new( scale_note => 60 );
$note = $msn->get_offset;
print $note->format('midinum'), "\n"; # 62

$note = $msn->get_offset(
  note_name => $note->format('midinum'),
  offset    => -1,
);
print $note->format('midinum'), "\n"; # 60

$note = $msn->get_offset(
  note_name => $note->format('midinum'),
  offset    => -2,
);
print $note->format('midinum'), "\n"; # 57

$note = $msn->step(
  note_name   => 'Eb3',
  note_format => 'ISO',
  steps       => -2,
  flat        => 1,
);
print $note->format('ISO'), "\n"; # Db3

DESCRIPTION

A Music::ScaleNote object manipulates the position of a note in a scale. Its methods return a Music::Note object.

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: D, G#, Eb

scale_name

This is the name of the scale to use.

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

Default: major

note_format

This is used to tell the module what the type of scale_note is.

Please see the formats in "STYLES" in Music::Note. This is used in the get_offset() method.

Default: midinum

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 only flat notes, not sharps, if the note_format is set to anything other than midinum.

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,
  note_format => $format,
  offset      => $integer,
  flat        => $flat,
  verbose     => $boolean,
);

Create a new Music::ScaleNote object.

get_offset

$note = $msn->get_offset;
$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 optional note_name, note_format, and offset parameters.

If the note_name is not recognized, a default of 60 (middle-C) is used.

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 note_name and number of half-steps - either a positive or negative integer.

Default step: 1

SEE ALSO

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

List::SomeUtils

MIDI::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.boggs@gmail.com>

COPYRIGHT AND LICENSE

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