vizcore 0.1.0

data/lib/vizcore/server/frame_broadcaster.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+require_relative "../audio"
+require_relative "../analysis"
+require_relative "../dsl"
+require_relative "../errors"
+require_relative "../renderer"
+
+module Vizcore
+  module Server
+    # Produces audio-reactive frame payloads and broadcasts them over WebSocket.
+    class FrameBroadcaster
+      # Target broadcast frame rate.
+      FRAME_RATE = 60.0
+
+      # @param scene_name [String]
+      # @param scene_layers [Array<Hash>, nil]
+      # @param input_manager [Vizcore::Audio::InputManager, nil]
+      # @param analysis_pipeline [Vizcore::Analysis::Pipeline, nil]
+      # @param mapping_resolver [Vizcore::DSL::MappingResolver, nil]
+      # @param scene_serializer [Vizcore::Renderer::SceneSerializer, nil]
+      # @param frame_scheduler [Vizcore::Renderer::FrameScheduler, nil]
+      # @param scene_catalog [Array<Hash>, nil]
+      # @param transitions [Array<Hash>, nil]
+      # @param transition_controller [Vizcore::DSL::TransitionController, nil]
+      # @param error_reporter [#call, nil]
+      def initialize(
+        scene_name: "basic",
+        scene_layers: nil,
+        input_manager: nil,
+        analysis_pipeline: nil,
+        mapping_resolver: nil,
+        scene_serializer: nil,
+        frame_scheduler: nil,
+        scene_catalog: nil,
+        transitions: nil,
+        transition_controller: nil,
+        error_reporter: nil
+      )
+        @scene_name = scene_name
+        @scene_layers = Array(scene_layers)
+        @scene_mutex = Mutex.new
+        @input_manager = input_manager || Vizcore::Audio::InputManager.new(source: :mic)
+        fft_size = supported_fft_size(@input_manager.frame_size)
+        @analysis_pipeline = analysis_pipeline || Vizcore::Analysis::Pipeline.new(
+          sample_rate: @input_manager.sample_rate,
+          fft_size: fft_size
+        )
+        @mapping_resolver = mapping_resolver || Vizcore::DSL::MappingResolver.new
+        @scene_serializer = scene_serializer || Vizcore::Renderer::SceneSerializer.new
+        @transition_controller = transition_controller || Vizcore::DSL::TransitionController.new(
+          scenes: scene_catalog || [],
+          transitions: transitions || []
+        )
+        @error_reporter = error_reporter || ->(_message) {}
+        @last_error = nil
+        @frame_count = 0
+        @transport_playing = initial_transport_playing_state
+        reset_transition_trigger_counters!
+        @frame_scheduler = frame_scheduler || Vizcore::Renderer::FrameScheduler.new(frame_rate: FRAME_RATE) do |elapsed|
+          tick(elapsed)
+        end
+      end
+
+      attr_reader :last_error
+
+      # @return [void]
+      def start
+        return if running?
+
+        @input_manager.start
+        @frame_scheduler.start
+      rescue StandardError => e
+        report_error(e, context: "frame broadcaster start failed")
+        @input_manager.stop
+        raise
+      end
+
+      # @return [void]
+      def stop
+        return unless running?
+
+        @frame_scheduler.stop
+        @input_manager.stop
+      end
+
+      # @return [Boolean]
+      def running?
+        @frame_scheduler.running?
+      end
+
+      # @return [Hash] current scene snapshot (`name`, `layers`)
+      def current_scene_snapshot
+        current_scene
+      end
+
+      # Synchronize external playback transport (e.g. browser audio element) with the input source.
+      #
+      # @param playing [Boolean]
+      # @param position_seconds [Numeric]
+      # @return [void]
+      def sync_transport(playing:, position_seconds:)
+        @scene_mutex.synchronize do
+          @transport_playing = !!playing
+          reset_transition_trigger_counters! if transport_position_reset?(position_seconds)
+        end
+        return unless @input_manager.respond_to?(:sync_transport)
+
+        @input_manager.sync_transport(playing: playing, position_seconds: position_seconds)
+      rescue StandardError => e
+        report_error(e, context: "audio transport sync failed")
+      end
+
+      # Run one frame tick and broadcast it.
+      #
+      # @param elapsed_seconds [Float]
+      # @param samples [Array<Float>, nil]
+      # @return [Hash] serialized frame
+      def tick(elapsed_seconds, samples = nil)
+        @frame_count += 1
+        frame = build_frame(elapsed_seconds, samples)
+        WebSocketHandler.broadcast(type: "audio_frame", payload: frame)
+        evaluate_transition(frame[:audio], frame_count: @frame_count)
+        frame
+      end
+
+      # Replace active scene and layers.
+      #
+      # @param scene_name [String, Symbol]
+      # @param scene_layers [Array<Hash>]
+      # @return [void]
+      def update_scene(scene_name:, scene_layers:)
+        @scene_mutex.synchronize do
+          @scene_name = scene_name.to_s
+          @scene_layers = Array(scene_layers)
+          reset_transition_trigger_counters!
+        end
+      end
+
+      # Replace transition catalog used by automatic scene switching.
+      #
+      # @param scenes [Array<Hash>]
+      # @param transitions [Array<Hash>]
+      # @return [void]
+      def update_transition_definition(scenes:, transitions:)
+        @scene_mutex.synchronize do
+          @transition_controller.update(scenes: scenes, transitions: transitions)
+        end
+      end
+
+      # Build one frame payload for transport to frontend.
+      #
+      # @param _elapsed_seconds [Float]
+      # @param samples [Array<Float>, nil]
+      # @raise [Vizcore::FrameBuildError] when frame construction fails
+      # @return [Hash]
+      def build_frame(_elapsed_seconds, samples = nil)
+        audio_samples = samples || capture_samples
+        analyzed = @analysis_pipeline.call(audio_samples)
+        scene = current_scene
+        layers = build_scene_layers(scene[:layers], analyzed)
+
+        @scene_serializer.audio_frame(
+          timestamp: Time.now.to_f,
+          audio: analyzed,
+          scene_name: scene[:name],
+          scene_layers: layers,
+          transition: nil
+        )
+      rescue StandardError => e
+        report_error(e, context: "frame build failed")
+        raise Vizcore::FrameBuildError, Vizcore::ErrorFormatting.summarize(e, context: "Frame build failed")
+      end
+
+      private
+
+      def capture_samples
+        ingest_count =
+          if @input_manager.respond_to?(:realtime_capture_size)
+            @input_manager.realtime_capture_size(FRAME_RATE)
+          else
+            @input_manager.frame_size
+          end
+
+        @input_manager.capture_frame(ingest_count)
+        samples = Array(@input_manager.latest_samples(@input_manager.frame_size))
+        return samples if samples.length == @input_manager.frame_size
+        return Array.new(@input_manager.frame_size, 0.0) if samples.empty?
+
+        Array.new(@input_manager.frame_size - samples.length, 0.0) + samples
+      rescue StandardError => e
+        report_error(e, context: "audio capture failed")
+        fallback_frame_size = @input_manager.respond_to?(:frame_size) ? Integer(@input_manager.frame_size) : 1024
+        Array.new(fallback_frame_size, 0.0)
+      end
+
+      def supported_fft_size(size)
+        value = Integer(size)
+        return value if power_of_two?(value)
+
+        1024
+      rescue StandardError
+        1024
+      end
+
+      def power_of_two?(value)
+        value.positive? && (value & (value - 1)).zero?
+      end
+
+      def build_scene_layers(scene_layers, analyzed)
+        return default_scene_layers(analyzed) if scene_layers.empty?
+
+        @mapping_resolver.resolve_layers(scene_layers: scene_layers, audio: analyzed)
+      end
+
+      def default_scene_layers(analyzed)
+        amplitude = analyzed[:amplitude]
+        high = analyzed.dig(:bands, :high).to_f
+
+        [
+          {
+            name: "wireframe_cube",
+            type: "geometry",
+            params: {
+              rotation_speed: (0.4 + amplitude * 1.5).round(4),
+              color_shift: high.round(4)
+            }
+          }
+        ]
+      end
+
+      def current_scene
+        @scene_mutex.synchronize do
+          {
+            name: @scene_name,
+            layers: Array(@scene_layers)
+          }
+        end
+      end
+
+      def evaluate_transition(audio, frame_count:)
+        return if transition_evaluation_paused?
+
+        transition = @scene_mutex.synchronize do
+          scene = {
+            name: @scene_name,
+            layers: Array(@scene_layers)
+          }
+          trigger_frame_count, trigger_audio = transition_trigger_inputs(
+            scene_name: scene[:name],
+            audio: audio,
+            frame_count: frame_count
+          )
+          @transition_controller.next_transition(
+            scene_name: scene[:name],
+            audio: trigger_audio,
+            frame_count: trigger_frame_count
+          )
+        end
+        return unless transition
+
+        update_scene(scene_name: transition[:to], scene_layers: transition.dig(:scene, :layers))
+        WebSocketHandler.broadcast(
+          type: "scene_change",
+          payload: {
+            from: transition[:from].to_s,
+            to: transition[:to].to_s,
+            effect: transition[:effect]
+          }
+        )
+      end
+
+      def reset_transition_trigger_counters!
+        @transition_counter_scene_name = nil
+        @transition_counter_frame_base = 0
+        @transition_counter_beat_base = 0
+      end
+
+      def transition_evaluation_paused?
+        @scene_mutex.synchronize { file_transport_source? && !@transport_playing }
+      end
+
+      def initial_transport_playing_state
+        file_transport_source? ? false : true
+      end
+
+      def file_transport_source?
+        return false unless @input_manager.is_a?(Vizcore::Audio::InputManager)
+
+        @input_manager.source_name.to_sym == :file
+      rescue StandardError
+        false
+      end
+
+      def transport_position_reset?(position_seconds)
+        Float(position_seconds) <= 0.05
+      rescue StandardError
+        false
+      end
+
+      def transition_trigger_inputs(scene_name:, audio:, frame_count:)
+        sync_transition_trigger_counters(scene_name: scene_name, audio: audio, frame_count: frame_count)
+
+        global_frame_count = Integer(frame_count)
+        scene_frame_count = [global_frame_count - @transition_counter_frame_base, 0].max
+
+        audio_hash = Hash(audio)
+        global_beat_count = extract_beat_count(audio_hash)
+        scene_beat_count = [global_beat_count - @transition_counter_beat_base, 0].max
+
+        [scene_frame_count, audio_hash.merge(beat_count: scene_beat_count)]
+      rescue StandardError
+        [0, { beat_count: 0 }]
+      end
+
+      def sync_transition_trigger_counters(scene_name:, audio:, frame_count:)
+        normalized_scene_name = scene_name.to_s
+        return if @transition_counter_scene_name == normalized_scene_name
+
+        audio_hash = Hash(audio)
+        global_frame_count = Integer(frame_count)
+        global_beat_count = extract_beat_count(audio_hash)
+
+        @transition_counter_scene_name = normalized_scene_name
+        @transition_counter_frame_base = [global_frame_count - 1, 0].max
+        # Include the current frame's beat in the new scene-local counter when a beat is detected.
+        @transition_counter_beat_base = global_beat_count - (truthy_audio_beat?(audio_hash) ? 1 : 0)
+      rescue StandardError
+        reset_transition_trigger_counters!
+      end
+
+      def extract_beat_count(audio)
+        Integer(audio[:beat_count] || audio["beat_count"] || 0)
+      rescue StandardError
+        0
+      end
+
+      def truthy_audio_beat?(audio)
+        !!(audio[:beat] || audio["beat"])
+      end
+
+      def report_error(error, context:)
+        @last_error = error
+        @error_reporter.call(Vizcore::ErrorFormatting.summarize(error, context: context))
+      rescue StandardError
+        nil
+      end
+
+    end
+  end
+end

data/lib/vizcore/server/rack_app.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "rack"
+require_relative "websocket_handler"
+
+module Vizcore
+  module Server
+    # Rack app serving frontend assets, health endpoint, and WebSocket upgrade.
+    class RackApp
+      AUDIO_FILE_PATH = "/audio-file"
+      RUNTIME_PATH = "/runtime"
+
+      # @param frontend_root [Pathname]
+      # @param websocket_path [String]
+      # @param audio_source [Symbol, String, nil]
+      # @param audio_file [String, Pathname, nil]
+      # @param scene_names [Array<String, Symbol>, nil]
+      def initialize(frontend_root:, websocket_path: "/ws", audio_source: nil, audio_file: nil, scene_names: nil)
+        @frontend_root = frontend_root.expand_path
+        @websocket_path = websocket_path
+        @audio_source = audio_source&.to_sym
+        @audio_file = audio_file ? Pathname.new(audio_file).expand_path : nil
+        @scene_names = normalize_scene_names(scene_names)
+      end
+
+      # @param env [Hash]
+      # @return [Array(Integer, Hash, Array<String>)]
+      def call(env)
+        request = Rack::Request.new(env)
+
+        return WebSocketHandler.call(env) if request.path_info == @websocket_path
+        return health_response if request.path_info == "/health"
+        return runtime_response if request.path_info == RUNTIME_PATH
+        return audio_file_response(request) if request.path_info == AUDIO_FILE_PATH
+
+        serve_static(request.path_info)
+      end
+
+      private
+
+      def health_response
+        body = JSON.generate(status: "ok", websocket_clients: WebSocketHandler.connection_count)
+        [200, json_headers.merge("content-length" => body.bytesize.to_s), [body]]
+      end
+
+      def runtime_response
+        payload = {
+          status: "ok",
+          audio_source: (@audio_source || :unknown).to_s,
+          audio_file_name: nil,
+          audio_file_url: nil,
+          scene_names: @scene_names
+        }
+
+        if audio_file_available?
+          payload[:audio_file_name] = @audio_file.basename.to_s
+          payload[:audio_file_url] = AUDIO_FILE_PATH
+        end
+
+        body = JSON.generate(payload)
+        [200, json_headers.merge("content-length" => body.bytesize.to_s), [body]]
+      end
+
+      def audio_file_response(request)
+        return not_found_response unless audio_file_available?
+
+        file_size = @audio_file.size
+        range = parse_byte_range(request.get_header("HTTP_RANGE"), file_size)
+        return range_not_satisfiable_response(file_size) if range == :invalid
+
+        if range
+          byte_start, byte_end = range
+          length = byte_end - byte_start + 1
+          body = File.binread(@audio_file, length, byte_start)
+          return [
+            206,
+            audio_headers(content_length: body.bytesize).merge("content-range" => "bytes #{byte_start}-#{byte_end}/#{file_size}"),
+            [body]
+          ]
+        end
+
+        body = File.binread(@audio_file)
+        [200, audio_headers(content_length: body.bytesize), [body]]
+      end
+
+      def serve_static(path_info)
+        path = path_info == "/" ? "index.html" : path_info.delete_prefix("/")
+        full_path = File.expand_path(path, @frontend_root.to_s)
+
+        return not_found_response unless full_path.start_with?(@frontend_root.to_s)
+        return not_found_response unless File.file?(full_path)
+
+        body = File.binread(full_path)
+        headers = {
+          "content-type" => Rack::Mime.mime_type(File.extname(full_path), "text/plain"),
+          "content-length" => body.bytesize.to_s,
+          "cache-control" => "no-store, max-age=0, must-revalidate"
+        }
+        [200, headers, [body]]
+      end
+
+      def not_found_response
+        [404, text_headers.merge("content-length" => "9"), ["Not Found"]]
+      end
+
+      def text_headers
+        { "content-type" => "text/plain; charset=utf-8" }
+      end
+
+      def json_headers
+        { "content-type" => "application/json; charset=utf-8" }
+      end
+
+      def audio_file_available?
+        @audio_source == :file && @audio_file && @audio_file.file?
+      end
+
+      def audio_headers(content_length:)
+        {
+          "content-type" => Rack::Mime.mime_type(@audio_file.extname, "application/octet-stream"),
+          "content-length" => content_length.to_s,
+          "cache-control" => "no-store, max-age=0, must-revalidate",
+          "accept-ranges" => "bytes"
+        }
+      end
+
+      def normalize_scene_names(values)
+        Array(values).filter_map do |entry|
+          name = entry.to_s.strip
+          next if name.empty?
+
+          name
+        end.uniq
+      rescue StandardError
+        []
+      end
+
+      def parse_byte_range(raw_range, file_size)
+        range_value = raw_range.to_s.strip
+        return nil if range_value.empty?
+        return :invalid unless range_value.start_with?("bytes=")
+        return :invalid if file_size <= 0
+
+        match = /\Abytes=(\d*)-(\d*)\z/.match(range_value)
+        return :invalid unless match
+
+        start_part = match[1]
+        end_part = match[2]
+
+        if start_part.empty?
+          return :invalid if end_part.empty?
+
+          suffix_length = Integer(end_part)
+          return :invalid unless suffix_length.positive?
+
+          return [0, file_size - 1] if suffix_length >= file_size
+
+          return [file_size - suffix_length, file_size - 1]
+        end
+
+        start_offset = Integer(start_part)
+        return :invalid if start_offset.negative? || start_offset >= file_size
+
+        if end_part.empty?
+          return [start_offset, file_size - 1]
+        end
+
+        end_offset = Integer(end_part)
+        return :invalid if end_offset < start_offset
+
+        [start_offset, [end_offset, file_size - 1].min]
+      rescue StandardError
+        :invalid
+      end
+
+      def range_not_satisfiable_response(file_size)
+        [416, text_headers.merge("content-range" => "bytes */#{file_size}", "content-length" => "0"), []]
+      end
+    end
+  end
+end