vizcore 0.1.0

data/lib/vizcore/dsl/midi_map_executor.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Executes `midi_map` action blocks against incoming MIDI events.
+    class MidiMapExecutor
+      # @param midi_maps [Array<Hash>]
+      # @param scenes [Array<Hash>]
+      # @param globals [Hash]
+      def initialize(midi_maps:, scenes:, globals: {})
+        update(midi_maps: midi_maps, scenes: scenes, globals: globals)
+      end
+
+      # @param midi_maps [Array<Hash>]
+      # @param scenes [Array<Hash>]
+      # @param globals [Hash, nil]
+      # @return [void]
+      def update(midi_maps:, scenes:, globals: nil)
+        @midi_maps = normalize_midi_maps(midi_maps)
+        @scenes = normalize_scenes(scenes)
+        @globals = normalize_globals(globals) unless globals.nil?
+      end
+
+      # @return [Hash] mutable global parameter snapshot
+      def globals
+        @globals.dup
+      end
+
+      # @param event [Vizcore::Audio::MidiInput::Event]
+      # @return [Array<Hash>] runtime actions (`:switch_scene`, `:set_global`)
+      def handle_event(event)
+        @midi_maps.each_with_object([]) do |mapping, actions|
+          next unless mapping_match?(mapping[:trigger], event)
+
+          context = ActionContext.new(scenes: @scenes, globals: @globals)
+          invoke_action_block(context, mapping[:action], event, mapping[:trigger])
+          actions.concat(context.actions)
+        end
+      end
+
+      private
+
+      def normalize_midi_maps(midi_maps)
+        Array(midi_maps).filter_map do |mapping|
+          values = symbolize_hash(mapping)
+          trigger = symbolize_hash(values[:trigger])
+          action = values[:action]
+          next if trigger.empty?
+          next unless action.respond_to?(:call)
+
+          {
+            trigger: trigger,
+            action: action
+          }
+        end
+      end
+
+      def normalize_scenes(scenes)
+        Array(scenes).each_with_object({}) do |scene, output|
+          values = symbolize_hash(scene)
+          name = values[:name]
+          next unless name
+
+          output[name.to_sym] = {
+            name: name.to_sym,
+            layers: Array(values[:layers]).map { |layer| deep_dup(layer) }
+          }
+        end
+      end
+
+      def normalize_globals(globals)
+        symbolize_hash(globals)
+      end
+
+      def mapping_match?(trigger, event)
+        if trigger.key?(:note)
+          event.type == :note_on && event.data1 == trigger[:note].to_i
+        elsif trigger.key?(:cc)
+          event.type == :control_change && event.data1 == trigger[:cc].to_i
+        elsif trigger.key?(:pc)
+          event.type == :program_change && event.data1 == trigger[:pc].to_i
+        else
+          false
+        end
+      end
+
+      def invoke_action_block(context, action, event, trigger)
+        value = event_value(event, trigger)
+        if action.arity.zero?
+          context.instance_exec(&action)
+        else
+          context.instance_exec(value, &action)
+        end
+      end
+
+      def event_value(event, trigger)
+        if trigger.key?(:note) || trigger.key?(:cc)
+          event.data2.to_i.clamp(0, 127)
+        elsif trigger.key?(:pc)
+          event.data1.to_i.clamp(0, 127)
+        else
+          0
+        end
+      end
+
+      def symbolize_hash(value)
+        Hash(value).each_with_object({}) do |(key, entry), output|
+          output[key.to_sym] = entry
+        end
+      rescue StandardError
+        {}
+      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
+      end
+
+      # Runtime DSL context used while executing one `midi_map` action block.
+      # @api private
+      class ActionContext
+        # Collected runtime actions emitted by DSL calls.
+        attr_reader :actions
+
+        # @param scenes [Hash]
+        # @param globals [Hash]
+        def initialize(scenes:, globals:)
+          @scenes = scenes
+          @globals = globals
+          @actions = []
+        end
+
+        # @param name [Symbol, String]
+        # @param effect [Hash, nil]
+        # @return [void]
+        def switch_scene(name, effect: nil)
+          scene = @scenes[name.to_sym]
+          return unless scene
+
+          @actions << {
+            type: :switch_scene,
+            scene: {
+              name: scene[:name],
+              layers: scene[:layers].map { |layer| deep_dup(layer) }
+            },
+            effect: deep_dup(effect)
+          }
+        end
+
+        # @param key [Symbol, String]
+        # @param value [Object]
+        # @return [void]
+        def set(key, value)
+          symbol_key = key.to_sym
+          @globals[symbol_key] = value
+          @actions << {
+            type: :set_global,
+            key: symbol_key,
+            value: value
+          }
+        end
+
+        private
+
+        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
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/scene_builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "layer_builder"
+
+module Vizcore
+  module DSL
+    # Collects layer definitions inside a single scene block.
+    class SceneBuilder
+      # @param name [Symbol, String] scene identifier
+      def initialize(name:)
+        @name = name.to_sym
+        @layers = []
+      end
+
+      # Evaluate a scene block.
+      #
+      # @yield Layer definitions
+      # @return [Vizcore::DSL::SceneBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        self
+      end
+
+      # Define one layer in this scene.
+      #
+      # @param name [Symbol, String] layer identifier
+      # @yield Layer definition block
+      # @return [void]
+      def layer(name, &block)
+        builder = LayerBuilder.new(name: name)
+        builder.evaluate(&block)
+        @layers << builder.to_h
+      end
+
+      # @return [Hash] serialized scene payload
+      def to_h
+        {
+          name: @name,
+          layers: @layers.map { |layer| layer.dup }
+        }
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/shader_source_resolver.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Vizcore
+  module DSL
+    # Replaces layer `glsl` paths with inlined shader source text.
+    class ShaderSourceResolver
+      # @param definition [Hash] DSL definition payload
+      # @param scene_file [String, Pathname] source scene file
+      # @raise [ArgumentError] when a referenced GLSL file is missing
+      # @return [Hash] deep-copied definition with `:glsl_source` entries
+      def resolve(definition:, scene_file:)
+        scene_path = Pathname.new(scene_file.to_s).expand_path
+        base_dir = scene_path.dirname
+        output = deep_dup(definition)
+        output[:scenes] = Array(output[:scenes]).map do |scene|
+          scene_hash = symbolize_hash(scene)
+          scene_hash[:layers] = Array(scene_hash[:layers]).map do |layer|
+            resolve_layer(layer, base_dir: base_dir)
+          end
+          scene_hash
+        end
+        output
+      end
+
+      private
+
+      def resolve_layer(layer, base_dir:)
+        layer_hash = symbolize_hash(layer)
+        shader_path = layer_hash[:glsl]
+        return layer_hash unless shader_path
+
+        full_path = resolve_path(base_dir: base_dir, shader_path: shader_path)
+        raise ArgumentError, "GLSL file not found: #{shader_path}" unless full_path.file?
+
+        layer_hash[:glsl] = shader_path.to_s
+        layer_hash[:glsl_source] = full_path.read
+        layer_hash
+      end
+
+      def resolve_path(base_dir:, shader_path:)
+        path = Pathname.new(shader_path.to_s)
+        return path.expand_path if path.absolute?
+
+        base_dir.join(path).expand_path
+      end
+
+      def symbolize_hash(value)
+        Hash(value).each_with_object({}) do |(key, entry), output|
+          output[key.to_sym] = entry
+        end
+      rescue StandardError
+        {}
+      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
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/transition_controller.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Evaluates transition rules and returns scene-change payloads.
+    class TransitionController
+      # @param scenes [Array<Hash>]
+      # @param transitions [Array<Hash>]
+      def initialize(scenes:, transitions:)
+        update(scenes: scenes, transitions: transitions)
+      end
+
+      # @param scenes [Array<Hash>]
+      # @param transitions [Array<Hash>]
+      # @return [void]
+      def update(scenes:, transitions:)
+        @scenes_by_name = normalize_scenes(scenes)
+        @transitions = normalize_transitions(transitions)
+      end
+
+      # @param scene_name [String, Symbol]
+      # @param audio [Hash]
+      # @param frame_count [Integer]
+      # @return [Hash, nil] transition payload when condition matches
+      def next_transition(scene_name:, audio:, frame_count: 0)
+        current = scene_name.to_sym
+        transition = @transitions.find do |entry|
+          entry[:from] == current && trigger_match?(entry[:trigger], audio, frame_count)
+        end
+        return nil unless transition
+
+        target_scene = @scenes_by_name[transition[:to]]
+        return nil unless target_scene
+
+        {
+          from: transition[:from],
+          to: transition[:to],
+          effect: transition[:effect],
+          scene: deep_dup(target_scene)
+        }
+      end
+
+      private
+
+      def normalize_scenes(scenes)
+        Array(scenes).each_with_object({}) do |scene, output|
+          values = symbolize_hash(scene)
+          name = values[:name]
+          next unless name
+
+          output[name.to_sym] = {
+            name: name.to_sym,
+            layers: Array(values[:layers]).map { |layer| deep_dup(layer) }
+          }
+        end
+      end
+
+      def normalize_transitions(transitions)
+        Array(transitions).filter_map do |transition|
+          values = symbolize_hash(transition)
+          from = values[:from]
+          to = values[:to]
+          next unless from && to
+
+          {
+            from: from.to_sym,
+            to: to.to_sym,
+            trigger: values[:trigger],
+            effect: deep_dup(values[:effect])
+          }
+        end
+      end
+
+      def trigger_match?(trigger, audio, frame_count)
+        return false unless trigger.respond_to?(:call)
+
+        TriggerContext.new(audio, frame_count: frame_count).instance_exec(&trigger)
+      rescue StandardError
+        false
+      end
+
+      def symbolize_hash(value)
+        Hash(value).each_with_object({}) do |(key, entry), output|
+          output[key.to_sym] = entry
+        end
+      rescue StandardError
+        {}
+      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
+      end
+
+      # Runtime DSL context exposed to transition trigger blocks.
+      # @api private
+      class TriggerContext
+        # @param audio [Hash]
+        # @param frame_count [Integer]
+        def initialize(audio, frame_count:)
+          @audio = symbolize_hash(audio)
+          @bands = symbolize_hash(@audio[:bands])
+          @frame_count = Integer(frame_count)
+        rescue StandardError
+          @frame_count = 0
+        end
+
+        # @return [Float]
+        def amplitude
+          @audio[:amplitude].to_f
+        end
+
+        # @param name [Symbol, String]
+        # @return [Float]
+        def frequency_band(name)
+          @bands[name.to_sym].to_f
+        end
+
+        # @return [Array<Float>]
+        def fft_spectrum
+          Array(@audio[:fft])
+        end
+
+        # @return [Boolean]
+        def beat?
+          !!@audio[:beat]
+        end
+
+        # @return [Integer]
+        def beat_count
+          Integer(@audio[:beat_count] || 0)
+        rescue StandardError
+          0
+        end
+
+        # @return [Float]
+        def bpm
+          @audio[:bpm].to_f
+        end
+
+        # @return [Integer]
+        def frame_count
+          @frame_count
+        end
+
+        private
+
+        def symbolize_hash(value)
+          Hash(value).each_with_object({}) do |(key, entry), output|
+            output[key.to_sym] = entry
+          end
+        rescue StandardError
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/dsl.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # DSL builders and runtime helpers.
+  module DSL
+  end
+end
+
+require_relative "dsl/layer_builder"
+require_relative "dsl/file_watcher"
+require_relative "dsl/mapping_resolver"
+require_relative "dsl/midi_map_executor"
+require_relative "dsl/scene_builder"
+require_relative "dsl/shader_source_resolver"
+require_relative "dsl/transition_controller"
+require_relative "dsl/engine"

data/lib/vizcore/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Invalid or missing user-provided configuration.
+  class ConfigurationError < ArgumentError; end
+
+  # Scene DSL could not be loaded or resolved.
+  class SceneLoadError < ArgumentError; end
+
+  # Audio source initialization/processing failure.
+  class AudioSourceError < StandardError; end
+
+  # Frame generation failed in the render pipeline.
+  class FrameBuildError < StandardError; end
+
+  # Small helper for concise contextual error messages.
+  module ErrorFormatting
+    module_function
+
+    # @param error [Exception]
+    # @param context [String]
+    # @return [String]
+    def summarize(error, context:)
+      "#{context}: #{error.class}: #{error.message}"
+    end
+  end
+end

data/lib/vizcore/renderer/frame_scheduler.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Renderer
+    # Fixed-interval scheduler used by the frame broadcast loop.
+    class FrameScheduler
+      # Default frame rate used by renderer loops.
+      DEFAULT_FRAME_RATE = 60.0
+
+      # @param frame_rate [Float]
+      # @param monotonic_clock [#call, nil]
+      # @param sleeper [#call, nil]
+      # @param error_handler [#call, nil]
+      # @yieldparam elapsed [Float]
+      def initialize(frame_rate: DEFAULT_FRAME_RATE, monotonic_clock: nil, sleeper: nil, error_handler: nil, &on_tick)
+        @frame_rate = Float(frame_rate)
+        raise ArgumentError, "frame_rate must be positive" unless @frame_rate.positive?
+
+        @frame_interval = 1.0 / @frame_rate
+        @monotonic_clock = monotonic_clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+        @error_handler = error_handler || ->(error) { raise error }
+        @on_tick = on_tick
+        @running = false
+        @thread = nil
+      end
+
+      # @return [void]
+      def start
+        return if running?
+
+        @running = true
+        started_at = @monotonic_clock.call
+        @thread = Thread.new { run_loop(started_at) }
+      end
+
+      # @param timeout [Float]
+      # @return [void]
+      def stop(timeout: 1.0)
+        return unless running?
+
+        @running = false
+        thread = @thread
+        @thread = nil
+        return unless thread
+        return if thread == Thread.current
+
+        thread.join(timeout)
+      end
+
+      # @return [Boolean]
+      def running?
+        @running
+      end
+
+      private
+
+      def run_loop(started_at)
+        while running?
+          begin
+            loop_started = @monotonic_clock.call
+            elapsed = loop_started - started_at
+            @on_tick&.call(elapsed)
+
+            duration = @monotonic_clock.call - loop_started
+            sleep_time = @frame_interval - duration
+            @sleeper.call(sleep_time) if sleep_time.positive?
+          rescue StandardError => e
+            @error_handler.call(e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/renderer/scene_serializer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Renderer
+    # Serializes analysis and scene state into transport payloads.
+    class SceneSerializer
+      # @param timestamp [Numeric]
+      # @param audio [Hash]
+      # @param scene_name [String, Symbol]
+      # @param scene_layers [Array<Hash>]
+      # @param transition [Hash, nil]
+      # @return [Hash]
+      def audio_frame(timestamp:, audio:, scene_name:, scene_layers:, transition: nil)
+        {
+          timestamp: Float(timestamp),
+          audio: serialize_audio(audio),
+          scene: serialize_scene(scene_name, scene_layers),
+          transition: transition
+        }
+      end
+
+      private
+
+      def serialize_audio(audio)
+        bands = symbolize_hash(audio[:bands])
+
+        {
+          amplitude: round_float(audio[:amplitude]),
+          bands: bands.transform_values { |value| round_float(value) },
+          fft: Array(audio[:fft]).map { |value| round_float(value) },
+          beat: !!audio[:beat],
+          beat_count: Integer(audio[:beat_count] || 0),
+          bpm: audio[:bpm]
+        }
+      end
+
+      def serialize_scene(scene_name, scene_layers)
+        {
+          name: scene_name.to_s,
+          layers: Array(scene_layers).map { |layer| serialize_layer(layer) }
+        }
+      end
+
+      def serialize_layer(layer)
+        values = symbolize_hash(layer)
+
+        output = {
+          name: values.fetch(:name).to_s,
+          type: (values[:type] || :geometry).to_s,
+          params: symbolize_hash(values[:params])
+        }
+        output[:shader] = values[:shader].to_s if values[:shader]
+        output[:glsl] = values[:glsl].to_s if values[:glsl]
+        output[:glsl_source] = values[:glsl_source].to_s if values[:glsl_source]
+        output
+      end
+
+      def symbolize_hash(value)
+        Hash(value).each_with_object({}) do |(key, entry), output|
+          output[key.to_sym] = entry
+        end
+      rescue StandardError
+        {}
+      end
+
+      def round_float(value, digits: 4)
+        Float(value).round(digits)
+      rescue StandardError
+        0.0
+      end
+    end
+  end
+end

data/lib/vizcore/renderer.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Renderer-side frame scheduling and scene serialization.
+  module Renderer
+  end
+end
+
+require_relative "renderer/frame_scheduler"
+require_relative "renderer/scene_serializer"