Lang - introduce language support for Ableton Link

`use_bpm :link`

When using the :link BPM, Sonic Pi switches all timing algorithms for that specific thread to use the shared Ableton Link metronome. Ableton Link is GPL software that implements a metronome that is automatically shared and synchronised with other pieces of link-enabled software running on the same local network. This means that  with `use_bpm :link` the BPM effectively becomes dynamic and can be modified from any piece of link-enabled software on the local network.

With use_bpm *all* timing functions for that thread now use Link as their ground truth with respect to time. However, whilst this does mean that the BPM becomes dynamic, functions such as `at`, `time_warp`, `density` and `use_bpm_mul` *should* continue to work as expected as we now also internally capture a notion of time density which works as a multiplier on the dynamic BPM value.

Note that this commit and other related ones introduce a lot of changes to the core timing functionality. However, by default when not using the `:link` option for the BPM, it is expected that functionality should be identical. Any differences should be considered a bug.

There are also likely to be quite a few kinks remaining - this has only been tested on Windows and I'm yet to do any co-located jamming with multiple link-powered audio apps so there's also a good chance that the schedule ahead functionality needs to be tweaked and possibly new latency compensation routines to be added to get everything in actual audio sync.

Also, the Link functionality has to be extended before a release can be contemplated (resetting, changing BPM, etc). There also needs to be some representation in the GUI (likely using the Ableton Live metrome widget as inspiration to improve knowledge transfer and familiarity).

Finally, the Link beat quantum needs to be explored and added to the API. Perhaps something like `use_bpm :link, quantum: 4`

Author: samaaron

app/server/ruby/lib/sonicpi/lang/core.rb

@@ -3563,7 +3563,7 @@ def with_cue_logging(v, &block)
 
       def use_bpm(bpm, &block)
         raise ArgumentError, "use_bpm does not work with a block. Perhaps you meant with_bpm" if block
-        raise ArgumentError, "use_bpm's BPM should be a positive value. You tried to use: #{bpm}" unless bpm > 0
+        raise ArgumentError, "use_bpm's BPM should be a positive value or :link. You tried to use: #{bpm}" unless bpm == :link || (bpm.is_a?(Numeric) && bpm > 0)
         __change_spider_bpm!(bpm)
       end
       doc name:           :use_bpm,
@@ -3674,11 +3674,10 @@ def with_bpm(bpm, &block)
       def with_bpm_mul(mul, &block)
         raise ArgumentError, "with_bpm_mul must be called with a do/end block. Perhaps you meant use_bpm_mul" unless block
         raise ArgumentError, "with_bpm_mul's mul should be a positive value. You tried to use: #{mul}" unless mul > 0
-        current_bpm = __get_spider_bpm
-        new_bpm = current_bpm * mul.to_f
-        __change_spider_bpm!(new_bpm)
-        res = block.call
-        __change_spider_bpm!(current_bpm)
+        res = nil
+        __with_spider_time_density(mul) do
+          res = block.call
+        end
         res
       end
       doc name:           :with_bpm_mul,
@@ -3710,7 +3709,7 @@ def use_bpm_mul(mul, &block)
         raise ArgumentError, "use_bpm_mul must not be called with a block. Perhaps you meant with_bpm_mul" if block
         raise ArgumentError, "use_bpm_mul's mul should be a positive value. You tried to use: #{mul}" unless mul > 0
         new_bpm = __get_spider_bpm * mul.to_f
-        __change_spider_bpm!(new_bpm)
+        __layer_spider_time_density!(mul)
       end
       doc name:           :use_bpm_mul,
           introduced:     Version.new(2,3,0),
@@ -3738,9 +3737,7 @@ def density(d, &block)
         raise ArgumentError, "density must be called with a do/end block." unless block
         raise ArgumentError, "density must be a positive number. Got: #{d.inspect}." unless d.is_a?(Numeric) && d > 0
         reps = d < 1 ? 1.0 : d
-        prev_density = __thread_locals.get(:sonic_pi_local_spider_density) || 1.0
-        __thread_locals.set_local(:sonic_pi_local_spider_density, prev_density * d)
-        with_bpm_mul d do
+        __with_spider_time_density(d) do
           if block.arity == 0
             reps.times do
               block.call
@@ -3751,7 +3748,6 @@ def density(d, &block)
             end
           end
         end
-        __thread_locals.set_local(:sonic_pi_local_spider_density, prev_density)
       end
       doc name:           :density,
           introduced:     Version.new(2,3,0),
@@ -4138,31 +4134,18 @@ def sleep(beats)
         __change_spider_beat_and_time_by_beat_delta!(beats)
 
         sat = current_sched_ahead_time
-        new_vt = __get_spider_time
-        now = Time.now
+        new_vt = __get_spider_time.to_r
+        now = Time.now.to_f
 
         in_time_warp = __system_thread_locals.get(:sonic_pi_spider_in_time_warp)
 
-        if now - (sat + 0.5) > new_vt
-          raise TimingError, "Timing Exception: thread got too far behind time"
+        if (now - (sat + 0.5)) > new_vt
+
+          # raise TimingError, "Timing Exception: thread got too far behind time
+          __delayed_serious_warning "Serious timing error. Too far behind time..."
         elsif (now - sat) > new_vt
-          # TODO: Empirical tests to see what effect this priority stuff
-          # actually has on typical workloads
-
-          # Hard warning, system is too far behind, expect timing issues.
-          p = Thread.current.priority
-          p += 10
-          p = 100 if p < 100
-          p = 150 if p > 150
-          Thread.current.priority = p
           __delayed_serious_warning "Timing error: can't keep up..."
         elsif now > new_vt
-          # Soft warning, system should work correctly, but is currently behind
-          p = Thread.current.priority
-          p += 5
-          p = 50 if p < 50
-          p = 150 if p > 150
-          Thread.current.priority = p
           ## TODO: Remove this and replace with a much better silencing system which
           ## is implemented within the __delayed_* fns
           unless __thread_locals.get(:sonic_pi_mod_sound_synth_silent) || in_time_warp
@@ -4175,7 +4158,8 @@ def sleep(beats)
             # However, do make sure the vt hasn't got too far ahead of the real time
             # raise TimingError, "Timing Exception: thread got too far ahead of time" if  (new_vt - 17) > now
           else
-            Kernel.sleep new_vt - now
+            t = (new_vt - now).to_f
+            Kernel.sleep t
           end
         end
 
@@ -4317,13 +4301,17 @@ def sync_event(*args)
 
         __system_thread_locals.set(:sonic_pi_spider_synced, true)
 
-        ## only need to use se for beat and time if not in :link or :metro bpm
         __change_spider_time_and_beat!(se.time, se.beat)
         __system_thread_locals.set_local :sonic_pi_local_last_sync, se
 
         if bpm_sync
-          bpm = se.bpm <= 0 ? 60 : se.bpm
-          use_bpm bpm
+          if se.bpm == :link
+            use_bpm :link
+          elsif se.bpm.is_a?(Numeric)
+            use_bpm se.bpm
+          else
+            raise StandardError, "Incorrect bpm value. Expecting either :link or a number such as 120"
+          end
         end
 
         run_info = ""

app/server/ruby/lib/sonicpi/lang/sound.rb

@@ -3909,7 +3909,7 @@ def validate_if_necessary!(info, args_h)
 
       def ensure_good_timing!
         return true if __thread_locals.get(:sonic_pi_mod_sound_disable_timing_warnings)
-        raise "Timing Exception: thread got too far behind time." if time_diff > 1.1
+#        raise "Timing Exception: thread got too far behind time." if time_diff > 1.1
       end
 
       def time_diff
@@ -3918,7 +3918,7 @@ def time_diff
         vt  = __get_spider_time
         sat = current_sched_ahead_time
         compensated = (Time.now - sat)
-        compensated - vt
+        (compensated - vt).to_f
       end
 
       def in_good_time?(error_window=0)

app/server/ruby/lib/sonicpi/runtime.rb

@@ -89,58 +89,127 @@ def load_snippets(path=snippets_path, quiet=false)
       end
     end
 
+
+
     ### Start - Spider Time Management functions
     ###
-    def __change_spider_time_and_beat!(new_time, new_beat)
-      __system_thread_locals.set :sonic_pi_spider_time, new_time.freeze
-      __system_thread_locals.set(:sonic_pi_spider_beat, new_beat)
+    def __layer_spider_time_density!(density)
+      new_density = __get_spider_time_density * density
+      __change_spider_time_density!(new_density)
+    end
+
+    def __change_spider_time_density!(new_density)
+      __thread_locals.set(:sonic_pi_spider_time_density, new_density.to_f)
+    end
+
+    def __with_spider_time_density(density, &blk)
+      prev_density = __get_spider_time_density
+      __layer_spider_time_density!(density)
+      blk.call
+      __change_spider_time_density!(prev_density)
+    end
+
+    def __in_link_bpm_mode
+      __system_thread_locals.get(:sonic_pi_spider_bpm) == :link
+    end
+
+    def __change_spider_time_and_beat!(new_time = nil, new_beat = nil)
+      __system_thread_locals.set :sonic_pi_spider_time, new_time.to_r
+      __system_thread_locals.set(:sonic_pi_spider_beat, new_beat.to_f)
     end
 
     def __reset_spider_time_and_beat!
-      t = Time.now.freeze
-      __change_spider_time_and_beat!(t, 0)
-      __system_thread_locals.set :sonic_pi_spider_start_time, t
+      if __in_link_bpm_mode
+        new_time, new_beat = @tau_api.link_current_time_and_beat(0)
+        __system_thread_locals.set :sonic_pi_spider_time, new_time.to_r
+        __system_thread_locals.set(:sonic_pi_spider_beat, new_beat.to_f)
+        __system_thread_locals.set :sonic_pi_spider_start_time, new_time.to_r
+      else
+        t = Time.now.to_r
+        __change_spider_time_and_beat!(t, 0)
+        __system_thread_locals.set :sonic_pi_spider_start_time, t
+      end
     end
 
     def __change_spider_bpm!(new_bpm)
-      __system_thread_locals.set :sonic_pi_spider_bpm, new_bpm.to_f
+      case new_bpm
+      when :link
+        if __in_link_bpm_mode
+          # do nothing, we're already in link bpm mode
+        else
+          __system_thread_locals.set :sonic_pi_spider_bpm, :link
+          __reset_spider_time_and_beat!
+        end
+
+      when Numeric
+        __system_thread_locals.set :sonic_pi_spider_bpm, new_bpm.to_f
+      else
+        raise StandardError, "Unknown BPM value. Expecting either a number e.g. 120 or :link."
+      end
     end
 
     def __reset_spider_bpm!
       __change_spider_bpm!(60.0)
     end
 
     def __change_spider_beat_and_time_by_beat_delta!(beat_delta)
-      sleep_time = beat_delta * __get_spider_sleep_mul
-      new_time   = __get_spider_time + sleep_time
-      new_beat = __get_spider_beat + beat_delta
-      __change_spider_time_and_beat!(new_time, new_beat)
+      new_beat = __get_spider_beat + (beat_delta / __get_spider_time_density)
+
+      if __in_link_bpm_mode
+        __system_thread_locals.set(:sonic_pi_spider_beat, new_beat.to_f)
+      else
+        sleep_mul = __get_spider_sleep_mul
+        sleep_time = beat_delta * sleep_mul
+        new_time   = __get_spider_time + sleep_time
+        __change_spider_time_and_beat!(new_time, new_beat)
+      end
     end
 
     def __get_spider_time
-      __system_thread_locals.get(:sonic_pi_spider_time)
+      if __in_link_bpm_mode
+        @tau_api.link_get_clock_time_at_beat(__get_spider_beat)
+      else
+        __system_thread_locals.get(:sonic_pi_spider_time)
+      end
+    end
+
+    def __get_spider_time_density
+      __thread_locals.get(:sonic_pi_spider_time_density, 1)
     end
 
     def __get_spider_schedule_time
-      __system_thread_locals.get(:sonic_pi_spider_time) + current_sched_ahead_time
+      __get_spider_time + current_sched_ahead_time
     end
 
     def __get_spider_sleep_mul
-      60.0 / __system_thread_locals.get(:sonic_pi_spider_bpm)
+      (60.0 / __get_spider_bpm)
     end
 
     def __get_spider_bpm
-      __system_thread_locals.get(:sonic_pi_spider_bpm)
+      # take into account density
+      if __in_link_bpm_mode
+        @tau_api.link_tempo * __get_spider_time_density
+      else
+        __system_thread_locals.get(:sonic_pi_spider_bpm) * __get_spider_time_density
+      end
     end
 
     def __get_spider_beat
-      __system_thread_locals.get(:sonic_pi_spider_beat)
+      __system_thread_locals.get :sonic_pi_spider_beat
     end
 
     def __get_spider_start_time
       __system_thread_locals.get :sonic_pi_spider_start_time
     end
 
+    def __current_run_time
+      (__get_spider_time - @global_start_time).round(6)
+    end
+
+    def __current_local_run_time
+      (__get_spider_time - __get_spider_start_time).to_f.round(6)
+    end
+
     def __with_preserved_spider_time_and_beat(&blk)
       time = __get_spider_time
       beat = __get_spider_beat
@@ -323,7 +392,7 @@ def __schedule_delayed_blocks_and_messages!
           :thread_name => __current_thread_name}
             last_vt = __get_spider_time
             sched_ahead_sync_t = last_vt + __current_sched_ahead_time
-            sleep_time = sched_ahead_sync_t - Time.now
+            sleep_time = sched_ahead_sync_t.to_f - Time.now.to_f
 
         Thread.new do
             Kernel.sleep(sleep_time) if sleep_time > 0
@@ -390,14 +459,6 @@ def __error(e, m=nil)
       __msg_queue.push({type: :error, val: res, backtrace: e.backtrace, jobid: __current_job_id, jobinfo: __current_job_info, line: line})
     end
 
-    def __current_run_time
-      (__get_spider_time - @global_start_time).round(6)
-    end
-
-    def __current_local_run_time
-      (__get_spider_time - __system_thread_locals.get(:sonic_pi_spider_start_time)).round(6)
-    end
-
     def __current_thread_name
       __system_thread_locals.get(:sonic_pi_local_spider_users_thread_name) || ""
     end
@@ -410,14 +471,6 @@ def __current_job_info
       __system_thread_locals.get(:sonic_pi_spider_job_info) || {}
     end
 
-    def __sync(id, res)
-      @cue_events.event("/sync", {:id => id, :result => res})
-    end
-
-    def __cue_events
-      @cue_events
-    end
-
     def __stop_start_cue_server!(stop)
       @tau_api.start_stop_cue_server!(stop)
     end
@@ -948,11 +1001,6 @@ def __gui_cue_log_idxs
       @gui_cue_log_idxs
     end
 
-
-
-
-
-
     def __in_thread(*opts, &block)
       args_h = resolve_synth_opts_hash_or_array(opts)
       name = args_h[:name]
@@ -1323,13 +1371,9 @@ def normalise_buffer_name(name)
              end
       return norm
     end
-
-
-
   end
 
 
-
   class Runtime
 
     include Util
@@ -1393,8 +1437,9 @@ def initialize(ports, msg_queue, user_methods)
       @system_state.set 0, 0, osc_cue_server_thread_id, 0, 0, 60, :sched_ahead_time, default_sched_ahead_time
       @gui_cue_log_idxs = Counter.new
       @osc_cue_server_mutex = Mutex.new
-      @register_cue_event_lambda = lambda do |t, p, i, d, b, m, address, args, sched_ahead_time=0|
 
+      @register_cue_event_lambda = lambda do |t, p, i, d, b, m, address, args, sched_ahead_time=0|
+        t = t.to_r
         sym = nil
         address, sym = *address if address.is_a?(Array)
 
@@ -1408,7 +1453,8 @@ def initialize(ports, msg_queue, user_methods)
                                   :cue => address })
 
         sched_ahead_sync_t = t + sched_ahead_time
-        sleep_time = sched_ahead_sync_t - Time.now
+
+        sleep_time = sched_ahead_sync_t - Time.now.to_r
         if sleep_time > 0
           Thread.new do
             Kernel.sleep(sleep_time)