vizcore 0.1.0 → 1.1.0

data/lib/vizcore/layer_catalog.rb

@@ -0,0 +1,275 @@
+# 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>",
+          shape_schema_version: "Integer",
+          units: "Symbol",
+          color_shift: "Float"
+        ),
+        mappable_params: %i[color_shift opacity shapes],
+        description: "Declarative and Ruby-generated 2D circle, line, rect, polygon, polyline, path, and star 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

data/lib/vizcore/renderer/png_writer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Vizcore
+  module Renderer
+    # Minimal PNG encoder for RGBA pixel buffers.
+    class PngWriter
+      SIGNATURE = "\x89PNG\r\n\x1A\n".b
+      COLOR_TYPE_RGBA = 6
+      BIT_DEPTH = 8
+
+      class << self
+        # @param width [Integer]
+        # @param height [Integer]
+        # @param rgba [String] RGBA bytes, row-major
+        # @return [String] PNG bytes
+        def encode(width:, height:, rgba:)
+          width = Integer(width)
+          height = Integer(height)
+          pixels = rgba.to_s.b
+          expected_size = width * height * 4
+          raise ArgumentError, "RGBA buffer must be #{expected_size} bytes" unless pixels.bytesize == expected_size
+
+          SIGNATURE + chunk("IHDR", ihdr(width, height)) + chunk("IDAT", Zlib::Deflate.deflate(scanlines(width, height, pixels))) + chunk("IEND", "".b)
+        end
+
+        # @return [void]
+        def write(path:, width:, height:, rgba:)
+          File.binwrite(path, encode(width: width, height: height, rgba: rgba))
+        end
+
+        private
+
+        def ihdr(width, height)
+          [width, height, BIT_DEPTH, COLOR_TYPE_RGBA, 0, 0, 0].pack("NNCCCCC")
+        end
+
+        def scanlines(width, height, pixels)
+          row_size = width * 4
+          output = +""
+          output.force_encoding(Encoding::BINARY)
+          height.times do |row|
+            output << "\x00".b
+            output << pixels.byteslice(row * row_size, row_size)
+          end
+          output
+        end
+
+        def chunk(type, data)
+          typed_data = type.b + data.b
+          [data.bytesize].pack("N") + typed_data + [Zlib.crc32(typed_data)].pack("N")
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/renderer/render_sequence.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "pathname"
+require "tmpdir"
+require_relative "scene_frame_source"
+require_relative "snapshot_renderer"
+
+module Vizcore
+  module Renderer
+    # Writes a deterministic PNG image sequence from a scene.
+    class RenderSequence
+      DEFAULT_FRAME_COUNT = 60
+      DEFAULT_FRAME_RATE = 30.0
+
+      def initialize(
+        config:,
+        frames: DEFAULT_FRAME_COUNT,
+        fps: DEFAULT_FRAME_RATE,
+        width: SnapshotRenderer::DEFAULT_WIDTH,
+        height: SnapshotRenderer::DEFAULT_HEIGHT,
+        command_runner: Open3,
+        ffmpeg_checker: nil
+      )
+        @config = config
+        @frames = normalize_frame_count(frames)
+        @fps = normalize_frame_rate(fps)
+        @width = width
+        @height = height
+        @command_runner = command_runner
+        @ffmpeg_checker = ffmpeg_checker || method(:ffmpeg_available?)
+      end
+
+      # @param out [String, Pathname] output directory for PNG frames, or `.mp4`
+      # @return [Hash] render metadata
+      def write(out:)
+        output_path = Pathname.new(out.to_s).expand_path
+        return write_video(output_path) if video_output?(output_path)
+
+        write_frames(output_path)
+      end
+
+      private
+
+      def write_frames(output_dir)
+        FileUtils.mkdir_p(output_dir)
+        render_frames(output_dir).merge(path: output_dir, format: :png_sequence)
+      end
+
+      def write_video(output_file)
+        raise ArgumentError, "Only .mp4 video output is supported" unless output_file.extname.downcase == ".mp4"
+        raise ArgumentError, "ffmpeg is required for MP4 output" unless @ffmpeg_checker.call
+
+        FileUtils.mkdir_p(output_file.dirname)
+        metadata = nil
+        Dir.mktmpdir("vizcore-render-frames") do |dir|
+          frame_dir = Pathname.new(dir)
+          metadata = render_frames(frame_dir)
+          encode_mp4(frame_dir: frame_dir, output_file: output_file)
+        end
+        metadata.merge(path: output_file, format: :mp4)
+      end
+
+      def render_frames(output_dir)
+        source = SceneFrameSource.new(config: @config, frame_rate: @fps)
+        source.start
+        renderer = SnapshotRenderer.new(width: @width, height: @height)
+        scene_name = nil
+
+        @frames.times do |index|
+          frame = source.capture
+          scene_name ||= frame.fetch(:scene_name)
+          File.binwrite(
+            frame_path(output_dir, index),
+            renderer.render(scene: frame.fetch(:scene), audio: frame.fetch(:audio))
+          )
+        end
+
+        {
+          frames: @frames,
+          fps: @fps,
+          width: renderer.width,
+          height: renderer.height,
+          scene: scene_name
+        }
+      ensure
+        source&.stop
+      end
+
+      def video_output?(path)
+        %w[.mp4 .mov .webm].include?(path.extname.downcase)
+      end
+
+      def frame_path(output_dir, index)
+        output_dir.join(format("frame_%05d.png", index + 1))
+      end
+
+      def encode_mp4(frame_dir:, output_file:)
+        stdout, stderr, status = @command_runner.capture3(*ffmpeg_command(frame_dir: frame_dir, output_file: output_file))
+        return if status.success?
+
+        detail = stderr.to_s.strip.empty? ? stdout.to_s.strip : stderr.to_s.strip
+        message = detail.empty? ? "ffmpeg failed with non-zero status" : "ffmpeg failed: #{detail}"
+        raise ArgumentError, message
+      end
+
+      def ffmpeg_command(frame_dir:, output_file:)
+        [
+          "ffmpeg",
+          "-y",
+          "-framerate",
+          format_frame_rate,
+          "-i",
+          frame_dir.join("frame_%05d.png").to_s,
+          "-vf",
+          "format=yuv420p",
+          "-pix_fmt",
+          "yuv420p",
+          output_file.to_s
+        ]
+      end
+
+      def ffmpeg_available?
+        system("ffmpeg", "-version", out: File::NULL, err: File::NULL)
+      end
+
+      def format_frame_rate
+        return @fps.to_i.to_s if @fps == @fps.to_i
+
+        @fps.to_s
+      end
+
+      def normalize_frame_count(value)
+        count = Integer(value)
+        raise ArgumentError, "frames must be positive" unless count.positive?
+
+        count
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "frames must be a positive integer"
+      end
+
+      def normalize_frame_rate(value)
+        rate = Float(value)
+        raise ArgumentError, "fps must be positive" unless rate.positive?
+
+        rate
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "fps must be a positive number"
+      end
+    end
+  end
+end