Module: Musa::Datasets::AbsD

Includes:

Abs

Included in:

GDV, PDV, PS, Score

Defined in:

lib/musa-dsl/datasets/e.rb

Overview

Absolute events with duration.

AbsD represents absolute events that have duration - they occupy a time span rather than occurring at a single instant.

What a duration is measured in

A BAR. 1r is one bar, 1/4r is a quarter of a bar, 2r is two bars. That is what the sequencer counts -- position 1 is bar 1, position 2 is bar 2 -- and every duration in the library is a fraction of it.

It is NOT a fraction of a whole note, and that distinction only shows itself outside 4/4, where a bar and a whole note stop being the same length:

• in 4/4, 1/4r lasts a quarter note, and 1r a whole one;
• in 3/4, 1/4r lasts three quarters of a beat, and a quarter note is 1/3r; the bar, 1r, is a dotted half;
• in 6/8, a beat is 1/6r and is written as an eighth.

So "1/4r is a quarter note" is true of 4/4 and of nothing else. It is the meter's coincidence rather than a definition, and the documentation of this library stated it as a rule for a long time.

The only place that needs to know about whole notes is Score::ToMXML, which has to name figures, and it converts there.

Natural Keys

• :duration: Total duration of the event process
• :note_duration: Actual note duration (may differ for staccato, etc.)
• :forward_duration: Time until next event (may be 0 for simultaneous events)

None of the three is required: an event belongs here as soon as it declares ANY of them. :duration and :forward_duration are what make it occupy time, and either one alone is enough -- an impulse (a click, a percussive attack that frees itself) has no sounding length of its own and does have a distance to the next event, and that is a well formed event of the domain.

Duration Types

duration: How long the event process lasts (note playing, dynamics change, etc.)

note_duration: Actual note length. For staccato, this is shorter than duration. Defaults to duration if not specified.

forward_duration: Time to wait before next event. Can be:

• Same as duration (default): next event starts when this one ends
• Less than duration: events overlap
• Zero: next event starts simultaneously
• More than duration: gap/rest before next event

Examples:

Basic duration

event = { pitch: 60, duration: 1.0 }.extend(AbsD)
event.duration          # => 1.0
event.note_duration     # => 1.0 (defaults to duration)
event.forward_duration  # => 1.0 (defaults to duration)

Staccato note

staccato = { pitch: 60, duration: 1.0, note_duration: 0.5 }.extend(AbsD)
staccato.note_duration     # => 0.5 (sounds shorter)
staccato.forward_duration  # => 1.0 (the next event still waits a full beat)

Simultaneous events

chord_note = { pitch: 60, duration: 1.0, forward_duration: 0 }.extend(AbsD)
chord_note.forward_duration  # => 0 (the next event starts at the same time)

An impulse: spacing without a length of its own

click = { forward_duration: 1/4r }.extend(AbsD)
click.forward_duration  # => (1/4)
click.duration          # => nil
click.note_duration     # => nil

# `duration` does not fall back on `forward_duration`, and should not: the
# click does not sound for the whole gap. Nil is the honest answer.

See Also:

• Parent absolute module
• Pitch series with duration
• Pitch/Duration/Velocity
• Grade/Duration/Velocity

Constant Summary

NaturalKeys =

Natural keys including duration variants.

Returns:

• (Array<Symbol>)

(NaturalKeys +
[:duration, # duration of the process (note reproduction, dynamics evolution, etc)
 :note_duration, # duration of the note (a staccato note is effectively shorter than elapsed duration until next note)
 :forward_duration # duration to wait until next event (if 0 means the next event should be executed at the same time than this one)
]).freeze

Class Method Summary

• .is_compatible?(thing) ⇒ Boolean

  Checks if thing can be converted to AbsD.

• .to_AbsD(thing) ⇒ AbsD

  Converts thing to AbsD if possible.

Instance Method Summary

• #duration ⇒ Numeric

  Returns event duration.

• #forward_duration ⇒ Numeric

  Returns forward duration (time until next event).

• #note_duration ⇒ Numeric

  Returns actual note duration.

• #valid? ⇒ Boolean included from E

  Checks if event is valid.

• #validate! ⇒ void included from E

  Validates event, raising if invalid.

Class Method Details

.is_compatible?(thing) ⇒ Boolean

Checks if thing can be converted to AbsD.

Either duration key is enough: what makes an event occupy time is that it declares how long it lasts, or how long until the next one, and it need not declare both.

Examples:

AbsD compatibility check

AbsD.is_compatible?({ duration: 1.0 })          # => true
AbsD.is_compatible?({ forward_duration: 1.0 })  # => true
AbsD.is_compatible?({ pitch: 60 })              # => false

Parameters:

• thing (Object) —

  object to check

Returns:

• (Boolean) —

  true if compatible

# File 'lib/musa-dsl/datasets/e.rb', line 289

def self.is_compatible?(thing)
  thing.is_a?(AbsD) ||
    thing.is_a?(Hash) && (thing.has_key?(:duration) || thing.has_key?(:forward_duration))
end

.to_AbsD(thing) ⇒ AbsD

Converts thing to AbsD if possible.

Examples:

Convert to AbsD

AbsD.to_AbsD({ duration: 1.0 }).is_a?(AbsD)          # => true
AbsD.to_AbsD({ forward_duration: 1.0 }).is_a?(AbsD)  # => true

Parameters:

• thing (Object) —

  object to convert

Returns:

• (AbsD) —

  AbsD dataset

Raises:

• (ArgumentError) —

  if thing cannot be converted

# File 'lib/musa-dsl/datasets/e.rb', line 303

def self.to_AbsD(thing)
  if thing.is_a?(AbsD)
    thing
  elsif thing.is_a?(Hash) && (thing.has_key?(:duration) || thing.has_key?(:forward_duration))
    thing.clone.extend(AbsD)
  else
    raise ArgumentError, "Cannot convert #{thing} to AbsD dataset"
  end
end

Instance Method Details

#duration ⇒ Numeric

Returns event duration.

Examples:

{ pitch: 60, duration: 1.0 }.extend(AbsD).duration  # => 1.0

Returns:

• (Numeric) —

  duration

# File 'lib/musa-dsl/datasets/e.rb', line 272

def duration
  self[:duration]
end

#forward_duration ⇒ Numeric

Returns forward duration (time until next event).

Defaults to :duration if :forward_duration not specified. This is the value play waits on in :wait mode, so it is what advances a serie.

Examples:

{ pitch: 60, duration: 1.0 }.extend(AbsD).forward_duration  # => 1.0

The fallback runs one way only

{ forward_duration: 1/2r }.extend(AbsD).forward_duration  # => (1/2)
{ forward_duration: 1/2r }.extend(AbsD).duration          # => nil

Returns:

• (Numeric) —

  forward duration

# File 'lib/musa-dsl/datasets/e.rb', line 250

def forward_duration
  self[:forward_duration] || self[:duration]
end

#note_duration ⇒ Numeric

Returns actual note duration.

Defaults to :duration if :note_duration not specified.

Examples:

{ pitch: 60, duration: 1.0, note_duration: 0.5 }.extend(AbsD).note_duration  # => 0.5

Returns:

• (Numeric) —

  note duration

# File 'lib/musa-dsl/datasets/e.rb', line 262

def note_duration
  self[:note_duration] || self[:duration]
end

#valid? ⇒ Boolean Originally defined in module E

Checks if event is valid.

Base implementation always returns true. Subclasses should override to implement specific validation logic.

Examples:

event.valid?  # => true

Returns:

• (Boolean) —

  true if valid

#validate! ⇒ void Originally defined in module E

This method returns an undefined value.

Validates event, raising if invalid.

Examples:

event.validate!  # Raises if invalid

Raises:

• (RuntimeError) —

  if event is not valid