muze 0.1.0 → 1.0.0

data/lib/muze/filters/mel.rb

@@ -4,6 +4,7 @@ module Muze
   # Filterbank generation utilities.
   module Filters
     module_function
+    MEL_CACHE = Muze::Core::BoundedCache.new(max_size: 64)
 
     # @param sr [Integer]
     # @param n_fft [Integer]
@@ -11,13 +12,39 @@ module Muze
     # @param fmin [Float]
     # @param fmax [Float, nil]
     # @param htk [Boolean]
+    # @param norm [Symbol, nil]
     # @return [Numo::SFloat] shape: [n_mels, 1 + n_fft/2]
-    def mel(sr: 22_050, n_fft: 2048, n_mels: 128, fmin: 0.0, fmax: nil, htk: false)
+    def mel(sr: 22_050, n_fft: 2048, n_mels: 128, fmin: 0.0, fmax: nil, htk: false, norm: nil)
+      key = [sr, n_fft, n_mels, fmin, fmax, htk, norm]
+      MEL_CACHE.fetch(key) { build_mel(sr:, n_fft:, n_mels:, fmin:, fmax:, htk:, norm:) }.dup
+    end
+
+    # @param n_mels [Integer]
+    # @param fmin [Float]
+    # @param fmax [Float]
+    # @param htk [Boolean]
+    # @return [Numo::SFloat]
+    def mel_frequencies(n_mels:, fmin:, fmax:, htk: false)
+      validate_frequency_bounds!(sr: fmax * 2.0, fmin:, fmax:)
+      raise Muze::ParameterError, "n_mels must be positive" unless n_mels.positive?
+
+      mel_min = hz_to_mel(fmin, htk:)
+      mel_max = hz_to_mel(fmax, htk:)
+      Numo::SFloat.cast(
+        Array.new(n_mels) do |idx|
+          mel_to_hz(mel_min + ((mel_max - mel_min) * idx / [n_mels - 1, 1].max.to_f), htk:)
+        end
+      )
+    end
+
+    def build_mel(sr:, n_fft:, n_mels:, fmin:, fmax:, htk:, norm:)
       raise Muze::ParameterError, "sr must be positive" unless sr.positive?
       raise Muze::ParameterError, "n_fft must be positive" unless n_fft.positive?
       raise Muze::ParameterError, "n_mels must be positive" unless n_mels.positive?
+      raise Muze::ParameterError, "norm must be nil or :slaney" unless norm.nil? || norm == :slaney
 
       fmax ||= sr / 2.0
+      validate_frequency_bounds!(sr:, fmin:, fmax:)
       mel_min = hz_to_mel(fmin, htk:)
       mel_max = hz_to_mel(fmax, htk:)
 
@@ -47,10 +74,29 @@ module Muze
 
           matrix[mel_index, bin] = (right - bin).to_f / (right - center)
         end
+
+        if norm == :slaney
+          enorm = 2.0 / (hz_points[mel_index + 2] - hz_points[mel_index])
+          matrix[mel_index, true] = matrix[mel_index, true] * enorm
+        end
+      end
+
+      empty_filters = n_mels.times.select { |mel_index| matrix[mel_index, true].sum <= 0.0 }
+      unless empty_filters.empty?
+        raise Muze::ParameterError, "mel filterbank contains empty filters: #{empty_filters.join(', ')}"
       end
 
       matrix
     end
+    private_class_method :build_mel
+
+    def validate_frequency_bounds!(sr:, fmin:, fmax:)
+      raise Muze::ParameterError, "fmin must be >= 0" if fmin.negative?
+      raise Muze::ParameterError, "fmax must be positive" unless fmax.positive?
+      raise Muze::ParameterError, "fmin must be less than fmax" unless fmin < fmax
+      raise Muze::ParameterError, "fmax must be <= sr / 2" unless fmax <= (sr / 2.0)
+    end
+    private_class_method :validate_frequency_bounds!
 
     # @param hz [Float]
     # @param htk [Boolean]

data/lib/muze/io/audio_loader/ffmpeg_backend.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "open3"
+require "timeout"
 
 module Muze
   module IO
@@ -11,6 +12,7 @@ module Muze
         module_function
 
         SUPPORTED_EXTENSIONS = %w[.flac .mp3 .ogg].freeze
+        DEFAULT_TIMEOUT_SECONDS = 30
         INSTALLATION_STEPS = [
           "Install ffmpeg and ensure both `ffmpeg` and `ffprobe` are available on PATH.",
           "macOS: `brew install ffmpeg`.",
@@ -25,7 +27,8 @@ module Muze
 
         # @return [Boolean]
         def available?
-          command_available?("ffmpeg") && command_available?("ffprobe")
+          @available = command_available?("ffmpeg") && command_available?("ffprobe") if @available.nil?
+          @available
         end
 
         # @param extension [String]
@@ -35,23 +38,58 @@ module Muze
           "Unable to load #{format} because the FFmpeg backend is unavailable. #{INSTALLATION_STEPS.join(' ')}"
         end
 
+        # @return [Boolean]
+        def applies_time_window?
+          true
+        end
+
         # @param path [String]
+        # @param offset [Float]
+        # @param duration [Float, nil]
         # @return [Array(Array<Float>, Integer, Integer)]
-        def read(path)
+        def read(path, offset: 0.0, duration: nil)
           raise Muze::DependencyError, installation_message(File.extname(path).downcase) unless available?
 
           source_sr, channels = probe_stream(path)
-          [decode_samples(path, channels), source_sr, channels]
+          [decode_samples(path, channels, offset:, duration:), source_sr, channels]
+        end
+
+        # @yieldparam samples [Array<Float>, Array<Array<Float>>]
+        # @yieldparam sample_rate [Integer]
+        # @yieldparam channels [Integer]
+        # @return [void]
+        def read_stream(path, chunk_frames:, offset: 0.0, duration: nil)
+          raise Muze::DependencyError, installation_message(File.extname(path).downcase) unless available?
+
+          source_sr, channels = probe_stream(path)
+          stream_decoded_samples(path, source_sr:, channels:, chunk_frames:, offset:, duration:) do |samples|
+            yield samples, source_sr, channels
+          end
+        end
+
+        # @param path [String]
+        # @return [Hash]
+        def info(path)
+          raise Muze::DependencyError, installation_message(File.extname(path).downcase) unless available?
+
+          sample_rate, channels, duration = probe_stream(path, include_duration: true)
+          {
+            sample_rate: sample_rate,
+            channels: channels,
+            duration: duration,
+            format: File.extname(path).delete_prefix(".")
+          }
         end
 
         # @param path [String]
         # @return [Array(Integer, Integer)]
-        def probe_stream(path)
-          stdout, stderr, status = Open3.capture3(
+        def probe_stream(path, include_duration: false)
+          stream_entries = include_duration ? "stream=sample_rate,channels,duration:format=duration" : "stream=sample_rate,channels"
+          stdout, stderr, status = capture_with_timeout(
             "ffprobe",
             "-v", "error",
             "-select_streams", "a:0",
-            "-show_entries", "stream=sample_rate,channels",
+            "-show_entries", stream_entries,
             "-of", "json",
             path
           )
@@ -60,14 +98,16 @@ module Muze
             raise Muze::AudioLoadError, "ffprobe failed for #{path}: #{stderr.strip}"
           end
 
-          parse_probe_output(stdout, path)
+          parse_probe_output(stdout, path, stderr:, include_duration:)
         end
         private_class_method :probe_stream
 
         # @param raw_output [String]
         # @param path [String]
-        # @return [Array(Integer, Integer)]
-        def parse_probe_output(raw_output, path)
+        # @param stderr [String]
+        # @param include_duration [Boolean]
+        # @return [Array(Integer, Integer, Float)]
+        def parse_probe_output(raw_output, path, stderr:, include_duration:)
           data = JSON.parse(raw_output)
           stream = data.fetch("streams", []).first
           raise Muze::AudioLoadError, "No audio stream found in #{path}" unless stream
@@ -79,20 +119,33 @@ module Muze
             raise Muze::AudioLoadError, "Invalid stream metadata for #{path}: sample_rate=#{source_sr}, channels=#{channels}"
           end
 
-          [source_sr, channels]
+          return [source_sr, channels] unless include_duration
+
+          duration = stream["duration"] || data.fetch("format", {})["duration"]
+          [source_sr, channels, duration ? duration.to_f : nil]
         rescue JSON::ParserError, KeyError, TypeError, ArgumentError => e
-          raise Muze::AudioLoadError, "Failed to parse ffprobe output for #{path}: #{e.message}"
+          stderr_detail = stderr.to_s.strip
+          suffix = stderr_detail.empty? ? "" : " stderr: #{stderr_detail}"
+          raise Muze::AudioLoadError, "Failed to parse ffprobe output for #{path}: #{e.message}#{suffix}"
         end
         private_class_method :parse_probe_output
 
         # @param path [String]
         # @param channels [Integer]
+        # @param offset [Float]
+        # @param duration [Float, nil]
         # @return [Array<Float>, Array<Array<Float>>]
-        def decode_samples(path, channels)
-          raw_samples, stderr, status = Open3.capture3(
+        def decode_samples(path, channels, offset:, duration:)
+          floats, stderr, status = stream_float32le_with_timeout(
             "ffmpeg",
             "-v", "error",
+            "-nostdin",
+            *seek_args(offset),
             "-i", path,
+            "-map", "0:a:0",
+            "-vn",
+            "-sn",
+            *duration_args(duration),
             "-f", "f32le",
             "-acodec", "pcm_f32le",
             "pipe:1"
@@ -102,7 +155,6 @@ module Muze
             raise Muze::AudioLoadError, "ffmpeg failed for #{path}: #{stderr.strip}"
           end
 
-          floats = raw_samples.unpack("e*")
           return floats if channels == 1
 
           unless (floats.length % channels).zero?
@@ -113,12 +165,124 @@ module Muze
         end
         private_class_method :decode_samples
 
+        def stream_decoded_samples(path, source_sr:, channels:, chunk_frames:, offset:, duration:)
+          pending = []
+          frame_sample_count = [chunk_frames * channels, 1].max
+          _, stderr, status = stream_float32le_with_timeout(
+            "ffmpeg",
+            "-v", "error",
+            "-nostdin",
+            *seek_args(offset),
+            "-i", path,
+            "-map", "0:a:0",
+            "-vn",
+            "-sn",
+            *duration_args(duration),
+            "-f", "f32le",
+            "-acodec", "pcm_f32le",
+            "pipe:1"
+          ) do |floats|
+            pending.concat(floats)
+            while pending.length >= frame_sample_count
+              yield samples_from_floats(pending.shift(frame_sample_count), channels)
+            end
+          end
+
+          unless status.success?
+            raise Muze::AudioLoadError, "ffmpeg failed for #{path}: #{stderr.strip}"
+          end
+
+          raise Muze::AudioLoadError, "Decoded samples are not divisible by channels (#{pending.length} / #{channels})" unless (pending.length % channels).zero?
+
+          yield samples_from_floats(pending, channels) unless pending.empty?
+        end
+        private_class_method :stream_decoded_samples
+
+        def samples_from_floats(floats, channels)
+          return floats if channels == 1
+
+          floats.each_slice(channels).map(&:dup)
+        end
+        private_class_method :samples_from_floats
+
+        def seek_args(offset)
+          offset.positive? ? ["-ss", offset.to_s] : []
+        end
+        private_class_method :seek_args
+
+        def duration_args(duration)
+          duration ? ["-t", duration.to_s] : []
+        end
+        private_class_method :duration_args
+
+        def capture_with_timeout(*command)
+          Timeout.timeout(DEFAULT_TIMEOUT_SECONDS) { Open3.capture3(*command) }
+        rescue Timeout::Error
+          raise Muze::AudioLoadError, "#{command.first} timed out after #{DEFAULT_TIMEOUT_SECONDS}s"
+        end
+        private_class_method :capture_with_timeout
+
+        def stream_float32le_with_timeout(*command)
+          floats = block_given? ? nil : []
+          stderr_data = +""
+          status = nil
+          wait_thread = nil
+          reader_error = nil
+          leftover = +"".b
+
+          Timeout.timeout(DEFAULT_TIMEOUT_SECONDS) do
+            Open3.popen3(*command) do |stdin, stdout, stderr, process_wait|
+              wait_thread = process_wait
+              stdin.close
+              stdout.binmode
+              reader = Thread.new do
+                until stdout.eof?
+                  data = leftover + stdout.readpartial(16 * 1024)
+                  whole_bytes = data.bytesize - (data.bytesize % 4)
+                  decoded = whole_bytes.positive? ? data.byteslice(0, whole_bytes).unpack("e*") : []
+                  block_given? ? yield(decoded) : floats.concat(decoded)
+                  leftover = data.byteslice(whole_bytes, data.bytesize - whole_bytes) || +"".b
+                end
+              rescue EOFError
+                nil
+              rescue StandardError => e
+                reader_error = e
+              end
+              stderr_reader = Thread.new { stderr_data << stderr.read.to_s }
+              reader.join
+              stderr_reader.join
+              raise reader_error if reader_error
+              raise Muze::AudioLoadError, "ffmpeg emitted a partial f32 sample" unless leftover.empty?
+
+              status = process_wait.value
+            end
+          end
+          [floats, stderr_data, status]
+        rescue Timeout::Error
+          terminate_process(wait_thread)
+          raise Muze::AudioLoadError, "#{command.first} timed out after #{DEFAULT_TIMEOUT_SECONDS}s"
+        end
+        private_class_method :stream_float32le_with_timeout
+
+        def terminate_process(wait_thread)
+          return unless wait_thread&.pid
+
+          Process.kill("TERM", wait_thread.pid)
+          wait_thread.join(0.2)
+          Process.kill("KILL", wait_thread.pid) if wait_thread.alive?
+        rescue Errno::ESRCH
+          nil
+        end
+        private_class_method :terminate_process
+
         # @param command [String]
         # @return [Boolean]
         def command_available?(command)
-          system(command, "-version", out: File::NULL, err: File::NULL)
+          Timeout.timeout(5) { system(command, "-version", out: File::NULL, err: File::NULL) }
         rescue Errno::ENOENT
           false
+        rescue Timeout::Error
+          false
         end
         private_class_method :command_available?
       end

data/lib/muze/io/audio_loader/wavify_backend.rb

@@ -27,25 +27,132 @@ module Muze
           true
         end
 
+        # @return [Boolean]
+        def applies_time_window?
+          true
+        end
+
+        # @param extension [String]
+        # @return [String]
+        def installation_message(extension)
+          "Unable to load #{extension.delete_prefix('.')} because the WAV backend is unavailable."
+        end
+
         # @param path [String]
+        # @param offset [Float]
+        # @param duration [Float, nil]
         # @return [Array(Array<Float>, Integer, Integer)]
-        def read(path)
-          buffer = Wavify::Codecs::Wav.read(path)
-          float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
-          converted = buffer.convert(float_format)
+        def read(path, offset: 0.0, duration: nil)
+          metadata = Wavify::Codecs::Wav.metadata(path)
+          source_format = metadata.fetch(:format)
+          float_format = source_format.with(sample_format: :float, bit_depth: 32)
+          samples = stream_samples(path, float_format:, offset:, duration:)
+
+          [samples_from_interleaved(samples, float_format.channels), float_format.sample_rate, float_format.channels]
+        end
+
+        # @yieldparam samples [Array<Float>, Array<Array<Float>>]
+        # @yieldparam sample_rate [Integer]
+        # @yieldparam channels [Integer]
+        # @return [void]
+        def read_stream(path, chunk_frames:, offset: 0.0, duration: nil)
+          metadata = Wavify::Codecs::Wav.metadata(path)
+          source_format = metadata.fetch(:format)
+          float_format = source_format.with(sample_format: :float, bit_depth: 32)
+
+          stream_sample_chunks(path, float_format:, offset:, duration:, chunk_frames:) do |samples|
+            yield samples_from_interleaved(samples, float_format.channels), float_format.sample_rate, float_format.channels
+          end
+        end
+
+        # @param path [String]
+        # @return [Hash]
+        def info(path)
+          metadata = Wavify::Codecs::Wav.metadata(path)
+          format = metadata.fetch(:format)
+          {
+            sample_rate: format.sample_rate,
+            channels: format.channels,
+            duration: metadata.fetch(:duration).total_seconds,
+            format: format_label(path)
+          }
+        end
+
+        # @return [Array<Float>]
+        def stream_samples(path, float_format:, offset:, duration:)
+          start_frame = (offset * float_format.sample_rate).floor
+          end_frame = duration ? start_frame + (duration * float_format.sample_rate).floor : nil
+          samples = []
+          current_frame = 0
+
+          Wavify::Codecs::Wav.stream_read(path) do |chunk|
+            converted = chunk.format == float_format ? chunk : chunk.convert(float_format)
+            chunk_frames = converted.sample_frame_count
+            chunk_start = current_frame
+            chunk_end = current_frame + chunk_frames
+            copy_start = [start_frame, chunk_start].max
+            copy_end = end_frame ? [end_frame, chunk_end].min : chunk_end
+
+            if copy_start < copy_end
+              local_start = copy_start - chunk_start
+              local_length = copy_end - copy_start
+              samples.concat(converted.slice(local_start, local_length).samples)
+            end
+
+            current_frame = chunk_end
+            break if end_frame && current_frame >= end_frame
+          end
+
+          samples
+        end
+        private_class_method :stream_samples
 
-          samples = samples_from_buffer(converted)
-          [samples, converted.format.sample_rate, converted.format.channels]
+        def stream_sample_chunks(path, float_format:, offset:, duration:, chunk_frames:)
+          start_frame = (offset * float_format.sample_rate).floor
+          end_frame = duration ? start_frame + (duration * float_format.sample_rate).floor : nil
+          current_frame = 0
+          chunk_samples = [chunk_frames * float_format.channels, 1].max
+          pending = []
+
+          Wavify::Codecs::Wav.stream_read(path) do |chunk|
+            converted = chunk.format == float_format ? chunk : chunk.convert(float_format)
+            chunk_frames_count = converted.sample_frame_count
+            chunk_start = current_frame
+            chunk_end = current_frame + chunk_frames_count
+            copy_start = [start_frame, chunk_start].max
+            copy_end = end_frame ? [end_frame, chunk_end].min : chunk_end
+
+            if copy_start < copy_end
+              local_start = copy_start - chunk_start
+              local_length = copy_end - copy_start
+              pending.concat(converted.slice(local_start, local_length).samples)
+              while pending.length >= chunk_samples
+                yield pending.shift(chunk_samples)
+              end
+            end
+
+            current_frame = chunk_end
+            break if end_frame && current_frame >= end_frame
+          end
+
+          yield pending unless pending.empty?
         end
+        private_class_method :stream_sample_chunks
 
-        # @param buffer [Wavify::Core::SampleBuffer]
         # @return [Array<Float>, Array<Array<Float>>]
-        def samples_from_buffer(buffer)
-          return buffer.samples if buffer.format.channels == 1
+        def samples_from_interleaved(samples, channels)
+          return samples if channels == 1
+
+          samples.each_slice(channels).map(&:dup)
+        end
+        private_class_method :samples_from_interleaved
+
+        def format_label(source)
+          return File.extname(source).delete_prefix(".") if source.is_a?(String)
 
-          buffer.samples.each_slice(buffer.format.channels).map(&:dup)
+          "wav"
         end
-        private_class_method :samples_from_buffer
+        private_class_method :format_label
       end
     end
   end