vizcore 1.1.0 → 1.2.0

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

data/lib/vizcore/analysis/pipeline.rb

@@ -8,6 +8,11 @@ module Vizcore
       BEAT_PULSE_FLOOR = 0.001
       DEFAULT_NOISE_GATE = 0.01
       DEFAULT_AUDIO_NORMALIZE = { mode: :off }.freeze
+      DEFAULT_FFT_PREVIEW_BINS = 32
+      BEATS_PER_BAR = 4
+      BEATS_PER_PHRASE = 32
+      BEAT_SUBDIVISIONS = { beat_2: 2, beat_4: 4, beat_8: 8, beat_triplet: 3 }.freeze
+      BAND_KEYS = %i[sub low mid high].freeze
       SILENCE_RESET_FRAMES = 90
 
       attr_reader :fft_processor, :band_splitter, :beat_detector, :bpm_estimator, :smoother
@@ -22,7 +27,11 @@ module Vizcore
       # @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)
+      # @param onset_sensitivity [Numeric] multiplier applied to positive onset deltas
+      # @param fft_preview_bins [Integer] number of FFT preview bins included in payloads
+      # @param peak_hold_frames [Integer] frames to hold per-band peak values
+      # @param silence_reset_frames [Integer] silent frames before tempo state resets
+      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, onset_sensitivity: 1.0, fft_preview_bins: DEFAULT_FFT_PREVIEW_BINS, peak_hold_frames: 0, silence_reset_frames: SILENCE_RESET_FRAMES)
         @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
@@ -30,13 +39,20 @@ module Vizcore
         @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
+        self.onset_sensitivity = onset_sensitivity
+        self.fft_preview_bins = fft_preview_bins
+        self.peak_hold_frames = peak_hold_frames
+        self.silence_reset_frames = silence_reset_frames
         @beat_pulse = 0.0
+        @beat_phase = 0.0
         @last_bpm = 0.0
+        self.bpm_lock = { bpm: bpm, locked: bpm_lock }
+        self.audio_normalize = audio_normalize
         @silent_frame_count = 0
+        @band_peak_state = {}
         @previous_onset_amplitude = 0.0
         @previous_onset_bands = {}
+        @previous_flux_spectrum = nil
       end
 
       # @param settings [Hash, nil]
@@ -54,6 +70,30 @@ module Vizcore
         @last_bpm = @locked_bpm if @locked_bpm
       end
 
+      # @param value [Numeric]
+      # @return [Float]
+      def onset_sensitivity=(value)
+        @onset_sensitivity = normalize_positive_number(value, fallback: 1.0)
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def fft_preview_bins=(value)
+        @fft_preview_bins = normalize_integer(value, fallback: DEFAULT_FFT_PREVIEW_BINS, min: 8, max: 128)
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def peak_hold_frames=(value)
+        @peak_hold_frames = normalize_integer(value, fallback: 0, min: 0, max: 10_000)
+      end
+
+      # @param value [Integer]
+      # @return [Integer]
+      def silence_reset_frames=(value)
+        @silence_reset_frames = normalize_integer(value, fallback: SILENCE_RESET_FRAMES, min: 1, max: 10_000)
+      end
+
       # @param samples [Array<Numeric>] audio frame samples
       # @return [Hash] normalized analysis payload consumed by frame broadcaster
       def call(samples)
@@ -73,17 +113,24 @@ module Vizcore
         @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)
+        tempo = tempo_features(beat_detected: beat_detected, beat_count: beat[:beat_count], bpm: bpm)
+        peak = peak_level(samples)
+        spectrum_preview = preview_spectrum(fft[:magnitudes], bins: @fft_preview_bins)
+        spectral = spectral_features(fft[:magnitudes], spectrum_preview)
         normalized = normalize_features(
           amplitude: amplitude,
           bands: bands,
-          fft: preview_spectrum(fft[:magnitudes])
+          fft: spectrum_preview
         )
+        band_peaks = update_band_peaks(normalized[:bands])
         onsets = detect_onsets(amplitude: normalized[:amplitude], bands: normalized[:bands])
         drums = detect_drum_sources(bands: normalized[:bands], onsets: onsets[:bands])
 
         {
           amplitude: @smoother.smooth(:amplitude, normalized[:amplitude]),
+          peak: peak,
           bands: @smoother.smooth_hash(normalized[:bands], namespace: :bands),
+          band_peaks: band_peaks,
           fft: @smoother.smooth_array(normalized[:fft], namespace: :fft),
           onset: onsets[:amplitude],
           onsets: onsets[:bands],
@@ -92,7 +139,21 @@ module Vizcore
           beat_confidence: confidence,
           beat_pulse: @beat_pulse,
           beat_count: beat[:beat_count],
+          beat_phase: tempo[:beat_phase],
+          beat_2: tempo[:beat_2],
+          beat_4: tempo[:beat_4],
+          beat_8: tempo[:beat_8],
+          beat_triplet: tempo[:beat_triplet],
+          bar_phase: tempo[:bar_phase],
+          bar_count: tempo[:bar_count],
+          phrase_count: tempo[:phrase_count],
           bpm: bpm,
+          bpm_confidence: bpm_confidence,
+          spectral_centroid: spectral[:centroid],
+          spectral_rolloff: spectral[:rolloff],
+          spectral_flatness: spectral[:flatness],
+          spectral_flux: spectral[:flux],
+          zero_crossing_rate: zero_crossing_rate(samples),
           peak_frequency: fft[:peak_frequency]
         }
       end
@@ -109,6 +170,21 @@ module Vizcore
         DEFAULT_NOISE_GATE
       end
 
+      def normalize_positive_number(value, fallback:)
+        numeric = Float(value)
+        return fallback unless numeric.finite? && numeric.positive?
+
+        numeric
+      rescue ArgumentError, TypeError
+        fallback
+      end
+
+      def normalize_integer(value, fallback:, min:, max:)
+        Integer(value).clamp(min, max)
+      rescue ArgumentError, TypeError
+        fallback
+      end
+
       def normalize_audio_normalize(value)
         settings = DEFAULT_AUDIO_NORMALIZE.merge(symbolize_hash(value))
         mode = settings[:mode].to_s.strip.to_sym
@@ -134,7 +210,8 @@ module Vizcore
         AdaptiveNormalizer.new(
           window_size: normalization_window_size(settings),
           target: settings.fetch(:target, AdaptiveNormalizer::DEFAULT_TARGET),
-          floor: settings.fetch(:floor, AdaptiveNormalizer::DEFAULT_FLOOR)
+          floor: settings.fetch(:floor, AdaptiveNormalizer::DEFAULT_FLOOR),
+          per_band: settings.fetch(:per_band, false)
         )
       end
 
@@ -155,6 +232,25 @@ module Vizcore
         @normalizer.call(amplitude: amplitude, bands: bands, fft: fft)
       end
 
+      def update_band_peaks(bands)
+        values = zero_bands.merge(symbolize_hash(bands))
+        return values.transform_values { |value| Float(value).clamp(0.0, 1.0) } if @peak_hold_frames <= 0
+
+        values.each_with_object({}) do |(key, value), output|
+          current = Float(value).clamp(0.0, 1.0)
+          state = @band_peak_state[key] || { value: 0.0, remaining: 0 }
+          if current >= state[:value].to_f || state[:remaining].to_i <= 0
+            @band_peak_state[key] = { value: current, remaining: @peak_hold_frames }
+            output[key] = current
+          else
+            @band_peak_state[key] = { value: state[:value].to_f, remaining: state[:remaining].to_i - 1 }
+            output[key] = state[:value].to_f
+          end
+        end
+      rescue StandardError
+        zero_bands
+      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) }
@@ -173,7 +269,7 @@ module Vizcore
       end
 
       def positive_delta(current, previous)
-        [current - previous, 0.0].max.clamp(0.0, 1.0)
+        ([current - previous, 0.0].max * @onset_sensitivity).clamp(0.0, 1.0)
       end
 
       def detect_drum_sources(bands:, onsets:)
@@ -198,14 +294,19 @@ module Vizcore
       def silent_frame(reset_tempo:)
         @beat_pulse = 0.0
         reset_tempo_state if reset_tempo
+        tempo = tempo_features(beat_detected: false, beat_count: current_beat_count, bpm: @last_bpm, advance: !reset_tempo)
         @smoother.reset if @smoother.respond_to?(:reset)
+        @band_peak_state.clear
         @previous_onset_amplitude = 0.0
         @previous_onset_bands = {}
+        @previous_flux_spectrum = nil
 
         {
           amplitude: 0.0,
-          bands: { sub: 0.0, low: 0.0, mid: 0.0, high: 0.0 },
-          fft: Array.new(32, 0.0),
+          peak: 0.0,
+          bands: zero_bands,
+          band_peaks: zero_bands,
+          fft: Array.new(@fft_preview_bins, 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 },
@@ -213,13 +314,29 @@ module Vizcore
           beat_confidence: 0.0,
           beat_pulse: 0.0,
           beat_count: current_beat_count,
+          beat_phase: tempo[:beat_phase],
+          beat_2: tempo[:beat_2],
+          beat_4: tempo[:beat_4],
+          beat_8: tempo[:beat_8],
+          beat_triplet: tempo[:beat_triplet],
+          bar_phase: tempo[:bar_phase],
+          bar_count: tempo[:bar_count],
+          phrase_count: tempo[:phrase_count],
           bpm: @last_bpm,
+          bpm_confidence: bpm_confidence,
+          spectral_centroid: 0.0,
+          spectral_rolloff: 0.0,
+          spectral_flatness: 0.0,
+          spectral_flux: 0.0,
+          zero_crossing_rate: 0.0,
           peak_frequency: 0.0
         }
       end
 
       def reset_tempo_state
         @last_bpm = @locked_bpm || 0.0
+        @beat_phase = 0.0
+        @previous_flux_spectrum = nil
         @bpm_estimator.reset if @bpm_estimator.respond_to?(:reset)
       end
 
@@ -232,7 +349,7 @@ module Vizcore
       end
 
       def sustained_silence?
-        @silent_frame_count == SILENCE_RESET_FRAMES
+        @silent_frame_count == @silence_reset_frames
       end
 
       def current_beat_count
@@ -243,6 +360,10 @@ module Vizcore
         0
       end
 
+      def zero_bands
+        BAND_KEYS.to_h { |key| [key, 0.0] }
+      end
+
       def beat_confidence(beat)
         threshold = Float(beat[:threshold])
         instant_energy = Float(beat[:instant_energy])
@@ -260,6 +381,116 @@ module Vizcore
         @last_bpm = @smoother.smooth(:bpm, bpm, alpha: 0.2).to_f
       end
 
+      def tempo_features(beat_detected:, beat_count:, bpm:, advance: true)
+        previous_phase = @beat_phase
+        @beat_phase = advance ? next_beat_phase(beat_detected: beat_detected, bpm: bpm) : 0.0
+        count = non_negative_integer(beat_count)
+        beat_index = count.positive? ? count - 1 : 0
+
+        subdivision_pulses = BEAT_SUBDIVISIONS.transform_values do |divisions|
+          beat_detected || crossed_subdivision?(previous_phase, @beat_phase, divisions)
+        end
+
+        {
+          beat_phase: @beat_phase,
+          bar_phase: (((beat_index % BEATS_PER_BAR) + @beat_phase) / BEATS_PER_BAR.to_f).clamp(0.0, 1.0),
+          bar_count: beat_index / BEATS_PER_BAR,
+          phrase_count: beat_index / BEATS_PER_PHRASE
+        }.merge(subdivision_pulses)
+      end
+
+      def next_beat_phase(beat_detected:, bpm:)
+        return 0.0 if beat_detected
+
+        numeric_bpm = Float(bpm)
+        return 0.0 unless numeric_bpm.positive? && @analysis_frame_rate.positive?
+
+        (@beat_phase + (numeric_bpm / 60.0 / @analysis_frame_rate)) % 1.0
+      rescue ArgumentError, TypeError
+        0.0
+      end
+
+      def crossed_subdivision?(previous_phase, current_phase, divisions)
+        previous_step = (Float(previous_phase) * divisions).floor
+        current_step = (Float(current_phase) * divisions).floor
+        current_phase < previous_phase || current_step > previous_step
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def non_negative_integer(value)
+        [Integer(value || 0), 0].max
+      rescue ArgumentError, TypeError
+        0
+      end
+
+      def bpm_confidence
+        return 1.0 if @locked_bpm
+        return @bpm_estimator.confidence.to_f if @bpm_estimator.respond_to?(:confidence)
+
+        @last_bpm.to_f.positive? ? 1.0 : 0.0
+      rescue StandardError
+        0.0
+      end
+
+      def spectral_features(magnitudes, spectrum_preview)
+        values = Array(magnitudes).map { |value| Float(value).abs }
+        return zero_spectral_features if values.empty?
+
+        total = values.sum
+        return zero_spectral_features unless total.positive?
+
+        {
+          centroid: spectral_centroid(values, total),
+          rolloff: spectral_rolloff(values, total),
+          flatness: spectral_flatness(values),
+          flux: spectral_flux(spectrum_preview)
+        }
+      rescue StandardError
+        zero_spectral_features
+      end
+
+      def zero_spectral_features
+        { centroid: 0.0, rolloff: 0.0, flatness: 0.0, flux: 0.0 }
+      end
+
+      def spectral_centroid(values, total)
+        weighted = values.each_with_index.sum do |magnitude, index|
+          @fft_processor.bin_frequency(index) * magnitude
+        end
+        weighted / total
+      end
+
+      def spectral_rolloff(values, total, threshold: 0.85)
+        target = total * threshold
+        running = 0.0
+        index = values.index do |magnitude|
+          running += magnitude
+          running >= target
+        end
+        @fft_processor.bin_frequency(index || 0)
+      end
+
+      def spectral_flatness(values)
+        epsilon = 1e-12
+        arithmetic_mean = values.sum / values.length.to_f
+        return 0.0 unless arithmetic_mean.positive?
+
+        log_mean = values.sum { |value| Math.log([value, epsilon].max) } / values.length.to_f
+        (Math.exp(log_mean) / arithmetic_mean).clamp(0.0, 1.0)
+      end
+
+      def spectral_flux(spectrum_preview)
+        current = Array(spectrum_preview).map { |value| Float(value).clamp(0.0, 1.0) }
+        previous = @previous_flux_spectrum
+        @previous_flux_spectrum = current
+        return 0.0 unless previous && previous.length == current.length
+
+        Math.sqrt(current.each_with_index.sum { |value, index| [value - previous[index], 0.0].max**2 }).clamp(0.0, 1.0)
+      rescue StandardError
+        0.0
+      end
+
       def preview_spectrum(magnitudes, bins: 32)
         values = Array(magnitudes)
         return Array.new(bins, 0.0) if values.empty?
@@ -284,6 +515,24 @@ module Vizcore
         0.0
       end
 
+      def peak_level(samples)
+        Array(samples).map { |sample| Float(sample).abs }.max.to_f.clamp(0.0, 1.0)
+      rescue StandardError
+        0.0
+      end
+
+      def zero_crossing_rate(samples)
+        values = Array(samples).map { |sample| Float(sample) }
+        return 0.0 if values.length < 2
+
+        crossings = values.each_cons(2).count do |previous, current|
+          (previous.negative? && current >= 0.0) || (previous.positive? && current <= 0.0)
+        end
+        (crossings / (values.length - 1).to_f).clamp(0.0, 1.0)
+      rescue StandardError
+        0.0
+      end
+
       def symbolize_hash(value)
         Hash(value).each_with_object({}) do |(key, entry), output|
           output[key.to_sym] = entry

data/lib/vizcore/analysis/tap_tempo.rb

@@ -66,8 +66,23 @@ module Vizcore
       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)
+        interval = robust_interval(@intervals)
+        (60_000.0 / interval).clamp(@min_bpm, @max_bpm)
+      end
+
+      def robust_interval(intervals)
+        sorted = intervals.sort
+        return median(sorted) if sorted.length < 4
+
+        trimmed = sorted[1...-1]
+        trimmed.sum / trimmed.length.to_f
+      end
+
+      def median(sorted)
+        midpoint = sorted.length / 2
+        return sorted[midpoint] if sorted.length.odd?
+
+        (sorted[midpoint - 1] + sorted[midpoint]) / 2.0
       end
     end
   end

data/lib/vizcore/audio/calibration.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "input_manager"
+
+module Vizcore
+  module Audio
+    # Samples an audio input and derives practical level/noise-gate metrics.
+    class Calibration
+      DEFAULT_DURATION = 3.0
+      DEFAULT_FPS = 20.0
+
+      Result = Struct.new(
+        :source,
+        :sample_rate,
+        :frame_size,
+        :frames,
+        :rms_mean,
+        :rms_p95,
+        :peak_max,
+        :clip_ratio,
+        :recommended_noise_gate,
+        keyword_init: true
+      ) do
+        def to_h
+          {
+            source: source,
+            sample_rate: sample_rate,
+            frame_size: frame_size,
+            frames: frames,
+            rms_mean: rms_mean,
+            rms_p95: rms_p95,
+            peak_max: peak_max,
+            clip_ratio: clip_ratio,
+            recommended_noise_gate: recommended_noise_gate
+          }
+        end
+      end
+
+      # @param source [String, Symbol]
+      # @param file_path [String, nil]
+      # @param audio_device [String, nil]
+      # @param duration [Numeric]
+      # @param fps [Numeric]
+      # @param input_manager_factory [#call]
+      # @param sleeper [#call]
+      def initialize(
+        source: :mic,
+        file_path: nil,
+        audio_device: nil,
+        duration: DEFAULT_DURATION,
+        fps: DEFAULT_FPS,
+        input_manager_factory: nil,
+        sleeper: ->(seconds) { sleep(seconds) }
+      )
+        @source = source.to_sym
+        @file_path = file_path
+        @audio_device = audio_device
+        @duration = positive_float(duration, "duration")
+        @fps = positive_float(fps, "fps")
+        @input_manager_factory = input_manager_factory || method(:build_input_manager)
+        @sleeper = sleeper
+      end
+
+      # @return [Result]
+      def call
+        manager = @input_manager_factory.call(source: @source, file_path: @file_path, audio_device: @audio_device)
+        rms_values = []
+        peak_values = []
+        manager.start
+        frame_count.times do
+          samples = manager.capture_frame(manager.realtime_capture_size(@fps))
+          rms_values << rms(samples)
+          peak_values << peak(samples)
+          @sleeper.call(1.0 / @fps) if @source == :mic
+        end
+
+        build_result(manager, rms_values, peak_values)
+      ensure
+        manager&.stop
+      end
+
+      private
+
+      def build_input_manager(source:, file_path:, audio_device:)
+        Vizcore::Audio::InputManager.new(source: source, file_path: file_path, audio_device: audio_device)
+      end
+
+      def build_result(manager, rms_values, peak_values)
+        peak_max = peak_values.max.to_f
+        Result.new(
+          source: manager.source_name.to_s,
+          sample_rate: manager.sample_rate,
+          frame_size: manager.frame_size,
+          frames: rms_values.length,
+          rms_mean: round_metric(mean(rms_values)),
+          rms_p95: round_metric(percentile(rms_values, 0.95)),
+          peak_max: round_metric(peak_max),
+          clip_ratio: round_metric(clip_ratio(peak_values)),
+          recommended_noise_gate: round_metric(recommended_noise_gate(rms_values))
+        )
+      end
+
+      def frame_count
+        [(@duration * @fps).ceil, 1].max
+      end
+
+      def rms(samples)
+        values = Array(samples)
+        return 0.0 if values.empty?
+
+        Math.sqrt(values.sum { |sample| sample.to_f * sample.to_f } / values.length.to_f)
+      end
+
+      def peak(samples)
+        Array(samples).map { |sample| sample.to_f.abs }.max.to_f
+      end
+
+      def mean(values)
+        return 0.0 if values.empty?
+
+        values.sum / values.length.to_f
+      end
+
+      def percentile(values, ratio)
+        sorted = values.sort
+        return 0.0 if sorted.empty?
+
+        sorted[((sorted.length - 1) * ratio).round]
+      end
+
+      def clip_ratio(peaks)
+        return 0.0 if peaks.empty?
+
+        peaks.count { |value| value >= 0.98 } / peaks.length.to_f
+      end
+
+      def recommended_noise_gate(rms_values)
+        baseline = percentile(rms_values, 0.50)
+        [[baseline * 1.5, 0.001].max, 0.25].min
+      end
+
+      def round_metric(value)
+        value.to_f.round(6)
+      end
+
+      def positive_float(value, label)
+        numeric = Float(value)
+        raise ArgumentError, "#{label} must be positive" unless numeric.positive?
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{label} must be positive"
+      end
+    end
+  end
+end

data/lib/vizcore/audio/file_input.rb

@@ -67,6 +67,34 @@ module Vizcore
         self
       end
 
+      # @return [Float] current playback position in seconds (looped)
+      def transport_position_seconds
+        @state_mutex.synchronize do
+          return 0.0 if @samples.empty?
+
+          rate = @stream_sample_rate.to_f.positive? ? @stream_sample_rate.to_f : sample_rate.to_f
+          return 0.0 if rate <= 0
+
+          @cursor.to_f / rate
+        end
+      rescue StandardError
+        0.0
+      end
+
+      # @return [Float] looped track duration in seconds
+      def track_duration_seconds
+        @state_mutex.synchronize do
+          return 0.0 if @samples.empty?
+
+          rate = @stream_sample_rate.to_f.positive? ? @stream_sample_rate.to_f : sample_rate.to_f
+          return 0.0 if rate <= 0
+
+          @samples.length.to_f / rate
+        end
+      rescue StandardError
+        0.0
+      end
+
       private
 
       def load_samples