pulse-analysis 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 13321ee37a8c9ee41fe615fae126c0a3b2837bda
+  data.tar.gz: 1b6a15cdb0924fb4bd09d64d5f8b6d2a25673455
+SHA512:
+  metadata.gz: c2a9b965a5210d0629915f5dbffe0aedc6bbb1e5afe4ac6f3d622a78fc3c233ea137f7a4725b8d0b97d2793284c03d74c502a4cab2cfa0027d21ff3f7771cc54
+  data.tar.gz: 8f2195c44bc4b2f8445a9f5d771977b224c95802e57372286dc57f8093ee24eb3d46e05ecd58b425e1c157fd5703bb5ba414231255f628f0c328ce4ce26515a4

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2017 Ari Russo
+
+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/README.md

@@ -0,0 +1,106 @@
+# Pulse Analysis
+
+Using an audio file, measure pulses for timing deviation
+
+This would generally be used to measure the timing accuracy of drum machines, sequencers and other music electronics.  Inspired by the [Inner Clock Systems Litmus Test](http://innerclocksystems.com/New%20ICS%20Litmus.html)
+
+## Installation
+
+The package [libsndfile](https://github.com/erikd/libsndfile) must be installed first.  It's available in *Homebrew*, *APT*, *Yum* as well as many other package managers. For those who wish to compile themselves or need more information, follow the link above for more information
+
+Install the gem itself using
+
+```sh
+gem install pulse-analysis
+```
+
+Or if you're using Bundler, add this to your Gemfile
+
+```ruby
+gem "pulse-analysis"
+```
+
+## Usage
+
+### Input file
+
+Pulse-Analysis operates on a single input audio file at a time.  This file must be in an uncompressed format such as *WAV* or *AIFF*.
+
+In keeping with conventions established by the Litmus Test, audio input files must be at least *48k* sample rate.  
+
+Mono audio files are recommended.  If a stereo file is used, only the left channel will be analyzed.
+
+It's recommended that the audio file have a pulse rate of *16th notes* at *120 BPM* and be around *10 minutes long*. In other words, to produce the best results, use only a single repetitive pulse-like sound (eg snare drum) striking 16th notes.
+
+Example audio files are included in the repository and can be found [here](https://github.com/arirusso/pulse-analysis/tree/master/spec/media)
+
+### Command Line
+
+```sh
+pulse-analysis /path/to/a/sound/file.wav
+```
+
+This will run the program and output something like
+
+```sh
+[/] Reading file /path/to/a/sound/file.wav Done!
+[/] Running analysis Done!
+[\] Generating Report Done!
+
++------------------------+-------------------------+-------------+
+|                         Pulse Analysis                         |
++------------------------+-------------------------+-------------+
+| Item                   | Value                                 |
++------------------------+-------------------------+-------------+
+| Sample rate            | 88200 (Hertz)                         |
+| Length                 | 4311 (Number of pulses) | 9m0s (Time) |
+| Tempo                  | 119.9371 (BPM)                        |
+| Longest period length  | 11289 (Samples)         | 127.99 (MS) |
+| Shortest period length | 10687 (Samples)         | 121.17 (MS) |
+| Average period length  | 11030.7838 (Samples)    | 125.07 (MS) |
+| Largest abberation     | 543 (Samples)           | 6.16 (MS)   |
+| Average abberation     | 155.5279 (Samples)      | 1.76 (MS)   |
++------------------------+-------------------------+-------------+
+```
+
+### In Ruby
+
+```ruby
+2.4.0 :002 > require "pulse-analysis"
+ => true
+
+2.4.0 :003 > PulseAnalysis.report("/path/to/a/sound/file.wav")
+ => {
+   :file=>{
+     :path=>"/path/to/a/sound/file.wav"},
+     :analysis=>[
+       {
+         :key=>:sample_rate,
+         :description=>"Sample rate",
+         :value=>{
+           :unit=>"Hertz",
+           :value=>88200
+         }
+       },
+       {
+         :key=>:tempo,
+         :description=>"Tempo",
+         :value=>{
+           :unit=>"BPM",
+           :value=>119.9371
+         }
+       },
+       ...
+```
+
+## Disclaimer
+
+With the subjective nature of the data at hand, this program is not meant to reflect poorly on any musicians, companies, hobbyists or anyone whose product has measurable timing.  After all, variation in timing may be desirable in musical context.
+
+Additionally, it's recommended that results be independently verified.  The configuration of a particular device or recording environment can cause variation in timing accuracy.
+
+## License
+
+Licensed under Apache 2.0, See the file LICENSE
+
+Copyright (c) 2017 [Ari Russo](http://arirusso.com)

data/bin/pulse-analysis

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require "pulse-analysis"
+require "pulse-analysis/console"
+
+require "optparse"
+require "tty-spinner"
+
+def help(opts)
+  puts(opts)
+  exit
+end
+
+options = {}
+
+parser = OptionParser.new do |opts|
+
+  opts.banner = "Usage: pulse-analysis [file] [options]"
+  opts.separator ""
+  opts.separator "Specific options:"
+
+  opts.on("-aAMPLITUDE", "--amplitude_threshold=AMPLITUDE", "Amplitude Threshold") do |amplitude|
+    options[:amplitude_threshold] = amplitude.to_f
+  end
+
+  opts.on("-lLENGTH", "--length_threshold=LENGTH", "Length Threshold") do |length|
+    options[:length_threshold] = length.to_i
+  end
+
+  opts.on("-q", "--quiet", "Quiet") do |quiet|
+    options[:quiet] = quiet
+  end
+
+  opts.on("-oFILE", "--output-file=FILE", "Output File (YAML)") do |file|
+    options[:output_file] = file
+  end
+
+  opts.on_tail("-h", "--help", "Show this message") { help(opts) }
+
+  opts.on_tail("--version", "Show version") do
+    puts PulseAnalysis::VERSION
+    exit
+  end
+
+  help(opts) if ARGV.empty?
+end
+
+parser.parse!
+
+unless options[:output_file].nil?
+  File.open(options[:output_file], "w") do |f|
+    f.write("")
+  end
+end
+
+sound = PulseAnalysis::Sound.load(ARGV[0])
+
+if options[:quiet]
+  analysis = PulseAnalysis::Analysis.new(sound, options)
+  analysis.run
+  analysis.validate
+  report = PulseAnalysis::Report.new(analysis)
+else
+  spinner = TTY::Spinner.new("[:spinner] :title")
+  analysis = nil
+  report = nil
+
+  spinner.update(title: "Reading file #{ARGV[0]}")
+  spinner.run("Done!") { analysis = PulseAnalysis::Analysis.new(sound, options) }
+
+  spinner.update(title: "Running analysis")
+  spinner.run("Done!") do
+    analysis.run
+    analysis.validate
+  end
+
+  spinner.update(title: "Generating Report")
+  spinner.run("Done!") { report = PulseAnalysis::Report.new(analysis) }
+
+  puts
+
+  table = PulseAnalysis::Console::Table.build(report)
+  puts(table.content)
+end
+
+unless options[:output_file].nil?
+  require "yaml"
+
+  File.open(options[:output_file], "w") do |f|
+    f.write(output.to_h.to_yaml)
+  end
+end

data/lib/pulse-analysis/analysis.rb

@@ -0,0 +1,213 @@
+module PulseAnalysis
+
+  class Analysis
+
+    MINIMUM_PULSES = 10
+
+    attr_reader :abberations, :data, :periods, :sound
+
+    # @param [PulseAnalysis::Sound] sound Sound to analyze
+    # @param [Hash] options
+    # @option options [Float] :amplitude_threshold Pulses above this amplitude will be analyzed
+    # @option options [Integer] :length_threshold Pulse periods longer than this value will be analyzed
+    def initialize(sound, options = {})
+      @amplitude_threshold = options[:amplitude_threshold]
+      @length_threshold = options[:length_threshold]
+      populate_sound(sound)
+      @data = AudioData.new(@sound)
+    end
+
+    # Run the analysis
+    # @return [Boolean]
+    def run
+      prepare
+      populate_periods
+      validate
+      true
+    end
+
+    # Average number of samples between pulses
+    # @return [Float]
+    def average_period
+      @average_period ||= @periods.inject(&:+).to_f / num_pulses
+    end
+
+    # Number of usable pulses in the audio file
+    # @return [Integer]
+    def num_pulses
+      @num_pulses ||= @periods.count
+    end
+
+    # Longest number of samples between pulse
+    # @return [Integer]
+    def longest_period
+      @longest_period ||= @periods.max
+    end
+
+    # Shortest number of samples between pulse
+    # @return [Integer]
+    def shortest_period
+      @shortest_period ||= @periods.min
+    end
+
+    # Tempo of the audio file in beats per minute (BPM)
+    # Assumes that the pulse is 16th notes as per the Innerclock
+    # Litmus Test
+    # @return [Float]
+    def tempo_bpm
+      @tempo_bpm ||= calculate_tempo_bpm
+    end
+
+    # Largest sequential abberation between pulses
+    # @return [Integer]
+    def largest_abberation
+      @largest_abberation ||= abberations.max || 0
+    end
+
+    # Average sequential abberation between pulses
+    # @return [Float]
+    def average_abberation
+      @average_abberation ||= calculate_average_abberation
+    end
+
+    # Non-zero pulse timing abberations derived from the periods
+    # @return [Array<Integer>]
+    def abberations
+      @abberations ||= calculate_abberations
+    end
+
+    # The threshold (0..1) at which pulses will register as high
+    # @return [Float]
+    def amplitude_threshold
+      @amplitude_threshold ||= calculate_amplitude_threshold
+    end
+
+    # Validate that analysis on the given data can produce
+    # meaningful results
+    # @return [Boolean]
+    def validate
+      if valid?
+        true
+      else
+        message = "Could not produce a valid analysis."
+        raise(message)
+      end
+    end
+
+    # Validate that the analysis has produced meaningful results
+    # @return [Boolean]
+    def valid?
+      @periods.count > MINIMUM_PULSES
+    end
+
+    private
+
+    def prepare
+      @data.prepare
+    end
+
+    # Calculate the average deviation from timing of one period to
+    # the next
+    # @return [Float]
+    def calculate_average_abberation
+      if abberations.empty?
+        0.0
+      else
+        abberations.inject(&:+).to_f / abberations.count
+      end
+    end
+
+    # Calculate the rhythmic tempo of the sound in beats per minute
+    # @return [Float]
+    def calculate_tempo_bpm
+      seconds = average_period / @sound.sample_rate
+      division = 4 # 16th notes
+      60 / seconds / division
+    end
+
+    # Load the sound file and validate the data
+    # @param [PulseAnalysis::Sound] sound Sound to analyze
+    # @return [PulseAnalysis::Sound]
+    def populate_sound(sound)
+      @sound = sound
+      @sound.validate_for_analysis
+      @sound
+    end
+
+    # Populate the instance with abberations derived from the periods
+    # @return [Array<Integer>]
+    def calculate_abberations
+      i = 0
+      abberations = []
+      @periods.each do |period|
+        unless i.zero?
+          last_period = @periods[i - 1]
+          abberations << period - last_period
+        end
+        i += 1
+      end
+      abberations.reject!(&:zero?)
+      abberations.map(&:abs)
+    end
+
+    # Calcuate the threshold at which pulses will register as high
+    # This is derived from the audio data
+    # @return [Float]
+    def calculate_amplitude_threshold
+      @data.max * 0.8
+    end
+
+    # Threshold at which periods will be disregarded if they are shorter than
+    # Defaults to 80% of the average period size
+    # @param [Array<Integer>]
+    # @return [Integer]
+    def length_threshold(raw_periods)
+      if @length_threshold.nil?
+        average_period = raw_periods.inject(&:+).to_f / raw_periods.count
+        @length_threshold = (average_period * 0.8).to_i
+      end
+      @length_threshold
+    end
+
+    # Calculate periods between pulses
+    # @return [Array<Integer>]
+    def populate_periods
+      is_low = false
+      periods = []
+      period_index = 0
+      @data.each do |frame|
+        if frame.abs < amplitude_threshold # if pulse is low
+          is_low = true
+          periods[period_index] ||= 0
+          # count period length
+          periods[period_index] += 1
+        else
+          # pulse is high
+          if is_low # last frame, the pulse was low
+            is_low = false
+            # move to next period
+            period_index += 1
+          end
+          # if the pulse was already high, don't do anything
+        end
+      end
+      prune_periods(periods)
+      @periods = periods
+    end
+
+    # Remove any possibly malformed periods from the calculated set
+    # @return [Array<Integer>]
+    def prune_periods(periods)
+      # remove the first and last periods in case recording wasn't started/
+      # stopped in sync
+      periods.shift
+      periods.pop
+      # remove periods that are below length threshold
+      length = length_threshold(periods)
+      periods.reject! { |period| period < length }
+      periods
+    end
+
+  end
+
+end

data/lib/pulse-analysis/audio_data.rb

@@ -0,0 +1,54 @@
+module PulseAnalysis
+
+  class AudioData
+
+    extend Forwardable
+
+    def_delegators :@data, :[], :count, :each, :length, :max, :min, :size
+
+    # @param [PulseAnalysis::Sound] sound
+    def initialize(sound)
+      @sound = sound
+      @data = @sound.data
+    end
+
+    # Prepare the audio data for analysis
+    # @return [Boolean]
+    def prepare
+      convert_to_mono if convert_to_mono?
+      normalize if normalize?
+      true
+    end
+
+    private
+
+    # Should the audio data be normalized?
+    # @return [Boolean]
+    def normalize?
+      headroom = 1.0 - @data.max
+      headroom > 0.0
+    end
+
+    # Normalize the audio data
+    # @return [Array<Float>]
+    def normalize
+      factor = 1.0 / @data.max
+      @data.map! { |frame| frame * factor }
+    end
+
+    # Should the audio data be converted to a single channel?
+    # @return [Boolean]
+    def convert_to_mono?
+      @sound.num_channels > 1
+    end
+
+    # Logic for converting a stereo sound to mono
+    # @return [Array<Float>]
+    def convert_to_mono
+      # Use left channel
+      @data = @data.map(&:first)
+    end
+
+  end
+
+end

data/lib/pulse-analysis/console/table.rb

@@ -0,0 +1,84 @@
+require "terminal-table"
+
+module PulseAnalysis
+
+  module Console
+
+    class Table
+
+      attr_reader :content
+
+      # @param [PulseAnalysis::Report] report
+      # @return [PulseAnalysis::Console::Table]
+      def self.build(report)
+        table = new(report)
+        table.build
+        table
+      end
+
+      # @param [PulseAnalysis::Report] report
+      def initialize(report)
+        @report = report
+      end
+
+      # Populate the table content
+      # @return [Terminal::Table]
+      def build
+        @content = Terminal::Table.new(title: "Pulse Analysis", headings: header) do |table|
+          @report.items.each { |item| table << build_row(item) }
+        end
+      end
+
+      private
+
+      # Table header
+      # @return [Array<Hash, String>]
+      def header
+        [
+          "Item",
+          {
+            value: "Value",
+            colspan: value_colspan
+          }
+        ]
+      end
+
+      # How many columns should the 'value' row be?
+      # @return [Integer]
+      def value_colspan
+        @value_colspan ||= @report.items.map { |item| item[:value] }.map(&:count).max
+      end
+
+      # Build a single table row with the given report item
+      # @param [Hash] item
+      # @return [Array<String>]
+      def build_row(item)
+        row = [item[:description]]
+        if item[:value].kind_of?(Array)
+          # item has multiple units of measure
+          item[:value].each_with_index do |value, i|
+            cell = {
+              value: "#{value[:value]} (#{value[:unit]})",
+            }
+            # make up remaining colspan
+            if item[:value].last == value
+              cell[:colspan] = value_colspan - i
+            end
+            row << cell
+          end
+        else
+          # item has single unit of measure
+          value = item[:value]
+          row << {
+            value: "#{value[:value]} (#{value[:unit]})",
+            colspan: value_colspan # full width
+          }
+        end
+        row
+      end
+
+    end
+
+  end
+
+end

data/lib/pulse-analysis/console.rb

@@ -0,0 +1,8 @@
+require "pulse-analysis/console/table"
+
+module PulseAnalysis
+
+  module Console
+  end
+
+end

data/lib/pulse-analysis/conversion.rb

@@ -0,0 +1,43 @@
+module PulseAnalysis
+
+  module Conversion
+
+    extend self
+
+    # Convert a quantity of samples to seconds with regard to the sample
+    # rate
+    # @param [Integer] sample_rate Sample rate in hertz (eg 88200)
+    # @param [Integer] num_samples
+    # @return [Float]
+    def num_samples_to_seconds(sample_rate, num_samples)
+      num_samples.to_f / sample_rate
+    end
+
+    # Convert a quantity of samples to a formatted time string with regard
+    # to the sample rate.  (eg "1m20s", "2m22.4s"
+    # @param [Integer] sample_rate Sample rate in hertz (eg 88200)
+    # @param [Integer] num_samples
+    # @return [String]
+    def num_samples_to_formatted_time(sample_rate, num_samples)
+      min, sec = *num_samples_to_seconds(sample_rate, num_samples).divmod(60)
+      # convert seconds to int if it has no decimal value
+      if sec.to_i % sec == 0
+        sec = sec.to_i
+      end
+      # only include minutes if there is a value
+      result = min > 0 ? "#{min}m" : ""
+      result + "#{sec}s"
+    end
+
+    # Convert a quantity of samples to milliseconds with regard to the
+    # sample rate
+    # @param [Integer] sample_rate Sample rate in hertz (eg 88200)
+    # @param [Integer] num_samples
+    # @return [Float]
+    def num_samples_to_millis(sample_rate, num_samples)
+      (num_samples.to_f / sample_rate) * 1000
+    end
+
+  end
+
+end

data/lib/pulse-analysis/file.rb

@@ -0,0 +1,47 @@
+module PulseAnalysis
+
+  # An audio file
+  class File
+
+    extend Forwardable
+
+    attr_reader :file, :num_channels, :size
+
+    def_delegators :@file, :absolute_path, :path
+
+    # @param [::File, String] file_or_path
+    def initialize(file_or_path)
+      @file = file_or_path.kind_of?(::File) ? file_or_path : ::File.new(file_or_path)
+      @sound = RubyAudio::Sound.open(@file)
+      @size = ::File.size(@file)
+      @num_channels = @sound.info.channels
+    end
+
+    # The sample rate of the audio file
+    # @return [Integer]
+    def sample_rate
+      @sample_rate ||= @sound.info.samplerate
+    end
+
+    # Read the audio file into memory
+    # @param [Hash] options
+    # @option options [IO] :logger
+    # @return [Array<Array<Float>>, Array<Float>] File data
+    def read(options = {})
+      if logger = options[:logger]
+        logger.puts("Reading audio file #{@file}")
+      end
+      buffer = RubyAudio::Buffer.float(@size, @num_channels)
+      begin
+        @sound.seek(0)
+        @sound.read(buffer, @size)
+        data = buffer.to_a
+      rescue RubyAudio::Error
+      end
+      logger.puts("Finished reading audio file #{@file}") if logger
+      data
+    end
+
+  end
+
+end

data/lib/pulse-analysis/report.rb

@@ -0,0 +1,151 @@
+module PulseAnalysis
+
+  class Report
+
+    attr_reader :analysis, :items
+
+    # @param [PulseAnalysis::Analysis] analysis The analysis to report on.  Required that analysis has been run (see Analysis#run)
+    def initialize(analysis)
+      @analysis = analysis
+      populate_items
+    end
+
+    # Convert the report to a hash
+    # @return [Hash]
+    def to_h
+      {
+        file: {
+          path: @analysis.sound.audio_file.path.to_s
+        },
+        analysis: @items
+      }
+    end
+
+    # Override Object#inspect to not include the large audio data
+    # @return [String]
+    def inspect
+      to_h.inspect
+    end
+
+    private
+
+    # Usable length of the audio file in the format (MMmSSs)
+    # @return [String]
+    def length_in_formatted_time
+      @length_in_formatted_time ||= Conversion.num_samples_to_formatted_time(@analysis.sound.sample_rate, @analysis.sound.size)
+    end
+
+    # Popualate the report
+    # @return [Array]
+    def populate_items
+      if @analysis.periods.nil?
+        raise "Analysis has not been run yet (use Analysis#run)"
+      else
+        @items = []
+        @items << {
+          key: :sample_rate,
+          description: "Sample rate",
+          value: {
+            unit: "Hertz",
+            value: @analysis.sound.sample_rate
+          }
+        }
+        @items << {
+          key: :length,
+          description: "Length",
+          value: [
+            {
+              unit: "Number of pulses",
+              value: @analysis.num_pulses
+            },
+            {
+              unit: "Time",
+              value: length_in_formatted_time
+            }
+          ]
+        }
+        @items << {
+          key: :tempo,
+          description: "Tempo",
+          value: {
+            unit: "BPM",
+            value: @analysis.tempo_bpm.round(4)
+          }
+        }
+        @items << {
+          key: :longest_period,
+          description: "Longest period length",
+          value: [
+            {
+              unit: "Samples",
+              value: @analysis.longest_period
+            },
+            {
+              unit: "ms",
+              value: Conversion.num_samples_to_millis(@analysis.sound.sample_rate, @analysis.longest_period).round(2)
+            }
+          ]
+        }
+        @items << {
+          key: :shortest_period,
+          description: "Shortest period length",
+          value: [
+            {
+              unit: "Samples",
+              value: @analysis.shortest_period
+            },
+            {
+              unit: "ms",
+              value: Conversion.num_samples_to_millis(@analysis.sound.sample_rate, @analysis.shortest_period).round(2)
+            }
+          ]
+        }
+        @items << {
+          key: :average_period,
+          description: "Average period length",
+          value: [
+            {
+              unit: "Samples",
+              value: @analysis.average_period.round(4)
+            },
+            {
+              unit: "ms",
+              value: Conversion.num_samples_to_millis(@analysis.sound.sample_rate, @analysis.average_period).round(2)
+            }
+          ]
+        }
+        @items << {
+          key: :largest_abberation,
+          description: "Largest abberation",
+          value: [
+            {
+              unit: "Samples",
+              value: @analysis.largest_abberation
+            },
+            {
+              unit: "ms",
+              value: Conversion.num_samples_to_millis(@analysis.sound.sample_rate, @analysis.largest_abberation).round(2)
+            }
+          ]
+        }
+        @items << {
+          key: :average_abberation,
+          description: "Average abberation",
+          value: [
+            {
+              unit: "Samples",
+              value: @analysis.average_abberation.round(4)
+            },
+            {
+              unit: "ms",
+              value: Conversion.num_samples_to_millis(@analysis.sound.sample_rate, @analysis.average_abberation).round(2)
+            }
+          ]
+        }
+        @items
+      end
+    end
+
+  end
+
+end

data/lib/pulse-analysis/sound.rb

@@ -0,0 +1,63 @@
+module PulseAnalysis
+
+  class Sound
+
+    extend Forwardable
+
+    attr_reader :audio_file, :data, :size
+    def_delegators :@audio_file, :num_channels, :sample_rate
+
+    # Load a sound from the given file path
+    # @param [::File, String] file_or_path
+    # @param [Hash] options
+    # @option options [IO] logger
+    # @return [Sound]
+    def self.load(file_or_path, options = {})
+      file = PulseAnalysis::File.new(file_or_path)
+      new(file, options)
+    end
+
+    # @param [PulseAnalysis::File] audio_file
+    # @param [Hash] options
+    # @option options [IO] :logger
+    def initialize(audio_file, options = {})
+      @audio_file = audio_file
+      populate(options)
+      report(options[:logger]) if options[:logger]
+    end
+
+    # Log a report about the sound
+    # @param [IO] logger
+    # @return [Boolean]
+    def report(logger)
+      logger.puts("Sound report for #{@audio_file.file}")
+      logger.puts("  Sample rate: #{@audio_file.sample_rate}")
+      logger.puts("  Channels: #{@audio_file.num_channels}")
+      logger.puts("  File size: #{@audio_file.size}")
+      true
+    end
+
+    # Validate that the sound is analyzable
+    # @return [Boolean]
+    def validate_for_analysis
+      if sample_rate < 48000
+        raise "Sample rate must be at least 48000"
+      end
+      true
+    end
+
+    private
+
+    # Populate the sound meta/data
+    # @param [Hash] options
+    # @option options [IO] :logger
+    # @return [Sound]
+    def populate(options = {})
+      @data = @audio_file.read(options)
+      @size = data.size
+      self
+    end
+
+  end
+
+end

data/lib/pulse-analysis.rb

@@ -0,0 +1,39 @@
+# Pulse Analysis
+# Measure pulse timing accuracy in an audio file
+#
+# (c)2017 Ari Russo
+# Apache 2.0 License
+# https://github.com/arirusso/pulse-analysis
+#
+
+# libs
+require "forwardable"
+require "ruby-audio"
+
+# modules
+require "pulse-analysis/conversion"
+
+# classes
+require "pulse-analysis/analysis"
+require "pulse-analysis/audio_data"
+require "pulse-analysis/file"
+require "pulse-analysis/report"
+require "pulse-analysis/sound"
+
+module PulseAnalysis
+
+  VERSION = "0.0.1"
+
+  # Analyze the given audio file with the given options and generate a report
+  # @param [::File, String] file_or_path File or path to audio file to run analysis on
+  # @param [Hash] options
+  # @option options [Float] :amplitude_threshold Pulses above this amplitude will be analyzed
+  # @option options [Integer] :length_threshold Pulse periods longer than this value will be analyzed
+  # @return [PulseAnalysis::Report]
+  def self.report(file_or_path, options = {})
+    analysis = Analysis.new(file_or_path, options)
+    analysis.run
+    Report.new(analysis)
+  end
+
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: pulse-analysis
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ari Russo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.2
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+- !ruby/object:Gem::Dependency
+  name: ruby-audio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.1
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+- !ruby/object:Gem::Dependency
+  name: tty-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+description: Measure pulse timing accuracy in an audio file.  Use to measure the timing
+  accuracy of drum machines, sequencers and other music electronics. Inspired by the
+  Inner Clock Systems Litmus Test
+email:
+- ari.russo@gmail.com
+executables:
+- pulse-analysis
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/pulse-analysis
+- lib/pulse-analysis.rb
+- lib/pulse-analysis/analysis.rb
+- lib/pulse-analysis/audio_data.rb
+- lib/pulse-analysis/console.rb
+- lib/pulse-analysis/console/table.rb
+- lib/pulse-analysis/conversion.rb
+- lib/pulse-analysis/file.rb
+- lib/pulse-analysis/report.rb
+- lib/pulse-analysis/sound.rb
+homepage: http://github.com/arirusso/pulse-analysis
+licenses:
+- Apache-2.0
+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: 1.3.6
+requirements: []
+rubyforge_project: pulse-analysis
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Measure pulse timing accuracy in an audio file
+test_files: []