beats 1.2.4 → 1.2.5

data/lib/songoptimizer.rb

@@ -1,160 +0,0 @@
-# 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)
-
-    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
-    
-    # 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
-
-    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)
-    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()
-
-    return 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
-
-    return replacements
-  end
-end

data/lib/songparser.rb

@@ -1,216 +0,0 @@
-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
-      if 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)
-    
-    if 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"]
-    if raw_flow != nil
-      raw_song_components[:flow]    = raw_flow
-    else
-      if 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 = Kit.new(base_path, kit_items)
-    return kit
-  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

data/lib/track.rb

@@ -1,55 +0,0 @@
-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