vizcore 1.0.0 → 1.2.0

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)

data/lib/vizcore/analysis/feature_replay.rb

@@ -8,7 +8,7 @@ module Vizcore
   module Analysis
     # Replays recorded analysis features as a pipeline-compatible source.
     class FeatureReplay
-      attr_reader :metadata
+      attr_reader :metadata, :cursor
 
       def initialize(path:)
         @path = Pathname.new(path.to_s).expand_path
@@ -30,8 +30,48 @@ module Vizcore
         @features.length
       end
 
+      # Move the replay cursor to a frame index.
+      #
+      # @param index [Integer]
+      # @return [Vizcore::Analysis::FeatureReplay]
+      def seek(index)
+        @cursor = normalize_index(index)
+        self
+      end
+
+      # Move the replay cursor to the frame nearest to the given timestamp.
+      #
+      # @param seconds [Numeric]
+      # @return [Vizcore::Analysis::FeatureReplay]
+      def seek_seconds(seconds)
+        fps = metadata_fps
+        raise ArgumentError, "feature metadata fps must be positive to seek by seconds" unless fps.positive?
+
+        seek((numeric_seconds(seconds) * fps).floor)
+      end
+
+      # Read a specific feature frame without changing the replay cursor.
+      #
+      # @param index [Integer]
+      # @return [Hash<Symbol, Object>]
+      def frame(index)
+        deep_dup(@features.fetch(normalize_index(index)))
+      end
+
       private
 
+      def metadata_fps
+        Float(metadata[:fps] || metadata["fps"] || 0.0)
+      rescue ArgumentError, TypeError
+        0.0
+      end
+
+      def numeric_seconds(value)
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "seconds must be numeric"
+      end
+
       def load_payload
         raise ArgumentError, "Feature file not found: #{@path}" unless @path.file?
 
@@ -56,6 +96,12 @@ module Vizcore
         features
       end
 
+      def normalize_index(value)
+        Integer(value) % @features.length
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "feature frame index must be an integer"
+      end
+
       def deep_symbolize(value)
         case value
         when Hash
@@ -70,14 +116,7 @@ module Vizcore
       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
+        Vizcore::DeepCopy.copy(value)
       end
     end
   end