beats 1.2.4 → 1.2.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4f2f7351421971cb29e95868abde34acaa5ab6b2
+  data.tar.gz: ba692d9e94e5cac568eff994493a45b4739ee2ac
+SHA512:
+  metadata.gz: 23dd31bfc7e19dcf52dcc573e054f36b46f93b4cd5d5aaa9e9077d9a9227082ddf42b4781f9564af1ab54fd70de1758116e8cf94c6189ca1bbf3f7426628b8dc
+  data.tar.gz: 19d77737f3a74672d0d73267ba673ecebf99c46c8af487d75762ee8956aab9e034d888d39707e1d6ef10cb6bdb3fd42f499b838b6e032290db664a2476ec5a68

data/LICENSE

@@ -1,6 +1,6 @@
 == BEATS
 
-# Copyright (c) 2010-12 Joel Strait
+# Copyright (c) 2010-13 Joel Strait
 #
 # Permission is hereby granted, free of charge, to any person
 # obtaining a copy of this software and associated documentation

data/README.markdown

@@ -33,16 +33,19 @@ And [here's what it sounds like](http://beatsdrummachine.com/media/beat.mp3) aft
 Current Status
 --------------
 
-The latest stable version of Beats is 1.2.4, released on December 22, 2012. This is a minor release which includes two improvements:
+The latest stable version of Beats is 1.2.5, released on December 31, 2013. This release includes these improvements: 
 
-* Now works in MRI 1.9.3
-* Now supports 32-bit PCM Wave files, due to upgrading to WaveFile 0.4.0. Previously, only 8-bit and 16-bit PCM files were supported.
+* Tracks that start with a `|` no longer cause an error in Ruby 2.0.0 and 2.1.0.
+* Additional Wave file formats can now be used as samples, due to upgrading to [WaveFile 0.6.0](http://wavefilegem.com) behind the scenes:
+  * 24-bit PCM
+  * 32-bit IEEE Float
+  * 64-bit IEEE Float
 
 
 Installation
 ------------
 
-To install the latest stable version (1.2.4) from [rubygems.org](http://rubygems.org/gems/beats), run the following from the command line:
+To install the latest stable version (1.2.5) from [rubygems.org](http://rubygems.org/gems/beats), run the following from the command line:
 
     gem install beats
 
@@ -61,6 +64,23 @@ Beats runs from the command-line. Run `beats -h` to see the available options. F
 The Beats wiki also has a [Getting Started](https://github.com/jstrait/beats/wiki/Getting-Started) tutorial which shows how to create an example beat from scratch.
 
 
+Local Development
+-----------------
+
+First, install the required dependencies:
+
+    bundle install
+
+To run Beats locally, use `bundle exec` and run `bin/beats`, to avoid using any installed gem executable. For example:
+
+    bundle exec bin/beats -v
+
+To run the tests:
+
+    bundle exec rake test
+
+
+
 Found a Bug? Have a Suggestion? Want to Contribute?
 ---------------------------------------------------
 

data/Rakefile

@@ -1,5 +1,5 @@
 require 'rake/testtask'
- 
+
 Rake::TestTask.new do |t|
   t.libs << 'lib' << 'test'
   t.pattern = 'test/**/*_test.rb'

data/bin/beats

@@ -2,20 +2,15 @@
 
 start_time = Time.now
 
-$:.unshift File.dirname(__FILE__) + "/.."
+$:.unshift File.dirname(__FILE__) + "/../lib"
 require "optparse"
 require "yaml"
+require "syck"
 require "wavefile"
-require "lib/audioengine"
-require "lib/audioutils"
-require "lib/beats"
-require "lib/wavefile/cachingwriter"
-require "lib/kit"
-require "lib/pattern"
-require "lib/song"
-require "lib/songoptimizer"
-require "lib/songparser"
-require "lib/track"
+require "beats"
+require "wavefile/cachingwriter"
+
+include Beats
 
 USAGE_INSTRUCTIONS = ""
 YAML::ENGINE.yamler = 'syck' if defined?(YAML::ENGINE)
@@ -39,7 +34,7 @@ def parse_options()
     end
 
     opts.on('-v', '--version', "Display version number and exit") do
-      puts "BEATS v#{Beats::BEATS_VERSION}"
+      puts "Beats Drum Machine #{Beats::VERSION}"
       exit
     end
 
@@ -69,7 +64,7 @@ def print_error(error, input_file_name)
     puts "An error occured while generating sound for '#{input_file_name}':\n"
     puts "  #{error}\n"
   else
-    puts "An unexpected error occured while running BEATS:"
+    puts "An unexpected error occured while running Beats Drum Machine:"
     puts "  #{error}\n"
   end
 end
@@ -79,11 +74,11 @@ begin
   input_file_name = ARGV[0]
   output_file_name = ARGV[1]
 
-  beats = Beats.new(input_file_name, output_file_name, options)
+  beats = BeatsRunner.new(input_file_name, output_file_name, options)
 
   output = beats.run()
   duration = output[:duration]
-  puts "#{duration[:minutes]}:#{duration[:seconds].to_s.rjust(2, '0')} of audio written in #{Time.now - start_time} seconds."
+  puts "#{duration.minutes}:#{duration.seconds.to_s.rjust(2, '0')} of audio written in #{Time.now - start_time} seconds."
 rescue => error
   print_error(error, input_file_name)
   exit(false)

data/ext/mkrf_conf.rb

@@ -0,0 +1,28 @@
+# Based on: http://www.programmersparadox.com/2012/05/21/gemspec-loading-dependent-gems-based-on-the-users-system/
+
+# This file needs to be named mkrf_conf.rb
+# so that rubygems will recognize it as a ruby extension
+# file and not think it is a C extension file
+
+require 'rubygems/dependency_installer.rb'
+
+# Load up the rubygem's dependency installer to 
+# installer the gems we want based on the version
+# of Ruby the user has installed
+installer = Gem::DependencyInstaller.new
+begin
+  if RUBY_VERSION >= "2"
+    installer.install "syck"
+  end
+
+  rescue
+    # Exit with a non-zero value to let rubygems something went wrong
+    exit(1)
+end  
+
+# If this was C, rubygems would attempt to run make
+# Since this is Ruby, rubygems will attempt to run rake
+# If it doesn't find and successfully run a rakefile, it errors out
+f = File.open(File.join(File.dirname(__FILE__), "Rakefile"), "w")
+f.write("task :default\n")
+f.close

data/lib/beats.rb

@@ -1,77 +1,13 @@
-class Beats
-  BEATS_VERSION = "1.2.4"
- 
-  # Each pattern in the song will be split up into sub patterns that have at most this many steps.
-  # In general, audio for several shorter patterns can be generated more quickly than for one long
-  # pattern, and can also be cached more effectively.
-  OPTIMIZED_PATTERN_LENGTH = 4
-
-  def initialize(input_file_name, output_file_name, options)
-    @input_file_name =  input_file_name
-
-    if output_file_name == nil
-      output_file_name = File.basename(input_file_name, File.extname(input_file_name)) + ".wav"
-    end
-    @output_file_name = output_file_name
-    
-    @options = options
-  end
-
-  def run
-    base_path = @options[:base_path] || File.dirname(@input_file_name)
-    song, kit = SongParser.new().parse(base_path, File.read(@input_file_name))
-
-    song = normalize_for_pattern_option(song)
-    songs_to_generate = normalize_for_split_option(song)
-
-    duration = nil
-    song_optimizer = SongOptimizer.new()
-    songs_to_generate.each do |output_file_name, song|
-      song = song_optimizer.optimize(song, OPTIMIZED_PATTERN_LENGTH)
-      duration = AudioEngine.new(song, kit).write_to_file(output_file_name)
-    end
-
-    return {:duration => duration}
-  end
-
-private
-
-  # If the -p option is used, transform the song into one whose flow consists of
-  # playing that single pattern once.
-  def normalize_for_pattern_option(song)
-    unless @options[:pattern] == nil
-      pattern_name = @options[:pattern].downcase.to_sym
-
-      unless song.patterns.has_key?(pattern_name)
-        raise StandardError, "The song does not include a pattern called #{pattern_name}"
-      end
-
-      song.flow = [pattern_name]
-      song.remove_unused_patterns()
-    end
-
-    return song
-  end
-
-  # Returns a hash of file name => song object for each song that should go through the audio engine
-  def normalize_for_split_option(song)
-    songs_to_generate = {}
-
-    if @options[:split]
-      split_songs = song.split()
-      split_songs.each do |track_name, split_song|
-        # TODO: Move building the output file name into its own method?
-        extension = File.extname(@output_file_name)
-        file_name = File.dirname(@output_file_name) + "/" +
-                    File.basename(@output_file_name, extension) + "-" + File.basename(track_name, extension) +
-                    extension
-
-        songs_to_generate[file_name] = split_song
-      end
-    else
-      songs_to_generate[@output_file_name] = song
-    end
-
-    return songs_to_generate
-  end
+require 'beats/audioengine'
+require 'beats/audioutils'
+require 'beats/beatsrunner'
+require 'beats/kit'
+require 'beats/pattern'
+require 'beats/song'
+require 'beats/songparser'
+require 'beats/songoptimizer'
+require 'beats/track'
+
+module Beats
+  VERSION = "1.2.5"
 end

data/lib/beats/audioengine.rb

@@ -0,0 +1,163 @@
+module Beats
+  # This class actually generates the output audio data that is saved to disk.
+  #
+  # To produce audio data, it needs two things: a Song and a Kit. The Song tells
+  # it which sounds to trigger and when, while the Kit provides the sample data
+  # for each of these sounds.
+  #
+  # Example usage, assuming song and kit are already defined:
+  #
+  #   engine = AudioEngine.new(song, kit)
+  #   engine.write_to_file("my_song.wav")
+  #
+  class AudioEngine
+    SAMPLE_RATE = 44100
+    PACK_CODE = "s*"   # All output sample data is assumed to be 16-bit
+
+    def initialize(song, kit)
+      @song = song
+      @kit = kit
+
+      @step_sample_length = AudioUtils.step_sample_length(SAMPLE_RATE, @song.tempo)
+      @composited_pattern_cache = {}
+    end
+
+    def write_to_file(output_file_name)
+      packed_pattern_cache = {}
+      num_tracks_in_song = @song.total_tracks
+
+      # Open output wave file and prepare it for writing sample data.
+      format = WaveFile::Format.new(@kit.num_channels, @kit.bits_per_sample, SAMPLE_RATE)
+      writer = WaveFile::CachingWriter.new(output_file_name, format)
+
+      # Generate each pattern's sample data, or pull it from cache, and append it to the wave file.
+      incoming_overflow = {}
+      @song.flow.each do |pattern_name|
+        key = [pattern_name, incoming_overflow.hash]
+        unless packed_pattern_cache.member?(key)
+          sample_data = generate_pattern_sample_data(@song.patterns[pattern_name], incoming_overflow)
+
+          packed_pattern_cache[key] = { :primary => WaveFile::Buffer.new(sample_data[:primary], format),
+                                        :overflow => WaveFile::Buffer.new(sample_data[:overflow], format) }
+        end
+
+        writer.write(packed_pattern_cache[key][:primary])
+        incoming_overflow = packed_pattern_cache[key][:overflow].samples
+      end
+
+      # Write any remaining overflow from the final pattern
+      final_overflow_composite = AudioUtils.composite(incoming_overflow.values, format.channels)
+      final_overflow_composite = AudioUtils.scale(final_overflow_composite, format.channels, num_tracks_in_song)
+      writer.write(WaveFile::Buffer.new(final_overflow_composite, format))
+
+      writer.close()
+
+      writer.total_duration
+    end
+
+    attr_reader :step_sample_length
+
+  private
+
+    # Generates the sample data for a single track, using the specified sound's sample data.
+    def generate_track_sample_data(track, sound)
+      beats = track.beats
+      if beats == [0]
+        return {:primary => [], :overflow => []}    # Is this really what should happen? Why throw away overflow?
+      end
+
+      fill_value = (@kit.num_channels == 1) ? 0 : [0, 0]
+      primary_sample_data = [].fill(fill_value, 0, AudioUtils.step_start_sample(track.step_count, @step_sample_length))
+
+      step_index = beats[0]
+      beat_sample_length = 0
+      beats[1...(beats.length)].each do |beat_step_length|
+        start_sample = AudioUtils.step_start_sample(step_index, @step_sample_length)
+        end_sample = [(start_sample + sound.length), primary_sample_data.length].min
+        beat_sample_length = end_sample - start_sample
+
+        primary_sample_data[start_sample...end_sample] = sound[0...beat_sample_length]
+
+        step_index += beat_step_length
+      end
+
+      overflow_sample_data = (sound == [] || beats.length == 1) ? [] : sound[beat_sample_length...(sound.length)]
+
+      {:primary => primary_sample_data, :overflow => overflow_sample_data}
+    end
+
+    # Composites the sample data for each of the pattern's tracks, and returns the overflow sample data
+    # from tracks whose last sound trigger extends past the end of the pattern. This overflow can be
+    # used by the next pattern to avoid sounds cutting off when the pattern changes.
+    def generate_pattern_sample_data(pattern, incoming_overflow)
+      # Unless cached, composite each track's sample data.
+      if @composited_pattern_cache[pattern].nil?
+        primary_sample_data, overflow_sample_data = composite_pattern_tracks(pattern)
+        @composited_pattern_cache[pattern] = {:primary => primary_sample_data.dup, :overflow => overflow_sample_data.dup}
+      else
+        primary_sample_data = @composited_pattern_cache[pattern][:primary].dup
+        overflow_sample_data = @composited_pattern_cache[pattern][:overflow].dup
+      end
+
+      # Composite overflow from the previous pattern onto this pattern, to prevent sounds from cutting off.
+      primary_sample_data, overflow_sample_data = handle_incoming_overflow(pattern,
+                                                                           incoming_overflow,
+                                                                           primary_sample_data,
+                                                                           overflow_sample_data)
+      primary_sample_data = AudioUtils.scale(primary_sample_data, @kit.num_channels, @song.total_tracks)
+
+      {:primary => primary_sample_data, :overflow => overflow_sample_data}
+    end
+
+    def composite_pattern_tracks(pattern)
+      overflow_sample_data = {}
+
+      raw_track_sample_arrays = []
+        pattern.tracks.each do |track_name, track|
+          temp = generate_track_sample_data(track, @kit.get_sample_data(track.name))
+          raw_track_sample_arrays << temp[:primary]
+          overflow_sample_data[track_name] = temp[:overflow]
+        end
+
+      primary_sample_data = AudioUtils.composite(raw_track_sample_arrays, @kit.num_channels)
+      return primary_sample_data, overflow_sample_data
+    end
+
+    # Applies sound overflow (i.e. long sounds such as cymbal crash which extend past the last step)
+    # from the previous pattern in the flow to the current pattern. This prevents sounds from being
+    # cut off when the pattern changes.
+    #
+    # It would probably be shorter and conceptually simpler to deal with incoming overflow in
+    # generate_track_sample_data() instead of this method. (In fact, this method would go away).
+    # However, doing it this way allows for caching composited pattern sample data, and
+    # applying incoming overflow to the composite. This allows each pattern to only be composited once,
+    # regardless of the incoming overflow that each performance of it receives. If incoming overflow
+    # was handled at the Track level we couldn't do that.
+    def handle_incoming_overflow(pattern, incoming_overflow, primary_sample_data, overflow_sample_data)
+      pattern_track_names = pattern.tracks.keys
+      sample_arrays = [primary_sample_data]
+
+      incoming_overflow.each do |incoming_track_name, incoming_sample_data|
+        end_sample = incoming_sample_data.length
+
+        if pattern_track_names.member?(incoming_track_name)
+          track = pattern.tracks[incoming_track_name]
+
+          if track.beats.length > 1
+            intro_length = (pattern.tracks[incoming_track_name].beats[0] * step_sample_length).floor
+            end_sample = [end_sample, intro_length].min
+          end
+        end
+
+        if end_sample > primary_sample_data.length
+          end_sample = primary_sample_data.length
+          overflow_sample_data[incoming_track_name] = incoming_sample_data[(primary_sample_data.length)...(incoming_sample_data.length)]
+        end
+
+        sample_arrays << incoming_sample_data[0...end_sample]
+      end
+
+      return AudioUtils.composite(sample_arrays, @kit.num_channels), overflow_sample_data
+    end
+  end
+end

data/lib/beats/audioutils.rb

@@ -0,0 +1,74 @@
+module Beats
+  # This class contains some utility methods for working with sample data.
+  module AudioUtils
+
+    # Combines multiple sample arrays into one, by adding them together.
+    # When the sample arrays are different lengths, the output array will be the length
+    # of the longest input array.
+    # WARNING: Incoming arrays can be modified.
+    def self.composite(sample_arrays, num_channels)
+      if sample_arrays == []
+        return []
+      end
+
+      # Sort from longest to shortest
+      sample_arrays = sample_arrays.sort {|x, y| y.length <=> x.length}
+
+      composited_output = sample_arrays.slice!(0)
+      sample_arrays.each do |sample_array|
+        unless sample_array == []
+          if num_channels == 1
+            sample_array.length.times {|i| composited_output[i] += sample_array[i] }
+          elsif num_channels == 2
+            sample_array.length.times do |i|
+              composited_output[i] = [composited_output[i][0] + sample_array[i][0],
+                                      composited_output[i][1] + sample_array[i][1]]
+            end
+          end
+        end
+      end
+
+      composited_output
+    end
+
+
+    # Scales the amplitude of the incoming sample array by *scale* amount. Can be used in conjunction
+    # with composite() to make sure composited sample arrays don't have an amplitude greater than 1.0.
+    def self.scale(sample_array, num_channels, scale)
+      if sample_array == []
+        return sample_array
+      end
+
+      if scale > 1
+        if num_channels == 1
+          sample_array = sample_array.map {|sample| sample / scale }
+        elsif num_channels == 2
+          sample_array = sample_array.map {|sample| [sample[0] / scale, sample[1] / scale]}
+        else
+          raise StandardError, "Invalid sample data array in AudioUtils.normalize()"
+        end
+      end
+
+      sample_array
+    end
+
+
+    # Returns the number of samples that each step (i.e. a 'X' or a '.') lasts at a given sample
+    # rate and tempo. The sample length can be a non-integer value. Although there's no such
+    # thing as a partial sample, this is required to prevent small timing errors from creeping in.
+    # If they accumulate, they can cause rhythms to drift out of time.
+    def self.step_sample_length(samples_per_second, tempo)
+       samples_per_minute = samples_per_second * 60.0
+       samples_per_quarter_note = samples_per_minute / tempo
+
+       # Each step is equivalent to a 16th note
+       samples_per_quarter_note / 4.0
+    end
+
+
+    # Returns the sample index that a given step (offset from 0) starts on.
+    def self.step_start_sample(step_index, step_sample_length)
+      (step_index * step_sample_length).floor
+    end
+  end
+end