vizcore 1.1.0 → 1.2.0

data/frontend/src/runtime-control-preset.js

@@ -3,9 +3,53 @@ export const normalizeRuntimeControlPreset = (value) => {
   return {
     visualSettings: objectValue(input.visual_settings) || objectValue(input.visualSettings) || null,
     midiLearnBindings: objectValue(input.midi_learn_bindings) || objectValue(input.midiLearnBindings) || null,
+    sceneOverrides: normalizeSceneOverrides(
+      input.scene_overrides || input.sceneOverrides || null
+    ),
   };
 };
 
 const objectValue = (value) => {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 };
+
+const normalizeSceneOverrides = (value) => {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+
+  const output = {};
+  for (const [rawSceneName, rawOverride] of Object.entries(value)) {
+    const sceneName = String(rawSceneName || "").trim();
+    if (!sceneName) {
+      continue;
+    }
+
+    const override = normalizeSceneOverride(rawOverride);
+    if (!override) {
+      continue;
+    }
+
+    output[sceneName] = override;
+  }
+
+  return output;
+};
+
+const normalizeSceneOverride = (value) => {
+  const input = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const visualSettings = objectValue(input.visual_settings) || objectValue(input.visualSettings);
+  const midiLearnBindings = objectValue(input.midi_learn_bindings) || objectValue(input.midiLearnBindings);
+  if (!visualSettings && !midiLearnBindings) {
+    return null;
+  }
+
+  const output = {};
+  if (visualSettings) {
+    output.visualSettings = visualSettings;
+  }
+  if (midiLearnBindings) {
+    output.midiLearnBindings = midiLearnBindings;
+  }
+  return output;
+};

data/frontend/src/scene-patches.js

@@ -0,0 +1,159 @@
+const REMOVED_LAYER = Symbol("vizcore.scene.removed_layer");
+
+const isObject = (value) => value !== null && typeof value === "object";
+
+const clonePayload = (value) => {
+  if (!isObject(value) && !Array.isArray(value)) {
+    return value;
+  }
+
+  if (typeof structuredClone === "function") {
+    try {
+      return structuredClone(value);
+    } catch {
+      // Fall back to JSON clone below.
+    }
+  }
+
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return null;
+  }
+};
+
+const sceneVersion = (value) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+};
+
+const normalizeIndex = (value) => {
+  const numeric = Number(value);
+  return Number.isInteger(numeric) && numeric >= 0 ? numeric : null;
+};
+
+export const applyScenePayload = (payload) => {
+  if (!isObject(payload)) {
+    return null;
+  }
+
+  const scene = clonePayload(payload);
+  if (!isObject(scene)) {
+    return null;
+  }
+
+  if (!Array.isArray(scene.layers)) {
+    scene.layers = [];
+  } else {
+    scene.layers = scene.layers.map((entry) => clonePayload(entry)).filter(Boolean);
+  }
+
+  return scene;
+};
+
+export const applyScenePatch = (currentScene, patch) => {
+  if (!isObject(currentScene) || !isObject(patch) || !Array.isArray(Array.isArray(patch.layers) ? patch.layers : null)) {
+    return null;
+  }
+
+  const currentName = String(currentScene.name || "");
+  if (String(patch.name || "") !== currentName) {
+    return null;
+  }
+
+  const currentVersion = sceneVersion(currentScene.version);
+  const patchVersion = sceneVersion(patch.version);
+  if (currentVersion !== null && patchVersion !== null && patchVersion !== currentVersion) {
+    return null;
+  }
+
+  const next = applyScenePayload(currentScene);
+  if (!isObject(next)) {
+    return null;
+  }
+
+  const layers = next.layers;
+  for (const entry of patch.layers) {
+    if (!isObject(entry)) {
+      continue;
+    }
+
+    const index = normalizeIndex(entry.index);
+    if (index === null) {
+      continue;
+    }
+
+    if (entry.remove) {
+      if (index < layers.length) {
+        layers[index] = REMOVED_LAYER;
+      }
+      continue;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(entry, "layer")) {
+      if (!isObject(entry.layer)) {
+        continue;
+      }
+      while (layers.length <= index) {
+        layers.push(REMOVED_LAYER);
+      }
+      layers[index] = applyScenePayload(entry.layer);
+      continue;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(entry, "params")) {
+      continue;
+    }
+    if (!isObject(entry.params)) {
+      continue;
+    }
+
+    const layer = layers[index];
+    if (!isObject(layer) || layer === REMOVED_LAYER) {
+      continue;
+    }
+
+    const params = isObject(layer.params) ? clonePayload(layer.params) : {};
+    layers[index] = {
+      ...layer,
+      params: {
+        ...params,
+        ...clonePayload(entry.params)
+      }
+    };
+  }
+
+  next.version = patchVersion !== null ? patchVersion : next.version;
+  if (Object.prototype.hasOwnProperty.call(patch, "schema_version")) {
+    next.schema_version = patch.schema_version;
+  }
+  next.layers = layers.filter((layer) => layer !== REMOVED_LAYER);
+
+  return next;
+};
+
+export const resolveScenePayload = ({ incomingScene = null, currentScene = null, frameVersion = null } = {}) => {
+  if (!isObject(incomingScene) && !isObject(currentScene)) {
+    return null;
+  }
+
+  if (incomingScene.patch) {
+    if (!isObject(currentScene)) {
+      return null;
+    }
+
+    const expectedVersion = sceneVersion(frameVersion);
+    const currentVersion = sceneVersion(currentScene.version);
+    if (expectedVersion !== null && currentVersion !== null && expectedVersion !== currentVersion) {
+      return applyScenePayload(currentScene);
+    }
+
+    return applyScenePatch(currentScene, incomingScene) || applyScenePayload(currentScene);
+  }
+
+  if (!isObject(incomingScene)) {
+    return applyScenePayload(currentScene);
+  }
+
+  return applyScenePayload(incomingScene);
+};

data/frontend/src/shader-error-overlay.js

@@ -7,6 +7,7 @@ export const buildShaderErrorDetail = ({ layer, error, phase }) => {
     name,
     shader,
     phase: String(phase || "shader"),
+    event: "shader_failed",
     message: normalizeErrorMessage(error),
   };
 };

data/frontend/src/visuals/image-renderer.js

@@ -198,6 +198,25 @@ export class ImageRenderer {
     gl.uniform1f(this.invertLocation, normalizeInvert(invert));
     gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
   }
+
+  dispose() {
+    for (const media of this.media.values()) {
+      if (isVideoElement(media)) {
+        media.pause?.();
+        media.removeAttribute?.("src");
+        media.load?.();
+      }
+    }
+    this.media.clear();
+    if (this.texture) {
+      this.gl.deleteTexture(this.texture);
+      this.texture = null;
+    }
+    if (this.buffer) {
+      this.gl.deleteBuffer(this.buffer);
+      this.buffer = null;
+    }
+  }
 }
 
 export const resolveMediaSource = (value) => {

data/frontend/src/visuals/particle-system.js

@@ -170,6 +170,16 @@ export class ParticleSystem {
     );
     gl.drawArrays(gl.POINTS, 0, this.count);
   }
+
+  dispose() {
+    if (this.buffer) {
+      this.gl.deleteBuffer(this.buffer);
+      this.buffer = null;
+    }
+    this.positions = new Float32Array(0);
+    this.velocities = new Float32Array(0);
+    this.count = 0;
+  }
 }
 
 const clampInt = (value, min, max) => {

data/frontend/src/visuals/shape-renderer.js

@@ -123,6 +123,19 @@ export class ShapeRenderer {
     gl.uniform1f(this.intensityLocation, clamp(Number(intensity || 1), 0, 1));
     gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
   }
+
+  dispose() {
+    if (this.texture) {
+      this.gl.deleteTexture(this.texture);
+      this.texture = null;
+    }
+    if (this.buffer) {
+      this.gl.deleteBuffer(this.buffer);
+      this.buffer = null;
+    }
+    this.canvas = null;
+    this.ctx = null;
+  }
 }
 
 export const shapeCoordinateContext = (params = {}) => {

data/frontend/src/visuals/spectrogram-renderer.js

@@ -124,6 +124,20 @@ export class SpectrogramRenderer {
     gl.uniform1f(this.opacityLocation, clamp(Number(opacity || 1), 0, 1));
     gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
   }
+
+  dispose() {
+    this.histories.clear();
+    if (this.texture) {
+      this.gl.deleteTexture(this.texture);
+      this.texture = null;
+    }
+    if (this.buffer) {
+      this.gl.deleteBuffer(this.buffer);
+      this.buffer = null;
+    }
+    this.canvas = null;
+    this.ctx = null;
+  }
 }
 
 export const normalizeSpectrogramScroll = (value) => {

data/frontend/src/visuals/text-renderer.js

@@ -163,6 +163,19 @@ export class TextRenderer {
     gl.uniform1f(this.intensityLocation, clamp(Number(intensity || 1), 0, 1));
     gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
   }
+
+  dispose() {
+    if (this.texture) {
+      this.gl.deleteTexture(this.texture);
+      this.texture = null;
+    }
+    if (this.buffer) {
+      this.gl.deleteBuffer(this.buffer);
+      this.buffer = null;
+    }
+    this.canvas = null;
+    this.ctx = null;
+  }
 }
 
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);

data/frontend/src/websocket-client.js

@@ -10,6 +10,7 @@ export class WebSocketClient {
     this.onSceneChange = callbacks.onSceneChange || (() => {});
     this.onConfigUpdate = callbacks.onConfigUpdate || (() => {});
     this.onLatencyProbe = callbacks.onLatencyProbe || (() => {});
+    this.onRuntimeError = callbacks.onRuntimeError || (() => {});
     this.onStatus = callbacks.onStatus || (() => {});
     this.socket = null;
     this.reconnectTimer = null;
@@ -120,6 +121,11 @@ export class WebSocketClient {
 
     if (message.type === "latency_probe") {
       this.onLatencyProbe(message.payload);
+      return;
+    }
+
+    if (message.type === "runtime_error") {
+      this.onRuntimeError(message.payload);
     }
   }
 

data/lib/vizcore/analysis/adaptive_normalizer.rb

@@ -11,11 +11,14 @@ module Vizcore
       # @param window_size [Integer] number of recent active frames used to track the peak
       # @param target [Numeric] desired level for the rolling peak
       # @param floor [Numeric] minimum peak level used when calculating gain
-      def initialize(window_size: DEFAULT_WINDOW_SIZE, target: DEFAULT_TARGET, floor: DEFAULT_FLOOR)
+      # @param per_band [Boolean] true when band levels should track independent peaks
+      def initialize(window_size: DEFAULT_WINDOW_SIZE, target: DEFAULT_TARGET, floor: DEFAULT_FLOOR, per_band: false)
         @window_size = normalize_window_size(window_size)
         @target = normalize_unit(target, DEFAULT_TARGET)
         @floor = normalize_unit(floor, DEFAULT_FLOOR)
+        @per_band = !!per_band
         @history = []
+        @band_history = Hash.new { |history, key| history[key] = [] }
       end
 
       # @param amplitude [Numeric] current RMS amplitude
@@ -30,7 +33,7 @@ module Vizcore
         gain = @target / [@history.max.to_f, @floor].max
         {
           amplitude: scale_value(current_amplitude, gain),
-          bands: scale_hash(bands, gain),
+          bands: normalize_bands(bands, gain),
           fft: scale_array(fft, gain),
           gain: gain
         }
@@ -56,6 +59,21 @@ module Vizcore
         {}
       end
 
+      def normalize_bands(values, amplitude_gain)
+        return scale_hash(values, amplitude_gain) unless @per_band
+
+        Hash(values).each_with_object({}) do |(key, value), output|
+          normalized = normalize_unit(value, 0.0)
+          history = @band_history[key.to_sym]
+          history << normalized
+          history.shift while history.length > @window_size
+          gain = @target / [history.max.to_f, @floor].max
+          output[key] = scale_value(normalized, gain)
+        end
+      rescue StandardError
+        {}
+      end
+
       def scale_array(values, gain)
         Array(values).map { |value| scale_value(value, gain) }
       end

data/lib/vizcore/analysis/bpm_estimator.rb

@@ -4,7 +4,7 @@ module Vizcore
   module Analysis
     # Estimates tempo (BPM) from beat onsets using lag autocorrelation.
     class BPMEstimator
-      attr_reader :frame_rate
+      attr_reader :confidence, :frame_rate
 
       # @param frame_rate [Float] analysis frames per second
       # @param min_bpm [Float] minimum candidate BPM
@@ -21,6 +21,7 @@ module Vizcore
         @min_onsets = Integer(min_onsets)
         @history = []
         @current_bpm = 0.0
+        @confidence = 0.0
       end
 
       # @param beat [Boolean] whether the current frame contains a beat onset
@@ -29,10 +30,17 @@ module Vizcore
         @history << (beat ? 1.0 : 0.0)
         @history.shift while @history.length > @history_size
 
-        return @current_bpm if onset_count < @min_onsets
+        if onset_count < @min_onsets
+          @confidence = 0.0
+          return @current_bpm
+        end
 
-        candidate = estimate_candidate_bpm
-        return @current_bpm if candidate <= 0.0
+        candidate, confidence = estimate_candidate_bpm
+        if candidate <= 0.0
+          @confidence = 0.0
+          return @current_bpm
+        end
+        @confidence = confidence
 
         @current_bpm =
           if @current_bpm <= 0.0
@@ -50,6 +58,7 @@ module Vizcore
       def reset
         @history.clear
         @current_bpm = 0.0
+        @confidence = 0.0
       end
 
       private
@@ -60,11 +69,11 @@ module Vizcore
 
       def estimate_candidate_bpm
         n = @history.length
-        return 0.0 if n < 2
+        return [0.0, 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
+        return [0.0, 0.0] if min_lag > max_lag
 
         best_lag = nil
         best_score = -Float::INFINITY
@@ -77,9 +86,10 @@ module Vizcore
           best_lag = lag
         end
 
-        return 0.0 unless best_lag && best_score.positive?
+        return [0.0, 0.0] unless best_lag && best_score.positive?
 
-        (60.0 * @frame_rate / best_lag).clamp(@min_bpm, @max_bpm)
+        bpm = (60.0 * @frame_rate / best_lag).clamp(@min_bpm, @max_bpm)
+        [bpm, (best_score / onset_count.to_f).clamp(0.0, 1.0)]
       end
 
       def autocorrelation_at_lag(lag)

data/lib/vizcore/analysis/feature_recorder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "digest"
 require "json"
 require "pathname"
 require_relative "../audio/file_input"
@@ -22,7 +23,8 @@ module Vizcore
         noise_gate: Pipeline::DEFAULT_NOISE_GATE,
         audio_normalize: nil,
         bpm: nil,
-        bpm_lock: false
+        bpm_lock: false,
+        cache_root: nil
       )
         @audio_file = Pathname.new(audio_file.to_s).expand_path
         @frames = normalize_frame_count(frames)
@@ -31,6 +33,16 @@ module Vizcore
         @audio_normalize = audio_normalize
         @bpm = bpm
         @bpm_lock = bpm_lock
+        @cache_root = normalize_cache_root(cache_root)
+      end
+
+      # Absolute cache file path for current recorder settings.
+      #
+      # @return [Pathname, nil]
+      def cache_path
+        return nil unless @cache_root
+
+        @cache_root.join("#{cache_key}.json")
       end
 
       # @param out [String, Pathname] JSON output path
@@ -38,18 +50,116 @@ module Vizcore
       def write(out:)
         output_path = Pathname.new(out.to_s).expand_path
         FileUtils.mkdir_p(output_path.dirname)
-        payload = record
-        output_path.write("#{JSON.pretty_generate(payload)}\n")
-        {
-          path: output_path,
+
+        if cache_path
+          cached_payload = load_cached_payload(cache_path)
+          output_payload = cached_payload if cached_payload
+        end
+
+        output_payload ||= record
+        output_path.write("#{JSON.pretty_generate(output_payload)}\n")
+        write_cached_output(output_payload) if cache_path && cache_path != output_path
+
+        metadata_from_payload(output_payload, path: output_path)
+      end
+
+      # Stable hash key for this recorder configuration.
+      #
+      # @return [String]
+      def cache_key
+        self.class.cache_key(
+          version: VERSION,
+          audio_file: @audio_file,
           frames: @frames,
           fps: @fps,
-          sample_rate: payload.fetch("metadata").fetch("sample_rate")
-        }
+          noise_gate: @noise_gate,
+          audio_normalize: @audio_normalize,
+          bpm: @bpm,
+          bpm_lock: @bpm_lock
+        )
+      end
+
+      # @return [Hash] recorder metadata
+      def self.cache_key(version:, audio_file:, frames:, fps:, noise_gate:, audio_normalize:, bpm:, bpm_lock:)
+        audio_path = Pathname.new(audio_file.to_s).expand_path
+        Digest::SHA256.hexdigest(
+          JSON.generate(
+            {
+              version: version,
+              audio_file: audio_path.to_s,
+              audio_file_size: audio_file_size(audio_path),
+              audio_file_mtime: audio_file_mtime(audio_path),
+              frames: frames,
+              fps: fps,
+              noise_gate: noise_gate,
+              audio_normalize: audio_normalize,
+              bpm: bpm,
+              bpm_lock: bpm_lock
+            }
+          )
+        )
+      end
+
+      def self.audio_file_size(path)
+        file_stat_value(path, :size)
+      end
+
+      def self.audio_file_mtime(path)
+        file_stat_value(path, :mtime).to_i
+      rescue StandardError
+        0
+      end
+
+      def self.file_stat_value(path, name)
+        stat = Pathname.new(path).stat
+        stat.send(name)
+      rescue StandardError
+        0
       end
 
       private
 
+      def load_cached_payload(path)
+        payload = JSON.parse(Pathname.new(path).read)
+        return unless payload.is_a?(Hash)
+
+        payload if valid_cached_payload?(payload)
+      rescue StandardError
+        nil
+      end
+
+      def valid_cached_payload?(payload)
+        payload.fetch("version", nil) == VERSION &&
+          payload.fetch("metadata", {}).fetch("frames", nil) == @frames &&
+          (Float(payload.fetch("metadata", {}).fetch("fps", nil)) - @fps).abs < Float::EPSILON &&
+          payload.fetch("features", nil).is_a?(Array) &&
+          !payload.fetch("features", []).empty?
+      end
+
+      def write_cached_output(payload)
+        cache = cache_path
+        return unless cache
+
+        FileUtils.mkdir_p(cache.dirname)
+        cache.write("#{JSON.pretty_generate(payload)}\n")
+      end
+
+      def metadata_from_payload(payload, path:)
+        metadata = payload.fetch("metadata", {})
+        {
+          path: path,
+          frames: metadata.fetch("frames"),
+          fps: metadata.fetch("fps"),
+          sample_rate: metadata.fetch("sample_rate")
+        }
+      end
+
+      def normalize_cache_root(value)
+        return nil if value.nil?
+
+        Pathname.new(value.to_s).expand_path
+      end
+
       def record
         validate_audio_file!
         input = Vizcore::Audio::FileInput.new(path: @audio_file.to_s)