beats 1.2.4 → 1.2.5

data/lib/beats/songoptimizer.rb

@@ -0,0 +1,162 @@
+module Beats
+  # This class is used to transform a Song object into an equivalent Song object whose
+  # sample data will be generated faster by the audio 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) with one canonical Pattern. This allows for better caching, by
+  #       preventing the audio engine from generating the same sample data more than once.
+  #
+  # 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_flow()
+
+      # 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)
+
+      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
+
+      # For each pattern, add a new pattern to new song every max_pattern_length steps
+      optimized_flow = {}
+      original_song.patterns.values.each do |pattern|
+        step_index = 0
+        optimized_flow[pattern.name] = []
+
+        while(pattern.tracks.values.first.rhythm[step_index] != nil) do
+          # TODO: Is this pattern 100% sufficient to prevent collisions between subdivided
+          #       pattern names and existing patterns with numeric suffixes?
+          new_pattern = optimized_song.pattern("#{pattern.name}_#{step_index}".to_sym)
+          optimized_flow[pattern.name] << new_pattern.name
+          pattern.tracks.values.each do |track|
+            sub_track_pattern = track.rhythm[step_index...(step_index + max_pattern_length)]
+
+            if sub_track_pattern != blank_track_pattern
+              new_pattern.track(track.name, 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 steps, and no sound will be generated,
+          # causing the pattern to be "compacted away".
+          if new_pattern.tracks.empty?
+            new_pattern.track("placeholder", blank_track_pattern)
+          end
+
+          step_index += max_pattern_length
+        end
+      end
+
+      # Replace the Song's flow to reference the new sub-divided patterns
+      # instead of the old patterns.
+      optimized_flow = original_song.flow.map do |original_pattern|
+        optimized_flow[original_pattern]
+      end
+      optimized_song.flow = optimized_flow.flatten
+
+      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)
+      pattern_replacements = determine_pattern_replacements(song.patterns)
+
+      # Update flow to remove references to duplicates
+      new_flow = song.flow
+      pattern_replacements.each do |duplicate, replacement|
+        new_flow = new_flow.map do |pattern_name|
+          (pattern_name == duplicate) ? replacement : pattern_name
+        end
+      end
+      song.flow = new_flow
+
+      # This isn't strictly necessary, but makes resulting songs easier to read for debugging purposes.
+      song.remove_unused_patterns()
+
+      song
+    end
+
+
+    # Examines a set of patterns definitions, determining which ones have the same tracks with the same
+    # rhythms. Then constructs a hash of pattern => pattern indicating that all occurances in the flow
+    # of the key should be replaced with the value, so that the other equivalent definitions can be pruned
+    # from the song (and hence their sample data doesn't need to be generated).
+    def determine_pattern_replacements(patterns)
+      seen_patterns = []
+      replacements = {}
+
+      # Pattern names are sorted to ensure predictable pattern replacement. Makes tests easier to write.
+      # Sort function added manually because Ruby 1.8 doesn't know how to sort symbols...
+      pattern_names = patterns.keys.sort {|x, y| x.to_s <=> y.to_s }
+
+      # Detect duplicates
+      pattern_names.each do |pattern_name|
+        pattern = 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
+
+      replacements
+    end
+  end
+end

data/lib/beats/songparser.rb

@@ -0,0 +1,217 @@
+module Beats
+  class SongParseError < RuntimeError; end
+
+
+  # This class is used to parse a raw YAML song definition into domain objects (i.e.
+  # Song, Pattern, Track, and Kit). These domain objects can then be used by AudioEngine
+  # to generate the actual audio data that is saved to disk.
+  #
+  # The sole public method is parse(). It takes a raw YAML string and returns a Song and
+  # Kit object (or raises an error if the YAML string couldn't be parsed correctly).
+  class SongParser
+    DONT_USE_STRUCTURE_WARNING =
+        "\n" +
+        "WARNING! This song contains a 'Structure' section in the header.\n" +
+        "As of BEATS 1.2.1, the 'Structure' section should be renamed 'Flow'.\n" +
+        "You should change your song file, in a future version using 'Structure' will cause an error.\n"
+
+    NO_SONG_HEADER_ERROR_MSG =
+  "Song must have a header. Here's an example:
+
+    Song:
+      Tempo: 120
+      Flow:
+        - Verse: x2
+        - Chorus: x2"
+
+    def initialize
+    end
+
+
+    # Parses a raw YAML song definition and converts it into a Song and Kit object.
+    def parse(base_path, raw_yaml_string)
+      raw_song_components = hashify_raw_yaml(raw_yaml_string)
+
+      unless raw_song_components[:folder].nil?
+        base_path = raw_song_components[:folder]
+      end
+
+      song = Song.new()
+
+      # 1.) Set tempo
+      begin
+        unless raw_song_components[:tempo].nil?
+          song.tempo = raw_song_components[:tempo]
+        end
+      rescue InvalidTempoError => detail
+        raise SongParseError, "#{detail}"
+      end
+
+      # 2.) Build the kit
+      begin
+        kit = build_kit(base_path, raw_song_components[:kit], raw_song_components[:patterns])
+      rescue SoundFileNotFoundError => detail
+        raise SongParseError, "#{detail}"
+      rescue InvalidSoundFormatError => detail
+        raise SongParseError, "#{detail}"
+      end
+
+      # 3.) Load patterns
+      add_patterns_to_song(song, raw_song_components[:patterns])
+
+      # 4.) Set flow
+      if raw_song_components[:flow].nil?
+        raise SongParseError, "Song must have a Flow section in the header."
+      else
+        set_song_flow(song, raw_song_components[:flow])
+      end
+
+      return song, kit
+    end
+
+
+  private
+
+
+    def hashify_raw_yaml(raw_yaml_string)
+      begin
+        raw_song_definition = YAML.load(raw_yaml_string)
+      rescue ArgumentError => detail
+        raise SongParseError, "Syntax error in YAML file"
+      end
+
+      raw_song_components = {}
+      raw_song_components[:full_definition] = downcase_hash_keys(raw_song_definition)
+
+      unless raw_song_components[:full_definition]["song"].nil?
+        raw_song_components[:header] = downcase_hash_keys(raw_song_components[:full_definition]["song"])
+      else
+        raise SongParseError, NO_SONG_HEADER_ERROR_MSG
+      end
+      raw_song_components[:tempo]     = raw_song_components[:header]["tempo"]
+      raw_song_components[:folder]    = raw_song_components[:header]["folder"]
+      raw_song_components[:kit]       = raw_song_components[:header]["kit"]
+
+      raw_flow = raw_song_components[:header]["flow"]
+      raw_structure = raw_song_components[:header]["structure"]
+      unless raw_flow.nil?
+        raw_song_components[:flow]    = raw_flow
+      else
+        unless raw_structure.nil?
+          puts DONT_USE_STRUCTURE_WARNING
+        end
+
+        raw_song_components[:flow]    = raw_structure
+      end
+
+      raw_song_components[:patterns]  = raw_song_components[:full_definition].reject {|k, v| k == "song"}
+
+      return raw_song_components
+    end
+
+
+    def build_kit(base_path, raw_kit, raw_patterns)
+      kit_items = {}
+
+      # Add sounds defined in the Kit section of the song header
+      # Converts [{a=>1}, {b=>2}, {c=>3}] from raw YAML to {a=>1, b=>2, c=>3}
+      # TODO: Raise error is same name is defined more than once in the Kit
+      unless raw_kit.nil?
+        raw_kit.each do |kit_item|
+          kit_items[kit_item.keys.first] = kit_item.values.first
+        end
+      end
+
+      # Add sounds not defined in Kit section, but used in individual tracks
+      # TODO Investigate detecting duplicate keys already defined in the Kit section, as this could possibly
+      # result in a performance improvement when the sound has to be converted to a different bit rate/num channels,
+      # as well as use less memory.
+      raw_patterns.keys.each do |key|
+        track_list = raw_patterns[key]
+
+        unless track_list.nil?
+          track_list.each do |track_definition|
+            track_name = track_definition.keys.first
+            track_path = track_name
+
+            if track_name != Pattern::FLOW_TRACK_NAME && kit_items[track_name].nil?
+              kit_items[track_name] = track_path
+            end
+          end
+        end
+      end
+
+      Kit.new(base_path, kit_items)
+    end
+
+
+    def add_patterns_to_song(song, raw_patterns)
+      raw_patterns.keys.each do |key|
+        new_pattern = song.pattern key.to_sym
+
+        track_list = raw_patterns[key]
+        # TODO Also raise error if only there is only 1 track and it's a flow track
+        if track_list.nil?
+          # TODO: Use correct capitalization of pattern name in error message
+          # TODO: Possibly allow if pattern not referenced in the Flow, or has 0 repeats?
+          raise SongParseError, "Pattern '#{key}' has no tracks. It needs at least one."
+        end
+
+        # TODO: What if there is more than one flow? Raise error, or have last one win?
+        track_list.each do |track_definition|
+          track_name = track_definition.keys.first
+
+          # Handle case where no track rhythm is specified (i.e. "- foo.wav:" instead of "- foo.wav: X.X.X.X.")
+          track_definition[track_name] ||= ""
+
+          new_pattern.track track_name, track_definition[track_name]
+        end
+      end
+    end
+
+
+    def set_song_flow(song, raw_flow)
+      flow = []
+
+      raw_flow.each{|pattern_item|
+        if pattern_item.class == String
+          pattern_item = {pattern_item => "x1"}
+        end
+
+        pattern_name = pattern_item.keys.first
+        pattern_name_sym = pattern_name.downcase.to_sym
+
+        # Convert the number of repeats from a String such as "x4" into an integer such as 4.
+        multiples_str = pattern_item[pattern_name]
+        multiples_str.slice!(0)
+        multiples = multiples_str.to_i
+
+        unless multiples_str.match(/[^0-9]/).nil?
+          raise SongParseError,
+                "'#{multiples_str}' is an invalid number of repeats for pattern '#{pattern_name}'. Number of repeats should be a whole number."
+        else
+          if multiples < 0
+            raise SongParseError, "'#{multiples_str}' is an invalid number of repeats for pattern '#{pattern_name}'. Must be 0 or greater."
+          elsif multiples > 0 && !song.patterns.has_key?(pattern_name_sym)
+            # This test is purposefully designed to only throw an error if the number of repeats is greater
+            # than 0. This allows you to specify an undefined pattern in the flow with "x0" repeats.
+            # This can be convenient for defining the flow before all patterns have been added to the song file.
+            raise SongParseError, "Song flow includes non-existent pattern: #{pattern_name}."
+          end
+        end
+
+        multiples.times { flow << pattern_name_sym }
+      }
+      song.flow = flow
+    end
+
+
+    # Converts all hash keys to be lowercase
+    def downcase_hash_keys(hash)
+      return hash.inject({}) do |new_hash, pair|
+          new_hash[pair.first.downcase] = pair.last
+          new_hash
+      end
+    end
+  end
+end

data/lib/beats/track.rb

@@ -0,0 +1,57 @@
+module Beats
+  class InvalidRhythmError < RuntimeError; end
+
+
+  # Domain object which models a kit sound playing a rhythm. For example,
+  # a bass drum playing every quarter note for two measures.
+  #
+  # This object is like sheet music; the AudioEngine is responsible creating actual
+  # audio data for a Track (with the help of a Kit).
+  class Track
+    REST = "."
+    BEAT = "X"
+    BARLINE = "|"
+
+    def initialize(name, rhythm)
+      # TODO: Add validation for input parameters
+      @name = name
+      self.rhythm = rhythm
+    end
+
+    # TODO: What to have this invoked when setting like this?
+    #   track.rhythm[x..y] = whatever
+    def rhythm=(rhythm)
+      @rhythm = rhythm.delete(BARLINE)
+      beats = []
+
+      beat_length = 0
+      #rhythm.each_char{|ch|
+      @rhythm.each_byte do |ch|
+        ch = ch.chr
+        if ch == BEAT
+          beats << beat_length
+          beat_length = 1
+        elsif ch == REST
+          beat_length += 1
+        else
+          raise InvalidRhythmError, "Track #{@name} has an invalid rhythm: '#{rhythm}'. Can only contain '#{BEAT}', '#{REST}' or '#{BARLINE}'"
+        end
+      end
+
+      if beat_length > 0
+        beats << beat_length
+      end
+      if beats == []
+        beats = [0]
+      end
+      @beats = beats
+    end
+
+    def step_count
+      @rhythm.length
+    end
+
+    attr_accessor :name
+    attr_reader :rhythm, :beats
+  end
+end

data/lib/wavefile/cachingwriter.rb

@@ -30,7 +30,7 @@ module WaveFile
       end
 
       @file.syswrite(packed_buffer_data[:data])
-      @samples_written += packed_buffer_data[:sample_count]
+      @total_sample_frames += packed_buffer_data[:sample_count]
     end
   end
 end

data/test/audioengine_test.rb

@@ -28,15 +28,15 @@ class AudioEngineTest < Test::Unit::TestCase
     test_engines = {}
     base_path = File.dirname(__FILE__) + "/.."
     song_parser = SongParser.new()
-    
+
     test_engines[:blank] = AudioEngine.new(Song.new(), Kit.new(base_path, {}))
 
     FIXTURES.each do |fixture_name|
       song, kit = song_parser.parse(base_path, File.read("test/fixtures/valid/#{fixture_name}.txt"))
       test_engines[fixture_name] = AudioEngine.new(song, kit)
     end
-     
-    return test_engines 
+
+    test_engines
   end
 
   def test_initialize
@@ -142,7 +142,7 @@ class AudioEngineTest < Test::Unit::TestCase
       #helper_generate_track_sample_data kit, "XX", 1, [-100, -100], [200, 300, -400]
 
       # 3C.) Tick sample length is shorter than the sound sample data, but not by an integer amount.
-      # 
+      #
       # Each step of 1.83 samples should end on the following boundaries:
       # Tick:               1,    2,    3,    4,    5,     6
       # Raw:        0.0, 1.83, 3.66, 5.49, 7.32, 9.15, 10.98
@@ -162,7 +162,7 @@ class AudioEngineTest < Test::Unit::TestCase
     engine = MockAudioEngine.new(Song.new(), kit)
     engine.step_sample_length = step_sample_length
     actual = engine.generate_track_sample_data(track, kit.get_sample_data("S"))
-    
+
     assert_equal(Hash,                     actual.class)
     assert_equal(["overflow", "primary"],  actual.keys.map{|key| key.to_s}.sort)
     assert_equal(expected_primary,         actual[:primary])