vizcore 0.1.0 → 1.0.0

data/lib/vizcore/server/runner.rb

@@ -2,10 +2,13 @@
 
 require "puma"
 require_relative "../config"
+require_relative "../control_preset"
 require_relative "../dsl"
 require_relative "../errors"
+require_relative "../sync/osc_receiver"
 require_relative "frame_broadcaster"
 require_relative "rack_app"
+require_relative "scene_dependency_watcher"
 require_relative "websocket_handler"
 
 module Vizcore
@@ -20,6 +23,9 @@ module Vizcore
         @shader_source_resolver = Vizcore::DSL::ShaderSourceResolver.new
         @scene_catalog_mutex = Mutex.new
         @scene_catalog = []
+        @runtime_globals_mutex = Mutex.new
+        @runtime_globals = {}
+        @live_controls = { "blackout" => false, "freeze" => false }
       end
 
       # Run server lifecycle until interrupted.
@@ -29,51 +35,75 @@ module Vizcore
       # @return [void]
       def run
         validate_scene_file!
+        validate_feature_settings!
+        validate_control_preset_settings!
+        validate_plugin_asset_settings!
         validate_audio_settings!
         definition = load_definition!
+        control_preset = load_control_preset
+        replace_runtime_globals(globals_for(definition))
+        @tap_tempo_key = tap_tempo_key(definition)
         scene = first_scene(definition) || fallback_scene
 
         app = RackApp.new(
           frontend_root: Vizcore.frontend_root,
-          audio_source: @config.audio_source,
-          audio_file: @config.audio_file,
-          scene_names: scene_names_for(definition)
+          audio_source: runtime_audio_source,
+          audio_file: runtime_audio_file,
+          scene_names: scene_names_for(definition),
+          tap_tempo_key: @tap_tempo_key,
+          key_mappings: key_mappings_for(definition),
+          globals: runtime_globals_snapshot,
+          control_preset: control_preset,
+          control_preset_path: @config.control_preset,
+          plugin_assets: @config.plugin_assets,
+          projector_mode: @config.projector_mode
         )
         server = Puma::Server.new(app, nil, min_threads: 0, max_threads: 4)
         server.add_tcp_listener(@config.host, @config.port)
         server.run
 
-        input_manager = Vizcore::Audio::InputManager.new(
-          source: @config.audio_source,
-          file_path: @config.audio_file&.to_s
-        )
+        input_manager = build_input_manager
         broadcaster = FrameBroadcaster.new(
           scene_name: scene[:name].to_s,
           scene_layers: scene[:layers],
           scene_catalog: definition[:scenes],
           transitions: definition[:transitions],
           input_manager: input_manager,
+          analysis_pipeline: replay_pipeline,
+          noise_gate: @config.noise_gate,
+          audio_normalize: audio_normalize_settings(definition),
+          bpm: bpm_setting(definition),
+          bpm_lock: bpm_lock_setting(definition),
           error_reporter: ->(message) { @output.puts(message) }
         )
         replace_scene_catalog(definition[:scenes])
-        if @config.audio_source == :file
+        if file_transport_enabled?
           broadcaster.sync_transport(playing: false, position_seconds: 0.0)
         end
         broadcaster.start
         register_client_message_handler(broadcaster)
         midi_runtime = start_midi_runtime(definition, broadcaster)
-        watcher = start_scene_watcher(broadcaster) do |updated_definition|
-          midi_runtime = refresh_midi_runtime(midi_runtime, updated_definition, broadcaster)
-        end
+        osc_runtime = start_osc_runtime(broadcaster)
+        watcher = if @config.reload?
+                    start_scene_watcher(broadcaster, definition: definition) do |updated_definition|
+                      midi_runtime = refresh_midi_runtime(midi_runtime, updated_definition, broadcaster)
+                    end
+                  end
 
         @output.puts("Vizcore server listening at http://#{@config.host}:#{@config.port}")
+        @output.puts("Projector output: http://#{@config.host}:#{@config.port}/projector")
+        @output.puts("Control panel: http://#{@config.host}:#{@config.port}/control")
         @output.puts("Scene: #{scene[:name]}")
-        @output.puts("Audio playback: http://#{@config.host}:#{@config.port}/audio-file") if @config.audio_source == :file
+        @output.puts("Hot reload: #{@config.reload? ? 'enabled' : 'disabled'}")
+        @output.puts("Audio playback: http://#{@config.host}:#{@config.port}/audio-file") if file_transport_enabled?
+        @output.puts("Feature replay: #{@config.feature_file}") if feature_replay?
+        @output.puts("OSC sync: udp://#{@config.host}:#{@config.osc_port}") if osc_runtime
         @output.puts("Press Ctrl+C to stop.")
 
         wait_for_interrupt
       ensure
         Vizcore::Server::WebSocketHandler.clear_message_handler
+        stop_osc_runtime(osc_runtime)
         stop_midi_runtime(midi_runtime)
         watcher&.stop
         broadcaster&.stop
@@ -105,12 +135,72 @@ module Vizcore
       end
 
       def validate_audio_settings!
+        return if feature_replay?
         return unless @config.audio_source == :file
         return if @config.audio_file && @config.audio_file.file?
 
         raise Vizcore::ConfigurationError, "Audio file not found: #{@config.audio_file || '(nil)'}"
       end
 
+      def validate_feature_settings!
+        return unless feature_replay?
+        return if @config.feature_file.file?
+
+        raise Vizcore::ConfigurationError, "Feature file not found: #{@config.feature_file}"
+      end
+
+      def validate_control_preset_settings!
+        return unless @config.control_preset
+        return if @config.control_preset.file?
+
+        raise Vizcore::ConfigurationError, "Control preset file not found: #{@config.control_preset}"
+      end
+
+      def validate_plugin_asset_settings!
+        missing = @config.plugin_assets.find { |path| !path.file? }
+        return unless missing
+
+        raise Vizcore::ConfigurationError, "Plugin asset file not found: #{missing}"
+      end
+
+      def load_control_preset
+        return nil unless @config.control_preset
+
+        Vizcore::ControlPreset.load(@config.control_preset)
+      rescue ArgumentError => e
+        raise Vizcore::ConfigurationError, e.message
+      end
+
+      def build_input_manager
+        Vizcore::Audio::InputManager.new(
+          source: feature_replay? ? :dummy : @config.audio_source,
+          file_path: runtime_audio_file&.to_s,
+          audio_device: feature_replay? ? nil : @config.audio_device
+        )
+      end
+
+      def replay_pipeline
+        return nil unless feature_replay?
+
+        Vizcore::Analysis::FeatureReplay.new(path: @config.feature_file)
+      end
+
+      def feature_replay?
+        !!@config.feature_file
+      end
+
+      def file_transport_enabled?
+        @config.audio_source == :file && !feature_replay?
+      end
+
+      def runtime_audio_source
+        feature_replay? ? :features : @config.audio_source
+      end
+
+      def runtime_audio_file
+        feature_replay? ? nil : @config.audio_file
+      end
+
       def wait_for_interrupt
         stop_requested = false
         %w[INT TERM].each do |signal_name|
@@ -121,22 +211,32 @@ module Vizcore
         sleep(0.1) until stop_requested
       end
 
-      def start_scene_watcher(broadcaster, &on_reload)
-        watcher = Vizcore::DSL::Engine.watch_file(@config.scene_file.to_s) do |definition, _changed_path|
+      def start_scene_watcher(broadcaster, definition:, &on_reload)
+        watcher = Vizcore::Server::SceneDependencyWatcher.new(scene_file: @config.scene_file.to_s, definition: definition) do |definition, _changed_path|
           definition = resolve_shader_sources(definition)
           replace_scene_catalog(definition[:scenes])
+          replace_runtime_globals(globals_for(definition))
+          @tap_tempo_key = tap_tempo_key(definition)
           scene = first_scene(definition) || fallback_scene
           broadcaster.update_transition_definition(
             scenes: Array(definition[:scenes]),
             transitions: Array(definition[:transitions])
           )
+          broadcaster.update_analysis_settings(
+            audio_normalize: audio_normalize_settings(definition),
+            bpm: bpm_setting(definition),
+            bpm_lock: bpm_lock_setting(definition)
+          )
           broadcaster.update_scene(scene_name: scene[:name], scene_layers: scene[:layers])
           on_reload&.call(definition)
           WebSocketHandler.broadcast(
             type: "config_update",
             payload: {
               scene: scene,
-              scenes: scene_names_for(definition)
+              scenes: scene_names_for(definition),
+              tap_tempo_key: @tap_tempo_key,
+              key_mappings: key_mappings_for(definition),
+              globals: runtime_globals_snapshot
             }
           )
           @output.puts("Scene reloaded: #{scene[:name]}")
@@ -216,6 +316,53 @@ module Vizcore
         nil
       end
 
+      def start_osc_runtime(broadcaster)
+        return nil unless @config.osc_port
+
+        receiver = Vizcore::Sync::OscReceiver.new(
+          host: @config.host,
+          port: @config.osc_port,
+          handler: ->(message) { handle_osc_message(message, broadcaster) },
+          error_reporter: ->(message) { @output.puts(message) }
+        )
+        receiver.start
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "OSC runtime disabled"))
+        receiver&.stop
+        nil
+      end
+
+      def stop_osc_runtime(runtime)
+        runtime&.stop
+        nil
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "OSC runtime shutdown failed"))
+        nil
+      end
+
+      def handle_osc_message(message, broadcaster)
+        case message.address
+        when "/vizcore/scene"
+          switch_scene_from_client(message.arguments.first, broadcaster, source: "osc")
+        when "/vizcore/tap"
+          apply_tap_tempo({ "client_tapped_at_ms" => wall_clock_ms }, broadcaster)
+        when "/vizcore/bpm"
+          apply_osc_bpm(message.arguments.first, broadcaster)
+        when "/vizcore/bpm_unlock"
+          apply_osc_bpm_unlock(broadcaster)
+        when %r{\A/vizcore/global/([^/]+)\z}
+          apply_osc_global(Regexp.last_match(1), message.arguments.first)
+        when %r{\A/vizcore/live/(blackout|freeze)\z}
+          apply_osc_live_control(Regexp.last_match(1), message.arguments.first)
+        when "/vizcore/transport/play", "/vizcore/transport/position"
+          apply_osc_transport(broadcaster, playing: true, position_seconds: message.arguments.first)
+        when "/vizcore/transport/stop"
+          apply_osc_transport(broadcaster, playing: false, position_seconds: message.arguments.first)
+        end
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "OSC control message failed"))
+      end
+
       def handle_midi_event(executor, event, broadcaster)
         actions = executor.handle_event(event)
         actions.each do |action|
@@ -226,17 +373,19 @@ module Vizcore
       end
 
       def register_client_message_handler(broadcaster)
-        Vizcore::Server::WebSocketHandler.on_message do |message|
-          handle_client_message(message, broadcaster)
+        Vizcore::Server::WebSocketHandler.on_message do |message, socket|
+          handle_client_message(message, broadcaster, socket)
         end
       end
 
-      def handle_client_message(message, broadcaster)
+      def handle_client_message(message, broadcaster, socket = nil)
         type = message["type"] || message[:type]
         payload = message["payload"] || message[:payload]
         case type.to_s
+        when "latency_probe"
+          respond_to_latency_probe(socket, payload)
         when "transport_sync"
-          return unless @config.audio_source == :file
+          return unless file_transport_enabled?
 
           values = Hash(payload)
           broadcaster.sync_transport(
@@ -247,11 +396,28 @@ module Vizcore
           values = Hash(payload)
           target_name = values.fetch("scene", values.fetch(:scene, values.fetch("scene_name", values.fetch(:scene_name, nil))))
           switch_scene_from_client(target_name, broadcaster)
+        when "tap_tempo"
+          apply_tap_tempo(payload, broadcaster)
         end
       rescue StandardError => e
         @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "Client control message failed"))
       end
 
+      def respond_to_latency_probe(socket, payload)
+        return unless socket
+
+        received_at_ms = wall_clock_ms
+        values = Hash(payload)
+        response = {
+          server_received_at_ms: received_at_ms,
+          server_sent_at_ms: wall_clock_ms
+        }
+        client_sent_at_ms = finite_float(values["client_sent_at_ms"] || values[:client_sent_at_ms])
+        response[:client_sent_at_ms] = client_sent_at_ms if client_sent_at_ms
+
+        WebSocketHandler.send_to(socket, type: "latency_probe", payload: response)
+      end
+
       def apply_midi_action(action, executor, broadcaster)
         case action[:type]
         when :switch_scene
@@ -287,11 +453,59 @@ module Vizcore
           enabled: !Array(definition[:midi_maps]).empty?,
           midi_maps: Array(definition[:midi_maps]),
           scenes: Array(definition[:scenes]),
-          globals: Hash(definition[:globals] || {}),
+          globals: globals_for(definition),
           device: midi_inputs.first&.dig(:options, :device)
         }
       end
 
+      def globals_for(definition)
+        Hash(definition[:globals] || {})
+      rescue StandardError
+        {}
+      end
+
+      def replace_runtime_globals(values)
+        @runtime_globals_mutex.synchronize do
+          @runtime_globals = normalize_runtime_globals(values)
+        end
+      end
+
+      def set_runtime_global(name, value)
+        key = name.to_s.strip
+        return runtime_globals_snapshot if key.empty?
+
+        @runtime_globals_mutex.synchronize do
+          @runtime_globals[key] = value
+          @runtime_globals.dup
+        end
+      end
+
+      def runtime_globals_snapshot
+        @runtime_globals_mutex.synchronize { @runtime_globals.dup }
+      end
+
+      def normalize_runtime_globals(values)
+        Hash(values || {}).each_with_object({}) do |(key, value), output|
+          name = key.to_s.strip
+          output[name] = value unless name.empty?
+        end
+      rescue StandardError
+        {}
+      end
+
+      def key_mappings_for(definition)
+        Array(definition[:key_mappings]).map do |mapping|
+          key = mapping[:key] || mapping["key"]
+          action = mapping[:action] || mapping["action"]
+          {
+            key: key.to_s,
+            action: action
+          }
+        end
+      rescue StandardError
+        []
+      end
+
       def resolve_shader_sources(definition)
         @shader_source_resolver.resolve(definition: definition, scene_file: @config.scene_file.to_s)
       end
@@ -316,7 +530,128 @@ module Vizcore
         []
       end
 
-      def switch_scene_from_client(target_name, broadcaster)
+      def audio_normalize_settings(definition)
+        Hash(definition[:analysis] || {})[:audio_normalize]
+      rescue StandardError
+        nil
+      end
+
+      def bpm_setting(definition)
+        @config.bpm || Hash(definition[:analysis] || {})[:bpm]
+      rescue StandardError
+        @config.bpm
+      end
+
+      def bpm_lock_setting(definition)
+        @config.bpm_lock? || !!Hash(definition[:analysis] || {})[:bpm_lock]
+      rescue StandardError
+        @config.bpm_lock?
+      end
+
+      def tap_tempo_key(definition)
+        settings = Hash(definition.dig(:analysis, :tap_tempo) || {})
+        key = settings[:key] || settings["key"]
+        key.to_s unless key.nil? || key.to_s.empty?
+      rescue StandardError
+        nil
+      end
+
+      def apply_tap_tempo(payload, broadcaster)
+        return unless @tap_tempo_key
+
+        values = Hash(payload)
+        tapped_at_ms = finite_float(values["client_tapped_at_ms"] || values[:client_tapped_at_ms]) || wall_clock_ms
+        bpm = broadcaster.tap_tempo(timestamp_ms: tapped_at_ms)
+        return unless bpm
+
+        WebSocketHandler.broadcast(
+          type: "config_update",
+          payload: {
+            bpm: bpm,
+            bpm_lock: true,
+            source: "tap_tempo"
+          }
+        )
+      end
+
+      def apply_osc_bpm(value, broadcaster)
+        bpm = finite_float(value)
+        return unless bpm&.positive?
+        return unless broadcaster.respond_to?(:lock_bpm)
+
+        locked_bpm = broadcaster.lock_bpm(bpm)
+        return unless locked_bpm
+
+        WebSocketHandler.broadcast(
+          type: "config_update",
+          payload: {
+            bpm: locked_bpm,
+            bpm_lock: true,
+            source: "osc"
+          }
+        )
+      end
+
+      def apply_osc_bpm_unlock(broadcaster)
+        return unless broadcaster.respond_to?(:unlock_bpm)
+
+        broadcaster.unlock_bpm
+        WebSocketHandler.broadcast(
+          type: "config_update",
+          payload: {
+            bpm_lock: false,
+            source: "osc"
+          }
+        )
+      end
+
+      def apply_osc_global(name, value)
+        globals = set_runtime_global(name, normalize_osc_value(value))
+        WebSocketHandler.broadcast(
+          type: "config_update",
+          payload: {
+            globals: globals,
+            source: "osc"
+          }
+        )
+      end
+
+      def apply_osc_live_control(control, value)
+        @live_controls[control] = osc_truthy?(value)
+        WebSocketHandler.broadcast(
+          type: "config_update",
+          payload: {
+            live_controls: @live_controls.dup,
+            source: "osc"
+          }
+        )
+      end
+
+      def apply_osc_transport(broadcaster, playing:, position_seconds:)
+        return unless file_transport_enabled?
+
+        broadcaster.sync_transport(
+          playing: playing,
+          position_seconds: finite_float(position_seconds) || 0.0
+        )
+      end
+
+      def normalize_osc_value(value)
+        numeric = finite_float(value)
+        numeric.nil? ? value : numeric
+      end
+
+      def osc_truthy?(value)
+        return true if value.nil?
+        return value if value == true || value == false
+
+        numeric = finite_float(value)
+        return numeric.positive? unless numeric.nil?
+
+        %w[true on yes 1].include?(value.to_s.strip.downcase)
+      end
+
+      def switch_scene_from_client(target_name, broadcaster, source: "ui")
         requested = target_name.to_s.strip
         return if requested.empty?
 
@@ -332,7 +667,7 @@ module Vizcore
             from: from_scene.to_s,
             to: target_scene[:name].to_s,
             effect: nil,
-            source: "ui"
+            source: source
           }
         )
       end
@@ -352,6 +687,19 @@ module Vizcore
       rescue StandardError
         nil
       end
+
+      def wall_clock_ms
+        Time.now.to_f * 1000.0
+      end
+
+      def finite_float(value)
+        numeric = Float(value)
+        return nil unless numeric.finite?
+
+        numeric
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/vizcore/server/scene_dependency_watcher.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../dsl"
+
+module Vizcore
+  module Server
+    # Watches a scene file and the custom GLSL files referenced by that scene.
+    class SceneDependencyWatcher
+      # @param scene_file [String, Pathname]
+      # @param definition [Hash] current scene definition
+      # @param watcher_factory [Class] file watcher class or compatible factory
+      # @yieldparam definition [Hash] reloaded scene definition
+      # @yieldparam changed_path [Pathname] changed scene or shader file
+      def initialize(scene_file:, definition:, watcher_factory: Vizcore::DSL::FileWatcher, &on_change)
+        @scene_file = Pathname.new(scene_file.to_s).expand_path
+        @definition = definition
+        @watcher_factory = watcher_factory
+        @on_change = on_change
+        @scene_watcher = nil
+        @shader_watchers = []
+      end
+
+      # @return [Vizcore::Server::SceneDependencyWatcher]
+      def start
+        @scene_watcher = build_watcher(@scene_file)
+        @scene_watcher.start
+        refresh_shader_watchers(@definition)
+        self
+      end
+
+      # @param timeout [Float]
+      # @return [void]
+      def stop(timeout: 1.0)
+        @scene_watcher&.stop(timeout: timeout)
+        stop_shader_watchers(timeout: timeout)
+      end
+
+      private
+
+      def build_watcher(path)
+        @watcher_factory.new(path: path) do |changed_path|
+          definition = Vizcore::DSL::Engine.load_file(@scene_file.to_s)
+          @on_change&.call(definition, changed_path)
+          @definition = definition
+          refresh_shader_watchers(definition)
+        end
+      end
+
+      def refresh_shader_watchers(definition)
+        paths = shader_paths(definition)
+        stop_shader_watchers
+        @shader_watchers = paths.map do |path|
+          build_watcher(path).tap(&:start)
+        end
+      end
+
+      def stop_shader_watchers(timeout: 1.0)
+        @shader_watchers.each { |watcher| watcher.stop(timeout: timeout) }
+        @shader_watchers = []
+      end
+
+      def shader_paths(definition)
+        Array(definition[:scenes]).flat_map do |scene|
+          Array(scene[:layers]).filter_map { |layer| shader_path(layer) }
+        end.uniq
+      end
+
+      def shader_path(layer)
+        glsl = layer[:glsl] || layer["glsl"]
+        return nil unless glsl
+
+        path = Pathname.new(glsl.to_s)
+        path = @scene_file.dirname.join(path) unless path.absolute?
+        path.expand_path
+      end
+    end
+  end
+end