wavefile 1.0.1 → 1.1.0

data/lib/wavefile/format.rb

@@ -31,17 +31,21 @@ module WaveFile
     # 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.
+    #                   +:top_back_right+.
+    #
+    #                   Each value should only appear once, and the channels must follow the ordering above.
+    #
+    #                   For example, <code>[:front_center, :back_left]</code>
+    #                   is a valid speaker mapping, but <code>[:back_left, :front_center]</code> 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 +: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].
+    #                   channels, this will be set to <code>[:front_left, :front_right]</code>.
     #
     # Examples
     #
@@ -99,11 +103,11 @@ module WaveFile
     end
 
     # Public: Returns the number of channels, such as 1 or 2. This will always return a
-    # Integer, even if the number of channels is specified with a symbol (e.g. :mono)
+    # Integer, even if the number of channels is specified with a symbol (e.g. +:mono+)
     # in the constructor.
     attr_reader :channels
 
-    # Public: Returns a symbol indicating the sample format, such as :pcm or :float
+    # Public: Returns a symbol indicating the sample format, such as +:pcm+ or +:float+
     attr_reader :sample_format
 
     # Public: Returns the number of bits per sample, such as 8, 16, 24, 32, or 64.
@@ -117,7 +121,7 @@ module WaveFile
     attr_reader :block_align
 
     # Public: Returns the number of bytes contained in 1 second of sample data.
-    # Is equivalent to block_align * sample_rate.
+    # Is equivalent to #block_align * #sample_rate.
     attr_reader :byte_rate
 
     # Public: Returns the mapping of each channel to a speaker.
@@ -128,7 +132,7 @@ module WaveFile
     # Internal
     VALID_CHANNEL_RANGE     = 1..65535    # :nodoc:
     # Internal
-    VALID_SAMPLE_RATE_RANGE = 1..4_294_967_296    # :nodoc:
+    VALID_SAMPLE_RATE_RANGE = 1..4_294_967_295    # :nodoc:
 
     # Internal
     SUPPORTED_FORMAT_CODES = [:pcm_8, :pcm_16, :pcm_24, :pcm_32, :float, :float_32, :float_64].freeze    # :nodoc:

data/lib/wavefile/reader.rb

@@ -27,7 +27,9 @@ 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 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)
@@ -40,13 +42,9 @@ module WaveFile
 
       @closed = false
 
-      begin
-        riff_reader = ChunkReaders::RiffReader.new(@io, format)
-      rescue InvalidFormatError
-        raise InvalidFormatError, "Does not appear to be a valid Wave file"
-      end
-
+      riff_reader = ChunkReaders::RiffReader.new(@io, format)
       @data_chunk_reader = riff_reader.data_chunk_reader
+      @sample_chunk = riff_reader.sample_chunk
 
       if block_given?
         begin
@@ -115,8 +113,11 @@ module WaveFile
     #                      each channel.
     #
     # Returns a Buffer containing sample_frame_count sample frames.
+    #
     # Raises UnsupportedFormatError if file is in a format that can't be read by this gem.
+    #
     # Raises ReaderClosedError if the Writer has been closed.
+    #
     # Raises EOFError if no samples could be read due to reaching the end of the file.
     def read(sample_frame_count)
       if @closed
@@ -150,7 +151,7 @@ module WaveFile
       @closed = true
     end
 
-    # Public: Returns a Duration instance for the total number of sample frames in the file
+    # Public: Returns a Duration instance which indicates the playback time of the file.
     def total_duration
       Duration.new(total_sample_frames, @data_chunk_reader.format.sample_rate)
     end
@@ -193,5 +194,12 @@ module WaveFile
     def total_sample_frames
       @data_chunk_reader.total_sample_frames
     end
+
+    # Public: Returns a SamplerInfo object if the file contains "smpl" chunk, or nil if it doesn't.
+    # If present, this will contain information about how the file can be use by a sampler, such as
+    # corresponding MIDI note, or loop points.
+    def sampler_info
+      @sample_chunk
+    end
   end
 end

data/lib/wavefile/sampler_info.rb

@@ -0,0 +1,162 @@
+module WaveFile
+  # Public: Error that is raised when constructing a SamplerInfo instance that is invalid.
+  #         "Invalid" means that one or more fields have a value that can't be encoded in the
+  #         field inside a *.wav file. For example, there's no way to encode "-23" as a value
+  #         for the midi_note field. However, this error _won't_ be raised for values that
+  #         can be encoded, but aren't semantically correct. For example, it's possible to
+  #         construct a SamplerInfo instance with a midi_note value of 10000, which can be
+  #         encoded in a *.wav file, even though this isn't a valid value in real life.
+  class InvalidSamplerInfoError < StandardError; end
+
+  # Public: Provides a way to indicate the data contained in a "smpl" chunk.
+  #         That is, information about how the *.wav file could be used by a
+  #         sampler, such as the file's MIDI note or loop points. If a *.wav
+  #         file contains a "smpl" chunk, then Reader.sampler_info will
+  #         return an instance of this object with the relevant info.
+  class SamplerInfo
+    VALID_32_BIT_INTEGER_RANGE = 0..4_294_967_295    # :nodoc:
+    private_constant :VALID_32_BIT_INTEGER_RANGE
+
+
+    # Public: Constructs a new SamplerInfo instance.
+    #
+    # manufacturer_id - the ID of the manufacturer that this sample is intended for. If it's not
+    #                   intended for a sampler from a particular manufacturer, this should be 0.
+    #                   See the list at https://www.midi.org/specifications-old/item/manufacturer-id-numbers
+    # product_id - the ID of the product made by the manufacturer this sample is intended for.
+    #              If not intended for a particular product, this should be 0.
+    # sample_nanoseconds - the length of each sample in nanoseconds, which is typically determined by
+    #                      converting <code>1 / sample rate</code> (in seconds) into nanoseconds.
+    #                      For example, with a sample rate of 44100 this would be 22675 nanoseconds. However,
+    #                      this can be set to an arbitrary value to allow for fine tuning.
+    # midi_note - the MIDI note number of the sample. Should be between 0 and 127.
+    # fine_tuning_cents - the number of cents >= 0.0 and < 100.0 the note should be tuned up from the midi_note
+    #                     field. 100 cents is equal to one semitone. For example, if this value is 50.0, and
+    #                     midi_note is 60, then the sample is tuned half-way between MIDI note 60 and 61. If the
+    #                     value is 0, then the sample has no fine tuning.
+    # smpte_format - the SMPTE format. Should be 0, 24, 25, 29 or 30.
+    # smpte_offset - a SMPTETimecode representing the SMPTE time offset.
+    # loops - an Array of 0 or more SamplerLoop objects containing loop point info. Loop point info
+    #         can indicate that (for example) the sampler should loop between a given sample range as long
+    #         as the sample is played.
+    # sampler_specific_data - a String of data specific to the intended target sampler, or nil if there is no sampler
+    #                         specific data.
+    #
+    # Raises InvalidSamplerInfoError if the given arguments are can't be written to a *.wav file.
+    def initialize(manufacturer_id: required("manufacturer_id"),
+                   product_id: required("product_id"),
+                   sample_nanoseconds: required("sample_nanoseconds"),
+                   midi_note: required("midi_note"),
+                   fine_tuning_cents: required("fine_tuning_cents"),
+                   smpte_format: required("smpte_format"),
+                   smpte_offset: required("smpte_offset"),
+                   loops: required("loops"),
+                   sampler_specific_data: required("sampler_specific_data"))
+      validate_32_bit_integer_field(manufacturer_id, "manufacturer_id")
+      validate_32_bit_integer_field(product_id, "product_id")
+      validate_32_bit_integer_field(sample_nanoseconds, "sample_nanoseconds")
+      validate_32_bit_integer_field(midi_note, "midi_note")
+      validate_fine_tuning_cents(fine_tuning_cents)
+      validate_32_bit_integer_field(smpte_format, "smpte_format")
+      validate_smpte_offset(smpte_offset)
+      validate_loops(loops)
+      validate_sampler_specific_data(sampler_specific_data)
+
+      @manufacturer_id = manufacturer_id
+      @product_id = product_id
+      @sample_nanoseconds = sample_nanoseconds
+      @midi_note = midi_note
+      @fine_tuning_cents = fine_tuning_cents
+      @smpte_format = smpte_format
+      @smpte_offset = smpte_offset
+      @loops = loops
+      @sampler_specific_data = sampler_specific_data
+    end
+
+    # Public: Returns the ID of the manufacturer that this sample is intended for. If it's not
+    #         intended for a sampler from a particular manufacturer, this should be 0.
+    #         See the list at https://www.midi.org/specifications-old/item/manufacturer-id-numbers
+    attr_reader :manufacturer_id
+
+    # Public: Returns the ID of the product made by the manufacturer this sample is intended for.
+    #         If not intended for a particular product, this should be 0.
+    attr_reader :product_id
+
+    # Public: Returns the length of each sample in nanoseconds, which is typically determined by
+    #         converting <code>1 / sample rate</code> (in seconds) into nanoseconds. For example,
+    #         with a sample rate of 44100 this would be 22675 nanoseconds. However, this can be set
+    #         to an arbitrary value to allow for fine tuning.
+    attr_reader :sample_nanoseconds
+
+    # Public: Returns the MIDI note number of the sample, which normally should be between 0 and 127.
+    attr_reader :midi_note
+
+    # Public: Returns the number of cents >= 0.0 and < 100.0 the note should be tuned up from the midi_note
+    #         field. 100 cents is equal to one semitone. For example, if this value is 50, and midi_note is
+    #         60, then the sample is tuned half-way between MIDI note 60 and 61. If the value is 0, then the
+    #         sample has no fine tuning.
+    attr_reader :fine_tuning_cents
+
+    # Public: Returns the SMPTE format (0, 24, 25, 29 or 30)
+    attr_reader :smpte_format
+
+    # Public: Returns a SMPTETimecode representing the SMPTE time offset.
+    attr_reader :smpte_offset
+
+    # Public: Returns an Array of 0 or more SamplerLoop objects containing loop point info. Loop point info
+    #         can indicate that (for example) the sampler should loop between a given sample range as long
+    #         as the sample is played.
+    attr_reader :loops
+
+    # Public: Returns a String of data specific to the intended target sampler, or nil if there is no sampler
+    #         specific data. This is returned as a raw String because the structure of this data depends on
+    #         the specific sampler. If you want to use it, you'll need to unpack the String yourself.
+    attr_reader :sampler_specific_data
+
+    private
+
+    def required(keyword)
+      raise ArgumentError.new("missing keyword: #{keyword}")
+    end
+
+    # Internal
+    def validate_32_bit_integer_field(candidate, field_name)
+      unless candidate.is_a?(Integer) && VALID_32_BIT_INTEGER_RANGE === candidate
+        raise InvalidSamplerInfoError,
+              "Invalid `#{field_name}` value: `#{candidate}`. Must be an Integer between #{VALID_32_BIT_INTEGER_RANGE.min} and #{VALID_32_BIT_INTEGER_RANGE.max}"
+      end
+    end
+
+    # Internal
+    def validate_fine_tuning_cents(candidate)
+      unless (candidate.is_a?(Integer) || candidate.is_a?(Float)) && candidate >= 0.0 && candidate < 100.0
+        raise InvalidSamplerInfoError,
+              "Invalid `fine_tuning_cents` value: `#{candidate}`. Must be a number >= 0.0 and < 100.0"
+      end
+    end
+
+    # Internal
+    def validate_smpte_offset(candidate)
+      unless candidate.is_a?(SMPTETimecode)
+        raise InvalidSamplerInfoError,
+              "Invalid `smpte_offset` value: `#{candidate}`. Must be an instance of SMPTETimecode"
+      end
+    end
+
+    # Internal
+    def validate_loops(candidate)
+      unless candidate.is_a?(Array) && candidate.select {|loop| !loop.is_a?(SamplerLoop) }.empty?
+        raise InvalidSamplerInfoError,
+              "Invalid `loops` value: `#{candidate}`. Must be an Array of SampleLoop objects"
+      end
+    end
+
+    # Internal
+    def validate_sampler_specific_data(candidate)
+      unless candidate.is_a?(String)
+        raise InvalidSamplerInfoError,
+              "Invalid `sampler_specific_data` value: `#{candidate}`. Must be a String"
+      end
+    end
+  end
+end

data/lib/wavefile/sampler_loop.rb

@@ -0,0 +1,142 @@
+module WaveFile
+  # Public: Error that is raised when constructing a SamplerLoop instance that is invalid.
+  #         "Invalid" means that one or more fields have a value that can't be encoded in the
+  #         field inside a *.wav file. For example, there's no way to encode "-23" as a value
+  #         for the start_sample_frame field. However, this error _won't_ be raised for values
+  #         that can be encoded, but aren't semantically correct. For example, it's possible
+  #         to set the start_sample_frame or end_sample_frame fields to values that don't
+  #         correspond to the actual sample frame range of the file. This error _won't_ be
+  #         raised for "encodeable but not semantically valid" field values.
+  class InvalidSamplerLoopError < StandardError; end
+
+  # Public: Provides a way to indicate the data about sampler loop points
+  #         in a file's "smpl" chunk. That is, information about how a sampler
+  #         could loop between a sample range while playing this *.wav as a note.
+  #         If a *.wav file contains a "smpl" chunk, then Reader.sampler_info.loops
+  #         will return an array of SamplerLoop objects with the relevant info.
+  class SamplerLoop
+    VALID_32_BIT_INTEGER_RANGE = 0..4_294_967_295    # :nodoc:
+    private_constant :VALID_32_BIT_INTEGER_RANGE
+    VALID_LOOP_TYPES = [:forward, :alternating, :backward].freeze    # :nodoc:
+    private_constant :VALID_LOOP_TYPES
+
+
+    # Public: Constructs a new SamplerLoop instance.
+    #
+    # id - A numeric ID which identifies the specific loop. Should be an Integer 0 or greater.
+    # type - Indicates which direction the loop should run. Should either be one of the symbols
+    #        +:forward+, +:alternating+, +:backward+, or a positive Integer. If an Integer, then 0 will
+    #        be normalized to +:forward+, 1 to +:alternating+, 2 to +:backward+. Integer values 3 or
+    #        greater are allowed by the *.wav file spec, but don't necessarily have a defined meaning.
+    # start_sample_frame - The first sample frame in the loop.
+    # end_sample_frame - The last sample frame in the loop.
+    # fraction - A Float >= 0.0 and < 1.0 which specifies a fraction of a sample at which to start
+    #            the loop. This allows a loop start to be fine tuned at a resolution finer than one sample.
+    # play_count - The number of times to loop. Can be an Integer 0 or greater, or Float::INFINITY.
+    #              A value of 0 will be normalized to Float::INFINITY, because in the file format a
+    #              value of 0 means to repeat the loop indefinitely.
+    #
+    # Raises InvalidSamplerLoopError if the given arguments can't be written to a *.wav file.
+    def initialize(id: required("id"),
+                  type: required("type"),
+                  start_sample_frame: required("start_sample_frame"),
+                  end_sample_frame: required("end_sample_frame"),
+                  fraction: required("fraction"),
+                  play_count: required("play_count"))
+      type = normalize_type(type)
+      if play_count == 0
+        play_count = Float::INFINITY
+      end
+
+      validate_32_bit_integer_field(id, "id")
+      validate_loop_type(type)
+      validate_32_bit_integer_field(start_sample_frame, "start_sample_frame")
+      validate_32_bit_integer_field(end_sample_frame, "end_sample_frame")
+      validate_fraction(fraction)
+      validate_play_count(play_count)
+
+      @id = id
+      @type = type
+      @start_sample_frame = start_sample_frame
+      @end_sample_frame = end_sample_frame
+      @fraction = fraction
+      @play_count = play_count
+    end
+
+    # Public: Returns a numeric ID which identifies the specific loop
+    attr_reader :id
+
+    # Public: Returns a symbol indicating which direction the loop should run. The possible values
+    #         are :forward, :alternating, :backward, or a positive Integer. Integer values 3 or greater
+    #         are allowed by the *.wav file spec, but don't necessarily have a defined meaning.
+    attr_reader :type
+
+    # Public: Returns the first sample frame of the loop.
+    attr_reader :start_sample_frame
+
+    # Public: Returns the last sample frame of the loop.
+    attr_reader :end_sample_frame
+
+    # Public: A value >= 0.0 and < 1.0 which specifies a fraction of a sample at which to loop.
+    #         This allows a loop to be fine tuned at a resolution finer than one sample.
+    attr_reader :fraction
+
+    # Public: Returns the number of times to loop. Will be an Integer 1 or greater, or Float::INFINITY.
+    attr_reader :play_count
+
+    private
+
+    def required(keyword)
+      raise ArgumentError.new("missing keyword: #{keyword}")
+    end
+
+    # Internal
+    def normalize_type(type)
+      if !type.is_a?(Integer)
+        return type
+      end
+
+      if type == 0
+        :forward
+      elsif type == 1
+        :alternating
+      elsif type == 2
+        :backward
+      else
+        type
+      end
+    end
+
+    # Internal
+    def validate_32_bit_integer_field(candidate, field_name)
+      unless candidate.is_a?(Integer) && VALID_32_BIT_INTEGER_RANGE === candidate
+        raise InvalidSamplerLoopError,
+              "Invalid `#{field_name}` value: `#{candidate}`. Must be an Integer between #{VALID_32_BIT_INTEGER_RANGE.min} and #{VALID_32_BIT_INTEGER_RANGE.max}"
+      end
+    end
+
+    # Internal
+    def validate_loop_type(candidate)
+      unless VALID_LOOP_TYPES.include?(candidate) || (candidate.is_a?(Integer) && VALID_32_BIT_INTEGER_RANGE === candidate)
+        raise InvalidSamplerLoopError,
+              "Invalid `type` value: `#{candidate}`. Must be an Integer between #{VALID_32_BIT_INTEGER_RANGE.min} and #{VALID_32_BIT_INTEGER_RANGE.max} or one of #{VALID_LOOP_TYPES}"
+      end
+    end
+
+    # Internal
+    def validate_fraction(candidate)
+      unless (candidate.is_a?(Integer) || candidate.is_a?(Float)) && candidate >= 0.0 && candidate < 1.0
+        raise InvalidSamplerLoopError,
+              "Invalid `fraction` value: `#{candidate}`. Must be >= 0.0 and < 1.0"
+      end
+    end
+
+    # Internal
+    def validate_play_count(candidate)
+      unless candidate == Float::INFINITY || (candidate.is_a?(Integer) && VALID_32_BIT_INTEGER_RANGE === candidate)
+        raise InvalidSamplerLoopError,
+              "Invalid `type` value: `#{candidate}`. Must be Float::INFINITY or an Integer between #{VALID_32_BIT_INTEGER_RANGE.min} and #{VALID_32_BIT_INTEGER_RANGE.max}"
+      end
+    end
+  end
+end

data/lib/wavefile/smpte_timecode.rb

@@ -0,0 +1,61 @@
+module WaveFile
+  # Public: Error that is raised when constructing a SMPTETimecode instance that is not valid.
+  # Valid means that each field is in the range that can be encoded in a *.wav file, but not
+  # not necessarily semantically correct. For example, a SMPTETimecode field can be constructed
+  # with a hours value of 100, even though this isn't a valid value in real life.
+  class InvalidSMPTETimecodeError < StandardError; end
+
+  # Public: Represents an SMPTE timecode: https://en.wikipedia.org/wiki/SMPTE_timecode
+  #         If a *.wav file has a "smpl" chunk, then Reader.sampler_info.smpte_offset
+  #         will return an instance of this class.
+  class SMPTETimecode
+    VALID_8_BIT_UNSIGNED_INTEGER_RANGE = 0..255    # :nodoc:
+    private_constant :VALID_8_BIT_UNSIGNED_INTEGER_RANGE
+    VALID_8_BIT_SIGNED_INTEGER_RANGE = -128..127    # :nodoc:
+    private_constant :VALID_8_BIT_SIGNED_INTEGER_RANGE
+
+
+    # Public: Constructs a new SMPTETimecode instance.
+    #
+    # Raises InvalidSMPTETimecodeError if the given arguments can't be written to a *.wav file.
+    def initialize(hours: required("hours"),
+                   minutes: required("minutes"),
+                   seconds: required("seconds"),
+                   frames: required("frames"))
+      validate_8_bit_signed_integer_field(hours, "hours")
+      validate_8_bit_unsigned_integer_field(minutes, "minutes")
+      validate_8_bit_unsigned_integer_field(seconds, "seconds")
+      validate_8_bit_unsigned_integer_field(frames, "frames")
+
+      @hours = hours
+      @minutes = minutes
+      @seconds = seconds
+      @frames = frames
+    end
+
+    attr_reader :hours
+    attr_reader :minutes
+    attr_reader :seconds
+    attr_reader :frames
+
+    private
+
+    def required(keyword)
+      raise ArgumentError.new("missing keyword: #{keyword}")
+    end
+
+    def validate_8_bit_unsigned_integer_field(candidate, field_name)
+      unless candidate.is_a?(Integer) && VALID_8_BIT_UNSIGNED_INTEGER_RANGE === candidate
+        raise InvalidSMPTETimecodeError,
+              "Invalid `#{field_name}` value: `#{candidate}`. Must be an Integer between #{VALID_8_BIT_UNSIGNED_INTEGER_RANGE.min} and #{VALID_8_BIT_UNSIGNED_INTEGER_RANGE.max}"
+      end
+    end
+
+    def validate_8_bit_signed_integer_field(candidate, field_name)
+      unless candidate.is_a?(Integer) && VALID_8_BIT_SIGNED_INTEGER_RANGE === candidate
+        raise InvalidSMPTETimecodeError,
+              "Invalid `#{field_name}` value: `#{candidate}`. Must be an Integer between #{VALID_8_BIT_SIGNED_INTEGER_RANGE.min} and #{VALID_8_BIT_SIGNED_INTEGER_RANGE.max}"
+      end
+    end
+  end
+end