Class: Musa::Scales::ScaleSystem Abstract

Inherits:

Object

Object
Musa::Scales::ScaleSystem

show all

Defined in:: lib/musa-dsl/music/scales.rb

Overview

This class is abstract.

Subclass and implement abstract methods

Abstract base class for musical scale systems.

ScaleSystem defines the foundation of a tuning system, including:

Number of notes per octave
Available intervals
Frequency calculation method
Registered scale kinds (major, minor, etc.)

Subclass Requirements

Subclasses must implement:

ScaleSystem.id: Unique symbol identifier
ScaleSystem.notes_in_octave: Number of notes in an octave
ScaleSystem.part_of_tone_size: Size of smallest pitch unit (for sharps/flats)
ScaleSystem.intervals: Hash of named intervals to semitone offsets
ScaleSystem.frequency_of_pitch: Pitch to frequency conversion

Optionally override:

ScaleSystem.default_a_frequency: Reference A frequency (defaults to 440.0 Hz)

Usage

ScaleSystem is accessed via Scales module, not instantiated directly:

system = Scales[:et12]           # Get system
tuning = system[440.0]           # Get tuning
scale = tuning.major[60]         # Get scale

Direct Known Subclasses

TwelveSemitonesScaleSystem

Class Method Summary collapse

.chromatic_class ⇒ Class<ScaleKind>
Returns the chromatic scale kind class.
.default_a_frequency ⇒ Float
Returns the default A frequency.
.default_tuning ⇒ ScaleSystemTuning
Returns the default tuning (A=440Hz).
.frequency_of_pitch(pitch, root_pitch, a_frequency) ⇒ Float abstract
Calculates frequency for a given pitch.
.get(a_frequency) ⇒ ScaleSystemTuning (also: [])
Creates or retrieves a tuning for this scale system.
.id ⇒ Symbol abstract
Returns the unique identifier for this scale system.
.intervals ⇒ Hash{Symbol => Integer} abstract
Returns available intervals as name-to-offset mapping.
.notes_in_octave ⇒ Integer abstract
Returns the number of notes in one octave.
.offset_of_interval(name) ⇒ Integer
Returns semitone offset for a named interval.
.part_of_tone_size ⇒ Integer abstract
Returns the size of the smallest pitch unit.
.register(scale_kind_class) ⇒ self
Registers a scale kind (major, minor, etc.) with this system.
.scale_kind_class(id) ⇒ Class<ScaleKind>
Retrieves a registered scale kind by ID.
.scale_kind_class?(id) ⇒ Boolean
Checks if a scale kind is registered.
.scale_kind_classes ⇒ Hash{Symbol => Class}
Returns all registered scale kinds.

Instance Method Summary collapse

#==(other) ⇒ Boolean
Compares scale systems for equality.

Class Method Details

.chromatic_class ⇒ `Class<ScaleKind>`

Returns the chromatic scale kind class.

Returns:

(Class<ScaleKind>) —
chromatic ScaleKind subclass

Raises:

(RuntimeError) —
if chromatic scale not defined

# File 'lib/musa-dsl/music/scales.rb', line 447

def self.chromatic_class
  raise "Chromatic scale kind class for [#{self.id}] scale system undefined" if @chromatic_scale_kind_class.nil?

  @chromatic_scale_kind_class
end

.default_a_frequency ⇒ `Float`

Returns the default A frequency.

Examples:

ScaleSystem.default_a_frequency  # => 440.0

Returns:

(Float) —
default A frequency in Hz (440.0 standard concert pitch)



322
323
324

# File 'lib/musa-dsl/music/scales.rb', line 322

def self.default_a_frequency
  440.0
end

.default_tuning ⇒ `ScaleSystemTuning`

Returns the default tuning (A=440Hz).

Examples:

Scales.et12.default_tuning.a_frequency  # => 440.0

Returns:

(ScaleSystemTuning) —
default tuning instance



373
374
375

# File 'lib/musa-dsl/music/scales.rb', line 373

def self.default_tuning
  self[default_a_frequency]
end

.frequency_of_pitch(pitch, root_pitch, a_frequency) ⇒ `Float`

This method is abstract.

Subclass must implement

Calculates frequency for a given pitch.

Converts MIDI pitch numbers to frequencies in Hz. The calculation method depends on the tuning system (equal temperament, just intonation, etc.).

Examples:

Equal temperament

# On a concrete system: this one is abstract and raises.
Scales.et12.frequency_of_pitch(69, 60, 440.0)  # => 440.0
Scales.et12.frequency_of_pitch(60, 60, 440.0).round(2)  # => 261.63

Parameters:

pitch (Numeric) —
MIDI pitch number (60 = middle C, 69 = A440)
root_pitch (Numeric) —
root pitch of scale (for non-equal temperaments)
a_frequency (Numeric) —
reference A frequency in Hz

Returns:

(Float) —
frequency in Hz

Raises:

(RuntimeError) —
if not implemented in subclass



312
313
314

# File 'lib/musa-dsl/music/scales.rb', line 312

def self.frequency_of_pitch(pitch, root_pitch, a_frequency)
  raise 'Method not implemented. Should be implemented in subclass.'
end

.get(a_frequency) ⇒ `ScaleSystemTuning` Also known as: []

Creates or retrieves a tuning for this scale system.

Returns a Musa::Scales::ScaleSystemTuning instance for the specified A frequency. Tunings are cached—repeated calls with same frequency return same instance.

Examples:

Standard pitch

tuning = Scales.et12[440.0]
tuning.a_frequency  # => 440.0

Baroque pitch

Scales.et12[415.0].a_frequency  # => 415.0

Tunings are cached

Scales.et12[442.0].equal?(Scales.et12[442.0])  # => true

Parameters:

a_frequency (Numeric) —
reference A frequency in Hz

Returns:

(ScaleSystemTuning) —
tuning instance

# File 'lib/musa-dsl/music/scales.rb', line 343

def self.get(a_frequency)
  a_frequency = a_frequency.to_f

  @a_tunings ||= {}
  @a_tunings[a_frequency] = ScaleSystemTuning.new self, a_frequency unless @a_tunings.key?(a_frequency)

  @a_tunings[a_frequency]
end

.id ⇒ `Symbol`

This method is abstract.

Subclass must implement

Returns the unique identifier for this scale system.

Examples:

EquallyTempered12ToneScaleSystem.id  # => :et12

Returns:

(Symbol) —
the scale system ID (e.g., :et12)

Raises:

(RuntimeError) —
if not implemented in subclass



240
241
242

# File 'lib/musa-dsl/music/scales.rb', line 240

def self.id
  raise 'Method not implemented. Should be implemented in subclass.'
end

.intervals ⇒ `Hash{Symbol => Integer}`

This method is abstract.

Subclass must implement

Returns available intervals as name-to-offset mapping.

Intervals are named using standard music theory notation:

P (Perfect): P1, P4, P5, P8
M (Major): M2, M3, M6, M7
m (minor): m2, m3, m6, m7
TT: Tritone

Examples:

# On a concrete system: this one is abstract and raises.
Scales.et12.intervals[:M3]   # => 4   (major third)
Scales.et12.intervals[:P5]   # => 7   (perfect fifth)
Scales.et12.intervals[:m7]   # => 10  (minor seventh)

Returns:

(Hash{Symbol => Integer}) —
interval names to semitone offsets

Raises:

(RuntimeError) —
if not implemented in subclass

# File 'lib/musa-dsl/music/scales.rb', line 289

def self.intervals
  # TODO: implementar intérvalos sinónimos (p.ej, m3 = A2)
  # TODO: implementar identificación de intérvalos, teniendo en cuenta no sólo los semitonos sino los grados de separación
  # TODO: implementar inversión de intérvalos
  raise 'Method not implemented. Should be implemented in subclass.'
end

.notes_in_octave ⇒ `Integer`

This method is abstract.

Subclass must implement

Returns the number of notes in one octave.

Examples:

EquallyTempered12ToneScaleSystem.notes_in_octave  # => 12

Returns:

(Integer) —
notes per octave (e.g., 12 for chromatic)

Raises:

(RuntimeError) —
if not implemented in subclass



252
253
254

# File 'lib/musa-dsl/music/scales.rb', line 252

def self.notes_in_octave
  raise 'Method not implemented. Should be implemented in subclass.'
end

.offset_of_interval(name) ⇒ `Integer`

Returns semitone offset for a named interval.

Examples:

Scales.et12.offset_of_interval(:P5)  # => 7

Parameters:

name (Symbol) —
interval name (e.g., :M3, :P5)

Returns:

(Integer) —
semitone offset



363
364
365

# File 'lib/musa-dsl/music/scales.rb', line 363

def self.offset_of_interval(name)
  intervals[name]
end

.part_of_tone_size ⇒ `Integer`

This method is abstract.

Subclass must implement

Returns the size of the smallest pitch unit.

Used for calculating sharp (#) and flat (♭) alterations. In equal temperament, this is 1 semitone.

Examples:

EquallyTempered12ToneScaleSystem.part_of_tone_size  # => 1

Returns:

(Integer) —
smallest unit size

Raises:

(RuntimeError) —
if not implemented in subclass



267
268
269

# File 'lib/musa-dsl/music/scales.rb', line 267

def self.part_of_tone_size
  raise 'Method not implemented. Should be implemented in subclass.'
end

.register(scale_kind_class) ⇒ `self`

Registers a scale kind (major, minor, etc.) with this system.

Examples:

# This is how the library registers its own:
#   EquallyTempered12ToneScaleSystem.register MajorScaleKind
#
# A second registration under the same id is refused, and here it
# mattered twice over: replacing the class does NOT reach the tunings
# that have already built a scale of that kind, because those are
# cached -- so a silent swap gave different answers depending on
# whether anybody had asked before.
Musa::Scales::EquallyTempered12ToneScaleSystem.register(
  Musa::Scales::MajorScaleKind)
# => ArgumentError

Parameters:

scale_kind_class (Class<ScaleKind>) —
ScaleKind subclass to register

Returns:

(self)

Raises:

(ArgumentError) —
if a kind with that id is already registered

# File 'lib/musa-dsl/music/scales.rb', line 396

def self.register(scale_kind_class)
  @scale_kind_classes ||= {}

  # Same reasoning as ChordDefinition.register, with a twist that made it
  # worse: replacing the class here does NOT reach the tunings that have
  # already built a scale of that kind, because those are cached. So a
  # silent replacement gave two different answers depending on whether
  # anyone had asked before.
  if (existing = @scale_kind_classes[scale_kind_class.id])
    raise ArgumentError,
          "scale kind #{scale_kind_class.id.inspect} is already registered " \
          "as #{existing.name}; unregister it first if you mean to replace it"
  end

  @scale_kind_classes[scale_kind_class.id] = scale_kind_class
  if scale_kind_class.chromatic?
    @chromatic_scale_kind_class = scale_kind_class
  end
  self
end

.scale_kind_class(id) ⇒ `Class<ScaleKind>`

Retrieves a registered scale kind by ID.

Parameters:

id (Symbol) —
scale kind identifier

Returns:

(Class<ScaleKind>) —
ScaleKind subclass

Raises:

(KeyError) —
if not found

# File 'lib/musa-dsl/music/scales.rb', line 422

def self.scale_kind_class(id)
  raise KeyError, "Scale kind class [#{id}] not found in scale system [#{self.id}]" unless @scale_kind_classes.key? id

  @scale_kind_classes[id]
end

.scale_kind_class?(id) ⇒ `Boolean`

Checks if a scale kind is registered.

Parameters:

id (Symbol) —
scale kind identifier

Returns:

(Boolean)



432
433
434

# File 'lib/musa-dsl/music/scales.rb', line 432

def self.scale_kind_class?(id)
  @scale_kind_classes.key? id
end

.scale_kind_classes ⇒ `Hash{Symbol => Class}`

Returns all registered scale kinds.

Returns:

(Hash{Symbol => Class}) —
scale kind classes



439
440
441

# File 'lib/musa-dsl/music/scales.rb', line 439

def self.scale_kind_classes
  @scale_kind_classes
end

Instance Method Details

#==(other) ⇒ `Boolean`

Compares scale systems for equality.

Parameters:

other (ScaleSystem)

Returns:

(Boolean)



457
458
459

# File 'lib/musa-dsl/music/scales.rb', line 457

def ==(other)
  self.class == other.class
end

Class: Musa::Scales::ScaleSystem Abstract

Overview

Subclass Requirements

Usage

Direct Known Subclasses

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.chromatic_class ⇒ Class<ScaleKind>

.default_a_frequency ⇒ Float

Examples:

.default_tuning ⇒ ScaleSystemTuning

Examples:

.frequency_of_pitch(pitch, root_pitch, a_frequency) ⇒ Float

Examples:

Equal temperament

.get(a_frequency) ⇒ ScaleSystemTuning Also known as: []

Examples:

Standard pitch

Baroque pitch

Tunings are cached

.id ⇒ Symbol

Examples:

.intervals ⇒ Hash{Symbol => Integer}

Examples:

.notes_in_octave ⇒ Integer

Examples:

.offset_of_interval(name) ⇒ Integer

Examples:

.part_of_tone_size ⇒ Integer

Examples:

.register(scale_kind_class) ⇒ self

Examples:

.scale_kind_class(id) ⇒ Class<ScaleKind>

.scale_kind_class?(id) ⇒ Boolean

.scale_kind_classes ⇒ Hash{Symbol => Class}

Instance Method Details

#==(other) ⇒ Boolean

.chromatic_class ⇒ `Class<ScaleKind>`

.default_a_frequency ⇒ `Float`

.default_tuning ⇒ `ScaleSystemTuning`

.frequency_of_pitch(pitch, root_pitch, a_frequency) ⇒ `Float`

.get(a_frequency) ⇒ `ScaleSystemTuning` Also known as: []

.id ⇒ `Symbol`

.intervals ⇒ `Hash{Symbol => Integer}`

.notes_in_octave ⇒ `Integer`

.offset_of_interval(name) ⇒ `Integer`

.part_of_tone_size ⇒ `Integer`

.register(scale_kind_class) ⇒ `self`

.scale_kind_class(id) ⇒ `Class<ScaleKind>`

.scale_kind_class?(id) ⇒ `Boolean`

.scale_kind_classes ⇒ `Hash{Symbol => Class}`

#==(other) ⇒ `Boolean`