vizcore 1.1.0 → 1.2.0

data/lib/vizcore/renderer/scene_frame_source.rb

@@ -8,21 +8,40 @@ module Vizcore
   module Renderer
     # Produces analyzed scene frames for offline renderers.
     class SceneFrameSource
-      def initialize(config:, frame_rate: nil)
+      def initialize(config:, frame_rate: nil, seed: nil)
         @config = config
         @frame_rate = frame_rate
+        @seed = seed
         @shader_source_resolver = Vizcore::DSL::ShaderSourceResolver.new
       end
 
       # @return [Vizcore::Renderer::SceneFrameSource]
       def start
         @definition = resolve_shader_sources(Vizcore::DSL::Engine.load_file(@config.scene_file.to_s))
-        @scene = first_scene(@definition)
-        @input_manager = build_input_manager
-        @input_manager.start
-        @capture_size = capture_size
-        @pipeline = build_pipeline
+        apply_seed!
+        @source_started_at = monotonic_seconds
+        scenes = Array(@definition[:scenes])
+        initial_timeline_entry = initial_timeline_entry(@definition)
+        @scene = resolve_initial_scene(scenes, initial_timeline_entry)
+        @transition_controller = Vizcore::DSL::TransitionController.new(
+          scenes: scenes,
+          transitions: Array(@definition[:transitions]),
+          error_reporter: lambda do |message|
+            report_transition_error(message)
+          end
+        )
+        @mapping_resolver = Vizcore::DSL::MappingResolver.new
+        unless feature_replay?
+          @input_manager = build_input_manager
+          @input_manager.start
+          @capture_size = capture_size
+        end
+        @pipeline = replay_pipeline || build_pipeline
         @frame_count = 0
+        @scene_frame_base = 0
+        @scene_elapsed_base = 0.0
+        @scene_beat_base = 0
+        align_timeline_start(entry: initial_timeline_entry)
         self
       end
 
@@ -30,19 +49,29 @@ module Vizcore
       def capture
         ensure_started!
 
-        audio = @pipeline.call(@input_manager.capture_frame(@capture_size))
+        audio = if feature_replay?
+                  @pipeline.call
+                else
+                  @pipeline.call(@input_manager.capture_frame(@capture_size))
+                end
         @frame_count += 1
-        layers = Vizcore::DSL::MappingResolver.new.resolve_layers(
-          scene_layers: @scene[:layers],
+        scene = @scene
+        layers = @mapping_resolver.resolve_layers(
+          scene_layers: scene[:layers],
           audio: audio,
           time: frame_time,
           frame: @frame_count
         )
+        evaluate_transition(audio)
 
         {
-          scene: { name: @scene[:name], layers: layers },
+          scene: {
+            schema_version: Vizcore::Renderer::SceneSerializer::SCENE_SCHEMA_VERSION,
+            name: scene[:name],
+            layers: layers
+          },
           audio: audio,
-          scene_name: @scene[:name].to_s
+          scene_name: scene[:name].to_s
         }
       end
 
@@ -57,6 +86,15 @@ module Vizcore
         @shader_source_resolver.resolve(definition: definition, scene_file: @config.scene_file.to_s)
       end
 
+      def apply_seed!
+        seed = @seed || @definition[:seed]
+        return if seed.nil?
+
+        Kernel.srand(Integer(seed))
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "render seed must be an integer"
+      end
+
       def first_scene(definition)
         scene = Array(definition[:scenes]).first
         return scene if scene
@@ -64,6 +102,95 @@ module Vizcore
         { name: @config.scene_file.basename(".rb").to_sym, layers: [] }
       end
 
+      def initial_timeline_entry(definition)
+        timelines = Array(definition[:timelines])
+        timelines.each do |timeline|
+          first_entry = Array(timeline).first
+          return first_entry if first_entry
+        end
+
+        nil
+      end
+
+      def resolve_initial_scene(scenes, initial_timeline_entry)
+        scene_name = initial_timeline_entry&.dig(:scene)
+        scene = scenes.find { |entry| entry[:name].to_s == scene_name.to_s } if scene_name
+        scene || first_scene({ scenes: scenes })
+      end
+
+      def align_timeline_start(entry:)
+        return unless entry
+
+        unit = entry[:unit].to_s
+        start_position = Float(entry[:at] || 0.0)
+        return unless start_position.positive?
+
+        @scene_elapsed_base = start_position if unit == "seconds"
+        @scene_beat_base = Integer(start_position) if unit == "beats"
+      rescue StandardError
+        nil
+      end
+
+      def evaluate_transition(audio)
+        transition = @transition_controller.next_transition(
+          scene_name: @scene[:name],
+          audio: transition_audio(audio),
+          frame_count: scene_frame_count,
+          elapsed_seconds: scene_elapsed_seconds
+        )
+        return unless transition
+
+        @scene = transition.fetch(:scene)
+        reset_scene_counters(audio)
+      end
+
+      def transition_audio(audio)
+        audio_hash = Hash(audio)
+        scene_count = scene_beat_count(audio_hash)
+        audio_hash.merge(scene_musical_counts(audio_hash, beat_count: scene_count))
+      rescue StandardError
+        { beat_count: 0 }
+      end
+
+      def scene_frame_count
+        [@frame_count - @scene_frame_base, 0].max
+      end
+
+      def scene_elapsed_seconds
+        [frame_time - @scene_elapsed_base, 0.0].max
+      end
+
+      def scene_beat_count(audio)
+        global_beat_count = Integer(Hash(audio)[:beat_count] || 0)
+        [global_beat_count - @scene_beat_base, 0].max
+      rescue StandardError
+        0
+      end
+
+      def reset_scene_counters(audio)
+        audio_hash = Hash(audio)
+        @scene_frame_base = @frame_count
+        @scene_elapsed_base = frame_time
+        @scene_beat_base = Integer(audio_hash[:beat_count] || 0) - (audio_hash[:beat] ? 1 : 0)
+      rescue StandardError
+        @scene_frame_base = @frame_count
+        @scene_elapsed_base = frame_time
+        @scene_beat_base = 0
+      end
+
+      def scene_musical_counts(audio, beat_count:)
+        beat_index = beat_count.positive? ? beat_count - 1 : 0
+        beat_phase = Float(audio[:beat_phase] || audio["beat_phase"] || 0.0).clamp(0.0, 1.0)
+        {
+          beat_count: beat_count,
+          bar_phase: (((beat_index % 4) + beat_phase) / 4.0).clamp(0.0, 1.0),
+          bar_count: beat_index / 4,
+          phrase_count: beat_index / 32
+        }
+      rescue StandardError
+        { beat_count: beat_count, bar_phase: 0.0, bar_count: 0, phrase_count: 0 }
+      end
+
       def build_input_manager
         Vizcore::Audio::InputManager.new(
           source: @config.audio_source,
@@ -72,12 +199,26 @@ module Vizcore
         )
       end
 
+      def replay_pipeline
+        return unless feature_replay?
+
+        Vizcore::Analysis::FeatureReplay.new(path: @config.feature_file)
+      end
+
+      def feature_replay?
+        !!@config.feature_file
+      end
+
       def capture_size
         return @input_manager.frame_size unless @frame_rate
 
         @input_manager.realtime_capture_size(@frame_rate)
       end
 
+      def report_transition_error(message)
+        warn(message)
+      end
+
       def build_pipeline
         Vizcore::Analysis::Pipeline.new(
           sample_rate: @input_manager.sample_rate,
@@ -85,22 +226,46 @@ module Vizcore
           noise_gate: @config.noise_gate,
           audio_normalize: audio_normalize_settings,
           bpm: bpm_setting,
-          bpm_lock: bpm_lock_setting
+          bpm_lock: bpm_lock_setting,
+          onset_sensitivity: analysis_setting(:onset_sensitivity, 1.0),
+          fft_preview_bins: analysis_setting(:fft_bins, Vizcore::Analysis::Pipeline::DEFAULT_FFT_PREVIEW_BINS),
+          peak_hold_frames: analysis_setting(:peak_hold_frames, 0),
+          silence_reset_frames: analysis_setting(:silence_reset_frames, Vizcore::Analysis::Pipeline::SILENCE_RESET_FRAMES)
         )
       end
 
       def frame_time
-        return 0.0 unless @frame_rate
+        return monotonic_elapsed unless @frame_rate
 
         (@frame_count - 1).fdiv(@frame_rate)
       end
 
+      def monotonic_elapsed
+        now = monotonic_seconds
+        return 0.0 unless @source_started_at
+
+        elapsed = now - @source_started_at
+        elapsed.positive? ? elapsed : 0.0
+      rescue StandardError
+        0.0
+      end
+
+      def monotonic_seconds
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
       def audio_normalize_settings
         Hash(@definition[:analysis] || {})[:audio_normalize]
       rescue StandardError
         nil
       end
 
+      def analysis_setting(key, fallback)
+        Hash(@definition[:analysis] || {}).fetch(key, fallback)
+      rescue StandardError
+        fallback
+      end
+
       def bpm_setting
         @config.bpm || Hash(@definition[:analysis] || {})[:bpm]
       rescue StandardError
@@ -123,7 +288,7 @@ module Vizcore
       end
 
       def ensure_started!
-        return if @input_manager && @pipeline && @scene
+        return if @pipeline && @scene && (!feature_replay? || @input_manager.nil? || @input_manager.running?)
 
         raise RuntimeError, "scene frame source has not been started"
       end

data/lib/vizcore/renderer/scene_serializer.rb

@@ -4,6 +4,11 @@ module Vizcore
   module Renderer
     # Serializes analysis and scene state into transport payloads.
     class SceneSerializer
+      SCENE_SCHEMA_VERSION = "vizcore.scene.v1"
+      FRAME_SCHEMA_VERSION = "vizcore.frame.v1"
+      LAYER_SCHEMA_VERSION = "vizcore.layer.v1"
+      MAPPING_SCHEMA_VERSION = "vizcore.mapping.v1"
+
       # @param timestamp [Numeric]
       # @param audio [Hash]
       # @param scene_name [String, Symbol]
@@ -13,6 +18,7 @@ module Vizcore
       # @return [Hash]
       def audio_frame(timestamp:, audio:, scene_name:, scene_layers:, transition: nil, metrics: nil)
         frame = {
+          schema_version: FRAME_SCHEMA_VERSION,
           timestamp: Float(timestamp),
           audio: serialize_audio(audio),
           scene: serialize_scene(scene_name, scene_layers),
@@ -26,12 +32,15 @@ module Vizcore
 
       def serialize_audio(audio)
         bands = symbolize_hash(audio[:bands])
+        band_peaks = { sub: 0.0, low: 0.0, mid: 0.0, high: 0.0 }.merge(symbolize_hash(audio[:band_peaks]))
         onsets = { sub: 0.0, low: 0.0, mid: 0.0, high: 0.0 }.merge(symbolize_hash(audio[:onsets]))
         drums = { kick: 0.0, snare: 0.0, hihat: 0.0 }.merge(symbolize_hash(audio[:drums]))
 
         {
           amplitude: round_float(audio[:amplitude]),
+          peak: round_float(audio[:peak]),
           bands: bands.transform_values { |value| round_float(value) },
+          band_peaks: band_peaks.transform_values { |value| round_float(value) },
           fft: Array(audio[:fft]).map { |value| round_float(value) },
           onset: round_float(audio[:onset]),
           onsets: onsets.transform_values { |value| round_float(value) },
@@ -40,13 +49,28 @@ module Vizcore
           beat_confidence: round_float(audio[:beat_confidence]),
           beat_pulse: round_float(audio[:beat_pulse]),
           beat_count: Integer(audio[:beat_count] || 0),
+          beat_phase: round_float(audio[:beat_phase]),
+          beat_2: !!audio[:beat_2],
+          beat_4: !!audio[:beat_4],
+          beat_8: !!audio[:beat_8],
+          beat_triplet: !!audio[:beat_triplet],
+          bar_phase: round_float(audio[:bar_phase]),
+          bar_count: Integer(audio[:bar_count] || 0),
+          phrase_count: Integer(audio[:phrase_count] || 0),
           bpm: audio[:bpm],
+          bpm_confidence: round_float(audio[:bpm_confidence]),
+          spectral_centroid: round_float(audio[:spectral_centroid]),
+          spectral_rolloff: round_float(audio[:spectral_rolloff]),
+          spectral_flatness: round_float(audio[:spectral_flatness]),
+          spectral_flux: round_float(audio[:spectral_flux]),
+          zero_crossing_rate: round_float(audio[:zero_crossing_rate]),
           peak_frequency: round_float(audio[:peak_frequency])
         }
       end
 
       def serialize_scene(scene_name, scene_layers)
         {
+          schema_version: SCENE_SCHEMA_VERSION,
           name: scene_name.to_s,
           layers: Array(scene_layers).map { |layer| serialize_layer(layer) }
         }
@@ -58,12 +82,14 @@ module Vizcore
         output = {
           name: values.fetch(:name).to_s,
           type: (values[:type] || :geometry).to_s,
+          schema_version: LAYER_SCHEMA_VERSION,
           params: symbolize_hash(values[:params])
         }
         output[:shader] = values[:shader].to_s if values[:shader]
         output[:glsl] = values[:glsl].to_s if values[:glsl]
         output[:glsl_source] = values[:glsl_source].to_s if values[:glsl_source]
         output[:param_schema] = serialize_param_schema(values[:param_schema]) if values[:param_schema]
+        output[:mappings] = serialize_mappings(values[:mappings]) unless Array(values[:mappings]).empty?
         output
       end
 
@@ -80,6 +106,18 @@ module Vizcore
         end
       end
 
+      def serialize_mappings(mappings)
+        Array(mappings).map do |mapping|
+          values = symbolize_hash(mapping)
+          {
+            schema_version: MAPPING_SCHEMA_VERSION,
+            source: values[:source],
+            target: values[:target].to_s,
+            transform: symbolize_hash(values[:transform])
+          }
+        end
+      end
+
       def serialize_metrics(metrics)
         symbolize_hash(metrics).each_with_object({}) do |(key, value), output|
           output[key] = key == :frame_id ? Integer(value) : round_float(value)

data/lib/vizcore/renderer/snapshot.rb

@@ -9,10 +9,11 @@ module Vizcore
   module Renderer
     # Builds one analyzed scene frame and writes a PNG preview.
     class Snapshot
-      def initialize(config:, width: SnapshotRenderer::DEFAULT_WIDTH, height: SnapshotRenderer::DEFAULT_HEIGHT)
+      def initialize(config:, width: SnapshotRenderer::DEFAULT_WIDTH, height: SnapshotRenderer::DEFAULT_HEIGHT, transparent: false)
         @config = config
         @width = width
         @height = height
+        @transparent = !!transparent
       end
 
       # @param out [String, Pathname]
@@ -22,14 +23,14 @@ module Vizcore
         frame_source = SceneFrameSource.new(config: @config)
         frame_source.start
         frame = frame_source.capture
-        png = SnapshotRenderer.new(width: @width, height: @height).render(
+        png = SnapshotRenderer.new(width: @width, height: @height, transparent: @transparent).render(
           scene: frame.fetch(:scene),
           audio: frame.fetch(:audio)
         )
 
         FileUtils.mkdir_p(output_path.dirname)
         File.binwrite(output_path, png)
-        { path: output_path, scene: frame.fetch(:scene_name), width: @width, height: @height }
+        { path: output_path, scene: frame.fetch(:scene_name), width: @width, height: @height, transparent: @transparent }
       ensure
         frame_source&.stop
       end

data/lib/vizcore/renderer/snapshot_renderer.rb

@@ -19,9 +19,10 @@ module Vizcore
         [250, 204, 21]
       ].freeze
 
-      def initialize(width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT)
+      def initialize(width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, transparent: false)
         @width = normalize_dimension(width)
         @height = normalize_dimension(height)
+        @transparent = !!transparent
       end
 
       attr_reader :width, :height
@@ -30,8 +31,8 @@ module Vizcore
       # @param audio [Hash]
       # @return [String] PNG bytes
       def render(scene:, audio:)
-        canvas = Canvas.new(width: width, height: height)
-        canvas.fill_gradient(background_top(audio), background_bottom(audio))
+        canvas = Canvas.new(width: width, height: height, transparent: @transparent)
+        canvas.fill_gradient(background_top(audio), background_bottom(audio)) unless @transparent
         layers = Array(scene[:layers] || scene["layers"])
         layers = [default_layer] if layers.empty?
         layers.each_with_index { |layer, index| render_layer(canvas, layer, audio, index) }
@@ -759,14 +760,115 @@ module Vizcore
       end
 
       def configured_color(params)
-        [params[:color], params["color"]].map { |value| value.to_s.strip }.find { |value| !value.empty? }
+        value = params[:color]
+        value = params["color"] unless value
+        resolved = resolve_color_value(value)
+        return resolved.to_s.strip unless resolved.to_s.strip.empty?
+
+        nil
+      end
+
+      def resolve_color_value(value)
+        return value if value.is_a?(String)
+        return resolve_gradient_color(value) if value.is_a?(Hash)
+
+        value
+      end
+
+      def resolve_gradient_color(value)
+        gradient = value[:gradient] || value["gradient"]
+        return nil unless gradient.is_a?(Hash)
+
+        colors = normalize_colors(gradient[:colors] || gradient["colors"])
+        return nil if colors.empty?
+
+        return colors[0] if colors.length == 1
+
+        position = normalize_position(gradient[:position] || gradient["position"])
+        stops = normalize_gradient_stops(gradient[:stops] || gradient["stops"], colors.length)
+
+        if stops
+          resolve_gradient_color_with_stops(colors, position, stops)
+        else
+          resolve_gradient_color_with_position(colors, position)
+        end
+      end
+
+      def normalize_gradient_stops(stops, color_count)
+        return nil unless stops
+
+        values = Array(stops).filter_map { |entry| Float(entry, exception: false) }
+        return nil if values.length != color_count
+
+        values.sort.map { |value| value.to_f.clamp(0.0, 1.0) }
+      end
+
+      def resolve_gradient_color_with_position(colors, position)
+        segment_length = 1.0 / (colors.length - 1)
+        segment = [(position / segment_length).floor, colors.length - 2].min
+        blend = (position % segment_length) / segment_length
+
+        left_color = parse_hex_color(colors[segment])
+        right_color = parse_hex_color(colors[segment + 1])
+        return colors[segment] if left_color.nil? || right_color.nil?
+
+        interpolate_hex_color(left_color, right_color, blend)
+      end
+
+      def resolve_gradient_color_with_stops(colors, position, stops)
+        index = Array.new(colors.length - 1) { |offset| offset }.index do |offset|
+          position <= stops[offset + 1]
+        end
+
+        return colors.last if index.nil?
+
+        return colors[0] if index == 0 && position <= stops[0]
+
+        left_index = [index, colors.length - 2].min
+        right_index = left_index + 1
+        start = stops[left_index]
+        stop = stops[right_index]
+        blend = ((position - start) / (stop - start)).clamp(0.0, 1.0)
+
+        left_color = parse_hex_color(colors[left_index])
+        right_color = parse_hex_color(colors[right_index])
+        return colors[left_index] if left_color.nil? || right_color.nil?
+
+        interpolate_hex_color(left_color, right_color, blend)
+      end
+
+      def normalize_colors(value)
+        Array(value).map { |entry| entry.to_s.strip }.reject(&:empty?)
+      end
+
+      def normalize_position(value)
+        position = Float(value)
+        position = 0.0 unless position.finite?
+
+        position % 1.0
+      rescue ArgumentError, TypeError
+        0.0
       end
 
       def palette_color(params, index)
         palette = Array(params[:palette] || params["palette"]).map { |color| color.to_s.strip }.reject(&:empty?)
         return nil if palette.empty?
 
-        palette[index % palette.length]
+        position = normalize_palette_position(index, palette.length)
+        return palette[0] if position.nil?
+
+        lower_index = position.floor
+        upper_index = (lower_index + 1) % palette.length
+        blend = position - lower_index
+
+        base_color = palette[lower_index]
+        return base_color unless blend.positive? && blend < 1.0
+
+        lower_rgb = parse_hex_color(base_color)
+        upper_rgb = parse_hex_color(palette[upper_index])
+        return base_color if lower_rgb.nil? || upper_rgb.nil?
+
+        interpolate_hex_color(lower_rgb, upper_rgb, blend)
       end
 
       def parse_hex_color(value)
@@ -778,6 +880,28 @@ module Vizcore
         [hex[0, 2], hex[2, 2], hex[4, 2]].map { |component| component.to_i(16) }
       end
 
+      def normalize_palette_position(value, palette_length)
+        return nil unless palette_length.positive?
+
+        numeric = Float(value)
+        return nil unless numeric.finite?
+
+        position = numeric % palette_length
+        return nil if position.nan?
+
+        position
+      rescue StandardError
+        nil
+      end
+
+      def interpolate_hex_color(left_rgb, right_rgb, blend)
+        blend = blend.to_f.clamp(0.0, 1.0)
+        rgb = left_rgb.zip(right_rgb).map do |left, right|
+          (left + (right - left) * blend).round.clamp(0, 255)
+        end
+        format("##{rgb.map { |value| format('%02x', value) }.join}")
+      end
+
       def default_layer
         { type: "geometry", name: "snapshot" }
       end
@@ -808,11 +932,12 @@ module Vizcore
 
       # Tiny RGBA canvas with alpha blending and a few primitive drawing helpers.
       class Canvas
-        def initialize(width:, height:)
+        def initialize(width:, height:, transparent: false)
           @width = width
           @height = height
           @bytes = String.new(capacity: width * height * 4, encoding: Encoding::BINARY)
-          @bytes << ([0, 0, 0, 255].pack("C4") * (width * height))
+          alpha = transparent ? 0 : 255
+          @bytes << ([0, 0, 0, alpha].pack("C4") * (width * height))
         end
 
         attr_reader :width, :height, :bytes
@@ -918,7 +1043,8 @@ module Vizcore
             current = bytes.getbyte(offset + index)
             bytes.setbyte(offset + index, interpolate(current, color[index], amount).round)
           end
-          bytes.setbyte(offset + 3, 255)
+          alpha = bytes.getbyte(offset + 3)
+          bytes.setbyte(offset + 3, [alpha + (255 - alpha) * amount, 255].min.round)
         end
 
         def set_pixel(x, y, color, alpha)

data/lib/vizcore/scene_trust.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Vizcore
+  # Builds safety warnings for Ruby scene files, which execute as normal Ruby.
+  module SceneTrust
+    module_function
+
+    # @param scene_file [String, Pathname, nil]
+    # @param project_root [String, Pathname]
+    # @return [String, nil]
+    def warning_for(scene_file, project_root: Dir.pwd)
+      return nil if scene_file.to_s.strip.empty?
+
+      path = Pathname.new(scene_file).expand_path
+      root = Pathname.new(project_root).expand_path
+      return nil if under?(path, root)
+      return nil if under?(path, Vizcore.root)
+
+      "Scene files execute Ruby code. Review #{path} before running it, or pass --trust to suppress this warning."
+    end
+
+    def under?(path, root)
+      relative = path.relative_path_from(root)
+      !relative.each_filename.first&.start_with?("..")
+    rescue ArgumentError
+      false
+    end
+  end
+end