wavify 0.1.0 → 0.2.0

data/lib/wavify/codecs/flac.rb

@@ -9,10 +9,13 @@ module Wavify
       # Recognized filename extensions.
       EXTENSIONS = %w[.flac].freeze
       STREAMINFO_BLOCK_TYPE = 0 # :nodoc:
+      SEEKTABLE_BLOCK_TYPE = 3 # :nodoc:
+      VORBIS_COMMENT_BLOCK_TYPE = 4 # :nodoc:
       STREAMINFO_LENGTH = 34 # :nodoc:
       FLAC_SYNC_CODE = 0x3FFE # :nodoc:
       # Default block size used by the FLAC stream encoder.
       DEFAULT_ENCODE_BLOCK_SIZE = 4096
+      COMPRESSION_BLOCK_SIZES = [1024, 2048, 4096, 4096, 4096, 8192, 8192, 16_384, 16_384].freeze # :nodoc:
 
       BLOCK_SIZE_CODES = { # :nodoc:
         1 => 192,
@@ -52,12 +55,18 @@ module Wavify
         6 => 24
       }.freeze
 
+      # Bounds malicious unary/Rice runs before they can consume unbounded CPU.
+      MAX_UNARY_ZERO_RUN = 1_048_576
+
       # Internal bit reader used by the FLAC decoder.
       class BitReader # :nodoc:
+        attr_reader :captured_bytes
+
         def initialize(io)
           @io = io
           @buffer = 0
           @bits_available = 0
+          @captured_bytes = +"".b
         end
 
         def read_bits(count)
@@ -100,6 +109,7 @@ module Wavify
           byte = @io.read(1)
           raise InvalidFormatError, "truncated FLAC frame" if byte.nil?
 
+          @captured_bytes << byte
           @buffer = byte.getbyte(0)
           @bits_available = 8
         end
@@ -108,7 +118,7 @@ module Wavify
       # Internal bit writer used by the FLAC encoder.
       class BitWriter # :nodoc:
         def initialize
-          @bytes = []
+          @bytes = +"".b
           @buffer = 0
           @bits_used = 0
         end
@@ -117,11 +127,13 @@ module Wavify
           raise InvalidParameterError, "bit count must be a non-negative Integer" unless count.is_a?(Integer) && count >= 0
           return if count.zero?
 
-          count.times do |shift_index|
-            shift = (count - 1) - shift_index
-            bit = (value >> shift) & 0x1
-            @buffer = (@buffer << 1) | bit
-            @bits_used += 1
+          remaining = count
+          while remaining.positive?
+            take = [8 - @bits_used, remaining].min
+            shift = remaining - take
+            @buffer = (@buffer << take) | ((value >> shift) & ((1 << take) - 1))
+            @bits_used += take
+            remaining -= take
             flush_byte_if_needed
           end
         end
@@ -132,7 +144,27 @@ module Wavify
         end
 
         def write_unary_zeros_then_one(zero_count) # :nodoc:
-          zero_count.times { write_bits(0, 1) }
+          unless zero_count.is_a?(Integer) && zero_count.between?(0, MAX_UNARY_ZERO_RUN)
+            raise InvalidParameterError, "FLAC unary zero run exceeds resource limit"
+          end
+
+          if @bits_used.positive?
+            fill = [8 - @bits_used, zero_count].min
+            @buffer <<= fill
+            @bits_used += fill
+            zero_count -= fill
+            flush_byte_if_needed
+          end
+
+          if @bits_used.zero? && zero_count >= 8
+            whole_bytes, zero_count = zero_count.divmod(8)
+            @bytes << ("\x00".b * whole_bytes)
+          end
+
+          if zero_count.positive?
+            @buffer <<= zero_count
+            @bits_used += zero_count
+          end
           write_bits(1, 1)
         end
 
@@ -156,7 +188,7 @@ module Wavify
 
         def to_s # :nodoc:
           align_to_byte
-          @bytes.pack("C*")
+          @bytes.dup
         end
 
         private
@@ -177,9 +209,10 @@ module Wavify
           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 == "fLaC"
+        rescue StreamError
+          false
         end
 
         # Reads a FLAC stream and returns decoded samples.
@@ -189,7 +222,6 @@ module Wavify
         # @return [Wavify::Core::SampleBuffer]
         def read(io_or_path, format: nil)
           io, close_io = open_input(io_or_path)
-          ensure_seekable!(io)
 
           metadata = parse_metadata(io)
           source_format = metadata.fetch(:format)
@@ -205,22 +237,28 @@ module Wavify
         # @param io_or_path [String, IO]
         # @param sample_buffer [Wavify::Core::SampleBuffer]
         # @param format [Wavify::Core::Format]
+        # @param block_size [Integer]
         # @return [String, IO]
-        def write(io_or_path, sample_buffer, format:)
+        def write(io_or_path, sample_buffer, format:, block_size: DEFAULT_ENCODE_BLOCK_SIZE, compression_level: nil,
+                  comments: nil, stereo_coding: :auto, predictor: :auto, **codec_options)
+          validate_no_codec_options!(codec_options, operation: "FLAC write")
           raise InvalidParameterError, "sample_buffer must be Core::SampleBuffer" unless sample_buffer.is_a?(Core::SampleBuffer)
 
           target_format = validate_encode_format!(format)
           buffer = sample_buffer.format == target_format ? sample_buffer : sample_buffer.convert(target_format)
-
-          io, close_io = open_output(io_or_path)
-          io.rewind if io.respond_to?(:rewind)
-          io.truncate(0) if io.respond_to?(:truncate)
-          io.write(encode_verbatim_stream(buffer, target_format))
-          io.flush if io.respond_to?(:flush)
-          io.rewind if io.respond_to?(:rewind)
-          io_or_path
-        ensure
-          io.close if close_io && io
+          target_block_size = normalize_write_block_size(block_size, compression_level)
+          vorbis_comments = normalize_vorbis_comments(comments)
+          normalized_stereo_coding = normalize_stereo_coding!(stereo_coding)
+          normalized_predictor = normalize_predictor!(predictor)
+          stream_write(
+            io_or_path,
+            format: target_format,
+            block_size: target_block_size,
+            block_size_strategy: :fixed,
+            comments: vorbis_comments,
+            stereo_coding: normalized_stereo_coding,
+            predictor: normalized_predictor
+          ) { |writer| writer.call(buffer) }
         end
 
         # Streams FLAC decoding as chunked sample buffers.
@@ -233,22 +271,29 @@ module Wavify
           raise InvalidParameterError, "chunk_size must be a positive Integer" unless chunk_size.is_a?(Integer) && chunk_size.positive?
 
           io, close_io = open_input(io_or_path)
-          ensure_seekable!(io)
 
           metadata = parse_metadata(io)
           format = metadata.fetch(:format)
           chunk_sample_count = chunk_size * format.channels
           pending_samples = []
+          pending_offset = 0
 
           each_decoded_frame_samples(io, metadata) do |frame_samples|
             pending_samples.concat(frame_samples)
 
-            while pending_samples.length >= chunk_sample_count
-              yield Core::SampleBuffer.new(pending_samples.shift(chunk_sample_count), format)
+            while (pending_samples.length - pending_offset) >= chunk_sample_count
+              yield Core::SampleBuffer.new(pending_samples.slice(pending_offset, chunk_sample_count), format)
+              pending_offset += chunk_sample_count
+            end
+
+            if pending_offset >= chunk_sample_count * 8
+              pending_samples = pending_samples.slice(pending_offset, pending_samples.length - pending_offset) || []
+              pending_offset = 0
             end
           end
 
-          yield Core::SampleBuffer.new(pending_samples, format) unless pending_samples.empty?
+          remaining = pending_samples.length - pending_offset
+          yield Core::SampleBuffer.new(pending_samples.slice(pending_offset, remaining), format) if remaining.positive?
         ensure
           io.close if close_io && io
         end
@@ -260,71 +305,94 @@ module Wavify
         # @param block_size [Integer]
         # @param block_size_strategy [Symbol] `:per_chunk`, `:fixed`, or `:source_chunk`
         # @return [Enumerator, String, IO]
-        def stream_write(io_or_path, format:, block_size: DEFAULT_ENCODE_BLOCK_SIZE, block_size_strategy: :per_chunk)
+        def stream_write(io_or_path, format:, block_size: DEFAULT_ENCODE_BLOCK_SIZE, block_size_strategy: :per_chunk,
+                         compression_level: nil, comments: nil, stereo_coding: :auto, predictor: :auto, **codec_options)
+          validate_no_codec_options!(codec_options, operation: "FLAC stream_write")
           unless block_given?
             return enum_for(
               __method__,
               io_or_path,
               format: format,
               block_size: block_size,
-              block_size_strategy: block_size_strategy
+              block_size_strategy: block_size_strategy,
+              compression_level: compression_level,
+              comments: comments,
+              stereo_coding: stereo_coding,
+              predictor: predictor,
+              **codec_options
             )
           end
 
           target_format = validate_encode_format!(format)
-          stream_write_options = normalize_stream_write_options(block_size, block_size_strategy)
+          stream_write_options = normalize_stream_write_options(block_size, block_size_strategy, compression_level)
+          vorbis_comments = normalize_vorbis_comments(comments)
+          normalized_stereo_coding = normalize_stereo_coding!(stereo_coding)
+          normalized_predictor = normalize_predictor!(predictor)
           io, close_io = open_output(io_or_path)
           ensure_seekable!(io)
-          io.rewind if io.respond_to?(:rewind)
-          io.truncate(0) if io.respond_to?(:truncate)
+          prepare_output!(io, owned: close_io)
 
-          header = write_stream_header(io)
+          header = write_stream_header(io, comments: vorbis_comments)
           total_sample_frames = 0
           next_frame_number = 0
           encode_stats = empty_encode_stats
           header[:md5] = Digest::MD5.new
           pending_samples = []
+          pending_offset = 0
 
           writer = lambda do |chunk|
             raise InvalidParameterError, "stream chunk must be Core::SampleBuffer" unless chunk.is_a?(Core::SampleBuffer)
 
             buffer = chunk.format == target_format ? chunk : chunk.convert(target_format)
-            header.fetch(:md5).update(pcm_bytes_for_md5(buffer.samples, target_format))
+            encoded_samples = unalign_encoded_samples(buffer.samples, target_format)
+            header.fetch(:md5).update(flac_md5_bytes(encoded_samples, target_format.valid_bits))
             total_sample_frames += buffer.sample_frame_count
 
             if stream_write_options[:strategy] == :fixed
-              pending_samples.concat(buffer.samples)
+              pending_samples.concat(encoded_samples)
               fixed_chunk_sample_count = stream_write_options.fetch(:block_size) * target_format.channels
 
-              while pending_samples.length >= fixed_chunk_sample_count
+              while (pending_samples.length - pending_offset) >= fixed_chunk_sample_count
                 encoded = encode_verbatim_frames(
-                  pending_samples.shift(fixed_chunk_sample_count),
+                  pending_samples.slice(pending_offset, fixed_chunk_sample_count),
                   target_format,
                   start_frame_number: next_frame_number,
-                  block_size: stream_write_options.fetch(:block_size)
+                  block_size: stream_write_options.fetch(:block_size),
+                  stereo_coding: normalized_stereo_coding,
+                  predictor: normalized_predictor
                 )
-                io.write(encoded.fetch(:bytes))
+                write_all(io, encoded.fetch(:bytes))
                 next_frame_number = encoded.fetch(:next_frame_number)
                 merge_encode_stats!(encode_stats, encoded)
+                pending_offset += fixed_chunk_sample_count
+              end
+
+              if pending_offset >= fixed_chunk_sample_count * 8
+                pending_samples = pending_samples.slice(pending_offset, pending_samples.length - pending_offset) || []
+                pending_offset = 0
               end
             elsif stream_write_options[:strategy] == :source_chunk
               encoded = encode_verbatim_frames(
-                buffer.samples,
+                encoded_samples,
                 target_format,
                 start_frame_number: next_frame_number,
-                block_size: buffer.sample_frame_count
+                block_size: buffer.sample_frame_count,
+                stereo_coding: normalized_stereo_coding,
+                predictor: normalized_predictor
               )
-              io.write(encoded.fetch(:bytes))
+              write_all(io, encoded.fetch(:bytes))
               next_frame_number = encoded.fetch(:next_frame_number)
               merge_encode_stats!(encode_stats, encoded)
             else
               encoded = encode_verbatim_frames(
-                buffer.samples,
+                encoded_samples,
                 target_format,
                 start_frame_number: next_frame_number,
-                block_size: stream_write_options.fetch(:block_size)
+                block_size: stream_write_options.fetch(:block_size),
+                stereo_coding: normalized_stereo_coding,
+                predictor: normalized_predictor
               )
-              io.write(encoded.fetch(:bytes))
+              write_all(io, encoded.fetch(:bytes))
               next_frame_number = encoded.fetch(:next_frame_number)
               merge_encode_stats!(encode_stats, encoded)
             end
@@ -332,21 +400,23 @@ module Wavify
 
           yield writer
 
-          unless pending_samples.empty?
+          remaining = pending_samples.length - pending_offset
+          if remaining.positive?
             encoded = encode_verbatim_frames(
-              pending_samples,
+              pending_samples.slice(pending_offset, remaining),
               target_format,
               start_frame_number: next_frame_number,
-              block_size: stream_write_options.fetch(:block_size)
+              block_size: stream_write_options.fetch(:block_size),
+              stereo_coding: normalized_stereo_coding,
+              predictor: normalized_predictor
             )
-            io.write(encoded.fetch(:bytes))
+            write_all(io, encoded.fetch(:bytes))
             next_frame_number = encoded.fetch(:next_frame_number)
             merge_encode_stats!(encode_stats, encoded)
           end
 
           finalize_stream_header(io, header, target_format, total_sample_frames, encode_stats)
-          io.flush if io.respond_to?(:flush)
-          io.rewind if io.respond_to?(:rewind)
+          finalize_output!(io, owned: close_io)
           io_or_path
         ensure
           io.close if close_io && io
@@ -358,7 +428,6 @@ module Wavify
         # @return [Hash]
         def metadata(io_or_path)
           io, close_io = open_input(io_or_path)
-          ensure_seekable!(io)
 
           parse_metadata(io)
         ensure
@@ -368,11 +437,12 @@ module Wavify
         private
 
         def parse_metadata(io)
-          io.rewind
           marker = read_exact(io, 4, "missing FLAC stream marker")
           raise InvalidFormatError, "invalid FLAC stream marker" unless marker == "fLaC"
 
           streaminfo = nil
+          seektable = nil
+          vorbis_comment = nil
           loop do
             header = read_exact(io, 4, "truncated FLAC metadata block header")
             byte0 = header.getbyte(0)
@@ -381,13 +451,29 @@ module Wavify
             length = ((header.getbyte(1) << 16) | (header.getbyte(2) << 8) | header.getbyte(3))
             data = read_exact(io, length, "truncated FLAC metadata block")
 
-            streaminfo = parse_streaminfo(data) if block_type == STREAMINFO_BLOCK_TYPE
+            case block_type
+            when STREAMINFO_BLOCK_TYPE
+              streaminfo = parse_streaminfo(data)
+            when SEEKTABLE_BLOCK_TYPE
+              seektable = parse_seektable(data)
+            when VORBIS_COMMENT_BLOCK_TYPE
+              vorbis_comment = parse_vorbis_comment(data)
+            end
             break if last_block
           end
 
           raise InvalidFormatError, "STREAMINFO metadata block missing" unless streaminfo
 
-          streaminfo
+          streaminfo.merge(
+            seektable: seektable,
+            seekpoints: seektable&.fetch(:points) || [],
+            vorbis_comment: vorbis_comment,
+            vendor: vorbis_comment&.fetch(:vendor),
+            comments: vorbis_comment&.fetch(:comments) || {},
+            comment_values: vorbis_comment&.fetch(:comment_values) || {},
+            raw_comments: vorbis_comment&.fetch(:raw) || [],
+            raw_comment_bytes: vorbis_comment&.fetch(:raw_bytes) || []
+          )
         end
 
         def parse_streaminfo(data)
@@ -400,19 +486,26 @@ module Wavify
           packed = data[10, 8].unpack1("Q>")
           sample_rate = (packed >> 44) & 0xFFFFF
           channels = ((packed >> 41) & 0x7) + 1
-          bit_depth = ((packed >> 36) & 0x1F) + 1
+          encoded_bit_depth = ((packed >> 36) & 0x1F) + 1
           total_samples = packed & 0xFFFFFFFFF
           md5 = data[18, 16].unpack1("H*")
+          container_bit_depth = [8, 16, 24, 32].find { |depth| depth >= encoded_bit_depth }
+          unless container_bit_depth
+            raise UnsupportedFormatError, "unsupported FLAC sample size: #{encoded_bit_depth} bits"
+          end
 
           format = Core::Format.new(
             channels: channels,
             sample_rate: sample_rate,
-            bit_depth: bit_depth,
-            sample_format: :pcm
+            bit_depth: container_bit_depth,
+            sample_format: :pcm,
+            valid_bits: encoded_bit_depth
           )
 
           {
             format: format,
+            encoded_bit_depth: encoded_bit_depth,
+            container_bit_depth: container_bit_depth,
             sample_frame_count: total_samples,
             duration: Core::Duration.from_samples(total_samples, sample_rate),
             min_block_size: min_block_size,
@@ -423,12 +516,75 @@ module Wavify
           }
         end
 
-        def encode_verbatim_stream(buffer, format)
+        def parse_seektable(data)
+          raise InvalidFormatError, "SEEKTABLE block size must be a multiple of 18" unless (data.bytesize % 18).zero?
+
+          points = data.bytes.each_slice(18).map do |bytes|
+            block = bytes.pack("C*")
+            sample_number = block[0, 8].unpack1("Q>")
+            {
+              sample_number: sample_number,
+              stream_offset: block[8, 8].unpack1("Q>"),
+              frame_samples: block[16, 2].unpack1("n"),
+              placeholder: sample_number == 0xFFFF_FFFF_FFFF_FFFF
+            }
+          end
+          { points: points }
+        end
+
+        def parse_vorbis_comment(data)
+          offset = 0
+          vendor, offset = read_vorbis_comment_string(data, offset, "vendor")
+          comment_count, offset = read_vorbis_comment_uint32(data, offset, "comment count")
+
+          raw = []
+          raw_bytes = []
+          comments = {}
+          comment_values = Hash.new { |hash, key| hash[key] = [] }
+          comment_count.times do
+            text, offset = read_vorbis_comment_string(data, offset, "comment")
+            raw_bytes << text.b.dup.freeze
+            display_text = text.scrub
+            raw << display_text
+            key, value = display_text.split("=", 2)
+            if key && value
+              normalized_key = key.downcase
+              comments[normalized_key] ||= value
+              comment_values[normalized_key] << value
+            end
+          end
+
+          {
+            vendor: vendor.scrub,
+            raw: raw.freeze,
+            raw_bytes: raw_bytes.freeze,
+            comments: comments.freeze,
+            comment_values: comment_values.transform_values(&:freeze).freeze
+          }
+        end
+
+        def read_vorbis_comment_uint32(data, offset, label)
+          raise InvalidFormatError, "truncated Vorbis Comment #{label}" if offset + 4 > data.bytesize
+
+          [data.byteslice(offset, 4).unpack1("V"), offset + 4]
+        end
+
+        def read_vorbis_comment_string(data, offset, label)
+          length, offset = read_vorbis_comment_uint32(data, offset, "#{label} length")
+          raise InvalidFormatError, "truncated Vorbis Comment #{label}" if offset + length > data.bytesize
+
+          [data.byteslice(offset, length).force_encoding(Encoding::UTF_8), offset + length]
+        end
+
+        def encode_verbatim_stream(buffer, format, block_size: DEFAULT_ENCODE_BLOCK_SIZE, comments: nil,
+                                   stereo_coding: :auto, predictor: :auto)
           encoded_frames = encode_verbatim_frames(
             buffer.samples,
             format,
             start_frame_number: 0,
-            block_size: DEFAULT_ENCODE_BLOCK_SIZE
+            block_size: block_size,
+            stereo_coding: stereo_coding,
+            predictor: predictor
           )
           md5_hex = pcm_md5_hex(buffer.samples, format)
 
@@ -440,24 +596,35 @@ module Wavify
           )
 
           bytes = +"fLaC"
-          bytes << [0x80, 0x00, 0x00, STREAMINFO_LENGTH].pack("C4")
+          bytes << metadata_block_header(STREAMINFO_BLOCK_TYPE, STREAMINFO_LENGTH, last: comments.nil?)
           bytes << streaminfo
+          if comments
+            comment_block = build_vorbis_comment_block(comments)
+            bytes << metadata_block_header(VORBIS_COMMENT_BLOCK_TYPE, comment_block.bytesize, last: true)
+            bytes << comment_block
+          end
           bytes << encoded_frames.fetch(:bytes)
           bytes
         end
 
-        def write_stream_header(io)
-          io.write("fLaC")
-          io.write([0x80, 0x00, 0x00, STREAMINFO_LENGTH].pack("C4"))
+        def write_stream_header(io, comments: nil)
+          write_all(io, "fLaC")
+          write_all(io, metadata_block_header(STREAMINFO_BLOCK_TYPE, STREAMINFO_LENGTH, last: comments.nil?))
           streaminfo_offset = io.pos
-          io.write("\x00" * STREAMINFO_LENGTH)
+          write_all(io, "\x00" * STREAMINFO_LENGTH)
+          if comments
+            comment_block = build_vorbis_comment_block(comments)
+            write_all(io, metadata_block_header(VORBIS_COMMENT_BLOCK_TYPE, comment_block.bytesize, last: true))
+            write_all(io, comment_block)
+          end
           { streaminfo_offset: streaminfo_offset }
         end
 
         def finalize_stream_header(io, header, format, total_sample_frames, encode_stats)
           file_end = io.pos
           io.seek(header.fetch(:streaminfo_offset), IO::SEEK_SET)
-          io.write(
+          write_all(
+            io,
             build_streaminfo_bytes(
               format: format,
               sample_frame_count: total_sample_frames,
@@ -477,7 +644,96 @@ module Wavify
           }
         end
 
-        def normalize_stream_write_options(block_size, block_size_strategy)
+        def metadata_block_header(block_type, length, last:)
+          [block_type | (last ? 0x80 : 0), (length >> 16) & 0xFF, (length >> 8) & 0xFF, length & 0xFF].pack("C4")
+        end
+
+        def build_vorbis_comment_block(comments)
+          vendor = "Wavify"
+          entries = comments.map do |entry|
+            key, value = entry.split("=", 2)
+            "#{key.upcase}=#{value}"
+          end
+          bytes = [vendor.bytesize].pack("V") + vendor + [entries.length].pack("V")
+          entries.each do |entry|
+            bytes << [entry.bytesize].pack("V")
+            bytes << entry
+          end
+          bytes
+        end
+
+        def normalize_vorbis_comments(comments)
+          return nil if comments.nil?
+
+          normalized = case comments
+                       when Hash
+                         comments.flat_map do |key, value|
+                           Array(value).map { |entry| normalize_vorbis_comment_entry(key, entry) }
+                         end
+                       when Array
+                         comments.map do |entry|
+                           key, value = entry.to_s.split("=", 2)
+                           raise InvalidParameterError, "FLAC comments must be KEY=VALUE strings" unless key && value
+
+                           normalize_vorbis_comment_entry(key, value)
+                         end
+                       else
+                         raise InvalidParameterError, "comments must be a Hash or Array"
+                       end
+          normalized.empty? ? nil : normalized
+        end
+
+        def normalize_vorbis_comment_entry(key, value)
+          field_name = key.to_s
+          unless field_name.match?(/\A[\x20-\x3C\x3E-\x7D]+\z/)
+            raise InvalidParameterError, "FLAC comment field names must be printable ASCII without '='"
+          end
+
+          text = value.to_s.encode(Encoding::UTF_8)
+          raise InvalidParameterError, "FLAC comment values must be valid UTF-8" unless text.valid_encoding?
+
+          "#{field_name}=#{text}"
+        rescue EncodingError
+          raise InvalidParameterError, "FLAC comment values must be valid UTF-8"
+        end
+
+        def normalize_stereo_coding!(stereo_coding)
+          value = stereo_coding.to_sym
+          return value if %i[auto independent mid_side].include?(value)
+
+          raise InvalidParameterError, "stereo_coding must be :auto, :independent, or :mid_side"
+        rescue NoMethodError
+          raise InvalidParameterError, "stereo_coding must be Symbol/String"
+        end
+
+        def normalize_predictor!(predictor)
+          value = predictor.to_sym
+          return value if %i[auto fixed lpc verbatim].include?(value)
+
+          raise InvalidParameterError, "predictor must be :auto, :fixed, :lpc, or :verbatim"
+        rescue NoMethodError
+          raise InvalidParameterError, "predictor must be Symbol/String"
+        end
+
+        def normalize_write_block_size(block_size, compression_level)
+          level = normalize_compression_level(compression_level)
+          return normalize_encode_block_size(block_size) unless level && block_size == DEFAULT_ENCODE_BLOCK_SIZE
+
+          normalize_encode_block_size(COMPRESSION_BLOCK_SIZES.fetch(level))
+        end
+
+        def normalize_compression_level(compression_level)
+          return nil if compression_level.nil?
+
+          level = Integer(compression_level)
+          return level if level.between?(0, 8)
+
+          raise InvalidParameterError, "compression_level must be in 0..8"
+        rescue ArgumentError, TypeError
+          raise InvalidParameterError, "compression_level must be an Integer"
+        end
+
+        def normalize_stream_write_options(block_size, block_size_strategy, compression_level = nil)
           strategy = block_size_strategy.to_sym
           supported = %i[per_chunk source_chunk fixed]
           unless supported.include?(strategy)
@@ -486,7 +742,7 @@ module Wavify
 
           {
             strategy: strategy,
-            block_size: normalize_encode_block_size(block_size)
+            block_size: normalize_write_block_size(block_size, compression_level)
           }
         rescue NoMethodError
           raise InvalidParameterError, "block_size_strategy must be Symbol/String: #{block_size_strategy.inspect}"
@@ -507,7 +763,8 @@ module Wavify
           aggregate[:max_frame_size] = [aggregate[:max_frame_size], current_max_frame].max
         end
 
-        def encode_verbatim_frames(interleaved_samples, format, start_frame_number:, block_size:)
+        def encode_verbatim_frames(interleaved_samples, format, start_frame_number:, block_size:, stereo_coding: :auto,
+                                   predictor: :auto)
           channels = format.channels
           samples_per_frame = channels * normalize_encode_block_size(block_size)
           bytes = +""
@@ -516,7 +773,13 @@ module Wavify
           frame_sizes = []
 
           interleaved_samples.each_slice(samples_per_frame) do |frame_samples|
-            encoded_frame = encode_pcm_frame(frame_samples, format, frame_number: frame_number)
+            encoded_frame = encode_pcm_frame(
+              frame_samples,
+              format,
+              frame_number: frame_number,
+              stereo_coding: stereo_coding,
+              predictor: predictor
+            )
             bytes << encoded_frame
             block_sizes << (frame_samples.length / channels)
             frame_sizes << encoded_frame.bytesize
@@ -533,25 +796,47 @@ module Wavify
           }
         end
 
-        def encode_pcm_frame(interleaved_samples, format, frame_number:)
+        def encode_pcm_frame(interleaved_samples, format, frame_number:, stereo_coding:, predictor:)
           channels = format.channels
           block_size = interleaved_samples.length / channels
           raise InvalidParameterError, "FLAC frame block size must be positive" if block_size <= 0
 
           block_size_code, block_size_extra_bits = encode_block_size_descriptor(block_size)
           channel_samples = deinterleave_samples(interleaved_samples, channels)
+          candidates = frame_channel_candidates(channel_samples, format, stereo_coding)
+
+          encoded_candidates = candidates.map do |candidate|
+            encode_pcm_frame_candidate(
+              candidate,
+              block_size: block_size,
+              block_size_code: block_size_code,
+              block_size_extra_bits: block_size_extra_bits,
+              frame_number: frame_number,
+              predictor: predictor
+            )
+          end
+          selected = if stereo_coding == :auto
+                       encoded_candidates.min_by(&:bytesize)
+                     else
+                       encoded_candidates.fetch(0)
+                     end
+          selected
+        end
+
+        def encode_pcm_frame_candidate(candidate, block_size:, block_size_code:, block_size_extra_bits:,
+                                       frame_number:, predictor:)
           header_without_crc8 = build_frame_header_bytes(
             block_size: block_size,
             block_size_code: block_size_code,
             block_size_extra_bits: block_size_extra_bits,
-            channels: channels,
+            channel_assignment: candidate.fetch(:channel_assignment),
             frame_number: frame_number
           )
           header_crc8 = flac_crc8(header_without_crc8)
 
           payload_writer = BitWriter.new
-          channel_samples.each do |channel|
-            write_best_subframe(payload_writer, channel, format.bit_depth)
+          candidate.fetch(:channel_samples).each_with_index do |channel, channel_index|
+            write_best_subframe(payload_writer, channel, candidate.fetch(:sample_sizes).fetch(channel_index), predictor: predictor)
           end
           payload_writer.align_to_byte
           payload_bytes = payload_writer.to_s
@@ -562,8 +847,29 @@ module Wavify
           crc16_input + [crc16].pack("n")
         end
 
-        def write_best_subframe(writer, channel_samples, sample_size)
-          selection = select_subframe_encoding(channel_samples, sample_size)
+        def frame_channel_candidates(channel_samples, format, stereo_coding)
+          independent = {
+            channel_assignment: format.channels - 1,
+            channel_samples: channel_samples,
+            sample_sizes: Array.new(format.channels, format.valid_bits)
+          }
+          return [independent] unless format.channels == 2
+          return [independent] if stereo_coding == :independent
+
+          left = channel_samples.fetch(0)
+          right = channel_samples.fetch(1)
+          side = left.zip(right).map { |l, r| l - r }
+          mid = left.zip(right).map { |l, r| (l + r) >> 1 }
+          mid_side = {
+            channel_assignment: 10,
+            channel_samples: [mid, side],
+            sample_sizes: [format.valid_bits, format.valid_bits + 1]
+          }
+          stereo_coding == :mid_side ? [mid_side] : [independent, mid_side]
+        end
+
+        def write_best_subframe(writer, channel_samples, sample_size, predictor:)
+          selection = select_subframe_encoding(channel_samples, sample_size, predictor: predictor)
 
           if selection[:kind] == :fixed
             write_fixed_subframe(
@@ -575,22 +881,45 @@ module Wavify
             return
           end
 
+          if selection[:kind] == :lpc
+            write_lpc_subframe(
+              writer,
+              channel_samples,
+              sample_size,
+              selection: selection
+            )
+            return
+          end
+
           write_verbatim_subframe(writer, channel_samples, sample_size)
         end
 
-        def select_subframe_encoding(channel_samples, sample_size)
+        def select_subframe_encoding(channel_samples, sample_size, predictor:)
           best = {
             kind: :verbatim,
             bit_length: verbatim_subframe_bit_length(channel_samples.length, sample_size)
           }
+          return best if predictor == :verbatim
 
-          max_predictor_order = [4, channel_samples.length - 1].min
-          (0..max_predictor_order).each do |predictor_order|
-            candidate = build_fixed_subframe_encoding(channel_samples, sample_size, predictor_order)
-            next unless candidate
-            next unless candidate.fetch(:bit_length) < best.fetch(:bit_length)
+          if %i[auto fixed].include?(predictor)
+            max_predictor_order = [4, channel_samples.length - 1].min
+            (0..max_predictor_order).each do |predictor_order|
+              candidate = build_fixed_subframe_encoding(channel_samples, sample_size, predictor_order)
+              next unless candidate
+              next unless candidate.fetch(:bit_length) < best.fetch(:bit_length)
 
-            best = candidate
+              best = candidate
+            end
+          end
+
+          if %i[auto lpc].include?(predictor)
+            (1..[8, channel_samples.length - 1].min).each do |order|
+              candidate = build_lpc_subframe_encoding(channel_samples, sample_size, order)
+              next unless candidate
+              next unless candidate.fetch(:bit_length) < best.fetch(:bit_length)
+
+              best = candidate
+            end
           end
 
           best
@@ -602,7 +931,11 @@ module Wavify
 
         def build_fixed_subframe_encoding(channel_samples, sample_size, predictor_order)
           residuals = fixed_subframe_residuals(channel_samples, predictor_order)
-          residual_encoding = choose_residual_encoding(residuals)
+          residual_encoding = choose_residual_encoding(
+            residuals,
+            block_size: channel_samples.length,
+            predictor_order: predictor_order
+          )
           return nil unless residual_encoding
 
           {
@@ -614,6 +947,93 @@ module Wavify
           }
         end
 
+        def build_lpc_subframe_encoding(channel_samples, sample_size, predictor_order)
+          return nil if predictor_order >= channel_samples.length
+
+          coefficient_data = quantized_lpc_coefficients(channel_samples, predictor_order, sample_size)
+          return nil unless coefficient_data
+
+          coefficients = coefficient_data.fetch(:coefficients)
+          qlp_shift = coefficient_data.fetch(:qlp_shift)
+          coefficient_precision = coefficient_data.fetch(:precision)
+          residuals = lpc_subframe_residuals(channel_samples, coefficients, qlp_shift)
+          residual_encoding = choose_residual_encoding(
+            residuals,
+            block_size: channel_samples.length,
+            predictor_order: predictor_order
+          )
+          return nil unless residual_encoding
+
+          {
+            kind: :lpc,
+            predictor_order: predictor_order,
+            coefficients: coefficients,
+            coefficient_precision: coefficient_precision,
+            qlp_shift: qlp_shift,
+            residuals: residuals,
+            residual_encoding: residual_encoding,
+            bit_length: 8 + (predictor_order * sample_size) + 4 + 5 +
+              (predictor_order * coefficient_precision) + residual_encoding.fetch(:bit_length)
+          }
+        end
+
+        def quantized_lpc_coefficients(samples, predictor_order, sample_size)
+          coefficients = levinson_durbin_coefficients(samples, predictor_order)
+          return nil unless coefficients
+
+          precision = [sample_size, 15].min
+          maximum = coefficients.map(&:abs).max
+          return nil unless maximum&.positive?
+
+          max_integer = (1 << (precision - 1)) - 1
+          qlp_shift = Math.log2(max_integer / maximum).floor.clamp(-16, 15)
+          quantized = coefficients.map { |coefficient| (coefficient * (2.0**qlp_shift)).round }
+          return nil unless quantized.all? { |coefficient| signed_bit_width(coefficient) <= precision }
+
+          { coefficients: quantized, precision: precision, qlp_shift: qlp_shift }
+        end
+
+        def levinson_durbin_coefficients(samples, predictor_order)
+          return nil if samples.length <= predictor_order
+
+          autocorrelation = Array.new(predictor_order + 1) do |lag|
+            (lag...samples.length).sum { |index| samples.fetch(index).to_f * samples.fetch(index - lag) }
+          end
+          error = autocorrelation.fetch(0)
+          return nil unless error.positive?
+
+          coefficients = []
+          predictor_order.times do |index|
+            correction = index.times.sum do |coefficient_index|
+              coefficients.fetch(coefficient_index) * autocorrelation.fetch(index - coefficient_index)
+            end
+            reflection = (autocorrelation.fetch(index + 1) - correction) / error
+            return nil unless reflection.finite? && reflection.abs < 1.0
+
+            previous = coefficients.dup
+            index.times do |coefficient_index|
+              coefficients[coefficient_index] = previous.fetch(coefficient_index) -
+                                                (reflection * previous.fetch(index - coefficient_index - 1))
+            end
+            coefficients[index] = reflection
+            error *= 1.0 - (reflection * reflection)
+            return nil unless error.positive?
+          end
+          coefficients
+        end
+
+        def lpc_subframe_residuals(samples, coefficients, qlp_shift)
+          predictor_order = coefficients.length
+          samples.drop(predictor_order).each_with_index.map do |sample, index|
+            history_index = predictor_order + index
+            sum = coefficients.each_with_index.sum do |coefficient, coefficient_index|
+              coefficient * samples.fetch(history_index - coefficient_index - 1)
+            end
+            predicted = qlp_shift.negative? ? (sum << -qlp_shift) : (sum >> qlp_shift)
+            sample - predicted
+          end
+        end
+
         def fixed_subframe_residuals(samples, predictor_order)
           history = samples.first(predictor_order).dup
 
@@ -625,27 +1045,67 @@ module Wavify
           end
         end
 
-        def choose_residual_encoding(residuals)
-          rice_candidates = (0..14).map do |parameter|
+        def choose_residual_encoding(residuals, block_size:, predictor_order:)
+          max_partition_order = if block_size < 256
+                                  0
+                                else
+                                  [Math.log2(block_size / 256).floor, 6].min
+                                end
+          candidates = (0..max_partition_order).filter_map do |partition_order|
+            partition_count = 1 << partition_order
+            next unless (block_size % partition_count).zero?
+
+            partition_size = block_size / partition_count
+            next if partition_size < predictor_order
+
+            partitions = residual_partitions(
+              residuals,
+              partition_count: partition_count,
+              partition_size: partition_size,
+              predictor_order: predictor_order
+            )
+            next unless partitions
+
+            encodings = partitions.map { |partition| choose_rice_partition_encoding(partition) }
             {
-              kind: :rice,
-              parameter: parameter,
-              bit_length: rice_partition0_bit_length(residuals, parameter)
+              kind: :partitioned,
+              partition_order: partition_order,
+              partitions: partitions.zip(encodings),
+              bit_length: 6 + encodings.sum { |encoding| encoding.fetch(:bit_length) }
             }
           end
-
-          escape_candidate = escape_residual_encoding(residuals)
-          candidates = rice_candidates
-          candidates << escape_candidate if escape_candidate
           candidates.min_by { |candidate| candidate.fetch(:bit_length) }
         end
 
-        def rice_partition0_bit_length(residuals, parameter)
-          residuals.reduce(6 + 4) do |bits, residual|
-            unsigned = residual >= 0 ? (residual << 1) : ((-residual << 1) - 1)
-            quotient = unsigned >> parameter
-            bits + quotient + 1 + parameter
+        def residual_partitions(residuals, partition_count:, partition_size:, predictor_order:)
+          offset = 0
+          partitions = Array.new(partition_count) do |partition_index|
+            length = partition_size - (partition_index.zero? ? predictor_order : 0)
+            partition = residuals.slice(offset, length)
+            return nil unless partition&.length == length
+
+            offset += length
+            partition
+          end
+          offset == residuals.length ? partitions : nil
+        end
+
+        def choose_rice_partition_encoding(residuals)
+          unsigned = residuals.map { |residual| residual >= 0 ? (residual << 1) : ((-residual << 1) - 1) }
+          mean = unsigned.empty? ? 0.0 : unsigned.sum.to_f / unsigned.length
+          estimate = mean.positive? ? Math.log2(mean).floor.clamp(0, 14) : 0
+          parameters = [estimate - 1, estimate, estimate + 1].select { |value| value.between?(0, 14) }.uniq
+          rice_candidates = parameters.map do |parameter|
+            { kind: :rice, parameter: parameter, bit_length: 4 + rice_data_bit_length(unsigned, parameter) }
           end
+          escape = escape_residual_encoding(residuals)
+          rice_candidates << escape if escape
+          rice_candidates.min_by { |candidate| candidate.fetch(:bit_length) }
+        end
+
+        def rice_data_bit_length(unsigned_residuals, parameter)
+          unsigned_residuals.sum { |value| value >> parameter } +
+            (unsigned_residuals.length * (parameter + 1))
         end
 
         def escape_residual_encoding(residuals)
@@ -655,7 +1115,7 @@ module Wavify
           {
             kind: :escape,
             raw_bits: raw_bits,
-            bit_length: 6 + 4 + 5 + (residuals.length * raw_bits)
+            bit_length: 4 + 5 + (residuals.length * raw_bits)
           }
         end
 
@@ -670,41 +1130,40 @@ module Wavify
         def write_fixed_subframe(writer, channel_samples, sample_size, selection:)
           predictor_order = selection.fetch(:predictor_order)
           residual_encoding = selection.fetch(:residual_encoding)
-          residuals = selection.fetch(:residuals)
 
           writer.write_bits(0, 1) # padding bit
           writer.write_bits(8 + predictor_order, 6)
           writer.write_bits(0, 1) # no wasted bits
 
           channel_samples.first(predictor_order).each { |sample| writer.write_signed_bits(sample, sample_size) }
-          write_partition0_residuals(writer, residual_encoding, residuals)
+          write_residuals(writer, residual_encoding)
         end
 
-        def write_partition0_residuals(writer, residual_encoding, residuals)
-          if residual_encoding[:kind] == :rice
-            writer.write_bits(0, 2) # Rice
-            writer.write_bits(0, 4) # partition order = 0
-            writer.write_bits(residual_encoding.fetch(:parameter), 4)
-            residuals.each { |residual| writer.write_rice_signed(residual, residual_encoding.fetch(:parameter)) }
-            return
-          end
-
+        def write_residuals(writer, residual_encoding)
           writer.write_bits(0, 2) # Rice coding method family
-          writer.write_bits(0, 4) # partition order = 0
-          writer.write_bits(0xF, 4) # escape code
-          raw_bits = residual_encoding.fetch(:raw_bits)
-          writer.write_bits(raw_bits, 5)
-          residuals.each { |residual| writer.write_signed_bits(residual, raw_bits) } if raw_bits.positive?
+          writer.write_bits(residual_encoding.fetch(:partition_order), 4)
+          residual_encoding.fetch(:partitions).each do |residuals, partition|
+            if partition[:kind] == :rice
+              writer.write_bits(partition.fetch(:parameter), 4)
+              residuals.each { |residual| writer.write_rice_signed(residual, partition.fetch(:parameter)) }
+              next
+            end
+
+            writer.write_bits(0xF, 4) # escape code
+            raw_bits = partition.fetch(:raw_bits)
+            writer.write_bits(raw_bits, 5)
+            residuals.each { |residual| writer.write_signed_bits(residual, raw_bits) } if raw_bits.positive?
+          end
         end
 
-        def build_frame_header_bytes(block_size:, block_size_code:, block_size_extra_bits:, channels:, frame_number:)
+        def build_frame_header_bytes(block_size:, block_size_code:, block_size_extra_bits:, channel_assignment:, frame_number:)
           writer = BitWriter.new
           writer.write_bits(FLAC_SYNC_CODE, 14)
           writer.write_bits(0, 1) # reserved
           writer.write_bits(0, 1) # fixed-blocksize stream
           writer.write_bits(block_size_code, 4)
           writer.write_bits(0, 4) # sample rate from STREAMINFO
-          writer.write_bits(channels - 1, 4) # independent channels
+          writer.write_bits(channel_assignment, 4)
           writer.write_bits(0, 3) # sample size from STREAMINFO
           writer.write_bits(0, 1) # reserved
           write_utf8_uint(writer, frame_number)
@@ -720,6 +1179,21 @@ module Wavify
           channel_samples.each { |sample| writer.write_signed_bits(sample, sample_size) }
         end
 
+        def write_lpc_subframe(writer, channel_samples, sample_size, selection:)
+          predictor_order = selection.fetch(:predictor_order)
+          writer.write_bits(0, 1) # padding bit
+          writer.write_bits(32 + predictor_order - 1, 6)
+          writer.write_bits(0, 1) # no wasted bits
+
+          channel_samples.first(predictor_order).each { |sample| writer.write_signed_bits(sample, sample_size) }
+          writer.write_bits(selection.fetch(:coefficient_precision) - 1, 4)
+          writer.write_signed_bits(selection.fetch(:qlp_shift), 5)
+          selection.fetch(:coefficients).each do |coefficient|
+            writer.write_signed_bits(coefficient, selection.fetch(:coefficient_precision))
+          end
+          write_residuals(writer, selection.fetch(:residual_encoding))
+        end
+
         def deinterleave_samples(interleaved_samples, channels)
           channel_samples = Array.new(channels) { [] }
 
@@ -776,7 +1250,7 @@ module Wavify
           size = block_size.to_i
           raise InvalidParameterError, "FLAC block_size must be a positive Integer" unless size.positive?
 
-          [size, 65_536].min
+          [size, 65_535].min
         end
 
         def build_streaminfo_bytes(format:, sample_frame_count:, stats:, md5_hex:)
@@ -791,7 +1265,7 @@ module Wavify
 
           packed = ((format.sample_rate & 0xFFFFF) << 44) |
                    (((format.channels - 1) & 0x7) << 41) |
-                   (((format.bit_depth - 1) & 0x1F) << 36) |
+                   (((format.valid_bits - 1) & 0x1F) << 36) |
                    (sample_frame_count & 0xFFFFFFFFF)
 
           [min_block_size, max_block_size].pack("n2") +
@@ -802,22 +1276,41 @@ module Wavify
         end
 
         def pcm_md5_hex(samples, format)
-          Digest::MD5.hexdigest(pcm_bytes_for_md5(samples, format))
+          encoded_samples = unalign_encoded_samples(samples, format)
+          Digest::MD5.hexdigest(flac_md5_bytes(encoded_samples, format.valid_bits))
         end
 
         def pcm_bytes_for_md5(samples, format)
-          case format.bit_depth
-          when 8
-            samples.pack("c*")
-          when 16
-            samples.pack("s<*")
-          when 24
-            encode_pcm24_le(samples)
-          when 32
-            samples.pack("l<*")
-          else
-            raise UnsupportedFormatError, "unsupported FLAC MD5 PCM bit depth: #{format.bit_depth}"
+          encoded_samples = unalign_encoded_samples(samples, format)
+          flac_md5_bytes(encoded_samples, format.valid_bits)
+        end
+
+        def flac_md5_bytes(samples, valid_bits)
+          byte_width = (valid_bits + 7) / 8
+          mask = (1 << (byte_width * 8)) - 1
+          bytes = String.new(capacity: samples.length * byte_width, encoding: Encoding::BINARY)
+          samples.each do |sample|
+            value = sample & mask
+            byte_width.times do
+              bytes << (value & 0xFF)
+              value >>= 8
+            end
           end
+          bytes
+        end
+
+        def unalign_encoded_samples(samples, format)
+          shift = format.bit_depth - format.valid_bits
+          return samples if shift.zero?
+
+          samples.map { |sample| sample >> shift }
+        end
+
+        def align_decoded_samples(samples, format)
+          shift = format.bit_depth - format.valid_bits
+          return samples if shift.zero?
+
+          samples.map { |sample| sample << shift }
         end
 
         def encode_pcm24_le(samples)
@@ -880,14 +1373,11 @@ module Wavify
           format = metadata.fetch(:format)
           remaining_frames = metadata[:sample_frame_count]
           bounded_total = remaining_frames.is_a?(Integer) && remaining_frames.positive?
+          md5 = decoded_pcm_md5(metadata)
 
           until io.eof?
             break if bounded_total && remaining_frames <= 0
 
-            next_byte = io.read(1)
-            break if next_byte.nil?
-
-            io.seek(-1, IO::SEEK_CUR)
             frame_samples = decode_frame(io, metadata)
 
             if bounded_total
@@ -898,12 +1388,16 @@ module Wavify
               remaining_frames -= decoded_frame_count
             end
 
-            yield frame_samples unless frame_samples.empty?
+            md5&.update(flac_md5_bytes(frame_samples, metadata.fetch(:encoded_bit_depth)))
+            aligned_samples = align_decoded_samples(frame_samples, format)
+            yield aligned_samples unless aligned_samples.empty?
           end
 
-          return unless bounded_total && remaining_frames.positive?
+          if bounded_total && remaining_frames.positive?
+            raise InvalidFormatError, "decoded FLAC samples are shorter than STREAMINFO total sample count"
+          end
 
-          raise InvalidFormatError, "decoded FLAC samples are shorter than STREAMINFO total sample count"
+          verify_decoded_pcm_md5!(md5, metadata[:md5])
         end
 
         def decode_frame(io, metadata)
@@ -912,7 +1406,9 @@ module Wavify
           channel_samples = decode_subframes(bit_reader, frame_header)
           channel_samples = restore_channel_assignment(channel_samples, frame_header)
           bit_reader.align_to_byte
-          _crc16 = bit_reader.read_bits(16)
+          actual_crc16 = flac_crc16(bit_reader.captured_bytes)
+          expected_crc16 = bit_reader.read_bits(16)
+          raise InvalidFormatError, "FLAC frame CRC-16 mismatch" unless expected_crc16 == actual_crc16
 
           interleave_channels(channel_samples, frame_header.fetch(:block_size), frame_header.fetch(:channels))
         end
@@ -937,8 +1433,10 @@ module Wavify
           _frame_number = read_utf8_uint(bit_reader)
           block_size = decode_block_size(block_size_code, bit_reader)
           sample_rate = decode_sample_rate(sample_rate_code, bit_reader, metadata.fetch(:format).sample_rate)
-          sample_size = decode_sample_size(sample_size_code, metadata.fetch(:format).bit_depth)
-          _crc8 = bit_reader.read_bits(8)
+          sample_size = decode_sample_size(sample_size_code, metadata.fetch(:encoded_bit_depth))
+          actual_crc8 = flac_crc8(bit_reader.captured_bytes)
+          expected_crc8 = bit_reader.read_bits(8)
+          raise InvalidFormatError, "FLAC frame header CRC-8 mismatch" unless expected_crc8 == actual_crc8
 
           channels = decode_channel_count(channel_assignment, metadata.fetch(:format).channels)
 
@@ -951,6 +1449,20 @@ module Wavify
           }
         end
 
+        def decoded_pcm_md5(metadata)
+          expected = metadata[:md5]
+          return if expected.nil? || expected == ("0" * 32)
+
+          Digest::MD5.new
+        end
+
+        def verify_decoded_pcm_md5!(md5, expected)
+          return unless md5
+          return if md5.hexdigest == expected
+
+          raise InvalidFormatError, "FLAC STREAMINFO MD5 mismatch"
+        end
+
         def read_utf8_uint(bit_reader)
           first = bit_reader.read_bits(8)
           return first if first.nobits?(0x80)
@@ -1189,8 +1701,14 @@ module Wavify
 
         def read_unary_zero_run(bit_reader)
           count = 0
-          count += 1 while bit_reader.read_bits(1).zero?
-          count
+          loop do
+            return count unless bit_reader.read_bits(1).zero?
+
+            count += 1
+            if count > MAX_UNARY_ZERO_RUN
+              raise InvalidFormatError, "FLAC unary zero run exceeds resource limit"
+            end
+          end
         end
 
         def reconstruct_fixed_subframe(warmup, residuals, predictor_order)
@@ -1288,34 +1806,6 @@ module Wavify
           bytes.unpack("C3").then { |b0, b1, b2| (b0 << 16) | (b1 << 8) | b2 }
         end
 
-        def read_exact(io, size, message)
-          data = io.read(size)
-          raise InvalidFormatError, message if data.nil? || data.bytesize != size
-
-          data
-        end
-
-        def ensure_seekable!(io)
-          return if io.respond_to?(:seek) && io.respond_to?(:rewind)
-
-          raise StreamError, "FLAC codec requires seekable IO"
-        end
-
-        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
       end
     end
   end