waveform 0.0.3 → 0.1.0

data/README.md

@@ -1,35 +1,27 @@
 Waveform
 ========
 
-Waveform is a class to generate waveform images from audio files. You can
-combine it with jPlayer to make a soundcloud.com style MP3 player. It also
-comes with a handy CLI you can use to generate waveform images on the command
-line.
+Waveform is a class to generate waveform images from audio files. You can combine it with jPlayer to make a soundcloud.com style MP3 player. It also comes with a handy CLI you can use to generate waveform images on the command line.
 
 Installation
 ============
 
-Build libsndfile (http://www.mega-nerd.com/libsndfile/), or install it via `apt`
-(`sudo apt-get install libsndfile1-dev`), or `libsndfile` in macports.
+Waveform depends on `ruby-audio`, which in turn depends on libsndfile.
 
-    $ sudo gem install waveform
+Build libsndfile from (http://www.mega-nerd.com/libsndfile/), install it via `apt` (`sudo apt-get install libsndfile1-dev`), `libsndfile` in macports, etc...
 
-You might also want to, but don't have to:
+Then:
 
-    $ sudo gem install oily_png
-    
-to make things a bit faster, and:
+    $ sudo gem install waveform
 
-    $ sudo apt-get install ffmpeg
-    
-if you want Waveform to convert non WAV audio for you.
+Image creation depends on `chunky_png`, which has a faster native library called `oily_png` which will be used if availble.
 
-_See Requirements below for more info_
+    $ sudo gem install oily_png
 
 CLI Usage
 =========
 
-    $ waveform song.mp3 waveform.png
+    $ waveform song.wav waveform.png
 
 There are some nifty options you can supply to switch things up:
 
@@ -53,51 +45,54 @@ Generating a small waveform "cut out" of a white background is pretty useful,
 then you can overlay it on a web-gradient on the website for your new startup
 and it will look really cool. To make it you could use:
 
-    $ waveform -W900 -H140 -ctransparent -b#ffffff Motley\ Crüe/Kickstart\ my\ Heart.mp3 sweet_waveforms/Kickstart\ my\ Heart.png
+    $ waveform -W900 -H140 -ctransparent -b#ffffff Motley\ Crüe/Kickstart\ my\ Heart.wav sweet_waveforms/Kickstart\ my\ Heart.png
 
 Usage in code
 =============
 
-The CLI is really just a thin wrapper around the Waveform 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.
+The CLI is really just a thin wrapper around the Waveform 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`.
+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`.
 
 `chunky_png`
 
-`chunky_png` is a pure ruby (!) PNG manipulation library. Caveat to this
-requirement is that if you also install `oily_png` you will get *better
-performance* as it uses some C code, and C code is fast.
+`chunky_png` is a pure ruby (!) PNG manipulation library. Caveat to this requirement is that if you also install `oily_png` you will get *better performance* as it uses some C code, and C code is fast.
 
-`ffmpeg` (sorta)
+Converting MP3 to WAV
+=====================
 
-You only need `ffmpeg` if you plan to generate waveforms from files that aren't
-already WAVs (like MP3, or M4A). On my same Ubuntu VM I installed it via `sudo
-apt-get install ffmpeg` and it was able to convert MP3 and M4A files out of the
-box. The formats you can convert depend on which decoders you have installed.
+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 don't want to install ffmpeg, you could also use one of the many audio
-format converters to convert your files to WAV before generating waveforms.
+If you happen to be using ffmpeg, you can easily convert MP3 to WAV via:
 
-Or you could be all retro and use WAV audio for everything in the first place.
+    ffmpeg -i "/path/to/source/file.mp3" -f wav "/path/to/output/file.wav"
 
 Tests
 =====
 
-Tests require `contest` gem & `ffmpeg` (to test conversion), run via:
+    $ rake
+    
+If you get an error about not being able to find ruby-audio gem (and you have ruby-audio gem) you might need to let rake know how to load your gems -- if you're using rubygems:
 
+    $ export RUBYOPT="rubygems"
     $ rake
 
-Sample sound file is in Public Domain from soundbible.com.
-<http://soundbible.com/1598-Electronic-Chime.html>
+Sample sound file used in tests is in the Public Domain from soundbible.com: <http://soundbible.com/1598-Electronic-Chime.html>.
+
+Changes
+=======
+
+0.1.0
+-----
+  * No more wrapping ffmpeg to automatically convert mp3 to wav
+  * Fixed support for mono audio sources (4-channel, surround, etc. should also work)
+  * Change to gemspec & added seperate version file so that bundler won't try to load ruby-audio (thanks, amiel)
+  * Changed Waveform-class API as there's no longer a need to instantiate a waveform
 
 References
 ==========
@@ -110,7 +105,7 @@ References
 License
 =======
 
-Copyright (c) 2010-2011 Ben Alavi
+Copyright (c) 2010-2012 Ben Alavi
 
 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

data/bin/waveform

@@ -5,7 +5,8 @@ require "optparse"
 options = Waveform::DefaultOptions
 optparse = OptionParser.new do |o|
   o.banner = "Usage: waveform [options] source_audio [ouput.png]"
-
+  o.version = Waveform::VERSION
+  
   o.on("-W", "--width WIDTH", "Width (in pixels) of generated waveform image -- Default #{Waveform::DefaultOptions[:width]}.") do |width|
     options[:width] = width.to_i
   end
@@ -34,9 +35,9 @@ optparse = OptionParser.new do |o|
     options[:method] = method.to_sym
   end
 
-  options[:quiet] = false
+  options[:logger] = $stdout
   o.on("-q", "--quiet", "Don't print anything out when generating waveform") do
-    options[:quiet] = true
+    options[:logger] = nil
   end
 
   options[:force] = false
@@ -53,11 +54,10 @@ end
 optparse.parse!
 
 begin
-  Waveform.new(ARGV[0], options[:quiet] ? nil : $stdout).generate(ARGV[1] || "waveform.png", options)
+  Waveform.generate(ARGV[0], ARGV[1] || "waveform.png", options)
 rescue Waveform::ArgumentError => e
   puts e.message + "\n\n"
   puts optparse
 rescue Waveform::RuntimeError => e
   puts e.message
 end
-

data/lib/waveform.rb

@@ -1,6 +1,6 @@
-require "ruby-audio"
-require "tempfile"
+require File.join(File.dirname(__FILE__), "waveform/version")
 
+require "ruby-audio"
 begin
   require "oily_png"
 rescue LoadError
@@ -8,15 +8,14 @@ rescue LoadError
 end
 
 class Waveform
-  VERSION = "0.0.3"
-  
   DefaultOptions = {
     :method => :peak,
     :width => 1800,
     :height => 280,
     :background_color => "#666666",
     :color => "#00ccff",
-    :force => false
+    :force => false,
+    :logger => nil
   }
   
   TransparencyMask = "#00ff00"
@@ -29,111 +28,115 @@ class Waveform
   class RuntimeError < ::RuntimeError;end;
   class ArgumentError < ::ArgumentError;end;
   
-  # Setup a new Waveform for the given audio file. If given anything besides a
-  # WAV file it will attempt to first convert the file to a WAV using ffmpeg.
-  # 
-  # Optionally takes an IO stream to which it will print log/benchmarking info.
-  # 
-  # See #generate for how to generate the waveform image from the given audio
-  # file.
-  # 
-  # Available conversions depend on your installation of ffmpeg.
-  # 
-  # Example:
-  # 
-  #   Waveform.new("mp3s/Kickstart My Heart.mp3")
-  #   Waveform.new("mp3s/Kickstart My Heart.mp3", $stdout)
-  # 
-  def initialize(source, log=nil)
-    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(log)
-    @log.start!
-    
-    # @source is the path to the given source file, whatever it may be
-    @source = source
-    
-    # @audio is the path to the actual audio file we will process, always wav
-    if File.extname(source) == ".wav"
-      @audio = File.open(source, "rb")
-    else
-      # This happens in initialize so you can generate multiple waveforms from
-      # the same audio without decoding multiple times
-      # 
-      # Note that we're leaving it up to the ruby/system GC to clean up these
-      # tempfiles because someone may be generating multiple waveform images
-      # from a single audio source so we can't explicitly unlink the tempfile.
-      @audio = to_wav(source)
-    end
-    
-    raise RuntimeError.new("Unable to decode source \'#{@source}\' to WAV. Do you have ffmpeg installed with an appropriate decoder for your source file?") unless @audio
-  end
-  
-  # Generate a Waveform image at the given filename with the given options.
-  # 
-  # Available options 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.
-  # 
-  #   :height => The height (in pixels) of the final waveform image.
-  #     Default is 280.
-  # 
-  #   :background_color => Hex code of the background color of the generated
-  #     waveform image.
-  #     Default is #666666 (gray).
-  #
-  #   :color => Hex code of the color to draw the waveform, or can pass
-  #     :transparent to render the waveform transparent (use w/ a solid
-  #     color background to achieve a "cutout" effect).
-  #     Default is #00ccff (cyan-ish).
-  #
-  #   :force => Force generation of waveform, overwriting WAV or PNG file.
-  #
-  # Example:
-  #   waveform = Waveform.new("mp3s/Kickstart My Heart.mp3")
-  #
-  #   waveform.generate("waves/Kickstart My Heart.png")
-  #   waveform.generate("waves/Kickstart My Heart.png", :method => :rms)
-  #   waveform.generate("waves/Kickstart My Heart.png", :color => "#ff00ff")
-  #
-  def generate(filename, options={})
-    raise ArgumentError.new("No destination filename given for waveform") unless filename
+  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.
+    # 
+    #   :height => The height (in pixels) of the final waveform image.
+    #     Default is 280.
+    # 
+    #   :background_color => Hex code of the background color of the generated
+    #     waveform image.
+    #     Default is #666666 (gray).
+    #
+    #   :color => Hex code of the color to draw the waveform, or can pass
+    #     :transparent to render the waveform transparent (use w/ a solid
+    #     color background to achieve a "cutout" effect).
+    #     Default is #00ccff (cyan-ish).
+    #
+    #   :force => Force generation of waveform, overwriting WAV or PNG file.
+    # 
+    #   :logger => IOStream to log progress to.
+    #
+    # Example:
+    #   Waveform.generate("Kickstart My Heart.wav", "Kickstart My Heart.png")
+    #   Waveform.generate("Kickstart My Heart.wav", "Kickstart My Heart.png", :method => :rms)
+    #   Waveform.generate("Kickstart My Heart.wav", "Kickstart My Heart.png", :color => "#ff00ff", :logger => $stdout)
+    #
+    def generate(source, filename, options={})
+      options = DefaultOptions.merge(options)
+      
+      raise ArgumentError.new("No source audio filename given, must be an existing sound file.") unless source
+      raise ArgumentError.new("No destination filename given for waveform") unless filename
+      raise RuntimeError.new("Source audio file '#{source}' not found.") unless File.exist?(source)
+      raise RuntimeError.new("Destination file #{filename} exists. Use --force if you want to automatically remove it.") if File.exists?(filename) && !options[:force] === true
 
-    if File.exists?(filename)
-      if options[:force]
-        @log.out("Output file #{filename} encountered. Removing.")
-        File.unlink(filename)
-      else
-        raise RuntimeError.new("Destination file #{filename} exists. Use --force if you want to automatically remove it.")
+      @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
-    end    
+      
+      @log.timed("\nDrawing...") do
+        # Don't remove the file even if force is true until we're sure the
+        # source was readable
+        if File.exists?(filename) && options[:force] === true
+          @log.out("Output file #{filename} encountered. Removing.")
+          File.unlink(filename)
+        end
+        
+        image = draw samples, options
+        image.save filename
+      end
+      
+      @log.done!("Generated waveform '#{filename}'")      
+    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 = []
 
-    options = DefaultOptions.merge(options)
+      RubyAudio::Sound.open(source) do |audio|
+        frames_read = 0
+        frames_per_sample = (audio.info.frames.to_f / width.to_f).to_i
+        sample = RubyAudio::Buffer.new("float", frames_per_sample, audio.info.channels)
 
-    # 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(options[:width], options[:method]).collect do |frame|
-      frame.inject(0.0) { |sum, peak| sum + peak } / frame.size
+        @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 Waveform::RuntimeError.new("Source audio file #{source} could not be read by RubyAudio library -- try converting to WAV first (RubyAudio: #{e.message})")
     end
     
-    @log.timed("\nDrawing...") do
-      background_color = options[:background_color] == :transparent ? ChunkyPNG::Color::TRANSPARENT : options[:background_color]
+    # Draws the given samples using the given options, returns a ChunkyPNG::Image.
+    def draw(samples, options)      
+      image = ChunkyPNG::Image.new(options[:width], options[:height],
+        options[:background_color] == :transparent ? ChunkyPNG::Color::TRANSPARENT : options[:background_color]
+      )
       
       if options[:color] == :transparent
         color = transparent = ChunkyPNG::Color.from_hex(
@@ -146,11 +149,10 @@ class Waveform
         color = ChunkyPNG::Color.from_hex(options[:color])
       end
 
-      image = ChunkyPNG::Image.new(options[:width], options[:height], background_color)
       # Calling "zero" the middle of the waveform, like there's positive and
       # negative amplitude
       zero = options[:height] / 2.0
-      
+    
       samples.each_with_index do |sample, x|
         # Half the amplitude goes above zero, half below
         amplitude = sample * options[:height].to_f / 2.0
@@ -169,96 +171,56 @@ class Waveform
         end
       end
       
-      image.save(filename)
+      image
     end
-
-    @log.done!("Generated waveform '#{filename}'")
-  end
   
-  # Returns a sampling of frames from the given wave file using the given method
-  # the sample size is determined by the given pixel width -- we want one sample
-  # frame per horizontal pixel.
-  def frames(width, method = :peak)
-    raise ArgumentError.new("Unknown sampling method #{method}") unless [ :peak, :rms ].include?(method)
-    
-    frames = []
-    
-    RubyAudio::Sound.open(@audio.path) do |snd|
-      frames_read       = 0
-      frames_per_sample = (snd.info.frames.to_f / width.to_f).to_i
-      sample            = RubyAudio::Buffer.new("float", frames_per_sample, snd.info.channels)
-
-      @log.timed("Sampling #{frames_per_sample} frames per sample: ") do
-        while(frames_read = snd.read(sample)) > 0
-          frames << send(method, sample, snd.info.channels)
-          @log.out(".")
-        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
-  
-    frames
-  end
-  
-  private
-  
-  # Decode given src file to a wav Tempfile. Returns the Tempfile if the decode
-  # succeeded, or false if the decode failed.
-  def to_wav(src, force=false)
-    wav = nil
-    
-    @log.timed("Decoding source audio '#{src}' to WAV...") do    
-      wav = Tempfile.new(File.basename(src))
-      system %Q{ffmpeg -y -i "#{src}" -f wav "#{wav.path}" > /dev/null 2>&1}
-    end
-    
-    return wav.size == 0 ? false : wav
-  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)
+    # 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
-    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?
-      peak = frame[channel].abs if frame[channel].abs > peak
+    # 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
-    peak
-  end
 
-  # Returns the rms value across the given collection of frames for the given
-  # channel.
-  # 
-  # FIXME: this RMS calculation might be wrong...
-  # refactored this from: http://pscode.org/javadoc/src-html/org/pscode/ui/audiotrace/AudioPlotPanel.html#line.996
-  def channel_rms(frames, channel=0)
-    avg = frames.inject(0.0){ |sum, frame| sum += frame ? frame[channel] : 0 }/frames.size.to_f
-    Math.sqrt(frames.inject(0.0){ |sum, frame| sum += frame ? (frame[channel]-avg)**2 : 0 }/frames.size.to_f)
+    # Returns the rms value across the given collection of frames for the given
+    # channel.
+    # 
+    # FIXME: this RMS calculation might be wrong...
+    # refactored this from: http://pscode.org/javadoc/src-html/org/pscode/ui/audiotrace/AudioPlotPanel.html#line.996
+    def channel_rms(frames, channel=0)
+      avg = frames.inject(0.0){ |sum, frame| sum += frame ? Array(frame)[channel] : 0 }/frames.size.to_f
+      Math.sqrt(frames.inject(0.0){ |sum, frame| sum += frame ? (Array(frame)[channel]-avg)**2 : 0 }/frames.size.to_f)
+    end
   end
 end
 
@@ -270,11 +232,11 @@ class Waveform
   # 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
@@ -311,7 +273,7 @@ class Waveform
     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)
@@ -321,4 +283,4 @@ class Waveform
       done!
     end
   end
-end
+end    

data/lib/waveform/version.rb

@@ -0,0 +1,3 @@
+class Waveform
+  VERSION = "0.1.0"
+end

data/test/waveform_test.rb

@@ -1,174 +1,168 @@
-require "contest"
-require "fileutils"
 require File.expand_path(File.join(File.dirname(__FILE__), "..", "lib", "waveform"))
 
-class WaveformTest < Test::Unit::TestCase
-  def self.fixture(file)
+require "test/unit"
+require "ruby-debug"
+require "fileutils"
+
+module Helpers
+  def fixture(file)
     File.join(File.dirname(__FILE__), "fixtures", file)
   end
-  def fixture(file);self.class.fixture(file);end;
   
-  def self.output(file)
+  def output(file)
     File.join(File.dirname(__FILE__), "output", file)
   end
-  def output(file);self.class.output(file);end;
   
   def open_png(file)
     ChunkyPNG::Image.from_datastream(ChunkyPNG::Datastream.from_file(file))
   end
+end
+
+class WaveformTest < Test::Unit::TestCase
+  include Helpers
+  extend Helpers
+
+  def self.cleanup
+    puts "Removing existing testing artifacts..."
+    Dir[output("*.*")].each{ |f| FileUtils.rm(f) }
+    FileUtils.mkdir_p(output(""))
+  end
   
-  puts "Removing existing testing artifacts..."
-  FileUtils.rm_rf(output("")) if File.exists?(output(""))
-  FileUtils.mkdir(output(""))
-  sample_wav = fixture("sample_mp3.wav")
-  FileUtils.rm(sample_wav) if File.exists?(sample_wav)
-  
-  context "generating waveform" do
-    setup do
-      @waveform = Waveform.new(fixture("sample.wav"))
-    end
-    
-    should "generate waveform from audio source" do
-      @waveform.generate(output("waveform_from_audio_source.png"))
-      assert File.exists?(output("waveform_from_audio_source.png"))
+  def test_generates_waveform
+    Waveform.generate(fixture("sample.wav"), output("waveform_from_audio_source.png"))
+    assert File.exists?(output("waveform_from_audio_source.png"))
       
-      image = open_png(output("waveform_from_audio_source.png"))
-      assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), image[60, 120]
-      assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:background_color]), image[0, 0]
-    end
+    image = open_png(output("waveform_from_audio_source.png"))
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), image[60, 120]
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:background_color]), image[0, 0]
+  end
     
-    should "convert non-wav audio source before generation" do
-      Waveform.new(fixture("sample_mp3.mp3")).generate(output("from_mp3.png"))
+  def test_generates_waveform_from_mono_audio_source_via_peak
+    Waveform.generate(fixture("mono_sample.wav"), output("waveform_from_mono_audio_source_via_peak.png"))
+    assert File.exists?(output("waveform_from_mono_audio_source_via_peak.png"))
 
-      assert File.exists?(output("from_mp3.png"))
-    end
+    image = open_png(output("waveform_from_mono_audio_source_via_peak.png"))
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), image[60, 120]
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:background_color]), image[0, 0]
+  end
 
-    should "log to given io" do
-      File.open(output("waveform.log"), "w") do |io|
-        Waveform.new(fixture("sample.wav"), io).generate(output("logged.png"))
-      end
-      
-      assert_match /Generated waveform/, File.read(output("waveform.log"))
-    end
-            
-    should "generate waveform using rms method instead of peak" do
-      @waveform.generate(output("peak.png"))
-      @waveform.generate(output("rms.png"), :method => :rms)
-      rms = open_png(output("rms.png"))
-      peak = open_png(output("peak.png"))
-      
-      assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), peak[44, 43]
-      assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:background_color]), rms[44, 43]
-      assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), rms[60, 120]
+  def test_generates_waveform_from_mono_audio_source_via_rms
+    Waveform.generate(fixture("mono_sample.wav"), output("waveform_from_mono_audio_source_via_rms.png"), :method => :rms)
+    assert File.exists?(output("waveform_from_mono_audio_source_via_rms.png"))
+
+    image = open_png(output("waveform_from_mono_audio_source_via_rms.png"))
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), image[60, 120]
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:background_color]), image[0, 0]
+  end
+        
+  def test_logs_to_given_io
+    File.open(output("waveform.log"), "w") do |io|
+      Waveform.generate(fixture("sample.wav"), output("logged.png"), :logger => io)
     end
     
-    should "generate waveform 900px wide" do
-      @waveform.generate(output("width-900.png"), :width => 900)
-      image = open_png(output("width-900.png"))
-      
-      assert_equal 900, image.width
-    end
+    assert_match /Generated waveform/, File.read(output("waveform.log"))
+  end
+  
+  def test_uses_rms_instead_of_peak
+    Waveform.generate(fixture("sample.wav"), output("peak.png"))
+    Waveform.generate(fixture("sample.wav"), output("rms.png"), :method => :rms)
+
+    rms = open_png(output("rms.png"))
+    peak = open_png(output("peak.png"))
     
-    should "generate waveform 100px tall" do
-      @waveform.generate(output("height-100.png"), :height => 100)
-      image = open_png(output("height-100.png"))
-      
-      assert_equal 100, image.height
-    end
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), peak[44, 43]
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:background_color]), rms[44, 43]
+    assert_equal ChunkyPNG::Color.from_hex(Waveform::DefaultOptions[:color]), rms[60, 120]
+  end
+  
+  def test_is_900px_wide
+    Waveform.generate(fixture("sample.wav"), output("width-900.png"), :width => 900)
     
-    should "generate waveform on red background color" do
-      @waveform.generate(output("background_color-#ff0000.png"), :background_color => "#ff0000")
-      image = open_png(output("background_color-#ff0000.png"))
-      
-      assert_equal ChunkyPNG::Color.from_hex("#ff0000"), image[0, 0]
-    end
+    image = open_png(output("width-900.png"))
     
-    should "generate waveform on transparent background color" do
-      @waveform.generate(output("background_color-transparent.png"), :background_color => :transparent)
-      image = open_png(output("background_color-transparent.png"))
-      
-      assert_equal ChunkyPNG::Color::TRANSPARENT, image[0, 0]
-    end
+    assert_equal 900, image.width
+  end
+  
+  def test_is_100px_tall
+    Waveform.generate(fixture("sample.wav"), output("height-100.png"), :height => 100)
     
-    should "generate waveform in black foreground color" do
-      @waveform.generate(output("color-#000000.png"), :color => "#000000")
-      image = open_png(output("color-#000000.png"))
-      
-      assert_equal ChunkyPNG::Color.from_hex("#000000"), image[60, 120]
-    end
+    image = open_png(output("height-100.png"))
     
-    should "generate waveform on red background color with transparent foreground cut-out" do
-      @waveform.generate(output("background_color-#ff0000+color-transparent.png"), :background_color => "#ff0000", :color => :transparent)
-      image = open_png(output("background_color-#ff0000+color-transparent.png"))
-      
-      assert_equal ChunkyPNG::Color.from_hex("#ff0000"), image[0, 0]
-      assert_equal ChunkyPNG::Color::TRANSPARENT, image[60, 120]
-    end
+    assert_equal 100, image.height
+  end
+  
+  def test_has_red_background_color
+    Waveform.generate(fixture("sample.wav"), output("background_color-#ff0000.png"), :background_color => "#ff0000")
     
-    # Bright green is our transparency mask color, so this test ensures that we
-    # don't destroy the image if the background also uses the transparency mask
-    # color
-    should "generate waveform with transparent foreground on bright green background" do
-      @waveform.generate(output("background_color-#00ff00+color-transparent.png"), :background_color => "#00ff00", :color => :transparent)
-      image = open_png(output("background_color-#00ff00+color-transparent.png"))
-      
-      assert_equal ChunkyPNG::Color.from_hex("#00ff00"), image[0, 0]
-      assert_equal ChunkyPNG::Color::TRANSPARENT, image[60, 120]
-    end
-
-    # Not sure how to best test this as it's totally dependent on the ruby and
-    # system GC when the tempfiles are removed (as we're not explicitly
-    # unlinking them).
-    # should "use a tempfile when generating a temporary wav" do
-    #   tempfiles = Dir[File.join(Dir.tmpdir(), "sample_mp3*")].size
-    #   Waveform.new(fixture("sample_mp3.mp3")).generate(output("cleanup_temporary_wav.png"))
-    #   assert_equal tempfiles + 1, Dir[File.join(Dir.tmpdir(), "sample_mp3*")].size
-    # end
-    
-    should "not delete source wav file if one was given" do
-      assert File.exists?(fixture("sample.wav"))
-      Waveform.new(fixture("sample.wav")).generate(output("keep_source_wav.png"))
-      assert File.exists?(fixture("sample.wav"))
-    end
+    image = open_png(output("background_color-#ff0000.png"))
     
-    should "raise an error if unable to decode to wav" do
-      assert_raise(Waveform::RuntimeError) do
-        Waveform.new(fixture("sample.txt")).generate(output("shouldnt_exist.png"))
-      end
-    end
-
-    context "with existing PNG files" do
-      setup do
-        @existing = output("existing.png")
-        FileUtils.touch @existing
-      end
-
-      should "generate waveform if :force is true and PNG exists" do
-        @waveform.generate(@existing, :force => true)
-      end
-
-      should "raise an exception if PNG exists and :force is false" do
-        assert_raises Waveform::RuntimeError do
-          @waveform.generate(@existing, :force => false)
-        end
-      end
+    assert_equal ChunkyPNG::Color.from_hex("#ff0000"), image[0, 0]
+  end
+  
+  def test_has_transparent_background_color
+    Waveform.generate(fixture("sample.wav"), output("background_color-transparent.png"), :background_color => :transparent)
+    
+    image = open_png(output("background_color-transparent.png"))
+    
+    assert_equal ChunkyPNG::Color::TRANSPARENT, image[0, 0]
+  end
+  
+  def test_has_black_foreground_color
+    Waveform.generate(fixture("sample.wav"), output("color-#000000.png"), :color => "#000000")
+    
+    image = open_png(output("color-#000000.png"))
+    
+    assert_equal ChunkyPNG::Color.from_hex("#000000"), image[60, 120]
+  end
+  
+  def test_has_red_background_color_with_transparent_foreground_cutout
+    Waveform.generate(fixture("sample.wav"), output("background_color-#ff0000+color-transparent.png"), :background_color => "#ff0000", :color => :transparent)
+    
+    image = open_png(output("background_color-#ff0000+color-transparent.png"))
+    
+    assert_equal ChunkyPNG::Color.from_hex("#ff0000"), image[0, 0]
+    assert_equal ChunkyPNG::Color::TRANSPARENT, image[60, 120]
+  end
+  
+  # Bright green is our transparency mask color, so this test ensures that we
+  # don't destroy the image if the background also uses the transparency mask
+  # color
+  def test_has_transparent_foreground_on_bright_green_background
+    Waveform.generate(fixture("sample.wav"), output("background_color-#00ff00+color-transparent.png"), :background_color => "#00ff00", :color => :transparent)
+    
+    image = open_png(output("background_color-#00ff00+color-transparent.png"))
+    
+    assert_equal ChunkyPNG::Color.from_hex("#00ff00"), image[0, 0]
+    assert_equal ChunkyPNG::Color::TRANSPARENT, image[60, 120]
+  end
+  
+  def test_raises_error_if_not_given_readable_audio_source
+    assert_raise(Waveform::RuntimeError) do
+      Waveform.generate(fixture("sample.txt"), output("shouldnt_exist.png"))
     end
+  end
+  
+  def test_overwrites_existing_waveform_if_force_is_true_and_file_exists
+    FileUtils.touch output("overwritten.png")
 
-    context "with existing WAV files" do
-      setup do
-        @existing = output("existing.wav")
-        FileUtils.touch @existing
-      end
-
-      should "generate waveform if :force is true and WAV exists" do
-        @waveform.generate(@existing, :force => true)
-      end
+    Waveform.generate(fixture("sample.wav"), output("overwritten.png"), :force => true)
+  end
 
-      should "raise an exception if WAV exists and :force is false" do
-        assert_raises Waveform::RuntimeError do
-          @waveform.generate(@existing, :force => false)
-        end
-      end
+  def test_raises_exception_if_waveform_exists_and_force_is_false
+    FileUtils.touch output("wont_be_overwritten.png")
+    
+    assert_raises Waveform::RuntimeError do
+      Waveform.generate(fixture("sample.wav"), output("wont_be_overwritten.png"), :force => false)
     end
   end
+  
+  def test_raises_exception_if_waveform_exists
+    FileUtils.touch output("wont_be_overwritten_by_default.png")
+    
+    assert_raises Waveform::RuntimeError do
+      Waveform.generate(fixture("sample.wav"), output("wont_be_overwritten_by_default.png"))
+    end
+  end  
 end
+
+WaveformTest.cleanup

data/waveform.gemspec

@@ -1,10 +1,10 @@
-require "./lib/waveform"
+require "./lib/waveform/version"
 
 Gem::Specification.new do |s|
   s.name              = "waveform"
   s.version           = Waveform::VERSION
-  s.summary           = "Generate waveform images from WAV, MP3, etc... files"
-  s.description       = "Generate waveform images from WAV, MP3, etc... files - as a gem or via CLI."
+  s.summary           = "Generate waveform images from audio files"
+  s.description       = "Generate waveform images 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           = ["Ben Alavi"]
   s.email             = ["benalavi@gmail.com"]
   s.homepage          = "http://github.com/benalavi/waveform"
@@ -23,6 +23,4 @@ Gem::Specification.new do |s|
 
   s.add_dependency "ruby-audio"
   s.add_dependency "chunky_png"
-  
-  s.add_development_dependency "contest"
 end

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: waveform
 version: !ruby/object:Gem::Version 
+  hash: 27
   prerelease: 
-  version: 0.0.3
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Ben Alavi
@@ -10,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-28 00:00:00 Z
+date: 2012-09-27 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: ruby-audio
@@ -20,6 +25,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id001
@@ -31,21 +39,13 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: contest
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-  type: :development
-  version_requirements: *id003
-description: Generate waveform images from WAV, MP3, etc... files - as a gem or via CLI.
+description: Generate waveform images 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: 
 - benalavi@gmail.com
 executables: 
@@ -57,6 +57,7 @@ extra_rdoc_files: []
 files: 
 - README.md
 - Rakefile
+- lib/waveform/version.rb
 - lib/waveform.rb
 - waveform.gemspec
 - test/waveform_test.rb
@@ -74,19 +75,25 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.6
+rubygems_version: 1.8.5
 signing_key: 
 specification_version: 3
-summary: Generate waveform images from WAV, MP3, etc... files
+summary: Generate waveform images from audio files
 test_files: []