beats 1.1.0 → 1.2.0

data/lib/song.rb

@@ -13,19 +13,26 @@ class Song
     @structure = []
   end
 
+  # Adds a new pattern to the song, with the specified name.
   def pattern(name)
     @patterns[name] = Pattern.new(name)
     return @patterns[name]
   end
 
-  def sample_length()
-    @structure.inject(0) {|sum, pattern_name|
+  # Returns the number of samples required for the entire song at the current tempo.
+  # (Assumes a sample rate of 44100). Does NOT include samples required for sound
+  # overflow from the last pattern.
+  def sample_length
+    @structure.inject(0) do |sum, pattern_name|
       sum + @patterns[pattern_name].sample_length(@tick_sample_length)
-    }
+    end
   end
 
-  def sample_length_with_overflow()
-    if(@structure.length == 0)
+  # Returns the number of samples required for the entire song at the current tempo.
+  # (Assumes a sample rate of 44100). Includes samples required for sound overflow
+  # from the last pattern.
+  def sample_length_with_overflow
+    if @structure.length == 0
       return 0
     end
     
@@ -37,158 +44,182 @@ class Song
     return sample_length + overflow
   end
   
-  def total_tracks()
+  # The number of tracks that the pattern with the greatest number of tracks has.
+  # TODO: Is it a problem that an optimized song can have a different total_tracks() value than
+  # the original? Or is that actually a good thing?
+  # TODO: Investigate replacing this with a method max_sounds_playing_at_once() or something
+  # like that. Would look each pattern along with it's incoming overflow.
+  def total_tracks
     @patterns.keys.collect {|pattern_name| @patterns[pattern_name].tracks.length }.max || 0
   end
+  
+  def track_names
+    track_names = {}
+    @patterns.values.each do |pattern|
+      pattern.tracks.values.each {|track| track_names[track.name] = nil}
+    end
+    
+    return track_names.keys.sort
+  end
 
-  def sample_data(pattern_name, split)
+  def write_to_file(output_file_name)
+    cache = {}
+    pack_code = pack_code()
     num_tracks_in_song = self.total_tracks()
-    fill_value = (@kit.num_channels == 1) ? 0 : [].fill(0, 0, @kit.num_channels)
-
-    if(pattern_name == "")      
-      if(split)
-        return sample_data_split_all_patterns(fill_value, num_tracks_in_song)
-      else
-        return sample_data_combined_all_patterns(fill_value, num_tracks_in_song)
-      end
-    else
-      pattern = @patterns[pattern_name.downcase.to_sym]
-      
-      if(pattern == nil)
-        raise StandardError, "Pattern '#{pattern_name}' not found in song."
-      else
-        primary_sample_length = pattern.sample_length(@tick_sample_length)
-      
-        if(split)
-          return sample_data_split_single_pattern(fill_value, num_tracks_in_song, pattern, primary_sample_length)
+    sample_length = sample_length_with_overflow()
+    
+    wave_file = BeatsWaveFile.new(@kit.num_channels, SAMPLE_RATE, @kit.bits_per_sample)
+    file = wave_file.open_for_appending(output_file_name, sample_length)
+    
+    incoming_overflow = {}
+    @structure.each do |pattern_name|
+      key = [pattern_name, incoming_overflow.hash]
+      unless cache.member?(key)
+        sample_data = @patterns[pattern_name].sample_data(@tick_sample_length,
+                                                          @kit.num_channels,
+                                                          num_tracks_in_song,
+                                                          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.
+          cache[key] = {:primary => sample_data[:primary].pack(pack_code), :overflow => sample_data[:overflow]}
         else
-          return sample_data_combined_single_pattern(fill_value, num_tracks_in_song, pattern, primary_sample_length)
+          cache[key] = {:primary => sample_data[:primary].flatten.pack(pack_code), :overflow => sample_data[:overflow]}
         end
       end
+      
+      file.syswrite(cache[key][:primary])
+      incoming_overflow = cache[key][:overflow]
     end
+    
+    wave_file.write_snippet(file, merge_overflow(incoming_overflow, num_tracks_in_song))
+    file.close()
+    
+    return wave_file.calculate_duration(SAMPLE_RATE, sample_length)
   end
 
-  def num_channels()
+  def num_channels
     return @kit.num_channels
   end
   
-  def bits_per_sample()
+  def bits_per_sample
     return @kit.bits_per_sample
   end
 
-  def tempo()
+  def tempo
     return @tempo
   end
 
   def tempo=(new_tempo)
-    if(new_tempo.class != Fixnum || new_tempo <= 0)
+    unless new_tempo.class == Fixnum && new_tempo > 0
       raise InvalidTempoError, "Invalid tempo: '#{new_tempo}'. Tempo must be a number greater than 0."
     end
     
     @tempo = new_tempo
     @tick_sample_length = SAMPLES_PER_MINUTE / new_tempo / 4.0
   end
+  
+  # Returns a new Song that is identical but with no patterns or structure.
+  def copy_ignoring_patterns_and_structure
+    copy = Song.new(@kit.base_path)
+    copy.tempo = @tempo
+    copy.kit = @kit
+    
+    return copy
+  end
+  
+  # Removes any patterns that aren't referenced in the structure.
+  def remove_unused_patterns
+    # Using reject() here, because for some reason select() returns an Array not a Hash.
+    @patterns = @patterns.reject {|k, pattern| !@structure.member?(pattern.name) }
+  end
+
+  # Serializes the current Song to a YAML string. This string can then be used to construct a new Song
+  # using the SongParser class. This lets you save a Song to disk, to be re-loaded later. Produces nicer
+  # looking output than the default version of to_yaml().
+  def to_yaml
+    # This implementation intentionally builds up a YAML string manually instead of using YAML::dump().
+    # Ruby 1.8 makes it difficult to ensure a consistent ordering of hash keys, which makes the output ugly
+    # and also hard to test.
+    
+    yaml_output = "Song:\n"
+    yaml_output += "  Tempo: #{@tempo}\n"
+    yaml_output += structure_to_yaml()
+    yaml_output += @kit.to_yaml(2)
+    yaml_output += patterns_to_yaml()
+    
+    return yaml_output
+  end
 
   attr_reader :tick_sample_length, :patterns
   attr_accessor :structure, :kit
 
 private
 
+  def pack_code
+    if @kit.bits_per_sample == 8
+      return "C*"
+    elsif @kit.bits_per_sample == 16
+      return "s*"
+    else
+      raise StandardError, "Invalid bits per sample of #{@kit.bits_per_sample}"
+    end
+  end
+
+  def longest_length_in_array(arr)
+    return arr.inject(0) {|max_length, name| (name.to_s.length > max_length) ? name.to_s.length : max_length }
+  end
+
+  def structure_to_yaml
+    yaml_output = "  Structure:\n"
+    ljust_amount = longest_length_in_array(@structure) + 1  # The +1 is for the trailing ":"
+    previous = nil
+    count = 0
+    @structure.each do |pattern_name|
+      if pattern_name == previous || previous == nil
+        count += 1
+      else
+        yaml_output += "    - #{(previous.to_s.capitalize + ':').ljust(ljust_amount)}  x#{count}\n"
+        count = 1
+      end
+      previous = pattern_name
+    end
+    yaml_output += "    - #{(previous.to_s.capitalize + ':').ljust(ljust_amount)}  x#{count}\n"
+    
+    return yaml_output
+  end
+
+  def patterns_to_yaml
+    yaml_output = ""
+    
+    # Sort to ensure a consistent order, to make testing easier
+    pattern_names = @patterns.keys.map {|key| key.to_s}  # Ruby 1.8 can't sort symbols...
+    pattern_names.sort.each do |pattern_name|
+      yaml_output += "\n" + @patterns[pattern_name.to_sym].to_yaml()
+    end
+    
+    return yaml_output
+  end
+
   def merge_overflow(overflow, num_tracks_in_song)
     merged_sample_data = []
 
-    if(overflow != {})
+    unless overflow == {}
       longest_overflow = overflow[overflow.keys.first]
-      overflow.keys.each {|track_name|
-        if(overflow[track_name].length > longest_overflow.length)
+      overflow.keys.each do |track_name|
+        if overflow[track_name].length > longest_overflow.length
           longest_overflow = overflow[track_name]
         end
-      }
+      end
 
+      # TODO: What happens if final overflow is really long, and extends past single '.' rhythm?
       final_overflow_pattern = Pattern.new(:overflow)
-      final_overflow_pattern.track "", [], "."
-      final_overflow_sample_data = final_overflow_pattern.sample_data(longest_overflow.length, @kit.num_channels, num_tracks_in_song, overflow, false)
+      wave_data = @kit.num_channels == 1 ? [] : [[]]
+      final_overflow_pattern.track "", wave_data, "."
+      final_overflow_sample_data = final_overflow_pattern.sample_data(longest_overflow.length, @kit.num_channels, num_tracks_in_song, overflow)
       merged_sample_data = final_overflow_sample_data[:primary]
     end
 
     return merged_sample_data
   end
-  
-  def sample_data_split_all_patterns(fill_value, num_tracks_in_song)
-    output_data = {}
-    
-    offset = 0
-    overflow = {}
-    @structure.each {|pattern_name|
-      pattern_sample_length = @patterns[pattern_name].sample_length(@tick_sample_length)
-      pattern_sample_data = @patterns[pattern_name].sample_data(@tick_sample_length, @kit.num_channels, num_tracks_in_song, overflow, true)
-      
-      pattern_sample_data[:primary].keys.each {|track_name|
-        if(output_data[track_name] == nil)
-          output_data[track_name] = [].fill(fill_value, 0, self.sample_length_with_overflow())
-        end
-
-        output_data[track_name][offset...(offset + pattern_sample_length)] = pattern_sample_data[:primary][track_name]
-      }
-      
-      overflow.keys.each {|track_name|
-        if(pattern_sample_data[:primary][track_name] == nil)
-          output_data[track_name][offset...overflow[track_name].length] = overflow[track_name]
-        end
-      }
-      
-      overflow = pattern_sample_data[:overflow]
-      offset += pattern_sample_length
-    }
-
-    overflow.keys.each {|track_name|
-      output_data[track_name][offset...overflow[track_name].length] = overflow[track_name]
-    }
-
-    return output_data
-  end
-  
-  def sample_data_split_single_pattern(fill_value, num_tracks_in_song, pattern, primary_sample_length)
-    output_data = {}
-    
-    pattern_sample_length = pattern.sample_length(@tick_sample_length)
-    pattern_sample_data = pattern.sample_data(@tick_sample_length, @kit.num_channels, num_tracks_in_song, {}, true)
-    
-    pattern_sample_data[:primary].keys.each {|track_name|
-      overflow_sample_length = pattern_sample_data[:overflow][track_name].length
-      full_sample_length = pattern_sample_length + overflow_sample_length
-      output_data[track_name] = [].fill(fill_value, 0, full_sample_length)
-      output_data[track_name][0...pattern_sample_length] = pattern_sample_data[:primary][track_name]
-      output_data[track_name][pattern_sample_length...full_sample_length] = pattern_sample_data[:overflow][track_name]
-    }
-    
-    return output_data
-  end
-  
-  def sample_data_combined_all_patterns(fill_value, num_tracks_in_song)
-    output_data = [].fill(fill_value, 0, self.sample_length_with_overflow)
-
-    offset = 0
-    overflow = {}
-    @structure.each {|pattern_name|
-      pattern_sample_length = @patterns[pattern_name].sample_length(@tick_sample_length)
-      pattern_sample_data = @patterns[pattern_name].sample_data(@tick_sample_length, @kit.num_channels, num_tracks_in_song, overflow)
-      output_data[offset...offset + pattern_sample_length] = pattern_sample_data[:primary]
-      overflow = pattern_sample_data[:overflow]
-      offset += pattern_sample_length
-    }
-    
-    # Handle overflow from final pattern
-    output_data[offset...output_data.length] = merge_overflow(overflow, num_tracks_in_song)
-    return output_data
-  end
-  
-  def sample_data_combined_single_pattern(fill_value, num_tracks_in_song, pattern, primary_sample_length)
-    output_data = [].fill(fill_value, 0, pattern.sample_length_with_overflow(@tick_sample_length))
-    sample_data = pattern.sample_data(tick_sample_length, @kit.num_channels, num_tracks_in_song, {}, false)
-    output_data[0...primary_sample_length] = sample_data[:primary]
-    output_data[primary_sample_length...output_data.length] = merge_overflow(sample_data[:overflow], num_tracks_in_song)
-
-    return output_data
-  end
 end

data/lib/songoptimizer.rb

@@ -0,0 +1,154 @@
+# This class is used to transform a Song object into an equivalent Song object that
+# will be generated faster by the sound engine.
+#
+# The primary method is optimize(). Currently, it performs two optimizations:
+#
+#   1.) Breaks patterns into shorter patterns. Generating one long Pattern is generally
+#       slower than generating several short Patterns with the same combined length.
+#   2.) Replaces Patterns which are equivalent (i.e. they have the same tracks with the
+#       same rhythms) into one canonical Pattern. This allows for better caching, by
+#       preventing the sound engine from generating sample data for a Pattern when the
+#       same sample data has already been generated for a different Pattern.
+#
+# Note that step #1 actually performs double duty, because breaking Patterns into smaller
+# pieces increases the likelihood there will be duplicates that can be combined.
+class SongOptimizer
+  def initialize()
+  end
+  
+  # Returns a Song that will produce the same output as original_song, but should be
+  # generated faster.
+  def optimize(original_song, max_pattern_length)
+    # 1.) Create a new song, cloned from the original
+    optimized_song = original_song.copy_ignoring_patterns_and_structure()
+    
+    # 2.) Subdivide patterns
+    optimized_song = subdivide_song_patterns(original_song, optimized_song, max_pattern_length)
+
+    # 3.) Prune duplicate patterns
+    optimized_song = prune_duplicate_patterns(optimized_song)
+
+    return optimized_song
+  end
+
+protected  
+  
+  # Splits the patterns of a Song into smaller patterns, each one with at most
+  # max_pattern_length steps. For example, if max_pattern_length is 4, then
+  # the following pattern:
+  #
+  # track1: X...X...X.
+  # track2: ..X.....X.
+  # track3: X.X.X.X.X.
+  #
+  # will be converted into the following 3 patterns:
+  #
+  # track1: X...
+  # track2: ..X.
+  # track3: X.X.
+  #
+  # track1: X...
+  # track3: X.X.
+  #
+  # track1: X.
+  # track2: X.
+  # track3: X.
+  #
+  # Note that if a track in a sub-divided pattern has no triggers (such as track2 in the
+  # 2nd pattern above), it will not be included in the new pattern.
+  def subdivide_song_patterns(original_song, optimized_song, max_pattern_length)
+    blank_track_pattern = '.' * max_pattern_length
+    
+    # 2.) For each pattern, add a new pattern to new song every max_pattern_length ticks
+    optimized_structure = {}
+    original_song.patterns.values.each do |pattern|
+      tick_index = 0
+      optimized_structure[pattern.name] = []
+      
+      while(pattern.tracks.values.first.rhythm[tick_index] != nil) do
+        new_pattern = optimized_song.pattern("#{pattern.name}#{tick_index}".to_sym)
+        optimized_structure[pattern.name] << new_pattern.name
+        pattern.tracks.values.each do |track|
+          sub_track_pattern = track.rhythm[tick_index...(tick_index + max_pattern_length)]
+          
+          if sub_track_pattern != blank_track_pattern
+            new_pattern.track(track.name, track.wave_data, sub_track_pattern)
+          end
+        end
+        
+        # If no track has a trigger during this step pattern, add a blank track.
+        # Otherwise, this pattern will have no ticks, and no sound will be generated,
+        # causing the pattern to be "compacted away".
+        if new_pattern.tracks.empty?
+          # Track.sample_data() examines its sound's sample data to determine if it is
+          # mono or stereo. If the first item in the sample data Array is an Array,
+          # it decides stereo. That's what the [] vs. [[]] is about.
+          placeholder_wave_data = (optimized_song.kit.num_channels == 1) ? [] : [[]]          
+          
+          new_pattern.track("placeholder", placeholder_wave_data, blank_track_pattern)
+        end
+        
+        tick_index += max_pattern_length
+      end
+    end
+    
+    # 3.) Replace the Song's structure to reference the new sub-divided patterns
+    # instead of the old patterns.
+    optimized_structure = original_song.structure.map do |original_pattern|
+      optimized_structure[original_pattern]
+    end
+    optimized_song.structure = optimized_structure.flatten
+
+    return optimized_song    
+  end
+  
+  
+  # Replaces any Patterns that are duplicates (i.e., each track uses the same sound and has
+  # the same rhythm) with a single canonical pattern.
+  #
+  # The benefit of this is that it allows more effective caching. For example, suppose Pattern A
+  # and Pattern B are equivalent. If Pattern A gets generated first, it will be cached. When
+  # Pattern B gets generated, it will be generated from scratch instead of using Pattern A's
+  # cached data. Consolidating duplicates into one prevents this from happening.
+  #
+  # Duplicate Patterns are more likely to occur after calling subdivide_song_patterns().
+  def prune_duplicate_patterns(song)
+    seen_patterns = []
+    replacements = {}
+    
+    # Pattern names are sorted to ensure consistent pattern replacement. Makes tests easier to write.
+    # Sort function added manually because Ruby 1.8 doesn't know how to sort symbols...
+    pattern_names = song.patterns.keys.sort {|x, y| x.to_s <=> y.to_s }
+    
+    # Detect duplicates
+    pattern_names.each do |pattern_name|
+      pattern = song.patterns[pattern_name]
+      found_duplicate = false
+      seen_patterns.each do |seen_pattern|
+        if !found_duplicate && pattern.same_tracks_as?(seen_pattern)
+          replacements[pattern.name.to_sym] = seen_pattern.name.to_sym
+          found_duplicate = true
+        end
+      end
+      
+      if !found_duplicate
+        seen_patterns << pattern
+      end
+    end
+    
+    # Update structure to remove references to duplicates
+    new_structure = song.structure
+    replacements.each do |duplicate, replacement|
+      new_structure = new_structure.map do |pattern_name|
+        (pattern_name == duplicate) ? replacement : pattern_name
+      end
+    end
+    song.structure = new_structure
+    
+    # Remove unused Patterns. Not strictly necessary, but makes resulting songs
+    # easier to read for debugging purposes.
+    song.remove_unused_patterns()
+
+    return song
+  end
+end