sonic-pi-akai-apc-mini 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f1ebf42972f8a9b3d2906047bbbeb2292a1a1a4d8f0ba4de4e74eb809b0c6ea
+  data.tar.gz: 03ab06c2fefd7b6741a303374073404d1b065213734e185b3b0da95a29beda9e
+SHA512:
+  metadata.gz: 3868b1f5b216126776a0d388eecddc36992d4354c22d3fb519061b59e26dcc0219acae3e1b388102f89ab8dacdbb476bfa11c41dcf8733e0db054fefac8c1043
+  data.tar.gz: d4f0b4c643f33c5e41705376b40beb68eb58ae8801f4e3db006c660128a301637f474cfb26aa0911bc0cd7ef38342e29f233ab1a6add6c98bc87ef0ba4e3415b

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,18 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+Lint/AssignmentInCondition:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+# This is a weird gem. This is fine here :)
+Naming/FileName:
+  Exclude:
+    - 'lib/sonic-pi-akai-apc-mini.rb'
+    - 'spec/sonic-pi-akai-apc-mini_spec.rb'

data/.ruby-version

@@ -0,0 +1 @@
+3.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at TODO: Write your email address. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sonic-pi-akai-apc-mini.gemspec
+gemspec
+
+gem 'rake'
+gem 'rspec'
+gem 'rubocop'
+gem 'rubocop-rake'
+gem 'rubocop-rspec'

data/Gemfile.lock

@@ -0,0 +1,61 @@
+PATH
+  remote: .
+  specs:
+    sonic-pi-akai-apc-mini (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    parallel (1.21.0)
+    parser (3.1.0.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.2.0)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    rubocop (1.24.1)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.15.1)
+      parser (>= 3.0.1.1)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.7.0)
+      rubocop (~> 1.19)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  rake
+  rspec
+  rubocop
+  rubocop-rake
+  rubocop-rspec
+  sonic-pi-akai-apc-mini!
+
+BUNDLED WITH
+   2.3.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+# Using the Akai APC mini to control Sonic Pi ![(build status)](https://github.com/porras/sonic-pi-akai-apc-mini/actions/workflows/main.yml/badge.svg)
+
+A collection of utility functions to use the [Akai APC mini](https://www.akaipro.com/apc-mini) MIDI controller with [Sonic Pi](https://sonic-pi.net/).
+
+![Photo of an Akai APC mini](akai-apc-mini.jpg)
+
+_Photo credit: <a href="https://commons.wikimedia.org/wiki/File:APC_Mini_and_other_Music_Tools_(15387729761).jpg">I G</a>, <a href="https://creativecommons.org/licenses/by/2.0">CC BY 2.0</a>, via Wikimedia Commons_.
+
+### Important note
+
+This is work in progress and, while it mostly works as described, its performance is not great and it is not completely stable. It can make the controller crash* sometimes when there is _too much_ going on, and even Sonic Pi itself (this is more rare and I have only seen it once, but it's fair to mention).
+
+You should _probably_ not use this yet for live performances, at least without having reproduced similar loads to what you plan to do.
+
+\*I don't know if this crashes happen in the controller itself, or in the software in the computer (be it drivers or Sonic Pi itself), but the way it manifests is: you can still control the sounds using the board, but its lights stop updating. I haven't found a solution to this crashes that is not restarting Sonic PI + plugging and unplugging the controller.
+
+## 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`):
+
+```ruby
+require '<path-to-sonic-pi-akai-apc-mini>/init.rb'
+# for example: require '~/sonic-pi-akai-apc-mini/init.rb'
+```
+
+### Finding out where the code is, when installed as a gem
+
+Sonic Pi ships with its own Ruby, meaning that in principle it has no access to the gems installed in your system. To find out where is the file you need to require, run `sonic-pi-akai-apc-mini` in a terminal and the path will be printed.
+
+## Usage
+
+First of all, call `initialize_akai` 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.
+
+### 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:
+
+```ruby
+play :c4, amp: fader(0)
+sample :bd_haus, cutoff: fader(1, (60..127))
+```
+
+`target-values` is typically a range, but it can also be an array or a ring. In that case, the range of the fader is divided into discrete regions, each of them mapped to a value:
+
+```ruby
+with_fx :slicer, phase: fader(0, [0.125, 0.25, 0.5]) do
+  play fader(1, chord(:c4, :major))
+end
+```
+
+`fader` also accepts the special value `:pan`, which maps to `(-1..1)`, for that very obvious usecase:
+
+```ruby
+play :c4, pan: fader(0, :pan)
+```
+
+Finally, it is possible to use the same fader for two different things, with two different target values, if that makes sense for your music:
+
+```ruby
+play :c4, amp: fader(0, (0.8..1.5)), pan: fader(0, :pan)
+```
+
+\*In reallity, `(0..0.999)`. The reason is that there are many parameters with range [0, 1), that is, between 0 and 1 but **not** 1, for example a synth's `res` (resonance). This weird default helps with this case while making no difference for the normal case. If you **really** need to be able to get to 1, then pass `(0..1)` explicitly.
+
+#### `attach_fader(n, node, property, [target-values])`
+
+All this is fine and good and works great with short synth notes or samples, but sometimes you want to control a sound with a fader _while it is playing_. That's what `attach_fader` is for. Apart from the already known `n` and `target-values`, which work the same, it expects a `node` (a synth node, a sample node, or a fx node) and a `property`, which will be attached to the fader and updated in real-time:
+
+```ruby
+with_fx :slicer do |fx|
+  attach_fader(0, fx, :mix)
+  ... # while these sounds play, you can control how much the slicer can be heard using fader 0
+end
+```
+
+Or:
+
+```ruby
+live_loop :drums do
+  drums = sample :loop_amen, beat_stretch: 4
+  attach_fader(0, drums, :cutoff, (60..120))
+  sleep 4
+end
+```
+
+In this case, at the moment it is not possible to attach the same fader to two different controls. But you can combine **one** `attach_fader` with as many `fader` as you want.
+
+`attach_fader` uses `control` under the hood, which means:
+
+* The property needs to be one that can be changed while the sound is playing. Refer to the documentation of each synth and fx.
+* It will be affected by the corresponding `_slide` options. It could be said that _it doesn't play very well with any non-zero value in the corresponding `_slide` option_, but in reality pretty cool effects can be created by mixing them.
+
+#### Important note about faders
+
+Because MIDI works with events, it is not possible for Sonic Pi to know the initial position of a fader until it is moved and its new value is sent. Until then, it is assumed it is set to zero. So, two little advices:
+
+* Start your performances with the faders physically set to zero, to match that assumption. Move them to the desired position _before_ evaluating the code that will read them.
+* The lights above the faders are used as a hint to avoid this problem: they will be off when Sonic Pi _thinks_ they're set at zero, and on when it _thinks_ they're set at non-zero. If you see a fader physically not at zero but with the light off, move it slightly, so that Sonic Pi learns where it is :)
+
+### Switches
+
+Each button in the grid can be used as a boolean switch, for any purpose (typically, triggering a sound or not). You could use a fader to map `amp` (and set it to zero when you don't want to hear it), but faders are scarce and there are 64 buttons in the grid :)
+
+#### `switch?(row, col)`
+
+Returns the current value (`true` or `false`) of the specified switch. Columns and rows start from 0, 0 at the lower left corner.
+
+```ruby
+live_loop :music do
+  sample "some_noisy_sample" if switch?(0, 0)
+  ... # some nice music
+end
+```
+
+The buttons will light green when they're on.
+
+### Selectors
+
+_NOTE: This feature is experimental. It mostly works, but its performance is quite bad and is one of the things that incresases the chance of crashes._
+
+Selectors are a special kind of switches. You can map a series of consecutive buttons in the grid, to different values. Only one of them will be active at the time (lighting green, while the others light red).
+
+#### `selector(row, col, target-values)`
+
+`row` and `col` points to the first button you want to assign, and `values` is an array/ring with the possible values. As many buttons as possible values will be mapped, but the end of the row is a hard limit.
+
+```ruby
+live_loop :notes do
+  use_synth selector(7, 0, [:fm, :beep, :tb303])
+  play scale(:c3, :minor_pentatonic).choose
+  sleep 0.5
+end
+```
+
+Or:
+
+```ruby
+play_chord selector(6, 0, [chord(:e3, :minor), chord(:g3, :major), chord(:d3, :major)])
+```
+
+As you can see, the use case is very similar to using `fader` with an array, but it is a better UI for many cases. Sadly, it doesn't work perfectly at the moment, so you might prefer to stick with `fader`.
+
+### Looping with the grid
+
+One of the most useful uses of the grid is _looping_. You can set it up so that you can punch notes in the grid, that will be played in loop. This is great (but not only) for drum loops.
+
+#### `loop_rows(duration, rows)`
+
+`duration` is the number of beats the loop lasts. It will always divided by the 8 columns of the grid. `rows` is a hash which maps the row number to a block with the sound to play. For example:
+
+```ruby
+live_loop :drums do
+  loop_rows(4, {
+    7 => -> { sample :drum_heavy_kick },
+    6 => -> { sample :drum_snare_hard },
+    5 => -> { synth :noise, release: 0.1 } # sketchy hi-hat
+  })
+end
+```
+
+This will assign the top 3 rows of the grid to punch a drum pattern. Notes will be shown as green, and there will be a hinting yellow light showing which column is being played as the loop progresses.
+
+#### `loop_rows_synth(duration, rows, notes, [options])`
+
+A typical use case of looping is calling a synth (always the same) with different notes (e.g. for basslines). This function makes it a bit less verbose:
+
+```ruby
+live_loop :bassline do
+  loop_rows_synth(8, (0..2), chord(:c2, :minor))
+end
+```
+
+This will assign each of the three notes of the chord to each row, and now you can punch your baseline.
+
+You can pass options, that will be applied to each note:
+
+```ruby
+live_loop :bassline do
+  loop_rows_synth(8, (0..2), chord(:c2, :minor), amp: 0.8)
+end
+```
+
+And, if you need those options to be evaluated separately for each note (because you call random values, or maybe `fader`), you can wrap it in a lambda:
+
+```ruby
+live_loop :bassline do
+  loop_rows_synth(8, (0..2), chord(:c2, :minor), -> {{ pan: rrand(-1..1), cutoff: fader(5, (60..120)) }}
+end
+```
+
+Something to note, is that there is no problem to run more than one loop, with different durations, as long as they don't use the same rows.
+
+### Free play
+
+The APC mini is a MIDI device, so you can... play! Be aware that this is of limited usefulness for several reasons (1. there is some latency that is ok for faders and such but makes playing quite difficult, and 2. it is not a keyboard, which makes it _even_ more difficult), but it can be ok for very simple things.
+
+#### `free_play(row, col, notes, [options])`
+
+Assigns a series of consecutive buttons starting at `row`, `col`, to play `notes` with the current synth (and the given `options`, if any). The mapped buttons with light yellow. This call should live in its own `live_loop`.
+
+```ruby
+live_loop :bass do
+  use_synth :fm
+  free_play 0, 0, scale(:c3, :major), amp: 0.8
+end
+```
+
+#### `reset_free_play(row, col, notes, [options])`
+
+If you want to remove a free play mapping (so that the buttons are again available as switches), you need to call `reset_free_play`. It has the same signature so you can just prepend `reset_` to the previous call.
+
+### Roadmap of planned features
+
+* A `selector` that actually works
+* Free play with samples
+* Improvements to `attach_fader` so that a couple of things that are currently not possible, are:
+  * Using it to control the mixer (`set_mixer_control!`, etc.)
+  * Attaching the same fader to different nodes, or different properties of the same node
+* Better performance and stability in general
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/porras/sonic-pi-akai-apc-mini. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/porras/sonic-pi-akai-apc-mini/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+This code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the sonic-pi-akai-apc-mini project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/porras/sonic-pi-akai-apc-mini/blob/master/CODE_OF_CONDUCT.md).
+
+## Acknowledgments
+
+Apart from the excellent documentation of the Sonic Pi project, [this wonderful summary](https://github.com/TomasHubelbauer/akai-apc-mini) by Tomáš Hübelbauer took me from barely knowing what MIDI is to a functional prototype in a couple of hours. Cheers!

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,13 @@
+#!/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__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/sonic-pi-akai-apc-mini

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+path_to_init = File.expand_path(File.join(__dir__, '..', 'init'))
+
+if ARGV.first == 'path'
+  puts path_to_init
+else
+  puts <<~RUBY
+    # To load sonic-pi-akai-apc-mini into Sonic Pi, add the following to your
+    # buffer, or ~/.sonic-pi/config/init.rb
+    require '#{path_to_init}'
+  RUBY
+end

data/init.rb

@@ -0,0 +1,3 @@
+require_relative './lib/sonic-pi-akai-apc-mini'
+
+include SonicPiAkaiApcMini::API

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

@@ -0,0 +1,131 @@
+module SonicPiAkaiApcMini
+  module API
+    def switch?(line, col)
+      n = (line * 8) + col
+      !!get("switch_#{n}")
+    end
+
+    # default `target` is 0-0.999 instead of 0.1 because many parameters have
+    # [0,1) as range and throw an error when passed 1 (e.g. tb303 synth's res).
+    # It's not the most common usecase, but for the common use case it makes no
+    # 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)
+      value = get("fader_#{n}", 0)
+      Helpers.normalize(value, target)
+    end
+
+    def attach_fader(n, node, property, target = (0..0.999))
+      control node, property => fader(n, target)
+      set "attached_fader_#{n}", node: node, property: property, target: target
+    end
+
+    def loop_rows(duration, rows)
+      first_row = rows.keys.first
+      8.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
+        rows.each do |row, sound|
+          in_thread(&sound) if get("switch_#{(row * 8) + beat}")
+        end
+        sleep duration / 8.0
+      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
+    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
+        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
+        set "free_play_#{key}", notes[i]
+      end
+
+      use_real_time
+
+      message = sync(:free_play)
+      note_control = play message[:note], { sustain: 9999 }.merge(options)
+      set "free_play_playing_#{message[:key]}", note_control
+    end
+
+    def selector(row, col, values)
+      # TODO: selector is quite messy. It can use a refactor and proper reset/cleanup (like free_play's).
+      krange = Helpers.key_range(row, col, values.size)
+      set "selector_values_#{krange}", values.ring
+      set "selector_current_value_#{krange}", 0 if get("selector_current_value_#{krange}").nil?
+      krange.each.with_index do |key, i|
+        set "selector_keys_#{key}", krange.to_a
+        midi_note_on key, i == get("selector_current_value_#{krange}") ? 1 : 3
+      end
+      values[get("selector_current_value_#{krange}")]
+    end
+
+    def initialize_akai
+      # 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}")
+          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.
+      live_loop :switches_and_freeplay do
+        use_real_time
+        n, _vel = sync('/midi:apc_mini_apc_mini_midi_1_20_0:1/note_on')
+        if note = get("free_play_#{n}")
+          cue :free_play, note: note, key: n
+        elsif keys = get("selector_keys_#{n}")
+          keys.each do |k|
+            midi_note_on k, 3
+          end
+          midi_note_on n, 1
+          set "selector_current_value_#{keys.first}..#{keys.last}", n - keys.first
+        else
+          new_value = !get("switch_#{n}", false)
+          set "switch_#{n}", new_value
+          midi_note_on n, (new_value ? 1 : 0)
+        end
+      end
+
+      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')
+        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
+          at(release) { note_control.kill }
+        end
+      end
+    end
+  end
+end
+
+include SonicPiAkaiApcMini::API

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

@@ -0,0 +1,13 @@
+module SonicPiAkaiApcMini
+  module SPThreadSafeRange
+    def __sp_make_thread_safe
+      (self.begin.__sp_make_thread_safe..self.end.__sp_make_thread_safe).freeze
+    end
+
+    def sp_thread_safe?
+      frozen? && self.begin.sp_thread_safe? && self.end.sp_thread_safe?
+    end
+  end
+end
+
+Range.prepend SonicPiAkaiApcMini::SPThreadSafeRange

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

@@ -0,0 +1,23 @@
+module SonicPiAkaiApcMini
+  module Helpers
+    module_function
+
+    def normalize(value, target)
+      value /= 127.0
+      target = (-1..1) if target == :pan
+      case target
+      when Range
+        target.begin + (value * (target.end - target.begin))
+      when Array, SonicPi::Core::RingVector
+        index = ((target.size - 1) * value).round
+        target[index]
+      end
+    end
+
+    def key_range(row, col, max_size)
+      first = (row * 8) + col
+      last = [(row * 8) + 7, first + max_size - 1].min
+      (first..last)
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+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'

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: sonic-pi-akai-apc-mini
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergio Gil
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-01-09 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- sgilperez@gmail.com
+executables:
+- sonic-pi-akai-apc-mini
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- akai-apc-mini.jpg
+- bin/console
+- bin/setup
+- exe/sonic-pi-akai-apc-mini
+- init.rb
+- lib/sonic-pi-akai-apc-mini.rb
+- lib/sonic-pi-akai-apc-mini/api.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
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/porras/sonic-pi-akai-apc-mini
+  source_code_uri: https://github.com/porras/sonic-pi-akai-apc-mini
+  rubygems_mfa_required: 'true'
+post_install_message: Remember to run sonic-pi-akai-apc-mini to get instructions on
+  how to load the new version into Sonic Pi
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Utility functions to use the Akai APC mini MIDI controller with Sonic Pi
+test_files: []