vizcore 1.0.0 → 1.2.0

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

data/lib/vizcore/renderer/scene_frame_source.rb

@@ -8,20 +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
 
@@ -29,13 +49,29 @@ module Vizcore
       def capture
         ensure_started!
 
-        audio = @pipeline.call(@input_manager.capture_frame(@capture_size))
-        layers = Vizcore::DSL::MappingResolver.new.resolve_layers(scene_layers: @scene[:layers], audio: audio)
+        audio = if feature_replay?
+                  @pipeline.call
+                else
+                  @pipeline.call(@input_manager.capture_frame(@capture_size))
+                end
+        @frame_count += 1
+        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
 
@@ -50,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
@@ -57,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,
@@ -65,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,
@@ -78,16 +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 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
@@ -110,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