beats 1.2.4 → 1.2.5

data/lib/beats/beatsrunner.rb

@@ -0,0 +1,76 @@
+module Beats
+  class BeatsRunner
+    # Each pattern in the song will be split up into sub patterns that have at most this many steps.
+    # In general, audio for several shorter patterns can be generated more quickly than for one long
+    # pattern, and can also be cached more effectively.
+    OPTIMIZED_PATTERN_LENGTH = 4
+
+    def initialize(input_file_name, output_file_name, options)
+      @input_file_name =  input_file_name
+
+      if output_file_name.nil?
+        output_file_name = File.basename(input_file_name, File.extname(input_file_name)) + ".wav"
+      end
+      @output_file_name = output_file_name
+
+      @options = options
+    end
+
+    def run
+      base_path = @options[:base_path] || File.dirname(@input_file_name)
+      song, kit = SongParser.new().parse(base_path, File.read(@input_file_name))
+
+      song = normalize_for_pattern_option(song)
+      songs_to_generate = normalize_for_split_option(song)
+
+      song_optimizer = SongOptimizer.new()
+      durations = songs_to_generate.collect do |output_file_name, song|
+        song = song_optimizer.optimize(song, OPTIMIZED_PATTERN_LENGTH)
+        AudioEngine.new(song, kit).write_to_file(output_file_name)
+      end
+
+      {:duration => durations.last}
+    end
+
+  private
+
+    # If the -p option is used, transform the song into one whose flow consists of
+    # playing that single pattern once.
+    def normalize_for_pattern_option(song)
+      unless @options[:pattern].nil?
+        pattern_name = @options[:pattern].downcase.to_sym
+
+        unless song.patterns.has_key?(pattern_name)
+          raise StandardError, "The song does not include a pattern called #{pattern_name}"
+        end
+
+        song.flow = [pattern_name]
+        song.remove_unused_patterns()
+      end
+
+      song
+    end
+
+    # Returns a hash of file name => song object for each song that should go through the audio engine
+    def normalize_for_split_option(song)
+      songs_to_generate = {}
+
+      if @options[:split]
+        split_songs = song.split()
+        split_songs.each do |track_name, split_song|
+          # TODO: Move building the output file name into its own method?
+          extension = File.extname(@output_file_name)
+          file_name = File.dirname(@output_file_name) + "/" +
+                      File.basename(@output_file_name, extension) + "-" + File.basename(track_name, extension) +
+                      extension
+
+          songs_to_generate[file_name] = split_song
+        end
+      else
+        songs_to_generate[@output_file_name] = song
+      end
+
+      songs_to_generate
+    end
+  end
+end

data/lib/beats/kit.rb

@@ -0,0 +1,187 @@
+module Beats
+  # Raised when trying to load a sound file which can't be found at the path specified
+  class SoundFileNotFoundError < RuntimeError; end
+
+  # 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.
+  #
+  # For example if the kit has these sounds:
+  #
+  #   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
+    def initialize(base_path, kit_items)
+      @base_path = base_path
+      @label_mappings = {}
+      @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).
+
+      load_sounds(base_path, kit_items)
+    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
+
+      sample_data = @sound_bank[label]
+
+      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
+        return sample_data
+      end
+    end
+
+    def scale!(scale_factor)
+      @sound_bank.each do |label, sample_array|
+        @sound_bank[label] = AudioUtils.scale(sample_array, @num_channels, scale_factor)
+      end
+    end
+
+    # 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 =
+        @label_mappings.keys.inject(0) do |max_length, name|
+          (name.to_s.length > max_length) ? name.to_s.length : max_length
+        end
+
+      if @label_mappings.length > 0
+        yaml += " " * indent_space_count + "Kit:\n"
+        ljust_amount = longest_label_mapping_length + 1  # The +1 is for the trailing ":"
+        @label_mappings.sort.each do |label, path|
+          yaml += " " * indent_space_count + "  - #{(label + ":").ljust(ljust_amount)}  #{path}\n"
+        end
+      end
+
+      yaml
+    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)
+      sound_buffers = load_raw_sounds(kit_items)
+
+      canonical_format = WaveFile::Format.new(@num_channels, @bits_per_sample, 44100)
+
+      # Convert each sound to a common format
+      sound_buffers.each {|file_name, buffer| sound_buffers[file_name] = buffer.convert(canonical_format) }
+
+      # If necessary, mix component sounds into a composite
+      kit_items.each do |label, sound_file_names|
+        @sound_bank[label] = mixdown(sound_file_names, sound_buffers)
+      end
+    end
+
+    # Converts relative paths into absolute paths. Note that this will also handle
+    # expanding ~ on platforms that support that.
+    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| File.expand_path(sound_file_name, base_path) }
+        kit_items[label] = sound_file_names
+      end
+
+      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
+          info = WaveFile::Reader.info(sound_file_name)
+          WaveFile::Reader.new(sound_file_name).each_buffer(info.sample_frame_count) do |buffer|
+            raw_sounds[sound_file_name] = buffer
+            @num_channels = [@num_channels, buffer.channels].max
+          end
+        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, 16, 24, or 32-bit PCM *.wav files."
+        end
+      end
+
+      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].samples
+      end
+
+      composited_sample_data = AudioUtils.composite(sample_arrays, @num_channels)
+
+      AudioUtils.scale(composited_sample_data, @num_channels, sound_file_names.length)
+    end
+  end
+end

data/lib/beats/pattern.rb

@@ -0,0 +1,88 @@
+module Beats
+  # Domain object which models one or more Tracks playing a part of the song at the same time.
+  # For example, a bass drum, snare drum, and hi-hat track playing the song's chorus.
+  #
+  # This object is like sheet music; the AudioEngine is responsible creating actual
+  # audio data for a Pattern (with the help of a Kit).
+  class Pattern
+    FLOW_TRACK_NAME = "flow"
+
+    def initialize(name)
+      @name = name
+      @tracks = {}
+    end
+
+    # Adds a new track to the pattern.
+    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 = step_count()
+      @tracks.values.each do |track|
+        if track.rhythm.length < longest_track_length
+          track.rhythm += "." * (longest_track_length - track.rhythm.length)
+        end
+      end
+
+      new_track
+    end
+
+    def step_count
+      @tracks.values.collect {|track| track.rhythm.length }.max || 0
+    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
+    # return true if the two patterns have the same tracks but in a different ordering.
+    def same_tracks_as?(other_pattern)
+      @tracks.keys.each do |track_name|
+        other_pattern_track = other_pattern.tracks[track_name]
+        if other_pattern_track.nil? || @tracks[track_name].rhythm != other_pattern_track.rhythm
+          return false
+        end
+      end
+
+      @tracks.length == other_pattern.tracks.length
+    end
+
+    # Returns a YAML representation of the Pattern. Produces nicer looking output than the default
+    # version of to_yaml().
+    def to_yaml
+      longest_track_name_length =
+        @tracks.keys.inject(0) do |max_length, name|
+          (name.to_s.length > max_length) ? name.to_s.length : max_length
+        end
+      ljust_amount = longest_track_name_length + 7
+
+      yaml = "#{@name.to_s.capitalize}:\n"
+      @tracks.keys.sort.each do |track_name|
+        yaml += "  - #{track_name}:".ljust(ljust_amount)
+        yaml += "#{@tracks[track_name].rhythm}\n"
+      end
+
+      yaml
+    end
+
+    attr_accessor :tracks, :name
+
+  private
+
+    # 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
+
+      name_key
+    end
+  end
+end

data/lib/beats/song.rb

@@ -0,0 +1,162 @@
+module Beats
+  class InvalidTempoError < RuntimeError; end
+
+
+  # Domain object which models the 'sheet music' for a full song. Models the Patterns
+  # that should be played, in which order (i.e. the flow), and at which tempo.
+  #
+  # This is the top-level model object that is used by the AudioEngine to produce
+  # actual audio data. A Song tells the AudioEngine what sounds to trigger and when.
+  # A Kit provides the sample data for each of these sounds. With a Song and a Kit
+  # the AudioEngine can produce the audio data that is saved to disk.
+  class Song
+    DEFAULT_TEMPO = 120
+
+    def initialize
+      self.tempo = DEFAULT_TEMPO
+      @patterns = {}
+      @flow = []
+    end
+
+    # Adds a new pattern to the song, with the specified name.
+    def pattern(name)
+      @patterns[name] = Pattern.new(name)
+      @patterns[name]
+    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
+    # 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
+
+    # 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=(new_tempo)
+      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
+    end
+
+    # 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
+    end
+
+    # 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
+
+      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.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(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 += flow_to_yaml()
+      yaml_output += kit.to_yaml(2)
+      yaml_output += patterns_to_yaml()
+
+      yaml_output
+    end
+
+    attr_reader :patterns, :tempo
+    attr_accessor :flow
+
+  private
+
+    def longest_length_in_array(arr)
+      arr.inject(0) {|max_length, name| [name.to_s.length, max_length].max }
+    end
+
+    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
+      @flow.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"
+
+      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
+
+      yaml_output
+    end
+  end
+end