vizcore 0.1.0

data/lib/vizcore/server/runner.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require "puma"
+require_relative "../config"
+require_relative "../dsl"
+require_relative "../errors"
+require_relative "frame_broadcaster"
+require_relative "rack_app"
+require_relative "websocket_handler"
+
+module Vizcore
+  module Server
+    # Bootstraps Rack/Puma, audio pipeline, scene reload, and MIDI runtime.
+    class Runner
+      # @param config [Vizcore::Config]
+      # @param output [#puts]
+      def initialize(config, output: $stdout)
+        @config = config
+        @output = output
+        @shader_source_resolver = Vizcore::DSL::ShaderSourceResolver.new
+        @scene_catalog_mutex = Mutex.new
+        @scene_catalog = []
+      end
+
+      # Run server lifecycle until interrupted.
+      #
+      # @raise [Vizcore::ConfigurationError]
+      # @raise [Vizcore::SceneLoadError]
+      # @return [void]
+      def run
+        validate_scene_file!
+        validate_audio_settings!
+        definition = load_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)
+        )
+        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
+        )
+        broadcaster = FrameBroadcaster.new(
+          scene_name: scene[:name].to_s,
+          scene_layers: scene[:layers],
+          scene_catalog: definition[:scenes],
+          transitions: definition[:transitions],
+          input_manager: input_manager,
+          error_reporter: ->(message) { @output.puts(message) }
+        )
+        replace_scene_catalog(definition[:scenes])
+        if @config.audio_source == :file
+          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
+
+        @output.puts("Vizcore server listening at http://#{@config.host}:#{@config.port}")
+        @output.puts("Scene: #{scene[:name]}")
+        @output.puts("Audio playback: http://#{@config.host}:#{@config.port}/audio-file") if @config.audio_source == :file
+        @output.puts("Press Ctrl+C to stop.")
+
+        wait_for_interrupt
+      ensure
+        Vizcore::Server::WebSocketHandler.clear_message_handler
+        stop_midi_runtime(midi_runtime)
+        watcher&.stop
+        broadcaster&.stop
+        server&.stop(true)
+      end
+
+      private
+
+      def validate_scene_file!
+        return if @config.scene_exists?
+
+        message = if @config.scene_file
+                    "Scene file not found: #{@config.scene_file}"
+                  else
+                    "Scene file is required"
+                  end
+
+        raise Vizcore::ConfigurationError, message
+      end
+
+      def load_definition!
+        raw_definition = Vizcore::DSL::Engine.load_file(@config.scene_file.to_s)
+        resolve_shader_sources(raw_definition)
+      rescue StandardError => e
+        raise Vizcore::SceneLoadError, Vizcore::ErrorFormatting.summarize(
+          e,
+          context: "Failed to load scene file #{@config.scene_file}"
+        )
+      end
+
+      def validate_audio_settings!
+        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 wait_for_interrupt
+        stop_requested = false
+        %w[INT TERM].each do |signal_name|
+          Signal.trap(signal_name) { stop_requested = true }
+        rescue ArgumentError
+          nil
+        end
+        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|
+          definition = resolve_shader_sources(definition)
+          replace_scene_catalog(definition[:scenes])
+          scene = first_scene(definition) || fallback_scene
+          broadcaster.update_transition_definition(
+            scenes: Array(definition[:scenes]),
+            transitions: Array(definition[:transitions])
+          )
+          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)
+            }
+          )
+          @output.puts("Scene reloaded: #{scene[:name]}")
+        rescue StandardError => e
+          @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "Scene reload failed"))
+        end
+        watcher.start
+        watcher
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "Scene watcher disabled"))
+        nil
+      end
+
+      def first_scene(definition)
+        definition.fetch(:scenes, []).first
+      end
+
+      def fallback_scene
+        {
+          name: @config.scene_file.basename(".rb").to_sym,
+          layers: []
+        }
+      end
+
+      def start_midi_runtime(definition, broadcaster)
+        settings = midi_runtime_settings(definition)
+        return nil unless settings[:enabled]
+
+        midi_input = Vizcore::Audio::MidiInput.new(device: settings[:device])
+        executor = Vizcore::DSL::MidiMapExecutor.new(
+          midi_maps: settings[:midi_maps],
+          scenes: settings[:scenes],
+          globals: settings[:globals]
+        )
+        midi_input.start { |event| handle_midi_event(executor, event, broadcaster) }
+        @output.puts("MIDI mapping enabled#{settings[:device] ? " (device=#{settings[:device]})" : ""}")
+
+        {
+          input: midi_input,
+          executor: executor,
+          device: settings[:device]
+        }
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "MIDI runtime disabled"))
+        midi_input&.stop
+        nil
+      end
+
+      def refresh_midi_runtime(runtime, definition, broadcaster)
+        settings = midi_runtime_settings(definition)
+        return stop_midi_runtime(runtime) unless settings[:enabled]
+        return start_midi_runtime(definition, broadcaster) unless runtime
+
+        if runtime[:device] != settings[:device]
+          stop_midi_runtime(runtime)
+          return start_midi_runtime(definition, broadcaster)
+        end
+
+        runtime[:executor].update(
+          midi_maps: settings[:midi_maps],
+          scenes: settings[:scenes],
+          globals: settings[:globals]
+        )
+        runtime
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "MIDI runtime update failed"))
+        runtime
+      end
+
+      def stop_midi_runtime(runtime)
+        return nil unless runtime
+
+        runtime[:input]&.stop
+        nil
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "MIDI runtime shutdown failed"))
+        nil
+      end
+
+      def handle_midi_event(executor, event, broadcaster)
+        actions = executor.handle_event(event)
+        actions.each do |action|
+          apply_midi_action(action, executor, broadcaster)
+        end
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "MIDI action failed"))
+      end
+
+      def register_client_message_handler(broadcaster)
+        Vizcore::Server::WebSocketHandler.on_message do |message|
+          handle_client_message(message, broadcaster)
+        end
+      end
+
+      def handle_client_message(message, broadcaster)
+        type = message["type"] || message[:type]
+        payload = message["payload"] || message[:payload]
+        case type.to_s
+        when "transport_sync"
+          return unless @config.audio_source == :file
+
+          values = Hash(payload)
+          broadcaster.sync_transport(
+            playing: values.fetch("playing", values.fetch(:playing, false)),
+            position_seconds: values.fetch("position_seconds", values.fetch(:position_seconds, 0.0))
+          )
+        when "switch_scene"
+          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)
+        end
+      rescue StandardError => e
+        @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "Client control message failed"))
+      end
+
+      def apply_midi_action(action, executor, broadcaster)
+        case action[:type]
+        when :switch_scene
+          target_scene = action[:scene]
+          return unless target_scene
+
+          current = broadcaster.current_scene_snapshot
+          from_scene = current[:name]
+          broadcaster.update_scene(scene_name: target_scene[:name], scene_layers: target_scene[:layers])
+          WebSocketHandler.broadcast(
+            type: "scene_change",
+            payload: {
+              from: from_scene.to_s,
+              to: target_scene[:name].to_s,
+              effect: action[:effect],
+              source: "midi"
+            }
+          )
+        when :set_global
+          WebSocketHandler.broadcast(
+            type: "config_update",
+            payload: {
+              globals: executor.globals
+            }
+          )
+        end
+      end
+
+      def midi_runtime_settings(definition)
+        midi_inputs = Array(definition[:midi])
+
+        {
+          enabled: !Array(definition[:midi_maps]).empty?,
+          midi_maps: Array(definition[:midi_maps]),
+          scenes: Array(definition[:scenes]),
+          globals: Hash(definition[:globals] || {}),
+          device: midi_inputs.first&.dig(:options, :device)
+        }
+      end
+
+      def resolve_shader_sources(definition)
+        @shader_source_resolver.resolve(definition: definition, scene_file: @config.scene_file.to_s)
+      end
+
+      def replace_scene_catalog(scenes)
+        @scene_catalog_mutex.synchronize do
+          @scene_catalog = Array(scenes)
+        end
+      end
+
+      def scene_names_for(definition)
+        Array(definition[:scenes]).filter_map do |scene|
+          name = scene.dig(:name) || scene["name"]
+          next if name.nil?
+
+          value = name.to_s.strip
+          next if value.empty?
+
+          value
+        end
+      rescue StandardError
+        []
+      end
+
+      def switch_scene_from_client(target_name, broadcaster)
+        requested = target_name.to_s.strip
+        return if requested.empty?
+
+        target_scene = find_scene_catalog_scene(requested)
+        return unless target_scene
+
+        current = broadcaster.current_scene_snapshot
+        from_scene = current[:name]
+        broadcaster.update_scene(scene_name: target_scene[:name], scene_layers: target_scene[:layers])
+        WebSocketHandler.broadcast(
+          type: "scene_change",
+          payload: {
+            from: from_scene.to_s,
+            to: target_scene[:name].to_s,
+            effect: nil,
+            source: "ui"
+          }
+        )
+      end
+
+      def find_scene_catalog_scene(name)
+        @scene_catalog_mutex.synchronize do
+          Array(@scene_catalog).each do |scene|
+            raw_name = scene.dig(:name) || scene["name"]
+            next unless raw_name
+            next unless raw_name.to_s == name
+
+            layers = scene.dig(:layers) || scene["layers"]
+            return { name: raw_name.to_sym, layers: Array(layers) }
+          end
+          nil
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/vizcore/server/websocket_handler.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+require "thread"
+require_relative "../errors"
+
+module Vizcore
+  module Server
+    # Stateless WebSocket endpoint manager for frame broadcast transport.
+    class WebSocketHandler
+      class << self
+        # Rack endpoint for WebSocket upgrade handling.
+        #
+        # @param env [Hash]
+        # @return [Array]
+        def call(env)
+          websocket_klass = faye_websocket_class
+          return dependency_error_response unless websocket_klass
+          return [426, text_headers, ["WebSocket upgrade required"]] unless websocket_klass.websocket?(env)
+
+          socket = websocket_klass.new(env, nil, ping: 15)
+
+          socket.on(:open) { register(socket) }
+          socket.on(:close) { unregister(socket) }
+          socket.on(:message) { |event| handle_message(socket, event.data) }
+
+          socket.rack_response
+        end
+
+        # Broadcast one typed payload to all active websocket clients.
+        #
+        # @param type [String]
+        # @param payload [Hash]
+        # @return [Boolean] false when websocket backend is unavailable
+        def broadcast(type:, payload:)
+          return false unless faye_websocket_class
+
+          message = JSON.generate(type: type, payload: payload)
+
+          each_socket do |socket|
+            send_message(socket, message)
+          end
+
+          true
+        end
+
+        # @return [Integer]
+        def connection_count
+          mutex.synchronize { sockets.size }
+        end
+
+        # @return [StandardError, nil]
+        def last_error
+          mutex.synchronize { @last_error }
+        end
+
+        # Register one inbound message handler for client -> server control messages.
+        #
+        # @yieldparam message [Hash]
+        # @return [void]
+        def on_message(&block)
+          mutex.synchronize { @message_handler = block }
+        end
+
+        # Clear inbound message handler.
+        #
+        # @return [void]
+        def clear_message_handler
+          mutex.synchronize { @message_handler = nil }
+        end
+
+        private
+
+        def faye_websocket_class
+          require "faye/websocket"
+          Faye::WebSocket
+        rescue LoadError
+          nil
+        end
+
+        def send_message(socket, message)
+          if event_machine_reactor_running?
+            EventMachine.schedule { safe_send(socket, message) }
+          else
+            safe_send(socket, message)
+          end
+        end
+
+        def safe_send(socket, message)
+          socket.send(message)
+        rescue StandardError => e
+          set_last_error(e)
+          unregister(socket)
+        end
+
+        def event_machine_reactor_running?
+          require "eventmachine"
+          EventMachine.reactor_running?
+        rescue LoadError
+          false
+        end
+
+        def dependency_error_response
+          [500, json_headers, [JSON.generate(error: "Missing dependency: faye-websocket")]]
+        end
+
+        def handle_message(_socket, raw_message)
+          message = JSON.parse(raw_message)
+          dispatch_message(message)
+          message
+        rescue JSON::ParserError => e
+          set_last_error(e)
+          nil
+        end
+
+        def register(socket)
+          mutex.synchronize { sockets << socket }
+        end
+
+        def unregister(socket)
+          mutex.synchronize { sockets.delete(socket) }
+        end
+
+        def each_socket(&block)
+          snapshot = mutex.synchronize { sockets.dup }
+          snapshot.each(&block)
+        end
+
+        def sockets
+          @sockets ||= Set.new
+        end
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+
+        def set_last_error(error)
+          mutex.synchronize { @last_error = error }
+        end
+
+        def dispatch_message(message)
+          handler = mutex.synchronize { @message_handler }
+          return unless handler
+          return unless message.is_a?(Hash)
+
+          handler.call(message)
+        rescue StandardError => e
+          set_last_error(e)
+          nil
+        end
+
+        def text_headers
+          { "content-type" => "text/plain; charset=utf-8" }
+        end
+
+        def json_headers
+          { "content-type" => "application/json; charset=utf-8" }
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/server.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Rack/WebSocket server runtime namespace.
+  module Server
+  end
+end
+
+require_relative "server/frame_broadcaster"
+require_relative "server/rack_app"
+require_relative "server/runner"
+require_relative "server/websocket_handler"

data/lib/vizcore/templates/basic_scene.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# {{project_name}} starter scene.
+Vizcore.define do
+  scene :basic do
+    layer :wireframe_cube do
+      type :wireframe_cube
+    end
+  end
+end

data/lib/vizcore/templates/custom_shader_scene.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# {{project_name}} custom GLSL shader example.
+Vizcore.define do
+  scene :shader_art do
+    layer :kaleidoscope do
+      type :shader
+      glsl "../shaders/custom_wave.frag"
+      map amplitude => :param_intensity
+      map frequency_band(:low) => :param_bass
+      map beat? => :param_flash
+    end
+
+    layer :title do
+      type :text
+      content "{{project_name}}"
+      font_size 72
+      glow_strength 0.0
+      color "#f5f9ff"
+    end
+  end
+end

data/lib/vizcore/templates/custom_wave.frag

@@ -0,0 +1,31 @@
+#version 300 es
+precision mediump float;
+
+uniform vec2 u_resolution;
+uniform float u_time;
+uniform float u_amplitude;
+uniform float u_bass;
+uniform float u_param_intensity;
+uniform float u_param_bass;
+uniform float u_param_flash;
+out vec4 outColor;
+
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+  vec2 centered = uv * 2.0 - 1.0;
+  centered.x *= u_resolution.x / max(u_resolution.y, 1.0);
+
+  float intensity = max(u_param_intensity, u_amplitude);
+  float bass = max(u_param_bass, u_bass);
+  float wave = sin(centered.x * 9.0 + u_time * (2.4 + bass * 7.0));
+  float lineDistance = abs(centered.y - wave * 0.28);
+  float core = smoothstep(0.045 + intensity * 0.03, 0.0, lineDistance);
+  float halo = smoothstep(0.12 + intensity * 0.06, 0.0, lineDistance);
+
+  vec3 color = vec3(0.02, 0.03, 0.08);
+  color += vec3(0.22, 0.68, 0.92) * halo * (0.22 + intensity * 0.45);
+  color += vec3(0.50, 0.92, 1.0) * core * (0.55 + intensity * 0.55);
+  color += vec3(0.95, 0.28, 0.44) * u_param_flash * 0.18;
+
+  outColor = vec4(color, 1.0);
+}

data/lib/vizcore/templates/intro_drop_scene.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# {{project_name}} transition example.
+Vizcore.define do
+  scene :intro do
+    layer :background do
+      shader :neon_grid
+      opacity 0.82
+    end
+
+    layer :geometry do
+      type :wireframe_cube
+      map fft_spectrum => :deform
+      map amplitude => :rotation_speed
+      map frequency_band(:high) => :color_shift
+    end
+  end
+
+  scene :drop do
+    layer :particles do
+      type :particle_field
+      count 3600
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+      map beat? => :flash
+    end
+
+    layer :title do
+      type :text
+      content "{{project_name}}"
+      font_size 96
+      map beat? => :flash
+    end
+  end
+
+  transition from: :intro, to: :drop do
+    trigger { beat_count >= 64 || frame_count >= 360 }
+    effect :crossfade, duration: 1.4
+  end
+end

data/lib/vizcore/templates/midi_control_scene.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# {{project_name}} MIDI mapping example.
+Vizcore.define do
+  midi :controller, device: :default
+
+  scene :warmup do
+    layer :warm_bg do
+      shader :neon_grid
+      map frequency_band(:mid) => :intensity
+    end
+  end
+
+  scene :impact do
+    layer :impact_bg do
+      shader :glitch_flash
+      map beat? => :flash
+      map amplitude => :effect_intensity
+    end
+  end
+
+  midi_map note: 36 do
+    switch_scene :impact
+  end
+
+  midi_map note: 38 do
+    switch_scene :warmup
+  end
+
+  midi_map cc: 1 do |value|
+    set :global_intensity, value / 127.0
+  end
+end

data/lib/vizcore/templates/project_readme.md

@@ -0,0 +1,35 @@
+# {{project_name}}
+
+This project was generated by `vizcore new`.
+
+## Start
+
+```bash
+vizcore start scenes/basic.rb
+```
+
+## Included Scenes
+
+- `scenes/basic.rb`: Minimal wireframe starter
+- `scenes/intro_drop.rb`: Transition flow with beat trigger
+- `scenes/midi_control.rb`: MIDI note/CC mapping example
+- `scenes/custom_shader.rb`: Custom GLSL + post/VJ effect example
+
+## Custom Shader
+
+`scenes/custom_shader.rb` references `shaders/custom_wave.frag`.
+Edit that file and save to see hot-reload updates.
+
+## MIDI
+
+List devices:
+
+```bash
+vizcore devices midi
+```
+
+Start MIDI example:
+
+```bash
+vizcore start scenes/midi_control.rb
+```