vizcore 0.1.0 → 1.1.0

data/lib/vizcore/dsl/shader_source_resolver.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
+require "base64"
 require "pathname"
 
 module Vizcore
   module DSL
-    # Replaces layer `glsl` paths with inlined shader source text.
+    # Replaces external layer source paths with browser-ready inline payloads.
     class ShaderSourceResolver
+      MEDIA_MIME_TYPES = {
+        ".gif" => "image/gif",
+        ".jpg" => "image/jpeg",
+        ".jpeg" => "image/jpeg",
+        ".png" => "image/png",
+        ".svg" => "image/svg+xml",
+        ".webp" => "image/webp",
+        ".mp4" => "video/mp4",
+        ".ogv" => "video/ogg",
+        ".webm" => "video/webm"
+      }.freeze
+
       # @param definition [Hash] DSL definition payload
       # @param scene_file [String, Pathname] source scene file
-      # @raise [ArgumentError] when a referenced GLSL file is missing
-      # @return [Hash] deep-copied definition with `:glsl_source` entries
+      # @raise [ArgumentError] when a referenced source file is missing
+      # @return [Hash] deep-copied definition with resolved layer source entries
       def resolve(definition:, scene_file:)
         scene_path = Pathname.new(scene_file.to_s).expand_path
         base_dir = scene_path.dirname
@@ -29,8 +42,13 @@ module Vizcore
       def resolve_layer(layer, base_dir:)
         layer_hash = symbolize_hash(layer)
         shader_path = layer_hash[:glsl]
-        return layer_hash unless shader_path
+        layer_hash = resolve_shader_layer(layer_hash, base_dir: base_dir) if shader_path
+        layer_hash = resolve_media_layer(layer_hash, base_dir: base_dir) if media_layer?(layer_hash)
+        layer_hash
+      end
 
+      def resolve_shader_layer(layer_hash, base_dir:)
+        shader_path = layer_hash.fetch(:glsl)
         full_path = resolve_path(base_dir: base_dir, shader_path: shader_path)
         raise ArgumentError, "GLSL file not found: #{shader_path}" unless full_path.file?
 
@@ -39,8 +57,51 @@ module Vizcore
         layer_hash
       end
 
-      def resolve_path(base_dir:, shader_path:)
-        path = Pathname.new(shader_path.to_s)
+      def resolve_media_layer(layer_hash, base_dir:)
+        params = symbolize_hash(layer_hash[:params] || {})
+        media_path = params[:file]
+        return layer_hash unless media_path
+
+        full_path = resolve_path(base_dir: base_dir, relative_path: media_path)
+        raise ArgumentError, "#{media_layer_label(layer_hash)} file not found: #{media_path}" unless full_path.file?
+
+        mime_type = MEDIA_MIME_TYPES[full_path.extname.downcase]
+        raise ArgumentError, "Unsupported #{media_layer_label(layer_hash)} file extension: #{media_path}" unless mime_type
+        raise ArgumentError, "Unsupported SVG file extension: #{media_path}" if svg_layer?(layer_hash) && mime_type != "image/svg+xml"
+        raise ArgumentError, "Unsupported Image file extension: #{media_path}" if image_layer?(layer_hash) && !mime_type.start_with?("image/")
+        raise ArgumentError, "Unsupported Video file extension: #{media_path}" if video_layer?(layer_hash) && !mime_type.start_with?("video/")
+
+        params[:file] = media_path.to_s
+        params[:src] = "data:#{mime_type};base64,#{Base64.strict_encode64(full_path.binread)}"
+        layer_hash[:params] = params
+        layer_hash
+      end
+
+      def svg_layer?(layer_hash)
+        %i[svg svg_layer].include?(layer_hash[:type]&.to_sym)
+      end
+
+      def image_layer?(layer_hash)
+        %i[image image_layer photo].include?(layer_hash[:type]&.to_sym)
+      end
+
+      def video_layer?(layer_hash)
+        %i[video video_layer footage].include?(layer_hash[:type]&.to_sym)
+      end
+
+      def media_layer?(layer_hash)
+        svg_layer?(layer_hash) || image_layer?(layer_hash) || video_layer?(layer_hash)
+      end
+
+      def media_layer_label(layer_hash)
+        return "SVG" if svg_layer?(layer_hash)
+        return "Video" if video_layer?(layer_hash)
+
+        "Image"
+      end
+
+      def resolve_path(base_dir:, relative_path: nil, shader_path: nil)
+        path = Pathname.new((relative_path || shader_path).to_s)
         return path.expand_path if path.absolute?
 
         base_dir.join(path).expand_path

data/lib/vizcore/dsl/style_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects reusable layer parameter presets for the `style` DSL.
+    class StyleBuilder
+      # @param name [Symbol, String] style identifier
+      # @param kind [String] user-facing DSL kind for error messages
+      def initialize(name:, kind: "style")
+        @name = name.to_sym
+        @kind = kind
+        @params = {}
+      end
+
+      # Evaluate a style block.
+      #
+      # @yield Style parameter declarations
+      # @return [Vizcore::DSL::StyleBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        raise ArgumentError, "#{@kind} #{@name} requires at least one parameter" if @params.empty?
+
+        self
+      end
+
+      # @return [Hash] serialized style payload
+      def to_h
+        {
+          name: @name,
+          params: @params.dup
+        }
+      end
+
+      # Store an ordered color palette for styles and themes.
+      #
+      # @param colors [Array<String, Array<String>>] color values such as "#00ffff"
+      # @raise [ArgumentError] when no non-blank colors are supplied
+      # @return [Array<String>]
+      def palette(*colors)
+        @params[:palette] = normalize_palette(colors)
+      end
+
+      # Stores one-argument style setters into `params`.
+      # @api private
+      def method_missing(method_name, *args, &block)
+        if block.nil? && args.length == 1
+          @params[method_name.to_sym] = args.first
+          return args.first
+        end
+
+        super
+      end
+
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
+      end
+
+      private
+
+      def normalize_palette(colors)
+        values = colors.flatten.map { |color| color.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "#{@kind} #{@name} palette requires at least one color" if values.empty?
+
+        values
+      end
+    end
+  end
+end

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"