audio_waveform-ruby 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b59f3197bce64e87040f8f21d501027a21bfdffa
+  data.tar.gz: b5b2e04ffa3ce3085542f65d419885a9e2896592
+SHA512:
+  metadata.gz: 1d70deefc853262ceb4cb1c2670c6c417c7440c8fae0cb6cb0cfac6b5fff4861088bdfd1cd32b0124fccbbad8dc1ae6d421bb3e089939da3e21ab9c7ce80c71a
+  data.tar.gz: d1ef99d028155f8dc6dddf15c5ff3470ea7635570b784ab43b62e46508847375d67cbb08c98e351680df8b447f703df052eef46b07a0e42f6079bde6ac8e2c1b

data/COPYING

@@ -0,0 +1,202 @@
+
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/ChangeLog

@@ -0,0 +1,3 @@
+2013-10-14 Chris Needham <chris.needham@bbc.co.uk>
+
+ * v1.0.1, initial public release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in audio_waveform.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,36 @@
+PATH
+  remote: .
+  specs:
+    audio_waveform-ruby (1.0.1)
+      json
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.4)
+    json (1.8.0)
+    multi_json (1.8.1)
+    redcarpet (3.0.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.3)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.3)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    yard (0.8.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  audio_waveform-ruby!
+  redcarpet
+  rspec
+  simplecov
+  yard

data/README.md

@@ -0,0 +1,91 @@
+# audio_waveform-ruby
+
+The audio_waveform-ruby gem provides a Ruby API for access to audio waveform data
+files generated by the [audiowaveform](https://github.com/bbcrd/audiowaveform) program.
+
+Refer to the [audiowaveform](https://github.com/bbcrd/audiowaveform) documentation for more information and [this page](https://github.com/bbcrd/audiowaveform/blob/master/doc/DataFormat.md) for file format details.
+
+## Installation
+
+To install:
+
+    $ gem install audio_waveform-ruby
+
+or, if using bundler, add this line to your application's Gemfile:
+
+    gem 'audio_waveform'
+
+    gem 'audio_waveform-ruby', :require => 'audio_waveform', :git => 'https://github.com/bbcrd/audio_waveform-ruby.git'
+
+and run
+
+    $ bundle install
+
+## Usage
+
+To use this Gem in your program, add:
+
+    require 'audio_waveform'
+
+Then, to load and use data from an existing waveform data file:
+
+    waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
+
+    puts waveform.sample_rate       # Returns audio sample rate, in Hz
+    puts waveform.bits              # Returns resolution of waveform data points
+    puts waveform.samples_per_pixel # Returns waveform zoom level, in samples per pixel
+    puts waveform.length            # Returns number of waveform data points
+
+    (0...waveform.length).each do |i|
+      puts waveform.min(i)   # Returns waveform minimum at index i
+      puts waveform.max(i)   # Returns waveform maximum at index i
+    end
+
+To generate a binary representation of a waveform data file:
+
+    waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
+    data = waveform.to_binary
+
+To save waveform data as a file in binary format:
+
+    waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
+    waveform.save_as_binary("output.dat")
+
+To generate a JSON representation of a waveform data file:
+
+    waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
+    waveform.to_json
+
+To save waveform data as a file in JSON format:
+
+    waveform = AudioWaveform::WaveformDataFile.new(filename: "test.dat")
+    waveform.save_as_json("output.json")
+
+To create a new waveform data file:
+
+    waveform = AudioWaveform::WaveformDataFile.new(
+        sample_rate: 44100,
+        samples_per_pixel: 512,
+        bits: 8
+    )
+
+    waveform.append(-10, 10)
+            .append(-11, 11)
+            .append(-3, 3)
+    # etc
+
+## License
+
+See COPYING for details.
+
+## Contributing
+
+If you have a feature request or want to report a bug, we'd be happy to hear from you. Please either raise an [issue](https://github.com/bbcrd/audio_waveform-ruby/issues), or fork the project and send us a pull request.
+
+## Authors
+
+This software was written by [Chris Needham](https://github.com/chrisn), chris.needham at bbc.co.uk.
+
+## Copyright
+
+Copyright 2013 British Broadcasting Corporation

data/Rakefile

@@ -0,0 +1,25 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+require 'yard'
+
+task :default => :test
+
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = ["--color"]
+end
+
+desc "Run tests with code coverage"
+task :coverage do
+  ENV['COVERAGE'] = "true"
+  Rake::Task["test"].execute
+end
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = [
+    '--output-dir', 'docs',
+    '--default-return', 'void',
+    '--readme', 'README.md'
+  ]
+end

data/audio_waveform-ruby.gemspec

@@ -0,0 +1,25 @@
+$:.unshift File.expand_path('../lib', __FILE__)
+
+require 'audio_waveform/version'
+
+Gem::Specification.new do |s|
+  s.name          = "audio_waveform-ruby"
+  s.version       = AudioWaveform::VERSION
+  s.authors       = ["Chris Needham"]
+  s.email         = ["chris.needham@bbc.co.uk"]
+  s.description   = "The audiowaveform_ruby gem provides a Ruby API for access to audio waveform data files generated by the audiowaveform program"
+  s.summary       = "Reads, writes, and rescales audio waveform data files"
+  s.homepage      = "https://github.com/bbcrd/audio_waveform-ruby"
+
+  s.files         = `git ls-files`.split($/)
+  s.test_files    = s.files.grep(%r{^spec/audio_waveform/.*\.rb$})
+
+  s.require_paths = ["lib"]
+
+  s.add_dependency('json')
+
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('simplecov')
+  s.add_development_dependency('redcarpet')
+  s.add_development_dependency('yard')
+end

data/lib/audio_waveform.rb

@@ -0,0 +1,8 @@
+require "audio_waveform/error"
+require "audio_waveform/waveform_data_file"
+require "audio_waveform/version"
+
+# AudioWaveform Ruby gem. See README.md for usage information.
+#
+module AudioWaveform
+end

data/lib/audio_waveform/error.rb

@@ -0,0 +1,7 @@
+module AudioWaveform
+
+  # AudioWaveform exception class.
+  #
+  class Error < ::Exception
+  end
+end

data/lib/audio_waveform/version.rb

@@ -0,0 +1,6 @@
+module AudioWaveform
+
+  # AudioWaveform gem version.
+  #
+  VERSION = "1.0.1"
+end

data/lib/audio_waveform/waveform_data_file.rb

@@ -0,0 +1,287 @@
+require 'json'
+
+module AudioWaveform
+
+  # Provides access to audio waveform data, and serialization to and from
+  # binary and JSON data formats.
+  #
+  class WaveformDataFile
+
+    # @param args [Hash]
+    #
+    # @option args [String] :filename Loads the specified binary waveform data
+    #   file.
+    #
+    # @option args [Integer] :sample_rate
+    # @option args [Integer] :samples_per_pixel
+    # @option args [Integer] :bits
+    # @option args [Numeric, nil] :start_time Start time, in seconds, or nil
+    #   if no start time to be set.
+    #
+    def initialize(args)
+      if args[:filename]
+        read(args[:filename])
+      else
+        self.sample_rate       = args[:sample_rate]
+        self.samples_per_pixel = args[:samples_per_pixel]
+        self.bits              = args[:bits]
+        self.start_time        = args[:start_time]
+
+        @data = []
+      end
+    end
+
+    # @return [Integer] Audio sample rate, in Hz.
+    #
+    def sample_rate
+      @sample_rate
+    end
+
+    # @param sample_rate [Integer] Audio sample rate, in Hz. Must be greater
+    #   than zero.
+    #
+    def sample_rate=(sample_rate)
+      if sample_rate <= 0
+        raise Error, "Invalid sample rate: #{sample_rate}"
+      else
+        @sample_rate = sample_rate
+      end
+    end
+
+    # @return [Integer] Number of audio samples per waveform minimum/maximum
+    #   pair.
+    #
+    def samples_per_pixel
+      @samples_per_pixel
+    end
+
+    # Sets the waveform data scaling.
+    #
+    # @param samples_per_pixel [Integer] Number of audio samples per waveform
+    #   minimum/maximum pair.
+    #
+    def samples_per_pixel=(samples_per_pixel)
+      if samples_per_pixel <= 0
+        raise Error, "Invalid samples per pixel: #{samples_per_pixel}"
+      else
+        @samples_per_pixel = samples_per_pixel
+      end
+    end
+
+    # @return [Integer] Resolution of waveform data points, either 8 or 16 bits.
+    #
+    def bits
+      @bits
+    end
+
+    # Sets the resolution of waveform data points.
+    #
+    # @param bits [Integer] Number of bits, must be either 8 or 16 bits
+    #
+    def bits=(bits)
+      if bits != 8 && bits != 16
+        raise Error, "Invalid bits: #{bits}"
+      else
+        @bits = bits
+      end
+    end
+
+    # @return [Numeric, nil] Start time of the waveform data, in seconds, or
+    #   nil if not set.
+    #
+    def start_time
+      @start_time
+    end
+
+    #
+    # Sets the start time of the waveform data.
+    #
+    # @param start_time [Numeric, nil] Start time of the waveform data, in
+    #   seconds, or nil if none.
+    #
+    def start_time=(start_time)
+      if start_time.nil?
+        @start_time = nil
+      elsif start_time < 0
+        raise Error, "Invalid start time: #{start_time}"
+      else
+        @start_time = start_time
+      end
+    end
+
+    # Writes the waveform data to file in JSON format.
+    #
+    # @param filename [String] The name of the file to write.
+    # @return [WaveformDataFile] The current object.
+    #
+    def save_as_json(filename)
+      File.open(filename, "w") do |file|
+        file.write(to_json)
+      end
+
+      self
+    end
+
+    # Writes the waveform data to file in binary (.dat) format.
+    #
+    # @param filename [String] The name of the file to write.
+    # @return [WaveformDataFile] The current object.
+    #
+    def save_as_binary(filename)
+      File.open(filename, "wb") do |file|
+        file.write(to_binary)
+      end
+
+      self
+    end
+
+    # @return [Hash] A hash representation of the waveform data file.
+    #
+    def to_hash
+      obj = {
+        sample_rate:       @sample_rate,
+        bits:              @bits,
+        samples_per_pixel: @samples_per_pixel,
+        length:            @data.size / 2,
+        data:              @data
+      }
+
+      if @start_time
+        obj[:start_time] = @start_time
+      end
+
+      obj
+    end
+
+    # @return [String] A JSON representation of the waveform data file.
+    #
+    def to_json
+      JSON.generate(to_hash)
+    end
+
+    # @return [String] A binary representation of the waveform data file.
+    #
+    def to_binary
+      if @bits == 8
+        flags  = FLAG_8_BIT
+        format = "c*"
+      else
+        flags  = 0
+        format = "s*"
+      end
+
+      output = encode_header(1, flags, @sample_rate, @samples_per_pixel, size)
+      output += @data.pack(format)
+      output
+    end
+
+    # Appends a waveform minimum/maximum pair.
+    #
+    # @param min_sample [Integer] Minimum audio sample amplitude value.
+    # @param max_sample [Integer] Maximum audio sample amplitude value.
+    #
+    # @return [WaveformDataFile] The current object.
+    #
+    def append(min_sample, max_sample)
+      @data << min_sample
+      @data << max_sample
+
+      self
+    end
+
+    # @return [Integer] The minimum waveform data point at the specified index.
+    #
+    def min_sample(index)
+      @data[2 * index]
+    end
+
+    # @return [Integer] The maximum waveform data point at the specified index.
+    #
+    def max_sample(index)
+      @data[2 * index + 1]
+    end
+
+    # @return [Integer] Length of waveform data (number of minimum/maximum
+    #   value pairs).
+    #
+    def size
+      @data.size / 2
+    end
+
+    private
+
+    # Header format:
+    # version           - 4 byte signed integer
+    # flags             - 4 byte unsigned integer
+    # sample_rate       - 4 byte signed integer
+    # samples_per_pixel - 4 byte signed integer
+    # size              - 4 byte unsigned integer
+
+    HEADER_FORMAT = "lLllL"
+    HEADER_SIZE   = 20
+    FLAG_8_BIT    = 1
+
+    def read(filename)
+      # TODO: loading of JSON data from file
+
+      File.open(filename, "rb") do |file|
+        size = read_header(file)
+        read_data(file, size)
+      end
+    end
+
+    def encode_header(version, flags, sample_rate, samples_per_pixel, size)
+      [version, flags, sample_rate, samples_per_pixel, size].pack(HEADER_FORMAT)
+    end
+
+    def decode_header(header)
+      header.unpack(HEADER_FORMAT)
+    end
+
+    # @param file [File] The input file to read from.
+    # @return [Integer] Number of waveform data points, from Length header field.
+    #
+    def read_header(file)
+      header = file.read(HEADER_SIZE)
+
+      if header.nil? || header.bytesize != HEADER_SIZE
+        raise Error, "Failed to read file header"
+      end
+
+      version, flags, self.sample_rate, self.samples_per_pixel, size = decode_header(header)
+
+      if version != 1
+        raise Error, "Cannot load data file version: #{version}"
+      end
+
+      if (flags & FLAG_8_BIT) != 0
+        @bits = 8
+      else
+        @bits = 16
+      end
+
+      size
+    end
+
+    # @param file [File] The input file to read from.
+    # @param size [Integer] Number of waveform data points to read.
+    #
+    def read_data(file, size)
+      if @bits == 8
+        format = 'c*' # Array of 8-bit signed integers
+      elsif @bits == 16
+        format = 's*' # Array of 16-bit signed integers
+      end
+
+      length = size * (@bits / 8) * 2
+
+      raw_data = file.read(length)
+
+      if raw_data
+        @data = raw_data.unpack(format)
+      else
+        @data = []
+      end
+    end
+  end
+end

data/spec/audio_waveform/version_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+describe AudioWaveform do
+  describe "version" do
+    it "should return version number" do
+      AudioWaveform::VERSION.should match %r{^(\d+)(\.(\d+)){2}$}
+    end
+  end
+end

data/spec/audio_waveform/waveform_data_file_spec.rb

@@ -0,0 +1,393 @@
+require 'spec_helper'
+
+require 'tempfile'
+require 'tmpdir'
+
+describe AudioWaveform::WaveformDataFile do
+  context "with valid 8-bit data file" do
+    let(:filename) { "spec/data/test_file_stereo_8bit_64spp.dat" }
+    let(:file) { AudioWaveform::WaveformDataFile.new(filename: filename) }
+
+    describe "to_binary" do
+      it "should return binary data" do
+        output = file.to_binary
+
+        output.bytesize.should == 3620
+
+        expected = Digest::MD5.hexdigest(File.read(filename))
+        actual   = Digest::MD5.hexdigest(output)
+
+        actual.should == expected
+
+        fields = output.unpack("lLllL")
+        fields[0].should == 1 # version
+        fields[1].should == 1 # flags (8-bit)
+        fields[2].should == 16000
+        fields[3].should == 64
+        fields[4].should == 1800
+      end
+    end
+
+    describe "save_as_binary" do
+      let(:temp_filename) {
+        File.join(Dir.tmpdir, Dir::Tmpname.make_tmpname("waveform", 1))
+      }
+
+      after do
+        File.unlink(temp_filename)
+      end
+
+      it "should write binary data to a file" do
+        result = file.save_as_binary(temp_filename)
+        result.should == file
+
+        data = File.open(temp_filename, "rb") { |f| f.read }
+
+        data.bytesize.should == 3620
+      end
+    end
+
+    describe "to_json" do
+      it "should return JSON data" do
+        output = file.to_json
+
+        data = JSON.parse(output)
+
+        data.should have_key("sample_rate")
+        data["sample_rate"].should == 16000
+
+        data.should have_key("samples_per_pixel")
+        data["samples_per_pixel"].should == 64
+
+        data.should have_key("bits")
+        data["bits"].should == 8
+
+        data.should have_key("length")
+        data["length"].should == 1800
+
+        data.should have_key("data")
+        data["data"].should be_instance_of(Array)
+        data["data"].size.should == 3600
+      end
+    end
+
+    describe "save_as_json" do
+      let(:temp_filename) {
+        File.join(Dir.tmpdir, Dir::Tmpname.make_tmpname("waveform", 1))
+      }
+
+      after do
+        File.unlink(temp_filename)
+      end
+
+      it "should write JSON data to a file" do
+        result = file.save_as_json(temp_filename)
+        result.should == file
+
+        data = File.open(temp_filename, "rb") { |f| f.read }
+
+        obj = JSON.parse(data)
+        obj.should have_key("sample_rate")
+        obj.should have_key("samples_per_pixel")
+        obj.should have_key("bits")
+        obj.should have_key("length")
+        obj.should have_key("data")
+      end
+    end
+
+    describe "attributes" do
+      it "should return sample rate in hertz" do
+        file.sample_rate.should == 16000
+      end
+
+      it "should return samples per pixel" do
+        file.samples_per_pixel.should == 64
+      end
+
+      it "should return waveform data resolution in bits" do
+        file.bits.should == 8
+      end
+
+      it "should not have a start time" do
+        file.start_time.should be_nil
+      end
+
+      it "should return number of min and max waveform data pairs" do
+        file.size.should == 1800
+      end
+
+      it "should return waveform data" do
+        file.min_sample(0).should == 0
+        file.max_sample(0).should == 0
+
+        file.min_sample(26).should == -53
+        file.max_sample(26).should == 64
+
+        file.min_sample(206).should == 8
+        file.max_sample(206).should == 17
+
+        file.min_sample(217).should == -15
+        file.max_sample(217).should == -1
+
+        file.min_sample(1799).should == 0
+        file.max_sample(1799).should == 0
+      end
+    end
+  end
+
+  context "with valid 16-bit data file" do
+    let(:filename) { "spec/data/test_file_stereo_16bit_64spp.dat" }
+    let(:file) { AudioWaveform::WaveformDataFile.new(filename: filename) }
+
+    describe "attributes" do
+      it "should return sample rate in hertz" do
+        file.sample_rate.should == 16000
+      end
+
+      it "should return samples per pixel" do
+        file.samples_per_pixel.should == 64
+      end
+
+      it "should return waveform data resolution in bits" do
+        file.bits.should == 16
+      end
+
+      it "should not have a start time" do
+        file.start_time.should be_nil
+      end
+
+      it "should return number of min and max waveform data pairs" do
+        file.size.should == 1800
+      end
+
+      it "should return waveform data" do
+        file.min_sample(0).should == 0
+        file.max_sample(0).should == 0
+
+        file.min_sample(26).should == -13606
+        file.max_sample(26).should == 16602
+
+        file.min_sample(206).should == 2166
+        file.max_sample(206).should == 4512
+
+        file.min_sample(217).should == -4052
+        file.max_sample(217).should == -430
+
+        file.min_sample(1799).should == -8
+        file.max_sample(1799).should == 7
+      end
+    end
+  end
+
+  context "with a file containing no waveform data" do
+    let(:filename) { "spec/data/zero_length.dat" }
+    let(:file) { AudioWaveform::WaveformDataFile.new(filename: filename) }
+
+    describe "attributes" do
+      it "should return sample rate in hertz" do
+        file.sample_rate.should == 16000
+      end
+
+      it "should return samples per pixel" do
+        file.samples_per_pixel.should == 64
+      end
+
+      it "should return waveform data resolution in bits" do
+        file.bits.should == 8
+      end
+
+      it "should not have a start time" do
+        file.start_time.should be_nil
+      end
+
+      it "should return number of min and max waveform data pairs" do
+        file.size.should == 0
+      end
+    end
+  end
+
+  context "with a version 2 data file" do
+    let(:filename) { "spec/data/version2.dat" }
+
+    it "should not load the file" do
+      expect {
+        AudioWaveform::WaveformDataFile.new(filename: filename)
+      }.to raise_error(AudioWaveform::Error, "Cannot load data file version: 2")
+    end
+  end
+
+  context "with a file with invalid scale" do
+    let(:filename) { "spec/data/scale_too_low.dat" }
+
+    it "should not load the file" do
+      expect {
+        AudioWaveform::WaveformDataFile.new(filename: filename)
+      }.to raise_error(AudioWaveform::Error, "Invalid samples per pixel: 0")
+    end
+  end
+
+  context "with a file with invalid sample rate" do
+    let(:filename) { "spec/data/sample_rate_too_low.dat" }
+
+    it "should not load the file" do
+      expect {
+        AudioWaveform::WaveformDataFile.new(filename: filename)
+      }.to raise_error(AudioWaveform::Error, "Invalid sample rate: 0")
+    end
+  end
+
+  context "with a file with incomplete header" do
+    let(:filename) { "spec/data/invalid_header.dat" }
+
+    it "should not load the file" do
+      expect {
+        AudioWaveform::WaveformDataFile.new(filename: filename)
+      }.to raise_error(AudioWaveform::Error, "Failed to read file header")
+    end
+  end
+
+  context "with a newly created waveform data file" do
+    let(:file) {
+      AudioWaveform::WaveformDataFile.new(
+        sample_rate: 44100,
+        samples_per_pixel: 512,
+        bits: 16
+      )
+    }
+
+    describe "append" do
+      it "should append waveform data points" do
+        file.size.should == 0
+
+        file.append(-99, 101).append(-49, 51)
+
+        file.size.should == 2
+        file.min_sample(0).should == -99
+        file.max_sample(0).should == 101
+        file.min_sample(1).should == -49
+        file.max_sample(1).should == 51
+      end
+    end
+
+    describe "to_binary" do
+      it "should return binary data" do
+        output = file.to_binary
+
+        output.bytesize.should == 20
+
+        fields = output.unpack("lLllL")
+        fields[0].should == 1 # version
+        fields[1].should == 0 # flags (16-bit)
+        fields[2].should == 44100
+        fields[3].should == 512
+        fields[4].should == 0
+      end
+    end
+
+    describe "to_json" do
+      it "should return JSON string" do
+        output = file.to_json
+
+        data = JSON.parse(output)
+
+        data.should have_key("sample_rate")
+        data["sample_rate"].should == 44100
+
+        data.should have_key("samples_per_pixel")
+        data["samples_per_pixel"].should == 512
+
+        data.should have_key("bits")
+        data["bits"].should == 16
+
+        data.should have_key("length")
+        data["length"].should == 0
+
+        data.should have_key("data")
+        data["data"].should be_instance_of(Array)
+        data["data"].size.should == 0
+
+        data.should_not have_key("start_time")
+      end
+    end
+  end
+
+  context "with new waveform data file with start time" do
+    let(:file) {
+      AudioWaveform::WaveformDataFile.new(
+        sample_rate: 44100,
+        samples_per_pixel: 512,
+        bits: 16,
+        start_time: 8.5
+      )
+    }
+
+    describe "attributes" do
+      it "should return start time" do
+        file.start_time.should == 8.5
+      end
+    end
+
+    describe "to_json" do
+      it "should include start_time field in output" do
+        output = file.to_json
+
+        data = JSON.parse(output)
+
+        data.should have_key("start_time")
+        data["start_time"].should == 8.5
+      end
+    end
+
+  end
+
+  context "invalid constructor arguments" do
+    describe "bits" do
+      it "should raise exception if not 8 or 16" do
+        expect {
+          AudioWaveform::WaveformDataFile.new(
+            sample_rate: 44100,
+            samples_per_pixel: 512,
+            bits: 10
+          )
+        }.to raise_error(AudioWaveform::Error, %r{Invalid bits})
+      end
+    end
+
+    describe "sample_rate" do
+      it "should raise exception if too small" do
+        expect {
+          AudioWaveform::WaveformDataFile.new(
+            sample_rate: 0,
+            samples_per_pixel: 512,
+            bits: 8
+          )
+        }.to raise_error(AudioWaveform::Error, %r{Invalid sample rate})
+      end
+    end
+
+    describe "samples_per_pixel" do
+      it "should raise exception if too small" do
+        expect {
+          AudioWaveform::WaveformDataFile.new(
+            sample_rate: 44100,
+            samples_per_pixel: 0,
+            bits: 8
+          )
+        }.to raise_error(AudioWaveform::Error, %r{Invalid samples per pixel})
+      end
+    end
+
+    describe "start_time" do
+      it "should raise exception if less than zero" do
+        expect {
+          AudioWaveform::WaveformDataFile.new(
+            sample_rate: 44100,
+            samples_per_pixel: 512,
+            bits: 8,
+            start_time: -1.0
+          )
+        }.to raise_error(AudioWaveform::Error, %r{Invalid start time})
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'logger'
+
+Bundler.require :test
+
+if ENV['COVERAGE']
+  require 'simplecov'
+  SimpleCov.start do
+    # Exclude test code from coverage report
+    add_filter '/spec/'
+    add_filter '/vendor/'
+  end
+end
+
+# add lib to current path
+$:.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require 'audio_waveform'

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: audio_waveform-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Chris Needham
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: The audiowaveform_ruby gem provides a Ruby API for access to audio waveform
+  data files generated by the audiowaveform program
+email:
+- chris.needham@bbc.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- COPYING
+- ChangeLog
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- audio_waveform-ruby.gemspec
+- lib/audio_waveform.rb
+- lib/audio_waveform/error.rb
+- lib/audio_waveform/version.rb
+- lib/audio_waveform/waveform_data_file.rb
+- spec/audio_waveform/version_spec.rb
+- spec/audio_waveform/waveform_data_file_spec.rb
+- spec/data/invalid_header.dat
+- spec/data/sample_rate_too_low.dat
+- spec/data/scale_too_low.dat
+- spec/data/test_file_stereo_16bit_64spp.dat
+- spec/data/test_file_stereo_8bit_64spp.dat
+- spec/data/version2.dat
+- spec/data/zero_length.dat
+- spec/spec_helper.rb
+homepage: https://github.com/bbcrd/audio_waveform-ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Reads, writes, and rescales audio waveform data files
+test_files:
+- spec/audio_waveform/version_spec.rb
+- spec/audio_waveform/waveform_data_file_spec.rb
+has_rdoc: