sonic-pi-akai-apc-mini 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f1ebf42972f8a9b3d2906047bbbeb2292a1a1a4d8f0ba4de4e74eb809b0c6ea
-  data.tar.gz: 03ab06c2fefd7b6741a303374073404d1b065213734e185b3b0da95a29beda9e
+  metadata.gz: bd279db408994ddf67942a34f1576feb382b7fedafdcaeeeb227f447b6b1073c
+  data.tar.gz: 628d1d73459b6e01f7554317e53db308967b17753cc94c2e48845d9c909bd485
 SHA512:
-  metadata.gz: 3868b1f5b216126776a0d388eecddc36992d4354c22d3fb519061b59e26dcc0219acae3e1b388102f89ab8dacdbb476bfa11c41dcf8733e0db054fefac8c1043
-  data.tar.gz: d4f0b4c643f33c5e41705376b40beb68eb58ae8801f4e3db006c660128a301637f474cfb26aa0911bc0cd7ef38342e29f233ab1a6add6c98bc87ef0ba4e3415b
+  metadata.gz: dd0673065b74993754899a449a1129ecfcce6b252fb93834ac8be33d148cff04f13a1361417ee9682117cd4bf9a41cd8d4d89a83347479335dcadbaaa9d99d35
+  data.tar.gz: 20d6cc379e57eda32090cd3cae0b70fab1c18946d9f17ffe79cbb34eac12d7aa556eee4065c5abd28fdd2ce7cc87a5ca5648a610c37b24a1da0cdd6f72069eee

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sonic-pi-akai-apc-mini (0.1.0)
+    sonic-pi-akai-apc-mini (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -16,7 +16,7 @@ You should _probably_ not use this yet for live performances, at least without h
 
 ## Installation
 
-Download, clone the code or install the gem, then add this to the top of your Sonic Pi buffer (or your `~/.sonic-pi/config/init.rb`):
+[Download](https://github.com/porras/sonic-pi-akai-apc-mini/archive/refs/heads/main.zip), clone the code or install [the gem](https://rubygems.org/gems/sonic-pi-akai-apc-mini), then add this to the top of your Sonic Pi buffer (or your `~/.sonic-pi/config/init.rb`):
 
 ```ruby
 require '<path-to-sonic-pi-akai-apc-mini>/init.rb'
@@ -29,15 +29,22 @@ Sonic Pi ships with its own Ruby, meaning that in principle it has no access to
 
 ## Usage
 
-First of all, call `initialize_akai` at the top of your buffer. That will make all the features available.
+If you want to skip this reference, feel free to load `example.rb` on Sonic Pi and start jamming. Otherwise:
+
+First of all, call `initialize_akai(<model>)` at the top of your buffer. That will make all the features available.
 
 A small set of functions get added to the Sonic Pi API, in order to use the controls in the APC mini in different ways.
 
+### Supported models
+
+* `:apc_mini`
+* `:apc_key_25` (experimental; please contact the author if you use it, either successfully or not. in any case, only the grid and the knobs are supported, not the keyboard --yet)
+
 ### Faders
 
 #### `fader(n, [target-values])`
 
-This function lets you use any of the faders to control the value of _anything_ in Sonic Pi. `n` is the fader number (they are 0-8, left to right). `target-values` is the range of values the fader will map to (and defaults to `(0..1)`\*). Some examples:
+This function lets you use any of the faders to control the value of _anything_ in Sonic Pi. `n` is the fader number (starting from 0, left to right). `target-values` is the range of values the fader will map to (and defaults to `(0..1)`\*). Some examples:
 
 ```ruby
 play :c4, amp: fader(0)

data/example.rb

@@ -0,0 +1,65 @@
+# This is a (probably contrived) example of the kind of things you can control.
+# This short script sets things up so that:
+#
+# Rows 0 and 1 of the grid are used for a simple drum loop with a kick and a
+# snare. Toggling the buttons in those rows will get you the pattern played, in
+# real time (note that this is initialized as an empty pattern, and the volume
+# is controlled by faders 0 and 2, so you won't hear anything until you toggle
+# some notes and push those faders).
+#
+# The is a second live_loop with a chord and an arpeggio based on that chord,
+# where some of the parameters are controlled by faders:
+#
+# 0 -> Kick volume
+# 1 -> Kick cutoff frequency
+# 2 -> Snare volume
+# 3 -> Snare cutoff frequency
+# 4 -> The chord itself! Atypical UI for this for works fine
+# 5 -> Chord volume
+# 6 -> Arpeggio volume
+# 7 -> Arpeggio reverb amount
+#
+# Finally a switch is setup on button [2, 0] (leftmost button of third row,
+# starting from the bottom) to toggle a background vinyl effect.
+#
+# Feel free to experiment with changing the music using the controller only,
+# then to try to control different things!
+
+initialize_akai(:apc_mini)
+
+use_bpm 110
+
+live_loop :drums do
+  loop_rows(4, {
+              1 => -> { sample :drum_bass_soft, amp: fader(0), cutoff: fader(1, (60..127)) },
+              0 => -> { sample :drum_snare_soft, amp: fader(2), cutoff: fader(3, (60..127)) }
+            })
+end
+
+live_loop :bass, sync: :drums do
+  sample :vinyl_hiss, sustain: 2, attack: 1, release: 1 if switch?(2, 0)
+
+  crd = fader(4, [
+                chord(:c3, :major),
+                chord(:g3, :major),
+                chord(:a3, :minor),
+                chord(:e3, :major)
+              ])
+
+  use_synth :blade
+
+  play_chord crd, release: 4, attack: 2, amp: fader(5)
+
+  use_synth :pluck
+
+  with_fx :reverb do |fx|
+    use_random_seed crd.first
+    attach_fader(7, fx, :room)
+    16.times do
+      play crd.choose + 12, release: 0.25, pan: rrand(-0.1, 0.1),
+                            amp: fader(6),
+                            on: spread(11, 16).tick(:note)
+      sleep 0.25
+    end
+  end
+end

data/init_dev.rb

@@ -0,0 +1,15 @@
+# Script to be used in development. Instead of `require '.../init.rb'` from
+# sonic pi, `load '.../init_dev.rb'` and code will be reloaded on each Alt+R.
+
+dir = File.join(__dir__, 'lib', 'sonic-pi-akai-apc-mini')
+
+load "#{dir}/core_extensions/range.rb"
+load "#{dir}/helpers.rb"
+load "#{dir}/api.rb"
+load "#{dir}/controller.rb"
+
+# bypass the mechanism that avoids hot-changing the model, forcing a reload of
+# the config on each call:
+SonicPiAkaiApcMini::Controller.instance_variable_set(:@_model, nil)
+
+include SonicPiAkaiApcMini::API

data/lib/sonic-pi-akai-apc-mini/api.rb

@@ -1,8 +1,7 @@
 module SonicPiAkaiApcMini
   module API
-    def switch?(line, col)
-      n = (line * 8) + col
-      !!get("switch_#{n}")
+    def switch?(row, col)
+      !!get("switch_#{Helpers.key(row, col)}")
     end
 
     # default `target` is 0-0.999 instead of 0.1 because many parameters have
@@ -11,7 +10,9 @@ module SonicPiAkaiApcMini
     # difference so I think it's a good default.
     def fader(n, target = (0..0.999), _options = {})
       # TODO: Try to optimize speed, there is some latency because the
-      # controller send a lot of events (too much granularity)
+      # controller send a lot of events (too much granularity). It is in theory
+      # possible to save some of it by `get`ting the value directly instead of
+      # waiting for all the events to be processed.
       value = get("fader_#{n}", 0)
       Helpers.normalize(value, target)
     end
@@ -22,42 +23,41 @@ module SonicPiAkaiApcMini
     end
 
     def loop_rows(duration, rows)
-      first_row = rows.keys.first
-      8.times do |beat|
+      first_row = rows.keys.max
+      Controller.model.grid_columns.times do |beat|
         prev = (beat - 1) % 8
-        midi_note_on (first_row * 8) + prev, get("switch_#{(first_row * 8) + prev}") ? 1 : 0
-        midi_note_on (first_row * 8) + beat, 5
+        prev_key = Helpers.key(first_row, prev)
+        beat_key = Helpers.key(first_row, beat)
+        midi_note_on prev_key, get("switch_#{prev_key}") ? Controller.model.light_green : Controller.model.light_off
+        midi_note_on beat_key, Controller.model.light_yellow
         rows.each do |row, sound|
-          in_thread(&sound) if get("switch_#{(row * 8) + beat}")
+          in_thread(&sound) if switch?(row, beat)
         end
-        sleep duration / 8.0
+        sleep duration.to_f / Controller.model.grid_columns
       end
     end
 
     def loop_rows_synth(duration, rows, notes, options = {})
-      8.times do |beat|
-        prev = (beat - 1) % 8
-        midi_note_on (rows.first * 8) + prev, get("switch_#{(rows.first * 8) + prev}") ? 1 : 0
-        midi_note_on (rows.first * 8) + beat, 5
-        rows.each.with_index do |row, index|
-          opts = options.respond_to?(:call) ? options.call : options
-          play(notes[index], opts) if get("switch_#{(row * 8) + beat}")
-        end
-        sleep duration / 8.0
-      end
+      rows = rows.map.with_index do |row, i|
+        [row, lambda do
+                opts = options.respond_to?(:call) ? options.call : options
+                play(notes[i], opts)
+              end]
+      end.to_h
+      loop_rows(duration, rows)
     end
 
     def reset_free_play(row, col, size)
       size = size.size unless size.is_a?(Integer) # so we can pass the same ring
       Helpers.key_range(row, col, size).each do |key|
-        midi_note_on key, 0
+        midi_note_on key, Controller.model.light_off
         set "free_play_#{key}", nil
       end
     end
 
     def free_play(row, col, notes, options = {})
       Helpers.key_range(row, col, notes.size).each.with_index do |key, i|
-        midi_note_on key, 5
+        midi_note_on key, Controller.model.light_yellow
         set "free_play_#{key}", notes[i]
       end
 
@@ -80,26 +80,31 @@ module SonicPiAkaiApcMini
       values[get("selector_current_value_#{krange}")]
     end
 
-    def initialize_akai
+    def initialize_akai(model)
+      Controller.model = model
       # This loop manages faders. Whenever they change, the new value is stored via set,
       # and the corresponding light is turned on/off.
       live_loop :faders do
         use_real_time
-        n, value = sync('/midi:apc_mini_apc_mini_midi_1_20_0:1/control_change')
-        set "fader_#{n - 48}", value
-        midi_note_on n - 48 + 64, value.zero? ? 0 : 1
-        if attachment = get("attached_fader_#{n - 48}")
+        n, value = sync(Controller.model.midi_event(:control_change))
+        set "fader_#{n - Controller.model.fader_offset}", value
+        if Controller.model.fader_light_offset
+          midi_note_on n + Controller.model.fader_light_offset,
+                       value.zero? ? Controller.model.light_off : Controller.model.light_red
+        end
+        if attachment = get("attached_fader_#{n - Controller.model.fader_offset}")
           normalized_value = Helpers.normalize(value, attachment[:target])
           control attachment[:node], attachment[:property] => normalized_value
         end
       end
 
-      # Manages the buttons in the grid, both as switches and to "free play". Whenever one is,
-      # pressed, we check if that row is being used to "free play". If it is, we play. If it's
-      # not, we manage it as a switch.
+      # Manages the buttons in the grid, both as switches, selectors, and to
+      # "free play". Whenever one is pressed, we check if that row is being used
+      # to "free play". If it is, we play. If it's not, we check if its used as
+      # a selector and manage it. Otherwise, we manage it as a switch.
       live_loop :switches_and_freeplay do
         use_real_time
-        n, _vel = sync('/midi:apc_mini_apc_mini_midi_1_20_0:1/note_on')
+        n, _vel = sync(Controller.model.midi_event(:note_on))
         if note = get("free_play_#{n}")
           cue :free_play, note: note, key: n
         elsif keys = get("selector_keys_#{n}")
@@ -117,7 +122,7 @@ module SonicPiAkaiApcMini
 
       live_loop :free_play_note_offs do
         use_real_time
-        n, _vel = sync('/midi:apc_mini_apc_mini_midi_1_20_0:1/note_off')
+        n, _vel = sync(Controller.model.midi_event(:note_off))
         if note_control = get("free_play_playing_#{n}")
           release = note_control.args['release'] || note_control.info.arg_defaults[:release]
           control note_control, amp: 0, amp_slide: release

data/lib/sonic-pi-akai-apc-mini/controller.rb

@@ -0,0 +1,68 @@
+module SonicPiAkaiApcMini
+  module Controller
+    class Error < StandardError; end
+
+    module_function
+
+    def model=(model_name)
+      if @_model
+        if @_model.name == model_name
+          return
+        else
+          raise Error, 'Changing the model is not supported. Please restart Sonic Pi and initialize with new model name'
+        end
+      end
+
+      config = Configs.fetch(model_name.to_sym) { raise Error, "model #{model_name} not supported" }
+
+      @_model = Model.new(config.merge(name: model_name))
+    end
+
+    def model
+      @_model || raise(Error, 'model not initialized')
+    end
+
+    Model = Struct.new(
+      :name, :midi_port,
+      :grid_rows, :grid_columns, :grid_offset,
+      :fader_count, :fader_offset, :fader_light_offset,
+      :light_off, :light_green, :light_red, :light_yellow,
+      keyword_init: true
+    ) do
+      def midi_event(event_name)
+        "/midi:#{midi_port}/#{event_name}"
+      end
+    end
+
+    Configs = {
+      apc_mini: {
+        midi_port: 'apc_mini*',
+        grid_rows: 8,
+        grid_columns: 8,
+        grid_offset: 0,
+        fader_count: 9,
+        fader_offset: 48,
+        fader_light_offset: 16,
+        light_off: 0,
+        light_green: 1,
+        light_red: 3,
+        light_yellow: 5
+      },
+      # TODO: Some assumptions here, check!
+      apc_key_25: {
+        midi_port: 'apc_key_25*', # TODO: this is just a guess
+        grid_rows: 5,
+        grid_columns: 8,
+        grid_offset: 0,
+        fader_count: 8,
+        fader_offset: 48,
+        fader_light_offset: nil, # no fader lights
+        light_off: 0,
+        light_green: 1,
+        light_red: 3,
+        light_yellow: 5
+        # TODO: handle keyboard
+      }
+    }.freeze
+  end
+end

data/lib/sonic-pi-akai-apc-mini/helpers.rb

@@ -2,6 +2,9 @@ module SonicPiAkaiApcMini
   module Helpers
     module_function
 
+    # Normalizes a MIDI velocity value (between 0 and 127) to the corresponding
+    # value in `target`, which can be a range, a ring/array, or the special
+    # value :pan (shortcut for (-1..1)).
     def normalize(value, target)
       value /= 127.0
       target = (-1..1) if target == :pan
@@ -14,10 +17,25 @@ module SonicPiAkaiApcMini
       end
     end
 
-    def key_range(row, col, max_size)
-      first = (row * 8) + col
-      last = [(row * 8) + 7, first + max_size - 1].min
-      (first..last)
+    class RangeError < StandardError; end
+
+    # Given a starting button (row, col) and a size, return the range of
+    # corresponding MIDI notes for those buttons. If `size` is bigger than the
+    # amount of remaining buttons before the end of the row, the range finishes
+    # at the end of the row. If the currently configured model has fewer
+    # rows/columns, it raises a RangeError error.
+    def key_range(row, col, size)
+      raise RangeError, 'out of range' if row >= Controller.model.grid_rows || col >= Controller.model.grid_columns
+
+      first = key(row, col)
+      last = first + size - 1
+      end_of_row = key(row, Controller.model.grid_columns - 1)
+
+      (first..[last, end_of_row].min)
+    end
+
+    def key(row, col)
+      (row * Controller.model.grid_columns) + col + Controller.model.grid_offset
     end
   end
 end

data/lib/sonic-pi-akai-apc-mini.rb

@@ -1,3 +1,4 @@
 require_relative './sonic-pi-akai-apc-mini/core_extensions/range'
 require_relative './sonic-pi-akai-apc-mini/helpers'
 require_relative './sonic-pi-akai-apc-mini/api'
+require_relative './sonic-pi-akai-apc-mini/controller'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sonic-pi-akai-apc-mini
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergio Gil
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-09 00:00:00.000000000 Z
+date: 2022-01-29 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -28,12 +28,14 @@ files:
 - README.md
 - Rakefile
 - akai-apc-mini.jpg
-- bin/console
 - bin/setup
+- example.rb
 - exe/sonic-pi-akai-apc-mini
 - init.rb
+- init_dev.rb
 - lib/sonic-pi-akai-apc-mini.rb
 - lib/sonic-pi-akai-apc-mini/api.rb
+- lib/sonic-pi-akai-apc-mini/controller.rb
 - lib/sonic-pi-akai-apc-mini/core_extensions/range.rb
 - lib/sonic-pi-akai-apc-mini/helpers.rb
 homepage: https://github.com/porras/sonic-pi-akai-apc-mini

data/bin/console

@@ -1,13 +0,0 @@
-#!/usr/bin/env ruby
-require 'bundler/setup'
-require 'sonic/pi/akai/apc/mini'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)