vizcore 0.1.0 → 1.0.0

data/lib/vizcore/cli/scene_inspector.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module CLISupport
+    # Formats loaded scene definitions for CLI inspection.
+    class SceneInspector
+      def initialize(definition:)
+        @definition = definition
+      end
+
+      def lines
+        output = []
+        append_inputs(output, "Audio", Array(@definition[:audio]))
+        append_inputs(output, "MIDI", Array(@definition[:midi]))
+        append_scenes(output, Array(@definition[:scenes]))
+        append_timelines(output, Array(@definition[:timelines]))
+        append_transitions(output, Array(@definition[:transitions]))
+        append_key_mappings(output, Array(@definition[:key_mappings]))
+        output
+      end
+
+      private
+
+      def append_inputs(output, label, values)
+        return if values.empty?
+
+        output << "#{label}:"
+        values.each do |input|
+          output << "  - #{input[:name]}#{format_options(input[:options])}"
+        end
+      end
+
+      def append_scenes(output, scenes)
+        output << "Scenes:"
+        if scenes.empty?
+          output << "  (none)"
+          return
+        end
+
+        scenes.each do |scene|
+          output << "  #{scene[:name]}"
+          append_layers(output, Array(scene[:layers]))
+        end
+      end
+
+      def append_layers(output, layers)
+        layers.each do |layer|
+          output << "    layer #{layer[:name]} (#{format_layer(layer)})"
+          Array(layer[:mappings]).each do |mapping|
+            output << "      #{format_source(mapping[:source])} -> #{mapping[:target]}#{format_transform(mapping[:transform])}"
+          end
+        end
+      end
+
+      def append_transitions(output, transitions)
+        return if transitions.empty?
+
+        output << "Transitions:"
+        transitions.each do |transition|
+          trigger = transition[:trigger].respond_to?(:call) ? "triggered" : "no trigger"
+          output << "  #{transition[:from]} -> #{transition[:to]} (#{trigger})"
+        end
+      end
+
+      def append_timelines(output, timelines)
+        timelines.each_with_index do |timeline, index|
+          next if Array(timeline).empty?
+
+          output << "Timeline #{index + 1}:"
+          Array(timeline).each do |entry|
+            output << "  #{format_timeline_position(entry)} -> #{entry[:scene]}"
+          end
+        end
+      end
+
+      def append_key_mappings(output, mappings)
+        return if mappings.empty?
+
+        output << "Keyboard:"
+        mappings.each do |mapping|
+          output << "  #{mapping[:key]} -> #{format_key_action(mapping[:action])}"
+        end
+      end
+
+      def format_layer(layer)
+        type = layer[:type] || :geometry
+        return "#{type}, shader=#{layer[:shader]}" if layer[:shader]
+        return "#{type}, glsl=#{layer[:glsl]}" if layer[:glsl]
+
+        type.to_s
+      end
+
+      def format_source(source)
+        values = Hash(source || {})
+        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]
+
+        values[:kind].to_s
+      end
+
+      def format_transform(transform)
+        values = Hash(transform || {})
+        return "" if values.empty?
+
+        formatted = values.map { |key, value| "#{key}=#{value.inspect}" }.join(", ")
+        " [#{formatted}]"
+      end
+
+      def format_options(options)
+        values = Hash(options || {})
+        return "" if values.empty?
+
+        formatted = values.map { |key, value| "#{key}=#{value.inspect}" }.join(", ")
+        " (#{formatted})"
+      end
+
+      def format_key_action(action)
+        values = Hash(action || {})
+        case values[:type]&.to_sym
+        when :switch_scene
+          "switch_scene #{values[:scene]}"
+        when :live_control
+          values[:control].to_s
+        else
+          "unknown"
+        end
+      end
+
+      def format_timeline_position(entry)
+        unit = entry[:unit] == :seconds ? "s" : " beats"
+        "#{entry[:at]}#{unit}"
+      end
+    end
+  end
+end

data/lib/vizcore/cli/scene_validator.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "../../vizcore"
+require_relative "../dsl"
+require_relative "../layer_catalog"
+
+module Vizcore
+  module CLISupport
+    # Validates scene DSL files without starting the realtime server.
+    class SceneValidator
+      BUILTIN_SHADERS = Vizcore::LayerCatalog::BUILTIN_SHADERS
+
+      MAPPING_SOURCE_KINDS = %i[
+        amplitude frequency_band fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+      ].freeze
+
+      FREQUENCY_BANDS = %i[sub low mid high].freeze
+      SUPPORTED_BLEND_MODES = Vizcore::LayerCatalog::BLEND_MODES
+      SUPPORTED_POST_EFFECTS = Vizcore::LayerCatalog::POST_EFFECTS
+      SUPPORTED_VJ_EFFECTS = Vizcore::LayerCatalog::VJ_EFFECTS
+
+      Issue = Struct.new(:severity, :message, keyword_init: true) do
+        def error?
+          severity == :error
+        end
+      end
+
+      Result = Struct.new(:definition, :issues, keyword_init: true) do
+        def valid?
+          issues.none?(&:error?)
+        end
+
+        def errors
+          issues.select(&:error?)
+        end
+
+        def warnings
+          issues.reject(&:error?)
+        end
+      end
+
+      def initialize(scene_file:, loader: Vizcore::DSL::Engine.method(:load_file), shader_resolver: Vizcore::DSL::ShaderSourceResolver.new)
+        @scene_file = scene_file
+        @loader = loader
+        @shader_resolver = shader_resolver
+      end
+
+      def call
+        definition = load_definition
+        Result.new(definition: definition, issues: validate_definition(definition))
+      rescue StandardError => e
+        Result.new(
+          definition: nil,
+          issues: [Issue.new(severity: :error, message: "failed to load scene: #{e.message}")]
+        )
+      end
+
+      private
+
+      def load_definition
+        definition = @loader.call(@scene_file)
+        @shader_resolver.resolve(definition: definition, scene_file: @scene_file)
+      end
+
+      def validate_definition(definition)
+        issues = []
+        scenes = Array(definition[:scenes])
+        validate_scenes(scenes, issues)
+        names = scene_names(scenes)
+        validate_transitions(Array(definition[:transitions]), names, issues)
+        validate_key_mappings(Array(definition[:key_mappings]), names, issues)
+        issues
+      end
+
+      def validate_scenes(scenes, issues)
+        issues << error("no scenes defined") if scenes.empty?
+        duplicate_values(scenes.filter_map { |scene| scene[:name]&.to_sym }).each do |name|
+          issues << error("duplicate scene name: #{name}")
+        end
+
+        scenes.each do |scene|
+          scene_name = scene[:name] || "(unnamed)"
+          layers = Array(scene[:layers])
+          issues << warn("scene #{scene_name} has no layers; frontend will render the default geometry") if layers.empty?
+          validate_layers(layers, scene_name, issues)
+        end
+      end
+
+      def validate_layers(layers, scene_name, issues)
+        duplicate_values(layers.filter_map { |layer| layer[:name]&.to_sym }).each do |name|
+          issues << warn("scene #{scene_name} has duplicate layer name: #{name}")
+        end
+
+        layers.each do |layer|
+          validate_layer(layer, scene_name, issues)
+        end
+      end
+
+      def validate_layer(layer, scene_name, issues)
+        layer_name = layer[:name] || "(unnamed)"
+        type = layer[:type]&.to_sym || :geometry
+        unless supported_layer_types.include?(type)
+          issues << error("scene #{scene_name} layer #{layer_name} has unsupported type: #{type}")
+        end
+
+        shader = layer[:shader]&.to_sym
+        if shader && !BUILTIN_SHADERS.include?(shader)
+          issues << error("scene #{scene_name} layer #{layer_name} uses unknown shader: #{shader}")
+        end
+
+        glsl_source = layer[:glsl_source]
+        issues << warn("scene #{scene_name} layer #{layer_name} has an empty GLSL file") if layer[:glsl] && glsl_source.to_s.empty?
+        validate_blend_mode(layer, scene_name, layer_name, issues)
+        validate_layer_effects(layer, scene_name, layer_name, issues)
+        validate_mappings(Array(layer[:mappings]), scene_name, layer_name, issues)
+      end
+
+      def validate_blend_mode(layer, scene_name, layer_name, issues)
+        blend = layer.dig(:params, :blend)
+        return unless blend
+        return if SUPPORTED_BLEND_MODES.include?(blend.to_sym)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported blend mode: #{blend}")
+      end
+
+      def validate_layer_effects(layer, scene_name, layer_name, issues)
+        params = layer[:params] || {}
+        validate_effect_name(params[:effect], SUPPORTED_POST_EFFECTS, "effect", scene_name, layer_name, issues)
+        validate_effect_name(params[:vj_effect], SUPPORTED_VJ_EFFECTS, "vj_effect", scene_name, layer_name, issues)
+      end
+
+      def supported_layer_types
+        Vizcore::LayerCatalog.supported_types
+      end
+
+      def validate_effect_name(value, supported, field, scene_name, layer_name, issues)
+        return unless value
+        return if supported.include?(value.to_sym)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported #{field}: #{value}")
+      end
+
+      def validate_mappings(mappings, scene_name, layer_name, issues)
+        mappings.each do |mapping|
+          source = Hash(mapping[:source] || {})
+          kind = source[:kind]&.to_sym
+          issues << error("scene #{scene_name} layer #{layer_name} has mapping without source kind") unless kind
+          next unless kind
+
+          validate_mapping_source(kind, source, scene_name, layer_name, issues)
+          issues << error("scene #{scene_name} layer #{layer_name} has mapping without target") unless mapping[:target]
+          validate_transform(Hash(mapping[:transform] || {}), scene_name, layer_name, mapping[:target], issues)
+        end
+      end
+
+      def validate_mapping_source(kind, source, scene_name, layer_name, issues)
+        unless MAPPING_SOURCE_KINDS.include?(kind)
+          issues << error("scene #{scene_name} layer #{layer_name} uses unsupported mapping source: #{kind}")
+        end
+        validate_frequency_band(source, scene_name, layer_name, issues) if kind == :frequency_band
+        validate_onset_band(source, scene_name, layer_name, issues) if kind == :onset
+      end
+
+      def validate_frequency_band(source, scene_name, layer_name, issues)
+        band = source[:band]&.to_sym
+        return if FREQUENCY_BANDS.include?(band)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported frequency band: #{band.inspect}")
+      end
+
+      def validate_onset_band(source, scene_name, layer_name, issues)
+        return unless source.key?(:band)
+
+        band = source[:band]&.to_sym
+        return if FREQUENCY_BANDS.include?(band)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported onset band: #{band.inspect}")
+      end
+
+      def validate_transform(transform, scene_name, layer_name, target, issues)
+        return unless transform.key?(:min) && transform.key?(:max)
+        return unless Float(transform[:min]) > Float(transform[:max])
+
+        issues << error("scene #{scene_name} layer #{layer_name} mapping #{target} has min greater than max")
+      rescue ArgumentError, TypeError
+        issues << error("scene #{scene_name} layer #{layer_name} mapping #{target} has non-numeric min/max")
+      end
+
+      def validate_transitions(transitions, names, issues)
+        transitions.each do |transition|
+          from = transition[:from]&.to_sym
+          to = transition[:to]&.to_sym
+          issues << error("transition has unknown source scene: #{from}") if from && !names.include?(from)
+          issues << error("transition has unknown target scene: #{to}") if to && !names.include?(to)
+          unless transition[:trigger].respond_to?(:call)
+            issues << warn("transition #{from || '?'} -> #{to || '?'} has no trigger block")
+          end
+        end
+      end
+
+      def validate_key_mappings(mappings, names, issues)
+        mappings.each do |mapping|
+          key = mapping[:key] || mapping["key"]
+          action = mapping[:action] || mapping["action"]
+          issues << error("key mapping has empty key") if key.to_s.strip.empty?
+          validate_key_action(action.is_a?(Hash) ? action : {}, names, key, issues)
+        end
+      end
+
+      def validate_key_action(action, names, key, issues)
+        type = (action[:type] || action["type"]).to_s.to_sym
+        case type
+        when :switch_scene
+          scene = action[:scene] || action["scene"]
+          scene_name = scene&.to_sym
+          issues << error("key #{key} switches to unknown scene: #{scene}") unless scene_name && names.include?(scene_name)
+        when :live_control
+          control = (action[:control] || action["control"]).to_s.to_sym
+          issues << error("key #{key} uses unsupported live control: #{control}") unless %i[blackout freeze].include?(control)
+        else
+          issues << error("key #{key} has unsupported action: #{type}")
+        end
+      end
+
+      def scene_names(scenes)
+        scenes.filter_map { |scene| scene[:name]&.to_sym }.to_set
+      end
+
+      def duplicate_values(values)
+        counts = Hash.new(0)
+        values.each { |value| counts[value] += 1 }
+        counts.select { |_value, count| count > 1 }.keys
+      end
+
+      def error(message)
+        Issue.new(severity: :error, message: message)
+      end
+
+      def warn(message)
+        Issue.new(severity: :warn, message: message)
+      end
+    end
+  end
+end

data/lib/vizcore/cli/shader_template.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Vizcore
+  module CLISupport
+    # Writes starter GLSL ES fragment shaders for custom shader layers.
+    class ShaderTemplate
+      TEMPLATE = <<~GLSL
+        #version 300 es
+        precision highp float;
+
+        uniform vec2 u_resolution;
+        uniform float u_time;
+        uniform float u_amplitude;
+        uniform float u_bass;
+        uniform float u_mid;
+        uniform float u_high;
+        uniform float u_beat;
+        uniform float u_beat_pulse;
+        uniform float u_onset;
+        uniform float u_kick;
+        uniform float u_bpm;
+        uniform float u_fft[32];
+        uniform float u_fft_size;
+
+        out vec4 outColor;
+
+        void main() {
+          vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+          float wave = 0.5 + 0.5 * sin((uv.x + u_time * 0.12) * 12.0 + u_bass * 4.0);
+          vec3 color = mix(vec3(0.02, 0.06, 0.12), vec3(0.1, 0.75, 0.95), wave);
+          color += vec3(0.95, 0.16, 0.32) * (u_beat_pulse * 0.35 + u_onset * 0.2 + u_kick * 0.25 + u_high * 0.2);
+          color *= 0.35 + u_amplitude * 1.8;
+          outColor = vec4(color, 1.0);
+        }
+      GLSL
+
+      # @param name [String]
+      # @return [String]
+      def self.default_path(name)
+        "shaders/#{safe_name(name)}.frag"
+      end
+
+      # @param name [String]
+      # @return [String]
+      def self.safe_name(name)
+        raw_name = name.to_s.strip.sub(/\.frag\z/i, "")
+        safe = raw_name.gsub(/[^a-zA-Z0-9_-]+/, "_").gsub(/\A_+|_+\z/, "")
+        raise ArgumentError, "shader name is required" if safe.empty?
+
+        safe
+      end
+
+      # @param path [String, Pathname]
+      # @return [Pathname]
+      def write(path)
+        destination = Pathname(path)
+        raise ArgumentError, "Shader file already exists: #{destination}" if destination.exist?
+
+        FileUtils.mkdir_p(destination.dirname)
+        destination.write(TEMPLATE)
+        destination
+      end
+    end
+  end
+end

data/lib/vizcore/cli/shader_uniform_docs.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module CLISupport
+    # Produces the custom GLSL uniform reference used by CLI and docs.
+    class ShaderUniformDocs
+      Uniform = Struct.new(:name, :type, :description, keyword_init: true)
+
+      UNIFORMS = [
+        Uniform.new(name: "u_resolution", type: "vec2", description: "Canvas size in pixels as width and height."),
+        Uniform.new(name: "u_time", type: "float", description: "Renderer time in seconds."),
+        Uniform.new(name: "u_amplitude", type: "float", description: "Normalized RMS amplitude, usually 0.0..1.0."),
+        Uniform.new(name: "u_bass", type: "float", description: "Low-frequency band level."),
+        Uniform.new(name: "u_mid", type: "float", description: "Mid-frequency band level."),
+        Uniform.new(name: "u_high", type: "float", description: "High-frequency band level."),
+        Uniform.new(name: "u_beat", type: "float", description: "1.0 on detected beat frames, otherwise 0.0."),
+        Uniform.new(name: "u_beat_pulse", type: "float", description: "Decaying beat pulse after detection."),
+        Uniform.new(name: "u_onset", type: "float", description: "Positive amplitude rise since the previous active frame."),
+        Uniform.new(name: "u_sub_onset", type: "float", description: "Positive sub-band rise since the previous active frame."),
+        Uniform.new(name: "u_low_onset", type: "float", description: "Positive low-band rise since the previous active frame."),
+        Uniform.new(name: "u_mid_onset", type: "float", description: "Positive mid-band rise since the previous active frame."),
+        Uniform.new(name: "u_high_onset", type: "float", description: "Positive high-band rise since the previous active frame."),
+        Uniform.new(name: "u_kick", type: "float", description: "Low-band percussive confidence derived from band level and onset."),
+        Uniform.new(name: "u_snare", type: "float", description: "Mid-band percussive confidence derived from band level and onset."),
+        Uniform.new(name: "u_hihat", type: "float", description: "High-band percussive confidence derived from band level and onset."),
+        Uniform.new(name: "u_bpm", type: "float", description: "Current BPM estimate, or 0.0 when unavailable."),
+        Uniform.new(name: "u_fft[32]", type: "float[]", description: "Normalized FFT preview bins."),
+        Uniform.new(name: "u_fft_size", type: "float", description: "Number of populated FFT preview bins."),
+        Uniform.new(name: "u_visual_gain", type: "float", description: "Browser visual gain control value."),
+        Uniform.new(name: "u_bass_boost", type: "float", description: "Browser bass boost control value."),
+        Uniform.new(name: "u_wobble_amount", type: "float", description: "Browser wobble amount control value."),
+        Uniform.new(name: "u_param_<name>", type: "float", description: "Numeric layer param or mapped DSL target."),
+        Uniform.new(name: "u_global_<name>", type: "float", description: "Numeric runtime global from DSL or MIDI set.")
+      ].freeze
+
+      # @return [Array<String>]
+      def lines
+        [
+          "# Vizcore Shader Uniforms",
+          "",
+          "Custom fragment shaders use GLSL ES 3.00 and receive these uniforms:",
+          "",
+          "| Uniform | Type | Description |",
+          "| --- | --- | --- |",
+          *UNIFORMS.map { |uniform| "| `#{uniform.name}` | `#{uniform.type}` | #{uniform.description} |" },
+          "",
+          "Layer params are exposed as `u_param_<name>` after non-word characters are converted to underscores.",
+          "For compatibility, a mapped target like `:param_intensity` is also exposed as `u_param_intensity`.",
+          "Runtime globals are exposed as `u_global_<name>`; `:global_intensity` becomes `u_global_intensity`."
+        ]
+      end
+    end
+  end
+end