vizcore 0.1.0 → 1.0.0

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
 

data/lib/vizcore/audio/portaudio_ffi.rb

@@ -6,6 +6,8 @@ module Vizcore
     module PortAudioFFI
       # Runtime wrapper for an opened PortAudio input stream.
       class Stream
+        PA_INPUT_OVERFLOWED = -9981
+
         # @param mod [Module] ffi-bound PortAudio module
         # @param pointer [FFI::Pointer] native stream pointer
         # @param channels [Integer] input channel count
@@ -37,7 +39,7 @@ module Vizcore
 
           buffer = ffi_module::MemoryPointer.new(:float, frames * @channels)
           result = @mod.Pa_ReadStream(@pointer, buffer, frames)
-          return Array.new(frames, 0.0) unless ok?(result)
+          return Array.new(frames, 0.0) unless readable_result?(result)
 
           samples = buffer.read_array_of_float(frames * @channels)
           return samples if @channels == 1
@@ -83,6 +85,10 @@ module Vizcore
           result == self.class.pa_no_error
         end
 
+        def readable_result?(result)
+          ok?(result) || result == self.class.pa_input_overflowed
+        end
+
         def ffi_module
           self.class.ffi_module
         end
@@ -98,6 +104,12 @@ module Vizcore
           def pa_no_error
             0
           end
+
+          # PortAudio returns this when input data was dropped before this read,
+          # but the current read buffer can still contain usable samples.
+          def pa_input_overflowed
+            PA_INPUT_OVERFLOWED
+          end
         end
       end
 
@@ -109,6 +121,8 @@ module Vizcore
       PA_NO_ERROR = 0
       # PortAudio float sample format code.
       PA_FLOAT_32 = 0x0000_0001
+      # PortAudio stream flags.
+      PA_NO_FLAGS = 0
 
       # @return [Boolean] true when PortAudio native library can be loaded
       def available?
@@ -174,6 +188,50 @@ module Vizcore
         nil
       end
 
+      # @param device [String, Integer] PortAudio device index or case-insensitive name fragment
+      # @param sample_rate [Float]
+      # @param channels [Integer]
+      # @param frames_per_buffer [Integer]
+      # @return [Vizcore::Audio::PortAudioFFI::Stream, nil]
+      def open_input_stream(device:, sample_rate:, channels: DEFAULT_CHANNELS, frames_per_buffer: 1024)
+        mod = ffi_module
+        return nil unless mod
+        return nil unless ok?(mod.Pa_Initialize)
+
+        device_info = resolve_input_device(mod, device)
+        return terminate_with_nil(mod) unless device_info
+
+        device_index, info = device_info
+        actual_channels = [Integer(channels), info[:maxInputChannels]].min
+        input_params = mod::StreamParameters.new
+        input_params[:device] = device_index
+        input_params[:channelCount] = actual_channels
+        input_params[:sampleFormat] = PA_FLOAT_32
+        input_params[:suggestedLatency] = info[:defaultLowInputLatency].to_f
+        input_params[:hostApiSpecificStreamInfo] = nil
+
+        stream_ptr_ptr = ffi::MemoryPointer.new(:pointer)
+        result = mod.Pa_OpenStream(
+          stream_ptr_ptr,
+          input_params.to_ptr,
+          nil,
+          Float(sample_rate),
+          Integer(frames_per_buffer),
+          PA_NO_FLAGS,
+          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: actual_channels)
+      rescue StandardError
+        mod&.Pa_Terminate
+        nil
+      end
+
       # @param stream [Vizcore::Audio::PortAudioFFI::Stream, nil]
       # @return [nil]
       def close_stream(stream)
@@ -190,6 +248,44 @@ module Vizcore
         nil
       end
 
+      def resolve_input_device(mod, device)
+        if integer_string?(device)
+          index = Integer(device)
+          pointer = mod.Pa_GetDeviceInfo(index)
+          return nil if pointer.null?
+
+          info = mod::DeviceInfo.new(pointer)
+          return nil unless info[:maxInputChannels].positive?
+
+          return [index, info]
+        end
+
+        find_input_device_by_name(mod, device.to_s)
+      end
+
+      def find_input_device_by_name(mod, query)
+        normalized_query = query.downcase
+        count = mod.Pa_GetDeviceCount
+        return nil if count <= 0
+
+        count.times do |index|
+          pointer = mod.Pa_GetDeviceInfo(index)
+          next if pointer.null?
+
+          info = mod::DeviceInfo.new(pointer)
+          next unless info[:maxInputChannels].positive?
+
+          name = info[:name].read_string
+          return [index, info] if name.downcase.include?(normalized_query)
+        end
+
+        nil
+      end
+
+      def integer_string?(value)
+        value.to_s.match?(/\A\d+\z/)
+      end
+
       def ffi
         @ffi ||= begin
           require "ffi"
@@ -225,11 +321,20 @@ module Vizcore
                            :defaultSampleRate, :double
         mod.const_set(:DeviceInfo, device_info)
 
+        stream_parameters = Class.new(ffi::Struct)
+        stream_parameters.layout :device, :int,
+                                 :channelCount, :int,
+                                 :sampleFormat, :ulong,
+                                 :suggestedLatency, :double,
+                                 :hostApiSpecificStreamInfo, :pointer
+        mod.const_set(:StreamParameters, stream_parameters)
+
         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_OpenStream, [:pointer, :pointer, :pointer, :double, :ulong, :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

data/lib/vizcore/audio.rb

@@ -9,6 +9,7 @@ end
 require_relative "audio/base_input"
 require_relative "audio/dummy_sine_input"
 require_relative "audio/file_input"
+require_relative "audio/fixture_input"
 require_relative "audio/input_manager"
 require_relative "audio/mic_input"
 require_relative "audio/midi_input"

data/lib/vizcore/cli/doctor.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "../analysis"
+require_relative "../audio"
+require_relative "../config"
+
+module Vizcore
+  module CLISupport
+    # Environment preflight checks for local Vizcore development and live use.
+    class Doctor
+      REQUIRED_RUBY = Gem::Requirement.new(">= 3.2.0")
+
+      Check = Struct.new(:name, :status, :message, keyword_init: true) do
+        def ok?
+          status == :ok
+        end
+
+        def failure?
+          status == :fail
+        end
+      end
+
+      Report = Struct.new(:checks, keyword_init: true) do
+        def failure?
+          checks.any?(&:failure?)
+        end
+      end
+
+      def initialize(
+        ruby_version: RUBY_VERSION,
+        portaudio_available: -> { Vizcore::Audio::PortAudioFFI.available? },
+        audio_devices: -> { Vizcore::Audio::PortAudioFFI.input_devices },
+        midi_devices: -> { Vizcore::Audio::MidiInput.available_devices },
+        fftw_available: -> { Vizcore::Analysis::FFTProcessor.fftw_available? },
+        command_available: method(:command_available?),
+        port_available: method(:port_available?)
+      )
+        @ruby_version = ruby_version
+        @portaudio_available = portaudio_available
+        @audio_devices = audio_devices
+        @midi_devices = midi_devices
+        @fftw_available = fftw_available
+        @command_available = command_available
+        @port_available = port_available
+      end
+
+      def call
+        Report.new(
+          checks: [
+            ruby_check,
+            frontend_check,
+            portaudio_check,
+            audio_devices_check,
+            midi_check,
+            fftw_check,
+            ffmpeg_check,
+            port_check
+          ]
+        )
+      end
+
+      private
+
+      attr_reader :ruby_version
+
+      def ruby_check
+        version = Gem::Version.new(ruby_version)
+        return ok("Ruby", "#{ruby_version} satisfies #{REQUIRED_RUBY}") if REQUIRED_RUBY.satisfied_by?(version)
+
+        fail_check("Ruby", "#{ruby_version} is too old; Vizcore requires #{REQUIRED_RUBY}")
+      end
+
+      def frontend_check
+        index_path = Vizcore.frontend_root.join("index.html")
+        src_path = Vizcore.frontend_root.join("src")
+        return ok("Frontend assets", "browser runtime assets found") if index_path.file? && src_path.directory?
+
+        fail_check("Frontend assets", "missing browser runtime assets under #{Vizcore.frontend_root}")
+      end
+
+      def portaudio_check
+        return ok("PortAudio", "native audio input bridge is available") if @portaudio_available.call
+
+        warn("PortAudio", "native audio input unavailable; use --audio-source dummy or install PortAudio for mic input")
+      rescue StandardError => e
+        warn("PortAudio", "availability check failed: #{e.message}")
+      end
+
+      def audio_devices_check
+        devices = Array(@audio_devices.call)
+        return ok("Audio devices", "#{devices.length} input device(s) detected") unless devices.empty?
+
+        warn("Audio devices", "no native input devices detected; mic input may fall back to silence")
+      rescue StandardError => e
+        warn("Audio devices", "device scan failed: #{e.message}")
+      end
+
+      def midi_check
+        devices = Array(@midi_devices.call)
+        return ok("MIDI", "#{devices.length} MIDI input device(s) detected") unless devices.empty?
+
+        warn("MIDI", "no MIDI input devices detected; install unimidi and connect a controller to use midi_map")
+      rescue StandardError => e
+        warn("MIDI", "device scan failed: #{e.message}")
+      end
+
+      def fftw_check
+        return ok("FFTW3", "native FFT backend is available") if @fftw_available.call
+
+        warn("FFTW3", "native FFT backend unavailable; pure Ruby FFT fallback will be used")
+      rescue StandardError => e
+        warn("FFTW3", "availability check failed: #{e.message}")
+      end
+
+      def ffmpeg_check
+        return ok("ffmpeg", "compressed audio decoding is available") if @command_available.call("ffmpeg")
+
+        warn("ffmpeg", "not found on PATH; WAV input still works, MP3/FLAC file input will not")
+      end
+
+      def port_check
+        return ok("Default port", "#{Config::DEFAULT_HOST}:#{Config::DEFAULT_PORT} is available") if @port_available.call(Config::DEFAULT_HOST, Config::DEFAULT_PORT)
+
+        warn("Default port", "#{Config::DEFAULT_HOST}:#{Config::DEFAULT_PORT} is already in use")
+      rescue StandardError => e
+        warn("Default port", "availability check failed: #{e.message}")
+      end
+
+      def ok(name, message)
+        Check.new(name: name, status: :ok, message: message)
+      end
+
+      def warn(name, message)
+        Check.new(name: name, status: :warn, message: message)
+      end
+
+      def fail_check(name, message)
+        Check.new(name: name, status: :fail, message: message)
+      end
+
+      def command_available?(command)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
+          path = File.join(directory, command)
+          File.file?(path) && File.executable?(path)
+        end
+      end
+
+      def port_available?(host, port)
+        server = TCPServer.new(host, port)
+        true
+      rescue Errno::EADDRINUSE
+        false
+      ensure
+        server&.close
+      end
+    end
+  end
+end

data/lib/vizcore/cli/dsl_reference.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "../layer_catalog"
+
+module Vizcore
+  module CLISupport
+    # Produces a generated reference for the Ruby DSL entrypoints.
+    class DslReference
+      Entry = Struct.new(:syntax, :description, keyword_init: true)
+
+      TOP_LEVEL = [
+        Entry.new(syntax: "audio :mic, **options", description: "Register an audio input definition."),
+        Entry.new(syntax: "midi :controller, **options", description: "Register a MIDI input definition."),
+        Entry.new(syntax: "audio_normalize mode: :adaptive", description: "Configure analysis-level normalization."),
+        Entry.new(syntax: "bpm 128 / bpm_lock true", description: "Set and optionally lock the analysis BPM."),
+        Entry.new(syntax: "tap_tempo key: :space", description: "Enable browser tap tempo events."),
+        Entry.new(syntax: "set :global_intensity, 0.8", description: "Set a runtime global exposed to shaders."),
+        Entry.new(syntax: "style :name { ... } / theme :name { ... }", description: "Define reusable layer params or scene defaults."),
+        Entry.new(syntax: "scene :name, extends: :base { ... }", description: "Define a scene and optional inherited layers."),
+        Entry.new(syntax: "section :intro, bars: 8 { ... }", description: "Define beat-counted scenes and generated transitions."),
+        Entry.new(syntax: "timeline { at beats(0), scene: :intro }", description: "Define ordered scene markers."),
+        Entry.new(syntax: "transition from: :intro, to: :drop { ... }", description: "Define explicit scene transitions."),
+        Entry.new(syntax: "midi_map note: 36 { ... }", description: "Map MIDI events to runtime actions."),
+        Entry.new(syntax: "key \"d\" { switch_scene :drop }", description: "Map browser keyboard shortcuts to runtime actions.")
+      ].freeze
+
+      SCENE = [
+        Entry.new(syntax: "use_theme :name", description: "Apply scene-wide layer defaults."),
+        Entry.new(syntax: "group :foreground { layer :name { ... } }", description: "Apply shared params to a related layer group."),
+        Entry.new(syntax: "layer :name { ... }", description: "Append a render layer to the scene.")
+      ].freeze
+
+      LAYER = [
+        Entry.new(syntax: "type :particle_field", description: "Set the layer renderer type."),
+        Entry.new(syntax: "shader :neon_grid / shader \"shaders/liquid.frag\"", description: "Use a built-in or custom fragment shader."),
+        Entry.new(syntax: "glsl \"shaders/liquid.frag\"", description: "Load a custom fragment shader file."),
+        Entry.new(syntax: "type :svg / file \"assets/logo.svg\"", description: "Render an SVG asset resolved relative to the scene file."),
+        Entry.new(syntax: "type :image / file \"assets/noise.png\"", description: "Render a PNG/JPEG/GIF/WebP asset resolved relative to the scene file."),
+        Entry.new(syntax: "type :video / file \"assets/loop.mp4\"", description: "Render a looping MP4/WebM/OGV video texture."),
+        Entry.new(syntax: "type :waveform / source :audio / style :ribbon", description: "Render an audio feature waveform layer."),
+        Entry.new(syntax: "type :spectrogram / scroll :vertical", description: "Render a scrolling FFT heatmap layer."),
+        Entry.new(syntax: "type :mesh / geometry :icosahedron / material :wireframe", description: "Render preset 3D wireframe geometry."),
+        Entry.new(syntax: "circle count: 8 { radius 100 } / line x1: 0, y1: 360, x2: 1280, y2: 360", description: "Render declarative 2D shape primitives."),
+        Entry.new(syntax: "font \"Inter\" / letter_spacing 4", description: "Set text presentation params."),
+        Entry.new(syntax: "palette \"#ff0055\", \"#00ffff\"", description: "Set ordered colors for supported layer renderers."),
+        Entry.new(syntax: "blend :add / effect :bloom / vj_effect :mirror", description: "Set compositing and browser effects."),
+        Entry.new(syntax: "param :wobble, default: 0.3, range: 0.0..2.0", description: "Declare numeric shader parameter metadata."),
+        Entry.new(syntax: "map amplitude, to: :speed, range: 0.0..2.0", description: "Map audio features to layer params."),
+        Entry.new(syntax: "react_to bass { change :size }", description: "Group mappings by source.")
+      ].freeze
+
+      SOURCES = %w[
+        amplitude frequency_band(:low) sub low bass mid high treble fft_spectrum
+        onset onset(:high) kick snare hihat beat? beat beat_confidence beat_pulse beat_count bpm
+      ].freeze
+
+      TRANSFORMS = %w[
+        gain range min max curve deadzone smooth(attack:,release:)
+      ].freeze
+
+      # @return [Array<String>]
+      def lines
+        [
+          "# Vizcore Ruby DSL Reference",
+          "",
+          "## Top-level DSL",
+          *entry_lines(TOP_LEVEL),
+          "",
+          "## Scene DSL",
+          *entry_lines(SCENE),
+          "",
+          "## Layer DSL",
+          *entry_lines(LAYER),
+          "",
+          "Mapping sources: #{SOURCES.join(', ')}",
+          "Mapping transforms: #{TRANSFORMS.join(', ')}",
+          "",
+          "## Built-in Layer Capabilities",
+          *capability_lines
+        ]
+      end
+
+      private
+
+      def entry_lines(entries)
+        entries.map { |entry| "- `#{entry.syntax}` - #{entry.description}" }
+      end
+
+      def capability_lines
+        Vizcore::LayerCatalog.capabilities.map do |capability|
+          aliases = capability.aliases.empty? ? "" : " (aliases: #{capability.aliases.join(', ')})"
+          params = capability.params.keys.join(", ")
+          mappable = capability.mappable_params.empty? ? "(none)" : capability.mappable_params.join(", ")
+          "- `#{capability.type}`#{aliases}: params #{params}; mappable #{mappable}"
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/cli/layer_docs.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../layer_catalog"
+
+module Vizcore
+  module CLISupport
+    # Formats built-in layer capability metadata for CLI output.
+    class LayerDocs
+      def lines
+        [
+          "# Vizcore Layer Capabilities",
+          "",
+          *layer_lines,
+          "",
+          "Built-in shaders: #{Vizcore::LayerCatalog::BUILTIN_SHADERS.join(', ')}",
+          "Blend modes: #{Vizcore::LayerCatalog::BLEND_MODES.join(', ')}",
+          "Post effects: #{Vizcore::LayerCatalog::POST_EFFECTS.join(', ')}",
+          "VJ effects: #{Vizcore::LayerCatalog::VJ_EFFECTS.join(', ')}"
+        ]
+      end
+
+      private
+
+      def layer_lines
+        Vizcore::LayerCatalog.capabilities.flat_map do |capability|
+          aliases = capability.aliases.empty? ? "" : " (aliases: #{capability.aliases.join(', ')})"
+          [
+            "## #{capability.type}#{aliases}",
+            capability.description,
+            "Params: #{format_params(capability.params)}",
+            "Mappable params: #{format_list(capability.mappable_params)}",
+            ""
+          ]
+        end.tap(&:pop)
+      end
+
+      def format_params(params)
+        params.map { |name, type| "#{name}: #{type}" }.join(", ")
+      end
+
+      def format_list(values)
+        values.empty? ? "(none)" : values.join(", ")
+      end
+    end
+  end
+end

data/lib/vizcore/cli/scene_diagnostics.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "scene_inspector"
+require_relative "scene_validator"
+
+module Vizcore
+  module CLISupport
+    # Facade used by Thor commands for scene validation and inspection.
+    class SceneDiagnostics
+      def initialize(scene_file:)
+        @validator = SceneValidator.new(scene_file: scene_file)
+      end
+
+      def validate
+        @validator.call
+      end
+
+      def inspect_lines(definition)
+        SceneInspector.new(definition: definition).lines
+      end
+    end
+  end
+end