scamp_extensions.pitch.scale.Scale

class scamp_extensions.pitch.scale.Scale(scale_type: ScaleType, start_pitch: Real, cycle: bool = True)

Bases: SavesToJSON

Class representing a scale starting on a specific pitch. A Scale combines a ScaleType with a starting pitch, and also an option as to whether the pitch collection should cycle (as pretty much all the standard scales do). To illustrate the difference between a ScaleType and a Scale, “D dorian” would be represented by a Scale, whereas “dorian” would be represented by a ScaleType.

Parameters:

• scale_type – a ScaleType object

• start_pitch – a pitch to treat as the starting note of the scale

• cycle – whether or not this scale cycles. If so, the interval from the first pitch to the last pitch is treated as the cycle size.

Methods

aeolian(start_pitch[, cycle])	Convenience method for creating a aeolian scale with the given start pitch.
blues(start_pitch[, cycle])	Returns a 6-note blues scale starting on the specified pitch.
ceil(pitch)	Returns the nearest note of the scale above or equal to the given pitch.
chromatic([start_pitch, cycle])	Returns a 12-tone equal tempered chromatic scale starting on the specified pitch.
degree_to_pitch(degree)	Given a degree of the scale, returns the pitch that it corresponds to.
diatonic(start_pitch[, modal_shift, cycle])	Returns a diatonic scale starting on the specified pitch, and with the specified modal shift.
dorian(start_pitch[, cycle])	Convenience method for creating a dorian scale with the given start pitch.
floor(pitch)	Returns the nearest note of the scale below or equal to the given pitch.
from_pitches(seed_pitches[, cycle])	Constructs a Scale from a list of seed pitches, given as floating-point MIDI pitch values.
from_scala_file(file_path, start_pitch[, cycle])	Constructs a Scale from a scala file located at the given file path, and a start pitch.
from_start_pitch_and_cent_or_ratio_intervals(...)	Creates a scale from a start pitch and a sequence of intervals (either cents or frequency ratios).
harmonic_minor(start_pitch[, modal_shift, cycle])	Returns a harmonic minor scale starting on the specified pitch, and with the specified modal shift.
ionian(start_pitch[, modal_shift, cycle])	Alias of Scale.diatonic().
locrian(start_pitch[, cycle])	Convenience method for creating a locrian scale with the given start pitch.
lydian(start_pitch[, cycle])	Convenience method for creating a lydian scale with the given start pitch.
major(start_pitch[, modal_shift, cycle])	Alias of Scale.diatonic().
melodic_minor(start_pitch[, modal_shift, cycle])	Returns a melodic minor scale starting on the specified pitch, and with the specified modal shift.
mixolydian(start_pitch[, cycle])	Convenience method for creating a mixolydian scale with the given start pitch.
natural_minor(start_pitch[, cycle])	Alias of Scale.aeolian().
octatonic(start_pitch[, cycle, whole_step_first])	Returns an octatonic scale with the given start pitch.
pentatonic(start_pitch[, modal_shift, cycle])	Returns a pentatonic scale starting on the specified pitch, and with the specified modal shift.
pentatonic_minor(start_pitch[, cycle])	Returns a pentatonic minor scale starting on the specified pitch.
phrygian(start_pitch[, cycle])	Convenience method for creating a phrygian scale with the given start pitch.
pitch_to_degree(pitch)	Given a pitch, returns the scale degree that it corresponds to.
round(pitch)	Rounds the given pitch to the nearest note of the scale.
transpose(half_steps)	Transposes this scale (in place) by the given number of half steps.
transposed(half_steps)	Same as Scale.transpose(), except that it returns a transposed copy, leaving this scale unaltered.
whole_tone(start_pitch[, cycle])	Returns a whole tone scale with the given start pitch.

Inherited Methods

duplicate()	Returns a copy of this object by serializing to and from JSON.
json_dumps()	Dump this object as a JSON string.
json_loads(s)	Load this object from a JSON string.
load_from_json(file_path)	Load this object from a JSON file with the given path.
save_to_json(file_path)	Save this object to a JSON file using the given path.

Attributes

cycle	Whether or not this scale repeats after a full cycle.
start_pitch	The pitch that scale starts from.

property start_pitch: Real

The pitch that scale starts from.

property cycle: bool

Whether or not this scale repeats after a full cycle.

classmethod from_pitches(seed_pitches: Sequence[Real], cycle: bool = True) → Scale

Constructs a Scale from a list of seed pitches, given as floating-point MIDI pitch values. For instance, a C major scale could be constructed by calling Scale.from_pitches([60, 62, 64, 65, 67, 69, 71, 72]). Note that the upper C needs to be specified, since it is not assumed that scales will be octave repeating, and the repeat interval is given by the distance between the first and last seed pitch. Also note that this particular C major scale would place scale degree 0 at middle C, whereas Scale.from_pitches([48, 50, 52, 53, 55, 57, 59, 60]) would place it an octave lower.

Parameters:

• seed_pitches – a list of floating-point MIDI pitch values.

• cycle – Whether or not to cycle the scale, creating multiple “octaves” (or perhaps not octaves if the scale repeats at a different interval.

classmethod from_scala_file(file_path: str, start_pitch: Real, cycle: bool = True) → Scale

Constructs a Scale from a scala file located at the given file path, and a start pitch.

Parameters:

• file_path – path of the scala file to load

• start_pitch – the pitch to define as scale degree 0

• cycle – whether or not this scale is treated as cyclic

classmethod from_start_pitch_and_cent_or_ratio_intervals(start_pitch: Real, intervals, cycle: bool = True) → Scale

Creates a scale from a start pitch and a sequence of intervals (either cents or frequency ratios).

Parameters:

• start_pitch – The pitch to start on

• intervals – a sequence of intervals above the start pitch. These can be either PitchInterval objects or anything that can be interpreted by PitchInterval.parse().

• cycle – whether or not this scale is treated as cyclic. See explanation in Scale.from_pitches() about defining cyclic scales.

degree_to_pitch(degree: Real) → float

Given a degree of the scale, returns the pitch that it corresponds to. Degree 0 corresponds to the start pitch, and negative degrees correspond to notes below the start pitch (for cyclical scales). Fractional degrees are possible and result in pitches interpolated between the scale degrees. The first argument can optionally be a list, tuple, or iterator, in which case this is performed on each element.

Parameters:

degree – a (potentially floating-point) scale degree

pitch_to_degree(pitch: Real) → float

Given a pitch, returns the scale degree that it corresponds to. Pitches that lie in between the notes of the scale will return fractional degrees via interpolation. The first argument can optionally be a list, tuple, or iterator, in which case this is performed on each element.

Parameters:

pitch – a pitch, potentially in between scale degrees

round(pitch: Real) → float

Rounds the given pitch to the nearest note of the scale. The first argument can optionally be a list, tuple, or iterator, in which case this is performed on each element.

floor(pitch: Real) → float

Returns the nearest note of the scale below or equal to the given pitch. The first argument can optionally be a list, tuple, or iterator, in which case this is performed on each element.

ceil(pitch: Real) → float

Returns the nearest note of the scale above or equal to the given pitch. The first argument can optionally be a list, tuple, or iterator, in which case this is performed on each element.

transpose(half_steps: float) → Scale

Transposes this scale (in place) by the given number of half steps.

Parameters:

half_steps – number of half steps to transpose up or down by

Returns:

self, for chaining purposes

transposed(half_steps: float) → Scale

Same as Scale.transpose(), except that it returns a transposed copy, leaving this scale unaltered.

classmethod chromatic(start_pitch: Real = 60, cycle: bool = True) → Scale

Returns a 12-tone equal tempered chromatic scale starting on the specified pitch.

Parameters:

• start_pitch – the pitch this scale starts from (doesn’t affect the scale in this case, but affects where we count scale degrees from).

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod diatonic(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) → Scale

Returns a diatonic scale starting on the specified pitch, and with the specified modal shift.

Parameters:

• start_pitch – the pitch this scale starts from

• modal_shift – how many steps up or down to shift the scale’s interval relationships. 0 is ionian, 1 is dorian, 2 is phrygian, etc. (There are also convenience methods for creating these modal scales.)

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod major(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) → Scale

Alias of Scale.diatonic().

classmethod ionian(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) → Scale

Alias of Scale.diatonic().

classmethod dorian(start_pitch: Real, cycle: bool = True) → Scale

Convenience method for creating a dorian scale with the given start pitch. (Same as Scale.diatonic() with a modal shift of 1.)

classmethod phrygian(start_pitch: Real, cycle: bool = True) → Scale

Convenience method for creating a phrygian scale with the given start pitch. (Same as Scale.diatonic() with a modal shift of 2.)

classmethod lydian(start_pitch: Real, cycle: bool = True) → Scale

Convenience method for creating a lydian scale with the given start pitch. (Same as Scale.diatonic() with a modal shift of 3.)

classmethod mixolydian(start_pitch: Real, cycle: bool = True) → Scale

Convenience method for creating a mixolydian scale with the given start pitch. (Same as Scale.diatonic() with a modal shift of 4.)

classmethod aeolian(start_pitch: Real, cycle: bool = True) → Scale

Convenience method for creating a aeolian scale with the given start pitch. (Same as Scale.diatonic() with a modal shift of 5.)

classmethod natural_minor(start_pitch: Real, cycle: bool = True) → Scale

Alias of Scale.aeolian().

classmethod locrian(start_pitch: Real, cycle: bool = True) → Scale

Convenience method for creating a locrian scale with the given start pitch. (Same as Scale.diatonic() with a modal shift of 6.)

classmethod harmonic_minor(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) → Scale

Returns a harmonic minor scale starting on the specified pitch, and with the specified modal shift.

Parameters:

• start_pitch – the pitch this scale starts from

• modal_shift – How many steps up or down to shift the scale’s interval relationships. To get a regular harmonic minor scale, simply use the default modal shift of 0.

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod melodic_minor(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) → Scale

Returns a melodic minor scale starting on the specified pitch, and with the specified modal shift.

Parameters:

• start_pitch – the pitch this scale starts from

• modal_shift – How many steps up or down to shift the scale’s interval relationships. To get a regular melodic minor scale, simply use the default modal shift of 0. A so-called acoustic scale (major sharp-4, flat-7) can be produced with a modal shift of 4.

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod whole_tone(start_pitch: Real, cycle: bool = True) → Scale

Returns a whole tone scale with the given start pitch.

Parameters:

• start_pitch – the pitch this scale starts from

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod octatonic(start_pitch: Real, cycle: bool = True, whole_step_first: bool = True) → Scale

Returns an octatonic scale with the given start pitch.

Parameters:

• start_pitch – the pitch this scale starts from

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

• whole_step_first – whether this is a whole-half or half-whole octatonic scale.

classmethod pentatonic(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) → Scale

Returns a pentatonic scale starting on the specified pitch, and with the specified modal shift.

Parameters:

• start_pitch – the pitch this scale starts from

• modal_shift – How many steps up or down to shift the scale’s interval relationships. To get a regular harmonic minor scale, simply use the default modal shift of 0.

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod pentatonic_minor(start_pitch: Real, cycle: bool = True) → Scale

Returns a pentatonic minor scale starting on the specified pitch.

Parameters:

• start_pitch – the pitch this scale starts from

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

classmethod blues(start_pitch: Real, cycle: bool = True) → Scale

Returns a 6-note blues scale starting on the specified pitch.

Parameters:

• start_pitch – the pitch this scale starts from

• cycle – whether or not this scale repeats after an octave or is constrained to a single octave.

duplicate() → T

Returns a copy of this object by serializing to and from JSON.

json_dumps() → str

Dump this object as a JSON string. This uses a custom encoder that recognizes and appropriately converts any attributes that are object inheriting from SavesToJSON.

classmethod json_loads(s: str) → T

Load this object from a JSON string. This uses a custom decoder that looks for a “_type” key in any object/dictionary being parsed and converts it to the class specified (assuming it a subclass of SavesToJSON).

Parameters:

s – a string representing this object in JSON format

classmethod load_from_json(file_path: str) → T

Load this object from a JSON file with the given path. This uses a custom decoder that looks for a “_type” key in any object/dictionary being parsed and converts it to the class specified (assuming it a subclass of SavesToJSON).

Parameters:

file_path – path for loading the file

save_to_json(file_path: str) → None

Save this object to a JSON file using the given path. This uses a custom encoder that recognizes and appropriately converts any attributes that are object inheriting from SavesToJSON.

Parameters:

file_path – path for saving the file