wavefile 0.3.0 → 0.4.0

data/lib/wavefile/writer.rb

@@ -0,0 +1,128 @@
+module WaveFile
+  # Provides the ability to write data to a wave file.
+  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
+    # count is an odd number.
+    #
+    # See http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/riffmci.pdf, page 11.
+    EMPTY_BYTE = "\000"
+
+    # 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 (No Extension) (16 bytes)
+    # Data Chunk Header (8 bytes)
+    #
+    # All wave files written by Writer use this canonical format.
+    CANONICAL_HEADER_BYTE_LENGTH = 36
+
+
+    # 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 no block is given, then sample data can be written until the close() method is called.
+    def initialize(file_name, format)
+      @file = File.open(file_name, "wb")
+      @format = format
+
+      @samples_written = 0
+      @pack_code = PACK_CODES[format.bits_per_sample]
+
+      # Note that the correct sizes for the RIFF and data chunks can't be determined
+      # until all samples have been written, so this header as written will be incorrect.
+      # When close() is called, the correct sizes will be re-written.
+      write_header(0)
+
+      if block_given?
+        yield(self)
+        close()
+      end
+    end
+
+
+    # Appends the sample data in the given Buffer to the end of the wave file.
+    #
+    # Returns the number of sample that have been written to the file so far.
+    # Raises IOError if the Writer has been closed.
+    def write(buffer)
+      samples = buffer.convert(@format).samples
+
+      @file.syswrite(samples.flatten.pack(@pack_code))
+      @samples_written += samples.length
+    end
+
+
+    # Returns true if the Writer is closed, and false if it is open and available for writing.
+    def closed?()
+      return @file.closed?
+    end
+
+
+    # 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. 
+    #
+    # Returns nothing.
+    # Raises IOError if the Writer is already closed.
+    def close()
+      # 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
+      # written, write an empty padding byte.
+      #
+      # See http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/riffmci.pdf, page 11.
+      bytes_written = @samples_written * @format.block_align
+      if bytes_written.odd?
+        @file.syswrite(EMPTY_BYTE)
+      end
+
+      # We can't know what chunk sizes to write for the RIFF and data chunks until all
+      # samples have been written, so go back to the beginning of the file and re-write
+      # those chunk headers with the correct sizes.
+      @file.sysseek(0)
+      write_header(@samples_written)
+      
+      @file.close()
+    end
+
+    attr_reader :file_name, :format
+
+  private
+
+    # 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_count)
+      sample_data_byte_count = sample_count * @format.block_align
+
+      # Write the header for the RIFF chunk
+      header = CHUNK_IDS[:riff]
+      header += [CANONICAL_HEADER_BYTE_LENGTH + 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].pack(UNSIGNED_INT_32)
+      header += [PCM].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)
+
+      # Write the header for the data chunk
+      header += CHUNK_IDS[:data]
+      header += [sample_data_byte_count].pack(UNSIGNED_INT_32)
+
+      @file.syswrite(header)
+    end
+  end
+end

data/test/buffer_test.rb

@@ -0,0 +1,121 @@
+require 'test/unit'
+require 'wavefile.rb'
+
+include WaveFile
+
+class BufferTest < Test::Unit::TestCase
+  def test_convert
+    old_format = Format.new(1, 16, 44100)
+    new_format = Format.new(2, 16, 22050)
+
+    old_buffer = Buffer.new([-100, 0, 200], old_format)
+    new_buffer = old_buffer.convert(new_format)
+
+    assert_equal([-100, 0, 200], old_buffer.samples)
+    assert_equal(1, old_buffer.channels)
+    assert_equal(16, old_buffer.bits_per_sample)
+    assert_equal(44100, old_buffer.sample_rate)
+
+    assert_equal([[-100, -100], [0, 0], [200, 200]], new_buffer.samples)
+    assert_equal(2, new_buffer.channels)
+    assert_equal(16, new_buffer.bits_per_sample)
+    assert_equal(22050, new_buffer.sample_rate)
+  end
+
+  def test_convert!
+    old_format = Format.new(1, 16, 44100)
+    new_format = Format.new(2, 16, 22050)
+
+    old_buffer = Buffer.new([-100, 0, 200], old_format)
+    new_buffer = old_buffer.convert!(new_format)
+
+    assert(old_buffer.equal?(new_buffer))
+    assert_equal([[-100, -100], [0, 0], [200, 200]], old_buffer.samples)
+    assert_equal(2, old_buffer.channels)
+    assert_equal(16, old_buffer.bits_per_sample)
+    assert_equal(22050, old_buffer.sample_rate)
+  end
+
+
+  def test_convert_buffer_channels
+    Format::SUPPORTED_BITS_PER_SAMPLE.each do |bits_per_sample|
+      [44100, 22050].each do |sample_rate|
+        # Assert that not changing the number of channels is a no-op
+        b = Buffer.new([-100, 0, 200], Format.new(1, bits_per_sample, sample_rate))
+        b.convert!(Format.new(1, bits_per_sample, sample_rate))
+        assert_equal([-100, 0, 200], b.samples)
+
+        # Mono => Stereo
+        b = Buffer.new([-100, 0, 200], Format.new(1, bits_per_sample, sample_rate))
+        b.convert!(Format.new(2, bits_per_sample, sample_rate))
+        assert_equal([[-100, -100], [0, 0], [200, 200]], b.samples)
+
+        # Mono => 3-channel
+        b = Buffer.new([-100, 0, 200], Format.new(1, bits_per_sample, sample_rate))
+        b.convert!(Format.new(3, bits_per_sample, sample_rate))
+        assert_equal([[-100, -100, -100], [0, 0, 0], [200, 200, 200]], b.samples)
+
+        # Stereo => Mono
+        b = Buffer.new([[-100, -100], [0, 0], [200, 50], [8, 1]], Format.new(2, bits_per_sample, sample_rate))
+        b.convert!(Format.new(1, bits_per_sample, sample_rate))
+        assert_equal([-100, 0, 125, 4], b.samples)
+
+        # 3-channel => Mono
+        b = Buffer.new([[-100, -100, -100], [0, 0, 0], [200, 50, 650], [5, 1, 1], [5, 1, 2]],
+                       Format.new(3, bits_per_sample, sample_rate))
+        b.convert!(Format.new(1, bits_per_sample, sample_rate))
+        assert_equal([-100, 0, 300, 2, 2], b.samples)
+
+        # 3-channel => Stereo
+        b = Buffer.new([[-100, -100, -100], [1, 2, 3], [200, 50, 650]],
+                       Format.new(3, bits_per_sample, sample_rate))
+        b.convert!(Format.new(2, bits_per_sample, sample_rate))
+        assert_equal([[-100, -100], [1, 2], [200, 50]], b.samples)
+
+        # Unsupported conversion (4-channel => 3-channel)
+        b = Buffer.new([[-100, 200, -300, 400], [1, 2, 3, 4]],
+                       Format.new(4, bits_per_sample, sample_rate))
+        assert_raise(BufferConversionError) { b.convert!(Format.new(3, bits_per_sample, sample_rate)) }
+      end
+    end
+  end
+
+  def test_convert_buffer_bits_per_sample
+    # Assert that not changing the number of channels is a no-op
+    b = Buffer.new([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], Format.new(1, 16, 44100))
+    b.convert!(Format.new(1, 16, 44100))
+    assert_equal([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], b.samples)
+
+    # 8 => 16, Mono
+    b = Buffer.new([0, 32, 64, 96, 128, 160, 192, 223, 255], Format.new(1, 8, 44100))
+    b.convert!(Format.new(1, 16, 44100))
+    assert_equal([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24320, 32512], b.samples)
+
+    # 8 => 32, Mono
+    b = Buffer.new([0, 32, 64, 96, 128, 160, 192, 223, 255], Format.new(1, 8, 44100))
+    b.convert!(Format.new(1, 32, 44100))
+    assert_equal([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1593835520, 2130706432], b.samples)
+
+    # 16 => 8, Mono
+    b = Buffer.new([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], Format.new(1, 16, 44100))
+    b.convert!(Format.new(1, 8, 44100))
+    assert_equal([0, 32, 64, 96, 128, 160, 192, 223, 255], b.samples)
+
+    # 16 => 32, Mono
+    b = Buffer.new([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], Format.new(1, 16, 44100))
+    b.convert!(Format.new(1, 32, 44100))
+    assert_equal([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1610547200, 2147418112], b.samples)
+
+    # 32 => 8, Mono
+    b = Buffer.new([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1610612735, 2147483647],
+                   Format.new(1, 32, 44100))
+    b.convert!(Format.new(1, 8, 44100))
+    assert_equal([0, 32, 64, 96, 128, 160, 192, 223, 255], b.samples)
+
+    # 32 => 16, Mono
+    b = Buffer.new([-2147483648, -1610612736, -1073741824, -536870912, 0, 536870912, 1073741824, 1610612735, 2147483647],
+                   Format.new(1, 32, 44100))
+    b.convert!(Format.new(1, 16, 44100))
+    assert_equal([-32768, -24576, -16384, -8192, 0, 8192, 16384, 24575, 32767], b.samples)
+  end
+end

data/test/fixtures/invalid/README.markdown

@@ -0,0 +1,10 @@
+The files in this folder are not valid wave files, and should not be readable by the WaveFile gem and other audio tools/programs.
+
+* **empty.wav** - An empty file, size of 0 bytes.
+* **incomplete_riff_header.wav** - The file consists of the characters "RIFF" and nothing else.
+* **bad_riff_header.wav** - The first four bytes in the file are not "RIFF", which is a magic number required for wave files.
+* **bad_wavefile_format.wav** - The format code inside the RIFF header is not "WAVE".
+* **no_format_chunk.wav** - The file contains a valid RIFF header, but not after that.
+* **empty_format_chunk.wav** - The format chunk has no data in it, despite the format chunk header indicating is is 16 bytes long.
+* **insufficient_format_chunk.wav** - The format chunk has some data, but not the minimum amount required.
+* **no_data_chunk.wav** - The RIFF header and format chunk are valid, but there is no data chunk.

data/test/fixtures/invalid/bad_riff_header.wav

@@ -0,0 +1 @@
+This is not a wave file

data/test/fixtures/invalid/incomplete_riff_header.wav

@@ -0,0 +1 @@
+RIFF

data/test/fixtures/unsupported/README.markdown

@@ -0,0 +1,6 @@
+The files in this folder are wave files that do not violate the wave file spec, but can not be read by the WaveFile gem.
+
+* **unsupported_audio_format.wav** - The audio format defined in the format chunk is 2, or ADPCM. While a valid format, this gem only supports 1 (PCM).
+* **unsupported_bits_per_sample.wav** - The bits per sample is 24. While this is a valid sample rate, this gem only supports 8, 16, and 32 bits per sample.
+* **bad_channel_count.wav** - The channel count defined in the format chunk is 0.
+* **bad_sample_rate.wav** - The sample rate defined in the format chunk is 0.

data/test/fixtures/valid/README.markdown

@@ -0,0 +1,3 @@
+The files in this folder are valid wave files that the WaveFile gem should be able to read.
+
+Note that these files won't necessarily sound like anything if you play them. They intentionally have a small amount of sample data to make tests easy to write and test failures easier to diagnose.

data/test/format_test.rb

@@ -0,0 +1,105 @@
+require 'test/unit'
+require 'wavefile.rb'
+
+include WaveFile
+
+class FormatTest < Test::Unit::TestCase
+  def test_valid_channels()
+    [1, 2, 3, 4, 65535].each do |valid_channels|
+      assert_equal(valid_channels, Format.new(valid_channels, 16, 44100).channels)
+    end
+
+    assert_equal(1, Format.new(:mono, 16, 44100).channels)
+    assert_equal(2, Format.new(:stereo, 16, 44100).channels)
+  end
+
+  def test_invalid_channels()
+    ["dsfsfsdf", :foo, 0, -1, 65536].each do |invalid_channels|
+      assert_raise(InvalidFormatError) { Format.new(invalid_channels, 16, 44100) }
+    end
+  end
+
+  def test_valid_bits_per_sample()
+    assert_equal(8, Format.new(1, 8, 44100).bits_per_sample)
+    assert_equal(16, Format.new(1, 16, 44100).bits_per_sample)
+    assert_equal(32, Format.new(1, 32, 44100).bits_per_sample)
+  end
+
+  def test_invalid_bits_per_sample()
+    ["dsfsfsdf", :foo, 0, 12].each do |invalid_bits_per_sample|
+      assert_raise(InvalidFormatError) { Format.new(1, invalid_bits_per_sample, 44100) }
+    end
+  end
+
+  def test_valid_sample_rate()
+    [1, 44100, 4294967296].each do |valid_sample_rate|
+      assert_equal(valid_sample_rate, Format.new(1, 16, valid_sample_rate).sample_rate)
+    end
+  end
+
+  def test_invalid_sample_rate()
+    ["dsfsfsdf", :foo, 0, -1, 4294967297].each do |invalid_sample_rate|
+      assert_raise(InvalidFormatError) { Format.new(1, 16, invalid_sample_rate) }
+    end
+  end
+
+  def test_byte_rate()
+    format = Format.new(1, 8, 44100)
+    assert_equal(44100, format.byte_rate)
+
+    format = Format.new(1, 16, 44100)
+    assert_equal(88200, format.byte_rate)
+
+    format = Format.new(1, 32, 44100)
+    assert_equal(176400, format.byte_rate)
+
+    format = Format.new(2, 8, 44100)
+    assert_equal(88200, format.byte_rate)
+
+    format = Format.new(2, 16, 44100)
+    assert_equal(176400, format.byte_rate)
+
+    format = Format.new(2, 32, 44100)
+    assert_equal(352800, format.byte_rate)
+  end
+
+  def test_block_align()
+    [1, :mono].each do |one_channel|
+      format = Format.new(one_channel, 8, 44100)
+      assert_equal(1, format.block_align)
+
+      format = Format.new(one_channel, 16, 44100)
+      assert_equal(2, format.block_align)
+
+      format = Format.new(one_channel, 32, 44100)
+      assert_equal(4, format.block_align)
+    end
+
+    [2, :stereo].each do |two_channels|
+      format = Format.new(two_channels, 8, 44100)
+      assert_equal(2, format.block_align)
+
+      format = Format.new(two_channels, 16, 44100)
+      assert_equal(4, format.block_align)
+
+      format = Format.new(two_channels, 32, 44100)
+      assert_equal(8, format.block_align)
+    end
+  end
+
+  def test_mono?()
+    [1, :mono].each do |one_channel|
+      format = Format.new(one_channel, 8, 44100)
+      assert_equal(true, format.mono?)
+      assert_equal(false, format.stereo?)
+    end
+  end
+
+  def test_stereo?()
+    [2, :stereo].each do |two_channels|
+      format = Format.new(two_channels, 8, 44100)
+      assert_equal(false, format.mono?)
+      assert_equal(true, format.stereo?)
+    end
+  end
+end