wavify 0.1.0 → 0.2.0

data/lib/wavify/codecs/wav.rb

@@ -9,10 +9,47 @@ module Wavify
       WAV_FORMAT_PCM = 0x0001 # :nodoc:
       WAV_FORMAT_FLOAT = 0x0003 # :nodoc:
       WAV_FORMAT_EXTENSIBLE = 0xFFFE # :nodoc:
+      RIFF_MAX_SIZE = 0xFFFF_FFFF # :nodoc:
 
       GUID_TAIL = [0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71].pack("C*").freeze # :nodoc:
       PCM_SUBFORMAT_GUID = ([WAV_FORMAT_PCM, 0x0000, 0x0010].pack("V v v") + GUID_TAIL).freeze # :nodoc:
       FLOAT_SUBFORMAT_GUID = ([WAV_FORMAT_FLOAT, 0x0000, 0x0010].pack("V v v") + GUID_TAIL).freeze # :nodoc:
+      SPEAKER_BITS = {
+        front_left: 0x0001,
+        front_right: 0x0002,
+        front_center: 0x0004,
+        low_frequency: 0x0008,
+        back_left: 0x0010,
+        back_right: 0x0020,
+        front_left_of_center: 0x0040,
+        front_right_of_center: 0x0080,
+        back_center: 0x0100,
+        side_left: 0x0200,
+        side_right: 0x0400,
+        top_center: 0x0800,
+        top_front_left: 0x1000,
+        top_front_center: 0x2000,
+        top_front_right: 0x4000,
+        top_back_left: 0x8000,
+        top_back_center: 0x1_0000,
+        top_back_right: 0x2_0000
+      }.freeze # :nodoc:
+      INFO_TAGS = {
+        "INAM" => :title,
+        "IART" => :artist,
+        "ICMT" => :comment,
+        "ICOP" => :copyright,
+        "ICRD" => :date,
+        "IGNR" => :genre,
+        "ISFT" => :software,
+        "ITCH" => :technician
+      }.freeze # :nodoc:
+      INFO_TAG_CODES = INFO_TAGS.invert.freeze # :nodoc:
+      SMPL_LOOP_TYPES = {
+        0 => :forward,
+        1 => :alternating,
+        2 => :backward
+      }.freeze # :nodoc:
 
       class << self
         # @param io_or_path [String, IO]
@@ -26,9 +63,10 @@ module Wavify
           io, close_io = open_input(io_or_path)
           return false unless io
 
-          header = io.read(12)
-          io.rewind if io.respond_to?(:rewind)
-          header&.start_with?("RIFF") && header[8, 4] == "WAVE"
+          header = probe_bytes(io, 12)
+          (header&.start_with?("RIFF") || header&.start_with?("RF64")) && header[8, 4] == "WAVE"
+        rescue StreamError
+          false
         ensure
           io.close if close_io && io
         end
@@ -38,11 +76,12 @@ module Wavify
         # @param io_or_path [String, IO]
         # @param format [Wavify::Core::Format, nil] optional output conversion
         # @return [Wavify::Core::SampleBuffer]
-        def read(io_or_path, format: nil)
+        def read(io_or_path, format: nil, warning_io: nil)
           io, close_io = open_input(io_or_path)
           ensure_seekable!(io)
 
           info = parse_chunk_directory(io)
+          emit_warnings(info.fetch(:warnings), warning_io)
           source_format = info.fetch(:format)
           samples = read_data_chunk(io, info, source_format)
           buffer = Core::SampleBuffer.new(samples, source_format)
@@ -57,14 +96,15 @@ module Wavify
         # @param sample_buffer [Wavify::Core::SampleBuffer]
         # @param format [Wavify::Core::Format, nil]
         # @return [String, IO]
-        def write(io_or_path, sample_buffer, format: nil)
+        def write(io_or_path, sample_buffer, format: nil, info: nil, **codec_options)
+          validate_no_codec_options!(codec_options, operation: "WAV write")
           raise InvalidParameterError, "sample_buffer must be Core::SampleBuffer" unless sample_buffer.is_a?(Core::SampleBuffer)
 
           target_format = format || sample_buffer.format
           raise InvalidParameterError, "format must be Core::Format" unless target_format.is_a?(Core::Format)
 
           buffer = sample_buffer.format == target_format ? sample_buffer : sample_buffer.convert(target_format)
-          stream_write(io_or_path, format: target_format) do |writer|
+          stream_write(io_or_path, format: target_format, info: info) do |writer|
             writer.call(buffer)
           end
         end
@@ -74,14 +114,15 @@ module Wavify
         # @param io_or_path [String, IO]
         # @param chunk_size [Integer]
         # @return [Enumerator]
-        def stream_read(io_or_path, chunk_size: 4096)
-          return enum_for(__method__, io_or_path, chunk_size: chunk_size) unless block_given?
+        def stream_read(io_or_path, chunk_size: 4096, warning_io: nil)
+          return enum_for(__method__, io_or_path, chunk_size: chunk_size, warning_io: warning_io) unless block_given?
           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)
 
           info = parse_chunk_directory(io)
+          emit_warnings(info.fetch(:warnings), warning_io)
           format = info.fetch(:format)
           bytes_per_frame = format.block_align
           remaining = info.fetch(:data_size)
@@ -103,16 +144,16 @@ module Wavify
         # @param io_or_path [String, IO]
         # @param format [Wavify::Core::Format]
         # @return [Enumerator, String, IO]
-        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:, info: nil, **codec_options)
+          validate_no_codec_options!(codec_options, operation: "WAV stream_write")
+          return enum_for(__method__, io_or_path, format: format, info: info, **codec_options) unless block_given?
           raise InvalidParameterError, "format must be Core::Format" unless format.is_a?(Core::Format)
 
           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, format)
+          header = write_stream_header(io, format, info: info)
           total_data_bytes = 0
           total_sample_frames = 0
 
@@ -120,17 +161,25 @@ module Wavify
             raise InvalidParameterError, "stream chunk must be Core::SampleBuffer" unless chunk.is_a?(Core::SampleBuffer)
 
             buffer = chunk.format == format ? chunk : chunk.convert(format)
+            encoded_bytes = buffer.sample_frame_count * format.block_align
+            next_data_bytes = total_data_bytes + encoded_bytes
+            next_sample_frames = total_sample_frames + buffer.sample_frame_count
+            projected_container_bytes = (io.pos - header.fetch(:container_start)) + encoded_bytes + (next_data_bytes.odd? ? 1 : 0)
+            validate_riff_sizes!(next_data_bytes, next_sample_frames, projected_container_bytes)
             encoded = encode_samples(buffer.samples, format)
-            io.write(encoded)
-            total_data_bytes += encoded.bytesize
-            total_sample_frames += buffer.sample_frame_count
+            unless encoded.bytesize == encoded_bytes
+              raise StreamError, "WAV encoder produced an unexpected byte count"
+            end
+
+            write_all(io, encoded)
+            total_data_bytes = next_data_bytes
+            total_sample_frames = next_sample_frames
           end
 
           yield writer
-          io.write("\x00") if total_data_bytes.odd?
+          write_all(io, "\x00") if total_data_bytes.odd?
           finalize_stream_header(io, header, total_data_bytes, total_sample_frames)
-          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
@@ -153,7 +202,19 @@ module Wavify
             sample_frame_count: sample_frame_count,
             duration: Core::Duration.from_samples(sample_frame_count, format.sample_rate),
             fact_sample_length: info[:fact_sample_length],
-            smpl: info[:smpl]
+            smpl: info[:smpl],
+            loops: normalized_smpl_loops(info[:smpl]),
+            cue: info[:cue],
+            cue_points: info[:cue]&.fetch(:points) || [],
+            info: info[:info],
+            bext: info[:bext],
+            broadcast_extension: info[:bext],
+            rf64: info[:rf64],
+            container_bit_depth: info[:container_bit_depth],
+            valid_bits_per_sample: info[:valid_bits_per_sample],
+            channel_mask: info[:channel_mask],
+            channel_layout: format.channel_layout,
+            warnings: info[:warnings].freeze
           }
         ensure
           io.close if close_io && io
@@ -161,28 +222,38 @@ module Wavify
 
         private
 
-        def write_stream_header(io, format)
-          io.write("RIFF")
+        def emit_warnings(warnings, warning_io)
+          return if warning_io.nil?
+          raise InvalidParameterError, "warning_io must respond to :puts or be nil" unless warning_io.respond_to?(:puts)
+
+          warnings.each { |warning| warning_io.puts("WAV warning: #{warning}") }
+        end
+
+        def write_stream_header(io, format, info:)
+          container_start = io.pos
+          write_all(io, "RIFF")
           riff_size_offset = io.pos
-          io.write([0].pack("V"))
-          io.write("WAVE")
+          write_all(io, [0].pack("V"))
+          write_all(io, "WAVE")
 
           fmt_chunk = build_fmt_chunk(format)
           write_chunk(io, "fmt ", fmt_chunk)
+          write_chunk(io, "LIST", build_info_list_chunk(info)) if info
 
           fact_sample_offset = nil
           if format.sample_format != :pcm
-            io.write("fact")
-            io.write([4].pack("V"))
+            write_all(io, "fact")
+            write_all(io, [4].pack("V"))
             fact_sample_offset = io.pos
-            io.write([0].pack("V"))
+            write_all(io, [0].pack("V"))
           end
 
-          io.write("data")
+          write_all(io, "data")
           data_size_offset = io.pos
-          io.write([0].pack("V"))
+          write_all(io, [0].pack("V"))
 
           {
+            container_start: container_start,
             riff_size_offset: riff_size_offset,
             data_size_offset: data_size_offset,
             fact_sample_offset: fact_sample_offset
@@ -191,72 +262,143 @@ module Wavify
 
         def finalize_stream_header(io, header, total_data_bytes, total_sample_frames)
           file_end = io.pos
+          container_bytes = file_end - header.fetch(:container_start)
+          validate_riff_sizes!(total_data_bytes, total_sample_frames, container_bytes)
 
           io.seek(header.fetch(:data_size_offset), IO::SEEK_SET)
-          io.write([total_data_bytes].pack("V"))
+          write_all(io, [total_data_bytes].pack("V"))
 
           fact_sample_offset = header[:fact_sample_offset]
           if fact_sample_offset
             io.seek(fact_sample_offset, IO::SEEK_SET)
-            io.write([total_sample_frames].pack("V"))
+            write_all(io, [total_sample_frames].pack("V"))
           end
 
           io.seek(header.fetch(:riff_size_offset), IO::SEEK_SET)
-          io.write([file_end - 8].pack("V"))
+          write_all(io, [container_bytes - 8].pack("V"))
           io.seek(file_end, IO::SEEK_SET)
         end
 
         def parse_chunk_directory(io)
-          io.rewind
+          container_start = io.pos
           header = read_exact(io, 12, "missing RIFF/WAVE header")
-          raise InvalidFormatError, "invalid WAV header" unless header.start_with?("RIFF") && header[8, 4] == "WAVE"
+          container_id = header[0, 4]
+          unless %w[RIFF RF64].include?(container_id) && header[8, 4] == "WAVE"
+            raise InvalidFormatError, "invalid WAV header"
+          end
+          riff_size = header[4, 4].unpack1("V")
+          container_end = container_id == "RIFF" ? container_start + 8 + riff_size : nil
+          raise InvalidFormatError, "RIFF size is smaller than WAVE header" if container_end && container_end < container_start + 12
+          if container_end && io.respond_to?(:size) && container_end > io.size
+            raise InvalidFormatError, "RIFF size exceeds available input"
+          end
 
           info = {
             format: nil,
+            container_bit_depth: nil,
+            valid_bits_per_sample: nil,
+            channel_mask: nil,
+            warnings: [],
             data_offset: nil,
             data_size: nil,
             sample_frame_count: nil,
             fact_sample_length: nil,
-            smpl: nil
+            smpl: nil,
+            cue: nil,
+            info: nil,
+            bext: nil,
+            rf64: container_id == "RF64" ? {} : nil
           }
+          seen_chunks = {}
+
+          loop do
+            break if container_end && io.pos >= container_end
+            break if !container_end && io.eof?
+            if container_end && (container_end - io.pos) < 8
+              raise InvalidFormatError, "truncated chunk header inside RIFF container"
+            end
 
-          until io.eof?
-            chunk_header = io.read(8)
-            break if chunk_header.nil?
-            raise InvalidFormatError, "truncated chunk header" unless chunk_header.bytesize == 8
+            chunk_header = read_exact(io, 8, "truncated chunk header")
 
             chunk_id = chunk_header[0, 4]
             chunk_size = chunk_header[4, 4].unpack1("V")
+            consumed_size = chunk_size
+            if ["fmt ", "data", "ds64"].include?(chunk_id) && seen_chunks[chunk_id]
+              raise InvalidFormatError, "duplicate #{chunk_id.inspect} chunk"
+            end
+            seen_chunks[chunk_id] = true
 
             case chunk_id
             when "fmt "
               chunk_data = read_exact(io, chunk_size, "truncated fmt chunk")
-              info[:format] = parse_fmt_chunk(chunk_data)
+              fmt_info = parse_fmt_chunk(chunk_data)
+              info[:format] = fmt_info.fetch(:format)
+              info[:container_bit_depth] = fmt_info.fetch(:container_bit_depth)
+              info[:valid_bits_per_sample] = fmt_info.fetch(:valid_bits_per_sample)
+              info[:channel_mask] = fmt_info.fetch(:channel_mask)
+              info[:warnings].concat(fmt_info.fetch(:warnings))
             when "data"
               info[:data_offset] = io.pos
-              info[:data_size] = chunk_size
-              skip_bytes(io, chunk_size)
+              data_size = rf64_chunk_size(info, :data_size, chunk_size)
+              consumed_size = data_size
+              info[:data_size] = data_size
+              skip_bytes(io, data_size)
+            when "ds64"
+              chunk_data = read_exact(io, chunk_size, "truncated ds64 chunk")
+              info[:rf64] = parse_ds64_chunk(chunk_data)
+              container_end = container_start + 8 + info.fetch(:rf64).fetch(:riff_size)
+              if io.respond_to?(:size) && container_end > io.size
+                raise InvalidFormatError, "RF64 size exceeds available input"
+              end
             when "fact"
               chunk_data = read_exact(io, chunk_size, "truncated fact chunk")
               info[:fact_sample_length] = chunk_data.unpack1("V") if chunk_data.bytesize >= 4
             when "smpl"
               chunk_data = read_exact(io, chunk_size, "truncated smpl chunk")
               info[:smpl] = parse_smpl_chunk(chunk_data)
+            when "cue "
+              chunk_data = read_exact(io, chunk_size, "truncated cue chunk")
+              info[:cue] = parse_cue_chunk(chunk_data)
+            when "bext"
+              chunk_data = read_exact(io, chunk_size, "truncated bext chunk")
+              info[:bext] = parse_bext_chunk(chunk_data)
+            when "LIST"
+              chunk_data = read_exact(io, chunk_size, "truncated LIST chunk")
+              list_info = parse_list_chunk(chunk_data)
+              info[:info] = list_info if list_info
             else
               skip_bytes(io, chunk_size)
             end
 
-            skip_padding_byte(io, chunk_size)
+            skip_padding_byte(io, consumed_size)
+            if container_end && io.pos > container_end
+              raise InvalidFormatError, "chunk exceeds RIFF container boundary"
+            end
           end
 
           raise InvalidFormatError, "fmt chunk missing" unless info[:format]
           raise InvalidFormatError, "data chunk missing" unless info[:data_offset] && info[:data_size]
 
           validate_data_chunk!(io, info)
-          info[:sample_frame_count] = info[:data_size] / info[:format].block_align
+          rf64_frame_count = info.dig(:rf64, :sample_frame_count)
+          info[:sample_frame_count] = if rf64_frame_count&.positive?
+                                        rf64_frame_count
+                                      else
+                                        info[:data_size] / info[:format].block_align
+                                      end
+          validate_smpl_loops!(info[:smpl], info[:sample_frame_count])
           info
         end
 
+        def rf64_chunk_size(info, key, chunk_size)
+          return chunk_size unless chunk_size == 0xFFFF_FFFF
+
+          rf64_size = info.dig(:rf64, key)
+          raise InvalidFormatError, "RF64 #{key} requires ds64 chunk" unless rf64_size
+
+          rf64_size
+        end
+
         def validate_data_chunk!(io, info)
           format = info.fetch(:format)
           data_size = info.fetch(:data_size)
@@ -280,7 +422,9 @@ module Wavify
         def parse_fmt_chunk(chunk)
           raise InvalidFormatError, "fmt chunk is too small" if chunk.bytesize < 16
 
-          audio_format, channels, sample_rate, byte_rate, block_align, bit_depth = chunk.unpack("v v V V v v")
+          audio_format, channels, sample_rate, byte_rate, block_align, container_bit_depth = chunk.unpack("v v V V v v")
+          valid_bits = container_bit_depth
+          channel_mask = nil
 
           if audio_format == WAV_FORMAT_EXTENSIBLE
             raise InvalidFormatError, "fmt extensible chunk is too small" if chunk.bytesize < 40
@@ -289,9 +433,19 @@ module Wavify
             raise InvalidFormatError, "invalid extensible fmt chunk size" if extension_size < 22 || chunk.bytesize < (18 + extension_size)
 
             valid_bits = chunk[18, 2].unpack1("v")
+            valid_bits = container_bit_depth if valid_bits.zero?
+            if valid_bits > container_bit_depth
+              raise InvalidFormatError, "valid bits per sample exceeds container bit depth"
+            end
+            channel_mask = chunk[20, 4].unpack1("V")
             sub_format_guid = chunk[24, 16]
-            audio_format = sub_format_guid.unpack1("v")
-            bit_depth = valid_bits if valid_bits.positive?
+            audio_format = case sub_format_guid
+                           when PCM_SUBFORMAT_GUID then WAV_FORMAT_PCM
+                           when FLOAT_SUBFORMAT_GUID then WAV_FORMAT_FLOAT
+                           else
+                             raise UnsupportedFormatError,
+                                   "unsupported WAV extensible subformat GUID: #{sub_format_guid.unpack1('H*')}"
+                           end
           end
 
           sample_format = case audio_format
@@ -304,21 +458,32 @@ module Wavify
           format = Core::Format.new(
             channels: channels,
             sample_rate: sample_rate,
-            bit_depth: bit_depth,
-            sample_format: sample_format
+            bit_depth: container_bit_depth,
+            sample_format: sample_format,
+            valid_bits: valid_bits,
+            channel_layout: channel_layout_for_mask(channel_mask, channels)
           )
 
           expected_block_align = format.block_align
           expected_byte_rate = format.byte_rate
-          unless block_align == expected_block_align && byte_rate == expected_byte_rate
-            raise InvalidFormatError, "fmt chunk has inconsistent byte_rate/block_align"
+          raise InvalidFormatError, "fmt chunk has inconsistent block_align" unless block_align == expected_block_align
+
+          warnings = []
+          if byte_rate != expected_byte_rate
+            warnings << "fmt chunk byte_rate #{byte_rate} does not match expected #{expected_byte_rate}"
           end
 
-          format
+          {
+            format: format,
+            container_bit_depth: container_bit_depth,
+            valid_bits_per_sample: valid_bits,
+            channel_mask: channel_mask,
+            warnings: warnings
+          }
         end
 
         def parse_smpl_chunk(chunk)
-          return nil if chunk.bytesize < 36
+          raise InvalidFormatError, "smpl chunk too small" if chunk.bytesize < 36
 
           manufacturer, product, sample_period, midi_unity_note, midi_pitch_fraction,
             smpte_format, smpte_offset, loop_count, sampler_data = chunk.unpack("V9")
@@ -326,7 +491,7 @@ module Wavify
           loops = []
           offset = 36
           loop_count.times do
-            break if offset + 24 > chunk.bytesize
+            raise InvalidFormatError, "truncated smpl loop table" if offset + 24 > chunk.bytesize
 
             identifier, loop_type, start_frame, end_frame, fraction, play_count = chunk.byteslice(offset, 24).unpack("V6")
             loops << {
@@ -354,27 +519,164 @@ module Wavify
           }
         end
 
+        def normalized_smpl_loops(smpl)
+          return [] unless smpl
+
+          smpl.fetch(:loops).map do |loop|
+            {
+              identifier: loop.fetch(:identifier),
+              type: SMPL_LOOP_TYPES.fetch(loop.fetch(:type), loop.fetch(:type)),
+              start_frame: loop.fetch(:start_frame),
+              end_frame: loop.fetch(:end_frame),
+              length_frames: loop.fetch(:end_frame) - loop.fetch(:start_frame) + 1,
+              play_count: loop.fetch(:play_count)
+            }
+          end
+        end
+
+        def parse_cue_chunk(chunk)
+          raise InvalidFormatError, "cue chunk too small" if chunk.bytesize < 4
+
+          cue_count = chunk.unpack1("V")
+          points = []
+          offset = 4
+          cue_count.times do
+            raise InvalidFormatError, "truncated cue point table" if offset + 24 > chunk.bytesize
+
+            identifier, position, data_chunk_id, chunk_start, block_start, sample_offset =
+              chunk.byteslice(offset, 24).unpack("V V A4 V V V")
+            points << {
+              identifier: identifier,
+              position: position,
+              data_chunk_id: data_chunk_id,
+              chunk_start: chunk_start,
+              block_start: block_start,
+              sample_offset: sample_offset
+            }
+            offset += 24
+          end
+
+          { cue_count: cue_count, points: points }
+        end
+
+        def parse_ds64_chunk(chunk)
+          raise InvalidFormatError, "ds64 chunk too small" if chunk.bytesize < 28
+
+          riff_size, data_size, sample_frame_count = chunk.byteslice(0, 24).unpack("Q< Q< Q<")
+          table_count = chunk.byteslice(24, 4).unpack1("V")
+          table = {}
+          offset = 28
+          table_count.times do
+            raise InvalidFormatError, "truncated ds64 table" if offset + 12 > chunk.bytesize
+
+            chunk_id = chunk.byteslice(offset, 4)
+            size = chunk.byteslice(offset + 4, 8).unpack1("Q<")
+            table[chunk_id] = size
+            offset += 12
+          end
+
+          {
+            riff_size: riff_size,
+            data_size: data_size,
+            sample_frame_count: sample_frame_count,
+            table: table
+          }
+        end
+
+        def parse_bext_chunk(chunk)
+          return nil if chunk.bytesize < 602
+
+          coding_history = chunk.bytesize > 602 ? strip_trailing_nuls(chunk.byteslice(602, chunk.bytesize - 602)) : ""
+          {
+            description: wav_string(chunk.byteslice(0, 256)),
+            originator: wav_string(chunk.byteslice(256, 32)),
+            originator_reference: wav_string(chunk.byteslice(288, 32)),
+            origination_date: wav_string(chunk.byteslice(320, 10)),
+            origination_time: wav_string(chunk.byteslice(330, 8)),
+            time_reference: chunk.byteslice(338, 8).unpack1("Q<"),
+            version: chunk.byteslice(346, 2).unpack1("v"),
+            umid: chunk.byteslice(348, 64).unpack1("H*"),
+            loudness_value: bext_loudness_value(chunk, 412),
+            loudness_range: bext_loudness_value(chunk, 414),
+            max_true_peak_level: bext_loudness_value(chunk, 416),
+            max_momentary_loudness: bext_loudness_value(chunk, 418),
+            max_short_term_loudness: bext_loudness_value(chunk, 420),
+            coding_history: coding_history
+          }
+        end
+
+        def wav_string(bytes)
+          strip_trailing_nuls(bytes).split("\x00", 2).first.to_s.force_encoding(Encoding::UTF_8).scrub
+        end
+
+        def bext_loudness_value(chunk, offset)
+          return nil if chunk.bytesize < offset + 2
+
+          chunk.byteslice(offset, 2).unpack1("s<")
+        end
+
+        def parse_list_chunk(chunk)
+          return nil if chunk.bytesize < 4
+          return nil unless chunk[0, 4] == "INFO"
+
+          result = { raw: {}, raw_bytes: {} }
+          offset = 4
+          while offset + 8 <= chunk.bytesize
+            tag = chunk[offset, 4]
+            size = chunk[offset + 4, 4].unpack1("V")
+            offset += 8
+            break if offset + size > chunk.bytesize
+
+            raw_value = strip_trailing_nuls(chunk.byteslice(offset, size))
+            value = raw_value.dup.force_encoding(Encoding::UTF_8).scrub
+            result[:raw][tag] = value
+            result[:raw_bytes][tag] = raw_value.freeze
+            semantic_key = INFO_TAGS[tag]
+            result[semantic_key] = value if semantic_key
+            offset += size
+            offset += 1 if size.odd?
+          end
+
+          result
+        end
+
+        def validate_smpl_loops!(smpl, sample_frame_count)
+          return unless smpl
+
+          smpl.fetch(:loops).each do |loop|
+            start_frame = loop.fetch(:start_frame)
+            end_frame = loop.fetch(:end_frame)
+            if end_frame < start_frame || end_frame >= sample_frame_count
+              raise InvalidFormatError,
+                    "smpl loop range #{start_frame}..#{end_frame} is outside #{sample_frame_count} sample frames"
+            end
+          end
+        end
+
         def decode_samples(data_chunk, format)
           if format.sample_format == :float
             return data_chunk.unpack("e*") if format.bit_depth == 32
             return data_chunk.unpack("E*") if format.bit_depth == 64
           elsif format.sample_format == :pcm
-            return data_chunk.unpack("C*").map { |byte| byte - 128 } if format.bit_depth == 8
-            return data_chunk.unpack("s<*") if format.bit_depth == 16
-            return decode_pcm24(data_chunk) if format.bit_depth == 24
-            return data_chunk.unpack("l<*") if format.bit_depth == 32
+            samples = data_chunk.unpack("C*").map { |byte| byte - 128 } if format.bit_depth == 8
+            samples = data_chunk.unpack("s<*") if format.bit_depth == 16
+            samples = decode_pcm24(data_chunk) if format.bit_depth == 24
+            samples = data_chunk.unpack("l<*") if format.bit_depth == 32
+            return canonicalize_valid_bits(samples, format) if samples
           end
 
           raise UnsupportedFormatError, "unsupported WAV bit depth: #{format.bit_depth}"
         end
 
         def decode_pcm24(data)
-          bytes = data.unpack("C*")
-          bytes.each_slice(3).map do |b0, b1, b2|
-            value = b0 | (b1 << 8) | (b2 << 16)
+          samples = Array.new(data.bytesize / 3)
+          samples.length.times do |index|
+            offset = index * 3
+            value = data.getbyte(offset) | (data.getbyte(offset + 1) << 8) | (data.getbyte(offset + 2) << 16)
             value -= 0x1000000 if value.anybits?(0x800000)
-            value
+            samples[index] = value
           end
+          samples
         end
 
         def encode_samples(samples, format)
@@ -385,7 +687,7 @@ module Wavify
           elsif format.sample_format == :pcm
             min = -(2**(format.bit_depth - 1))
             max = (2**(format.bit_depth - 1)) - 1
-            ints = samples.map { |sample| sample.to_i.clamp(min, max) }
+            ints = canonicalize_valid_bits(samples.map { |sample| sample.to_i.clamp(min, max) }, format)
             return ints.map { |sample| sample + 128 }.pack("C*") if format.bit_depth == 8
             return ints.pack("s<*") if format.bit_depth == 16
             return encode_pcm24(ints) if format.bit_depth == 24
@@ -396,23 +698,24 @@ module Wavify
         end
 
         def encode_pcm24(samples)
-          bytes = samples.flat_map do |sample|
+          bytes = String.new(capacity: samples.length * 3, encoding: Encoding::BINARY)
+          samples.each do |sample|
             value = sample
             value += 0x1000000 if value.negative?
-            [value & 0xFF, (value >> 8) & 0xFF, (value >> 16) & 0xFF]
+            bytes << (value & 0xFF) << ((value >> 8) & 0xFF) << ((value >> 16) & 0xFF)
           end
-          bytes.pack("C*")
+          bytes
         end
 
         def build_fmt_chunk(format)
           return build_standard_fmt_chunk(format) unless use_extensible_format?(format)
 
           base_format_code = format.sample_format == :pcm ? WAV_FORMAT_PCM : WAV_FORMAT_FLOAT
-          channel_mask = channel_mask_for(format.channels)
+          channel_mask = channel_mask_for(format)
           sub_format_guid = base_format_code == WAV_FORMAT_PCM ? PCM_SUBFORMAT_GUID : FLOAT_SUBFORMAT_GUID
 
           [WAV_FORMAT_EXTENSIBLE, format.channels, format.sample_rate, format.byte_rate, format.block_align, format.bit_depth,
-           22, format.bit_depth, channel_mask].pack("v v V V v v v v V") + sub_format_guid
+           22, format.valid_bits, channel_mask].pack("v v V V v v v v V") + sub_format_guid
         end
 
         def build_standard_fmt_chunk(format)
@@ -421,11 +724,55 @@ module Wavify
             .pack("v v V V v v")
         end
 
+        def build_info_list_chunk(info)
+          normalized = normalize_info_tags!(info)
+          chunks = normalized.map do |tag, value|
+            data = "#{value}\x00".b
+            tag + [data.bytesize].pack("V") + data + (data.bytesize.odd? ? "\x00" : "")
+          end
+
+          "INFO" + chunks.join
+        end
+
+        def normalize_info_tags!(info)
+          raise InvalidParameterError, "WAV info must be a Hash" unless info.is_a?(Hash)
+
+          info.each_with_object({}) do |(key, value), normalized|
+            tag = info_tag_for!(key)
+            raise InvalidParameterError, "WAV info values must be String-compatible" unless value.respond_to?(:to_s)
+
+            normalized[tag] = value.to_s
+          end
+        end
+
+        def info_tag_for!(key)
+          return key if key.is_a?(String) && key.match?(/\A[A-Z0-9 ]{4}\z/)
+
+          semantic = key.to_sym if key.respond_to?(:to_sym)
+          tag = INFO_TAG_CODES[semantic]
+          return tag if tag
+
+          raise InvalidParameterError, "unsupported WAV info tag: #{key.inspect}"
+        end
+
         def use_extensible_format?(format)
-          format.channels > 2 || format.bit_depth > 16
+          default_layout = Core::Format::DEFAULT_CHANNEL_LAYOUTS[format.channels]
+          nonstandard_layout = format.channel_layout && format.channel_layout != default_layout
+          format.channels > 2 || format.bit_depth > 16 || format.valid_bits != format.bit_depth || nonstandard_layout
         end
 
-        def channel_mask_for(channels)
+        def channel_mask_for(format)
+          if format.channel_layout
+            return format.channel_layout.sum do |position|
+              SPEAKER_BITS.fetch(position) do
+                raise UnsupportedFormatError, "WAV cannot encode channel position: #{position.inspect}"
+              end
+            end
+          end
+
+          return 0 if format.channel_layout.nil?
+
+          channels = format.channels
           return 0 if channels <= 0
           return 0x4 if channels == 1
           return 0x3 if channels == 2
@@ -439,11 +786,43 @@ module Wavify
           ((1 << [channels, 32].min) - 1) & 0xFFFF_FFFF
         end
 
+        def channel_layout_for_mask(channel_mask, channels)
+          return Core::Format::DEFAULT_CHANNEL_LAYOUTS[channels] if channel_mask.nil?
+          return Core::Format::UNKNOWN_LAYOUT if channel_mask.zero?
+
+          unknown_bits = channel_mask & ~SPEAKER_BITS.values.reduce(0, :|)
+          raise UnsupportedFormatError, "unsupported WAV channel mask bits: 0x#{unknown_bits.to_s(16)}" unless unknown_bits.zero?
+
+          layout = SPEAKER_BITS.filter_map { |position, bit| position if channel_mask.anybits?(bit) }
+          unless layout.length == channels
+            raise InvalidFormatError, "WAV channel mask has #{layout.length} positions for #{channels} channels"
+          end
+
+          layout
+        end
+
+        def canonicalize_valid_bits(samples, format)
+          shift = format.bit_depth - format.valid_bits
+          return samples if shift.zero?
+
+          samples.map { |sample| (sample >> shift) << shift }
+        end
+
         def write_chunk(io, chunk_id, chunk_data)
-          io.write(chunk_id)
-          io.write([chunk_data.bytesize].pack("V"))
-          io.write(chunk_data)
-          io.write("\x00") if chunk_data.bytesize.odd?
+          write_all(io, chunk_id)
+          write_all(io, [chunk_data.bytesize].pack("V"))
+          write_all(io, chunk_data)
+          write_all(io, "\x00") if chunk_data.bytesize.odd?
+        end
+
+        def validate_riff_sizes!(data_bytes, sample_frames, container_bytes)
+          return if data_bytes <= RIFF_MAX_SIZE && sample_frames <= RIFF_MAX_SIZE && (container_bytes - 8) <= RIFF_MAX_SIZE
+
+          raise UnsupportedFormatError, "WAV output exceeds RIFF 32-bit size limits; RF64 writing is not supported"
+        end
+
+        def strip_trailing_nuls(bytes)
+          bytes.to_s.sub(/\x00+\z/, "")
         end
 
         def skip_padding_byte(io, chunk_size)