wavefile 0.3.0 → 0.4.0

data/lib/wavefile/buffer.rb

@@ -0,0 +1,147 @@
+module WaveFile
+  # Error that is raised when an attempt is made to perform an unsupported or undefined
+  # conversion between two sample data formats.
+  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
+  # 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.
+    def initialize(samples, format)
+      @samples = samples
+      @format = format
+    end
+
+
+    # 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_buffer = old_buffer.convert(new_format)
+    #
+    # 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)
+    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.
+    #
+    # new_format - The format that the sample data should be converted to
+    #
+    # Examples
+    #
+    #   new_format = Format.new(:mono, 16, 44100)
+    #   old_buffer.convert!(new_format)
+    #
+    # Returns self.
+    def convert!(new_format)
+      @samples = convert_buffer(@samples, @format, new_format)
+      @format = new_format
+      return self
+    end
+
+
+    # The number of channels the buffer's sample data has
+    def channels
+      return @format.channels
+    end
+
+
+    # The bits per sample of the buffer's sample data
+    def bits_per_sample
+      return @format.bits_per_sample
+    end
+
+
+    # The sample rate of the buffer's sample data
+    def sample_rate
+      return @format.sample_rate
+    end
+
+    attr_reader :samples
+
+  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
+
+      return samples
+    end
+
+    def convert_buffer_channels(samples, 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.
+      if old_channels == 1 && new_channels == 2
+        samples.map! {|sample| [sample, sample]}
+      elsif old_channels == 2 && new_channels == 1
+        samples.map! {|sample| (sample[0] + sample[1]) / 2}
+      elsif old_channels == 1 && new_channels >= 2
+        samples.map! {|sample| [].fill(sample, 0, new_channels)}
+      elsif old_channels >= 2 && new_channels == 1
+        samples.map! {|sample| sample.inject(0) {|sub_sample, sum| sum + sub_sample } / old_channels }
+      elsif old_channels > 2 && new_channels == 2
+        samples.map! {|sample| [sample[0], sample[1]]}
+      else
+        raise BufferConversionError,
+              "Conversion of sample data from #{old_channels} channels to #{new_channels} channels is unsupported"
+      end
+
+      return samples
+    end
+
+    def convert_buffer_bits_per_sample(samples, 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
+      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
+      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
+        else
+          samples.map! {|sample| sample.send(operator, shift_amount) }
+        end
+      end
+
+      return samples
+    end
+  end
+end

data/lib/wavefile/format.rb

@@ -0,0 +1,69 @@
+module WaveFile
+  class InvalidFormatError < StandardError; end
+
+  class Format
+    # 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]
+
+    def initialize(channels, bits_per_sample, sample_rate)
+      channels = canonicalize_channels(channels)
+      validate_channels(channels)
+      validate_bits_per_sample(bits_per_sample)
+      validate_sample_rate(sample_rate)
+
+      @channels = channels
+      @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
+    end
+
+    def stereo?()
+      return @channels == 2
+    end
+
+    attr_reader :channels, :bits_per_sample, :sample_rate, :block_align, :byte_rate
+  
+  private
+
+    def canonicalize_channels(channels)
+      if channels == :mono
+        return 1
+      elsif channels == :stereo
+        return 2
+      else
+        return channels
+      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)
+        raise InvalidFormatError,
+              "Bits per sample of #{candidate_bits_per_sample} is unsupported. " +
+              "Only #{SUPPORTED_BITS_PER_SAMPLE.inspect} are supported."
+      end
+    end
+
+    def validate_sample_rate(candidate_sample_rate)
+      unless (MIN_SAMPLE_RATE..MAX_SAMPLE_RATE) === candidate_sample_rate
+        raise InvalidFormatError, "Invalid sample rate. Must be between 1 and #{MAX_SAMPLE_RATE}"
+      end
+    end
+  end
+end

data/lib/wavefile/info.rb

@@ -0,0 +1,53 @@
+module WaveFile
+  class Info
+    def initialize(file_name, raw_format_chunk, sample_count)
+      @file_name = file_name
+      @audio_format = raw_format_chunk[:audio_format]
+      @channels = raw_format_chunk[:channels]
+      @bits_per_sample = raw_format_chunk[:bits_per_sample]
+      @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()
+    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
+  end
+end

data/lib/wavefile/reader.rb

@@ -0,0 +1,296 @@
+module WaveFile
+  # 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.
+  class InvalidFormatError < StandardError; end
+
+  # Error that is raised when trying to read from a valid wave file that has its sample data
+  # stored in a format that Reader doesn't understand.
+  class UnsupportedFormatError < StandardError; end
+
+
+  # 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). 
+  class Reader
+    # Returns a Reader object that is ready to start reading the specified file's sample data.
+    #
+    # file_name - The name of the wave file to read from.
+    # format - The format that read sample data should be returned in
+    #          (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 InvalidFormatError if the specified file isn't a valid wave file
+    # Raises UnsupportedFormatError if the specified file has its sample data stored in a format
+    #                               that Reader doesn't know how to process.
+    def initialize(file_name, format=nil)
+      @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
+
+      # Make file is in a format we can actually read
+      validate_format_chunk(raw_format_chunk)
+
+      @native_format = Format.new(raw_format_chunk[:channels],
+                                  raw_format_chunk[:bits_per_sample],
+                                  raw_format_chunk[:sample_rate])
+      @pack_code = PACK_CODES[@native_format.bits_per_sample]
+
+      if format == nil
+        @format = @native_format
+      else
+        @format = format
+      end
+
+      if block_given?
+        yield(self)
+        close()
+      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.
+    #
+    # file_name - The name of the wave file to read from
+    #
+    # Examples:
+    #
+    #   info = Reader.info("my_docs/my_sounds/my_file.wav")
+    #
+    # Returns an Info object containing metadata about the wave file.
+    # Raises Errno::ENOENT if the specified file can't be found
+    # Raises InvalidFormatError if the specified file isn't a valid wave file, or is in a format
+    #                           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()
+
+      return Info.new(file_name, raw_format_chunk, sample_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.
+    #
+    # Note that the number of sames to read is for *each channel*. That is, if buffer_size 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.
+    #
+    # Returns nothing.
+    def each_buffer(buffer_size)
+      begin
+        while true do
+          yield(read(buffer_size))
+        end
+      rescue EOFError
+        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.
+    #
+    # buffer_size - The number of samples to read. Note that for multi-channel files, this number of samples
+    #               will be read from each channel.
+    #
+    # Returns a Buffer containing buffer_size samples
+    # Raises EOFError if no samples could be read due to reaching the end of the file
+    def read(buffer_size)
+      if @samples_remaining == 0
+        #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
+      end
+
+      samples = @file.sysread(buffer_size * @native_format.block_align).unpack(@pack_code)
+      @samples_remaining -= buffer_size
+
+      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!() }
+        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!()
+          end
+        end
+
+        samples = multichannel_data.reverse!()
+      end
+
+      buffer = Buffer.new(samples, @native_format)
+      return 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?
+    end
+
+
+    # Closes the Reader. After a Reader is closed, no more sample data can be read from it.
+    #
+    # Returns nothing.
+    # Raises IOError if the Reader is already closed.
+    def close()
+      @file.close()
+    end
+
+    attr_reader :file_name, :format
+
+  private
+
+    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
+        raise UnsupportedFormatError, "Audio format is #{raw_format_chunk[:audio_format]}, " +
+                                      "but only format code 1 (i.e. PCM) is supported."
+      end
+
+      unless Format::SUPPORTED_BITS_PER_SAMPLE.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."
+      end
+
+      unless raw_format_chunk[:channels] > 0
+        raise UnsupportedFormatError, "Number of channels is #{raw_format_chunk[:channels]}, " +
+                                      "but only #{Format::MIN_CHANNELS}-#{Format::MAX_CHANNELS} are supported."
+      end
+
+      unless raw_format_chunk[:sample_rate] > 0
+        raise UnsupportedFormatError, "Sample rate is #{raw_format_chunk[:sample_rate]}, " +
+                                      "but only #{Format::MIN_SAMPLE_RATE}-#{Format::MAX_SAMPLE_RATE} are supported."
+      end
+    end
+  end
+
+
+  # Used to read the RIFF chunks in a wave file up until the data chunk. Thus is can be used
+  # to open a wave file and "queue it up" to the start of the actual sample data, as well as
+  # extract information out of pre-data chunks, such as the format chunk.
+  class HeaderReader
+    RIFF_CHUNK_HEADER_SIZE = 12
+    FORMAT_CHUNK_MINIMUM_SIZE = 16
+
+    def initialize(file, file_name)
+      @file = file
+      @file_name = file_name
+    end
+
+    def read_until_data_chunk()
+      read_riff_chunk()
+
+      begin
+        chunk_id = @file.sysread(4)
+        chunk_size = @file.sysread(4).unpack(UNSIGNED_INT_32).first
+        while chunk_id != CHUNK_IDS[:data]
+          if chunk_id == CHUNK_IDS[:format]
+            format_chunk = read_format_chunk(chunk_id, chunk_size)
+          else
+            # Other chunk types besides the format chunk are ignored. This may change in the future.
+            @file.sysread(chunk_size)
+          end
+
+          chunk_id = @file.sysread(4)
+          chunk_size = @file.sysread(4).unpack(UNSIGNED_INT_32).first
+        end
+      rescue EOFError
+        raise_error InvalidFormatError, "It doesn't have a data chunk."
+      end
+
+      if format_chunk == nil
+        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]
+
+      return format_chunk, sample_count
+    end
+
+  private
+
+    def read_riff_chunk()
+      riff_header = {}
+      riff_header[:chunk_id],
+      riff_header[:chunk_size],
+      riff_header[:riff_format] = read_chunk_body(CHUNK_IDS[:riff], RIFF_CHUNK_HEADER_SIZE).unpack("a4Va4")
+
+      unless riff_header[:chunk_id] == CHUNK_IDS[:riff]
+        raise_error InvalidFormatError, "Expected chunk ID '#{CHUNK_IDS[:riff]}', but was '#{riff_header[:chunk_id]}'"
+      end
+
+      unless riff_header[:riff_format] == WAVEFILE_FORMAT_CODE
+        raise_error InvalidFormatError, "Expected RIFF format of '#{WAVEFILE_FORMAT_CODE}', but was '#{riff_header[:riff_format]}'"
+      end
+
+      return riff_header
+    end
+
+    def read_format_chunk(chunk_id, chunk_size)
+      if chunk_size < FORMAT_CHUNK_MINIMUM_SIZE
+        raise_error InvalidFormatError, "The format chunk is incomplete."
+      end
+
+      raw_bytes = read_chunk_body(CHUNK_IDS[:format], chunk_size)
+
+      format_chunk = {}
+      format_chunk[:audio_format],
+      format_chunk[:channels],
+      format_chunk[:sample_rate],
+      format_chunk[:byte_rate],
+      format_chunk[:block_align],
+      format_chunk[:bits_per_sample] = raw_bytes.slice!(0...FORMAT_CHUNK_MINIMUM_SIZE).unpack("vvVVvv")
+
+      if chunk_size > FORMAT_CHUNK_MINIMUM_SIZE
+        format_chunk[:extension_size] = raw_bytes.slice!(0...2).unpack(UNSIGNED_INT_16).first
+
+        if format_chunk[:extension_size] == nil
+          raise_error InvalidFormatError, "The format chunk is missing an expected extension."
+        end
+
+        if format_chunk[:extension_size] != raw_bytes.length
+          raise_error InvalidFormatError, "The format chunk extension is shorter than expected."
+        end
+
+        # TODO: Parse the extension
+      end
+
+      return format_chunk
+    end
+
+    def read_chunk_body(chunk_id, chunk_size)
+      begin
+        return @file.sysread(chunk_size)
+      rescue EOFError
+        raise_error InvalidFormatError, "The #{chunk_id} chunk has incomplete data."
+      end
+    end
+
+    def raise_error(exception_class, message)
+      raise exception_class, "File '#{@file_name}' is not a supported wave file. #{message}"
+    end
+  end
+end