wavefile 0.4.0 → 0.5.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!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=

data/LICENSE

@@ -1,6 +1,6 @@
 == WaveFile
 
-# Copyright (c) 2009-12 Joel Strait
+# Copyright (c) 2009-13 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,31 +1,79 @@
-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).
+A pure Ruby gem for reading and writing sound files in Wave format (*.wav).
 
-# What's New in v0.4.0?
+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.
 
-This version is a re-write with a completely new, much improved API. (The old API has been removed). Some improvements due to the new API include:
 
-* Reduced memory consumption, due to not having to load the entire file into memory. In practice, this allows the gem to read/write files that previously would have been prohibitively large.
-* Better performance for large files, for the same reason as above.
-* Ability to progressively append data to the end of a file, instead of writing the entire file at once.
-* Ability to easily read and write data in an arbitrary format, regardless of the file's native format. For example, you can transparently read data out of a 16-bit stereo file as 8-bit mono.
-* Automatic file management, similar to how IO.open() works. It's easy to continually read the sample data from a file, passing each buffer to a block, and have the file automatically close when there is no more data left.
+# Example Usage
 
-Other improvements include:
+This is a short example that shows how to append three separate Wave files into a single file:
 
-* Ability to query format metadata of files without opening them, even for formats that this gem can't read or write.
-* Support for reading and writing 32-bit PCM files.
+    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
+    end
+
+More examples can be [found on the wiki](https://github.com/jstrait/wavefile/wiki).
+
+
+# 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)
+  * 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))
+
+* 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.
 
-However, reading or writing data as floating point (i.e. values between -1.0 and 1.0) won't be supported in v0.4.0 to keep the scope in check. It might be re-added in the future.
+        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.5.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).
 
 
 # Compatibility
 
 WaveFile has been tested with these Ruby versions, and appears to be compatible with them:
 
-* MRI 1.9.3, 1.9.2, 1.9.1, 1.8.7
-* JRuby 1.6.5
+* MRI 2.0.0, 1.9.3, 1.9.2, 1.9.1, 1.8.7
+* JRuby 1.7.3
 * Rubinius 1.2.4
-* MacRuby 0.10
+* MacRuby 0.12
 
 If you find any compatibility issues, please let me know by opening a GitHub issue.
 
@@ -45,8 +93,13 @@ First, install the WaveFile gem from rubygems.org:
 
     require 'wavefile'
 
-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://beginrescueend.com/)), you should used `sudo gem install wavefile`. Otherwise you might run into a file permission error.
+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://beginrescueend.com/) or [rbenv](https://github.com/sstephenson/rbenv/)), you should used `sudo gem install wavefile`. Otherwise you might run into a file permission error.
+
 
-# Usage
+# Contributing
 
-For usage instructions with examples, check out the [wiki](https://github.com/jstrait/wavefile/wiki).
+1. Fork my repo
+2. Create a branch for your changes
+3. Add your changes, and please include tests
+4. Make sure the tests pass by running `rake test`
+5. Create a pull request

data/lib/wavefile/buffer.rb

@@ -32,7 +32,7 @@ module WaveFile
     # Returns a new Buffer; the existing Buffer is unmodified.
     def convert(new_format)
       new_samples = convert_buffer(@samples.dup, @format, new_format)
-      return Buffer.new(new_samples, new_format)
+      Buffer.new(new_samples, new_format)
     end
 
 
@@ -50,25 +50,25 @@ module WaveFile
     def convert!(new_format)
       @samples = convert_buffer(@samples, @format, new_format)
       @format = new_format
-      return self
+      self
     end
 
 
     # The number of channels the buffer's sample data has
     def channels
-      return @format.channels
+      @format.channels
     end
 
 
     # The bits per sample of the buffer's sample data
     def bits_per_sample
-      return @format.bits_per_sample
+      @format.bits_per_sample
     end
 
 
     # The sample rate of the buffer's sample data
     def sample_rate
-      return @format.sample_rate
+      @format.sample_rate
     end
 
     attr_reader :samples
@@ -76,18 +76,15 @@ module WaveFile
   private
 
     def convert_buffer(samples, old_format, new_format)
-      unless old_format.channels == new_format.channels
-        samples = convert_buffer_channels(samples, old_format.channels, new_format.channels)
-      end
-
-      unless old_format.bits_per_sample == new_format.bits_per_sample
-        samples = convert_buffer_bits_per_sample(samples, old_format.bits_per_sample, new_format.bits_per_sample)
-      end
+      samples = convert_channels(samples, old_format.channels, new_format.channels)
+      samples = convert_sample_format(samples, old_format, new_format)
 
-      return samples
+      samples
     end
 
-    def convert_buffer_channels(samples, old_channels, new_channels)
+    def convert_channels(samples, old_channels, new_channels)
+      return samples if old_channels == new_channels
+
       # The cases of mono -> stereo and vice-versa are handled specially,
       # because those conversion methods are faster than the general methods,
       # and the large majority of wave files are expected to be either mono or stereo.
@@ -106,42 +103,69 @@ module WaveFile
               "Conversion of sample data from #{old_channels} channels to #{new_channels} channels is unsupported"
       end
 
-      return samples
+      samples
+    end
+
+    def convert_sample_format(samples, old_format, new_format)
+      return samples if old_format.sample_format == :float && new_format.sample_format == :float
+
+      if old_format.sample_format == :pcm && new_format.sample_format == :pcm
+        convert_sample_format_pcm_to_pcm(samples, old_format.bits_per_sample, new_format.bits_per_sample)
+      elsif old_format.sample_format == :pcm && new_format.sample_format == :float
+        convert_sample_format_pcm_to_float(samples, old_format.bits_per_sample, new_format.bits_per_sample)
+      elsif old_format.sample_format == :float && new_format.sample_format == :pcm
+        convert_sample_format_float_to_pcm(samples, old_format.bits_per_sample, new_format.bits_per_sample)
+      end
     end
 
-    def convert_buffer_bits_per_sample(samples, old_bits_per_sample, new_bits_per_sample)
+    def convert_sample_format_pcm_to_pcm(samples, old_bits_per_sample, new_bits_per_sample)
+      return samples if old_bits_per_sample == new_bits_per_sample
+
       shift_amount = (new_bits_per_sample - old_bits_per_sample).abs
-      more_than_one_channel = (Array === samples.first)
 
       if old_bits_per_sample == 8
-        if more_than_one_channel
-          samples.map! do |sample|
-            sample.map! {|sub_sample| (sub_sample - 128) << shift_amount }
-          end
-        else
-          samples.map! {|sample| (sample - 128) << shift_amount }
-        end
+        convert_sample_format_helper(samples) {|sample| (sample - 128) << shift_amount }
       elsif new_bits_per_sample == 8
-        if more_than_one_channel
-          samples.map! do |sample|
-            sample.map! {|sub_sample| (sub_sample >> shift_amount) + 128 }
-          end
-        else
-          samples.map! {|sample| (sample >> shift_amount) + 128 }
-        end
+        convert_sample_format_helper(samples) {|sample| (sample >> shift_amount) + 128 }
       else
-        operator = (new_bits_per_sample > old_bits_per_sample) ? :<< : :>>
-
-        if more_than_one_channel
-          samples.map! do |sample|
-            sample.map! {|sub_sample| sub_sample.send(operator, shift_amount) }
-          end
+        if new_bits_per_sample > old_bits_per_sample
+          convert_sample_format_helper(samples) {|sample| sample << shift_amount }
         else
-          samples.map! {|sample| sample.send(operator, shift_amount) }
+          convert_sample_format_helper(samples) {|sample| sample >> shift_amount }
         end
       end
+    end
+
+    def convert_sample_format_pcm_to_float(samples, old_bits_per_sample, new_bits_per_sample)
+      if old_bits_per_sample == 8
+        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 == 32
+        convert_sample_format_helper(samples) {|sample| sample.to_f / 2147483648.0 }
+      end
+    end
+
+    def convert_sample_format_float_to_pcm(samples, old_bits_per_sample, new_bits_per_sample)
+      if new_bits_per_sample == 8
+        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 == 32
+        convert_sample_format_helper(samples) {|sample| (sample * 2147483647.0).round }
+      end
+    end
+
+    def convert_sample_format_helper(samples, &converter)
+      more_than_one_channel = (Array === samples.first)
 
-      return samples
+      if more_than_one_channel
+        samples.map! do |sample|
+          sample.map! &converter
+        end
+      else
+        samples.map! &converter
+      end
     end
   end
 end

data/lib/wavefile/duration.rb

@@ -0,0 +1,34 @@
+module WaveFile
+  # Calculates playback time given the number of sample frames and the sample rate.
+  class Duration
+    def initialize(sample_frame_count, sample_rate)
+      @sample_frame_count = sample_frame_count
+      @sample_rate = sample_rate
+
+      sample_frames_per_millisecond = sample_rate / 1000.0
+      sample_frames_per_second = sample_rate
+      sample_frames_per_minute = sample_frames_per_second * 60
+      sample_frames_per_hour = sample_frames_per_minute * 60
+      @hours, @minutes, @seconds, @milliseconds = 0, 0, 0, 0
+
+      if(sample_frame_count >= sample_frames_per_hour)
+        @hours = sample_frame_count / sample_frames_per_hour
+        sample_frame_count -= sample_frames_per_hour * @hours
+      end
+
+      if(sample_frame_count >= sample_frames_per_minute)
+        @minutes = sample_frame_count / sample_frames_per_minute
+        sample_frame_count -= sample_frames_per_minute * @minutes
+      end
+
+      if(sample_frame_count >= sample_frames_per_second)
+        @seconds = sample_frame_count / sample_frames_per_second
+        sample_frame_count -= sample_frames_per_second * @seconds
+      end
+
+      @milliseconds = (sample_frame_count / sample_frames_per_millisecond).floor
+    end
+
+    attr_reader :sample_frame_count, :sample_rate, :hours, :minutes, :seconds, :milliseconds
+  end
+end

data/lib/wavefile/format.rb

@@ -2,41 +2,48 @@ module WaveFile
   class InvalidFormatError < StandardError; end
 
   class Format
-    # Not using ranges because of 1.8.7 performance problems with Range.max()
+    # Not using ranges because of 1.8.7 performance problems with Range.max
     MIN_CHANNELS = 1
     MAX_CHANNELS = 65535
 
     MIN_SAMPLE_RATE = 1
     MAX_SAMPLE_RATE = 4_294_967_296
 
-    SUPPORTED_BITS_PER_SAMPLE = [8, 16, 32]
+    SUPPORTED_SAMPLE_FORMATS = [:pcm, :float]
+    SUPPORTED_BITS_PER_SAMPLE = {
+                                  :pcm => [8, 16, 32],
+                                  :float => [32, 64],
+                                }
 
-    def initialize(channels, bits_per_sample, sample_rate)
-      channels = canonicalize_channels(channels)
+    def initialize(channels, format_code, sample_rate)
+      channels = normalize_channels(channels)
+      sample_format, bits_per_sample = normalize_format_code(format_code)
       validate_channels(channels)
-      validate_bits_per_sample(bits_per_sample)
+      validate_sample_format(sample_format)
+      validate_bits_per_sample(sample_format, bits_per_sample)
       validate_sample_rate(sample_rate)
 
       @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
     end
 
-    def mono?()
-      return @channels == 1
+    def mono?
+      @channels == 1
     end
 
-    def stereo?()
-      return @channels == 2
+    def stereo?
+      @channels == 2
     end
 
-    attr_reader :channels, :bits_per_sample, :sample_rate, :block_align, :byte_rate
-  
+    attr_reader :channels, :sample_format, :bits_per_sample, :sample_rate, :block_align, :byte_rate
+
   private
 
-    def canonicalize_channels(channels)
+    def normalize_channels(channels)
       if channels == :mono
         return 1
       elsif channels == :stereo
@@ -46,17 +53,36 @@ module WaveFile
       end
     end
 
+    def normalize_format_code(format_code)
+      if SUPPORTED_BITS_PER_SAMPLE[:pcm].include? format_code
+        [:pcm, format_code]
+      elsif format_code == :float
+        [:float, 32]
+      else
+        sample_format, bits_per_sample = format_code.to_s.split("_")
+        [sample_format.to_sym, bits_per_sample.to_i]
+      end
+    end
+
+    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."
+      end
+    end
+
     def validate_channels(candidate_channels)
       unless (MIN_CHANNELS..MAX_CHANNELS) === candidate_channels
         raise InvalidFormatError, "Invalid number of channels. Must be between 1 and #{MAX_CHANNELS}."
       end
     end
 
-    def validate_bits_per_sample(candidate_bits_per_sample)
-      unless SUPPORTED_BITS_PER_SAMPLE.member?(candidate_bits_per_sample)
+    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
         raise InvalidFormatError,
-              "Bits per sample of #{candidate_bits_per_sample} is unsupported. " +
-              "Only #{SUPPORTED_BITS_PER_SAMPLE.inspect} are supported."
+              "Bits per sample of #{candidate_bits_per_sample} is unsupported for " +
+              "sample format #{candidate_sample_format}."
       end
     end
 

data/lib/wavefile/info.rb

@@ -1,6 +1,6 @@
 module WaveFile
   class Info
-    def initialize(file_name, raw_format_chunk, sample_count)
+    def initialize(file_name, raw_format_chunk, sample_frame_count)
       @file_name = file_name
       @audio_format = raw_format_chunk[:audio_format]
       @channels = raw_format_chunk[:channels]
@@ -8,46 +8,13 @@ module WaveFile
       @sample_rate = raw_format_chunk[:sample_rate]
       @byte_rate = raw_format_chunk[:byte_rate]
       @block_align = raw_format_chunk[:block_align]
-      @sample_count = sample_count
-      @duration = calculate_duration()
+      @sample_frame_count = sample_frame_count
+
+      @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_count, :duration
-  
-  private
-
-    # Calculates playback time given the number of samples and the sample rate.
-    #
-    # Returns a hash listing the number of hours, minutes, seconds, and milliseconds of
-    # playback time.
-    def calculate_duration()
-      total_samples = @sample_count
-      samples_per_millisecond = @sample_rate / 1000.0
-      samples_per_second = @sample_rate
-      samples_per_minute = samples_per_second * 60
-      samples_per_hour = samples_per_minute * 60
-      hours, minutes, seconds, milliseconds = 0, 0, 0, 0
-      
-      if(total_samples >= samples_per_hour)
-        hours = total_samples / samples_per_hour
-        total_samples -= samples_per_hour * hours
-      end
-      
-      if(total_samples >= samples_per_minute)
-        minutes = total_samples / samples_per_minute
-        total_samples -= samples_per_minute * minutes
-      end
-      
-      if(total_samples >= samples_per_second)
-        seconds = total_samples / samples_per_second
-        total_samples -= samples_per_second * seconds
-      end
-      
-      milliseconds = (total_samples / samples_per_millisecond).floor
-      
-      @duration = { :hours => hours, :minutes => minutes, :seconds => seconds, :milliseconds => milliseconds }
-    end
+                :sample_frame_count, :duration
   end
 end