midi-topaz 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3f0c8761ea2448cd3a28a29b15a1c8779e002be9
-  data.tar.gz: 03f8b39884bb6cc77cabed0d27f93eb553a08978
+  metadata.gz: 0ce370c533a7d6bf26395da93632c35985e939c3
+  data.tar.gz: 2d225a7fd71f4fe2390278fd63c1c50e4ac3e3b1
 SHA512:
-  metadata.gz: 884034e8940159b9997770a4ab7ac2e9eb1aa598aec6d1b58bcb14315f0077d25d7aa4ff5438c87a899e0c72ebd22e674dd3e0b2aa91497865b8c3bfd2b7f2d2
-  data.tar.gz: b2e526421f8f9450fd0d36d46ec685eb4c3918dedd0637b7312eeeb1dc8bb0ac68c13fc83d70efc3d344bd4368ea0fff984a1b6ae92b6abd42066a5f566dfb51
+  metadata.gz: 563c0fcec28ebd826488239e42b95ebab118b1d35f13bf50e590f2d44adff102da9a434c63990f370cbb9b1df20fa3ec8969a9269119a7b860e653c0ba31e4e2
+  data.tar.gz: 8205a2ec2232efb86edb38d2ec0280cd4c69516ad6334e861fc8160ca03b19367551dc3fa3bc40c335b3121c1cd29814c022fe132d550b88cab964a9b123cc2f

data/README.md

@@ -36,7 +36,7 @@ sequencer = Sequencer.new
 The simplest application of Topaz is to create a clock to step that sequencer at a given rate.  Using timing generated internally by your computer, the passed in block will be called repeatedly at 130 BPM
 
 ```ruby
-@tempo = Topaz::Tempo.new(130) { sequencer.step }
+@tempo = Topaz::Clock.new(130) { sequencer.step }
 ```
 
 You may also use another MIDI device to generate timing and control the tempo.  The unimidi input to which that device is connected can be passed to the Tempo constructor    
@@ -44,7 +44,7 @@ You may also use another MIDI device to generate timing and control the tempo.
 ```ruby
 @input = UniMIDI::Input.first.open # an midi input 
   
-@tempo = Topaz::Tempo.new(@input) { sequencer.step }
+@tempo = Topaz::Clock.new(@input) { sequencer.step }
 ```
         
 Topaz can also act as a master clock. If a MIDI output is passed to Topaz, MIDI start, stop and clock signals will automatically be sent to that output at the appropriate time
@@ -52,7 +52,7 @@ Topaz can also act as a master clock. If a MIDI output is passed to Topaz, MIDI
 ```ruby
 @output = UniMIDI::Output.first.open # a midi output 
   
-@tempo = Topaz::Tempo.new(120, :midi => @output) do
+@tempo = Topaz::Clock.new(120, :midi => @output) do
   sequencer.step
 end
 ```
@@ -60,7 +60,7 @@ end
 Input and multiple outputs can be used simultaneously
 
 ```ruby
-@tempo = Topaz::Tempo.new(@input, :midi => [@output1, @output2]) do 
+@tempo = Topaz::Clock.new(@input, :midi => [@output1, @output2]) do 
   sequencer.step
 end
 ```
@@ -78,7 +78,7 @@ If you are syncing to external clock, nothing will happen until a "start" or "cl
 Whether or not you are using an internal or external clock source, the event block will be called at quarter note intervals by default.  If you wish to change this set the option :interval.  In this case, the event will be fired 4 times per beat (16th notes) at 138 BPM   
 
 ```ruby
-@tempo = Topaz::Tempo.new(138, :interval => 16) do
+@tempo = Topaz::Clock.new(138, :interval => 16) do
   sequencer.step
 end
 ```

data/lib/topaz/api.rb

@@ -0,0 +1,19 @@
+module Topaz
+
+  # Convenience shortcuts for the clock
+  module API
+
+    def self.included(base)
+      base.send(:extend, Forwardable)
+      base.send(:def_delegators, :source, :interval, :interval=, :join, 
+                :pause, :pause?, :paused?, :running?, :tempo, :toggle_pause, :unpause)
+    end
+
+    # Alias for Clock#time
+    # @return [Time]
+    def time_since_start
+      time
+    end
+    
+  end
+end

data/lib/topaz/clock.rb

@@ -0,0 +1,187 @@
+module Topaz
+
+  # The main tempo clock
+  class Clock
+
+    include API
+
+    attr_reader :event, :midi_output, :source, :trigger
+
+    # @param [Fixnum, UniMIDI::Input] tempo_or_input
+    # @param [Hash] options
+    # @param [Proc] tick_event
+    def initialize(tempo_or_input, options = {}, &tick_event)
+      # The MIDI clock output is initialized regardless of whether there are devices
+      # so that it is ready if any are added during the running process.
+      @midi_output = MIDIClockOutput.new(:devices => options[:midi])
+      @event = Event.new
+      @trigger = EventTrigger.new
+      @source = TempoSource.new(tempo_or_input, options.merge({ :event => @event })) 
+      initialize_events(&tick_event)
+    end
+
+    # Set the tempo
+    #
+    # If external MIDI tempo is being used, this will switch to internal tempo at the desired rate.
+    #
+    # @param [Fixnum] value
+    # @return [ExternalMIDITempo, InternalTempo]
+    def tempo=(value)
+      if @source.respond_to?(:tempo=)
+        @source.tempo = value
+      else
+        @source = TempoSource.new(event, tempo_or_input)
+      end
+    end
+
+    # This will start the clock source
+    #
+    # In the case that external midi tempo is being used, this will instead start the process
+    # of waiting for a start or clock message
+    #
+    # @param [Hash] options
+    # @option options [Boolean] :background Whether to run the timer in a background thread (default: false)
+    # @return [Boolean]
+    def start(options = {})
+      @start_time = Time.now
+      begin
+        @source.start(options)
+      rescue SystemExit, Interrupt => exception
+        stop
+      end
+      true
+    end
+
+    # This will stop the clock source
+    # @param [Hash] options
+    # @return [Boolean]
+    def stop(options = {})
+      @source.stop(options)
+      @start_time = nil
+      true
+    end
+
+    # Seconds since start was called
+    # @return [Float]
+    def time
+      (Time.now - @start_time).to_f unless @start_time.nil?
+    end
+
+    private
+
+    # Initialize the tick and MIDI clock events so that they can be passed to the source
+    # and fired when needed
+    # @param [Proc] block
+    # @return [Clock::Event]
+    def initialize_events(&block)
+      @event.tick << block if block_given?
+      clock = proc do 
+        if @trigger.stop?
+          stop
+        else
+          @midi_output.do_clock
+        end
+      end
+      @event.clock = clock
+      @event.start << proc { @midi_output.do_start }
+      @event.stop << proc { @midi_output.do_stop }
+      @event
+    end
+
+    # Trigger clock events
+    class EventTrigger
+
+      def initialize
+        @stop = []
+      end
+
+      # Pass in a callback which will stop the clock if it evaluates to true
+      # @param [Proc] callback
+      # @return [Array<Proc>]
+      def stop(&callback)
+        if block_given?
+          @stop.clear
+          @stop << callback
+        end
+        @stop
+      end
+
+      # Should the stop event be triggered?
+      # @return [Boolean]
+      def stop?
+        !@stop.nil? && @stop.any?(&:call)
+      end
+
+    end
+
+    # Clock events
+    class Event
+
+      attr_accessor :clock
+
+      def initialize
+        @start = []
+        @stop = []
+        @tick = []
+      end
+
+      # @return [Array]
+      def do_clock
+        !@clock.nil? && @clock.call
+      end
+
+      # Pass in a callback that is called when start is called
+      # @param [Proc] callback
+      # @return [Array<Proc>]
+      def start(&callback)
+        if block_given?
+          @start.clear
+          @start << callback
+        end
+        @start
+      end
+
+      # @return [Array]
+      def do_start
+        @start.map(&:call)
+      end
+
+      # pass in a callback that is called when stop is called
+      # @param [Proc] callback
+      # @return [Array<Proc>]
+      def stop(&callback)
+        if block_given?
+          @stop.clear
+          @stop << callback
+        end
+        @stop
+      end
+
+      # @return [Array]
+      def do_stop
+        @stop.map(&:call)
+      end
+
+      # Pass in a callback which will be fired on each tick
+      # @param [Proc] callback
+      # @return [Array<Proc>]
+      def tick(&callback)
+        if block_given?
+          @tick.clear
+          @tick << callback
+        end
+        @tick
+      end
+
+      # @return [Array]
+      def do_tick
+        @tick.map(&:call)
+      end
+
+    end
+
+  end
+
+  Tempo = Clock # For backwards compat
+
+end

data/lib/topaz/midi_clock_input.rb

@@ -0,0 +1,186 @@
+module Topaz
+  
+  # Trigger an event based on received midi clock messages
+  class MIDIClockInput
+      
+    include Pausable
+
+    attr_reader :clock, :listening, :running
+    alias_method :listening?, :listening
+    alias_method :running?, :running
+  
+    # @param [UniMIDI::Input] input
+    # @param [Hash] options
+    # @option options [Clock::Event] :event
+    def initialize(input, options = {})
+      @event = options[:event]
+      @tick_counter = 0
+      @pause = false
+      @listening = false
+      @running = false
+      @tempo_calculator = TempoCalculator.new
+      @tick_threshold = interval_to_ticks(options.fetch(:interval, 4))
+
+      initialize_listener(input)
+    end
+    
+    # This will return a calculated tempo
+    # @return [Fixnum]
+    def tempo
+      @tempo_calculator.calculate
+    end
+    
+    # Start the listener
+    # @param [Hash] options
+    # @option options [Boolean] :background Whether to run the listener in a background process
+    # @option options [Boolean] :focus (or :blocking) Whether to run the listener in a foreground process
+    # @return [MIDIInputClock] self
+    def start(options = {})  
+      @listening = true
+      blocking = options[:focus] || options[:blocking]
+      background = options[:background] || blocking.nil? || blocking.eql?(false)
+      @listener.start(:background => background)
+      self
+    end
+    
+    # Stop the listener
+    # @return [MIDIInputClock] self
+    def stop(*a)
+      @listening = false
+      @listener.stop
+      self
+    end
+    
+    # Join the listener thread
+    # @return [MIDIInputClock] self
+    def join
+      @listener.join
+      self
+    end
+        
+    # Change the clock interval
+    # Defaults to 4, which means click once every 24 ticks or one quarter note (per MIDI spec).
+    # Therefore, to fire the on_tick event twice as often, pass 8 
+    #
+    #   1 = whole note
+    #   2 = half note
+    #   4 = quarter note
+    #   6 = dotted quarter
+    #   8 = eighth note
+    #  16 = sixteenth note
+    #  etc
+    #
+    # @param [Fixnum] interval
+    # @return [Fixnum]
+    def interval=(interval)
+      @tick_threshold = interval_to_ticks(interval)
+    end
+    
+    # Return the interval at which the tick event is fired
+    # @return [Fixnum]
+    def interval
+      ticks_to_interval(@tick_threshold)
+    end
+    
+    private
+
+    # Convert a note interval to number of ticks
+    # @param [Fixnum] interval
+    # @param [Fixnum]
+    def interval_to_ticks(interval)
+      per_qn = interval / 4
+      24 / per_qn
+    end
+
+    # Convert a number of ticks to a note interval
+    # @param [Fixnum] ticks
+    # @param [Fixnum]
+    def ticks_to_interval(ticks)
+      note_value = 24 / ticks
+      4 * note_value
+    end
+    
+    # Initialize the MIDI input listener
+    # @param [UniMIDI::Input] input
+    # @return [MIDIEye::Listener]
+    def initialize_listener(input)
+      @listener = MIDIEye::Listener.new(input)
+      @listener.listen_for(:name => "Clock") { |message| handle_clock_message(message) }     
+      @listener.listen_for(:name => "Start") { handle_start_message } 
+      @listener.listen_for(:name => "Stop") { handle_stop_message }
+      @listener
+    end
+
+    # Handle a received start message
+    # @return [Boolean]
+    def handle_start_message
+      @running = true
+      if !@event.nil?
+        @event.do_start
+        true
+      end
+    end
+
+    # Handle a received stop message
+    # @return [Boolean]
+    def handle_stop_message
+      @running = false
+      if !@event.nil?
+        @event.do_stop
+        true
+      end
+    end
+
+    # Handle a received clock message
+    # @param [Hash] message
+    # @return [Fixnum] The current counter
+    def handle_clock_message(message)
+      @running ||= true
+      thru
+      log(message)
+      tick? ? tick : advance
+    end
+
+    # Advance the tick counter
+    # @return [Fixnum]
+    def advance
+      @tick_counter += 1
+    end
+
+    # Log the timestamp of a message for tempo calculation
+    # @param [Hash] message
+    # @return [Array<Fixnum>]
+    def log(message)
+      time = message[:timestamp] / 1000.0
+      @tempo_calculator.timestamps << time
+    end
+
+    # Fire the clock event
+    # (this results in MIDI output sending clock, thus thru)
+    # @return [Boolean]
+    def thru
+      if !@event.nil?
+        @event.do_clock
+        true
+      end
+    end
+
+    # Fire the tick event
+    # @return [Boolean]
+    def tick
+      @tick_counter = 0
+      if !@event.nil? && !@pause
+        @event.do_tick
+        true
+      end
+    end
+
+    # Should the tick event be fired given the current state?
+    # @return [Boolean]
+    def tick?
+      @tick_counter >= (@tick_threshold - 1)
+    end
+    
+  end
+  
+end

data/lib/topaz/midi_clock_output.rb

@@ -0,0 +1,49 @@
+module Topaz
+  
+  # Send clock messages via MIDI
+  class MIDIClockOutput
+
+    attr_reader :devices
+
+    # @param [Hash] options
+    # @option options [Array<UniMIDI::Output>, UniMIDI::Output] :device
+    def initialize(options)
+      device = options[:device] || options[:devices]
+      @devices = [device].flatten.compact
+    end
+    
+    # Send a start message
+    # @return [Boolean] Whether a message was emitted
+    def do_start(*a)
+      start = MIDIMessage::SystemRealtime["Start"].new
+      emit(start)
+      !@devices.empty?
+    end
+
+    # Send a stop message
+    # @return [Boolean] Whether a message was emitted
+    def do_stop(*a)
+      stop = MIDIMessage::SystemRealtime["Stop"].new
+      emit(stop)
+      !@devices.empty?
+    end
+        
+    # Send a clock tick message
+    # @return [Boolean] Whether a message was emitted
+    def do_clock(*a)
+      clock = MIDIMessage::SystemRealtime["Clock"].new
+      emit(clock)
+      !@devices.empty?
+    end
+
+    private
+
+    # Emit a message to the devices
+    # @param [MIDIMessage] message
+    def emit(message)
+      @devices.each { |device| device.puts(*message.to_bytes) }
+    end
+    
+  end
+  
+end

data/lib/topaz/pausable.rb

@@ -0,0 +1,32 @@
+module Topaz
+
+  # Pause functionality
+  module Pausable
+
+    # Pause the clock
+    # @return [Boolean]
+    def pause
+      @pause = true
+    end
+
+    # Unpause the clock
+    # @return [Boolean]
+    def unpause
+      @pause = false
+    end
+
+    # Is this clock paused?
+    # @return [Boolean]
+    def paused?
+      @pause
+    end
+    alias_method :pause?, :paused?
+
+    # Toggle pausing the clock
+    # @return [Boolean]
+    def toggle_pause
+      @pause = !@pause      
+    end
+
+  end
+end

data/lib/topaz/tempo_calculator.rb

@@ -3,7 +3,7 @@ module Topaz
   # Calculate tempo given timestamps
   class TempoCalculator
 
-    THRESHOLD = 6 # minimum number of ticks to analyze
+    THRESHOLD = 6 # Optimal number of ticks to analyze
     
     attr_reader :tempo, :timestamps
     
@@ -13,25 +13,42 @@ module Topaz
     end
     
     # Analyze the tempo based on the threshold
-    def find_tempo
+    # @return [Float, nil] The tempo as a float, or nil if there's not enough data to calculate it
+    def calculate
       tempo = nil
-      diffs = []
-      @timestamps.shift while @timestamps.length > THRESHOLD
-      @timestamps.each_with_index { |n, i| (diffs << (@timestamps[i+1] - n)) unless @timestamps[i+1].nil? }
-      unless diffs.empty?
-        avg = (diffs.inject { |a, b| a + b }.to_f / diffs.length.to_f) 
-        tempo = ppq24_millis_to_bpm(avg)
-      end 
-      @tempo = tempo
+      if @timestamps.count >= 2
+        limit_timestamps
+        deltas = get_deltas
+        sum = deltas.inject(&:+)
+        average = sum.to_f / deltas.count
+        bpm = ppq24_millis_to_bpm(average)
+        @tempo = bpm
+      end
     end
     
     private
-    
-    # convert the raw tick intervals to bpm
+
+    # Limit the timestamp list to within the threshold
+    # @return [Array<Time>, nil]
+    def limit_timestamps
+      if @timestamps.count > THRESHOLD
+        @timestamps.slice!(THRESHOLD - @timestamps.count, THRESHOLD)
+        @timstamps
+      end
+    end
+
+    # Get the delta values between the timestamps
+    # @return [Array<Float>]
+    def get_deltas
+      @timestamps.each_cons(2).map { |a,b| b - a }
+    end
+
+    # Convert the raw tick intervals to beats-per-minute (BPM)
+    # @param [Float] ppq24 
+    # @return [Float]
     def ppq24_millis_to_bpm(ppq24)
-      quarter_note = (ppq24 * 24.to_f)
-      minute = (60 * 1000) # one minute in millis
-      minute/quarter_note
+      quarter_note = ppq24.to_f * 24.to_f
+      60 / quarter_note
     end
     
   end

data/lib/topaz/tempo_source.rb

@@ -0,0 +1,27 @@
+module Topaz
+
+  # Construct a tempo source object
+  module TempoSource
+
+    extend self
+
+    # Construct a tempo source
+    # @param [Fixnum, UniMIDI::Input] tempo_or_input
+    # @param [Hash] options
+    # @option options [Clock::Event] :event
+    # @return [MIDIClockInput, Timer]
+    def new(tempo_or_input, options = {})
+      klass = case tempo_or_input
+      when Numeric then Timer
+      when UniMIDI::Input then MIDIClockInput
+      else
+        raise "Not a valid tempo source"
+      end
+      source = klass.new(tempo_or_input, :event => options[:event])
+      source.interval = options[:interval] unless options[:interval].nil?
+      source
+    end
+
+  end
+
+end