vizcore 0.1.0

data/lib/vizcore/analysis/pipeline.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # End-to-end analysis pipeline from PCM samples to renderer-ready features.
+    class Pipeline
+      attr_reader :fft_processor, :band_splitter, :beat_detector, :bpm_estimator, :smoother
+
+      # @param sample_rate [Integer]
+      # @param fft_size [Integer]
+      # @param window [Symbol]
+      # @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)
+        @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)
+        @smoother = smoother || Smoother.new(alpha: 0.35)
+      end
+
+      # @param samples [Array<Numeric>] audio frame samples
+      # @return [Hash] normalized analysis payload consumed by frame broadcaster
+      def call(samples)
+        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])
+
+        {
+          amplitude: @smoother.smooth(:amplitude, amplitude),
+          bands: @smoother.smooth_hash(bands, namespace: :bands),
+          fft: @smoother.smooth_array(spectrum_preview, namespace: :fft),
+          beat: beat[:beat],
+          beat_count: beat[:beat_count],
+          bpm: @smoother.smooth(:bpm, bpm, alpha: 0.2),
+          peak_frequency: fft[:peak_frequency]
+        }
+      end
+
+      private
+
+      def preview_spectrum(magnitudes, bins: 32)
+        values = Array(magnitudes)
+        return Array.new(bins, 0.0) if values.empty?
+
+        step = [values.length / bins, 1].max
+
+        Array.new(bins) do |index|
+          window = values[index * step, step]
+          next 0.0 if window.nil? || window.empty?
+
+          (window.sum / window.length.to_f).clamp(0.0, 1.0)
+        end
+      end
+
+      def rms(samples)
+        values = Array(samples).map { |sample| Float(sample) }
+        return 0.0 if values.empty?
+
+        sum = values.reduce(0.0) { |acc, sample| acc + sample * sample }
+        Math.sqrt(sum / values.length.to_f).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        0.0
+      end
+    end
+  end
+end

data/lib/vizcore/analysis/smoother.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Analysis
+    # Utility for smoothing scalar, hash, and array signals with EMA.
+    class Smoother
+      # @param alpha [Float] default smoothing coefficient (0.0..1.0)
+      def initialize(alpha: 0.35)
+        @alpha = normalize_alpha(alpha)
+        @states = {}
+      end
+
+      # Smooth one scalar value under a key.
+      #
+      # @param key [Object] state key
+      # @param value [Numeric]
+      # @param alpha [Float]
+      # @return [Float]
+      def smooth(key, value, alpha: @alpha)
+        normalized = Float(value)
+        step = normalize_alpha(alpha)
+        previous = @states[key]
+        current = previous.nil? ? normalized : previous + (normalized - previous) * step
+        @states[key] = current
+      rescue ArgumentError, TypeError
+        0.0
+      end
+
+      # Smooth each value in a hash independently.
+      #
+      # @param values [Hash]
+      # @param namespace [Object]
+      # @param alpha [Float]
+      # @return [Hash]
+      def smooth_hash(values, namespace:, alpha: @alpha)
+        Hash(values).each_with_object({}) do |(entry_key, value), result|
+          result[entry_key] = smooth([namespace, entry_key], value, alpha: alpha)
+        end
+      end
+
+      # Smooth each value in an array independently.
+      #
+      # @param values [Array]
+      # @param namespace [Object]
+      # @param alpha [Float]
+      # @return [Array<Float>]
+      def smooth_array(values, namespace:, alpha: @alpha)
+        Array(values).each_with_index.map do |value, index|
+          smooth([namespace, index], value, alpha: alpha)
+        end
+      end
+
+      # Reset smoothing state.
+      #
+      # @param namespace [Object, nil] when provided, resets keys under this namespace only
+      # @return [void]
+      def reset(namespace = nil)
+        return @states.clear if namespace.nil?
+
+        @states.delete_if do |key, _value|
+          key.is_a?(Array) && key.first == namespace
+        end
+      end
+
+      private
+
+      def normalize_alpha(value)
+        Float(value).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        0.35
+      end
+    end
+  end
+end

data/lib/vizcore/analysis.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Analysis components used to transform raw audio into visual parameters.
+  module Analysis
+  end
+end
+
+require_relative "analysis/band_splitter"
+require_relative "analysis/beat_detector"
+require_relative "analysis/bpm_estimator"
+require_relative "analysis/fft_processor"
+require_relative "analysis/pipeline"
+require_relative "analysis/smoother"

data/lib/vizcore/audio/base_input.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Audio
+    # Base class for audio inputs used by {Vizcore::Audio::InputManager}.
+    class BaseInput
+      attr_reader :sample_rate
+
+      # @param sample_rate [Integer]
+      def initialize(sample_rate: 44_100)
+        @sample_rate = Integer(sample_rate)
+        @running = false
+      end
+
+      # @return [Vizcore::Audio::BaseInput]
+      def start
+        @running = true
+        self
+      end
+
+      # @return [Vizcore::Audio::BaseInput]
+      def stop
+        @running = false
+        self
+      end
+
+      # @return [Boolean]
+      def running?
+        @running
+      end
+
+      # @param frame_size [Integer]
+      # @return [Array<Float>] silence by default
+      def read(frame_size)
+        Array.new(Integer(frame_size), 0.0)
+      end
+    end
+  end
+end

data/lib/vizcore/audio/dummy_sine_input.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base_input"
+
+module Vizcore
+  module Audio
+    # Deterministic sine-wave generator used as fallback/dummy source.
+    class DummySineInput < BaseInput
+      # Default oscillator amplitude.
+      DEFAULT_AMPLITUDE = 0.45
+      # Default oscillator frequency in Hz.
+      DEFAULT_FREQUENCY = 220.0
+
+      # @param sample_rate [Integer]
+      # @param frequency [Float] sine frequency in Hz
+      # @param amplitude [Float] clamped to 0.0..1.0
+      def initialize(sample_rate: 44_100, frequency: DEFAULT_FREQUENCY, amplitude: DEFAULT_AMPLITUDE)
+        super(sample_rate: sample_rate)
+        @frequency = Float(frequency)
+        @amplitude = Float(amplitude).clamp(0.0, 1.0)
+        @phase = 0.0
+      end
+
+      # @param frame_size [Integer]
+      # @return [Array<Float>] generated sine wave samples
+      def read(frame_size)
+        count = Integer(frame_size)
+        return Array.new(count, 0.0) unless running?
+
+        step = (2.0 * Math::PI * @frequency) / sample_rate
+
+        Array.new(count) do
+          value = Math.sin(@phase) * @amplitude
+          @phase += step
+          value
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/audio/file_input.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "open3"
+require "thread"
+require_relative "../errors"
+require_relative "base_input"
+
+module Vizcore
+  module Audio
+    # File-backed audio input for WAV and ffmpeg-decoded formats.
+    class FileInput < BaseInput
+      # Supported file extensions.
+      SUPPORTED_EXTENSIONS = %w[.wav .mp3 .flac].freeze
+      attr_reader :last_error
+      attr_reader :stream_sample_rate
+
+      # @param path [String, Pathname]
+      # @param sample_rate [Integer]
+      # @param command_runner [#capture3]
+      # @param ffmpeg_checker [#call, nil]
+      def initialize(path:, sample_rate: 44_100, command_runner: Open3, ffmpeg_checker: nil)
+        super(sample_rate: sample_rate)
+        @path = path
+        @command_runner = command_runner
+        @ffmpeg_checker = ffmpeg_checker || method(:ffmpeg_available?)
+        @cursor = 0
+        @last_error = nil
+        @stream_sample_rate = sample_rate
+        @state_mutex = Mutex.new
+        @transport_paused = false
+        @samples = load_samples
+      end
+
+      # @param frame_size [Integer]
+      # @return [Array<Float>] file samples (looped), or silence when unavailable
+      def read(frame_size)
+        count = Integer(frame_size)
+        return Array.new(count, 0.0) unless running?
+        return Array.new(count, 0.0) if @samples.empty?
+
+        @state_mutex.synchronize do
+          return Array.new(count, 0.0) if @transport_paused
+
+          Array.new(count) do
+            sample = @samples[@cursor]
+            @cursor = (@cursor + 1) % @samples.length
+            sample
+          end
+        end
+      end
+
+      # Synchronize file cursor with an external playback transport (browser audio element).
+      #
+      # @param playing [Boolean]
+      # @param position_seconds [Numeric]
+      # @return [Vizcore::Audio::FileInput]
+      def sync_transport(playing:, position_seconds:)
+        return self if @samples.empty?
+
+        seconds = Float(position_seconds)
+        @state_mutex.synchronize do
+          @transport_paused = !playing
+          @cursor = seconds_to_cursor(seconds)
+        end
+        self
+      rescue StandardError
+        self
+      end
+
+      private
+
+      def load_samples
+        return [] unless @path
+        return record_error(AudioSourceError.new("Audio file not found: #{@path}")) unless File.file?(@path)
+        return record_error(AudioSourceError.new("Unsupported audio format: #{extension}")) unless SUPPORTED_EXTENSIONS.include?(extension)
+
+        return load_wav_samples if extension == ".wav"
+
+        load_compressed_samples
+      end
+
+      def extension
+        File.extname(@path).downcase
+      end
+
+      def load_wav_samples
+        require "wavefile"
+
+        samples = []
+        WaveFile::Reader.new(@path) do |reader|
+          @stream_sample_rate = reader.native_format.sample_rate
+
+          reader.each_buffer(1024) do |buffer|
+            mono = if buffer.channels == 1
+                     buffer.samples
+                   else
+                     buffer.samples.map { |frame| frame.is_a?(Array) ? frame.sum / frame.length.to_f : frame }
+                   end
+            samples.concat(mono.map { |sample| Float(sample) })
+          end
+        end
+        @last_error = nil
+        samples
+      rescue LoadError => e
+        record_error(
+          AudioSourceError.new(
+            "wavefile gem is required for WAV input: #{e.message}"
+          )
+        )
+      end
+
+      def load_compressed_samples
+        return record_error(AudioSourceError.new("ffmpeg is unavailable")) unless @ffmpeg_checker.call
+
+        stdout, _stderr, status = @command_runner.capture3(*ffmpeg_decode_command)
+        return record_error(AudioSourceError.new("ffmpeg decode failed with non-zero status")) unless status.success?
+
+        @last_error = nil
+        stdout.unpack("e*").map { |sample| Float(sample) }
+      rescue StandardError => e
+        record_error(AudioSourceError.new("ffmpeg decode failed: #{e.message}"))
+      end
+
+      def ffmpeg_decode_command
+        [
+          "ffmpeg",
+          "-hide_banner",
+          "-loglevel",
+          "error",
+          "-i",
+          @path.to_s,
+          "-f",
+          "f32le",
+          "-ac",
+          "1",
+          "-ar",
+          sample_rate.to_s,
+          "pipe:1"
+        ]
+      end
+
+      def ffmpeg_available?
+        system("ffmpeg", "-version", out: File::NULL, err: File::NULL)
+      rescue StandardError
+        false
+      end
+
+      def record_error(error)
+        @last_error = error
+        []
+      end
+
+      def seconds_to_cursor(seconds)
+        return 0 if @samples.empty?
+
+        rate = @stream_sample_rate.to_f.positive? ? @stream_sample_rate.to_f : sample_rate.to_f
+        index = (seconds * rate).floor
+        index %= @samples.length
+        index.negative? ? index + @samples.length : index
+      end
+    end
+  end
+end

data/lib/vizcore/audio/input_manager.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "dummy_sine_input"
+require_relative "file_input"
+require_relative "mic_input"
+require_relative "midi_input"
+require_relative "portaudio_ffi"
+require_relative "ring_buffer"
+
+module Vizcore
+  module Audio
+    # High-level coordinator for audio frame capture and ring-buffer storage.
+    class InputManager
+      # Default analysis/input sample rate.
+      DEFAULT_SAMPLE_RATE = 44_100
+      # Default samples read per frame.
+      DEFAULT_FRAME_SIZE = 1024
+      # Default ring buffer capacity in samples.
+      DEFAULT_RING_BUFFER_SIZE = 4096
+
+      attr_reader :frame_size, :sample_rate, :ring_buffer, :source_name
+
+      # @param source [Symbol, String] input source (`:mic`, `:file`, `:dummy`)
+      # @param sample_rate [Integer] sample rate in Hz
+      # @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)
+        @source_name = source.to_sym
+        @sample_rate = Integer(sample_rate)
+        @frame_size = Integer(frame_size)
+        @ring_buffer = RingBuffer.new(ring_buffer_size)
+        @input = build_input(file_path)
+        @sample_rate = resolve_input_sample_rate(@input, fallback: @sample_rate)
+      end
+
+      # @return [Vizcore::Audio::InputManager]
+      def start
+        @input.start
+        self
+      end
+
+      # @return [Vizcore::Audio::InputManager]
+      def stop
+        @input.stop
+        self
+      end
+
+      # @return [Boolean]
+      def running?
+        @input.running?
+      end
+
+      # Capture one frame from the underlying input and append to ring buffer.
+      #
+      # @return [Array<Float>]
+      def capture_frame(read_size = frame_size)
+        count = Integer(read_size)
+        samples = @input.read(count)
+        ring_buffer.write(samples)
+        samples
+      end
+
+      # @param count [Integer]
+      # @return [Array<Float>] recent samples from the ring buffer
+      def latest_samples(count = frame_size)
+        ring_buffer.latest(count)
+      end
+
+      # @param frame_rate [Numeric]
+      # @return [Integer] approximate real-time sample count to ingest per render tick
+      def realtime_capture_size(frame_rate)
+        rate = Float(frame_rate)
+        return frame_size unless rate.positive?
+
+        [(@sample_rate.to_f / rate).round, 1].max
+      rescue StandardError
+        frame_size
+      end
+
+      # @param playing [Boolean]
+      # @param position_seconds [Numeric]
+      # @return [void]
+      def sync_transport(playing:, position_seconds:)
+        return unless @input.respond_to?(:sync_transport)
+
+        @input.sync_transport(playing: playing, position_seconds: position_seconds)
+      end
+
+      # @return [Array<Hash>] detected audio devices or fallback dummy descriptor
+      def self.available_audio_devices
+        devices = PortAudioFFI.input_devices
+        return devices unless devices.empty?
+
+        [
+          { index: 0, name: "default (dummy fallback)", max_input_channels: 1, default_sample_rate: DEFAULT_SAMPLE_RATE.to_f }
+        ]
+      end
+
+      # @return [Array<Hash>] detected MIDI devices or virtual fallback descriptor
+      def self.available_midi_devices
+        devices = MidiInput.available_devices
+        return devices unless devices.empty?
+
+        [{ id: "virtual-0", name: "virtual-midi (optional dependency: unimidi)" }]
+      end
+
+      private
+
+      def build_input(file_path)
+        case @source_name
+        when :mic
+          MicInput.new(sample_rate: sample_rate)
+        when :file
+          FileInput.new(path: file_path, sample_rate: sample_rate)
+        when :dummy
+          DummySineInput.new(sample_rate: sample_rate)
+        else
+          raise ArgumentError, "unsupported audio source: #{@source_name}"
+        end
+      end
+
+      def resolve_input_sample_rate(input, fallback:)
+        return fallback unless input.respond_to?(:stream_sample_rate)
+
+        rate = input.stream_sample_rate
+        Integer(rate)
+      rescue StandardError
+        fallback
+      end
+    end
+  end
+end

data/lib/vizcore/audio/mic_input.rb

@@ -0,0 +1,121 @@
+# 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.
+    class MicInput < BaseInput
+      attr_reader :device, :last_error
+
+      # @param device [Symbol, String]
+      # @param sample_rate [Integer]
+      # @param fallback_input [Vizcore::Audio::BaseInput, nil]
+      # @param portaudio_backend [Module]
+      # @param channels [Integer]
+      # @param frames_per_buffer [Integer]
+      def initialize(device: :default, sample_rate: 44_100, fallback_input: nil, portaudio_backend: PortAudioFFI, channels: 1, frames_per_buffer: 1024)
+        super(sample_rate: sample_rate)
+        @device = device
+        @channels = Integer(channels)
+        @frames_per_buffer = Integer(frames_per_buffer)
+        @fallback_input = fallback_input || DummySineInput.new(sample_rate: sample_rate)
+        @portaudio_backend = portaudio_backend
+        @stream = nil
+        @using_fallback = false
+        @last_error = nil
+      end
+
+      # @return [Vizcore::Audio::MicInput]
+      def start
+        super
+        @using_fallback = false
+
+        @stream = open_stream
+        @using_fallback = !@stream
+        @fallback_input.start if @using_fallback
+        self
+      end
+
+      # @return [Vizcore::Audio::MicInput]
+      def stop
+        close_stream
+        @fallback_input.stop if @using_fallback
+        @using_fallback = false
+        super
+      end
+
+      # @param frame_size [Integer]
+      # @return [Array<Float>] microphone frame or fallback samples
+      def read(frame_size)
+        count = Integer(frame_size)
+        return Array.new(count, 0.0) unless running?
+
+        if @stream
+          samples = @stream.read(count)
+          @last_error = nil
+          normalize_samples(samples, count)
+        else
+          @fallback_input.read(count)
+        end
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("Microphone read failed: #{e.message}")
+        switch_to_fallback
+        @fallback_input.read(count)
+      end
+
+      # @return [Boolean]
+      def using_fallback?
+        @using_fallback
+      end
+
+      private
+
+      def open_stream
+        stream = @portaudio_backend.open_default_input_stream(
+          sample_rate: sample_rate,
+          channels: @channels,
+          frames_per_buffer: @frames_per_buffer
+        )
+        return nil unless stream
+        return stream if stream.start
+
+        @portaudio_backend.close_stream(stream)
+        nil
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("Microphone stream open failed: #{e.message}")
+        nil
+      end
+
+      def close_stream
+        return unless @stream
+
+        @portaudio_backend.close_stream(@stream)
+      ensure
+        @stream = nil
+      end
+
+      def switch_to_fallback
+        return if @using_fallback
+
+        close_stream
+        @using_fallback = true
+        @fallback_input.start
+      end
+
+      def normalize_samples(samples, expected_count)
+        normalized = Array(samples).map { |sample| Float(sample) }
+        if normalized.length < expected_count
+          normalized + Array.new(expected_count - normalized.length, 0.0)
+        else
+          normalized.first(expected_count)
+        end
+      rescue ArgumentError, TypeError
+        Array.new(expected_count, 0.0)
+      end
+    end
+  end
+end