deftones 0.1.0 → 1.0.0

data/lib/deftones/io/buffer.rb

@@ -2,16 +2,26 @@
 
 require "open3"
 require "tempfile"
+require "timeout"
 
 module Deftones
   module IO
     class Buffer
       include Enumerable
 
-      attr_reader :samples, :channels, :sample_rate
+      attr_reader :samples, :channels, :sample_rate, :interpolation
 
       COMPRESSED_EXTENSIONS = %w[.mp3 .ogg .oga].freeze
       SAVEABLE_FORMATS = %i[wav mp3 ogg].freeze
+      DEFAULT_CODEC_TIMEOUT = 30.0
+      INTERPOLATION_MODES = %i[linear nearest cubic sinc_lite].freeze
+      SINC_LITE_RADIUS = 8
+      WAV_BIT_DEPTHS = [16, 24, 32].freeze
+      Statistics = Struct.new(:peak, :rms, :clip_count, keyword_init: true)
+
+      class << self
+        attr_accessor :codec_backend, :codec_timeout
+      end
 
       def self.interleave(mono_samples, channels)
         return mono_samples.dup if channels == 1
@@ -19,12 +29,12 @@ module Deftones
         mono_samples.flat_map { |sample| Array.new(channels, sample) }
       end
 
-      def self.from_mono(samples, channels: 1, sample_rate: Context::DEFAULT_SAMPLE_RATE)
+      def self.from_mono(samples, channels: 1, sample_rate: Context::DEFAULT_SAMPLE_RATE, interpolation: :linear)
         interleaved = channels == 1 ? samples : interleave(samples, channels)
-        new(interleaved, channels: channels, sample_rate: sample_rate)
+        new(interleaved, channels: channels, sample_rate: sample_rate, interpolation: interpolation)
       end
 
-      def self.from_array(samples, sample_rate: Context::DEFAULT_SAMPLE_RATE, channels: nil)
+      def self.from_array(samples, sample_rate: Context::DEFAULT_SAMPLE_RATE, channels: nil, interpolation: :linear)
         if samples.first.is_a?(Array)
           channel_count = channels || samples.length
           frame_count = samples.map(&:length).max || 0
@@ -37,9 +47,9 @@ module Deftones
             end
           end
 
-          new(interleaved, channels: channel_count, sample_rate: sample_rate)
+          new(interleaved, channels: channel_count, sample_rate: sample_rate, interpolation: interpolation)
         else
-          from_mono(samples, channels: channels || 1, sample_rate: sample_rate)
+          from_mono(samples, channels: channels || 1, sample_rate: sample_rate, interpolation: interpolation)
         end
       end
 
@@ -51,24 +61,40 @@ module Deftones
         true
       end
 
+      def self.compressed_audio_available?
+        return true if codec_backend&.respond_to?(:decode)
+        return true if codec_backend&.respond_to?(:encode)
+
+        send(:executable_available?, "ffmpeg") || send(:executable_available?, "afconvert")
+      end
+
       class << self
         alias fromArray from_array
         alias fromUrl from_url
+        alias compressedAudioAvailable compressed_audio_available?
       end
 
-      def self.load(path)
-        extension = File.extname(path).downcase
-        return load_wav(path) if extension == ".wav"
-        return load_compressed(path, extension) if COMPRESSED_EXTENSIONS.include?(extension)
+      def self.load(source, sample_rate: nil, channels: nil)
+        return load_io(source) if source.respond_to?(:read) && !source.is_a?(String)
+
+        validate_path_string!(source, role: "audio source")
+        extension = File.extname(source).downcase
+        return load_wav(source) if extension == ".wav"
+        return load_compressed(source, extension, sample_rate: sample_rate, channels: channels) if COMPRESSED_EXTENSIONS.include?(extension)
 
-        raise ArgumentError, "Unsupported audio format: #{extension}"
+        raise Deftones::UnsupportedAudioFormatError, "Unsupported audio format: #{extension}"
       end
 
-      def initialize(samples, channels:, sample_rate:)
+      def initialize(samples, channels:, sample_rate:, interpolation: :linear)
         @samples = samples.map(&:to_f)
         @channels = channels
         @sample_rate = sample_rate
+        @interpolation = normalize_interpolation(interpolation)
         @disposed = false
+        @mono_cache = nil
+        @peak_cache = nil
+        @rms_cache = nil
+        @statistics_cache = {}
       end
 
       def each(&block)
@@ -103,21 +129,42 @@ module Deftones
 
       def mono
         return @samples if @channels == 1
+        return @mono_cache if @mono_cache
 
-        Array.new(frames) do |frame|
+        @mono_cache = Array.new(frames) do |frame|
           offset = frame * @channels
           @samples[offset, @channels].sum / @channels.to_f
         end
       end
 
       def peak
-        @samples.map(&:abs).max || 0.0
+        @peak_cache ||= @samples.map(&:abs).max || 0.0
       end
 
       def rms
         return 0.0 if @samples.empty?
 
-        Math.sqrt(@samples.sum { |sample| sample * sample } / @samples.length)
+        @rms_cache ||= Math.sqrt(@samples.sum { |sample| sample * sample } / @samples.length)
+      end
+
+      def integrated_lufs
+        return -Float::INFINITY if rms <= 0.0
+
+        (20.0 * Math.log10(rms)) - 0.691
+      end
+
+      def clip_count(threshold = 1.0)
+        limit = threshold.to_f.abs
+        @samples.count { |sample| sample.abs >= limit }
+      end
+
+      def statistics(clip_threshold: 1.0)
+        threshold = clip_threshold.to_f.abs
+        @statistics_cache[threshold] ||= Statistics.new(
+          peak: peak,
+          rms: rms,
+          clip_count: clip_count(threshold)
+        )
       end
 
       def [](frame_index, channel = nil)
@@ -146,43 +193,172 @@ module Deftones
         Array.new(@channels) { |channel_index| get_channel_data(channel_index) }
       end
 
-      def sample_at(frame_position, channel = 0)
+      def interpolation=(value)
+        @interpolation = normalize_interpolation(value)
+      end
+
+      def sample_at(frame_position, channel = 0, interpolation: @interpolation)
         return 0.0 if @samples.empty?
 
         clamped_position = Deftones::DSP::Helpers.clamp(frame_position.to_f, 0.0, [frames - 1, 0].max)
+        channel_index = [channel, @channels - 1].min
+        case normalize_interpolation(interpolation)
+        when :nearest
+          self[clamped_position.round, channel_index]
+        when :cubic
+          cubic_sample_at(clamped_position, channel_index)
+        when :sinc_lite
+          sinc_lite_sample_at(clamped_position, channel_index)
+        else
+          linear_sample_at(clamped_position, channel_index)
+        end
+      end
+
+      def sample_at_nearest(frame_position, channel = 0)
+        sample_at(frame_position, channel, interpolation: :nearest)
+      end
+
+      def sample_at_cubic(frame_position, channel = 0)
+        sample_at(frame_position, channel, interpolation: :cubic)
+      end
+
+      def sample_at_sinc_lite(frame_position, channel = 0)
+        sample_at(frame_position, channel, interpolation: :sinc_lite)
+      end
+
+      alias sampleAt sample_at
+      alias sampleAtNearest sample_at_nearest
+      alias sampleAtCubic sample_at_cubic
+      alias sampleAtSincLite sample_at_sinc_lite
+
+      def resample(target_sample_rate, interpolation: @interpolation)
+        normalized_sample_rate = target_sample_rate.to_f
+        raise ArgumentError, "sample rate must be positive" unless normalized_sample_rate.positive? && normalized_sample_rate.finite?
+        return new_like(@samples) if normalized_sample_rate == @sample_rate.to_f
+
+        target_frames = (frames * (normalized_sample_rate / @sample_rate.to_f)).round
+        channel_data = Array.new(@channels) do |channel_index|
+          Array.new(target_frames) do |frame_index|
+            source_position = frame_index * (@sample_rate.to_f / normalized_sample_rate)
+            sample_at(source_position, channel_index, interpolation: interpolation)
+          end
+        end
+        self.class.from_array(
+          channel_data,
+          sample_rate: normalized_sample_rate.round,
+          channels: @channels,
+          interpolation: normalize_interpolation(interpolation)
+        )
+      end
+
+      alias resampleTo resample
+
+      def linear_sample_at(clamped_position, channel)
         lower = clamped_position.floor
         upper = [lower + 1, frames - 1].min
         fraction = clamped_position - lower
-        lower_sample = self[lower, [channel, @channels - 1].min]
-        upper_sample = self[upper, [channel, @channels - 1].min]
+        lower_sample = self[lower, channel]
+        upper_sample = self[upper, channel]
         Deftones::DSP::Helpers.lerp(lower_sample, upper_sample, fraction)
       end
 
+      def cubic_sample_at(clamped_position, channel)
+        base = clamped_position.floor
+        fraction = clamped_position - base
+        p0 = self[[base - 1, 0].max, channel]
+        p1 = self[base, channel]
+        p2 = self[[base + 1, frames - 1].min, channel]
+        p3 = self[[base + 2, frames - 1].min, channel]
+        a0 = (-0.5 * p0) + (1.5 * p1) - (1.5 * p2) + (0.5 * p3)
+        a1 = p0 - (2.5 * p1) + (2.0 * p2) - (0.5 * p3)
+        a2 = (-0.5 * p0) + (0.5 * p2)
+        a3 = p1
+        (((a0 * fraction) + a1) * fraction * fraction) + (a2 * fraction) + a3
+      end
+
+      def sinc_lite_sample_at(clamped_position, channel)
+        center = clamped_position.floor
+        weighted_sum = 0.0
+        weight_total = 0.0
+
+        ((center - SINC_LITE_RADIUS + 1)..(center + SINC_LITE_RADIUS)).each do |index|
+          next if index.negative? || index >= frames
+
+          distance = clamped_position - index
+          weight = sinc(distance) * hann_window(distance / SINC_LITE_RADIUS)
+          weighted_sum += self[index, channel] * weight
+          weight_total += weight
+        end
+
+        return linear_sample_at(clamped_position, channel) if weight_total.abs < 1.0e-12
+
+        weighted_sum / weight_total
+      end
+
+      def sinc(value)
+        return 1.0 if value.abs < 1.0e-12
+
+        x = Math::PI * value
+        Math.sin(x) / x
+      end
+
+      def hann_window(normalized_distance)
+        distance = normalized_distance.abs
+        return 0.0 if distance >= 1.0
+
+        0.5 * (1.0 + Math.cos(Math::PI * distance))
+      end
+
       def slice(start_frame, length)
         frame_count = [length.to_i, 0].max
-        offset = start_frame.to_i * @channels
+        first_frame = [start_frame.to_i, 0].max
+        offset = first_frame * @channels
         subset = @samples.slice(offset, frame_count * @channels) || []
-        self.class.new(subset, channels: @channels, sample_rate: @sample_rate)
+        new_like(subset)
+      end
+
+      def slice_seconds(start_time, duration)
+        start_frame = (Deftones::Music::Time.parse(start_time) * @sample_rate).floor
+        frame_count = (Deftones::Music::Time.parse(duration) * @sample_rate).ceil
+        slice(start_frame, frame_count)
       end
 
       def reverse
         reversed_frames = each_frame.to_a.reverse.flatten
-        self.class.new(reversed_frames, channels: @channels, sample_rate: @sample_rate)
+        new_like(reversed_frames)
       end
 
       def normalize(target_peak = 0.99)
-        return self.class.new(@samples, channels: @channels, sample_rate: @sample_rate) if peak.zero?
+        normalized_target = normalize_level_target(target_peak, "target peak")
+        return new_like(@samples) if peak.zero?
+
+        scale = normalized_target / peak
+        new_like(@samples.map { |sample| sample * scale })
+      end
+
+      def normalize_rms(target_rms = 0.2)
+        normalized_target = normalize_level_target(target_rms, "target RMS")
+        return new_like(@samples) if rms.zero?
 
-        scale = target_peak.to_f / peak
-        self.class.new(@samples.map { |sample| sample * scale }, channels: @channels, sample_rate: @sample_rate)
+        scale = normalized_target / rms
+        new_like(@samples.map { |sample| sample * scale })
+      end
+
+      def normalize_lufs(target_lufs = -14.0)
+        target_gain = 10.0**((target_lufs.to_f + 0.691) / 20.0)
+        normalize_rms(target_gain)
       end
 
       def mixdown
-        self.class.new(mono, channels: 1, sample_rate: @sample_rate)
+        self.class.new(mono, channels: 1, sample_rate: @sample_rate, interpolation: @interpolation)
       end
 
       def dispose
         @samples = []
+        @mono_cache = nil
+        @peak_cache = nil
+        @rms_cache = nil
+        @statistics_cache.clear
         @disposed = true
         self
       end
@@ -190,46 +366,100 @@ module Deftones
       alias numberOfChannels number_of_channels
       alias getChannelData get_channel_data
       alias toArray to_array
+      alias sliceSeconds slice_seconds
+      alias normalizeRms normalize_rms
+      alias normalizeLufs normalize_lufs
+      alias integratedLufs integrated_lufs
+      alias stats statistics
+
+      def save(target, format: nil, on_format_mismatch: :error, bit_depth: 16, dither: false, dither_rng: nil)
+        if target.respond_to?(:write) && !target.is_a?(String)
+          return save_io(target, format: format || :wav, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng)
+        end
 
-      def save(path, format: nil)
-        resolved_format = self.class.send(:resolve_save_format, path, format)
-        raise ArgumentError, "Unsupported format: #{resolved_format}" unless SAVEABLE_FORMATS.include?(resolved_format)
+        self.class.send(:validate_path_string!, target, role: "audio target")
+        resolved_format = self.class.send(:resolve_save_format, target, format, on_format_mismatch: on_format_mismatch)
+        raise Deftones::UnsupportedAudioFormatError, "Unsupported format: #{resolved_format}" unless SAVEABLE_FORMATS.include?(resolved_format)
 
         case resolved_format
         when :wav
-          save_wav(path)
+          save_wav(target, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng)
         when :mp3, :ogg
-          save_compressed(path, resolved_format)
+          save_compressed(target, resolved_format, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng)
         end
-        path
+        target
       end
 
       private
 
-      def save_wav(path)
+      def new_like(samples, channels: @channels, sample_rate: @sample_rate)
+        self.class.new(samples, channels: channels, sample_rate: sample_rate, interpolation: @interpolation)
+      end
+
+      def normalize_interpolation(value)
+        normalized = value.to_sym
+        return normalized if INTERPOLATION_MODES.include?(normalized)
+
+        raise ArgumentError, "Unsupported interpolation mode: #{value}"
+      end
+
+      def normalize_level_target(value, name)
+        normalized = value.to_f
+        raise ArgumentError, "#{name} must be finite and non-negative" unless normalized.finite? && !normalized.negative?
+
+        normalized
+      end
+
+      def save_io(io, format:, bit_depth:, dither:, dither_rng:)
+        Tempfile.create(["deftones-buffer-save", ".#{format}"]) do |tempfile|
+          tempfile.close
+          save(tempfile.path, format: format, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng)
+          io.write(File.binread(tempfile.path))
+        end
+        io
+      end
+
+      def save_wav(path, bit_depth:, dither:, dither_rng:)
+        self.class.send(:ensure_wav_backend!)
+        normalized_bit_depth = self.class.send(:validate_wav_bit_depth, bit_depth)
+        output_samples = dither ? dithered_samples(normalized_bit_depth, dither_rng) : @samples
+
         sample_buffer = Wavify::Core::SampleBuffer.new(
-          @samples,
+          output_samples,
           self.class.send(:wavify_work_format, @channels, @sample_rate)
         )
         Wavify::Codecs::Wav.write(
           path,
           sample_buffer,
-          format: self.class.send(:wavify_wav_format, @channels, @sample_rate)
+          format: self.class.send(:wavify_wav_format, @channels, @sample_rate, normalized_bit_depth)
         )
       end
 
-      def save_compressed(path, format)
+      def save_compressed(path, format, bit_depth:, dither:, dither_rng:)
         backend = self.class.send(:encoder_backend_for, format)
-        raise ArgumentError, self.class.send(:missing_encoder_message, format) unless backend
+        raise Deftones::MissingCodecBackendError, self.class.send(:missing_encoder_message, format) unless backend
 
         Tempfile.create(["deftones-buffer-export", ".wav"]) do |tempfile|
           tempfile.close
-          save_wav(tempfile.path)
-          stdout, stderr, status = Open3.capture3(*self.class.send(:encoder_command, backend, tempfile.path, path, format))
+          save_wav(tempfile.path, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng)
+          if self.class.send(:custom_codec_backend?, backend)
+            backend.encode(tempfile.path, path, format: format, sample_rate: @sample_rate, channels: @channels)
+            return
+          end
+
+          command = self.class.send(:encoder_command, backend, tempfile.path, path, format, @sample_rate, @channels)
+          stdout, stderr, status = self.class.send(:capture_codec_command, *command)
           return if status.success?
 
-          message = [stderr, stdout].map(&:strip).reject(&:empty?).first || "unknown encoder error"
-          raise ArgumentError, "Failed to encode #{format}: #{message}"
+          self.class.send(:raise_codec_command_error, "Failed to encode #{format}", command, stdout, stderr, status)
+        end
+      end
+
+      def dithered_samples(bit_depth, rng)
+        random = rng || Random
+        step = 1.0 / ((2**(bit_depth - 1)) - 1)
+        @samples.map do |sample|
+          Deftones::DSP::Helpers.clamp(sample + ((random.rand - random.rand) * step), -1.0, 1.0)
         end
       end
 
@@ -237,27 +467,60 @@ module Deftones
         private
 
         def load_wav(path)
+          validate_path_string!(path, role: "WAV source")
+          ensure_wav_backend!
+
           sample_buffer = Wavify::Codecs::Wav.read(path)
           float_buffer = sample_buffer.convert(wavify_work_format(sample_buffer.format.channels, sample_buffer.format.sample_rate))
           new(float_buffer.samples, channels: float_buffer.format.channels, sample_rate: float_buffer.format.sample_rate)
-        rescue Wavify::Error => error
+        rescue StandardError => error
+          raise if error.is_a?(Deftones::MissingCodecBackendError)
+          raise unless defined?(Wavify::Error) && error.is_a?(Wavify::Error)
+
           raise ArgumentError, "Failed to load WAV: #{error.message}"
         end
 
-        def load_compressed(path, extension)
+        def load_io(io)
+          extension = io.respond_to?(:path) ? File.extname(io.path).downcase : ".wav"
+          extension = ".wav" if extension.empty?
+          Tempfile.create(["deftones-buffer-load", extension]) do |tempfile|
+            tempfile.binmode
+            tempfile.write(io.read)
+            tempfile.close
+            load(tempfile.path)
+          end
+        end
+
+        def load_compressed(path, extension, sample_rate: nil, channels: nil)
+          validate_path_string!(path, role: "compressed audio source")
           backend = decoder_backend_for(extension)
-          raise ArgumentError, missing_decoder_message(extension) unless backend
+          raise Deftones::MissingCodecBackendError, missing_decoder_message(extension) unless backend
 
           Tempfile.create(["deftones-buffer", ".wav"]) do |tempfile|
             tempfile.close
-            stdout, stderr, status = Open3.capture3(*decoder_command(backend, path, tempfile.path))
+            if custom_codec_backend?(backend)
+              decode_options = { extension: extension }
+              decode_options[:sample_rate] = sample_rate if sample_rate
+              decode_options[:channels] = channels if channels
+              backend.decode(path, tempfile.path, **decode_options)
+              next load_wav(tempfile.path)
+            end
+
+            command = decoder_command(backend, path, tempfile.path, sample_rate: sample_rate, channels: channels)
+            stdout, stderr, status = capture_codec_command(*command)
             next load_wav(tempfile.path) if status.success?
 
-            message = [stderr, stdout].map(&:strip).reject(&:empty?).first || "unknown decoder error"
-            raise ArgumentError, "Failed to decode #{extension}: #{message}"
+            raise_codec_command_error("Failed to decode #{extension}", command, stdout, stderr, status)
           end
         end
 
+        def ensure_wav_backend!
+          return if Deftones.wavify_available?
+
+          raise Deftones::MissingCodecBackendError,
+                "WAV codec backend is unavailable. Install the wavify gem to load or save WAV audio."
+        end
+
         def wavify_work_format(channels, sample_rate)
           Wavify::Core::Format.new(
             channels: channels,
@@ -267,16 +530,24 @@ module Deftones
           )
         end
 
-        def wavify_wav_format(channels, sample_rate)
+        def wavify_wav_format(channels, sample_rate, bit_depth)
           Wavify::Core::Format.new(
             channels: channels,
             sample_rate: sample_rate,
-            bit_depth: 16,
+            bit_depth: bit_depth,
             sample_format: :pcm
           )
         end
 
+        def validate_wav_bit_depth(bit_depth)
+          normalized = bit_depth.to_i
+          return normalized if WAV_BIT_DEPTHS.include?(normalized)
+
+          raise ArgumentError, "Unsupported WAV bit depth: #{bit_depth}"
+        end
+
         def decoder_backend_for(extension)
+          return codec_backend if codec_backend&.respond_to?(:decode)
           return :ffmpeg if executable_available?("ffmpeg")
           return :afconvert if extension == ".mp3" && executable_available?("afconvert")
 
@@ -284,16 +555,20 @@ module Deftones
         end
 
         def encoder_backend_for(format)
+          return codec_backend if codec_backend&.respond_to?(:encode)
           return :ffmpeg if executable_available?("ffmpeg")
           return :afconvert if format == :mp3 && executable_available?("afconvert")
 
           nil
         end
 
-        def decoder_command(backend, input_path, output_path)
+        def decoder_command(backend, input_path, output_path, sample_rate: nil, channels: nil)
           case backend
           when :ffmpeg
-            ["ffmpeg", "-v", "error", "-y", "-i", input_path, "-f", "wav", output_path]
+            command = ["ffmpeg", "-v", "error", "-y", "-i", input_path, "-vn", "-map", "0:a:0", "-acodec", "pcm_f32le"]
+            command += ["-ar", sample_rate.to_i.to_s] if sample_rate
+            command += ["-ac", channels.to_i.to_s] if channels
+            command + ["-f", "wav", output_path]
           when :afconvert
             ["afconvert", "-f", "WAVE", "-d", "LEI16", input_path, output_path]
           else
@@ -301,11 +576,17 @@ module Deftones
           end
         end
 
-        def encoder_command(backend, input_path, output_path, format)
+        def encoder_command(backend, input_path, output_path, format, sample_rate, channels)
           case backend
           when :ffmpeg
             container = format == :ogg ? "ogg" : format.to_s
-            ["ffmpeg", "-v", "error", "-y", "-i", input_path, "-f", container, output_path]
+            sample_format = format == :mp3 ? "s16p" : "s16"
+            codec = format == :mp3 ? "libmp3lame" : "flac"
+            [
+              "ffmpeg", "-v", "error", "-y", "-i", input_path, "-vn", "-map", "0:a:0",
+              "-codec:a", codec, "-sample_fmt", sample_format, "-ar", sample_rate.to_s, "-ac", channels.to_s,
+              "-f", container, output_path
+            ]
           when :afconvert
             raise ArgumentError, "afconvert only supports mp3 export" unless format == :mp3
 
@@ -322,6 +603,30 @@ module Deftones
           end
         end
 
+        def capture_codec_command(*command)
+          Timeout.timeout(codec_timeout || DEFAULT_CODEC_TIMEOUT) do
+            Open3.capture3(*command)
+          end
+        rescue Timeout::Error
+          raise ArgumentError, "Codec command timed out after #{codec_timeout || DEFAULT_CODEC_TIMEOUT} seconds"
+        end
+
+        def custom_codec_backend?(backend)
+          !backend.is_a?(Symbol)
+        end
+
+        def raise_codec_command_error(prefix, command, stdout, stderr, status)
+          detail = [stderr, stdout].map(&:to_s).map(&:strip).reject(&:empty?).first || "unknown codec error"
+          exit_status = status.respond_to?(:exitstatus) && status.exitstatus ? " (exit #{status.exitstatus})" : ""
+          raise Deftones::CodecCommandError.new(
+            "#{prefix}: #{detail}#{exit_status}",
+            command: command,
+            stdout: stdout,
+            stderr: stderr,
+            status: status
+          )
+        end
+
         def missing_decoder_message(extension)
           "No decoder available for #{extension}. Install ffmpeg to enable compressed audio loading."
         end
@@ -330,10 +635,18 @@ module Deftones
           "No encoder available for #{format}. Install ffmpeg to enable compressed audio export."
         end
 
-        def resolve_save_format(path, format)
-          return normalize_format(format) if format
-
+        def resolve_save_format(path, format, on_format_mismatch:)
           extension = File.extname(path).downcase
+          if format
+            normalized = normalize_format(format)
+            expected_extension = ".#{normalized}"
+            if on_format_mismatch == :error && !extension.empty? && extension != expected_extension
+              raise Deftones::UnsupportedAudioFormatError,
+                    "Format #{normalized} does not match file extension #{extension}"
+            end
+            return normalized
+          end
+
           return :mp3 if extension == ".mp3"
           return :ogg if COMPRESSED_EXTENSIONS.include?(extension)
 
@@ -346,6 +659,14 @@ module Deftones
 
           normalized
         end
+
+        def validate_path_string!(path, role:)
+          string = path.to_s
+          raise ArgumentError, "#{role} path must not be empty" if string.empty?
+          raise ArgumentError, "#{role} path contains a null byte" if string.include?("\0")
+
+          true
+        end
       end
     end
   end