vizcore 0.1.0

data/frontend/src/visuals/vj-effects.js

@@ -0,0 +1,56 @@
+export const VJ_EFFECT_SHADERS = {
+  mirror: `#version 300 es
+precision mediump float;
+in vec2 v_uv;
+uniform sampler2D u_texture;
+uniform float u_intensity;
+out vec4 outColor;
+
+void main() {
+  vec2 uv = v_uv;
+  if (uv.x > 0.5) {
+    uv.x = 1.0 - uv.x;
+  }
+  vec4 left = texture(u_texture, uv);
+  vec4 base = texture(u_texture, v_uv);
+  float mixAmount = clamp(0.4 + u_intensity * 0.6, 0.0, 1.0);
+  outColor = mix(base, left, mixAmount);
+}
+`,
+  color_shift: `#version 300 es
+precision mediump float;
+in vec2 v_uv;
+uniform sampler2D u_texture;
+uniform float u_intensity;
+out vec4 outColor;
+
+void main() {
+  vec2 shift = vec2(0.008 * (0.2 + u_intensity), 0.0);
+  float r = texture(u_texture, v_uv + shift).r;
+  float g = texture(u_texture, v_uv).g;
+  float b = texture(u_texture, v_uv - shift).b;
+  float a = texture(u_texture, v_uv).a;
+  outColor = vec4(r, g, b, a);
+}
+`,
+  pixelate: `#version 300 es
+precision mediump float;
+in vec2 v_uv;
+uniform sampler2D u_texture;
+uniform vec2 u_resolution;
+uniform float u_intensity;
+out vec4 outColor;
+
+void main() {
+  float blocks = mix(260.0, 40.0, clamp(u_intensity, 0.0, 1.0));
+  vec2 grid = vec2(blocks, blocks * (u_resolution.y / max(u_resolution.x, 1.0)));
+  vec2 uv = floor(v_uv * grid) / grid;
+  outColor = texture(u_texture, uv);
+}
+`
+};
+
+export const getVJEffectShader = (name) => {
+  const key = String(name || "").trim().toLowerCase();
+  return VJ_EFFECT_SHADERS[key] || null;
+};

data/frontend/src/websocket-client.js

@@ -0,0 +1,131 @@
+const RECONNECT_INTERVAL_MS = 1000;
+const READY_STATE_CONNECTING = 0;
+const READY_STATE_OPEN = 1;
+
+export class WebSocketClient {
+  constructor(url, callbacks = {}) {
+    this.url = url;
+    this.onFrame = callbacks.onFrame || (() => {});
+    this.onSceneChange = callbacks.onSceneChange || (() => {});
+    this.onConfigUpdate = callbacks.onConfigUpdate || (() => {});
+    this.onStatus = callbacks.onStatus || (() => {});
+    this.socket = null;
+    this.reconnectTimer = null;
+    this.shouldReconnect = true;
+    this.connectionSerial = 0;
+  }
+
+  connect() {
+    if (this.socket && (this.socket.readyState === READY_STATE_CONNECTING || this.socket.readyState === READY_STATE_OPEN)) {
+      return;
+    }
+    this.shouldReconnect = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.onStatus("connecting");
+
+    const serial = this.connectionSerial + 1;
+    this.connectionSerial = serial;
+    const socket = new WebSocket(this.url);
+    this.socket = socket;
+    socket.addEventListener("open", () => {
+      if (!this.isActiveSocket(socket, serial)) {
+        return;
+      }
+      this.onStatus("connected");
+    });
+    socket.addEventListener("close", () => {
+      if (!this.isActiveSocket(socket, serial)) {
+        return;
+      }
+      this.socket = null;
+      if (!this.shouldReconnect) {
+        this.onStatus("disconnected");
+        return;
+      }
+      this.scheduleReconnect();
+    });
+    socket.addEventListener("error", () => {
+      if (!this.isActiveSocket(socket, serial)) {
+        return;
+      }
+      this.onStatus("error");
+    });
+    socket.addEventListener("message", (event) => {
+      if (!this.isActiveSocket(socket, serial)) {
+        return;
+      }
+      this.handleMessage(event.data);
+    });
+  }
+
+  disconnect() {
+    this.shouldReconnect = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    const socket = this.socket;
+    this.socket = null;
+    if (socket && (socket.readyState === READY_STATE_CONNECTING || socket.readyState === READY_STATE_OPEN)) {
+      socket.close();
+    }
+  }
+
+  scheduleReconnect() {
+    if (!this.shouldReconnect || this.reconnectTimer) {
+      return;
+    }
+    this.onStatus("reconnecting");
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, RECONNECT_INTERVAL_MS);
+  }
+
+  handleMessage(rawMessage) {
+    let message;
+    try {
+      message = JSON.parse(rawMessage);
+    } catch {
+      return;
+    }
+
+    if (!message || !message.type || !message.payload) {
+      return;
+    }
+
+    if (message.type === "audio_frame") {
+      this.onFrame(message.payload);
+      return;
+    }
+
+    if (message.type === "scene_change") {
+      this.onSceneChange(message.payload);
+      return;
+    }
+
+    if (message.type === "config_update") {
+      this.onConfigUpdate(message.payload);
+    }
+  }
+
+  isActiveSocket(socket, serial) {
+    return this.socket === socket && this.connectionSerial === serial;
+  }
+
+  send(type, payload = {}) {
+    if (!this.socket || this.socket.readyState !== READY_STATE_OPEN) {
+      return false;
+    }
+
+    try {
+      this.socket.send(JSON.stringify({ type, payload }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

data/lib/vizcore/analysis/band_splitter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # Converts FFT magnitudes into normalized sub/low/mid/high band energies.
+    class BandSplitter
+      # Frequency ranges for each named band in Hz.
+      BANDS = {
+        sub: [20.0, 60.0],
+        low: [60.0, 250.0],
+        mid: [250.0, 4000.0],
+        high: [4000.0, 20_000.0]
+      }.freeze
+
+      attr_reader :sample_rate, :fft_size
+
+      # @param sample_rate [Integer] input sample rate
+      # @param fft_size [Integer] FFT frame size used to compute magnitudes
+      def initialize(sample_rate: 44_100, fft_size: 1024)
+        @sample_rate = Integer(sample_rate)
+        @fft_size = Integer(fft_size)
+        @bin_hz = @sample_rate.to_f / @fft_size.to_f
+      end
+
+      # @param magnitudes [Array<Numeric>] FFT magnitude bins
+      # @return [Hash] normalized energy values for `:sub/:low/:mid/:high`
+      def call(magnitudes)
+        values = normalize_magnitudes(magnitudes)
+        return BANDS.transform_values { 0.0 } if values.empty?
+
+        scale = [values.max, 1.0e-9].max
+
+        BANDS.transform_values do |(low_hz, high_hz)|
+          indices = band_indices(low_hz, high_hz, values.length)
+          next 0.0 if indices.empty?
+
+          average = indices.sum { |index| values[index] } / indices.length.to_f
+          (average / scale).clamp(0.0, 1.0)
+        end
+      end
+
+      private
+
+      def normalize_magnitudes(magnitudes)
+        Array(magnitudes).map { |value| Float(value).abs }
+      rescue ArgumentError, TypeError
+        []
+      end
+
+      def band_indices(low_hz, high_hz, length)
+        return [] if length.zero?
+
+        first = (low_hz / @bin_hz).floor
+        last = (high_hz / @bin_hz).ceil
+        first = first.clamp(0, length - 1)
+        last = last.clamp(0, length - 1)
+        return [] if first > last
+
+        (first..last).to_a
+      end
+    end
+  end
+end

data/lib/vizcore/analysis/beat_detector.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # Detects beat onsets using short-term energy thresholding.
+    class BeatDetector
+      attr_reader :beat_count
+
+      # @param history_size [Integer] number of historical frames to keep
+      # @param sensitivity [Float] multiplier applied to moving average energy
+      # @param refractory_frames [Integer] minimum frames between beat events
+      # @param min_history [Integer] minimum history size before detecting beats
+      def initialize(history_size: 43, sensitivity: 1.35, refractory_frames: 4, min_history: 8)
+        @history_size = Integer(history_size)
+        @sensitivity = Float(sensitivity)
+        @refractory_frames = Integer(refractory_frames)
+        @min_history = Integer(min_history)
+        @energy_history = []
+        @frame_index = 0
+        @last_beat_frame = -@refractory_frames
+        @beat_count = 0
+      end
+
+      # @param samples [Array<Numeric>] PCM frame samples
+      # @return [Hash] beat flag and detector internals
+      def call(samples)
+        instant_energy = frame_energy(samples)
+        average_energy = average(@energy_history)
+        threshold = average_energy * @sensitivity
+        enough_history = @energy_history.length >= @min_history
+        refractory_ok = (@frame_index - @last_beat_frame) > @refractory_frames
+        beat = enough_history && refractory_ok && instant_energy > threshold && instant_energy.positive?
+
+        if beat
+          @beat_count += 1
+          @last_beat_frame = @frame_index
+        end
+
+        @energy_history << instant_energy
+        @energy_history.shift while @energy_history.length > @history_size
+        @frame_index += 1
+
+        {
+          beat: beat,
+          beat_count: @beat_count,
+          instant_energy: instant_energy,
+          average_energy: average_energy,
+          threshold: threshold
+        }
+      end
+
+      private
+
+      def frame_energy(samples)
+        values = Array(samples).map { |sample| Float(sample) }
+        return 0.0 if values.empty?
+
+        values.reduce(0.0) { |sum, value| sum + value * value } / values.length.to_f
+      rescue ArgumentError, TypeError
+        0.0
+      end
+
+      def average(values)
+        return 0.0 if values.empty?
+
+        values.sum / values.length.to_f
+      end
+    end
+  end
+end

data/lib/vizcore/analysis/bpm_estimator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # Estimates tempo (BPM) from beat onsets using lag autocorrelation.
+    class BPMEstimator
+      attr_reader :frame_rate
+
+      # @param frame_rate [Float] analysis frames per second
+      # @param min_bpm [Float] minimum candidate BPM
+      # @param max_bpm [Float] maximum candidate BPM
+      # @param history_seconds [Float] history duration used for autocorrelation
+      # @param smoothing [Float] EMA factor for stable BPM output
+      # @param min_onsets [Integer] minimum onsets before estimation
+      def initialize(frame_rate:, min_bpm: 60.0, max_bpm: 200.0, history_seconds: 10.0, smoothing: 0.25, min_onsets: 4)
+        @frame_rate = Float(frame_rate)
+        @min_bpm = Float(min_bpm)
+        @max_bpm = Float(max_bpm)
+        @history_size = [(@frame_rate * Float(history_seconds)).to_i, 8].max
+        @smoothing = Float(smoothing)
+        @min_onsets = Integer(min_onsets)
+        @history = []
+        @current_bpm = 0.0
+      end
+
+      # @param beat [Boolean] whether the current frame contains a beat onset
+      # @return [Float] smoothed BPM estimate
+      def call(beat:)
+        @history << (beat ? 1.0 : 0.0)
+        @history.shift while @history.length > @history_size
+
+        return @current_bpm if onset_count < @min_onsets
+
+        candidate = estimate_candidate_bpm
+        return @current_bpm if candidate <= 0.0
+
+        @current_bpm =
+          if @current_bpm <= 0.0
+            candidate
+          else
+            @current_bpm + (candidate - @current_bpm) * @smoothing
+          end
+
+        @current_bpm
+      end
+
+      private
+
+      def onset_count
+        @history.count { |value| value.positive? }
+      end
+
+      def estimate_candidate_bpm
+        n = @history.length
+        return 0.0 if n < 2
+
+        min_lag = [(60.0 * @frame_rate / @max_bpm).round, 1].max
+        max_lag = [(60.0 * @frame_rate / @min_bpm).round, n - 1].min
+        return 0.0 if min_lag > max_lag
+
+        best_lag = nil
+        best_score = -Float::INFINITY
+
+        (min_lag..max_lag).each do |lag|
+          score = autocorrelation_at_lag(lag)
+          next unless score > best_score
+
+          best_score = score
+          best_lag = lag
+        end
+
+        return 0.0 unless best_lag && best_score.positive?
+
+        (60.0 * @frame_rate / best_lag).clamp(@min_bpm, @max_bpm)
+      end
+
+      def autocorrelation_at_lag(lag)
+        score = 0.0
+        (lag...@history.length).each do |index|
+          score += @history[index] * @history[index - lag]
+        end
+        score
+      end
+    end
+  end
+end

data/lib/vizcore/analysis/fft_processor.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require_relative "fftw_ffi"
+
+module Vizcore
+  module Analysis
+    # Performs FFT analysis with optional FFTW acceleration and Ruby fallback.
+    class FFTProcessor
+      # Supported windowing functions applied before FFT.
+      SUPPORTED_WINDOWS = %i[hamming hann blackman none].freeze
+      # Supported transform backends.
+      SUPPORTED_BACKENDS = %i[auto ruby fftw].freeze
+
+      attr_reader :sample_rate, :fft_size, :window, :backend_name
+
+      # @return [Boolean] true when FFTW3 is available.
+      def self.fftw_available?
+        FFTWFFI.available?
+      end
+
+      # @param sample_rate [Integer] input sample rate
+      # @param fft_size [Integer] FFT frame size (power of two)
+      # @param window [Symbol] one of {SUPPORTED_WINDOWS}
+      # @param backend [Symbol] one of {SUPPORTED_BACKENDS}
+      def initialize(sample_rate: 44_100, fft_size: 1024, window: :hamming, backend: :auto)
+        @sample_rate = Integer(sample_rate)
+        @fft_size = Integer(fft_size)
+        @window = window.to_sym
+        @backend_requested = backend.to_sym
+
+        raise ArgumentError, "fft_size must be power of two" unless power_of_two?(@fft_size)
+        raise ArgumentError, "unsupported window: #{@window}" unless SUPPORTED_WINDOWS.include?(@window)
+        raise ArgumentError, "unsupported backend: #{@backend_requested}" unless SUPPORTED_BACKENDS.include?(@backend_requested)
+
+        @backend = resolve_backend(@backend_requested)
+      end
+
+      # @param samples [Array<Numeric>] PCM frame samples
+      # @return [Hash] FFT result with magnitudes, complex spectrum, and peak info
+      def call(samples)
+        frame = prepare_frame(samples)
+        windowed = apply_window(frame)
+        spectrum = execute_transform(windowed)
+        half_spectrum = spectrum.first(@fft_size / 2)
+        magnitudes = half_spectrum.map(&:abs)
+        peak_bin = peak_index(magnitudes)
+
+        {
+          magnitudes: magnitudes,
+          spectrum: half_spectrum,
+          peak_bin: peak_bin,
+          peak_frequency: bin_frequency(peak_bin)
+        }
+      end
+
+      # @param bin_index [Integer]
+      # @return [Float] frequency in Hz corresponding to the FFT bin
+      def bin_frequency(bin_index)
+        Integer(bin_index) * sample_rate.to_f / fft_size.to_f
+      end
+
+      private
+
+      def prepare_frame(samples)
+        values = Array(samples).map { |sample| Float(sample) }
+        values = values.first(fft_size)
+        return values if values.length == fft_size
+
+        values + Array.new(fft_size - values.length, 0.0)
+      rescue ArgumentError, TypeError
+        Array.new(fft_size, 0.0)
+      end
+
+      def apply_window(frame)
+        return frame if window == :none
+
+        frame.each_with_index.map do |value, index|
+          value * window_coefficient(index, frame.length)
+        end
+      end
+
+      def execute_transform(windowed)
+        @backend.transform(windowed)
+      rescue StandardError
+        raise unless @backend_requested == :auto && @backend_name == :fftw
+
+        @backend_name = :ruby
+        @backend = RubyBackend.new
+        @backend.transform(windowed)
+      end
+
+      def resolve_backend(requested)
+        case requested
+        when :ruby
+          @backend_name = :ruby
+          RubyBackend.new
+        when :fftw
+          raise ArgumentError, "fftw backend is unavailable on this system" unless self.class.fftw_available?
+
+          @backend_name = :fftw
+          FFTWBackend.new(fft_size)
+        else
+          if self.class.fftw_available?
+            @backend_name = :fftw
+            FFTWBackend.new(fft_size)
+          else
+            @backend_name = :ruby
+            RubyBackend.new
+          end
+        end
+      end
+
+      def window_coefficient(index, size)
+        angle = 2.0 * Math::PI * index.to_f / (size - 1).to_f
+
+        case window
+        when :hamming
+          0.54 - 0.46 * Math.cos(angle)
+        when :hann
+          0.5 * (1.0 - Math.cos(angle))
+        when :blackman
+          0.42 - 0.5 * Math.cos(angle) + 0.08 * Math.cos(2 * angle)
+        else
+          1.0
+        end
+      end
+
+      def power_of_two?(value)
+        value.positive? && (value & (value - 1)).zero?
+      end
+
+      def peak_index(magnitudes)
+        pair = magnitudes.each_with_index.max_by { |magnitude, _index| magnitude }
+        pair ? pair.last : 0
+      end
+
+      # Pure-Ruby Cooley-Tukey FFT backend.
+      # @api private
+      class RubyBackend
+        # @param values [Array<Float>]
+        # @return [Array<Complex>]
+        def transform(values)
+          fft(values.map { |value| Complex(value, 0.0) })
+        end
+
+        private
+
+        def fft(values)
+          n = values.length
+          bit_reversed = bit_reverse_copy(values)
+
+          len = 2
+          while len <= n
+            angle = -2.0 * Math::PI / len
+            twiddle_step = Complex(Math.cos(angle), Math.sin(angle))
+
+            (0...n).step(len) do |offset|
+              twiddle = Complex(1.0, 0.0)
+              half = len / 2
+
+              half.times do |index|
+                even = bit_reversed[offset + index]
+                odd = bit_reversed[offset + index + half] * twiddle
+                bit_reversed[offset + index] = even + odd
+                bit_reversed[offset + index + half] = even - odd
+                twiddle *= twiddle_step
+              end
+            end
+
+            len <<= 1
+          end
+
+          bit_reversed
+        end
+
+        def bit_reverse_copy(values)
+          n = values.length
+          output = values.dup
+          j = 0
+
+          (1...n).each do |i|
+            bit = n >> 1
+            while j & bit != 0
+              j ^= bit
+              bit >>= 1
+            end
+            j ^= bit
+            output[i], output[j] = output[j], output[i] if i < j
+          end
+
+          output
+        end
+      end
+
+      # FFTW3-backed transform backend.
+      # @api private
+      class FFTWBackend
+        # @param fft_size [Integer]
+        def initialize(fft_size)
+          @fft_size = fft_size
+        end
+
+        # @param values [Array<Float>]
+        # @return [Array<Complex>]
+        def transform(values)
+          input = FFI::MemoryPointer.new(:double, @fft_size)
+          bins = (@fft_size / 2) + 1
+          output = FFI::MemoryPointer.new(:double, bins * 2)
+          input.write_array_of_double(values)
+
+          plan = FFTWFFI.fftw_plan_dft_r2c_1d(@fft_size, input, output, FFTWFFI::ESTIMATE)
+          raise RuntimeError, "fftw failed to create transform plan" if plan.null?
+
+          FFTWFFI.fftw_execute(plan)
+          output.read_array_of_double(bins * 2).each_slice(2).map do |real, imag|
+            Complex(real, imag)
+          end
+        ensure
+          FFTWFFI.fftw_destroy_plan(plan) if plan && !plan.null?
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/analysis/fftw_ffi.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Vizcore
+  module Analysis
+    # Thin FFI wrapper for FFTW3 availability checks and symbol binding.
+    module FFTWFFI
+      extend FFI::Library
+
+      # Candidate library names across macOS/Linux/Windows.
+      LIBRARY_NAMES = %w[
+        fftw3
+        libfftw3.so.3
+        libfftw3.so
+        libfftw3-3
+        libfftw3.dylib
+        libfftw3.3.dylib
+        fftw3-3.dll
+        libfftw3-3.dll
+      ].freeze
+
+      # FFTW planning flag (`FFTW_ESTIMATE`).
+      ESTIMATE = 64
+
+      class << self
+        # @return [Boolean] true when FFTW bindings can be attached.
+        def available?
+          attach_bindings!
+          true
+        rescue LoadError, FFI::NotFoundError
+          false
+        end
+
+        private
+
+        def attach_bindings!
+          return if @bindings_attached
+
+          ffi_lib LIBRARY_NAMES
+          attach_function :fftw_plan_dft_r2c_1d, %i[int pointer pointer uint], :pointer
+          attach_function :fftw_execute, [:pointer], :void
+          attach_function :fftw_destroy_plan, [:pointer], :void
+
+          @bindings_attached = true
+        end
+      end
+    end
+  end
+end