step_sequencer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7f05e5833d38340144b70f118284273333692da7
+  data.tar.gz: f1f28455b5272f7dff4a7d2d3aa578bcf64fec49
+SHA512:
+  metadata.gz: 4b600c61efe15377b72893b484b020894e7aba4cd4e902da2f0d46d99146bf98aea810624b23d0d603cf4020724d95188ca8cd21eb1d3cfe3663cecbb44f7281
+  data.tar.gz: 170de1a63b8618181f7536fcfdcb8687602eaea3dd9e62ac07a3b68995188c32307f6edb2c432cf54542e5c734dcfa61be1049cbc124c29ea5d310f8ba294537

data/README.md

@@ -0,0 +1,233 @@
+## Step Sequencer 
+
+#### About
+
+This is a Ruby tool to play mp3 files in a step sequencer.
+
+It also handles polyrhythmic playback and 
+
+#### Depedencies
+
+Some external programs need to be installed (via `apt-get`, `brew`, `yum`, etc)
+
+`mpg123 ffmpeg sox libsox-fmt-mp3`
+
+To run the tests, the program `espeak` is also required.
+
+#### Installing
+
+```sh
+gem install step_sequencer
+```
+
+```rb
+require 'step_sequencer'
+```
+
+#### Usage
+
+There are two main components: `StepSequencer::SoundBuilder` and
+`StepSequencer::SoundPlayer`. A third component,
+`StepSequencer::SoundAnalyser`, can also be useful.
+
+##### 1. **`StepSequencer::SoundBuilder`**
+
+There are number of `StepSequencer::SoundBuilder::EffectsComponents`
+(this constant refers to a hash, the values of which are classes).
+All of them inherit from and implement the protocol of
+`StepSequencer::SoundBuilder::EffectsComponentProtocol`. To use a custom effect,
+add the class to this list. Through the protocol, they're connected to the
+`StepSequencer::SoundBuilder.build` method.
+
+```rb
+# returns nested array (array of generated sounds for each source)
+builder = StepSequencer::SoundBuilder
+filenames = builder.build(
+  sources: ["middle_c.mp3"],
+  effect: :Scale,
+  args: [{scale: :equal_temperament}]
+)
+```
+
+The `:Scale` effect also allows an `inverse: true` key in `args` which will
+set all pitch change values to their inverse (creating a descending scale).
+
+Now say I want to apply a 150% gain to all these files:
+
+```rb
+# returns array of paths, one for each source
+new_filenames = builder.build(
+  sources: filenames.shift,
+  effect: :Gain,
+  args: [{value: 1.5}]
+)
+```
+
+Other builtin effects:
+
+_change speed_ (returns array of paths, one for each source)
+
+```rb
+new_filenames = builder.build(
+  sources: new_filenames,
+  effect: :Speed,
+  args: [{value: 0.5}]
+)
+```
+
+_change pitch_ (returns array of paths, one for each source)
+
+```rb
+new_filenames = builder.build(
+  sources: filenames,
+  effect: :Pitch,
+  args: [{value: 2}] # doubling pitch to account for 0.5 speed
+)
+# By default this will adjust the speed so that only the pitch changes.
+# However the `speed_correction: false` arg prevents this.
+```
+
+_loop_ (returns array of paths, one for each source)
+
+```rb
+new_filenames = builder.build(
+  sources: filenames,
+  effect: :Loop,
+  args: [{times: 1.5}]
+)
+```
+
+_slice_ (returns array of paths, one for each source)
+
+```rb
+new_filenames = builder.build(
+  sources: filenames,
+  effect: :Slice,
+  args: [{start_time: 0.5, end_time: 1}] # A 0.5 second slice
+  # start_pct and end_pct can be used for percentage-based slicing, e.g.
+  # {start_pct: 25, end_pct: 75} which will take a 50% slice from the middle.
+)
+```
+
+_combine_ (returns single path)
+
+```rb
+new_filenames = builder.build(
+  sources: filenames,
+  effect: :Combine,
+  args: [{filename: "foo.mp3"}], # filename arg is optional,
+                                 # and one will be auto-generated otherwise.
+)
+`
+
+_overlay_ (returns single path)
+
+```rb
+new_filenames = builder.build(
+  sources: filenames,
+  effect: :Overlay,
+  args: [{filename: "foo.mp3"}], # filename arg is optional,
+                                 # and one will be auto-generated otherwise.
+)
+`
+
+As the above examples illustrate,  `#build` is always given an array of sources
+(audio paths). `effect` is always a symbol, and although it can be ommitted if
+it's empty, `args` is always a array, the signature of which is dependent on the
+specific effects component's implementation.
+
+**2. `StepSequencer::SoundPlayer`**
+
+Playing sounds is a two part process. First, the player must be initialized,
+which is when the sounds are mapped to rows.
+
+For example, say I want to plug in the sounds I created earlier using
+`StepSequencer::SoundBuilder#build`. I have 12 sounds and I want to give each
+of them their own row in the sequencer. This pretty easy to do:
+
+```rb
+player = StepSequencer::SoundPlayer.new(filenames)
+```
+
+After `#initialize`, only one other method needs to get called, and that's `play`.
+As you might have expected by now, it's overloaded as well:
+
+```rb
+# This will play the descending scale, there is 1 row for each note
+player.play(
+  tempo: 240
+  string: <<-TXT
+  x _ _ _ _ _ _ _ _ _ _ _ 
+  _ x _ _ _ _ _ _ _ _ _ _ 
+  _ _ x _ _ _ _ _ _ _ _ _ 
+  _ _ _ x _ _ _ _ _ _ _ _ # comments can be added too
+  _ _ _ _ x _ _ _ _ _ _ _
+  _ _ _ _ _ x _ _ _ _ _ _ 
+  _ _ _ _ _ _ x _ _ _ _ _ 
+  _ _ _ _ _ _ _ x _ _ _ _ 
+  _ _ _ _ _ _ _ _ x _ _ _
+  _ _ _ _ _ _ _ _ _ x _ _ 
+  _ _ _ _ _ _ _ _ _ _ x _ 
+  _ _ _ _ _ _ _ _ _ _ _ x 
+  TXT
+)
+```
+
+To use something other than `x` or `_`, use the environment variables
+`STEP_SEQUENCER_GRID_HIT_CHAR` and `STEP_SEQUENCER_GRID_REST_CHAR`
+
+```rb
+# plays the same notes, but with nested arrays.
+# the note/rest are denoted by 1 and nil, respectively
+player.play(
+  tempo: 240,
+  matrix: 0.upto(11).reduce([]) do |rows, i|
+   rows.push Array.new(12, nil)
+   rows[-1][i] = 1
+   rows
+ end  
+)
+```
+
+Some other notes:
+
+- this intentionally doesn't validate that the rows
+are the same length. This is so that polyrhythms can be played.
+- by default the rows are looped forever in a background thread. To stop, simply
+`player.stop`. To trigger playback for a limited time only, pass a `limit` option
+which is an integer representing a number of _total hits_. I.e. if I wanted to
+play the aformentioned 12-step grid 4 times, I'd pass a limit of 48.
+- although there is no option to make `play` happen synchronously, just use
+something like `sleep 0.5 while player.playing`
+- the tempo can be understood as BPM in quarter notes. So to get the same speed
+as 16th notes at 120 BPM, use a tempo of 480. The default is 120.
+- The player isn't configured to be manipulated while playing. Use a new instance instead.
+
+#### Todos
+
+- precompile the grid into a single mp3. this will result in optimal playback
+  but may be slightly difficult considering many sounds can be played at once,
+  and a single sound can be played over itself.
+
+#### Tests
+
+The tests are found in lib/step_sequencer/tests.rb. They are not traditional
+unit tests since the value cannot be automatically determined to be correct.
+Rather, it generates sounds and then plays them back for manual aural
+validation. 
+
+A couple small (1 second) mp3s are bundled with the gem and are used in the tests.
+To run the tests from the command line after installing the gem:
+
+```rb
+step_sequencer test
+```
+
+They are packaged with the distributed gem, so after `require 'step_sequencer'`
+just use `StepSequencer::Tests.run`. Individual cases can also be run by calling
+the class methods of `Builder` and `Player` in `StepSequencer::Tests::TestCases`.
+
+There is one extra dependency required to use the tests, and that's the
+`espeak-ruby` gem. which will indicate what sounds are playing.
+This requires the external tool to be installed as well,
+e.g. `brew install espeak` or `sudo apt-get install espeak`.

data/bin/step_sequencer

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+require 'step_sequencer'
+require 'thor'
+class StepSequencer::CLI < Thor
+  desc "test", "run tests"
+  def test
+    StepSequencer::Tests.run
+  end
+end
+StepSequencer::CLI.start ARGV

data/lib/step_sequencer/example.rb

@@ -0,0 +1,14 @@
+sounds = [
+  "blip_1.mp3",
+  "blip_1.mp3",
+  "blip_1.mp3",
+]
+
+4.times do
+  sounds.each do |sound|
+    Thread.new do
+      `mpg123 #{sound} 2> /dev/null`
+    end
+  end
+  sleep 0.5
+end

data/lib/step_sequencer/refinements.rb

@@ -0,0 +1,124 @@
+module StepSequencer::Refinements
+
+  # =============================================================================
+  # String#strip_heredoc
+  # -----------------------------------------------------------------------------
+  # Another one from active support, this lets heredocs be indented without
+  # effecting the underlying string
+  # =============================================================================
+  module StringStripHeredoc
+    def strip_heredoc
+      indent = scan(/^[ \t]*(?=\S)/).min.__send__(:size) || 0
+      gsub(/^[ \t]{#{indent}}/, '')
+    end
+    refine String do
+      include StepSequencer::Refinements::StringStripHeredoc
+    end
+  end
+
+
+  # =============================================================================
+  # String#blank
+  # -----------------------------------------------------------------------------
+  # ActiveSupport provides a similar method for many classes,
+  # but from my experience the most useful is the String patch
+  # =============================================================================
+  module StringBlank
+    def blank?
+      /\A[[:space:]]*\z/ === self
+    end
+    refine String do
+      include StepSequencer::Refinements::StringBlank
+    end
+  end
+
+  # Object#yield_self
+  # -----------------------------------------------------------------------------
+  # is in Ruby since a v2.5 patch although there it's implemented on Kernel,
+  # which, being a module, makes it difficult to refine.
+  # Anyway, this is a backport; and it's a incredibly simply function
+  # =============================================================================
+  module ObjectYieldSelf
+    def yield_self(&blk)
+      blk&.call self
+    end
+    refine Object do
+      include StepSequencer::Refinements::ObjectYieldSelf
+    end
+  end
+
+  # =============================================================================
+  # String#rational_eval
+  # -----------------------------------------------------------------------------
+  # a method I've written to help work with rational numbers.
+  # It evals a string containing math, but wraps all number values in a call
+  # It raises an error if the result is not a rational
+  # =============================================================================
+  module StringRationalEval
+    def rational_eval
+      result = eval <<-RB
+        Rational(#{
+          gsub(/\d[\d\.\_]*/) { |str| "Rational(#{str})"}
+        })
+      RB
+      result.is_a?(Rational) ? result : raise("#{result} is not Rational")
+    end
+    refine String do
+      include StepSequencer::Refinements::StringRationalEval
+    end
+  end
+  
+  # =============================================================================
+  # Symbol#call
+  # -----------------------------------------------------------------------------
+  # cryptic but immensely useful.
+  # It enables passing arguments with the symbol-to-proc shorthand, e.g.:
+  #   [1,2,3].map(&:+.(1)) == [2,3,4]
+  # source: https://stackoverflow.com/a/23711606/2981429
+  # =============================================================================
+  module SymbolCall
+    def call(*args, &block)
+      ->(caller, *rest) { caller.send(self, *rest, *args, &block) }
+    end
+    refine Symbol do
+      include StepSequencer::Refinements::SymbolCall
+    end
+  end
+
+  # =============================================================================
+  # String#constantize
+  # -----------------------------------------------------------------------------
+  # comes from activesupport
+  # =============================================================================
+  module StringConstantize
+    def constantize
+      names = self.split("::".freeze)
+      # Trigger a built-in NameError exception including the ill-formed constant in the message.
+      Object.const_get(self) if names.empty?
+      # Remove the first blank element in case of '::ClassName' notation.
+      names.shift if names.size > 1 && names.first.empty?
+      names.inject(Object) do |constant, name|
+        if constant == Object
+          constant.const_get(name)
+        else
+          candidate = constant.const_get(name)
+          next candidate if constant.const_defined?(name, false)
+          next candidate unless Object.const_defined?(name)
+          # Go down the ancestors to check if it is owned directly. The check
+          # stops when we reach Object or the end of ancestors tree.
+          constant = constant.ancestors.inject(constant) do |const, ancestor|
+            break const    if ancestor == Object
+            break ancestor if ancestor.const_defined?(name, false)
+            const
+          end
+          # owner is in Object, so raise
+          constant.const_get(name, false)
+        end
+      end
+    end
+    refine String do
+      include StepSequencer::Refinements::StringConstantize
+    end
+
+  end
+end

data/lib/step_sequencer/sound_builder/default_effects/combine.rb

@@ -0,0 +1,25 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Combine < protocol
+
+  # This combines the files one after another.
+  # To make them overlap, use Overlay
+
+  def self.build(sources:, filename: nil)
+    concat_cmd = "concat:#{sources.join("|")}"
+    outfile = filename || generate_outfile_path(sources)
+    system %{ffmpeg -y -i "#{concat_cmd}" -c copy #{outfile} 2> /dev/null }
+    outfile
+  end
+
+  # The following is an alternate script to combine:
+  # `sox #{sources.join(" ")} #{outfile}`
+
+  class << self
+    private
+    def generate_outfile_path(sources)
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+  end
+
+end

data/lib/step_sequencer/sound_builder/default_effects/gain.rb

@@ -0,0 +1,21 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Gain < protocol
+
+  def self.build(sources:, value:)
+    sources.map do |path|
+      outfile = build_outfile_path path, value
+      `ffmpeg -y -i "#{path}" -af "volume=#{value.to_f}" #{outfile} 2> /dev/null`
+      outfile
+    end
+  end
+
+  class << self
+    private
+    def build_outfile_path path, value
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+  end
+
+  
+end

data/lib/step_sequencer/sound_builder/default_effects/loop.rb

@@ -0,0 +1,47 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Loop < protocol
+
+  def self.build(sources:, times:)
+    num_full_loops = times.to_i # rounds down
+    num_partial_loops = times - num_full_loops.to_f
+    outfiles = build_full_loops(sources, num_full_loops)
+    if num_partial_loops > 0
+      outfiles = build_partial_loops(sources, outfiles, num_partial_loops)
+    end
+    outfiles
+  end
+
+  class << self
+    private
+    def build_outfile_path
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+    def build_partial_loops(sources, outfiles, num_partial_loops)
+      outfiles.map.with_index do |outfile, idx|
+        source = sources[idx]
+        sliced = slice_source(source, num_partial_loops)
+        combine([outfile, sliced])
+      end
+    end
+    def build_full_loops(sources, num_full_loops)
+      sources.map do |source|
+        combine(Array.new(num_full_loops, source))
+      end
+    end
+    def slice_source(source, num_partial_loops)
+      builder.build(
+        sources: [source],
+        effect: :Slice,
+        args: [{start_pct: 0.0, end_pct: (num_partial_loops * 100) }]
+      )[0]
+    end
+    def combine(sources)
+      builder.build(
+        sources: sources,
+        effect: :Combine
+      )
+    end
+  end
+
+end

data/lib/step_sequencer/sound_builder/default_effects/overlay.rb

@@ -0,0 +1,35 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Overlay < protocol
+
+  def self.build(sources:, filename: nil)
+    # ensure_correct_sample_rates(sources)
+    outfile = filename || build_outfile_path
+    # `sox --combine mix #{sources.join(" ")} #{outfile}`
+    system <<-SH
+      ffmpeg -i #{sources.join(" -i ")} \
+      -filter_complex amerge -ac 2 -c:a libmp3lame -q:a 4 \
+      #{outfile} 2> /dev/null
+    SH
+    outfile
+  end
+
+  class << self
+    private
+    def build_outfile_path
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+    # def ensure_correct_sample_rates(sources)
+    #   sources.each do |source|
+    #     tmp_path = "#{SecureRandom.urlsafe_base64}.mp3"
+    #     `sox -r 44.1k #{source} #{tmp_path}`
+    #     unless File.exists?(tmp_path)
+    #       raise StandardError, "an error occurred setting sample rate in Overlay"
+    #     end
+    #     `rm #{source}`
+    #     `mv #{tmp_path} #{source}`
+    #   end
+    # end
+  end
+
+end

data/lib/step_sequencer/sound_builder/default_effects/pitch.rb

@@ -0,0 +1,40 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Pitch < protocol
+
+  def self.build(sources:, value:, speed_correction: true)
+    sources.map &change_pitch(value, speed_correction)
+  end
+
+  def self.change_pitch(value, speed_correction)
+    ->(source){
+      outfile = build_outfile_name(source, value)
+      cmd = <<-SH
+        ffmpeg -y -i #{source} -af   \
+          asetrate=44100*#{value} \
+          #{outfile}              \
+          2> /dev/null
+      SH
+      system cmd
+      return outfile unless speed_correction
+      outfile_with_correct_speed = correct_speed(outfile, value)
+      outfile_with_correct_speed
+    }
+  end
+
+  class << self
+    private
+    def build_outfile_name(source, value)
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+    def correct_speed(outfile, pitch_change_value)
+      inverse_value = Rational(1) / Rational(pitch_change_value)
+      builder.build(
+        sources: [outfile],
+        effect: :Speed,
+        args: [value: inverse_value]
+      ).shift
+    end
+  end
+
+end

data/lib/step_sequencer/sound_builder/default_effects/scale.rb

@@ -0,0 +1,34 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Scale < protocol
+
+  using StepSequencer.refinement(:SymbolCall)
+  using StepSequencer.refinement(:StringRationalEval)
+  using StepSequencer.refinement(:ObjectYieldSelf)
+
+  # Each returns an array of floats, representing pitch change from original
+  Scales = {
+    equal_temperament: begin
+      twelth_root_of_two = "2 ** (1 / 12)".rational_eval
+      1.upto(12).reduce([twelth_root_of_two]) do |memo|
+        memo.concat([memo[-1] * twelth_root_of_two])
+      end
+    end
+  }
+
+  def self.build(sources:, scale:, inverse: false, speed_correction: true)
+    pitch_changes = Scales.fetch(scale).yield_self do |notes|
+      inverse ? notes.map(&Rational(1).method(:/)) : notes
+    end
+    sources.map do |source|
+      pitch_changes.flat_map do |pitch_change|
+        builder.build(
+          sources: [source],
+          effect: :Pitch,
+          args: [value: pitch_change, speed_correction: speed_correction]
+        )
+      end
+    end
+  end
+
+end

data/lib/step_sequencer/sound_builder/default_effects/slice.rb

@@ -0,0 +1,46 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Slice < protocol
+
+  def self.build(sources:, start_pct: nil, end_pct: nil, start_time: nil, end_time: nil)
+    sources.map do |source|
+      len = get_audio_length(source)
+      start_time ||= calc_start_time(source, len, start_pct)
+      end_time ||= calc_end_time(source, len, end_pct)
+      diff = (end_time - start_time).round(6)
+      outfile = build_outfile_path
+      `sox #{source} #{outfile} trim #{start_time} #{diff} 2> /dev/null`
+      outfile
+    end
+  end
+
+  class << self
+    private
+    def build_outfile_path
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+    def get_audio_length(source)
+      raise(
+        StandardError,
+        "#{source} doesn't exist (can't slice)"
+      ) unless File.exists?(source)
+      `soxi -D #{source}`.to_f
+    end
+    def calc_start_time(source, len, start_pct)
+      raise(
+        StandardError,
+        "one of start_pct or start_time needs to be passed to Slice"
+      ) unless start_pct
+      start_pct_decimal = start_pct.to_f / 100.0
+      len * start_pct_decimal
+    end
+    def calc_end_time(sourse, len, end_pct)
+      raise(
+        StandardError,
+        "one of end_pct or end_time needs to be passed to Slice"
+      ) unless end_pct      
+      end_pct_decimal = end_pct.to_f / 100.0
+      len * end_pct_decimal
+    end
+  end
+end

data/lib/step_sequencer/sound_builder/default_effects/speed.rb

@@ -0,0 +1,20 @@
+protocol = StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+class StepSequencer::SoundBuilder::DefaultEffects::Speed < protocol
+
+  def self.build(sources:, value:)
+    sources.map do |path|
+      outfile = build_outfile_path path, value
+      `sox #{path} #{outfile} tempo #{value.to_f} 2> /dev/null`
+      outfile
+    end
+  end
+
+  class << self
+    private
+    def build_outfile_path path, value
+      "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
+    end
+  end
+
+end

data/lib/step_sequencer/sound_builder/default_effects.rb

@@ -0,0 +1,2 @@
+class StepSequencer::SoundBuilder::DefaultEffects
+end

data/lib/step_sequencer/sound_builder/effects_component_protocol.rb

@@ -0,0 +1,27 @@
+class StepSequencer::SoundBuilder::EffectsComponentProtocol
+
+  # receives dispatch from SoundBuilder.build
+  def self.build(sources:, args:)
+    raise "
+      ERROR.
+      Something inheriting from #{self.class} didn't implement #build.
+    "
+  end
+
+  class << self
+    
+    private
+
+    # Helper method to call other effects
+    def builder
+      StepSequencer::SoundBuilder
+    end
+
+    # Any created files should be placed in here (see sound_builder.rb)
+    def output_dir
+      builder::OutputDir
+    end
+
+  end
+
+end

data/lib/step_sequencer/sound_builder.rb

@@ -0,0 +1,27 @@
+class StepSequencer::SoundBuilder
+
+  # Check the ENV config for an output dir, otherwise use a default one
+  OutputDir = ENV.fetch(
+    "STEP_SEQUENCER_OUTPUT_DIR",
+    "./.step_sequencer/generated"
+  ).tap do |path|
+    `mkdir -p #{path}`
+    raise(
+      StandardError,
+      "#{path} dir couldn't be created/found. Maybe create it manually."
+    ) unless File.directory?(path)
+  end
+
+  def self.build(sources:, effect:, args: [{}])
+    effect_class = effects_components[effect]
+    effect_class.build({sources: sources}.merge *args)
+  end
+
+  class << self
+    private
+    def effects_components
+      StepSequencer::SoundBuilder::EffectsComponents
+    end
+  end
+  
+end

data/lib/step_sequencer/sound_player.rb

@@ -0,0 +1,132 @@
+class StepSequencer::SoundPlayer
+
+  using StepSequencer.refinement(:StringBlank)
+
+  HitChar = ENV.fetch("STEP_SEQUENCER_GRID_HIT_CHAR", "x")
+  RestChar = ENV.fetch("STEP_SEQUENCER_GRID_REST_CHAR", "_")
+
+  if [HitChar, RestChar].any? &:blank?
+    raise StandardError, "HitChar or RestChar cannot be just whitespace"
+  end
+
+  attr_reader :playing
+  
+  def initialize(sources)
+    @sources = sources
+    reset_state
+  end
+
+  def play(tempo: 120, string: nil, matrix: nil, limit: nil)
+    @limit = limit
+    if @playing
+      raise( StandardError,
+        "A sound player received #play when it was not in a stopped state.
+         Use multiple instances instead"
+      )
+    end
+    if matrix
+      play_from_matrix(tempo: tempo, matrix: matrix)
+    else
+      play_from_string(tempo: tempo, string: string)
+    end
+    @playing = true
+  end
+
+  def stop
+    reset_state
+    @thread&.kill
+  end
+
+  def reset_state
+    @thread = nil
+    @playing = false # It can't be called multiple times at once.
+                     # Use multiple instances instead.
+                     # There's a check to precaution against this.
+    @row_lengths = []
+    @active_steps = []
+    @steps_played = 0
+    @limit = nil # an upper limit for steps_played, defaults to no limit
+  end
+
+  private
+
+  def build_matrix_from_string(string)
+    string.tr(" ", '').split("\n").map(&:chars).map do |chars|
+      chars.map do |char|
+        if char == hit_char then 1
+        elsif char == rest_char then nil
+        else
+          raise( StandardError,
+            "
+              Error playing from string. Found char #{char} which is not
+              one of '#{hit_char}' or '#{rest_char}'.
+            "
+          )
+        end
+      end
+    end
+  end
+
+  def play_from_string(tempo:, string:)
+    raise(
+      StandardError,
+      "one of :string or :matrix must be provided for SoundPlayer#play"
+    ) if !string
+    matrix = build_matrix_from_string(string)
+    play_from_matrix tempo: tempo, matrix: matrix
+  end
+
+  def play_from_matrix(tempo:, matrix:)
+    init_matrix_state matrix
+    rest_time = calculate_rest_time(tempo)
+    @thread = Thread.new do
+      loop do
+        if @limit && (@steps_played >= @limit)
+          stop # Thread kills itself, no need to break from the loop
+        end
+        matrix.each_with_index do |row, row_idx|
+          play_next_step_in_row row, row_idx
+        end
+        @steps_played += 1
+        sleep rest_time
+      end
+    end
+  end
+
+  def play_next_step_in_row row, row_idx
+    Thread.new do
+      row_length = @row_lengths[row_idx]
+      active_step = @active_steps[row_idx]
+      Thread.stop unless active_step
+      step_content = row[active_step]
+      if step_content
+        path = @sources[row_idx]
+        Thread.new { `mpg123 #{path} 2> /dev/null` }
+      end
+      @active_steps[row_idx] += 1
+      if @active_steps[row_idx] >= row_length
+        @active_steps[row_idx] = 0
+      end
+    end
+  end
+
+  def calculate_rest_time(tempo)
+    # Tempo is seen as quarter notes, i.e. at 120 BPM there's 0.5 seconds
+    # between steps
+    60.0 / tempo.to_f
+  end
+
+  def init_matrix_state(matrix)
+    @row_lengths = matrix.map(&:length)
+    @active_steps = Array.new((matrix.length), 0)
+  end
+
+  def hit_char
+    self.class::HitChar
+  end
+
+  def rest_char
+    self.class::RestChar
+  end
+
+end

data/lib/step_sequencer/tests/test_cases.rb

@@ -0,0 +1,110 @@
+class StepSequencer::Tests::TestCases
+
+  class Player
+    extend StepSequencer::Tests::TestCaseHelpers
+
+
+    def self.play_a_simple_grid_from_string
+      player = build_player %w{blip_1 blip_1}.map(&method(:asset_path))
+      player.play(
+        tempo: 240,
+        limit: 16,
+        string: <<-TXT,
+          x _ x _
+          _ _ x _
+        TXT
+      )
+      sleep 0.5 while player.playing
+    end
+
+    def self.play_a_polyrhythmic_string
+      player = build_player %w{blip_1 blip_1}.map(&method(:asset_path))
+      player.play(
+        tempo: 240,
+        limit: 16,
+        string: <<-TXT,
+          x _ _
+          x _ _ _
+        TXT
+      )
+      sleep 0.5 while player.playing
+    end    
+
+  end
+
+  class Builder
+
+    extend StepSequencer::Tests::TestCaseHelpers
+
+    def self.build_c_major_chord
+      scale = equal_temperament_notes_with_speed_correction[0]
+      result_path = builder.build(
+        sources: scale.values_at(0, 4, 7),
+        effect: :Overlay
+      )
+      [result_path]
+    end
+
+    def self.build_f_sharp_major_chord
+      scale = equal_temperament_notes_with_speed_correction[0]
+      result_path = builder.build(
+        sources: scale.values_at(1, 6, 10),
+        effect: :Overlay
+      )
+      [result_path]
+    end
+
+    def self.loop_a_sound_4_point_5_times
+      builder.build(
+        sources: [asset_path("blip_1")],
+        effect: :Loop,
+        args: [times: 4.5]
+      )
+    end
+
+    def self.equal_temperament_notes_combined
+      scale_sources = equal_temperament_notes_with_speed_correction[0]
+      result_path = builder.build(
+        sources: scale_sources,
+        effect: :Combine
+      )
+      [result_path]
+    end
+
+    def self.equal_temperament_notes_with_speed_correction
+      builder.build(
+        sources: [asset_path("blip_1")],
+        effect: :Scale,
+        args: [scale: :equal_temperament]
+      )
+    end
+
+    def self.equal_temperament_with_no_speed_correction
+      builder.build(
+        sources: [asset_path("blip_1")],
+        effect: :Scale,
+        args: [scale: :equal_temperament, speed_correction: false]
+      )
+    end
+
+    def self.inverse_equal_temperament
+      builder.build(
+        sources: [asset_path("blip_1")],
+        effect: :Scale,
+        args: [scale: :equal_temperament, inverse: true]
+      )
+    end
+
+    def self.increase_gain
+      [0.25, 0.5, 0.75, 1, 1.5, 3, 5, 10].map do |val|
+        builder.build(
+          sources: [asset_path("blip_1")],
+          effect: :Gain,
+          args: [value: val]
+        )
+      end
+    end
+
+  end
+
+end

data/lib/step_sequencer/tests.rb

@@ -0,0 +1,104 @@
+require 'espeak'
+require 'method_source'
+
+# =============================================================================
+# A custom test runner. The tests themselves are in test_cases.rb
+# Usage: StepSequencer::Tests.run
+# The private method run_test_collection can also be used; it's more modular.
+# =============================================================================
+
+class StepSequencer::Tests
+
+  # Runs all the test cases, speaking the method name and playing the result.
+  #
+  # Returns the results from the tests, for manual inspection from Pry
+  #
+  def self.run
+    cleanup
+    run_test_collection(builder_tests) do |fn_name, test_case|
+      result = run_test_case(builder_tests, fn_name, test_case)
+      result.tap &method(:play_sounds)
+    end
+    run_test_collection(player_tests) do |fn_name, test_case|
+      run_test_case(player_tests, fn_name, test_case)
+    end
+  end
+
+  # shared 'around' hook for tests
+  def self.run_test_case(test_class, fn_name, test_case)
+    speak_fn_name fn_name
+    puts fn_name
+    test_class.method(fn_name).source.display
+    test_case.call
+  end
+
+  class << self
+    private
+
+    def builder_tests
+      StepSequencer::Tests::TestCases::Builder
+    end
+    def player_tests
+      StepSequencer::Tests::TestCases::Player
+    end
+
+    def speak_fn_name fn_name
+      say fn_name.to_s.gsub("_", " ")
+    end
+
+    def cleanup
+      dir = StepSequencer::SoundBuilder::OutputDir
+      Dir.glob("#{dir}/*.mp3").each &File.method(:delete)
+    end
+
+    # Runs all the methods in a class, optionally filtered via :only and
+    # :accept options (arrays of symbols referencing methods of klass).
+    #
+    # If a block is provided, then it is passed the name as a symbol and
+    # the test case as a proc. The proc will need to be called manually
+    # from the block, and the block should return the result.
+    # This allows a before/after hook to be inserted.
+    # With no given block, the test case is automatically run.
+    #
+    # Returns a hash mapping test case names (symbols) to results
+    #
+    def run_test_collection(klass, only: nil, except: nil, &blk)
+      klass.methods(false).reduce({}) do |memo, fn_name|
+        next memo if only && !only.include?(fn_name)
+        next memo if except && except.include?(fn_name)
+        memo[fn_name] = if blk
+          blk.call(fn_name, ->{klass.send fn_name})
+        else
+          klass.send(fn_name)
+        end
+        memo
+      end
+    end
+
+    def say(phrase)
+      ESpeak::Speech.new(phrase).speak
+    end
+    def play_sounds(sounds, tempo: 800)
+      sleep_time = 60.0 / tempo.to_f
+      sounds.flatten.each do |path|
+        `mpg123 #{path} 2> /dev/null`
+        sleep sleep_time
+      end
+    end
+  end
+
+  # Helpers made available to test cases (if they include the module)
+  module TestCaseHelpers
+    private
+    def asset_path(name)
+      Gem.find_files("step_sequencer/test_assets/#{name}.mp3")[0]
+    end
+    def builder
+      StepSequencer::SoundBuilder
+    end
+    def build_player(sources)
+      StepSequencer::SoundPlayer.new sources
+    end
+  end
+
+end

data/lib/step_sequencer.rb

@@ -0,0 +1,33 @@
+require 'byebug'
+require 'securerandom'
+
+Thread.abort_on_exception = true
+
+# only top-level constant defined by the gem
+class StepSequencer; end
+
+# Require the refinements file first
+refinements_file = Gem.find_files("step_sequencer/refinements.rb").shift
+require refinements_file
+
+# Add a little util method to access the refinements from other files.
+class StepSequencer
+  def self.refinement(name)
+    StepSequencer::Refinements.const_get name
+  end
+end
+
+# Require all ruby files in lib/step_sequencer, ordered by depth
+# This loads the refinements file again but it's no big deal
+Gem.find_files("step_sequencer/**/*.rb")
+   .sort_by { |path| path.count "/" }
+   .each &method(:require)
+
+# Add the default effects to the sound builder
+StepSequencer::SoundBuilder.class_exec do
+  self::EffectsComponents = self::DefaultEffects.constants
+  .reduce({}) do |memo, name|
+    memo.tap { memo[name] = self::DefaultEffects.const_get name }
+  end
+end
+

data/lib/version.rb

@@ -0,0 +1,3 @@
+module StepSequencer
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: step_sequencer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- max pleaner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: espeak-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: ''
+email: maxpleaner@gmail.com
+executables:
+- step_sequencer
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/step_sequencer
+- lib/step_sequencer.rb
+- lib/step_sequencer/example.rb
+- lib/step_sequencer/refinements.rb
+- lib/step_sequencer/sound_builder.rb
+- lib/step_sequencer/sound_builder/default_effects.rb
+- lib/step_sequencer/sound_builder/default_effects/combine.rb
+- lib/step_sequencer/sound_builder/default_effects/gain.rb
+- lib/step_sequencer/sound_builder/default_effects/loop.rb
+- lib/step_sequencer/sound_builder/default_effects/overlay.rb
+- lib/step_sequencer/sound_builder/default_effects/pitch.rb
+- lib/step_sequencer/sound_builder/default_effects/scale.rb
+- lib/step_sequencer/sound_builder/default_effects/slice.rb
+- lib/step_sequencer/sound_builder/default_effects/speed.rb
+- lib/step_sequencer/sound_builder/effects_component_protocol.rb
+- lib/step_sequencer/sound_player.rb
+- lib/step_sequencer/test_assets/blip_1.mp3
+- lib/step_sequencer/test_assets/blip_2.mp3
+- lib/step_sequencer/tests.rb
+- lib/step_sequencer/tests/test_cases.rb
+- lib/version.rb
+homepage: http://github.com/maxpleaner/step_sequencer
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.11
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: step sequencer (music tool)
+test_files: []