beats 1.1.0 → 1.2.0

data/README.markdown

@@ -1,7 +1,7 @@
-BEATS
------
+BEATS Drum Machine
+------------------
 
-BEATS is a drum machine written in pure Ruby. Feed it a song notated in YAML, and it will produce a precision-milled Wave file of impeccable timing and feel. Here's an example song:
+BEATS is a command-line drum machine written in pure Ruby. Feed it a song notated in YAML, and it will produce a precision-milled *.wav file of impeccable timing and feel. Here's an example song:
 
     Song:
       Tempo: 120
@@ -29,4 +29,29 @@ BEATS is a drum machine written in pure Ruby. Feed it a song notated in YAML, an
 	  - sounds/tom4.wav:  ...........X....
 	  - sounds/tom2.wav:  ..............X.
 
-For installation and usage instructions, visit the BEATS website at [http://beatsdrummachine.com](http://beatsdrummachine.com).
+And [here is what it sounds like](http://beatsdrummachine.com/beat.mp3) after getting the BEATS treatment. What a glorious groove!
+
+Current Status
+--------------
+
+The latest stable version of BEATS is 1.2.0. It was just released! It brings significant performance and architectural improvements. It also contains a few bug fixes.
+
+Since it was just released, I'm not sure just yet what will be coming in 1.3.0.
+
+
+Installation
+------------
+
+To install the latest stable version (1.2.0), run the following from the command line:
+
+    sudo gem install beats
+
+You can then run BEATS from the command-line using the `beats` command.
+
+BEATS is not very useful unless you have some sounds to use with it. You can download some example sounds from [http://beatsdrummachine.com](http://beatsdrummachine.com).
+
+
+Usage
+-----
+
+BEATS runs from the command-line. Run `beats -h` to see the available options. For more detailed instructions, visit [http://beatsdrummachine.com](http://beatsdrummachine.com)

data/bin/beats

@@ -1,20 +1,23 @@
 #!/usr/bin/env ruby
 
-require File.dirname(__FILE__) + "/../lib/song"
-require File.dirname(__FILE__) + "/../lib/songparser"
-require File.dirname(__FILE__) + "/../lib/kit"
-require File.dirname(__FILE__) + "/../lib/pattern"
-require File.dirname(__FILE__) + "/../lib/track"
-require "rubygems"
+start_time = Time.now
+
+$:.unshift File.dirname(__FILE__) + "/.."
 require "optparse"
 require "yaml"
-require "wavefile"
-
-BEATS_VERSION = "1.1.0"
-SAMPLE_RATE = 44100
+require "lib/beats"
+require "lib/song"
+require "lib/songparser"
+require "lib/songoptimizer"
+require "lib/songsplitter"
+require "lib/kit"
+require "lib/pattern"
+require "lib/track"
+require "lib/wavefile"
+require "lib/beatswavefile"
 
 def parse_options
-  options = {:split => false, :pattern => ""}
+  options = {:split => false, :pattern => nil}
 
   optparse = OptionParser.new do |opts|
     opts.on('-s', '--split', "Save each track to an individual wave file") do
@@ -24,82 +27,44 @@ def parse_options
     opts.on('-p', '--pattern PATTERN_NAME', "Output a single pattern instead of the whole song" ) do |p|
       options[:pattern] = p
     end
-    
+  
     opts.on('-v', '--version', "Display version number and exit") do
-      puts "BEATS v#{BEATS_VERSION}"
+      puts "BEATS v#{Beats::BEATS_VERSION}"
       exit
     end
-    
+  
     opts.on( '-h', '--help', "Display this screen and exit" ) do
       puts opts
       exit
     end
   end
   optparse.parse!
-  
-  return options
-end
 
-def save_wave_file(file_name, num_channels, bits_per_sample, sample_data)
-  output = WaveFile.new(num_channels, SAMPLE_RATE, bits_per_sample)
-  output.sample_data = sample_data
-  output.save(file_name)
-  return output.duration
+  return options
 end
 
-start = Time.now
-
 options = parse_options
-input_file = ARGV[0]
-output_file = ARGV[1]
+input_file_name = ARGV[0]
+output_file_name = ARGV[1]
 
-if(input_file == nil)
-  ARGV[0] = '-h'
-  parse_options()
-end
-
-if(output_file == nil)
-  output_file = File.basename(input_file, File.extname(input_file)) + ".wav"
-end
+beats = Beats.new(input_file_name, output_file_name, options)
 
 begin
-  parse_start_time = Time.now
-  song_parser = SongParser.new()
-  song_from_file = song_parser.parse(File.dirname(input_file), YAML.load_file(input_file))
-  
-  generate_samples_start = Time.now
-  sample_data = song_from_file.sample_data(options[:pattern], options[:split])
-  #puts "Time to generate sample data: #{Time.now - generate_samples_start}"
-
-  wave_write_start = Time.now
-  if(options[:split])
-    duration = nil
-    sample_data.keys.each {|track_name|
-      extension = File.extname(output_file)
-      file_name = File.basename(output_file, extension) + "-" + File.basename(track_name.to_s, extension) + extension
-      
-      duration = save_wave_file(file_name,
-                                song_from_file.num_channels,
-                                song_from_file.bits_per_sample,
-                                sample_data[track_name])
-    }
-  else
-    duration = save_wave_file(output_file, song_from_file.num_channels, song_from_file.bits_per_sample, sample_data)
-  end
-  
-  puts "#{duration[:minutes]}:#{duration[:seconds].to_s.rjust(2, '0')} of audio produced in #{Time.now - start} seconds."
+  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."
 rescue Errno::ENOENT => detail
-  puts ""
-  puts "Song file '#{input_file}' not found."
-  puts ""
+  puts "\n"
+  puts "Song file '#{input_file_name}' not found.\n"
+  puts "\n"
 rescue SongParseError => detail
-  puts ""
-  puts "Song file '#{input_file}' has an error:"
-  puts "  #{detail}"
-  puts ""
+  puts "\n"
+  puts "Song file '#{input_file_name}' has an error:\n"
+  puts "  #{detail}\n"
+  puts "\n"
 rescue StandardError => detail
-  puts ""
-  puts "An error occured while generating sound for '#{input_file}':"
-  puts "  #{detail}"
-  puts ""
-end
+  puts "\n"
+  puts "An error occured while generating sound for '#{input_file_name}':\n"
+  puts "  #{detail}\n"
+  puts "\n"
+end

data/lib/beats.rb

@@ -0,0 +1,57 @@
+class Beats
+  BEATS_VERSION = "1.2.0"
+  SAMPLE_RATE = 44100
+  OPTIMIZED_PATTERN_LENGTH = 4
+
+  def initialize(input_file_name, output_file_name, options)
+    @input_file_name =  input_file_name
+    @output_file_name = output_file_name
+    @options = options
+  end
+
+  def run
+    if @input_file_name == nil
+      ARGV[0] = '-h'
+      parse_options()
+    end
+
+    if @output_file_name == nil
+      @output_file_name = File.basename(@input_file_name, File.extname(@input_file_name)) + ".wav"
+    end
+
+    song_parser = SongParser.new()
+    song = song_parser.parse(File.dirname(@input_file_name), YAML.load_file(@input_file_name))
+    song_optimizer = SongOptimizer.new()
+
+    if @options[:pattern] != nil
+      pattern_name = @options[:pattern].downcase.to_sym
+      unless song.patterns.member?(pattern_name)
+        raise StandardError, "The song does not include a pattern called #{@options[:pattern]}"
+      end
+      
+      song.structure = [pattern_name]
+      song.remove_unused_patterns()
+    end
+
+    duration = nil
+    if @options[:split]
+      song_splitter = SongSplitter.new()
+      split_songs = song_splitter.split(song)
+      split_songs.each do |track_name, split_song|
+        split_song = song_optimizer.optimize(split_song, OPTIMIZED_PATTERN_LENGTH)
+
+        # 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
+        duration = split_song.write_to_file(file_name)
+      end
+    else
+      song = song_optimizer.optimize(song, OPTIMIZED_PATTERN_LENGTH)
+      duration = song.write_to_file(@output_file_name)
+    end
+
+    return {:duration => duration}
+  end
+end

data/lib/beatswavefile.rb

@@ -0,0 +1,93 @@
+# Adds some functionality to the WaveFile gem that allows for improved performance. The 
+# combo of open_for_appending() and write_snippet() allow a wave file to be written to
+# disk in chunks, instead of all at once. This improves performance (and I would assume
+# memory usage) by eliminating the need to store the entire sample data for the song in
+# memory in a giant (i.e. millions of elements) array.
+#
+# I'm not sure these methods in their current form are suitable for the WaveFile gem.
+# That's a public API so I want to be careful adding to it, and these methods fall into the
+# category of "you should know what you're doing." In particular, open_for_appending() and
+# write_snippet() need to be used together, and if you don't use them right your saved wave
+# file will be messed up. There's probably a better API for doing this.
+#
+# If I figure out a better API I might add it to the WaveFile gem in the future, but until
+# then I'm just putting it here. Since BEATS is a stand-alone app and not a re-usable library,
+# I don't think this should be a problem.
+class BeatsWaveFile < WaveFile
+  
+  # Writes the header for the wave file to path, and returns an open File object that
+  # can be used outside the method to append the sample data. WARNING: The header contains
+  # a field for the total number of samples in the file. This number of samples must be
+  # subsequently be written to the file using write_snippet() or it won't be valid and you
+  # won't be able to play it.
+  def open_for_appending(path, num_samples)
+    bytes_per_sample = (@bits_per_sample / 8)
+    sample_data_size = num_samples * bytes_per_sample * @num_channels
+
+    # Write the header
+    header = CHUNK_ID
+    header += [HEADER_SIZE + sample_data_size].pack("V")
+    header += FORMAT
+    header += FORMAT_CHUNK_ID
+    header += [SUB_CHUNK1_SIZE].pack("V")
+    header += [PCM].pack("v")
+    header += [@num_channels].pack("v")
+    header += [@sample_rate].pack("V")
+    header += [@byte_rate].pack("V")
+    header += [@block_align].pack("v")
+    header += [@bits_per_sample].pack("v")
+    header += DATA_CHUNK_ID
+    header += [sample_data_size].pack("V")
+
+    file = File.open(path, "w")
+    file.syswrite(header)
+    
+    return file
+  end
+  
+  # Appending sample_data to file, which is assumed to be open. Should be used in
+  # conjunction with open_for_appending(). The File object returned by that method
+  # should be passed in here. WARNING: you are responsible for writing the correct
+  # number of samples to the file, with 1 or more calls to this method. The caller
+  # of this method is also responsible for closing the File object when finished.
+  def write_snippet(file, sample_data)
+    if @bits_per_sample == 8
+      pack_code = "C*"
+    elsif @bits_per_sample == 16
+      pack_code = "s*"
+    end
+    
+    if @num_channels == 1
+      file.syswrite(sample_data.pack(pack_code))
+    else
+      file.syswrite(sample_data.flatten.pack(pack_code))
+    end
+  end
+  
+  def calculate_duration(sample_rate, total_samples)
+    samples_per_millisecond = sample_rate / 1000.0
+    samples_per_second = sample_rate
+    samples_per_minute = samples_per_second * 60
+    samples_per_hour = samples_per_minute * 60
+    hours, minutes, seconds, milliseconds = 0, 0, 0, 0
+    
+    if total_samples >= samples_per_hour
+      hours = total_samples / samples_per_hour
+      total_samples -= samples_per_hour * hours
+    end
+    
+    if total_samples >= samples_per_minute
+      minutes = total_samples / samples_per_minute
+      total_samples -= samples_per_minute * minutes
+    end
+    
+    if total_samples >= samples_per_second
+      seconds = total_samples / samples_per_second
+      total_samples -= samples_per_second * seconds
+    end
+    
+    milliseconds = (total_samples / samples_per_millisecond).floor
+    
+    return { :hours => hours, :minutes => minutes, :seconds => seconds, :milliseconds => milliseconds }
+  end
+end

data/lib/kit.rb

@@ -1,38 +1,74 @@
+# Raised when trying to load a sound file which can't be found at the path specified
 class SoundNotFoundError < RuntimeError; end
 
+# This class keeps track of the sounds that are used in a song. It provides a
+# central place for storing sound data, and most usefully, handles converting
+# sounds in different formats to a standard format.
+# 
+# For example, if a song requires a sound that is mono/8-bit, another that is
+# stereo/8-bit, and another that is stereo/16-bit, it can't mix them together
+# because they are in different formats. Kit however automatically handles the
+# details of converting them to a common format. If you add sounds to the kit
+# using add(), sounds that you get using get_sample_data() will be in a common
+# format.
+#
+# All sounds returned by get_sample_data() will be 16-bit. All sounds will be
+# either mono or stereo; if at least one added sound is stereo then all sounds
+# will be stereo. So for example if a mono/8-bit, stereo/8-bit, and stereo/16-bit
+# sound are added, when you retrieve each one using get_sample_data() they will
+# be stereo/16-bit.
+#
+# Note that this means that each time a new sound is added to the Kit, the common
+# format might change, if the incoming sound has a greater number of channels than
+# any of the previously added sounds. Therefore, all of the sounds
+# used by a Song should be added to the Kit before generation begins. If you
+# create Song objects by using SongParser, this will be taken care of for you (as
+# long as you don't modify the Kit afterward).
 class Kit
   PATH_SEPARATOR = File.const_get("SEPARATOR")
   
+  # Creates a new Kit object. base_path indicates the folder from which sound files
+  # with relative file paths will be loaded from.
   def initialize(base_path)
     @base_path = base_path
+    @label_mappings = {}
     @sounds = {}
-    @num_channels = 0
-    @bits_per_sample = 0
+    @num_channels = 1
+    @bits_per_sample = 16  # Only use 16-bit files as output. Supporting 8-bit output
+                           # means extra complication for no real gain (I'm skeptical
+                           # anyone would explicitly want 8-bit output instead of 16-bit.
   end
   
+  # Adds a new sound to the kit. 
   def add(name, path)
-    if(!@sounds.has_key? name)
-      if(!path.start_with?(PATH_SEPARATOR))
-        path = @base_path + PATH_SEPARATOR + path
+    unless @sounds.has_key? name
+      path_is_absolute = path.start_with?(PATH_SEPARATOR)
+      if path_is_absolute
+        full_path = path
+      else
+        full_path = @base_path + PATH_SEPARATOR + path
       end
       
       begin
-        wavefile = WaveFile.open(path)
+        wavefile = WaveFile.open(full_path)
       rescue
-        raise SoundNotFoundError, "Sound file #{name} not found."
+        # TODO: Raise different error if sound is in an unsupported format
+        raise SoundNotFoundError, "Sound file #{full_path} not found."
       end
       
       @sounds[name] = wavefile
+      if name != path
+        @label_mappings[name] = path
+      end
     
       if wavefile.num_channels > @num_channels
         @num_channels = wavefile.num_channels
       end
-      if wavefile.bits_per_sample > @bits_per_sample
-        @bits_per_sample = wavefile.bits_per_sample
-      end
     end
   end
   
+  # Returns the sample data (as an Array) for a sound contained in the Kit.
+  # Raises an error if the sound doesn't exist in the Kit.
   def get_sample_data(name)
     wavefile = @sounds[name]
     
@@ -46,9 +82,29 @@ class Kit
     end
   end
   
+  # Returns the number of sounds currently contained in the kit.
   def size
     return @sounds.length
   end
   
-  attr_reader :base_path, :bits_per_sample, :num_channels
+  # Produces nicer looking output than the default version of to_yaml().
+  def to_yaml(indent_space_count = 0)
+    yaml = ""
+    longest_label_mapping_length =
+      @label_mappings.keys.inject(0) do |max_length, name|
+        (name.to_s.length > max_length) ? name.to_s.length : max_length
+      end
+
+    if @label_mappings.length > 0
+      yaml += " " * indent_space_count + "Kit:\n"
+      ljust_amount = longest_label_mapping_length + 1  # The +1 is for the trailing ":"
+      @label_mappings.sort.each do |label, path|
+        yaml += " " * indent_space_count + "  - #{(label + ":").ljust(ljust_amount)}  #{path}\n"
+      end
+    end
+    
+    return yaml
+  end
+  
+  attr_reader :base_path, :label_mappings, :bits_per_sample, :num_channels
 end

data/lib/pattern.rb

@@ -1,133 +1,178 @@
 class Pattern
   def initialize(name)
     @name = name
-    @cache = {}
     @tracks = {}
   end
   
-  def track(name, wave_data, pattern)
-    new_track = Track.new(name, wave_data, pattern)        
+  # Adds a new track to the pattern.
+  def track(name, wave_data, rhythm)
+    new_track = Track.new(name, wave_data, rhythm)        
     @tracks[new_track.name] = new_track
     
     # If the new track is longer than any of the previously added tracks,
     # pad the other tracks with trailing . to make them all the same length.
     # Necessary to prevent incorrect overflow calculations for tracks.
-    longest_track_length = 0
-    @tracks.values.each {|track|
-      if(track.pattern.length > longest_track_length)
-        longest_track_length = track.pattern.length
+    longest_track_length = tick_count()
+    @tracks.values.each do |track|
+      if track.rhythm.length < longest_track_length
+        track.rhythm += "." * (longest_track_length - track.rhythm.length)
       end
-    }
-    @tracks.values.each {|track|
-      if(track.pattern.length < longest_track_length)
-        track.pattern += "." * (longest_track_length - track.pattern.length)
-      end
-    }
+    end
     
     return new_track
   end
   
+  # The number of samples required for the pattern at the given tempo. DOES NOT include samples
+  # necessary for sound that overflows past the last tick of the pattern.
   def sample_length(tick_sample_length)
     @tracks.keys.collect {|track_name| @tracks[track_name].sample_length(tick_sample_length) }.max || 0
   end
   
+  # The number of samples required for the pattern at the given tempo. Include sound overflow
+  # past the last tick of the pattern.
   def sample_length_with_overflow(tick_sample_length)
     @tracks.keys.collect {|track_name| @tracks[track_name].sample_length_with_overflow(tick_sample_length) }.max || 0
   end
   
-  def sample_data(tick_sample_length, num_channels, num_tracks_in_song, incoming_overflow, split = false)
-    if(split)
-      return split_sample_data(tick_sample_length, num_channels, incoming_overflow)
-    else
-      return combined_sample_data(tick_sample_length, num_channels, num_tracks_in_song, incoming_overflow)
+  def tick_count
+    return @tracks.values.collect {|track| track.rhythm.length }.max || 0
+  end
+    
+  def sample_data(tick_sample_length, num_channels, num_tracks_in_song, incoming_overflow)
+    primary_sample_data, overflow_sample_data = generate_main_sample_data(tick_sample_length, num_channels)
+    primary_sample_data, overflow_sample_data = handle_incoming_overflow(tick_sample_length,
+                                                                         num_channels,
+                                                                         incoming_overflow,
+                                                                         primary_sample_data,
+                                                                         overflow_sample_data)
+    primary_sample_data = mixdown_sample_data(num_channels, num_tracks_in_song, primary_sample_data)
+    
+    return {:primary => primary_sample_data, :overflow => overflow_sample_data}
+  end
+  
+  # Returns whether or not this pattern has the same number of tracks as other_pattern, and that
+  # each of the tracks has the same name and rhythm. Ordering of tracks does not matter; will
+  # return true if the two patterns have the same tracks but in a different ordering.
+  def same_tracks_as?(other_pattern)
+    @tracks.keys.each do |track_name|
+      other_pattern_track = other_pattern.tracks[track_name]
+      if other_pattern_track == nil || @tracks[track_name].rhythm != other_pattern_track.rhythm
+        return false
+      end
+    end
+    
+    return @tracks.length == other_pattern.tracks.length
+  end
+  
+  # Returns a YAML representation of the Pattern. Produces nicer looking output than the default
+  # version of to_yaml().
+  def to_yaml
+    longest_track_name_length =
+      @tracks.keys.inject(0) do |max_length, name|
+        (name.to_s.length > max_length) ? name.to_s.length : max_length
+      end
+    ljust_amount = longest_track_name_length + 7
+    
+    yaml = "#{@name.to_s.capitalize}:\n"
+    @tracks.keys.sort.each do |track_name|
+      yaml += "  - #{track_name}:".ljust(ljust_amount)
+      yaml += "#{@tracks[track_name].rhythm}\n"
     end
+    
+    return yaml
   end
   
   attr_accessor :tracks, :name
-
+  
 private
 
-  def combined_sample_data(tick_sample_length, num_channels, num_tracks_in_song, incoming_overflow)
-    # If we've already encountered this pattern with the same incoming overflow before,
-    # return the pre-mixed down version from the cache.
-    if(@cache.member?(incoming_overflow))
-      return @cache[incoming_overflow]
-    end
-    
-    fill_value = (num_channels == 1) ? 0 : [].fill(0, 0, num_channels)
+  def generate_main_sample_data(tick_sample_length, num_channels)
     track_names = @tracks.keys
     primary_sample_data = []
     overflow_sample_data = {}
     actual_sample_length = sample_length(tick_sample_length)
-
-    if(track_names.length > 0)
-      primary_sample_data = [].fill(fill_value, 0, actual_sample_length)
-
-      track_names.each {|track_name|
-        temp = @tracks[track_name].sample_data(tick_sample_length, incoming_overflow[track_name])
-
-        track_samples = temp[:primary]
-        if(num_channels == 1)
-          (0...track_samples.length).each {|i| primary_sample_data[i] += track_samples[i] }
-        else
-          (0...track_samples.length).each {|i|
-            primary_sample_data[i][0] += track_samples[i][0]
-            primary_sample_data[i][1] += track_samples[i][1]
-          }
-        end
-
-        overflow_sample_data[track_name] = temp[:overflow]
-      }
-    end
+  
+    if @intermediate_cache == nil
+      track_names.each do |track_name|
+        temp = @tracks[track_name].sample_data(tick_sample_length)
     
-    # Add samples for tracks with overflow from previous pattern, but not
-    # contained in current pattern.
-    incoming_overflow.keys.each {|track_name|
-      if(!track_names.member?(track_name) && incoming_overflow[track_name].length > 0)
-        if(num_channels == 1)
-          (0...incoming_overflow[track_name].length).each {|i| primary_sample_data[i] += incoming_overflow[track_name][i]}
+        if primary_sample_data == []
+          primary_sample_data = temp[:primary]
+          overflow_sample_data[track_name] = temp[:overflow]
         else
-          (0...incoming_overflow[track_name].length).each {|i| primary_sample_data[i][0] += incoming_overflow[track_name][i][0]
-                                                               primary_sample_data[i][1] += incoming_overflow[track_name][i][1]}
+          track_samples = temp[:primary]
+          if num_channels == 1
+            track_samples.length.times {|i| primary_sample_data[i] += track_samples[i] }
+          else
+            track_samples.length.times do |i|
+              primary_sample_data[i] = [primary_sample_data[i][0] + track_samples[i][0],
+                                        primary_sample_data[i][1] + track_samples[i][1]]
+            end
+          end
+
+          overflow_sample_data[track_name] = temp[:overflow]
         end
       end
-    }
     
-    # Mix down the pattern's tracks into one single track
-    if(num_channels == 1)
-      primary_sample_data = primary_sample_data.map {|sample| (sample / num_tracks_in_song).round }
+      @intermediate_cache = {:primary => primary_sample_data.dup, :overflow => overflow_sample_data.dup}
     else
-      primary_sample_data = primary_sample_data.map {|sample| [(sample[0] / num_tracks_in_song).round, (sample[1] / num_tracks_in_song).round] }
+      primary_sample_data = @intermediate_cache[:primary].dup
+      overflow_sample_data = @intermediate_cache[:overflow].dup
     end
-    
-    # Add the result to the cache so we don't have to go through all of this the next time...
-    mixdown_sample_data = {:primary => primary_sample_data, :overflow => overflow_sample_data}
-    @cache[incoming_overflow] = mixdown_sample_data
-    
-    return mixdown_sample_data
+  
+    return primary_sample_data, overflow_sample_data
   end
 
-  def split_sample_data(tick_sample_length, num_channels, incoming_overflow)
-    fill_value = (num_channels == 1) ? 0 : [].fill(0, 0, num_channels)
-    primary_sample_data = {}
-    overflow_sample_data = {}
-    
-    @tracks.keys.each {|track_name|
-      temp = @tracks[track_name].sample_data(tick_sample_length, incoming_overflow[track_name])
-      primary_sample_data[track_name] = temp[:primary]
-      overflow_sample_data[track_name] = temp[:overflow]
-    }
+  def handle_incoming_overflow(tick_sample_length, num_channels, incoming_overflow, primary_sample_data, overflow_sample_data)
+    track_names = @tracks.keys
+  
+    # Add overflow from previous pattern
+    incoming_overflow.keys.each do |track_name|
+      num_incoming_overflow_samples = incoming_overflow[track_name].length
     
-    incoming_overflow.keys.each {|track_name|
-      if(@tracks[track_name] == nil)
-        # TO DO: Add check for when incoming overflow is longer than
-        # track full length to prevent track from lengthening.
-        primary_sample_data[track_name] = [].fill(fill_value, 0, sample_length(tick_sample_length))
-        primary_sample_data[track_name][0...incoming_overflow[track_name].length] = incoming_overflow[track_name]
-        overflow_sample_data[track_name] = []
+      if num_incoming_overflow_samples > 0
+        if track_names.member?(track_name)
+          # TODO: Does this handle situations where track has a .... rhythm and overflow is
+          # longer than track length?
+        
+          intro_length = @tracks[track_name].intro_sample_length(tick_sample_length)
+          if num_incoming_overflow_samples > intro_length
+            num_incoming_overflow_samples = intro_length
+          end
+        else
+          # If incoming overflow for track is longer than the pattern length, only add the first part of
+          # the overflow to the pattern, and add the remainder to overflow_sample_data so that it gets
+          # handled by the next pattern to be generated.
+          if num_incoming_overflow_samples > primary_sample_data.length
+            overflow_sample_data[track_name] = (incoming_overflow[track_name])[primary_sample_data.length...num_incoming_overflow_samples]
+            num_incoming_overflow_samples = primary_sample_data.length
+          end
+        end
+      
+        if num_channels == 1
+          num_incoming_overflow_samples.times {|i| primary_sample_data[i] += incoming_overflow[track_name][i]}
+        else
+          num_incoming_overflow_samples.times do |i|
+            primary_sample_data[i] = [primary_sample_data[i][0] + incoming_overflow[track_name][i][0],
+                                      primary_sample_data[i][1] + incoming_overflow[track_name][i][1]]
+          end
+        end
       end
-    }
-    
-    return {:primary => primary_sample_data, :overflow => overflow_sample_data}
+    end
+  
+    return primary_sample_data, overflow_sample_data
+  end
+
+  def mixdown_sample_data(num_channels, num_tracks_in_song, primary_sample_data)
+    # Mix down the pattern's tracks into one single track
+    if num_tracks_in_song > 1
+      if num_channels == 1
+        primary_sample_data = primary_sample_data.map {|sample| sample / num_tracks_in_song }
+      else
+        primary_sample_data = primary_sample_data.map {|sample| [sample[0] / num_tracks_in_song, sample[1] / num_tracks_in_song]}
+      end
+    end
+  
+    return primary_sample_data
   end
 end