vizcore 0.1.0 → 1.0.0

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

data/lib/vizcore/renderer/scene_frame_source.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../analysis"
+require_relative "../audio"
+require_relative "../dsl"
+
+module Vizcore
+  module Renderer
+    # Produces analyzed scene frames for offline renderers.
+    class SceneFrameSource
+      def initialize(config:, frame_rate: nil)
+        @config = config
+        @frame_rate = frame_rate
+        @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
+        self
+      end
+
+      # @return [Hash] frame data consumed by offline renderers
+      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)
+
+        {
+          scene: { name: @scene[:name], layers: layers },
+          audio: audio,
+          scene_name: @scene[:name].to_s
+        }
+      end
+
+      # @return [void]
+      def stop
+        @input_manager&.stop
+      end
+
+      private
+
+      def resolve_shader_sources(definition)
+        @shader_source_resolver.resolve(definition: definition, scene_file: @config.scene_file.to_s)
+      end
+
+      def first_scene(definition)
+        scene = Array(definition[:scenes]).first
+        return scene if scene
+
+        { name: @config.scene_file.basename(".rb").to_sym, layers: [] }
+      end
+
+      def build_input_manager
+        Vizcore::Audio::InputManager.new(
+          source: @config.audio_source,
+          file_path: @config.audio_file&.to_s,
+          audio_device: @config.audio_device
+        )
+      end
+
+      def capture_size
+        return @input_manager.frame_size unless @frame_rate
+
+        @input_manager.realtime_capture_size(@frame_rate)
+      end
+
+      def build_pipeline
+        Vizcore::Analysis::Pipeline.new(
+          sample_rate: @input_manager.sample_rate,
+          fft_size: supported_fft_size(@input_manager.frame_size),
+          noise_gate: @config.noise_gate,
+          audio_normalize: audio_normalize_settings,
+          bpm: bpm_setting,
+          bpm_lock: bpm_lock_setting
+        )
+      end
+
+      def audio_normalize_settings
+        Hash(@definition[:analysis] || {})[:audio_normalize]
+      rescue StandardError
+        nil
+      end
+
+      def bpm_setting
+        @config.bpm || Hash(@definition[:analysis] || {})[:bpm]
+      rescue StandardError
+        @config.bpm
+      end
+
+      def bpm_lock_setting
+        @config.bpm_lock? || !!Hash(@definition[:analysis] || {})[:bpm_lock]
+      rescue StandardError
+        @config.bpm_lock?
+      end
+
+      def supported_fft_size(size)
+        value = Integer(size)
+        return value if value.positive? && (value & (value - 1)).zero?
+
+        1024
+      rescue StandardError
+        1024
+      end
+
+      def ensure_started!
+        return if @input_manager && @pipeline && @scene
+
+        raise RuntimeError, "scene frame source has not been started"
+      end
+    end
+  end
+end

data/lib/vizcore/renderer/scene_serializer.rb

@@ -9,28 +9,39 @@ module Vizcore
       # @param scene_name [String, Symbol]
       # @param scene_layers [Array<Hash>]
       # @param transition [Hash, nil]
+      # @param metrics [Hash, nil]
       # @return [Hash]
-      def audio_frame(timestamp:, audio:, scene_name:, scene_layers:, transition: nil)
-        {
+      def audio_frame(timestamp:, audio:, scene_name:, scene_layers:, transition: nil, metrics: nil)
+        frame = {
           timestamp: Float(timestamp),
           audio: serialize_audio(audio),
           scene: serialize_scene(scene_name, scene_layers),
           transition: transition
         }
+        frame[:metrics] = serialize_metrics(metrics) if metrics
+        frame
       end
 
       private
 
       def serialize_audio(audio)
         bands = symbolize_hash(audio[:bands])
+        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]),
           bands: bands.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) },
+          drums: drums.transform_values { |value| round_float(value) },
           beat: !!audio[:beat],
+          beat_confidence: round_float(audio[:beat_confidence]),
+          beat_pulse: round_float(audio[:beat_pulse]),
           beat_count: Integer(audio[:beat_count] || 0),
-          bpm: audio[:bpm]
+          bpm: audio[:bpm],
+          peak_frequency: round_float(audio[:peak_frequency])
         }
       end
 
@@ -52,9 +63,31 @@ module Vizcore
         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
       end
 
+      def serialize_param_schema(schema)
+        Array(schema).map do |entry|
+          values = symbolize_hash(entry)
+          {
+            name: values.fetch(:name).to_s,
+            default: round_float(values[:default]),
+            min: round_float(values[:min]),
+            max: round_float(values[:max]),
+            step: round_float(values[:step])
+          }.compact
+        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)
+        rescue StandardError
+          output[key] = 0
+        end
+      end
+
       def symbolize_hash(value)
         Hash(value).each_with_object({}) do |(key, entry), output|
           output[key.to_sym] = entry

data/lib/vizcore/renderer/snapshot.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require_relative "scene_frame_source"
+require_relative "snapshot_renderer"
+
+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)
+        @config = config
+        @width = width
+        @height = height
+      end
+
+      # @param out [String, Pathname]
+      # @return [Hash] snapshot metadata
+      def write(out:)
+        output_path = Pathname.new(out.to_s).expand_path
+        frame_source = SceneFrameSource.new(config: @config)
+        frame_source.start
+        frame = frame_source.capture
+        png = SnapshotRenderer.new(width: @width, height: @height).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 }
+      ensure
+        frame_source&.stop
+      end
+    end
+  end
+end