wavefile 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b591254c77ebd547a827a0e63c8b39c76ec6189
-  data.tar.gz: f3053ba74f3b4132d9002b9703040d3d1f1d500b
+  metadata.gz: 5dccc3baf1df6d96e421a5229bee8937d6a6688e
+  data.tar.gz: 39bc477f86b49caa967ada0eff54625e2288f074
 SHA512:
-  metadata.gz: deab4d8ce0c1ea47ad4b96a729b25540fd46d9c0cdcc9c68f04c662756a69b3d9d1b67a6a3a13210382e39441326f718f7aeeda136faee2dad27e98f86b736ac
-  data.tar.gz: 8177739fad9a27317666f4d2f6675a64689907ec06d9c0309ac3d0967075881c4b931c91536a4b9f7c6ac2fc8722e587159ce01e79f9078b143c0295c629ddee
+  metadata.gz: e13f217ae8eac502c631e910b67ecd3b0aff02c46a3cc7a3149dea75e02563c213eb4511e3a66fec02b62c746b3b8c0cbdb4249423684ddb5a4650396377936f
+  data.tar.gz: 3f5b047ddb807ffc9c5c88e059d2e37b1325147a42ffc562cfae1c854c8c1c711ba2f4c978541c3eccf274cd4b41612e7466e8f35e11db8f6381b7eb49d0995d

data/LICENSE

@@ -1,6 +1,6 @@
-== WaveFile
+== WaveFile Ruby Gem
 
-# Copyright (c) 2009-16 Joel Strait
+# Copyright (c) 2009-17 Joel Strait
 #
 # Permission is hereby granted, free of charge, to any person
 # obtaining a copy of this software and associated documentation

data/README.markdown

@@ -1,6 +1,6 @@
 A pure Ruby gem for reading and writing sound files in Wave format (*.wav).
 
-You can use this gem to create Ruby programs that work with audio, such as [drum machine](http://beatsdrummachine.com). Since it is written in pure Ruby (as opposed to wrapping an existing C library), you can use it without having to compile a separate extension.
+You can use this gem to create Ruby programs that work with audio, such as a [command-line drum machine](http://beatsdrummachine.com). Since it is written in pure Ruby (as opposed to wrapping an existing C library), you can use it without having to compile a separate extension.
 
 For more info, check out the website: <http://wavefilegem.com/>
 
@@ -8,76 +8,66 @@ For more info, check out the website: <http://wavefilegem.com/>
 
 This is a short example that shows how to append three separate Wave files into a single file:
 
-    require 'wavefile'
-    include WaveFile
-    
-    FILES_TO_APPEND = ["file1.wav", "file2.wav", "file3.wav"]
-    SAMPLES_PER_BUFFER = 4096
-
-    Writer.new("append.wav", Format.new(:stereo, :pcm_16, 44100)) do |writer|
-      FILES_TO_APPEND.each do |file_name|
-        Reader.new(file_name).each_buffer(SAMPLES_PER_BUFFER) do |buffer|
-          writer.write(buffer)
-        end
-      end
+```ruby
+require 'wavefile'
+include WaveFile
+
+FILES_TO_APPEND = ["file1.wav", "file2.wav", "file3.wav"]
+
+Writer.new("append.wav", Format.new(:stereo, :pcm_16, 44100)) do |writer|
+  FILES_TO_APPEND.each do |file_name|
+    Reader.new(file_name).each_buffer do |buffer|
+      writer.write(buffer)
     end
+  end
+end
+```
 
-More examples can be [found on the wiki](https://github.com/jstrait/wavefile/wiki).
+More examples can be found at <http://wavefilegem.com/examples>.
 
 
 # Features
 
-* Ability to read and write Wave files with any number of channels in the following formats:
-  * PCM (8, 16, 24, and 32 bits per sample)
-  * Floating Point (32 and 64 bits per sample)
-* Ability to read sample data from a file in any of the supported formats, regardless of the file's actual sample format
-
-            # Sample data will be returned as 32-bit floating point samples,
-            # regardless of the actual sample format in the file.
-            Reader.new("some_file.wav", Format.new(:mono, :float_32, 44100))
+This gem lets you read and write audio data! You can use it to create Ruby programs that work with sound.
 
+* Read and write Wave files with any number of channels, in PCM (8/16/24/32 bits per sample) or IEEE Floating Point (32/64 bits per sample) format.
+* Seamlessly convert between sample formats. Read sample data from a file into any format supported by this gem, regardless of how the sample data is stored in the actual file. Or, create sample data in one format (such as floats between -1.0 and 1.0), but write it to a file in a different format (such as 16-bit PCM).
 * Automatic file management, similar to how `IO.open` works. That is, you can open a file for reading or writing, and if a block is given, the file will automatically be closed when the block exits.
+* Query metadata about Wave files (sample rate, number of channels, number of sample frames, etc.), including files that are in a format this gem can't read or write.
+* Written in pure Ruby, so it's easy to include in your program. There's no need to compile a separate extension in order to use it.
 
-        Writer.new("some_file.wav", Format.new(:mono, :pcm_16, 44100)) do |writer|
-          # write some sample data
-        end
-        # At this point, the writer will automatically be closed, no need to do it manually
 
-* Ability to query metadata about Wave files (sample rate, number of channels, number of sample frames, etc.), including files that are in a format this gem can't read or write.
-* Pure Ruby, so no need to compile a separate extension in order to use it.
+# Current Release: v0.8.0
 
+Released on January 29, 2017, this version includes these changes:
 
-# Current Release: v0.7.0
-
-Released on March 6, 2016, this version includes these changes:
-
-* The minimum supported Ruby version is now 1.9.3 - earlier versions are no longer supported.
-* New method: `Reader.native_format`. Returns a `Format` instance with information about the underlaying format of the Wave file being read, which is not necessarily the same format the sample data is being converted to as it's being read.
-* `Reader.info()` has been removed. Instead, construct a new `Reader` instance and use `Reader.native_format()` - this will return a `Format` instance with the same info that would have been returned by `Reader.info()`.
-* Similarly, the `Info` class has been removed, due to `Reader.info()` being removed.
-* Constructing a `Reader` instance will no longer raise an exception if the file is valid Wave file, but in a format unsupported by this gem. The purpose of this is to allow calling `Reader.native_format()` on this instance, to get format information for files not supported by this gem.
-* New method: `Reader.readable_format?` returns true if the file is a valid format that the gem can read, false otherwise.
-* `Reader.read()` and `Reader.each_buffer()` will now raise an exception if the file is a valid Wave file, but not a format that the gem can read. Or put differently, if `Reader.readable_format?` returns `false`, any subsequent calls to `Reader.read()` or `Reader.each_buffer()` will raise an exception.
-* Some constants have been made private since they are intended for internal use.
-* Bug fix: Files will now be read/written correctly on big-endian platforms. Or in other words, sample data is always read as little-endian, regardless of the native endianness of the platform.
+* Wave files using WAVEFORMATEXTENSIBLE format (format code 65534) can now be read.
+  * Notes/Limitations
+    * The same formats supported in "vanilla" Wave files are supported when reading WAVEFORMATEXTENSIBLE files. That is, PCM (8/16/24/32 bits per sample) or IEEE_FLOAT (32/64 bits per sample).
+    * The channel speaker mapping field is not exposed.
+    * The number of valid bits per sample must match the sample container size. For example, if a file has a sample container size of 24 bits and each sample is 24 bits, then it can be read. If the container size is 32 bits and each sample is 24 bits, it _can't_ be read.
+    * Writing files using WAVEFORMATEXTENSIBLE format is not supported - all files will be written as a "vanilla" file regardless of the number of channels or sample format.
+* `Reader` and `Writer` can now be constructed using an open `IO` instance, to allow reading/writing using an arbitrary `IO`-like object (`File`, `StringIO`, etc). Previously, they could only be constructed from a file name (given by a String). Thanks to [@taf2](https://github.com/taf2) for suggesting this feature and providing an example pull request.
+* The buffer size in `Reader.each_buffer()` is now optional. If not given, a default buffer size will be used.
+* Two `Duration` objects will now evaluate to equal if they represent the same amount of time, due to an overridden definition of `==`. Thanks to [Christopher Smith](https://github.com/chrylis) for suggesting this improvement.
+* A `ReaderClosedError` is now raised (instead of `IOError`) when attempting to read from a closed `Reader` instance. However, `ReaderClosedError` extends `IOError`.
+* A `WriterClosedError` is now raised (instead of `IOError`) when attempting to read from a closed `Writer` instance. However, `ReaderClosedError` extends `IOError`.
+* **Backwards Incompatible Changes**
+  * `Reader.file_name` and `Writer.file_name` have been removed. When a `Reader` or `Writer` instance is constructed from an `IO` instance, this field wouldn't necessarily have a sensible value. Since I don't know of an obvious use-case for these fields, going ahead and removing them altogether.
+  * The long deprecated ability to provide the sample format for a `Format` instance as an integer (implying PCM format) has been removed. For example, this is no longer valid: `Format.new(:mono, 16, 44100)`. Instead, use `Format.new(:mono, :pcm_16, 44100)`.
 
 
 # Compatibility
 
 WaveFile has been tested with these Ruby versions, and appears to be compatible with them:
 
-* MRI 2.3, 2.2, 2.1, 2.0, 1.9.3
+* MRI 2.4.0, 2.3.3, 2.2.6, 2.1.10, 2.0, 1.9.3
 
 1.9.3 is the minimum supported Ruby version.
 
 If you find any compatibility issues, please let me know by opening a GitHub issue.
 
 
-# Dependencies
-
-WaveFile has no external dependencies. It is written in pure Ruby, and is entirely self-contained.
-
-
 # Installation
 
 First, install the WaveFile gem from rubygems.org:
@@ -91,6 +81,36 @@ First, install the WaveFile gem from rubygems.org:
 Note that if you're installing the gem into the default Ruby that comes pre-installed on MacOS (as opposed to a Ruby installed via [RVM](http://rvm.io/) or [rbenv](https://github.com/sstephenson/rbenv/)), you should used `sudo gem install wavefile`. Otherwise you might run into a file permission error.
 
 
+# Dependencies
+
+WaveFile has no external dependencies when used as a gem. It is written in pure Ruby, and is entirely self-contained.
+
+However, it does have dependencies for local development, in order to run the tests. See below in section "Local Development".
+
+
+# Local Development
+
+## Running the Tests
+
+First, install the required development/test dependencies:
+
+    bundle install
+
+Then, to run the tests:
+
+    bundle exec rake test
+
+## Generating test fixtures
+
+If you want to change one of the fixture `*.wav` files under `/test/fixtures`, edit the appropriate `*.yml` file defined in `/tools`, and then run this:
+
+    rake test:create_fixtures
+
+## Generating RDoc Documentation
+
+    rake rdoc
+
+
 # Contributing
 
 1. Fork my repo

data/Rakefile

@@ -1,6 +1,29 @@
 require 'rake/testtask'
+require 'rdoc/task'
+#$:.push File.expand_path("../tools", __FILE__)
 
 Rake::TestTask.new do |t|
   t.libs << "test"
   t.test_files = FileList['test/**/*_test.rb']
 end
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_files.include("README.rdoc", "lib")
+  rdoc.main = "README.rdoc"
+  rdoc.title = "WaveFile Gem - Read/Write *.wav Files with Ruby"
+  rdoc.markup = "tomdoc"
+  rdoc.rdoc_dir = "doc"
+end
+
+namespace :test do
+  task :create_fixtures do
+    ["valid", "invalid", "unsupported"].each do |subfolder|
+      fixtures = Dir.glob("tools/#{subfolder}/*.yml")
+
+      fixtures.each do |fixture|
+        basename = File.basename(fixture, ".yml")
+        `ruby tools/fixture_writer.rb #{fixture} test/fixtures/#{subfolder}/#{basename}.wav`
+      end
+    end
+  end
+end

data/lib/wavefile.rb

@@ -7,10 +7,12 @@ require 'wavefile/unvalidated_format'
 require 'wavefile/writer'
 
 module WaveFile
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 
   WAVEFILE_FORMAT_CODE = "WAVE"    # :nodoc:
-  FORMAT_CODES = {:pcm => 1, :float => 3}    # :nodoc:
+  FORMAT_CODES = {:pcm => 1, :float => 3, :extensible => 65534}    # :nodoc:
+  SUB_FORMAT_GUID_PCM = "\x01\x00\x00\x00\x00\x00\x10\x00\x80\x00\x00\xAA\x00\x38\x9B\x71".force_encoding("ASCII-8BIT")    # :nodoc:
+  SUB_FORMAT_GUID_FLOAT = "\x03\x00\x00\x00\x00\x00\x10\x00\x80\x00\x00\xAA\x00\x38\x9B\x71".force_encoding("ASCII-8BIT")    # :nodoc:
   CHUNK_IDS = {:riff         => "RIFF",
                :format       => "fmt ",
                :data         => "data",

data/lib/wavefile/buffer.rb

@@ -1,39 +1,52 @@
 module WaveFile
-  # Error that is raised when an attempt is made to perform an unsupported or undefined 
-  # conversion between two sample data formats. For example, converting a Buffer with 
-  # 3 channels into a Buffer with 2 channels is undefined.
+  # Public: Error that is raised when an attempt is made to perform an unsupported or
+  # undefined conversion between two sample data formats. For example, converting a Buffer
+  # with 3 channels into a Buffer with 2 channels is undefined.
   class BufferConversionError < StandardError; end
 
 
-  # Represents a collection of samples in a certain format (e.g. 16-bit mono). 
-  # Reader returns sample data contained in Buffers, and Writer expects incoming sample 
+  # Public: Represents a collection of samples in a certain format (e.g. 16-bit mono).
+  # Reader returns sample data contained in Buffers, and Writer expects incoming sample
   # data to be contained in a Buffer as well.
   #
   # Contains methods to convert the sample data in the buffer to a different format.
   class Buffer
 
-    # Creates a new Buffer.
+    # Public: Creates a new Buffer.
     #
-    # samples - An array of samples. If the Format has 1 channel (i.e. is mono), this 
-    #           should be a flat array of samples such as [0.5, 0.4, -0.3, ...]. If the 
-    #           Format has 2 or more channels the array should include a sub-array for 
-    #           each sample frame. For example, [[0.5, 0.2], [0.1, 0.6], [-0.2, 0.4], ...] 
+    # samples - An array of samples. If the Format has 1 channel (i.e. is mono), this
+    #           should be a flat array of samples such as [0.5, 0.4, -0.3, ...]. If the
+    #           Format has 2 or more channels the array should include a sub-array for
+    #           each sample frame. For example, [[0.5, 0.2], [0.1, 0.6], [-0.2, 0.4], ...]
     #           for a stereo file.
     #
-    # format - A Format instance which describes the sample format of the sample array. 
+    #           The individual samples should match the given format:
     #
-    #          Note that the sample array is not compared with the format to make sure 
+    #           :pcm_8    - Integer between 0 and 255
+    #           :pcm_16   - Integer between -32_768 and 32_767
+    #           :pcm_24   - Integer between -8_388_608 and 8_388_607
+    #           :pcm_32   - Integer between 2_147_483_648 and 2_147_483_647
+    #           :float    - Float between -1.0 and 1.0
+    #           :float_32 - Float between -1.0 and 1.0
+    #           :float_64 - Float between -1.0 and 1.0
+    #
+    # format - A Format instance which describes the sample format of the sample array.
+    #
+    #          Note that the sample array is not compared with the format to make sure
     #          they match - you are on the honor system to make sure they do. If they
     #          don't match, unexpected things will happen.
     #
     # Examples
     #
-    #   samples = ([0.5] * 50) + ([-0.5] * 50)   # A 440Hz mono square wave
+    #   samples = ([0.5] * 50) + ([-0.5] * 50)   # A floating point 440Hz mono square wave
     #   buffer = Buffer.new(samples, Format.new(:mono, :float, 44100)
     #
     #   samples = ([0.5, 0.5] * 50) + ([-0.5, -0.5] * 50)   # A 440Hz stereo square wave
     #   buffer = Buffer.new(samples, Format.new(2, :float, 44100)
     #
+    #   samples = ([16000] * 50) + ([-16000] * 50)   # A 16-bit PCM 440Hz mono square wave
+    #   buffer = Buffer.new(samples, Format.new(1, :pcm_16, 44100)
+    #
     # Returns a constructed Buffer.
     def initialize(samples, format)
       @samples = samples
@@ -41,8 +54,8 @@ module WaveFile
     end
 
 
-    # Creates a new Buffer containing the sample data of this Buffer, but converted to 
-    # a different format.
+    # Public: Creates a new Buffer containing the sample data of this Buffer, but converted
+    # to a different format.
     #
     # new_format - The format that the sample data should be converted to
     #
@@ -52,14 +65,15 @@ module WaveFile
     #   new_buffer = old_buffer.convert(new_format)
     #
     # Returns a new Buffer; the existing Buffer is unmodified.
+    # Raises BufferConversionError if the Buffer can't be converted to the given format
     def convert(new_format)
       new_samples = convert_buffer(@samples.dup, @format, new_format)
       Buffer.new(new_samples, new_format)
     end
 
 
-    # Converts the sample data contained in the Buffer to a new format. The sample data 
-    # is converted in place, so the existing Buffer is modified.
+    # Public: Converts the sample data contained in the Buffer to a new format. The sample
+    # data is converted in place, so the existing Buffer is modified.
     #
     # new_format - The format that the sample data should be converted to
     #
@@ -69,6 +83,7 @@ module WaveFile
     #   old_buffer.convert!(new_format)
     #
     # Returns self.
+    # Raises BufferConversionError if the Buffer can't be converted to the given format
     def convert!(new_format)
       @samples = convert_buffer(@samples, @format, new_format)
       @format = new_format
@@ -76,26 +91,26 @@ module WaveFile
     end
 
 
-    # Returns the number of channels the buffer's sample data has
+    # Public: Returns the number of channels the buffer's sample data has
     def channels
       @format.channels
     end
 
 
-    # Returns the bits per sample of the buffer's sample data
+    # Public: Returns the bits per sample of the buffer's sample data
     def bits_per_sample
       @format.bits_per_sample
     end
 
 
-    # Returns the sample rate of the buffer's sample data
+    # Public: Returns the sample rate of the buffer's sample data
     def sample_rate
       @format.sample_rate
     end
 
-    # Returns the sample data contained in the Buffer as an Array. If the Format has 
-    # 1 channel, the Array will be a flat list of samples. If the Format has 2 or more 
-    # channels, the Array will include sub arrays for each sample frame, with a sample 
+    # Public: Returns the sample data contained in the Buffer as an Array. If the Format
+    # has 1 channel, the Array will be a flat list of samples. If the Format has 2 or
+    # more channels, the Array will include sub arrays for each sample frame, with a sample
     # for each channel.
     #
     # Examples
@@ -207,10 +222,10 @@ module WaveFile
 
       if more_than_one_channel
         samples.map! do |sample|
-          sample.map! &converter
+          sample.map!(&converter)
         end
       else
-        samples.map! &converter
+        samples.map!(&converter)
       end
     end
   end

data/lib/wavefile/chunk_readers.rb

@@ -1,6 +1,12 @@
-require 'wavefile/chunk_readers/header_reader'
+require 'wavefile/chunk_readers/riff_reader'
+require 'wavefile/chunk_readers/base_chunk_reader'
+require 'wavefile/chunk_readers/generic_chunk_reader'
+require 'wavefile/chunk_readers/riff_chunk_reader'
+require 'wavefile/chunk_readers/format_chunk_reader'
+require 'wavefile/chunk_readers/data_chunk_reader'
 
 module WaveFile
+  # Internal
   module ChunkReaders    # :nodoc:
   end
 end

data/lib/wavefile/chunk_readers/base_chunk_reader.rb

@@ -0,0 +1,10 @@
+module WaveFile
+  module ChunkReaders
+    # Internal
+    class BaseChunkReader    # :nodoc:
+      def raise_error(exception_class, message)
+        raise exception_class, "Not a supported wave file. #{message}"
+      end
+    end
+  end
+end

data/lib/wavefile/chunk_readers/data_chunk_reader.rb

@@ -0,0 +1,77 @@
+module WaveFile
+  module ChunkReaders
+    # Internal
+    class DataChunkReader < BaseChunkReader    # :nodoc:
+      def initialize(io, chunk_size, raw_native_format, format=nil)
+        @io = io
+        @raw_native_format = raw_native_format
+
+        @total_sample_frames = chunk_size / @raw_native_format.block_align
+        @current_sample_frame = 0
+
+        @readable_format = true
+        begin
+          @native_format = @raw_native_format.to_validated_format
+          @pack_code = PACK_CODES[@native_format.sample_format][@native_format.bits_per_sample]
+        rescue FormatError
+          @readable_format = false
+          @native_format = nil
+          @pack_code = nil
+        end
+
+        @format = (format == nil) ? (@native_format || @raw_native_format) : format
+      end
+
+      def read(sample_frame_count)
+        raise UnsupportedFormatError unless @readable_format
+
+        if @current_sample_frame >= @total_sample_frames
+          #FIXME: Do something different here, because the end of the file has not actually necessarily been reached
+          raise EOFError
+        elsif sample_frame_count > sample_frames_remaining
+          sample_frame_count = sample_frames_remaining
+        end
+
+        samples = @io.sysread(sample_frame_count * @native_format.block_align).unpack(@pack_code)
+        @current_sample_frame += sample_frame_count
+
+        if @native_format.bits_per_sample == 24
+          samples = convert_24_bit_samples(samples)
+        end
+
+        if @native_format.channels > 1
+          samples = samples.each_slice(@native_format.channels).to_a
+        end
+
+        buffer = Buffer.new(samples, @native_format)
+        buffer.convert(@format)
+      end
+
+      attr_reader :raw_native_format,
+                  :format,
+                  :current_sample_frame,
+                  :total_sample_frames,
+                  :readable_format
+
+    private
+
+      # The number of sample frames in the file after the current sample frame
+      def sample_frames_remaining
+        @total_sample_frames - @current_sample_frame
+      end
+
+      # Since Ruby doesn't have a way to natively extract 24-bit values using pack/unpack,
+      # unsigned bytes are read instead, and then every 3 is manually combined into a
+      # signed 24-bit integer.
+      # Since the sample data is little endian, the 3 bytes will go from least->most significant
+      def convert_24_bit_samples(samples)
+        samples.each_slice(3).map do |least_significant_byte, middle_byte, most_significant_byte|
+          # Convert the most significant byte from unsigned to signed, since 24-bit samples are signed
+          most_significant_byte = [most_significant_byte].pack("c").unpack("c").first
+
+          (most_significant_byte << 16) | (middle_byte << 8) | least_significant_byte
+        end
+      end
+    end
+  end
+end