vizcore 1.1.0 → 1.2.0

data/lib/vizcore/dsl/transition_controller.rb

@@ -8,7 +8,9 @@ module Vizcore
 
       # @param scenes [Array<Hash>]
       # @param transitions [Array<Hash>]
-      def initialize(scenes:, transitions:)
+      # @param error_reporter [#call, nil]
+      def initialize(scenes:, transitions:, error_reporter: nil)
+        @error_reporter = error_reporter || ->(_message) {}
         update(scenes: scenes, transitions: transitions)
       end
 
@@ -23,11 +25,12 @@ module Vizcore
       # @param scene_name [String, Symbol]
       # @param audio [Hash]
       # @param frame_count [Integer]
+      # @param elapsed_seconds [Numeric, nil]
       # @return [Hash, nil] transition payload when condition matches
-      def next_transition(scene_name:, audio:, frame_count: 0)
+      def next_transition(scene_name:, audio:, frame_count: 0, elapsed_seconds: nil)
         current = scene_name.to_sym
         transition = @transitions.find do |entry|
-          entry[:from] == current && trigger_match?(entry[:trigger], audio, frame_count)
+          entry[:from] == current && trigger_match?(entry, audio, frame_count, elapsed_seconds)
         end
         return nil unless transition
 
@@ -73,14 +76,24 @@ module Vizcore
         end
       end
 
-      def trigger_match?(trigger, audio, frame_count)
+      def trigger_match?(transition, audio, frame_count, elapsed_seconds)
+        trigger = transition[:trigger]
         return false unless trigger.respond_to?(:call)
 
-        TriggerContext.new(audio, frame_count: frame_count).instance_exec(&trigger)
-      rescue StandardError
+        TriggerContext.new(audio, frame_count: frame_count, elapsed_seconds: elapsed_seconds).instance_exec(&trigger)
+      rescue StandardError => e
+        report_trigger_error(transition, e)
         false
       end
 
+      def report_trigger_error(transition, error)
+        @error_reporter.call(
+          "transition trigger failed: #{transition[:from]} -> #{transition[:to]} (#{error.class}: #{error.message})"
+        )
+      rescue StandardError
+        nil
+      end
+
       def symbolize_hash(value)
         Hash(value).each_with_object({}) do |(key, entry), output|
           output[key.to_sym] = entry
@@ -90,16 +103,7 @@ module Vizcore
       end
 
       def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, entry), output|
-            output[key] = deep_dup(entry)
-          end
-        when Array
-          value.map { |entry| deep_dup(entry) }
-        else
-          value
-        end
+        Vizcore::DeepCopy.copy(value)
       end
 
       # Runtime DSL context exposed to transition trigger blocks.
@@ -107,14 +111,18 @@ module Vizcore
       class TriggerContext
         # @param audio [Hash]
         # @param frame_count [Integer]
-        def initialize(audio, frame_count:)
+        # @param elapsed_seconds [Numeric, nil]
+        def initialize(audio, frame_count:, elapsed_seconds: nil)
           @audio = symbolize_hash(audio)
           @bands = symbolize_hash(@audio[:bands])
+          @band_peaks = symbolize_hash(@audio[:band_peaks])
           @onsets = symbolize_hash(@audio[:onsets])
           @drums = symbolize_hash(@audio[:drums])
           @frame_count = Integer(frame_count)
+          @elapsed_seconds = normalize_elapsed_seconds(elapsed_seconds)
         rescue StandardError
           @frame_count = 0
+          @elapsed_seconds = nil
         end
 
         # @return [Float]
@@ -122,42 +130,83 @@ module Vizcore
           @audio[:amplitude].to_f
         end
 
+        # @return [Float]
+        def peak
+          @audio[:peak].to_f
+        end
+
         # @param name [Symbol, String]
         # @return [Float]
         def frequency_band(name)
           @bands[name.to_sym].to_f
         end
 
+        # @param name [Symbol, String]
+        # @return [Float]
+        def frequency_band_peak(name)
+          @band_peaks[name.to_sym].to_f
+        end
+
         # @return [Float]
         def sub
           frequency_band(:sub)
         end
 
+        # @return [Float]
+        def sub_peak
+          frequency_band_peak(:sub)
+        end
+
         # @return [Float]
         def low
           frequency_band(:low)
         end
 
+        # @return [Float]
+        def low_peak
+          frequency_band_peak(:low)
+        end
+
         # @return [Float]
         def bass
           frequency_band(:low)
         end
 
+        # @return [Float]
+        def bass_peak
+          frequency_band_peak(:low)
+        end
+
         # @return [Float]
         def mid
           frequency_band(:mid)
         end
 
+        # @return [Float]
+        def mid_peak
+          frequency_band_peak(:mid)
+        end
+
         # @return [Float]
         def high
           frequency_band(:high)
         end
 
+        # @return [Float]
+        def high_peak
+          frequency_band_peak(:high)
+        end
+
         # @return [Float]
         def treble
           frequency_band(:high)
         end
 
+        # @return [Float]
+        def treble_peak
+          frequency_band_peak(:high)
+        end
+
         # @return [Array<Float>]
         def fft_spectrum
           Array(@audio[:fft])
@@ -213,23 +262,113 @@ module Vizcore
           0
         end
 
+        # @return [Float]
+        def beat_phase
+          @audio[:beat_phase].to_f
+        end
+
+        # @return [Boolean]
+        def beat_2
+          !!@audio[:beat_2]
+        end
+
+        # @return [Boolean]
+        def beat_4
+          !!@audio[:beat_4]
+        end
+
+        # @return [Boolean]
+        def beat_8
+          !!@audio[:beat_8]
+        end
+
+        # @return [Boolean]
+        def beat_triplet
+          !!@audio[:beat_triplet]
+        end
+
+        # @return [Boolean]
+        def triplet
+          beat_triplet
+        end
+
+        # @return [Float]
+        def bar_phase
+          @audio[:bar_phase].to_f
+        end
+
+        # @return [Integer]
+        def bar_count
+          Integer(@audio[:bar_count] || 0)
+        rescue StandardError
+          0
+        end
+
+        # @return [Integer]
+        def phrase_count
+          Integer(@audio[:phrase_count] || 0)
+        rescue StandardError
+          0
+        end
+
         # @return [Float]
         def bpm
           @audio[:bpm].to_f
         end
 
+        # @return [Float]
+        def bpm_confidence
+          @audio[:bpm_confidence].to_f
+        end
+
+        # @return [Float]
+        def spectral_centroid
+          @audio[:spectral_centroid].to_f
+        end
+
+        # @return [Float]
+        def spectral_rolloff
+          @audio[:spectral_rolloff].to_f
+        end
+
+        # @return [Float]
+        def spectral_flatness
+          @audio[:spectral_flatness].to_f
+        end
+
+        # @return [Float]
+        def spectral_flux
+          @audio[:spectral_flux].to_f
+        end
+
+        # @return [Float]
+        def zero_crossing_rate
+          @audio[:zero_crossing_rate].to_f
+        end
+
         # @return [Integer]
         def frame_count
           @frame_count
         end
 
-        # @return [Float] scene-local elapsed seconds at the default runtime frame rate
+        # @return [Float] scene-local elapsed seconds
         def seconds
+          return @elapsed_seconds if @elapsed_seconds
+
           @frame_count / DEFAULT_FRAME_RATE
         end
 
         private
 
+        def normalize_elapsed_seconds(value)
+          return nil if value.nil?
+
+          numeric = Float(value)
+          numeric.finite? ? numeric : nil
+        rescue StandardError
+          nil
+        end
+
         def symbolize_hash(value)
           Hash(value).each_with_object({}) do |(key, entry), output|
             output[key.to_sym] = entry

data/lib/vizcore/dsl.rb

@@ -6,11 +6,13 @@ module Vizcore
   end
 end
 
+require_relative "deep_copy"
 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/mapping_preset_builder"
 require_relative "dsl/style_builder"
 require_relative "dsl/layer_builder"
 require_relative "dsl/scene_builder"

data/lib/vizcore/layer_catalog.rb

@@ -19,6 +19,7 @@ module Vizcore
       opacity: "Float",
       blend: "Symbol",
       effect: "Symbol",
+      post_effects: "Array<Symbol>",
       effect_intensity: "Float",
       vj_effect: "Symbol",
       palette: "Array<String>",

data/lib/vizcore/plugin_asset_policy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rack"
+
+module Vizcore
+  # Validates browser-side plugin assets before they are served by the runtime.
+  class PluginAssetPolicy
+    ALLOWED_EXTENSIONS = %w[.js .mjs].freeze
+    ALLOWED_MIME_TYPES = %w[text/javascript application/javascript].freeze
+
+    # @param path [String, Pathname]
+    # @param root [String, Pathname, nil] optional sandbox root
+    # @return [Pathname]
+    def self.validate!(path, root: nil)
+      asset_path = Pathname.new(path).expand_path
+      root_path = root ? Pathname.new(root).expand_path : nil
+
+      if root_path && !inside_root?(asset_path, root_path)
+        raise ArgumentError, "Plugin asset must stay inside #{root_path}: #{asset_path}"
+      end
+
+      unless ALLOWED_EXTENSIONS.include?(asset_path.extname.downcase)
+        raise ArgumentError, "Unsupported plugin asset extension: #{asset_path.extname}. Use one of: #{ALLOWED_EXTENSIONS.join(', ')}"
+      end
+
+      extname = asset_path.extname.downcase
+      mime_type = Rack::Mime.mime_type(extname, "application/octet-stream")
+      mime_type = case extname
+      when ".mjs"
+        mime_type == "application/octet-stream" ? "application/javascript" : mime_type
+      when ".js"
+        mime_type == "application/octet-stream" ? "text/javascript" : mime_type
+      else
+        mime_type
+      end
+      unless ALLOWED_MIME_TYPES.include?(mime_type)
+        raise ArgumentError, "Unsupported plugin asset MIME type: #{mime_type}. Use one of: #{ALLOWED_MIME_TYPES.join(", ")}"
+      end
+
+      asset_path
+    end
+
+    # @param path [Pathname]
+    # @param root [Pathname]
+    # @return [Boolean]
+    def self.inside_root?(path, root)
+      relative = path.relative_path_from(root)
+      !relative.each_filename.first&.start_with?("..")
+    rescue ArgumentError
+      false
+    end
+    private_class_method :inside_root?
+  end
+end

data/lib/vizcore/project_manifest.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require "yaml"
+require_relative "plugin_asset_policy"
 
 module Vizcore
   # Reads a project-level manifest such as vizcore.yml.
@@ -36,6 +37,8 @@ module Vizcore
         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"),
+        scene_switch_effect: value_at(data, "scene_switch_effect"),
+        scene_switch_effect_duration: value_at(data, "scene_switch_effect_duration"),
         plugin_assets: plugin_assets(profile: profile)
       }.compact
     end
@@ -49,7 +52,8 @@ module Vizcore
     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
+      manifest_assets = assets.filter_map { |entry| validate_plugin_asset_path(expand_path(entry)) }
+      (entries.filter_map { |entry| plugin_asset_path(entry) } + manifest_assets).uniq
     end
 
     # @return [Array<String>] configured profile names
@@ -124,7 +128,7 @@ module Vizcore
     def plugin_asset_path(entry)
       return nil unless entry.is_a?(Hash)
 
-      expand_path(entry["asset"] || entry[:asset] || entry["frontend"] || entry[:frontend])
+      validate_plugin_asset_path(expand_path(entry["asset"] || entry[:asset] || entry["frontend"] || entry[:frontend]))
     end
 
     def expand_path(value)
@@ -135,6 +139,12 @@ module Vizcore
       path_value.absolute? ? path_value : @root.join(path_value).expand_path
     end
 
+    def validate_plugin_asset_path(path)
+      return nil unless path
+
+      Vizcore::PluginAssetPolicy.validate!(path, root: @root)
+    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

data/lib/vizcore/renderer/render_sequence.rb

@@ -20,12 +20,39 @@ module Vizcore
         fps: DEFAULT_FRAME_RATE,
         width: SnapshotRenderer::DEFAULT_WIDTH,
         height: SnapshotRenderer::DEFAULT_HEIGHT,
+        duration: nil,
+        from_frame: 1,
+        to_frame: nil,
+        resume: false,
+        seed: nil,
+        transparent: false,
+        video_codec: nil,
+        video_bitrate: nil,
+        video_crf: nil,
+        pixel_format: "yuv420p",
+        progress_reporter: nil,
         command_runner: Open3,
         ffmpeg_checker: nil
       )
         @config = config
-        @frames = normalize_frame_count(frames)
         @fps = normalize_frame_rate(fps)
+        @frames = normalize_frame_count(duration ? (Float(duration) * @fps).ceil : frames)
+        @from_frame = normalize_frame_index(from_frame, "from-frame")
+        @to_frame = normalize_optional_frame_index(to_frame, "to-frame")
+        @to_frame = @frames if @to_frame.nil?
+        raise ArgumentError, "to-frame must be greater than or equal to from-frame" if @to_frame < @from_frame
+        raise ArgumentError, "from-frame must be within rendered frame count" if @from_frame > @frames
+
+        @to_frame = [@to_frame, @frames].min
+        @output_frames = @to_frame - @from_frame + 1
+        @resume = !!resume
+        @seed = normalize_seed(seed)
+        @transparent = !!transparent
+        @video_codec = optional_string(video_codec, "video codec")
+        @video_bitrate = optional_string(video_bitrate, "video bitrate")
+        @video_crf = optional_string(video_crf, "video crf")
+        @pixel_format = optional_string(pixel_format, "pixel format") || "yuv420p"
+        @progress_reporter = progress_reporter
         @width = width
         @height = height
         @command_runner = command_runner
@@ -56,32 +83,44 @@ module Vizcore
         metadata = nil
         Dir.mktmpdir("vizcore-render-frames") do |dir|
           frame_dir = Pathname.new(dir)
-          metadata = render_frames(frame_dir)
+          metadata = render_frames(frame_dir, preserve_frame_numbers: false)
           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)
+      def render_frames(output_dir, preserve_frame_numbers: true)
+        source = SceneFrameSource.new(config: @config, frame_rate: @fps, seed: @seed)
         source.start
-        renderer = SnapshotRenderer.new(width: @width, height: @height)
+        renderer = SnapshotRenderer.new(width: @width, height: @height, transparent: @transparent)
         scene_name = nil
 
         @frames.times do |index|
+          frame_number = index + 1
+          break if frame_number > @to_frame
+
           frame = source.capture
           scene_name ||= frame.fetch(:scene_name)
+          next if frame_number < @from_frame || frame_number > @to_frame
+          output_frame_number = preserve_frame_numbers ? frame_number : frame_number - @from_frame + 1
+          next if @resume && frame_path(output_dir, output_frame_number).file?
+
           File.binwrite(
-            frame_path(output_dir, index),
+            frame_path(output_dir, output_frame_number),
             renderer.render(scene: frame.fetch(:scene), audio: frame.fetch(:audio))
           )
+          emit_progress(frame_number: frame_number, output_frame_number: output_frame_number)
         end
 
         {
-          frames: @frames,
+          frames: @output_frames,
+          total_frames: @frames,
+          from_frame: @from_frame,
+          to_frame: @to_frame,
           fps: @fps,
           width: renderer.width,
           height: renderer.height,
+          transparent: @transparent,
           scene: scene_name
         }
       ensure
@@ -92,8 +131,8 @@ module Vizcore
         %w[.mp4 .mov .webm].include?(path.extname.downcase)
       end
 
-      def frame_path(output_dir, index)
-        output_dir.join(format("frame_%05d.png", index + 1))
+      def frame_path(output_dir, frame_number)
+        output_dir.join(format("frame_%05d.png", frame_number))
       end
 
       def encode_mp4(frame_dir:, output_file:)
@@ -106,7 +145,7 @@ module Vizcore
       end
 
       def ffmpeg_command(frame_dir:, output_file:)
-        [
+        command = [
           "ffmpeg",
           "-y",
           "-framerate",
@@ -114,17 +153,37 @@ module Vizcore
           "-i",
           frame_dir.join("frame_%05d.png").to_s,
           "-vf",
-          "format=yuv420p",
+          "format=#{@pixel_format}",
           "-pix_fmt",
-          "yuv420p",
-          output_file.to_s
+          @pixel_format
         ]
+        command.concat(["-c:v", @video_codec]) if @video_codec
+        command.concat(["-b:v", @video_bitrate]) if @video_bitrate
+        command.concat(["-crf", @video_crf]) if @video_crf
+        command << output_file.to_s
+        command
       end
 
       def ffmpeg_available?
         system("ffmpeg", "-version", out: File::NULL, err: File::NULL)
       end
 
+      def emit_progress(frame_number:, output_frame_number:)
+        return unless @progress_reporter.respond_to?(:call)
+
+        @progress_reporter.call(
+          frame: frame_number,
+          output_frame: output_frame_number,
+          from_frame: @from_frame,
+          to_frame: @to_frame,
+          total_frames: @frames,
+          output_frames: @output_frames,
+          percent: ((frame_number - @from_frame + 1).to_f / @output_frames * 100).clamp(0.0, 100.0)
+        )
+      rescue StandardError
+        nil
+      end
+
       def format_frame_rate
         return @fps.to_i.to_s if @fps == @fps.to_i
 
@@ -140,6 +199,21 @@ module Vizcore
         raise ArgumentError, "frames must be a positive integer"
       end
 
+      def normalize_frame_index(value, name)
+        index = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless index.positive?
+
+        index
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{name} must be a positive integer"
+      end
+
+      def normalize_optional_frame_index(value, name)
+        return nil if value.nil?
+
+        normalize_frame_index(value, name)
+      end
+
       def normalize_frame_rate(value)
         rate = Float(value)
         raise ArgumentError, "fps must be positive" unless rate.positive?
@@ -148,6 +222,23 @@ module Vizcore
       rescue ArgumentError, TypeError
         raise ArgumentError, "fps must be a positive number"
       end
+
+      def normalize_seed(value)
+        return nil if value.nil?
+
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "seed must be an integer"
+      end
+
+      def optional_string(value, name)
+        return nil if value.nil?
+
+        normalized = value.to_s.strip
+        raise ArgumentError, "#{name} must not be empty" if normalized.empty?
+
+        normalized
+      end
     end
   end
 end