wavefile 0.8.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 21ddb98d87753898bf2893d58097b8fb53050e8e
-  data.tar.gz: b45ed2b6c1aa0c34ac760c49d0a285bf59606856
+SHA256:
+  metadata.gz: 345be2bed4e76c59bfb0163cc844399ff54bc7ca2643b82ba555c4bf167d5b5e
+  data.tar.gz: 1923c71c3af5438319425709de665acd6bf6be53f67058f7bf4b99c43d7a2493
 SHA512:
-  metadata.gz: 899880af7dc77b33d23035e7b2a1708c2e679f69f7b66fd1a302e736dccf8e1abf65bb7b2719c606e3e93977caba9882376dbd3f45708fb0d97a2c72be28c952
-  data.tar.gz: e44cc7f1066a21762ae8fb627043d1c26eb2bd7ab1254d81e4d7fcd9a66dc7c3937591b37b96903b1b6f6c7837e77a17360137351bf1610ab3e5feb3ca7cd691
+  metadata.gz: 3134a277c3c239e41e0dc60dda461223664a316e2ea16b299b61d137deee8cb545ccde99bac35566a8834571da2538aa973551d6f27b0521be9f78c0c8d88765
+  data.tar.gz: '069c9654d04eabb25c5125983b658ff468697de5eb551b7673be42fe6775a470899d20ba19e7e44c9fcd280377866ade72b1bf1aa672523065155e75c17c0604'

data/LICENSE

@@ -1,6 +1,6 @@
 == WaveFile Ruby Gem
 
-# Copyright (c) 2009-17 Joel Strait
+# Copyright (c) 2009-18 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,12 +1,12 @@
-A pure Ruby gem for reading and writing sound files in Wave format (*.wav).
+A 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 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.
+You can use this gem to create Ruby programs that work with audio, such as a [command-line drum machine](https://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/>
 
 # Example Usage
 
-This is a short example that shows how to append three separate Wave files into a single file:
+This short example shows how to append three separate Wave files into a single file:
 
 ```ruby
 require 'wavefile'
@@ -30,44 +30,44 @@ More examples can be found at <http://wavefilegem.com/examples>.
 
 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.
+* Read and write Wave files with any number of channels, in integer PCM (8/16/24/32 bits per sample) or floating point PCM (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.
 
 
-# Current Release: v0.8.1
+# Current Release: v1.0.0
 
-Released on January 31, 2017, this version fixes an error when frozen string literals are enabled in Ruby 2.3 or higher. (At the time of this release, that means Ruby 2.3 or 2.4). The gem should now work properly when the `--enable-frozen-string-literal` Ruby option is enabled. Thanks to [@samaaron](https://github.com/samaaron) for finding and fixing this!
+Released on June 10, 2018, this version has these changes:
 
-# Release v0.8.0
-
-Released on January 29, 2017, this version includes these changes:
-
-* 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)`.
+* **Ruby 2.0 or greater is now required** - the gem no longer works in Ruby 1.9.3.
+* **Backwards incompatible change:** Calling `Reader.close` on a `Reader` instance that is already closed no longer raises `ReaderClosedError`. Instead, it does nothing. Similarly, calling `Writer.close` on a `Writer` instance that is already closed no longer raises `WriterClosedError`. Thanks to [@kylekyle](https://github.com/kylekyle) for raising this as an issue.
+* **Better compatibility when writing Wave files.** `Writer` will now write files using a format called WAVE_FORMAT_EXTENSIBLE where appropriate. This is a behind-the-scenes improvement - for most use cases it won't affect how you use the gem, but can result in better compatibility with other programs.
+  * A file will automatically be written using WAVE_FORMAT_EXTENSIBLE format if any of the following are true:
+    * It has more than 2 channels
+    * It uses integer PCM sample format and the bits per sample is not 8 or 16 (in other words, if the sample format is `:pcm_24` or `:pcm_32`).
+    * A specific channel->speaker mapping is given (see below).
+* **The channel->speaker mapping field can now be read from files that have it defined.** For example, if a file indicates that the first sound channel should be mapped to the back right speaker, the second channel to the top center speaker, etc., this can be read using the `Reader.format.speaker_mapping` field.
+  * Example:
+    * ~~~
+      reader = Reader.new("4_channel_file.wav")
+      puts reader.format.speaker_mapping.inspect  # [:front_left, :front_right, :front_center, :back_center]
+      ~~~
+  * The channel->speaker mapping field isn't present in all Wave files. (Specifically, it's only present if the file uses WAVE_FORMAT_EXTENSIBLE format). For a non-WAVE_FORMAT_EXTENSIBLE file, `Reader.native_format.speaker_mapping` will be `nil`, to reflect that the channel->speaker mapping is undefined. `Reader.format.speaker_mapping` will use a "sensible" default value for the given number of channels.
+* **A channel->speaker mapping array can optionally be given when constructing a `Format` instance.** If not given, a default value will be set for the given number of channels.
+  * Example:
+    * `Format.new(4, :pcm_16, 44100, speaker_mapping: [:front_left, :front_right, :front_center, :low_frequency])`
+* **Errors raised by `Format.new` are improved to provide more detail.**
 
 
 # Compatibility
 
 WaveFile has been tested with these Ruby versions, and appears to be compatible with them:
 
-* MRI 2.4.0, 2.3.3, 2.2.6, 2.1.10, 2.0, 1.9.3
+* MRI 2.5.1, 2.4.4, 2.3.7, 2.2.10, 2.1.10, 2.0
 
-1.9.3 is the minimum supported Ruby version.
+2.0 is the minimum supported Ruby version.
 
 If you find any compatibility issues, please let me know by opening a GitHub issue.
 
@@ -87,7 +87,7 @@ Note that if you're installing the gem into the default Ruby that comes pre-inst
 
 # Dependencies
 
-WaveFile has no external dependencies when used as a gem. It is written in pure Ruby, and is entirely self-contained.
+WaveFile has no external dependencies when used as a gem.
 
 However, it does have dependencies for local development, in order to run the tests. See below in section "Local Development".
 
@@ -106,10 +106,15 @@ Then, to run the tests:
 
 ## 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:
+The `*.wav` fixtures in `test/fixtures/wave` are generated from `*.yml` files defined in `/test/fixtures/yaml`. To change one of the `*.wav` fixtures, edit the corresponding `*.yml` file, and then run:
 
     rake test:create_fixtures
 
+Similarly, if you want to add a new `*.wav` fixture, add a new `*.yml` file that describes it in `/test/fixtures/yaml`, and then run the rake command above.
+
+Behind the scenes, `rake test:create_fixtures` runs `tools/fixture_writer.rb`, which is what actually generates each `*.wav` file.
+
+
 ## Generating RDoc Documentation
 
     rake rdoc

data/Rakefile

@@ -18,11 +18,11 @@ end
 namespace :test do
   task :create_fixtures do
     ["valid", "invalid", "unsupported"].each do |subfolder|
-      fixtures = Dir.glob("tools/#{subfolder}/*.yml")
+      fixtures = Dir.glob("test/fixtures/yaml/#{subfolder}/*.yml")
 
       fixtures.each do |fixture|
         basename = File.basename(fixture, ".yml")
-        `ruby tools/fixture_writer.rb #{fixture} test/fixtures/#{subfolder}/#{basename}.wav`
+        `ruby tools/fixture_writer.rb #{fixture} test/fixtures/wave/#{subfolder}/#{basename}.wav`
       end
     end
   end

data/lib/wavefile.rb

@@ -7,10 +7,10 @@ require 'wavefile/unvalidated_format'
 require 'wavefile/writer'
 
 module WaveFile
-  VERSION = "0.8.1"
+  VERSION = "1.0.0"
 
   WAVEFILE_FORMAT_CODE = "WAVE"    # :nodoc:
-  FORMAT_CODES = {:pcm => 1, :float => 3, :extensible => 65534}    # :nodoc:
+  FORMAT_CODES = {:pcm => 1, :float => 3, :extensible => 65534}.freeze    # :nodoc:
   SUB_FORMAT_GUID_PCM = String.new("\x01\x00\x00\x00\x00\x00\x10\x00\x80\x00\x00\xAA\x00\x38\x9B\x71").force_encoding("ASCII-8BIT").freeze   # :nodoc:
   SUB_FORMAT_GUID_FLOAT = String.new("\x03\x00\x00\x00\x00\x00\x10\x00\x80\x00\x00\xAA\x00\x38\x9B\x71").force_encoding("ASCII-8BIT").freeze   # :nodoc:
   CHUNK_IDS = {:riff         => "RIFF",
@@ -25,10 +25,10 @@ module WaveFile
                :labeled_text => "ltxt",
                :note         => "note",
                :sample       => "smpl",
-               :instrument   => "inst" }    # :nodoc:
+               :instrument   => "inst" }.freeze    # :nodoc:
 
-  PACK_CODES = {:pcm   => { 8  => "C*", 16 => "s<*", 24 => "C*", 32 => "l<*"},
-                :float => { 32 => "e*", 64 => "E*"}}    # :nodoc:
+  PACK_CODES = {:pcm   => { 8  => "C*", 16 => "s<*", 24 => "C*", 32 => "l<*"}.freeze,
+                :float => { 32 => "e*", 64 => "E*"}.freeze}.freeze    # :nodoc:
 
   UNSIGNED_INT_16 = "v"    # :nodoc:
   UNSIGNED_INT_32 = "V"    # :nodoc:

data/lib/wavefile/chunk_readers/format_chunk_reader.rb

@@ -33,7 +33,7 @@ module WaveFile
             raise_error InvalidFormatError, "The format chunk extension is shorter than expected."
           end
 
-          if format_chunk[:extension_size] == 22
+          if format_chunk[:audio_format] == FORMAT_CODES[:extensible]
             format_chunk[:valid_bits_per_sample] = raw_bytes.slice!(0...2).unpack(UNSIGNED_INT_16).first
             format_chunk[:speaker_mapping] = raw_bytes.slice!(0...4).unpack(UNSIGNED_INT_32).first
             format_chunk[:sub_audio_format_guid] = raw_bytes

data/lib/wavefile/duration.rb

@@ -78,7 +78,7 @@ module WaveFile
       @seconds == other_duration.seconds &&
       @milliseconds == other_duration.milliseconds
     end
- 
+
     # Public
     attr_reader :sample_frame_count
 

data/lib/wavefile/format.rb

@@ -4,8 +4,9 @@ module WaveFile
   # this Gem. Or, because it's a not a valid Wave file period.
   class FormatError < StandardError; end
 
-  # Public: 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.
+  # Public: Error that is raised when constructing a Format instance that is not valid,
+  # trying to read from a file that is not a wave file, or trying to read from a file
+  # that is not valid according to the wave file spec.
   class InvalidFormatError < FormatError; end
 
   # Public: Error that is raised when trying to read from a valid wave file that has its sample data
@@ -23,13 +24,26 @@ module WaveFile
     # Public: Constructs a new immutable Format.
     #
     # channels - The number of channels in the format. Can either be an Integer
-    #            (e.g. 1, 2, 3) or the symbols :mono (equivalent to 1) or
-    #            :stereo (equivalent to 2).
+    #            (e.g. 1, 2, 3) or the symbols +:mono+ (equivalent to 1) or
+    #            +:stereo+ (equivalent to 2).
     # format_code - A symbol indicating the format of each sample. Consists of
     #               two parts: a format code, and the bits per sample. The valid
-    #               values are :pcm_8, :pcm_16, :pcm_24, :pcm_32, :float_32,
-    #               :float_64, and :float (equivalent to :float_32)
+    #               values are +:pcm_8+, +:pcm_16+, +:pcm_24+, +:pcm_32+, +:float_32+,
+    #               +:float_64+, and +:float+ (equivalent to +:float_32+)
     # sample_rate - The number of samples per second, such as 44100
+    # speaker_mapping - An optional array which indicates which speaker each channel should be
+    #                   mapped to. Each value in the array should be one of these values:
+    #                   +: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+. Each value should only appear once, and the channels
+    #                   must follow the ordering above. For example, [:front_center, :back_left]
+    #                   is a valid speaker mapping, but [:back_left, :front_center] is not.
+    #                   If a given channel should not be mapped to a specific speaker, the
+    #                   value :undefined can be used. If this field is omitted, a default
+    #                   value for the given number of channels. For example, if there are 2
+    #                   channels, this will be set to [:front_left, :front_right].
     #
     # Examples
     #
@@ -38,20 +52,42 @@ module WaveFile
     #
     #   format = Format.new(:stereo, :float_32, 44100)
     #   format = Format.new(:stereo, :float, 44100)  # Equivalent to above
-    def initialize(channels, format_code, sample_rate)
+    #
+    #   format = Format.new(2, :pcm_16, 44100, speaker_mapping: [:front_right, :front_center])
+    #
+    #   # Channels should explicitly not be mapped to particular speakers
+    #   # (otherwise, if no speaker_mapping set, it will be set to a default
+    #   # value for the number of channels).
+    #   format = Format.new(2, :pcm_16, 44100, speaker_mapping: [:undefined, :undefined])
+    #
+    #   # Will result in InvalidFormatError, because speakers are defined in
+    #   # invalid order
+    #   format = Format.new(2, :pcm_16, 44100, speaker_mapping: [:front_right, :front_left])
+    #
+    #   # speaker_mapping will be set to [:front_left, :undefined, :undefined],
+    #   # because channels without a speaker mapping will be mapped to :undefined
+    #   format = Format.new(3, :pcm_16, 44100, speaker_mapping: [:front_left])
+    #
+    # Raises InvalidFormatError if the given arguments are invalid.
+    def initialize(channels, format_code, sample_rate, speaker_mapping: nil)
       channels = normalize_channels(channels)
-      sample_format, bits_per_sample = normalize_format_code(format_code)
+
       validate_channels(channels)
-      validate_sample_format(sample_format)
-      validate_bits_per_sample(sample_format, bits_per_sample)
+      validate_format_code(format_code)
       validate_sample_rate(sample_rate)
 
+      sample_format, bits_per_sample = normalize_format_code(format_code)
+
+      speaker_mapping = normalize_speaker_mapping(channels, speaker_mapping)
+      validate_speaker_mapping(channels, speaker_mapping)
+
       @channels = channels
       @sample_format = sample_format
       @bits_per_sample = bits_per_sample
       @sample_rate = sample_rate
       @block_align = (@bits_per_sample / 8) * @channels
       @byte_rate = @block_align * @sample_rate
+      @speaker_mapping = speaker_mapping
     end
 
     # Public: Returns true if the format has 1 channel, false otherwise.
@@ -86,6 +122,9 @@ module WaveFile
     # Is equivalent to block_align * sample_rate.
     attr_reader :byte_rate
 
+    # Public: Returns the mapping of each channel to a speaker.
+    attr_reader :speaker_mapping
+
   private
 
     # Internal
@@ -94,12 +133,7 @@ module WaveFile
     VALID_SAMPLE_RATE_RANGE = 1..4_294_967_296    # :nodoc:
 
     # Internal
-    SUPPORTED_SAMPLE_FORMATS = [:pcm, :float]    # :nodoc:
-    # Internal
-    SUPPORTED_BITS_PER_SAMPLE = {
-                                  :pcm => [8, 16, 24, 32],
-                                  :float => [32, 64],
-                                }    # :nodoc:
+    SUPPORTED_FORMAT_CODES = [:pcm_8, :pcm_16, :pcm_24, :pcm_32, :float, :float_32, :float_64].freeze    # :nodoc:
 
     # Internal
     def normalize_channels(channels)
@@ -123,37 +157,94 @@ module WaveFile
     end
 
     # Internal
-    def validate_sample_format(candidate_sample_format)
-      unless SUPPORTED_SAMPLE_FORMATS.include? candidate_sample_format
-        raise InvalidFormatError,
-              "Sample format of #{candidate_sample_format} is unsupported. " +
-              "Only #{SUPPORTED_SAMPLE_FORMATS.inspect} are supported."
+    def normalize_speaker_mapping(channels, speaker_mapping)
+      if speaker_mapping.nil?
+        speaker_mapping = default_speaker_mapping(channels)
+      elsif !speaker_mapping.is_a?(Array)
+        return speaker_mapping
+      else
+        speaker_mapping = speaker_mapping.dup
+      end
+
+      if speaker_mapping.length < channels
+        speaker_mapping += [:undefined] * (channels - speaker_mapping.length)
+      end
+
+      speaker_mapping.freeze
+    end
+
+    # Internal
+    def default_speaker_mapping(channels)
+      # These default mappings determined from these sources:
+      #
+      # See https://docs.microsoft.com/en-us/windows-hardware/drivers/audio/extensible-wave-format-descriptors
+      # This article says to use the `front_center` speaker for mono files when using WAVE_FORMAT_EXTENSIBLE
+      #
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/dd390971(v=vs.85).aspx
+      #
+      # https://xiph.org/flac/format.html#frame_header
+      if channels == 1  # Mono
+        [:front_center]
+      elsif channels == 2  # Stereo
+        [:front_left, :front_right]
+      elsif channels == 3
+        [:front_left, :front_right, :front_center]
+      elsif channels == 4  # Quad
+        [:front_left, :front_right, :back_left, :back_right]
+      elsif channels == 5
+        [:front_left, :front_right, :front_center, :back_left, :back_right]
+      elsif channels == 6  # 5.1
+        [:front_left, :front_right, :front_center, :low_frequency, :back_left, :back_right]
+      elsif channels == 7
+        [:front_left, :front_right, :front_center, :low_frequency, :back_center, :side_left, :side_right]
+      elsif channels == 8  # 7.1
+        [:front_left, :front_right, :front_center, :low_frequency, :back_left, :back_right, :front_left_of_center, :front_right_of_center]
+      elsif channels <= UnvalidatedFormat::SPEAKER_POSITIONS.length
+        UnvalidatedFormat::SPEAKER_POSITIONS[0...channels]
+      else
+        UnvalidatedFormat::SPEAKER_POSITIONS
       end
     end
 
     # Internal
     def validate_channels(candidate_channels)
-      unless VALID_CHANNEL_RANGE === candidate_channels
+      unless candidate_channels.is_a?(Integer) && VALID_CHANNEL_RANGE === candidate_channels
         raise InvalidFormatError,
-              "Invalid number of channels. Must be between #{VALID_CHANNEL_RANGE.min} and #{VALID_CHANNEL_RANGE.max}."
+              "Invalid number of channels: `#{candidate_channels}`. Must be an Integer between #{VALID_CHANNEL_RANGE.min} and #{VALID_CHANNEL_RANGE.max}."
       end
     end
 
     # Internal
-    def validate_bits_per_sample(candidate_sample_format, candidate_bits_per_sample)
-      unless SUPPORTED_BITS_PER_SAMPLE[candidate_sample_format].include? candidate_bits_per_sample
+    def validate_format_code(candidate_format_code)
+      unless SUPPORTED_FORMAT_CODES.include? candidate_format_code
         raise InvalidFormatError,
-              "Bits per sample of #{candidate_bits_per_sample} is unsupported for " +
-              "sample format #{candidate_sample_format}."
+              "Invalid sample format: `#{candidate_format_code}`. Must be one of: #{SUPPORTED_FORMAT_CODES.inspect}"
       end
     end
 
     # Internal
     def validate_sample_rate(candidate_sample_rate)
-      unless VALID_SAMPLE_RATE_RANGE === candidate_sample_rate
+      unless candidate_sample_rate.is_a?(Integer) && VALID_SAMPLE_RATE_RANGE === candidate_sample_rate
         raise InvalidFormatError,
-              "Invalid sample rate. Must be between #{VALID_SAMPLE_RATE_RANGE.min} and #{VALID_SAMPLE_RATE_RANGE.max}"
+              "Invalid sample rate: `#{candidate_sample_rate}`. Must be an Integer between #{VALID_SAMPLE_RATE_RANGE.min} and #{VALID_SAMPLE_RATE_RANGE.max}"
+      end
+    end
+
+    # Internal
+    def validate_speaker_mapping(channels, candidate_speaker_mapping)
+      if candidate_speaker_mapping.is_a?(Array) && candidate_speaker_mapping.length == channels
+        speaker_mapping_without_invalid_speakers = UnvalidatedFormat::SPEAKER_POSITIONS & candidate_speaker_mapping
+        if speaker_mapping_without_invalid_speakers.length < channels
+          speaker_mapping_without_invalid_speakers += [:undefined] * (channels - speaker_mapping_without_invalid_speakers.length)
+        end
+
+        if speaker_mapping_without_invalid_speakers == candidate_speaker_mapping
+          return
+        end
       end
+
+      raise InvalidFormatError,
+            "Invalid speaker_mapping: `#{candidate_speaker_mapping.inspect}`. Should be an array the same size as the number of channels, containing either :undefined or these known speakers: #{UnvalidatedFormat::SPEAKER_POSITIONS.inspect}. Each defined speaker must come before any of the ones after it in the master list, and all :undefined speakers must come after the last defined speaker."
     end
   end
 end

data/lib/wavefile/reader.rb

@@ -27,7 +27,7 @@ module WaveFile
     #          (default: the wave file's internal format).
     #
     # Returns a Reader object that is ready to start reading the specified file's sample data.
-    # Raises Errno::ENOENT if the specified file can't be found
+    # Raises +Errno::ENOENT+ if the specified file can't be found
     # Raises InvalidFormatError if the specified file isn't a valid wave file
     def initialize(io_or_file_name, format=nil)
       if io_or_file_name.is_a?(String)
@@ -45,7 +45,7 @@ module WaveFile
       rescue InvalidFormatError
         raise InvalidFormatError, "Does not appear to be a valid Wave file"
       end
-      
+
       @data_chunk_reader = riff_reader.data_chunk_reader
 
       if block_given?
@@ -133,16 +133,15 @@ module WaveFile
     end
 
 
-    # Public: Closes the Reader. After a Reader is closed, no more sample data can be read from it.
-    # Note: If the Reader is constructed from an open IO instance (as opposed to a file name),
-    # the IO instance will _not_ be closed. You'll have to manually close it yourself.
+    # Public: Closes the Reader. If the Reader is already closed, does nothing. After a Reader
+    # is closed, no more sample data can be read from it. Note: If the Reader is constructed
+    # from an open IO instance (as opposed to a file name), the IO instance will _not_ be closed.
+    # You'll have to manually close it yourself. This is intentional, because Reader can't know
+    # what you may/may not want to do with the IO instance in the future.
     #
     # Returns nothing.
-    # Raises ReaderClosedError if the Reader is already closed.
     def close
-      if @closed
-        raise ReaderClosedError
-      end
+      return if @closed
 
       if @io_source == :file_name
         @io.close
@@ -156,23 +155,26 @@ module WaveFile
       Duration.new(total_sample_frames, @data_chunk_reader.format.sample_rate)
     end
 
-    # Public: Returns a Format object describing the sample format of the Wave file being read.
-    # This is not necessarily the format that the sample data will be read as - to determine
-    # that, use #format.
+    # Public: Returns an object describing the sample format of the Wave file being read.
+    # This returns the data contained in the "fmt " chunk of the Wave file. It will not
+    # necessarily match the format that the samples are read out as (for that, see #format).
     def native_format
       @data_chunk_reader.raw_native_format
     end
 
     # Public: Returns true if this is a valid Wave file and contains sample data that is in a format
     # that this class can read, and returns false if this is a valid Wave file but does not
-    # contain a sample format supported by this class.
+    # contain a sample format that this gem knows how to read.
     def readable_format?
       @data_chunk_reader.readable_format
     end
 
-    # Public: 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.
+    # Public: Returns an object describing how sample data is being read from the Wave file.
+    # I.e., number of channels, bits per sample, sample format, etc. If #readable_format? is
+    # true, then this will be a Format object. The format the samples are read out as might
+    # be different from how the samples are actually stored in the file. Therefore, #format
+    # might not match #native_format. If #readable_format? is false, then this will return the
+    # same value as #native_format.
     def format
       @data_chunk_reader.format
     end