vizcore 0.1.0 → 1.1.0

data/lib/vizcore/renderer.rb

@@ -7,4 +7,9 @@ module Vizcore
 end
 
 require_relative "renderer/frame_scheduler"
+require_relative "renderer/png_writer"
+require_relative "renderer/scene_frame_source"
+require_relative "renderer/render_sequence"
 require_relative "renderer/scene_serializer"
+require_relative "renderer/snapshot"
+require_relative "renderer/snapshot_renderer"

data/lib/vizcore/server/frame_broadcaster.rb

@@ -23,6 +23,10 @@ module Vizcore
       # @param scene_catalog [Array<Hash>, nil]
       # @param transitions [Array<Hash>, nil]
       # @param transition_controller [Vizcore::DSL::TransitionController, nil]
+      # @param noise_gate [Numeric]
+      # @param audio_normalize [Hash, nil]
+      # @param bpm [Numeric, nil]
+      # @param bpm_lock [Boolean]
       # @param error_reporter [#call, nil]
       def initialize(
         scene_name: "basic",
@@ -35,6 +39,10 @@ module Vizcore
         scene_catalog: nil,
         transitions: nil,
         transition_controller: nil,
+        noise_gate: Vizcore::Analysis::Pipeline::DEFAULT_NOISE_GATE,
+        audio_normalize: nil,
+        bpm: nil,
+        bpm_lock: false,
         error_reporter: nil
       )
         @scene_name = scene_name
@@ -44,7 +52,11 @@ module Vizcore
         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
+          fft_size: fft_size,
+          noise_gate: noise_gate,
+          audio_normalize: audio_normalize,
+          bpm: bpm,
+          bpm_lock: bpm_lock
         )
         @mapping_resolver = mapping_resolver || Vizcore::DSL::MappingResolver.new
         @scene_serializer = scene_serializer || Vizcore::Renderer::SceneSerializer.new
@@ -55,8 +67,11 @@ module Vizcore
         @error_reporter = error_reporter || ->(_message) {}
         @last_error = nil
         @frame_count = 0
+        @custom_shape_param_overrides = {}
+        @custom_shape_param_mutex = Mutex.new
         @transport_playing = initial_transport_playing_state
         reset_transition_trigger_counters!
+        @tap_tempo = Vizcore::Analysis::TapTempo.new
         @frame_scheduler = frame_scheduler || Vizcore::Renderer::FrameScheduler.new(frame_rate: FRAME_RATE) do |elapsed|
           tick(elapsed)
         end
@@ -148,24 +163,98 @@ module Vizcore
         end
       end
 
+      # Replace audio analysis settings after scene hot reload.
+      #
+      # @param audio_normalize [Hash, nil]
+      # @param bpm [Numeric, nil]
+      # @param bpm_lock [Boolean]
+      # @return [void]
+      def update_analysis_settings(audio_normalize:, bpm: nil, bpm_lock: false)
+        return unless @analysis_pipeline.respond_to?(:audio_normalize=)
+
+        @analysis_pipeline.audio_normalize = audio_normalize
+        @analysis_pipeline.bpm_lock = { bpm: bpm, locked: bpm_lock } if @analysis_pipeline.respond_to?(:bpm_lock=)
+      end
+
+      # Apply a manual tap tempo event and lock analysis BPM when enough taps exist.
+      #
+      # @param timestamp_ms [Numeric]
+      # @return [Float, nil]
+      def tap_tempo(timestamp_ms:)
+        bpm = @tap_tempo.tap(timestamp_ms: timestamp_ms)
+        return nil unless bpm
+        return bpm unless @analysis_pipeline.respond_to?(:bpm_lock=)
+
+        @analysis_pipeline.bpm_lock = { bpm: bpm, locked: true }
+        bpm
+      end
+
+      # Lock analysis BPM from an external sync source.
+      #
+      # @param bpm [Numeric]
+      # @return [Float, nil]
+      def lock_bpm(bpm)
+        numeric = Float(bpm)
+        return nil unless numeric.finite? && numeric.positive?
+        return numeric unless @analysis_pipeline.respond_to?(:bpm_lock=)
+
+        @analysis_pipeline.bpm_lock = { bpm: numeric, locked: true }
+        numeric
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Unlock analysis BPM after an external sync lock.
+      #
+      # @return [Boolean]
+      def unlock_bpm
+        @analysis_pipeline.bpm_lock = { bpm: nil, locked: false } if @analysis_pipeline.respond_to?(:bpm_lock=)
+        true
+      end
+
+      def set_custom_shape_param(layer_name:, custom_shape_index:, param:, value:)
+        layer_key = layer_name.to_s
+        param_key = param.to_s.strip
+        index = Integer(custom_shape_index)
+        numeric = finite_float(value)
+        return custom_shape_param_overrides_snapshot if layer_key.empty? || param_key.empty? || index.negative? || numeric.nil?
+
+        @custom_shape_param_mutex.synchronize do
+          @custom_shape_param_overrides[layer_key] ||= {}
+          @custom_shape_param_overrides[layer_key][index] ||= {}
+          @custom_shape_param_overrides[layer_key][index][param_key] = numeric
+          deep_dup(@custom_shape_param_overrides)
+        end
+      rescue ArgumentError, TypeError
+        custom_shape_param_overrides_snapshot
+      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)
+      def build_frame(elapsed_seconds, samples = nil)
+        started_at_ms = monotonic_ms
+        audio_samples, audio_capture_ms = capture_or_use_samples(samples)
+        analyzed, audio_analysis_ms = measure_ms { @analysis_pipeline.call(audio_samples) }
         scene = current_scene
-        layers = build_scene_layers(scene[:layers], analyzed)
+        layers, scene_build_ms = measure_ms { build_scene_layers(scene[:layers], analyzed, time: elapsed_seconds, frame: @frame_count) }
 
         @scene_serializer.audio_frame(
           timestamp: Time.now.to_f,
           audio: analyzed,
           scene_name: scene[:name],
           scene_layers: layers,
-          transition: nil
+          transition: nil,
+          metrics: {
+            frame_id: @frame_count,
+            audio_capture_ms: audio_capture_ms,
+            audio_analysis_ms: audio_analysis_ms,
+            scene_build_ms: scene_build_ms,
+            server_frame_ms: monotonic_ms - started_at_ms
+          }
         )
       rescue StandardError => e
         report_error(e, context: "frame build failed")
@@ -174,6 +263,22 @@ module Vizcore
 
       private
 
+      def capture_or_use_samples(samples)
+        return [samples, 0.0] if samples
+
+        measure_ms { capture_samples }
+      end
+
+      def measure_ms
+        started_at = monotonic_ms
+        result = yield
+        [result, monotonic_ms - started_at]
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      end
+
       def capture_samples
         ingest_count =
           if @input_manager.respond_to?(:realtime_capture_size)
@@ -207,10 +312,40 @@ module Vizcore
         value.positive? && (value & (value - 1)).zero?
       end
 
-      def build_scene_layers(scene_layers, analyzed)
+      def build_scene_layers(scene_layers, analyzed, time: 0.0, frame: 0)
         return default_scene_layers(analyzed) if scene_layers.empty?
 
-        @mapping_resolver.resolve_layers(scene_layers: scene_layers, audio: analyzed)
+        @mapping_resolver.resolve_layers(
+          scene_layers: scene_layers,
+          audio: analyzed,
+          time: time,
+          frame: frame,
+          custom_shape_overrides: custom_shape_param_overrides_snapshot
+        )
+      end
+
+      def custom_shape_param_overrides_snapshot
+        @custom_shape_param_mutex.synchronize { deep_dup(@custom_shape_param_overrides) }
+      end
+
+      def finite_float(value)
+        numeric = Float(value)
+        return nil unless numeric.finite?
+
+        numeric
+      rescue ArgumentError, TypeError
+        nil
+      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
       end
 
       def default_scene_layers(analyzed)

data/lib/vizcore/server/gallery_app.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "rack"
+require_relative "../dsl"
+require_relative "gallery_page"
+
+module Vizcore
+  module Server
+    # Rack app that lists bundled example scenes and their launch commands.
+    class GalleryApp
+      POSTER_PATH = "/assets/vizcore-poster.png"
+      DESCRIPTIONS = {
+        "basic.rb" => "Single wireframe cube starter.",
+        "intro_drop.rb" => "Beat-triggered intro to drop transition.",
+        "file_audio_demo.rb" => "File-audio walkthrough with layered visuals.",
+        "complex_audio_showcase.rb" => "Dense multi-scene showcase for audio-reactive layers.",
+        "rhythm_geometry.rb" => "Morphing geometric pattern driven by rhythm and bands.",
+        "ruby_crystal_show.rb" => "Ruby-themed crystal, particles, and text showcase.",
+        "parser_visualizer.rb" => "Parser-themed token, AST, and reduce visual sketch.",
+        "live_coding_minimal.rb" => "Tiny live-coding scene with a pulsing blob.",
+        "club_intro_drop.rb" => "Intro, build, and drop flow for rhythmic file input.",
+        "shader_playground.rb" => "Focused liquid shader scene with mapped params.",
+        "audio_inspector.rb" => "Audio feature visualization scene with bars and blob.",
+        "readme_demo.rb" => "Minimal beat pulse to ring radius demo.",
+        "midi_scene_switch.rb" => "MIDI note and CC driven scene switching.",
+        "midi_controller_show.rb" => "MIDI pads switch scenes and knobs drive global shader uniforms.",
+        "kansai_rubykaigi_visual.rb" => "Event showcase with ruby crystal, water ripple, and Kyoto-inspired pattern.",
+        "custom_shader.rb" => "Custom GLSL fragment shader example.",
+        "unyo_liquid.rb" => "Organic liquid wobble scene with FFT blobs and particles."
+      }.freeze
+      FILE_AUDIO_EXAMPLES = %w[
+        file_audio_demo.rb
+        complex_audio_showcase.rb
+        rhythm_geometry.rb
+        ruby_crystal_show.rb
+        parser_visualizer.rb
+        club_intro_drop.rb
+        audio_inspector.rb
+        readme_demo.rb
+        kansai_rubykaigi_visual.rb
+      ].freeze
+      ORDER = DESCRIPTIONS.keys.freeze
+
+      # @param examples_root [Pathname, String]
+      # @param docs_assets_root [Pathname, String]
+      def initialize(
+        examples_root: Vizcore.root.join("examples"),
+        docs_assets_root: Vizcore.root.join("docs", "assets")
+      )
+        @examples_root = Pathname.new(examples_root.to_s).expand_path
+        @docs_assets_root = Pathname.new(docs_assets_root.to_s).expand_path
+      end
+
+      # @param env [Hash]
+      # @return [Array(Integer, Hash, Array<String>)]
+      def call(env)
+        request = Rack::Request.new(env)
+
+        return html_response if request.path_info == "/"
+        return json_response if request.path_info == "/examples.json"
+        return poster_response if request.path_info == POSTER_PATH
+        return health_response if request.path_info == "/health"
+
+        not_found_response
+      end
+
+      private
+
+      def html_response
+        body = GalleryPage.new(entries: examples, poster_path: POSTER_PATH).render
+        response(body, content_type: "text/html; charset=utf-8")
+      end
+
+      def json_response
+        body = JSON.generate(examples: examples)
+        response(body, content_type: "application/json; charset=utf-8")
+      end
+
+      def health_response
+        body = JSON.generate(status: "ok", examples: examples.length)
+        response(body, content_type: "application/json; charset=utf-8")
+      end
+
+      def poster_response
+        path = @docs_assets_root.join("vizcore-poster.png")
+        return not_found_response unless path.file?
+
+        response(File.binread(path), content_type: "image/png")
+      end
+
+      def examples
+        example_paths.map { |path| example_payload(path) }
+      end
+
+      def example_paths
+        paths = @examples_root.children.select { |path| path.file? && path.extname == ".rb" }
+        paths.sort_by { |path| [ORDER.index(path.basename.to_s) || ORDER.length, path.basename.to_s] }
+      rescue Errno::ENOENT
+        []
+      end
+
+      def example_payload(path)
+        definition = Vizcore::DSL::Engine.load_file(path.to_s)
+        scenes = Array(definition[:scenes])
+        {
+          file: display_path(path),
+          title: path.basename(".rb").to_s.tr("_", " "),
+          description: DESCRIPTIONS.fetch(path.basename.to_s, "Vizcore example scene."),
+          scene_names: scenes.map { |scene| scene[:name].to_s },
+          layer_count: scenes.sum { |scene| Array(scene[:layers]).length },
+          command: launch_command(path),
+          audio_source: audio_source_for(path)
+        }
+      rescue StandardError => e
+        {
+          file: display_path(path),
+          title: path.basename(".rb").to_s.tr("_", " "),
+          description: "This example could not be inspected: #{e.message}",
+          scene_names: [],
+          layer_count: 0,
+          command: launch_command(path),
+          audio_source: audio_source_for(path)
+        }
+      end
+
+      def launch_command(path)
+        command = "vizcore start #{display_path(path)} --audio-source #{audio_source_for(path)}"
+        return command unless audio_source_for(path) == "file"
+
+        "#{command} --audio-file #{display_path(@examples_root.join('assets', 'complex_demo_loop.wav'))}"
+      end
+
+      def audio_source_for(path)
+        FILE_AUDIO_EXAMPLES.include?(path.basename.to_s) ? "file" : "dummy"
+      end
+
+      def display_path(path)
+        path = Pathname.new(path.to_s).expand_path
+        path.relative_path_from(Vizcore.root).to_s
+      rescue ArgumentError
+        path.to_s
+      end
+
+      def response(body, content_type:)
+        [200, { "content-type" => content_type, "content-length" => body.bytesize.to_s, "cache-control" => "no-store" }, [body]]
+      end
+
+      def not_found_response
+        [404, { "content-type" => "text/plain; charset=utf-8", "content-length" => "9" }, ["Not Found"]]
+      end
+    end
+  end
+end

data/lib/vizcore/server/gallery_page.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Vizcore
+  module Server
+    # Renders the browser HTML for the bundled example gallery.
+    class GalleryPage
+      # @param entries [Array<Hash>]
+      # @param poster_path [String]
+      def initialize(entries:, poster_path:)
+        @entries = entries
+        @poster_path = poster_path
+      end
+
+      # @return [String]
+      def render
+        cards = @entries.map { |entry| render_card(entry) }.join
+        <<~HTML
+          <!doctype html>
+          <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>Vizcore Example Gallery</title>
+            <style>#{css}</style>
+          </head>
+          <body>
+            <main>
+              <header class="header">
+                <img src="#{@poster_path}" alt="" class="poster">
+                <div>
+                  <p class="eyebrow">Vizcore Examples</p>
+                  <h1>Example Gallery</h1>
+                  <p class="lede">Bundled scenes with scene counts, layer counts, audio-source hints, and launch commands.</p>
+                </div>
+              </header>
+              <section class="grid" aria-label="Example scenes">
+                #{cards}
+              </section>
+            </main>
+          </body>
+          </html>
+        HTML
+      end
+
+      private
+
+      def render_card(entry)
+        scenes = entry.fetch(:scene_names).empty? ? "none" : entry.fetch(:scene_names).join(", ")
+        <<~HTML
+          <article class="card">
+            <div class="thumb"></div>
+            <div class="card-body">
+              <h2>#{escape(entry.fetch(:title))}</h2>
+              <p>#{escape(entry.fetch(:description))}</p>
+              <dl>
+                <div><dt>File</dt><dd>#{escape(entry.fetch(:file))}</dd></div>
+                <div><dt>Scenes</dt><dd>#{escape(scenes)}</dd></div>
+                <div><dt>Layers</dt><dd>#{entry.fetch(:layer_count)}</dd></div>
+                <div><dt>Audio</dt><dd>#{escape(entry.fetch(:audio_source))}</dd></div>
+              </dl>
+              <code>#{escape(entry.fetch(:command))}</code>
+            </div>
+          </article>
+        HTML
+      end
+
+      def css
+        <<~CSS
+          :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #090b10; color: #ecf4ff; }
+          * { box-sizing: border-box; }
+          body { margin: 0; min-height: 100vh; background: #090b10; }
+          main { width: min(1180px, calc(100% - 32px)); margin: 0 auto; padding: 32px 0 48px; }
+          .header { display: grid; grid-template-columns: minmax(220px, 360px) 1fr; gap: 28px; align-items: end; margin-bottom: 28px; }
+          .poster { width: 100%; aspect-ratio: 16 / 9; object-fit: cover; border-radius: 8px; border: 1px solid rgba(255, 255, 255, 0.14); }
+          .eyebrow { margin: 0 0 8px; color: #7dd3fc; font-size: 13px; text-transform: uppercase; letter-spacing: 0; }
+          h1 { margin: 0; font-size: 42px; line-height: 1.05; letter-spacing: 0; }
+          .lede { max-width: 680px; margin: 14px 0 0; color: #b8c7d9; font-size: 17px; line-height: 1.55; }
+          .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 16px; }
+          .card { overflow: hidden; border: 1px solid rgba(255, 255, 255, 0.12); border-radius: 8px; background: #111722; }
+          .thumb { height: 96px; background: url("#{@poster_path}") center / cover; border-bottom: 1px solid rgba(255, 255, 255, 0.1); }
+          .card-body { padding: 16px; }
+          h2 { margin: 0 0 8px; font-size: 20px; line-height: 1.2; letter-spacing: 0; }
+          p { margin: 0 0 14px; color: #bdcadb; line-height: 1.5; }
+          dl { display: grid; gap: 8px; margin: 0 0 14px; }
+          dl div { display: grid; grid-template-columns: 68px 1fr; gap: 10px; }
+          dt { color: #7dd3fc; font-size: 12px; text-transform: uppercase; }
+          dd { margin: 0; color: #dfe9f6; overflow-wrap: anywhere; }
+          code { display: block; min-height: 52px; padding: 10px; border-radius: 6px; background: #05070b; color: #b8f7d4; overflow-wrap: anywhere; line-height: 1.45; }
+          @media (max-width: 720px) { .header { grid-template-columns: 1fr; } h1 { font-size: 34px; } }
+        CSS
+      end
+
+      def escape(value)
+        CGI.escapeHTML(value.to_s)
+      end
+    end
+  end
+end

data/lib/vizcore/server/gallery_runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "puma"
+require_relative "../config"
+require_relative "gallery_app"
+
+module Vizcore
+  module Server
+    # Starts a small Rack/Puma server for the example gallery.
+    class GalleryRunner
+      DEFAULT_PORT = Config::DEFAULT_PORT + 1
+
+      # @param host [String]
+      # @param port [Integer]
+      # @param output [#puts]
+      def initialize(host: Config::DEFAULT_HOST, port: DEFAULT_PORT, output: $stdout)
+        @host = host
+        @port = Integer(port)
+        @output = output
+      end
+
+      # @return [void]
+      def run
+        server = Puma::Server.new(GalleryApp.new, nil, min_threads: 0, max_threads: 4)
+        server.add_tcp_listener(@host, @port)
+        server.run
+
+        @output.puts("Vizcore gallery: http://#{@host}:#{@port}")
+        @output.puts("Press Ctrl+C to stop.")
+        wait_for_interrupt
+      ensure
+        server&.stop(true)
+      end
+
+      private
+
+      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
+    end
+  end
+end