vizcore 0.1.0 → 1.1.0

data/lib/vizcore/analysis/pipeline.rb

@@ -4,6 +4,12 @@ module Vizcore
   module Analysis
     # End-to-end analysis pipeline from PCM samples to renderer-ready features.
     class Pipeline
+      BEAT_PULSE_DECAY = 0.86
+      BEAT_PULSE_FLOOR = 0.001
+      DEFAULT_NOISE_GATE = 0.01
+      DEFAULT_AUDIO_NORMALIZE = { mode: :off }.freeze
+      SILENCE_RESET_FRAMES = 90
+
       attr_reader :fft_processor, :band_splitter, :beat_detector, :bpm_estimator, :smoother
 
       # @param sample_rate [Integer]
@@ -12,38 +18,248 @@ module Vizcore
       # @param beat_detector [Vizcore::Analysis::BeatDetector, nil]
       # @param bpm_estimator [Vizcore::Analysis::BPMEstimator, nil]
       # @param smoother [Vizcore::Analysis::Smoother, nil]
-      def initialize(sample_rate: 44_100, fft_size: 1024, window: :hamming, beat_detector: nil, bpm_estimator: nil, smoother: nil)
+      # @param noise_gate [Numeric] RMS threshold below which input is treated as silence
+      # @param audio_normalize [Hash, nil] optional audio normalization settings
+      # @param bpm [Numeric, nil] fixed BPM value used when bpm_lock is true
+      # @param bpm_lock [Boolean] true when BPM output should stay fixed
+      def initialize(sample_rate: 44_100, fft_size: 1024, window: :hamming, beat_detector: nil, bpm_estimator: nil, smoother: nil, noise_gate: DEFAULT_NOISE_GATE, audio_normalize: nil, bpm: nil, bpm_lock: false)
         @fft_processor = FFTProcessor.new(sample_rate: sample_rate, fft_size: fft_size, window: window)
         @band_splitter = BandSplitter.new(sample_rate: sample_rate, fft_size: fft_size)
         @beat_detector = beat_detector || BeatDetector.new
-        frame_rate = sample_rate.to_f / fft_size.to_f
-        @bpm_estimator = bpm_estimator || BPMEstimator.new(frame_rate: frame_rate)
+        @analysis_frame_rate = sample_rate.to_f / fft_size.to_f
+        @bpm_estimator = bpm_estimator || BPMEstimator.new(frame_rate: @analysis_frame_rate)
         @smoother = smoother || Smoother.new(alpha: 0.35)
+        @noise_gate = normalize_noise_gate(noise_gate)
+        self.bpm_lock = { bpm: bpm, locked: bpm_lock }
+        self.audio_normalize = audio_normalize
+        @beat_pulse = 0.0
+        @last_bpm = 0.0
+        @silent_frame_count = 0
+        @previous_onset_amplitude = 0.0
+        @previous_onset_bands = {}
+      end
+
+      # @param settings [Hash, nil]
+      # @return [Hash] normalized settings
+      def audio_normalize=(settings)
+        @audio_normalize = normalize_audio_normalize(settings)
+        @normalizer = build_normalizer(@audio_normalize)
+      end
+
+      # @param settings [Hash]
+      # @return [Float, nil]
+      def bpm_lock=(settings)
+        values = symbolize_hash(settings)
+        @locked_bpm = normalize_locked_bpm(values[:bpm], bpm_lock: values[:locked])
+        @last_bpm = @locked_bpm if @locked_bpm
       end
 
       # @param samples [Array<Numeric>] audio frame samples
       # @return [Hash] normalized analysis payload consumed by frame broadcaster
       def call(samples)
+        amplitude = rms(samples)
+        if silence?(amplitude)
+          track_silent_frame(samples)
+          return silent_frame(reset_tempo: sustained_silence?)
+        end
+
+        @silent_frame_count = 0
+
         fft = @fft_processor.call(samples)
         bands = @band_splitter.call(fft[:magnitudes])
         beat = @beat_detector.call(samples)
-        bpm = @bpm_estimator.call(beat: beat[:beat])
-        amplitude = rms(samples)
-        spectrum_preview = preview_spectrum(fft[:magnitudes])
+        beat_detected = beat[:beat]
+        confidence = beat_confidence(beat)
+        @beat_pulse = beat_detected ? 1.0 : @beat_pulse * BEAT_PULSE_DECAY
+        @beat_pulse = 0.0 if @beat_pulse < BEAT_PULSE_FLOOR
+        bpm = resolve_bpm(beat_detected)
+        normalized = normalize_features(
+          amplitude: amplitude,
+          bands: bands,
+          fft: preview_spectrum(fft[:magnitudes])
+        )
+        onsets = detect_onsets(amplitude: normalized[:amplitude], bands: normalized[:bands])
+        drums = detect_drum_sources(bands: normalized[:bands], onsets: onsets[:bands])
 
         {
-          amplitude: @smoother.smooth(:amplitude, amplitude),
-          bands: @smoother.smooth_hash(bands, namespace: :bands),
-          fft: @smoother.smooth_array(spectrum_preview, namespace: :fft),
-          beat: beat[:beat],
+          amplitude: @smoother.smooth(:amplitude, normalized[:amplitude]),
+          bands: @smoother.smooth_hash(normalized[:bands], namespace: :bands),
+          fft: @smoother.smooth_array(normalized[:fft], namespace: :fft),
+          onset: onsets[:amplitude],
+          onsets: onsets[:bands],
+          drums: drums,
+          beat: beat_detected,
+          beat_confidence: confidence,
+          beat_pulse: @beat_pulse,
           beat_count: beat[:beat_count],
-          bpm: @smoother.smooth(:bpm, bpm, alpha: 0.2),
+          bpm: bpm,
           peak_frequency: fft[:peak_frequency]
         }
       end
 
       private
 
+      def silence?(amplitude)
+        amplitude < @noise_gate
+      end
+
+      def normalize_noise_gate(value)
+        Float(value).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        DEFAULT_NOISE_GATE
+      end
+
+      def normalize_audio_normalize(value)
+        settings = DEFAULT_AUDIO_NORMALIZE.merge(symbolize_hash(value))
+        mode = settings[:mode].to_s.strip.to_sym
+        raise ArgumentError, "unsupported audio_normalize mode: #{settings[:mode]}" unless %i[off adaptive].include?(mode)
+
+        settings.merge(mode: mode)
+      end
+
+      def normalize_locked_bpm(value, bpm_lock:)
+        return nil unless bpm_lock
+
+        numeric = Float(value)
+        raise ArgumentError, "bpm must be positive when bpm_lock is enabled" unless numeric.positive?
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "bpm must be a positive number when bpm_lock is enabled"
+      end
+
+      def build_normalizer(settings)
+        return nil unless settings[:mode] == :adaptive
+
+        AdaptiveNormalizer.new(
+          window_size: normalization_window_size(settings),
+          target: settings.fetch(:target, AdaptiveNormalizer::DEFAULT_TARGET),
+          floor: settings.fetch(:floor, AdaptiveNormalizer::DEFAULT_FLOOR)
+        )
+      end
+
+      def normalization_window_size(settings)
+        return settings[:window_size] if settings.key?(:window_size)
+
+        seconds = settings.fetch(:window, nil)
+        return AdaptiveNormalizer::DEFAULT_WINDOW_SIZE if seconds.nil?
+
+        (Float(seconds) * @analysis_frame_rate).round.clamp(1, 10_000)
+      rescue ArgumentError, TypeError
+        AdaptiveNormalizer::DEFAULT_WINDOW_SIZE
+      end
+
+      def normalize_features(amplitude:, bands:, fft:)
+        return { amplitude: amplitude, bands: bands, fft: fft } unless @normalizer
+
+        @normalizer.call(amplitude: amplitude, bands: bands, fft: fft)
+      end
+
+      def detect_onsets(amplitude:, bands:)
+        current_amplitude = Float(amplitude).clamp(0.0, 1.0)
+        current_bands = Hash(bands).transform_values { |value| Float(value).clamp(0.0, 1.0) }
+
+        amplitude_onset = positive_delta(current_amplitude, @previous_onset_amplitude)
+        band_onsets = current_bands.each_with_object({}) do |(key, value), output|
+          output[key] = positive_delta(value, @previous_onset_bands[key].to_f)
+        end
+
+        @previous_onset_amplitude = current_amplitude
+        @previous_onset_bands = current_bands
+
+        { amplitude: amplitude_onset, bands: band_onsets }
+      rescue ArgumentError, TypeError
+        { amplitude: 0.0, bands: {} }
+      end
+
+      def positive_delta(current, previous)
+        [current - previous, 0.0].max.clamp(0.0, 1.0)
+      end
+
+      def detect_drum_sources(bands:, onsets:)
+        band_values = Hash(bands)
+        onset_values = Hash(onsets)
+
+        {
+          kick: drum_confidence([:sub, :low], band_values, onset_values),
+          snare: drum_confidence([:mid], band_values, onset_values),
+          hihat: drum_confidence([:high], band_values, onset_values)
+        }
+      end
+
+      def drum_confidence(keys, bands, onsets)
+        level = keys.map { |key| Float(bands[key] || 0.0) }.max || 0.0
+        rise = keys.map { |key| Float(onsets[key] || 0.0) }.max || 0.0
+        (level * rise).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        0.0
+      end
+
+      def silent_frame(reset_tempo:)
+        @beat_pulse = 0.0
+        reset_tempo_state if reset_tempo
+        @smoother.reset if @smoother.respond_to?(:reset)
+        @previous_onset_amplitude = 0.0
+        @previous_onset_bands = {}
+
+        {
+          amplitude: 0.0,
+          bands: { sub: 0.0, low: 0.0, mid: 0.0, high: 0.0 },
+          fft: Array.new(32, 0.0),
+          onset: 0.0,
+          onsets: { sub: 0.0, low: 0.0, mid: 0.0, high: 0.0 },
+          drums: { kick: 0.0, snare: 0.0, hihat: 0.0 },
+          beat: false,
+          beat_confidence: 0.0,
+          beat_pulse: 0.0,
+          beat_count: current_beat_count,
+          bpm: @last_bpm,
+          peak_frequency: 0.0
+        }
+      end
+
+      def reset_tempo_state
+        @last_bpm = @locked_bpm || 0.0
+        @bpm_estimator.reset if @bpm_estimator.respond_to?(:reset)
+      end
+
+      def track_silent_frame(samples)
+        @silent_frame_count += 1
+        @beat_detector.call(samples) if @beat_detector.respond_to?(:call)
+        @last_bpm = @bpm_estimator.call(beat: false).to_f if @bpm_estimator.respond_to?(:call)
+      rescue StandardError
+        nil
+      end
+
+      def sustained_silence?
+        @silent_frame_count == SILENCE_RESET_FRAMES
+      end
+
+      def current_beat_count
+        return Integer(@beat_detector.beat_count) if @beat_detector.respond_to?(:beat_count)
+
+        0
+      rescue StandardError
+        0
+      end
+
+      def beat_confidence(beat)
+        threshold = Float(beat[:threshold])
+        instant_energy = Float(beat[:instant_energy])
+        return beat[:beat] ? 1.0 : 0.0 unless threshold.positive?
+
+        (instant_energy / threshold).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        beat[:beat] ? 1.0 : 0.0
+      end
+
+      def resolve_bpm(beat_detected)
+        return @last_bpm = @locked_bpm if @locked_bpm
+
+        bpm = @bpm_estimator.call(beat: beat_detected)
+        @last_bpm = @smoother.smooth(:bpm, bpm, alpha: 0.2).to_f
+      end
+
       def preview_spectrum(magnitudes, bins: 32)
         values = Array(magnitudes)
         return Array.new(bins, 0.0) if values.empty?
@@ -67,6 +283,14 @@ module Vizcore
       rescue ArgumentError, TypeError
         0.0
       end
+
+      def symbolize_hash(value)
+        Hash(value).each_with_object({}) do |(key, entry), output|
+          output[key.to_sym] = entry
+        end
+      rescue StandardError
+        {}
+      end
     end
   end
 end

data/lib/vizcore/analysis/tap_tempo.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # Estimates a fixed BPM from manual tap timestamps.
+    class TapTempo
+      DEFAULT_MIN_BPM = 40.0
+      DEFAULT_MAX_BPM = 240.0
+      DEFAULT_HISTORY_SIZE = 4
+      DEFAULT_RESET_AFTER_MS = 2_500.0
+
+      def initialize(
+        min_bpm: DEFAULT_MIN_BPM,
+        max_bpm: DEFAULT_MAX_BPM,
+        history_size: DEFAULT_HISTORY_SIZE,
+        reset_after_ms: DEFAULT_RESET_AFTER_MS
+      )
+        @min_bpm = Float(min_bpm)
+        @max_bpm = Float(max_bpm)
+        @history_size = Integer(history_size).clamp(1, 16)
+        @reset_after_ms = Float(reset_after_ms)
+        @last_tap_ms = nil
+        @intervals = []
+      end
+
+      # @param timestamp_ms [Numeric] tap timestamp in milliseconds
+      # @return [Float, nil] estimated BPM after at least two taps
+      def tap(timestamp_ms:)
+        current = Float(timestamp_ms)
+        reset_if_stale(current)
+        return remember_first_tap(current) unless @last_tap_ms
+
+        interval = current - @last_tap_ms
+        @last_tap_ms = current
+        return nil unless valid_interval?(interval)
+
+        @intervals << interval
+        @intervals.shift while @intervals.length > @history_size
+        bpm_from_intervals
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      private
+
+      def reset_if_stale(current)
+        return unless @last_tap_ms
+        return unless current - @last_tap_ms > @reset_after_ms
+
+        @last_tap_ms = nil
+        @intervals.clear
+      end
+
+      def remember_first_tap(current)
+        @last_tap_ms = current
+        nil
+      end
+
+      def valid_interval?(interval)
+        return false unless interval.positive?
+
+        bpm = 60_000.0 / interval
+        bpm.between?(@min_bpm, @max_bpm)
+      end
+
+      def bpm_from_intervals
+        return nil if @intervals.empty?
+
+        average_interval = @intervals.sum / @intervals.length.to_f
+        (60_000.0 / average_interval).clamp(@min_bpm, @max_bpm)
+      end
+    end
+  end
+end

data/lib/vizcore/analysis.rb

@@ -7,8 +7,12 @@ module Vizcore
 end
 
 require_relative "analysis/band_splitter"
+require_relative "analysis/adaptive_normalizer"
 require_relative "analysis/beat_detector"
 require_relative "analysis/bpm_estimator"
 require_relative "analysis/fft_processor"
 require_relative "analysis/pipeline"
+require_relative "analysis/feature_recorder"
+require_relative "analysis/feature_replay"
 require_relative "analysis/smoother"
+require_relative "analysis/tap_tempo"

data/lib/vizcore/audio/dummy_sine_input.rb

@@ -4,7 +4,7 @@ require_relative "base_input"
 
 module Vizcore
   module Audio
-    # Deterministic sine-wave generator used as fallback/dummy source.
+    # Deterministic sine-wave generator used for the explicit dummy source.
     class DummySineInput < BaseInput
       # Default oscillator amplitude.
       DEFAULT_AMPLITUDE = 0.45

data/lib/vizcore/audio/fixture_input.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "base_input"
+
+module Vizcore
+  module Audio
+    # Deterministic sample-frame input for tests and repeatable development checks.
+    class FixtureInput < BaseInput
+      # @param frames [Array<Array<Numeric>>] sample frames returned in order
+      # @param sample_rate [Integer]
+      # @param loop [Boolean] whether to repeat frames after the last one
+      def initialize(frames:, sample_rate: 44_100, loop: true)
+        super(sample_rate: sample_rate)
+        @frames = normalize_frames(frames)
+        @loop = !!loop
+        @index = 0
+      end
+
+      # @param frame_size [Integer]
+      # @return [Array<Float>]
+      def read(frame_size)
+        count = Integer(frame_size)
+        return Array.new(count, 0.0) unless running?
+
+        frame = next_frame
+        return Array.new(count, 0.0) unless frame
+
+        normalize_frame_size(frame, count)
+      end
+
+      # @return [void]
+      def reset
+        @index = 0
+      end
+
+      private
+
+      def next_frame
+        return nil if @frames.empty?
+        return nil if @index >= @frames.length && !@loop
+
+        frame = @frames[@index % @frames.length]
+        @index += 1
+        frame
+      end
+
+      def normalize_frames(frames)
+        Array(frames).map do |frame|
+          values = Array(frame).map { |sample| Float(sample) }
+          raise ArgumentError, "fixture frames must not be empty" if values.empty?
+
+          values
+        end
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "fixture frames must contain numeric samples"
+      end
+
+      def normalize_frame_size(frame, count)
+        return frame.first(count) if frame.length >= count
+
+        frame + Array.new(count - frame.length, 0.0)
+      end
+    end
+  end
+end

data/lib/vizcore/audio/input_manager.rb

@@ -25,11 +25,13 @@ module Vizcore
       # @param frame_size [Integer] frame size used by capture loop
       # @param ring_buffer_size [Integer] stored sample capacity
       # @param file_path [String, nil] source file path for `:file`
-      def initialize(source: :mic, sample_rate: DEFAULT_SAMPLE_RATE, frame_size: DEFAULT_FRAME_SIZE, ring_buffer_size: DEFAULT_RING_BUFFER_SIZE, file_path: nil)
+      # @param audio_device [String, Integer, nil] input device index/name for `:mic`
+      def initialize(source: :mic, sample_rate: DEFAULT_SAMPLE_RATE, frame_size: DEFAULT_FRAME_SIZE, ring_buffer_size: DEFAULT_RING_BUFFER_SIZE, file_path: nil, audio_device: nil)
         @source_name = source.to_sym
         @sample_rate = Integer(sample_rate)
         @frame_size = Integer(frame_size)
         @ring_buffer = RingBuffer.new(ring_buffer_size)
+        @audio_device = audio_device
         @input = build_input(file_path)
         @sample_rate = resolve_input_sample_rate(@input, fallback: @sample_rate)
       end
@@ -110,7 +112,7 @@ module Vizcore
       def build_input(file_path)
         case @source_name
         when :mic
-          MicInput.new(sample_rate: sample_rate)
+          MicInput.new(sample_rate: sample_rate, device: @audio_device || :default)
         when :file
           FileInput.new(path: file_path, sample_rate: sample_rate)
         when :dummy

data/lib/vizcore/audio/mic_input.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "base_input"
-require_relative "dummy_sine_input"
 require_relative "../errors"
 require_relative "portaudio_ffi"
 
 module Vizcore
   module Audio
-    # Microphone input using PortAudio, with automatic fallback to dummy source.
+    # Microphone input using PortAudio, with automatic fallback to silence.
     class MicInput < BaseInput
       attr_reader :device, :last_error
 
@@ -22,7 +21,7 @@ module Vizcore
         @device = device
         @channels = Integer(channels)
         @frames_per_buffer = Integer(frames_per_buffer)
-        @fallback_input = fallback_input || DummySineInput.new(sample_rate: sample_rate)
+        @fallback_input = fallback_input || BaseInput.new(sample_rate: sample_rate)
         @portaudio_backend = portaudio_backend
         @stream = nil
         @using_fallback = false
@@ -75,11 +74,7 @@ module Vizcore
       private
 
       def open_stream
-        stream = @portaudio_backend.open_default_input_stream(
-          sample_rate: sample_rate,
-          channels: @channels,
-          frames_per_buffer: @frames_per_buffer
-        )
+        stream = open_requested_stream
         return nil unless stream
         return stream if stream.start
 
@@ -90,6 +85,27 @@ module Vizcore
         nil
       end
 
+      def open_requested_stream
+        if default_device?
+          return @portaudio_backend.open_default_input_stream(
+            sample_rate: sample_rate,
+            channels: @channels,
+            frames_per_buffer: @frames_per_buffer
+          )
+        end
+
+        @portaudio_backend.open_input_stream(
+          device: @device,
+          sample_rate: sample_rate,
+          channels: @channels,
+          frames_per_buffer: @frames_per_buffer
+        )
+      end
+
+      def default_device?
+        @device.nil? || @device.to_s.empty? || @device.to_s == "default"
+      end
+
       def close_stream
         return unless @stream