vizcore 0.1.0

data/lib/vizcore/config.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Vizcore
+  # Runtime configuration for CLI/server startup.
+  class Config
+    # Default host used by `vizcore start`.
+    DEFAULT_HOST = "127.0.0.1"
+    # Default HTTP/WebSocket port.
+    DEFAULT_PORT = 4567
+    # Default audio source.
+    DEFAULT_AUDIO_SOURCE = :mic
+    # Supported CLI audio source values.
+    SUPPORTED_AUDIO_SOURCES = %i[mic file dummy].freeze
+
+    attr_reader :host, :port, :scene_file, :audio_source, :audio_file
+
+    # @param scene_file [String, Pathname] scene DSL file path
+    # @param host [String] bind host
+    # @param port [Integer] bind port
+    # @param audio_source [Symbol, String] one of `:mic`, `:file`, `:dummy`
+    # @param audio_file [String, Pathname, nil] file path used with `audio_source=:file`
+    def initialize(scene_file:, host: DEFAULT_HOST, port: DEFAULT_PORT, audio_source: DEFAULT_AUDIO_SOURCE, audio_file: nil)
+      @scene_file = Pathname.new(scene_file).expand_path if scene_file
+      @host = host
+      @port = Integer(port)
+      @audio_source = normalize_audio_source(audio_source)
+      @audio_file = audio_file ? Pathname.new(audio_file).expand_path : nil
+    end
+
+    # @return [Boolean] true when the configured scene file exists.
+    def scene_exists?
+      scene_file && scene_file.file?
+    end
+
+    private
+
+    def normalize_audio_source(value)
+      source = value.to_sym
+      return source if SUPPORTED_AUDIO_SOURCES.include?(source)
+
+      raise ArgumentError, "Unsupported audio source: #{value}. Use one of: #{SUPPORTED_AUDIO_SOURCES.join(', ')}"
+    end
+  end
+end

data/lib/vizcore/dsl/engine.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "file_watcher"
+require_relative "scene_builder"
+
+module Vizcore
+  module DSL
+    # Evaluates and stores scene definitions built with the Vizcore Ruby DSL.
+    class Engine
+      # Thread-local key used when evaluating scene files.
+      THREAD_KEY = :vizcore_current_dsl_engine
+
+      class << self
+        # Evaluate a DSL block using the current thread-local engine, or a new engine.
+        #
+        # @yield Scene/audio/midi DSL configuration block
+        # @return [Hash] serialized DSL definition
+        def define(&block)
+          engine = current || new
+          engine.evaluate(&block)
+        end
+
+        # Load and evaluate a scene file.
+        #
+        # @param path [String, Pathname] scene file path
+        # @raise [ArgumentError] when the scene file does not exist
+        # @return [Hash] serialized DSL definition
+        def load_file(path)
+          scene_path = Pathname.new(path.to_s).expand_path
+          raise ArgumentError, "Scene file not found: #{scene_path}" unless scene_path.file?
+
+          engine = new
+          with_current(engine) { Kernel.load(scene_path.to_s) }
+          engine.result
+        end
+
+        # Build a file watcher that reloads and yields definitions on change.
+        #
+        # @param path [String, Pathname] scene file path to watch
+        # @param poll_interval [Float] watcher poll interval in seconds
+        # @param listener_factory [#call, nil] optional listener factory for tests
+        # @yieldparam definition [Hash] reloaded DSL definition
+        # @yieldparam changed_path [Pathname] path reported by the watcher
+        # @return [Vizcore::DSL::FileWatcher]
+        def watch_file(path, poll_interval: FileWatcher::DEFAULT_POLL_INTERVAL, listener_factory: nil, &on_change)
+          FileWatcher.new(path: path, poll_interval: poll_interval, listener_factory: listener_factory) do |changed_path|
+            definition = load_file(changed_path.to_s)
+            on_change&.call(definition, changed_path)
+          end
+        end
+
+        # @return [Vizcore::DSL::Engine, nil] current thread-local DSL engine.
+        def current
+          Thread.current[THREAD_KEY]
+        end
+
+        private
+
+        def with_current(engine)
+          previous = current
+          Thread.current[THREAD_KEY] = engine
+          yield
+        ensure
+          Thread.current[THREAD_KEY] = previous
+        end
+      end
+
+      def initialize
+        @audio_inputs = []
+        @midi_inputs = []
+        @scenes = []
+        @transitions = []
+        @midi_mappings = []
+        @global_params = {}
+      end
+
+      # Evaluate DSL methods on this engine instance.
+      #
+      # @yield DSL configuration block
+      # @return [Hash] serialized DSL definition
+      def evaluate(&block)
+        instance_eval(&block) if block
+        result
+      end
+
+      # Register an audio input definition.
+      #
+      # @param name [Symbol, String] input name
+      # @param options [Hash] input options
+      # @return [void]
+      def audio(name, **options)
+        @audio_inputs << { name: name.to_sym, options: symbolize_keys(options) }
+      end
+
+      # Register a MIDI input definition.
+      #
+      # @param name [Symbol, String] input name
+      # @param options [Hash] input options
+      # @return [void]
+      def midi(name, **options)
+        @midi_inputs << { name: name.to_sym, options: symbolize_keys(options) }
+      end
+
+      # Define a scene and its layers.
+      #
+      # @param name [Symbol, String] scene identifier
+      # @yield Scene definition block
+      # @return [void]
+      def scene(name, &block)
+        builder = SceneBuilder.new(name: name)
+        builder.evaluate(&block)
+        @scenes << builder.to_h
+      end
+
+      # Define a transition between scenes.
+      #
+      # @param from [Symbol, String] source scene name
+      # @param to [Symbol, String] target scene name
+      # @yield Optional transition block (`effect`, `trigger`)
+      # @return [void]
+      def transition(from:, to:, &block)
+        definition = {
+          from: from.to_sym,
+          to: to.to_sym
+        }
+        builder = TransitionBuilder.new
+        builder.instance_eval(&block) if block
+        @transitions << definition.merge(builder.to_h)
+      end
+
+      # Register a MIDI trigger/action mapping.
+      #
+      # @param note [Integer, nil] note number trigger
+      # @param cc [Integer, nil] control-change trigger
+      # @param pc [Integer, nil] program-change trigger
+      # @yield Action block executed by midi runtime
+      # @raise [ArgumentError] when no trigger is supplied
+      # @return [void]
+      def midi_map(note: nil, cc: nil, pc: nil, &block)
+        trigger = {}
+        trigger[:note] = Integer(note) unless note.nil?
+        trigger[:cc] = Integer(cc) unless cc.nil?
+        trigger[:pc] = Integer(pc) unless pc.nil?
+        raise ArgumentError, "midi_map requires note, cc or pc" if trigger.empty?
+
+        @midi_mappings << {
+          trigger: trigger,
+          action: block
+        }
+      end
+
+      # Set a mutable global value shared with scene/runtime logic.
+      #
+      # @param key [Symbol, String] global key
+      # @param value [Object] global value
+      # @return [Object] assigned value
+      def set(key, value)
+        @global_params[key.to_sym] = value
+      end
+
+      # @return [Hash] deep-copied definition payload for renderer/runtime.
+      def result
+        {
+          audio: @audio_inputs.map { |item| deep_dup(item) },
+          midi: @midi_inputs.map { |item| deep_dup(item) },
+          scenes: @scenes.map { |scene| deep_dup(scene) },
+          transitions: @transitions.map { |transition| deep_dup(transition) },
+          midi_maps: @midi_mappings.map { |mapping| deep_dup(mapping) },
+          globals: deep_dup(@global_params)
+        }
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(key, value), output|
+          output[key.to_sym] = value
+        end
+      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
+
+      # Builder object for `transition` block internals.
+      # @api private
+      class TransitionBuilder
+        def initialize
+          @effect = nil
+          @trigger = nil
+        end
+
+        # @param name [Symbol, String] transition effect name
+        # @param options [Hash] effect options
+        # @return [void]
+        def effect(name, **options)
+          @effect = {
+            name: name.to_sym,
+            options: options.each_with_object({}) { |(key, value), output| output[key.to_sym] = value }
+          }
+        end
+
+        # @yield Trigger predicate executed in transition context
+        # @return [void]
+        def trigger(&block)
+          @trigger = block
+        end
+
+        # @return [Hash] serialized transition extras
+        def to_h
+          output = {}
+          output[:effect] = @effect if @effect
+          output[:trigger] = @trigger if @trigger
+          output
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/file_watcher.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Vizcore
+  module DSL
+    # Watches one scene file and invokes a callback when it changes.
+    class FileWatcher
+      # Default polling interval in seconds when `listen` is unavailable.
+      DEFAULT_POLL_INTERVAL = 0.25
+
+      # @param path [String, Pathname]
+      # @param poll_interval [Float]
+      # @param listener_factory [#call, nil]
+      # @yieldparam changed_path [Pathname]
+      def initialize(path:, poll_interval: DEFAULT_POLL_INTERVAL, listener_factory: nil, &on_change)
+        @path = Pathname.new(path.to_s).expand_path
+        @poll_interval = Float(poll_interval)
+        @listener_factory = listener_factory
+        @on_change = on_change
+        @running = false
+        @listener = nil
+        @thread = nil
+      end
+
+      # @return [Boolean]
+      def start
+        return if running?
+
+        @running = true
+        start_with_listener || start_with_polling
+      end
+
+      # @param timeout [Float]
+      # @return [void]
+      def stop(timeout: 1.0)
+        return unless running?
+
+        @running = false
+        @listener&.stop
+        @listener = nil
+
+        thread = @thread
+        @thread = nil
+        return unless thread
+        return if thread == Thread.current
+
+        thread.join(timeout)
+      end
+
+      # @return [Boolean]
+      def running?
+        @running
+      end
+
+      private
+
+      def start_with_listener
+        factory = @listener_factory || default_listener_factory
+        return false unless factory
+
+        file_pattern = /\A#{Regexp.escape(@path.basename.to_s)}\z/
+        @listener = factory.call(@path.dirname.to_s, file_pattern) do |modified, added, _removed|
+          changed = (Array(modified) + Array(added)).map { |entry| Pathname.new(entry.to_s).expand_path }
+          next unless changed.include?(@path)
+
+          @on_change&.call(@path)
+        end
+        @listener.start
+        true
+      rescue StandardError
+        @listener = nil
+        false
+      end
+
+      def start_with_polling
+        @thread = Thread.new { poll_loop }
+      end
+
+      def poll_loop
+        last_mtime = file_mtime
+
+        while running?
+          sleep(@poll_interval)
+          current_mtime = file_mtime
+          changed = !current_mtime.nil? && (last_mtime.nil? || current_mtime > last_mtime)
+          if changed
+            @on_change&.call(@path)
+            last_mtime = current_mtime
+          end
+        end
+      end
+
+      def file_mtime
+        return nil unless @path.file?
+
+        @path.mtime
+      end
+
+      def default_listener_factory
+        require "listen"
+        ->(directory, pattern, &block) { Listen.to(directory, only: pattern, &block) }
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/layer_builder.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Builder for one render layer in a scene.
+    class LayerBuilder
+      # @param name [Symbol, String] layer identifier
+      def initialize(name:)
+        @name = name.to_sym
+        @type = nil
+        @shader = nil
+        @glsl = nil
+        @params = {}
+        @mappings = []
+      end
+
+      # Evaluate a layer block.
+      #
+      # @yield Layer DSL methods
+      # @return [Vizcore::DSL::LayerBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        self
+      end
+
+      # @param value [Symbol, String] layer type (`shader`, `particle_field`, etc.)
+      # @return [Symbol]
+      def type(value)
+        @type = value.to_sym
+      end
+
+      # @param value [Symbol, String] built-in shader key
+      # @return [Symbol]
+      def shader(value)
+        @shader = value.to_sym
+        @type ||= :shader
+      end
+
+      # @param path [String, Pathname] custom fragment shader path
+      # @return [String]
+      def glsl(path)
+        @glsl = path.to_s
+        @type ||= :shader
+      end
+
+      # @param value [Integer] particle count or similar numeric parameter
+      # @return [Integer]
+      def count(value)
+        @params[:count] = Integer(value)
+      end
+
+      # @param value [String] text content
+      # @return [String]
+      def content(value)
+        @params[:content] = value.to_s
+      end
+
+      # @param value [Integer] font size in pixels
+      # @return [Integer]
+      def font_size(value)
+        @params[:font_size] = Integer(value)
+      end
+
+      # Map analysis source(s) to layer parameter target(s).
+      #
+      # @param definition [Hash] mapping pairs (`source` => `target`)
+      # @raise [ArgumentError] when the mapping is empty or invalid
+      # @return [void]
+      def map(definition)
+        mapping = Hash(definition)
+        raise ArgumentError, "map requires at least one mapping pair" if mapping.empty?
+
+        mapping.each do |source, target|
+          @mappings << {
+            source: normalize_source(source),
+            target: target.to_sym
+          }
+        end
+      end
+
+      # @return [Hash] source descriptor for overall amplitude
+      def amplitude
+        source(:amplitude)
+      end
+
+      # @param name [Symbol, String] band key (`sub`, `low`, `mid`, `high`)
+      # @return [Hash] source descriptor for a frequency band
+      def frequency_band(name)
+        source(:frequency_band, band: name.to_sym)
+      end
+
+      # @return [Hash] source descriptor for FFT spectrum array
+      def fft_spectrum
+        source(:fft_spectrum)
+      end
+
+      # @return [Hash] source descriptor for beat trigger
+      def beat?
+        source(:beat)
+      end
+
+      # @return [Hash] source descriptor for beat counter
+      def beat_count
+        source(:beat_count)
+      end
+
+      # @return [Hash] source descriptor for estimated BPM
+      def bpm
+        source(:bpm)
+      end
+
+      # @return [Hash] serialized layer payload
+      def to_h
+        layer = {
+          name: @name,
+          type: resolved_type,
+          params: @params.dup
+        }
+        layer[:shader] = @shader if @shader
+        layer[:glsl] = @glsl if @glsl
+        layer[:mappings] = @mappings.map { |mapping| mapping.dup } unless @mappings.empty?
+        layer
+      end
+
+      # Stores dynamic one-argument setters into `params`.
+      # @api private
+      def method_missing(method_name, *args, &block)
+        if block.nil? && args.length == 1
+          @params[method_name.to_sym] = args.first
+          return args.first
+        end
+
+        super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @params.key?(method_name.to_sym) || super
+      end
+
+      private
+
+      def resolved_type
+        return @type if @type
+        return :shader if @shader || @glsl
+
+        :geometry
+      end
+
+      def normalize_source(source_value)
+        case source_value
+        when Hash
+          kind = source_value[:kind] || source_value["kind"]
+          raise ArgumentError, "mapping source hash must contain :kind" unless kind
+
+          source(kind.to_sym, **normalize_source_options(source_value))
+        when Symbol
+          source(source_value)
+        when String
+          source(source_value.to_sym)
+        else
+          raise ArgumentError, "unsupported mapping source: #{source_value.inspect}"
+        end
+      end
+
+      def normalize_source_options(source_value)
+        source_value.each_with_object({}) do |(key, value), options|
+          symbol_key = key.to_sym
+          next if symbol_key == :kind
+
+          options[symbol_key] = value.respond_to?(:to_sym) ? value.to_sym : value
+        end
+      end
+
+      def source(kind, **options)
+        {
+          kind: kind.to_sym,
+          **options
+        }
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/mapping_resolver.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Resolves `map` definitions into concrete per-layer parameter values.
+    class MappingResolver
+      # @param scene_layers [Array<Hash>]
+      # @param audio [Hash]
+      # @return [Array<Hash>] normalized layer payloads with resolved params
+      def resolve_layers(scene_layers:, audio:)
+        normalize_scene_layers(scene_layers).map do |layer|
+          resolve_layer(layer, audio)
+        end
+      end
+
+      private
+
+      def resolve_layer(layer, audio)
+        params = (layer[:params] || {}).dup
+        params.merge!(resolve_mappings(layer[:mappings], audio))
+
+        output = {
+          name: layer.fetch(:name).to_s,
+          type: (layer[:type] || :geometry).to_s,
+          params: params
+        }
+        output[:shader] = layer[:shader].to_s if layer[:shader]
+        output[:glsl] = layer[:glsl].to_s if layer[:glsl]
+        output[:glsl_source] = layer[:glsl_source].to_s if layer[:glsl_source]
+        output
+      end
+
+      def resolve_mappings(mappings, audio)
+        Array(mappings).each_with_object({}) do |mapping, resolved|
+          source = mapping[:source]
+          target = mapping[:target]
+          next unless source && target
+
+          value = resolve_source_value(source, audio)
+          resolved[target.to_sym] = value unless value.nil?
+        end
+      end
+
+      def resolve_source_value(source, audio)
+        case source[:kind]&.to_sym
+        when :amplitude
+          audio[:amplitude]
+        when :frequency_band
+          audio.dig(:bands, source[:band]&.to_sym)
+        when :fft_spectrum
+          audio[:fft]
+        when :beat
+          audio[:beat]
+        when :beat_count
+          audio[:beat_count]
+        when :bpm
+          audio[:bpm]
+        else
+          nil
+        end
+      end
+
+      def normalize_scene_layers(scene_layers)
+        Array(scene_layers).map { |layer| deep_symbolize(layer) }
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, entry), output|
+            output[key.to_sym] = deep_symbolize(entry)
+          end
+        when Array
+          value.map { |entry| deep_symbolize(entry) }
+        else
+          value
+        end
+      end
+    end
+  end
+end