vizcore 0.1.0

data/lib/vizcore/audio/midi_input.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "thread"
+require_relative "../errors"
+
+module Vizcore
+  module Audio
+    # Poll-based MIDI input wrapper using the `unimidi` backend.
+    class MidiInput
+      # Normalized MIDI event payload.
+      Event = Struct.new(:type, :channel, :data1, :data2, :raw, :timestamp, keyword_init: true)
+      # Poll interval for empty reads in seconds.
+      DEFAULT_POLL_INTERVAL = 0.01
+
+      class << self
+        # @param backend [Module, nil]
+        # @return [Array<Hash>] available MIDI devices
+        def available_devices(backend: nil)
+          midi_backend = backend || load_backend
+          return [] unless midi_backend
+
+          midi_backend::Input.all.each_with_index.map do |device, index|
+            {
+              id: extract_device_id(device, index),
+              name: extract_device_name(device)
+            }
+          end
+        rescue StandardError
+          []
+        end
+
+        private
+
+        def load_backend
+          require "unimidi"
+          UniMIDI
+        rescue LoadError
+          nil
+        end
+
+        def extract_device_id(device, fallback)
+          return device.device_id if device.respond_to?(:device_id)
+          fallback
+        end
+
+        def extract_device_name(device)
+          return device.name if device.respond_to?(:name) && device.name
+          "unknown-midi-device"
+        end
+      end
+
+      # @param device [Integer, String, Symbol, nil]
+      # @param backend [Module, nil]
+      # @param poll_interval [Float]
+      def initialize(device: nil, backend: nil, poll_interval: DEFAULT_POLL_INTERVAL)
+        @device = device
+        @backend = backend || self.class.send(:load_backend)
+        @poll_interval = Float(poll_interval)
+        @running = false
+        @thread = nil
+        @input = nil
+        @events = Queue.new
+        @callback = nil
+        @last_error = nil
+      end
+
+      attr_reader :last_error
+
+      # @yieldparam event [Vizcore::Audio::MidiInput::Event]
+      # @return [Vizcore::Audio::MidiInput]
+      def start(&callback)
+        return self if running?
+
+        @callback = callback if block_given?
+        @input = open_input
+        return self unless @input
+
+        @running = true
+        @thread = Thread.new { consume_loop }
+        self
+      end
+
+      # @return [Vizcore::Audio::MidiInput]
+      def stop
+        @running = false
+        join_thread
+        close_input
+        self
+      end
+
+      # @return [Boolean]
+      def running?
+        @running
+      end
+
+      # @param max [Integer, nil]
+      # @return [Array<Vizcore::Audio::MidiInput::Event>]
+      def poll(max = nil)
+        limit = max ? Integer(max) : nil
+        result = []
+
+        while limit.nil? || result.length < limit
+          begin
+            result << @events.pop(true)
+          rescue ThreadError
+            break
+          end
+        end
+
+        result
+      end
+
+      private
+
+      def open_input
+        return nil unless @backend
+
+        devices = @backend::Input.all
+        return nil if devices.empty?
+
+        device = select_device(devices)
+        unless device
+          @last_error = AudioSourceError.new("MIDI device not found: #{@device}")
+          return nil
+        end
+
+        device.respond_to?(:open) ? device.open : device
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("MIDI open failed: #{e.message}")
+        nil
+      end
+
+      def select_device(devices)
+        return devices.first if @device.nil? || @device == :default || @device == :first
+        return devices[@device] if @device.is_a?(Integer)
+
+        needle = @device.to_s.downcase
+        devices.find do |device|
+          name = device.respond_to?(:name) ? device.name.to_s.downcase : ""
+          id = device.respond_to?(:device_id) ? device.device_id.to_s.downcase : ""
+          name == needle || id == needle
+        end
+      end
+
+      def consume_loop
+        while @running
+          raw_message = read_message
+          unless raw_message
+            sleep(@poll_interval)
+            next
+          end
+
+          event = parse_message(raw_message)
+          next unless event
+
+          @events << event
+          @callback&.call(event)
+        end
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("MIDI consume loop failed: #{e.message}")
+        @running = false
+      end
+
+      def read_message
+        return nil unless @input
+        return @input.gets if @input.respond_to?(:gets)
+        return @input.read if @input.respond_to?(:read)
+
+        nil
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("MIDI read failed: #{e.message}")
+        nil
+      end
+
+      def parse_message(raw_message)
+        bytes = normalize_message(raw_message)
+        return nil if bytes.empty?
+
+        status = bytes[0]
+        command = status & 0xF0
+        channel = status & 0x0F
+        data1 = bytes[1] || 0
+        data2 = bytes[2] || 0
+
+        Event.new(
+          type: detect_event_type(command, data2),
+          channel: channel,
+          data1: data1,
+          data2: data2,
+          raw: bytes,
+          timestamp: Time.now.to_f
+        )
+      end
+
+      def normalize_message(raw_message)
+        values =
+          if raw_message.respond_to?(:data)
+            Array(raw_message.data)
+          else
+            Array(raw_message)
+          end
+
+        values.map { |value| Integer(value) & 0xFF }
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("MIDI message parse failed: #{e.message}")
+        []
+      end
+
+      def detect_event_type(command, data2)
+        case command
+        when 0x80
+          :note_off
+        when 0x90
+          data2.zero? ? :note_off : :note_on
+        when 0xB0
+          :control_change
+        when 0xC0
+          :program_change
+        else
+          :unknown
+        end
+      end
+
+      def join_thread
+        thread = @thread
+        @thread = nil
+        return unless thread
+
+        thread.join(0.3)
+        thread.kill if thread.alive?
+      end
+
+      def close_input
+        input = @input
+        @input = nil
+        return unless input
+        return unless input.respond_to?(:close)
+
+        input.close
+      rescue StandardError => e
+        @last_error = AudioSourceError.new("MIDI close failed: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/vizcore/audio/portaudio_ffi.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Audio
+    # PortAudio FFI bridge for microphone stream access and device discovery.
+    module PortAudioFFI
+      # Runtime wrapper for an opened PortAudio input stream.
+      class Stream
+        # @param mod [Module] ffi-bound PortAudio module
+        # @param pointer [FFI::Pointer] native stream pointer
+        # @param channels [Integer] input channel count
+        def initialize(mod:, pointer:, channels:)
+          @mod = mod
+          @pointer = pointer
+          @channels = channels
+          @started = false
+          @closed = false
+        end
+
+        # @return [Boolean] true when stream start succeeded
+        def start
+          return true if @started
+          return false if @closed
+
+          result = @mod.Pa_StartStream(@pointer)
+          return false unless ok?(result)
+
+          @started = true
+          true
+        end
+
+        # @param frame_size [Integer]
+        # @return [Array<Float>] mono samples or silence on failure
+        def read(frame_size)
+          frames = Integer(frame_size)
+          return Array.new(frames, 0.0) unless @started
+
+          buffer = ffi_module::MemoryPointer.new(:float, frames * @channels)
+          result = @mod.Pa_ReadStream(@pointer, buffer, frames)
+          return Array.new(frames, 0.0) unless ok?(result)
+
+          samples = buffer.read_array_of_float(frames * @channels)
+          return samples if @channels == 1
+
+          downmix(samples, frames)
+        rescue StandardError
+          Array.new(frames, 0.0)
+        end
+
+        # @return [Boolean] true when stop call succeeded
+        def stop
+          return true if @closed || !@started
+
+          result = @mod.Pa_StopStream(@pointer)
+          @started = false if ok?(result)
+          ok?(result)
+        rescue StandardError
+          false
+        end
+
+        # @return [void]
+        def close
+          return if @closed
+
+          stop
+          @mod.Pa_CloseStream(@pointer) unless @pointer.nil? || @pointer.null?
+          @closed = true
+        rescue StandardError
+          @closed = true
+        end
+
+        private
+
+        def downmix(samples, frames)
+          Array.new(frames) do |frame|
+            offset = frame * @channels
+            chunk = samples[offset, @channels]
+            chunk.sum / @channels.to_f
+          end
+        end
+
+        def ok?(result)
+          result == self.class.pa_no_error
+        end
+
+        def ffi_module
+          self.class.ffi_module
+        end
+
+        class << self
+          # @return [Module] loaded ffi module
+          def ffi_module
+            require "ffi"
+            FFI
+          end
+
+          # @return [Integer]
+          def pa_no_error
+            0
+          end
+        end
+      end
+
+      extend self
+
+      # Default mono channel count.
+      DEFAULT_CHANNELS = 1
+      # PortAudio no-error status code.
+      PA_NO_ERROR = 0
+      # PortAudio float sample format code.
+      PA_FLOAT_32 = 0x0000_0001
+
+      # @return [Boolean] true when PortAudio native library can be loaded
+      def available?
+        !ffi_module.nil?
+      end
+
+      # @return [Array<Hash>] available input device descriptors
+      def input_devices
+        mod = ffi_module
+        return [] unless mod
+        return [] unless ok?(mod.Pa_Initialize)
+
+        count = mod.Pa_GetDeviceCount
+        return [] if count <= 0
+
+        count.times.filter_map do |index|
+          pointer = mod.Pa_GetDeviceInfo(index)
+          next if pointer.null?
+
+          info = mod::DeviceInfo.new(pointer)
+          next unless info[:maxInputChannels].positive?
+
+          {
+            index: index,
+            name: info[:name].read_string,
+            max_input_channels: info[:maxInputChannels],
+            default_sample_rate: info[:defaultSampleRate].to_f
+          }
+        end
+      ensure
+        mod&.Pa_Terminate
+      end
+
+      # @param sample_rate [Float]
+      # @param channels [Integer]
+      # @param frames_per_buffer [Integer]
+      # @return [Vizcore::Audio::PortAudioFFI::Stream, nil]
+      def open_default_input_stream(sample_rate:, channels: DEFAULT_CHANNELS, frames_per_buffer: 1024)
+        mod = ffi_module
+        return nil unless mod
+        return nil unless ok?(mod.Pa_Initialize)
+
+        stream_ptr_ptr = ffi::MemoryPointer.new(:pointer)
+
+        result = mod.Pa_OpenDefaultStream(
+          stream_ptr_ptr,
+          Integer(channels),
+          0,
+          PA_FLOAT_32,
+          Float(sample_rate),
+          Integer(frames_per_buffer),
+          nil,
+          nil
+        )
+        return terminate_with_nil(mod) unless ok?(result)
+
+        stream_pointer = stream_ptr_ptr.read_pointer
+        return terminate_with_nil(mod) if stream_pointer.null?
+
+        Stream.new(mod: mod, pointer: stream_pointer, channels: Integer(channels))
+      rescue StandardError
+        mod&.Pa_Terminate
+        nil
+      end
+
+      # @param stream [Vizcore::Audio::PortAudioFFI::Stream, nil]
+      # @return [nil]
+      def close_stream(stream)
+        stream&.close
+        ffi_module&.Pa_Terminate
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def terminate_with_nil(mod)
+        mod.Pa_Terminate
+        nil
+      end
+
+      def ffi
+        @ffi ||= begin
+          require "ffi"
+          FFI
+        end
+      end
+
+      def ok?(result)
+        result == PA_NO_ERROR
+      end
+
+      def ffi_module
+        return @ffi_module if defined?(@ffi_module)
+
+        @ffi_module = build_ffi_module
+      end
+
+      def build_ffi_module
+        mod = Module.new
+        mod.extend(ffi::Library)
+        mod.ffi_lib("portaudio")
+
+        device_info = Class.new(ffi::Struct)
+        device_info.layout :structVersion, :int,
+                           :name, :pointer,
+                           :hostApi, :int,
+                           :maxInputChannels, :int,
+                           :maxOutputChannels, :int,
+                           :defaultLowInputLatency, :double,
+                           :defaultLowOutputLatency, :double,
+                           :defaultHighInputLatency, :double,
+                           :defaultHighOutputLatency, :double,
+                           :defaultSampleRate, :double
+        mod.const_set(:DeviceInfo, device_info)
+
+        mod.attach_function :Pa_Initialize, [], :int
+        mod.attach_function :Pa_Terminate, [], :int
+        mod.attach_function :Pa_GetDeviceCount, [], :int
+        mod.attach_function :Pa_GetDeviceInfo, [:int], :pointer
+        mod.attach_function :Pa_OpenDefaultStream, [:pointer, :int, :int, :ulong, :double, :ulong, :pointer, :pointer], :int
+        mod.attach_function :Pa_StartStream, [:pointer], :int
+        mod.attach_function :Pa_StopStream, [:pointer], :int
+        mod.attach_function :Pa_CloseStream, [:pointer], :int
+        mod.attach_function :Pa_ReadStream, [:pointer, :pointer, :ulong], :int
+        mod
+      rescue LoadError, ffi::NotFoundError, StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/vizcore/audio/ring_buffer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Vizcore
+  module Audio
+    # Thread-safe circular buffer for recent audio samples.
+    class RingBuffer
+      attr_reader :capacity
+
+      # @param capacity [Integer]
+      def initialize(capacity)
+        raise ArgumentError, "capacity must be positive" unless capacity.to_i.positive?
+
+        @capacity = Integer(capacity)
+        @buffer = Array.new(@capacity, 0.0)
+        @write_index = 0
+        @size = 0
+        @mutex = Mutex.new
+      end
+
+      # @param samples [Array<Numeric>]
+      # @return [void]
+      def write(samples)
+        normalized = normalize_samples(samples)
+        return if normalized.empty?
+
+        @mutex.synchronize do
+          normalized.each do |sample|
+            @buffer[@write_index] = sample
+            @write_index = (@write_index + 1) % @capacity
+            @size += 1 if @size < @capacity
+          end
+        end
+      end
+
+      # @param sample [Numeric]
+      # @return [void]
+      def push(sample)
+        write([sample])
+      end
+
+      # @param count [Integer, nil]
+      # @return [Array<Float>] newest values first-in-order
+      def latest(count = nil)
+        @mutex.synchronize do
+          return [] if @size.zero?
+
+          requested = count ? Integer(count) : @size
+          return [] if requested <= 0
+
+          length = [requested, @size].min
+          start = (@write_index - length) % @capacity
+
+          extract_range(start, length)
+        end
+      end
+
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @size }
+      end
+
+      # @return [void]
+      def clear
+        @mutex.synchronize do
+          @buffer.fill(0.0)
+          @write_index = 0
+          @size = 0
+        end
+      end
+
+      private
+
+      def extract_range(start, length)
+        if start + length <= @capacity
+          @buffer[start, length].dup
+        else
+          tail = @buffer[start, @capacity - start]
+          head = @buffer[0, length - tail.length]
+          tail + head
+        end
+      end
+
+      def normalize_samples(samples)
+        Array(samples).map { |sample| Float(sample) }
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "samples must be numeric"
+      end
+    end
+  end
+end

data/lib/vizcore/audio.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Audio input/runtime namespace.
+  module Audio
+  end
+end
+
+require_relative "audio/base_input"
+require_relative "audio/dummy_sine_input"
+require_relative "audio/file_input"
+require_relative "audio/input_manager"
+require_relative "audio/mic_input"
+require_relative "audio/midi_input"
+require_relative "audio/portaudio_ffi"
+require_relative "audio/ring_buffer"

data/lib/vizcore/cli.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "thor"
+require_relative "../vizcore"
+require_relative "audio"
+require_relative "config"
+require_relative "server"
+
+module Vizcore
+  # Thor-based CLI entrypoint for Vizcore.
+  class CLI < Thor
+    package_name "vizcore"
+
+    # Exit with non-zero status when a Thor command fails.
+    #
+    # @return [Boolean]
+    def self.exit_on_failure?
+      true
+    end
+
+    default_command :help
+
+    desc "start SCENE_FILE", "Start vizcore HTTP/WebSocket server"
+    option :host, type: :string, default: Config::DEFAULT_HOST, desc: "Bind host"
+    option :port, type: :numeric, default: Config::DEFAULT_PORT, desc: "Bind port"
+    option :audio_source, type: :string, default: Config::DEFAULT_AUDIO_SOURCE.to_s, desc: "Audio source: mic, file, dummy"
+    option :audio_file, type: :string, desc: "Path to audio file used when --audio-source file (wav/mp3/flac)"
+    # Start the Vizcore server with the given scene file.
+    #
+    # @param scene_file [String] path to a Ruby scene DSL file
+    # @raise [Thor::Error] when CLI arguments are invalid
+    # @return [void]
+    def start(scene_file)
+      config = Config.new(
+        scene_file: scene_file,
+        host: options.fetch(:host),
+        port: options.fetch(:port),
+        audio_source: options.fetch(:audio_source),
+        audio_file: options[:audio_file]
+      )
+      Server::Runner.new(config).run
+    rescue ArgumentError => e
+      raise Thor::Error, e.message
+    end
+
+    desc "new NAME", "Create a starter project scaffold"
+    # Generate a new Vizcore project scaffold.
+    #
+    # @param name [String] directory name for the new project
+    # @return [void]
+    def new(name)
+      root = Pathname.new(name).expand_path
+      FileUtils.mkdir_p(root.join("scenes"))
+      FileUtils.mkdir_p(root.join("shaders"))
+
+      write_template("project_readme.md", root.join("README.md"), project_name: name)
+      write_template("basic_scene.rb", root.join("scenes", "basic.rb"), project_name: name)
+      write_template("intro_drop_scene.rb", root.join("scenes", "intro_drop.rb"), project_name: name)
+      write_template("midi_control_scene.rb", root.join("scenes", "midi_control.rb"), project_name: name)
+      write_template("custom_shader_scene.rb", root.join("scenes", "custom_shader.rb"), project_name: name)
+      write_template("custom_wave.frag", root.join("shaders", "custom_wave.frag"), project_name: name)
+
+      say("Created project scaffold: #{root}")
+      say("Next: cd #{name} && vizcore start scenes/basic.rb")
+    end
+
+    desc "devices [TYPE]", "Show available devices (audio or midi)"
+    # Print audio and/or MIDI devices detected by the runtime.
+    #
+    # @param type [String, nil] `audio`, `midi`, or nil for both
+    # @raise [Thor::Error] when an unknown type is provided
+    # @return [void]
+    def devices(type = nil)
+      case type
+      when nil
+        print_audio_devices
+        print_midi_devices
+      when "audio"
+        print_audio_devices
+      when "midi"
+        print_midi_devices
+      else
+        raise Thor::Error, "Unknown type: #{type}. Use `audio` or `midi`."
+      end
+    end
+
+    private
+
+    def write_template(template_name, destination, project_name:)
+      template_path = Vizcore.templates_root.join(template_name)
+      body = template_path.read.gsub("{{project_name}}", project_name)
+      destination.write(body)
+    end
+
+    def print_audio_devices
+      say("Audio devices:")
+      Vizcore::Audio::InputManager.available_audio_devices.each do |device|
+        index = device[:index]
+        name = device[:name]
+        channels = device[:max_input_channels]
+        sample_rate = device[:default_sample_rate]
+        say("  - #{index}: #{name} (inputs=#{channels}, rate=#{sample_rate})")
+      end
+    end
+
+    def print_midi_devices
+      say("MIDI devices:")
+      Vizcore::Audio::InputManager.available_midi_devices.each do |device|
+        say("  - #{device[:id]}: #{device[:name]}")
+      end
+    end
+  end
+end