wavefile 0.5.0 → 0.6.0

data/lib/wavefile/reader.rb

@@ -1,20 +1,33 @@
 module WaveFile
-  # Error that is raised when trying to read from a file that is either not a wave file,
+  # Error that is raised when trying to read from a file that is either not a wave file, 
   # or that is not valid according to the wave file spec.
   class InvalidFormatError < StandardError; end
 
-  # Error that is raised when trying to read from a valid wave file that has its sample data
+  # Error that is raised when trying to read from a valid wave file that has its sample data 
   # stored in a format that Reader doesn't understand.
   class UnsupportedFormatError < StandardError; end
 
 
-  # Provides the ability to read sample data out of a wave file, as well as query a
+  # Provides the ability to read sample data out of a wave file, as well as query a 
   # wave file about its metadata (e.g. number of channels, sample rate, etc).
+  #
+  # When constructing a Reader a block can be given. All data should be read inside this 
+  # block, and when the block exits the Reader will automatically be closed.
+  #
+  #     Reader.new("my_file.wav") do |reader|
+  #       # Read sample data here
+  #     end
+  #
+  # Alternately, if a block isn't given you should make sure to call close when finished reading.
+  #
+  #     reader = Reader.new("my_file.wav")
+  #     # Read sample data here
+  #     reader.close
   class Reader
-    # Returns a Reader object that is ready to start reading the specified file's sample data.
+    # Returns a Reader object that is ready to start reading the specified file's sample data. 
     #
     # file_name - The name of the wave file to read from.
-    # format - The format that read sample data should be returned in
+    # format - The format that read sample data should be returned in 
     #          (default: the wave file's internal format).
     #
     # Returns a Reader object that is ready to start reading the specified file's sample data.
@@ -50,9 +63,9 @@ module WaveFile
     end
 
 
-    # Reads metadata from the specified wave file and returns an Info object with the results.
-    # Metadata includes things like the number of channels, bits per sample, number of sample
-    # frames, sample encoding format (i.e. PCM, IEEE float, uLaw etc). See the Info object for
+    # Reads metadata from the specified wave file and returns an Info object with the results. 
+    # Metadata includes things like the number of channels, bits per sample, number of sample 
+    # frames, sample encoding format (i.e. PCM, IEEE float, uLaw etc). See the Info object for 
     # more detail on exactly what metadata is available.
     #
     # file_name - The name of the wave file to read from
@@ -74,17 +87,17 @@ module WaveFile
     end
 
 
-    # Reads sample data of the into successive Buffers of the specified size, until there is no more
-    # sample data to be read. When all sample data has been read, the Reader is automatically closed.
+    # Reads sample data of the into successive Buffers of the specified size, until there is no more 
+    # sample data to be read. When all sample data has been read, the Reader is automatically closed. 
     # Each Buffer is passed to the given block.
     #
-    # Note that sample_frame_count indicates the number of sample frames to read, not number of samples.
-    # A sample frame include one sample for each channel. For example, if sample_frame_count is 1024, then
-    # for a stereo file 1024 samples will be read from the left channel, and 1024 samples will be read from
+    # Note that sample_frame_count indicates the number of sample frames to read, not number of samples. 
+    # A sample frame include one sample for each channel. For example, if sample_frame_count is 1024, then 
+    # for a stereo file 1024 samples will be read from the left channel, and 1024 samples will be read from 
     # the right channel.
     #
-    # sample_frame_count - The number of sample frames to read into each Buffer from each channel. The number
-    #                      of sample frames read into the final Buffer could be less than this size, if there
+    # sample_frame_count - The number of sample frames to read into each Buffer from each channel. The number 
+    #                      of sample frames read into the final Buffer could be less than this size, if there 
     #                      are not enough remaining.
     #
     # Returns nothing.
@@ -99,10 +112,10 @@ module WaveFile
     end
 
 
-    # Reads the specified number of sample frames from the wave file into a Buffer. Note that the Buffer will have
+    # Reads the specified number of sample frames from the wave file into a Buffer. Note that the Buffer will have 
     # at most sample_frame_count sample frames, but could have less if the file doesn't have enough remaining.
     #
-    # sample_frame_count - The number of sample frames to read. Note that each sample frame includes a sample for
+    # sample_frame_count - The number of sample frames to read. Note that each sample frame includes a sample for 
     #                      each channel.
     #
     # Returns a Buffer containing sample_frame_count sample frames
@@ -118,24 +131,18 @@ module WaveFile
       samples = @file.sysread(sample_frame_count * @native_format.block_align).unpack(@pack_code)
       @current_sample_frame += sample_frame_count
 
-      if @native_format.channels > 1
-        num_multichannel_samples = samples.length / @native_format.channels
-        multichannel_data = Array.new(num_multichannel_samples)
-
-        if(@native_format.channels == 2)
-          # Files with more than 2 channels are expected to be less common, so if there are 2 channels
-          # using a faster specific algorithm instead of a general one.
-          num_multichannel_samples.times {|i| multichannel_data[i] = [samples.pop, samples.pop].reverse! }
-        else
-          # General algorithm that works for any number of channels, 2 or greater.
-          num_multichannel_samples.times do |i|
-            sample = Array.new(@native_format.channels)
-            @native_format.channels.times {|j| sample[j] = samples.pop }
-            multichannel_data[i] = sample.reverse!
-          end
-        end
+      if @native_format.bits_per_sample == 24
+        # Since the sample data is little endian, the 3 bytes will go from least->most significant
+        samples = samples.each_slice(3).map {|least_significant_byte, middle_byte, most_significant_byte|
+          # Convert the byte read as "C" to one read as "c"
+          most_significant_byte = [most_significant_byte].pack("c").unpack("c").first
+          
+          (most_significant_byte << 16) | (middle_byte << 8) | least_significant_byte
+        }
+      end
 
-        samples = multichannel_data.reverse!
+      if @native_format.channels > 1
+        samples = samples.each_slice(@native_format.channels).to_a
       end
 
       buffer = Buffer.new(samples, @native_format)
@@ -165,19 +172,19 @@ module WaveFile
     # Returns the name of the Wave file that is being read
     attr_reader :file_name
 
-    # Returns a Format object describing how sample data is being read from the Wave file (number of
-    # channels, sample format and bits per sample, etc). Note that this might be different from the
+    # Returns a Format object describing how sample data is being read from the Wave file (number of 
+    # channels, sample format and bits per sample, etc). Note that this might be different from the 
     # underlying format of the Wave file on disk.
     attr_reader :format
 
-    # Returns the index of the sample frame which is "cued up" for reading. I.e., the index
-    # of the next sample frame that will be read. A sample frame contains a single sample
-    # for each channel. So if there are 1,000 sample frames in a stereo file, this means
+    # Returns the index of the sample frame which is "cued up" for reading. I.e., the index 
+    # of the next sample frame that will be read. A sample frame contains a single sample 
+    # for each channel. So if there are 1,000 sample frames in a stereo file, this means 
     # there are 1,000 left-channel samples and 1,000 right-channel samples.
     attr_reader :current_sample_frame
 
-    # Returns the total number of sample frames in the file. A sample frame contains a single
-    # sample for each channel. So if there are 1,000 sample frames in a stereo file, this means
+    # Returns the total number of sample frames in the file. A sample frame contains a single 
+    # sample for each channel. So if there are 1,000 sample frames in a stereo file, this means 
     # there are 1,000 left-channel samples and 1,000 right-channel samples.
     attr_reader :total_sample_frames
 
@@ -218,7 +225,7 @@ module WaveFile
   # Used to read the RIFF chunks in a wave file up until the data chunk. Thus is can be used
   # to open a wave file and "queue it up" to the start of the actual sample data, as well as
   # extract information out of pre-data chunks, such as the format chunk.
-  class HeaderReader
+  class HeaderReader    # :nodoc:
     RIFF_CHUNK_HEADER_SIZE = 12
     FORMAT_CHUNK_MINIMUM_SIZE = 16
 
@@ -237,6 +244,14 @@ module WaveFile
           if chunk_id == CHUNK_IDS[:format]
             format_chunk = read_format_chunk(chunk_id, chunk_size)
           else
+            # 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.
+            if chunk_size.odd?
+              chunk_size += 1
+            end
+
             # Other chunk types besides the format chunk are ignored. This may change in the future.
             @file.sysread(chunk_size)
           end

data/lib/wavefile/writer.rb

@@ -1,15 +1,29 @@
 module WaveFile
   # Provides the ability to write data to a wave file.
+  #
+  # When a Writer is constructed it can be given a block. All samples should be written inside this 
+  # block, and when the block exits the file will automatically be closed:
+  #
+  #    Writer.new("my_file.wav", Format.new(:mono, :pcm_16, 44100)) do |writer|
+  #      # Write sample data here
+  #    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.
+  #
+  #    writer = Writer.new("my_file.wav", Format.new(:mono, :pcm_16, 44100))
+  #    # Write sample data here
+  #    writer.close
   class Writer
 
-    # 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
+    # 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"
+    EMPTY_BYTE = "\000"    # :nodoc:
 
-    # The number of bytes at the beginning of a wave file before the sample data in the data chunk
+    # 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)
@@ -18,16 +32,16 @@ module WaveFile
     # Data Chunk Header (8 bytes)
     #
     # All wave files written by Writer use this canonical format.
-    CANONICAL_HEADER_BYTE_LENGTH = {:pcm => 36, :float => 50}
+    CANONICAL_HEADER_BYTE_LENGTH = {:pcm => 36, :float => 50}    # :nodoc:
 
 
-    # Returns a constructed Writer object which is available for writing sample data to the specified
-    # file (via the write method). When all sample data has been written, the Writer should be closed.
-    # Note that the wave file being written to will NOT be valid (and playable in other programs) until
+    # Returns a constructed Writer object which is available for writing sample data to the specified 
+    # file (via the write method). When all sample data has been written, the Writer should be closed. 
+    # Note that the wave file being written to will NOT be valid (and playable in other programs) until 
     # the Writer has been closed.
     #
-    # If a block is given to this method, sample data can be written inside the given block. When the
-    # block terminates, the Writer will be automatically closed (and no more sample data can be written).
+    # If a block is given to this method, sample data can be written inside the given block. When the 
+    # block terminates, the Writer will be automatically closed (and no more sample data can be written). 
     #
     # If no block is given, then sample data can be written until the close method is called.
     def initialize(file_name, format)
@@ -60,7 +74,14 @@ module WaveFile
     def write(buffer)
       samples = buffer.convert(@format).samples
 
-      @file.syswrite(samples.flatten.pack(@pack_code))
+      if @format.bits_per_sample == 24 && @format.sample_format == :pcm
+        samples.flatten.each do |sample|
+          @file.syswrite([sample].pack("lX"))
+        end
+      else
+        @file.syswrite(samples.flatten.pack(@pack_code))
+      end
+
       @total_sample_frames += samples.length
     end
 
@@ -73,10 +94,10 @@ module WaveFile
 
     # Closes the Writer. After a Writer is closed, no more sample data can be written to it.
     #
-    # Note that the wave file will NOT be valid until this method is called. The wave file
-    # format requires certain information about the amount of sample data, and this can't be
-    # determined until all samples have been written. (This method doesn't need to be called
-    # when passing a block to Writer.new, as this method will automatically be called when
+    # Note that the wave file will NOT be valid until this method is called. The wave file 
+    # format requires certain information about the amount of sample data, and this can't be 
+    # determined until all samples have been written. (This method doesn't need to be called 
+    # when passing a block to Writer.new, as this method will automatically be called when 
     # the block exits).
     #
     # Returns nothing.
@@ -109,12 +130,12 @@ module WaveFile
     # Returns the name of the Wave file that is being written to
     attr_reader :file_name
 
-    # Returns a Format object describing the Wave file being written (number of channels, sample
+    # Returns a Format object describing the Wave file being written (number of channels, sample 
     # format and bits per sample, sample rate, etc.)
     attr_reader :format
 
-    # Returns the number of samples (per channel) that have been written to the file so far.
-    # For example, if 1000 "left" samples and 1000 "right" samples have been written to a stereo file,
+    # Returns the number of samples (per channel) that have been written to the file so far. 
+    # For example, if 1000 "left" samples and 1000 "right" samples have been written to a stereo file, 
     # this will return 1000.
     attr_reader :total_sample_frames
 

data/test/buffer_test.rb

@@ -106,6 +106,22 @@ class BufferTest < Test::Unit::TestCase
                  b.samples)
   end
 
+  def test_convert_buffer_bits_per_sample_8_to_24
+    # Mono
+    b = Buffer.new([0, 32, 64, 96, 128, 160, 192, 223, 255], Format.new(:mono, :pcm_8, 44100))
+    b.convert!(Format.new(:mono, :pcm_24, 44100))
+    assert_equal([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6225920, 8323072], b.samples)
+
+    # Stereo
+    b = Buffer.new([[0, 255],  [32, 223], [64, 192], [96, 160], [128, 128],
+                    [160, 96], [192, 64], [223, 32], [255, 0]],
+                   Format.new(:stereo, :pcm_8, 44100))
+    b.convert!(Format.new(:stereo, :pcm_24, 44100))
+    assert_equal([[-8388608, 8323072], [-6291456, 6225920], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                  [2097152, -2097152],   [4194304, -4194304], [6225920, -6291456], [8323072, -8388608]],
+                 b.samples)
+  end
+
   def test_convert_buffer_bits_per_sample_8_to_32
     # Mono
     b = Buffer.new([0, 32, 64, 96, 128, 160, 192, 223, 255], Format.new(:mono, :pcm_8, 44100))
@@ -158,6 +174,22 @@ class BufferTest < Test::Unit::TestCase
                  b.samples)
   end
 
+  def test_convert_buffer_bits_per_sample_16_to_24
+    # Mono
+    b = Buffer.new([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], Format.new(:mono, :pcm_16, 44100))
+    b.convert!(Format.new(:mono, :pcm_24, 44100))
+    assert_equal([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6291200, 8388352], b.samples)
+
+    # Stereo
+    b = Buffer.new([[-32768, 32767], [-24576, 24575], [-16384, 16384], [-8192, 8192], [0, 0],
+                    [8192, -8192],   [16384, -16384], [24575, -24576], [32767, -32768]],
+                   Format.new(:stereo, :pcm_16, 44100))
+    b.convert!(Format.new(:stereo, :pcm_24, 44100))
+    assert_equal([[-8388608, 8388352], [-6291456, 6291200], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                  [2097152, -2097152], [4194304, -4194304], [6291200, -6291456], [8388352, -8388608]],
+                 b.samples)
+  end
+
   def test_convert_buffer_bits_per_sample_16_to_32
     # Mono
     b = Buffer.new([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], Format.new(:mono, :pcm_16, 44100))
@@ -194,6 +226,78 @@ class BufferTest < Test::Unit::TestCase
     end
   end
 
+  def test_convert_buffer_bits_per_sample_24_to_8
+    # Mono
+    b = Buffer.new([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6291455, 8388607],
+                   Format.new(:mono, :pcm_24, 44100))
+    b.convert!(Format.new(:mono, :pcm_8, 44100))
+    assert_equal([0, 32, 64, 96, 128, 160, 192, 223, 255], b.samples)
+
+    # Stereo
+    b = Buffer.new([[-8388608, 8388607], [-6291456, 6291455], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                    [2097152, -2097152], [4194304, -4194304], [6291455, -6291456], [8388607, -8388608]],
+                   Format.new(:stereo, :pcm_24, 44100))
+    b.convert!(Format.new(:stereo, :pcm_8, 44100))
+    assert_equal([[0, 255],  [32, 223], [64, 192], [96, 160], [128, 128],
+                  [160, 96], [192, 64], [223, 32], [255, 0]],
+                 b.samples)
+  end
+
+  def test_convert_buffer_bits_per_sample_24_to_16
+    # Mono
+    b = Buffer.new([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6291455, 8388607],
+                   Format.new(:mono, :pcm_24, 44100))
+    b.convert!(Format.new(:mono, :pcm_16, 44100))
+    assert_equal([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], b.samples)
+
+    # Stereo
+    b = Buffer.new([[-8388608, 8388607], [-6291456, 6291455], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                    [2097152, -2097152], [4194304, -4194304], [6291455, -6291456], [8388607, -8388608]],
+                   Format.new(:stereo, :pcm_24, 44100))
+    b.convert!(Format.new(:stereo, :pcm_16, 44100))
+    assert_equal([[-32768, 32767], [-24576, 24575], [-16384, 16384], [-8192, 8192], [0, 0],
+                  [8192, -8192],   [16384, -16384], [24575, -24576], [32767, -32768]],
+                 b.samples)
+  end
+
+  def test_convert_buffer_bits_per_sample_24_to_32
+    # Mono
+    b = Buffer.new([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6291455, 8388607],
+                   Format.new(:mono, :pcm_24, 44100))
+    b.convert!(Format.new(:mono, :pcm_32, 44100))
+    assert_equal([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1610612480, 2147483392], b.samples)
+
+    # Stereo
+    b = Buffer.new([[-8388608, 8388607], [-6291456, 6291455], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                    [2097152, -2097152], [4194304, -4194304], [6291455, -6291456], [8388607, -8388608]],
+                   Format.new(:stereo, :pcm_24, 44100))
+    b.convert!(Format.new(:stereo, :pcm_32, 44100))
+    assert_equal([[-2147483648, 2147483392], [-1610612736, 1610612480], [-1073741824, 1073741824], [-536870912, 536870912], [0, 0],
+                  [536870912, -536870912],   [1073741824, -1073741824], [1610612480, -1610612736], [2147483392, -2147483648]],
+                 b.samples)
+  end
+
+  def test_convert_buffer_bits_per_sample_24_to_float
+    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+      float_format = "float_#{bits_per_sample}".to_sym
+
+      # Mono
+      b = Buffer.new([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6291455, 8388607],
+                     Format.new(:mono, :pcm_24, 44100))
+      b.convert!(Format.new(:mono, float_format, 44100))
+      assert_equal([-1.0, -0.75, -0.5, -0.25, 0.0, 0.25, 0.5, 0.7499998807907104, 0.9999998807907104], b.samples)
+
+      # Stereo
+      b = Buffer.new([[-8388608, 8388607], [-6291456, 6291455], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                      [2097152, -2097152], [4194304, -4194304], [6291455, -6291456], [8388607, -8388608]],
+                     Format.new(:stereo, :pcm_24, 44100))
+      b.convert!(Format.new(:stereo, float_format, 44100))
+      assert_equal([[-1.0, 0.9999998807907104], [-0.75, 0.7499998807907104 ], [-0.5, 0.5], [-0.25, 0.25], [0.0, 0.0],
+                    [0.25, -0.25], [0.5, -0.5], [0.7499998807907104 , -0.75], [0.9999998807907104, -1.0]],
+                   b.samples)
+    end
+  end
+
   def test_convert_buffer_bits_per_sample_32_to_8
     # Mono
     b = Buffer.new([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1610612735, 2147483647],
@@ -228,6 +332,23 @@ class BufferTest < Test::Unit::TestCase
                  b.samples)
   end
 
+  def test_convert_buffer_bits_per_sample_32_to_24
+    # Mono
+    b = Buffer.new([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1610612735, 2147483647],
+                   Format.new(:mono, :pcm_32, 44100))
+    b.convert!(Format.new(:mono, :pcm_24, 44100))
+    assert_equal([-8388608, -6291456, -4194304, -2097152, 0, 2097152, 4194304, 6291455, 8388607], b.samples)
+
+    # Stereo
+    b = Buffer.new([[-2147483648, 2147483647], [-1610612736, 1610612735], [-1073741824, 1073741824], [-536870912, 536870912], [0, 0],
+                  [536870912, -536870912],   [1073741824, -1073741824], [1610612735, -1610612736], [2147483647, -2147483648]],
+                   Format.new(:stereo, :pcm_32, 44100))
+    b.convert!(Format.new(:stereo, :pcm_24, 44100))
+    assert_equal([[-8388608, 8388607], [-6291456, 6291455], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                  [2097152, -2097152],   [4194304, -4194304], [6291455, -6291456], [8388607, -8388608]],
+                 b.samples)
+  end
+
   def test_convert_buffer_bits_per_sample_32_to_float
     Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym
@@ -289,6 +410,26 @@ class BufferTest < Test::Unit::TestCase
     end
   end
 
+  def test_convert_buffer_bits_per_sample_float_to_24
+    Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
+      float_format = "float_#{bits_per_sample}".to_sym
+
+      # Mono
+      b = Buffer.new([-1.0, -0.75, -0.5, -0.25, 0.0, 0.25, 0.5, 0.75, 1.0], Format.new(:mono, float_format, 44100))
+      b.convert!(Format.new(:mono, :pcm_24, 44100))
+      assert_equal([-8388607, -6291455, -4194304, -2097152, 0, 2097152, 4194304, 6291455, 8388607], b.samples)
+
+      # Stereo
+      b = Buffer.new([[-1.0, 1.0], [-0.75, 0.75], [-0.5, 0.5], [-0.25, 0.25], [0.0, 0.0],
+                      [0.25, -0.25], [0.5, -0.5], [0.75, -0.75], [1.0, -1.0]],
+                     Format.new(:stereo, float_format, 44100))
+      b.convert!(Format.new(:stereo, :pcm_24, 44100))
+      assert_equal([[-8388607, 8388607], [-6291455, 6291455], [-4194304, 4194304], [-2097152, 2097152], [0, 0],
+                    [2097152, -2097152], [4194304, -4194304], [6291455, -6291455], [8388607, -8388607]],
+                   b.samples)
+    end
+  end
+
   def test_convert_buffer_bits_per_sample_float_to_32
     Format::SUPPORTED_BITS_PER_SAMPLE[:float].each do |bits_per_sample|
       float_format = "float_#{bits_per_sample}".to_sym