beats 1.2.0 → 1.2.1

data/lib/song.rb

@@ -1,16 +1,12 @@
 class InvalidTempoError < RuntimeError; end
 
 class Song
-  SAMPLE_RATE = 44100
-  SECONDS_PER_MINUTE = 60.0
-  SAMPLES_PER_MINUTE = SAMPLE_RATE * SECONDS_PER_MINUTE
   DEFAULT_TEMPO = 120
 
-  def initialize(base_path)
+  def initialize()
     self.tempo = DEFAULT_TEMPO
-    @kit = Kit.new(base_path)
     @patterns = {}
-    @structure = []
+    @flow = []
   end
 
   # Adds a new pattern to the song, with the specified name.
@@ -19,30 +15,6 @@ class Song
     return @patterns[name]
   end
 
-  # 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
-
-  # 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
-    
-    full_sample_length = self.sample_length
-    last_pattern_sample_length = @patterns[@structure.last].sample_length(@tick_sample_length)
-    last_pattern_overflow_length = @patterns[@structure.last].sample_length_with_overflow(@tick_sample_length)
-    overflow = last_pattern_overflow_length - last_pattern_sample_length
-
-    return sample_length + overflow
-  end
   
   # 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
@@ -52,58 +24,22 @@ class Song
   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 write_to_file(output_file_name)
-    cache = {}
-    pack_code = pack_code()
-    num_tracks_in_song = self.total_tracks()
-    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
-          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
-    return @kit.num_channels
-  end
-  
-  def bits_per_sample
-    return @kit.bits_per_sample
+  # The unique track names used in each of the song's patterns. Sorted in alphabetical order.
+  # For example calling this method for this song:
+  #
+  #   Verse:
+  #     - bass:  X...
+  #     - snare: ..X.
+  #
+  #   Chorus:
+  #     - bass:  X.X.
+  #     - snare: X.X.
+  #     - hihat: XXXX
+  #
+  # Will return: ["bass", "hihat", "snare"]
+  def track_names
+    @patterns.values.inject([]) {|track_names, pattern| track_names | pattern.tracks.keys }.sort
   end
 
   def tempo
@@ -116,66 +52,98 @@ class Song
     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)
+  # Returns a new Song that is identical but with no patterns or flow.
+  def copy_ignoring_patterns_and_flow
+    copy = Song.new()
     copy.tempo = @tempo
-    copy.kit = @kit
     
     return copy
   end
+
+  # Changes the song flow to consist of playing the specified pattern once. All other patterns will
+  # be removed from the song as a side effect.
+  #
+  # pattern_to_keep - The Symbol name of the pattern to preserve.
+  #
+  # Returns nothing.
+  def remove_patterns_except(pattern_to_keep)
+    unless @patterns.has_key?(pattern_to_keep)
+      raise StandardError, "The song does not include a pattern called #{pattern_to_keep}"
+    end
+      
+    @flow = [pattern_to_keep]
+    remove_unused_patterns()
+  end
   
-  # Removes any patterns that aren't referenced in the structure.
+  # Splits a Song object into multiple Song objects, where each new
+  # Song only has 1 track. For example, if a Song has 5 tracks, this will return
+  # a hash of 5 songs, each with one of the original Song's tracks.
+  def split()
+    split_songs = {}
+    track_names = track_names()
+    
+    track_names.each do |track_name|
+      new_song = copy_ignoring_patterns_and_flow()
+      
+      @patterns.each do |name, original_pattern|
+        new_pattern = new_song.pattern(name)
+        
+        if original_pattern.tracks.has_key?(track_name)
+          original_track = original_pattern.tracks[track_name]
+          new_pattern.track(original_track.name, original_track.rhythm)
+        else
+          new_pattern.track(track_name, "." * original_pattern.step_count)
+        end
+      end
+      
+      new_song.flow = @flow
+      
+      split_songs[track_name] = new_song
+    end
+    
+    return split_songs
+  end
+  
+  # Removes any patterns that aren't referenced in the flow.
   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) }
+    # Using reject() here because for some reason select() returns an Array not a Hash.
+    @patterns.reject! {|k, pattern| !@flow.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
+  def to_yaml(kit)
     # 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 += flow_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
+  attr_reader :patterns
+  attr_accessor :flow
 
 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 }
+    return arr.inject(0) {|max_length, name| [name.to_s.length, max_length].max }
   end
 
-  def structure_to_yaml
-    yaml_output = "  Structure:\n"
-    ljust_amount = longest_length_in_array(@structure) + 1  # The +1 is for the trailing ":"
+  def flow_to_yaml
+    yaml_output = "  Flow:\n"
+    ljust_amount = longest_length_in_array(@flow) + 1  # The +1 is for the trailing ":"
     previous = nil
     count = 0
-    @structure.each do |pattern_name|
+    @flow.each do |pattern_name|
       if pattern_name == previous || previous == nil
         count += 1
       else
@@ -200,26 +168,4 @@ private
     
     return yaml_output
   end
-
-  def merge_overflow(overflow, num_tracks_in_song)
-    merged_sample_data = []
-
-    unless overflow == {}
-      longest_overflow = overflow[overflow.keys.first]
-      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)
-      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
-end
+end

data/lib/songoptimizer.rb

@@ -1,14 +1,13 @@
-# This class is used to transform a Song object into an equivalent Song object that
-# will be generated faster by the sound engine.
+# 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) 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.
+#       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.
@@ -20,7 +19,7 @@ class SongOptimizer
   # 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()
+    optimized_song = original_song.copy_ignoring_patterns_and_flow()
     
     # 2.) Subdivide patterns
     optimized_song = subdivide_song_patterns(original_song, optimized_song, max_pattern_length)
@@ -59,45 +58,42 @@ protected
   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 = {}
+    # For each pattern, add a new pattern to new song every max_pattern_length steps
+    optimized_flow = {}
     original_song.patterns.values.each do |pattern|
-      tick_index = 0
-      optimized_structure[pattern.name] = []
+      step_index = 0
+      optimized_flow[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
+      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[tick_index...(tick_index + max_pattern_length)]
+          sub_track_pattern = track.rhythm[step_index...(step_index + max_pattern_length)]
           
           if sub_track_pattern != blank_track_pattern
-            new_pattern.track(track.name, track.wave_data, sub_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 ticks, and no sound will be generated,
+        # 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?
-          # 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)
+          new_pattern.track("placeholder", blank_track_pattern)
         end
         
-        tick_index += max_pattern_length
+        step_index += max_pattern_length
       end
     end
     
-    # 3.) Replace the Song's structure to reference the new sub-divided patterns
+    # Replace the Song's flow 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]
+    optimized_flow = original_song.flow.map do |original_pattern|
+      optimized_flow[original_pattern]
     end
-    optimized_song.structure = optimized_structure.flatten
+    optimized_song.flow = optimized_flow.flatten
 
     return optimized_song    
   end
@@ -116,7 +112,7 @@ protected
     seen_patterns = []
     replacements = {}
     
-    # Pattern names are sorted to ensure consistent pattern replacement. Makes tests easier to write.
+    # 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 = song.patterns.keys.sort {|x, y| x.to_s <=> y.to_s }
     
@@ -136,14 +132,14 @@ protected
       end
     end
     
-    # Update structure to remove references to duplicates
-    new_structure = song.structure
+    # Update flow to remove references to duplicates
+    new_flow = song.flow
     replacements.each do |duplicate, replacement|
-      new_structure = new_structure.map do |pattern_name|
+      new_flow = new_flow.map do |pattern_name|
         (pattern_name == duplicate) ? replacement : pattern_name
       end
     end
-    song.structure = new_structure
+    song.flow = new_flow
     
     # Remove unused Patterns. Not strictly necessary, but makes resulting songs
     # easier to read for debugging purposes.
@@ -151,4 +147,4 @@ protected
 
     return song
   end
-end
+end

data/lib/songparser.rb

@@ -1,23 +1,37 @@
 class SongParseError < RuntimeError; end
 
+# This class is used to parse a raw YAML song definition into domain objects. These
+# domain objects can then be used by AudioEngine to generate the output sample data
+# for the song.
 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
-    Structure:
+    Flow:
       - Verse: x2
       - Chorus: x2"
   
   def initialize
   end
   
-  def parse(base_path, definition = nil)
-    raw_song_definition = canonicalize_definition(definition)
-    raw_song_components = split_raw_yaml_into_components(raw_song_definition)
+  # 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)
+    
+    # This will be coming in a future version...
+    #unless raw_song_components[:folder] == nil
+    #  base_path = raw_song_components[:folder]
+    #end
     
-    song = Song.new(base_path)
+    song = Song.new()
     
     # 1.) Set tempo
     begin
@@ -31,45 +45,36 @@ class SongParser
     # 2.) Build the kit
     begin
       kit = build_kit(base_path, raw_song_components[:kit], raw_song_components[:patterns])
-    rescue SoundNotFoundError => detail
+    rescue SoundFileNotFoundError => detail
+      raise SongParseError, "#{detail}"
+    rescue InvalidSoundFormatError => detail
       raise SongParseError, "#{detail}"
     end
-    song.kit = kit
     
     # 3.) Load patterns
     add_patterns_to_song(song, raw_song_components[:patterns])
     
-    # 4.) Set structure
-    if raw_song_components[:structure] == nil
-      raise SongParseError, "Song must have a Structure section in the header."
+    # 4.) Set flow
+    if raw_song_components[:flow] == nil
+      raise SongParseError, "Song must have a Flow section in the header."
     else
-      set_song_structure(song, raw_song_components[:structure])
+      set_song_flow(song, raw_song_components[:flow])
     end
     
-    return song
+    return song, kit
   end
   
 private
 
-  # Is "canonicalize" a word?
-  def canonicalize_definition(definition)
-    if definition.class == String
-      begin
-        raw_song_definition = YAML.load(definition)
-      rescue ArgumentError => detail
-        raise SongParseError, "Syntax error in YAML file"
-      end
-    elsif definition.class == Hash
-      raw_song_definition = definition
-    else
-      raise SongParseError, "Invalid song input"
+  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
-    
-    return raw_song_definition
-  end
 
-  def split_raw_yaml_into_components(raw_song_definition)
     raw_song_components = {}
+    warnings = []
     raw_song_components[:full_definition] = downcase_hash_keys(raw_song_definition)
     
     if raw_song_components[:full_definition]["song"] != nil
@@ -78,20 +83,34 @@ private
       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_song_components[:structure] = raw_song_components[:header]["structure"]
+    
+    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 = Kit.new(base_path)
+    kit_items = {}
     
     # Add sounds defined in the Kit section of the song header
+    # 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.add(kit_item.keys.first, kit_item.values.first)
+        kit_items[kit_item.keys.first] = kit_item.values.first
       end
     end
     
@@ -107,11 +126,14 @@ private
           track_name = track_definition.keys.first
           track_path = track_name
         
-          kit.add(track_name, track_path)
+          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
   
@@ -120,27 +142,29 @@ private
       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 Structure, 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 pattern is specified (i.e. "- foo.wav:" instead of "- foo.wav: X.X.X.X.")
+        # 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, song.kit.get_sample_data(track_name), track_definition[track_name]
+        new_pattern.track track_name, track_definition[track_name]
       end
     end
   end
   
-  def set_song_structure(song, raw_structure)
-    structure = []
+  def set_song_flow(song, raw_flow)
+    flow = []
 
-    raw_structure.each{|pattern_item|
+    raw_flow.each{|pattern_item|
       if pattern_item.class == String
         pattern_item = {pattern_item => "x1"}
       end
@@ -154,21 +178,22 @@ private
       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."
+        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 structure with "x0" repeats.
-          # This can be convenient for defining the structure before all patterns have been added to the song file.
-          raise SongParseError, "Song structure includes non-existent pattern: #{pattern_name}."
+          # 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 { structure << pattern_name_sym }
+      multiples.times { flow << pattern_name_sym }
     }
-    song.structure = structure
+    song.flow = flow
   end
     
   # Converts all hash keys to be lowercase
@@ -178,4 +203,4 @@ private
         new_hash
     end
   end
-end
+end