vizcore 1.1.0 → 1.2.0

data/lib/vizcore/audio/input_manager.rb

@@ -28,7 +28,8 @@ module Vizcore
       # @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)
+        @requested_sample_rate = Integer(sample_rate)
+        @sample_rate = @requested_sample_rate
         @frame_size = Integer(frame_size)
         @ring_buffer = RingBuffer.new(ring_buffer_size)
         @audio_device = audio_device
@@ -69,6 +70,32 @@ module Vizcore
         ring_buffer.latest(count)
       end
 
+      # @return [Hash] current input health values for runtime status endpoints.
+      def status
+        {
+          source: source_name.to_s,
+          sample_rate: sample_rate,
+          frame_size: frame_size,
+          ring_buffer: ring_buffer.respond_to?(:metrics) ? ring_buffer.metrics : {},
+          requested_sample_rate: @requested_sample_rate,
+          sample_rate_mismatch: sample_rate_mismatch?
+        }
+      end
+
+      # @return [Float, nil] current transport position seconds for file sources
+      def transport_position_seconds
+        return @input.transport_position_seconds if @input.respond_to?(:transport_position_seconds)
+
+        nil
+      end
+
+      # @return [Float, nil] input track duration seconds for file sources
+      def track_duration_seconds
+        return @input.track_duration_seconds if @input.respond_to?(:track_duration_seconds)
+
+        nil
+      end
+
       # @param frame_rate [Numeric]
       # @return [Integer] approximate real-time sample count to ingest per render tick
       def realtime_capture_size(frame_rate)
@@ -130,6 +157,14 @@ module Vizcore
       rescue StandardError
         fallback
       end
+
+      def sample_rate_mismatch?
+        return false unless @input.respond_to?(:stream_sample_rate)
+
+        Integer(@input.stream_sample_rate) != Integer(@requested_sample_rate)
+      rescue StandardError
+        false
+      end
     end
   end
 end

data/lib/vizcore/audio/midi_input.rb

@@ -29,6 +29,11 @@ module Vizcore
           []
         end
 
+        # @return [Boolean] true when the optional UniMIDI backend can be loaded
+        def available?
+          !load_backend.nil?
+        end
+
         private
 
         def load_backend

data/lib/vizcore/audio/ring_buffer.rb

@@ -16,6 +16,9 @@ module Vizcore
         @buffer = Array.new(@capacity, 0.0)
         @write_index = 0
         @size = 0
+        @write_count = 0
+        @overrun_count = 0
+        @underrun_count = 0
         @mutex = Mutex.new
       end
 
@@ -27,8 +30,10 @@ module Vizcore
 
         @mutex.synchronize do
           normalized.each do |sample|
+            @overrun_count += 1 if @size == @capacity
             @buffer[@write_index] = sample
             @write_index = (@write_index + 1) % @capacity
+            @write_count += 1
             @size += 1 if @size < @capacity
           end
         end
@@ -49,6 +54,7 @@ module Vizcore
           requested = count ? Integer(count) : @size
           return [] if requested <= 0
 
+          @underrun_count += requested - @size if requested > @size
           length = [requested, @size].min
           start = (@write_index - length) % @capacity
 
@@ -61,12 +67,28 @@ module Vizcore
         @mutex.synchronize { @size }
       end
 
+      # @return [Hash] buffer health counters for runtime diagnostics.
+      def metrics
+        @mutex.synchronize do
+          {
+            capacity: @capacity,
+            size: @size,
+            write_count: @write_count,
+            overrun_count: @overrun_count,
+            underrun_count: @underrun_count
+          }
+        end
+      end
+
       # @return [void]
       def clear
         @mutex.synchronize do
           @buffer.fill(0.0)
           @write_index = 0
           @size = 0
+          @write_count = 0
+          @overrun_count = 0
+          @underrun_count = 0
         end
       end
 

data/lib/vizcore/audio.rb

@@ -7,6 +7,7 @@ module Vizcore
 end
 
 require_relative "audio/base_input"
+require_relative "audio/calibration"
 require_relative "audio/dummy_sine_input"
 require_relative "audio/file_input"
 require_relative "audio/fixture_input"

data/lib/vizcore/cli/dsl_reference.rb

@@ -12,20 +12,23 @@ module Vizcore
         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: "audio_analysis onset_sensitivity: 1.4, fft_bins: 64", description: "Tune analysis feature extraction."),
         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: "mapping :name { ... }", description: "Define reusable layer mapping groups."),
         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: "section :intro, bars: 8, loop: true, hold: 2, outro: false", description: "Define beat-counted scenes with optional auto-loop/outro/hold behavior."),
+        Entry.new(syntax: "timeline { at beats(0), scene: :intro, cue: :prelude }", description: "Define ordered scene markers with optional cue metadata."),
         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: "midi_map cc: 1, channel: 1, deadband: 2, smooth: 0.25, allow_multiple: true { ... }", 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: "use_mapping :name", description: "Apply a reusable mapping group to a layer."),
         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
@@ -43,19 +46,72 @@ module Vizcore
         Entry.new(syntax: "circle count: 8 { radius 100 } / rect width: 320, height: 160 / custom_shape :flower", description: "Render declarative and Ruby-generated 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: "hsl(240, 100, 50) / hsv(0, 100, 100)", description: "Generate CSS hex color values from HSL / HSV."),
+        Entry.new(syntax: "gradient(type: :radial, colors: [\"#f00\", \"#0ff\"])", description: "Build reusable gradient descriptors for color fields."),
+        Entry.new(syntax: "grid(count: 12, columns: 4, spacing: 20)", description: "Generate point layouts for shape geometry."),
+        Entry.new(syntax: "radial(count: 16, radius: 120, start_angle: -90)", description: "Generate polar layout points."),
+        Entry.new(syntax: "spiral(count: 24, radius: 150, turns: 4)", description: "Generate expanding spiral points."),
+        Entry.new(syntax: "circle_pack(count: 20, radius: 140)", description: "Generate packed points in concentric circles."),
+        Entry.new(syntax: "scatter(count: 12, width: 320, height: 180, seed: 7)", description: "Generate deterministic scattered point layouts."),
         Entry.new(syntax: "blend :add / effect :bloom / vj_effect :mirror", description: "Set compositing and browser effects."),
+        Entry.new(syntax: "post :bloom / post :motion_blur / post :chromatic", description: "Build a post effect chain for a layer."),
         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
+      SOURCES = [
+        "amplitude",
+        "frequency_band(:low)",
+        "frequency_band_peak(:low)",
+        "sub",
+        "low",
+        "bass",
+        "bass_peak",
+        "mid",
+        "mid_peak",
+        "high",
+        "high_peak",
+        "treble",
+        "fft_spectrum",
+        "onset",
+        "onset(:high)",
+        "kick",
+        "snare",
+        "hihat",
+        "beat?",
+        "beat",
+        "beat_confidence",
+        "beat_pulse",
+        "beat_count",
+        "adsr(:kick, attack: 0.02, decay: 0.08, sustain: 0.7, release: 0.16, threshold: 0.0, peak: 1.0)",
+        "envelope(:kick, attack: 0.02)",
+        "beat_phase",
+        "beat_2",
+        "beat_4",
+        "beat_8",
+        "triplet",
+        "bar_phase",
+        "bar_count",
+        "phrase_count",
+        "bpm"
       ].freeze
 
-      TRANSFORMS = %w[
-        gain range min max curve deadzone smooth(attack:,release:)
+      TRANSFORMS = [
+        "as(:trigger)",
+        "gain",
+        "range",
+        "min",
+        "max",
+        "curve",
+        "deadzone",
+        "threshold",
+        "hysteresis",
+        "hold",
+        "decay",
+        "cooldown",
+        "one_shot",
+        "smooth(attack:,release:)"
       ].freeze
 
       # @return [Array<String>]

data/lib/vizcore/cli/plugin_checker.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../plugin_asset_policy"
+
+module Vizcore
+  module CLISupport
+    # Performs local smoke checks for a Vizcore plugin scaffold.
+    class PluginChecker
+      Check = Struct.new(:name, :status, :message, keyword_init: true) do
+        def failure?
+          status == :fail
+        end
+      end
+
+      Report = Struct.new(:checks, keyword_init: true) do
+        def failure?
+          checks.any?(&:failure?)
+        end
+      end
+
+      # @param root [String, Pathname]
+      def initialize(root)
+        @root = Pathname.new(root).expand_path
+      end
+
+      # @return [Report]
+      def call
+        return Report.new(checks: [fail_check("Plugin root", "directory not found: #{@root}")]) unless @root.directory?
+
+        Report.new(
+          checks: [
+            ruby_layer_check,
+            frontend_asset_check,
+            example_scene_check
+          ]
+        )
+      end
+
+      private
+
+      def ruby_layer_check
+        files = @root.join("lib").glob("*.rb")
+        return fail_check("Ruby layer", "missing lib/*.rb") if files.empty?
+
+        syntax_check("Ruby layer", files.first)
+      end
+
+      def frontend_asset_check
+        files = @root.join("frontend").glob("*.{js,mjs}")
+        return fail_check("Frontend renderer", "missing frontend/*.js or frontend/*.mjs") if files.empty?
+
+        Vizcore::PluginAssetPolicy.validate!(files.first, root: @root)
+        body = files.first.read
+        return warn_check("Frontend renderer", "#{files.first} does not register globalThis.VizcorePlugins") unless body.include?("VizcorePlugins")
+
+        ok("Frontend renderer", "#{files.first.relative_path_from(@root)} is loadable")
+      rescue ArgumentError => e
+        fail_check("Frontend renderer", e.message)
+      end
+
+      def example_scene_check
+        files = @root.join("examples").glob("*.rb")
+        return fail_check("Example scene", "missing examples/*.rb") if files.empty?
+
+        syntax_check("Example scene", files.first)
+      end
+
+      def syntax_check(name, path)
+        if defined?(RubyVM::InstructionSequence)
+          RubyVM::InstructionSequence.compile_file(path.to_s)
+        else
+          return warn_check(name, "syntax check skipped on this Ruby engine")
+        end
+        ok(name, "#{path.relative_path_from(@root)} has valid Ruby syntax")
+      rescue SyntaxError => e
+        fail_check(name, "#{path.relative_path_from(@root)} has invalid Ruby syntax: #{e.message.lines.first&.strip}")
+      end
+
+      def ok(name, message)
+        Check.new(name: name, status: :ok, message: message)
+      end
+
+      def warn_check(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
+    end
+  end
+end

data/lib/vizcore/cli/scene_diagnostics.rb

@@ -7,8 +7,8 @@ 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)
+      def initialize(scene_file:, strict: false)
+        @validator = SceneValidator.new(scene_file: scene_file, strict: strict)
       end
 
       def validate

data/lib/vizcore/cli/scene_inspector.rb

@@ -19,8 +19,27 @@ module Vizcore
         output
       end
 
+      def to_h
+        sanitize(@definition)
+      end
+
       private
 
+      def sanitize(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, entry), output|
+            output[key.to_s] = sanitize(entry)
+          end
+        when Array
+          value.map { |entry| sanitize(entry) }
+        when Symbol
+          value.to_s
+        else
+          value.respond_to?(:call) ? true : value
+        end
+      end
+
       def append_inputs(output, label, values)
         return if values.empty?
 
@@ -95,10 +114,21 @@ module Vizcore
         return "unknown" unless values[:kind]
         return "frequency_band(#{values[:band]})" if values[:kind].to_sym == :frequency_band
         return "onset(#{values[:band]})" if values[:kind].to_sym == :onset && values[:band]
+        return "global(#{values[:name]})" if values[:kind].to_sym == :global && values[:name]
+        return format_lfo_source(values) if values[:kind].to_sym == :lfo
 
         values[:kind].to_s
       end
 
+      def format_lfo_source(values)
+        wave = values[:wave] || :sine
+        parts = []
+        parts << "rate=#{values[:rate]}" if values.key?(:rate)
+        parts << "phase=#{values[:phase]}" if values.key?(:phase)
+        suffix = parts.empty? ? "" : ", #{parts.join(', ')}"
+        "lfo(#{wave}#{suffix})"
+      end
+
       def format_transform(transform)
         values = Hash(transform || {})
         return "" if values.empty?
@@ -121,7 +151,11 @@ module Vizcore
         when :switch_scene
           "switch_scene #{values[:scene]}"
         when :live_control
-          values[:control].to_s
+          options = values.slice(:value, :fade, :release)
+          control = values[:control].to_s
+          return control if options.empty?
+
+          "#{control}#{format_options(options)}"
         else
           "unknown"
         end