vizcore 0.1.0 → 1.0.0

data/lib/vizcore/config.rb

@@ -11,22 +11,62 @@ module Vizcore
     DEFAULT_PORT = 4567
     # Default audio source.
     DEFAULT_AUDIO_SOURCE = :mic
+    # Default RMS noise gate for live audio.
+    DEFAULT_NOISE_GATE = 0.01
+    # Default scene file hot reload behavior.
+    DEFAULT_RELOAD = true
     # Supported CLI audio source values.
     SUPPORTED_AUDIO_SOURCES = %i[mic file dummy].freeze
 
-    attr_reader :host, :port, :scene_file, :audio_source, :audio_file
+    attr_reader :host, :port, :scene_file, :audio_source, :audio_file, :audio_device, :feature_file, :control_preset, :plugin_assets, :noise_gate, :bpm, :osc_port, :projector_mode
 
     # @param scene_file [String, Pathname] scene DSL file path
     # @param host [String] bind host
     # @param port [Integer] bind port
     # @param audio_source [Symbol, String] one of `:mic`, `:file`, `:dummy`
     # @param audio_file [String, Pathname, nil] file path used with `audio_source=:file`
-    def initialize(scene_file:, host: DEFAULT_HOST, port: DEFAULT_PORT, audio_source: DEFAULT_AUDIO_SOURCE, audio_file: nil)
+    # @param audio_device [String, Integer, nil] input device index/name used with `audio_source=:mic`
+    # @param feature_file [String, Pathname, nil] recorded feature JSON used instead of live analysis
+    # @param control_preset [String, Pathname, nil] browser control preset JSON
+    # @param plugin_assets [Array<String, Pathname>] browser plugin renderer files to serve
+    # @param noise_gate [Numeric] RMS threshold below which live input is treated as silence
+    # @param bpm [Numeric, nil] fixed BPM value used when BPM lock is enabled
+    # @param bpm_lock [Boolean] true when the analysis output BPM should stay fixed
+    # @param osc_port [Integer, nil] UDP port for OSC control sync
+    # @param reload [Boolean] true when scene file changes should be reloaded while running
+    # @param projector_mode [Boolean] true when the browser should hide operator UI by default
+    def initialize(
+      scene_file:,
+      host: DEFAULT_HOST,
+      port: DEFAULT_PORT,
+      audio_source: DEFAULT_AUDIO_SOURCE,
+      audio_file: nil,
+      audio_device: nil,
+      feature_file: nil,
+      control_preset: nil,
+      plugin_assets: [],
+      noise_gate: DEFAULT_NOISE_GATE,
+      bpm: nil,
+      bpm_lock: false,
+      osc_port: nil,
+      reload: DEFAULT_RELOAD,
+      projector_mode: false
+    )
       @scene_file = Pathname.new(scene_file).expand_path if scene_file
       @host = host
       @port = Integer(port)
       @audio_source = normalize_audio_source(audio_source)
       @audio_file = audio_file ? Pathname.new(audio_file).expand_path : nil
+      @audio_device = normalize_audio_device(audio_device)
+      @feature_file = feature_file ? Pathname.new(feature_file).expand_path : nil
+      @control_preset = control_preset ? Pathname.new(control_preset).expand_path : nil
+      @plugin_assets = normalize_plugin_assets(plugin_assets)
+      @noise_gate = normalize_noise_gate(noise_gate)
+      @bpm = normalize_bpm(bpm)
+      @bpm_lock = !!bpm_lock
+      @osc_port = normalize_optional_port(osc_port)
+      @reload = !!reload
+      @projector_mode = !!projector_mode
     end
 
     # @return [Boolean] true when the configured scene file exists.
@@ -34,6 +74,21 @@ module Vizcore
       scene_file && scene_file.file?
     end
 
+    # @return [Boolean] true when browser output should start without operator UI.
+    def projector?
+      projector_mode
+    end
+
+    # @return [Boolean] true when scene hot reload is enabled.
+    def reload?
+      @reload
+    end
+
+    # @return [Boolean] true when BPM output should use the fixed BPM value.
+    def bpm_lock?
+      @bpm_lock
+    end
+
     private
 
     def normalize_audio_source(value)
@@ -42,5 +97,51 @@ module Vizcore
 
       raise ArgumentError, "Unsupported audio source: #{value}. Use one of: #{SUPPORTED_AUDIO_SOURCES.join(', ')}"
     end
+
+    def normalize_audio_device(value)
+      return nil if value.nil?
+
+      normalized = value.to_s.strip
+      return nil if normalized.empty?
+
+      normalized
+    end
+
+    def normalize_noise_gate(value)
+      Float(value).clamp(0.0, 1.0)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "Noise gate must be numeric"
+    end
+
+    def normalize_bpm(value)
+      return nil if value.nil?
+
+      numeric = Float(value)
+      raise ArgumentError, "BPM must be positive" unless numeric.positive?
+
+      numeric
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "BPM must be a positive number"
+    end
+
+    def normalize_optional_port(value)
+      return nil if value.nil?
+
+      port_value = Integer(value)
+      raise ArgumentError, "OSC port must be between 1 and 65535" unless port_value.between?(1, 65_535)
+
+      port_value
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "OSC port must be between 1 and 65535"
+    end
+
+    def normalize_plugin_assets(values)
+      Array(values).filter_map do |value|
+        raw_value = value.to_s.strip
+        next if raw_value.empty?
+
+        value.is_a?(Pathname) ? value.expand_path : Pathname.new(raw_value).expand_path
+      end
+    end
   end
 end

data/lib/vizcore/control_preset.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Vizcore
+  # Loads browser control presets shared through the runtime endpoint.
+  class ControlPreset
+    # @param path [String, Pathname]
+    # @return [Hash]
+    def self.load(path)
+      new(path).load
+    end
+
+    # @param path [String, Pathname]
+    # @param payload [Hash]
+    # @return [Hash]
+    def self.write(path, payload)
+      new(path).write(payload)
+    end
+
+    # @param path [String, Pathname]
+    def initialize(path)
+      @path = Pathname.new(path).expand_path
+    end
+
+    # @return [Hash]
+    def load
+      raise ArgumentError, "Control preset file not found: #{@path}" unless @path.file?
+
+      parsed = JSON.parse(@path.read)
+      normalize_payload(parsed)
+    rescue JSON::ParserError => e
+      raise ArgumentError, "Invalid control preset JSON #{@path}: #{e.message}"
+    end
+
+    # @param payload [Hash]
+    # @return [Hash]
+    def write(payload)
+      normalized = normalize_payload(payload)
+      FileUtils.mkdir_p(@path.dirname)
+      @path.write(JSON.pretty_generate(normalized) << "\n")
+      normalized
+    end
+
+    private
+
+    def normalize_payload(value)
+      input = value.is_a?(Hash) ? value : {}
+      visual_settings = hash_value(input, "visual_settings", "visualSettings", "settings")
+      midi_learn_bindings = hash_value(input, "midi_learn_bindings", "midiLearnBindings", "midi")
+
+      {}.tap do |payload|
+        payload["visual_settings"] = visual_settings if visual_settings
+        payload["midi_learn_bindings"] = midi_learn_bindings if midi_learn_bindings
+      end
+    end
+
+    def hash_value(input, *keys)
+      keys.each do |key|
+        value = input[key] || input[key.to_sym]
+        return value if value.is_a?(Hash)
+      end
+      nil
+    end
+  end
+end

data/lib/vizcore/dsl/engine.rb

@@ -3,6 +3,8 @@
 require "pathname"
 require_relative "file_watcher"
 require_relative "scene_builder"
+require_relative "style_builder"
+require_relative "timeline_builder"
 
 module Vizcore
   module DSL
@@ -72,7 +74,14 @@ module Vizcore
         @scenes = []
         @transitions = []
         @midi_mappings = []
+        @key_mappings = []
         @global_params = {}
+        @analysis_settings = {}
+        @section_tail = nil
+        @timelines = []
+        @styles = {}
+        @themes = {}
+        @scene_registry = {}
       end
 
       # Evaluate DSL methods on this engine instance.
@@ -93,6 +102,28 @@ module Vizcore
         @audio_inputs << { name: name.to_sym, options: symbolize_keys(options) }
       end
 
+      # Register a reusable layer parameter style.
+      #
+      # @param name [Symbol, String] style identifier
+      # @yield Style parameter block
+      # @return [void]
+      def style(name, &block)
+        builder = StyleBuilder.new(name: name)
+        style_definition = builder.evaluate(&block).to_h
+        @styles[style_definition[:name]] = deep_dup(style_definition[:params])
+      end
+
+      # Register a reusable scene-wide layer parameter theme.
+      #
+      # @param name [Symbol, String] theme identifier
+      # @yield Theme parameter block
+      # @return [void]
+      def theme(name, &block)
+        builder = StyleBuilder.new(name: name, kind: "theme")
+        theme_definition = builder.evaluate(&block).to_h
+        @themes[theme_definition[:name]] = deep_dup(theme_definition[:params])
+      end
+
       # Register a MIDI input definition.
       #
       # @param name [Symbol, String] input name
@@ -102,15 +133,86 @@ module Vizcore
         @midi_inputs << { name: name.to_sym, options: symbolize_keys(options) }
       end
 
+      # Configure analysis-level audio feature normalization.
+      #
+      # @param mode [Symbol, String] `:off` or `:adaptive`
+      # @param options [Hash] optional `window`, `target`, and `floor` values
+      # @return [Hash] normalized audio normalization settings
+      def audio_normalize(mode: :adaptive, **options)
+        settings = normalize_audio_normalize(mode: mode, **options)
+        @analysis_settings[:audio_normalize] = settings
+      end
+
+      # Set a fixed BPM value for analysis output.
+      #
+      # @param value [Numeric]
+      # @return [Float]
+      def bpm(value)
+        @analysis_settings[:bpm] = positive_float(value, "bpm")
+      end
+
+      # Enable or disable fixed BPM output.
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def bpm_lock(value = true)
+        @analysis_settings[:bpm_lock] = !!value
+      end
+
+      # Enable browser keyboard tap tempo.
+      #
+      # @param key [Symbol, String] key that should send tap tempo events
+      # @return [Hash]
+      def tap_tempo(key: :t)
+        normalized_key = key.to_s.strip.downcase
+        raise ArgumentError, "tap_tempo key must not be empty" if normalized_key.empty?
+
+        @analysis_settings[:tap_tempo] = { key: normalized_key }
+      end
+
       # Define a scene and its layers.
       #
       # @param name [Symbol, String] scene identifier
+      # @param extends [Symbol, String, nil] optional base scene to copy layers from
       # @yield Scene definition block
       # @return [void]
-      def scene(name, &block)
-        builder = SceneBuilder.new(name: name)
+      def scene(name, extends: nil, &block)
+        builder = SceneBuilder.new(name: name, styles: @styles, themes: @themes, layers: inherited_layers(extends))
         builder.evaluate(&block)
-        @scenes << builder.to_h
+        scene_definition = builder.to_h
+        @scenes << scene_definition
+        @scene_registry[scene_definition[:name]] = deep_dup(scene_definition)
+      end
+
+      # Define a beat-counted song section as a scene and auto-transition to the
+      # following section.
+      #
+      # @param name [Symbol, String] scene/section identifier
+      # @param bars [Integer] section duration in bars
+      # @param beats_per_bar [Integer] meter used to convert bars into beats
+      # @yield Scene definition block
+      # @return [void]
+      def section(name, bars:, beats_per_bar: 4, &block)
+        section_name = name.to_sym
+        section_beats = positive_integer(bars, "section bars") * positive_integer(beats_per_bar, "beats_per_bar")
+
+        scene(section_name, &block)
+        add_section_transition(to: section_name) if @section_tail
+        @section_tail = { name: section_name, beats: section_beats }
+      end
+
+      # Define ordered scene markers and derive transitions between them.
+      #
+      # @param beats_per_bar [Integer] meter used by timeline `bars(...)` markers
+      # @yield Timeline marker block
+      # @return [void]
+      def timeline(beats_per_bar: TimelineBuilder::DEFAULT_BEATS_PER_BAR, &block)
+        raise ArgumentError, "timeline requires a block" unless block
+
+        builder = TimelineBuilder.new(beats_per_bar: beats_per_bar).evaluate(&block)
+        entries = builder.to_h
+        @timelines << entries unless entries.empty?
+        @transitions.concat(builder.transitions)
       end
 
       # Define a transition between scenes.
@@ -150,6 +252,25 @@ module Vizcore
         }
       end
 
+      # Register a browser keyboard shortcut for runtime controls.
+      #
+      # @param value [Symbol, String] browser KeyboardEvent key value
+      # @yield Action block (`switch_scene`, `blackout`, or `freeze`)
+      # @raise [ArgumentError] when the key or action is missing
+      # @return [void]
+      def key(value, &block)
+        binding_key = normalize_keyboard_key(value)
+        builder = KeyBindingBuilder.new
+        builder.instance_eval(&block) if block
+        action = builder.to_h
+        raise ArgumentError, "key #{binding_key.inspect} requires an action" if action.empty?
+
+        @key_mappings << {
+          key: binding_key,
+          action: action
+        }
+      end
+
       # Set a mutable global value shared with scene/runtime logic.
       #
       # @param key [Symbol, String] global key
@@ -161,14 +282,20 @@ module Vizcore
 
       # @return [Hash] deep-copied definition payload for renderer/runtime.
       def result
-        {
+        definition = {
           audio: @audio_inputs.map { |item| deep_dup(item) },
           midi: @midi_inputs.map { |item| deep_dup(item) },
           scenes: @scenes.map { |scene| deep_dup(scene) },
           transitions: @transitions.map { |transition| deep_dup(transition) },
           midi_maps: @midi_mappings.map { |mapping| deep_dup(mapping) },
-          globals: deep_dup(@global_params)
+          key_mappings: @key_mappings.map { |mapping| deep_dup(mapping) },
+          globals: deep_dup(@global_params),
+          analysis: deep_dup(@analysis_settings),
+          styles: @styles.map { |name, params| { name: name, params: deep_dup(params) } },
+          themes: @themes.map { |name, params| { name: name, params: deep_dup(params) } }
         }
+        definition[:timelines] = @timelines.map { |timeline| deep_dup(timeline) } unless @timelines.empty?
+        definition
       end
 
       private
@@ -179,6 +306,69 @@ module Vizcore
         end
       end
 
+      def normalize_audio_normalize(mode:, **options)
+        normalized_mode = mode.to_s.strip.to_sym
+        raise ArgumentError, "unsupported audio_normalize mode: #{mode}" unless %i[off adaptive].include?(normalized_mode)
+
+        settings = { mode: normalized_mode }
+        settings[:window] = positive_float(options[:window], "audio_normalize window") if options.key?(:window)
+        settings[:target] = unit_float(options[:target], "audio_normalize target") if options.key?(:target)
+        settings[:floor] = unit_float(options[:floor], "audio_normalize floor") if options.key?(:floor)
+        settings
+      end
+
+      def positive_integer(value, name)
+        numeric = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless numeric.positive?
+
+        numeric
+      end
+
+      def positive_float(value, name)
+        numeric = Float(value)
+        raise ArgumentError, "#{name} must be positive" unless numeric.positive?
+
+        numeric
+      end
+
+      def unit_float(value, name)
+        numeric = Float(value)
+        raise ArgumentError, "#{name} must be between 0.0 and 1.0" unless numeric.between?(0.0, 1.0)
+
+        numeric
+      end
+
+      def normalize_keyboard_key(value)
+        raw = value.to_s
+        return "space" if raw == " "
+
+        normalized = raw.strip.downcase
+        normalized = "space" if normalized == "spacebar"
+        raise ArgumentError, "key value must not be empty" if normalized.empty?
+
+        normalized
+      end
+
+      def add_section_transition(to:)
+        from = @section_tail.fetch(:name)
+        beats = @section_tail.fetch(:beats)
+        @transitions << {
+          from: from,
+          to: to,
+          trigger: proc { beat_count >= beats }
+        }
+      end
+
+      def inherited_layers(scene_name)
+        return [] if scene_name.nil?
+
+        normalized = scene_name.to_sym
+        base_scene = @scene_registry[normalized]
+        raise ArgumentError, "unknown base scene: #{normalized}" unless base_scene
+
+        deep_dup(base_scene.fetch(:layers))
+      end
+
       def deep_dup(value)
         case value
         when Hash
@@ -216,6 +406,31 @@ module Vizcore
           @trigger = block
         end
 
+        # Trigger after a scene-local beat count reaches the given value.
+        #
+        # @param count [Integer]
+        # @return [void]
+        def on_beat(count)
+          beat_target = Integer(count)
+          raise ArgumentError, "on_beat count must be positive" unless beat_target.positive?
+
+          @trigger = proc { beat_count >= beat_target }
+        end
+
+        # Trigger after a scene-local bar count reaches the given value.
+        #
+        # @param count [Integer]
+        # @param beats_per_bar [Integer]
+        # @return [void]
+        def on_bar(count, beats_per_bar: 4)
+          bar_target = Integer(count)
+          beats = Integer(beats_per_bar)
+          raise ArgumentError, "on_bar count must be positive" unless bar_target.positive?
+          raise ArgumentError, "beats_per_bar must be positive" unless beats.positive?
+
+          on_beat(bar_target * beats)
+        end
+
         # @return [Hash] serialized transition extras
         def to_h
           output = {}
@@ -224,6 +439,63 @@ module Vizcore
           output
         end
       end
+
+      # Builder object for `key` block internals.
+      # @api private
+      class KeyBindingBuilder
+        def initialize
+          @action = nil
+        end
+
+        # Switch to a named scene when the key is pressed.
+        #
+        # @param name [Symbol, String]
+        # @return [void]
+        def switch_scene(name)
+          scene_name = name.to_s.strip
+          raise ArgumentError, "switch_scene scene must not be empty" if scene_name.empty?
+
+          assign_action(type: :switch_scene, scene: scene_name)
+        end
+
+        # Toggle browser blackout output.
+        #
+        # @return [void]
+        def blackout
+          live_control(:blackout)
+        end
+
+        # Toggle browser freeze output.
+        #
+        # @return [void]
+        def freeze
+          live_control(:freeze)
+        end
+
+        # Toggle a browser live control.
+        #
+        # @param control [Symbol, String]
+        # @return [void]
+        def live_control(control)
+          normalized = control.to_s.strip.downcase.to_sym
+          raise ArgumentError, "unsupported live control: #{control}" unless %i[blackout freeze].include?(normalized)
+
+          assign_action(type: :live_control, control: normalized)
+        end
+
+        # @return [Hash] serialized key action
+        def to_h
+          @action || {}
+        end
+
+        private
+
+        def assign_action(action)
+          raise ArgumentError, "key mapping already has an action" if @action
+
+          @action = action
+        end
+      end
     end
   end
 end