wavefile 0.5.0 → 0.6.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MWI2M2Y5OWVkZTU1ZWE0MGI0MDcyOTY4ODAyODg0ZjU3YWQ3YWI0Mw==
-  data.tar.gz: !binary |-
-    YzI5Yzg1YTI2MzgxYTJmYjNkOTk1NGJkYWU4MDM4Nzk1Zjk5MjgxOA==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    ZjVlZjg0NTBjOTFhMTI2NjFlZWMzNzVlOTc5NjY4MjFjMDI5OWNmYmY5MmQ2
-    MDE0ZDAxNWUxYWFiYWU5NjRiMWU4MWE5NWQ0ZjBlNTQwNDc4ZDExYmY3NmEz
-    M2IxZmRlYTVkNjliODY3OGY2YmY4YjFhYTUzZTllNGU3M2YwNzI=
-  data.tar.gz: !binary |-
-    YjRmYWVkZDVkYjJmMGI4OTAwOTgzM2RlYTA1OGYwNmYzMGViMjAyNzk4N2Ey
-    ZTliMDVkNmNlYWMxNDg4ODA3Y2Q3YTQxZjhiNjQ3YTgwZjFiOGIwMGM1YWJk
-    MTg0MGJlMDEwOGRiNGMwY2ZhNjY5NzlhZDQ3ODU1NDlhYzUxNTY=
+SHA1:
+  metadata.gz: 48ad3ca7155a04fd1b674dd9add8f556746db460
+  data.tar.gz: a8f70d7c7ddce88d1bd93a7c2fef2963b80fc2d4
+SHA512:
+  metadata.gz: 3eb29c14f9146190fa8a01bb36e4a1e25259f09bf36d27f390bb99e1229f25abb94dd9438937fcb52f856d088b114717a626b0e78948a0156551cb313a02a2b6
+  data.tar.gz: 91d5abb8d5284a387b267ef951a5974298ceb497bb7b6cb8c7e53c034a32ac5b90c3a2f2e356cfabf788c0f279427fbdf877e5e052f42ebfc20f461de45558d4

data/README.markdown

@@ -2,6 +2,7 @@ A pure Ruby gem for reading and writing sound files in Wave format (*.wav).
 
 You can use this gem to create Ruby programs that produce 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.
 
+For more info, check out the website: <http://wavefilegem.com/>
 
 # Example Usage
 
@@ -27,7 +28,7 @@ More examples can be [found on the wiki](https://github.com/jstrait/wavefile/wik
 # Features
 
 * Ability to read and write Wave files with any number of channels in the following formats:
-  * PCM (8, 16, and 32 bits per sample)
+  * 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
 
@@ -46,24 +47,14 @@ More examples can be [found on the wiki](https://github.com/jstrait/wavefile/wik
 * Pure Ruby, so no need to compile a separate extension in order to use it.
 
 
-# Current Release: v0.5.0
+# Current Release: v0.6.0
 
 This release includes these improvements:
 
-* Support for reading and writing Wave files containing 32 and 64-bit floating point sample data.
-* Support for buffers that contain floating point data (i.e., samples between -1.0 and 1.0), including the ability to convert to and from PCM buffers.
-* A new `Duration` object which can be used to calculate the playback time given a sample rate and number of sample frames.
-* New attributes: `Reader.current_sample_frame`, `Reader.total_sample_frames`, and `Writer.total_sample_frames`.
-* Ability to get these attributes as a `Duration` object as well: `Reader.total_duration`, `Writer.total_duration`.
-* The 2nd argument to `Format.new` now indicates the sample format, not the bits per sample. For example, `:pcm_16` or `:float_32` instead of `8` or `16`. For backwards compatibility, `8`, `16`, and `32` can still be given and will be interpreted as `:pcm_8`, `:pcm_16`, and `:pcm_32`, but this support might be removed in the future.
-* Bug fix: Wave files are no longer corrupted when an unhandled exception occurs inside a `Writer` block. (Thanks to [James Tunnell](https://github.com/jamestunnell) for reporting and fixing this).
-* Bug fix: `Writer.file_name` now returns the file name, instead of always returning nil (Thanks to [James Tunnell](https://github.com/jamestunnell) for reporting this).
-
-This release also includes changes that are not backwards compatible with v0.4.0. (Until version v1.0, no guarantees to avoid this will be made, but I'll try to have a good reason before doing so).
-
-* `Info.duration` now returns a `Duration` object, instead of a hash.
-* `Info.sample_count` has been renamed `sample_frame_count`.
-* Some constants in the `WaveFile` module have changed. (In general, you should treat these as internal to this gem and not use them in your own program).
+* Support for reading and writing Wave files containing 24-bit PCM sample data, and the ability to convert buffers containing 24-bit PCM sample data to/from other formats. (Thanks to [Rich Orton](https://github.com/richorton) for suggesting this).
+* Reading files with 2 or more channels is now faster.
+* Converting buffers from one format to another is now faster in certain cases.
+* Bug fix: Files containing certain chunks with an odd size are now read properly. According to the Wave file spec, all chunks should be aligned to an even number of bytes. If the chunk has an odd size, a padding byte should be appended to bring the chunk to an even size. The `Reader` class now properly takes this expected padding byte into account for all chunks when reading files. (Previously it just took this into account for the main `data` chunk). (Thanks to [Andrew Kuklewicz](https://github.com/kookster) for reporting this).
 
 
 # Compatibility
@@ -71,7 +62,7 @@ This release also includes changes that are not backwards compatible with v0.4.0
 WaveFile has been tested with these Ruby versions, and appears to be compatible with them:
 
 * MRI 2.0.0, 1.9.3, 1.9.2, 1.9.1, 1.8.7
-* JRuby 1.7.3
+* JRuby 1.7.8
 * Rubinius 1.2.4
 * MacRuby 0.12
 

data/lib/wavefile.rb

@@ -6,11 +6,11 @@ require 'wavefile/reader'
 require 'wavefile/writer'
 
 module WaveFile
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 
-  WAVEFILE_FORMAT_CODE = "WAVE"
-  FORMAT_CHUNK_BYTE_LENGTH = {:pcm => 16, :float => 18}
-  FORMAT_CODES = {:pcm => 1, :float => 3}
+  WAVEFILE_FORMAT_CODE = "WAVE"    # :nodoc:
+  FORMAT_CHUNK_BYTE_LENGTH = {:pcm => 16, :float => 18}    # :nodoc:
+  FORMAT_CODES = {:pcm => 1, :float => 3}    # :nodoc:
   CHUNK_IDS = {:riff         => "RIFF",
                :format       => "fmt ",
                :data         => "data",
@@ -23,12 +23,12 @@ module WaveFile
                :labeled_text => "ltxt",
                :note         => "note",
                :sample       => "smpl",
-               :instrument   => "inst" }
+               :instrument   => "inst" }    # :nodoc:
 
-  PACK_CODES = {:pcm => {8 => "C*", 16 => "s*", 32 => "l*"},
-                :float => { 32 => "e*", 64 => "E*"}}
+  PACK_CODES = {:pcm => {8 => "C*", 16 => "s*", 24 => "C*", 32 => "l*"},
+                :float => { 32 => "e*", 64 => "E*"}}    # :nodoc:
 
-  UNSIGNED_INT_16 = "v"
-  UNSIGNED_INT_32 = "V"
+  UNSIGNED_INT_16 = "v"    # :nodoc:
+  UNSIGNED_INT_32 = "V"    # :nodoc:
 end
 

data/lib/wavefile/buffer.rb

@@ -1,32 +1,54 @@
 module WaveFile
-  # Error that is raised when an attempt is made to perform an unsupported or undefined
-  # conversion between two sample data formats.
+  # 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
+  # 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. You are on the honor system to make sure that the given
-    # sample data matches the given format.
+    # 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], ...] 
+    #           for a stereo file.
+    #
+    # 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
+    #   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)
+    #
+    # Returns a constructed Buffer.
     def initialize(samples, format)
       @samples = samples
       @format = format
     end
 
 
-    # Creates a new Buffer containing the sample data of this Buffer, but converted to
+    # 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
     #
     # Examples
     #
-    #   new_format = Format.new(:mono, 16, 44100)
+    #   new_format = Format.new(:mono, :pcm_16, 44100)
     #   new_buffer = old_buffer.convert(new_format)
     #
     # Returns a new Buffer; the existing Buffer is unmodified.
@@ -36,14 +58,14 @@ module WaveFile
     end
 
 
-    # Converts the sample data contained in the Buffer to a new format. The sample data
+    # 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
     #
     # Examples
     #
-    #   new_format = Format.new(:mono, 16, 44100)
+    #   new_format = Format.new(:mono, :pcm_16, 44100)
     #   old_buffer.convert!(new_format)
     #
     # Returns self.
@@ -54,30 +76,50 @@ module WaveFile
     end
 
 
-    # The number of channels the buffer's sample data has
+    # Returns the number of channels the buffer's sample data has
     def channels
       @format.channels
     end
 
 
-    # The bits per sample of the buffer's sample data
+    # Returns the bits per sample of the buffer's sample data
     def bits_per_sample
       @format.bits_per_sample
     end
 
 
-    # The sample rate of the buffer's sample data
+    # 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 
+    # for each channel.
+    #
+    # Examples
+    #
+    #   samples = mono_buffer.samples
+    #   # => [-0.5, 0.3, 0.2, -0.9, ...]
+    #
+    #   samples = stereo_buffer.samples
+    #   # => [[-0.2, 0.5], [0.1, 0.2], [-0.4, 0.7], [0.1, 0.2], ...]
+    #
+    #   samples = three_channel_buffer.samples
+    #   # => [[0.3, 0.5, 0.2], [-0.1, 0.2, -0.9], [0.2, 0.3, -0.4], [0.1, 0.2, -0.8], ...]
     attr_reader :samples
 
   private
 
     def convert_buffer(samples, old_format, new_format)
-      samples = convert_channels(samples, old_format.channels, new_format.channels)
-      samples = convert_sample_format(samples, old_format, new_format)
+      if old_format.channels > new_format.channels
+        samples = convert_channels(samples, old_format.channels, new_format.channels)
+        samples = convert_sample_format(samples, old_format, new_format)
+      else
+        samples = convert_sample_format(samples, old_format, new_format)
+        samples = convert_channels(samples, old_format.channels, new_format.channels)
+      end
 
       samples
     end
@@ -141,6 +183,8 @@ module WaveFile
         convert_sample_format_helper(samples) {|sample| (sample - 128).to_f / 128.0 }
       elsif old_bits_per_sample == 16
         convert_sample_format_helper(samples) {|sample| sample.to_f / 32768.0 }
+      elsif old_bits_per_sample == 24
+        convert_sample_format_helper(samples) {|sample| sample.to_f / 8388608.0 }
       elsif old_bits_per_sample == 32
         convert_sample_format_helper(samples) {|sample| sample.to_f / 2147483648.0 }
       end
@@ -151,6 +195,8 @@ module WaveFile
         convert_sample_format_helper(samples) {|sample| (sample * 127.0).round + 128 }
       elsif new_bits_per_sample == 16
         convert_sample_format_helper(samples) {|sample| (sample * 32767.0).round }
+      elsif new_bits_per_sample == 24
+        convert_sample_format_helper(samples) {|sample| (sample * 8388607.0).round }
       elsif new_bits_per_sample == 32
         convert_sample_format_helper(samples) {|sample| (sample * 2147483647.0).round }
       end

data/lib/wavefile/duration.rb

@@ -1,6 +1,32 @@
 module WaveFile
-  # Calculates playback time given the number of sample frames and the sample rate.
+  # Calculates playback time given the number of sample frames and the sample rate. For 
+  # example, you can use this to calculate how long a given Wave file is. 
+  #
+  # The hours, minutes, seconds, and milliseconds fields return values like you would 
+  # see on a stopwatch, and not the total amount of time in that unit. For example, a 
+  # stopwatch running for exactly 2 hours would show something like "2:00:00.000". 
+  # Accordingly, if the given sample frame count and sample rate add up to exactly 
+  # 2 hours, then hours will be 2, and minutes, seconds, and milliseconds will all be 0.
+  #
+  # This class is immutable - once a new Duration is constructed, it can't be modified.
   class Duration
+    # Constructs a new immutable Duration.
+    #
+    # sample_frame_count - The number of sample frames, i.e. the number 
+    #                      samples in each channel.
+    # sample_rate - The number of samples per second, such as 44100
+    #
+    # Examples:
+    #
+    #   duration = Duration.new(400_000_000, 44100)
+    #   duration.hours         # => 2
+    #   duration.minutes       # => 31
+    #   duration.seconds       # => 10
+    #   duration.milliseconds  # => 294
+    #
+    # Note that the hours, minutes, seconds, and milliseconds fields do not return 
+    # the total of the respective unit in the entire duration. For example, if a 
+    # duration is exactly 2 hours, then minutes will be 0, not 120.
     def initialize(sample_frame_count, sample_rate)
       @sample_frame_count = sample_frame_count
       @sample_rate = sample_rate
@@ -28,7 +54,12 @@ module WaveFile
 
       @milliseconds = (sample_frame_count / sample_frames_per_millisecond).floor
     end
-
-    attr_reader :sample_frame_count, :sample_rate, :hours, :minutes, :seconds, :milliseconds
+ 
+    attr_reader :sample_frame_count
+    attr_reader :sample_rate 
+    attr_reader :hours
+    attr_reader :minutes
+    attr_reader :seconds
+    attr_reader :milliseconds
   end
 end

data/lib/wavefile/format.rb

@@ -1,20 +1,44 @@
 module WaveFile
   class InvalidFormatError < StandardError; end
 
+  # Represents information about the data format for a Wave file, such as number of 
+  # channels, bits per sample, sample rate, and so forth. A Format instance is used 
+  # by Reader to indicate what format to read samples out as, and by Writer to 
+  # indicate what format to write samples as.
+  #
+  # This class is immutable - once a new Format is constructed, it can't be modified.
   class Format
     # Not using ranges because of 1.8.7 performance problems with Range.max
-    MIN_CHANNELS = 1
-    MAX_CHANNELS = 65535
+    MIN_CHANNELS = 1    # :nodoc:
+    MAX_CHANNELS = 65535    # :nodoc:
 
-    MIN_SAMPLE_RATE = 1
-    MAX_SAMPLE_RATE = 4_294_967_296
+    MIN_SAMPLE_RATE = 1    # :nodoc:
+    MAX_SAMPLE_RATE = 4_294_967_296    # :nodoc:
 
-    SUPPORTED_SAMPLE_FORMATS = [:pcm, :float]
+    SUPPORTED_SAMPLE_FORMATS = [:pcm, :float]    # :nodoc:
     SUPPORTED_BITS_PER_SAMPLE = {
-                                  :pcm => [8, 16, 32],
+                                  :pcm => [8, 16, 24, 32],
                                   :float => [32, 64],
-                                }
+                                }    # :nodoc:
 
+    # Constructs a new immutable Format.
+    #
+    # channels - The number of channels in the format. Can either be a Fixnum 
+    #            (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_32, :float_32, :float_64,
+    #               and :float (equivalent to :float_32)
+    # sample_rate - The number of samples per second, such as 44100
+    #
+    # Examples
+    #
+    #   format = Format.new(1, :pcm_16, 44100)
+    #   format = Format.new(:mono, :pcm_16, 44100)  # Equivalent to above
+    #
+    #   format = Format.new(:stereo, :float_32, 44100)
+    #   format = Format.new(:stereo, :float, 44100)
     def initialize(channels, format_code, sample_rate)
       channels = normalize_channels(channels)
       sample_format, bits_per_sample = normalize_format_code(format_code)
@@ -31,15 +55,37 @@ module WaveFile
       @byte_rate = @block_align * @sample_rate
     end
 
+    # Returns true if the format has 1 channel, false otherwise.
     def mono?
       @channels == 1
     end
 
+    # Returns true if the format has 2 channels, false otherwise.
     def stereo?
       @channels == 2
     end
 
-    attr_reader :channels, :sample_format, :bits_per_sample, :sample_rate, :block_align, :byte_rate
+    # Returns the number of channels, such as 1 or 2. This will always return a 
+    # Fixnum, even if the number of channels is specified with a symbol (e.g. :mono) 
+    # in the constructor.
+    attr_reader :channels
+
+    # Returns a symbol indicating the sample format, such as :pcm or :float
+    attr_reader :sample_format
+
+    # Returns the number of bits per sample, such as 8, 16, 24, 32, or 64.
+    attr_reader :bits_per_sample
+
+    # Returns the number of samples per second, such as 44100.
+    attr_reader :sample_rate
+
+    # Returns the number of bytes in each sample frame. For example, in a 16-bit stereo file, 
+    # this will be 4 (2 bytes for each 16-bit sample, times 2 channels).
+    attr_reader :block_align
+
+    # Returns the number of bytes contained in 1 second of sample data. 
+    # Is equivalent to block_align * sample_rate.
+    attr_reader :byte_rate
 
   private
 

data/lib/wavefile/info.rb

@@ -1,6 +1,9 @@
 module WaveFile
+  # Contains metadata about an existing wave file. Returned by Reader.info.
+  #
+  # This class is immutable - once a new Info is constructed, it can't be modified.
   class Info
-    def initialize(file_name, raw_format_chunk, sample_frame_count)
+    def initialize(file_name, raw_format_chunk, sample_frame_count)    # :nodoc:
       @file_name = file_name
       @audio_format = raw_format_chunk[:audio_format]
       @channels = raw_format_chunk[:channels]
@@ -13,8 +16,35 @@ module WaveFile
       @duration = Duration.new(@sample_frame_count, @sample_rate)
     end
 
-    attr_reader :file_name,
-                :audio_format, :channels, :bits_per_sample, :sample_rate, :byte_rate, :block_align,
-                :sample_frame_count, :duration
+    # Returns the name of file this Info contains metadata about.
+    attr_reader :file_name
+
+    # Returns a Fixnum indicating the audio format, such as 1 for PCM or 3 for IEEE float.
+    attr_reader :audio_format
+    
+    # Returns the number of channels, such as 1 or 2.
+    attr_reader :channels
+    
+    # Returns the number of bits per sample, such as 8, 16, 32, or 64.
+    attr_reader :bits_per_sample
+    
+    # Returns the number of samples per second, such as 44100.
+    attr_reader :sample_rate
+    
+    # Returns the number of bytes contained in 1 second of sample data. 
+    # Is equivalent to block_align * sample_rate.
+    attr_reader :byte_rate
+    
+    # Returns the number of bytes in each sample frame. For example, in a 16-bit stereo file, 
+    # this will be 4 (2 bytes for each 16-bit sample, times 2 channels).
+    attr_reader :block_align
+
+    # 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 :sample_frame_count
+    
+    # Returns a Duration instance for the total number of sample frames in the file
+    attr_reader :duration
   end
 end