Class: Musa::Sequencer::BaseSequencer::PlayControl Private

Inherits:
EventHandler show all
Defined in:
lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Control object for play operations.

Manages play lifecycle including pause/continue and after callbacks. Extends EventHandler to support custom events and hierarchical control.

Pause/Continue

When paused:

  1. Stores continuation parameters (series state, evaluator, etc.)
  2. Stops processing series
  3. Awaits continue call

When continued:

  1. Restores continuation parameters
  2. Resumes play from stored position

After Callbacks

Executed after play completes, with optional delay in bars.

Examples:

Basic play control

seq = Musa::Sequencer::BaseSequencer.new(4, 24)

series = Musa::Series::S(60, 62, 64, 65, 67)
played_notes = []
after_executed = []

control = seq.play(series) do |note|
  played_notes << { pitch: note, position: seq.position }
end

control.after(2r) { after_executed << seq.position }

seq.run
# Result: played_notes contains all 5 notes
# Result: after_executed contains position 2 bars after play completes

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(parent, on_stop: nil, after_bars: nil, after: nil) ⇒ PlayControl

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates play control with optional callbacks.

Parameters:

  • parent (EventHandler) —

    parent event handler

  • on_stop (Proc, nil) (defaults to: nil) —

    stop callback (fires on any termination)

  • after_bars (Rational, nil) (defaults to: nil) —

    delay for after callback

  • after (Proc, nil) (defaults to: nil) —

    after callback block (fires only on natural termination)



272
273
274
275
276
277
278
279
280
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 272

def initialize(parent, on_stop: nil, after_bars: nil, after: nil)
  super parent

  @do_on_stop = []
  @do_after = []

  @do_on_stop << on_stop if on_stop
  after(after_bars, &after) if after
end

Instance Attribute Details

#do_after ⇒ Array<Hash> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns after callbacks with delays (only on natural termination).

Returns:

  • (Array<Hash>) —

    after callbacks with delays (only on natural termination)



262
263
264
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 262

def do_after
  @do_after
end

#do_on_stop ⇒ Array<Proc> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns callbacks when play stops (any reason, including manual stop).

Returns:

  • (Array<Proc>) —

    callbacks when play stops (any reason, including manual stop)



260
261
262
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 260

def do_on_stop
  @do_on_stop
end

Instance Method Details

#after(bars = nil) { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Registers callback to execute after play completes naturally (series exhausted). Not called on manual stop.

Examples:

Delayed callback

control.after(4r) { puts "4 bars after play ends" }

Parameters:

  • bars (Numeric, nil) (defaults to: nil) —

    delay in bars after completion (default: 0)

Yields:

  • after callback block



357
358
359
360
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 357

def after(bars = nil, &block)
  bars ||= 0
  @do_after << { bars: bars.rationalize, block: block }
end

#continue ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Continues from pause.

Restores paused state and resumes play using stored continuation.



329
330
331
332
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 329

def continue
  super
  @continuation_sequencer&.continuation_play(@continuation_parameters)
end

#on_stop { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Registers callback for when play stops (any reason, including manual stop).

Yields:

  • stop callback block



341
342
343
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 341

def on_stop(&block)
  @do_on_stop << block
end

#pause ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Pauses play and stores continuation state.

Sets paused flag. Continuation must be stored separately via store_continuation.



290
291
292
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 290

def pause
  @paused = true
end

#store_continuation(sequencer:, serie:, neumalang_context:, mode:, decoder:, play_eval:, mode_args:) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Stores state for continue operation.

Saves all parameters needed to resume play from current position. Called automatically by _play when paused.

Parameters:

  • sequencer (BaseSequencer) —

    sequencer instance

  • serie (Series) —

    series being played

  • neumalang_context (Object, nil) —

    neumalang context

  • mode (Symbol, nil) —

    evaluation mode

  • decoder (Object, nil) —

    decoder

  • play_eval (PlayEval) —

    evaluator

  • mode_args (Hash) —

    mode arguments



310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb', line 310

def store_continuation(sequencer:, serie:, neumalang_context:, mode:, decoder:, play_eval:, mode_args:)
  @continuation_sequencer = sequencer
  @continuation_parameters = {
    serie: serie,
    control: self,
    neumalang_context: neumalang_context,
    mode: mode,
    decoder: decoder,
    play_eval: play_eval,
    mode_args: mode_args }
end