vizcore 0.1.0 → 1.0.0

data/lib/vizcore/dsl/timeline_builder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects ordered timeline scene markers and converts them to transitions.
+    class TimelineBuilder
+      DEFAULT_BEATS_PER_BAR = 4
+
+      Point = Struct.new(:value, :unit, keyword_init: true)
+
+      def initialize(beats_per_bar: DEFAULT_BEATS_PER_BAR)
+        @beats_per_bar = positive_integer(beats_per_bar, "beats_per_bar")
+        @entries = []
+      end
+
+      # Evaluate a timeline block.
+      #
+      # @yield Timeline marker definitions
+      # @return [Vizcore::DSL::TimelineBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        validate_entries!
+        self
+      end
+
+      # Add a scene marker at a timeline position.
+      #
+      # @param position [Numeric, Point] seconds by default, or a value from `seconds`, `beats`, or `bars`
+      # @param scene [Symbol, String] scene to activate at the position
+      # @return [Hash]
+      def at(position, scene:)
+        point = normalize_position(position)
+        entry = {
+          at: point.value,
+          unit: point.unit,
+          scene: scene.to_sym
+        }
+        @entries << entry
+        entry
+      end
+
+      # @param value [Numeric] seconds from the timeline start
+      # @return [Point]
+      def seconds(value)
+        Point.new(value: non_negative_float(value, "timeline seconds"), unit: :seconds)
+      end
+
+      # @param value [Numeric] beats from the timeline start
+      # @return [Point]
+      def beats(value)
+        Point.new(value: non_negative_float(value, "timeline beats"), unit: :beats)
+      end
+
+      # @param value [Numeric] bars from the timeline start
+      # @param beats_per_bar [Integer, nil] meter override
+      # @return [Point]
+      def bars(value, beats_per_bar: nil)
+        beats_per_measure = beats_per_bar.nil? ? @beats_per_bar : positive_integer(beats_per_bar, "beats_per_bar")
+        beats(non_negative_float(value, "timeline bars") * beats_per_measure)
+      end
+
+      # @return [Array<Hash>] serialized marker definitions
+      def to_h
+        @entries.map(&:dup)
+      end
+
+      # @return [Array<Hash>] generated scene transitions
+      def transitions
+        @entries.each_cons(2).map do |from_entry, to_entry|
+          delta = to_entry.fetch(:at) - from_entry.fetch(:at)
+          {
+            from: from_entry.fetch(:scene),
+            to: to_entry.fetch(:scene),
+            trigger: trigger_for(delta, from_entry.fetch(:unit))
+          }
+        end
+      end
+
+      private
+
+      def normalize_position(position)
+        return position if position.is_a?(Point)
+
+        seconds(position)
+      end
+
+      def trigger_for(delta, unit)
+        case unit
+        when :seconds
+          proc { seconds >= delta }
+        when :beats
+          proc { beat_count >= delta }
+        else
+          proc { false }
+        end
+      end
+
+      def validate_entries!
+        return if @entries.length < 2
+
+        unit = @entries.first.fetch(:unit)
+        @entries.each_cons(2) do |from_entry, to_entry|
+          raise ArgumentError, "timeline entries must use the same unit" unless to_entry.fetch(:unit) == unit
+
+          from_position = from_entry.fetch(:at)
+          to_position = to_entry.fetch(:at)
+          raise ArgumentError, "timeline positions must increase" unless to_position > from_position
+        end
+      end
+
+      def non_negative_float(value, name)
+        numeric = parse_float(value, name)
+        raise ArgumentError, "#{name} must be non-negative" if numeric.negative?
+
+        numeric
+      end
+
+      def positive_integer(value, name)
+        numeric = parse_integer(value, name)
+        raise ArgumentError, "#{name} must be positive" unless numeric.positive?
+
+        numeric
+      end
+
+      def parse_float(value, name)
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{name} must be numeric"
+      end
+
+      def parse_integer(value, name)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{name} must be an integer"
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/transition_controller.rb

@@ -4,6 +4,8 @@ module Vizcore
   module DSL
     # Evaluates transition rules and returns scene-change payloads.
     class TransitionController
+      DEFAULT_FRAME_RATE = 60.0
+
       # @param scenes [Array<Hash>]
       # @param transitions [Array<Hash>]
       def initialize(scenes:, transitions:)
@@ -108,6 +110,8 @@ module Vizcore
         def initialize(audio, frame_count:)
           @audio = symbolize_hash(audio)
           @bands = symbolize_hash(@audio[:bands])
+          @onsets = symbolize_hash(@audio[:onsets])
+          @drums = symbolize_hash(@audio[:drums])
           @frame_count = Integer(frame_count)
         rescue StandardError
           @frame_count = 0
@@ -124,16 +128,84 @@ module Vizcore
           @bands[name.to_sym].to_f
         end
 
+        # @return [Float]
+        def sub
+          frequency_band(:sub)
+        end
+
+        # @return [Float]
+        def low
+          frequency_band(:low)
+        end
+
+        # @return [Float]
+        def bass
+          frequency_band(:low)
+        end
+
+        # @return [Float]
+        def mid
+          frequency_band(:mid)
+        end
+
+        # @return [Float]
+        def high
+          frequency_band(:high)
+        end
+
+        # @return [Float]
+        def treble
+          frequency_band(:high)
+        end
+
         # @return [Array<Float>]
         def fft_spectrum
           Array(@audio[:fft])
         end
 
+        # @param name [Symbol, String, nil]
+        # @return [Float]
+        def onset(name = nil)
+          return @audio[:onset].to_f if name.nil?
+
+          @onsets[name.to_sym].to_f
+        end
+
+        # @return [Float]
+        def kick
+          @drums[:kick].to_f
+        end
+
+        # @return [Float]
+        def snare
+          @drums[:snare].to_f
+        end
+
+        # @return [Float]
+        def hihat
+          @drums[:hihat].to_f
+        end
+
         # @return [Boolean]
         def beat?
           !!@audio[:beat]
         end
 
+        # @return [Boolean]
+        def beat
+          beat?
+        end
+
+        # @return [Float]
+        def beat_confidence
+          @audio[:beat_confidence].to_f
+        end
+
+        # @return [Float]
+        def beat_pulse
+          @audio[:beat_pulse].to_f
+        end
+
         # @return [Integer]
         def beat_count
           Integer(@audio[:beat_count] || 0)
@@ -151,6 +223,11 @@ module Vizcore
           @frame_count
         end
 
+        # @return [Float] scene-local elapsed seconds at the default runtime frame rate
+        def seconds
+          @frame_count / DEFAULT_FRAME_RATE
+        end
+
         private
 
         def symbolize_hash(value)

data/lib/vizcore/dsl.rb

@@ -6,11 +6,15 @@ module Vizcore
   end
 end
 
-require_relative "dsl/layer_builder"
 require_relative "dsl/file_watcher"
 require_relative "dsl/mapping_resolver"
+require_relative "dsl/mapping_transform_builder"
 require_relative "dsl/midi_map_executor"
+require_relative "dsl/reaction_builder"
+require_relative "dsl/style_builder"
+require_relative "dsl/layer_builder"
 require_relative "dsl/scene_builder"
 require_relative "dsl/shader_source_resolver"
+require_relative "dsl/timeline_builder"
 require_relative "dsl/transition_controller"
 require_relative "dsl/engine"

data/lib/vizcore/layer_catalog.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Metadata for built-in layer types, params, shaders, and browser effects.
+  module LayerCatalog
+    Capability = Struct.new(:type, :aliases, :params, :mappable_params, :description, keyword_init: true) do
+      def types
+        [type, *aliases].map(&:to_sym)
+      end
+
+      def supports?(value)
+        types.include?(value.to_sym)
+      rescue StandardError
+        false
+      end
+    end
+
+    COMMON_PARAMS = {
+      opacity: "Float",
+      blend: "Symbol",
+      effect: "Symbol",
+      effect_intensity: "Float",
+      vj_effect: "Symbol",
+      palette: "Array<String>",
+      color: "String",
+      group: "Symbol"
+    }.freeze
+
+    CAPABILITIES = [
+      Capability.new(
+        type: :geometry,
+        aliases: %i[wireframe_cube radial_blob],
+        params: COMMON_PARAMS.merge(
+          rotation_speed: "Float",
+          color_shift: "Float",
+          deform: "Array<Float>"
+        ),
+        mappable_params: %i[rotation_speed color_shift deform],
+        description: "Wireframe and radial geometry rendered by the browser."
+      ),
+      Capability.new(
+        type: :shader,
+        aliases: [],
+        params: COMMON_PARAMS.merge(
+          shader_reload: "Boolean",
+          param_schema: "Array<Hash>"
+        ),
+        mappable_params: %i[effect_intensity],
+        description: "GLSL ES fragment shader layer with built-in audio uniforms."
+      ),
+      Capability.new(
+        type: :particle_field,
+        aliases: %i[particles particle],
+        params: COMMON_PARAMS.merge(
+          count: "Integer",
+          speed: "Float",
+          size: "Float",
+          force_field: "Symbol",
+          turbulence: "Float",
+          bass_explosion: "Float",
+          sparkle: "Float"
+        ),
+        mappable_params: %i[speed size turbulence bass_explosion sparkle],
+        description: "Audio-reactive point particles with simple force fields."
+      ),
+      Capability.new(
+        type: :text,
+        aliases: %i[text_layer],
+        params: COMMON_PARAMS.merge(
+          content: "String",
+          font_size: "Integer",
+          letter_spacing: "Float",
+          font: "String",
+          align: "Symbol",
+          stroke_width: "Float",
+          stroke_color: "String",
+          shadow_color: "String",
+          shadow_blur: "Float",
+          glow_strength: "Float"
+        ),
+        mappable_params: %i[font_size letter_spacing glow_strength],
+        description: "Canvas text rendered into the WebGL scene."
+      ),
+      Capability.new(
+        type: :svg,
+        aliases: %i[svg_layer],
+        params: COMMON_PARAMS.merge(
+          file: "String",
+          src: "String",
+          scale: "Float",
+          rotation: "Float",
+          fit: "Symbol"
+        ),
+        mappable_params: %i[scale rotation opacity],
+        description: "Inline SVG asset rendered as a textured visual layer."
+      ),
+      Capability.new(
+        type: :image,
+        aliases: %i[image_layer photo],
+        params: COMMON_PARAMS.merge(
+          file: "String",
+          src: "String",
+          scale: "Float",
+          rotation: "Float",
+          fit: "Symbol"
+        ),
+        mappable_params: %i[scale rotation opacity],
+        description: "Inline PNG/JPEG/GIF/WebP image asset rendered as a textured visual layer."
+      ),
+      Capability.new(
+        type: :video,
+        aliases: %i[video_layer footage],
+        params: COMMON_PARAMS.merge(
+          file: "String",
+          src: "String",
+          fit: "Symbol",
+          scale: "Float",
+          rotation: "Float",
+          playback_rate: "Float",
+          invert: "Float"
+        ),
+        mappable_params: %i[scale rotation opacity playback_rate invert],
+        description: "Inline MP4/WebM/OGV video texture rendered as a looping visual layer."
+      ),
+      Capability.new(
+        type: :waveform,
+        aliases: %i[waveform_layer],
+        params: COMMON_PARAMS.merge(
+          source: "Symbol",
+          style: "Symbol",
+          height: "Float",
+          detail: "Integer"
+        ),
+        mappable_params: %i[height opacity color_shift],
+        description: "Audio feature waveform rendered as line, mirror, or ribbon geometry."
+      ),
+      Capability.new(
+        type: :spectrogram,
+        aliases: %i[spectrogram_layer],
+        params: COMMON_PARAMS.merge(
+          scroll: "Symbol",
+          bins: "Integer",
+          history: "Integer",
+          gain: "Float"
+        ),
+        mappable_params: %i[gain opacity],
+        description: "Scrolling FFT heatmap rendered by the browser."
+      ),
+      Capability.new(
+        type: :shape,
+        aliases: %i[shapes shape_layer],
+        params: COMMON_PARAMS.merge(
+          shapes: "Array<Hash>",
+          color_shift: "Float"
+        ),
+        mappable_params: %i[color_shift opacity],
+        description: "Declarative 2D circle and line primitives rendered by the browser."
+      ),
+      Capability.new(
+        type: :mesh,
+        aliases: %i[mesh_layer preset_mesh],
+        params: COMMON_PARAMS.merge(
+          geometry: "Symbol",
+          material: "Symbol",
+          scale: "Float",
+          deform: "Float",
+          color_shift: "Float"
+        ),
+        mappable_params: %i[scale deform opacity color_shift],
+        description: "Preset 3D wireframe meshes: cube, tetrahedron, octahedron, and icosahedron."
+      )
+    ].freeze
+
+    BUILTIN_SHADERS = %i[
+      default gradient_pulse bass_tunnel neon_grid kaleidoscope spectrum_rings
+      liquid_wobble audio_bars ruby_crystal starfield waveform_ribbon
+      unyo_geometry glitch_flash
+    ].freeze
+
+    BLEND_MODES = %i[
+      alpha normal add additive multiply screen difference
+    ].freeze
+
+    POST_EFFECTS = %i[
+      bloom glitch chromatic feedback motion_blur crt
+    ].freeze
+
+    VJ_EFFECTS = %i[
+      mirror color_shift pixelate
+    ].freeze
+
+    module_function
+
+    def capabilities
+      (CAPABILITIES + plugin_capabilities).freeze
+    end
+
+    def capability_for(type)
+      capabilities.find { |capability| capability.supports?(type) }
+    end
+
+    def supported_type?(type)
+      !!capability_for(type)
+    end
+
+    def supported_types
+      capabilities.flat_map(&:types).uniq.freeze
+    end
+
+    def params_for(type)
+      capability_for(type)&.params || {}
+    end
+
+    def mappable_params_for(type)
+      capability_for(type)&.mappable_params || []
+    end
+
+    def register_layer_capability(type:, aliases: [], params: {}, mappable_params: [], description: nil)
+      capability = Capability.new(
+        type: normalize_type!(type),
+        aliases: normalize_symbols(aliases),
+        params: COMMON_PARAMS.merge(normalize_param_types(params)),
+        mappable_params: normalize_symbols(mappable_params),
+        description: normalize_description(description)
+      )
+      validate_plugin_capability!(capability)
+      plugin_capabilities.reject! { |entry| entry.type == capability.type }
+      plugin_capabilities << capability
+      capability
+    end
+
+    def reset_plugin_capabilities!
+      plugin_capabilities.clear
+    end
+
+    def plugin_capabilities
+      @plugin_capabilities ||= []
+    end
+
+    def normalize_type!(type)
+      value = type.to_s.strip
+      raise ArgumentError, "layer capability type must not be empty" if value.empty?
+
+      value.to_sym
+    end
+
+    def normalize_symbols(values)
+      Array(values).filter_map do |value|
+        symbol = value.to_s.strip
+        symbol.empty? ? nil : symbol.to_sym
+      end.uniq
+    end
+
+    def normalize_param_types(params)
+      Hash(params).to_h do |name, type|
+        [normalize_type!(name), type.to_s]
+      end
+    end
+
+    def normalize_description(description)
+      value = description.to_s.strip
+      value.empty? ? "Plugin layer capability." : value
+    end
+
+    def validate_plugin_capability!(capability)
+      reserved_types = CAPABILITIES.flat_map(&:types)
+      conflicts = capability.types & reserved_types
+      return if conflicts.empty?
+
+      raise ArgumentError, "layer capability conflicts with built-in type: #{conflicts.first}"
+    end
+  end
+end

data/lib/vizcore/project_manifest.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Vizcore
+  # Reads a project-level manifest such as vizcore.yml.
+  class ProjectManifest
+    # @param path [String, Pathname]
+    # @return [Vizcore::ProjectManifest]
+    def self.load(path)
+      new(path)
+    end
+
+    attr_reader :path, :root
+
+    # @param path [String, Pathname]
+    def initialize(path)
+      @path = Pathname.new(path).expand_path
+      raise ArgumentError, "Project manifest not found: #{@path}" unless @path.file?
+
+      @root = @path.dirname
+      @data = normalize_hash(YAML.safe_load_file(@path, aliases: false) || {})
+    rescue Psych::Exception => e
+      raise ArgumentError, "Invalid project manifest #{@path}: #{e.message}"
+    end
+
+    # @return [Hash] config defaults accepted by Vizcore::Config
+    def config_defaults(profile: nil)
+      data = data_for(profile)
+      {
+        scene_file: expand_path(value_at(data, "scene") || value_at(data, "scene_file")),
+        audio_source: value_at(data, "audio_source") || value_at(data, "audio", "source"),
+        audio_file: expand_path(value_at(data, "audio_file") || value_at(data, "audio", "file")),
+        audio_device: value_at(data, "audio_device") || value_at(data, "audio", "device"),
+        feature_file: expand_path(value_at(data, "feature_file") || value_at(data, "features")),
+        control_preset: expand_path(value_at(data, "control_preset") || value_at(data, "controlPreset")),
+        osc_port: value_at(data, "osc_port") || value_at(data, "sync", "osc_port") || value_at(data, "sync", "osc", "port"),
+        plugin_assets: plugin_assets(profile: profile)
+      }.compact
+    end
+
+    # @return [Array<String>] require paths loaded before scene evaluation
+    def plugins(profile: nil)
+      plugin_entries(profile: profile).filter_map { |entry| plugin_require_path(entry) }.uniq
+    end
+
+    # @return [Array<Pathname>] frontend plugin assets served and loaded by RackApp
+    def plugin_assets(profile: nil)
+      entries = plugin_entries(profile: profile)
+      assets = base_values("plugin_assets", "frontend_plugins") + profile_values(profile, "plugin_assets", "frontend_plugins")
+      (entries.filter_map { |entry| plugin_asset_path(entry) } + assets.filter_map { |entry| expand_path(entry) }).uniq
+    end
+
+    # @return [Array<String>] configured profile names
+    def profile_names
+      Hash(@data["profiles"] || {}).keys
+    end
+
+    private
+
+    def value_at(data, *keys)
+      current = data
+      keys.each do |key|
+        return nil unless current.is_a?(Hash)
+
+        current = current[key.to_s]
+      end
+      current
+    end
+
+    def data_for(profile)
+      profile_name = profile.to_s.strip
+      return @data if profile_name.empty?
+
+      deep_merge(@data.reject { |key, _value| key == "profiles" }, profile_overlay(profile_name))
+    end
+
+    def plugin_entries(profile:)
+      base_entries = base_values("plugins", ["package", "plugins"])
+      profile_entries = profile_values(profile, "plugins", ["package", "plugins"])
+      base_entries + profile_entries
+    end
+
+    def base_values(*paths)
+      paths.each do |path|
+        value = path.is_a?(Array) ? value_at(@data, *path) : value_at(@data, path)
+        return Array(value) if value
+      end
+      []
+    end
+
+    def profile_values(profile, *paths)
+      overlay = profile_overlay(profile)
+      return [] if overlay.empty?
+
+      paths.each do |path|
+        value = path.is_a?(Array) ? value_at(overlay, *path) : value_at(overlay, path)
+        return Array(value) if value
+      end
+      []
+    end
+
+    def profile_overlay(profile)
+      profile_name = profile.to_s.strip
+      return {} if profile_name.empty?
+
+      profiles = Hash(@data["profiles"] || {})
+      normalize_hash(profiles.fetch(profile_name) do
+        raise ArgumentError, "Unknown project profile: #{profile_name}. Use one of: #{profile_names.join(', ')}"
+      end)
+    end
+
+    def plugin_require_path(entry)
+      value = if entry.is_a?(Hash)
+                entry["require"] || entry[:require] || entry["name"] || entry[:name]
+              else
+                entry
+              end
+      plugin = value.to_s.strip
+      plugin unless plugin.empty?
+    end
+
+    def plugin_asset_path(entry)
+      return nil unless entry.is_a?(Hash)
+
+      expand_path(entry["asset"] || entry[:asset] || entry["frontend"] || entry[:frontend])
+    end
+
+    def expand_path(value)
+      raw_value = value.to_s.strip
+      return nil if raw_value.empty?
+
+      path_value = Pathname.new(raw_value)
+      path_value.absolute? ? path_value : @root.join(path_value).expand_path
+    end
+
+    def deep_merge(base, overlay)
+      base.merge(overlay) do |_key, left, right|
+        left.is_a?(Hash) && right.is_a?(Hash) ? deep_merge(left, right) : right
+      end
+    end
+
+    def normalize_hash(value)
+      return {} unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, entry), output|
+        output[key.to_s] = entry.is_a?(Hash) ? normalize_hash(entry) : entry
+      end
+    end
+  end
+end