beats 1.2.0 → 1.2.1

data/LICENSE

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

data/README.markdown

@@ -12,9 +12,9 @@ BEATS is a command-line drum machine written in pure Ruby. Feed it a song notate
         - Chorus:  x4
       Kit:
         - bass:       sounds/bass.wav
-		- snare:      sounds/snare.wav
-		- hh_closed:  sounds/hh_closed.wav
-		- agogo:      sounds/agogo_high.wav
+        - snare:      sounds/snare.wav
+        - hh_closed:  sounds/hh_closed.wav
+        - agogo:      sounds/agogo_high.wav
 
     Verse:
       - bass:             X...X...X...X...
@@ -26,23 +26,27 @@ BEATS is a command-line drum machine written in pure Ruby. Feed it a song notate
       - bass:             X...X...X...X...
       - snare:            ....X.......X...
       - hh_closed:        X.XXX.XXX.XX..X.
-	  - sounds/tom4.wav:  ...........X....
-	  - sounds/tom2.wav:  ..............X.
+      - sounds/tom4.wav:  ...........X....
+      - sounds/tom2.wav:  ..............X.
+
+And [here's what it sounds like](http://beatsdrummachine.com/beat.mp3) after getting the BEATS treatment. What a glorious groove!
 
-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.
+The latest stable version of BEATS is 1.2.1, released on March 6, 2011. This is a minor release which includes the following improvments:
 
-Since it was just released, I'm not sure just yet what will be coming in 1.3.0.
+* You can use the | character to represent bar lines in a track rhythm. This is optional, but often makes longer rhythms easier to read.
+* The "Structure" section of the song header is now called "Flow". (You can still use "Structure" for now, but you'll get a warning).
+* A pattern can contain multiple tracks that use the same sound. Previously, BEATS would pick one of those tracks as the 'winner', and the other tracks wouldn't be played.
+* Bug fix: A better error message is displayed if a sound file is in an unsupported format (such as MP3), or is not even a sound file.
 
 
 Installation
 ------------
 
-To install the latest stable version (1.2.0), run the following from the command line:
+To install the latest stable version (1.2.1) from [rubygems.org](http://rubygems.org/gems/beats), run the following from the command line:
 
     sudo gem install beats
 
@@ -54,4 +58,18 @@ BEATS is not very useful unless you have some sounds to use with it. You can dow
 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)
+BEATS runs from the command-line. Run `beats -h` to see the available options. For more detailed instructions, visit [https://github.com/jstrait/beats/wiki/Usage](https://github.com/jstrait/beats/wiki/Usage) on the [BEATS Wiki](https://github.com/jstrait/beats/wiki).
+
+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.
+
+
+Found a Bug? Have a Suggestion? Want to Contribute?
+---------------------------------------------------
+
+Contact me (Joel Strait) by sending a GitHub message.
+
+
+License
+-------
+BEATS is released under the MIT license.
+

data/bin/beats

@@ -5,16 +5,18 @@ start_time = Time.now
 $:.unshift File.dirname(__FILE__) + "/.."
 require "optparse"
 require "yaml"
+require "lib/wavefile"
+require "lib/beatswavefile"
+require "lib/audioengine"
+require "lib/audioutils"
 require "lib/beats"
-require "lib/song"
-require "lib/songparser"
-require "lib/songoptimizer"
-require "lib/songsplitter"
 require "lib/kit"
 require "lib/pattern"
+require "lib/patternexpander"
+require "lib/song"
+require "lib/songoptimizer"
+require "lib/songparser"
 require "lib/track"
-require "lib/wavefile"
-require "lib/beatswavefile"
 
 def parse_options
   options = {:split => false, :pattern => nil}
@@ -67,4 +69,4 @@ rescue StandardError => detail
   puts "An error occured while generating sound for '#{input_file_name}':\n"
   puts "  #{detail}\n"
   puts "\n"
-end
+end

data/lib/audioengine.rb

@@ -0,0 +1,172 @@
+# This class actually generates the output sound data for the performance.
+# Applies a Kit to a Song (which contains sub Patterns and Tracks) to
+# produce output sample data.
+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
+    samples_written = 0
+    
+    # Open output wave file and preparing it for writing sample data.
+    wave_file = BeatsWaveFile.new(@kit.num_channels, SAMPLE_RATE, @kit.bits_per_sample)
+    file = wave_file.open_for_appending(output_file_name)
+
+    # 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)
+
+        if @kit.num_channels == 1
+          # Don't flatten the sample data Array, since it is already flattened. That would be a waste of time, yo.
+          packed_pattern_cache[key] = {:primary        => sample_data[:primary].pack(PACK_CODE),
+                                       :overflow       => sample_data[:overflow],
+                                       :primary_length => sample_data[:primary].length}
+        else
+          packed_pattern_cache[key] = {:primary        => sample_data[:primary].flatten.pack(PACK_CODE),
+                                       :overflow       => sample_data[:overflow],
+                                       :primary_length => sample_data[:primary].length}
+        end
+      end
+
+      file.syswrite(packed_pattern_cache[key][:primary])
+      incoming_overflow = packed_pattern_cache[key][:overflow]
+      samples_written += packed_pattern_cache[key][:primary_length]
+    end
+
+    # Write any remaining overflow from the final pattern
+    final_overflow_composite = AudioUtils.composite(incoming_overflow.values, @kit.num_channels)
+    final_overflow_composite = AudioUtils.scale(final_overflow_composite, @kit.num_channels, num_tracks_in_song)
+    if @kit.num_channels == 1
+      file.syswrite(final_overflow_composite.pack(PACK_CODE))
+    else
+      file.syswrite(final_overflow_composite.flatten.pack(PACK_CODE))
+    end
+    samples_written += final_overflow_composite.length
+    
+    # Now that we know how many samples have been written, go back and re-write the correct header.
+    file.sysseek(0)
+    wave_file.write_header(file, samples_written)
+
+    file.close()
+
+    return wave_file.calculate_duration(SAMPLE_RATE, samples_written)
+  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)]
+
+    return {: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)
+    
+    return {: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

data/lib/audioutils.rb

@@ -0,0 +1,73 @@
+# This class contains some utility methods for working with sample data.
+class 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
+ 
+    return 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
+    
+    return 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
+     return 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)
+    return (step_index * step_sample_length).floor
+  end
+end
+

data/lib/beats.rb

@@ -1,6 +1,9 @@
 class Beats
-  BEATS_VERSION = "1.2.0"
-  SAMPLE_RATE = 44100
+  BEATS_VERSION = "1.2.1"
+  
+  # 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)
@@ -20,23 +23,19 @@ class Beats
     end
 
     song_parser = SongParser.new()
-    song = song_parser.parse(File.dirname(@input_file_name), YAML.load_file(@input_file_name))
+    song, kit = song_parser.parse(File.dirname(@input_file_name), File.read(@input_file_name))
     song_optimizer = SongOptimizer.new()
 
-    if @options[:pattern] != nil
+    # If the -p option is used, transform the song into one whose flow consists of
+    # playing that single pattern once.
+    unless @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()
+      song.remove_patterns_except(pattern_name)
     end
 
     duration = nil
     if @options[:split]
-      song_splitter = SongSplitter.new()
-      split_songs = song_splitter.split(song)
+      split_songs = song.split()
       split_songs.each do |track_name, split_song|
         split_song = song_optimizer.optimize(split_song, OPTIMIZED_PATTERN_LENGTH)
 
@@ -45,13 +44,13 @@ class Beats
         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)
+        duration = AudioEngine.new(split_song, kit).write_to_file(file_name)
       end
     else
       song = song_optimizer.optimize(song, OPTIMIZED_PATTERN_LENGTH)
-      duration = song.write_to_file(@output_file_name)
+      duration = AudioEngine.new(song, kit).write_to_file(@output_file_name)
     end
 
     return {:duration => duration}
   end
-end
+end

data/lib/beatswavefile.rb

@@ -1,15 +1,10 @@
 # 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.
+# use of open_for_appending() allows 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.
@@ -17,12 +12,19 @@ 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)
+  # a field for the total number of samples in the file. This number of samples (and exactly
+  # this number of samples) must be subsequently be written to the file before it is closed
+  # or it won't be valid and you won't be able to play it.
+  def open_for_appending(path)
+    file = File.open(path, "w")
+    write_header(file, 0)
+    
+    return file
+  end
+
+  def write_header(file, sample_length)
     bytes_per_sample = (@bits_per_sample / 8)
-    sample_data_size = num_samples * bytes_per_sample * @num_channels
+    sample_data_size = sample_length * bytes_per_sample * @num_channels
 
     # Write the header
     header = CHUNK_ID
@@ -39,29 +41,7 @@ class BeatsWaveFile < WaveFile
     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)
@@ -90,4 +70,4 @@ class BeatsWaveFile < WaveFile
     
     return { :hours => hours, :minutes => minutes, :seconds => seconds, :milliseconds => milliseconds }
   end
-end
+end