step_sequencer 1.0.6 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75a694b928505f59f1e10c1378e5ca6fc0258da6
-  data.tar.gz: 5575c13783e126aa1da243cee88d5a1ac7521b56
+  metadata.gz: 35e70912bfa1e7b6f09f3934f4f8937333aeb62e
+  data.tar.gz: 734b86e139fd8d55bb65a94b8db6edadb4e26a56
 SHA512:
-  metadata.gz: 15a27f5c1310bc03794a4ca1710a59917faf28700c2ea7b35cb1f35ba1d0a757b6633f40b399ba80cf6f597154d2168d86b46458406ad8b21cfd50e4d568763e
-  data.tar.gz: 8feb17c505798fa16b602c626fa2e47d0e6bf41a338e0413135c45089d5a2b37f6b5318de2ecd0a3436b25d1b6c41c805243bd236c05dd4e87346bd7d1960ed4
+  metadata.gz: bcf615d12d4924b6b6066a413c714acc08ae94f776d0f4af63617908fb109720f712ea73d996d5071229b7de9c73fb866920d0f8656da91129d7c5cd9ded0a52
+  data.tar.gz: 0e864b28ece6903840a12fec93f38db3de186b7802e504ef46b69e51b666650a6efd9f4daf9b0e8c24c63a632d874adcb0ea87afffd48ffd95a01d680b7a8a23

data/README.md

@@ -1,12 +1,13 @@
 ## Step Sequencer 
 
-#### About
-
 This is a Ruby tool to play mp3 files in a step sequencer.
 
-It also handles polyrhythmic playback and building sounds using effects like 
+It also handles polyrhythmic playback and building sounds using effects like
+loop, combine, slice, overlay, combine, gain, speed, and pitch
+
+## Setup
 
-#### Depedencies
+### Dependencies
 
 Some external programs need to be installed:
 
@@ -14,7 +15,7 @@ Some external programs need to be installed:
 
 To run the tests, the program `espeak` is also required.
 
-#### Installing
+### Installing
 
 ```sh
 gem install step_sequencer
@@ -24,42 +25,69 @@ gem install step_sequencer
 require 'step_sequencer'
 ```
 
-#### Usage
+### Configuration
+
+The main point of config is to set the location that files are generated to.
+This program creates a lot of mp3s and doesn't automatically delete any of them.
+By default, the location is `./.step_sequencer/generated` which is a _relative
+path_. That means it's dependent on which directory the command was run from.
+To use an absolute path instead, set the `STEP_SEQUENCER_OUTPUT_DIR` environment
+variable.
+
+## REPL
+
+There is a Ruby-based REPL that ships with the gem.
+Launch it from shell with:
+
+```sh
+step_sequencer repl
+```
+
+and type 'help' or 'quit'. It will show the names of some helper functions
+that have been made available.
+Still, the REPL assumes familiarity with the underlying Ruby API.
+
+## Ruby API
 
 There are two main components: `StepSequencer::SoundBuilder` and
 `StepSequencer::SoundPlayer`
 
-**`StepSequencer::SoundBuilder`**
+### StepSequencer::SoundBuilder
+
+This offers only one public method, `.build`, which is overloaded
+    and dispatches to a number of other classes (each of which is responsible for
+    a single effect). 
+
+_note_
 
-This offers only one public method, `.build`, which is drastically overloaded
-and dispatches to a number of other classes (each of which is responsible for
-a single effect). The definitions of these can be found in the source code at
- `lib/step_sequencer/sound_builder/default_effects/`. To add a custom effect,
- use one of the existing ones as a template and then add a reference to the class
- in the `StepSequencer::SoundBuilder::EffectsComponents` hash.
+> The definitions of the default effects can be found in the source code at `lib/step_sequencer/sound_builder/default_effects/`. To add a custom effect, use one of the existing ones as a template and then add a reference to the class
+in the `StepSequencer::SoundBuilder::EffectsComponents` hash.
 
-Here is an example. It takes a single input mp3 and creates 12 new ones,
+Here is an example of using the builder. It takes a single input mp3 and creates 12 new ones,
 spanning the "equal temperament" tuning.
 
 ```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}]
-)
+).first
+# the :Scale effect returns a nested array (one array for each input source)
+# so after calling .first, filenames refers to a regular array of 12 file paths.
 ```
 
 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).
 
+Right now there is only the equal temperament option, more may be added later.
+
 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,
+filenames = builder.build(
+  sources: filenames
   effect: :Gain,
   args: [{value: 1.5}]
 )
@@ -67,20 +95,22 @@ new_filenames = builder.build(
 
 Other builtin effects:
 
-_change speed_ (returns array of paths, one for each source)
+_change speed_
 
 ```rb
-new_filenames = builder.build(
-  sources: new_filenames,
+# returns array of paths, one for each source
+filenames = builder.build(
+  sources: filenames,
   effect: :Speed,
   args: [{value: 0.5}]
 )
 ```
 
-_change pitch_ (returns array of paths, one for each source)
+_change pitch_
 
 ```rb
-new_filenames = builder.build(
+# returns array of paths, one for each source
+filenames = builder.build(
   sources: filenames,
   effect: :Pitch,
   args: [{value: 2}]
@@ -89,20 +119,22 @@ new_filenames = builder.build(
 # However the `speed_correction: false` arg will prevent this.
 ```
 
-_loop_ (returns array of paths, one for each source)
+_loop_
 
 ```rb
-new_filenames = builder.build(
+# returns array of paths, one for each source
+filenames = builder.build(
   sources: filenames,
   effect: :Loop,
   args: [{times: 1.5}]
 )
 ```
 
-_slice_ (returns array of paths, one for each source)
+_slice_
 
 ```rb
-new_filenames = builder.build(
+# returns array of paths, one for each source
+filenames = builder.build(
   sources: filenames,
   effect: :Slice,
   args: [{start_time: 0.5, end_time: 1}] # A 0.5 second slice
@@ -111,10 +143,11 @@ new_filenames = builder.build(
 )
 ```
 
-_combine_ (returns single path)
+_combine_
 
 ```rb
-new_filenames = builder.build(
+# returns single path
+path = builder.build(
   sources: filenames,
   effect: :Combine,
   args: [{filename: "foo.mp3"}], # filename arg is optional,
@@ -122,10 +155,11 @@ new_filenames = builder.build(
 )
 ```
 
-_overlay_ (returns single path)
+_overlay_
 
 ```rb
-new_filenames = builder.build(
+# returns single path
+path = builder.build(
   sources: filenames,
   effect: :Overlay,
   args: [{filename: "foo.mp3"}], # filename arg is optional,
@@ -138,10 +172,9 @@ As the above examples illustrate,  `#build` is always given an array of sources
 it's empty, `args` is always a array, the signature of which is dependent on the
 specific effects component's implementation.
 
-**`StepSequencer::SoundPlayer`**
+### StepSequencer::SoundPlayer
 
-Playing sounds is a two part process. First, the player must be initialized,
-which is when the sounds are mapped to rows.
+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
@@ -155,7 +188,7 @@ 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
+# This will play the ascending scale, there is 1 row for each note
 player.play(
   tempo: 240
   string: <<-TXT
@@ -205,12 +238,14 @@ something like `sleep 0.5 while player.playing`
 as 16th notes at 120 BPM, use a tempo of 480. The default is 120.
 - The player isn't set up to be manipulated while playing. Use a new instance instead.
 
-#### Todos
+## Todos
 
 - precompile the grid into a single mp3. this will result in optimal playback
-- make a nice REPL
+- support inlining effect directives into the grid (not just a separate build
+stage). Part of this could be supporting different note flags, such as whole notes,
+half notes, etc.
 
-#### Tests
+## 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.
@@ -225,4 +260,4 @@ step_sequencer test
 ```
 
 They can also be run from code: `require 'step_sequencer'` then
-`StepSequencer::Tests.run`.
+`StepSequencer::Tests.run`.

data/bin/step_sequencer

@@ -6,5 +6,9 @@ class StepSequencer::CLI < Thor
   def test
     StepSequencer::Tests.run
   end
+  desc "repl", "start repl"
+  def repl
+    StepSequencer::REPL.run
+  end  
 end
 StepSequencer::CLI.start ARGV

data/lib/step_sequencer/repl.rb

@@ -0,0 +1,14 @@
+class StepSequencer::REPL
+
+  # Makes all the instance methods of Helpers available to REPL
+  # The binding.pry here is not a remnant of bug-hunting,
+  # this is how the REPL starts
+  def self.start
+    self::Helpers.new.instance_exec { binding.pry }
+  end
+
+  class Helpers
+    # todo
+  end
+
+end

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

@@ -16,7 +16,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Combine < protocol
   # `sox #{sources.join(" ")} #{outfile}`
 
   class << self
-    public
+    private
     def generate_outfile_path(sources)
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

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

@@ -11,7 +11,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Gain < protocol
   end
 
   class << self
-    public
+    private
     def build_outfile_path path, value
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

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

@@ -13,7 +13,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Loop < protocol
   end
 
   class << self
-    public
+    private
     def build_outfile_path
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

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

@@ -15,7 +15,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Overlay < protocol
   end
 
   class << self
-    public
+    private
     def build_outfile_path
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

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

@@ -23,7 +23,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Pitch < protocol
   end
 
   class << self
-    public
+    private
     def build_outfile_name(source, value)
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

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

@@ -15,7 +15,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Slice < protocol
   end
 
   class << self
-    public
+    private
     def build_outfile_path
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

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

@@ -11,7 +11,7 @@ class StepSequencer::SoundBuilder::DefaultEffects::Speed < protocol
   end
 
   class << self
-    public
+    private
     def build_outfile_path path, value
       "#{output_dir}/#{SecureRandom.urlsafe_base64}.mp3"
     end

data/lib/step_sequencer/sound_builder/effects_component_protocol.rb

@@ -10,7 +10,7 @@ class StepSequencer::SoundBuilder::EffectsComponentProtocol
 
   class << self
     
-    public
+    private
 
     # Helper method to call other effects
     def builder

data/lib/step_sequencer/tests.rb

@@ -1,6 +1,3 @@
-require 'espeak'
-require 'method_source'
-
 # =============================================================================
 # A custom test runner. The tests themselves are in test_cases.rb
 # Usage: StepSequencer::Tests.run

data/lib/step_sequencer.rb

@@ -1,5 +1,7 @@
-require 'byebug'
 require 'securerandom'
+require 'pry'
+require 'espeak'
+require 'method_source'
 
 Thread.abort_on_exception = true
 

data/lib/version.rb

@@ -1,3 +1,3 @@
 module StepSequencer
-  VERSION = '1.0.6'
+  VERSION = '1.0.7'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: step_sequencer
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.7
 platform: ruby
 authors:
 - max pleaner
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 description: ''
 email: maxpleaner@gmail.com
 executables:
@@ -64,6 +78,7 @@ files:
 - lib/step_sequencer.rb
 - lib/step_sequencer/example.rb
 - lib/step_sequencer/refinements.rb
+- lib/step_sequencer/repl.rb
 - lib/step_sequencer/sound_builder.rb
 - lib/step_sequencer/sound_builder/default_effects.rb
 - lib/step_sequencer/sound_builder/default_effects/combine.rb