wavify 0.1.0 → 0.2.0

data/lib/wavify/codecs/ogg_vorbis.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "stringio"
-require "vorbis"
+require "tempfile"
 
 module Wavify
   module Codecs
@@ -15,6 +15,22 @@ module Wavify
     # resampled to the first logical stream sample rate when rates differ).
     # Interleaved multi-stream OGG logical streams are mixed with clipping.
     class OggVorbis < Base
+      DEPENDENCY_LOAD_ERRORS = begin
+        errors = {}
+        begin
+          require "ogg"
+        rescue LoadError => e
+          errors["ogg-ruby"] = e
+        end
+
+        begin
+          require "vorbis"
+        rescue LoadError => e
+          errors["vorbis"] = e
+        end
+        errors.freeze
+      end
+
       # Recognized filename extensions.
       EXTENSIONS = %w[.ogg .oga].freeze
 
@@ -24,17 +40,44 @@ module Wavify
       SETUP_HEADER_TYPE = 0x05 # :nodoc:
       GRANULE_POSITION_UNKNOWN = 0xFFFF_FFFF_FFFF_FFFF # :nodoc:
       VORBIS_ENCODE_DEFAULT_QUALITY = 0.4 # :nodoc:
+      VORBIS_ENCODE_QUALITY_RANGE = (-0.1..1.0) # :nodoc:
 
       class << self
+        # @return [Boolean]
+        def available?
+          DEPENDENCY_LOAD_ERRORS.empty?
+        end
+
+        def runtime_diagnostics
+          return { available: false, compatible: false, missing: DEPENDENCY_LOAD_ERRORS.keys.freeze } unless available?
+
+          required_native_methods = %i[
+            vorbis_info_init vorbis_info_clear vorbis_comment_init vorbis_comment_clear
+            vorbis_synthesis_headerin vorbis_synthesis_init vorbis_block_init
+            vorbis_synthesis vorbis_synthesis_blockin vorbis_synthesis_pcmout vorbis_synthesis_read
+          ]
+          missing_methods = required_native_methods.reject { |method| Vorbis::Native.respond_to?(method) }
+          {
+            available: true,
+            compatible: missing_methods.empty?,
+            missing_native_methods: missing_methods.freeze,
+            versions: {
+              "ogg-ruby" => Gem.loaded_specs["ogg-ruby"]&.version&.to_s,
+              "vorbis" => Gem.loaded_specs["vorbis"]&.version&.to_s
+            }.freeze
+          }.freeze
+        end
+
         # @param io_or_path [String, IO]
         # @return [Boolean]
         def can_read?(io_or_path)
           return true if io_or_path.is_a?(String) && EXTENSIONS.include?(File.extname(io_or_path).downcase)
           return false unless io_or_path.respond_to?(:read)
 
-          magic = io_or_path.read(4)
-          io_or_path.rewind if io_or_path.respond_to?(:rewind)
+          magic = probe_bytes(io_or_path, 4)
           magic == "OggS"
+        rescue StreamError
+          false
         end
 
         # Reads OGG Vorbis audio.
@@ -43,13 +86,15 @@ module Wavify
         #   OGG logical streams are concatenated and normalized to the first
         #   logical stream format (including resampling). Interleaved
         #   multi-stream OGG logical streams are mixed.
-        #   `decode_mode:` is accepted for API compatibility but has no
-        #   effect; libvorbis always performs full decode.
-        def read(io_or_path, format: nil, decode_mode: :strict)
-          raise InvalidParameterError, "decode_mode must be :strict or :placeholder, got #{decode_mode.inspect}" unless %i[strict
-                                                                                                                           placeholder].include?(decode_mode)
-
-          if (chained_decoded = decode_chained_vorbis_read_if_needed(io_or_path, decode_mode: decode_mode, target_format: format))
+        def read(io_or_path, format: nil, mix_strategy: :clip)
+          ensure_available!
+          mix_strategy = validate_vorbis_mix_strategy!(mix_strategy)
+
+          if (chained_decoded = decode_chained_vorbis_read_if_needed(
+            io_or_path,
+            target_format: format,
+            mix_strategy: mix_strategy
+          ))
             return chained_decoded
           end
 
@@ -61,10 +106,12 @@ module Wavify
         end
 
         # Writes OGG Vorbis audio.
-        def write(io_or_path, sample_buffer, format:)
+        def write(io_or_path, sample_buffer, format:, quality: VORBIS_ENCODE_DEFAULT_QUALITY, **codec_options)
+          ensure_available!
+          validate_no_codec_options!(codec_options, operation: "OGG Vorbis write")
           raise InvalidParameterError, "sample_buffer must be Core::SampleBuffer" unless sample_buffer.is_a?(Core::SampleBuffer)
 
-          stream_write(io_or_path, format: format) do |writer|
+          stream_write(io_or_path, format: format, quality: quality) do |writer|
             writer.call(sample_buffer)
           end
         end
@@ -75,14 +122,22 @@ module Wavify
         #   OGG logical streams are concatenated and normalized to the first
         #   logical stream format during streaming (including resampling).
         #   Interleaved multi-stream OGG logical streams are mixed.
-        #   `decode_mode:` is accepted for API compatibility but has no effect.
-        def stream_read(io_or_path, chunk_size: 4096, decode_mode: :strict, &block)
-          return enum_for(__method__, io_or_path, chunk_size: chunk_size, decode_mode: decode_mode) unless block_given?
+        def stream_read(io_or_path, chunk_size: 4096, mix_strategy: :clip, &block)
+          unless block_given?
+            return enum_for(__method__, io_or_path, chunk_size: chunk_size, mix_strategy: mix_strategy)
+          end
+          ensure_available!
           raise InvalidParameterError, "chunk_size must be a positive Integer" unless chunk_size.is_a?(Integer) && chunk_size.positive?
-          raise InvalidParameterError, "decode_mode must be :strict or :placeholder, got #{decode_mode.inspect}" unless %i[strict
-                                                                                                                           placeholder].include?(decode_mode)
+          mix_strategy = validate_vorbis_mix_strategy!(mix_strategy)
 
-          return nil if stream_chained_vorbis_if_needed(io_or_path, chunk_size: chunk_size, decode_mode: decode_mode, &block)
+          if multistream_ogg_prefix?(io_or_path)
+            return nil if stream_chained_vorbis_if_needed(
+              io_or_path,
+              chunk_size: chunk_size,
+              mix_strategy: mix_strategy,
+              &block
+            )
+          end
 
           decode_context = build_vorbis_decode_context(io_or_path)
           run_vorbis_decode_pipeline(decode_context, streaming: true, chunk_size: chunk_size, &block)
@@ -92,8 +147,13 @@ module Wavify
         #
         # @note Encodes using libvorbis at the default VBR quality level.
         #   Accepts any channel count and sample rate supported by libvorbis.
-        def stream_write(io_or_path, format:)
-          return enum_for(__method__, io_or_path, format: format) unless block_given?
+        def stream_write(io_or_path, format:, quality: VORBIS_ENCODE_DEFAULT_QUALITY, **codec_options)
+          ensure_available!
+          validate_no_codec_options!(codec_options, operation: "OGG Vorbis stream_write")
+          encode_quality = normalize_vorbis_quality(quality)
+          unless block_given?
+            return enum_for(__method__, io_or_path, format: format, quality: quality, **codec_options)
+          end
           raise InvalidParameterError, "format must be Core::Format" unless format.is_a?(Core::Format)
           raise InvalidParameterError, "Vorbis encode requires positive channel count" unless format.channels.to_i.positive?
           raise InvalidParameterError, "Vorbis encode requires positive sample_rate" unless format.sample_rate.to_i.positive?
@@ -106,16 +166,16 @@ module Wavify
           )
 
           io, close_io = open_output(io_or_path)
-          io.rewind if io.respond_to?(:rewind)
-          io.truncate(0) if io.respond_to?(:truncate)
+          prepare_output!(io, owned: close_io)
 
           encoder = Vorbis::Encoder.new(
             channels: target_format.channels,
             rate: target_format.sample_rate,
-            quality: VORBIS_ENCODE_DEFAULT_QUALITY
+            quality: encode_quality
           )
 
-          encoder.write_headers { |page_bytes| io.write(page_bytes) }
+          encoder.write_headers { |page_bytes| write_all(io, page_bytes) }
+          channels_data = Array.new(target_format.channels) { [] }
 
           writer = lambda do |chunk|
             raise InvalidParameterError, "stream chunk must be Core::SampleBuffer" unless chunk.is_a?(Core::SampleBuffer)
@@ -123,19 +183,18 @@ module Wavify
             buffer = chunk.format == target_format ? chunk : chunk.convert(target_format)
             next nil if buffer.sample_frame_count.zero?
 
-            channels_data = Array.new(target_format.channels) { [] }
-            buffer.samples.each_slice(target_format.channels) do |frame|
-              frame.each_with_index { |sample, ch| channels_data[ch] << sample.to_f }
+            channels_data.each(&:clear)
+            buffer.samples.each_with_index do |sample, index|
+              channels_data[index % target_format.channels] << sample.to_f
             end
-            encoder.encode(channels_data) { |page_bytes| io.write(page_bytes) }
+            encoder.encode(channels_data) { |page_bytes| write_all(io, page_bytes) }
           end
 
           yield writer
 
-          encoder.finish { |page_bytes| io.write(page_bytes) }
+          encoder.finish { |page_bytes| write_all(io, page_bytes) }
           encoder.close
-          io.flush if io.respond_to?(:flush)
-          io.rewind if io.respond_to?(:rewind)
+          finalize_output!(io, owned: close_io)
           io_or_path
         rescue StandardError
           begin
@@ -153,13 +212,13 @@ module Wavify
         # @param io_or_path [String, IO]
         # @return [Hash]
         def metadata(io_or_path)
+          ensure_available!
           io, close_io = open_input(io_or_path)
-          ensure_seekable!(io)
-          chained_streams, physical_ogg_info = read_ogg_logical_stream_chains(io)
+          chained_streams, physical_ogg_info = read_ogg_logical_stream_chains(io, storage: :tempfile)
 
           if chained_streams.length > 1
             chain_metadatas = chained_streams.map do |stream|
-              parse_single_logical_stream_metadata(StringIO.new(stream.fetch(:bytes)))
+              parse_single_logical_stream_metadata(logical_stream_io(stream))
             end
             if physical_ogg_info[:interleaved_multistream]
               return merge_interleaved_vorbis_metadata(chain_metadatas, chained_streams, physical_ogg_info)
@@ -168,29 +227,48 @@ module Wavify
             return merge_chained_vorbis_metadata(chain_metadatas, chained_streams)
           end
 
-          parse_single_logical_stream_metadata(StringIO.new(chained_streams.fetch(0).fetch(:bytes)))
+          parse_single_logical_stream_metadata(logical_stream_io(chained_streams.fetch(0)))
         ensure
+          close_logical_streams(chained_streams)
           io.close if close_io && io
         end
 
         private
 
+        def ensure_available!
+          return if available?
+
+          missing = DEPENDENCY_LOAD_ERRORS.keys.join(", ")
+          raise UnsupportedFormatError,
+                "OGG Vorbis support requires optional gems: #{missing}. Add them to your Gemfile to read or write .ogg/.oga files."
+        end
+
+        def normalize_vorbis_quality(quality)
+          unless quality.is_a?(Numeric) && VORBIS_ENCODE_QUALITY_RANGE.cover?(quality.to_f)
+            raise InvalidParameterError, "quality must be Numeric in -0.1..1.0"
+          end
+
+          quality.to_f
+        end
+
         # ---------------------------------------------------------------------------
         # OGG container reading (using ogg-ruby)
         # ---------------------------------------------------------------------------
 
-        def read_ogg_logical_stream_chains_from_input(io_or_path, with_info: false)
+        def read_ogg_logical_stream_chains_from_input(io_or_path, with_info: false, storage: :memory)
           io, close_io = open_input(io_or_path)
-          ensure_seekable!(io)
 
-          chains, physical_info = read_ogg_logical_stream_chains(io)
+          chains, physical_info = read_ogg_logical_stream_chains(io, storage: storage)
           with_info ? [chains, physical_info] : chains
         ensure
           io.close if close_io && io
         end
 
-        def read_ogg_logical_stream_chains(io)
-          io.rewind
+        def read_ogg_logical_stream_chains(io, storage: :memory)
+          unless %i[memory tempfile].include?(storage)
+            raise InvalidParameterError, "OGG logical stream storage must be :memory or :tempfile"
+          end
+
           sync = Ogg::SyncState.new
           streams_by_serial = {}
           total_page_count = 0
@@ -217,7 +295,7 @@ module Wavify
 
                 stream = {
                   serial_number: sn,
-                  bytes: +"",
+                  storage: build_logical_stream_storage(storage),
                   page_count: 0,
                   bos_page_count: 0,
                   eos_page_count: 0,
@@ -225,7 +303,7 @@ module Wavify
                   eos_seen: false,
                   first_physical_page_index: physical_page_index,
                   last_physical_page_index: physical_page_index,
-                  physical_page_indices: []
+                  physical_page_indices: storage == :memory ? [] : nil
                 }
                 streams_by_serial[sn] = stream
               elsif stream[:eos_seen]
@@ -234,14 +312,14 @@ module Wavify
 
               raise InvalidFormatError, "unexpected BOS page in OGG logical stream" if stream[:page_count].positive? && bos
 
-              stream[:bytes] << page.to_s
+              append_logical_stream_page(stream.fetch(:storage), page.to_s)
               stream[:page_count] += 1
               stream[:bos_page_count] += 1 if bos
               stream[:eos_page_count] += 1 if eos
               stream[:continued_page_count] += 1 if continued
               stream[:eos_seen] = true if eos
               stream[:last_physical_page_index] = physical_page_index
-              stream[:physical_page_indices] << physical_page_index
+              stream[:physical_page_indices]&.push(physical_page_index)
 
               total_page_count += 1
               total_bos_page_count += 1 if bos
@@ -275,12 +353,20 @@ module Wavify
           end
 
           result_streams = streams.map do |stream|
-            stream.merge(
-              bytes: stream[:bytes].dup.freeze,
-              interleaved_pages: per_stream_overlap.fetch(stream[:serial_number], false)
-            ).freeze
+            finalize_logical_stream_storage!(stream.fetch(:storage))
+            result = stream.reject { |key, _value| key == :storage }.merge(
+              interleaved_pages: per_stream_overlap.fetch(stream[:serial_number], false),
+              physical_page_indices: (stream[:physical_page_indices] || []).freeze
+            )
+            if storage == :memory
+              result[:bytes] = stream.fetch(:storage).dup.freeze
+            else
+              result[:io] = stream.fetch(:storage)
+            end
+            result.freeze
           end
 
+          completed = true
           [
             result_streams,
             {
@@ -299,6 +385,49 @@ module Wavify
           raise InvalidFormatError, "OGG stream sequence error: #{e.message}"
         ensure
           sync&.clear
+          unless completed
+            close_logical_streams(streams_by_serial&.values&.map { |stream| { io: stream[:storage] } })
+          end
+        end
+
+        def build_logical_stream_storage(storage)
+          return +"".b if storage == :memory
+
+          Tempfile.new(["wavify-ogg-logical-stream", ".ogg"]).tap(&:binmode)
+        end
+
+        def append_logical_stream_page(storage, bytes)
+          if storage.is_a?(String)
+            storage << bytes
+          else
+            write_all(storage, bytes)
+          end
+        end
+
+        def finalize_logical_stream_storage!(storage)
+          return if storage.is_a?(String)
+
+          storage.flush
+          storage.rewind
+        end
+
+        def logical_stream_io(stream)
+          return StringIO.new(stream.fetch(:bytes)) if stream.key?(:bytes)
+
+          io = stream.fetch(:io)
+          io.rewind
+          io
+        end
+
+        def close_logical_streams(streams)
+          Array(streams).each do |stream|
+            io = stream[:io]
+            next unless io.respond_to?(:close!)
+
+            io.close!
+          rescue IOError, SystemCallError
+            nil
+          end
         end
 
         # Reads OGG packets from a single logical stream IO using ogg-ruby.
@@ -307,7 +436,6 @@ module Wavify
         # :data, :kind, :granule_position keys, and ogg_info is a Hash with
         # page-level statistics.
         def read_ogg_packets(io)
-          io.rewind
           sync = Ogg::SyncState.new
           stream_state = nil
           serial_number = nil
@@ -378,15 +506,125 @@ module Wavify
           sync&.clear
         end
 
+        def build_ogg_packet_reader(io)
+          {
+            io: io,
+            sync: Ogg::SyncState.new,
+            stream_state: nil,
+            serial_number: nil,
+            page_count: 0,
+            bos_page_count: 0,
+            eos_page_count: 0,
+            continued_page_count: 0,
+            max_granule_position: nil,
+            input_eof: false,
+            closed: false
+          }
+        end
+
+        def next_ogg_packet!(reader)
+          loop do
+            if (packet = reader[:stream_state]&.packetout)
+              granule_position = packet.granulepos == -1 ? nil : packet.granulepos
+              if granule_position
+                reader[:max_granule_position] = [reader[:max_granule_position] || 0, granule_position].max
+              end
+              return {
+                data: packet.data,
+                bos: packet.bos?,
+                eos: packet.eos?,
+                packetno: packet.packetno,
+                kind: classify_vorbis_packet(packet.data),
+                granule_position: granule_position
+              }
+            end
+
+            if (page = reader.fetch(:sync).pageout)
+              serial_number = page.serialno
+              if reader[:serial_number] && serial_number != reader[:serial_number]
+                raise UnsupportedFormatError, "multiple OGG logical streams require the multistream decoder"
+              end
+              if reader[:page_count].zero? && !page.bos?
+                raise InvalidFormatError, "first OGG page must have BOS flag"
+              end
+
+              reader[:serial_number] ||= serial_number
+              reader[:stream_state] ||= Ogg::StreamState.new(serial_number)
+              reader.fetch(:stream_state).pagein(page)
+              reader[:page_count] += 1
+              reader[:bos_page_count] += 1 if page.bos?
+              reader[:eos_page_count] += 1 if page.eos?
+              reader[:continued_page_count] += 1 if page.continued?
+              next
+            end
+
+            return nil if reader[:input_eof]
+
+            data = reader.fetch(:io).read(4096)
+            if data.nil? || data.empty?
+              reader[:input_eof] = true
+            else
+              reader.fetch(:sync).write(data)
+            end
+          end
+        rescue Ogg::CorruptDataError, Ogg::SyncCorruptDataError => e
+          raise InvalidFormatError, "OGG data corrupt or invalid checksum: #{e.message}"
+        rescue Ogg::StreamCorruptDataError => e
+          raise InvalidFormatError, "OGG stream sequence error: #{e.message}"
+        end
+
+        def close_ogg_packet_reader(reader)
+          return unless reader && !reader[:closed]
+
+          reader[:stream_state]&.clear
+          reader[:sync]&.clear
+          reader[:closed] = true
+        end
+
+        def multistream_ogg_prefix?(io_or_path, probe_size: 4096, tail_probe_size: 65_536)
+          io, close_io = open_input(io_or_path)
+          ensure_seekable!(io)
+          original_position = io.pos
+          bytes = +"".b
+          while bytes.bytesize < probe_size
+            chunk = io.read(probe_size - bytes.bytesize)
+            break if chunk.nil? || chunk.empty?
+
+            bytes << chunk
+          end
+          io.seek(0, IO::SEEK_END)
+          input_end = io.pos
+          tail_start = [original_position + bytes.bytesize, input_end - tail_probe_size].max
+          if tail_start < input_end
+            io.seek(tail_start, IO::SEEK_SET)
+            tail = io.read(tail_probe_size)
+            bytes << tail if tail
+          end
+
+          sync = Ogg::SyncState.new
+          sync.write(bytes)
+          serial_numbers = []
+          while (page = sync.pageout)
+            serial_numbers << page.serialno
+            return true if serial_numbers.uniq.length > 1
+          end
+          false
+        rescue Ogg::CorruptDataError, Ogg::SyncCorruptDataError
+          false
+        ensure
+          sync&.clear
+          io.seek(original_position, IO::SEEK_SET) if original_position && io
+          io.close if close_io && io
+        end
+
         # ---------------------------------------------------------------------------
         # Vorbis decode (using Vorbis::Native synthesis functions)
         # ---------------------------------------------------------------------------
 
         def build_vorbis_decode_context(io_or_path)
           io, close_io = open_input(io_or_path)
-          ensure_seekable!(io)
-
-          packet_entries, ogg_info = read_ogg_packets(io)
+          packet_reader = build_ogg_packet_reader(io)
+          packet_entries = Array.new(3) { next_ogg_packet!(packet_reader) }
           raise InvalidFormatError, "missing Vorbis identification header" if packet_entries[0].nil?
           raise InvalidFormatError, "missing Vorbis comment header" if packet_entries[1].nil?
           raise InvalidFormatError, "missing Vorbis setup header" if packet_entries[2].nil?
@@ -394,7 +632,9 @@ module Wavify
           info_ptr = FFI::MemoryPointer.new(Vorbis::Native::VorbisInfo.size)
           comment_ptr = FFI::MemoryPointer.new(Vorbis::Native::VorbisComment.size)
           Vorbis::Native.vorbis_info_init(info_ptr)
+          info_initialized = true
           Vorbis::Native.vorbis_comment_init(comment_ptr)
+          comment_initialized = true
 
           packet_entries.first(3).each_with_index do |entry, idx|
             pkt = Ogg::Packet.new(
@@ -411,30 +651,34 @@ module Wavify
           channels = vinfo[:channels]
           sample_rate = vinfo[:rate]
 
-          audio_packets = packet_entries.drop(3).select { |e| e.fetch(:kind) == :audio }
-          raise InvalidFormatError, "OGG Vorbis stream does not contain audio packets" if audio_packets.empty?
-
           format = Core::Format.new(channels: channels, sample_rate: sample_rate, bit_depth: 32, sample_format: :float)
 
-          {
+          context = {
             format: format,
             channels: channels,
             sample_rate: sample_rate,
-            audio_packets: audio_packets,
-            sample_frame_count: ogg_info[:max_granule_position],
+            packet_reader: packet_reader,
+            io: io,
+            close_io: close_io,
             info_ptr: info_ptr,
             comment_ptr: comment_ptr
           }
+          ownership_transferred = true
+          context
         ensure
-          io.close if close_io && io
+          unless ownership_transferred
+            Vorbis::Native.vorbis_comment_clear(comment_ptr) if comment_initialized
+            Vorbis::Native.vorbis_info_clear(info_ptr) if info_initialized
+            close_ogg_packet_reader(packet_reader)
+            io.close if close_io && io
+          end
         end
 
         def run_vorbis_decode_pipeline(decode_context, streaming: false, chunk_size: nil, &block)
           info_ptr = decode_context.fetch(:info_ptr)
           comment_ptr = decode_context.fetch(:comment_ptr)
-          audio_packets = decode_context.fetch(:audio_packets)
+          packet_reader = decode_context.fetch(:packet_reader)
           channels = decode_context.fetch(:channels)
-          max_granule = decode_context.fetch(:sample_frame_count)
           format = decode_context.fetch(:format)
 
           dsp_ptr = FFI::MemoryPointer.new(Vorbis::Native::VorbisDspState.size)
@@ -453,10 +697,16 @@ module Wavify
 
           block_initialized = true
 
-          all_samples = []
+          samples = []
+          emitted_sample_count = 0
+          audio_packet_count = 0
+          chunk_sample_count = streaming ? chunk_size * channels : nil
           ptr_size = FFI::Pointer.size
 
-          audio_packets.each do |entry|
+          while (entry = next_ogg_packet!(packet_reader))
+            next unless entry.fetch(:kind) == :audio
+
+            audio_packet_count += 1
             pkt = Ogg::Packet.new(
               data: entry.fetch(:data),
               bos: entry.fetch(:bos, false),
@@ -464,7 +714,11 @@ module Wavify
               granulepos: entry[:granule_position].nil? ? -1 : entry[:granule_position],
               packetno: entry.fetch(:packetno, 0)
             )
-            next unless Vorbis::Native.vorbis_synthesis(block_ptr, pkt.native).zero?
+            synthesis_result = Vorbis::Native.vorbis_synthesis(block_ptr, pkt.native)
+            unless synthesis_result.zero?
+              raise InvalidFormatError,
+                    "Vorbis packet decode failed (packet #{entry.fetch(:packetno)}, code #{synthesis_result})"
+            end
 
             Vorbis::Native.vorbis_synthesis_blockin(dsp_ptr, block_ptr)
 
@@ -473,34 +727,42 @@ module Wavify
               n.times do |i|
                 channels.times do |ch|
                   ch_ptr = ch_array_ptr.get_pointer(ch * ptr_size)
-                  all_samples << ch_ptr.get_float(i * 4)
+                  samples << ch_ptr.get_float(i * 4)
                 end
               end
               Vorbis::Native.vorbis_synthesis_read(dsp_ptr, n)
+
+              while streaming && samples.length > chunk_sample_count
+                chunk_samples = samples.slice!(0, chunk_sample_count)
+                yield Core::SampleBuffer.new(chunk_samples, format)
+                emitted_sample_count += chunk_samples.length
+              end
             end
           end
+          raise InvalidFormatError, "OGG Vorbis stream does not contain audio packets" if audio_packet_count.zero?
 
+          max_granule = packet_reader.fetch(:max_granule_position)
           if max_granule&.positive?
-            target_sample_count = max_granule * channels
-            all_samples = all_samples.first(target_sample_count) if all_samples.length > target_sample_count
+            remaining_sample_count = [(max_granule * channels) - emitted_sample_count, 0].max
+            samples = samples.first(remaining_sample_count) if samples.length > remaining_sample_count
           end
 
-          result_buffer = Core::SampleBuffer.new(all_samples, format)
-
           if streaming && block
-            each_sample_buffer_frame_slice(result_buffer, chunk_size, &block)
+            each_sample_buffer_frame_slice(Core::SampleBuffer.new(samples, format), chunk_size, &block)
             nil
           elsif block
-            yield result_buffer
+            yield Core::SampleBuffer.new(samples, format)
             nil
           else
-            result_buffer
+            Core::SampleBuffer.new(samples, format)
           end
         ensure
           Vorbis::Native.vorbis_block_clear(block_ptr) if block_initialized
           Vorbis::Native.vorbis_dsp_clear(dsp_ptr) if dsp_initialized
           Vorbis::Native.vorbis_comment_clear(comment_ptr) if comment_ptr
           Vorbis::Native.vorbis_info_clear(info_ptr) if info_ptr
+          close_ogg_packet_reader(packet_reader)
+          decode_context[:io].close if decode_context[:close_io] && decode_context[:io]
         end
 
         # ---------------------------------------------------------------------------
@@ -508,15 +770,53 @@ module Wavify
         # ---------------------------------------------------------------------------
 
         def parse_single_logical_stream_metadata(io)
-          packet_entries, ogg_info = read_ogg_packets(io)
-          raise InvalidFormatError, "missing Vorbis identification header" if packet_entries[0].nil?
-          raise InvalidFormatError, "missing Vorbis comment header" if packet_entries[1].nil?
-          raise InvalidFormatError, "missing Vorbis setup header" if packet_entries[2].nil?
+          packet_reader = build_ogg_packet_reader(io)
+          header_entries = []
+          packet_count = 0
+          audio_packet_count = 0
+          non_audio_packet_count = 0
+          audio_packets_with_granule_count = 0
+          first_audio_granule_position = nil
+          last_audio_granule_position = nil
+
+          while (entry = next_ogg_packet!(packet_reader))
+            packet_count += 1
+            if header_entries.length < 3
+              header_entries << entry
+              next
+            end
+
+            if entry.fetch(:kind) == :audio
+              audio_packet_count += 1
+              granule_position = entry[:granule_position]
+              if granule_position
+                audio_packets_with_granule_count += 1
+                first_audio_granule_position ||= granule_position
+                last_audio_granule_position = granule_position
+              end
+            else
+              non_audio_packet_count += 1
+            end
+          end
+          raise InvalidFormatError, "missing Vorbis identification header" if header_entries[0].nil?
+          raise InvalidFormatError, "missing Vorbis comment header" if header_entries[1].nil?
+          raise InvalidFormatError, "missing Vorbis setup header" if header_entries[2].nil?
+
+          ogg_info = {
+            serial_number: packet_reader[:serial_number],
+            page_count: packet_reader[:page_count],
+            max_granule_position: packet_reader[:max_granule_position],
+            bos_page_count: packet_reader[:bos_page_count],
+            eos_page_count: packet_reader[:eos_page_count],
+            continued_page_count: packet_reader[:continued_page_count]
+          }
 
           info_ptr = FFI::MemoryPointer.new(Vorbis::Native::VorbisInfo.size)
           comment_ptr = FFI::MemoryPointer.new(Vorbis::Native::VorbisComment.size)
           Vorbis::Native.vorbis_info_init(info_ptr)
+          info_initialized = true
           Vorbis::Native.vorbis_comment_init(comment_ptr)
+          comment_initialized = true
 
           setup_parsed = false
           saved_channels = nil
@@ -524,7 +824,7 @@ module Wavify
           saved_bitrate_nominal = nil
           saved_bitrate_lower = nil
           saved_bitrate_upper = nil
-          packet_entries.first(3).each_with_index do |entry, index|
+          header_entries.each_with_index do |entry, index|
             pkt = Ogg::Packet.new(
               data: entry.fetch(:data),
               bos: entry.fetch(:bos, index.zero?),
@@ -563,8 +863,11 @@ module Wavify
           end
 
           vc = Vorbis::Native::VorbisComment.new(comment_ptr)
-          vendor = vc[:vendor].null? ? nil : vc[:vendor].read_string
+          vendor = vc[:vendor].null? ? nil : vc[:vendor].read_string.force_encoding(Encoding::UTF_8).scrub
           comments_hash = {}
+          comment_values = Hash.new { |hash, key| hash[key] = [] }
+          raw_comments = []
+          raw_comment_bytes = []
           n_comments = vc[:comments]
           if n_comments.positive? && !vc[:user_comments].null?
             user_comments_ptr = vc[:user_comments]
@@ -577,15 +880,18 @@ module Wavify
               next unless len.positive?
 
               str = str_ptr.read_bytes(len)
-              key, value = str.split("=", 2)
-              comments_hash[key.downcase] = value if key && value
+              raw_comment_bytes << str.b.dup.freeze
+              display = str.force_encoding(Encoding::UTF_8).scrub
+              raw_comments << display
+              key, value = display.split("=", 2)
+              if key && value
+                normalized_key = key.downcase
+                comments_hash[normalized_key] ||= value
+                comment_values[normalized_key] << value
+              end
             end
           end
 
-          audio_packets = packet_entries.drop(3).select { |e| e.fetch(:kind) == :audio }
-          non_audio_packets = packet_entries.drop(3).reject { |e| e.fetch(:kind) == :audio }
-          known_granule_positions = audio_packets.filter_map { |e| e[:granule_position] }
-
           format = Core::Format.new(channels: channels, sample_rate: sample_rate, bit_depth: 32, sample_format: :float)
           sample_frame_count = ogg_info[:max_granule_position]
           duration = sample_frame_count ? Core::Duration.from_samples(sample_frame_count, format.sample_rate) : nil
@@ -593,9 +899,14 @@ module Wavify
           {
             format: format,
             sample_frame_count: sample_frame_count,
+            granule_position_frame_count: sample_frame_count,
+            sample_frame_count_estimated: !sample_frame_count.nil?,
             duration: duration,
             vendor: vendor,
             comments: comments_hash,
+            comment_values: comment_values.transform_values(&:freeze).freeze,
+            raw_comments: raw_comments.freeze,
+            raw_comment_bytes: raw_comment_bytes.freeze,
             nominal_bitrate: nominal_bitrate_raw.positive? ? nominal_bitrate_raw : nil,
             minimum_bitrate: minimum_bitrate_raw.positive? ? minimum_bitrate_raw : nil,
             maximum_bitrate: maximum_bitrate_raw.positive? ? maximum_bitrate_raw : nil,
@@ -603,17 +914,15 @@ module Wavify
             blocksize_large: blocksize_large,
             ogg_serial_number: ogg_info[:serial_number],
             ogg_page_count: ogg_info[:page_count],
-            ogg_packet_count: packet_entries.length,
+            ogg_packet_count: packet_count,
             ogg_bos_page_count: ogg_info[:bos_page_count],
             ogg_eos_page_count: ogg_info[:eos_page_count],
             ogg_continued_page_count: ogg_info[:continued_page_count],
-            vorbis_audio_packet_count: audio_packets.length,
-            vorbis_non_audio_packet_count: non_audio_packets.length,
-            vorbis_audio_packets_with_granule_count: known_granule_positions.length,
-            first_audio_packet_granule_position: audio_packets.find { |e| !e[:granule_position].nil? }&.fetch(:granule_position),
-            last_audio_packet_granule_position: audio_packets.reverse_each.find do |e|
-              !e[:granule_position].nil?
-            end&.fetch(:granule_position),
+            vorbis_audio_packet_count: audio_packet_count,
+            vorbis_non_audio_packet_count: non_audio_packet_count,
+            vorbis_audio_packets_with_granule_count: audio_packets_with_granule_count,
+            first_audio_packet_granule_position: first_audio_granule_position,
+            last_audio_packet_granule_position: last_audio_granule_position,
             vorbis_setup_parsed: setup_parsed,
             vorbis_codebook_count: nil,
             vorbis_codebook_dimensions: nil,
@@ -656,11 +965,12 @@ module Wavify
             vorbis_output_assembly_window_curve_preflight_count: nil,
             vorbis_long_window_packet_count: nil,
             vorbis_short_window_packet_count: nil,
-            setup_header_size: packet_entries[2]&.fetch(:data)&.bytesize
+            setup_header_size: header_entries[2]&.fetch(:data)&.bytesize
           }
         ensure
-          Vorbis::Native.vorbis_comment_clear(comment_ptr) if comment_ptr
-          Vorbis::Native.vorbis_info_clear(info_ptr) if info_ptr
+          Vorbis::Native.vorbis_comment_clear(comment_ptr) if comment_initialized
+          Vorbis::Native.vorbis_info_clear(info_ptr) if info_initialized
+          close_ogg_packet_reader(packet_reader)
         end
 
         # ---------------------------------------------------------------------------
@@ -789,68 +1099,120 @@ module Wavify
         # Chained / interleaved stream decoding (high-level helpers)
         # ---------------------------------------------------------------------------
 
-        def decode_chained_vorbis_read_if_needed(io_or_path, decode_mode:, target_format: nil)
-          chained_streams, physical_ogg_info = read_ogg_logical_stream_chains_from_input(io_or_path, with_info: true)
-          return nil unless chained_streams.length > 1
+        def decode_chained_vorbis_read_if_needed(io_or_path, target_format: nil, mix_strategy: :clip)
+          original_position = io_or_path.pos if !io_or_path.is_a?(String) && io_or_path.respond_to?(:pos)
+          chained_streams, physical_ogg_info = read_ogg_logical_stream_chains_from_input(
+            io_or_path,
+            with_info: true,
+            storage: :tempfile
+          )
+          unless chained_streams.length > 1
+            io_or_path.seek(original_position, IO::SEEK_SET) if original_position && io_or_path.respond_to?(:seek)
+            return nil
+          end
 
           if physical_ogg_info[:interleaved_multistream]
             decoded_buffers = chained_streams.map do |stream|
-              read(StringIO.new(stream.fetch(:bytes)), decode_mode: decode_mode)
+              read(logical_stream_io(stream))
             end
 
-            return mix_vorbis_sample_buffers(decoded_buffers, target_format: target_format)
+            return mix_vorbis_sample_buffers(decoded_buffers, target_format: target_format, strategy: mix_strategy)
           end
 
           decoded_buffers = chained_streams.map do |stream|
-            read(StringIO.new(stream.fetch(:bytes)), format: target_format, decode_mode: decode_mode)
+            read(logical_stream_io(stream), format: target_format)
           end
 
           concatenate_vorbis_sample_buffers(decoded_buffers, target_format: target_format)
+        ensure
+          close_logical_streams(chained_streams)
         end
 
-        def stream_chained_vorbis_if_needed(io_or_path, chunk_size:, decode_mode:, &block)
-          chained_streams, physical_ogg_info = read_ogg_logical_stream_chains_from_input(io_or_path, with_info: true)
+        def stream_chained_vorbis_if_needed(io_or_path, chunk_size:, mix_strategy: :clip, &block)
+          chained_streams, physical_ogg_info = read_ogg_logical_stream_chains_from_input(
+            io_or_path,
+            with_info: true,
+            storage: :tempfile
+          )
           return false unless chained_streams.length > 1
 
           if physical_ogg_info[:interleaved_multistream]
             stream_metadatas = chained_streams.map do |stream|
-              parse_single_logical_stream_metadata(StringIO.new(stream.fetch(:bytes)))
+              parse_single_logical_stream_metadata(logical_stream_io(stream))
             end
             target_format = stream_metadatas.first.fetch(:format)
             return stream_interleaved_vorbis_logical_streams_mixed!(
               chained_streams,
               chunk_size: chunk_size,
-              decode_mode: decode_mode,
               target_format: target_format,
-              stream_metadatas: stream_metadatas, &block
+              stream_metadatas: stream_metadatas,
+              mix_strategy: mix_strategy,
+              &block
             )
           end
 
           stream_metadatas = chained_streams.map do |stream|
-            parse_single_logical_stream_metadata(StringIO.new(stream.fetch(:bytes)))
+            parse_single_logical_stream_metadata(logical_stream_io(stream))
           end
           target_format = stream_metadatas.first.fetch(:format)
           same_sample_rate = stream_metadatas.all? { |metadata| metadata.fetch(:format).sample_rate == target_format.sample_rate }
 
           unless same_sample_rate
-            chained_streams.each do |stream|
-              normalized = normalize_vorbis_logical_stream_buffer_for_target(
-                read(StringIO.new(stream.fetch(:bytes)), decode_mode: decode_mode),
-                target_format
+            chained_streams.zip(stream_metadatas).each do |stream, metadata|
+              stream_vorbis_logical_stream_resampled!(
+                stream,
+                source_format: metadata.fetch(:format),
+                target_format: target_format,
+                chunk_size: chunk_size,
+                &block
               )
-              each_sample_buffer_frame_slice(normalized, chunk_size, &block)
             end
             return true
           end
 
           chained_format = nil
           chained_streams.each do |stream|
-            stream_read(StringIO.new(stream.fetch(:bytes)), chunk_size: chunk_size, decode_mode: decode_mode) do |chunk|
+            stream_read(logical_stream_io(stream), chunk_size: chunk_size) do |chunk|
               chained_format ||= chunk.format
               yield(chunk.format == chained_format ? chunk : chunk.convert(chained_format))
             end
           end
 
+          true
+        ensure
+          close_logical_streams(chained_streams)
+        end
+
+        def stream_vorbis_logical_stream_resampled!(stream, source_format:, target_format:, chunk_size:)
+          return enum_for(
+            __method__,
+            stream,
+            source_format: source_format,
+            target_format: target_format,
+            chunk_size: chunk_size
+          ) unless block_given?
+
+          resampler = build_vorbis_streaming_linear_resampler_state(
+            source_format: source_format,
+            target_sample_rate: target_format.sample_rate
+          )
+          stream_read(logical_stream_io(stream), chunk_size: chunk_size) do |chunk|
+            unless resampler
+              yield(chunk.format == target_format ? chunk : chunk.convert(target_format))
+              next
+            end
+
+            feed_vorbis_streaming_linear_resampler_chunk!(resampler, chunk)
+            while (output = drain_vorbis_streaming_linear_resampler_chunk!(resampler, max_frames: chunk_size))
+              yield(output.format == target_format ? output : output.convert(target_format))
+            end
+          end
+          return true unless resampler
+
+          finish_vorbis_streaming_linear_resampler!(resampler)
+          while (output = drain_vorbis_streaming_linear_resampler_chunk!(resampler, max_frames: chunk_size))
+            yield(output.format == target_format ? output : output.convert(target_format))
+          end
           true
         end
 
@@ -873,7 +1235,7 @@ module Wavify
           end
         end
 
-        def mix_vorbis_sample_buffers(buffers, target_format: nil)
+        def mix_vorbis_sample_buffers(buffers, target_format: nil, strategy: :clip)
           buffers = Array(buffers)
           raise InvalidFormatError, "OGG Vorbis multi-stream decode did not produce any logical streams" if buffers.empty?
 
@@ -895,7 +1257,7 @@ module Wavify
               mixed_samples[index] += sample.to_f
             end
           end
-          mixed_samples.map! { |sample| [[sample, -1.0].max, 1.0].min }
+          apply_vorbis_mix_strategy!(mixed_samples, strategy, source_count: converted.length)
 
           mixed = Core::SampleBuffer.new(mixed_samples, work_format)
           return mixed if mixed.format == resolved_target_format
@@ -903,6 +1265,31 @@ module Wavify
           mixed.convert(resolved_target_format)
         end
 
+        def apply_vorbis_mix_strategy!(samples, strategy, source_count:)
+          strategy = validate_vorbis_mix_strategy!(strategy)
+          case strategy
+          when :clip
+            samples.map! { |sample| sample.clamp(-1.0, 1.0) }
+          when :normalize
+            peak = samples.map(&:abs).max.to_f
+            samples.map! { |sample| sample / peak } if peak > 1.0
+          when :headroom
+            samples.map! { |sample| sample / source_count } if source_count > 1
+          when :soft_limit
+            samples.map! { |sample| Math.tanh(sample) }
+          end
+          samples
+        end
+
+        def validate_vorbis_mix_strategy!(strategy)
+          value = strategy.to_sym
+          return value if %i[clip normalize headroom soft_limit].include?(value)
+
+          raise InvalidParameterError, "mix_strategy must be :clip, :normalize, :headroom, or :soft_limit"
+        rescue NoMethodError
+          raise InvalidParameterError, "mix_strategy must be Symbol/String"
+        end
+
         def normalize_vorbis_logical_stream_buffer_for_target(buffer, target_format)
           raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
           raise InvalidParameterError, "target_format must be Core::Format" unless target_format.is_a?(Core::Format)
@@ -989,18 +1376,18 @@ module Wavify
         def stream_interleaved_vorbis_logical_streams_mixed!(
           chained_streams,
           chunk_size:,
-          decode_mode:,
           target_format: nil,
-          stream_metadatas: nil, &block
+          stream_metadatas: nil,
+          mix_strategy: :clip, &block
         )
           unless block_given?
             return enum_for(
               __method__,
               chained_streams,
               chunk_size: chunk_size,
-              decode_mode: decode_mode,
               target_format: target_format,
-              stream_metadatas: stream_metadatas
+              stream_metadatas: stream_metadatas,
+              mix_strategy: mix_strategy
             )
           end
 
@@ -1023,16 +1410,15 @@ module Wavify
                 stream_metadatas: metadatas,
                 target_format: resolved_target_format,
                 chunk_size: chunk_size,
-                decode_mode: decode_mode, &block
+                mix_strategy: mix_strategy, &block
               )
             end
           end
 
           enumerators = streams.map do |stream|
             stream_read(
-              StringIO.new(stream.fetch(:bytes)),
-              chunk_size: chunk_size,
-              decode_mode: decode_mode
+              logical_stream_io(stream),
+              chunk_size: chunk_size
             )
           end
           loop do
@@ -1044,7 +1430,7 @@ module Wavify
             active_chunks = chunks.compact
             break if active_chunks.empty?
 
-            yield mix_vorbis_sample_buffers(active_chunks)
+            yield mix_vorbis_sample_buffers(active_chunks, strategy: mix_strategy)
           end
 
           true
@@ -1055,7 +1441,7 @@ module Wavify
           stream_metadatas:,
           target_format:,
           chunk_size:,
-          decode_mode:
+          mix_strategy: :clip
         )
           unless block_given?
             return enum_for(
@@ -1064,7 +1450,7 @@ module Wavify
               stream_metadatas: stream_metadatas,
               target_format: target_format,
               chunk_size: chunk_size,
-              decode_mode: decode_mode
+              mix_strategy: mix_strategy
             )
           end
 
@@ -1077,9 +1463,8 @@ module Wavify
           stream_states = streams.zip(metadatas).map do |stream, _metadata|
             {
               enumerator: stream_read(
-                StringIO.new(stream.fetch(:bytes)),
-                chunk_size: chunk_size,
-                decode_mode: decode_mode
+                logical_stream_io(stream),
+                chunk_size: chunk_size
               ),
               source_eof: false,
               pending_samples: [],
@@ -1116,7 +1501,7 @@ module Wavify
             mixed_inputs = stream_states.map do |stream_state|
               take_vorbis_interleaved_stream_pending_chunk!(stream_state, frame_count: emit_frames)
             end.compact
-            yield mix_vorbis_sample_buffers(mixed_inputs, target_format: target_work_format)
+            yield mix_vorbis_sample_buffers(mixed_inputs, target_format: target_work_format, strategy: mix_strategy)
           end
 
           true
@@ -1416,31 +1801,6 @@ module Wavify
           :unknown
         end
 
-        # ---------------------------------------------------------------------------
-        # IO helpers
-        # ---------------------------------------------------------------------------
-
-        def open_input(io_or_path)
-          return [io_or_path, false] if io_or_path.respond_to?(:read)
-          raise InvalidParameterError, "input path must be String or IO: #{io_or_path.inspect}" unless io_or_path.is_a?(String)
-
-          [File.open(io_or_path, "rb"), true]
-        rescue Errno::ENOENT
-          raise InvalidFormatError, "input file not found: #{io_or_path}"
-        end
-
-        def open_output(io_or_path)
-          return [io_or_path, false] if io_or_path.respond_to?(:write)
-          raise InvalidParameterError, "output path must be String or IO: #{io_or_path.inspect}" unless io_or_path.is_a?(String)
-
-          [File.open(io_or_path, "wb"), true]
-        end
-
-        def ensure_seekable!(io)
-          return if io.respond_to?(:seek) && io.respond_to?(:rewind)
-
-          raise StreamError, "OGG Vorbis codec requires seekable IO"
-        end
       end
     end
   end