vizcore 1.1.0 → 1.2.0

data/lib/vizcore/server/websocket_handler.rb

@@ -3,6 +3,7 @@
 require "json"
 require "set"
 require "thread"
+require "uri"
 require_relative "../errors"
 
 module Vizcore
@@ -12,6 +13,14 @@ module Vizcore
       PROTOCOL_VERSION = "vizcore.frame.v1"
       MAX_BUFFERED_FRAME_BYTES = 1_000_000
       DROPPABLE_MESSAGE_TYPES = Set["audio_frame"].freeze
+      VALID_CLIENT_ROLES = Set["projector", "control", "monitor"].freeze
+      CONTROL_ROLE = "control".freeze
+      PROJECTOR_ROLE = "projector".freeze
+      MONITOR_ROLE = "monitor".freeze
+      READ_ONLY_ROLES = Set[PROJECTOR_ROLE, MONITOR_ROLE].freeze
+      READ_ONLY_ALLOWED_MESSAGE_TYPES = Set["latency_probe", "client_runtime_error"].freeze
+      LOW_BANDWIDTH_ROLES = Set[CONTROL_ROLE, MONITOR_ROLE].freeze
+      CONTROL_AUDIO_FRAME_INTERVAL = 4
 
       class << self
         # Rack endpoint for WebSocket upgrade handling.
@@ -25,7 +34,7 @@ module Vizcore
 
           socket = websocket_klass.new(env, nil, ping: 15)
 
-          socket.on(:open) { register(socket) }
+          socket.on(:open) { register(socket, role: websocket_role_for_env(env)) }
           socket.on(:close) { unregister(socket) }
           socket.on(:message) { |event| handle_message(socket, event.data) }
 
@@ -78,6 +87,28 @@ module Vizcore
           mutex.synchronize { @dropped_frame_count || 0 }
         end
 
+        # @return [Hash] current websocket backpressure metrics for control/status surfaces.
+        def backpressure_status
+          mutex.synchronize do
+            clients = sockets.map { |socket| backpressure_client_status(socket) }
+            {
+              threshold_bytes: MAX_BUFFERED_FRAME_BYTES,
+              active_clients: sockets.size,
+              total: {
+                dropped_frames: socket_backpressure_totals[:dropped_frames],
+                dropped_payload_bytes: socket_backpressure_totals[:dropped_payload_bytes],
+                sent_frames: socket_backpressure_totals[:sent_frames],
+                sent_payload_bytes: socket_backpressure_totals[:sent_payload_bytes],
+                avg_payload_bytes: average(
+                  socket_backpressure_totals[:sent_payload_bytes],
+                  socket_backpressure_totals[:sent_frames]
+                )
+              },
+              clients: clients
+            }
+          end
+        end
+
         # Register one inbound message handler for client -> server control messages.
         #
         # @yieldparam message [Hash]
@@ -103,32 +134,52 @@ module Vizcore
         end
 
         def send_message(socket, message, type:)
-          return if drop_for_backpressure?(socket, type)
+          return unless should_send_to_socket?(socket, type: type)
+
+          message_bytes = message.bytesize
+          return if drop_for_backpressure?(socket, type, payload_bytes: message_bytes)
 
           if event_machine_reactor_running?
-            EventMachine.schedule { safe_send(socket, message, type: type) }
+            EventMachine.schedule { safe_send(socket, message, type: type, payload_bytes: message_bytes) }
           else
-            safe_send(socket, message, type: type)
+            safe_send(socket, message, type: type, payload_bytes: message_bytes)
           end
         end
 
-        def safe_send(socket, message, type:)
-          return if drop_for_backpressure?(socket, type)
+        def safe_send(socket, message, type:, payload_bytes:)
+          return if drop_for_backpressure?(socket, type, payload_bytes: payload_bytes)
 
           socket.send(message)
+          record_message_sent(socket, payload_bytes)
         rescue StandardError => e
           set_last_error(e)
           unregister(socket)
         end
 
-        def drop_for_backpressure?(socket, type)
+        def drop_for_backpressure?(socket, type, payload_bytes: nil)
           return false unless DROPPABLE_MESSAGE_TYPES.include?(type.to_s)
 
           buffered_amount = socket_buffered_amount(socket)
-          return false unless buffered_amount && buffered_amount > MAX_BUFFERED_FRAME_BYTES
+          begin
+            buffered_amount = Integer(buffered_amount) if buffered_amount
+          rescue ArgumentError, TypeError
+            buffered_amount = nil
+          end
 
-          increment_dropped_frame_count
-          true
+          if buffered_amount && buffered_amount > MAX_BUFFERED_FRAME_BYTES
+            mutex.synchronize do
+              refresh_socket_backpressure_metrics(socket, buffered_amount: buffered_amount)
+              increment_dropped_frame_count
+              increment_client_drop(socket, payload_bytes: payload_bytes)
+            end
+            return true
+          end
+
+          if buffered_amount
+            mutex.synchronize { refresh_socket_backpressure_metrics(socket, buffered_amount: buffered_amount) }
+          end
+
+          false
         end
 
         def socket_buffered_amount(socket)
@@ -160,12 +211,21 @@ module Vizcore
           nil
         end
 
-        def register(socket)
-          mutex.synchronize { sockets << socket }
+        def register(socket, role: PROJECTOR_ROLE)
+          mutex.synchronize do
+            sockets << socket
+            socket_backpressure_metrics[socket_id(socket)] = default_backpressure_metrics
+            client_backpressure_metrics(socket)[:role] = normalize_client_role(role)
+            client_backpressure_metrics(socket)[:control_audio_frame_index] = 0
+            socket_backpressure_metrics[socket_id(socket)] = client_backpressure_metrics(socket)
+          end
         end
 
         def unregister(socket)
-          mutex.synchronize { sockets.delete(socket) }
+          mutex.synchronize do
+            sockets.delete(socket)
+            socket_backpressure_metrics.delete(socket_id(socket))
+          end
         end
 
         def each_socket(&block)
@@ -177,6 +237,158 @@ module Vizcore
           @sockets ||= Set.new
         end
 
+        def socket_backpressure_metrics
+          @socket_backpressure_metrics ||= {}
+        end
+
+        def socket_backpressure_totals
+          @socket_backpressure_totals ||= {
+            dropped_frames: 0,
+            dropped_payload_bytes: 0,
+            sent_frames: 0,
+            sent_payload_bytes: 0
+          }
+        end
+
+        def backpressure_client_status(socket)
+          metrics = client_backpressure_metrics(socket)
+          {
+            id: socket_id(socket).to_s,
+            role: metrics[:role],
+            buffered_amount: metrics[:buffered_amount],
+            peak_buffered_amount: metrics[:peak_buffered_amount],
+            dropped_frames: metrics[:dropped_frames],
+            dropped_payload_bytes: metrics[:dropped_payload_bytes],
+            sent_frames: metrics[:sent_frames],
+            sent_payload_bytes: metrics[:sent_payload_bytes],
+            avg_payload_bytes: average(metrics[:sent_payload_bytes], metrics[:sent_frames]),
+            estimated_lag_frames: estimated_lag_frames(
+              metrics[:buffered_amount],
+              metrics[:sent_payload_bytes],
+              metrics[:sent_frames]
+            ),
+            last_payload_bytes: metrics[:last_payload_bytes]
+          }
+        end
+
+        def socket_id(socket)
+          socket.object_id
+        end
+
+        def client_backpressure_metrics(socket)
+          socket_backpressure_metrics.fetch(socket_id(socket)) do
+            socket_backpressure_metrics[socket_id(socket)] = default_backpressure_metrics
+          end
+        end
+
+        def socket_role(socket)
+          client_backpressure_metrics(socket)[:role]
+        end
+
+        def should_send_to_socket?(socket, type:)
+          return true unless LOW_BANDWIDTH_ROLES.include?(socket_role(socket))
+          return true unless type.to_s == "audio_frame"
+
+          control_audio_frame_due?(socket)
+        end
+
+        def control_audio_frame_due?(socket)
+          metrics = client_backpressure_metrics(socket)
+          metrics[:control_audio_frame_index] = (metrics[:control_audio_frame_index] || 0) + 1
+          count = metrics[:control_audio_frame_index]
+
+          return true if count == 1
+          return true if (count % CONTROL_AUDIO_FRAME_INTERVAL).zero?
+
+          false
+        end
+
+        def refresh_socket_backpressure_metrics(socket, buffered_amount: nil)
+          metrics = client_backpressure_metrics(socket)
+          amount = buffered_amount.nil? ? socket_buffered_amount(socket) : buffered_amount
+          return metrics unless amount
+
+          integer_amount = amount.to_i
+          metrics[:buffered_amount] = integer_amount
+          metrics[:peak_buffered_amount] = [metrics[:peak_buffered_amount], integer_amount].max
+          metrics
+        end
+
+        def increment_client_drop(socket, payload_bytes: nil)
+          payload_bytes = Integer(payload_bytes || 0)
+          metrics = client_backpressure_metrics(socket)
+          metrics[:dropped_frames] += 1
+          metrics[:dropped_payload_bytes] += payload_bytes
+          socket_backpressure_totals[:dropped_frames] += 1
+          socket_backpressure_totals[:dropped_payload_bytes] += payload_bytes
+        end
+
+        def record_message_sent(socket, payload_bytes)
+          payload_bytes = Integer(payload_bytes || 0)
+          buffered_amount = socket_buffered_amount(socket)
+          buffered_amount = Integer(buffered_amount) if buffered_amount
+
+          mutex.synchronize do
+            metrics = client_backpressure_metrics(socket)
+            metrics[:sent_frames] += 1
+            metrics[:sent_payload_bytes] += payload_bytes
+            metrics[:last_payload_bytes] = payload_bytes
+            socket_backpressure_totals[:sent_frames] += 1
+            socket_backpressure_totals[:sent_payload_bytes] += payload_bytes
+            refresh_socket_backpressure_metrics(socket, buffered_amount: buffered_amount) if buffered_amount
+          end
+        end
+
+        def average(numerator, denominator)
+          return 0.0 if denominator.to_i <= 0
+
+          numerator.to_f / denominator.to_f
+        end
+
+        def estimated_lag_frames(buffered_amount, payload_bytes, sent_frames)
+          avg_payload_bytes = average(payload_bytes, sent_frames)
+          return 0.0 if avg_payload_bytes <= 0.0
+
+          buffered_amount.to_f / avg_payload_bytes
+        end
+
+        def default_backpressure_metrics
+          {
+            role: PROJECTOR_ROLE,
+            control_audio_frame_index: 0,
+            buffered_amount: 0,
+            peak_buffered_amount: 0,
+            dropped_frames: 0,
+            dropped_payload_bytes: 0,
+            sent_frames: 0,
+            sent_payload_bytes: 0,
+            last_payload_bytes: 0
+          }
+        end
+
+        def websocket_role_for_env(env)
+          return PROJECTOR_ROLE unless env.is_a?(Hash)
+
+          role = query_param(String(env["QUERY_STRING"] || ""), "role")
+          normalize_client_role(role)
+        end
+
+        def query_param(query_string, key)
+          URI.decode_www_form(query_string).each do |entry_key, value|
+            return value if entry_key == key
+          end
+
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def normalize_client_role(role)
+          return PROJECTOR_ROLE unless VALID_CLIENT_ROLES.include?(role.to_s)
+
+          role.to_s
+        end
+
         def mutex
           @mutex ||= Mutex.new
         end
@@ -186,7 +398,7 @@ module Vizcore
         end
 
         def increment_dropped_frame_count
-          mutex.synchronize { @dropped_frame_count = (@dropped_frame_count || 0) + 1 }
+          @dropped_frame_count = (@dropped_frame_count || 0) + 1
         end
 
         def dispatch_message(message, socket)
@@ -194,12 +406,22 @@ module Vizcore
           return unless handler
           return unless message.is_a?(Hash)
 
+          type = message["type"] || message[:type]
+          role = socket_role(socket)
+          return unless client_message_allowed?(role: role, type: type)
+
           handler.call(message, socket)
         rescue StandardError => e
           set_last_error(e)
           nil
         end
 
+        def client_message_allowed?(role:, type:)
+          return true unless READ_ONLY_ROLES.include?(role.to_s)
+
+          READ_ONLY_ALLOWED_MESSAGE_TYPES.include?(type.to_s)
+        end
+
         def text_headers
           { "content-type" => "text/plain; charset=utf-8" }
         end

data/lib/vizcore/server.rb

@@ -1,8 +1,29 @@
 # frozen_string_literal: true
 
+require_relative "config"
+
 module Vizcore
   # Rack/WebSocket server runtime namespace.
   module Server
+    # Start a Vizcore server from Ruby code.
+    #
+    # @param config [Vizcore::Config, Hash, nil] runtime config or Config keyword options
+    # @param output [#puts] stream used by the runner
+    # @param options [Hash] Config keyword options when `config` is nil
+    # @return [void]
+    def self.start(config = nil, output: $stdout, **options)
+      runtime_config = start_config(config, options)
+      Runner.new(runtime_config, output: output).run
+    end
+
+    def self.start_config(config, options)
+      return Config.new(**options) if config.nil?
+      return config if config.is_a?(Config) && options.empty?
+      return Config.new(**config.merge(options)) if config.is_a?(Hash)
+
+      raise ArgumentError, "server start requires a Vizcore::Config or config options"
+    end
+    private_class_method :start_config
   end
 end
 

data/lib/vizcore/shape.rb

@@ -110,14 +110,7 @@ module Vizcore
       end
 
       def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) { |(key, entry), output| output[key] = deep_dup(entry) }
-        when Array
-          value.map { |entry| deep_dup(entry) }
-        else
-          value
-        end
+        Vizcore::DeepCopy.copy(value)
       end
 
       def shape_definition(renderer)
@@ -329,14 +322,26 @@ module Vizcore
         numeric(band(:low))
       end
 
+      def bass_peak
+        numeric(band_peak(:low))
+      end
+
       def mid
         numeric(band(:mid))
       end
 
+      def mid_peak
+        numeric(band_peak(:mid))
+      end
+
       def high
         numeric(band(:high))
       end
 
+      def high_peak
+        numeric(band_peak(:high))
+      end
+
       def fft
         Array(@payload[:fft])
       end
@@ -349,6 +354,26 @@ module Vizcore
         numeric(@payload[:beat_pulse])
       end
 
+      def beat_phase
+        numeric(@payload[:beat_phase])
+      end
+
+      def bar_phase
+        numeric(@payload[:bar_phase])
+      end
+
+      def bar_count
+        Integer(@payload[:bar_count] || 0)
+      rescue ArgumentError, TypeError
+        0
+      end
+
+      def phrase_count
+        Integer(@payload[:phrase_count] || 0)
+      rescue ArgumentError, TypeError
+        0
+      end
+
       def kick
         numeric(drum(:kick))
       end
@@ -372,6 +397,11 @@ module Vizcore
         bands[name]
       end
 
+      def band_peak(name)
+        peaks = symbolize_hash(@payload[:band_peaks])
+        peaks[name]
+      end
+
       def drum(name)
         drums = symbolize_hash(@payload[:drums])
         drums[name]
@@ -689,14 +719,7 @@ module Vizcore
       end
 
       def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) { |(key, entry), output| output[key] = deep_dup(entry) }
-        when Array
-          value.map { |entry| deep_dup(entry) }
-        else
-          value
-        end
+        Vizcore::DeepCopy.copy(value)
       end
     end
   end

data/lib/vizcore/sync/osc_message.rb

@@ -4,37 +4,46 @@ module Vizcore
   module Sync
     # Minimal OSC 1.0 message parser for control sync.
     class OscMessage
-      attr_reader :address, :arguments
+      attr_reader :address, :arguments, :timetag
 
       # @param data [String]
-      # @return [Vizcore::Sync::OscMessage, nil]
+      # @return [Vizcore::Sync::OscMessage, Array<Vizcore::Sync::OscMessage>, nil]
       def self.parse(data)
         parser = Parser.new(data)
-        address = parser.read_string
-        return nil unless address&.start_with?("/")
-
-        tags = parser.read_string
-        arguments = parser.read_arguments(tags)
-        new(address: address, arguments: arguments)
+        parser.parse_packet
       rescue StandardError
         nil
       end
 
       # @param address [String]
       # @param arguments [Array]
-      def initialize(address:, arguments: [])
+      # @param timetag [Float, nil]
+      def initialize(address:, arguments: [], timetag: nil)
         @address = address
         @arguments = Array(arguments)
+        @timetag = timetag
       end
 
       # @api private
       class Parser
+        BUNDLE_SIGNATURE = "#bundle"
+        NTP_TO_UNIX_OFFSET = 2_208_988_800
+
         # @param data [String]
         def initialize(data)
           @data = data.to_s.b
           @offset = 0
         end
 
+        # @return [Vizcore::Sync::OscMessage, Array<Vizcore::Sync::OscMessage>, nil]
+        def parse_packet(default_timetag: nil)
+          signature_or_address = read_string
+          return nil unless signature_or_address
+
+          return parse_bundle if signature_or_address == BUNDLE_SIGNATURE
+          parse_message(signature_or_address, timetag: default_timetag)
+        end
+
         # @return [String, nil]
         def read_string
           start = @offset
@@ -47,6 +56,42 @@ module Vizcore
           value
         end
 
+        def parse_bundle
+          bundle_timetag = parse_timetag(read_uint64)
+          messages = []
+
+          until @offset >= @data.bytesize
+            break if @offset + 4 > @data.bytesize
+
+            begin
+              message_size = read_int32
+            rescue StandardError
+              break
+            end
+
+            break if message_size <= 0
+
+            begin
+              message_data = read_bytes(message_size)
+            rescue StandardError
+              break
+            end
+
+            parsed = Parser.new(message_data).parse_packet(default_timetag: bundle_timetag)
+            messages.concat(Array(parsed))
+          end
+
+          messages
+        end
+
+        def parse_message(address, timetag: nil)
+          return nil unless address&.start_with?("/")
+
+          tags = read_string
+          arguments = read_arguments(tags)
+          OscMessage.new(address: address, arguments: arguments, timetag: timetag)
+        end
+
         # @param tags [String, nil]
         # @return [Array]
         def read_arguments(tags)
@@ -86,6 +131,10 @@ module Vizcore
           read_bytes(4).unpack1("g")
         end
 
+        def read_uint64
+          read_bytes(8).unpack1("Q>")
+        end
+
         def read_bytes(length)
           raise ArgumentError, "OSC payload truncated" if @offset + length > @data.bytesize
 
@@ -94,6 +143,14 @@ module Vizcore
           end
         end
 
+        def parse_timetag(raw)
+          return nil if raw == 0
+
+          seconds = (raw >> 32) - NTP_TO_UNIX_OFFSET
+          fraction = raw & 0xFFFF_FFFF
+          seconds + (fraction / 4_294_967_296.0)
+        end
+
         def align_offset
           @offset += 1 while (@offset % 4).positive?
         end

data/lib/vizcore/version.rb

@@ -2,5 +2,5 @@
 
 module Vizcore
   # Current gem version.
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/vizcore.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "vizcore/version"
+require_relative "vizcore/deep_copy"
 require_relative "vizcore/errors"
 require_relative "vizcore/layer_catalog"
+require_relative "vizcore/plugin_asset_policy"
+require_relative "vizcore/scene_trust"
 require_relative "vizcore/shape"
 require_relative "vizcore/dsl"
+require_relative "vizcore/analysis"
+require_relative "vizcore/audio"
 require "pathname"
 
 # Main namespace for the Vizcore runtime and DSL entrypoints.
@@ -29,6 +34,19 @@ module Vizcore
     root.join("lib", "vizcore", "templates")
   end
 
+  # @param command_available [#call, nil] optional command lookup for tests
+  # @return [Hash<Symbol, Boolean>] optional runtime feature availability
+  def self.features(command_available: nil)
+    command_available ||= method(:command_available?)
+    {
+      mic: feature_available? { Audio::PortAudioFFI.available? },
+      midi: feature_available? { Audio::MidiInput.available? },
+      ffmpeg: command_available.call("ffmpeg"),
+      browser_capture: root.join("scripts", "browser_capture.mjs").file? && command_available.call("node"),
+      fftw: feature_available? { Analysis::FFTProcessor.fftw_available? }
+    }
+  end
+
   # Evaluate a Vizcore DSL definition block.
   #
   # @yield DSL configuration block (`audio`, `scene`, `midi_map`, etc.)
@@ -62,4 +80,19 @@ module Vizcore
       description: description
     )
   end
+
+  def self.feature_available?
+    !!yield
+  rescue StandardError
+    false
+  end
+  private_class_method :feature_available?
+
+  def self.command_available?(command)
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
+      path = File.join(directory, command)
+      File.file?(path) && File.executable?(path)
+    end
+  end
+  private_class_method :command_available?
 end