beats 1.2.0 → 1.2.1

data/lib/kit.rb

@@ -1,93 +1,93 @@
 # Raised when trying to load a sound file which can't be found at the path specified
-class SoundNotFoundError < RuntimeError; end
+class SoundFileNotFoundError < RuntimeError; end
 
-# This class keeps track of the sounds that are used in a song. It provides a
-# central place for storing sound data, and most usefully, handles converting
-# sounds in different formats to a standard format.
-# 
-# For example, if a song requires a sound that is mono/8-bit, another that is
-# stereo/8-bit, and another that is stereo/16-bit, it can't mix them together
-# because they are in different formats. Kit however automatically handles the
-# details of converting them to a common format. If you add sounds to the kit
-# using add(), sounds that you get using get_sample_data() will be in a common
-# format.
+# Raised when trying to load a sound file which either isn't actually a sound file, or
+# is in an unsupported format.
+class InvalidSoundFormatError < RuntimeError; end
+
+
+# This class provides a repository for the sounds used in a song. Most usefully, it
+# also handles converting the sounds to a common format. For example, if a song requires
+# a sound that is mono/8-bit, another that is stereo/8-bit, and another that is
+# stereo/16-bit, they have to be converted to a common format before they can be used
+# together. Kit handles this conversion; all sounds retrieved using
+# get_sample_data() will be in a common format.
+#
+# Sounds can only be added at initialization. During initialization, the sample data
+# for each sound is loaded into memory, and converted to the common format if necessary.
+# This format is:
+#
+#   Bits per sample: 16
+#   Sample rate:     44100
+#   Channels:        Stereo, unless all of the kit sounds are mono.
 #
-# All sounds returned by get_sample_data() will be 16-bit. All sounds will be
-# either mono or stereo; if at least one added sound is stereo then all sounds
-# will be stereo. So for example if a mono/8-bit, stereo/8-bit, and stereo/16-bit
-# sound are added, when you retrieve each one using get_sample_data() they will
-# be stereo/16-bit.
+# For example if the kit has these sounds:
 #
-# Note that this means that each time a new sound is added to the Kit, the common
-# format might change, if the incoming sound has a greater number of channels than
-# any of the previously added sounds. Therefore, all of the sounds
-# used by a Song should be added to the Kit before generation begins. If you
-# create Song objects by using SongParser, this will be taken care of for you (as
-# long as you don't modify the Kit afterward).
+#   my_sound_1.wav:  mono, 16-bit
+#   my_sound_2.wav:  stereo, 8-bit
+#   my_sound_3.wav:  mono, 8-bit
+#
+# they will all be converted to stereo/16-bit during initialization.
 class Kit
-  PATH_SEPARATOR = File.const_get("SEPARATOR")
-  
-  # Creates a new Kit object. base_path indicates the folder from which sound files
-  # with relative file paths will be loaded from.
-  def initialize(base_path)
+  def initialize(base_path, kit_items)
     @base_path = base_path
     @label_mappings = {}
-    @sounds = {}
+    @sound_bank = {}
     @num_channels = 1
     @bits_per_sample = 16  # Only use 16-bit files as output. Supporting 8-bit output
                            # means extra complication for no real gain (I'm skeptical
-                           # anyone would explicitly want 8-bit output instead of 16-bit.
+                           # anyone would explicitly want 8-bit output instead of 16-bit).
+                           
+    load_sounds(base_path, kit_items)
   end
   
-  # Adds a new sound to the kit. 
-  def add(name, path)
-    unless @sounds.has_key? name
-      path_is_absolute = path.start_with?(PATH_SEPARATOR)
-      if path_is_absolute
-        full_path = path
-      else
-        full_path = @base_path + PATH_SEPARATOR + path
-      end
-      
-      begin
-        wavefile = WaveFile.open(full_path)
-      rescue
-        # TODO: Raise different error if sound is in an unsupported format
-        raise SoundNotFoundError, "Sound file #{full_path} not found."
-      end
-      
-      @sounds[name] = wavefile
-      if name != path
-        @label_mappings[name] = path
-      end
-    
-      if wavefile.num_channels > @num_channels
-        @num_channels = wavefile.num_channels
-      end
+  # Returns the sample data for a sound contained in the Kit. If the all sounds in the
+  # kit are mono, then this will be a flat Array of Fixnums between -32768 and 32767.
+  # Otherwise, this will be an Array of Fixnums pairs between -32768 and 32767.
+  #
+  # label - The name of the sound to get sample data for. If the sound was defined in
+  #         the Kit section of a song file, this will generally be a descriptive label
+  #         such as "bass" or "snare". If defined in a track but not the kit, it will
+  #         generally be a file name such as "my_sounds/hihat/hi_hat.wav".
+  #
+  # Examples
+  #
+  #   # If @num_channels is 1, a flat Array of Fixnums:
+  #   get_sample_data("bass")
+  #   # => [154, 7023, 8132, 2622, -132, 34, ..., -6702]
+  #
+  #   # If @num_channels is 2, a Array of Fixnums pairs:
+  #   get_sample_data("snare")
+  #   # => [[57, 1265], [-452, 10543], [-2531, 12643], [-6372, 11653], ..., [5482, 25673]]
+  #
+  # Returns the sample data Array for the sound bound to label.
+  def get_sample_data(label)
+    if label == "placeholder"
+      return []
     end
-  end
-  
-  # Returns the sample data (as an Array) for a sound contained in the Kit.
-  # Raises an error if the sound doesn't exist in the Kit.
-  def get_sample_data(name)
-    wavefile = @sounds[name]
+
+    sample_data = @sound_bank[label]
     
-    if wavefile == nil
-      raise StandardError, "Kit doesn't contain sound '#{name}'."
+    if sample_data == nil
+      # TODO: Should we really throw an exception here rather than just returning nil?
+      raise StandardError, "Kit doesn't contain sound '#{label}'."
     else
-      wavefile.num_channels = @num_channels
-      wavefile.bits_per_sample = @bits_per_sample
-
-      return wavefile.sample_data
+      return sample_data
     end
   end
   
-  # Returns the number of sounds currently contained in the kit.
-  def size
-    return @sounds.length
+  def scale!(scale_factor)
+    @sound_bank.each do |label, sample_array|
+      @sound_bank[label] = AudioUtils.scale(sample_array, @num_channels, scale_factor)
+    end
   end
-  
-  # Produces nicer looking output than the default version of to_yaml().
+
+  # Returns a YAML representation of the Kit. Produces nicer looking output than the default version
+  # of to_yaml().
+  #
+  # indent_space_count - The number of spaces to indent each line in the output (default: 0).
+  #
+  # Returns a String representation of the Kit in YAML format.
   def to_yaml(indent_space_count = 0)
     yaml = ""
     longest_label_mapping_length =
@@ -107,4 +107,81 @@ class Kit
   end
   
   attr_reader :base_path, :label_mappings, :bits_per_sample, :num_channels
+  
+private
+
+  def load_sounds(base_path, kit_items)
+    # Set label mappings
+    kit_items.each do |label, sound_file_names|
+      if sound_file_names.class == Array
+        raise StandardError, "Composite sounds aren't allowed (yet...)"
+      end
+
+      unless label == sound_file_names
+        @label_mappings[label] = sound_file_names
+      end
+    end
+    
+    kit_items = make_file_names_absolute(kit_items)
+    raw_sounds = load_raw_sounds(kit_items)
+    
+    # Convert each sound to a common format
+    raw_sounds.values.each do |wavefile|
+      wavefile.num_channels = @num_channels
+      wavefile.bits_per_sample = @bits_per_sample
+    end
+    
+    # If necessary, mix component sounds into a composite
+    kit_items.each do |label, sound_file_names|
+      @sound_bank[label] = mixdown(sound_file_names, raw_sounds)
+    end
+  end
+  
+  def get_absolute_path(base_path, sound_file_name)
+    path_is_absolute = sound_file_name.start_with?(File::SEPARATOR)
+    return path_is_absolute ? sound_file_name : (base_path + File::SEPARATOR + sound_file_name)
+  end
+  
+  def make_file_names_absolute(kit_items)
+    kit_items.each do |label, sound_file_names|
+      unless sound_file_names.class == Array
+        sound_file_names = [sound_file_names]
+      end
+      
+      sound_file_names.map! {|sound_file_name| get_absolute_path(base_path, sound_file_name)}  
+      kit_items[label] = sound_file_names
+    end
+    
+    return kit_items
+  end
+  
+  # Load all sound files, bailing if any are invalid
+  def load_raw_sounds(kit_items)
+    raw_sounds = {}
+    kit_items.values.flatten.each do |sound_file_name|
+      begin
+        wavefile = WaveFile.open(sound_file_name)
+      rescue Errno::ENOENT
+        raise SoundFileNotFoundError, "Sound file #{sound_file_name} not found."
+      rescue StandardError
+        raise InvalidSoundFormatError, "Sound file #{sound_file_name} is either not a sound file, " +
+                                       "or is in an unsupported format. BEATS can handle 8 or 16-bit *.wav files."
+      end
+      @num_channels = [@num_channels, wavefile.num_channels].max
+      raw_sounds[sound_file_name] = wavefile
+    end
+    
+    return raw_sounds
+  end
+  
+  def mixdown(sound_file_names, raw_sounds)
+    sample_arrays = []    
+    sound_file_names.each do |sound_file_name|
+      sample_arrays << raw_sounds[sound_file_name].sample_data
+    end
+
+    composited_sample_data = AudioUtils.composite(sample_arrays, @num_channels)
+
+    return AudioUtils.scale(composited_sample_data, @num_channels, sound_file_names.length)
+  end
 end

data/lib/pattern.rb

@@ -1,18 +1,21 @@
 class Pattern
+  FLOW_TRACK_NAME = "flow"
+  
   def initialize(name)
     @name = name
     @tracks = {}
   end
   
   # Adds a new track to the pattern.
-  def track(name, wave_data, rhythm)
-    new_track = Track.new(name, wave_data, rhythm)        
-    @tracks[new_track.name] = new_track
-    
+  def track(name, rhythm)
+    track_key = unique_track_name(name)
+    new_track = Track.new(name, rhythm)        
+    @tracks[track_key] = new_track
+
     # If the new track is longer than any of the previously added tracks,
     # pad the other tracks with trailing . to make them all the same length.
     # Necessary to prevent incorrect overflow calculations for tracks.
-    longest_track_length = tick_count()
+    longest_track_length = step_count()
     @tracks.values.each do |track|
       if track.rhythm.length < longest_track_length
         track.rhythm += "." * (longest_track_length - track.rhythm.length)
@@ -22,33 +25,9 @@ class Pattern
     return new_track
   end
   
-  # The number of samples required for the pattern at the given tempo. DOES NOT include samples
-  # necessary for sound that overflows past the last tick of the pattern.
-  def sample_length(tick_sample_length)
-    @tracks.keys.collect {|track_name| @tracks[track_name].sample_length(tick_sample_length) }.max || 0
-  end
-  
-  # The number of samples required for the pattern at the given tempo. Include sound overflow
-  # past the last tick of the pattern.
-  def sample_length_with_overflow(tick_sample_length)
-    @tracks.keys.collect {|track_name| @tracks[track_name].sample_length_with_overflow(tick_sample_length) }.max || 0
-  end
-  
-  def tick_count
+  def step_count
     return @tracks.values.collect {|track| track.rhythm.length }.max || 0
   end
-    
-  def sample_data(tick_sample_length, num_channels, num_tracks_in_song, incoming_overflow)
-    primary_sample_data, overflow_sample_data = generate_main_sample_data(tick_sample_length, num_channels)
-    primary_sample_data, overflow_sample_data = handle_incoming_overflow(tick_sample_length,
-                                                                         num_channels,
-                                                                         incoming_overflow,
-                                                                         primary_sample_data,
-                                                                         overflow_sample_data)
-    primary_sample_data = mixdown_sample_data(num_channels, num_tracks_in_song, primary_sample_data)
-    
-    return {:primary => primary_sample_data, :overflow => overflow_sample_data}
-  end
   
   # Returns whether or not this pattern has the same number of tracks as other_pattern, and that
   # each of the tracks has the same name and rhythm. Ordering of tracks does not matter; will
@@ -86,93 +65,17 @@ class Pattern
   
 private
 
-  def generate_main_sample_data(tick_sample_length, num_channels)
-    track_names = @tracks.keys
-    primary_sample_data = []
-    overflow_sample_data = {}
-    actual_sample_length = sample_length(tick_sample_length)
-  
-    if @intermediate_cache == nil
-      track_names.each do |track_name|
-        temp = @tracks[track_name].sample_data(tick_sample_length)
-    
-        if primary_sample_data == []
-          primary_sample_data = temp[:primary]
-          overflow_sample_data[track_name] = temp[:overflow]
-        else
-          track_samples = temp[:primary]
-          if num_channels == 1
-            track_samples.length.times {|i| primary_sample_data[i] += track_samples[i] }
-          else
-            track_samples.length.times do |i|
-              primary_sample_data[i] = [primary_sample_data[i][0] + track_samples[i][0],
-                                        primary_sample_data[i][1] + track_samples[i][1]]
-            end
-          end
-
-          overflow_sample_data[track_name] = temp[:overflow]
-        end
-      end
-    
-      @intermediate_cache = {:primary => primary_sample_data.dup, :overflow => overflow_sample_data.dup}
-    else
-      primary_sample_data = @intermediate_cache[:primary].dup
-      overflow_sample_data = @intermediate_cache[:overflow].dup
+  # Returns a unique track name that is not already in use by a track in
+  # this pattern. Used to help support having multiple tracks with the same
+  # sample in a track.
+  def unique_track_name(name)
+    i = 2
+    name_key = name
+    while @tracks.has_key? name_key
+      name_key = "#{name}#{i.to_s}"
+      i += 1
     end
-  
-    return primary_sample_data, overflow_sample_data
-  end
-
-  def handle_incoming_overflow(tick_sample_length, num_channels, incoming_overflow, primary_sample_data, overflow_sample_data)
-    track_names = @tracks.keys
-  
-    # Add overflow from previous pattern
-    incoming_overflow.keys.each do |track_name|
-      num_incoming_overflow_samples = incoming_overflow[track_name].length
     
-      if num_incoming_overflow_samples > 0
-        if track_names.member?(track_name)
-          # TODO: Does this handle situations where track has a .... rhythm and overflow is
-          # longer than track length?
-        
-          intro_length = @tracks[track_name].intro_sample_length(tick_sample_length)
-          if num_incoming_overflow_samples > intro_length
-            num_incoming_overflow_samples = intro_length
-          end
-        else
-          # If incoming overflow for track is longer than the pattern length, only add the first part of
-          # the overflow to the pattern, and add the remainder to overflow_sample_data so that it gets
-          # handled by the next pattern to be generated.
-          if num_incoming_overflow_samples > primary_sample_data.length
-            overflow_sample_data[track_name] = (incoming_overflow[track_name])[primary_sample_data.length...num_incoming_overflow_samples]
-            num_incoming_overflow_samples = primary_sample_data.length
-          end
-        end
-      
-        if num_channels == 1
-          num_incoming_overflow_samples.times {|i| primary_sample_data[i] += incoming_overflow[track_name][i]}
-        else
-          num_incoming_overflow_samples.times do |i|
-            primary_sample_data[i] = [primary_sample_data[i][0] + incoming_overflow[track_name][i][0],
-                                      primary_sample_data[i][1] + incoming_overflow[track_name][i][1]]
-          end
-        end
-      end
-    end
-  
-    return primary_sample_data, overflow_sample_data
-  end
-
-  def mixdown_sample_data(num_channels, num_tracks_in_song, primary_sample_data)
-    # Mix down the pattern's tracks into one single track
-    if num_tracks_in_song > 1
-      if num_channels == 1
-        primary_sample_data = primary_sample_data.map {|sample| sample / num_tracks_in_song }
-      else
-        primary_sample_data = primary_sample_data.map {|sample| [sample[0] / num_tracks_in_song, sample[1] / num_tracks_in_song]}
-      end
-    end
-  
-    return primary_sample_data
+    return name_key
   end
-end
+end

data/lib/patternexpander.rb

@@ -0,0 +1,111 @@
+class InvalidFlowError < RuntimeError; end
+
+# This class is used for an experimental feature that allows specifying repeats inside of
+# individual patterns, instead of the song flow. This feature is currently disabled, so for
+# the time being this class is dead code.
+#
+# TODO: The expand_pattern method in this class should probably be moved to the Pattern class.
+# This class would then go away.
+class PatternExpander
+  BARLINE = "|"
+  TICK = "-"
+  REPEAT_FRAME_REGEX = /:[-]*:[0-9]*/
+  NUMBER_REGEX = /[0-9]+/
+  
+  # TODO: What should happen if flow is longer than pattern?
+  # Either ignore extra flow, or add trailing .... to each track to match up?
+  def self.expand_pattern(flow, pattern)
+    unless self.valid_flow? flow
+      raise InvalidFlowError, "Invalid flow"
+    end
+    
+    flow = flow.delete(BARLINE)
+    
+    # Count number of :
+    # If odd, then there's an implicit : at the beginning of the pattern.
+    # TODO: What if the first character in the flow is already :
+    #       That means repeat the first step twice, right?
+    number_of_colons = flow.scan(/:/).length
+    if number_of_colons % 2 == 1
+      # TODO: What if flow[0] is not '-'
+      flow[0] = ":"  # Make the implicit : at the beginning explicit
+    end
+    
+    repeat_frames = parse_flow_for_repeat_frames(flow)
+    
+    repeat_frames.reverse.each do |frame|
+      pattern.tracks.each do |name, track|
+        range = frame[:range]
+        
+        # WARNING: Don't change the three lines below to:
+        #   track.rhythm[range] = whatever
+        # When changing the rhythm like this, rhythm=() won't be called,
+        # and Track.beats won't be updated as a result.
+        new_rhythm = track.rhythm
+        new_rhythm[range] = new_rhythm[range] * frame[:repeats]
+        track.rhythm = new_rhythm
+      end
+    end
+    
+    return pattern
+  end
+  
+  # TODO: Return more specific info on why flow isn't valid
+  def self.valid_flow?(flow)
+    flow = flow.delete(BARLINE)
+    flow = flow.delete(TICK)
+    
+    # If flow contains any characters other than : and [0-9], it's invalid.
+    if flow.match(/[^:0-9]/) != nil
+      return false
+    end
+    
+    # If flow contains nothing but :, it's always valid.
+    if flow == ":" * flow.length
+      return true
+    end
+    
+    # If flow DOESN'T contain a :, it's not valid.
+    if flow.match(/:/) == nil
+      return false
+    end
+    
+    segments = flow.split(/[0-9]+/)
+    
+    # Ignore first segment
+    segments[1...segments.length].each do |segment|
+      if segment.length % 2 == 1
+        return false
+      end
+    end
+    
+    return true
+  end
+  
+private
+
+  def self.parse_flow_for_repeat_frames(flow)
+    repeat_frames = []
+    lower_bound = 0
+    frame_start_index = flow[lower_bound...flow.length] =~ REPEAT_FRAME_REGEX
+    while frame_start_index != nil do
+      str = flow[lower_bound...flow.length].match(REPEAT_FRAME_REGEX).to_s
+      
+      range_start = lower_bound + frame_start_index
+      range_end = range_start + str.length - 1
+      
+      num_repeats = str.match(NUMBER_REGEX).to_s
+      num_repeats = (num_repeats == "") ? 2 : num_repeats.to_i
+      
+      repeat_frame = {}
+      repeat_frame[:range] = range_start..range_end
+      repeat_frame[:repeats] = num_repeats
+      repeat_frames << repeat_frame
+      
+      lower_bound += frame_start_index + str.length
+      frame_start_index = flow[lower_bound...flow.length] =~ REPEAT_FRAME_REGEX
+    end
+    
+    return repeat_frames
+  end
+end