vizcore 1.1.0 → 1.2.0

data/lib/vizcore/dsl/mapping_resolver.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../deep_copy"
 require_relative "../shape"
 
 module Vizcore
@@ -10,21 +11,29 @@ module Vizcore
         @mapping_state = {}
       end
 
+      # Clear stateful transform memory such as smoothing, hold, decay, and hysteresis.
+      #
+      # @return [void]
+      def reset!
+        @mapping_state.clear
+      end
+
       # @param scene_layers [Array<Hash>]
       # @param audio [Hash]
       # @return [Array<Hash>] normalized layer payloads with resolved params
-      def resolve_layers(scene_layers:, audio:, time: 0.0, frame: 0, resolution: [1280, 720], globals: {}, custom_shape_overrides: {})
+      def resolve_layers(scene_layers:, audio:, time: 0.0, frame: 0, resolution: [1280, 720], globals: {}, custom_shape_overrides: {}, layer_param_overrides: {})
         normalize_scene_layers(scene_layers).map do |layer|
-          resolve_layer(layer, audio, time: time, frame: frame, resolution: resolution, globals: globals, custom_shape_overrides: custom_shape_overrides)
+          resolve_layer(layer, audio, time: time, frame: frame, resolution: resolution, globals: globals, custom_shape_overrides: custom_shape_overrides, layer_param_overrides: layer_param_overrides)
         end
       end
 
       private
 
-      def resolve_layer(layer, audio, time:, frame:, resolution:, globals:, custom_shape_overrides:)
+      def resolve_layer(layer, audio, time:, frame:, resolution:, globals:, custom_shape_overrides:, layer_param_overrides:)
         params = deep_dup(layer[:params] || {})
         apply_custom_shape_overrides!(params, layer_name: layer[:name], custom_shape_overrides: custom_shape_overrides)
-        merge_resolved_mappings!(params, resolve_mappings(layer[:mappings], audio, layer_name: layer[:name]))
+        merge_resolved_mappings!(params, resolve_mappings(layer[:mappings], audio, globals: globals, layer_name: layer[:name], time: time, frame: frame))
+        apply_layer_param_overrides!(params, layer_name: layer[:name], layer_param_overrides: layer_param_overrides)
         expand_dynamic_custom_shapes!(params, layer: layer, audio: audio, time: time, frame: frame, resolution: resolution, globals: globals)
 
         output = {
@@ -39,14 +48,22 @@ module Vizcore
         output
       end
 
-      def resolve_mappings(mappings, audio, layer_name:)
+      def resolve_mappings(mappings, audio, globals:, layer_name:, time:, frame:)
         Array(mappings).each_with_object({}) do |mapping, resolved|
           source = mapping[:source]
           target = mapping[:target]
           next unless source && target
 
-          value = resolve_source_value(source, audio)
-          value = apply_transform(value, mapping[:transform], state_key: [layer_name, target, source])
+          state_key = [layer_name, target, source]
+          value = resolve_source_value(
+            source,
+            audio,
+            globals: globals,
+            time: time,
+            state_key: state_key,
+            frame: frame
+          )
+          value = apply_transform(value, mapping[:transform], state_key: state_key, frame: frame)
           resolved[target.to_s] = value unless value.nil?
         end
       end
@@ -134,6 +151,18 @@ module Vizcore
         {}
       end
 
+      def apply_layer_param_overrides!(params, layer_name:, layer_param_overrides:)
+        layer_overrides = custom_shape_layer_overrides(layer_param_overrides, layer_name)
+        layer_overrides.each do |target, value|
+          target_name = target.to_s
+          if target_name.include?(".")
+            assign_nested_param(params, target_name.split("."), value)
+          else
+            params[target_name.to_sym] = value
+          end
+        end
+      end
+
       def apply_custom_shape_attributes!(primitive, descriptor)
         style = Hash(descriptor[:style] || {})
         style.each do |key, value|
@@ -230,12 +259,18 @@ module Vizcore
         raise ArgumentError, "param #{name} must be numeric"
       end
 
-      def resolve_source_value(source, audio)
+      def resolve_source_value(source, audio, globals: {}, time: 0.0, state_key: nil, frame: 0)
+        return 0.0 unless source
+
         case source[:kind]&.to_sym
         when :amplitude
           audio[:amplitude]
+        when :peak
+          audio[:peak]
         when :frequency_band
           audio.dig(:bands, source[:band]&.to_sym)
+        when :frequency_band_peak
+          audio.dig(:band_peaks, source[:band]&.to_sym)
         when :fft_spectrum
           audio[:fft]
         when :onset
@@ -250,13 +285,252 @@ module Vizcore
           audio[:beat_pulse]
         when :beat_count
           audio[:beat_count]
+        when :beat_phase
+          audio[:beat_phase]
+        when :beat_2
+          audio[:beat_2]
+        when :beat_4
+          audio[:beat_4]
+        when :beat_8
+          audio[:beat_8]
+        when :beat_triplet, :triplet
+          audio[:beat_triplet]
+        when :bar_phase
+          audio[:bar_phase]
+        when :bar_count
+          audio[:bar_count]
+        when :phrase_count
+          audio[:phrase_count]
         when :bpm
           audio[:bpm]
+        when :bpm_confidence
+          audio[:bpm_confidence]
+        when :spectral_centroid
+          audio[:spectral_centroid]
+        when :spectral_rolloff
+          audio[:spectral_rolloff]
+        when :spectral_flatness
+          audio[:spectral_flatness]
+        when :spectral_flux
+          audio[:spectral_flux]
+        when :zero_crossing_rate
+          audio[:zero_crossing_rate]
+        when :global
+          resolve_global(source, globals)
+        when :lfo
+          resolve_lfo(source, time)
+        when :adsr, :envelope
+          resolve_envelope(source, audio, globals: globals, time: time, state_key: state_key, frame: frame)
         else
           nil
         end
       end
 
+      def resolve_envelope(source, audio, globals: {}, time: 0.0, state_key:, frame:)
+        state = envelope_state(state_key)
+        params = envelope_params(source)
+        nested = source[:source] || :kick
+        normalized_nested = normalize_source_descriptor(nested)
+        trigger_value = resolve_nested_source_value(normalized_nested, audio, globals: globals, time: time)
+        trigger = trigger_numeric(trigger_value)
+
+        now = normalized_time(time)
+        state[:time] = now
+        state[:last_frame] = frame
+        state[:gate] = trigger > params[:threshold]
+        state[:note_on] = state[:gate]
+
+        peak = normalize_envelope_peak(params.fetch(:peak)) * trigger
+        if state[:gate]
+          if state[:phase] == :idle || state[:phase] == :release
+            state[:phase] = :attack
+            state[:phase_started_at] = now
+            state[:phase_start_value] = state[:value]
+            state[:peak] = peak
+          else
+            state[:peak] = [state[:peak], peak].max
+          end
+        end
+
+        state[:value], state[:phase] = next_envelope_step(
+          state,
+          params: params,
+          now: now
+        )
+        state[:value]
+      rescue StandardError
+        0.0
+      ensure
+        @mapping_state[state_key] = state if state_key
+      end
+
+      def resolve_nested_source_value(source, audio, globals:, time:)
+        return resolve_source_value({ kind: :amplitude }, audio, globals: globals, time: time) if source.nil?
+
+        nested_kind = source[:kind]&.to_sym
+        return 0.0 if nested_kind == :adsr || nested_kind == :envelope
+
+        resolve_source_value(source, audio, globals: globals, time: time)
+      rescue StandardError
+        0.0
+      end
+
+      def normalize_source_descriptor(source)
+        return source if source.is_a?(Hash) && source[:kind]
+
+        { kind: source.to_sym }
+      rescue StandardError
+        nil
+      end
+
+      def resolve_lfo(source, time)
+        rate = Float(source[:rate] || 1.0)
+        phase = Float(source[:phase] || 0.0)
+        position = (Float(time) * rate + phase) % 1.0
+        case source[:wave]&.to_sym
+        when :triangle
+          1.0 - ((position * 2.0) - 1.0).abs
+        when :saw
+          position
+        when :square
+          position < 0.5 ? 1.0 : 0.0
+        else
+          (Math.sin(position * Math::PI * 2.0) + 1.0) * 0.5
+        end
+      rescue ArgumentError, TypeError
+        0.0
+      end
+
+      def resolve_global(source, globals)
+        name = source[:name]&.to_sym
+        return nil unless name
+
+        values = Hash(globals || {})
+        values[name] || values[name.to_s]
+      rescue StandardError
+        nil
+      end
+
+      def envelope_state(state_key)
+        return {} unless state_key
+
+        @mapping_state[state_key] ||= {
+          phase: :idle,
+          value: 0.0,
+          peak: 0.0,
+          phase_started_at: 0.0,
+          phase_start_value: 0.0,
+          time: 0.0,
+          note_on: false,
+          gate: false
+        }
+      end
+
+      def envelope_params(source)
+        {
+          attack: Float(source[:attack] || 0.02),
+          decay: Float(source[:decay] || 0.08),
+          sustain: Float(source[:sustain] || 0.7).clamp(0.0, 1.0),
+          release: Float(source[:release] || 0.16),
+          threshold: Float(source[:threshold] || 0.0),
+          peak: Float(source[:peak] || 1.0)
+        }
+      rescue StandardError
+        { attack: 0.02, decay: 0.08, sustain: 0.7, release: 0.16, threshold: 0.0, peak: 1.0 }
+      end
+
+      def normalized_time(value)
+        numeric = Float(value)
+        numeric.nan? ? 0.0 : numeric
+      rescue StandardError
+        0.0
+      end
+
+      def normalize_envelope_peak(value)
+        value = Float(value)
+        value.nan? ? 1.0 : value
+      rescue StandardError
+        1.0
+      end
+
+      def next_envelope_step(state, params:, now:)
+        phase = state[:phase] || :idle
+        if phase == :attack
+          return [state[:peak], :sustain] if params[:attack] <= 0.0
+
+          elapsed = now - state[:phase_started_at]
+          if elapsed >= params[:attack]
+            state[:phase_started_at] = now
+            state[:phase_start_value] = state[:peak]
+            return [state[:peak], :decay]
+          end
+
+          ratio = [elapsed / params[:attack], 1.0].min
+          value = state[:phase_start_value] + (state[:peak] - state[:phase_start_value]) * ratio
+          return [value, :attack]
+        end
+
+        if phase == :decay
+          return [state[:peak] * params[:sustain], :sustain] if params[:decay] <= 0.0
+
+          elapsed = now - state[:phase_started_at]
+          target = state[:peak] * params[:sustain]
+          if elapsed >= params[:decay]
+            state[:phase_started_at] = now
+            state[:phase_start_value] = target
+            return [target, :sustain]
+          end
+
+          ratio = [elapsed / params[:decay], 1.0].min
+          value = state[:phase_start_value] + (target - state[:phase_start_value]) * ratio
+          return [value, :decay]
+        end
+
+        if phase == :sustain
+          return state[:phase_start_value], :sustain if state[:gate]
+
+          state[:phase] = :release
+          state[:phase_started_at] = now
+          state[:phase_start_value] = state[:value]
+          return [state[:value], :release]
+        end
+
+        if phase == :release
+          return [0.0, :idle] if params[:release] <= 0.0
+
+          elapsed = now - state[:phase_started_at]
+          if elapsed >= params[:release]
+            state[:phase_started_at] = now
+            state[:phase_start_value] = 0.0
+            return [0.0, :idle]
+          end
+
+          ratio = [elapsed / params[:release], 1.0].min
+          value = state[:phase_start_value] * (1.0 - ratio)
+          return [value, :release]
+        end
+
+        if phase == :idle
+          return [0.0, :idle] unless state[:gate] && params[:attack] > 0.0
+
+          state[:phase_started_at] = now
+          state[:phase_start_value] = 0.0
+          return [0.0, :attack]
+        end
+
+        [0.0, :idle]
+      end
+
+      def trigger_numeric(value)
+        return 0.0 if value == false || value == 0
+        return 1.0 if value == true
+        return 0.0 if value.nil?
+
+        Float(value)
+      rescue StandardError
+        0.0
+      end
+
       def resolve_onset(source, audio)
         band = source[:band]&.to_sym
         return audio[:onset] unless band
@@ -264,15 +538,18 @@ module Vizcore
         audio.dig(:onsets, band)
       end
 
-      def apply_transform(value, transform, state_key:)
+      def apply_transform(value, transform, state_key:, frame:)
         return value if transform.nil? || transform.empty?
         return transform_array(value, transform) if value.is_a?(Array)
         return nil if value.is_a?(Hash) || value.nil?
 
-        transformed = transform_scalar(value, transform)
+        transformed = transform_scalar(value, transform, state_key: state_key)
         return nil if transformed.nil?
 
-        apply_smoothing(transformed, transform, state_key)
+        transformed = apply_trigger_mode(transformed, transform, state_key: state_key) if transform[:as] == :trigger
+        transformed = apply_event_shaping(transformed, transform, state_key: state_key, frame: frame)
+        return apply_smoothing(transformed, transform, state_key) unless transform[:as] == :trigger
+        transformed
       end
 
       def transform_array(value, transform)
@@ -281,11 +558,12 @@ module Vizcore
         end
       end
 
-      def transform_scalar(value, transform, fallback: nil)
+      def transform_scalar(value, transform, fallback: nil, state_key: nil)
         numeric = numeric_value(value, fallback: fallback)
         return nil if numeric.nil?
 
         numeric = 0.0 if transform.key?(:deadzone) && numeric.abs < Float(transform[:deadzone])
+        numeric = apply_threshold(numeric, transform, state_key: state_key)
         numeric *= Float(transform[:gain]) if transform.key?(:gain)
         numeric = apply_curve(numeric, transform[:curve]) if transform[:curve]
         numeric = [numeric, Float(transform[:min])].max if transform.key?(:min)
@@ -293,6 +571,20 @@ module Vizcore
         numeric
       end
 
+      def apply_threshold(value, transform, state_key:)
+        return value unless transform.key?(:threshold) || transform.key?(:hysteresis)
+
+        threshold = Float(transform.fetch(:threshold, 0.5))
+        hysteresis = Float(transform.fetch(:hysteresis, 0.0))
+        return value >= threshold ? value : 0.0 if hysteresis <= 0.0 || state_key.nil?
+
+        key = [:hysteresis, state_key]
+        active = !!@mapping_state[key]
+        active = value >= (active ? threshold - hysteresis : threshold)
+        @mapping_state[key] = active
+        active ? value : 0.0
+      end
+
       def numeric_value(value, fallback:)
         return value ? 1.0 : 0.0 if value == true || value == false
 
@@ -312,12 +604,111 @@ module Vizcore
         when :ease_out
           clamped = [[value, 0.0].max, 1.0].min
           1.0 - ((1.0 - clamped) * (1.0 - clamped))
+        when :ease_in
+          clamped = [[value, 0.0].max, 1.0].min
+          clamped * clamped
+        when :ease_in_out
+          clamped = [[value, 0.0].max, 1.0].min
+          clamped < 0.5 ? 2.0 * clamped * clamped : 1.0 - ((-2.0 * clamped + 2.0)**2 / 2.0)
+        when :smoothstep
+          clamped = [[value, 0.0].max, 1.0].min
+          clamped * clamped * (3.0 - 2.0 * clamped)
+        when :exp
+          clamped = [[value, 0.0].max, 1.0].min
+          ((Math.exp(clamped) - 1.0) / (Math::E - 1.0)).clamp(0.0, 1.0)
+        when :log
+          clamped = [[value, 0.0].max, 1.0].min
+          Math.log1p(clamped * (Math::E - 1.0))
+        when :step
+          value >= 0.5 ? 1.0 : 0.0
         end
       end
 
+      def apply_trigger_mode(value, _transform, state_key:)
+        key = [:trigger, state_key]
+        active = value.to_f > 0.0
+        previous = !!@mapping_state[key]
+        @mapping_state[key] = active
+        (active && !previous) ? 1.0 : 0.0
+      end
+
+      def apply_event_shaping(value, transform, state_key:, frame:)
+        shaped = value
+        shaped = apply_cooldown(shaped, transform, state_key: state_key, frame: frame) if transform.key?(:cooldown)
+        shaped = apply_one_shot(shaped, transform, state_key: state_key) if transform[:one_shot]
+        shaped = apply_hold(shaped, transform, state_key: state_key, frame: frame) if transform.key?(:hold)
+        shaped = apply_decay(shaped, transform, state_key: state_key) if transform.key?(:decay)
+        shaped
+      end
+
+      def apply_cooldown(value, transform, state_key:, frame:)
+        cooldown_frames = (Float(transform[:cooldown]) * 60.0).ceil
+        return value unless cooldown_frames.positive?
+
+        key = [:cooldown, state_key]
+        state = @mapping_state[key] || { until_frame: 0 }
+        current_frame = Integer(frame)
+        return value unless value.to_f > 0.0
+
+        if current_frame >= state[:until_frame]
+          state[:until_frame] = current_frame + cooldown_frames
+          @mapping_state[key] = state
+          value
+        else
+          0.0
+        end
+      rescue StandardError
+        value
+      end
+
+      def apply_one_shot(value, _transform, state_key:)
+        key = [:one_shot, state_key]
+
+        active = value.to_f > 0.0
+        return 0.0 unless active
+
+        fired = !!@mapping_state[key]
+        return 0.0 if fired
+
+        @mapping_state[key] = true
+        value
+      rescue StandardError
+        value
+      end
+
+      def apply_hold(value, transform, state_key:, frame:)
+        hold_frames = (Float(transform[:hold]) * 60.0).ceil
+        return value unless hold_frames.positive?
+
+        key = [:hold, state_key]
+        state = @mapping_state[key] || { until_frame: -1, value: 0.0 }
+        current_frame = Integer(frame)
+        if value.to_f.positive?
+          state = { until_frame: current_frame + hold_frames, value: value }
+        elsif current_frame <= state[:until_frame]
+          value = state[:value]
+        end
+        @mapping_state[key] = state
+        value
+      rescue StandardError
+        value
+      end
+
+      def apply_decay(value, transform, state_key:)
+        decay = Float(transform[:decay]).clamp(0.0, 1.0)
+        key = [:decay, state_key]
+        previous = @mapping_state[key].to_f
+        output = [value.to_f, previous * decay].max
+        @mapping_state[key] = output
+        output
+      rescue StandardError
+        value
+      end
+
       def apply_smoothing(value, transform, state_key)
         return value unless transform.key?(:attack) || transform.key?(:release)
 
+        state_key = [:smooth, state_key]
         previous = @mapping_state[state_key]
         if previous.nil?
           @mapping_state[state_key] = value
@@ -335,16 +726,7 @@ module Vizcore
       end
 
       def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, entry), output|
-            output[key] = deep_dup(entry)
-          end
-        when Array
-          value.map { |entry| deep_dup(entry) }
-        else
-          value
-        end
+        Vizcore::DeepCopy.copy(value)
       end
 
       def deep_symbolize(value)

data/lib/vizcore/dsl/mapping_transform_builder.rb

@@ -4,6 +4,8 @@ module Vizcore
   module DSL
     # Collects block-style mapping transform options.
     class MappingTransformBuilder
+      TRIGGER_MODES = %i[continuous trigger].freeze
+
       # @param initial [Hash]
       def initialize(initial = {})
         @values = initial.each_with_object({}) do |(key, value), output|
@@ -53,6 +55,42 @@ module Vizcore
         @values[:deadzone] = value
       end
 
+      # @param value [Numeric]
+      # @return [Numeric]
+      def threshold(value)
+        @values[:threshold] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def hysteresis(value)
+        @values[:hysteresis] = value
+      end
+
+      # @param value [Numeric] hold duration in seconds at the runtime frame cadence
+      # @return [Numeric]
+      def hold(value)
+        @values[:hold] = value
+      end
+
+      # @param value [Numeric] per-frame decay multiplier
+      # @return [Numeric]
+      def decay(value)
+        @values[:decay] = value
+      end
+
+      # @param seconds [Numeric]
+      # @return [Numeric]
+      def cooldown(seconds)
+        @values[:cooldown] = seconds
+      end
+
+      # @param enabled [Boolean, nil]
+      # @return [Boolean]
+      def one_shot(enabled = true)
+        @values[:one_shot] = !!enabled
+      end
+
       # @param attack [Numeric, nil]
       # @param release [Numeric, nil]
       # @return [Hash]
@@ -62,6 +100,18 @@ module Vizcore
         @values
       end
 
+      # @param mode [Symbol, String]
+      # @return [Symbol]
+      def as(mode)
+        normalized = mode.to_sym
+        unless TRIGGER_MODES.include?(normalized)
+          raise ArgumentError, "mapping as must be :continuous or :trigger"
+        end
+
+        @values[:as] = normalized
+        normalized
+      end
+
       # @return [Hash]
       def to_h
         @values.dup