wavefile 0.8.1 → 1.0.0

data/lib/wavefile/unvalidated_format.rb

@@ -15,6 +15,7 @@ module WaveFile
       @byte_rate = fields[:byte_rate]
       @block_align = fields[:block_align]
       @bits_per_sample = fields[:bits_per_sample]
+      @speaker_mapping = parse_speaker_mapping(fields[:speaker_mapping])
       @valid_bits_per_sample = fields[:valid_bits_per_sample]
     end
 
@@ -36,8 +37,7 @@ module WaveFile
       if @valid_bits_per_sample
         if @valid_bits_per_sample != @bits_per_sample
           raise UnsupportedFormatError,
-                "Sample container size (#{@bits_per_sample}) and valid bits per sample (#{@valid_bits_per_sample}) " +
-                "differ."
+                "Sample container size (#{@bits_per_sample}) and valid bits per sample (#{@valid_bits_per_sample}) differ."
         end
 
         bits_per_sample = @valid_bits_per_sample
@@ -47,7 +47,55 @@ module WaveFile
 
       sample_format = "#{FORMAT_CODES.invert[audio_format_code]}_#{bits_per_sample}".to_sym
 
-      Format.new(@channels, sample_format, @sample_rate)
+      speaker_mapping = @speaker_mapping
+      if !speaker_mapping.nil?
+        speaker_mapping = speaker_mapping[0...channels]
+      end
+
+      Format.new(@channels, sample_format, @sample_rate, speaker_mapping: speaker_mapping)
+    end
+
+  private
+
+    # Internal
+    def parse_speaker_mapping(bit_field)
+      return nil if bit_field.nil?
+
+      mapping = []
+      speaker_index = 0
+
+      while speaker_index < SPEAKER_POSITIONS.length
+        if bit_field & (2 ** speaker_index) != 0
+          mapping << SPEAKER_POSITIONS[speaker_index]
+        end
+
+        speaker_index += 1
+      end
+
+      mapping.fill(:undefined, mapping.length, @channels - mapping.length)
+      mapping.freeze
     end
+
+    # Internal
+    SPEAKER_POSITIONS = [
+      :front_left,
+      :front_right,
+      :front_center,
+      :low_frequency,
+      :back_left,
+      :back_right,
+      :front_left_of_center,
+      :front_right_of_center,
+      :back_center,
+      :side_left,
+      :side_right,
+      :top_center,
+      :top_front_left,
+      :top_front_center,
+      :top_front_right,
+      :top_back_left,
+      :top_back_center,
+      :top_back_right,
+    ].freeze
   end
 end

data/lib/wavefile/writer.rb

@@ -12,7 +12,7 @@ module WaveFile
   #    end
   #
   # If no block is given, you'll need to manually close the Writer when done. The underlaying
-  # file will not be valid or playable until close is called.
+  # file will not be valid or playable until #close is called.
   #
   #    writer = Writer.new("my_file.wav", Format.new(:mono, :pcm_16, 44100))
   #    # Write sample data here
@@ -82,9 +82,9 @@ module WaveFile
     #     writer.write(buffer)
     #   end
     #
-    #   Writer.new("my_file.wav", Format.new(:stereo, :pcm_16, 44100)) do |writer|
-    #     writer.write(buffer)
-    #   end
+    #   writer = Writer.new("my_file.wav", Format.new(:stereo, :pcm_16, 44100))
+    #   writer.write(buffer)
+    #   writer.close
     #   # This will raise WriterClosedError because the Writer has already been closed.
     #   writer.write(buffer)
     #
@@ -140,6 +140,7 @@ module WaveFile
     #   writer = Writer.new("my_file.wav", Format.new(:mono, :pcm_16, 44100))
     #   writer.write(buffer)
     #   writer.close
+    #   writer.close # Does nothing, since Writer is already closed
     #
     #   # Closing a Writer writing to an externally opened IO
     #   file = File.open("my_file.wav", "wb")
@@ -168,12 +169,10 @@ module WaveFile
     #   end
     #   # Writer is automatically closed here, because block has exited
     #
-    # Returns nothing. Has side effect of closing the Writer.
-    # Raises WriterClosedError if the Writer is already closed.
+    # Returns nothing. Has side effect of closing the Writer. If the Writer is already
+    # closed, does nothing.
     def close
-      if @closed
-        raise WriterClosedError
-      end
+      return if @closed
 
       # The RIFF specification requires that each chunk be aligned to an even number of bytes,
       # even if the byte count is an odd number. Therefore if an odd number of bytes has been
@@ -219,52 +218,106 @@ module WaveFile
 
   private
 
-    # Internal: Padding value written to the end of chunks whose payload is an odd number of bytes. The RIFF
+    # Internal
+    # Padding value written to the end of chunks whose payload is an odd number of bytes. The RIFF
     # specification requires that each chunk be aligned to an even number of bytes, even if the byte
     # count is an odd number.
     #
     # See http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/riffmci.pdf, page 11.
     EMPTY_BYTE = "\000"    # :nodoc:
 
-    # Internal: The number of bytes at the beginning of a wave file before the sample data in the data chunk
+    # Internal
+    # The number of bytes at the beginning of a wave file before the sample data in the data chunk
     # starts, assuming this canonical format:
     #
     # RIFF Chunk Header (12 bytes)
-    # Format Chunk (16 bytes for PCM, 18 bytes for floating point)
-    # FACT Chunk (0 bytes for PCM, 12 bytes for floating point)
+    # Format Chunk (16 bytes for PCM, 18 bytes for floating point, 40 bytes for WAVE_FORMAT_EXTENSIBLE)
+    # FACT Chunk (0 bytes for PCM, 12 bytes for any other format)
     # Data Chunk Header (8 bytes)
     #
     # All wave files written by Writer use this canonical format.
-    CANONICAL_HEADER_BYTE_LENGTH = {:pcm => 36, :float => 50}    # :nodoc:
+    CANONICAL_HEADER_BYTE_LENGTH = {:pcm => 36, :float => 50, :extensible => 72}.freeze    # :nodoc:
+
+    # Internal
+    FORMAT_CHUNK_BYTE_LENGTH = {:pcm => 16, :float => 18, :extensible => 40}.freeze    # :nodoc:
 
     # Internal
-    FORMAT_CHUNK_BYTE_LENGTH = {:pcm => 16, :float => 18}    # :nodoc:
+    SPEAKER_MAPPING_BIT_VALUES = {
+      undefined: 0,
+      front_left: 1,
+      front_right: 2,
+      front_center: 4,
+      low_frequency: 8,
+      back_left: 16,
+      back_right: 32,
+      front_left_of_center: 64,
+      front_right_of_center: 128,
+      back_center: 256,
+      side_left: 512,
+      side_right: 1024,
+      top_center: 2048,
+      top_front_left: 4096,
+      top_front_center: 8192,
+      top_front_right: 16384,
+      top_back_left: 32768,
+      top_back_center: 65536,
+      top_back_right: 131072,
+    }.freeze    # :nodoc:
 
-    # Internal: Writes the RIFF chunk header, format chunk, and the header for the data chunk. After this
+    # Internal
+    def pack_speaker_mapping(speaker_mapping)
+      speaker_mapping.inject(0) do |result, speaker|
+        result |= SPEAKER_MAPPING_BIT_VALUES[speaker]
+      end
+    end
+
+    # Internal
+    # Writes the RIFF chunk header, format chunk, and the header for the data chunk. After this
     # method is called the file will be "queued up" and ready for writing actual sample data.
     def write_header(sample_frame_count)
+      extensible = @format.channels > 2 ||
+                   (@format.sample_format == :pcm && @format.bits_per_sample != 8 && @format.bits_per_sample != 16) ||
+                   (@format.channels == 1 && @format.speaker_mapping != [:front_center]) ||
+                   (@format.channels == 2 && @format.speaker_mapping != [:front_left, :front_right])
+      format_code = extensible ? :extensible : @format.sample_format
+      requires_fact_chunk = (format_code != :pcm)
+
       sample_data_byte_count = sample_frame_count * @format.block_align
 
       # Write the header for the RIFF chunk
       header = CHUNK_IDS[:riff]
-      header += [CANONICAL_HEADER_BYTE_LENGTH[@format.sample_format] + sample_data_byte_count].pack(UNSIGNED_INT_32)
+      header += [CANONICAL_HEADER_BYTE_LENGTH[format_code] + sample_data_byte_count].pack(UNSIGNED_INT_32)
       header += WAVEFILE_FORMAT_CODE
 
       # Write the format chunk
       header += CHUNK_IDS[:format]
-      header += [FORMAT_CHUNK_BYTE_LENGTH[@format.sample_format]].pack(UNSIGNED_INT_32)
-      header += [FORMAT_CODES[@format.sample_format]].pack(UNSIGNED_INT_16)
+      header += [FORMAT_CHUNK_BYTE_LENGTH[format_code]].pack(UNSIGNED_INT_32)
+      header += [FORMAT_CODES[format_code]].pack(UNSIGNED_INT_16)
       header += [@format.channels].pack(UNSIGNED_INT_16)
       header += [@format.sample_rate].pack(UNSIGNED_INT_32)
       header += [@format.byte_rate].pack(UNSIGNED_INT_32)
       header += [@format.block_align].pack(UNSIGNED_INT_16)
       header += [@format.bits_per_sample].pack(UNSIGNED_INT_16)
-      if @format.sample_format == :float
+      if format_code == :float
         header += [0].pack(UNSIGNED_INT_16)
       end
 
+      if extensible
+        header += [22].pack(UNSIGNED_INT_16)
+        header += [@format.bits_per_sample].pack(UNSIGNED_INT_16)
+        header += [pack_speaker_mapping(@format.speaker_mapping)].pack(UNSIGNED_INT_32)
+
+        if @format.sample_format == :pcm
+          format_guid = WaveFile::SUB_FORMAT_GUID_PCM
+        elsif @format.sample_format == :float
+          format_guid = WaveFile::SUB_FORMAT_GUID_FLOAT
+        end
+
+        header += format_guid
+      end
+
       # Write the FACT chunk, if necessary
-      unless @format.sample_format == :pcm
+      if requires_fact_chunk
         header += CHUNK_IDS[:fact]
         header += [4].pack(UNSIGNED_INT_32)
         header += [sample_frame_count].pack(UNSIGNED_INT_32)

data/test/buffer_test.rb

@@ -1,9 +1,12 @@
 require 'minitest/autorun'
 require 'wavefile.rb'
+require 'wavefile_io_test_helper.rb'
 
 include WaveFile
 
 class BufferTest < Minitest::Test
+  include WaveFileIOTestHelper
+
   def test_convert
     old_format = Format.new(:mono, :pcm_16, 44100)
     new_format = Format.new(:stereo, :pcm_16, 22050)
@@ -38,7 +41,7 @@ class BufferTest < Minitest::Test
 
 
   def test_convert_buffer_channels
-    Format::SUPPORTED_BITS_PER_SAMPLE[:pcm].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:pcm].each do |bits_per_sample|
       format_code = "pcm_#{bits_per_sample}".to_sym
 
       [44100, 22050].each do |sample_rate|
@@ -83,7 +86,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_no_op
-    Format::SUPPORTED_BITS_PER_SAMPLE[:pcm].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:pcm].each do |bits_per_sample|
       format_code = "pcm_#{bits_per_sample}".to_sym
 
       b = Buffer.new([0, 128, 255], Format.new(:mono, format_code, 44100))
@@ -143,7 +146,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_8_to_float
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -211,7 +214,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_16_to_float
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -282,7 +285,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_24_to_float
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -354,7 +357,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_32_to_float
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -375,7 +378,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_float_to_8
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -395,7 +398,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_float_to_16
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -415,7 +418,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_float_to_24
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono
@@ -435,7 +438,7 @@ class BufferTest < Minitest::Test
   end
 
   def test_convert_buffer_bits_per_sample_float_to_32
-    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+    SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
 
       # Mono

data/test/chunk_readers/format_chunk_reader_test.rb

@@ -7,13 +7,13 @@ include WaveFile::ChunkReaders
 class FormatChunkReaderTest < Minitest::Test
   def test_basic_pcm_no_extension
     io = StringIO.new
-    io.syswrite([1].pack(UNSIGNED_INT_16))   # Audio format
-    io.syswrite([2].pack(UNSIGNED_INT_16))   # Channels
-    io.syswrite([44100].pack(UNSIGNED_INT_32))   # Sample rate
-    io.syswrite([176400].pack(UNSIGNED_INT_32))   # Byte rate
-    io.syswrite([4].pack(UNSIGNED_INT_16))   # Block align
-    io.syswrite([16].pack(UNSIGNED_INT_16))   # Bits per sample
-    io.syswrite("data")   # Start of the next chunk
+    io.write([1].pack(UNSIGNED_INT_16))   # Audio format
+    io.write([2].pack(UNSIGNED_INT_16))   # Channels
+    io.write([44100].pack(UNSIGNED_INT_32))   # Sample rate
+    io.write([176400].pack(UNSIGNED_INT_32))   # Byte rate
+    io.write([4].pack(UNSIGNED_INT_16))   # Block align
+    io.write([16].pack(UNSIGNED_INT_16))   # Bits per sample
+    io.write("data")   # Start of the next chunk
     io.rewind
 
     format_chunk_reader = FormatChunkReader.new(io, 16)
@@ -33,13 +33,13 @@ class FormatChunkReaderTest < Minitest::Test
   # is still read properly.
   def test_gibberish_no_extension
     io = StringIO.new
-    io.syswrite([555].pack(UNSIGNED_INT_16))   # Audio format
-    io.syswrite([111].pack(UNSIGNED_INT_16))   # Channels
-    io.syswrite([12345].pack(UNSIGNED_INT_32))   # Sample rate
-    io.syswrite([9].pack(UNSIGNED_INT_32))   # Byte rate
-    io.syswrite([8000].pack(UNSIGNED_INT_16))   # Block align
-    io.syswrite([23433].pack(UNSIGNED_INT_16))   # Bits per sample
-    io.syswrite("data")   # Start of the next chunk
+    io.write([555].pack(UNSIGNED_INT_16))   # Audio format
+    io.write([111].pack(UNSIGNED_INT_16))   # Channels
+    io.write([12345].pack(UNSIGNED_INT_32))   # Sample rate
+    io.write([9].pack(UNSIGNED_INT_32))   # Byte rate
+    io.write([8000].pack(UNSIGNED_INT_16))   # Block align
+    io.write([23433].pack(UNSIGNED_INT_16))   # Bits per sample
+    io.write("data")   # Start of the next chunk
     io.rewind
 
     format_chunk_reader = FormatChunkReader.new(io, 16)
@@ -57,14 +57,14 @@ class FormatChunkReaderTest < Minitest::Test
 
   def test_basic_float_with_empty_extension
     io = StringIO.new
-    io.syswrite([3].pack(UNSIGNED_INT_16))   # Audio format
-    io.syswrite([2].pack(UNSIGNED_INT_16))   # Channels
-    io.syswrite([44100].pack(UNSIGNED_INT_32))   # Sample rate
-    io.syswrite([352800].pack(UNSIGNED_INT_32))   # Byte rate
-    io.syswrite([8].pack(UNSIGNED_INT_16))   # Block align
-    io.syswrite([32].pack(UNSIGNED_INT_16))   # Bits per sample
-    io.syswrite([0].pack(UNSIGNED_INT_16))   # Extension size
-    io.syswrite("data")   # Start of the next chunk
+    io.write([3].pack(UNSIGNED_INT_16))   # Audio format
+    io.write([2].pack(UNSIGNED_INT_16))   # Channels
+    io.write([44100].pack(UNSIGNED_INT_32))   # Sample rate
+    io.write([352800].pack(UNSIGNED_INT_32))   # Byte rate
+    io.write([8].pack(UNSIGNED_INT_16))   # Block align
+    io.write([32].pack(UNSIGNED_INT_16))   # Bits per sample
+    io.write([0].pack(UNSIGNED_INT_16))   # Extension size
+    io.write("data")   # Start of the next chunk
     io.rewind
 
     format_chunk_reader = FormatChunkReader.new(io, 18)
@@ -82,17 +82,17 @@ class FormatChunkReaderTest < Minitest::Test
 
   def test_wave_format_extensible
     io = StringIO.new
-    io.syswrite([65534].pack(UNSIGNED_INT_16))   # Audio format
-    io.syswrite([2].pack(UNSIGNED_INT_16))   # Channels
-    io.syswrite([44100].pack(UNSIGNED_INT_32))   # Sample rate
-    io.syswrite([264600].pack(UNSIGNED_INT_32))   # Byte rate
-    io.syswrite([6].pack(UNSIGNED_INT_16))   # Block align
-    io.syswrite([24].pack(UNSIGNED_INT_16))   # Bits per sample
-    io.syswrite([22].pack(UNSIGNED_INT_16))   # Extension size
-    io.syswrite([20].pack(UNSIGNED_INT_16))   # Valid bits per sample
-    io.syswrite([0].pack(UNSIGNED_INT_32))   # Channel mask
-    io.syswrite(SUB_FORMAT_GUID_PCM)
-    io.syswrite("data")   # Start of the next chunk
+    io.write([65534].pack(UNSIGNED_INT_16))   # Audio format
+    io.write([2].pack(UNSIGNED_INT_16))   # Channels
+    io.write([44100].pack(UNSIGNED_INT_32))   # Sample rate
+    io.write([264600].pack(UNSIGNED_INT_32))   # Byte rate
+    io.write([6].pack(UNSIGNED_INT_16))   # Block align
+    io.write([24].pack(UNSIGNED_INT_16))   # Bits per sample
+    io.write([22].pack(UNSIGNED_INT_16))   # Extension size
+    io.write([20].pack(UNSIGNED_INT_16))   # Valid bits per sample
+    io.write([0].pack(UNSIGNED_INT_32))   # Channel mask
+    io.write(SUB_FORMAT_GUID_PCM)
+    io.write("data")   # Start of the next chunk
     io.rewind
 
     format_chunk_reader = FormatChunkReader.new(io, 40)
@@ -113,13 +113,13 @@ class FormatChunkReaderTest < Minitest::Test
 
   def test_chunk_size_too_small
     io = StringIO.new
-    io.syswrite([1].pack(UNSIGNED_INT_16))   # Audio format
-    io.syswrite([2].pack(UNSIGNED_INT_16))   # Channels
-    io.syswrite([44100].pack(UNSIGNED_INT_32))   # Sample rate
-    io.syswrite([176400].pack(UNSIGNED_INT_32))   # Byte rate
-    io.syswrite([4].pack(UNSIGNED_INT_16))   # Block align
-    io.syswrite([16].pack(UNSIGNED_INT_16))   # Bits per sample
-    io.syswrite("data")   # Start of the next chunk
+    io.write([1].pack(UNSIGNED_INT_16))   # Audio format
+    io.write([2].pack(UNSIGNED_INT_16))   # Channels
+    io.write([44100].pack(UNSIGNED_INT_32))   # Sample rate
+    io.write([176400].pack(UNSIGNED_INT_32))   # Byte rate
+    io.write([4].pack(UNSIGNED_INT_16))   # Block align
+    io.write([16].pack(UNSIGNED_INT_16))   # Bits per sample
+    io.write("data")   # Start of the next chunk
     io.rewind
 
     format_chunk_reader = FormatChunkReader.new(io, 15)