wavefile 0.4.0 → 0.5.0

data/lib/wavefile/reader.rb

@@ -9,7 +9,7 @@ module WaveFile
 
 
   # Provides the ability to read sample data out of a wave file, as well as query a
-  # wave file about its metadata (e.g. number of channels, sample rate, etc). 
+  # wave file about its metadata (e.g. number of channels, sample rate, etc).
   class Reader
     # Returns a Reader object that is ready to start reading the specified file's sample data.
     #
@@ -26,35 +26,34 @@ module WaveFile
       @file_name = file_name
       @file = File.open(file_name, "rb")
 
-      raw_format_chunk, sample_count = HeaderReader.new(@file, @file_name).read_until_data_chunk()
-      @sample_count = sample_count
-      @samples_remaining = sample_count
+      raw_format_chunk, sample_frame_count = HeaderReader.new(@file, @file_name).read_until_data_chunk
+      @current_sample_frame = 0
+      @total_sample_frames = sample_frame_count
 
       # Make file is in a format we can actually read
       validate_format_chunk(raw_format_chunk)
 
+      native_sample_format = "#{FORMAT_CODES.invert[raw_format_chunk[:audio_format]]}_#{raw_format_chunk[:bits_per_sample]}".to_sym
       @native_format = Format.new(raw_format_chunk[:channels],
-                                  raw_format_chunk[:bits_per_sample],
+                                  native_sample_format,
                                   raw_format_chunk[:sample_rate])
-      @pack_code = PACK_CODES[@native_format.bits_per_sample]
-
-      if format == nil
-        @format = @native_format
-      else
-        @format = format
-      end
+      @pack_code = PACK_CODES[@native_format.sample_format][@native_format.bits_per_sample]
+      @format = (format == nil) ? @native_format : format
 
       if block_given?
-        yield(self)
-        close()
+        begin
+          yield(self)
+        ensure
+          close
+        end
       end
     end
 
 
     # Reads metadata from the specified wave file and returns an Info object with the results.
-    # Metadata includes things like the number of channels, bits per sample, number of samples,
-    # sample encoding format (i.e. PCM, IEEE float, uLaw etc). See the Info object for more
-    # detail on exactly what metadata is available.
+    # Metadata includes things like the number of channels, bits per sample, number of sample
+    # frames, sample encoding format (i.e. PCM, IEEE float, uLaw etc). See the Info object for
+    # more detail on exactly what metadata is available.
     #
     # file_name - The name of the wave file to read from
     #
@@ -68,84 +67,85 @@ module WaveFile
     #                           that WaveFile can't read.
     def self.info(file_name)
       file = File.open(file_name, "rb")
-      raw_format_chunk, sample_count = HeaderReader.new(file, file_name).read_until_data_chunk()
-      file.close()
+      raw_format_chunk, sample_frame_count = HeaderReader.new(file, file_name).read_until_data_chunk
+      file.close
 
-      return Info.new(file_name, raw_format_chunk, sample_count)
+      Info.new(file_name, raw_format_chunk, sample_frame_count)
     end
 
 
     # Reads sample data of the into successive Buffers of the specified size, until there is no more
     # sample data to be read. When all sample data has been read, the Reader is automatically closed.
-    # Each Buffer is passed to the specified block.
+    # Each Buffer is passed to the given block.
     #
-    # Note that the number of sames to read is for *each channel*. That is, if buffer_size is 1024, then
+    # Note that sample_frame_count indicates the number of sample frames to read, not number of samples.
+    # A sample frame include one sample for each channel. For example, if sample_frame_count is 1024, then
     # for a stereo file 1024 samples will be read from the left channel, and 1024 samples will be read from
     # the right channel.
     #
-    # buffer_size - The number of samples to read into each Buffer from each channel. The number of
-    #               samples read into the final Buffer could be less than this size, if there are not
-    #               enough remaining samples.
+    # sample_frame_count - The number of sample frames to read into each Buffer from each channel. The number
+    #                      of sample frames read into the final Buffer could be less than this size, if there
+    #                      are not enough remaining.
     #
     # Returns nothing.
-    def each_buffer(buffer_size)
+    def each_buffer(sample_frame_count)
       begin
         while true do
-          yield(read(buffer_size))
+          yield(read(sample_frame_count))
         end
       rescue EOFError
-        close()
+        close
       end
     end
 
 
-    # Reads the specified number of samples from the wave file into a Buffer. Note that the Buffer will have
-    # at most buffer_size samples, but could have less if the file doesn't have enough remaining samples.
+    # Reads the specified number of sample frames from the wave file into a Buffer. Note that the Buffer will have
+    # at most sample_frame_count sample frames, but could have less if the file doesn't have enough remaining.
     #
-    # buffer_size - The number of samples to read. Note that for multi-channel files, this number of samples
-    #               will be read from each channel.
+    # sample_frame_count - The number of sample frames to read. Note that each sample frame includes a sample for
+    #                      each channel.
     #
-    # Returns a Buffer containing buffer_size samples
+    # Returns a Buffer containing sample_frame_count sample frames
     # Raises EOFError if no samples could be read due to reaching the end of the file
-    def read(buffer_size)
-      if @samples_remaining == 0
+    def read(sample_frame_count)
+      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 buffer_size > @samples_remaining
-        buffer_size = @samples_remaining
+      elsif sample_frame_count > sample_frames_remaining
+        sample_frame_count = sample_frames_remaining
       end
 
-      samples = @file.sysread(buffer_size * @native_format.block_align).unpack(@pack_code)
-      @samples_remaining -= buffer_size
+      samples = @file.sysread(sample_frame_count * @native_format.block_align).unpack(@pack_code)
+      @current_sample_frame += sample_frame_count
 
       if @native_format.channels > 1
         num_multichannel_samples = samples.length / @native_format.channels
         multichannel_data = Array.new(num_multichannel_samples)
-      
+
         if(@native_format.channels == 2)
           # Files with more than 2 channels are expected to be less common, so if there are 2 channels
           # using a faster specific algorithm instead of a general one.
-          num_multichannel_samples.times {|i| multichannel_data[i] = [samples.pop(), samples.pop()].reverse!() }
+          num_multichannel_samples.times {|i| multichannel_data[i] = [samples.pop, samples.pop].reverse! }
         else
           # General algorithm that works for any number of channels, 2 or greater.
           num_multichannel_samples.times do |i|
             sample = Array.new(@native_format.channels)
-            @native_format.channels.times {|j| sample[j] = samples.pop() }
-            multichannel_data[i] = sample.reverse!()
+            @native_format.channels.times {|j| sample[j] = samples.pop }
+            multichannel_data[i] = sample.reverse!
           end
         end
 
-        samples = multichannel_data.reverse!()
+        samples = multichannel_data.reverse!
       end
 
       buffer = Buffer.new(samples, @native_format)
-      return buffer.convert(@format)
+      buffer.convert(@format)
     end
 
 
     # Returns true if the Reader is closed, and false if it is open and available for reading.
-    def closed?()
-      return @file.closed?
+    def closed?
+      @file.closed?
     end
 
 
@@ -153,26 +153,53 @@ module WaveFile
     #
     # Returns nothing.
     # Raises IOError if the Reader is already closed.
-    def close()
-      @file.close()
+    def close
+      @file.close
+    end
+
+    # Returns a Duration instance for the total number of sample frames in the file
+    def total_duration
+      Duration.new(total_sample_frames, @format.sample_rate)
     end
 
-    attr_reader :file_name, :format
+    # Returns the name of the Wave file that is being read
+    attr_reader :file_name
+
+    # 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.
+    attr_reader :format
+
+    # Returns the index of the sample frame which is "cued up" for reading. I.e., the index
+    # of the next sample frame that will be read. 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 :current_sample_frame
+
+    # 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 :total_sample_frames
 
   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
+
     def validate_format_chunk(raw_format_chunk)
       # :byte_rate and :block_align are not checked to make sure that match :channels/:sample_rate/bits_per_sample
       # because this library doesn't use them.
 
-      unless raw_format_chunk[:audio_format] == PCM
+      unless FORMAT_CODES.values.include? raw_format_chunk[:audio_format]
         raise UnsupportedFormatError, "Audio format is #{raw_format_chunk[:audio_format]}, " +
-                                      "but only format code 1 (i.e. PCM) is supported."
+                                      "but only format code 1 (PCM) or 3 (floating point) is supported."
       end
 
-      unless Format::SUPPORTED_BITS_PER_SAMPLE.include?(raw_format_chunk[:bits_per_sample])
+      unless Format::SUPPORTED_BITS_PER_SAMPLE[FORMAT_CODES.invert[raw_format_chunk[:audio_format]]].include?(raw_format_chunk[:bits_per_sample])
         raise UnsupportedFormatError, "Bits per sample is #{raw_format_chunk[:bits_per_sample]}, " +
-                                      "but only #{Format::SUPPORTED_BITS_PER_SAMPLE.inspect} are supported."
+                                      "but only #{Format::SUPPORTED_BITS_PER_SAMPLE[:pcm].inspect} are supported."
       end
 
       unless raw_format_chunk[:channels] > 0
@@ -200,8 +227,8 @@ module WaveFile
       @file_name = file_name
     end
 
-    def read_until_data_chunk()
-      read_riff_chunk()
+    def read_until_data_chunk
+      read_riff_chunk
 
       begin
         chunk_id = @file.sysread(4)
@@ -225,14 +252,14 @@ module WaveFile
         raise_error InvalidFormatError, "The format chunk is either missing, or it comes after the data chunk."
       end
 
-      sample_count = chunk_size / format_chunk[:block_align]
+      sample_frame_count = chunk_size / format_chunk[:block_align]
 
-      return format_chunk, sample_count
+      return format_chunk, sample_frame_count
     end
 
   private
 
-    def read_riff_chunk()
+    def read_riff_chunk
       riff_header = {}
       riff_header[:chunk_id],
       riff_header[:chunk_size],
@@ -246,7 +273,7 @@ module WaveFile
         raise_error InvalidFormatError, "Expected RIFF format of '#{WAVEFILE_FORMAT_CODE}', but was '#{riff_header[:riff_format]}'"
       end
 
-      return riff_header
+      riff_header
     end
 
     def read_format_chunk(chunk_id, chunk_size)
@@ -278,7 +305,7 @@ module WaveFile
         # TODO: Parse the extension
       end
 
-      return format_chunk
+      format_chunk
     end
 
     def read_chunk_body(chunk_id, chunk_size)

data/lib/wavefile/writer.rb

@@ -13,56 +13,61 @@ module WaveFile
     # starts, assuming this canonical format:
     #
     # RIFF Chunk Header (12 bytes)
-    # Format Chunk (No Extension) (16 bytes)
+    # Format Chunk (16 bytes for PCM, 18 bytes for floating point)
+    # FACT Chunk (0 bytes for PCM, 12 bytes for floating point)
     # Data Chunk Header (8 bytes)
     #
     # All wave files written by Writer use this canonical format.
-    CANONICAL_HEADER_BYTE_LENGTH = 36
+    CANONICAL_HEADER_BYTE_LENGTH = {:pcm => 36, :float => 50}
 
 
     # Returns a constructed Writer object which is available for writing sample data to the specified
-    # file (via the write() method). When all sample data has been written, the Writer should be closed.
+    # file (via the write method). When all sample data has been written, the Writer should be closed.
     # Note that the wave file being written to will NOT be valid (and playable in other programs) until
     # the Writer has been closed.
     #
     # If a block is given to this method, sample data can be written inside the given block. When the
     # block terminates, the Writer will be automatically closed (and no more sample data can be written).
     #
-    # If no block is given, then sample data can be written until the close() method is called.
+    # If no block is given, then sample data can be written until the close method is called.
     def initialize(file_name, format)
+      @file_name = file_name
       @file = File.open(file_name, "wb")
       @format = format
 
-      @samples_written = 0
-      @pack_code = PACK_CODES[format.bits_per_sample]
+      @total_sample_frames = 0
+      @pack_code = PACK_CODES[format.sample_format][format.bits_per_sample]
 
       # Note that the correct sizes for the RIFF and data chunks can't be determined
       # until all samples have been written, so this header as written will be incorrect.
-      # When close() is called, the correct sizes will be re-written.
+      # When close is called, the correct sizes will be re-written.
       write_header(0)
 
       if block_given?
-        yield(self)
-        close()
+        begin
+          yield(self)
+        ensure
+          close
+        end
       end
     end
 
 
     # Appends the sample data in the given Buffer to the end of the wave file.
     #
-    # Returns the number of sample that have been written to the file so far.
+    # Returns the number of sample frames that have been written to the file so far.
     # Raises IOError if the Writer has been closed.
     def write(buffer)
       samples = buffer.convert(@format).samples
 
       @file.syswrite(samples.flatten.pack(@pack_code))
-      @samples_written += samples.length
+      @total_sample_frames += samples.length
     end
 
 
     # Returns true if the Writer is closed, and false if it is open and available for writing.
-    def closed?()
-      return @file.closed?
+    def closed?
+      @file.closed?
     end
 
 
@@ -70,17 +75,19 @@ module WaveFile
     #
     # Note that the wave file will NOT be valid until this method is called. The wave file
     # format requires certain information about the amount of sample data, and this can't be
-    # determined until all samples have been written. 
+    # determined until all samples have been written. (This method doesn't need to be called
+    # when passing a block to Writer.new, as this method will automatically be called when
+    # the block exits).
     #
     # Returns nothing.
     # Raises IOError if the Writer is already closed.
-    def close()
+    def close
       # The RIFF specification requires that each chunk be aligned to an even number of bytes,
       # even if the byte count is an odd number. Therefore if an odd number of bytes has been
       # written, write an empty padding byte.
       #
       # See http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/riffmci.pdf, page 11.
-      bytes_written = @samples_written * @format.block_align
+      bytes_written = @total_sample_frames * @format.block_align
       if bytes_written.odd?
         @file.syswrite(EMPTY_BYTE)
       end
@@ -89,34 +96,59 @@ module WaveFile
       # samples have been written, so go back to the beginning of the file and re-write
       # those chunk headers with the correct sizes.
       @file.sysseek(0)
-      write_header(@samples_written)
-      
-      @file.close()
+      write_header(@total_sample_frames)
+
+      @file.close
+    end
+
+    # Returns a Duration instance for the number of sample frames that have been written so far
+    def total_duration
+      Duration.new(@total_sample_frames, @format.sample_rate)
     end
 
-    attr_reader :file_name, :format
+    # Returns the name of the Wave file that is being written to
+    attr_reader :file_name
+
+    # Returns a Format object describing the Wave file being written (number of channels, sample
+    # format and bits per sample, sample rate, etc.)
+    attr_reader :format
+
+    # Returns the number of samples (per channel) that have been written to the file so far.
+    # For example, if 1000 "left" samples and 1000 "right" samples have been written to a stereo file,
+    # this will return 1000.
+    attr_reader :total_sample_frames
 
   private
 
     # Writes the RIFF chunk header, format chunk, and the header for the data chunk. After this
     # method is called the file will be "queued up" and ready for writing actual sample data.
-    def write_header(sample_count)
-      sample_data_byte_count = sample_count * @format.block_align
+    def write_header(sample_frame_count)
+      sample_data_byte_count = sample_frame_count * @format.block_align
 
       # Write the header for the RIFF chunk
       header = CHUNK_IDS[:riff]
-      header += [CANONICAL_HEADER_BYTE_LENGTH + sample_data_byte_count].pack(UNSIGNED_INT_32)
+      header += [CANONICAL_HEADER_BYTE_LENGTH[@format.sample_format] + sample_data_byte_count].pack(UNSIGNED_INT_32)
       header += WAVEFILE_FORMAT_CODE
 
       # Write the format chunk
       header += CHUNK_IDS[:format]
-      header += [FORMAT_CHUNK_BYTE_LENGTH].pack(UNSIGNED_INT_32)
-      header += [PCM].pack(UNSIGNED_INT_16)
+      header += [FORMAT_CHUNK_BYTE_LENGTH[@format.sample_format]].pack(UNSIGNED_INT_32)
+      header += [FORMAT_CODES[@format.sample_format]].pack(UNSIGNED_INT_16)
       header += [@format.channels].pack(UNSIGNED_INT_16)
       header += [@format.sample_rate].pack(UNSIGNED_INT_32)
       header += [@format.byte_rate].pack(UNSIGNED_INT_32)
       header += [@format.block_align].pack(UNSIGNED_INT_16)
       header += [@format.bits_per_sample].pack(UNSIGNED_INT_16)
+      if @format.sample_format == :float
+        header += [0].pack(UNSIGNED_INT_16)
+      end
+
+      # Write the FACT chunk, if necessary
+      unless @format.sample_format == :pcm
+        header += CHUNK_IDS[:fact]
+        header += [4].pack(UNSIGNED_INT_32)
+        header += [sample_frame_count].pack(UNSIGNED_INT_32)
+      end
 
       # Write the header for the data chunk
       header += CHUNK_IDS[:data]

data/lib/wavefile.rb

@@ -1,15 +1,16 @@
 require 'wavefile/buffer'
+require 'wavefile/duration'
 require 'wavefile/format'
 require 'wavefile/info'
 require 'wavefile/reader'
 require 'wavefile/writer'
 
 module WaveFile
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 
   WAVEFILE_FORMAT_CODE = "WAVE"
-  FORMAT_CHUNK_BYTE_LENGTH = 16
-  PCM = 1
+  FORMAT_CHUNK_BYTE_LENGTH = {:pcm => 16, :float => 18}
+  FORMAT_CODES = {:pcm => 1, :float => 3}
   CHUNK_IDS = {:riff         => "RIFF",
                :format       => "fmt ",
                :data         => "data",
@@ -24,7 +25,8 @@ module WaveFile
                :sample       => "smpl",
                :instrument   => "inst" }
 
-  PACK_CODES = {8 => "C*", 16 => "s*", 32 => "l*"}
+  PACK_CODES = {:pcm => {8 => "C*", 16 => "s*", 32 => "l*"},
+                :float => { 32 => "e*", 64 => "E*"}}
 
   UNSIGNED_INT_16 = "v"
   UNSIGNED_INT_32 = "V"