vizcore 0.1.0 → 1.0.0

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

@@ -20,6 +20,40 @@ void main() {
 }
 `;
 
+export const resolveParticleForces = ({ x, y, index, time, forceField, turbulence, bassExplosion, audio }) => {
+  const bass = clampNumber(audio?.bands?.low, 0, 1);
+  const mid = clampNumber(audio?.bands?.mid, 0, 1);
+  const high = clampNumber(audio?.bands?.high, 0, 1);
+  const pulse = clampNumber(audio?.beat_pulse || (audio?.beat ? 1 : 0), 0, 1);
+  const field = String(forceField || "drift").toLowerCase();
+
+  let fx = 0;
+  let fy = 0;
+
+  const radius = Math.max(0.001, Math.hypot(x, y));
+  const nx = x / radius;
+  const ny = y / radius;
+
+  if (field === "vortex") {
+    const strength = 0.00018 + mid * 0.00065;
+    fx += -ny * strength;
+    fy += nx * strength;
+  } else if (field === "pulse") {
+    const strength = (bass * 0.0007 + pulse * 0.0012) * (1 + clampNumber(bassExplosion, 0, 3));
+    fx += nx * strength;
+    fy += ny * strength;
+  }
+
+  const turb = clampNumber(turbulence, 0, 3);
+  if (turb > 0) {
+    const noise = Math.sin(time * (1.7 + high * 3.0) + index * 12.9898);
+    fx += Math.cos(noise * 6.28318530718) * turb * 0.00018;
+    fy += Math.sin(noise * 6.28318530718) * turb * 0.00018;
+  }
+
+  return [fx, fy];
+};
+
 export class ParticleSystem {
   constructor(gl, shaderManager) {
     this.gl = gl;
@@ -39,11 +73,11 @@ export class ParticleSystem {
     this.velocities = new Float32Array(0);
   }
 
-  render({ count, speed, size, audio, time }) {
+  render({ count, speed, size, forceField, turbulence, bassExplosion, sparkle, color, audio, time }) {
     const particleCount = clampInt(count, 200, 20_000);
     this.ensureParticles(particleCount);
-    this.updateParticles(speed, audio, time);
-    this.draw(size, audio);
+    this.updateParticles({ speed, forceField, turbulence, bassExplosion, audio, time });
+    this.draw({ size, sparkle, color, audio });
   }
 
   ensureParticles(nextCount) {
@@ -67,9 +101,9 @@ export class ParticleSystem {
     }
   }
 
-  updateParticles(speed, audio, time) {
+  updateParticles({ speed, forceField, turbulence, bassExplosion, audio, time }) {
     const motion = 0.4 + clampNumber(speed, 0, 4);
-    const beatBoost = audio?.beat ? 1.4 : 1.0;
+    const beatBoost = audio?.beat || audio?.beat_pulse ? 1.4 : 1.0;
     const drift = 0.0008 + clampNumber(audio?.amplitude, 0, 1) * 0.0018;
 
     for (let index = 0; index < this.count; index += 1) {
@@ -83,6 +117,12 @@ export class ParticleSystem {
       vx += swirl * 0.01;
       vy -= swirl * 0.01;
 
+      const [fx, fy] = resolveParticleForces({ x, y, index, time, forceField, turbulence, bassExplosion, audio });
+      vx += fx;
+      vy += fy;
+      vx = clampNumber(vx * 0.997, -0.035, 0.035);
+      vy = clampNumber(vy * 0.997, -0.035, 0.035);
+
       x += vx * motion * beatBoost;
       y += vy * motion * beatBoost;
 
@@ -102,12 +142,13 @@ export class ParticleSystem {
     }
   }
 
-  draw(size, audio) {
+  draw({ size, sparkle, color, audio }) {
     const gl = this.gl;
-    const pointSize = 1.5 + clampNumber(size, 0, 32);
     const amplitude = clampNumber(audio?.amplitude, 0, 1);
     const bass = clampNumber(audio?.bands?.low, 0, 1);
     const high = clampNumber(audio?.bands?.high, 0, 1);
+    const sparkleAmount = clampNumber(sparkle, 0, 3) * high;
+    const pointSize = 1.5 + clampNumber(size, 0, 32) + sparkleAmount * 1.5;
 
     gl.useProgram(this.program);
     gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
@@ -116,11 +157,16 @@ export class ParticleSystem {
     gl.vertexAttribPointer(this.positionLocation, 2, gl.FLOAT, false, 0, 0);
 
     gl.uniform1f(this.pointSizeLocation, pointSize);
+    const resolvedColor = Array.isArray(color) ? color : [
+      0.35 + bass * 0.45,
+      0.55 + high * 0.35 + sparkleAmount * 0.08,
+      0.95 + amplitude * 0.05 + sparkleAmount * 0.05
+    ];
     gl.uniform3f(
       this.colorLocation,
-      0.35 + bass * 0.45,
-      0.55 + high * 0.35,
-      0.95 + amplitude * 0.05
+      clampNumber(resolvedColor[0], 0, 1),
+      clampNumber(resolvedColor[1], 0, 1),
+      clampNumber(resolvedColor[2], 0, 1)
     );
     gl.drawArrays(gl.POINTS, 0, this.count);
   }

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

@@ -0,0 +1,226 @@
+const SPECTROGRAM_VERTEX_SHADER = `#version 300 es
+in vec2 a_position;
+in vec2 a_uv;
+out vec2 v_uv;
+void main() {
+  v_uv = a_uv;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+
+const SPECTROGRAM_FRAGMENT_SHADER = `#version 300 es
+precision mediump float;
+in vec2 v_uv;
+uniform sampler2D u_texture;
+uniform float u_opacity;
+out vec4 outColor;
+
+void main() {
+  vec4 texel = texture(u_texture, v_uv);
+  outColor = vec4(texel.rgb, texel.a * u_opacity);
+}
+`;
+
+const QUAD_VERTICES = new Float32Array([
+  -1.0, -1.0, 0.0, 1.0,
+  1.0, -1.0, 1.0, 1.0,
+  -1.0, 1.0, 0.0, 0.0,
+  1.0, 1.0, 1.0, 0.0
+]);
+
+export class SpectrogramRenderer {
+  constructor(gl, shaderManager) {
+    this.gl = gl;
+    this.shaderManager = shaderManager;
+    this.program = this.shaderManager.getProgram(
+      "spectrogram-renderer",
+      SPECTROGRAM_VERTEX_SHADER,
+      SPECTROGRAM_FRAGMENT_SHADER
+    );
+    this.positionLocation = this.gl.getAttribLocation(this.program, "a_position");
+    this.uvLocation = this.gl.getAttribLocation(this.program, "a_uv");
+    this.textureLocation = this.gl.getUniformLocation(this.program, "u_texture");
+    this.opacityLocation = this.gl.getUniformLocation(this.program, "u_opacity");
+    this.histories = new Map();
+
+    this.buffer = this.gl.createBuffer();
+    this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.buffer);
+    this.gl.bufferData(this.gl.ARRAY_BUFFER, QUAD_VERTICES, this.gl.STATIC_DRAW);
+
+    this.canvas = document.createElement("canvas");
+    this.ctx = this.canvas.getContext("2d");
+
+    this.texture = this.gl.createTexture();
+    this.gl.bindTexture(this.gl.TEXTURE_2D, this.texture);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MIN_FILTER, this.gl.LINEAR);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MAG_FILTER, this.gl.LINEAR);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_WRAP_S, this.gl.CLAMP_TO_EDGE);
+    this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_WRAP_T, this.gl.CLAMP_TO_EDGE);
+  }
+
+  render({ key, audio, params = {} }) {
+    const bins = normalizeSpectrogramBins(params.bins);
+    const historySize = normalizeSpectrogramHistory(params.history);
+    const scroll = normalizeSpectrogramScroll(params.scroll);
+    const gain = normalizeSpectrogramGain(params.gain);
+    const spectrum = normalizeSpectrogramSpectrum(audio?.fft, bins, gain);
+    const history = this.updateHistory({ key, bins, historySize, spectrum });
+    const image = buildSpectrogramPixels({ history, bins, historySize, scroll });
+
+    this.drawImage(image);
+    this.uploadTexture();
+    this.drawQuad({ opacity: 1 });
+  }
+
+  updateHistory({ key, bins, historySize, spectrum }) {
+    const cacheKey = String(key || "default");
+    const current = this.histories.get(cacheKey);
+    const history = current?.bins === bins && current?.historySize === historySize ? current.frames : [];
+    history.push(spectrum);
+    while (history.length > historySize) {
+      history.shift();
+    }
+    this.histories.set(cacheKey, { bins, historySize, frames: history });
+    return history;
+  }
+
+  drawImage({ width, height, pixels }) {
+    if (this.canvas.width !== width) {
+      this.canvas.width = width;
+    }
+    if (this.canvas.height !== height) {
+      this.canvas.height = height;
+    }
+
+    const imageData = this.ctx.createImageData(width, height);
+    imageData.data.set(pixels);
+    this.ctx.putImageData(imageData, 0, 0);
+  }
+
+  uploadTexture() {
+    this.gl.bindTexture(this.gl.TEXTURE_2D, this.texture);
+    this.gl.texImage2D(
+      this.gl.TEXTURE_2D,
+      0,
+      this.gl.RGBA,
+      this.gl.RGBA,
+      this.gl.UNSIGNED_BYTE,
+      this.canvas
+    );
+  }
+
+  drawQuad({ opacity }) {
+    const gl = this.gl;
+    gl.useProgram(this.program);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+    gl.enableVertexAttribArray(this.positionLocation);
+    gl.vertexAttribPointer(this.positionLocation, 2, gl.FLOAT, false, 16, 0);
+    gl.enableVertexAttribArray(this.uvLocation);
+    gl.vertexAttribPointer(this.uvLocation, 2, gl.FLOAT, false, 16, 8);
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.uniform1i(this.textureLocation, 0);
+    gl.uniform1f(this.opacityLocation, clamp(Number(opacity || 1), 0, 1));
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+  }
+}
+
+export const normalizeSpectrogramScroll = (value) => {
+  const scroll = String(value || "vertical").trim().toLowerCase();
+  return scroll === "horizontal" ? "horizontal" : "vertical";
+};
+
+export const normalizeSpectrogramBins = (value) => {
+  return clampInt(value || 64, 16, 256);
+};
+
+export const normalizeSpectrogramHistory = (value) => {
+  return clampInt(value || 96, 16, 512);
+};
+
+export const normalizeSpectrogramGain = (value) => {
+  const gain = Number(value);
+  if (!Number.isFinite(gain)) return 1;
+  return clamp(gain, 0.1, 8);
+};
+
+export const normalizeSpectrogramSpectrum = (value, bins, gain = 1) => {
+  const input = Array.isArray(value) || ArrayBuffer.isView(value) ? Array.from(value) : [];
+  const output = [];
+  const safeBins = normalizeSpectrogramBins(bins);
+  const safeGain = normalizeSpectrogramGain(gain);
+
+  for (let index = 0; index < safeBins; index += 1) {
+    const progress = safeBins === 1 ? 0 : index / (safeBins - 1);
+    output.push(clamp(sampleSpectrum(input, progress) * safeGain, 0, 1));
+  }
+
+  return output;
+};
+
+export const buildSpectrogramPixels = ({ history, bins, historySize, scroll }) => {
+  const safeBins = normalizeSpectrogramBins(bins);
+  const safeHistorySize = normalizeSpectrogramHistory(historySize);
+  const direction = normalizeSpectrogramScroll(scroll);
+  const width = direction === "vertical" ? safeBins : safeHistorySize;
+  const height = direction === "vertical" ? safeHistorySize : safeBins;
+  const pixels = new Uint8ClampedArray(width * height * 4);
+  const frames = Array.isArray(history) ? history.slice(-safeHistorySize) : [];
+
+  frames.forEach((frame, frameIndex) => {
+    const timeIndex = safeHistorySize - frames.length + frameIndex;
+    for (let bin = 0; bin < safeBins; bin += 1) {
+      const value = clamp(Number(frame?.[bin] || 0), 0, 1);
+      const x = direction === "vertical" ? bin : timeIndex;
+      const y = direction === "vertical" ? timeIndex : safeBins - 1 - bin;
+      writePixel(pixels, width, x, y, spectrogramColor(value));
+    }
+  });
+
+  return { width, height, pixels };
+};
+
+export const spectrogramColor = (value) => {
+  const energy = clamp(Number(value || 0), 0, 1);
+  const mid = 1 - Math.abs(energy * 2 - 1);
+  return [
+    Math.round(10 + energy * 245),
+    Math.round(18 + Math.max(0, energy - 0.18) * 250),
+    Math.round(36 + mid * 155 + energy * 36),
+    Math.round(energy * 255)
+  ];
+};
+
+const writePixel = (pixels, width, x, y, color) => {
+  const offset = ((y * width) + x) * 4;
+  pixels[offset] = color[0];
+  pixels[offset + 1] = color[1];
+  pixels[offset + 2] = color[2];
+  pixels[offset + 3] = color[3];
+};
+
+const sampleSpectrum = (spectrum, progress) => {
+  if (!spectrum.length) return 0;
+
+  const position = progress * (spectrum.length - 1);
+  const left = Math.floor(position);
+  const right = Math.min(left + 1, spectrum.length - 1);
+  const mix = position - left;
+  const from = finiteNumber(spectrum[left], 0);
+  const to = finiteNumber(spectrum[right], 0);
+  return clamp(from + (to - from) * mix, 0, 1);
+};
+
+const finiteNumber = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+
+const clampInt = (value, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return min;
+  return Math.round(Math.min(Math.max(numeric, min), max));
+};
+
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);

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

@@ -55,9 +55,9 @@ export class TextRenderer {
     this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_WRAP_T, this.gl.CLAMP_TO_EDGE);
   }
 
-  render({ content, fontSize, audio, time, color, glowStrength }) {
-    const text = String(content || "").trim();
-    if (!text) {
+  render({ content, fontSize, audio, time, color, fontFamily, align, letterSpacing, strokeWidth, strokeColor, shadowColor, shadowBlur, glowStrength }) {
+    const lines = normalizeTextLines(content);
+    if (!lines.length) {
       return;
     }
 
@@ -65,15 +65,24 @@ export class TextRenderer {
 
     const amp = clamp(Number(audio?.amplitude || 0), 0, 1);
     const beatBoost = audio?.beat ? 1.0 : 0.0;
-    const maxFontSize = Math.max(48, Math.floor(this.canvas.height * 0.22));
+    const singleLineMax = Math.floor(this.canvas.height * 0.22);
+    const multilineMax = Math.floor((this.canvas.height * 0.58) / Math.max(lines.length, 1));
+    const maxFontSize = Math.max(32, Math.min(singleLineMax, multilineMax));
     const dynamicSize = Math.round(
       clamp(Number(fontSize || 96), 18, maxFontSize) * (1 + amp * 0.08 + beatBoost * 0.04)
     );
     this.drawTextToCanvas({
-      text,
+      lines,
       fontSize: dynamicSize,
       time,
       color,
+      fontFamily,
+      align,
+      letterSpacing,
+      strokeWidth,
+      strokeColor,
+      shadowColor,
+      shadowBlur,
       amplitude: amp,
       glowStrength: Number(glowStrength ?? 0.15)
     });
@@ -81,7 +90,7 @@ export class TextRenderer {
     this.drawQuad({ intensity: 0.85 + amp * 0.15 });
   }
 
-  drawTextToCanvas({ text, fontSize, time, color, amplitude, glowStrength }) {
+  drawTextToCanvas({ lines, fontSize, time, color, fontFamily, align, letterSpacing, strokeWidth, strokeColor, shadowColor, shadowBlur, amplitude, glowStrength }) {
     const ctx = this.ctx;
     ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
 
@@ -91,14 +100,30 @@ export class TextRenderer {
     const safeColor = typeof color === "string" && color.trim() ? color : "#e5f3ff";
     const glow = clamp(Number(glowStrength || 0), 0, 1) * (1.5 + amplitude * 5.0);
     const xShift = Math.sin(time * 2.0) * (2 + amplitude * 4);
+    const textAlign = normalizeTextAlign(align);
+    const spacing = normalizeLetterSpacing(letterSpacing);
+    const stroke = clamp(Number(strokeWidth || 0), 0, 24);
+    const shadow = shadowBlur === undefined ? glow : clamp(Number(shadowBlur || 0), 0, 80);
 
-    ctx.textAlign = "center";
+    ctx.textAlign = textAlign;
     ctx.textBaseline = "middle";
-    ctx.font = `700 ${fontSize}px "IBM Plex Sans", "Noto Sans JP", sans-serif`;
-    ctx.shadowColor = "rgba(110, 208, 255, 0.35)";
-    ctx.shadowBlur = glow;
+    ctx.font = `700 ${fontSize}px ${normalizeFontFamily(fontFamily)}`;
+    ctx.shadowColor = normalizeTextColor(shadowColor, "rgba(110, 208, 255, 0.35)");
+    ctx.shadowBlur = shadow;
     ctx.fillStyle = safeColor;
-    ctx.fillText(text, this.canvas.width / 2 + xShift, this.canvas.height / 2);
+    const x = resolveTextX(this.canvas.width, textAlign) + xShift;
+    const lineHeight = fontSize * 1.16;
+    const startY = this.canvas.height / 2 - ((lines.length - 1) * lineHeight) / 2;
+    lines.forEach((line, index) => {
+      const y = startY + index * lineHeight;
+      if (stroke > 0) {
+        ctx.lineJoin = "round";
+        ctx.lineWidth = stroke;
+        ctx.strokeStyle = normalizeTextColor(strokeColor, safeColor);
+        drawText(ctx, { text: line, x, y, align: textAlign, letterSpacing: spacing, method: "strokeText" });
+      }
+      drawText(ctx, { text: line, x, y, align: textAlign, letterSpacing: spacing, method: "fillText" });
+    });
   }
 
   syncCanvasSize() {
@@ -141,3 +166,79 @@ export class TextRenderer {
 }
 
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+
+export const normalizeTextAlign = (value) => {
+  const align = String(value || "center").trim().toLowerCase();
+  if (align === "left" || align === "right" || align === "center") {
+    return align;
+  }
+  return "center";
+};
+
+export const resolveTextX = (width, align) => {
+  const canvasWidth = Number(width) || 0;
+  if (align === "left") return canvasWidth * 0.12;
+  if (align === "right") return canvasWidth * 0.88;
+  return canvasWidth * 0.5;
+};
+
+export const normalizeTextLines = (value) => {
+  return String(value || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .slice(0, 6);
+};
+
+export const normalizeLetterSpacing = (value) => {
+  const spacing = Number(value);
+  if (!Number.isFinite(spacing)) return 0;
+  return clamp(spacing, 0, 96);
+};
+
+export const measureLetterSpacedText = (ctx, text, letterSpacing = 0) => {
+  const chars = Array.from(String(text || ""));
+  if (!chars.length) return 0;
+
+  const spacing = normalizeLetterSpacing(letterSpacing);
+  const glyphWidth = chars.reduce((total, char) => {
+    return total + Number(ctx.measureText(char)?.width || 0);
+  }, 0);
+  return glyphWidth + spacing * (chars.length - 1);
+};
+
+export const resolveLetterSpacedStartX = (ctx, text, x, align, letterSpacing = 0) => {
+  const width = measureLetterSpacedText(ctx, text, letterSpacing);
+  if (align === "right") return x - width;
+  if (align === "center") return x - width / 2;
+  return x;
+};
+
+export const normalizeFontFamily = (value) => {
+  const family = String(value || "").trim();
+  if (!family) return "\"IBM Plex Sans\", \"Noto Sans JP\", sans-serif";
+  if (family.includes(",")) return `${family}, "IBM Plex Sans", "Noto Sans JP", sans-serif`;
+
+  return `"${family.replaceAll("\"", "")}", "IBM Plex Sans", "Noto Sans JP", sans-serif`;
+};
+
+const normalizeTextColor = (value, fallback) => {
+  const color = String(value || "").trim();
+  return color || fallback;
+};
+
+const drawText = (ctx, { text, x, y, align, letterSpacing, method }) => {
+  if (letterSpacing <= 0) {
+    ctx[method](text, x, y);
+    return;
+  }
+
+  const originalAlign = ctx.textAlign;
+  ctx.textAlign = "left";
+  let cursor = resolveLetterSpacedStartX(ctx, text, x, align, letterSpacing);
+  for (const char of Array.from(text)) {
+    ctx[method](char, cursor, y);
+    cursor += Number(ctx.measureText(char)?.width || 0) + letterSpacing;
+  }
+  ctx.textAlign = originalAlign;
+};

data/frontend/src/websocket-client.js

@@ -1,6 +1,7 @@
 const RECONNECT_INTERVAL_MS = 1000;
 const READY_STATE_CONNECTING = 0;
 const READY_STATE_OPEN = 1;
+export const PROTOCOL_VERSION = "vizcore.frame.v1";
 
 export class WebSocketClient {
   constructor(url, callbacks = {}) {
@@ -8,6 +9,7 @@ export class WebSocketClient {
     this.onFrame = callbacks.onFrame || (() => {});
     this.onSceneChange = callbacks.onSceneChange || (() => {});
     this.onConfigUpdate = callbacks.onConfigUpdate || (() => {});
+    this.onLatencyProbe = callbacks.onLatencyProbe || (() => {});
     this.onStatus = callbacks.onStatus || (() => {});
     this.socket = null;
     this.reconnectTimer = null;
@@ -97,6 +99,10 @@ export class WebSocketClient {
       return;
     }
 
+    if (message.protocol && message.protocol !== PROTOCOL_VERSION) {
+      return;
+    }
+
     if (message.type === "audio_frame") {
       this.onFrame(message.payload);
       return;
@@ -109,6 +115,11 @@ export class WebSocketClient {
 
     if (message.type === "config_update") {
       this.onConfigUpdate(message.payload);
+      return;
+    }
+
+    if (message.type === "latency_probe") {
+      this.onLatencyProbe(message.payload);
     }
   }
 
@@ -122,7 +133,7 @@ export class WebSocketClient {
     }
 
     try {
-      this.socket.send(JSON.stringify({ type, payload }));
+      this.socket.send(JSON.stringify({ protocol: PROTOCOL_VERSION, type, payload }));
       return true;
     } catch {
       return false;

data/lib/vizcore/analysis/adaptive_normalizer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # Scales audio features against a rolling amplitude peak for repeatable mappings.
+    class AdaptiveNormalizer
+      DEFAULT_WINDOW_SIZE = 128
+      DEFAULT_TARGET = 0.85
+      DEFAULT_FLOOR = 0.05
+
+      # @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)
+        @window_size = normalize_window_size(window_size)
+        @target = normalize_unit(target, DEFAULT_TARGET)
+        @floor = normalize_unit(floor, DEFAULT_FLOOR)
+        @history = []
+      end
+
+      # @param amplitude [Numeric] current RMS amplitude
+      # @param bands [Hash] current frequency band values
+      # @param fft [Array<Numeric>] current FFT preview values
+      # @return [Hash] normalized feature values plus the applied gain
+      def call(amplitude:, bands:, fft:)
+        current_amplitude = normalize_unit(amplitude, 0.0)
+        @history << current_amplitude
+        @history.shift while @history.length > @window_size
+
+        gain = @target / [@history.max.to_f, @floor].max
+        {
+          amplitude: scale_value(current_amplitude, gain),
+          bands: scale_hash(bands, gain),
+          fft: scale_array(fft, gain),
+          gain: gain
+        }
+      end
+
+      private
+
+      def normalize_window_size(value)
+        Integer(value).clamp(1, 10_000)
+      rescue ArgumentError, TypeError
+        DEFAULT_WINDOW_SIZE
+      end
+
+      def normalize_unit(value, fallback)
+        Float(value).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        fallback
+      end
+
+      def scale_hash(values, gain)
+        Hash(values).transform_values { |value| scale_value(value, gain) }
+      rescue StandardError
+        {}
+      end
+
+      def scale_array(values, gain)
+        Array(values).map { |value| scale_value(value, gain) }
+      end
+
+      def scale_value(value, gain)
+        (Float(value) * gain).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        0.0
+      end
+    end
+  end
+end

data/lib/vizcore/analysis/beat_detector.rb

@@ -10,11 +10,13 @@ module Vizcore
       # @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)
+      # @param min_energy [Float] absolute energy floor required for beat detection
+      def initialize(history_size: 43, sensitivity: 1.35, refractory_frames: 4, min_history: 8, min_energy: 1e-6)
         @history_size = Integer(history_size)
         @sensitivity = Float(sensitivity)
         @refractory_frames = Integer(refractory_frames)
         @min_history = Integer(min_history)
+        @min_energy = Float(min_energy)
         @energy_history = []
         @frame_index = 0
         @last_beat_frame = -@refractory_frames
@@ -29,7 +31,7 @@ module Vizcore
         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?
+        beat = enough_history && refractory_ok && instant_energy > threshold && instant_energy >= @min_energy
 
         if beat
           @beat_count += 1

data/lib/vizcore/analysis/bpm_estimator.rb

@@ -44,6 +44,14 @@ module Vizcore
         @current_bpm
       end
 
+      # Clear accumulated onset history and the current tempo estimate.
+      #
+      # @return [void]
+      def reset
+        @history.clear
+        @current_bpm = 0.0
+      end
+
       private
 
       def onset_count