waveformjson 0.0.1

data/README.md

@@ -0,0 +1,97 @@
+Waveformjson
+========
+
+Waveformjson is based on [waveform](https://github.com/benalavi/waveform) and functions the same. The only difference is that it generates json instead of json files.
+
+Installation
+============
+
+Waveformjson depends on `ruby-audio`, which in turn depends on libsndfile.
+
+Build libsndfile from (http://www.mega-nerd.com/libsndfile/), install it via `apt` (`sudo apt-get install libsndfile1-dev`), `libsndfile` in macports, etc...
+
+Then:
+
+    $ gem install waveformjson
+
+or add following to Gemfile:
+
+    gem 'waveformjson'
+
+CLI Usage
+=========
+
+    $ waveformjson song.wav waveform.json
+
+There are some nifty options you can supply to switch things up:
+
+    -m sets the method used to sample the source audio file, it can either be
+        'peak' or 'rms'. 'peak' is probably what you want because it looks
+        cooler, but 'rms' is closer to what you actually hear.
+    -W sets the width (in pixels) of the waveform.
+
+There are also some less-nifty options:
+
+    -q will generate your waveform without printing out a bunch of stuff.
+    -h will print out a help screen with all this info.
+    -F will automatically overwrite destination file.
+
+Usage in code
+=============
+
+The CLI is really just a thin wrapper around the Waveformjson class, which you can also use in your programs for reasons I haven't thought of. The Waveform class takes pretty much the same options as the CLI when generating waveforms.
+
+Requirements
+============
+
+`ruby-audio`
+
+The gem version, *not* the old outdated library listed on RAA. `ruby-audio` is a wrapper for `libsndfile`, on my Ubuntu 10.04LTS VM I installed the necessary libs to build `ruby-audio` via: `sudo apt-get install libsndfile1-dev`.
+
+Converting MP3 to WAV
+=====================
+
+Waveform used to (very thinly) wrap ffmpeg to convert MP3 (and whatever other format) to WAV audio before processing the WAV and generating the waveform image. It seemed a bit presumptious for Waveform to handle that, especially since you might want to use your own conversion options (i.e. downsampling the bitrate to generate waveforms faster, etc...).
+
+If you happen to be using ffmpeg, you can easily convert MP3 to WAV via:
+
+    ffmpeg -i "/path/to/source/file.mp3" -f wav "/path/to/output/file.wav"
+
+Tests
+=====
+
+    $ rake
+
+
+Sample sound file used in tests is in the Public Domain from soundbible.com: <http://soundbible.com/1598-Electronic-Chime.html>.
+
+References
+==========
+
+<http://pscode.org/javadoc/src-html/org/pscode/ui/audiotrace/AudioPlotPanel.html#line.996>
+<http://github.com/pangdudu/rude/blob/master/lib/waveform_narray_testing.rb>
+<http://stackoverflow.com/questions/1931952/asp-net-create-waveform-image-from-mp3>
+<http://codeidol.com/java/swing/Audio/Build-an-Audio-Waveform-Display>
+
+License
+=======
+
+Copyright (c) 2013 liufengyun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Rakefile

@@ -0,0 +1,5 @@
+task :default => :test
+
+task :test do
+  system "ruby test/*.rb"
+end

data/bin/waveformjson

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+require "waveformjson"
+require "optparse"
+
+options = Waveformjson::DefaultOptions
+optparse = OptionParser.new do |o|
+  o.banner = "Usage: waveformjson [options] source_audio [ouput.json]"
+  o.version = Waveformjson::VERSION
+
+  o.on("-m", "--method METHOD", "Wave analyzation method (can be 'peak' or 'rms') -- Default '#{Waveformjson::DefaultOptions[:method]}'.") do |method|
+    options[:method] = method.to_sym
+  end
+
+  o.on("-W", "--width WIDTH", "Width (in pixels) of generated waveform image -- Default #{Waveformjson::DefaultOptions[:width]}.") do |width|
+    options[:width] = width.to_i
+  end
+
+  options[:logger] = $stdout
+  o.on("-q", "--quiet", "Don't print anything out when generating waveform") do
+    options[:logger] = nil
+  end
+
+  options[:force] = false
+  o.on("-F", "--force", "Force generationg of waveform if file exists") do
+    options[:force] = true
+  end
+
+  o.on("-h", "--help", "Display this screen") do
+    puts o
+    exit
+  end
+end
+
+optparse.parse!
+
+begin
+  output = ARGV[1] || "waveform.json"
+
+  if File.exists?(output) && !options[:force]
+    raise RuntimeError.new("Destination file #{output} exists. Use --force if you want to automatically remove it.")
+  end
+
+  json = Waveformjson.generate(ARGV[0], options)
+  File.open(output) do |f|
+    f << json.to_s
+  end
+rescue ArgumentError => e
+  puts e.message + "\n\n"
+  puts optparse
+rescue RuntimeError => e
+  puts e.message
+end

data/lib/waveformjson.rb

@@ -0,0 +1,195 @@
+require File.join(File.dirname(__FILE__), "waveformjson/version")
+
+require "ruby-audio"
+
+class Waveformjson
+  DefaultOptions = {
+    :method => :peak,
+    :width => 1800,
+    :logger => nil
+  }
+  
+  attr_reader :source
+  
+  class << self    
+    # Generate a Waveform image at the given filename with the given options.
+    # 
+    # Available options (all optional) are:
+    # 
+    #   :method => The method used to read sample frames, available methods
+    #     are peak and rms. peak is probably what you're used to seeing, it uses
+    #     the maximum amplitude per sample to generate the waveform, so the
+    #     waveform looks more dynamic. RMS gives a more fluid waveform and
+    #     probably more accurately reflects what you hear, but isn't as
+    #     pronounced (typically).
+    #     
+    #     Can be :rms or :peak
+    #     Default is :peak.
+    # 
+    #   :width => The width (in pixels) of the final waveform image.
+    #     Default is 1800.
+    #
+    #   :logger => IOStream to log progress to.
+    #
+    # Example:
+    #   Waveformjson.generate("Kickstart My Heart.wav")
+    #   Waveformjson.generate("Kickstart My Heart.wav", :method => :rms)
+    #   Waveformjson.generate("Kickstart My Heart.wav", :logger => $stdout)
+    #
+    def generate(source, options={})
+      options = DefaultOptions.merge(options)
+      
+      raise ArgumentError.new("No source audio filename given, must be an existing sound file.") unless source
+      raise RuntimeError.new("Source audio file '#{source}' not found.") unless File.exist?(source)
+
+      @log = Log.new(options[:logger])
+      @log.start!
+      
+      # Frames gives the amplitudes for each channel, for our waveform we're
+      # saying the "visual" amplitude is the average of the amplitude across all
+      # the channels. This might be a little weird w/ the "peak" method if the
+      # frames are very wide (i.e. the image width is very small) -- I *think*
+      # the larger the frames are, the more "peaky" the waveform should get,
+      # perhaps to the point of inaccurately reflecting the actual sound.
+      samples = frames(source, options[:width], options[:method]).collect do |frame|
+        frame.inject(0.0) { |sum, peak| sum + peak } / frame.size
+      end
+
+      samples
+    end
+    
+    private
+    
+    # Returns a sampling of frames from the given RubyAudio::Sound using the
+    # given method the sample size is determined by the given pixel width --
+    # we want one sample frame per horizontal pixel.
+    def frames(source, width, method = :peak)
+      raise ArgumentError.new("Unknown sampling method #{method}") unless [ :peak, :rms ].include?(method)
+      
+      frames = []
+
+      RubyAudio::Sound.open(source) do |audio|
+        frames_read = 0
+        frames_per_sample = (audio.info.frames.to_f / width.to_f).floor
+        sample = RubyAudio::Buffer.new("float", frames_per_sample, audio.info.channels)
+
+        @log.timed("Sampling #{frames_per_sample} frames per sample: ") do
+          while(frames_read = audio.read(sample)) > 0
+            frames << send(method, sample, audio.info.channels)
+            @log.out(".")
+          end
+        end
+      end
+      
+      frames
+    rescue RubyAudio::Error => e
+      raise e unless e.message == "File contains data in an unknown format."
+      raise RuntimeError.new("Source audio file #{source} could not be read by RubyAudio library -- Hint: non-WAV files are no longer supported, convert to WAV first using something like ffmpeg (RubyAudio: #{e.message})")
+    end
+  
+    # Returns an array of the peak of each channel for the given collection of
+    # frames -- the peak is individual to the channel, and the returned collection
+    # of peaks are not (necessarily) from the same frame(s).
+    def peak(frames, channels=1)
+      peak_frame = []
+      (0..channels-1).each do |channel|
+        peak_frame << channel_peak(frames, channel)
+      end
+      peak_frame
+    end
+
+    # Returns an array of rms values for the given frameset where each rms value is
+    # the rms value for that channel.
+    def rms(frames, channels=1)
+      rms_frame = []
+      (0..channels-1).each do |channel|
+        rms_frame << channel_rms(frames, channel)
+      end
+      rms_frame
+    end
+  
+    # Returns the peak voltage reached on the given channel in the given collection
+    # of frames.
+    # 
+    # TODO: Could lose some resolution and only sample every other frame, would
+    # likely still generate the same waveform as the waveform is so comparitively
+    # low resolution to the original input (in most cases), and would increase
+    # the analyzation speed (maybe).
+    def channel_peak(frames, channel=0)
+      peak = 0.0
+      frames.each do |frame|
+        next if frame.nil?
+        frame = Array(frame)
+        peak = frame[channel].abs if frame[channel].abs > peak
+      end
+      peak
+    end
+
+    # Returns the rms value across the given collection of frames for the given
+    # channel.
+    def channel_rms(frames, channel=0)
+      Math.sqrt(frames.inject(0.0){ |sum, frame| sum += (frame ? Array(frame)[channel] ** 2 : 0) } / frames.size)
+    end
+  end
+end
+
+class Waveformjson
+  # A simple class for logging + benchmarking, nice to have good feedback on a
+  # long batch operation.
+  # 
+  # There's probably 10,000,000 other bechmarking classes, but writing this was
+  # easier than using Google.
+  class Log
+    attr_accessor :io
+
+    def initialize(io=$stdout)
+      @io = io
+    end
+
+    # Prints the given message to the log
+    def out(msg)
+      io.print(msg) if io
+    end
+
+    # Prints the given message to the log followed by the most recent benchmark
+    # (note that it calls .end! which will stop the benchmark)
+    def done!(msg="")
+      out "#{msg} (#{self.end!}s)\n"
+    end
+
+    # Starts a new benchmark clock and returns the index of the new clock.
+    # 
+    # If .start! is called again before .end! then the time returned will be
+    # the elapsed time from the next call to start!, and calling .end! again
+    # will return the time from *this* call to start! (that is, the clocks are
+    # LIFO)
+    def start!
+      (@benchmarks ||= []) << Time.now
+      @current = @benchmarks.size - 1
+    end
+
+    # Returns the elapsed time from the most recently started benchmark clock
+    # and ends the benchmark, so that a subsequent call to .end! will return
+    # the elapsed time from the previously started benchmark clock.
+    def end!
+      elapsed = (Time.now - @benchmarks[@current])
+      @current -= 1
+      elapsed
+    end
+
+    # Returns the elapsed time from the benchmark clock w/ the given index (as
+    # returned from when .start! was called).
+    def time?(index)
+      Time.now - @benchmarks[index]
+    end
+
+    # Benchmarks the given block, printing out the given message first (if
+    # given).
+    def timed(message=nil, &block)
+      start!
+      out(message) if message
+      yield
+      done!
+    end
+  end
+end    

data/lib/waveformjson/version.rb

@@ -0,0 +1,3 @@
+class Waveformjson
+  VERSION = "0.0.1"
+end

data/test/waveform_test.rb

@@ -0,0 +1,54 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "lib", "waveformjson"))
+
+require "test/unit"
+require "fileutils"
+
+module Helpers
+  def fixture(file)
+    File.join(File.dirname(__FILE__), "fixtures", file)
+  end  
+end
+
+class WaveformTest < Test::Unit::TestCase
+  include Helpers
+  extend Helpers
+
+  def test_generates_waveform
+    assert_equal Waveformjson::DefaultOptions[:width], Waveformjson.generate(fixture("sample.wav")).size
+  end
+
+  def test_generates_waveform_from_mono_audio_source_via_peak
+    assert_equal Waveformjson::DefaultOptions[:width], Waveformjson.generate(fixture("mono_sample.wav")).size
+  end
+
+  def test_generates_waveform_from_mono_audio_source_via_rms
+    assert_equal Waveformjson::DefaultOptions[:width], Waveformjson.generate(fixture("mono_sample.wav"), :method => :rms).size
+  end
+
+  def test_uses_rms_instead_of_peak
+    rms = Waveformjson.generate(fixture("sample.wav"))
+    peak = Waveformjson.generate(fixture("sample.wav"), :method => :rms)
+
+    assert peak[44] > rms[43]
+  end
+
+  def test_is_900px_wide
+    data = Waveformjson.generate(fixture("sample.wav"), :width => 900)
+    
+    assert_equal 900, data.size
+  end
+
+  def test_raises_error_if_not_given_readable_audio_source
+    assert_raise(RuntimeError) do
+      Waveformjson.generate(fixture("sample.txt"))
+    end
+  end
+
+  def test_raises_deprecation_exception_if_ruby_audio_fails_to_read_source_file
+    begin
+      Waveformjson.generate(fixture("sample.txt"))
+    rescue RuntimeError => e
+      assert_match /Hint: non-WAV files are no longer supported, convert to WAV first using something like ffmpeg/, e.message
+    end
+  end
+end

data/waveformjson.gemspec

@@ -0,0 +1,25 @@
+require "./lib/waveformjson/version"
+
+Gem::Specification.new do |s|
+  s.name              = "waveformjson"
+  s.version           = Waveformjson::VERSION
+  s.summary           = "Generate waveform json from audio files"
+  s.description       = "Generate waveform json from audio files. Includes a Waveform class for generating waveforms in your code as well as a simple command-line program called 'waveform' for generating on the command line."
+  s.authors           = ["liufengyun"]
+  s.email             = ["liufengyunchina@gmail.com"]
+  s.homepage          = "http://github.com/liufengyun/waveformjson"
+
+  s.files = Dir[
+    "LICENSE",
+    "README.md",
+    "Rakefile",
+    "lib/**/*.rb",
+    "*.gemspec",
+    "test/**/*.rb",
+    "bin/*"
+  ]
+
+  s.executables = "waveformjson"
+
+  s.add_dependency "ruby-audio"
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: waveformjson
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- liufengyun
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-audio
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Generate waveform json from audio files. Includes a Waveform class for
+  generating waveforms in your code as well as a simple command-line program called
+  'waveform' for generating on the command line.
+email:
+- liufengyunchina@gmail.com
+executables:
+- waveformjson
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/waveformjson/version.rb
+- lib/waveformjson.rb
+- waveformjson.gemspec
+- test/waveform_test.rb
+- bin/waveformjson
+homepage: http://github.com/liufengyun/waveformjson
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Generate waveform json from audio files
+test_files: []
+has_rdoc: